Brownfield Cartographer

What breaks if I change this? Cartographer finds the dependencies your language server can't see: a table written by a Python job, transformed in SQL, consumed by a dbt model. It maps them statically and locally, with file and line evidence, for you and your coding agent.

cartographer analyze .
cartographer impact models/staging/stg_orders.sql   # what is downstream of this file?
cartographer lineage customers --direction upstream # where does this table come from?
cartographer lineage customers::first_order          # which source columns feed this column?

Language servers and grep answer questions about code symbols. Cartographer answers questions that cross language boundaries through names in strings and configuration, starting with data lineage across Python, SQL and dbt. Every result carries source evidence and coverage, and unsupported cases are reported rather than guessed. It runs offline, needs no API key, and never executes repository code.

One query engine serves the CLI, a Python API, and a read-only MCP server for Claude Code, Codex and Cursor. The support table below lists current capabilities and known gaps.

Try it in 60 seconds

With uv installed, run it on dbt's public example project. Nothing is installed permanently, and analysis took 3 seconds here:

git clone --depth 1 https://github.com/dbt-labs/jaffle_shop && cd jaffle_shop
uvx --from brownfield-cartographer cartographer analyze .
uvx --from brownfield-cartographer cartographer impact models/staging/stg_payments.sql

analyze_impact | complete | snapshot eefa28cd4e13
┌───────────────┬──────────────┬──────────────────────────────────────┐
│ Symbol / node │ Relationship │ Evidence                             │
├───────────────┼──────────────┼──────────────────────────────────────┤
│ stg_payments  │ PRODUCES     │ models/staging/stg_payments.sql:1-26 │
│ orders        │ PRODUCES     │ models/orders.sql:1-57               │
│ customers     │ PRODUCES     │ models/customers.sql:1-70            │
└───────────────┴──────────────┴──────────────────────────────────────┘

Column lineage follows renames through each model:

uvx --from brownfield-cartographer cartographer lineage customers::number_of_orders

trace_data_lineage | complete | snapshot eefa28cd4e13
┌──────────────────────┬──────────────┬────────────────────────────────────┐
│ Symbol / node        │ Relationship │ Evidence                           │
├──────────────────────┼──────────────┼────────────────────────────────────┤
│ stg_orders::order_id │ DERIVES      │ models/customers.sql:1-70          │
│ raw_orders::id       │ DERIVES      │ models/staging/stg_orders.sql:1-24 │
└──────────────────────┴──────────────┴────────────────────────────────────┘

In Claude Code, the plugin lets you ask the same questions in plain language.

Related MCP server: project-surface

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
# or: pipx install brownfield-cartographer
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: pin the SQL dialect instead of choosing the best fit per file.
cartographer analyze /path/to/repository --dialect bigquery

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

# Optional: table columns from `dbt docs generate` for more column lineage.
cartographer analyze /path/to/dbt-project --dbt-catalog target/catalog.json

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 uploads source and never calls a model.

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.

Explore interactively with cartographer query /path/to/repository. It accepts find, impact, deps, dependents, lineage, lineage-down, context, overview, help and quit, using the same engine as the commands below.

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.

Review pull requests

cartographer diff reports what a branch changes and what that can affect, for a PR comment or a quick check before pushing:

cartographer diff --base main          # Markdown
cartographer diff --base main --json   # for scripts

Changed lines since the merge base with --base (committed, uncommitted and untracked) are mapped to functions, modules, SQL statements, dbt models, schema YAML and Airflow tasks, and their downstream dependents are listed with evidence. The merge base is analyzed too, so removed code counts: deleting a module, function or model reports the importers, callers and models that still use it.

To comment on every pull request, add a workflow:

on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  impact:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0   # the merge base must be available
      - uses: Sanoy24/the-brownfield-cartographer@v0.10.0

The action keeps one comment up to date and also writes the report to the job summary, which still works for pull requests from forks.

Connect your AI assistant

Claude Code plugin (needs uv; nothing else to install or configure):

/plugin marketplace add Sanoy24/the-brownfield-cartographer
/plugin install brownfield-cartographer@brownfield-cartographer

The plugin starts the MCP server for the current project and adds a data-impact skill. Ask questions such as "what breaks if I change stg_orders?". If the project has not been analyzed yet, the tools say so and the assistant runs cartographer analyze (offline; repository code is never executed) before answering.

Any MCP host:

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.

find is lexical matching. impact 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 -p brownfield_cartographer.analyzers.embedded_sql -p brownfield_cartographer.analyzers.sql_lineage -p brownfield_cartographer.analyzers.airflow_dag -p brownfield_cartographer.analyzers.dbt_manifest -p brownfield_cartographer.diff -p brownfield_cartographer.analyzers.python_calls -p brownfield_cartographer.analyzers.jinja_lite --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.