weavatrix-js

Weavatrix JS

Weavatrix エコシステムの一部です。このリポジトリでは、明示的な JavaScript エンジンの系統を維持しています。

これは Weavatrix の JavaScript エンジンであり、weavatrix-js として継続されています。 weavatrix npm パッケージには、 1.0.0 以降、 weavatrix-rust のネイティブ Rust エンジンが含まれます。JavaScript 実装（LSP 支援による TypeScript の処理経路を含む）を使い続けるには、[email protected] にバージョンを固定するか、weavatrix-js をインストールしてください。

AI コーディングエージェント向けのローカルリポジトリインテリジェンス — アプリケーションをすばやく理解し、根拠に基づいて変更できます。

Weavatrix は、あらゆるローカルリポジトリの再利用可能なライブグラフ（ファイル、シンボル、インポート、呼び出し、継承、Health の指摘事項、クローンのファミリー、Git 履歴上の関連性など）を構築し、Claude Code、Codex、その他の MCP クライアントに、すばやく理解するための範囲を限定したマップを提供して、繰り返し必要になるコンテキストを減らします。同じグラフを使って、変更の影響、Health、デッドコードのレビュー、重複、履歴、意図されたアーキテクチャに関する質問にも回答します。ネットワーク接続不要のツールが 34 個。リポジトリのデータがマシンの外に出ることはありません。

• ウェブサイト：weavatrix.com
• ソース：github.com/Weavatrix/weavatrix-js
• npm：weavatrix-js — npx -y weavatrix-js <repoRoot>

主要なネイティブ Rust エンジン

weavatrix-rust は、純粋な Rust で実装された読み取り専用の MCP およびライブラリです。デフォルトのビルドでは 39 個のツールを公開し、この JavaScript 系統の読み取り専用機能 34 個に加え、独立した MIT ライセンスのクレートを通じて、リポジトリ横断の Git、ベクトル検索、セマンティック／SEO リンク、時間的メモリーのコンテキストに対応しています。

cargo install weavatrix-rust
weavatrix mcp <repoRoot> --profile=code

Rust エンジンは、git、rg、Node.js、Python、言語サーバー、または解析対象のリポジトリ内のコードを実行しません。重複する MCP サーバーを起動せずに、範囲を限定した 1 つのビューを公開するには、--profile=all、code、または seo を使用してください。同じリビジョンでのベンチマークと制限事項は、ベンチマークレポートで公開されています。

このパッケージは、MIT ライセンスの完全なオフラインエンジンです。コードを読み取って解析しますが、外部への HTTP 通信は行わず、ソースを編集することもありません。これはレイヤー構成のスタックの読み取り専用基盤です。ハッシュ検証済みの可逆的な編集を適用するには weavatrix-refactor（Apache-2.0）を、許可された Cloud またはセルフホスト可能な同期を利用するには weavatrix-online を追加してください。いずれもこのコアに依存するオプションの上位機能であり、サポート対象の拡張 API を通じて連携します。オフライン／オンラインの分離については、docs/adr/0001-v0.3-offline-online-split.mdに記載されています。

インストール

Node ≥ 18 が必要です。

# Claude Code
claude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot>

# Codex CLI
codex mcp add weavatrix-js -- npx -y weavatrix-js <repoRoot>

# or in ~/.codex/config.toml
[mcp_servers.weavatrix-js]
command = "npx"
args = ["-y", "weavatrix-js", "C:/path/to/repo"]
startup_timeout_sec = 20
tool_timeout_sec = 60

または、クローンから実行します：

git clone https://github.com/Weavatrix/weavatrix-js
cd weavatrix-js && npm install
claude mcp add -s user weavatrix-js -- node <path-to>/weavatrix-js/bin/weavatrix-mcp.mjs <repoRoot>

<repoRoot> は、最初に対象とするリポジトリです。グラフは派生データであり、リポジトリ内に保存されることはありません。ユーザーごとのレジストリ ~/.weavatrix/graphs/<repository-storage-key>/graph.json に保存されます（その隣に安定した .repository-id も保存されます）。まだグラフがない場合は、エージェントに rebuild_graph を呼び出すよう依頼するか、ツールを使うだけで構いません。グラフと Health の読み取りでは、回答前に作業グラフが自動的に再調整されます。

手順を記載したエージェントスキルが skill/SKILL.md にあります。~/.claude/skills/weavatrix-js/SKILL.md（Claude Code）または ~/.codex/skills/weavatrix-js/SKILL.md（Codex）にインストールしてください。

設定

ローカル機能プロファイル — 最後の位置引数としてプロファイルを渡します（省略した場合は offline）。

プロファイル	ローカルリポジトリの切り替え	リポジトリ間のグラフ読み取り	ネットワークリクエスト	ツール
offline（デフォルト）	はい、open_repo 経由のみ	はい、trace_api_contract 経由のみ	なし	34
pinned	いいえ	いいえ	なし	31

# hard-pin one repository and expose no cross-repo tools:
claude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot> pinned

高度な登録では、カンマ区切りの機能セットを正確に指定することもできます。 graph,search,source,health,build,retarget,crossrepo。カスタムリストで trace_api_contract を公開するには、crossrepo を含める必要があります。従来の online／osv／hosted／full という名前を指定すると、明確なエラーが表示され、weavatrix-online が案内されます。

セマンティック精度 — 制限付きの読み取り専用 TypeScript／JavaScript 言語サーバーオーバーレイは、新しいグラフではデフォルトで有効になり、確認済みの参照を EXACT_LSP に昇格させます。パーサーのみで動作させるには、WEAVATRIX_PRECISION=off（環境変数）、rebuild_graph／open_repo の precision:"off"、または MCPB インストーラーの精度選択で無効にします。Java と Rust にはバンドルされた言語サーバーがないため、それらのエッジはパーサー由来のままです。

起動時の事前ウォームアップでは、デフォルトでランク付けされたシンボルを 32 個（最大でも 64 個）クエリします。意図的に高い予算で実行するには、WEAVATRIX_PRECISION_MAX_SYMBOLS を 64 より大きく設定するか、WEAVATRIX_PRECISION_PREWARM=full を設定して、最大 10,000 シンボルの上限まで対象となるすべてのターゲットを網羅します。WEAVATRIX_PRECISION_MAX_REFERENCES、WEAVATRIX_PRECISION_MAX_LINKS、WEAVATRIX_PRECISION_TIMEOUT_MS で予算を調整できます。厳格な上限を超えるリポジトリは、正確に PARTIAL のままになります。

リポジトリ設定ファイル（すべて任意、リポジトリルートに配置）：

• .weavatrixignore — Git で追跡したままにする分析専用の除外設定（*、**、?、ルート基準の /patterns、ディレクトリ接尾辞、順序付きの ! による再包含）。
• .weavatrix.json — リポジトリ間の HTTP クライアント／ラッパーコントラクト（httpContracts）と classify.product のオーバーライド。
• .weavatrix-deps.json — 安全に推論できない規約に対する entrypoints、nonRuntimeRoots、Python の managedDependencies／ignoreDependencies。

テストの実行 — verified_change はデフォルトで読み取り専用です。既存のパッケージテスト／チェック／検証スクリプトを実行するには、run_tests:true と WEAVATRIX_ALLOW_TEST_RUNS=1 の両方が必要です。任意のコマンドは常に拒否されます。

アップグレード後は、ツール一覧を確認する前に MCP サーバーへ再接続するか、新しいエージェントタスクを開始してください。多くのクライアントは、接続中は tools/list の内容をキャッシュします。graph_stats は実行中のバージョン、有効な機能、登録済みツール数を報告するため、キャッシュされたプロセスとインストール済みパッケージを区別できます。

ツール

34 個のメソッドが、同じ再利用可能なグラフをタスクに必要な最小限のビューとして投影します。

• グラフ — graph_stats、get_node、get_neighbors、query_graph、god_nodes、shortest_path、 get_community、list_communities、module_map、get_dependents、change_impact、 verified_change、git_history、graph_diff、get_architecture_contract、prepare_change。 ランタイム、TypeScript の型のみ、言語のコンパイルのみのエッジは個別に報告されます。各エッジにはバージョン管理された出所情報が付与され（EXTRACTED／RESOLVED／INFERRED。同梱の TS/JS オーバーレイによってのみ EXACT_LSP に昇格し、根拠が食い違う場合は CONFLICT）、その内容を確認できます。
• 検索／ソース — search_code（ripgrep を使用し、純粋な Node のフォールバックとリポジトリ相対パスの glob に対応）、read_source、context_bundle、inspect_symbol、 list_endpoints（Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum & actix-web/Spring）、 trace_endpoint。
• 健全性 — find_dead_code、run_audit（機能マトリックス＋未使用ファイル／エクスポート／依存関係、依存関係の欠落／重複、タイポスクワッティング、ロックファイルの不整合を確認。レビュー対象に絞った結果を得るには base_ref と debt: new|existing|all を指定）、find_duplicates（MOSS ウィノウィング方式で、名前を変更したクローンも検出）、coverage_map、hot_path_review、verify_architecture、 explain_architecture_violation、propose_architecture_exception。
• ビルド — rebuild_graph（構造上の差分を報告し、以前の状態を graph.prev.json として保持）。
• リターゲット（offline にあり、pinned にはありません）— open_repo、list_known_repos。
• リポジトリ間（offline にあり、pinned にはありません）— trace_api_contract（登録済みのローカルグラフ間でルートとクライアントの呼び出し箇所を結合。ソースは読み取りません）。結果はデフォルトで簡潔にまとめられ、ページ分割されます（page_size、不透明な cursor、上限付きの per_item_limit サンプルを使用）。response_detail="full" は明示的なオプトインで、引き続きページ分割されます。

検出結果はすべてレビューの根拠であり、自動削除の判定ではありません。find_dead_code／run_audit category=unused は常に REVIEW_REQUIRED を返し、autoDelete:false となります。リリースの可否を判断するのは、引き続き型チェック、テスト、ランタイムチェックです。

常に最新のグラフ

ウォッチャーデーモンの実行も、手動での更新も不要です。グラフ／健全性に関するすべての呼び出しは、回答前にグラフの整合性を確認します。Git トークンの最新状態プローブ（HEAD ＋変更済み／未追跡の内容。デバウンスは 2 秒）によって変更の有無を判定し、変更があった場合は、変更されたファイルとその逆方向のインポーターのみを再解析する、範囲を限定した増分更新を行います（変更ファイルは ≤ 24 個、再解析する JS/TS ファイルは ≤ 80 個）。範囲を限定した結果はファイルロックのもとで以前のグラフにマージされます。設定／ロックファイルの編集、エクスポート対象の変更、バレルファイル、JS/TS 以外の言語の場合は全体を再構築します。速度より常に正確性を優先します。 Git 作業ツリーの外部では読み取れるプローブがないため、最新状態であることを証明できません。そのため、作業量を制限するのはデバウンスウィンドウのみとなり、呼び出しごとではなく、ウィンドウごとに 1 回再構築します。 更新後の各回答には、構造化された refresh レコード（none／incremental／full、変更ファイル数）が付属するため、エージェントはどのリポジトリ状態に基づいて推論しているかを正確に確認できます。同じ保証は、1 つの正規グラフを共有する複数の同時 MCP クライアントにも適用されます。

ベンチマーク

リポジトリには2つのゲートがあります。

• npm run benchmark — TypeScript、JavaScript、Python、Go、Java、Rustを対象とする再現可能なゴールデンスイートに加え、リポジトリ横断のHTTPマッチング、フレームワークの規約、MCPグラフのライフサイクルを検証します。
• npm run benchmark:real — リビジョンを固定したローカルスナップショットを、チェックイン済みの0.2.1関係ベースラインと比較します。説明できないシグナルの損失があると失敗します（MISSING／STALE／UNBASELINEDは不完全なままで、成功扱いにはなりません）。

ローカルでの代表的な回帰テスト結果（Windows x64、Node 24.15.0）：

ゲート	結果	主な検証結果
6言語のフィクスチャ	6/6 PASS	シンボル／エッジが正確で、エッジの出所情報が完全
リポジトリ横断フィクスチャ	PASS、コールド時約432 ms	エンドポイントの一致、型付きラッパー、外部での使用
ライフサイクル	PASS	full → incremental → none → reconnect/none
フィクスチャのコールドビルド合計	約1.31 s	6言語すべてのグラフ
実リポジトリのベースライン	6/6 PASS	TS、JS、Python、Go、Java、Rustのスナップショット

実リポジトリのスナップショットは、473ノード／1,165エッジを0.22秒で処理したGoから、8,192ノード／21,814エッジを9.44秒で処理したTypeScriptまで幅がありました。これらは1台のマシンでの回帰測定値であり、競合製品とのベンチマークではありません。benchmark/cases.mjsとdocs/benchmarking.mdを参照してください。

セキュリティモデル

ソケットの機能に関するアラートは、ローカルのコード解析ツールに想定される権限を示すもので、脆弱性の検出結果ではありません。それぞれの発生源と制限方法は次のとおりです。

機能に関するアラート	存在する理由	有効化条件と境界
ネットワークアクセス	MITライセンスのコアにはありません	offline／pinnedではローカルツールのみを公開します。オンライン連携は別パッケージです
シェルアクセス	ローカルのgit（古さ／影響の確認）、rg（検索）、JS／TSのセマンティクス用に同梱されているtsserver、Windowsの子プロセスツリーの終了、任意のverified_changeテストスクリプト	セマンティックプロバイダーはリポジトリのコードを実行しません。テストの実行にはrun_tests:true + WEAVATRIX_ALLOW_TEST_RUNS=1が必要で、任意のコマンドは拒否します
デバッグ／動的読み込み	キャッシュバスター付きのimport()で監視対象のMCPツールモジュールをホットリロードします。createRequireでパッケージメタデータとパーサー依存関係を読み込みます	インストール済みパッケージ内のファイルのみを読み込みます。evalは使用しません
環境へのアクセス	ローカルのWEAVATRIX_*設定を読み取ります。子プロセスには認証情報を取り除いた環境を引き継ぎます	コネクターのシークレットは削除されます。tsserverに渡すのは、許可リストにあるOS／一時ファイル／ロケールの値のみです
ファイルシステムへのアクセス	アクティブなリポジトリ、グラフ、ロックファイル、カバレッジを読み取ります。派生グラフとキャッシュを書き込みます	実パスによる包含チェックで、パストラバーサルとシンボリックリンクによる境界回避をブロックします。pinnedではopen_repoを無効にします

read_sourceが受け付けるのはリポジトリ相対の通常ファイルのみです。読み取りサイズの上限は2 MBで、字句上または実パス上の境界を越えるアクセスは拒否します。脆弱性の疑いは、SECURITY.mdの説明に従って非公開で報告してください。

依存関係の脆弱性マッチング、アドバイザリーの更新、インストール済みパッケージのマルウェアレビューは、このパッケージには含まれません。これらのネットワークを使用するセキュリティレビューワークフローはweavatrix-onlineにあり、そのためローカルのJSエンジンは、確証のないセキュリティ判定を提示しません。

言語

JavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · Solidity · HTML · CSS —
web-tree-sitter の WASM 文法で解析します。Python のインストールもネイティブコンパイルも不要です。

SQL は文法なしでインデックス化されます。.sql ファイル内のテーブル、ビュー、列、関数、インデックス、トリガーは、グラフ内の第一級シンボルとして登録されます。また、ほかの言語の文字列リテラル内にある SQL は、それを含む関数とクエリ対象のテーブルを結び付けます。これにより、change_impact／get_dependents からスキーマオブジェクトを確認できるようになり（このテーブルにアクセスしているのはどのコードか？）、デッドコードチェックでは、どのステートメントからも参照されない列にフラグが付けられます。判定は保守的に行われ、リポジトリ内のリテラル SQL の証拠がある場合に限られます。また、SELECT * で使用されるテーブルの列は名前で判定されません（ORM が生成する SQL は可視化されないため、こちらも判定されません）。

テスト対象はファイルごと（パスの慣例と .weavatrix.json のオーバーライドによる）、Rust ではシンボルごとにも分類されます。プロダクション用 .rs ファイル内の #[cfg(test)] モジュールと #[test]／#[bench] 項目にはノードレベルの test_surface フラグが付くため、デッドコード、クエリ、ホットパス、ハブの各ツールは、それらをプロダクションコードではなくテストとして扱います。

開発

npm install
npm test                 # unit/integration tests plus the quick golden benchmark
npm run benchmark        # full TS/JS/Python/Go/Java/Rust + MCP lifecycle gate
npm run benchmark:real   # locally available real repos vs source-free 0.2.1 baselines

src、bin、scripts、test 内の保守対象である JavaScript／TypeScript の物理的な行数は、リリーススイートによって 300 行以下に制限されています。これを超える処理は、担当範囲に特化したモジュールに分割し、薄いファサードを介して公開します。weavatrix.com のランディングサイトは、独立したリポジトリ（weavatrix-site）にあります。

リリース履歴

バージョンごとのパッチノートは docs/releases/ にあります。最新の項目からご覧ください。リリースプロセスとゲートについては、scripts/verify-release.mjs をご覧ください。

ライセンス

このリポジトリ内の Weavatrix のソースコードは、MIT ライセンス のもとで公開されています。© 2026 Sergii Ziborov。 サードパーティの依存関係には、それぞれのライセンスが適用されます。同じ告知については、公開されている ライセンスページ をご覧ください。