RepoAssay/repo-test-architect

# Repo Test 架构师 面向代码库的审计优先测试策略工具。 Repo Test Architect 会在要求任何模型或代理对测试进行推理之前，构建一个确定性的审计图谱。其目标是根据工具可在本地检查的事实（包括项目根目录、框架信号、现有测试、源码分类、阻碍因素以及剩余风险），识别出原生的、高价值的测试工作。 当前实现可以： - 通过支持的 adapter 审计 JavaScript/TypeScript、Python 和 Swift 项目 - 通过相同的共享 artifact 模型，审计受支持且有边界的 Kotlin/JVM fixtures - 通过受支持且有边界的 adapter，审计常规的 Go modules 以及字面意义上包含在代码库中的 `go.work` 成员 - 检测多语言项目根目录，并报告不支持的生态系统，且不会将其隐藏 - 在一次审计过程中生成完整的代码库分析、发现结果、排名、计划、执行提示和验证命令 - 根据可能的测试价值对源文件进行分类，并推迟低价值的直接测试 - 根据审计图谱对候选者进行排名并生成测试计划 - 推导出与提供商无关的执行、上下文、并发安全以及代码库推理提示，且不选择模型或生成子代理 - 分析跨项目边界的保守测试放置发现 - 收集项目级别的统计数据，包括覆盖率、候选数量、框架、命令和 adapter 使用情况 - 提供默认关闭的本地 MCP 诊断、安全的内部错误报告 ID、运行时检查，以及可检查的脱敏数据包，且不进行外部报告 - 通过 CLI 命令、本地调用测试工具（invoke harness）以及 stdio MCP SDK 服务器暴露相同的确定性行为 - 使用 golden 快照、模型一致性场景、包检查和跨操作系统 CI 来锁定行为 原生测试生成被有意推迟。在存在特定于 adapter 的生成策略和修复循环 fixtures 之前，`generate_selected_test` 将返回一个结构化的推迟 artifact。 Repo Test Architect 目前处于早期公开 Alpha 阶段。请将其发现结果视为有证据支持的审查意见，而不是自动更改代码库的指令。 ## 安装 需要 Node.js 20 或更高版本。 无需全局安装即可运行 CLI： ``` npx --yes repo-test-architect doctor npx --yes repo-test-architect analyze . ``` 或者安装 CLI 和 MCP 服务器二进制文件： ``` npm install --global repo-test-architect repo-test-architect doctor repo-test-architect analyze . ``` 将本地 stdio MCP 服务器添加到支持 MCP 的客户端： ``` { "mcpServers": { "repo-test-architect": { "command": "npx", "args": [ "--yes", "repo-test-architect", "mcp" ] } } } ``` 客户端会在本地启动服务器。除非客户端或其他配置的工具将其发送到其他地方，否则代码库源码将保留在本地机器上。连接的模型会收到指示，要求其从 `analyze_repository` 开始进行常规的代码库审查。有关全局安装、本地检出和特定于主机的指导，请参阅 [MCP 客户端配置](docs/mcp-client-config.md)和 [Agent 安装路径](docs/agent-install-paths.md)。 ## 快速开始 要获取对当前代码库的人类可读审查： ``` npx --yes repo-test-architect analyze . ``` `analyze` 会检测每个项目根目录，运行每个受支持的 adapter 一次，并推导出审计摘要、主要发现、候选者排名、测试计划、执行提示、项目统计信息和验证命令。Markdown 保持紧凑；JSON 则保留完整的证据包： ``` npx --yes repo-test-architect analyze . --format json npx --yes repo-test-architect analyze . --changed ``` 有用的重点视图： | 目标 | 命令 | | --- | --- | | 完整的代码库审查 | `repo-test-architect analyze .` | | 简洁的架构发现 | `repo-test-architect findings-projects .` | | 可操作的跨项目计划 | `repo-test-architect plan-projects .` | | 原始的可重用项目审计 | `repo-test-architect audit-projects . --format json` | | 运行时就绪状态 | `repo-test-architect doctor` | 运行 `repo-test-architect --help` 获取简短命令映射，或运行 `repo-test-architect --help` 查看选项。[CLI 参考](docs/cli-reference.md)文档包含了完整的使用界面。 对于连接了 MCP 的模型，默认的等效工具是 `analyze_repository`。仅当请求要求提供单一 artifact 或已经提供审计 artifact 时，才使用范围更窄的工具。 ## 当前范围 受支持的 adapter： - `javascript`：使用 Node 的测试运行器（包括 TypeScript 执行脚本）、Bun 测试、AVA、Mocha/CommonJS、Vitest、Jest、Playwright、Cypress、Express/Supertest、React Testing Library 检测以及有边界的字面浏览器 request-to-route 证据的 JavaScript/TypeScript 代码库；有关证据边界和已知缺口，请参阅 [Alpha 支持矩阵](docs/javascript-typescript-alpha-support.md) - `go`：使用可运行的标准库 `TestXxx`、`FuzzXxx` 或 `ExampleXxx` 测试、包级本地文件名、通过显式类型或确切的简单构造函数结果获得的唯一顶级和具体 receiver-method 符号、same-package 或确切的外部 package 导入（包括 dot 导入）、通用顶级函数，以及有边界的 same-package 或 single-callable 模块本地源码跳转、模块本地命令，和可选的显式 `GOOS`/`GOARCH`/自定义 tag 选择的常规 `go.mod` 项目和字面上包含在代码库中的 `go.work` 成员；有关受支持的边界和阻碍因素，请参阅 [Alpha 支持矩阵](docs/go-alpha-support.md) - `kotlin`：常规的 Gradle/Maven JVM 模块根目录、由 settings 拥有的 Gradle 聚合，以及根目录声明的 Maven reactors，支持 Kotlin 和/或 Java 标准源码集、依赖限定的直接/导出传递模块证据、JUnit 4/5、`kotlin.test`、有边界的 Gradle/JUnit Platform Kotest 通用规范、常规的 Gradle/Spock 特性，以及通过直接的 Maven 依赖或 Gradle `useTestNG()` 实现的方法级 TestNG；请参阅 [Kotlin/JVM Alpha 支持矩阵](docs/kotlin-jvm-alpha-support.md) - `python`：具有声明式多包/命名空间所有权、已配置的 pytest 发现、确切的绝对/相对导入、单跳源依赖证据、静态框架 test-client 路由证据、pytest/unittest、异步和基于属性的扩展、fixture 可达性、pip/setuptools、uv、Poetry、Hatch、tox、nox 和覆盖率配置的有边界的 Python package、FastAPI、Django 和 Flask 布局；请参阅 [Python Alpha 支持矩阵](docs/python-alpha-support.md) - `swift`：Swift Package Manager、Xcode 风格和 Bazel/rules_swift 布局、Swift Testing、XCTest、Quick/Nimble、SnapshotTesting、VaporTesting/XCTVapor、响应式框架，以及带有特定于驱动程序的限定符的通用 Fluent 数据库边界；请参阅 [Swift Alpha 支持矩阵](docs/swift-alpha-support.md) 项目检测还会报告不支持的 Ruby、PHP、Elixir、Rust 和 .NET 根目录，以便客户端可以区分“尚未审计”和“不存在”。 公开的包在下面记录的稳定二进制文件名下公开了审计 CLI、stdio MCP 服务器以及一个确定性的 MCP 调用测试工具（invoke harness）。 ## 高级 CLI 和贡献者参考 以下命令为高级使用和代码库开发提供了专注于 artifact、fixtures、evals、诊断和发布检查的功能。

显示完整的命令和开发参考

直接或针对多语言示例运行完整的分析： ``` npm run analyze npm run analyze:json npm run analyze:example npm run analyze:example:json ``` 检查运行时和诊断就绪情况： ``` npm run doctor npm run doctor:json ``` 本地 MCP 诊断默认关闭。它们可以被明确指向 stderr 或一个有边界的本地 JSONL 文件；请参阅[本地诊断](docs/diagnostics.md)。使用以下命令构建一个经过脱敏处理的、可检查的数据包： ``` npm run diagnostic-bundle -- --diagnostics-file ./.repo-test-architect/diagnostics.jsonl --format json node ./src/cli/index.js diagnostic-bundle --diagnostics-file ./.repo-test-architect/diagnostics.jsonl --format json ``` 列出已注册的 adapter： ``` npm run adapters npm run adapters:json ``` 检查项目检测标记规则： ``` npm run detect-rules npm run detect-rules:json ``` 检测项目根目录和 adapter 匹配项： ``` npm run detect:example npm run detect:example:json npm run detect:kotlin-fixture npm run detect:kotlin-fixture:json npm run detect:apple-fixture npm run detect:apple-fixture:json npm run audit-projects:example npm run audit-projects:example:json npm run audit-projects:changed-since npm run summarize-projects:example npm run summarize-projects:example:json npm run rank-projects:example npm run rank-projects:example:json npm run plan-projects:example npm run plan-projects:example:json npm run hints-projects:example npm run hints-projects:example:json npm run findings-projects:example npm run findings-projects:example:json npm run placement-projects:example npm run placement-projects:example:json npm run placement-projects:split-example:json npm run stats-projects:example npm run stats-projects:example:json ``` 对于具有项目感知能力的自审计，请使用带引号的子树模式排除已检入的 fixture 或样本根目录： ``` node ./src/cli/index.js findings-projects . --exclude-project "examples/**" ``` 重用已保存的项目审计 artifact： ``` node ./src/cli/index.js audit-projects ./examples/polyglot-workspace --format json node ./src/cli/index.js summarize-projects --from-project-audits ./project-audits.json --format json node ./src/cli/index.js rank-projects --from-project-audits ./project-audits.json --format json node ./src/cli/index.js plan-projects --from-project-audits ./project-audits.json --format json node ./src/cli/index.js findings-projects --from-project-audits ./project-audits.json --format json node ./src/cli/index.js placement-projects --from-project-audits ./project-audits.json --format json node ./src/cli/index.js stats-projects --from-project-audits ./project-audits.json --format json ``` ``` npm run audit:example npm run audit:kotlin-fixture ``` 输出结构化的审计图谱： ``` npm run audit:example:json npm run audit:kotlin-fixture:json ``` 根据审计图谱生成可操作的测试计划： ``` npm run plan:example npm run plan:example:json npm run hints:example npm run hints:example:json npm run plan:kotlin-fixture npm run plan:kotlin-fixture:json npm run plan:item:example npm run plan:changed npm run plan:changed-since ``` 推导建议性的执行提示，同时保持 plan artifact 不变： ``` node ./src/cli/index.js hints ./examples/node-vitest-basic --item add-test:src/authService.ts node ./src/cli/index.js hints-projects ./examples/polyglot-workspace --format json ``` 安装 CLI 或 agent 主机仍然负责模型选择、预算、权限、上下文加载以及子代理生命周期。 通过稳定的目标 ID 解释一个已审计的目标： ``` npm run explain:example ``` 在不生成测试的情况下对测试候选者进行排名： ``` npm run rank:example ``` 根据审计证据分析现有的测试放置位置： ``` npm run placement:example npm run placement:example:json npm run placement:from-audit:example ``` 运行 MCP 风格的工具表面： ``` npm run mcp:tools npm run mcp:analyze:example npm run mcp:adapters npm run mcp:detect-rules npm run mcp:detect:example npm run mcp:audit-projects:example npm run mcp:summarize-projects:example npm run mcp:rank-projects:example npm run mcp:plan-projects:example npm run mcp:findings-projects:example npm run mcp:placement-projects:example npm run mcp:placement-split:example npm run mcp:stats-projects:example npm run mcp:audit:example npm run mcp:audit:kotlin-fixture npm run mcp:placement:example npm run mcp:audit:envelope npm run mcp:stdio npm run mcp:smoke ``` 从现有的审计 JSON 文件生成计划： ``` npm run plan:from-audit:example ``` 运行审计器回归测试： ``` npm test npm run alpha:check npm run release:check ``` 查找并对活跃的公开代码库进行排名，以用于真实世界的 adapter 验证： ``` npm run validation:repos -- --profile react npm run validation:repos -- --profile workspace --limit 10 npm run validation:repos -- --profile swift,gradle,maven --format json ``` 查找器使用经过身份验证的 GitHub 代码库搜索，验证根 manifest 中的确切生态系统标记，并根据维护情况近期程度、星标数、代码库大小、lockfile、CI 和许可证元数据对候选者进行排名。运行 `npm run validation:repos -- --list-profiles` 获取可用的配置文件，运行 `--help` 获取质量过滤选项。 检查每个受支持的 adapter 是否具有完整、已锁定的强化语料库： ``` npm run corpus:check npm run corpus:scorecard npm run corpus:measure -- --case python-asyncer --checkout /path/to/pinned/asyncer npm run javascript:performance:check npm run python:performance:check npm run kotlin:performance:check npm run swift:performance:check npm run go:performance:check ``` 版本化的 `evals/validation-corpus.json` manifest 为每个 adapter 记录了一个常规库或服务、一个重框架的应用程序，以及一个难以处理的所有权图。每条记录都包含共享的检测、所有权、命令、证据、排名、稳定性和性能记分卡。当前所有 15 个锁定的案例均通过了每个记分卡区域；一个新的或重新锁定的案例将保持 `pending` 状态，直到它在标准化的强化审查下被重新运行。案例可以带有有边界的 adapter 审计选项（例如显式的 Go 构建目标），以便重复的测量结果保持独立于主机。 `corpus:scorecard` 为人类呈现了审查契约。它将审查完整性报告与已审查检查中的通过率区分开来，并使每个区域的 `PASS`、`FAIL` 和 `PENDING` 状态保持可见。使用 `npm run corpus:scorecard -- --format json` 获取确定性的 `validation-scorecard/v1` 视图。这些是验证审查结果，而不是代码库质量评级。 `corpus:measure` 验证检出（checkout）的确切锁定 Git SHA，至少运行选定的 adapter 三次，拒绝标准的审计漂移，并报告原始持续时间、中位数持续时间、证据链接数，以及用于更新记分卡的标准化审计摘要。 每个 adapter 性能检查分别运行一个生成的 400 源码/200 测试的项目，验证其候选者和证据计数，并强制执行广泛的跨平台回归上限。这些合成的门控补充了记录的每个代码库的语料库分布。 使用 `alpha:check` 检查 adapter 支持的里程碑。`release:check` 额外涵盖了打包和已安装二进制文件的就绪情况。 CI 工作流保留了一个稳定的 Linux `pr-gate`：纯文档更改运行重点契约测试，常规更改运行 `npm run alpha:check`，而对分发敏感的更改运行 `npm run release:check`。Windows 仅针对运行时和可移植性更改运行；macOS 仅针对 Swift 敏感型更改运行。合并到 `master` 会在 Linux 上运行完整的发布门控，而手动调度则会在所有三种操作系统上运行完整的发布门控。 测试包括由 `evals/fixtures.json` 驱动的、位于 `evals/expected` 下的 golden 审计和计划快照，以及用于确定性 JSON、可移植路径、证据语义和下游 artifact 一致性的共享 adapter 一致性检查。 版本化 artifact 的 JSON schema 和信号注册表位于 `schemas/` 下。 在有目的地更改审计行为后刷新快照： ``` npm run eval:check npm run eval:summary npm run eval:test npm run eval:update ``` 根据确定性工具结果检查模型一致性场景的锁定字段： ``` npm run model-consistency:check npm run model-consistency:json npm run model-consistency:json -- --profile local-small npm run model-consistency:compare -- baseline-summary.json candidate-summary.json npm run model-consistency:stats ``` CLI 需要 Node 20 或更高版本。默认的冒烟检查可跨平台移植： ``` npm run smoke ``` 如果 Node 尚不可用，代码库仍包含一个 PowerShell 冒烟检查： ``` powershell -ExecutionPolicy Bypass -File ./scripts/smoke.ps1 ``` 在发布前检查包内容： ``` npm run pack:check npm run bin:check npm run installed-package:check npm run distribution:check npm run release:check ``` `distribution:check` 验证打包和 MCP 元数据准备。更严格的 `distribution:check:publish` 验证公开的 npm 和 MCP Registry 身份在发布前是否一致。请参阅[分发](docs/distribution.md)。

## 结构 ``` src/ core/ audit-model.ts plan-execution-hints.js plan-execution-hints.ts report.js report.ts diagnostics/ diagnostics.js adapters/ javascript/ audit.js audit.ts kotlin/ audit.js python/ audit.js swift/ audit.js cli/ index.js examples/ node-vitest-basic/ express-supertest/ react-testing-library/ kotlin-junit-basic/ kotlin-gradle-groovy-junit/ kotlin-gradle-module-graph-junit/ kotlin-maven-junit/ kotlin-maven-reactor-junit/ kotlin-maven-wrapper-junit4/ kotlin-gradle-aggregate-kotest/ kotlin-gradle-spock/ kotlin-maven-testng/ python-pytest-service/ python-uv-pytest/ python-poetry-pytest/ swift-spm-xctest/ swift-spm-swift-testing/ swift-spm-quick-nimble/ swift-spm-custom-paths/ swift-spm-alternate-roots/ swift-bazel-xctest/ swift-xcode-test-plans/ vapor-service-tests/ vapor-mongodb-boundaries/ evals/ expected/ model-consistency/ schemas/ ``` JavaScript/TypeScript、Python、Swift、有边界的 Kotlin/JVM 模块和有边界的 Go 模块是受支持的 adapter 概念验证。Go 支持包括字面上包含在代码库中的 `go.work` 成员和显式静态构建目标选择，定义见 [Go Alpha 支持](docs/go-alpha-support.md)。Kotlin/JVM 支持仅限于常规的 Gradle/Maven 模块和直接声明的聚合图、JUnit、已记录的 Kotest 通用规范和 Spock 特性变体，或方法级 TestNG 以及标准源码集，定义 [Kotlin/JVM Alpha 支持](docs/kotlin-jvm-alpha-support.md)。 重要的运行时表面： - CLI：`src/cli/index.js` - MCP 工具定义：`src/mcp/tool-definitions.js` - stdio MCP SDK 服务器：`src/mcp/stdio.js` - 本地调用测试工具：`src/mcp/invoke.js` - 发布门控：`scripts/check-release-readiness.js` ## 文档 - [贡献](CONTRIBUTING.md) - [支持](SUPPORT.md) - [安全政策](SECURITY.md) - [项目计划](docs/project-plan.md) - [项目状态](docs/status.md) - [公开就绪状态](docs/public-readiness.md) - [Alpha 就绪状态](docs/alpha-readiness.md) - [真实代码库审计报告](docs/real-repo-audit-reports.md) - [产品定位](docs/product-positioning.md) - [近期路线图](docs/near-term-roadmap.md) - [Adapter 强化计划](docs/adapter-hardening-plan.md) - [演示脚本](docs/demo-script.md) - [决策日志](docs/decision-log.md) - [第二个 Adapter 试点](docs/second-adapter-spike.md) - [Kotlin/JVM Alpha 支持](docs/kotlin-jvm-alpha-support.md) - [Go Alpha 支持](docs/go-alpha-support.md) - [Go 验证搜寻报告](docs/go-validation-hunt-report.md) - [Go HTTP 验证报告](docs/go-http-validation-report.md) - [Go 工作区所有权验证报告](docs/go-ownership-validation-report.md) - [Go dot-import 验证报告](docs/go-dot-import-validation-report.md) - [Kotlin/JVM 验证搜寻报告](docs/kotlin-jvm-validation-hunt-report.md) - [Adapter 契约](docs/adapter-contract.md) - [Artifact 契约](docs/artifact-contract.md) - [CLI 参考](docs/cli-reference.md) - [项目检测](docs/project-detection.md) - [多语言工作流](docs/polyglot-workflow.md) - [MCP 工具表面](docs/mcp-tools.md) - [MCP 客户端配置](docs/mcp-client-config.md) - [MCP 部署](docs/mcp-deployment.md) - [本地诊断](docs/diagnostics.md) - [Agent 安装路径](docs/agent-install-paths.md) - [发布生命周期](docs/release-lifecycle.md) - [发布检查清单](docs/release-checklist.md)

标签：AI辅助开发, Homebrew安装, MITM代理, SOC Prime, 云安全监控, 开发工具, 数据可视化, 数据管道, 文档结构分析, 日志审计, 测试自动化, 自定义脚本, 软件工程, 逆向工具, 防御加固, 静态分析