rename

Multi-file coordinated rename using the knowledge graph and text search

Overview

The rename tool performs safe, multi-file coordinated renaming of code symbols by combining knowledge graph relationships (high confidence) with regex text search (lower confidence). It previews changes by default and tags each edit with its confidence level.

When to use: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.

Next step: Run detect_changes() to verify no unexpected side effects.

Parameters

symbol_name · string

Current symbol name to rename (e.g., “validateUser”, “AuthService”)

Required unless symbol_uid is provided.

symbol_uid · string

Direct symbol UID from prior tool results for zero-ambiguity lookup

When available, prefer this over symbol_name to avoid disambiguation.

new_name · string · required

The new name for the symbol

Must be a valid identifier for the symbol’s language.

file_path · string

File path to disambiguate common names when multiple symbols share the same name

Example: "src/auth/validator.ts"

dry_run · boolean · default: true

Preview edits without modifying files

• true (default): Show what would be changed
• false: Apply changes to disk

Always review the dry run results before setting this to false.

repo · string

Repository name or path. Required when multiple repos are indexed.

At least one of symbol_name or symbol_uid must be provided.

Response

changes · array · required

All proposed edits grouped by file

Show file change properties

file_path · string

Path to the file being modified

edits · array

Individual edits within this file

Show edit properties

line · number

Line number of the change

old_text · string

Original text

new_text · string

Replacement text

confidence · string

“graph” - Found via knowledge graph (high confidence, safe)

“text_search” - Found via regex (lower confidence, review carefully)

context · string

Surrounding code context for review

summary · object · required

High-level summary of proposed changes

Show properties

totalEdits · number

Total number of edits across all files

filesAffected · number

Number of files that will be modified

graphEdits · number

High-confidence edits from knowledge graph

textSearchEdits · number

Lower-confidence edits from regex text search

applied · boolean · required

Whether changes were applied to disk (true) or just previewed (false)

Example Usage

Preview Rename (Default)

rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser"
})

Apply Rename

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

Rename with UID (Zero-Ambiguity)

rename({
  symbol_uid: "func_validateUser_abc123",
  new_name: "authenticateUser",
  dry_run: false
})

Disambiguate by File Path

rename({
  symbol_name: "validate",
  file_path: "src/auth/validator.ts",
  new_name: "validateAuthentication"
})

Multi-Repo Rename

rename({
  symbol_name: "processPayment",
  new_name: "handlePayment",
  repo: "my-app",
  dry_run: false
})

Example Response (Dry Run)

{
  "changes": [
    {
      "file_path": "src/auth/validator.ts",
      "edits": [
        {
          "line": 42,
          "old_text": "export function validateUser",
          "new_text": "export function authenticateUser",
          "confidence": "graph",
          "context": "export function validateUser(token: string) {\n  return checkToken(token);\n}"
        }
      ]
    },
    {
      "file_path": "src/auth/login.ts",
      "edits": [
        {
          "line": 18,
          "old_text": "const result = validateUser(token);",
          "new_text": "const result = authenticateUser(token);",
          "confidence": "graph",
          "context": "async function loginHandler(req) {\n  const result = validateUser(token);\n  return result;\n}"
        }
      ]
    },
    {
      "file_path": "config.json",
      "edits": [
        {
          "line": 7,
          "old_text": "\"validator\": \"validateUser\"",
          "new_text": "\"validator\": \"authenticateUser\"",
          "confidence": "text_search",
          "context": "{\n  \"auth\": {\n    \"validator\": \"validateUser\"\n  }\n}"
        }
      ]
    }
  ],
  "summary": {
    "totalEdits": 12,
    "filesAffected": 8,
    "graphEdits": 10,
    "textSearchEdits": 2
  },
  "applied": false
}

Confidence Levels

"graph" (High Confidence)

Source: Knowledge graph relationships

Safety: High — these are actual code references tracked by the graph

Examples:

• Function calls
• Import statements
• Class instantiations
• Method invocations

Action: Generally safe to accept

"text_search" (Lower Confidence)

Source: Regex text search

Safety: Lower — may include false positives like comments, strings, or unrelated matches

Examples:

• References in config files
• String literals
• Comments
• Dynamic references

Action: Review carefully, may need manual adjustment

Real-World Examples

Example 1: Safe Rename Workflow

// Step 1: Preview the rename
rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: true  // default
})

// Review output:
// - 10 graph edits (safe): validator.ts, login.ts, middleware.ts...
// - 2 text_search edits (review): config.json, README.md

// Step 2: Review text_search edits
// config.json: "validator": "validateUser" → OK, should be renamed
// README.md: "...validateUser function..." → Documentation, OK

// Step 3: Apply the rename
rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: false
})

// Step 4: Verify impact
detect_changes({ scope: "all" })
// → Affected: LoginFlow, TokenRefresh
// → Risk: MEDIUM

Example 2: Class Rename

// Rename a class and all its references
rename({
  symbol_name: "UserService",
  new_name: "UserRepository",
  dry_run: false
})

// Updates:
// - Class definition
// - All import statements
// - All instantiations
// - Type annotations

Example 3: Method Rename

// Rename a method within a class
rename({
  symbol_name: "getData",
  file_path: "src/services/ApiService.ts",
  new_name: "fetchData",
  dry_run: false
})

// Updates:
// - Method definition
// - All method calls on that class
// - Preserves other getData methods in different classes

Best Practices

Always dry run first

Never skip the preview. Review the changes, especially text_search edits, before applying.

Use UIDs when available

If you have a symbol_uid from query() or context() results, use it to avoid ambiguity.

Review text_search edits carefully

Graph edits are safe, but text_search edits may include false positives (comments, strings, unrelated code).

Run detect_changes after

After applying the rename, run detect_changes() to verify only expected files were modified.

Use impact() for high-risk renames

Before renaming widely-used symbols, run impact() to understand the blast radius.

Commit after rename

Rename operations can touch many files. Commit immediately after a successful rename to isolate it from other changes.

Workflow Checklist

- [ ] Run rename with dry_run: true (preview)
- [ ] Review graph edits (high confidence)
- [ ] Carefully review text_search edits (lower confidence)
- [ ] Apply rename with dry_run: false
- [ ] Run detect_changes() to verify scope
- [ ] Run tests for affected processes
- [ ] Commit the rename as a standalone change

Use Cases

• Function renaming: Better naming for clarity
• Class renaming: Architecture refactoring
• Method renaming: API improvements
• Variable renaming: Code quality improvements
• Refactoring prep: Rename before extracting modules

Limitations

String Literals and Dynamic References

The rename tool cannot detect:

• Dynamic property access: obj["validateUser"]()
• String literals in external configs
• References in non-indexed files

Solution: Use text_search results and manual review to catch these cases.

Related Tools

• impact - Analyze blast radius before renaming
• detect_changes - Verify rename scope after applying
• context - Understand symbol usage before renaming

Related Resources

• gitnexus://repo/{name}/processes - See which flows use the symbol