archbird 0.0.1

Deterministic architecture maps, verification, and change contracts

Archbird for Python

Archbird maps repositories into deterministic architecture evidence, verifies reviewed constraints, and judges reviewed Map → Verify → Act transitions. The Python package combines the language-neutral C core, lexical/protocol providers, and pinned Tree-sitter syntax packs with CPython-AST precision for Python source. The shared native core also decodes supplied SCIP indexes.

python -m pip install archbird

# Compact Markdown bird view with deterministic discovery by default.
archbird map /path/to/repository --check

# Complete canonical Map IR.
archbird map /path/to/repository \
  --format json --pretty --output ARCHBIRD.json

# Focused live or saved agent context and reviewed architecture checks.
archbird query /path/to/repository --symbol Renderer --depth 1 \
  --max-chars 12000
archbird query --map ARCHBIRD.json --symbol Renderer --depth 1
archbird query --map ARCHBIRD.json \
  --symbol 'py/package/renderer.py:Renderer.render' --depth 0
archbird query --map ARCHBIRD.json --symbol Renderer \
  --context-profile exact
archbird query --map ARCHBIRD.json --symbol Renderer \
  --candidate collapse
archbird query --map ARCHBIRD.json --symbol Renderer \
  --conservative expand --context-quota test_matches=50
archbird freshness /path/to/repository \
  --snapshot ARCHBIRD.json --check --output freshness.json
archbird verify --config architecture.verify.json --check

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

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

archbird serve binds only to loopback, uses the same configuration discovery as Map, opens the packaged UI before initial analysis completes, and runs each candidate rebuild in an isolated Python process. The UI exposes candidate state, keeps serving the last good content-addressed Map when a candidate fails, skips unchanged polling cycles, and provides bounded snapshots, diff, query, and generation-bound source views. The wheel contains the static application; no Node or frontend build is needed.

Library use:

from archbird import Project, audit_map_freshness

project = Project.from_repository("/path/to/repository")
architecture = project.map()
overview = project.map_markdown(max_chars=12_000).decode("utf-8")
context = project.query_markdown(
    symbols=["Renderer"],
    depth=1,
    context={
        "profile": "change",
        "quotas": {"test_matches": 24},
    },
    max_chars=8_000,
).decode("utf-8")
component_graph = project.graph_view_json()
symbol_graph = project.graph_view_json(
    view="symbols", query={"symbols": ["src/renderer.py:Renderer.render"]}
)
freshness = audit_map_freshness(saved_map_bytes, project.map_json())

Project.from_repository(..., config="archbird.json") applies the same typed resolution as the CLI. Explicit arguments override the project config, which overrides versioned discovery. A root archbird.json or .archbird.json is auto-detected by the CLI; the library accepts it explicitly. Use Project.from_config() when an exact reviewed config, rather than discovery, is the intended API boundary.

Project.map_json() and Project.query_json() return complete canonical JSON bytes. Markdown is a deterministic disposable projection of that IR. Selectors and traversal depth choose evidence scope. The optional context mapping 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. max_chars is only a final renderer guard. Every report includes a selection manifest with emitted and omitted counts plus continuation arguments. Project.graph_view_json() emits the compact deterministic graph projection for interactive consumers. Component/file views derive from the current Map; the symbol view first creates a focused Query from the supplied selectors. Use archbird map ... --merge-ledger conflicts.json when provider finalization fails to retain the compact, witness-bearing conflict artifact. audit_map_freshness(saved, current) is the shared native comparison used by the freshness command; the caller supplies a newly derived current Map, so the library remains usable with filesystem, virtual-file, and browser hosts.

--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. Imported-module attribute calls become direct only when mapped module bindings establish every intermediate hop and the final symbol; a mapped but unproven chain remains a conservative candidate.

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.

Archbird analyzes source bytes without importing or executing the analyzed project. Python analysis uses one process below 500 Python sources. At 500 or more, --jobs 0 selects up to eight workers; --jobs 1 is serial and a positive value is an exact override. Worker count cannot change canonical output.

Binary wheels contain the shared core, Tree-sitter grammar packs, and dependency-free SCIP decoder. The source distribution contains the same content-hashed C snapshot and can build it with a supported Python C toolchain. Optional host adapters remain isolated:

python -m pip install 'archbird[okf]'
# Optional protobuf reference/differential API; not needed for normal SCIP input.
python -m pip install 'archbird[scip]'

Configure native SCIP input with indexes[] in archbird.json. Legacy indexes that omit per-document position encoding require a reviewed position_encoding_fallback (utf8, utf16, or utf32) before occurrence spans are accepted; Archbird never guesses from the indexer name. Indexes have a separate 512 MiB default read limit, configurable as limits.max_index_bytes or --max-index-bytes, without widening the source file limit. Embedded SCIP document text must byte-match mapped source; mismatched or invalid-range documents are suppressed as stale. Range-valid documents without embedded text remain usable with explicitly unknown freshness.

All project-authored patterns are compiled by bundled PCRE2; Python re does not interpret them. PATTERN_CONTRACT, PATTERN_CONTRACT_VERSION, PATTERN_ENGINE, PATTERN_UNICODE, and PATTERN_OPTIONS expose the pinned contract. Archbird is pre-1 software, so schema and ABI evolution follows semantic versioning without a 1.x compatibility promise.