Metadata-Version: 2.4
Name: archbird
Version: 0.0.1
Summary: Deterministic architecture maps, verification, and change contracts
Author: Anton Zemlyansky
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/zemlyansky/archbird
Project-URL: Repository, https://github.com/zemlyansky/archbird
Project-URL: Issues, https://github.com/zemlyansky/archbird/issues
Keywords: archbird,static-analysis,agents,architecture,repository
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: scip
Requires-Dist: protobuf<7,>=5.27; extra == "scip"
Provides-Extra: okf
Requires-Dist: PyYAML>=6.0; extra == "okf"
Requires-Dist: markdown-it-py<5,>=3; extra == "okf"
Dynamic: license-file

# 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.

```bash
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:

```python
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:

```bash
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.
