Merge commit '3d83740f88b6aaba6962256be517656496b83f25' into lsp-server

2026-05-24 13:04:22 +08:00
parent 7aa60e78f8 3d83740f88
commit 696920df73
292 changed files with 30774 additions and 218828 deletions
@@ -0,0 +1,109 @@
+---
+name: bulk-refactor-workflow
+description: Use when renaming symbols, migrating APIs, or applying safe mechanical changes across many files in the repository.
+---
+
+# Bulk Refactor Workflow（批量重构 / 大范围修改）
+
+## Overview
+
+Guide repository-wide mechanical edits without losing scope control or damaging
+unrelated work. Core principle: enumerate first, transform mechanically, verify
+in loops, and keep every batch auditable.
+
+## When to Use
+
+- Rename APIs, symbols, file conventions, or repeated string patterns
+- Apply scripted or structural edits across many files
+- Migrate callers to a new interface where the change pattern is repeatable
+
+## When Not to Use
+
+- One-off logic changes where no repeatable transformation exists
+- Exploratory redesign or feature work that needs new architecture decisions
+- Cleanup that is only formatting/lint alignment; use `style-cleanup` directly
+
+## Inputs
+
+- Scope: directories, file types, include/exclude rules
+- Transformation: rename, replace, codemod, scripted edit, migration strategy
+- Constraints: behavior-preserving vs. compatibility window vs. staged rollout
+- Verification commands: smallest useful loop plus final gate
+
+## Procedure
+
+1. **Baseline and bound the scope**
+
+   - Record `git status --short`.
+   - Dirty worktrees are allowed.
+   - Do not revert unrelated changes.
+   - Mark the exact target file set before editing.
+   - Run a baseline verification command so existing failures are not misattributed
+     to the refactor.
+
+2. **Enumerate every intended hit**
+
+   - Search before editing with `rg`, `git grep`, or a structured query.
+   - Separate real code hits from comments, docs, generated files, and samples.
+   - Write down exclusions before running the transformation.
+
+3. **Choose the safest mechanical transform**
+
+   - Prefer deterministic transforms: codemods, scripts, structured edits, or
+     narrow search/replace with explicit scope.
+   - If compatibility matters, use a staged migration: adapt providers first,
+     migrate callers second, remove compatibility layer last.
+
+4. **Apply in bounded batches**
+
+   - First, apply the transformation in bounded batches.
+   - Verify each batch before widening scope.
+   - Stop immediately if output differs from the expected hit class.
+
+5. **Verify in loops**
+
+   - Run the smallest relevant verification after each batch.
+   - Re-check the hit list after edits to confirm the intended pattern is gone and
+     unintended patterns were not introduced.
+
+6. **Finish with targeted cleanup**
+
+   - If the mechanical change leaves formatting or lint fallout, Use `style-cleanup` for the final formatting/lint pass.
+   - Keep that cleanup scoped to the refactor set unless the user approves a wider
+     pass.
+
+7. **Report**
+
+   - Summarize files touched, transform rules used, verification evidence, and any
+     residual risk.
+
+## Output Contract
+
+- `Scope:` files, directories, and exclusions actually used
+- `Transformation:` exact rule or script applied
+- `Batches:` how the work was partitioned
+- `Verification:` commands, exit status, and what each loop proved
+- `Risks:` remaining ambiguous areas, compatibility debt, or deferred cleanup
+
+## Success Criteria
+
+- Every changed file belongs to the declared scope
+- The transformation is reproducible and explainable
+- Verification passes at both batch level and final gate
+- Unrelated work in the repository is preserved
+
+## Failure Handling
+
+- If the hit list is ambiguous, stop and refine scope before editing
+- If the transform cannot be expressed mechanically, downgrade to a normal
+  refactor plan instead of pretending it is safe bulk work
+- If verification fails mid-batch, stop, inspect the smallest failing delta, and
+  correct the transform before continuing
+- If compatibility risk is higher than expected, split the migration into staged
+  commits or phases
+
+## Guardrails
+
+- Never run repository-wide replacement without an explicit hit review
+- Never mix unrelated cleanup into the same batch
+- Never hide a large-scope behavior change behind the label "mechanical refactor"