Repo Test Architect

Audit-first test strategy tooling for codebases.

Repo Test Architect builds a deterministic audit graph before asking any model or agent to reason about tests. The goal is to identify repo-native, high-value test work from facts the tool can inspect locally: project roots, framework signals, existing tests, source classifications, blockers, and remaining risk.

The current implementation can:

audit JavaScript/TypeScript, PHP, Python, Ruby, and Swift projects through supported adapters
audit supported, bounded Kotlin/JVM fixtures through the same shared artifact model
audit conventional Go modules and literal repository-contained go.work members through a supported bounded adapter
audit conventional Cargo packages and literal repository-contained workspace members through a supported bounded Rust adapter
audit one conventional SDK-style C# test project or one unique literal production/test project edge, including bounded native xUnit MTP-v2 and MSTest.Sdk v4 ownership, literal and one-hop root-aliased target frameworks, one repository-contained direct *.cs compile include, finite target-conditioned package shapes, bounded nearest-file build and central-package props, exact immutable test-field receivers, stable direct-call results, inline out results, framework exception and collection/string assertions, one-hop test helpers, and guarded well-known System type collisions, through a supported bounded .NET adapter
audit one conventional Composer/PSR-4 project with PHPUnit through a supported bounded PHP adapter
audit one conventional Mix application with exact MixProject/Mixfile, bounded source and Mix-task ownership, literal local ExUnit wrapper discovery, and test-body evidence through a supported bounded Elixir adapter
detect polyglot project roots and report unsupported ecosystems without hiding them
produce a complete repository analysis, findings, ranking, plan, execution hints, and verification commands in one audit pass
classify source files by likely test value and defer low-value direct tests
rank candidates and generate test plans from the audit graph
derive provider-neutral execution, context, parallel-safety, and repository-reasoning hints without selecting models or spawning subagents
analyze conservative test placement findings across project boundaries
collect project-level stats for coverage, candidate counts, frameworks, commands, and adapter usage
provide disabled-by-default local MCP diagnostics, safe internal-error report IDs, runtime checks, and inspectable sanitized bundles without external reporting
expose the same deterministic behavior through CLI commands, a local invoke harness, and a stdio MCP SDK server
lock behavior with golden snapshots, model-consistency scenarios, package checks, and cross-OS CI

Native test generation is intentionally deferred. generate_selected_test returns a structured deferred artifact until adapter-specific generation policy and repair-loop fixtures exist.

Repo Test Architect 1.0.0-beta.2 is available as an opt-in public beta on npm and the Official MCP Registry. The unqualified npm command remains on 0.3.0 while the beta is evaluated. Treat its findings as evidence-backed review input rather than an automatic instruction to change a repository. See the beta release notes.

Beta.2 adds experimental Dart/Flutter support and adapter trust fixes. The @beta commands below select beta.2; see the release notes and validation plan. Dart remains experimental, and native generation remains deferred.

Install

Node.js 20 or newer is required.

Run the CLI without a global install:

Terminal

npx --yes repo-test-architect doctor
npx --yes repo-test-architect analyze .

Try the public beta without changing the default npm channel:

Terminal

npx --yes repo-test-architect@beta doctor
npx --yes repo-test-architect@beta analyze .

Or install the CLI and MCP server binaries:

Terminal

npm install --global repo-test-architect
repo-test-architect doctor
repo-test-architect analyze .

Add the local stdio MCP server to an MCP-capable client:

config.json

{
  "mcpServers": {
    "repo-test-architect": {
      "command": "npx",
      "args": [
        "--yes",
        "repo-test-architect",
        "mcp"
      ]
    }
  }
}

To opt into the public beta, pin the npm beta channel in the MCP configuration:

config.json

{
  "mcpServers": {
    "repo-test-architect": {
      "command": "npx",
      "args": [
        "--yes",
        "repo-test-architect@beta",
        "mcp"
      ]
    }
  }
}

The client launches the server locally. Repository source stays on the machine unless the client or another configured tool sends it elsewhere. Connected models receive instructions to start with analyze_repository for a general repository review. See MCP client config and agent install paths for global-install, local-checkout, and host-specific guidance.

Quick Start

For a human-readable review of the current repository:

Terminal

npx --yes repo-test-architect analyze .

analyze detects every project root, runs each supported adapter once, and derives the audit summary, top findings, candidate ranking, test plan, execution hints, project stats, and verification commands. Markdown stays compact; JSON preserves the complete evidence bundle:

Terminal

npx --yes repo-test-architect analyze . --format json
npx --yes repo-test-architect analyze . --changed

Useful focused views:

Goal	Command
Complete repository review	`repo-test-architect analyze .`
Concise architecture findings	`repo-test-architect findings-projects .`
Actionable cross-project plan	`repo-test-architect plan-projects .`
Raw reusable project audits	`repo-test-architect audit-projects . --format json`
Runtime readiness	`repo-test-architect doctor`

Run repo-test-architect --help for the short command map or repo-test-architect <command> --help for options. The CLI reference documents the full surface.

For an MCP-connected model, the equivalent default is analyze_repository. Use narrower tools only when the request asks for one artifact or already supplies an audit artifact.

Current Scope

Available adapters:

dart (experimental): Dart and Flutter pubspec packages, conventional package:test and flutter_test entrypoints, exact library-import evidence, widget test recommendations, and bounded dart test / flutter test commands; see Dart and Flutter support
csharp: one static SDK-style test project or one unique literal production/test project edge, including bounded native xUnit MTP-v2 and MSTest.Sdk v4 ownership, exact literal or one-hop root-aliased target membership, one repository-contained direct *.cs compile include, finite project-local target-conditioned package predicates, and a pair selected amid unrelated projects, with bounded nearest-file Directory.Build.props metadata and static Directory.Packages.props versions, xUnit, NUnit, or MSTest attributed tests, exact project-file commands, runnable-body-owned direct type calls, bounded concrete-local or immutable test-field receivers, one-hop stable direct-call, receiver-call, or inline out var result assertions, bounded exception assertions, and one same-class private-static test-helper hop; see the C# alpha support matrix
elixir: one conventional Mix application with literal app and exact MixProject/Mixfile ownership, conventional/app-prefixed modules and protocols, exact Mix tasks, bounded acronym, terminal-plural, repeated-declaration, and compiled local ExUnit-wrapper ownership, static startup options, test-body-scoped direct fully qualified or exact-alias calls, conservative filename evidence, and a blocker-free mix test command; see Elixir alpha support
javascript: JavaScript/TypeScript repositories with Node's test runner (including TypeScript execution scripts), Bun test, AVA, Mocha/CommonJS, Vitest, Jest, Playwright, Cypress, Express/Supertest, React Testing Library detection, and bounded literal browser request-to-route evidence; see the alpha support matrix for evidence boundaries and known gaps
go: conventional go.mod projects and literal repository-contained go.work members using runnable standard-library TestXxx, FuzzXxx, or ExampleXxx tests, package-local filename, unique top-level and parser-owned concrete receiver-method symbols through explicit types, exact simple constructor results, or exact statically typed test-helper results, bounded standard-library and Testify assertion usage, parser-scoped local shadow checks, same-package or exact external-package imports (including dot imports), generic top-level functions, and bounded callable-body-owned same-package or module-local source hops, module-local commands, and optional explicit GOOS/GOARCH/custom-tag selection; see the alpha support matrix for the supported boundary and blockers
kotlin: conventional Gradle/Maven JVM module roots, settings-owned Gradle aggregates, and root-declared Maven reactors with Kotlin and/or Java standard source sets, dependency-qualified direct/exported-transitive module evidence, JUnit 4/5, kotlin.test, bounded Gradle/JUnit Platform Kotest common specs, conventional Gradle/Spock features, and method-level TestNG through direct Maven dependencies or Gradle useTestNG(); see the Kotlin/JVM alpha support matrix
php: one root Composer project with literal string-valued PSR-4 source/test ownership, bounded literal autoloaded function files, statically declared PHPUnit, exact bounded commands or explicit safe command withholding, conventional runnable test classes including one unique source- or test-owned PHPUnit base edge, direct imported or exact same-namespace class calls, and conservative basename fallback; see PHP alpha support
python: bounded Python package, FastAPI, Django, and Flask layouts with declarative multi-package/namespace ownership, configured pytest discovery, exact absolute/relative imports, one-hop source dependency evidence, static framework test-client route evidence, pytest/unittest, async and property-based extensions, fixture reachability, pip/setuptools, uv, Poetry, Hatch, tox, nox, and coverage configuration; see the Python alpha support matrix
rust: conventional Cargo packages and literal repository-contained workspace members using the built-in #[test] harness, inline #[cfg(test)] modules, exact exclusion of external test-only module graphs, exact crate-module imports from tests/, and exact unconditional crate-root symbol re-exports; see the Rust alpha support matrix
ruby: one conventional Bundler project with lib/ sources, one root gemspec or a complete exact named root-gemspec set, runnable Minitest::Test test_* methods or RSpec examples, exact bounded commands, root .rspec and exact per-file spec_helper loading, three-edge literal require/unique-constant evidence, exact singleton calls, exact constant-owned RSpec described_class, direct immutable constructor-local, one-line RSpec let/subject, exact source-factory and same-group RSpec helper receivers, and exact same-file literal shared-example inclusion, bounded assertion usage, conservative basename fallback, and explicit Minitest-spec/Rails/mixed-runner blockers; see the Ruby alpha support matrix
swift: Swift Package Manager, Xcode-style and Bazel/rules_swift layouts, Swift Testing, XCTest, Quick/Nimble, SnapshotTesting, VaporTesting/XCTVapor, reactive frameworks, and generic Fluent database boundaries with driver-specific qualifiers; see the Swift alpha support matrix

Project detection reports Elixir Mix roots through the supported bounded adapter. Unsupported ecosystems remain visible so clients can distinguish "not audited yet" from "not present."

Don't see your stack? Open an adapter request with the language or ecosystem, build system, test frameworks, and—when possible—a representative public repository. Requests help prioritize adapters against real repository shapes and user demand.

The public package exposes the audit CLI, the stdio MCP server, and a deterministic MCP invoke harness under the stable binary names documented below.

Advanced CLI and Contributor Reference

The commands below expose focused artifacts, fixtures, evals, diagnostics, and release checks for advanced use and repository development.

Show the complete command and development reference

Run the complete analysis directly or against the polyglot example:

Terminal

npm run analyze
npm run analyze:json
npm run analyze:example
npm run analyze:example:json

Check runtime and diagnostics readiness:

Terminal

npm run doctor
npm run doctor:json

Local MCP diagnostics are disabled by default. They can be explicitly directed to stderr or a bounded local JSONL file; see Local diagnostics. Build a sanitized, inspectable bundle with:

Terminal

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

List registered adapters:

Terminal

npm run adapters
npm run adapters:json

Inspect project detection marker rules:

Terminal

npm run detect-rules
npm run detect-rules:json

Detect project roots and adapter matches:

Terminal

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

For project-aware self-audits, exclude checked-in fixture or sample roots with a quoted subtree pattern:

powershell

node ./src/cli/index.js findings-projects . --exclude-project "examples/**"

Reuse a saved project audit artifact:

powershell

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

Terminal

npm run audit:example
npm run audit:kotlin-fixture

Output the structured audit graph:

Terminal

npm run audit:example:json
npm run audit:kotlin-fixture:json

Generate an actionable test plan from the audit graph:

Terminal

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

Derive advisory execution hints while leaving the plan artifact unchanged:

powershell

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

The installing CLI or agent host remains responsible for model choice, budgets, permissions, context loading, and subagent lifecycle.

Explain one audited target by stable target ID:

Terminal

npm run explain:example

Rank test candidates without generating tests:

Terminal

npm run rank:example

Analyze existing test placement from audit evidence:

Terminal

npm run placement:example
npm run placement:example:json
npm run placement:from-audit:example

Exercise the MCP-style tool surface:

Terminal

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

Generate a plan from an existing audit JSON file:

Terminal

npm run plan:from-audit:example

Run the auditor regression tests:

Terminal

npm test
npm run alpha:check
npm run release:check

Find and rank active public repositories for real-world adapter validation:

Terminal

npm run validation:repos -- --profile react
npm run validation:repos -- --profile workspace --limit 10
npm run validation:repos -- --profile swift,gradle,maven --format json

The finder uses authenticated GitHub repository search, verifies exact ecosystem markers in root manifests, and ranks candidates using maintenance recency, stars, repository size, lockfiles, CI, and license metadata. Run npm run validation:repos -- --list-profiles for the available profiles and --help for quality-filter options.

Check that every supported adapter has a complete, pinned hardening corpus:

Terminal

npm run corpus:check
npm run corpus:scorecard
npm run corpus:measure -- --case python-asyncer --checkout /path/to/pinned/asyncer
npm run corpus:measure -- --case python-django --checkout /path/to/pinned/django --profile-phases
npm run csharp:performance:check
npm run javascript:performance:check
npm run python:performance:check
npm run kotlin:performance:check
npm run rust:performance:check
npm run swift:performance:check
npm run go:performance:check
npm run ruby:performance:check
npm run php:performance:check

The versioned evals/validation-corpus.json manifest records one conventional library or service, one framework-heavy application, and one difficult ownership graph per adapter cohort. Every supported adapter must have a complete cohort; a registered experimental adapter may be added only with all three roles. Each record carries the shared detection, ownership, command, evidence, ranking, stability, and performance scorecard. The 33 current pins span ten supported adapters and experimental Dart, with all 231 bounded scorecard areas passing. Dart live validation also records native upstream suite results and remaining limits. A reviewed command may be null when the adapter correctly withholds unsafe execution. Cases may also carry bounded adapter audit options, such as an explicit Go build target, so repeated measurements remain host-independent.

corpus:scorecard renders the review contract for humans. It reports review completeness separately from the pass rate among reviewed checks and keeps PASS, FAIL, and PENDING visible for every area. Use npm run corpus:scorecard -- --format json for the deterministic validation-scorecard/v1 view. These are validation-review results, not a repository-quality rating.

corpus:measure verifies the checkout's exact pinned Git SHA, runs the selected adapter at least three times, rejects canonical audit drift, and reports the raw durations, median duration, evidence-link count, and normalized audit digest used to update the scorecard. For the exact Python and Swift pins, --profile-phases defaults to five runs and additionally reports ordered samples and medians for traversal/text reading, project/build ownership, source discovery/indexing, test parsing/indexing, and evidence/classification/artifact assembly. These development timings are callback-only and never enter audit/v1, CLI/MCP audit output, or local MCP diagnostics.

Each adapter performance check separately runs a generated 400-source/200-test project, verifies its candidate and evidence counts, and enforces a broad cross-platform regression ceiling. The Rust gate includes one additional skipped src/lib.rs module-wiring target required to declare the 400 behavioral modules. These synthetic gates complement the recorded per-repository corpus distributions.

Use alpha:check for the adapter-support milestone. release:check additionally covers packaging and installed-binary readiness.

The CI workflow keeps one stable Linux pr-gate: documentation-only changes run focused contract tests, normal changes run npm run alpha:check, and distribution-sensitive changes run npm run release:check. Windows runs only for runtime and portability changes; macOS runs only for Swift-sensitive changes. A merge to master runs the complete release gate on Linux, while manual dispatch runs the full release gate on all three operating systems.

The tests include golden audit and plan snapshots under evals/expected, driven by evals/fixtures.json, plus shared adapter-conformance checks for deterministic JSON, portable paths, evidence semantics, and downstream artifact agreement. JSON schemas and the signal registry for versioned artifacts live under schemas/.

Refresh snapshots after intentional audit behavior changes:

Terminal

npm run eval:check
npm run eval:summary
npm run eval:test
npm run eval:update

Check model-consistency scenario locked fields against deterministic tool results:

Terminal

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

Node 20 or newer is required for the CLI. The default smoke check is portable across platforms:

Terminal

npm run smoke

If Node is not available yet, the repository still includes a PowerShell smoke check:

powershell

powershell -ExecutionPolicy Bypass -File ./scripts/smoke.ps1

Check package contents before publishing:

Terminal

npm run pack:check
npm run bin:check
npm run installed-package:check
npm run distribution:check
npm run release:check

distribution:check validates packaging and MCP metadata preparation. The stricter distribution:check:publish verifies that the public npm and MCP Registry identities are aligned before a release. See Distribution.

Shape

txt

src/
  core/
    audit-model.ts
    audit-phase-timing.js
    plan-execution-hints.js
    plan-execution-hints.ts
    repository-text-files.js
    report.js
    report.ts
  diagnostics/
    diagnostics.js
  adapters/
    csharp/
      audit.js
    javascript/
      audit.js
      audit.ts
    kotlin/
      audit.js
    python/
      audit.js
    rust/
      audit.js
    swift/
      audit.js
  cli/
    index.js
examples/
  csharp-sdk-project-pair/
  csharp-sdk-unique-pair/
  csharp-sdk-xunit-basic/
  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/
  rust-cargo-basic/
  rust-cargo-workspace-basic/
  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, PHP, Python, Ruby, Swift, bounded Kotlin/JVM modules, bounded Go modules, bounded C# SDK project shapes, and bounded Rust Cargo packages are supported adapter proof points. PHP support covers the bounded Composer/PSR-4/PHPUnit ownership, command-withholding, and evidence rules in PHP Alpha Support. Ruby support covers the bounded Bundler/Minitest/RSpec ownership and evidence rules in Ruby Alpha Support. Rust support includes literal repository-contained workspace members, exact package commands, built-in test ownership, literal module graphs, exact test-only module exclusion, direct logical-module imports, inherent associated calls, and exact unconditional crate-root symbol re-exports as defined in Rust Alpha Support. C# support covers one conventional SDK-style test project or one unique literal production/test project edge, including bounded native xUnit MTP-v2 and MSTest.Sdk v4 ownership, exact literal or one-hop root-aliased target membership, one repository-contained direct *.cs compile include, finite target-conditioned package predicates, and a pair amid unrelated projects, with bounded nearest-file build metadata and static central package versions, exact test-project commands, runnable-body-owned direct type calls, bounded concrete-local or immutable test-field receivers, one-hop stable direct-call, receiver-call, or inline out var result assertions, bounded exception assertions, and one same-class private-static test-helper hop while solution ownership remains excluded. Go support includes literal repository-contained go.work members, explicit static build-target selection, bounded standard-library/Testify assertion usage, parser-scoped receiver identity through concrete local and test-helper bindings, and callable-body-owned source evidence as defined in Go Alpha Support. Kotlin/JVM support is limited to conventional Gradle/Maven modules and directly declared aggregate graphs, JUnit, the documented Kotest common-spec and Spock feature variants, or method-level TestNG, and standard source sets as defined in Kotlin/JVM Alpha Support.

Important runtime surfaces:

CLI: src/cli/index.js
MCP tool definitions: src/mcp/tool-definitions.js
stdio MCP SDK server: src/mcp/stdio.js
local invoke harness: src/mcp/invoke.js
release gate: scripts/check-release-readiness.js

Repo Test Architect README

Repo Test Architect

Install

Quick Start

Current Scope

Advanced CLI and Contributor Reference

Shape

Docs