gitnexus-refactoring

GitNexus を使ったリファクタリング

使用する場面

• 「この関数を安全に名前変更する」
• 「これをモジュールに切り出す」
• 「このサービスを分割する」
• 「これを新しいファイルに移動する」
• コードの名前変更、切り出し、分割、再構成を伴うあらゆるタスク

ワークフロー

1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
2. gitnexus_query({query: "X"})                            → Find execution flows involving X
3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
4. Plan update order: interfaces → implementations → callers → tests

「インデックスが古くなっています」と表示された場合は、ターミナルで npx gitnexus analyze を実行してください。

チェックリスト

シンボルの名前変更

- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
- [ ] gitnexus_detect_changes() — verify only expected files changed
- [ ] Run tests for affected processes

モジュールの切り出し

- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
- [ ] Define new module interface
- [ ] Extract code, update imports
- [ ] gitnexus_detect_changes() — verify affected scope
- [ ] Run tests for affected processes

関数／サービスの分割

- [ ] gitnexus_context({name: target}) — understand all callees
- [ ] Group callees by responsibility
- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
- [ ] Create new functions/services
- [ ] Update callers
- [ ] gitnexus_detect_changes() — verify affected scope
- [ ] Run tests for affected processes

ツール

gitnexus_rename — 複数ファイルにまたがる名前変更を自動化します：

gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
→ 12 edits across 8 files
→ 10 graph edits (high confidence), 2 ast_search edits (review)
→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]

gitnexus_impact — まずすべての依存元をマッピングします：

gitnexus_impact({target: "validateUser", direction: "upstream"})
→ d=1: loginHandler, apiMiddleware, testUtils
→ Affected Processes: LoginFlow, TokenRefresh

gitnexus_detect_changes — リファクタリング後に変更を検証します：

gitnexus_detect_changes({scope: "all"})
→ Changed: 8 files, 12 symbols
→ Affected processes: LoginFlow, TokenRefresh
→ Risk: MEDIUM

gitnexus_cypher — カスタム参照クエリ：

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
RETURN caller.name, caller.filePath ORDER BY caller.filePath

リスクルール

リスク要因	対策
呼び出し元が多い（>5）	自動更新には gitnexus_rename を使用します
領域をまたぐ参照	スコープの検証には後で detect_changes を使用します
文字列／動的参照	gitnexus_query で検索します
外部／公開 API	適切にバージョン管理し、非推奨にします

例：validateUser を authenticateUser に名前変更する

1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
   → 12 edits: 10 graph (safe), 2 ast_search (review)
   → Files: validator.ts, login.ts, middleware.ts, config.json...

2. Review ast_search edits (config.json: dynamic reference!)

3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
   → Applied 12 edits across 8 files

4. gitnexus_detect_changes({scope: "all"})
   → Affected: LoginFlow, TokenRefresh
   → Risk: MEDIUM — run tests for these flows