基于证据的消费者文件修改系统规范¶
意图¶
人们会在自己拥有的项目上运行诸如 astryx upgrade --apply 之类的 Astryx 命令。这些命令会就地编辑现有文件。消费者必须能够信任:每次编辑都针对 Astryx 可以证明其有权更改的内容;生成、vendor 和依赖内容会被重新生成而不是被编辑;Astryx 无法更改的内容会被报告而不会被隐藏。
本记录规定一项操作可以修改现有消费者文件中的哪些内容、什么算作证据,以及跳过或被阻止的更改如何报告。它适用于消费者项目中每个修改或替换现有文件的操作,包括核心、集成和配置 codemods。对于 astryx upgrade,它还规定该操作作用于哪个项目、迁移到哪个已安装的 Core、其结果如何命名文件,以及如何报告因 CLI 过旧而无法完成迁移的情况。
非目标¶
- 创建新文件,例如模板副本或脚手架。其写入约束仍由
architecture:cli-surface负责,模板复制行为仍由spec:AST-028负责。 - 定义具体迁移或其映射。Release compatibility and versioning spec 规定何时弃用、计划清理或不兼容修复需要迁移证据;本记录规定消费者文件转换如何安全地编辑。
- 选择用于检查有效设置的命令;
spec:AST-017FR20 要求有这样的命令。 - 其他命令在哪里查找项目,包括
init写入 agent 文档的位置。FR9–FR13 仅约束astryx upgrade。 - 满足本契约的等效内部实现仍然有效。
要求¶
- FR1 — 每次编辑都需要明确证据。 操作 MUST 仅在文件不受保护(FR2–FR4)且被编辑的构造被证明在范围内时修改现有消费者内容。对于源代码转换,证据是到被迁移导出的解析绑定:命名、别名、默认或命名空间导入,或再导出,且该绑定在编辑位置未被遮蔽。仅类型导入只能证明类型位置,绝不允许编辑运行时值。仅靠匹配的名称、字符串或形状不构成证据,文件级导入也不授权编辑文件中的其他位置。当证据缺失时,内容 MUST 保持不变,候选 MUST 按 FR7 报告。
- FR2 — 生成、vendor 和依赖内容受保护。 操作 MUST NOT 修改以下文件:位于已安装依赖或版本控制元数据内部、位于操作根目录之外、通过符号链接访问、被 FR3 认可的约定标记为 generated 或 vendored、或被项目忽略规则排除的文件。仅凭文件或目录名既不保护也不解除保护文件。
-
FR3 — 认可的约定从检出中读取。 CLI MUST 不运行版本控制程序,而从工作树中存在的文件识别以下声明:
.gitattributes文件中的linguist-generated和linguist-vendored,包括嵌套文件;- 文件前导注释块中的生成标记:
@generated、@partially-generated,或匹配标准Code generated … DO NOT EDIT.形式的行。位于已编写代码之后的标记不保护该文件,@partially-generated保护整个文件; .gitignore文件和.hgignore中的排除项。
每种约定使用其自身的标准语义,包括后出现规则优先、显式 unset 或 false 属性值,以及忽略规则取反。针对该文件的最终结果决定是否受保护;Astryx 配置和集成贡献只能为其增加保护(FR4)。结果 MUST 在 Git、Sapling 和 Mercurial 检出中以及在无版本控制的目录中保持一致。被认可的集合是公开的,且可通过
spec:AST-017FR14 发现。当跨生态系统的约定确立时,通过修订来扩展。 -
FR4 — 保护是叠加的,并且失败时保持关闭(fails closed)。 项目配置和集成贡献 MAY 在
spec:AST-017FR19 和 FR20 下增加保护。保护设置需要 FR3 约定遗漏的可复现案例。任何配置或贡献都不能移除由 FR2、FR3 或其他来源确立的保护。当保护来源无法读取或解析时,操作 MUST 在任何写入之前失败,并使用指明该来源的稳定错误。 - FR5 — 生成的输出应重新生成,而不是编辑。 当必要更改会改动受保护的生成文件时,操作 MUST 保持该文件不变,完成对自有源代码的范围内编辑,然后运行项目声明的重新生成。CLI MUST 自行重新生成其自身生成器的输出,或报告执行该操作的确切命令。重新生成后,它 MUST 重新评估受保护的文件。
- FR6 — 被阻止的必要更改是不完整的结果。 如果受保护文件在 FR5 之后仍需要更改,操作 MUST 以非零状态退出,使用稳定的错误码,并列出每个此类文件及其保护声明。对自有文件已完成的编辑会保留。不需要更改的受保护文件永远不会阻止操作。在项目重新生成后再次运行相同操作 MUST NOT 重复应用已完成的编辑。试运行 MUST 在不写入的情况下报告相同的分类。
- FR7 — 每个跳过的候选都会被报告。 机器可读结果 MUST 列出已修改文件、需要更改的受保护文件(FR6),以及因缺乏证据而被拒绝的候选(FR1)及其位置和原因。人类可读输出 MUST 显示相同事实。被拒绝的候选会被报告为需要人工审查;它们本身不会导致操作失败。当必要更改被阻止时,结果 MUST NOT 看起来完整。
- FR8 — 每条修改路径都遵循本契约。 核心、集成和配置 codemods,以及任何其他修改现有消费者文件的操作,MUST 以相同方式应用 FR1–FR7。与
spec:AST-017FR16 一致,新的修改路径不能选择退出。受管理的 agent 文档块由architecture:cli-surfaceINV31 约束。 - FR9 — 升级作用于其所属项目的范围。
astryx upgradeMUST 作用于命令运行所在文件夹的项目:即该文件夹或其上方最近的、其package.json声明了 Astryx 包的文件夹;或者当工作区根目录的package.json声明了 Astryx 包时,被其工作区列为成员的文件夹。当package.json的任一依赖字段(包括 peer 依赖)命名了@astryxdesign/*包或旧的@xds/*包时,该package.json即声明了 Astryx 包。文件夹的工作区根目录是spec:AST-048FR15 从该文件夹找到的那个;当根目录package.json的workspaces字段或pnpm-workspace.yaml的packages中的模式匹配该文件夹,且没有排除模式将其移除时,工作区会列出该文件夹。一个安装了 Core 但两种方式都不符合条件的文件夹不是项目:在其中运行升级会作用于其上方的项目(如果有)。搜索 MUST NOT 越过持有版本控制元数据的文件夹,MUST 在 home 文件夹处结束,且不将 home 文件夹计为项目或工作区根目录。项目根目录即操作根目录(FR2):升级在那里读取项目的配置、agent 文档和保护来源(FR3、FR4)。当没有文件夹符合条件时,命令运行所在的文件夹即为操作根目录。 - FR10 — 指定的源文件夹从命令运行所在位置读取。 默认情况下,升级 MUST 扫描操作根目录的
src文件夹。调用者指定的源文件夹 MUST 从命令运行所在的文件夹解析,且 MUST 位于操作根目录内;位于其外部的源文件夹在任何写入之前以ERR_PATH_TRAVERSAL失败。 - FR11 — 工作区成员迁移到其工作区安装的 Core。 升级迁移到的版本 MUST 是项目安装的 Core(
@astryxdesign/core或旧的@xds/core)的版本:即项目根目录的node_modules中;对于其工作区列出的成员,位于从项目根目录向上到工作区根目录之间最近的node_modules;对于未安装node_modules的项目,则是其包管理器为其解析的副本。没有被任何工作区列出的项目,其上方的 Core MUST NOT 计入。当没有文件夹符合 FR9 的条件时,目标是命令运行所在文件夹的node_modules中的 Core。如果没有安装 Core,升级在任何写入之前以ERR_VERSION_DETECT失败。 - FR12 — 结果以命令运行所在位置为基准命名文件。 升级的机器可读结果 MUST 使用相对于命令运行所在文件夹的路径,来命名其已修改、受保护和被拒绝的文件(FR7)、其错误所指名的文件、其 agent 文档文件,以及其复制组合摘要中的文件,以便每一项都能从该处解析。当命令在操作根目录运行时,复制组合摘要改为相对于升级所扫描的源文件夹来命名其文件。当操作根目录是另一个文件夹时,人类可读输出 MUST 指明该文件夹。
- FR13 — 比已安装 Core 更旧的 CLI 会报告不完整的升级。 当已安装的
@astryxdesign/core比正在运行的 CLI 和升级所从开始的版本都更新时,升级 MUST 运行当前 CLI 针对该范围所拥有的 codemods,其人类可读输出 MUST 将升级报告为不完整,且 MUST NOT 声称代码是最新的。机器可读结果 MUST 携带可选的cliBehindCore字段,仅在此情况下存在,包含当前 CLI 的版本,以及一条使用与已安装 Core 匹配的 CLI 版本来完成升级的命令。该命令 MUST 在运行它的任何文件夹中都能工作,并升级同一项目;它 MUST 重复本次运行的选项,MUST 指明本次运行所扫描的源文件夹,并针对其目标 shell 引用每个参数。人类可读输出 MUST 在独立的一行中打印该命令,并且除非是 POSIX shell,否则 MUST 指明该 shell。此情况不改变退出状态,也不改变complete和errorCode在 FR6 下报告的内容。
平台支持¶
- 支持的功能/引擎下限:Linux、macOS 和 Windows 上所有受支持的 CLI 运行时;Git、Sapling 和 Mercurial 检出;没有版本控制的目录;以及 npm、pnpm、Yarn(包括 Plug'n'Play)和 Bun 的工作区和安装布局。
- 不支持的行为:仅存在于工作树之外的仓库元数据中的版本控制声明不会被读取;当复现案例需要时,项目会在 FR4 下添加保护。
- 浏览器证据:不适用。
当前状态影响¶
当前的 codemod 扫描器会跳过固定列表中的目录名,并且从不跟随符号链接。它们不读取生成的标记、属性或忽略文件,因此 codemod 可能会编辑生成的文件。某些转换将文件级导入视为编辑该文件中任意位置的匹配字面量的许可。这两种行为都不符合 FR1–FR3;本记录不选择它们的实现方式。
post-codemod 钩子已存在,并作为 FR5 的声明式再生成机制。authoring 指南和 codemod 作者指南必须解释保护机制、如何标记生成文件,以及转换如何证明作用范围。
这一仅涉及规范说明的变更不会改变任何运行时行为或已发布包,也不需要 Changeset。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1 | 转换夹具 | 命名、别名、默认、命名空间、再导出、在类型位置和值位置的仅类型、遮蔽、错误包、无关字面量 | 同名的本地变量或无关字面量发生变化,或已验证的用法未被编辑 |
| FR2–FR4 | 每种检出类型中的保护夹具 | 嵌套属性、未设置或为 false 的属性、取反的忽略规则、代码后的标记、部分标记、被忽略的路径、符号链接、配置与集成添加、尝试移除、错误源 | 受保护的文件发生变化、结果因版本控制而异,或错误源允许写入 |
| FR5–FR6 | 使用生成文件和再生成钩子进行升级运行 | 钩子成功、钩子失败、试运行、第二次运行 | 受保护的字节发生变化、有阻塞变更时退出码为零,或第二次运行编辑两次 |
| FR7 | JSON 和文本中的结果快照 | 已修改、已阻塞、已拒绝 | 被阻塞或被拒绝的候选者从任一输出中缺失 |
| FR8 | 所有修改现有文件的操作清单 | 核心、集成、配置 codemod、新路径 | 某个路径绕过了 FR1–FR7 |
| FR9 | 从项目内部和周边文件夹运行的升级 | 子文件夹;一个已列出和未列出的工作区成员;一个 package.json 未声明任何 Astryx 包的文件夹;位于安装了 Astryx 的主文件夹内且没有 package.json 的文件夹;嵌套检出;没有符合条件的文件夹 |
升级操作作用于另一个项目、主文件夹,或超出版本控制元数据范围的文件夹 |
| FR10 | 使用指定源文件夹运行的升级 | 来自子文件夹的默认值;以每种拼写方式从子文件夹命名的一个文件夹;操作根目录之外的文件夹 | 从命令运行目录之外的另一个文件夹读取指定文件夹,或一个位于操作根目录之外的文件夹被扫描 |
| FR11 | 升级目标检测 | 一个其工作区强制使用 Core 的成员,或一个声明了另一个范围或仅声明 peer 范围的成员;位于已安装 Core 下方但未列出的项目;父文件夹中的 Core;没有 node_modules 的安装;没有符合条件的文件夹 |
某个成员缺少其工作区所安装的 Core,或者未列出项目上方的 Core 被计入 |
| FR12 | 从子文件夹和根目录生成的结果快照 | modified、protected、declined、error、agent-doc 和 copied-composition 路径 | 一条无法从命令运行所在文件夹解析的路径,或一次根目录运行中 copied-composition 路径发生变化 |
| FR13 | 使用早于已安装 Core 的 CLI 运行升级 | 没有剩余的 codemods;仅覆盖部分范围;每个选项;打印的命令在项目内、项目上级目录以及无关文件夹中运行;每个目标 shell 中的文件夹名称包含 shell 元字符 | 一份最新或完整的报告、被丢弃的选项、在其他位置遗漏项目的命令,或未命名的非 POSIX shell |
决策日志¶
DEC-1 — 仅凭确证证据进行编辑¶
参考: spec:AST-040/DEC-1
决策者: josephfarina,2026-09-23
升级会在未经逐项审查的情况下重写用户的源代码,因此每次编辑都需要证据。已解析的绑定表明该构造正是被迁移的导出项。不确定的候选对象会被保留并报告。
已拒绝:按名称、字符串或形状匹配,以及将文件级导入视为对整个文件的许可。这两种方式都会静默重写无关代码。
DEC-2 — 采用既有的、与 VCS 无关的约定¶
参考: spec:AST-040/DEC-2
决策者: josephfarina,2026-09-23
项目已经通过属性、文件头和忽略文件来标记生成内容和 vendored 内容。从工作树读取这些内容在任何检出中都能得到相同的答案,且无需新增注解。
已拒绝:仅限 Astryx 的标记、以跳过标志作为主要机制、运行版本控制程序、文件名约定,以及没有可复现差距的配置。
DEC-3 — 重新生成,然后报告剩余内容¶
参考: spec:AST-040/DEC-3
决策者: josephfarina,2026-09-23
生成文件跟随其源文件,因此操作会编辑源文件、运行声明的重新生成流程,然后再次检查。任何仍被阻塞的内容都会使结果不完整,并逐个指明文件。
已拒绝:编辑生成输出、静默跳过生成文件,以及在编辑前停止,因为重新生成需要先有源文件的编辑。
未决问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx