weavatrix-refactor-js

Weavatrix Refactor JS

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

これは Weavatrix の JavaScript リファクタリングエンジンであり、 weavatrix-refactor-js として開発を継続しています。 weavatrix-refactor パッケージには、weavatrix-rust と weavatrix-edit / weavatrix-refactor-plan / weavatrix-worktree クレートを基盤とする ネイティブ Rust MCP ホストが含まれています。 このパッケージは、従来のバージョン系列を引き継ぎます。旧名称での最後の JavaScript リリースは [email protected] であり、[email protected] からその続きが始まります。JavaScript 実装を使い続けるには、 weavatrix-refactor-js をインストールするか、 [email protected] に固定してください。

コーディングエージェント向けの、根拠に基づくトランザクション型リファクタリングです。

weavatrix-refactor-js は、JavaScript ファミリーの中で書き込み機能を備えたパッケージです。 読み取り専用の weavatrix-js コードインテリジェンス MCP の全機能に、変更の妥当性を証明し、 現在の作業ツリーに対してプレビューし、アトミックに適用して、グラフを更新し、ロールバックできる 11 個のリファクタリングツールを組み合わせています。

エンジンの境界： このパッケージは weavatrix-js エンジンをホストします。 ネイティブの weavatrix-rust エンジンは使用しません。また、両方のパッケージをインストールしても、 このパッケージの解析レイヤーが暗黙にアップグレードされることはありません。このパッケージの状態は ~/.weavatrix-refactor-js に保存され、Rust ホストの状態とは分離されています。そのため、ロック、 トークンストア、ロールバックジャーナルが共有されることはありません。

単なる名称変更のラッパーをはるかに超える機能を備えています。

• バンドルされた言語サーバーを介した、意味に基づく JS/TS の名前変更
• スキーマを考慮した根拠に基づく、SQL テーブルおよびフィールドの名前変更
• Python、Rust、Go、Java、C#、Solidity に対応した、グラフと字句解析を組み合わせた厳密な名前変更
• 関連する複数の JS/TS の名前変更を、1 つのアトミックなトランザクションに統合
• シグネチャ、シンボル本体、インポート、一括置換、移動、安全な削除の各ワークフロー
• 適用可能なすべてのプランに含まれる、バイト単位で正確なファイルハッシュ、before テキスト、来歴、不確実性、グラフのリビジョン
• 古い作業ツリーの検出、リポジトリロック、ロールバックバンドル、書き込み途中の失敗後の自動ロールバック
• 構造的な移動の前に行うアーキテクチャと循環依存の投影
• コアから継承した、変更後の影響範囲分析と検証ツール

なぜ別のパッケージなのか

MIT ライセンスの weavatrix-js コアは、物理的に読み取り専用です。公開されている成果物には、 リポジトリのソースを書き換える経路がありません。このパッケージが、明示的な書き込み境界となります。 このパッケージをインストールし、refactor プロファイルを選択すると、edit 機能が利用可能になります。このパッケージがなければ、サーバーはソースを変更できません。

この分離は、安全性を確保するためのものであり、パッケージング上の見た目の問題ではありません。

weavatrix-js core       weavatrix-refactor-js                 repository
read-only evidence  ->  plan + preview + confirmation  ->  atomic write
graph / LSP / audit     hashes / provenance / rollback     refreshed graph

アーキテクチャ

実装は、一方向の境界を持つポートとアダプターのシステムです。

edit-plan model  <-  filesystem / lock / token adapters
       ^                         ^
       |                         |
plan engines     ->  preview / apply / rollback workflows  ->  MCP adapter

• モデルは、固定された weavatrix.edit-plan.v1 エンベロープを検証し、バイト単位で正確な編集を純粋な文字列変換として適用します。
• プラットフォームアダプターは、実パスの包含確認、アトミックな置換、リポジトリロック、使い捨てトークン、永続的なロールバックバンドルを管理します。
• プランエンジンは、書き込みワークフローを管理することなく、名前変更、シグネチャ、シンボル、インポート、移動、削除、一括置換の根拠を算出します。
• アプリケーションワークフローは、プレビューを現在のリポジトリに紐付け、確認トークンを発行して消費し、ロック下で適用し、失敗時に復元します。
• MCP アダプターは、11 個のリファクタリングツールを読み取り専用の weavatrix-js カタログと組み合わせ、1 つの stdio サーバーを公開します。

チェックイン済みの厳格なアーキテクチャ契約により、実行時の循環依存はゼロ、ファイルの長さは 300 行以下、関数の長さは 100 行以下に保たれます。例外も、段階的に制限を強化するためのベースラインもありません。

リファクタリングワークフローの特徴

一般的なエディターの名前変更が答えるのは、「今、どのテキストを編集すればよいか」です。 Weavatrix Refactor は、さらに次の問いにも答えます。

質問	返される根拠
これは正確にそのシンボルですか？	安定したグラフシンボル ID と、パーサー／LSP の選択範囲
どの参照が証明されていますか？	編集ごとの来歴：EXACT_LSP、RESOLVED、EXTRACTED、LEXICAL_EXACT
何が証明されていませんか？	明示的な uncertainReferences、notModified、警告、および PARTIAL の完全性
どのファイルが調査対象になりましたか？	名前変更セッションでは、グラフで宣言されたすべての参照と、識別子を含むテキストを持つすべてのインデックス済みファイルを調査対象にします。開けなかったファイルはすべて名前が示され、完全性は PARTIAL になります
プレビュー後にツリーは変更されましたか？	ファイルの sha256 と、書き込みロック下で再確認される正確な before テキスト
複数の名前変更が部分的に成功することはありますか？	いいえ。関連する名前変更は競合を確認したうえで、1 つのトランザクションとして適用されます
ディスク／書き込みエラーが発生するとどうなりますか？	すでに書き込まれたファイルは復元され、永続的なロールバックバンドルが残ります
移動によってアーキテクチャが悪化しますか？	投影される実行時の循環依存、境界違反、改善点、影響範囲
リファクタリングによって振る舞いの構造は維持されましたか？	更新されたグラフと、呼び出し元／インポート／参照の保存を示す verified_change

証明が不十分な場合、システムは安全側に倒して処理を停止します。INFERRED エッジを適用可能な編集に格上げすることも、曖昧な参照を隠すこともありません。

名前変更ワークフローの全体像

rename_symbol と rename_related_symbols は、PLANNED のみを行うヘルパーではなく、完全な操作です。各メソッドが両方のフェーズを担当します。

1. プレビュー

通常どおり名前変更メソッドを呼び出します。

{
  "symbol": "src/users.ts#getUser@12",
  "new_name": "getCustomer"
}

このメソッドは名前変更を計算し、すべてのプランファイルを作業ツリーと照合して検証し、短期間有効な confirmToken を伴う PREVIEW_OK を返します。プレビューではソースを書き換えず、環境の書き込みゲートも必要ありません。

2. 同じメソッドを通じて適用

同じ操作入力を再指定し、確認情報を追加します。

{
  "symbol": "src/users.ts#getUser@12",
  "new_name": "getCustomer",
  "mode": "apply",
  "confirm_token": "<token from preview>"
}

このツールは決定論的なプランを再計算し、トークンがそのプランとリポジトリに属することを検証します。次に、リポジトリロックを取得し、ハッシュと before テキストを再確認し、ロールバックバンドルを書き込んで、すべての編集を下から上へ適用します。

調整された編集セットにも同じ契約が適用されます。

{
  "renames": [
    {"symbol": "src/api.ts#getUser@8", "new_name": "getCustomer"},
    {"symbol": "src/api.ts#getOrder@20", "new_name": "getPurchase"}
  ]
}

rename_related_symbols は、トークンを発行する前に、編集の重複、連鎖、入れ替え、シャドーイングのリスク、サブ名前変更ごとの失敗を検出します。適用は、複数ファイルに対する 1 つのアトミックな操作です。

リファクタリングツール

完全な書き込みワークフロー

ツール	実際の動作
rename_symbol	言語をまたいだ名前変更をプレビュー／確認／適用します。正確な JS/TS LSP、SQL スキーマ、または厳密なグラフ＋字句解析のバックエンドに振り分け、バックエンドの実際の網羅性と、参照できなかったすべての箇所を返します。
rename_related_symbols	1つの共有言語サーバーセッションと1つのアトミックな編集計画で、最大50個の JS/TS シンボルの名前変更を調整します。書き込み前に、競合、連鎖、入れ替え、スナップショットの不一致、名前変更サブ処理の失敗を検出します。
apply_edit_plan	他のツールまたは weavatrix-online が生成した weavatrix.edit-plan.v1 エンベロープ向けの汎用2段階実行ツールです。プレビューで計画に紐づくトークンを発行し、適用時にはロールバックに対応したアトミックな書き込みを行います。
rollback_last_apply	直近の適用前の状態を復元します。適用後にファイルが変更されている場合は拒否し、復元が不完全だった場合は再試行を重ねることで完了します。

実証済みの計画生成元

ツール	実際の動作
change_signature	JS/TS の関数またはメソッドのパラメーターを追加または削除します。宣言と呼び出し引数をバイト単位で正確に編集し、スプレッド呼び出しと値を必要とする追加については、不確実性を明示したままにします。
edit_symbol	インデックス化されたパーサー範囲を使って、replace_symbol_body、insert_before_symbol、または insert_after_symbol を実行します。JS/TS の出力はパース検証を通過する必要があり、改行コードと UTF-16 座標は保持されます。
bulk_replace	インデックス化されたファイルを対象に、出現箇所を選択して2段階で置換します。最初の呼び出しでは安定した出現箇所 ID を返し、2回目の呼び出しでは選択した ID または正確な期待件数を受け付け、ハッシュに紐づく計画を生成します。デフォルトはリテラルモードで、正規表現による置換では実際のキャプチャ展開を行います。
organize_imports	使用されていないことが確実な名前付き JS/TS インポートのみを削除します。デフォルトインポートと名前空間インポートは不確実なままにし、副作用インポートには触れません。並べ替えは意図的にフォーマッターに任せます。

これらの計画は、名前変更と同じプレビュー、トークン、アトミック書き込み、ロールバックのプロトコルを使って、apply_edit_plan で適用します。

構造レビューと安全性ツール

ツール	実際の動作
move_file	JS/TS の移動レビューを作成します。インポーターの指定子と移動対象ファイル自身の相対インポートを書き換え、その後、アーキテクチャへの影響を予測します。ファイル名の変更自体は明示的にエディター／エージェントの操作に任せるため、これは意図的に適用用エンベロープではありません。
move_symbol	バイト編集を推測で作成することなく、宣言の移動を予測します。新たに生じる、または解消されるランタイムサイクル、移動先ファイルへの依存関係、アーキテクチャ違反または改善、影響範囲を報告します。
delete_readiness	既知の参照、動的参照／リフレクションのリスク、確信度、宣言の範囲とともに、safe: true、false、または UNPROVEN を返します。エクスポートされたシンボルは UNPROVEN を上限とし、削除が自動化されることはありません。

言語と証明のマトリクス

対象	バックエンド	適用可能な来歴	網羅性の契約
JavaScript / TypeScript の名前変更	同梱の TypeScript 言語サーバー	EXACT_LSP	シンボルに言及し得るすべてのファイルが名前変更セッションで開かれ、証明された場合にのみ COMPLETE となります。候補が1つでも除外されると PARTIAL になります
SQL テーブルの名前変更	SQL ファイルとホストファイルを対象としたスキーマ認識型 SQL スキャナー	EXTRACTED / LEXICAL_EXACT	スキップされた参照または曖昧な参照をすべて報告します
SQL フィールドの名前変更	定義を安全に扱う SQL バックエンド	証明済みの定義編集のみ	使用箇所は推測されず、UNPROVEN のままになります
Python / Rust / Go / Java / C# / Solidity の名前変更	インデックス化されたグラフ参照と、記録された行における正確な字句位置	EXTRACTED / LEXICAL_EXACT	常に PARTIAL となり、曖昧な行は編集されません
JS/TS のシグネチャとインポート	パーサーとグラフによる呼び出し／参照の証拠	EXTRACTED / RESOLVED	グラフ上の到達可能性から不在を証明できない場合は、部分的であることを明示します
シンボルを基準にした編集	インデックス化された各言語のパーサー範囲	EXTRACTED	JS/TS はパース検証を通過する必要があります。他の言語ではパーサー範囲の証拠境界が維持されます

編集計画の証明エンベロープ

適用可能な計画では、weavatrix.edit-plan.v1 を使用します。重要なフィールドは次のとおりです。

• 操作とグラフのリビジョン；
• リポジトリ相対の対象パスのみ；
• 各対象ファイルの sha256；
• 1 始まりの行番号と UTF-16 文字範囲の厳密な指定；
• 正確な before テキストと after テキスト；
• 編集ごとの出所情報；
• uncertainReferences、notModified、警告、完全性。

適用機能では、さらに次の事項から保護します。

• 絶対パス、パストラバーサル、.git の大文字小文字や末尾のドットを利用した細工、NTFS ストリーム、シンボリックリンクやジャンクションによるパスの逸脱；
• 非 UTF-8 のファイルまたはサイズ超過のファイル；
• 重複する編集、古くなった範囲、孤立サロゲート、サロゲートペアを分割する編集；
• 同じリポジトリ内での複数の書き込み処理の交錯；
• トークンの再利用、期限切れ、リポジトリ不一致、計画不一致；
• 部分的な書き込みと不完全なロールバック。

createdAt は出所情報のメタデータであり、確認用フィンガープリントから除外される唯一のフィールドです。これにより、rename メソッドは apply 呼び出し時に同じ計画を再計算できます。実行可能なフィールドはすべて、引き続きトークンに紐付けられます。

エージェントが対応できる結果状態

状態	意味
PREVIEW_OK	すべてのハッシュと before テキストが一致しました。1 回限りのトークンが発行されました。
PREVIEW_BLOCKED	生成された計画が現在のツリーと一致しません。適用できません。
WRITE_GATE_CLOSED	ソース編集を有効にして、サーバーが明示的に起動されていません。
APPLIED	計画されたすべての編集が書き込まれ、ロールバック用バンドルを利用できます。
STALE	プレビュー後、ロック下での適用チェック前に作業ツリーが変更されました。何も書き込まれていません。
TOKEN_UNKNOWN / TOKEN_EXPIRED / TOKEN_*_MISMATCH	確認が存在しない、使用済み、期限切れ、または別の計画／リポジトリに属しています。
REPO_BUSY	別の適用またはロールバックが現在リポジトリのロックを保持しています。
ROLLED_BACK	適用の失敗または明示的なロールバックにより、元のファイルが復元されました。
ROLLBACK_INCOMPLETE	ファイル名が示された一部の復元が阻止されました。永続的なバンドルを使って再試行できます。
INVALID_PLAN	書き込み前のスキーマ、パス、範囲、エンコーディング、重複、または出所情報の検証に失敗しました。
INVALID_ARGS	必須の引数が不足しているか、型が正しくありません。該当する名前が一覧表示されます。計画は作成されていません。

NOT_FOUND、NO_CHANGE、CONFLICT、BLOCKED、UNPROVEN、NOT_SUPPORTED などのプランナー固有の状態は、汎用的な失敗にまとめられず、そのまま表示されます。

3 つの書き込みゲート

リポジトリのソースを変更するには、次の 3 つすべてが必要です。

1. weavatrix-refactor-js がインストールされ、refactor プロファイルで edit が選択されている；
2. サーバーが WEAVATRIX_ALLOW_SOURCE_EDITS=1 を指定して起動されている；
3. apply 呼び出しで、正確な計画とリポジトリに紐付けられた、有効期限内の有効な 1 回限りのトークンが提示されている。

環境ゲートが閉じている場合でも、プレビューとすべての読み取り専用分析は引き続き利用できます。

エンドツーエンドの変更証明

このパッケージには、読み取り専用のコアツールが 34 個すべて、同じ MCP サーバーに含まれています。そのため、強力なリファクタリングセッションを一連の証拠で完結できます。

1. inspect_symbol、context_bundle、または get_dependents で正確な対象を特定します。
2. rename_symbol、change_signature、move_symbol、またはその他のリファクタリングツールで変更をプレビューします。
3. 書き込みワークフローで変更をアトミックに適用します。
4. 次のグラフ呼び出しで、変更されたファイルと逆方向のインポーターが自動更新されます。
5. verified_change で、呼び出し元、インポート、参照をマージベースと比較します。
6. change_impact、verify_architecture、coverage_map、run_audit、find_duplicates で変更の影響を調査します。

引き継がれる便利な機能には、次のものがあります。

• アーキテクチャマップとナビゲーション：module_map、query_graph、shortest_path、context_bundle；
• 影響と証明：change_impact、get_dependents、prepare_change、verified_change；
• 健全性：run_audit、find_dead_code、find_duplicates、coverage_map、hot_path_review；
• コントラクト：list_endpoints、trace_endpoint、trace_api_contract；
• 目標アーキテクチャ：get_architecture_contract、verify_architecture、explain_architecture_violation；
• リポジトリ管理：open_repo、rebuild_graph、graph_diff、list_known_repos。

JavaScript ホストの全カタログについては、weavatrix-js README をご覧ください。

実行

1 つのリポジトリに対して、読み取り専用機能とリファクタリング機能を統合した MCP サーバーを起動します。

npx -y weavatrix-refactor-js <repoRoot>

MCP クライアントでは、最小限の設定は次のとおりです。

{
  "mcpServers": {
    "weavatrix": {
      "command": "npx",
      "args": ["-y", "weavatrix-refactor-js", "/absolute/path/to/repository"]
    }
  }
}

Windows では、クライアントがコマンドシムを解決できない場合、npx.cmd を使用してください。環境変数による上書きがない場合、すべての解析ツールとプレビューツールは動作しますが、ソースへの書き込みはフェイルクローズします。適用とロールバックを意図的に許可するセッションでのみ、"env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"} を追加してください。

すでに weavatrix-js をホストしているアプリケーションでは、同じ拡張機能を組み込めます。

import {startMcpServer} from 'weavatrix-js/mcp-runtime'
import {refactorExtension} from 'weavatrix-refactor-js/extension'

await startMcpServer({
  defaultCapabilities: 'refactor',
  loadExtensions: async () => [refactorExtension()],
})

エクスポートされた拡張機能は、ツールと refactor 機能プロファイルを登録します。書き込みゲートを暗黙的に開くことはありません。

対象範囲と正直な制限

• 関連する複数シンボルの名前変更は、現在 JS/TS のみを対象としています。
• move_file は apply_edit_plan を通じてファイル名を変更できません。ファイル移動には異なるファイルシステムのセマンティクスがあるため、レビュー用のプランとなります。
• move_symbol はトポロジー／アーキテクチャのドライランであり、バイト編集の合成ではありません。
• グラフと字句解析を組み合わせた言語バックエンドでは参照の完全性を証明できないため、既知の参照をすべて特定しても PARTIAL のままです。
• delete_readiness が自動削除を行うことはありません。また、公開 API やエクスポート API に自動的な問題なし判定を与えることはできません。
• テスト、型チェック、ランタイムチェック、人間によるレビューが引き続きリリースの判断基準です。Weavatrix は範囲を限定した証拠を提供しますが、証明を捏造することはありません。

パッケージの境界

パッケージ	ライセンス	担当範囲
weavatrix-js	MIT	JavaScript の読み取り専用グラフ、解析、証拠、アーキテクチャ、検証
weavatrix-refactor-js	MIT	証明済みのリファクタリングプラン、トランザクション書き込み、ロールバック
weavatrix-online	MIT	明示的な公開ネットワークコネクターと、リモートのプラン／証拠ワークフロー

リファクタリングパッケージは、weavatrix-js/extension-api と weavatrix-js/analysis-kit のみを通じて従来の JavaScript コアを拡張します。そのコアをコピーしたり、別のライセンスを適用したりすることはありません。正式な weavatrix パッケージはネイティブの Rust エンジンであり、この JavaScript 拡張ホストとは異なります。

ライセンス

MIT。