# You'd miss these patterns:
const { createWidget } = api          # destructuring
const init = createWidget             # assignment
type Factory = typeof createWidget    # type reference
async ({ createWidget }: Deps) => {}  # parameter destructuring

bun tools/refactor.ts rename.batch --pattern createWidget --replace createGadget --output edits.json
bun tools/refactor.ts editset.apply edits.json
# Finds ALL 127 references including destructuring, types, re-exports

# Run from the batch plugin directory

# 1. Check file name conflicts
bun tools/refactor.ts file.rename --pattern widget --replace repo --glob "**/*.ts" --check-conflicts

# 2. Check symbol conflicts
bun tools/refactor.ts rename.batch --pattern widget --replace repo --check-conflicts

# 3. Check for existing targets manually
ls **/repo*.ts 2>/dev/null || echo "No existing repo files"

# Create file rename proposal
bun tools/refactor.ts file.rename --pattern widget --replace repo \
  --glob "**/*.{ts,tsx}" \
  --output file-editset.json

# Preview
bun tools/refactor.ts file.apply file-editset.json --dry-run

# Apply
bun tools/refactor.ts file.apply file-editset.json

# Create symbol rename proposal
bun tools/refactor.ts rename.batch --pattern widget --replace repo \
  --output symbol-editset.json

# Preview
bun tools/refactor.ts editset.apply symbol-editset.json --dry-run

# Apply
bun tools/refactor.ts editset.apply symbol-editset.json

# TypeScript comments and strings
bun tools/refactor.ts pattern.replace --pattern widget --replace repo \
  --glob "**/*.{ts,tsx}" \
  --backend ripgrep \
  --output text-editset.json

# Markdown documentation
bun tools/refactor.ts pattern.replace --pattern widget --replace repo \
  --glob "**/*.md" \
  --backend ripgrep \
  --output docs-editset.json

# Preview and apply each
bun tools/refactor.ts editset.apply text-editset.json --dry-run
bun tools/refactor.ts editset.apply text-editset.json

# For each vendor submodule with matches
cd vendor/<submodule>

# Run the same workflow (conflicts, files, symbols, text)
bun ../beorn-tools/plugins/batch/tools/refactor.ts rename.batch \
  --pattern widget --replace repo --check-conflicts

# After applying
git add -A
git commit -m "refactor: rename widget → repo"
git push

# Return to main repo
cd ../..
git add vendor/<submodule>
git commit -m "chore(vendor): update <submodule> with repo terminology"

# Check for remaining mentions
grep -ri widget . --include="*.ts" --include="*.tsx" | grep -v node_modules | wc -l

# Type check
bun tsc --noEmit

# Lint and fix
bun fix

# Run tests
bun run test:all

# 1. Find files that would be renamed
bun tools/refactor.ts file.find --pattern "user-service" --replace "account-service" --glob "**/*.ts"

# 2. Check for conflicts (target files already exist?)
bun tools/refactor.ts file.rename --pattern "user-service" --replace "account-service" \
  --glob "**/*.ts" --check-conflicts

# 3. Create editset
bun tools/refactor.ts file.rename --pattern "user-service" --replace "account-service" \
  --glob "**/*.ts" --output file-renames.json

# 4. Preview (dry run)
bun tools/refactor.ts file.apply file-renames.json --dry-run

# 5. Apply
bun tools/refactor.ts file.apply file-renames.json

# After renaming user-service.ts → account-service.ts, update imports:
bun tools/refactor.ts pattern.replace \
  --pattern "user-service" \
  --replace "account-service" \
  --glob "**/*.ts" \
  --backend ripgrep \
  --output import-updates.json

bun tools/refactor.ts editset.apply import-updates.json --dry-run
bun tools/refactor.ts editset.apply import-updates.json

import { createUser } from "./user-service"
import { UserService } from "../services/user-service"

import { createUser } from "./account-service"
import { UserService } from "../services/account-service"

# 1. Check for conflicts (does createGadget already exist?)
bun tools/refactor.ts rename.batch --pattern "createWidget" --replace "createGadget" --check-conflicts

# 2. Create editset
bun tools/refactor.ts rename.batch --pattern "createWidget" --replace "createGadget" \
  --output symbol-renames.json

# 3. Preview
bun tools/refactor.ts editset.apply symbol-renames.json --dry-run

# 4. Apply
bun tools/refactor.ts editset.apply symbol-renames.json

// Function declaration
export function createWidget(config: Config) { }  → createGadget

// Arrow function
const createWidget = (opts) => { }  → createGadget

// Destructuring
const { createWidget } = api  → createGadget

// Parameter
function init({ createWidget }: Deps) { }  → createGadget

// Type reference
type Factory = typeof createWidget  → createGadget

# Check conflicts
bun tools/refactor.ts rename.batch --pattern "ApiClient" --replace "HttpClient" --check-conflicts

# Create and apply
bun tools/refactor.ts rename.batch --pattern "ApiClient" --replace "HttpClient" \
  --output type-renames.json
bun tools/refactor.ts editset.apply type-renames.json

// Interface definition
export interface ApiClient { }  → HttpClient

// Type alias
type Client = ApiClient  → HttpClient

// Variable type annotation
const client: ApiClient = ...  → HttpClient

// Generic constraint
function fetch<T extends ApiClient>()  → HttpClient

// Import
import type { ApiClient } from "./api"  → HttpClient

# Markdown docs
bun tools/refactor.ts pattern.replace \
  --pattern "widget" \
  --replace "gadget" \
  --glob "**/*.md" \
  --backend ripgrep \
  --output docs-updates.json

# TypeScript comments and strings
bun tools/refactor.ts pattern.replace \
  --pattern "widget" \
  --replace "gadget" \
  --glob "**/*.ts" \
  --backend ripgrep \
  --output comment-updates.json

# Preview and apply
bun tools/refactor.ts editset.apply docs-updates.json --dry-run
bun tools/refactor.ts editset.apply docs-updates.json

// This creates a new widget  → gadget
const msg = "Widget not found"  → "Gadget not found"
/** @description Widget factory */  → Gadget factory

# Widget Guide → Gadget Guide

Create a widget with... → Create a gadget with...

bun tools/refactor.ts pattern.replace \
  --pattern 'fmt.Println($MSG)' \
  --replace 'log.Info($MSG)' \
  --glob "**/*.go" \
  --backend ast-grep \
  --output go-logging.json

bun tools/refactor.ts editset.apply go-logging.json

fmt.Println("Starting server")
fmt.Println(err.Error())

log.Info("Starting server")
log.Info(err.Error())

# Phase 1: Conflict Analysis
bun tools/refactor.ts file.rename --pattern "user" --replace "account" --check-conflicts
bun tools/refactor.ts rename.batch --pattern "user" --replace "account" --check-conflicts

# Phase 2: File Renames (FIRST)
bun tools/refactor.ts file.rename --pattern "user" --replace "account" \
  --glob "**/*.ts" --output phase2-files.json
bun tools/refactor.ts file.apply phase2-files.json

# Phase 3: Symbol Renames
bun tools/refactor.ts rename.batch --pattern "user" --replace "account" \
  --output phase3-symbols.json
bun tools/refactor.ts editset.apply phase3-symbols.json

# Phase 4: Text/Comments
bun tools/refactor.ts pattern.replace --pattern "user" --replace "account" \
  --glob "**/*.ts" --backend ripgrep --output phase4-text.json
bun tools/refactor.ts editset.apply phase4-text.json

# Phase 5: Documentation
bun tools/refactor.ts pattern.replace --pattern "user" --replace "account" \
  --glob "**/*.md" --backend ripgrep --output phase5-docs.json
bun tools/refactor.ts editset.apply phase5-docs.json

# Phase 6: Verify
grep -ri user . --include="*.ts" | wc -l  # Should be 0
bun tsc --noEmit
bun fix
bun run test:all

# Create full editset
bun tools/refactor.ts rename.batch --pattern "config" --replace "options" \
  --output full-editset.json

# Filter to only certain files
bun tools/refactor.ts editset.select full-editset.json \
  --include "src/core/**" \
  --exclude "src/core/legacy/**" \
  --output filtered-editset.json

# Apply filtered set
bun tools/refactor.ts editset.apply filtered-editset.json

git rev-parse --is-inside-work-tree 2>/dev/null
git status --porcelain

// ast-grep renames this ✓
const widgetDir = "/path"

// But MISSES these ✗
interface TestEnv { widgetDir: string }  // property definition
({ widgetDir }) => { ... }               // destructuring

# Run from the batch plugin directory

# 1. Generate editset with enriched context
bun tools/refactor.ts rename.batch --pattern widget --replace repo -o editset.json

# 2. LLM reviews the editset and patches specific references
#    - Set replace to null to skip a reference
#    - Set replace to a custom string for non-standard replacement
bun tools/refactor.ts editset.patch editset.json <<'EOF'
{ "b2c3": "Repository", "c3d4": null }
EOF

# 3. Apply the patched editset
bun tools/refactor.ts editset.apply editset.json

{
  "refs": [
    {
      "id": "a1b2",
      "kind": "decl",
      "scope": "createWidget",
      "replace": "repo"
    },
    { "id": "b2c3", "kind": "type", "scope": null, "replace": "repo" },
    { "id": "c3d4", "kind": "comment", "scope": null, "replace": "repo" }
  ]
}

bun tools/refactor.ts editset.patch editset.json <<'EOF'
{ "b2c3": "Repository", "c3d4": null }
EOF

{
  "ctx": [
    "  // Create a new widget for the user",
    "► const vault = createVault(config)",
    "  return widget"
  ]
}

# Run from the batch plugin directory

# Preview what would be migrated
bun tools/refactor.ts migrate --from widget --to repo --dry-run

# Run migration (creates editsets in .editsets/ directory)
bun tools/refactor.ts migrate --from widget --to repo

# Custom output directory
bun tools/refactor.ts migrate --from widget --to repo --output ./my-editsets

# Custom file glob
bun tools/refactor.ts migrate --from widget --to repo --glob "**/*.{ts,tsx,md}"

# Review and apply each phase
bun tools/refactor.ts file.apply .editsets/01-file-renames.json --dry-run
bun tools/refactor.ts file.apply .editsets/01-file-renames.json

bun tools/refactor.ts editset.apply .editsets/02-symbol-renames.json --dry-run
bun tools/refactor.ts editset.apply .editsets/02-symbol-renames.json

bun tools/refactor.ts editset.apply .editsets/03-text-patterns.json --dry-run
bun tools/refactor.ts editset.apply .editsets/03-text-patterns.json

# OLD API:
# const { lastFrame, stdin } = render(<App />)
# expect(stripAnsi(lastFrame())).toContain('Hello')
# stdin.write('\x1b[A')

# NEW API:
# const app = render(<App />)
# expect(app.text).toContain('Hello')
# await app.press('ArrowUp')

bun tools/refactor.ts pattern.migrate \
  --patterns "lastFrame(),stdin.write,= render(" \
  --glob "**/*.test.tsx" \
  --prompt "Migrate old render() API to new App API:
    - const { lastFrame, stdin } = render(...) → const app = render(...)
    - lastFrame() → app.ansi
    - stripAnsi(lastFrame()) → app.text
    - stdin.write('\\x1b[A') → await app.press('ArrowUp')
    - stdin.write('\\x1b[B') → await app.press('ArrowDown')" \
  --output /tmp/migrate.json

# Review
jq '.refs[:5]' /tmp/migrate.json

# Apply
bun tools/refactor.ts editset.apply /tmp/migrate.json

# 1. Dry run - see what would be sent to LLM
bun tools/refactor.ts pattern.migrate \
  --patterns "oldPattern" \
  --glob "**/*.ts" \
  --prompt "Migrate to new pattern" \
  --dry-run

# 2. Run migration
bun tools/refactor.ts pattern.migrate \
  --patterns "oldPattern" \
  --glob "**/*.ts" \
  --prompt "Migrate to new pattern" \
  --output /tmp/migrate.json

# 3. Review editset
jq '.refs | length' /tmp/migrate.json        # Count changes
jq '.refs[:3]' /tmp/migrate.json             # Preview first 3

# 4. Apply
bun tools/refactor.ts editset.apply /tmp/migrate.json

# 5. Verify
bun tsc --noEmit && bun run test:fast

# Good prompt example:
--prompt "Migrate test API:
  - const { lastFrame, stdin } = render(...) → const app = render(...)
  - lastFrame() → app.ansi
  - stripAnsi(lastFrame()) → app.text (remove stripAnsi wrapper)
  - stdin.write('x') → await app.press('x')
  - stdin.write('\\x1b[A') → await app.press('ArrowUp')
  - stdin.write('\\x1b[B') → await app.press('ArrowDown')
  - stdin.write('\\x1b[C') → await app.press('ArrowRight')
  - stdin.write('\\x1b[D') → await app.press('ArrowLeft')
  - stdin.write('\\r') → await app.press('Enter')"

{
  "id": "rename-widget-to-repo-1706123456789",
  "operation": "rename",
  "from": "widget",
  "to": "repo",
  "refs": [
    {
      "refId": "a1b2c3d4",
      "file": "src/storage.ts",
      "line": 45,
      "range": [45, 12, 45, 17],
      "kind": "call",
      "scope": "initStorage",
      "ctx": [
        "  function initStorage() {",
        "► const root = createVault(config);",
        "  return root;"
      ],
      "replace": "repo",
      "preview": "const root = createWidget(config);",
      "checksum": "abc123...",
      "selected": true
    },
    {
      "refId": "b2c3d4e5",
      "file": "src/errors.ts",
      "line": 12,
      "range": [12, 25, 12, 30],
      "kind": "string",
      "scope": "errorHandler",
      "ctx": ["► throw new Error(\"vault not found\");"],
      "replace": "repo",
      "preview": "throw new Error(\"widget not found\");",
      "checksum": "def456...",
      "selected": true
    }
  ],
  "edits": [
    /* ... byte-level edits */
  ],
  "createdAt": "2024-01-24T12:00:00.000Z"
}

# Minimal patch format: refId → replacement or null
bun tools/refactor.ts editset.patch editset.json <<'EOF'
{
  "b2c3d4e5": "repository",
  "c3d4e5f6": null
}
EOF

# Or pipe from a file
cat my-patch.json | bun tools/refactor.ts editset.patch editset.json

# Output to different file
bun tools/refactor.ts editset.patch editset.json --output patched.json <<'EOF'
{ "b2c3": null }
EOF

{
  "refId1": "custom replacement", // Use this replacement instead of default
  "refId2": null // Skip this reference
  // refId3 not mentioned           // Apply with default replacement
}

{
  "refs": [
    { "refId": "a1b2", "replace": "Repository" },
    { "refId": "b2c3", "replace": null }
  ]
}

const widgetPath = "/path/to/widget" // ✓ obvious

// Destructuring in function parameter
export function init({ widgetPath, config }: Options) {
  return load(widgetPath)
}

// Nested destructuring
const {
  paths: { widgetPath },
} = config

// Arrow function parameter destructuring
const handler = ({ widgetPath }: Ctx) => widgetPath

// Object shorthand
return { widgetPath } // property AND value both renamed

bun tools/refactor.ts rename.batch --pattern widgetPath --replace repoPath --output edits.json
bun tools/refactor.ts editset.apply edits.json
# All 47 occurrences updated atomically

// src/index.ts - barrel file
export { Widget } from "./widget"
export type { Widget, WidgetConfig } from "./widget"

// src/components/index.ts - nested barrel
export * from "./Widget"
export { Widget as DefaultWidget } from "./Widget"

bun tools/refactor.ts rename.batch --pattern Widget --replace Gadget --output edits.json
# Found: 89 references across 23 files including all re-exports

// Type-only import - easy to miss with grep
import type { UserService } from "./services"

// Inline type import
const fn = (service: import("./services").UserService) => {}

// Generic constraints
function process<T extends UserService>(svc: T) {}

bun tools/refactor.ts rename.batch --pattern UserService --replace AccountService --check-conflicts
bun tools/refactor.ts rename.batch --pattern UserService --replace AccountService --output edits.json

/**
 * @see parseConfig for config format
 * @param {ReturnType<typeof parseConfig>} config
 */
function initApp(config) {}

bun tools/refactor.ts pattern.replace \
  --pattern parseConfig \
  --replace loadConfig \
  --glob "**/*.{ts,js}" \
  --backend ripgrep \
  --output jsdoc-updates.json

// Static import (caught by ts-morph file.rename)
import { getUser } from "./user-api"

// Dynamic import (caught by ripgrep pattern.replace)
const api = await import("./user-api")
const { handler } = await import(`./user-api`)

# 1. Rename file + static imports
bun tools/refactor.ts file.rename --pattern user-api --replace account-api --output files.json
bun tools/refactor.ts file.apply files.json

# 2. Catch dynamic imports
bun tools/refactor.ts pattern.replace \
  --pattern "user-api" \
  --replace "account-api" \
  --glob "**/*.ts" \
  --backend ripgrep \
  --output dynamic.json
bun tools/refactor.ts editset.apply dynamic.json

// src/widget.ts
export function createWidget() {}

// tests/widget.test.ts
vi.mock("../widget", () => ({
  createWidget: vi.fn(), // Mock uses same name
}))

// tests/fixtures/widget-fixture.ts
export const mockCreateWidget = () => {} // Compound identifier

bun tools/refactor.ts rename.batch --pattern createWidget --replace createGadget --output edits.json
# Found in: src/widget.ts, 12 test files, 3 fixture files

const widget = {} // lowercase
const Repo = {} // PascalCase
const REPO_PATH = "" // SCREAMING_CASE
const widgetConfig = {} // camelCase compound
class RepoManager {} // PascalCase compound
const REPO_OPTIONS = {} // SCREAMING compound

bun tools/refactor.ts rename.batch --pattern widget --replace repo --output edits.json

const repo = {} // lowercase preserved
const Repo = {} // PascalCase preserved
const REPO_PATH = "" // SCREAMING_CASE preserved
const repoConfig = {} // camelCase compound
class RepoManager {} // PascalCase compound
const REPO_OPTIONS = {} // SCREAMING compound

packages/
  core/src/widget.ts
  cli/src/commands/widget.ts
  tui/src/views/widget-view.tsx
  storage/src/widget-loader.ts

bun tools/refactor.ts migrate --from widget --to repo --glob "packages/**/*.{ts,tsx}"

# Creates editsets in .editsets/:
# - 01-file-renames.json (4 files)
# - 02-symbol-renames.json (234 symbols)
# - 03-text-patterns.json (89 text occurrences)

# Create editset
bun tools/refactor.ts rename.batch --pattern Widget --replace Gadget --output edits.json

# ... time passes, teammate edits src/widget.ts ...

# Apply fails safely with drift detection
bun tools/refactor.ts editset.apply edits.json
# Error: Drift detected in src/widget.ts (checksum mismatch)
# Skipped: 3 edits in src/widget.ts
# Applied: 45 edits in other files

Is this a terminology migration (file names + code + docs)?
├── YES → `migrate --from X --to Y`
└── NO
    ├── Is this an API migration (complex pattern changes)?
    │   └── YES → `pattern.migrate --patterns X --prompt "..."` (LLM-powered)
    ├── Renaming files?
    │   └── YES → `file.rename --pattern X --replace Y`
    ├── Renaming TypeScript identifiers?
    │   └── YES → `rename.batch --pattern X --replace Y`
    ├── Updating Go/Rust/Python structural patterns?
    │   └── YES → `pattern.replace --backend ast-grep`
    └── Updating text/markdown/comments?
        └── YES → `pattern.replace --backend ripgrep`

# Instead of:
bun tools/refactor.ts migrate --from widget --to repo -o .editsets
rg -l widget -g "*.ts" | grep -v .editsets | wc -l  # Annoying

# Do this:
bun tools/refactor.ts migrate --from widget --to repo -o /tmp/editsets
rg -l widget -g "*.ts" | wc -l  # Clean

# Quick look at the editset structure and refs
cat /tmp/editset.json | head -50

# See how many refs/edits
cat /tmp/editset.json | jq '{refs: .refs | length, edits: .edits | length}'

# Dry-run shows what would be applied
bun tools/refactor.ts editset.apply /tmp/editset.json --dry-run

# Find files containing pattern
rg -l "useRepo" -g "*.ts"

# Show matches with line numbers
rg -n "useRepo" -g "*.ts"

# Count matches
rg -c "widget" -g "*.ts" | head -20

# Show context around matches
rg -C 2 "createWidget" -g "*.ts"

# Instead of find (slow, doesn't respect .gitignore):
find . -name "*widget*" -not -path "./node_modules/*"

# Use rg --files with glob:
rg --files -g "*widget*"           # Files with "widget" in name
rg --files -g "*.ts" | head -10   # All .ts files
rg --files -g "*widget*.ts"        # .ts files with "widget" in name
rg --files packages/              # All files in packages/

# SLOW - shell loop overhead - DON'T DO THIS
rg -l "widget" | while read f; do
  echo "=== $f ==="
  rg -n "widget" "$f"
done

# FAST - single rg invocation
rg -n "widget" -g "*.ts"                    # Filename:line:match
rg --heading -n "widget" -g "*.ts"          # Group by filename
rg --vimgrep "widget" -g "*.ts"             # file:line:col:match

# Test the glob finds expected files
rg --files -g "**/*.ts" | head -10
rg --files -g "apps/**/*.tsx" | head -10

# Then use same glob in batch command
bun tools/refactor.ts pattern.replace --pattern widget --glob "apps/**/*.tsx" -o /tmp/edits.json

# Fast count of remaining mentions
rg -c "widget" -g "*.ts" --stats

# List files still containing pattern
rg -l "widget" -g "*.ts" -g "*.tsx"

# Exclude vendor/node_modules (fd-style filtering)
rg -l "widget" -g "*.ts" -g "!vendor/**" -g "!node_modules/**"

# 1. Verify rg finds matches directly
rg -l "pattern" -g "*.ts"

# 2. Check the glob syntax
# Bad:  --glob "**/*.{ts,tsx}"   (shell may expand braces)
# Good: --glob "**/*.ts" --glob "**/*.tsx"  (separate globs)

# 3. Run with verbose output
DEBUG=* bun tools/refactor.ts pattern.replace --pattern widget --glob "**/*.ts"