zzop

zzop ( Zero Zone Of Pain )

[CI] [npm] [License: MIT]

zzop reads a whole repository and answers the same way every time — one tree, or a frontend and a backend joined so you can see which calls reach which routes and which reach nothing.

zzop is a kernel you attach to your own source environment. It turns source into one language-neutral IR, builds the dependency graph and the cross-tree join over it, runs rules, and writes one JSON reply that says what it found and what it could not see. What it reads and what it judges is yours to inject: a parser or adapter for your stack (a Normalized AST envelope, or an overlay on top of a native parse), your own conventions in the config, your own rule packs. Each run names the next gap and how to fill it.

Built-in parsers and rule packs ship on by default — TypeScript/JavaScript, Python, Java, C#, Go and Rust, plus Prisma and SQL schemas. They are an option, not the product: the Cargo feature builtin-units carries them, and cargo build -p zzop-cli-bin --no-default-features builds the kernel alone, which analyzes only what an envelope or overlay hands it.

Same commit in, same findings out. zzop never writes code and makes no network request.

Install

Every lane installs the same two Node-free binaries: zzop (the CLI) and zzop-mcp (an MCP server over stdio, for AI agents).

Which tags carry release assets is owned by VERSIONING.md.

First three commands

A config is required — zzop guesses nothing about your project that you did not declare. Put one config at the top of your workspace; every tree under it finds it by walking up.

cd ~/work/shop            # holds ./api and ./web, each its own git repositoryzzop init                 # writes zzop.config.jsonc here, declares both repos as `trees`zzop analyze ./api        # one treezzop cross ./api ./web    # the join between them

zzop init on that layout prints what it did and the next step:

wrote .\zzop.config.jsoncadded `**/.zzop/` to .\.gitignoredeclared the 2 repositories under it as `trees`: api, webnext: `zzop cross .\api .\web` joins them under this one config; `zzop analyze .\api` reads one of them alone.

and zzop cross answers with a short screen:

zzop cross — ./api ./web  (2 trees)
read      2 of 4 files parsed across 2 treesjoined    1 edges, 1 of them between trees  (http 1)
findings  cross-layer 2  (warning 2)  warning  cross-layer/unconsumed-mutation-endpoint  src/server.ts:9  (./api)  warning  cross-layer/unprovided-mutation-call      src/users.ts:7  (./web)...next      zzop endpoint "PUT /api/users/me" ./api ./web   — who provides and who calls the first row's key, and why they did or did not joinfull      ...\shop\.zzop\last-cross.json  (38 KB, every value with its meaning — `--json` prints it here instead)

Getting started continues from here: attaching an overlay for a route zzop cannot see, adding your own rule pack, and quieting a finding.

Reading the output

• The screen (stdout, default) — what was read, what was not, the finding counts and first rows, and one next step. Follow the next line; it is how zzop guides you to the gap that matters.
• .zzop/last-<command>.json — the full reply, written beside the config that governed the run. It explains itself: its blocks carry …Meaning fields saying what each value is and is not. zzop init git-ignores .zzop/, which also holds the per-file cache (safe to delete; "cacheDir": null writes no cache).
• --json — prints the full reply on stdout instead and writes nothing. Use it from scripts.

Every finding carries a rule id, a severity, a file and line, and a message. findings.byRule and findings.bySeverity count the whole run; findings.shown is the capped list (--limit). Read warnings and coverageGaps before trusting a short list: an empty findings list can mean a clean tree or a blind run, and only those fields tell the two apart.

The exit code is 0 whatever was found. For CI, --fail-on <severity> exits 3 when a finding reaches that severity, and --baseline <file> fails only on rules that find more than the recorded baseline. zzop --help prints both, with every other knob.

Everything else

zzop --help is the canonical list of subcommands and flags, and zzop <subcommand> --help prints one. In short:

• zzop coverage <path> — how much of each tree zzop actually sees, per extension and per io channel.
• zzop file <path> <tree> — everything known about one file; --source-id picks the tree when several declare the same path.
• zzop endpoint "<METHOD> <path>" <trees> — who provides and who consumes one key, and why they did or did not join.
• zzop map <path> / zzop graph <path> — the module map as data / a picture for an external renderer.
• zzop facts <path> — the uncapped post-assembly facts, for a rule program of your own.
• zzop manifest <a> <b> and zzop diff old.json new.json — commit a structural contract and compare a later run against it (--allow-tool-drift to compare across zzop builds).
• zzop validate-envelope, zzop validate-rule-pack — check what you inject before you inject it.
• zzop analyze-envelope <envelope.json> — analyze an envelope with no native parsing at all.
• zzop explain <rule-id> — one rule's data, its suppress marker and its off-switch.
• zzop contract [<name>] — the embedded authoring contracts (envelope schema, DSL reference, rule catalog, config surface, starter config, …).
• zzop version (or zzop --version; --verbose adds each parser's fingerprint).

From an AI agent. zzop-mcp answers the same questions through the same handlers, so a tool call and a CLI run on the same path agree. The server exposes the tools analyze_repo, cross_repo, check_file, check_endpoint, check_coverage, module_map, analyze_envelope, validate_envelope, validate_rule_pack — plus zzop://contract/* resources carrying the same documents zzop contract prints, so an adapter or rule pack can be written with nothing but the binary.

Embedding. The zzop-facade crate is the JSON-in/JSON-out contract under both binaries (zzop_facade::analyze_json, analyze_trees_json, analyze_envelope_json). It is workspace-internal and not on crates.io, so in-process use means vendoring this workspace; shelling out to zzop … --json needs no linkage.

Where next

• Getting started — the guided path: two repos, an overlay, a rule pack.
• Adapters and Normalized AST — inject a parser or an overlay for a language or framework.
• Rule authoring, DSL reference and the rule catalog — write a rule pack, look up a rule.
• Architecture — how a tree becomes IR, graphs and a reply.
• Versioning — pre-1.0 (0.x): pin an exact version. Which surfaces are stable and where breaks are recorded (CHANGELOG.md).
• Contributing · Security · documentation site: https://eezz4.github.io/zzop/

License

MIT — see LICENSE.