peaks-loop 4.1.18 → 4.1.20
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 +256 -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 +9 -9
- package/schemas/doctor-report.schema.json +1 -1
- package/scripts/canonical-store-report.mjs +84 -0
- 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.20"
|
|
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.20",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,261 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.20 — 2026-10-25(从 4.1.18 起装不上的根包,修好了)
|
|
4
|
+
|
|
5
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
|
|
6
|
+
没有改 fail-open 策略、没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;
|
|
7
|
+
改的是**根包自己的打包白名单**(§1–§2)、**消费者能看到的说法**(§3–§4)与**版本号本身**(§5)。
|
|
8
|
+
|
|
9
|
+
**一句话:`npm i -g peaks-loop` 从 4.1.18 起就是装不上的。这一版把它修好了。**
|
|
10
|
+
|
|
11
|
+
### 1. 缺陷:白名单少了一行,于是整个安装死在 postinstall
|
|
12
|
+
|
|
13
|
+
根包的 `package.json#files` 是**白名单** —— 只有被它点名的文件才会进 tarball。
|
|
14
|
+
`scripts/install-skills-bundles.mjs`(**在包里**)import 了 `./canonical-store-report.mjs`,
|
|
15
|
+
而后者**不在白名单里**,于是 npm 发出去的是**一个没有同伙的 import 方**。
|
|
16
|
+
|
|
17
|
+
Node 的 ESM 加载器在跑任何代码之前就要把整张模块图解析完,所以这不是"少了个功能",
|
|
18
|
+
是**图连不上**,安装死在 `postinstall`,CLI 根本轮不到上场:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
npm error Error [ERR_MODULE_NOT_FOUND]: Cannot find module
|
|
22
|
+
'.../node_modules/peaks-loop/scripts/canonical-store-report.mjs'
|
|
23
|
+
imported from .../node_modules/peaks-loop/scripts/install-skills-bundles.mjs
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
**根因提交**是 `12c71e55`("fix(gates): a surface must not say what the code does not do")。
|
|
27
|
+
那一个提交在 `scripts/` 下**新增了 3 个** canonical-store 脚本(`canonical-store-fs.mjs`、
|
|
28
|
+
`canonical-store-marker.mjs`、`canonical-store-report.mjs`),给 importer 接上了其中的**第三个**,
|
|
29
|
+
而白名单**只加了那 3 个里的 2 个** —— 漏掉的正是 `-report`。该提交落在 `v4.1.17` 与 `v4.1.18`
|
|
30
|
+
之间(`git merge-base --is-ancestor` 实测:在 `v4.1.18`/`v4.1.19` 之内,在 `v4.1.16`/`v4.1.17` 之外)。
|
|
31
|
+
|
|
32
|
+
### 2. 实测证据(每个数字都来自本次实测)
|
|
33
|
+
|
|
34
|
+
**两个互相独立的方法**,同一个结论:
|
|
35
|
+
|
|
36
|
+
| 方法 | 4.1.17 | 4.1.18 | 4.1.19 |
|
|
37
|
+
|---|---|---|---|
|
|
38
|
+
| **真实 `npm install`**(隔离 prefix + 隔离 HOME) | **exit 0**,`added 127 packages in 10s` | **exit 1**,`ERR_MODULE_NOT_FOUND` | **exit 1**,`ERR_MODULE_NOT_FOUND` |
|
|
39
|
+
| **静态解析已发布 tarball**(`scripts/*.mjs` 数 / 本地相对 import 数 / **未命中**的目标数) | 16 / 24 / **0** | 18 / 27 / **1** | 18 / 27 / **1** |
|
|
40
|
+
|
|
41
|
+
那个"**1**"在 4.1.18 与 4.1.19 里是**同一个**目标:`install-skills-bundles.mjs -> ./canonical-store-report.mjs`。
|
|
42
|
+
**4.1.19 tarball 里所有已发布脚本的本地相对 import 全被枚举过一遍,未命中的只有这一个** ——
|
|
43
|
+
其余没进包的 `scripts/*.mjs` 都是本就不该进包的 dev / build / 测试脚本。
|
|
44
|
+
|
|
45
|
+
**不是 4.1.19 那一批引入的**:`v4.1.18` 与 `v4.1.19` 之间,`package.json#files` 的脚本条目
|
|
46
|
+
**增 0 减 0**,importer 的 blob 哈希**完全相同**(`05e80b3da11df0fee5f870fa3285a0fe153d0ff3`)。
|
|
47
|
+
4.1.19 是**继承**了这个缺陷,不是**造成**了它。
|
|
48
|
+
|
|
49
|
+
**修好之后的实测**(不只是"打包内容看着对",是**真的装得上、跑得起来**):
|
|
50
|
+
|
|
51
|
+
- 把修好的树 `pnpm pack` 出来的 tarball 里,`scripts/*.mjs` 共 **19** 个,
|
|
52
|
+
`scripts/canonical-store-report.mjs` **在包里**,已发布脚本的本地相对 import **未命中 0 个**。
|
|
53
|
+
- **真实安装**:把那个 tarball 装进一个隔离的 prefix(`HOME`、`PEAKS_CLAUDE_SKILLS_DIR`、
|
|
54
|
+
`PEAKS_CLAUDE_AGENTS_DIR` 全部指到临时目录),`npm install` **退出 0**
|
|
55
|
+
(`added 293 packages in 40s`),**没有** `ERR_MODULE_NOT_FOUND`,postinstall 跑完。
|
|
56
|
+
- **装完就能用**:装好的包里 `peaks --version` 打出 **4.1.20**(退出 0),
|
|
57
|
+
`peaks mut --help` 打出完整命令树(退出 0)。
|
|
58
|
+
- 说明一句方法上的诚实:这 4 个 workspace 子包在本次版本里是**新版本号**,registry 上**还没有**
|
|
59
|
+
(实测 `npm view peaks-loop-mut@0.1.74` → **404**),所以端到端安装里这 4 个内部依赖是用
|
|
60
|
+
**本树自己打出来的 tarball**(`file:` spec)解析的,其余依赖全部走 registry。
|
|
61
|
+
这正是发布流程"先发子包、后发根包"之后的拓扑;**打包白名单这件事本身**由上面的 tarball
|
|
62
|
+
内容测量直接回答。
|
|
63
|
+
|
|
64
|
+
### 3. 修法:一行白名单 + 一个防回归守卫
|
|
65
|
+
|
|
66
|
+
**修法就是一行** —— 根 `package.json#files` 里加一条 `"scripts/canonical-store-report.mjs",`,
|
|
67
|
+
`files` 的其余部分**一字未动**。白名单**没有**被放宽成整个 `scripts/`:那些 dev / build / 测试
|
|
68
|
+
脚本是**故意**不进包的,放宽会把它们一起发出去。
|
|
69
|
+
|
|
70
|
+
**现在有了防回归守卫**:`tests/unit/release/packaging-shipped-scripts-import-guard.test.ts`
|
|
71
|
+
(**13** 个用例)。它**静态**地读根 manifest 的白名单,取出 `scripts/*.mjs` 条目作为**已发布脚本集**,
|
|
72
|
+
解析每个已发布脚本的本地相对 import,断言**每个被 import 的目标也在已发布集里**。
|
|
73
|
+
**不联网、不查 registry、不做真实 `npm install`**。
|
|
74
|
+
|
|
75
|
+
它守的是"**已发布脚本之间的**本地相对 import",**不会**要求 dev / build / 测试脚本进包。
|
|
76
|
+
而且它被证明**真的会红**:临时把那一行从 `files` 里去掉 → 守卫 **exit 1**(`4 failed | 9 passed (13)`);
|
|
77
|
+
逐字节还原(sha256 比对一致)→ 再跑 → **exit 0**(`13 passed (13)`)。**只看到绿不算验证过。**
|
|
78
|
+
|
|
79
|
+
守卫在修好的树上的数字:**已发布脚本条目 19 个**,**检查的本地相对 import 27 个**,**未命中 0 个**。
|
|
80
|
+
|
|
81
|
+
### 4. 顺手拆掉的一颗雷:`main` 指向了不在白名单里的文件
|
|
82
|
+
|
|
83
|
+
工作树里根 `package.json` 带着 4 处**与本次缺陷无关**的改动(`repository.url`、`bin.peaks`,
|
|
84
|
+
以及新增的 `main`、`directories`)。其中 **`main: "stryker.conf.js"`** 是一颗雷:
|
|
85
|
+
`stryker.conf.js` **不在 `files` 白名单里**,所以它**不会**进 tarball ——
|
|
86
|
+
而 `main` 正是消费者 `import 'peaks-loop'` 解析到的入口。
|
|
87
|
+
留着它,就等于**修好一个"装得上"的包,再塞一个"装上了但主入口用不了"的坑**。
|
|
88
|
+
这 4 处已全部**还原成 `HEAD` 的原值**(`main` 与 `directories` 直接删掉)。
|
|
89
|
+
|
|
90
|
+
**成因是查出来的,不是猜的**:`npm pkg fix` 会把 `repository.url` 归一化成 `git+https://` 形式、
|
|
91
|
+
把 `bin` 的 `./` 前缀去掉;`npm pkg set` 会写入 `main` 与 `directories`。
|
|
92
|
+
而**本次用的版本锁步脚本不会**(实测:跑一次 `scripts/bump-version.mjs`,这 4 个字段
|
|
93
|
+
**0 个**被改动)。
|
|
94
|
+
|
|
95
|
+
### 5. 版本号与发布含义
|
|
96
|
+
|
|
97
|
+
- 根包 `peaks-loop` **4.1.19 → 4.1.20**。`packages/` 下**实际只有 4 个**可发布 workspace 包,
|
|
98
|
+
由正路脚本**锁步升**(子包规则 = patch 位 +1,major/minor 不变):
|
|
99
|
+
|
|
100
|
+
| 包 | 改前 | 改后 |
|
|
101
|
+
| ----------------------------- | ------- | ---------- |
|
|
102
|
+
| `peaks-loop`(根) | 4.1.19 | **4.1.20** |
|
|
103
|
+
| `peaks-loop-mut` | 0.1.73 | **0.1.74** |
|
|
104
|
+
| `peaks-loop-shared` | 0.0.108 | 0.0.109 |
|
|
105
|
+
| `peaks-loop-shared-channel` | 0.0.76 | 0.0.77 |
|
|
106
|
+
| `peaks-loop-internal-runtime` | 0.0.59 | 0.0.60 |
|
|
107
|
+
|
|
108
|
+
- 两个**受版本控制**的版本戳同步为 4.1.20:`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.20` 与 `scripts/sync-version.mjs`
|
|
111
|
+
产生。逐字段比对证明:**5 个 manifest 各自只有 `version` 一个键变了**;根 manifest 相对 `HEAD`
|
|
112
|
+
只多两处 —— `version` 与 `files` 里的那一行。
|
|
113
|
+
- **维护者要做的**(本次**没有**做):合并后 `git tag v4.1.20` + push,由发布流程发包。
|
|
114
|
+
**本次不打 tag、不发布、不提交。**
|
|
115
|
+
|
|
116
|
+
### 6. 验证
|
|
117
|
+
|
|
118
|
+
- `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**(`RUNTIME_VERSION=4.1.20`)。
|
|
119
|
+
- `pnpm install --frozen-lockfile` 退出 **0**,而且**锁文件一个字都没改** ——
|
|
120
|
+
sha256 前后同为 `7f60e065a8df3a63d7b03a2fc8f91db9628362387997fc77655c8c75ef46cc72`,
|
|
121
|
+
`git diff pnpm-lock.yaml` 为**空**。workspace 包在锁文件里是 `link:` 引用(**不记版本号**),
|
|
122
|
+
所以版本号变动**不需要**动锁文件。
|
|
123
|
+
- 逐字段比对:**5 个 manifest 各自只有 `version` 一个键变了**。
|
|
124
|
+
- 新守卫 `tests/unit/release/packaging-shipaged-scripts-import-guard.test.ts`:
|
|
125
|
+
**13 passed (13)**;去掉那一行白名单则 **4 failed | 9 passed (13)**,逐字节还原后回到全绿。
|
|
126
|
+
- **端到端**:修好的树 `pnpm pack` → 隔离 prefix 里 `npm install` **退出 0**
|
|
127
|
+
(`added 293 packages in 40s`)、**无** `ERR_MODULE_NOT_FOUND`;装好的包里
|
|
128
|
+
`peaks --version` 打出 **4.1.20**,`peaks mut --help` 退出 **0**。
|
|
129
|
+
- `.claude-plugin/marketplace.json` 由 `npm run plugin:manifest` 重生成,**跑两次逐字节相同**。
|
|
130
|
+
- `tsc -p tsconfig.json --noEmit` 退出 **0**;`prettier --check` 对本次改动的清单文件退出 **0**;
|
|
131
|
+
`eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对本次改动的文件 **0 findings**。
|
|
132
|
+
|
|
133
|
+
## 4.1.19 — 2026-10-24(`peaks mut` 在真实用户机器上**真的能跑**)
|
|
134
|
+
|
|
135
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
|
|
136
|
+
没有改 fail-open 策略、没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;
|
|
137
|
+
改的是 `peaks mut` 这一条线上的**依赖位置、作用域与文档**(§1–§5),以及**版本号本身**(§6)。
|
|
138
|
+
|
|
139
|
+
这一批做的是**同一件事**:让 `peaks mut` 从"消费者装上就崩"走到"消费者装上就能跑"。
|
|
140
|
+
|
|
141
|
+
崩的原因**不是代码写错了**,是**依赖放错了地方**:变异测试引擎只挂在根包的 `devDependencies` 上,
|
|
142
|
+
而真正 import 它的是 `peaks-loop-mut` —— 一个**要被发布出去**的包。消费者装到的是 registry 上的
|
|
143
|
+
`peaks-loop-mut@0.1.72`,它的 dependencies 只有 `{zod, ecc-universal}`,**不带 stryker**,
|
|
144
|
+
于是 `Cannot find package '@stryker-mutator/core'`。
|
|
145
|
+
|
|
146
|
+
这一批把它修好,并且补上三件一直缺的东西:**项目作用域正确**(改谁就只改谁)、
|
|
147
|
+
**文档说真话**(文档里每句话都对得上代码)、**过期接受退休**(一条理由已经不成立的"豁免"从名单里划掉)。
|
|
148
|
+
|
|
149
|
+
**消费者要多付一点下载体积:约 2.66 MB。** 这件事写在 §1,不藏着。
|
|
150
|
+
|
|
151
|
+
### 1. 变异引擎落到生产依赖(以及它到底值不值这 2.66 MB)
|
|
152
|
+
|
|
153
|
+
- 现在 `@stryker-mutator/core`(Stryker 的变异引擎)与 `@stryker-mutator/vitest-runner` 是
|
|
154
|
+
`peaks-loop-mut` 的**生产依赖**(`dependencies`,不是 `devDependencies`),两者同为 **9.6.1**。
|
|
155
|
+
- **消费者视角 —— `@stryker-mutator/vitest-runner` 是干什么的**:它是把 Stryker 的变异引擎接到
|
|
156
|
+
vitest 上的**适配器**。没有它,Stryker 只能退回"跑一条命令看退出码"的粗粒度跑手,
|
|
157
|
+
**算不出逐 mutant 的 kill rate** —— 而 `peaks mut` 卖的**正是这个数字**。所以它不是可选项。
|
|
158
|
+
- **代价**:安装会多出 stryker 引擎闭包 **9 个包 / 约 2.66 MB**。
|
|
159
|
+
- **vitest 那部分不会自动来**:vitest-runner 声明的 peer 是 `vitest >=2.0.0`,而 pnpm 的 peer 自动安装
|
|
160
|
+
**只在 peer 缺失时**发生。vitest / vite 家族共 **11 个包 / 约 5.30 MB**,**只有在你的机器上
|
|
161
|
+
还没有 vitest 时**才会被自动装上 —— 而要跑 `peaks mut` 的项目**必然已经有 vitest**。
|
|
162
|
+
- 说人话:**你装 peaks-loop 多下载了约 2.7 MB**。参照:`peaks-loop-mut` 现有的生产依赖树是
|
|
163
|
+
**344 个包 / 156.6 MB**(大头是 `sql.js` 23.0 MB、`typescript` 22.5 MB、`ecc-universal` 18.6 MB,
|
|
164
|
+
**与本次改动无关**),2.66 MB 相对可忽略。(这一段的 MB 一律是**二进制 MB**:三个大头由同一份实测
|
|
165
|
+
脚本以 `/1024/1024` 从按 `KB` 记的实测字节换算,与上面 2.66 / 5.30 / 156.6 同一口径。)
|
|
166
|
+
- **为什么这一节必须配一次版本号**:发布脚本**先发子包、后发根包**,并且**跳过 registry 上已存在的同版本**。
|
|
167
|
+
`peaks-loop-mut@0.1.72` 已经在 registry 上,它不带 `dist/version.js` 所以不会被判 stale ——
|
|
168
|
+
版本不动,**这个改动到不了任何用户**。
|
|
169
|
+
|
|
170
|
+
### 2. core / vitest-runner 的大版本互斥修好了;那个**从来没激活过**的 checker 被移除
|
|
171
|
+
|
|
172
|
+
- 此前:vitest-runner 9.6.1 声明的 peer 要求 core **9.6.1**,而根包 `devDependencies` 里 core 停在
|
|
173
|
+
**^8.7.1** ⇒ 每次安装都有一条 unmet peer。
|
|
174
|
+
- 现在:core 与 vitest-runner 同为 **9.6.1**,**全量重解析零 unmet peer**。
|
|
175
|
+
- `@stryker-mutator/typescript-checker` **已移除**:**移除之前**全仓只有 **5 处**提到它 —— 根清单的
|
|
176
|
+
`devDependencies` 一行、锁文件里的 importer 条目 / package 条目 / peer 快照条目三条,以及
|
|
177
|
+
`.peaks/docs/lint-rule-divergences.md` 里的一句散文记录。**这 5 处没有一处是插件**:
|
|
178
|
+
`stryker.conf.js` 的 `plugins` 里**从来就没有它**(移除前的版本也没有),它**从来没有被激活过**。
|
|
179
|
+
而它声明的 peer 是 core `~8.7.0`,与 9.6.1 **互斥**,于是每次安装都报一条 unsatisfied binding。
|
|
180
|
+
移除后那条警告消失。这一版发出去的树里,它**只剩两处**被提到:那一句散文记录,和本节的这一句。
|
|
181
|
+
- 锁文件的改动**有闭包证明**,不是"看着像":把两份锁文件的 stryker 传递闭包逐键比对,结论是
|
|
182
|
+
**每一处改动都在闭包内**(**PASS**)。checker 移除那一轮单独是 **26 删 / 0 增 / 1 改**,
|
|
183
|
+
删掉的正是 checker 的子树;028 这一轮合起来,importer 只动了 `.` 与 `packages/peaks-loop-mut`。
|
|
184
|
+
|
|
185
|
+
### 3. `peaks mut` 的项目作用域与程序化配置(改谁就只改谁)
|
|
186
|
+
|
|
187
|
+
- 此前:`--project` 被**忽略** —— Stryker 读配置、解析 `mutate` / `testFiles` 模式都按 `process.cwd()` 来,
|
|
188
|
+
`--test-files` 根本没传到 Stryker;项目根的 `stryker.conf.js` 是**必须**的。
|
|
189
|
+
- 现在:作用域由 `--project` 决定,配置由 CLI **程序化**构建;项目根的 `stryker.conf.js`
|
|
190
|
+
降级为**可选的向后兼容兜底**(项目自己写的 `mutate` 仍然优先于 CLI 的默认值)。
|
|
191
|
+
- **实测(真实夹具,在仓库之外:没有 `node_modules`、没有 `stryker.conf.js`)**:
|
|
192
|
+
`mutantsTotal 4 / killed 2 / survived 2 / killRate 0.5`;
|
|
193
|
+
从**另一个工作目录**发起时,被改的是夹具里的文件,调用者 cwd 里的诱饵文件**没被改**
|
|
194
|
+
(`decoyUnchanged = true`)。**stdout 恰好 1 行**,可解析。
|
|
195
|
+
- 失败现在有**具名错误码**,不再是 `UNHANDLED_ERROR`:
|
|
196
|
+
`MUT_MUTATE_PATTERN_REQUIRED`、`MUT_NO_MUTANTS`、`MUT_TOOLCHAIN_UNAVAILABLE`。
|
|
197
|
+
- 测试:纯配置构建器 **13 passed**、CLI 标志解析 **5 passed**、集成 **2 个文件 / 5 个测试全绿**。
|
|
198
|
+
- 报告 schema 的源文件**逐字节未改**
|
|
199
|
+
(sha256 `bc675a8521601c8edb2cd217ccbe9972fe6ed2040b79701e3870cd1f3db60d1d` 前后相同)。
|
|
200
|
+
|
|
201
|
+
### 4. 文档与脚本说真话(每一句都对得上代码)
|
|
202
|
+
|
|
203
|
+
- `peaks-mut` 技能文档:**18 处校正 + 3 处收紧**(逐条"原句 → 现句"在切片载体里)。
|
|
204
|
+
- 守卫测试对着**真实的 commander 命令对象**比对,不是对着手抄的标志清单 ⇒ 标志改名/增删都会红。
|
|
205
|
+
当前 **12/12 绿**;红复现实测 **1 failed / 11 passed,退出码 1**。
|
|
206
|
+
- 仓库自己的 `stryker.conf.js` 此前指向 **4 个没有任何测试 import 的文件** ⇒ dogfood 运行必然
|
|
207
|
+
`killRate 0`、退出码 1(**不是配置写错了,是那几个文件根本没有测试**)。现在 4 个 mutate 目标
|
|
208
|
+
**每一个都有测试 import**。
|
|
209
|
+
- 根脚本 `mut:run` / `mut:scan` 现在带的参数**就是解析器认的参数**(之前那两个脚本各缺必需参数)。
|
|
210
|
+
|
|
211
|
+
### 5. `mut/mut-report.json` 的过期接受条目退休
|
|
212
|
+
|
|
213
|
+
- 此前:种子名单里有一条针对 `mut/mut-report.json` 的"过期可接受"豁免,它给的理由**两半都是假的**
|
|
214
|
+
("没有生产者"、"peaks tact read 不是注册命令")。现在 `peaks mut run` **真的**产出报告,
|
|
215
|
+
`peaks tact read` **真的**是注册命令 —— 理由不成立了,条目就该退休。
|
|
216
|
+
- 退休范围**只有那一条接受条目**:那行 `backCompat` / `backCompatUntil` 的**窗口本身一字未改**
|
|
217
|
+
(窗口仍在,缺的报告仍是软通过);另一条接受**保留**。
|
|
218
|
+
- 真实报告(`mut/mut-report.json`):`mutantsTotal 21 / killed 20 / survived 1`、
|
|
219
|
+
`killRate 0.9523809523809523`、`totalAssertions 29`、`weakAssertions 0`、`weakRate 0`、
|
|
220
|
+
`thresholds.passed true`。
|
|
221
|
+
- 阈值**一个都没改**(`mutationKillRateMin 0.80` / `weakAssertionRateMax 0.05`),
|
|
222
|
+
受影响的 **7 个测试文件 / 93 个测试全绿**。
|
|
223
|
+
|
|
224
|
+
### 6. 版本号与发布含义
|
|
225
|
+
|
|
226
|
+
- 根包 `peaks-loop` **4.1.18 → 4.1.19**。`packages/` 下**实际只有 4 个**可发布 workspace 包
|
|
227
|
+
(发现规则是扫 `packages/` 的直接子目录、且要求其中有 `package.json`),
|
|
228
|
+
由正路脚本**锁步升**(子包规则 = patch 位 +1,major/minor 不变):
|
|
229
|
+
|
|
230
|
+
| 包 | 改前 | 改后 |
|
|
231
|
+
| ----------------------------- | ------- | ---------- |
|
|
232
|
+
| `peaks-loop`(根) | 4.1.18 | **4.1.19** |
|
|
233
|
+
| `peaks-loop-mut` | 0.1.72 | **0.1.73** |
|
|
234
|
+
| `peaks-loop-shared` | 0.0.107 | 0.0.108 |
|
|
235
|
+
| `peaks-loop-shared-channel` | 0.0.75 | 0.0.76 |
|
|
236
|
+
| `peaks-loop-internal-runtime` | 0.0.58 | 0.0.59 |
|
|
237
|
+
|
|
238
|
+
- 两个**受版本控制**的版本戳同步为 4.1.19:`packages/peaks-loop-shared/src/version.ts` 的 `CLI_VERSION`
|
|
239
|
+
与 `packages/peaks-loop-internal-runtime/src/index.ts` 的 `RUNTIME_VERSION`。
|
|
240
|
+
- **版本字段一个都没手改**:全部由 `scripts/bump-version.mjs --to 4.1.19` 与 `scripts/sync-version.mjs`
|
|
241
|
+
产生。逐字段比对证明:**5 个 manifest 各自只有 `version` 一个键变了**。
|
|
242
|
+
- **维护者要做的**(本次**没有**做):合并后 `git tag v4.1.19` + push,由发布流程发包。
|
|
243
|
+
**本次不打 tag、不发布、不提交。**
|
|
244
|
+
- 为什么**必须**动版本号(再说一次,因为它就是本节存在的理由):发布脚本**先发子包、后发根包**,
|
|
245
|
+
并且**跳过 registry 上已存在的同版本**;线上根包 pin 的是 `peaks-loop-mut: 0.1.72`,
|
|
246
|
+
而 registry 上的 0.1.72 **不带 stryker** ⇒ 版本不动,§1 的依赖**到不了用户**。
|
|
247
|
+
|
|
248
|
+
### 7. 验证
|
|
249
|
+
|
|
250
|
+
- `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**(源码层,不需 build)。
|
|
251
|
+
- 源码 CLI `node node_modules/tsx/dist/cli.mjs src/cli/index.ts --version` 打印 **4.1.19**。
|
|
252
|
+
- `pnpm install --frozen-lockfile` 退出 **0**,而且**锁文件一个字都没改** ——
|
|
253
|
+
workspace 包在锁文件里是 `link:` 引用(**不记版本号**),所以版本号变动**不需要**动锁文件。
|
|
254
|
+
- 依赖守卫测试 `tests/unit/release/mut-runtime-dependency.test.ts` **13 passed (13)**。
|
|
255
|
+
- `tsc -p tsconfig.json --noEmit` 退出 **0**;`prettier --check` 对本次改动的清单文件退出 **0**;
|
|
256
|
+
`eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对两个版本戳文件 **0 findings**。
|
|
257
|
+
- 逐字段比对:**5 个 manifest 各自只有 `version` 一个键变了**。
|
|
258
|
+
|
|
3
259
|
## 4.1.18 — 2026-10-23(下游机器的技能商店会说谎了;门禁不再对自己的沉默撒谎)
|
|
4
260
|
|
|
5
261
|
**版本级别**:候选 **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.
|