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, Python, 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 an experimental bounded Rust 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 is an early public alpha. Treat its findings as evidence-backed review input rather than an automatic instruction to change a repository.

Install

Node.js 20 or newer is required.

Run the CLI without a global install:

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

Or install the CLI and MCP server binaries:

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:

{
  "mcpServers": {
    "repo-test-architect": {
      "command": "npx",
      "args": [
        "--yes",
        "repo-test-architect",
        "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:

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:

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

Useful focused views:

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:

• 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
• 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 (experimental): conventional Cargo packages and literal repository-contained workspace members using the built-in #[test] harness, inline #[cfg(test)] modules, and exact crate-module imports from tests/; see the Rust experimental 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 also reports unsupported Ruby, PHP, Elixir, and .NET roots 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.

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

npm run doctor
npm run doctor:json

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

npm run adapters
npm run adapters:json

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

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

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

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

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

npm run explain:example

npm run rank:example

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

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

npm run plan:from-audit:example

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

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

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

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

npm run smoke

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

Shape

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
    rust/
      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/
  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, Python, Swift, bounded Kotlin/JVM modules, and bounded Go modules are supported adapter proof points. The experimental Rust adapter adds conventional Cargo package audits, including literal repository-contained workspace members with exact package commands, while its evidence boundary is hardened. 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

Docs

• Contributing
• Support
• Security policy
• Project plan
• Project status
• Public readiness
• Alpha readiness
• Real repository audit reports
• Product positioning
• Near-term roadmap
• Adapter hardening plan
• Demo script
• Decision log
• Second adapter spike
• Kotlin/JVM alpha support
• Go alpha support
• Go validation hunt report
• Go HTTP validation report
• Go workspace ownership validation report
• Go dot-import validation report
• Go constructor-result validation report
• Go cross-package source validation report
• Go assertion-usage validation report
• Go parser-scoped binding validation report
• Go receiver and callable ownership validation report
• Go test-helper receiver validation report
• Rust experimental support
• Kotlin/JVM validation hunt report
• Adapter contract
• Artifact contract
• CLI reference
• Project detection
• Polyglot workflow
• MCP tool surface
• MCP client config
• MCP deployment
• Local diagnostics
• Agent install paths
• Release lifecycle
• Release checklist