Brownfield Cartographer

Brownfield Cartographer

これを変更したら、何が壊れますか？ Cartographer は、言語サーバーでは検出できない依存関係を見つけます。たとえば、Python ジョブが書き込み、SQL で変換され、dbt モデルで使用されるテーブルです。ファイルと行の根拠とともに依存関係を静的かつローカルにマッピングし、あなたとコーディングエージェントに提供します。

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?

言語サーバーと grep は、コードシンボルに関する質問に答えます。Cartographer は、文字列や設定に含まれる名前を通じて言語の境界を越える質問に答えます。まずは Python、SQL、dbt をまたぐデータリネージから対応します。すべての結果にはソースの根拠とカバレッジが含まれ、未対応のケースは推測せずに報告されます。オフラインで動作し、API キーは不要で、リポジトリのコードを実行することもありません。

1 つのクエリエンジンが、CLI、Python API、Claude Code、Codex、Cursor 向けの読み取り専用 MCP サーバーで利用されます。以下のサポート表には、現在の機能と既知の未対応項目を記載しています。

60 秒で試す

uv をインストールした状態で、dbt の公開サンプルプロジェクトに対して実行してください。恒久的にインストールされるものはなく、ここでは分析に 3 秒かかりました。

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            │
└───────────────┴──────────────┴──────────────────────────────────────┘

カラムリネージは、各モデルを通じて名前の変更を追跡します。

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 │
└──────────────────────┴──────────────┴────────────────────────────────────┘

Claude Code では、プラグインを使うと、同じ質問を自然な言葉で尋ねられます。

インストールと分析

Python 3.12 以降と Git が必要です。uv または pipx を使って、コマンドラインツールを PyPI からインストールします。

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

ソースチェックアウトから実行するには、リポジトリをクローンし、uv sync --frozen を実行してから、以下の例のようにコマンドの前に uv run を付けてください。

明示的な GitHub URL を入力した場合は、引き続きチェックアウトがダウンロードされます。

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

ローカル分析でソースがアップロードされることはなく、モデルへの呼び出しもありません。

出力とクエリ

ローカルチェックアウトの場合、成果物はデフォルトで <repository>/.cartography/<repository-name>/ に保存されます。--output を明示した場合、ローカルリポジトリでは <output-root>/.cartography/<repository-name>--<path-hash>/ が使用されるため、同じ名前のチェックアウトが互いに上書きされることはありません。ハッシュは解決済みのチェックアウトパスを識別します。チェックアウトを移動すると、別のインデックスが作成されます。JSON 分析結果には artifact_directory が含まれており、クエリコマンドに --index-dir として渡せます。既存のカスタム出力インデックスは変更されず、再分析結果は新しいディレクトリに書き込まれます。GitHub URL を入力した場合は、デフォルトで現在のディレクトリが使われ、フォルダー名には owner--repository が使われます。

成果物	用途
index.json	完全なバージョン管理されたグラフ、ソース位置、メタデータ、カバレッジ
module_graph.json	関数を含む構造グラフビュー
lineage_graph.json	データセット／変換グラフビュー
analysis_summary.json	完全／部分のステータス、診断、ステージの結果
CODEBASE.md	リポジトリの静的コンテキスト
onboarding_brief.md	主要モジュール、データの入口／出口、変更のホットスポット
cartography_trace.jsonl	実行 ID 付きで保持される実行履歴
state.json	最後に成功したスナップショットのコンテンツフィンガープリント

cartographer query /path/to/repository を使って、対話形式で調べられます。以下のコマンドと同じエンジンを使い、find、impact、deps、dependents、lineage、lineage-down、context、overview、help、quit を受け付けます。

または、個別のコマンドを使って、人が読みやすい形式または JSON 形式で出力できます。

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

カスタムの出力先には --index-dir を使用します。Python から呼び出す場合は、brownfield_cartographer.query_api.QueryEngine.open(Path(repo)) と同じクエリメソッドを使用します。応答には、スナップショットの識別情報、カバレッジ、出力上限を示すマーカー、利用可能なソースの根拠が含まれます。対象が曖昧な場合は拒否されます。

プルリクエストをレビューする

cartographer diff は、PR のコメントやプッシュ前の簡単な確認に使えるよう、ブランチで何が変更され、その変更が何に影響する可能性があるかを報告します。

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

--base で指定したマージベース以降の変更行（コミット済み、未コミット、未追跡）は、関数、モジュール、SQL ステートメント、dbt モデル、スキーマ YAML、Airflow タスクに対応付けられ、それらに依存する下流の要素が根拠とともに一覧表示されます。マージベースも分析されるため、削除されたコードも対象になります。モジュール、関数、モデルを削除すると、それを今も使用しているインポーター、呼び出し元、モデルが報告されます。

すべてのプルリクエストにコメントするには、ワークフローを追加します。

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/[email protected]

このアクションはコメントを最新の状態に保ち、ジョブのサマリーにもレポートを書き込みます。フォークからのプルリクエストでも、ジョブのサマリーへの書き込みは引き続き機能します。

AI アシスタントを接続する

Claude Code プラグイン（uv が必要です。それ以外のインストールや設定は不要です）：

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

このプラグインは現在のプロジェクト用に MCP サーバーを起動し、data-impact スキルを追加します。「stg_orders を変更すると何が壊れますか？」といった質問をしてください。プロジェクトがまだ分析されていない場合、ツールはその旨を伝え、アシスタントは回答の前に cartographer analyze を実行します（オフラインで実行され、リポジトリのコードは実行されません）。

任意の MCP ホスト：

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

stdio サーバーは get_architecture、find_symbol、trace_dependencies、analyze_impact、trace_data_lineage、get_code_context を公開します。固定されたリポジトリの範囲内にある、事前に分析済みのインデックスを読み込み、モデルを呼び出すことはありません。Claude Code、Codex、Cursor については、MCP のセットアップを参照してください。

find は字句マッチングを行います。impact は依存している可能性のある要素を報告するもので、すべての利用側が必ず壊れることを保証するものではありません。不完全なスキャンの結果を利用する前に、保存されたカバレッジと診断情報を確認してください。

分析は、完全または変更なしのスナップショットでは終了コード 0、一部カバレッジでは 2、入力エラーまたは実行中の致命的なエラーでは 1 を返します。一部カバレッジの実行では、成功時のチェックポイントは更新されません。変更された作業ツリーでは現在、完全な再構築が行われます。変更のない成功済みスナップショットでは、完全なインデックスを再利用できます。

サポートと安全性

入力	現在のサポート
Python	関数／クラス、サポート対象の絶対／相対インポート、リポジトリ内の関数間の呼び出し（同一モジュール内の名前、インポートした名前とモジュール、self／cls のメソッド。他のオブジェクト上の呼び出しや動的呼び出しは推測しません）；保守的なリテラル I/O 関連付け（pandas、Spark の読み取り／書き込み）。execute／executemany／executescript、.sql()、read_sql に渡される SQL は、text() と DB-API プレースホルダーを含め、リテラルと文字列定数（同一モジュール内、または別のリポジトリモジュールからインポートしたもの）から解析されます。値のみを補間する f 文字列（比較、IN、LIMIT、引用符で囲まれたリテラル）は解決されます。テーブル名や射影を補間する SQL、連結や .format を使う SQL は動的なものとして報告され、推測されません
SQL	SELECT／UNION、CTAS、INSERT、UPDATE、DELETE、MERGE。ステートメントの範囲とテーブル依存関係。テーブルのリネージュを含まない DDL とトランザクションステートメントはスキップされます。COPY などのその他のステートメントは、ファイルの残りを無視せず個別に報告されます。各ファイルは最適な方言（DuckDB、BigQuery、Snowflake、Postgres、MySQL、Spark、T-SQL、Trino）で解析され、証拠には sql:<dialect> として記録されます。--dialect で方言を固定できます
dbt	モデル、シード、スナップショット、ソースを対象とする、マニフェスト v12 の明示的な取り込み。マニフェストがない場合は、基本的な SQL／YAML フォールバックを使用します。リポジトリ内の任意の場所からプロジェクトを検出し、1 つのリポジトリ内に複数のプロジェクトがある場合も対応します
列	SQL ファイル、Python に埋め込まれた SQL、Airflow のインライン SQL、コンパイル済みマニフェストからの dbt モデル（dbt compile の後に --dbt-manifest を指定）、および Jinja が ref／source／config／コメントのみの dbt ソースモデルについて、CREATE ... AS と INSERT ... SELECT（列リストを含む）の列レベルのリネージュに対応します。各エッジは copy または derived です。CTE とサブクエリに対する SELECT * は展開されます。テーブルに対する SELECT *、結合内の修飾されていない列、その他の Jinja を含むモデルは、推測せず未解決として集計されます
Airflow	with DAG、@dag、dag= の DAG 内にあるオペレーターと @task 関数のタスクに対応します。>>／<<、リスト、set_downstream、chain()、TaskFlow のデータ受け渡しから順序を特定し、行の証拠を付与します。タスクは実行対象にリンクします。対象には python_callable、@task 関数、sql= ファイル（template_searchpath を含む）とインライン SQL のリネージュ、python x.py の bash コマンドが含まれます。影響はコードからタスクを経由して下流のタスクへ伝播します。ループ内で作成されたタスクや計算による ID を持つタスクは、推測せず報告されます
JavaScript/TypeScript	.js .mjs .cjs .jsx .ts .mts .cts .tsx：関数、アロー関数、クラスメソッド。ESM、型のみのインポート、相対指定子がリテラルの require() と import() によるインポート、および tsconfig/jsconfig の paths／baseUrl エイリアス（最も近い設定、リポジトリ内の extends）に対応します。パッケージのインポートは外部として扱われます

共有スキャナーは、ネストされた .gitignore と .cartographerignore を尊重し、 ビルド／環境ディレクトリを除外し、シンボリックリンク／ジャンクションを拒否して、 ファイルサイズ、合計バイト数、ファイル数、エントリー数、走査深度に上限を設けます。慣例的な シークレットのファイル名は除外されますが、通常のソースに埋め込まれたシークレットは検出されません。 大きいファイル、バイナリファイル、読み取り不能なファイル、未対応のファイルは、完全に解析されたものとして 扱わずに報告されます。ローカル解析では、リポジトリのソースコードを実行しません。

サポート対象のマニフェストバージョン、データセット識別子、アーティファクトの鮮度、スキャナーの制限については、dbt アーティファクトの取り込みを参照してください。

精度ベンチマークでは、既知のギャップを含む、バージョンを固定した dbt、Python、SQL のコーパスについて、抽出結果を手書きの期待結果と照合して採点します。CI で実行されます。

開発とブランチ運用

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 --follow-imports=skip
uv build
uv run --no-sync python scripts/check_wheel.py

短命の feat/、fix/、docs/、chore/ ブランチを使用し、プルリクエストを安定版の main に送ってください。機能開発の作業を main に直接プッシュしないでください。ワークフローとリリース規約についてはCONTRIBUTING.mdを、リリース履歴についてはCHANGELOG.mdを参照してください。

コミュニティとライセンス

参加にあたっては、行動規範に従ってください。脆弱性は SECURITY.mdに記載されている方法で非公開に報告してください。

Apache License 2.0のライセンスに基づいています。