git:20260506.3a07173 to git:20260809.a6d9541

29 added, 29 removed. Audit A to A.

---

name: gitnexus-refactoring

description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""

---

# Refactoring with GitNexus

## When to Use

- "Rename this function safely"

- "Extract this into a module"

- "Split this service"

- "Move this to a new file"

- Any task involving renaming, extracting, splitting, or restructuring code

## Workflow

```

- 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

+ 1. impact({target: "X", direction: "upstream"}) → Map all dependents

+ 2. query({search_query: "X"}) → Find execution flows involving X

+ 3. context({name: "X"}) → See all incoming/outgoing refs

4. Plan update order: interfaces → implementations → callers → tests

```

- > If "Index is stale" → run `npx gitnexus analyze` in terminal.

+ > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.

## Checklists

### Rename Symbol

```

- - [ ] 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

+ - [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits

+ - [ ] Review graph edits (high confidence) and text_search edits (review carefully)

+ - [ ] If satisfied: rename({..., dry_run: false}) — apply edits

+ - [ ] detect_changes() — verify only expected files changed

- [ ] Run tests for affected processes

```

### Extract Module

```

- - [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs

- - [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers

+ - [ ] context({name: target}) — see all incoming/outgoing refs

+ - [ ] impact({target, direction: "upstream"}) — find all external callers

- [ ] Define new module interface

- [ ] Extract code, update imports

- - [ ] gitnexus_detect_changes() — verify affected scope

+ - [ ] detect_changes() — verify affected scope

- [ ] Run tests for affected processes

```

### Split Function/Service

```

- - [ ] gitnexus_context({name: target}) — understand all callees

+ - [ ] context({name: target}) — understand all callees

- [ ] Group callees by responsibility

- - [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update

+ - [ ] impact({target, direction: "upstream"}) — map callers to update

- [ ] Create new functions/services

- [ ] Update callers

- - [ ] gitnexus_detect_changes() — verify affected scope

+ - [ ] detect_changes() — verify affected scope

- [ ] Run tests for affected processes

```

## Tools

- **gitnexus_rename** — automated multi-file rename:

+ **rename** — automated multi-file rename:

```

- gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})

+ 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)

+ → 10 graph edits (high confidence), 2 text_search edits (review)

→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]

```

- **gitnexus_impact** — map all dependents first:

+ **impact** — map all dependents first:

```

- gitnexus_impact({target: "validateUser", direction: "upstream"})

+ impact({target: "validateUser", direction: "upstream"})

→ d=1: loginHandler, apiMiddleware, testUtils

→ Affected Processes: LoginFlow, TokenRefresh

```

- **gitnexus_detect_changes** — verify your changes after refactoring:

+ **detect_changes** — verify your changes after refactoring:

```

- gitnexus_detect_changes({scope: "all"})

+ detect_changes({scope: "all"})

→ Changed: 8 files, 12 symbols

→ Affected processes: LoginFlow, TokenRefresh

→ Risk: MEDIUM

```

- **gitnexus_cypher** — custom reference queries:

+ **cypher** — custom reference queries:

```cypher

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})

RETURN caller.name, caller.filePath ORDER BY caller.filePath

```

## Risk Rules

| Risk Factor | Mitigation |

| ------------------- | ----------------------------------------- |

- | Many callers (>5) | Use gitnexus_rename for automated updates |

+ | Many callers (>5) | Use rename for automated updates |

| Cross-area refs | Use detect_changes after to verify scope |

- | String/dynamic refs | gitnexus_query to find them |

+ | String/dynamic refs | query to find them |

| External/public API | Version and deprecate properly |

## Example: Rename `validateUser` to `authenticateUser`

```

- 1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})

- → 12 edits: 10 graph (safe), 2 ast_search (review)

+ 1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})

+ → 12 edits: 10 graph (safe), 2 text_search (review)

→ Files: validator.ts, login.ts, middleware.ts, config.json...

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

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

- 3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})

+ 3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})

→ Applied 12 edits across 8 files

- 4. gitnexus_detect_changes({scope: "all"})

+ 4. detect_changes({scope: "all"})

→ Affected: LoginFlow, TokenRefresh

→ Risk: MEDIUM — run tests for these flows

```