weavatrix-refactor

Evidence-backed, transactional refactoring for coding agents.

weavatrix-refactor is the write-capable member of the Weavatrix family. It combines the complete read-only weavatrix code-intelligence MCP with 11 refactoring tools that can prove a change, preview it against the current working tree, apply it atomically, refresh the graph, and roll it back.

It is substantially more than a rename wrapper:

• semantic JS/TS rename through the bundled language server;

• SQL table and field rename with schema-aware evidence;

• strict graph-plus-lexical rename for Python, Rust, Go, Java, C#, and Solidity;

• several related JS/TS renames merged into one atomic transaction;

• signature, symbol-body, import, bulk-replace, move, and delete-safety workflows;

• byte-exact file hashes, before text, provenance, uncertainty, and graph revision in every applyable plan;

• stale-tree detection, repository locking, rollback bundles, and automatic rollback after a mid-write failure;

• architecture and cycle projection before structural moves;

• post-change blast-radius and verification tools inherited from the core.

Why this is a separate package

The MIT weavatrix core is physically read-only: its published artifact has no repository source-write path. This Apache-2.0 package is the explicit write boundary. Installing it and selecting its refactor profile makes the edit capability visible; without this package, the server cannot modify source.

The split is a safety property, not packaging cosmetics:

weavatrix core          weavatrix-refactor                 repository
read-only evidence  ->  plan + preview + confirmation  ->  atomic write
graph / LSP / audit     hashes / provenance / rollback     refreshed graph

Related MCP server: MCP Refactoring

What makes the refactor workflow different

An ordinary editor rename answers: "Which text edits should I make now?" Weavatrix Refactor also answers:

The system fails closed when proof is insufficient. It never upgrades an INFERRED edge into an applyable edit and never hides an ambiguous reference.

The complete rename workflow

rename_symbol and rename_related_symbols are complete operations, not PLANNED-only helpers. Each method owns both phases.

1. Preview

Call the rename method normally:

{
  "symbol": "src/users.ts#getUser@12",
  "new_name": "getCustomer"
}

The method computes the rename, validates every plan file against the working tree, and returns PREVIEW_OK with a short-lived confirmToken. Preview never writes source and does not require the environment write gate.

2. Apply through the same method

Repeat the same operation inputs and add the confirmation:

{
  "symbol": "src/users.ts#getUser@12",
  "new_name": "getCustomer",
  "mode": "apply",
  "confirm_token": "<token from preview>"
}

The tool recomputes the deterministic plan, verifies that the token belongs to that plan and repository, takes the repository lock, rechecks hashes and before text, writes a rollback bundle, and applies every edit bottom-up.

The same contract applies to a coordinated set:

{
  "renames": [
    {"symbol": "src/api.ts#getUser@8", "new_name": "getCustomer"},
    {"symbol": "src/api.ts#getOrder@20", "new_name": "getPurchase"}
  ]
}

rename_related_symbols detects overlapping edits, chains, swaps, shadowing risk, and per-sub-rename failure before it issues a token. Apply is one atomic multi-file operation.

Refactoring tools

Complete write workflows

Proven plan producers

These plans are applied with apply_edit_plan, using the same preview, token, atomic-write, and rollback protocol as rename.

Structural review and safety tools

Language and proof matrix

Edit-plan proof envelope

Every applyable plan uses weavatrix.edit-plan.v1. Its load-bearing fields are:

• operation and graph revision;

• repository-relative target paths only;

• sha256 of every target file;

• exact 1-based line and UTF-16 character ranges;

• exact before and after text;

• per-edit provenance;

• uncertainReferences, notModified, warnings, and completeness.

The applier additionally protects against:

• absolute paths, traversal, .git casing/trailing-dot tricks, NTFS streams, and escaping symlinks/junctions;

• non-UTF-8 or oversized files;

• overlapping edits, stale ranges, lone surrogates, and edits that split surrogate pairs;

• two writers interleaving in the same repository;

• token reuse, expiry, repository mismatch, or plan mismatch;

• partial writes and incomplete rollback.

createdAt is provenance metadata and is the only field excluded from the confirmation fingerprint. This allows a rename method to recompute the same plan on its apply call; every executable field remains token-bound.

Result states agents can act on

Planner-specific states such as NOT_FOUND, NO_CHANGE, CONFLICT, BLOCKED, UNPROVEN, and NOT_SUPPORTED remain visible instead of being collapsed into a generic failure.

The three write gates

Repository source changes require all three:

1. weavatrix-refactor is installed and the refactor profile selects edit;

2. the server starts with WEAVATRIX_ALLOW_SOURCE_EDITS=1;

3. the apply call presents a valid, unexpired, single-use token bound to the exact plan and repository.

Preview and every read-only analysis remain available while the environment gate is closed.

End-to-end change proof

The package includes all 34 read-only core tools in the same MCP server. A strong refactor session can therefore stay in one evidence chain:

1. inspect_symbol, context_bundle, or get_dependents identifies the exact target;

2. rename_symbol, change_signature, move_symbol, or another refactor tool previews the change;

3. the write workflow applies atomically;

4. the next graph call auto-refreshes changed files and reverse importers;

5. verified_change compares callers, imports, and references against the merge base;

6. change_impact, verify_architecture, coverage_map, run_audit, and find_duplicates inspect the consequences.

Useful inherited surfaces include:

• architecture maps and navigation: module_map, query_graph, shortest_path, context_bundle;

• impact and proof: change_impact, get_dependents, prepare_change, verified_change;

• health: run_audit, find_dead_code, find_duplicates, coverage_map, hot_path_review;

• contracts: list_endpoints, trace_endpoint, trace_api_contract;

• target architecture: get_architecture_contract, verify_architecture, explain_architecture_violation;

• repository control: open_repo, rebuild_graph, graph_diff, list_known_repos.

See the weavatrix README for the complete core catalog.

Install

npx -y weavatrix-refactor <repoRoot>

Set WEAVATRIX_ALLOW_SOURCE_EDITS=1 only for sessions in which apply and rollback should be enabled.

Scope and honest limits

• Related multi-symbol rename is currently JS/TS-only.

• move_file cannot rename the file through apply_edit_plan; it is a review plan because file relocation has different filesystem semantics.

• move_symbol is a topology/architecture dry-run, not byte-edit synthesis.

• Graph+lexical language backends cannot prove reference completeness and stay PARTIAL even when every known reference was located.

• delete_readiness never auto-deletes, and public/exported APIs cannot receive an automatic clean verdict.

• Tests, typechecking, runtime checks, and human review remain the release authority. Weavatrix supplies bounded evidence; it does not fabricate proof.

Package boundary

The refactor package extends core only through weavatrix/extension-api and weavatrix/analysis-kit; it does not copy or relicense the core.

License

Apache-2.0. The explicit patent grant and warranty/liability terms are a deliberate fit for a package whose purpose is writing code.