gen-system Understand

gen-system

Review code changes with facts from a parser, not guesses from a model.

WHAT IT DOES

AI writes more code than people can read. gen-system reads your code with parsers and tells you, for each change:

• what may break: a removed function that is still called, a changed signature with callers outside the change;
• what it now touches: the database, files or the network;
• whether any test reaches it;
• how much it grew: new branches.

No model takes part. The same change always gets the same answer.

$ understand-review --base main

## May break (2)
- store.go:8 Save changed its signature from (name string) error to (name string, force bool) error;
  1 caller outside this change: Main (main.go:3)
- store.go:9 Old was removed but is still called from 1 place: Main (main.go:3)

## New side effects (2)
- store.go:8 Save now touches files
- store.go:25 Fresh is new and touches the network

## No test reaches these (2)
- store.go: Save, Fresh

## Grew (1)
- store.go:12 Helper has 3 more branches (0 to 3)

USE IT

It reads Go, Python, TypeScript, Java, COBOL with copybooks and CA Gen, one hand written parser each. docs/review.md explains every check and its limits.

The Studio: what a routine calls, and its control flow graph. Try it in your browser, no install.

SYNOPSIS

understand-review --root DIR [--base REV] [--diff FILE] [--json] [--fail-on LEVEL]
understand-mcp    --root DIR [--copybooks DIRS] [--allow-corrections] [--no-watch]
understand-server --root DIR [--copybooks DIRS] [--port 28080] [--stdlib auto|none|LIST]
genbench          SUBCOMMAND --root DIR [--out FILE]
gen               idea --out DIR "WHAT TO BUILD"     (experiment, see below)

COMMANDS

understand-review, understand-mcp and understand-server contain no model client. A test fails the build if that changes.

MCP TOOLS

correct_belief appears only with --allow-corrections. See docs/mcp.md. review_diff reaches npx gen-understand with the next release; until then build understand-mcp from source.

THE GENERATOR (EXPERIMENT)

gen tests one idea: does the parser's call graph help a local model write code that works? It plans a Go service with qwen3:14b, writes each operation with qwen2.5-coder:14b, and each operation must compile. One that still fails after two repairs becomes a not implemented stub, and the run counts it. It needs Ollama and a 16 GB GPU. It is not the main product.

INSTALL

git clone https://github.com/hpdkhoa/gen-system.git && cd gen-system
./install.sh --understand   # only understand-server, for an air gapped review
./install.sh                # everything: also Ollama, two 14B models, one 16 GB GPU

For the MCP server alone, you need nothing but Node or Go:

claude mcp add gen-understand -- npx -y gen-understand --root ./your-repo
go install github.com/hpdkhoa/gen-system/generator/cmd/understand-mcp@latest

EXAMPLES

Review your uncommitted work, then a branch against main, and fail CI on a break:

understand-review --root .
understand-review --root . --base origin/main --fail-on break

Explore a repository in the browser:

understand-server --root ./your-repo
understand-server --root examples/payroll --copybooks examples/payroll/copybooks

Ask your agent "who calls CALC-TAX, and which paragraphs touch the database?" on the COBOL example examples/payroll. It calls call_graph and effects, and gets (shortened):

"edges":     [ { "from": "…#func:PROCESS-EMPLOYEE", "to_name": "CALC-TAX" },
               { "from": "…#func:MAIN-PARA",        "to_name": "PROCESS-EMPLOYEE" } ]
"by_effect": { "db":   [ { "name": "RECORD-RUN", "line": 78 } ],
               "pure": [ { "name": "CALC-GROSS" }, { "name": "CALC-TAX" } ] }

ENVIRONMENT

gen-system.env.example lists the rest. Copy it to .env; your shell wins over the file.

FILES

ACCURACY

On four public repositories (405 files, 268 of them COBOL) the parsers report 0 parse errors. In CobolCraft, a Minecraft server in COBOL, all 4,018 calls between its own programs and paragraphs resolve. GnuCOBOL's compiler agrees with gen-system on all 4,132 CALL and PERFORM sites, and CI checks that on every push. In four Go repositories, Go's own type checker agrees with 99% to 100% of gen-system's Go call links, and the links cover 97% to 100% of the calls into the project. On the same four repositories, Go's type checker and go test judged review_diff on edits with a known answer. It found the callers a signature change breaks with precision 0.98 to 1.00 and recall 0.87 to 1.00. It found all 306 inserted file, network and database calls and branches, and flagged 0 of 400 harmless calls. docs/results.md has the method, the limits and two corrections to earlier claims.

LIMITS

• Six languages. Other files show as unknown, with no symbols.
• The review finds callers through the call graph. A call through a function value or an interface it cannot resolve is not a caller, and "no test reaches it" means no test within the call depth it checks. docs/review.md lists the measured limits.
• COBOL is checked on one free format GnuCOBOL codebase; no numbers yet for IBM Enterprise COBOL.
• Generation writes Go, on one GPU. Body rewriting works for Go and Python only.
• The model's security review warns and never blocks.

DOCUMENTATION

CONTRIBUTING

Found code that gen-system reads wrong? Open an issue and attach .gen/beliefs.json. CONTRIBUTING.md covers bug reports, setup, tests and pull requests. Everyone follows the code of conduct.

SECURITY

Report a vulnerability privately, as SECURITY.md describes, not in a public issue.

LICENSE

Apache-2.0. See LICENSE and NOTICE. The only external Go dependency is github.com/lib/pq (MIT).