Embedding zzop

Four functions, JSON in / JSON out

All four are JSON-string-in / JSON-string-out, except version. Core logic lives in packages/napi/src/api.rs as plain Rust with no napi dependency at all (so it compiles and unit-tests under the workspace's default toolchain); packages/napi/src/addon.rs is a thin #[napi]-annotated wrapper over those same functions, gated behind the addon Cargo feature.

Zero config runs the full analysis

A bare { root: "." } request is the entire required configuration:

import zzop from '@zzop/native';

const result = JSON.parse(
  zzop.analyze(JSON.stringify({ root: '.' }))
);

The package is CommonJS, so both module systems work: import zzop from '@zzop/native' in ESM, const zzop = require('@zzop/native') in CommonJS.

Before the config crosses into Rust, the JS wrapper (index.js) injects two defaults — so a bare { root } request runs the full analysis instead of quietly degrading to native analyses only:

• packsDir omitted — defaults to the bundled DSL rule packs: <repo root>/rules/dsl in a source checkout (always the live copy), or the rules/ directory copied into the installed package at publish time by the prepack script.
• packsDir given — the wrapper prepends the bundled directory rather than replacing it: the effective load order becomes [bundled, ...yourDirs]. All listed directories 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) — so a caller's pack always wins a collision against a shipped one.
• packsDir: null — the one case the wrapper leaves untouched: disables all DSL pack loading, bundled packs included.
• git omitted — defaults to git: {}, so the engine applies its own recentDays: 30 default. git: null disables git collection entirely. If root is not a git repository, the engine degrades gracefully and reports it in warnings.

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, and disabledRules only. 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.

Two reference Mode-B adapters ship in the repo as worked examples: an OpenAPI-SDK adapter (resolves generated-SDK cross-layer consumption) and a Svelte/SvelteKit adapter (fills .svelte import fan-in and exempts route entrypoints via each file's is_entry marker).

Analyzing multiple repositories together

analyzeTrees({ trees: [...] }) 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.

const result = JSON.parse(zzop.analyzeTrees(JSON.stringify({
  trees: [
    { root: '../frontend', sourceId: 'web' },
    { root: '../backend', sourceId: 'api' },
  ],
})));

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. crossLayerFindings is the output of the 20 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.

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

Two layers. api.rs never panics by contract — every fallible path (malformed JSON, a missing root, an invalid envelope) returns a Result<String, String>. addon.rs wraps each fallible call in a second, outer safety net:

fn catch<F: FnOnce() -> Result<String, String> + UnwindSafe>(f: F) -> napi::Result<String> {
    match std::panic::catch_unwind(f) {
        Ok(Ok(json)) => Ok(json),
        Ok(Err(message)) => Err(Error::from_reason(message)),
        Err(_) => Err(Error::from_reason("zzop-napi: internal panic (this is a bug — please report it)")),
    }
}

This exists because unwinding across a #[napi]-exported boundary is undefined behavior and must never happen — the engine already isolates a single file's parse/rule failure internally, well before this outer net is ever needed. In practice a JS caller sees either a resolved value or a rejected/thrown Error, never a process crash. version has no Result and no catch wrapper — it cannot fail.