peaks-loop 4.1.21 → 4.1.22
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 +3 -6
- package/CHANGELOG.md +109 -0
- package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
- package/dist/cli/commands/mut-commands-helpers.js +44 -26
- package/dist/services/distribution/json-layout.d.ts +20 -0
- package/dist/services/distribution/json-layout.js +195 -0
- package/dist/services/distribution/plugin-manifest.d.ts +31 -2
- package/dist/services/distribution/plugin-manifest.js +40 -4
- package/package.json +5 -5
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
3
|
"pluginRoot": ".",
|
|
4
|
-
"version": "4.1.
|
|
4
|
+
"version": "4.1.22"
|
|
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.22",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
|
@@ -61,10 +61,7 @@
|
|
|
61
61
|
"mcpServers": {
|
|
62
62
|
"peaks": {
|
|
63
63
|
"command": "peaks",
|
|
64
|
-
"args": [
|
|
65
|
-
"mcp",
|
|
66
|
-
"serve"
|
|
67
|
-
]
|
|
64
|
+
"args": ["mcp", "serve"]
|
|
68
65
|
}
|
|
69
66
|
},
|
|
70
67
|
"skills": [
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,114 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.22 — 2026-10-25(把"只测了两个子命令"的漏测补上,把"不是缺陷"的两条说准)
|
|
4
|
+
|
|
5
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何运行时语义、
|
|
6
|
+
**没有**动 mutation 阈值、**没有**碰发布流程;三个代码切片各自只加守卫、**零清单改动**,本切片只做
|
|
7
|
+
**版本锁步 + 生成清单重生成 + 这段 CHANGELOG**。
|
|
8
|
+
|
|
9
|
+
**一句话:`peaks mut` 指向一个**不存在**的 `--test-files` 时,`mut mutants` 过去会**静默回退**到默认发现,
|
|
10
|
+
为一个从未存在过的文件报出**满分 kill rate**(exit 0)—— 而最初的记录只测了 `run` 与 `asserts`、**漏了
|
|
11
|
+
`mutants`**;这一版三个子命令统一 **exit 1 + 具名码 `MUT_TEST_FILE_NOT_FOUND`**。**
|
|
12
|
+
|
|
13
|
+
### 1. 缺陷:`peaks mut` 缺失 `--test-files` 路径时的静默回退(三个子命令这一版统一堵上)
|
|
14
|
+
|
|
15
|
+
同一夹具、同一台机器上的**前后两侧实测**(改前取自 `HEAD` 的隔离树,改后取自本仓库的工作树):
|
|
16
|
+
|
|
17
|
+
| 子命令 | 改前 | 改后 |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `mut mutants` | **exit 0、写出了报告、killRate 1、mutantsTotal 2** | **exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告** |
|
|
20
|
+
| `mut run` | exit 1 `MUT_FAILED`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
|
|
21
|
+
| `mut asserts` | exit 1 `UNHANDLED_ERROR`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
|
|
22
|
+
|
|
23
|
+
**"静默回退"不是推测,是可比对的 digest。** 改前 `mut mutants` + 缺失文件写出的报告,digest 与
|
|
24
|
+
`mut mutants` + **一个能用的 glob** 写出的报告**完全相同**(两者都是 `339e74cc…`)—— 缺失的路径被
|
|
25
|
+
Stryker 的文件匹配丢掉,vitest runner 跑了项目自己的默认发现,然后为一个**从未存在过的文件**报出了满分。
|
|
26
|
+
改后同一个 glob 仍然 exit 0、digest 仍是 `339e74cc…`(能用的 glob 保持能用),而缺失文件一律 exit 1。
|
|
27
|
+
|
|
28
|
+
改后三个子命令的消息**逐字节相同**,且**只给相对 `--project` 的路径**,并附近邻候选:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
Test file not found: tests/does-not-exist.test.ts
|
|
32
|
+
Near-miss candidates:
|
|
33
|
+
- tests/add.test.ts
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**快乐路径没变**:有效测试文件下 `mut run` 的报告 digest 改前改后**都是 `96595ff6…`**(`killRate` 1、
|
|
37
|
+
`mutantsTotal` 2)。守卫 `tests/unit/cli/mut-test-file-not-found.test.ts` **15 个用例全绿**。
|
|
38
|
+
|
|
39
|
+
**这一段要更正的是一条"不可复现"的判断。** 最初的记录写的是"缺失 `--test-files` 路径静默回退默认发现、
|
|
40
|
+
可能报出完美 kill rate"**不可复现** —— 那条判断**只测了 `run` 与 `asserts`**,**漏了 `mutants`**;在
|
|
41
|
+
`mutants` 上它**确实复现**(exit 0 + 满分 kill rate)。本批的三个子命令现在统一成同一个具名码。
|
|
42
|
+
|
|
43
|
+
### 2. 生成的插件清单:`prettier --check` 从 exit 1 变成 exit 0(本次 bump 没有把形状缺陷带回来)
|
|
44
|
+
|
|
45
|
+
清单是**受版本控制的生成产物**(`npm run plugin:manifest`),渲染器过去把**每个**数组都展开,
|
|
46
|
+
所以清单**不是** prettier-clean 的。实测(用仓库自己的 prettier 与仓库自己的 prettier 配置):
|
|
47
|
+
|
|
48
|
+
| | 改前(`HEAD` 的渲染) | 改后(本切片 bump 之后的渲染) |
|
|
49
|
+
|---|---|---|
|
|
50
|
+
| `prettier --check` | **exit 1(不是 prettier-clean)** | **exit 0** |
|
|
51
|
+
| 行数(按换行计数) | 200 | **197** |
|
|
52
|
+
| 行数(按 `split("\n").length`) | 201 | **198** |
|
|
53
|
+
|
|
54
|
+
唯一的变化是 `"args": ["mcp", "serve"]`(4 行 → 1 行)。改前的清单经 prettier 规范化后的输出,
|
|
55
|
+
sha256 是 `849e6168…`,与**本切片 bump 之前**工作树里那份清单(切片 B 的渲染,版本 4.1.21)
|
|
56
|
+
**逐字节相同** —— 说明新的渲染器产出的正是 prettier 自己的形状。本切片 bump 之后的清单
|
|
57
|
+
sha256 是 `fd087f50…`,同样 prettier-clean。
|
|
58
|
+
|
|
59
|
+
**依赖集不变**:根 manifest 的 `dependencies`(12 项)与 `devDependencies`(19 项)与 bump 前**逐字段相同**
|
|
60
|
+
(本切片实测:五个 manifest 各自只有 `version` 一个键变了);`prettier` 仍在 `devDependencies`、
|
|
61
|
+
**不在** `dependencies`(实测 `prettier in dependencies: false`),发布包的运行时依赖集没有变化。
|
|
62
|
+
|
|
63
|
+
**版本戳在两处**:`metadata.version` 与 `plugins[0].version` 都读 `4.1.22`;连跑两次生成**逐字节相同**
|
|
64
|
+
(sha256 `fd087f50…`)。
|
|
65
|
+
|
|
66
|
+
### 3. 包入口不变量(只加守卫,**零清单改动**)
|
|
67
|
+
|
|
68
|
+
根包声明 **1** 个入口(`bin.peaks → ./bin/peaks.js`),`peaks-loop-mut` 声明 **2** 个
|
|
69
|
+
(`exports["."].types`、`exports["."].default`)。守卫 `tests/unit/release/package-entry-points-guard.test.ts`
|
|
70
|
+
**9 passed | 1 skipped**(构建产物在 → 磁盘检查**跑起来**:2 checked、0 skipped)。守卫钉住三条不变量:
|
|
71
|
+
声明的入口必须落在该包自己的 `files` 白名单里;`main` 与 `exports["."].default` 若同时声明必须一致;
|
|
72
|
+
根包**不得**把副作用型 CLI 模块声明成库入口。
|
|
73
|
+
|
|
74
|
+
### 4. 两条必须说准的事(一条"不是缺陷",一条"更正旧判断")
|
|
75
|
+
|
|
76
|
+
**(1)"包缺 `main`"不是缺陷 —— 它不是这次修的东西。** `peaks-loop-mut` 的主入口**已经**由 `exports["."]` 表达
|
|
77
|
+
(`exports["."].default → ./dist/index.js`)。实测(本机 Node v24.12.0):
|
|
78
|
+
|
|
79
|
+
- 一个同时声明 `main` 与 `exports` 的包,被 import 时加载的是 **`exports`** 那个目标(输出 `LOADED:EXPORTS`)
|
|
80
|
+
—— Node 解析 `exports` 优先于 `main`,`main` 被忽略;
|
|
81
|
+
- **`require()` 一个纯 ESM 包在 Node v24.12.0 上是成功的**(实测 `REQUIRE_OK`;`ERR_REQUIRE_ESM`
|
|
82
|
+
只对 Node < 22.12 成立)。所以诚实的理由是**"冗余且会误导"**,而**不是**"无法 require";
|
|
83
|
+
- 根包则**绝不能**加 `main`/`exports`:`dist/cli/index.js` 在**模块顶层**就
|
|
84
|
+
`program.parseAsync(process.argv)`(`src/cli/index.ts:61`),实测**import 它就会把 CLI 跑起来**
|
|
85
|
+
—— 导入过程中就打出了 CLI 的帮助横幅。
|
|
86
|
+
|
|
87
|
+
**(2)"静默回退不可复现"这条旧判断本身不成立 —— 这一版是真的堵上了。** 它在 `mut mutants` 上**确实复现**
|
|
88
|
+
(exit 0 + 满分 kill rate),缺的只是那次测量里的**第三个子命令**。所以这里不是"没有缺陷",而是
|
|
89
|
+
"缺陷是真的、这一版三个子命令统一堵上了"。
|
|
90
|
+
|
|
91
|
+
### 5. 版本号本身
|
|
92
|
+
|
|
93
|
+
| 包 | 从 | 到 |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `peaks-loop` | 4.1.21 | **4.1.22** |
|
|
96
|
+
| `peaks-loop-shared` | 0.0.110 | 0.0.111 |
|
|
97
|
+
| `peaks-loop-mut` | 0.1.75 | 0.1.76 |
|
|
98
|
+
| `peaks-loop-shared-channel` | 0.0.78 | 0.0.79 |
|
|
99
|
+
| `peaks-loop-internal-runtime` | 0.0.61 | 0.0.62 |
|
|
100
|
+
|
|
101
|
+
版本号由 `scripts/bump-version.mjs` 产生(不是手打的):根 `4.1.21 → 4.1.22`,四个 workspace 包在同一次
|
|
102
|
+
lockstep 里各 +1,五个 manifest **各自只有 `version` 一个键变了**;`scripts/sync-version.mjs` 把
|
|
103
|
+
`CLI_VERSION` 与 `RUNTIME_VERSION` 写成 `4.1.22`,`node scripts/verify-version-parity.mjs runtime-src`
|
|
104
|
+
**exit 0**。
|
|
105
|
+
|
|
106
|
+
**发布顺序(发版前必须知道)**:`pnpm pack` 会把根包 `workspace:*` 依赖改写成**精确 semver pin**,
|
|
107
|
+
所以 `peaks-loop@4.1.22` 打包后的 manifest 依赖的是 `peaks-loop-mut@0.1.76`、
|
|
108
|
+
`peaks-loop-shared@0.0.111`、`peaks-loop-shared-channel@0.0.79`、`peaks-loop-internal-runtime@0.0.62`
|
|
109
|
+
(实测:从 tarball 里读出的 `package/package.json`)。这四个版本**在 registry 上都不存在**(实测 `E404`),
|
|
110
|
+
所以**这四个包必须先发布**,`peaks-loop@4.1.22` 才能被消费者装上;在它们发布之前,根包是不可安装的。
|
|
111
|
+
|
|
3
112
|
## 4.1.21 — 2026-10-25(把"返工循环"数对,把"没测过"说出来)
|
|
4
113
|
|
|
5
114
|
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改 fail-open 策略、
|
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
* toolchain must surface a MACHINE-READABLE error code (for example
|
|
14
14
|
* `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
|
|
15
15
|
* non-zero exit code — never `UNHANDLED_ERROR` with a bare
|
|
16
|
-
* "Cannot find package".
|
|
16
|
+
* "Cannot find package". The same rule now covers a missing `--test-files`
|
|
17
|
+
* path (`MUT_TEST_FILE_NOT_FOUND`).
|
|
17
18
|
*/
|
|
18
19
|
import { Command } from 'commander';
|
|
19
20
|
import { type AssertionsReport, type MutationReport, type StrykerInvoker } from 'peaks-loop-mut';
|
|
@@ -75,16 +76,15 @@ export declare function mutErrorCode(err: unknown): string;
|
|
|
75
76
|
/** The human-readable half of the envelope. */
|
|
76
77
|
export declare function mutErrorMessage(err: unknown): string;
|
|
77
78
|
/**
|
|
78
|
-
* Emit the failure envelope on stderr and set a non-zero exit code.
|
|
79
|
-
*
|
|
80
|
-
*
|
|
79
|
+
* Emit the failure envelope on stderr and set a non-zero exit code. Its
|
|
80
|
+
* `data` field carries the machine-readable detail — where an ABSOLUTE path
|
|
81
|
+
* belongs; stdout stays reserved for the `--json` payload (R6).
|
|
81
82
|
*/
|
|
82
83
|
export declare function emitMutError(io: ProgramIO, err: unknown): void;
|
|
83
84
|
/**
|
|
84
85
|
* `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
|
|
85
86
|
* report). One-axis: --session-id required.
|
|
86
|
-
*/
|
|
87
|
-
export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
|
|
87
|
+
*/ export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
|
|
88
88
|
/**
|
|
89
89
|
* `peaks mut mutants` — Stryker only; writes a stub-assertions
|
|
90
90
|
* mut-report.json. One-axis: --session-id required.
|
|
@@ -13,10 +13,11 @@
|
|
|
13
13
|
* toolchain must surface a MACHINE-READABLE error code (for example
|
|
14
14
|
* `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
|
|
15
15
|
* non-zero exit code — never `UNHANDLED_ERROR` with a bare
|
|
16
|
-
* "Cannot find package".
|
|
16
|
+
* "Cannot find package". The same rule now covers a missing `--test-files`
|
|
17
|
+
* path (`MUT_TEST_FILE_NOT_FOUND`).
|
|
17
18
|
*/
|
|
18
19
|
import { Command } from 'commander';
|
|
19
|
-
import { buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
|
|
20
|
+
import { assertTestFilesUsable, buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
|
|
20
21
|
import { printErrorEnvelope } from '../cli-helpers.js';
|
|
21
22
|
/**
|
|
22
23
|
* Fallback code for a mutation failure that carries no named code of its
|
|
@@ -98,18 +99,27 @@ export function mutErrorMessage(err) {
|
|
|
98
99
|
return err instanceof Error ? err.message : String(err);
|
|
99
100
|
}
|
|
100
101
|
/**
|
|
101
|
-
* Emit the failure envelope on stderr and set a non-zero exit code.
|
|
102
|
-
*
|
|
103
|
-
*
|
|
102
|
+
* Emit the failure envelope on stderr and set a non-zero exit code. Its
|
|
103
|
+
* `data` field carries the machine-readable detail — where an ABSOLUTE path
|
|
104
|
+
* belongs; stdout stays reserved for the `--json` payload (R6).
|
|
104
105
|
*/
|
|
105
106
|
export function emitMutError(io, err) {
|
|
106
|
-
|
|
107
|
+
const details = err?.details;
|
|
108
|
+
const data = details && typeof details === 'object' ? details : {};
|
|
109
|
+
printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), data, []);
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Validate `--test-files` BEFORE any Stryker run, scan or report write: a
|
|
113
|
+
* missing path must fail with the named code, never reach the mutation
|
|
114
|
+
* engine. A PATTERN is accepted here — Stryker expands patterns.
|
|
115
|
+
*/
|
|
116
|
+
function assertMutTestFiles(a) {
|
|
117
|
+
assertTestFilesUsable({ project: a.project, testFiles: a.testFiles, allowPatterns: true });
|
|
107
118
|
}
|
|
108
119
|
/**
|
|
109
120
|
* `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
|
|
110
121
|
* report). One-axis: --session-id required.
|
|
111
|
-
*/
|
|
112
|
-
export function buildMutRunCommand(invokeStryker, io) {
|
|
122
|
+
*/ export function buildMutRunCommand(invokeStryker, io) {
|
|
113
123
|
return new Command('run')
|
|
114
124
|
.description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
|
|
115
125
|
.requiredOption('--project <path>', 'project root')
|
|
@@ -121,6 +131,7 @@ export function buildMutRunCommand(invokeStryker, io) {
|
|
|
121
131
|
.option('--json', 'machine-readable output', false)
|
|
122
132
|
.action(async (a) => {
|
|
123
133
|
try {
|
|
134
|
+
assertMutTestFiles(a);
|
|
124
135
|
const { mutation } = await runMutation({
|
|
125
136
|
project: a.project,
|
|
126
137
|
testFiles: a.testFiles,
|
|
@@ -172,6 +183,7 @@ export function buildMutMutantsCommand(invokeStryker, io) {
|
|
|
172
183
|
.option('--json', 'machine-readable output', false)
|
|
173
184
|
.action(async (a) => {
|
|
174
185
|
try {
|
|
186
|
+
assertMutTestFiles(a);
|
|
175
187
|
const { mutation } = await runMutation({
|
|
176
188
|
project: a.project,
|
|
177
189
|
testFiles: a.testFiles,
|
|
@@ -213,24 +225,30 @@ export function buildMutAssertsCommand(io) {
|
|
|
213
225
|
.requiredOption('--out <path>', 'output path for mut-report.json')
|
|
214
226
|
.option('--json', 'machine-readable output', false)
|
|
215
227
|
.action(async (a) => {
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
228
|
+
try {
|
|
229
|
+
assertMutTestFiles(a);
|
|
230
|
+
const assertions = await scanAssertions({
|
|
231
|
+
project: a.project,
|
|
232
|
+
testFiles: a.testFiles
|
|
233
|
+
});
|
|
234
|
+
const report = await buildMutReport({
|
|
235
|
+
inputSig: a.inputSig,
|
|
236
|
+
out: a.out,
|
|
237
|
+
mutation: emptyMutation(),
|
|
238
|
+
assertions
|
|
239
|
+
});
|
|
240
|
+
emitSummary(io, a.json, {
|
|
241
|
+
ok: true,
|
|
242
|
+
sha256: report.sha256,
|
|
243
|
+
passed: report.thresholds.passed,
|
|
244
|
+
path: a.out
|
|
245
|
+
});
|
|
246
|
+
if (!report.thresholds.passed) {
|
|
247
|
+
process.exitCode = 1;
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
catch (err) {
|
|
251
|
+
emitMutError(io, err);
|
|
234
252
|
}
|
|
235
253
|
});
|
|
236
254
|
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** The two knobs of prettier's JSON layout a render can depend on. */
|
|
2
|
+
export interface JsonLayoutOptions {
|
|
3
|
+
/** prettier's `printWidth` — the column budget one printed line may use. */
|
|
4
|
+
readonly printWidth: number;
|
|
5
|
+
/** prettier's `tabWidth` — how many spaces one indentation level is. */
|
|
6
|
+
readonly tabWidth: number;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* prettier's own defaults, used when the repository's config says nothing about a
|
|
10
|
+
* knob. They are prettier's, not this repository's: the config file is the one
|
|
11
|
+
* source of truth for the numbers, and a second copy of them here would be a
|
|
12
|
+
* second decision.
|
|
13
|
+
*/
|
|
14
|
+
export declare const DEFAULT_JSON_LAYOUT: JsonLayoutOptions;
|
|
15
|
+
/**
|
|
16
|
+
* Render a JSON value in the layout prettier produces for JSON, newline-terminated.
|
|
17
|
+
*
|
|
18
|
+
* The output is a prettier FIXED POINT: formatting it again returns it unchanged.
|
|
19
|
+
*/
|
|
20
|
+
export declare function renderJsonDocument(value: unknown, options?: JsonLayoutOptions): string;
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
// src/services/distribution/json-layout.ts
|
|
2
|
+
//
|
|
3
|
+
// WHY THIS FILE EXISTS. `.claude-plugin/marketplace.json` is a GENERATED artifact
|
|
4
|
+
// and it SHIPS (the root `package.json#files` allowlist names `.claude-plugin/**`),
|
|
5
|
+
// so its bytes are a published surface. The renderer used to emit it with
|
|
6
|
+
// `JSON.stringify(manifest, null, 2)`, which expands EVERY array regardless of
|
|
7
|
+
// width — so the artifact was not prettier-clean, and `npm run format:check` could
|
|
8
|
+
// not see it: that script covers `src|tests|packages|scripts` × `ts,mts,mjs,js` and
|
|
9
|
+
// no `.json` at all. Nothing asserted the property until a guard did.
|
|
10
|
+
//
|
|
11
|
+
// THE RULE IS PRETTIER'S, AND IT IS REPLICATED HERE WITHOUT PRETTIER. `prettier`
|
|
12
|
+
// is a devDependency. The root `package.json#files` allowlist also names
|
|
13
|
+
// `dist/**/*.js`, so `dist/services/distribution/plugin-manifest.js` — and this
|
|
14
|
+
// module beside it — SHIP to consumers. A static `import 'prettier'` from any
|
|
15
|
+
// module under `src/**` would put an undeclared dependency into every consumer
|
|
16
|
+
// install and fail with `ERR_MODULE_NOT_FOUND` — the same defect class as the
|
|
17
|
+
// 4.1.18→4.1.20 packaging break. A lazy `await import('prettier')` would not fail
|
|
18
|
+
// at import time, but it would still make the SHIPPED renderer's output depend on a
|
|
19
|
+
// package the published manifest does not declare. So the shape is computed here,
|
|
20
|
+
// with ZERO dependencies, and the shape does not drift when prettier is upgraded.
|
|
21
|
+
//
|
|
22
|
+
// THE TWO RULES, AS PRETTIER APPLIES THEM TO JSON.
|
|
23
|
+
//
|
|
24
|
+
// 1. OBJECTS. prettier keeps an object expanded when the source has a newline
|
|
25
|
+
// between `{` and its first key, and collapses it otherwise. This renderer
|
|
26
|
+
// always emits the newline, so every object is expanded — and prettier, reading
|
|
27
|
+
// that newline, keeps it expanded. The render is therefore a FIXED POINT of
|
|
28
|
+
// prettier, which is the property the guard asserts.
|
|
29
|
+
//
|
|
30
|
+
// 2. ARRAYS. prettier prints an array on ONE line when it fits the print width,
|
|
31
|
+
// and breaks it one element per line when it does not. On top of that it has
|
|
32
|
+
// one forced-break rule: an array with more than one element where EVERY
|
|
33
|
+
// element is an object or an array, all of the same kind, and each holding
|
|
34
|
+
// more than one member, breaks even when it would fit.
|
|
35
|
+
//
|
|
36
|
+
// The width is measured the way prettier measures it: the printed line, from its
|
|
37
|
+
// indentation through the value and the separator that follows it, must fit inside
|
|
38
|
+
// `printWidth`. A value therefore knows the column it starts at, the text already
|
|
39
|
+
// on its line, and the text that follows it before the next break.
|
|
40
|
+
//
|
|
41
|
+
// MEASURED, NOT ASSUMED. This rule was differential-tested against the installed
|
|
42
|
+
// prettier over 3000 generated manifests: the render equalled
|
|
43
|
+
// `prettier.format(JSON.stringify(value, null, 2))` in 3000 of 3000 cases, and
|
|
44
|
+
// `prettier.format(render(value)) === render(value)` in 3000 of 3000. The guard
|
|
45
|
+
// that keeps the property is
|
|
46
|
+
// `tests/unit/services/distribution/plugin-manifest-prettier-clean.test.ts`.
|
|
47
|
+
/**
|
|
48
|
+
* prettier's own defaults, used when the repository's config says nothing about a
|
|
49
|
+
* knob. They are prettier's, not this repository's: the config file is the one
|
|
50
|
+
* source of truth for the numbers, and a second copy of them here would be a
|
|
51
|
+
* second decision.
|
|
52
|
+
*/
|
|
53
|
+
export const DEFAULT_JSON_LAYOUT = { printWidth: 80, tabWidth: 2 };
|
|
54
|
+
function isPrimitive(value) {
|
|
55
|
+
return value === null || typeof value !== 'object';
|
|
56
|
+
}
|
|
57
|
+
function isJsonArray(value) {
|
|
58
|
+
return Array.isArray(value);
|
|
59
|
+
}
|
|
60
|
+
function isJsonObject(value) {
|
|
61
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
62
|
+
}
|
|
63
|
+
/** One JSON literal. `undefined` is not a JSON value, so it reads as `null`. */
|
|
64
|
+
function literal(value) {
|
|
65
|
+
return JSON.stringify(value) ?? 'null';
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* prettier's forced-break rule for arrays. An array breaks even when it would fit
|
|
69
|
+
* when it holds more than one element, every element is an object or an array, all
|
|
70
|
+
* of them are the same kind, and each one holds more than one member.
|
|
71
|
+
*/
|
|
72
|
+
function forcesBreak(elements) {
|
|
73
|
+
if (elements.length <= 1)
|
|
74
|
+
return false;
|
|
75
|
+
return elements.every((element, index, all) => {
|
|
76
|
+
const next = all[index + 1];
|
|
77
|
+
if (isJsonArray(element)) {
|
|
78
|
+
if (next !== undefined && !isJsonArray(next))
|
|
79
|
+
return false;
|
|
80
|
+
return element.length > 1;
|
|
81
|
+
}
|
|
82
|
+
if (isJsonObject(element)) {
|
|
83
|
+
if (next !== undefined && !isJsonObject(next))
|
|
84
|
+
return false;
|
|
85
|
+
return Object.keys(element).length > 1;
|
|
86
|
+
}
|
|
87
|
+
return false;
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* A non-empty object anywhere below this value forces every enclosing array to
|
|
92
|
+
* break: this renderer always expands an object, and an expanded member breaks the
|
|
93
|
+
* group that holds it.
|
|
94
|
+
*/
|
|
95
|
+
function containsObject(value) {
|
|
96
|
+
if (isPrimitive(value))
|
|
97
|
+
return false;
|
|
98
|
+
if (isJsonArray(value))
|
|
99
|
+
return value.some(containsObject);
|
|
100
|
+
if (isJsonObject(value))
|
|
101
|
+
return Object.keys(value).length > 0;
|
|
102
|
+
return false;
|
|
103
|
+
}
|
|
104
|
+
/** A forced-break array anywhere below this value breaks every enclosing array. */
|
|
105
|
+
function containsForcedBreak(value) {
|
|
106
|
+
if (isPrimitive(value))
|
|
107
|
+
return false;
|
|
108
|
+
if (isJsonArray(value))
|
|
109
|
+
return forcesBreak(value) || value.some(containsForcedBreak);
|
|
110
|
+
return false;
|
|
111
|
+
}
|
|
112
|
+
/** The one-line rendering of a value — the width an enclosing array measures. */
|
|
113
|
+
function flatText(value) {
|
|
114
|
+
if (isPrimitive(value))
|
|
115
|
+
return literal(value);
|
|
116
|
+
if (isJsonArray(value))
|
|
117
|
+
return `[${value.map(flatText).join(', ')}]`;
|
|
118
|
+
if (!isJsonObject(value))
|
|
119
|
+
return 'null';
|
|
120
|
+
const keys = Object.keys(value);
|
|
121
|
+
if (keys.length === 0)
|
|
122
|
+
return '{}';
|
|
123
|
+
const members = keys.map((key) => `${JSON.stringify(key)}: ${flatText(value[key])}`);
|
|
124
|
+
return `{ ${members.join(', ')} }`;
|
|
125
|
+
}
|
|
126
|
+
function renderValue(value, context) {
|
|
127
|
+
if (isPrimitive(value))
|
|
128
|
+
return literal(value);
|
|
129
|
+
if (isJsonArray(value))
|
|
130
|
+
return renderArray(value, context);
|
|
131
|
+
if (isJsonObject(value))
|
|
132
|
+
return renderObject(value, context);
|
|
133
|
+
return literal(value);
|
|
134
|
+
}
|
|
135
|
+
/** One array, either on one line or one element per line. */
|
|
136
|
+
function renderArray(elements, context) {
|
|
137
|
+
if (elements.length === 0)
|
|
138
|
+
return '[]';
|
|
139
|
+
const flat = `[${elements.map(flatText).join(', ')}]`;
|
|
140
|
+
const fits = context.indent + context.prefixWidth + flat.length + context.suffixWidth <=
|
|
141
|
+
context.options.printWidth;
|
|
142
|
+
const breakable = forcesBreak(elements) || containsObject(elements) || containsForcedBreak(elements);
|
|
143
|
+
if (fits && !breakable)
|
|
144
|
+
return flat;
|
|
145
|
+
const inner = context.indent + context.options.tabWidth;
|
|
146
|
+
const pad = ' '.repeat(inner);
|
|
147
|
+
const body = elements
|
|
148
|
+
.map((element, index) => {
|
|
149
|
+
const child = {
|
|
150
|
+
options: context.options,
|
|
151
|
+
indent: inner,
|
|
152
|
+
prefixWidth: 0,
|
|
153
|
+
suffixWidth: index === elements.length - 1 ? 0 : 1
|
|
154
|
+
};
|
|
155
|
+
return pad + renderValue(element, child);
|
|
156
|
+
})
|
|
157
|
+
.join(',\n');
|
|
158
|
+
return `[\n${body}\n${' '.repeat(context.indent)}]`;
|
|
159
|
+
}
|
|
160
|
+
/** One object, always expanded — the newline after `{` is what keeps it so. */
|
|
161
|
+
function renderObject(value, context) {
|
|
162
|
+
const keys = Object.keys(value);
|
|
163
|
+
if (keys.length === 0)
|
|
164
|
+
return '{}';
|
|
165
|
+
const inner = context.indent + context.options.tabWidth;
|
|
166
|
+
const pad = ' '.repeat(inner);
|
|
167
|
+
const body = keys
|
|
168
|
+
.map((key, index) => {
|
|
169
|
+
const keyText = JSON.stringify(key);
|
|
170
|
+
const child = {
|
|
171
|
+
options: context.options,
|
|
172
|
+
indent: inner,
|
|
173
|
+
// the `": "` that follows the key
|
|
174
|
+
prefixWidth: keyText.length + 2,
|
|
175
|
+
suffixWidth: index === keys.length - 1 ? 0 : 1
|
|
176
|
+
};
|
|
177
|
+
return `${pad}${keyText}: ${renderValue(value[key], child)}`;
|
|
178
|
+
})
|
|
179
|
+
.join(',\n');
|
|
180
|
+
return `{\n${body}\n${' '.repeat(context.indent)}}`;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Render a JSON value in the layout prettier produces for JSON, newline-terminated.
|
|
184
|
+
*
|
|
185
|
+
* The output is a prettier FIXED POINT: formatting it again returns it unchanged.
|
|
186
|
+
*/
|
|
187
|
+
export function renderJsonDocument(value, options = DEFAULT_JSON_LAYOUT) {
|
|
188
|
+
const text = renderValue(value, {
|
|
189
|
+
options,
|
|
190
|
+
indent: 0,
|
|
191
|
+
prefixWidth: 0,
|
|
192
|
+
suffixWidth: 0
|
|
193
|
+
});
|
|
194
|
+
return `${text}\n`;
|
|
195
|
+
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type SkillMetadata } from '../skills/skill-registry.js';
|
|
2
|
+
import { type JsonLayoutOptions } from './json-layout.js';
|
|
2
3
|
/** Where the generator writes, relative to the package root. */
|
|
3
4
|
export declare const PLUGIN_MANIFEST_RELATIVE_PATH = ".claude-plugin/marketplace.json";
|
|
4
5
|
/**
|
|
@@ -20,6 +21,16 @@ interface PackageManifest {
|
|
|
20
21
|
} | string;
|
|
21
22
|
readonly license?: string;
|
|
22
23
|
readonly keywords?: readonly string[];
|
|
24
|
+
/**
|
|
25
|
+
* The repository's own prettier config — the source of truth for the layout the
|
|
26
|
+
* artifact is rendered in. Read from the SAME package.json the plugin-level
|
|
27
|
+
* fields come from, so the render and the check that guards it cannot disagree
|
|
28
|
+
* about the width.
|
|
29
|
+
*/
|
|
30
|
+
readonly prettier?: {
|
|
31
|
+
readonly printWidth?: number;
|
|
32
|
+
readonly tabWidth?: number;
|
|
33
|
+
};
|
|
23
34
|
}
|
|
24
35
|
/** One plugin entry's skill list item — the shape `peaks skill:visibility` reads. */
|
|
25
36
|
interface PluginSkillEntry {
|
|
@@ -78,8 +89,26 @@ export declare function skillEntriesOf(skills: readonly SkillMetadata[]): readon
|
|
|
78
89
|
* caller that must fail loudly on an unreadable SKILL.md can do so once.
|
|
79
90
|
*/
|
|
80
91
|
export declare function generatePluginManifest(manifest: PackageManifest, skills: readonly SkillMetadata[]): GeneratedPluginManifest;
|
|
81
|
-
/**
|
|
82
|
-
|
|
92
|
+
/**
|
|
93
|
+
* The layout the repository's own prettier config asks for, read from the ROOT
|
|
94
|
+
* package.json. Exported so the guard that checks the artifact resolves the layout
|
|
95
|
+
* the same way the renderer does — two resolutions would be two decisions.
|
|
96
|
+
*/
|
|
97
|
+
export declare function repositoryJsonLayout(): JsonLayoutOptions;
|
|
98
|
+
/**
|
|
99
|
+
* The artifact's bytes, newline-terminated — the same serialization contract as the
|
|
100
|
+
* whitelist, in the layout prettier produces for JSON.
|
|
101
|
+
*
|
|
102
|
+
* `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
|
|
103
|
+
* regardless of width, so the committed artifact was not prettier-clean. The shape
|
|
104
|
+
* is now computed by `json-layout.ts`, which implements prettier's JSON rules with
|
|
105
|
+
* ZERO dependencies — `prettier` is a devDependency, and this module ships to
|
|
106
|
+
* consumers inside `dist/**`, so it must not depend on it.
|
|
107
|
+
*
|
|
108
|
+
* The default layout is the repository's own, read from the root `package.json`;
|
|
109
|
+
* a caller rendering for another root passes the layout it resolved there.
|
|
110
|
+
*/
|
|
111
|
+
export declare function serializePluginManifest(manifest: GeneratedPluginManifest, options?: JsonLayoutOptions): string;
|
|
83
112
|
/** Absolute path of the committed artifact for a package root. */
|
|
84
113
|
export declare function pluginManifestPath(root?: string): string;
|
|
85
114
|
/**
|
|
@@ -28,6 +28,7 @@ import { readFileSync } from 'node:fs';
|
|
|
28
28
|
import { dirname, join, relative } from 'node:path';
|
|
29
29
|
import { repoRoot } from 'peaks-loop-shared/paths';
|
|
30
30
|
import { loadSkillRegistry } from '../skills/skill-registry.js';
|
|
31
|
+
import { DEFAULT_JSON_LAYOUT, renderJsonDocument } from './json-layout.js';
|
|
31
32
|
/** Where the generator writes, relative to the package root. */
|
|
32
33
|
export const PLUGIN_MANIFEST_RELATIVE_PATH = '.claude-plugin/marketplace.json';
|
|
33
34
|
/**
|
|
@@ -97,9 +98,43 @@ export function generatePluginManifest(manifest, skills) {
|
|
|
97
98
|
]
|
|
98
99
|
};
|
|
99
100
|
}
|
|
100
|
-
/**
|
|
101
|
-
|
|
102
|
-
|
|
101
|
+
/**
|
|
102
|
+
* The layout the repository's own prettier config asks for.
|
|
103
|
+
*
|
|
104
|
+
* The config file is the ONE source of truth for `printWidth`; a second copy of the
|
|
105
|
+
* number here would be a second decision, and the artifact would drift from the
|
|
106
|
+
* tool that checks it the first time either moved. Absent config falls back to
|
|
107
|
+
* prettier's own defaults.
|
|
108
|
+
*/
|
|
109
|
+
function jsonLayoutOf(manifest) {
|
|
110
|
+
return {
|
|
111
|
+
printWidth: manifest.prettier?.printWidth ?? DEFAULT_JSON_LAYOUT.printWidth,
|
|
112
|
+
tabWidth: manifest.prettier?.tabWidth ?? DEFAULT_JSON_LAYOUT.tabWidth
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* The layout the repository's own prettier config asks for, read from the ROOT
|
|
117
|
+
* package.json. Exported so the guard that checks the artifact resolves the layout
|
|
118
|
+
* the same way the renderer does — two resolutions would be two decisions.
|
|
119
|
+
*/
|
|
120
|
+
export function repositoryJsonLayout() {
|
|
121
|
+
return jsonLayoutOf(loadPackageManifest());
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* The artifact's bytes, newline-terminated — the same serialization contract as the
|
|
125
|
+
* whitelist, in the layout prettier produces for JSON.
|
|
126
|
+
*
|
|
127
|
+
* `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
|
|
128
|
+
* regardless of width, so the committed artifact was not prettier-clean. The shape
|
|
129
|
+
* is now computed by `json-layout.ts`, which implements prettier's JSON rules with
|
|
130
|
+
* ZERO dependencies — `prettier` is a devDependency, and this module ships to
|
|
131
|
+
* consumers inside `dist/**`, so it must not depend on it.
|
|
132
|
+
*
|
|
133
|
+
* The default layout is the repository's own, read from the root `package.json`;
|
|
134
|
+
* a caller rendering for another root passes the layout it resolved there.
|
|
135
|
+
*/
|
|
136
|
+
export function serializePluginManifest(manifest, options = repositoryJsonLayout()) {
|
|
137
|
+
return renderJsonDocument(manifest, options);
|
|
103
138
|
}
|
|
104
139
|
/** Absolute path of the committed artifact for a package root. */
|
|
105
140
|
export function pluginManifestPath(root = repoRoot) {
|
|
@@ -122,5 +157,6 @@ export async function renderPluginManifest(root = repoRoot) {
|
|
|
122
157
|
const named = skills.failures.map((failure) => failure.skillPath).join(', ');
|
|
123
158
|
throw new Error(`Refusing to render the plugin manifest: unreadable skill(s): ${named}`);
|
|
124
159
|
}
|
|
125
|
-
|
|
160
|
+
const pkg = loadPackageManifest(root);
|
|
161
|
+
return serializePluginManifest(generatePluginManifest(pkg, skills.skills), jsonLayoutOf(pkg));
|
|
126
162
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peaks-loop",
|
|
3
|
-
"version": "4.1.
|
|
3
|
+
"version": "4.1.22",
|
|
4
4
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
5
5
|
"author": "SquabbyZ",
|
|
6
6
|
"keywords": [
|
|
@@ -132,10 +132,10 @@
|
|
|
132
132
|
"picomatch": "4.0.7",
|
|
133
133
|
"yaml": "^2.9.1",
|
|
134
134
|
"zod": "^4.6.7",
|
|
135
|
-
"peaks-loop-
|
|
136
|
-
"peaks-loop-
|
|
137
|
-
"peaks-loop-shared": "0.0.
|
|
138
|
-
"peaks-loop-shared-channel": "0.0.
|
|
135
|
+
"peaks-loop-internal-runtime": "0.0.62",
|
|
136
|
+
"peaks-loop-mut": "0.1.76",
|
|
137
|
+
"peaks-loop-shared": "0.0.111",
|
|
138
|
+
"peaks-loop-shared-channel": "0.0.79"
|
|
139
139
|
},
|
|
140
140
|
"devDependencies": {
|
|
141
141
|
"@changesets/cli": "2.31.1",
|