Archbird for JavaScript

Archbird maps a repository into deterministic architecture evidence, verifies reviewed constraints, and judges reviewed Map → Verify → Act transitions. The npm package is self-contained: it includes the C core sources, a Node-API addon for the platform packaged by the release, and the same core compiled to Wasm as a portable Node/browser fallback.

npm install archbird

# Compact config-free architecture view; JSON is available with --format json.
npx archbird map /path/to/repository --check
npx archbird query /path/to/repository --symbol Renderer --depth 1
npx archbird query --map ARCHBIRD.json \
  --symbol 'src/renderer.ts:Renderer.render' --depth 0
npx archbird query --map ARCHBIRD.json --symbol Renderer \
  --context-profile exact
npx archbird query --map ARCHBIRD.json --symbol Renderer \
  --candidate collapse
npx archbird query --map ARCHBIRD.json --symbol Renderer \
  --conservative expand --context-quota test_matches=50
npx archbird freshness /path/to/repository \
  --snapshot ARCHBIRD.json --check --output freshness.json
npx archbird export json --map ARCHBIRD.json --view components \
  --output architecture.view.json

# Inspect or materialize the effective discovery profile.
npx archbird config show /path/to/repository --pretty
npx archbird config init /path/to/repository \
  --output /path/to/repository/archbird.json

# Reviewed architecture checks and Act artifacts.
npx archbird verify --config architecture.verify.json --check
npx archbird plan --verification before.verify.json --finding FINGERPRINT \
  --output change.proposal.json
npx archbird support --pretty

# Open the packaged offline application and rebuild after local changes.
npx archbird serve /path/to/repository

npx archbird is the Map command. It also exposes query, impact, diff, freshness, workspace, verify, plan, contract, verify-plan, export, serve, and support. Exit status is 0 for success, 1 when an explicitly requested --check blocks, and 2 for invalid input or configuration.

npx archbird serve binds only to loopback, watches mapped source and live configuration paths, opens the packaged UI before initial analysis completes, and computes each candidate Map in a Worker thread. The packaged UI exposes candidate state, filters unchanged mapped-file notifications, keeps the last good content-addressed generation when a candidate fails, and provides bounded snapshots, diff, query, and generation-bound source views. No separate Vite build or browser download is performed at install time.

Library use:

const { Project, auditMapFreshness } = require("archbird");

const project = Project.fromRepository("/path/to/repository");
const architecture = project.map();
const overview = project.mapMarkdown({ maxChars: 12_000 }).toString("utf8");
const context = project.queryMarkdown({
  symbols: ["Renderer"],
  depth: 1,
  context: {
    profile: "change",
    quotas: { test_matches: 24 },
  },
  maxChars: 8_000,
}).toString("utf8");
const componentGraph = project.graphViewJson();
const symbolGraph = project.graphViewJson({
  view: "symbols",
  query: { symbols: ["src/renderer.ts:Renderer.render"] },
});
const freshness = auditMapFreshness(savedMapBytes, project.mapJson());
project.dispose();

Project.fromRepository(root, { config }) uses the same resolver as the CLI. Explicit options override the project config, which overrides versioned discovery. A root archbird.json or .archbird.json is auto-detected by the CLI; the library accepts config bytes or a path explicitly. Project.fromConfig remains the exact reviewed-config API.

Project.mapJson() and Project.queryJson() return complete canonical JSON. Markdown is a deterministic disposable projection of that IR. Selectors and depth choose evidence scope. The optional context object and matching CLI flags select profile, provenance, confidence, maximum seed distance, independent candidate/conservative handling, per-kind quotas, and continuation offsets. The default change profile expands candidate rows and collapses conservative test rows; canonical Query JSON retains both. Collapsed rows are grouped by their evidence axes and include the highest-ranked sample plus an expansion command. maxChars is only a final renderer guard. Every report includes a selection manifest. mapMarkdown({ full: true }) renders all mapped detail. Project.graphViewJson() emits the compact deterministic graph projection used by interactive consumers. Component/file views derive from the current Map; the symbol view first creates a focused Query from the supplied selectors. Use npx archbird map ... --merge-ledger conflicts.json when provider finalization fails to retain the compact, witness-bearing conflict artifact. auditMapFreshness(saved, current) is shared by the native and Wasm engines. It accepts a saved Map/Query plus a newly derived Map, so browser virtual-file hosts can use the same contract without granting the core filesystem access.

--symbol PATTERN searches every mapped file. Use --symbol 'PATH:PATTERN' for one repository-relative file. Repeated symbol selectors form a union; independent --path and --symbol options are not an implicit intersection.

Focused test matches preserve case-local route witnesses and separately expose route provenance, confidence, evidence scope, exact target, seed distance, target role, and lexical ranking affinity. Markdown preserves the canonical Query ordering over those axes. The legacy direct, configuration-asserted, runner-observed, static candidate, transitive/file-level conservative, and unresolved classification remains for compatibility. Only an exact content-addressed project-runner artifact may add observed; a hit proves entry during that bound run, not behavioral correctness or complete coverage. Pass repeatable --test-symbol-observations FILE only with a live Map/Query/Impact; saved maps cannot establish current source freshness. The artifact contract is documented by schema/test-symbol-observations.schema.json in the source repository. Verification suites can bind asserted revisions to exact files with source_lock. A mismatch makes dependent facts stale and prevents Act proposal derivation until evidence is refreshed.

Config-free discovery derives conservative source/package/build and candidate role evidence only. Named components, cross-language bridge topology, routed tests, parity mappings, and verification checks require reviewed configuration. Verification always requires an explicit asserted suite.

Architecture collection selectors are segment-aware: *, ?, and [...] stay within one repository path segment, while ** as a complete segment matches zero or more segments. Thus src/*.c is top-level and src/**/*.c is recursive. Components may overlap intentionally and retain every matching membership.

For npm packages, runtime surfaces follow exports when present and otherwise main; bin, types, and versioned types@... targets remain metadata rather than runtime exports. Static ESM imports/re-exports and bounded file-local CommonJS aliases/property mutations are resolved recursively. Dynamic or conditional mutations, unresolved routes, and conflicting origins remain explicit diagnostics instead of guessed exports.

The default engine policy is ARCHBIRD_ENGINE=auto: load a matching native addon, otherwise use the bundled synchronous Wasm core. Set ARCHBIRD_ENGINE=native to require the addon or ARCHBIRD_ENGINE=wasm to test the portable path. npx archbird support reports the selected engine, exact pattern contract, portable provider IDs, Node host providers, and their per-language precision composition. The package performs no compiler lifecycle step during installation. To build a local native addon explicitly from the bundled content-hashed source snapshot:

npm run build:native
ARCHBIRD_ENGINE=native npx archbird support --pretty

That command requires a working Node-API C toolchain and node-gyp; the Wasm fallback does not. JavaScript/TypeScript use lexical/protocol evidence, portable Tree-sitter syntax, and TypeScript compiler evidence. C/C++, Python, and R use both the portable lexical and Tree-sitter providers. Install the PyPI distribution when a Python-heavy check specifically requires CPython-AST evidence. Supplied SCIP indexes are decoded by the shared native/Wasm core in Node and browsers without a protobuf npm dependency.

Browser use is asynchronous and accepts supplied source bytes instead of reading a filesystem:

const { createBrowserArchbird } = require("archbird/browser");

const archbird = await createBrowserArchbird();
const project = archbird.Project.fromFiles([
  new archbird.Source("src/index.ts", sourceBytes),
]);
const map = project.map();
project.dispose();

For browser SCIP use, include the configured index.scip bytes in Project.fromFiles and declare it under indexes[]. If an old producer omits SCIP's per-document position encoding, review that producer and configure position_encoding_fallback; the core does not infer an encoding from a tool name. limits.max_index_bytes and --max-index-bytes control index input independently from source files. Embedded document text must byte-match supplied source; mismatched or invalid-range documents are suppressed as stale, while range-valid documents without embedded text retain explicitly unknown freshness.

archbird/wasm exposes the lower-level async browser/Worker core loader, archbird/wasm-sync exposes the synchronous Node fallback, and archbird/worker exposes an in-browser map request handler. Archbird never imports or executes analyzed projects. All configured patterns go through the bundled PCRE2 core; the exported pattern constants identify the exact contract. The package is pre-1 software, so schema and ABI evolution follows semantic versioning without a 1.x compatibility promise.