The JSON contract

The shared operations

Every operation below is reached three identical ways — a zzop CLI subcommand, a zzop-mcp MCP tool, and an in-process call — over one shared implementation (crates/facade, plus crates/summary for the config auto-discovery and result-shaping the CLI and MCP tools get). Same request in, same JSON out, whichever surface you use; all are JSON-string-in / JSON-string-out except version.

A config is required; a starter config runs the full analysis

Every analysis lane refuses a tree with no zzop.config.jsonc — the same refusal, naming the same document, on both shipped binaries. It is not ceremony: the vocabulary block holds the names zzop would otherwise have to guess about your project, and an undeclared key is a judgment zzop does not make — name-based auth exemptions, generated-file detection and write-site judgments all switch off with it. zzop init writes that file with zzop's own values already in it.

Everything else still defaults. A starter config that declares only roots runs the full analysis on both binaries alike — both route through the shared zzop-summary layer and its zzop-config crate, which injects the bundled DSL rule packs (compiled into the binary), the engine's recentDays: 30 git default, and a cacheDir of .zzop/cache:

The one thing a starter config cannot supply is a second tree: a single root leaves the cross-layer join nothing to join. On a workspace root whose pnpm-workspace.yaml (or package.json workspaces) resolves to 2+ packages, the run's first configWarnings entry names the manifest, the exact package count, and the {"trees": "auto"} remedy.

zzop init        # writes zzop.config.jsonc — required once per tree
zzop analyze .   # that config is auto-discovered; bundled packs +
                     # git defaults fill in everything it did not say

Calling zzop_facade::analyze_json directly has no such wrapper in front of it — the facade applies no implicit defaults. A bare {"root": "."} config JSON loads zero DSL packs (native analyses only) and runs with git collection off (scores/health/recommendations stay null) unless you set packsDir/packDefs and git yourself:

let config = serde_json::json!({ "root": ".", "git": {} }).to_string();
let result: serde_json::Value =
    serde_json::from_str(&zzop_facade::analyze_json(&config)?)?;

• packsDir omitted (facade) — no DSL packs load at all; pass packsDir (a directory of *.json packs) or packDefs (inline definitions — see below) explicitly.
• packsDir given, multiple directories — all are loaded and merged; if two directories ship a pack with the same id, the later directory replaces that pack whole (not a rule-by-rule merge).
• packDefs given — loaded before any packsDir entries, so a directory pack with the same id wins the collision whole. This is how a host with no pack directory on disk (like zzop-mcp, whose zzop-config layer injects the bundled packs this way) supplies rules at all.
• git omitted (facade) — git collection is off; scores, health, recommendations, critical, seams, and layerCoChurn stay null. Pass git: {} to enable them with the engine's own recentDays: 30 default, or git: { "recentDays": N } to override it. If root is not a git repository, the engine degrades gracefully and reports it in warnings.
• cacheDir omitted — the one default that writes to disk, and so the one worth knowing which dialect you are in. Under zzop/zzop-mcp/a config file it defaults to .zzop/cache, resolved against the config file's directory (or the analyzed root when there is no config file), and the first run creates it inside the tree you analyzed — put an anchored **/.zzop/ in that repo's .gitignore, not a zzop* glob, which would also swallow the authored zzop/ directory (custom rule packs, adapter overlays) that belongs in version control. Set the key to null to turn caching off and write nothing. Calling the facade directly injects no default at all: omit the field and the run is uncached, with nothing written.
• vocabulary omitted — nothing is injected and nothing falls back — on every path, a key you do not declare is simply not judged (the built-in fallback arm was removed 2026-07-27). The built-in values survive only as what zzop init writes into your starter file, so they reach a run because your config says them. Writing the block therefore changes a great deal: leaving it out makes rules fire more, not less, because an undeclared guard vocabulary proves no guard and an undeclared exemption grants no exemption.

AnalyzeRequest

#[serde(rename_all = "camelCase", default)] — every field is optional except root, and unknown fields are ignored rather than rejected.

analyzeEnvelope's config (EnvelopeAnalyzeRequest) is a smaller shape: sourceId, packsDir, packDefs, disabledRules, severityOverrides, suppressions, globalExcludes, mountedAt, mounts, and clientBase only (packDefs and the middle four behave identically to their AnalyzeRequest counterparts). mountedAt/mounts carry the same deployment-topology mount semantics described above, applied uniformly to the envelope's http provides, with the same fold order (every mounts entry first, mountedAt as the implicit whole-tree dir: "" entry last). An envelope carries no filesystem location the engine can re-read, so root, cacheDir, git, and sizeCap don't apply — only symbol-scan/io-scan DSL rules ever fire in envelope mode, since no source text is available. The native call-graph-BFS rules (mutating-route-no-auth, unsafe-read-endpoint, non-idempotent-write) additionally run when the envelope supplies its calls channel (per-file call edges, files[].calls — see NORMALIZED_AST.md's calls section, floor version >= 0.29.0); an envelope with http routes and no calls keeps them silent and says so in warnings, naming the silent rules. The two shipped io-scan rules (http/protected-path-no-auth-evidence, http/dev-path-no-guard-hint) do run here, but their anchor-line channels do not: with no source text there is no line to read, so the derived zzop-<rule-id>-ok suppress marker and dev-path-no-guard-hint's anchor_exclude_pattern guard-hint carve-out are both inert. Both fail toward FIRING rather than silence — a matching route reports even when its registration line carries a marker or a guard-hint argument — so clear a vetted route by injecting the attribute the rule reads (auth-guarded for protected-path-no-auth-evidence) or by disabling the rule in config. Mode-B adapterOverlays are unaffected: they merge onto a natively-parsed tree whose source text is readable, so both channels stay live there.

Reference Mode-B adapters ship in the repo as worked examples — a minimal one-channel adapter (fills a missing imports channel in ~90 lines, the smallest on-ramp) and an attribute-injection adapter (injects router-level guards as file attributes), both built on the shared adapter-kit. They demonstrate the contract rather than one framework each: framework-specific flavors were removed in favour of the channels an adapter actually has to fill.

Beyond IO and dependency facts, an overlay can carry generic entity attributes: open-vocabulary { target, key, value } annotations attached to a route, symbol, file, or path scope that a rule consumes by key, without the engine ever knowing what the key means. This is how a cross-cutting fact the native pass can't see on its own — a rate limit, a validation layer, or (for anything outside the common Express shapes the native parser now recognizes directly) a router-level auth guard applied by middleware — is completed by injection instead of by ever-growing native modeling. The first consumer is mutating-route-no-auth: inject an auth-guarded attribute on a route's ioKey (or a pathScope prefix a middleware guards) and the rule clears it, composing with its native call-graph scan and with the same attribute the native parser itself emits for a recognized Express guard. The second consumer is cross-layer/retrying-write-no-idempotency: an idempotency-guarded attribute on the provider route — set natively by the TypeScript parser when a handler reads the Idempotency-Key header, or injected for any other provider language — vetoes the finding once a guard is witnessed.

Analyzing multiple repositories together

analyze_trees_json (CLI: zzop cross; MCP tool: cross_repo) runs analyze once per tree, then joins every tree's declared IoFacts (HTTP/DB/tRPC provides and consumes) across all of them. A frontend checkout and a backend checkout can be two entirely separate git repositories that share nothing on disk and still get joined.

let config = serde_json::json!({
  "trees": [
    { "root": "../frontend", "sourceId": "web" },
    { "root": "../backend",  "sourceId": "api" },
  ]
}).to_string();
let result: serde_json::Value = serde_json::from_str(&zzop_facade::analyze_trees_json(&config)?)?;

// Or from the CLI (trees tagged by directory name; use --config for custom sourceIds / topology):
// zzop cross ../frontend ../backend

The result shape is { trees: [{ root, sourceId, output }], crossLayer, crossLayerFindings, disclosure }. Each tree's output carries its own coverage census; disclosure (the silent-failure-class registry) is run-global and appears once. crossLayer carries the raw join result — matched edges, unconsumedProvides, unprovidedConsumes, unresolvedConsumes, ambiguousConsumes multi-tree matches, and externalConsumes (absolute-URL) consumes. When any tree declares topology hosts, crossLayer also carries hostRekeyCounts — one [host, rekeyedConsumeCount] pair per declared host, omitted entirely when no tree declares any hosts. crossLayerFindings is the output of the cross-layer/* native rules that run over that join (see the rule catalog for the full id list). No single tree owns a cross-layer finding, so disabling one of these rule ids via disabledRules on any one tree drops it from the combined array for every tree — a union, not a per-tree gate. A tree whose coverage.joinContributionZero is true contributed no IO to this join — discount any cross-layer finding that references it.

AnalyzeOutputView

Same input, byte-identical output — no timestamps, no unstable map/array ordering. A capability a given run cannot provide is absent from the schema and self-reported in warnings, never stubbed with a fake empty value. An empty array, by contrast, always means "this was analyzed and nothing was found."

The whole JSON tree is camelCase, top to bottom — every nested type carries its own casing rule, not just the top-level view. Finding.data is the one deliberate exception: opaque, rule-authored JSON with no uniform casing rule.

What a severity asserts. Severity states zzop's confidence in that one finding, and that confidence is bounded by what this run could see — zzop reads source and never probes a running system. Two cross-layer rules make the bound visible by de-escalating themselves: cross-layer/unconsumed-mutation-endpoint and cross-layer/unprovided-mutation-call report at info rather than warning when the run holds a source whose HTTP calls came back mostly unresolved (respectively, a source that imports a server framework yet yielded almost no routes), naming that source in the message; the finding fires either way, so this is a confidence match and not suppression. The converse does not follow, and the warning-branch message says so itself: each blindness check is one narrow predicate, so a rule holding at warning means blindness was not witnessed — not that coverage was proven complete. A caller in a call shape or language this extraction does not model, or in a repository outside the run, is invisible to the check exactly as it is to the rule. Read warnings and the coverage census below for the run's own account of its limits before treating a severity as a verdict.

A narrowed scope self-reports in warnings, never silently

An error means the call failed. A missing capability is not an error — the analysis completes normally, and the engine says exactly what it skipped and why. This self-report happens inside the engine itself, not the JS wrapper, so it applies identically to a non-JS consumer calling the Rust engine directly.

"warnings": [
  "git history not requested (git option omitted): scores, health,
   recommendations, criticality, seams and layerCoChurn are null.
   Pass git: {} to enable them."
]

The same pattern applies when no DSL rule packs could be found: the engine reports that only its native analyses ran, and names how many, rather than returning a quietly smaller findings array with no explanation.

The process never crashes

crates/facade/src/lib.rs (crate zzop-facade) never panics by contract — every fallible path (malformed JSON, a missing root, an invalid envelope) returns a Result<String, String> instead. The engine already isolates a single file's parse/rule failure internally, well before it would ever reach that outer boundary. A direct Rust caller sees either Ok(String) or Err(String), never a process abort; the zzop-mcp binary calls these functions with no FFI boundary in between, so there is no separate addon-side catch_unwind layer to reason about — the facade's own contract is the whole story. version_string has no Result at all — it cannot fail.