gapproof

gapproof is a local test-gap analysis tool for a code repository. It walks the sources, extracts the functions it finds, checks which of them are mentioned by a test, and reports the gaps: functions no test appears to cover. Recorded test runs add a second, stronger signal — a function named by a passing run (directly, or through the test that links it) counts as proven, not just linked — and the two signals combine into a single coverage score.

This package is a clean-room rebuild, and a labelled core subset: it covers 12 of the 18 tools documented for the original Orangepro MCP server (orangepro_*). The omitted tools are listed under "Scope" below.

How it works — honestly

There is no AST, no parser, and no network call anywhere. The engine is a set of documented heuristics:

• Walk. Starting at the given root, it skips node_modules, .git, dist, and dot-directories. Files ending in .ts, .tsx, .js, .jsx, or .py are classified as tests when they live under test/, tests/, or __tests__/, or are named *.test.*, *.spec.*, test_*.py, or *_test.py; all others are sources.

• Extraction (regex). TypeScript/JavaScript: function name(, export function name(, and const name = (...) => (also let/var, the function keyword form, and an optional async). Python: def name(. A Python name not starting with _ counts as exported; a TS/JS name counts as exported when declared with export.

• Linking. A function is linked when its name appears as a word in some test file's content.

• Proving. orangepro_record_run appends a run (test, outcome: "pass" | "fail", optional functions) to the persisted graph. A function is proven when a passing run names the function, or names a test file / test case that links it.

• Score. 60% × linked ratio + 40% × proven ratio, reported on a 0–100 scale with one decimal place.

• RTM. Requirement ids matching [A-Z]+-\d+ are read from source comments only (//, /* … */, #) and associated with the functions defined in the same file.

State lives in one file: <root>/.gapproof/graph.json, written by orangepro_start and orangepro_record_run. Everything else reads the repository (and that graph, when runs matter) without writing.

Related MCP server: repo-guardian

Install

npx @reneturcios/gapproof orangepro_start '{"root":"/path/to/repo"}'

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/gapproof

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead. No API key is needed — the original's optional model key only powers its AI test-generation tools, which this subset omits.

CLI

The CLI mirrors the tools: one subcommand per tool, taking its arguments as a single JSON object.

gapproof orangepro_start '{"root":"/path/to/repo"}'
gapproof orangepro_analyze_sources '{"root":"/path/to/repo"}'
gapproof orangepro_find_test_gaps '{"root":"/path/to/repo","limit":10}'
gapproof orangepro_status '{"root":"/path/to/repo"}'
gapproof orangepro_record_run '{"root":"/path/to/repo","test":"math.test","outcome":"pass"}'
gapproof orangepro_export_evidence_pack '{"root":"/path/to/repo"}'
gapproof --version

Exit codes: 0 on success, 1 on an analysis or validation error, 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/gapproof mcp

MCP client configuration:

{
  "mcpServers": {
    "gapproof": {
      "command": "npx",
      "args": ["-y", "@reneturcios/gapproof", "mcp"]
    }
  }
}

Tools

All tools take root (the repository path) unless noted.

Scope

Omitted from this core subset: orangepro_prove_loop, orangepro_prove, orangepro_generate_tests, orangepro_update_graph, orangepro_ai_links, and orangepro_ai_flows. Those are the original's proof-execution and AI-assisted tools; the AI flows need a model key in the original. This subset reproduces the local analysis surface only, with the heuristic limits stated above: name-based linking can miss indirect coverage and can credit a coincidental mention, and comment-based RTM extraction only sees ids written in comments.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, in-memory fixture repo, no network, no disk
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.