Brownfield Cartographer

A local-first repository analysis engine for evidence-backed code structure, dependency impact, and data lineage. The Python API, deterministic CLI, and read-only local MCP server share one query engine; reasoning belongs to the developer's existing AI assistant.

The CLI includes analyze, overview, find, impact, and lineage. The support table below describes current capabilities and limitations.

Install and analyze

Requires Python 3.12+ and Git. Install the command-line tools from PyPI with uv or pipx:

uv tool install "brownfield-cartographer[mcp]"
# or: pipx install "brownfield-cartographer[mcp]"
cartographer --version

# Local analysis needs no network, API key, or model service.
cartographer analyze /path/to/repository

# Force a fresh rebuild or choose an output root.
cartographer analyze /path/to/repository --full -o ./results

# Optional: use a previously generated dbt v12 manifest.
cartographer analyze /path/to/dbt-project --dbt-manifest target/manifest.json

Omit [mcp] if you only need the CLI. To run from a source checkout instead, clone the repository, run uv sync --frozen, and prefix commands with uv run, as in the examples below.

An explicit GitHub URL input still downloads a checkout:

cartographer analyze https://github.com/owner/repository

Local analysis never implicitly uploads source. Environment API keys do not enable models in the CLI. Legacy model-dependent capabilities remain available as optional Python code through uv sync --extra llm; they are outside the deterministic default workflow.

Outputs and queries

For a local checkout, artifacts default to <repository>/.cartography/<repository-name>/. With an explicit --output, local repositories use <output-root>/.cartography/<repository-name>--<path-hash>/ so same-named checkouts do not overwrite one another. The hash identifies the resolved checkout path; moving a checkout creates a separate index. The JSON analysis result includes artifact_directory, which can be passed to query commands as --index-dir. Existing custom-output indexes are left untouched; reanalyzing writes to the new directory. GitHub URL inputs use the current directory by default and an owner--repository folder name.

Start the existing deterministic interactive query interface:

uv run cartographer query /path/to/repository

Or use individual commands with human-readable or JSON output:

uv run --no-sync cartographer overview /path/to/repository --json
uv run --no-sync cartographer find run --repo /path/to/repository --json
uv run --no-sync cartographer impact producer.py --repo /path/to/repository
uv run --no-sync cartographer lineage output --repo /path/to/repository --direction upstream --json

Use --index-dir for a custom output location. Python callers use brownfield_cartographer.query_api.QueryEngine.open(Path(repo)) and the same query methods. Responses carry snapshot identity, coverage, capped-output markers, and available source evidence. Ambiguous targets are rejected.

Connect your AI assistant

cartographer analyze /absolute/path/to/repository
cartographer-mcp --repo /absolute/path/to/repository

The stdio server exposes get_architecture, find_symbol, trace_dependencies, analyze_impact, trace_data_lineage, and get_code_context. It reads a previously analyzed index inside a fixed repository scope and never calls a model. See MCP setup for Claude Code, Codex, and Cursor.

Commands: find <text>, lineage <dataset>, lineage-down <dataset>, blast <module-or-dataset>, explain <module>, summary, and quit. find is lexical matching. blast reports potential dependents, not a guarantee that every consumer will break. Read the persisted coverage and diagnostics before relying on results from an incomplete scan.

Analysis returns exit code 0 for complete/unchanged snapshots, 2 for partial coverage, and 1 for an input or fatal run error. A partial run does not advance the successful checkpoint. Changed working trees currently use full rebuilds; unchanged successful snapshots can reuse the complete index.

Support and safety

The shared scanner respects nested .gitignore and .cartographerignore, prunes build/environment directories, rejects symlinks/junctions, and caps file size, total bytes, file count, entry count and traversal depth. Conventional secret filenames are excluded; secrets embedded in normal source are not detected. Large, binary, unreadable or unsupported files are reported rather than treated as fully analyzed. No repository source code is executed by local analysis.

See dbt artifact ingestion for supported manifest versions, dataset identifiers, artifact freshness, and scanner limits.

The accuracy benchmark scores extraction against hand-written expected results for pinned dbt, Python and SQL corpora, including known gaps. It runs in CI.

Development and branching

uv sync --frozen
uv run --no-sync pytest -q
uv run --no-sync ruff check src tests scripts
uv run --no-sync mypy -p brownfield_cartographer.scanner -p brownfield_cartographer.persistence -p brownfield_cartographer.query_api -p brownfield_cartographer.analyzers.javascript_analyzer --follow-imports=skip
uv build
uv run --no-sync python scripts/check_wheel.py

Use short-lived feat/, fix/, docs/, and chore/ branches and pull requests into stable main. Do not push feature work directly to main. See CONTRIBUTING.md for the workflow and release conventions, and CHANGELOG.md for release history.

Community and license

Participation is governed by the Code of Conduct. Report vulnerabilities privately as described in SECURITY.md.

Licensed under the Apache License 2.0.