Scenario 17: Advanced File Editing

Scenario 17: Advanced File Editing

Developer making precise, AST-based code modifications with preview and undo support.

Quick Start

/select 17

Overview

Scenario 17 provides surgical code editing capabilities using AST (Abstract Syntax Tree) parsing. Unlike simple text replacement, AST-based editing understands code structure, preserves formatting, and ensures syntactically valid modifications.

Use Cases

Finding Code Targets

Locate specific functions, classes, or methods for editing:

> Find function heap_insert in src/backend/access/heap/heapam.c

╭─────────────── Found Code Target ─────────────────────────╮
│                                                            │
│  Name: heap_insert                                         │
│  Type: function                                            │
│  File: src/backend/access/heap/heapam.c                    │
│  Lines: 2156-2298                                          │
│                                                            │
│  ```c                                                      │
│  void heap_insert(Relation relation,                       │
│                   HeapTuple tup,                           │
│                   CommandId cid,                           │
│                   int options,                             │
│                   BulkInsertState bistate)                 │
│  {                                                         │
│      ...                                                   │
│  }                                                         │
│  ```                                                       │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Preview Changes with Diff

Generate a unified diff preview before applying changes:

> Edit function validate_input to add bounds checking

╭─────────────── Edit Preview ──────────────────────────────╮
│                                                            │
│  Target: validate_input (function)                         │
│  File: src/utils/validation.c:45-67                        │
│                                                            │
│  Changes:                                                  │
│  ```diff                                                   │
│  @@ -45,6 +45,10 @@                                        │
│   bool validate_input(const char *input, size_t len)       │
│   {                                                        │
│  +    /* Bounds checking */                                │
│  +    if (len > MAX_INPUT_SIZE) {                          │
│  +        return false;                                    │
│  +    }                                                    │
│       if (input == NULL) {                                 │
│           return false;                                    │
│       }                                                    │
│  ```                                                       │
│                                                            │
│  Use `/edit apply` to apply the changes.                   │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Apply Edits with Backup

Apply changes with automatic backup creation:

> Apply the edit

╭─────────────── Edit Applied ──────────────────────────────╮
│                                                            │
│  Status: SUCCESS                                           │
│  File: src/utils/validation.c                              │
│  Backup: src/utils/validation.c.bak.20241209_143521        │
│                                                            │
│  Changes applied:                                          │
│    - Added bounds checking (4 lines)                       │
│                                                            │
│  Use `/edit undo` to revert changes.                       │
│                                                            │
╰────────────────────────────────────────────────────────────╯

AST-Based Editing

Supported Target Types

Type Description Example
function Standalone functions heap_insert, main
method Class methods MyClass.process
class Class definitions TransactionManager
struct Structure definitions HeapTupleData

Edit Modes

Mode Description Use Case
replace Replace entire target Rewrite function logic
insert_before Insert code before target Add imports, declarations
insert_after Insert code after target Add new methods
delete Remove target Remove deprecated code
rename Rename identifier Refactor naming

Rename Operation

> Rename class OldManager to NewManager

╭─────────────── Rename Preview ────────────────────────────╮
│                                                            │
│  Rename: OldManager -> NewManager                          │
│                                                            │
│  Affected files (3):                                       │
│    src/core/manager.py:15,23,45,67                         │
│    src/api/handlers.py:12,34                               │
│    tests/test_manager.py:8,19,31                           │
│                                                            │
│  Total replacements: 9                                     │
│                                                            │
│  Use `/edit apply` to apply the rename.                    │
│                                                            │
╰────────────────────────────────────────────────────────────╯

CLI Commands

Finding Targets

# Find function by name
codegraph edit find --target heap_insert --file src/heap.c

# Find all functions matching pattern
codegraph edit find --pattern "validate_*" --type function

# Find class definition
codegraph edit find --target MyClass --type class

Applying Edits

# Apply edit with preview
codegraph edit apply --file src/file.c --target func_name --preview

# Apply edit immediately
codegraph edit apply --file src/file.c --target func_name --new-code @patch.txt

# Rename identifier across files
codegraph edit rename --old OldName --new NewName --scope src/

Undo Operations

# List recent edits
codegraph edit history

# Undo last edit
codegraph edit undo

# Undo specific edit by ID
codegraph edit undo --id edit_abc123

TUI Commands

Command Description
/edit find <target> Find code target
/edit preview Show pending changes
/edit apply Apply pending changes
/edit undo Undo last edit
/edit history Show edit history

Example Questions

  • “Find function heap_insert in src/heap.c”
  • “Edit function validate_input to add null check”
  • “Rename class TransactionHandler to TxHandler”
  • “Delete unused function old_helper”
  • “Insert logging before function process_request”
  • “Show me the current edit preview”

Integration with Other Scenarios

Scenario 17 integrates with:

  • S18 (Code Optimization): Apply optimization suggestions
  • S19 (Standards Check): Fix standards violations
  • S05 (Refactoring): Execute refactoring plans
> /select 18
> Optimize src/core/

# After reviewing suggestions...
> Apply suggestion opt_001

# This invokes S17 for the actual edit

Workflow Example

# 1. Find the target
> Find function process_data in src/processor.py

# 2. Review the code
> Show me the full implementation

# 3. Request edit
> Add error handling for empty input

# 4. Preview changes
> /edit preview

# 5. Apply changes
> /edit apply

# 6. Verify
> Show me the updated function