weavatrix-refactor-js

Weavatrix Refactor JS

属于 Weavatrix 生态系统的一部分。本仓库保留了独立的 JavaScript 重构版本线。

这是 Weavatrix 的 JavaScript 重构引擎，现以 weavatrix-refactor-js 的名称持续开发。 weavatrix-refactor 包提供基于 weavatrix-rust 构建的原生 Rust MCP 主机，以及 weavatrix-edit / weavatrix-refactor-plan / weavatrix-worktree crate。 本包延续原有版本线：[email protected] 是旧名称下的最后一个 JavaScript 版本，[email protected] 从此版本接续。安装 weavatrix-refactor-js，或固定使用 [email protected]，即可继续使用 JavaScript 实现。

为编码 Agent 提供有证据支持的事务式重构。

weavatrix-refactor-js 是 JavaScript 系列中具备写入能力的成员。它整合了完整的只读 weavatrix-js 代码智能 MCP，以及 11 个重构工具；这些工具可以验证变更、根据当前 工作树预览变更、原子化应用变更、刷新图谱，并回滚变更。

**引擎边界：**本包承载 weavatrix-js 引擎。它不 使用原生 weavatrix-rust 引擎，安装这两个包也不会 悄然升级本包的分析层。本包的状态保存在 ~/.weavatrix-refactor-js 中，与 Rust 主机的状态相互隔离，因此两者 不会共享锁、令牌存储或回滚日志。

它远不只是一个改名包装器：

• 通过捆绑的语言服务器进行 JS/TS 语义重命名；
• 依据带有架构信息的证据重命名 SQL 表和字段；
• 对 Python、Rust、Go、Java、C# 和 Solidity 进行严格的图谱加词法重命名；
• 将多个相关的 JS/TS 重命名合并为一个原子事务；
• 提供签名、符号主体、导入、批量替换、移动和删除安全工作流；
• 每个可应用的计划都包含精确到字节的文件哈希、before 文本、来源信息、不确定性和图谱版本；
• 过期工作树检测、仓库锁定、回滚包，以及写入中途失败后的自动回滚；
• 结构性移动前进行架构和循环投影；
• 继承自核心的变更后影响范围分析和验证工具。

为什么这是一个独立的包

MIT 许可的 weavatrix-js 核心在物理层面上是只读的：其发布产物没有 向仓库源代码写入的路径。本包是明确的写入边界。安装本包并选择其 refactor 配置后，edit 能力才会启用；没有本包，服务就无法修改源代码。

这种拆分是一项安全属性，而非包装上的装饰：

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

架构

此实现采用端口与适配器模式，并设有单向边界：

edit-plan model  <-  filesystem / lock / token adapters
       ^                         ^
       |                         |
plan engines     ->  preview / apply / rollback workflows  ->  MCP adapter

• 模型验证冻结的 weavatrix.edit-plan.v1 信封，并通过纯字符串转换应用字节级精确编辑。
• 平台适配器负责真实路径 containment、原子替换、仓库锁、单次使用令牌和持久化回滚包。
• 计划引擎计算重命名、签名、符号、导入、移动、删除和批量替换的证据，但不负责写入工作流。
• 应用工作流将预览绑定到当前仓库，签发和使用确认令牌，在锁定状态下应用更改，并在失败时还原。
• MCP 适配器将 11 个重构工具与只读的 weavatrix-js 目录组合起来，并提供一个 stdio 服务。

仓库中已纳入严格的架构契约，确保运行时循环依赖数为零、文件不超过 300 行、函数不超过 100 行。该契约没有例外或棘轮基准。

重构工作流有何不同

普通编辑器重命名会回答：“现在应该进行哪些文本编辑？” Weavatrix Refactor 还会回答：

问题	返回的证据
这是确切的符号吗？	稳定的图符号 ID，以及解析器/LSP 选择范围
哪些引用已得到证实？	每项编辑的来源：EXACT_LSP、RESOLVED、EXTRACTED 或 LEXICAL_EXACT
哪些内容尚未得到证实？	明确列出 uncertainReferences、notModified、警告和 PARTIAL 完整性状态
实际检查了哪些文件？	重命名会话会纳入图中声明的所有引用，以及文本中包含该标识符的所有索引文件；无法打开的文件会被明确列出，并导致完整性状态变为 PARTIAL
预览后代码树是否发生了变化？	在写入锁定状态下重新检查文件 sha256 和精确的 before 文本
多个重命名能否部分成功？	不能。相关重命名会经过冲突检查，并作为一个事务一并应用
磁盘/写入失败后会怎样？	已写入的文件会被还原；持久化回滚包会保留
移动操作会让架构变差吗？	预计的运行时循环依赖、边界违规、改进项和影响范围
重构是否保留了体现行为的结构？	刷新后的图，以及 verified_change 调用方/导入/引用守恒情况

证据不足时，系统会采取失败关闭策略。它绝不会将 INFERRED 边升级为可应用的编辑，也绝不会隐藏含糊不清的引用。

完整的重命名工作流

rename_symbol 和 rename_related_symbols 是完整操作，而非仅能生成 PLANNED 状态的辅助工具。每个方法都负责两个阶段。

1. 预览

正常调用重命名方法：

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

该方法会计算重命名、根据工作树验证每个计划文件，并返回带有短时有效 confirmToken 的 PREVIEW_OK。预览不会写入源代码，也不需要启用环境写入门控。

2. 通过同一方法应用

使用相同的操作输入再次调用，并添加确认信息：

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

该工具会重新计算确定性计划，验证令牌是否属于该计划和仓库，获取仓库锁，重新检查哈希和 before 文本，写入回滚包，然后自底向上应用每项编辑。

协调后的操作集合也适用相同契约：

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

rename_related_symbols 会在签发令牌前检测重叠编辑、链式修改、交换、遮蔽风险和每项子重命名的失败情况。应用时会将多个文件作为一个原子操作处理。

重构工具

完整写入工作流

工具	实际功能
rename_symbol	跨语言预览、确认并应用重命名。根据需要分派到精准的 JS/TS LSP、SQL 架构或严格的图谱加词法后端；如实返回后端完整性及每个未覆盖的引用。
rename_related_symbols	在一个共享的语言服务器会话和一个原子编辑计划中，协调最多 50 个 JS/TS 符号重命名。在写入前检测冲突、链式重命名、互换、快照漂移，以及任何失败的子重命名。
apply_edit_plan	用于执行其他工具或 weavatrix-online 生成的 weavatrix.edit-plan.v1 信封的通用两阶段执行器。预览会生成绑定到计划的令牌；应用时会原子写入，并在失败时回滚。
rollback_last_apply	恢复最近一次应用前的文件包。如果应用后的文件发生漂移，则拒绝执行；若恢复未完成，可重试直至收敛。

经验证的计划生成器

工具	实际功能
change_signature	添加或移除 JS/TS 函数或方法参数。执行字节级精确的声明和调用参数修改；对于展开调用和必须提供值的新增参数，仍会明确标记为不确定。
edit_symbol	使用索引解析器范围执行 replace_symbol_body、insert_before_symbol 或 insert_after_symbol。JS/TS 输出须通过解析检查；保留行尾格式和 UTF-16 坐标。
bulk_replace	对索引文件执行两阶段、按出现位置选择的替换。首次调用返回稳定的出现位置 ID；第二次调用接受选定 ID 或精确的预期数量，并生成绑定到哈希的计划。默认使用字面量模式；正则替换会真实展开捕获组。
organize_imports	仅移除可明确证明未使用的具名 JS/TS 导入。默认导入和命名空间导入仍标记为不确定；不触及副作用导入；有意将排序留给格式化工具处理。

这些计划使用 apply_edit_plan 应用，遵循与重命名相同的预览、令牌、原子写入和回滚协议。

结构审查与安全工具

工具	实际功能
move_file	构建 JS/TS 文件迁移审查：重写导入方的模块说明符和被移动文件自身的相对导入，然后评估架构影响。文件重命名仍须由编辑器或 Agent 明确执行，因此这不会生成可应用的信封。
move_symbol	评估声明移动，不凭空创建字节编辑。报告新增或移除的运行时循环、目标文件依赖、架构违规或改进，以及影响范围。
delete_readiness	返回 safe: true、false 或 UNPROVEN，并提供已知引用、动态调用或反射风险、置信度及声明范围。导出符号的结果最高为 UNPROVEN；绝不自动删除。

语言与证明矩阵

支持范围	后端	可应用的溯源类型	完整性约定
JavaScript / TypeScript 重命名	捆绑的 TypeScript 语言服务器	EXACT_LSP	只有在重命名会话中打开了所有可能提及该符号的文件并完成验证时，才会标记为 COMPLETE；任何未纳入的候选项都会导致标记为 PARTIAL
SQL 表重命名	跨 SQL 文件和宿主文件的架构感知型 SQL 扫描器	EXTRACTED / LEXICAL_EXACT	报告所有跳过或有歧义的引用
SQL 字段重命名	定义安全型 SQL 后端	仅限经证明的定义编辑	用法标记为 UNPROVEN，而非猜测结果
Python / Rust / Go / Java / C# / Solidity 重命名	索引图谱引用，加上记录行中的精确词法位置	EXTRACTED / LEXICAL_EXACT	始终标记为 PARTIAL；绝不编辑有歧义的行
JS/TS 签名和导入	解析器加图谱调用/引用证据	EXTRACTED / RESOLVED	当图谱遍历无法证明不存在相关项时，明确标记为不完整
符号锚定编辑	所有已索引语言的索引解析器范围	EXTRACTED	JS/TS 须通过解析检查；其他语言仍受解析器范围证据边界约束

编辑计划证明信封

每个可应用计划都使用 weavatrix.edit-plan.v1。其关键字段包括：

• 操作和图修订版本；
• 仅限相对于仓库的目标路径；
• 每个目标文件的 sha256；
• 精确的 1 基行号和 UTF-16 字符范围；
• 精确的 before 和 after 文本；
• 每项编辑的来源信息；
• uncertainReferences、notModified、警告和完整性。

应用器还会防范：

• 绝对路径、路径遍历、.git 大小写或尾随点伎俩、NTFS 数据流，以及逃逸的符号链接／联接点；
• 非 UTF-8 或过大的文件；
• 编辑重叠、过时的范围、孤立代理项，以及拆分代理对的编辑；
• 同一仓库中的两个写入者交错操作；
• 令牌重用、过期、仓库不匹配或计划不匹配；
• 部分写入和不完整回滚。

createdAt 是来源元数据，也是确认指纹中唯一排除的字段。这使重命名方法能够在应用调用时重新计算出相同的计划；所有可执行字段仍受令牌绑定。

Agent 可据此采取行动的结果状态

状态	含义
PREVIEW_OK	每个哈希和 before 文本均匹配；已签发一次性令牌。
PREVIEW_BLOCKED	生成的计划与当前工作树不匹配；无法应用任何内容。
WRITE_GATE_CLOSED	服务启动时未明确启用源代码编辑。
APPLIED	已写入所有计划的编辑，并且回滚包可用。
STALE	工作树在预览与加锁应用检查之间发生变化；未写入任何内容。
TOKEN_UNKNOWN / TOKEN_EXPIRED / TOKEN_*_MISMATCH	确认信息缺失、已使用、已过期，或属于其他计划／仓库。
REPO_BUSY	另一个应用或回滚操作当前持有仓库锁。
ROLLED_BACK	失败的应用或显式回滚已恢复原始文件。
ROLLBACK_INCOMPLETE	指定文件的恢复受阻；持久化包仍可重试。
INVALID_PLAN	写入前的架构、路径、范围、编码、重叠或来源验证失败。
INVALID_ARGS	缺少必需参数或参数类型错误；会列出有问题的名称。未规划任何内容。

规划器特有的状态，例如 NOT_FOUND、NO_CHANGE、CONFLICT、BLOCKED、UNPROVEN 和 NOT_SUPPORTED，仍会显示，不会被合并为通用失败。

三道写入门槛

修改仓库源代码必须满足以下全部条件：

1. 已安装 weavatrix-refactor-js，且 refactor 配置选择了 edit；
2. 服务启动时设置了 WEAVATRIX_ALLOW_SOURCE_EDITS=1；
3. 应用调用提供了有效、未过期、一次性且绑定到确切计划和仓库的令牌。

环境门槛关闭时，预览和所有只读分析仍可用。

端到端变更证明

此软件包在同一个 MCP 服务中包含全部 34 个只读核心工具。 因此，强有力的重构会话可以始终沿用同一条证据链：

1. inspect_symbol、context_bundle 或 get_dependents 确定精确目标；
2. rename_symbol、change_signature、move_symbol 或其他重构工具预览变更；
3. 写入工作流以原子方式应用变更；
4. 下次调用图工具时，自动刷新已变更的文件和反向导入方；
5. verified_change 将调用方、导入和引用与合并基准进行比较；
6. change_impact、verify_architecture、coverage_map、run_audit 和 find_duplicates 检查影响。

可用的继承功能包括：

• 架构图和导航：module_map、query_graph、shortest_path、context_bundle；
• 影响和证明：change_impact、get_dependents、prepare_change、verified_change；
• 健康状况：run_audit、find_dead_code、find_duplicates、coverage_map、hot_path_review；
• 契约：list_endpoints、trace_endpoint、trace_api_contract；
• 目标架构：get_architecture_contract、verify_architecture、explain_architecture_violation；
• 仓库控制：open_repo、rebuild_graph、graph_diff、list_known_repos。

完整的 JavaScript 宿主目录，请参阅 weavatrix-js README。

运行

为一个仓库启动合并后的只读和重构 MCP 服务：

npx -y weavatrix-refactor-js <repoRoot>

对于 MCP 客户端，最简配置如下：

{
  "mcpServers": {
    "weavatrix": {
      "command": "npx",
      "args": ["-y", "weavatrix-refactor-js", "/absolute/path/to/repository"]
    }
  }
}

在 Windows 上，如果客户端无法解析命令 shim，请使用 npx.cmd。 如果没有环境变量覆盖，所有分析和预览工具都能正常工作，但源代码写入会默认拒绝。仅在有意授权应用和回滚操作的会话中，添加 "env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"}。

已托管 weavatrix-js 的应用可以组合使用相同的扩展：

import {startMcpServer} from 'weavatrix-js/mcp-runtime'
import {refactorExtension} from 'weavatrix-refactor-js/extension'

await startMcpServer({
  defaultCapabilities: 'refactor',
  loadExtensions: async () => [refactorExtension()],
})

导出的扩展会注册工具和 refactor 能力配置；它不会在未提示的情况下开启写入权限。

范围和限制说明

• 目前，涉及多个相关符号的重命名仅支持 JS/TS。
• move_file 无法通过 apply_edit_plan 重命名文件；它是一个审查计划，因为文件移动具有不同的文件系统语义。
• move_symbol 是拓扑／架构演练，不会合成字节级编辑。
• 基于图和词法分析的语言后端无法证明引用完整性；即使已找到所有已知引用，状态仍为 PARTIAL。
• delete_readiness 从不自动删除；公共／导出的 API 也无法获得自动的干净判定。
• 测试、类型检查、运行时检查和人工审查仍是发布决策依据。Weavatrix 提供有界证据，不会捏造证明。

软件包边界

软件包	许可证	职责
weavatrix-js	MIT	只读 JavaScript 图、分析、证据、架构和验证
weavatrix-refactor-js	MIT	有依据的重构计划、事务性写入和回滚
weavatrix-online	MIT	明确的公共网络连接器以及远程计划／证据工作流

重构软件包仅通过 weavatrix-js/extension-api 和 weavatrix-js/analysis-kit 扩展旧版 JavaScript 核心；它不会复制该核心，也不会为其重新授权。规范的 weavatrix 软件包是原生 Rust 引擎，并非此 JavaScript 扩展宿主。

许可证

MIT。