peaks-loop 4.1.18 → 4.1.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +126 -0
- package/README-en.md +6 -0
- package/README.md +5 -0
- package/contracts/test-style-contract.md +14 -5
- package/dist/cli/commands/audit-red-lines-runners.js +6 -1
- package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
- package/dist/cli/commands/best-practice-scan-collision.js +115 -0
- package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
- package/dist/cli/commands/best-practice-scan-command.js +9 -18
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
- package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
- package/dist/cli/commands/code-auto-compact-command.js +26 -18
- package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
- package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
- package/dist/cli/commands/core/skill-presence-commands.js +42 -74
- package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
- package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
- package/dist/cli/commands/core/standards-init-command.js +44 -8
- package/dist/cli/commands/core/standards-migrate-command.js +5 -4
- package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
- package/dist/cli/commands/dispatch-dag-runners.js +11 -1
- package/dist/cli/commands/dispatch-detached-branch.js +19 -1
- package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
- package/dist/cli/commands/mut-commands-helpers.js +197 -4
- package/dist/cli/commands/mut-commands.d.ts +9 -1
- package/dist/cli/commands/mut-commands.js +82 -154
- package/dist/cli/commands/preferences-commands.js +27 -2
- package/dist/cli/commands/scan-scope-helpers.js +2 -2
- package/dist/services/24h-mode/auto-engage.d.ts +11 -3
- package/dist/services/24h-mode/auto-engage.js +14 -6
- package/dist/services/artifacts/artifact-templates.js +10 -0
- package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
- package/dist/services/artifacts/backcompat-acceptance.js +8 -7
- package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
- package/dist/services/artifacts/rd-transition-gates.js +96 -19
- package/dist/services/artifacts/request-artifact-service.js +6 -6
- package/dist/services/audit/enforcers/lint-output-style.js +14 -2
- package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
- package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
- package/dist/services/audit/static-service.js +4 -4
- package/dist/services/code/auto-compact-history.d.ts +6 -1
- package/dist/services/code/auto-compact-history.js +6 -1
- package/dist/services/code/auto-compact-modes.d.ts +60 -14
- package/dist/services/code/auto-compact-modes.js +75 -20
- package/dist/services/code/auto-compact-profile.d.ts +23 -0
- package/dist/services/code/auto-compact-profile.js +51 -0
- package/dist/services/compact-history/compact-history-service.d.ts +6 -1
- package/dist/services/compact-history/compact-history-service.js +5 -1
- package/dist/services/context/auto-compact-types.d.ts +7 -5
- package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
- package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
- package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
- package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
- package/dist/services/hooks/hook-payload-cwd.js +11 -4
- package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
- package/dist/services/hooks/presence-marker-detector.js +21 -19
- package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
- package/dist/services/ide/adapters/codex-adapter.js +23 -7
- package/dist/services/ide/adapters/cursor-adapter.js +23 -7
- package/dist/services/mode/mode-status-service.d.ts +26 -27
- package/dist/services/mode/mode-status-service.js +36 -60
- package/dist/services/preferences/preferences-types.d.ts +30 -0
- package/dist/services/preferences/preferences-types.js +13 -0
- package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
- package/dist/services/scan/acceptance-coverage-service.js +157 -52
- package/dist/services/scan/rid-change-claims.d.ts +15 -0
- package/dist/services/scan/rid-change-claims.js +116 -0
- package/dist/services/skills/presence-caller-id.d.ts +51 -0
- package/dist/services/skills/presence-caller-id.js +43 -0
- package/dist/services/skills/presence-gate.d.ts +65 -0
- package/dist/services/skills/presence-gate.js +113 -0
- package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
- package/dist/services/skills/presence-lease-resolver.js +114 -0
- package/dist/services/skills/presence-lease-selection.d.ts +91 -0
- package/dist/services/skills/presence-lease-selection.js +135 -0
- package/dist/services/skills/presence-lease-service.d.ts +3 -11
- package/dist/services/skills/presence-lease-service.js +34 -87
- package/dist/services/skills/presence-lease-store.d.ts +33 -0
- package/dist/services/skills/presence-lease-store.js +94 -0
- package/dist/services/skills/presence-lease-types.d.ts +31 -0
- package/dist/services/skills/presence-lease-types.js +27 -0
- package/dist/services/skills/presence-role.d.ts +35 -0
- package/dist/services/skills/presence-role.js +72 -0
- package/dist/services/skills/skill-presence-service.d.ts +39 -9
- package/dist/services/skills/skill-presence-service.js +143 -174
- package/dist/services/skills/skill-presence-write.d.ts +60 -0
- package/dist/services/skills/skill-presence-write.js +74 -0
- package/dist/services/skills/skill-statusline-service.js +7 -7
- package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
- package/dist/services/standards/ide-aware-standards-service.js +45 -20
- package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
- package/dist/services/standards/migrate-claude-rules-service.js +18 -0
- package/dist/services/standards/migrate-service.d.ts +1 -1
- package/dist/services/standards/migrate-service.js +27 -7
- package/dist/services/standards/project-scripts.d.ts +25 -0
- package/dist/services/standards/project-scripts.js +116 -0
- package/dist/services/standards/project-standards-service.d.ts +23 -15
- package/dist/services/standards/project-standards-service.js +176 -243
- package/dist/services/standards/standards-constitution.d.ts +89 -0
- package/dist/services/standards/standards-constitution.js +199 -0
- package/dist/services/standards/standards-files.d.ts +37 -0
- package/dist/services/standards/standards-files.js +138 -0
- package/dist/services/standards/standards-pointer.d.ts +73 -0
- package/dist/services/standards/standards-pointer.js +98 -0
- package/dist/services/standards/standards-render-agents.d.ts +34 -0
- package/dist/services/standards/standards-render-agents.js +149 -0
- package/dist/services/standards/standards-render-common.d.ts +38 -1
- package/dist/services/standards/standards-render-common.js +44 -7
- package/dist/services/standards/standards-render.d.ts +1 -3
- package/dist/services/standards/standards-render.js +6 -87
- package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
- package/dist/services/workflow/workflow-graph-ensure.js +97 -0
- package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
- package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
- package/dist/services/workspace/generated-artifacts-content.js +167 -0
- package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
- package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
- package/dist/services/workspace/runtime-layout.d.ts +64 -0
- package/dist/services/workspace/runtime-layout.js +62 -0
- package/output-styles/peaks-skill-swarm.md +18 -2
- package/package.json +8 -9
- package/schemas/doctor-report.schema.json +1 -1
- package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
- package/skills/bee/peaks-prd/SKILL.md +5 -3
- package/skills/bee/peaks-qa/SKILL.md +4 -2
- package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
- package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
- package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
- package/skills/bee/peaks-rd/SKILL.md +4 -2
- package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
- package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
- package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
- package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
- package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
- package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +3 -1
- package/skills/bee/peaks-sc/SKILL.md +4 -2
- package/skills/bee/peaks-security-audit/SKILL.md +3 -1
- package/skills/bee/peaks-txt/SKILL.md +5 -3
- package/skills/bee/peaks-ui/SKILL.md +6 -4
- package/skills/peaks-audit/SKILL.md +3 -1
- package/skills/peaks-code/SKILL.md +3 -1
- package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
- package/skills/peaks-code/references/completion-handoff.md +1 -1
- package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
- package/skills/peaks-code/references/micro-cycle.md +2 -2
- package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
- package/skills/peaks-code/references/runbook.md +4 -4
- package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
- package/skills/peaks-code/references/standards-preflight.md +7 -6
- package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
- package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
- package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
- package/skills/peaks-content/SKILL.md +3 -1
- package/skills/peaks-doctor/SKILL.md +3 -1
- package/skills/peaks-final-review/SKILL.md +3 -1
- package/skills/peaks-ide/SKILL.md +3 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
- package/skills/peaks-race-code/SKILL.md +3 -1
- package/skills/peaks-resume/SKILL.md +3 -1
- package/skills/peaks-slice-decompose/SKILL.md +3 -1
- package/skills/peaks-solo/SKILL.md +3 -1
- package/skills/peaks-sop/SKILL.md +4 -2
- package/skills/peaks-status/SKILL.md +3 -1
- package/skills/peaks-test/SKILL.md +3 -1
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
3
|
"pluginRoot": ".",
|
|
4
|
-
"version": "4.1.
|
|
4
|
+
"version": "4.1.19"
|
|
5
5
|
},
|
|
6
6
|
"plugins": [
|
|
7
7
|
{
|
|
8
8
|
"name": "peaks-loop",
|
|
9
9
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
10
|
-
"version": "4.1.
|
|
10
|
+
"version": "4.1.19",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,131 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.19 — 2026-10-24(`peaks mut` 在真实用户机器上**真的能跑**)
|
|
4
|
+
|
|
5
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
|
|
6
|
+
没有改 fail-open 策略、没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;
|
|
7
|
+
改的是 `peaks mut` 这一条线上的**依赖位置、作用域与文档**(§1–§5),以及**版本号本身**(§6)。
|
|
8
|
+
|
|
9
|
+
这一批做的是**同一件事**:让 `peaks mut` 从"消费者装上就崩"走到"消费者装上就能跑"。
|
|
10
|
+
|
|
11
|
+
崩的原因**不是代码写错了**,是**依赖放错了地方**:变异测试引擎只挂在根包的 `devDependencies` 上,
|
|
12
|
+
而真正 import 它的是 `peaks-loop-mut` —— 一个**要被发布出去**的包。消费者装到的是 registry 上的
|
|
13
|
+
`peaks-loop-mut@0.1.72`,它的 dependencies 只有 `{zod, ecc-universal}`,**不带 stryker**,
|
|
14
|
+
于是 `Cannot find package '@stryker-mutator/core'`。
|
|
15
|
+
|
|
16
|
+
这一批把它修好,并且补上三件一直缺的东西:**项目作用域正确**(改谁就只改谁)、
|
|
17
|
+
**文档说真话**(文档里每句话都对得上代码)、**过期接受退休**(一条理由已经不成立的"豁免"从名单里划掉)。
|
|
18
|
+
|
|
19
|
+
**消费者要多付一点下载体积:约 2.66 MB。** 这件事写在 §1,不藏着。
|
|
20
|
+
|
|
21
|
+
### 1. 变异引擎落到生产依赖(以及它到底值不值这 2.66 MB)
|
|
22
|
+
|
|
23
|
+
- 现在 `@stryker-mutator/core`(Stryker 的变异引擎)与 `@stryker-mutator/vitest-runner` 是
|
|
24
|
+
`peaks-loop-mut` 的**生产依赖**(`dependencies`,不是 `devDependencies`),两者同为 **9.6.1**。
|
|
25
|
+
- **消费者视角 —— `@stryker-mutator/vitest-runner` 是干什么的**:它是把 Stryker 的变异引擎接到
|
|
26
|
+
vitest 上的**适配器**。没有它,Stryker 只能退回"跑一条命令看退出码"的粗粒度跑手,
|
|
27
|
+
**算不出逐 mutant 的 kill rate** —— 而 `peaks mut` 卖的**正是这个数字**。所以它不是可选项。
|
|
28
|
+
- **代价**:安装会多出 stryker 引擎闭包 **9 个包 / 约 2.66 MB**。
|
|
29
|
+
- **vitest 那部分不会自动来**:vitest-runner 声明的 peer 是 `vitest >=2.0.0`,而 pnpm 的 peer 自动安装
|
|
30
|
+
**只在 peer 缺失时**发生。vitest / vite 家族共 **11 个包 / 约 5.30 MB**,**只有在你的机器上
|
|
31
|
+
还没有 vitest 时**才会被自动装上 —— 而要跑 `peaks mut` 的项目**必然已经有 vitest**。
|
|
32
|
+
- 说人话:**你装 peaks-loop 多下载了约 2.7 MB**。参照:`peaks-loop-mut` 现有的生产依赖树是
|
|
33
|
+
**344 个包 / 156.6 MB**(大头是 `sql.js` 23.0 MB、`typescript` 22.5 MB、`ecc-universal` 18.6 MB,
|
|
34
|
+
**与本次改动无关**),2.66 MB 相对可忽略。(这一段的 MB 一律是**二进制 MB**:三个大头由同一份实测
|
|
35
|
+
脚本以 `/1024/1024` 从按 `KB` 记的实测字节换算,与上面 2.66 / 5.30 / 156.6 同一口径。)
|
|
36
|
+
- **为什么这一节必须配一次版本号**:发布脚本**先发子包、后发根包**,并且**跳过 registry 上已存在的同版本**。
|
|
37
|
+
`peaks-loop-mut@0.1.72` 已经在 registry 上,它不带 `dist/version.js` 所以不会被判 stale ——
|
|
38
|
+
版本不动,**这个改动到不了任何用户**。
|
|
39
|
+
|
|
40
|
+
### 2. core / vitest-runner 的大版本互斥修好了;那个**从来没激活过**的 checker 被移除
|
|
41
|
+
|
|
42
|
+
- 此前:vitest-runner 9.6.1 声明的 peer 要求 core **9.6.1**,而根包 `devDependencies` 里 core 停在
|
|
43
|
+
**^8.7.1** ⇒ 每次安装都有一条 unmet peer。
|
|
44
|
+
- 现在:core 与 vitest-runner 同为 **9.6.1**,**全量重解析零 unmet peer**。
|
|
45
|
+
- `@stryker-mutator/typescript-checker` **已移除**:**移除之前**全仓只有 **5 处**提到它 —— 根清单的
|
|
46
|
+
`devDependencies` 一行、锁文件里的 importer 条目 / package 条目 / peer 快照条目三条,以及
|
|
47
|
+
`.peaks/docs/lint-rule-divergences.md` 里的一句散文记录。**这 5 处没有一处是插件**:
|
|
48
|
+
`stryker.conf.js` 的 `plugins` 里**从来就没有它**(移除前的版本也没有),它**从来没有被激活过**。
|
|
49
|
+
而它声明的 peer 是 core `~8.7.0`,与 9.6.1 **互斥**,于是每次安装都报一条 unsatisfied binding。
|
|
50
|
+
移除后那条警告消失。这一版发出去的树里,它**只剩两处**被提到:那一句散文记录,和本节的这一句。
|
|
51
|
+
- 锁文件的改动**有闭包证明**,不是"看着像":把两份锁文件的 stryker 传递闭包逐键比对,结论是
|
|
52
|
+
**每一处改动都在闭包内**(**PASS**)。checker 移除那一轮单独是 **26 删 / 0 增 / 1 改**,
|
|
53
|
+
删掉的正是 checker 的子树;028 这一轮合起来,importer 只动了 `.` 与 `packages/peaks-loop-mut`。
|
|
54
|
+
|
|
55
|
+
### 3. `peaks mut` 的项目作用域与程序化配置(改谁就只改谁)
|
|
56
|
+
|
|
57
|
+
- 此前:`--project` 被**忽略** —— Stryker 读配置、解析 `mutate` / `testFiles` 模式都按 `process.cwd()` 来,
|
|
58
|
+
`--test-files` 根本没传到 Stryker;项目根的 `stryker.conf.js` 是**必须**的。
|
|
59
|
+
- 现在:作用域由 `--project` 决定,配置由 CLI **程序化**构建;项目根的 `stryker.conf.js`
|
|
60
|
+
降级为**可选的向后兼容兜底**(项目自己写的 `mutate` 仍然优先于 CLI 的默认值)。
|
|
61
|
+
- **实测(真实夹具,在仓库之外:没有 `node_modules`、没有 `stryker.conf.js`)**:
|
|
62
|
+
`mutantsTotal 4 / killed 2 / survived 2 / killRate 0.5`;
|
|
63
|
+
从**另一个工作目录**发起时,被改的是夹具里的文件,调用者 cwd 里的诱饵文件**没被改**
|
|
64
|
+
(`decoyUnchanged = true`)。**stdout 恰好 1 行**,可解析。
|
|
65
|
+
- 失败现在有**具名错误码**,不再是 `UNHANDLED_ERROR`:
|
|
66
|
+
`MUT_MUTATE_PATTERN_REQUIRED`、`MUT_NO_MUTANTS`、`MUT_TOOLCHAIN_UNAVAILABLE`。
|
|
67
|
+
- 测试:纯配置构建器 **13 passed**、CLI 标志解析 **5 passed**、集成 **2 个文件 / 5 个测试全绿**。
|
|
68
|
+
- 报告 schema 的源文件**逐字节未改**
|
|
69
|
+
(sha256 `bc675a8521601c8edb2cd217ccbe9972fe6ed2040b79701e3870cd1f3db60d1d` 前后相同)。
|
|
70
|
+
|
|
71
|
+
### 4. 文档与脚本说真话(每一句都对得上代码)
|
|
72
|
+
|
|
73
|
+
- `peaks-mut` 技能文档:**18 处校正 + 3 处收紧**(逐条"原句 → 现句"在切片载体里)。
|
|
74
|
+
- 守卫测试对着**真实的 commander 命令对象**比对,不是对着手抄的标志清单 ⇒ 标志改名/增删都会红。
|
|
75
|
+
当前 **12/12 绿**;红复现实测 **1 failed / 11 passed,退出码 1**。
|
|
76
|
+
- 仓库自己的 `stryker.conf.js` 此前指向 **4 个没有任何测试 import 的文件** ⇒ dogfood 运行必然
|
|
77
|
+
`killRate 0`、退出码 1(**不是配置写错了,是那几个文件根本没有测试**)。现在 4 个 mutate 目标
|
|
78
|
+
**每一个都有测试 import**。
|
|
79
|
+
- 根脚本 `mut:run` / `mut:scan` 现在带的参数**就是解析器认的参数**(之前那两个脚本各缺必需参数)。
|
|
80
|
+
|
|
81
|
+
### 5. `mut/mut-report.json` 的过期接受条目退休
|
|
82
|
+
|
|
83
|
+
- 此前:种子名单里有一条针对 `mut/mut-report.json` 的"过期可接受"豁免,它给的理由**两半都是假的**
|
|
84
|
+
("没有生产者"、"peaks tact read 不是注册命令")。现在 `peaks mut run` **真的**产出报告,
|
|
85
|
+
`peaks tact read` **真的**是注册命令 —— 理由不成立了,条目就该退休。
|
|
86
|
+
- 退休范围**只有那一条接受条目**:那行 `backCompat` / `backCompatUntil` 的**窗口本身一字未改**
|
|
87
|
+
(窗口仍在,缺的报告仍是软通过);另一条接受**保留**。
|
|
88
|
+
- 真实报告(`mut/mut-report.json`):`mutantsTotal 21 / killed 20 / survived 1`、
|
|
89
|
+
`killRate 0.9523809523809523`、`totalAssertions 29`、`weakAssertions 0`、`weakRate 0`、
|
|
90
|
+
`thresholds.passed true`。
|
|
91
|
+
- 阈值**一个都没改**(`mutationKillRateMin 0.80` / `weakAssertionRateMax 0.05`),
|
|
92
|
+
受影响的 **7 个测试文件 / 93 个测试全绿**。
|
|
93
|
+
|
|
94
|
+
### 6. 版本号与发布含义
|
|
95
|
+
|
|
96
|
+
- 根包 `peaks-loop` **4.1.18 → 4.1.19**。`packages/` 下**实际只有 4 个**可发布 workspace 包
|
|
97
|
+
(发现规则是扫 `packages/` 的直接子目录、且要求其中有 `package.json`),
|
|
98
|
+
由正路脚本**锁步升**(子包规则 = patch 位 +1,major/minor 不变):
|
|
99
|
+
|
|
100
|
+
| 包 | 改前 | 改后 |
|
|
101
|
+
| ----------------------------- | ------- | ---------- |
|
|
102
|
+
| `peaks-loop`(根) | 4.1.18 | **4.1.19** |
|
|
103
|
+
| `peaks-loop-mut` | 0.1.72 | **0.1.73** |
|
|
104
|
+
| `peaks-loop-shared` | 0.0.107 | 0.0.108 |
|
|
105
|
+
| `peaks-loop-shared-channel` | 0.0.75 | 0.0.76 |
|
|
106
|
+
| `peaks-loop-internal-runtime` | 0.0.58 | 0.0.59 |
|
|
107
|
+
|
|
108
|
+
- 两个**受版本控制**的版本戳同步为 4.1.19:`packages/peaks-loop-shared/src/version.ts` 的 `CLI_VERSION`
|
|
109
|
+
与 `packages/peaks-loop-internal-runtime/src/index.ts` 的 `RUNTIME_VERSION`。
|
|
110
|
+
- **版本字段一个都没手改**:全部由 `scripts/bump-version.mjs --to 4.1.19` 与 `scripts/sync-version.mjs`
|
|
111
|
+
产生。逐字段比对证明:**5 个 manifest 各自只有 `version` 一个键变了**。
|
|
112
|
+
- **维护者要做的**(本次**没有**做):合并后 `git tag v4.1.19` + push,由发布流程发包。
|
|
113
|
+
**本次不打 tag、不发布、不提交。**
|
|
114
|
+
- 为什么**必须**动版本号(再说一次,因为它就是本节存在的理由):发布脚本**先发子包、后发根包**,
|
|
115
|
+
并且**跳过 registry 上已存在的同版本**;线上根包 pin 的是 `peaks-loop-mut: 0.1.72`,
|
|
116
|
+
而 registry 上的 0.1.72 **不带 stryker** ⇒ 版本不动,§1 的依赖**到不了用户**。
|
|
117
|
+
|
|
118
|
+
### 7. 验证
|
|
119
|
+
|
|
120
|
+
- `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**(源码层,不需 build)。
|
|
121
|
+
- 源码 CLI `node node_modules/tsx/dist/cli.mjs src/cli/index.ts --version` 打印 **4.1.19**。
|
|
122
|
+
- `pnpm install --frozen-lockfile` 退出 **0**,而且**锁文件一个字都没改** ——
|
|
123
|
+
workspace 包在锁文件里是 `link:` 引用(**不记版本号**),所以版本号变动**不需要**动锁文件。
|
|
124
|
+
- 依赖守卫测试 `tests/unit/release/mut-runtime-dependency.test.ts` **13 passed (13)**。
|
|
125
|
+
- `tsc -p tsconfig.json --noEmit` 退出 **0**;`prettier --check` 对本次改动的清单文件退出 **0**;
|
|
126
|
+
`eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对两个版本戳文件 **0 findings**。
|
|
127
|
+
- 逐字段比对:**5 个 manifest 各自只有 `version` 一个键变了**。
|
|
128
|
+
|
|
3
129
|
## 4.1.18 — 2026-10-23(下游机器的技能商店会说谎了;门禁不再对自己的沉默撒谎)
|
|
4
130
|
|
|
5
131
|
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
|
package/README-en.md
CHANGED
|
@@ -80,6 +80,12 @@ Other slash commands you'll reach for:
|
|
|
80
80
|
|
|
81
81
|
No CLI to memorize. No manifest to hand-author. No second terminal to open. **Send the slash, the rest is on it.**
|
|
82
82
|
|
|
83
|
+
> **How much more does this download?** This version ships the mutation-testing engine
|
|
84
|
+
> (`@stryker-mutator/core` + `@stryker-mutator/vitest-runner`) as a **runtime dependency**, so the install
|
|
85
|
+
> pulls the stryker engine closure — **about 2.66 MB (9 packages)** more. The vitest family's 5.30 MB is only
|
|
86
|
+
> auto-installed **if your machine does not have vitest yet**, and any project that runs `peaks mut` already
|
|
87
|
+
> has vitest. **In one line: installing peaks-loop downloads about 2.7 MB more.**
|
|
88
|
+
|
|
83
89
|
---
|
|
84
90
|
|
|
85
91
|
## Where files land after install
|
package/README.md
CHANGED
|
@@ -75,6 +75,11 @@ npm i -g peaks-loop
|
|
|
75
75
|
|
|
76
76
|
不需要记 CLI、不需要写 manifest、不需要切到第二个终端。**斜杠命令一发,后面的活它替你跑完。**
|
|
77
77
|
|
|
78
|
+
> **装这个包会多下载多少?** 这一版把变异测试引擎(`@stryker-mutator/core` +
|
|
79
|
+
> `@stryker-mutator/vitest-runner`)作为**运行时依赖**带上了 —— 消费者的安装会多出 stryker 引擎闭包
|
|
80
|
+
> **约 2.66 MB(9 个包)**。vitest 家族那 5.30 MB **只在你的机器上还没有 vitest 时**才会被自动装上,
|
|
81
|
+
> 而要跑 `peaks mut` 的项目**必然已经有 vitest**。**一句话:你装 peaks-loop 多下载了约 2.7 MB。**
|
|
82
|
+
|
|
78
83
|
---
|
|
79
84
|
|
|
80
85
|
## 装上以后,文件放在哪
|
|
@@ -28,11 +28,20 @@ MUST follow the given-when-then shape.
|
|
|
28
28
|
|
|
29
29
|
### 1.1 Description (the `it()` / `test()` string-literal)
|
|
30
30
|
|
|
31
|
-
- **
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
31
|
+
- **Preferred form (idiomatic — a preference, NOT a requirement)**:
|
|
32
|
+
`when X, should Y` — state the precondition in the `when` clause and the
|
|
33
|
+
observable outcome in the `should` clause. New tests SHOULD read this way,
|
|
34
|
+
because it names the precondition and the outcome in one sentence. Writing
|
|
35
|
+
only `when`, or only `should`, is ALLOWED; writing both is RECOMMENDED, never
|
|
36
|
+
required.
|
|
37
|
+
- **Enforced rule (the only rule a checker enforces)**: the description MUST
|
|
38
|
+
include at least one of `when` or `should`. This is exactly what the
|
|
39
|
+
verifier runs: `hasWhenOrShould` in
|
|
40
|
+
`src/services/qa/bdd-test-style-contract.ts` matches
|
|
41
|
+
`/(\bwhen\b|\bshould\b)/i`, and a description that contains neither fails
|
|
42
|
+
with the reason code `description-no-should-when`. A description carrying
|
|
43
|
+
only `when`, or only `should`, PASSES this rule — the checker never asks for
|
|
44
|
+
both.
|
|
36
45
|
- **Anti-pattern**: do NOT use legacy `// arrange:` / `// act:` /
|
|
37
46
|
`// assert:` markers anywhere in the test body.
|
|
38
47
|
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { fail, ok } from 'peaks-loop-shared/result';
|
|
9
9
|
import { runRedLinesAudit } from '../../services/audit/red-lines-service.js';
|
|
10
|
+
import { withRootScratchFindings } from '../../services/audit/enforcers/root-scratch-artifacts.js';
|
|
10
11
|
import { getErrorMessage, printResult } from '../cli-helpers.js';
|
|
11
12
|
import { PROJECT_PATH_HINT, SCANNER_HINT, validateProjectRoot } from './audit-command-shared.js';
|
|
12
13
|
import { emptyRedLineAudit } from './audit-refusal-data.js';
|
|
@@ -33,7 +34,11 @@ export function runRedLines(options, io) {
|
|
|
33
34
|
}
|
|
34
35
|
try {
|
|
35
36
|
const result = runRedLinesAudit({ projectRoot: validation.projectRoot });
|
|
36
|
-
|
|
37
|
+
// The root scratch sweep rides in this envelope: a capture at the project
|
|
38
|
+
// root is the shape that reaches a commit, because a tracked file leaves
|
|
39
|
+
// `git status` clean and no other gate reads it.
|
|
40
|
+
const audit = withRootScratchFindings(result.audit, validation.projectRoot);
|
|
41
|
+
const envelope = ok('audit.red-lines', audit, result.warnings.map((w) => `${w.file}: ${w.message}`), redLinesNextActions(audit));
|
|
37
42
|
printResult(io, envelope, options.json);
|
|
38
43
|
}
|
|
39
44
|
catch (error) {
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { type ProgramIO } from '../cli-helpers.js';
|
|
2
|
+
export declare function bestPracticeDir(projectRoot: string): string;
|
|
3
|
+
/** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
|
|
4
|
+
* every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
|
|
5
|
+
* truncated to 32, so no intent can introduce a path separator. */
|
|
6
|
+
export declare function scanArtifactPath(projectRoot: string, slugSource: string): string;
|
|
7
|
+
export declare function intentIdLine(intent: string): string;
|
|
8
|
+
/** The intent the artifact at `path` was written for, or null when it records
|
|
9
|
+
* none (an artifact written before this marker existed) or cannot be read.
|
|
10
|
+
*
|
|
11
|
+
* Only the FIRST line is read, and the marker is always written first, so a
|
|
12
|
+
* caller-supplied intent cannot forge a match by putting a marker of its own
|
|
13
|
+
* into the text it carries. */
|
|
14
|
+
export declare function readArtifactIntentId(path: string): string | null;
|
|
15
|
+
/**
|
|
16
|
+
* The collision §12.3 recorded: the artifact path keys on `(date, slug)` and
|
|
17
|
+
* the slug is capped at 32 characters, so two intents that agree in their
|
|
18
|
+
* first 32 slug characters land on one file and the second silently overwrote
|
|
19
|
+
* the first one's recommendation.
|
|
20
|
+
*
|
|
21
|
+
* The same intent again is NOT a collision — it is the same scan re-running,
|
|
22
|
+
* and it overwrites as it always did. An artifact this command cannot
|
|
23
|
+
* attribute is treated as another intent's: the refusal is unconditional,
|
|
24
|
+
* because an artifact that cannot be named cannot be cleared.
|
|
25
|
+
*/
|
|
26
|
+
export type SlugCollision = {
|
|
27
|
+
readonly project: string;
|
|
28
|
+
readonly intent: string;
|
|
29
|
+
readonly language: string;
|
|
30
|
+
readonly artifactPath: string;
|
|
31
|
+
readonly existingIntent: string | null;
|
|
32
|
+
};
|
|
33
|
+
/** The collision a scan would cause, or null when it would cause none. */
|
|
34
|
+
export declare function detectSlugCollision(project: string, intent: string, language: string): SlugCollision | null;
|
|
35
|
+
export declare const SLUG_COLLISION_MESSAGE: string;
|
|
36
|
+
/**
|
|
37
|
+
* Refuse a scan whose artifact path is already owned by another intent.
|
|
38
|
+
*
|
|
39
|
+
* Nothing is rendered: the refusal is the whole answer, exactly as the
|
|
40
|
+
* synthetic and no-fragments refusals are.
|
|
41
|
+
*/
|
|
42
|
+
export declare function emitSlugCollisionRefusal(io: ProgramIO, asJson: boolean, collision: SlugCollision): void;
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
*
|
|
3
|
+
* The best-practice-scan artifact path, the record of which intent owns it,
|
|
4
|
+
* and the refusal that replaced a silent overwrite (§12.3).
|
|
5
|
+
*
|
|
6
|
+
* The path keys on `(date, slug)` and the slug is capped at 32 characters, so
|
|
7
|
+
* two different intents can land on one file. Before this, the second scan
|
|
8
|
+
* silently overwrote the first one's recommendation and both exited 0 — one
|
|
9
|
+
* scan's result was lost, with no error and no warning.
|
|
10
|
+
*
|
|
11
|
+
* The behaviour implemented here is ONE: the second scan REFUSES, naming the
|
|
12
|
+
* collision. The path scheme itself is unchanged, so a scan that collides with
|
|
13
|
+
* nothing still writes exactly where it wrote before.
|
|
14
|
+
*
|
|
15
|
+
* To tell "the same intent again" from "a different intent that landed on the
|
|
16
|
+
* same path", every artifact this command writes starts with an intent-id
|
|
17
|
+
* marker: the exact intent, JSON-encoded, on the first line. The marker is
|
|
18
|
+
* always written FIRST, so a caller-supplied intent cannot forge a match by
|
|
19
|
+
* putting a marker of its own into the text it carries.
|
|
20
|
+
*/
|
|
21
|
+
import { closeSync, existsSync, openSync, readSync } from 'node:fs';
|
|
22
|
+
import { join } from 'node:path';
|
|
23
|
+
import { fail } from 'peaks-loop-shared/result';
|
|
24
|
+
import { printResult } from '../cli-helpers.js';
|
|
25
|
+
export function bestPracticeDir(projectRoot) {
|
|
26
|
+
return join(projectRoot, 'best-practice');
|
|
27
|
+
}
|
|
28
|
+
/** `YYYY-MM-DD` is 10 characters, and the slug is capped at 32 so the filename
|
|
29
|
+
* stays a filename. Both are part of the pinned artifact path. */
|
|
30
|
+
const ISO_DATE_LENGTH = 10;
|
|
31
|
+
const SLUG_MAX_LENGTH = 32;
|
|
32
|
+
/** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
|
|
33
|
+
* every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
|
|
34
|
+
* truncated to 32, so no intent can introduce a path separator. */
|
|
35
|
+
export function scanArtifactPath(projectRoot, slugSource) {
|
|
36
|
+
const dateStr = new Date().toISOString().slice(0, ISO_DATE_LENGTH);
|
|
37
|
+
const slug = slugSource.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, SLUG_MAX_LENGTH) || 'intent';
|
|
38
|
+
return join(bestPracticeDir(projectRoot), `${dateStr}-${slug}.md`);
|
|
39
|
+
}
|
|
40
|
+
/** The first line of every artifact this command writes: the exact intent,
|
|
41
|
+
* JSON-encoded. It is what tells "the same intent again" from "a different
|
|
42
|
+
* intent that landed on the same path". */
|
|
43
|
+
const INTENT_ID_PREFIX = '<!-- peaks-intent-id: ';
|
|
44
|
+
const INTENT_ID_SUFFIX = ' -->';
|
|
45
|
+
/** An intent longer than this cannot be read back; such an artifact is unattributable. */
|
|
46
|
+
const INTENT_ID_READ_LIMIT = 65_536;
|
|
47
|
+
export function intentIdLine(intent) {
|
|
48
|
+
return `${INTENT_ID_PREFIX}${JSON.stringify(intent)}${INTENT_ID_SUFFIX}`;
|
|
49
|
+
}
|
|
50
|
+
/** The intent the artifact at `path` was written for, or null when it records
|
|
51
|
+
* none (an artifact written before this marker existed) or cannot be read.
|
|
52
|
+
*
|
|
53
|
+
* Only the FIRST line is read, and the marker is always written first, so a
|
|
54
|
+
* caller-supplied intent cannot forge a match by putting a marker of its own
|
|
55
|
+
* into the text it carries. */
|
|
56
|
+
export function readArtifactIntentId(path) {
|
|
57
|
+
const fd = openSync(path, 'r');
|
|
58
|
+
try {
|
|
59
|
+
const buffer = Buffer.alloc(INTENT_ID_READ_LIMIT);
|
|
60
|
+
const read = readSync(fd, buffer, 0, INTENT_ID_READ_LIMIT, 0);
|
|
61
|
+
const firstLine = buffer.subarray(0, read).toString('utf8').split('\n')[0] ?? '';
|
|
62
|
+
if (!firstLine.startsWith(INTENT_ID_PREFIX) || !firstLine.endsWith(INTENT_ID_SUFFIX)) {
|
|
63
|
+
return null;
|
|
64
|
+
}
|
|
65
|
+
const encoded = firstLine.slice(INTENT_ID_PREFIX.length, firstLine.length - INTENT_ID_SUFFIX.length);
|
|
66
|
+
let decoded;
|
|
67
|
+
try {
|
|
68
|
+
decoded = JSON.parse(encoded);
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
// A marker that cannot be parsed is a marker that cannot be trusted:
|
|
72
|
+
// `decoded` stays null, so the caller gets "no usable marker" and the
|
|
73
|
+
// refusal stays fail-closed.
|
|
74
|
+
decoded = null;
|
|
75
|
+
}
|
|
76
|
+
return typeof decoded === 'string' ? decoded : null;
|
|
77
|
+
}
|
|
78
|
+
finally {
|
|
79
|
+
closeSync(fd);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/** The collision a scan would cause, or null when it would cause none. */
|
|
83
|
+
export function detectSlugCollision(project, intent, language) {
|
|
84
|
+
const primary = scanArtifactPath(project, intent);
|
|
85
|
+
if (!existsSync(primary))
|
|
86
|
+
return null;
|
|
87
|
+
const existingIntent = readArtifactIntentId(primary);
|
|
88
|
+
if (existingIntent === intent)
|
|
89
|
+
return null;
|
|
90
|
+
return { project, intent, language, artifactPath: primary, existingIntent };
|
|
91
|
+
}
|
|
92
|
+
export const SLUG_COLLISION_MESSAGE = 'best-practice-scan: SLUG COLLISION — this scan would overwrite an artifact that ' +
|
|
93
|
+
'belongs to another intent, so nothing was written and nothing was overwritten. The ' +
|
|
94
|
+
'artifact path keys on (date, slug) and the slug is capped at 32 characters, so two ' +
|
|
95
|
+
'intents that agree in their first 32 slug characters land on one file.';
|
|
96
|
+
/**
|
|
97
|
+
* Refuse a scan whose artifact path is already owned by another intent.
|
|
98
|
+
*
|
|
99
|
+
* Nothing is rendered: the refusal is the whole answer, exactly as the
|
|
100
|
+
* synthetic and no-fragments refusals are.
|
|
101
|
+
*/
|
|
102
|
+
export function emitSlugCollisionRefusal(io, asJson, collision) {
|
|
103
|
+
printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_SLUG_COLLISION', SLUG_COLLISION_MESSAGE, {
|
|
104
|
+
project: collision.project,
|
|
105
|
+
intent: collision.intent,
|
|
106
|
+
language: collision.language,
|
|
107
|
+
artifactPath: collision.artifactPath,
|
|
108
|
+
existingIntent: collision.existingIntent,
|
|
109
|
+
collision: true,
|
|
110
|
+
step25: 'skipped-slug-collision'
|
|
111
|
+
}, [
|
|
112
|
+
'Reword the intent so its first 32 slug characters differ, or delete the artifact that already owns the path',
|
|
113
|
+
`Existing artifact: ${collision.artifactPath}`
|
|
114
|
+
]), asJson);
|
|
115
|
+
}
|
|
@@ -29,6 +29,11 @@
|
|
|
29
29
|
* (`BEST_PRACTICE_SCAN_NO_FRAGMENTS` — see `emitNoFragmentsRefusal`, which is
|
|
30
30
|
* the guard against a `★` recommendation built from zero fragments).
|
|
31
31
|
*
|
|
32
|
+
* Collision refusal: the artifact path keys on `(date, slug)` with the slug
|
|
33
|
+
* capped at 32 characters, so two intents that agree in their first 32 slug
|
|
34
|
+
* characters land on one file. The second scan refuses
|
|
35
|
+
* (`BEST_PRACTICE_SCAN_SLUG_COLLISION`) rather than overwrite the first.
|
|
36
|
+
*
|
|
32
37
|
* Catch-gate (spec §7): the command emits a 3-line prompt asking the
|
|
33
38
|
* user to ack / pick alt / reject + reason. The gate is read from
|
|
34
39
|
* stdin via `PEAKS_BEST_PRACTICE_STDIN` (test seam) or the real stdin
|
|
@@ -3,24 +3,9 @@ import { fail, ok } from 'peaks-loop-shared/result';
|
|
|
3
3
|
import { detectLanguage } from '../../services/best-practice/language-detector.js';
|
|
4
4
|
import { scanBestPractice } from '../../services/best-practice/scan-orchestrator.js';
|
|
5
5
|
import { findForbiddenTokens, formatOutputTable } from '../../services/best-practice/output-formatter.js';
|
|
6
|
-
import { CATCH_GATE_PROMPT, emitNoFragmentsRefusal, INTENT_REQUIRED_MESSAGE,
|
|
6
|
+
import { CATCH_GATE_PROMPT, emitNoFragmentsRefusal, INTENT_REQUIRED_MESSAGE, readUserInput, renderSyntheticRefusal, SYNTHETIC_SOURCE_MESSAGE, writeRefusal, writeRenderedArtifact } from './best-practice-scan-helpers.js';
|
|
7
|
+
import { detectSlugCollision, emitSlugCollisionRefusal, scanArtifactPath } from './best-practice-scan-collision.js';
|
|
7
8
|
import { readLookupResultsOrFail } from './best-practice-scan-lookup-results.js';
|
|
8
|
-
async function readUserInput() {
|
|
9
|
-
const override = process.env.PEAKS_BEST_PRACTICE_STDIN;
|
|
10
|
-
if (override !== undefined)
|
|
11
|
-
return override;
|
|
12
|
-
if (process.stdin.isTTY)
|
|
13
|
-
return '';
|
|
14
|
-
return new Promise((resolveStdin) => {
|
|
15
|
-
let data = '';
|
|
16
|
-
process.stdin.setEncoding('utf8');
|
|
17
|
-
process.stdin.on('data', (chunk) => {
|
|
18
|
-
data += chunk;
|
|
19
|
-
});
|
|
20
|
-
process.stdin.on('end', () => resolveStdin(data.trim()));
|
|
21
|
-
process.stdin.on('error', () => resolveStdin(data.trim()));
|
|
22
|
-
});
|
|
23
|
-
}
|
|
24
9
|
export function parseCatchGateReply(raw, recommended) {
|
|
25
10
|
const trimmed = raw.trim();
|
|
26
11
|
if (trimmed.length === 0) {
|
|
@@ -117,6 +102,12 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
117
102
|
process.exitCode = 1;
|
|
118
103
|
return;
|
|
119
104
|
}
|
|
105
|
+
const collision = detectSlugCollision(opts.project, intent, language);
|
|
106
|
+
if (collision !== null) {
|
|
107
|
+
emitSlugCollisionRefusal(io, opts.json === true, collision);
|
|
108
|
+
process.exitCode = 1;
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
120
111
|
const recommendation = scan.results.length > 0 ? 'A' : 'B';
|
|
121
112
|
const reasoning = `基于调用方提供的 ${scan.fragments.length} 个 ${scan.source} 文档片段` +
|
|
122
113
|
`(URL 由调用方构造,Context7 响应不含 URL);` +
|
|
@@ -150,7 +141,7 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
150
141
|
commitFlag: opts.commit === true,
|
|
151
142
|
forbiddenHits
|
|
152
143
|
};
|
|
153
|
-
writeRenderedArtifact(artifactPath, table, payload);
|
|
144
|
+
writeRenderedArtifact(artifactPath, table, payload, intent);
|
|
154
145
|
printResult(io, ok('best-practice.scan', payload, forbiddenHits.length > 0 ? [`forbidden tokens present: ${forbiddenHits.join(', ')}`] : [], [`Artifact written to ${artifactPath}`, `catch-gate outcome: ${outcome.kind}`]), opts.json === true);
|
|
155
146
|
}
|
|
156
147
|
catch (err) {
|
|
@@ -2,11 +2,14 @@ import { type ProgramIO } from '../cli-helpers.js';
|
|
|
2
2
|
export declare const CATCH_GATE_PROMPT: string;
|
|
3
3
|
export declare const INTENT_REQUIRED_MESSAGE: string;
|
|
4
4
|
export declare const SYNTHETIC_SOURCE_MESSAGE: string;
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
|
|
5
|
+
/**
|
|
6
|
+
* The catch-gate reply: the `PEAKS_BEST_PRACTICE_STDIN` seam in tests, the
|
|
7
|
+
* real stdin in production.
|
|
8
|
+
*
|
|
9
|
+
* Moved here from the command file: that file had three lines of headroom
|
|
10
|
+
* under the 300-line cap, and the collision check needed more than that.
|
|
11
|
+
*/
|
|
12
|
+
export declare function readUserInput(): Promise<string>;
|
|
10
13
|
/** Refusal body for a synthetic scan. It is written to the artifact path so
|
|
11
14
|
* the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
|
|
12
15
|
* spawns with `stdio: 'ignore'`, so stdout never reaches anyone). */
|
|
@@ -39,8 +42,11 @@ export declare function writeRefusal(projectRoot: string, intent: string, refusa
|
|
|
39
42
|
* payload is proved to serialise *before* anything is written: a payload the
|
|
40
43
|
* printer cannot render must not leave behind an artifact claiming a scan that
|
|
41
44
|
* never reported.
|
|
45
|
+
*
|
|
46
|
+
* The first line is the intent-id marker, so a later scan can tell which
|
|
47
|
+
* intent owns this artifact.
|
|
42
48
|
*/
|
|
43
|
-
export declare function writeRenderedArtifact(artifactPath: string, table: string, payload: unknown): void;
|
|
49
|
+
export declare function writeRenderedArtifact(artifactPath: string, table: string, payload: unknown, intent: string): void;
|
|
44
50
|
export declare const NO_FRAGMENTS_MESSAGE: string;
|
|
45
51
|
/**
|
|
46
52
|
* Refuse a scan that resolved against real lookups and still found nothing.
|
|
@@ -4,11 +4,16 @@
|
|
|
4
4
|
* helper, and the synthetic-lookup refusal renderer. Later additions (the
|
|
5
5
|
* refusal write-path rule, the fragments-free refusal) live here for the same
|
|
6
6
|
* file-size reason.
|
|
7
|
+
*
|
|
8
|
+
* The artifact PATH and the record of which intent owns it moved to
|
|
9
|
+
* `best-practice-scan-collision.ts` in the same campaign: the §12.3 collision
|
|
10
|
+
* check needed more room than this file had under the 300-line cap.
|
|
7
11
|
*/
|
|
8
12
|
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
|
|
9
13
|
import { dirname, join, parse } from 'node:path';
|
|
10
14
|
import { fail } from 'peaks-loop-shared/result';
|
|
11
15
|
import { printResult } from '../cli-helpers.js';
|
|
16
|
+
import { intentIdLine, scanArtifactPath } from './best-practice-scan-collision.js';
|
|
12
17
|
export const CATCH_GATE_PROMPT = [
|
|
13
18
|
'⚠️ 任何跟你真实业务不一样,改 — LLM 推荐可能错。',
|
|
14
19
|
'回应 (默认 = 接受): 接受 / 接受方案 A|接受方案 B|接受方案 C / 拒绝 + 原因'
|
|
@@ -19,20 +24,32 @@ export const INTENT_REQUIRED_MESSAGE = 'best-practice-scan requires --intent <te
|
|
|
19
24
|
export const SYNTHETIC_SOURCE_MESSAGE = 'best-practice-scan: SKIPPED — the Context7 / WebSearch lookups in this build are stubs ' +
|
|
20
25
|
'(synthetic fragments), so no real documentation was consulted and there is nothing to ' +
|
|
21
26
|
'recommend. No recommendation, no comparison table and no ⚠️ catch gate were produced.';
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
*
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
return
|
|
27
|
+
/**
|
|
28
|
+
* The catch-gate reply: the `PEAKS_BEST_PRACTICE_STDIN` seam in tests, the
|
|
29
|
+
* real stdin in production.
|
|
30
|
+
*
|
|
31
|
+
* Moved here from the command file: that file had three lines of headroom
|
|
32
|
+
* under the 300-line cap, and the collision check needed more than that.
|
|
33
|
+
*/
|
|
34
|
+
export async function readUserInput() {
|
|
35
|
+
const override = process.env.PEAKS_BEST_PRACTICE_STDIN;
|
|
36
|
+
if (override !== undefined)
|
|
37
|
+
return override;
|
|
38
|
+
if (process.stdin.isTTY)
|
|
39
|
+
return '';
|
|
40
|
+
return new Promise((resolveStdin) => {
|
|
41
|
+
let data = '';
|
|
42
|
+
process.stdin.setEncoding('utf8');
|
|
43
|
+
process.stdin.on('data', (chunk) => {
|
|
44
|
+
// `setEncoding('utf8')` above makes every chunk a string at runtime, but
|
|
45
|
+
// the declared type of the 'data' event is still a Buffer, so the `+`
|
|
46
|
+
// needs a string operand. `String(chunk)` is the same ToString the `+`
|
|
47
|
+
// operator applies, so the bytes accumulated are unchanged.
|
|
48
|
+
data += String(chunk);
|
|
49
|
+
});
|
|
50
|
+
process.stdin.on('end', () => resolveStdin(data.trim()));
|
|
51
|
+
process.stdin.on('error', () => resolveStdin(data.trim()));
|
|
52
|
+
});
|
|
36
53
|
}
|
|
37
54
|
/** Refusal body for a synthetic scan. It is written to the artifact path so
|
|
38
55
|
* the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
|
|
@@ -74,7 +91,7 @@ export function writeRefusal(projectRoot, intent, refusal) {
|
|
|
74
91
|
? join(dirname(primary), 'skipped', parse(primary).base)
|
|
75
92
|
: primary;
|
|
76
93
|
mkdirSync(dirname(target), { recursive: true });
|
|
77
|
-
writeFileSync(target, refusal + '\n', 'utf8');
|
|
94
|
+
writeFileSync(target, intentIdLine(intent) + '\n' + refusal + '\n', 'utf8');
|
|
78
95
|
return target;
|
|
79
96
|
}
|
|
80
97
|
/**
|
|
@@ -84,11 +101,14 @@ export function writeRefusal(projectRoot, intent, refusal) {
|
|
|
84
101
|
* payload is proved to serialise *before* anything is written: a payload the
|
|
85
102
|
* printer cannot render must not leave behind an artifact claiming a scan that
|
|
86
103
|
* never reported.
|
|
104
|
+
*
|
|
105
|
+
* The first line is the intent-id marker, so a later scan can tell which
|
|
106
|
+
* intent owns this artifact.
|
|
87
107
|
*/
|
|
88
|
-
export function writeRenderedArtifact(artifactPath, table, payload) {
|
|
108
|
+
export function writeRenderedArtifact(artifactPath, table, payload, intent) {
|
|
89
109
|
JSON.stringify(payload);
|
|
90
110
|
mkdirSync(dirname(artifactPath), { recursive: true });
|
|
91
|
-
writeFileSync(artifactPath, table + '\n', 'utf8');
|
|
111
|
+
writeFileSync(artifactPath, intentIdLine(intent) + '\n' + table + '\n', 'utf8');
|
|
92
112
|
}
|
|
93
113
|
export const NO_FRAGMENTS_MESSAGE = 'best-practice-scan: NO FRAGMENTS — the lookups this scan resolved against returned no ' +
|
|
94
114
|
'documentation at all, so there is nothing to compare and no recommendation to make. ' +
|