create-clis 1.0.0 → 1.2.0

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.
Files changed (88) hide show
  1. package/README.md +22 -14
  2. package/README.zh-CN.md +22 -14
  3. package/assets/manifest.json +7 -2
  4. package/assets/template/.github/ISSUE_TEMPLATE/bug_report.yml +15 -29
  5. package/assets/template/.github/ISSUE_TEMPLATE/feature_request.yml +6 -12
  6. package/assets/template/.github/PULL_REQUEST_TEMPLATE.md +3 -3
  7. package/assets/template/.github/workflows/ci.yml +69 -7
  8. package/assets/template/.github/workflows/release.yml +23 -23
  9. package/assets/template/.gitignorerc.json +1 -8
  10. package/assets/template/.oxlintrc.json +1 -6
  11. package/assets/template/.prettierignore +0 -1
  12. package/assets/template/.releaserc.json +6 -1
  13. package/assets/template/.vscode/launch.json +1 -1
  14. package/assets/template/.vscode/settings.json +1 -0
  15. package/assets/template/.vscode/tasks.json +45 -0
  16. package/assets/template/AGENTS.md +4 -4
  17. package/assets/template/CONTRIBUTING.md +6 -4
  18. package/assets/template/CONTRIBUTING.zh-CN.md +6 -4
  19. package/assets/template/_gitignore +7 -405
  20. package/assets/template/bunfig.toml +2 -11
  21. package/assets/template/docs/README.md +6 -6
  22. package/assets/template/docs/adrs/README.md +4 -2
  23. package/assets/template/docs/development.md +15 -9
  24. package/assets/template/lefthook.yml +20 -30
  25. package/assets/template/package.json +5 -6
  26. package/assets/template/packages/{{NAME}}/README.md +4 -4
  27. package/assets/template/packages/{{NAME}}/README.zh-CN.md +2 -2
  28. package/assets/template/packages/{{NAME}}/package.json +3 -1
  29. package/assets/template/packages/{{NAME}}/scripts/build.ts +50 -14
  30. package/assets/template/packages/{{NAME}}/scripts/verify-release.test.ts +140 -15
  31. package/assets/template/packages/{{NAME}}/scripts/verify-release.ts +27 -14
  32. package/assets/template/packages/{{NAME}}/tsconfig.build.json +1 -1
  33. package/assets/template/packages/{{NAME}}-cli/README.md +9 -6
  34. package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +6 -3
  35. package/assets/template/packages/{{NAME}}-cli/bin/bunfig.toml +3 -0
  36. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}} +43 -21
  37. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd +8 -17
  38. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts +6 -3
  39. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs +189 -107
  40. package/assets/template/packages/{{NAME}}-cli/package.json +3 -2
  41. package/assets/template/packages/{{NAME}}-cli/scripts/release-artifact.ts +24 -73
  42. package/assets/template/packages/{{NAME}}-cli/scripts/release.fixtures.ts +8 -3
  43. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.test.ts +16 -10
  44. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.ts +8 -52
  45. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts +3 -3
  46. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.ts +8 -68
  47. package/assets/template/packages/{{NAME}}-cli/src/cli.ts +51 -11
  48. package/assets/template/scripts/ci.ts +285 -64
  49. package/assets/template/scripts/install-git-hooks.mjs +10 -0
  50. package/assets/template/scripts/install-git-hooks.test.ts +1 -1
  51. package/assets/template/scripts/lib/npm-trust-parse.ts +169 -0
  52. package/assets/template/scripts/lib/release-cli.ts +299 -0
  53. package/assets/template/scripts/lib/release-verify.ts +148 -15
  54. package/assets/template/scripts/lib/workspace.test.ts +63 -1
  55. package/assets/template/scripts/lib/workspace.ts +132 -42
  56. package/assets/template/scripts/lint-dependency-direction.test.ts +131 -0
  57. package/assets/template/scripts/lint-dependency-direction.ts +130 -0
  58. package/assets/template/scripts/lint-doc-examples.test.ts +45 -9
  59. package/assets/template/scripts/lint-doc-examples.ts +227 -50
  60. package/assets/template/scripts/lint-doc-references.test.ts +36 -0
  61. package/assets/template/scripts/lint-doc-references.ts +142 -57
  62. package/assets/template/scripts/lint-doc-shared.ts +26 -23
  63. package/assets/template/scripts/lint-stray-backups.test.ts +3 -1
  64. package/assets/template/scripts/lint-stray-backups.ts +7 -3
  65. package/assets/template/scripts/npm-trust-guard.test.ts +56 -8
  66. package/assets/template/scripts/npm-trust-guard.ts +116 -200
  67. package/assets/template/scripts/safe-install.ts +28 -23
  68. package/assets/template/scripts/transcription/api-harness.ts +28 -206
  69. package/assets/template/scripts/transcription/compare.test.ts +84 -0
  70. package/assets/template/scripts/transcription/compare.ts +4 -4
  71. package/assets/template/scripts/transcription/corpus.ts +9 -3
  72. package/assets/template/scripts/transcription/fixture.ts +2 -4
  73. package/assets/template/scripts/transcription/make-mutants.ts +116 -37
  74. package/assets/template/scripts/transcription/run-conformance.ts +57 -34
  75. package/assets/template/scripts/transcription/validate-coverage.test.ts +11 -14
  76. package/assets/template/scripts/transcription/validate-coverage.ts +8 -10
  77. package/assets/template/scripts/transcription/validate.ts +18 -3
  78. package/assets/template/tsconfig.json +2 -20
  79. package/assets/template/turbo.jsonc +7 -52
  80. package/bin/bunfig.toml +3 -0
  81. package/bin/create-clis.mjs +165 -104
  82. package/dist/create-clis.js +48 -87681
  83. package/dist/manifest.json +3 -3
  84. package/package.json +9 -5
  85. package/assets/template/packages/{{NAME}}/docs/README.md +0 -21
  86. package/assets/template/packages/{{NAME}}-cli/docs/README.md +0 -21
  87. package/bin/create-clis +0 -35
  88. package/bin/create-clis.cmd +0 -32
@@ -1,29 +1,25 @@
1
1
  /**
2
- * 文档引用闸门: 相对链接 / §章节引用 / ADR 编号的静态一致性。
2
+ * 文档引用闸门: 相对链接 / §章节引用 / ADR 编号与重号检测 / 包 README npm 外链防 404。
3
3
  *
4
- * 动机: 连续两轮全仓漂移审计 (2026-09-30) 反复检出三类引用断裂 (死链 / 幽灵章节 / 幽灵
5
- * ADR), 三类均为确定性可判的事实, 不该等下一轮人工审计才暴露, 故落为提交时闸门。
4
+ * 两级文档模型 (ADR 0019 / docs/designs/docs-layering.md):
5
+ * - 仓库级: `docs/` (纯工程治理、通用设计、仓级 ADR)
6
+ * - 包级: `packages/<pkg>/docs/` (单包及产品主包的全部设计、协议与 ADR)
6
7
  *
7
- * 口径 (保守读数, 宁漏勿误):
8
- * - 相对链接: `](路径)` 解析到仓内文件 / 目录须存在; 支持 `./` 与 `../` (相对本文件) 与 `/`
9
- * (相对仓库根, GitHub 渲染语义) 两种形态; 外链 (含合法 scheme) 与纯锚点 `](#...)` 跳过;
10
- * 围栏代码块内不查 (示例里的路径是示意)。
11
- * - §引用: 只校验「目标明确」的形态: § 前 30 字符窗口内出现 `x.md` 文件名或已知文档别名时,
12
- * 校验目标文档的节号存在性; 裸 `§N` (无目标线索) 一律跳过 —— 跨文档裸引用与泛称
13
- * 「设计文档 §7」无法机械定目标, 回落「本文档」的口径实测全为误报 (2026-09-30)。
14
- * - ADR 编号: `ADR 0005` / `ADR-0005` 形态须有对应两级 `adrs/` 下的 `00XX-*.md` (仓库级
15
- * `docs/adrs/` 或包级 `docs/adrs/`); 行内含
16
- * 「不存在 / 未创建 / 待创建 / 历史」字样时豁免 (文档正在陈述它不存在, 是真话)。
17
- *
18
- * 节号引擎: 收集标题 `## N.` / `### N.M` / `#### N.M.K` 的编号; `§N.M` 的命中规则为编号集合
19
- * 中存在 `N.M` 或以 `N.M.` 开头的编号 (指向 N.M 的任一子节与指向该节同义)。
8
+ * 检查面:
9
+ * 1. 相对链接: `](路径)` 解析到仓内文件/目录须存在; 外链、纯锚点与围栏代码块跳过;
10
+ * 2. 包 README 逃逸拦截: `packages/<pkg>/README*.md` 面向 npm 发布, 禁止逃出包根 (`../` 或
11
+ * 仓库根 `/...`) 的相对链接, 必须改用 GitHub 绝对链接 (消除 npm 页面 404);
12
+ * 3. §章节引用: 目标明确形态 (`x.md §N` 或别名), 同名文件按「同目录 → 同包 → 全仓」就近消歧;
13
+ * 4. ADR 编号与唯一性: 扫描 `docs/adrs/` 与全部 workspace 包 `packages/<pkg>/docs/adrs/`,
14
+ * 既拦截幽灵编号, 也拦截跨目录重号碰撞。
20
15
  *
21
16
  * 用法: bun scripts/lint-doc-references.ts
22
- * 退出码: 0 全绿; 1 存在断裂 (逐条打印 file:line 定位)。
17
+ * 退出码: 0 全绿; 1 存在断裂。
23
18
  */
24
19
  import { existsSync, readFileSync, readdirSync } from 'node:fs';
25
- import { dirname, join, resolve } from 'node:path';
20
+ import { dirname, join, relative, resolve } from 'node:path';
26
21
 
22
+ import { listWorkspacePackages } from './lib/workspace.ts';
27
23
  import { REPO_ROOT, walkFiles } from './lint-doc-shared.ts';
28
24
 
29
25
  /** 一条断裂发现 */
@@ -35,12 +31,12 @@ export interface RefFinding {
35
31
  message: string;
36
32
  }
37
33
 
38
- /** 文档别名表: 直角引号里的文档「别称」到仓库相对路径; 实测出现即增补 */
34
+ /** 文档别名表 (保留既有通用称谓映射; 仅在目标文件真实存在时参与解析) */
39
35
  export const DOC_ALIASES: Readonly<Record<string, string>> = {
40
36
  '可编程 API 面': 'packages/{{NAME}}/docs/designs/api-surface.md',
41
- 行为契约: 'docs/sweep/protocol/behavior-contract.md',
42
- 覆盖表: 'docs/sweep/protocol/conformance/coverage.md',
43
- 安全防护: 'docs/sweep/designs/safety-guardrails.md',
37
+ 行为契约: 'packages/{{NAME}}/docs/protocol/behavior-contract.md',
38
+ 覆盖表: 'packages/{{NAME}}/docs/protocol/conformance/coverage.md',
39
+ 安全防护: 'packages/{{NAME}}/docs/designs/safety-guardrails.md',
44
40
  };
45
41
 
46
42
  /** ADR 引用的行级豁免词: 文档正在陈述「该 ADR 尚不存在」时不算断裂 */
@@ -54,10 +50,7 @@ export function listDocFiles(root: string): string[] {
54
50
  return walkFiles(root, ['.md']);
55
51
  }
56
52
 
57
- /**
58
- * 围栏代码块内容置空 (保行数, 保行号): ``` 或 ~~~ 围栏, 支持带语言标注的开启行。
59
- * 引用检查在置空后的文本上做, 示例代码里的路径 / § 不参与判定。
60
- */
53
+ /** 围栏代码块内容置空 (保行数, 保行号) */
61
54
  export function stripFencedCode(content: string): string {
62
55
  let fence: string | null = null;
63
56
  return content
@@ -77,7 +70,7 @@ export function stripFencedCode(content: string): string {
77
70
  .join('\n');
78
71
  }
79
72
 
80
- /** 文件名 stem 到仓库相对路径的索引 (同 stem 多值时全部保留, 解析时优先同目录) */
73
+ /** 文件名 stem 到仓库相对路径的索引 */
81
74
  export function buildNameIndex(files: string[]): Map<string, string[]> {
82
75
  const index = new Map<string, string[]>();
83
76
  for (const file of files) {
@@ -89,7 +82,7 @@ export function buildNameIndex(files: string[]): Map<string, string[]> {
89
82
  return index;
90
83
  }
91
84
 
92
- /** 收集一个文档的节号集合 (`## N.` / `### N.M` / `#### N.M.K` 的 N 与 N.M 与 N.M.K) */
85
+ /** 收集一个文档的节号集合 (`## N.` / `### N.M` / `#### N.M.K`) */
93
86
  export function collectSectionNumbers(content: string): Set<string> {
94
87
  const numbers = new Set<string>();
95
88
  for (const m of content.matchAll(/^#{2,5}\s+(\d+(?:\.\d+)*)[.、\s]/gm)) {
@@ -98,7 +91,18 @@ export function collectSectionNumbers(content: string): Set<string> {
98
91
  return numbers;
99
92
  }
100
93
 
101
- /** 校验一个文件里的相对链接 (存在性; 外链 / 纯锚点 / 代码块 / 尖括号占位跳过) */
94
+ /** 提取相对路径所属包前缀 (`packages/<pkg>/`), 非包内返回 null */
95
+ function packagePrefixOf(relPath: string): string | null {
96
+ const m = relPath.match(/^(packages\/[^/]+)(?:\/|$)/);
97
+ return m ? `${m[1]!}/` : null;
98
+ }
99
+
100
+ /** 是否属于可发 npm 的包根 README (`packages/<pkg>/README.md` 或 `README.*.md`) */
101
+ function isPackageRootReadme(relPath: string): boolean {
102
+ return /^packages\/[^/]+\/README(?:\.[^/]+)?\.md$/.test(relPath);
103
+ }
104
+
105
+ /** 校验一个文件里的相对链接 (存在性 + 包根 README 禁止逃逸出包根) */
102
106
  export function findLinkIssues(
103
107
  lines: string[],
104
108
  file: string,
@@ -106,13 +110,16 @@ export function findLinkIssues(
106
110
  ): RefFinding[] {
107
111
  const findings: RefFinding[] = [];
108
112
  const dir = dirname(file);
113
+ const pkgPrefix = isPackageRootReadme(file) ? packagePrefixOf(file) : null;
114
+ const pkgRootAbs =
115
+ pkgPrefix === null ? null : resolve(root, pkgPrefix.slice(0, -1));
116
+
109
117
  for (const [index, line] of lines.entries()) {
110
118
  for (const m of line.matchAll(/\]\(([^)\s]+)\)/g)) {
111
119
  const raw = m[1]!;
112
120
  if (raw.startsWith('#') || raw.includes('://') || raw.startsWith('<')) {
113
121
  continue;
114
122
  }
115
- // 带 scheme 的非 URL 形态 (mailto: 等) 跳过
116
123
  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(raw) && !raw.startsWith('.')) {
117
124
  continue;
118
125
  }
@@ -122,10 +129,35 @@ export function findLinkIssues(
122
129
  try {
123
130
  decoded = decodeURIComponent(pathPart);
124
131
  } catch {
125
- // 非标准编码: 按原样解析
132
+ // 非标准编码按原样解析
126
133
  }
127
- // 协议相对形态 (//host) 不参与; 以 / 开头按仓库根解析 (GitHub 渲染语义); 其余相对本文件
128
134
  if (decoded.startsWith('//')) continue;
135
+
136
+ if (pkgRootAbs !== null) {
137
+ const targetAbs = decoded.startsWith('/')
138
+ ? join(root, decoded)
139
+ : resolve(root, dir, decoded);
140
+ const relFromPkg = relative(pkgRootAbs, targetAbs).replaceAll(
141
+ '\\',
142
+ '/',
143
+ );
144
+ if (
145
+ decoded.startsWith('/') ||
146
+ relFromPkg.startsWith('..') ||
147
+ relFromPkg === '..'
148
+ ) {
149
+ findings.push({
150
+ file,
151
+ line: index + 1,
152
+ kind: 'link',
153
+ reference: raw,
154
+ message:
155
+ '包根 README 禁止指向包目录之外的相对链接 (发布到 npm 后会 404, 请改用 GitHub 绝对 URL)',
156
+ });
157
+ continue;
158
+ }
159
+ }
160
+
129
161
  const target = decoded.startsWith('/')
130
162
  ? join(root, decoded)
131
163
  : resolve(root, dir, decoded);
@@ -143,7 +175,7 @@ export function findLinkIssues(
143
175
  return findings;
144
176
  }
145
177
 
146
- /** 解析 § 引用的目标文档: 窗口内的 `x.md` 文件名或已知别名; 无线索返回 null (跳过) */
178
+ /** 解析 § 引用的目标文档: 按「同目录 → 同包 → 全仓首项」就近消歧 */
147
179
  export function resolveSectionTarget(
148
180
  line: string,
149
181
  refIndex: number,
@@ -154,18 +186,21 @@ export function resolveSectionTarget(
154
186
  Math.max(0, refIndex - SECTION_TARGET_WINDOW),
155
187
  refIndex,
156
188
  );
157
- // 候选文件名要求前置分隔符 (不认窗口起点): 窗口截断会把长名切成残片
158
- // (api-surface.md → rface.md), 残片按 stem 查索引必然落空, 必须由右向左取
159
- // 第一个「能在索引里解析出真实文档」的名字 (离 § 最近者优先)
160
189
  const names: string[] = [];
161
190
  for (const m of before.matchAll(/[^A-Za-z0-9._-]([A-Za-z0-9_-]+\.md)/g)) {
162
191
  names.push(m[1]!);
163
192
  }
193
+ const pkgPrefix = packagePrefixOf(dir);
164
194
  for (const name of names.reverse()) {
165
195
  const candidates = nameIndex.get(name.replace(/\.md$/, ''));
166
196
  if (candidates && candidates.length > 0) {
167
- // 同目录优先, 其次全仓首个 (文档内引用自己的兄弟文档是主流形态)
168
- return candidates.find((c) => c.startsWith(dir + '/')) ?? candidates[0]!;
197
+ const sameDir = candidates.find((c) => dirname(c) === dir);
198
+ if (sameDir !== undefined) return sameDir;
199
+ if (pkgPrefix !== null) {
200
+ const samePkg = candidates.find((c) => c.startsWith(pkgPrefix));
201
+ if (samePkg !== undefined) return samePkg;
202
+ }
203
+ return candidates[0]!;
169
204
  }
170
205
  }
171
206
  for (const [alias, target] of Object.entries(DOC_ALIASES)) {
@@ -174,7 +209,7 @@ export function resolveSectionTarget(
174
209
  return null;
175
210
  }
176
211
 
177
- /** 校验一个文件里的 §章节引用 (仅目标明确形态; 节号须在目标文档的标题编号集合内) */
212
+ /** 校验一个文件里的 §章节引用 */
178
213
  export function findSectionIssues(
179
214
  lines: string[],
180
215
  file: string,
@@ -199,7 +234,7 @@ export function findSectionIssues(
199
234
  const target = resolveSectionTarget(line, m.index, dir, nameIndex);
200
235
  if (target === null) continue;
201
236
  const sections = sectionsOf(target);
202
- if (sections === null) continue; // 目标文档不存在由链接类检查负责
237
+ if (sections === null) continue;
203
238
  const hit = [...sections].some(
204
239
  (n) => n === number || n.startsWith(number + '.'),
205
240
  );
@@ -217,29 +252,79 @@ export function findSectionIssues(
217
252
  return findings;
218
253
  }
219
254
 
220
- /** 收集仓内真实存在的 ADR 编号 (四位): 两级查找面 (docs/adrs 与各包的 docs/adrs; 分层规则见 docs/designs/docs-layering.md) */
221
- export function collectAdrNumbers(root: string): Set<string> {
222
- const numbers = new Set<string>();
255
+ /** 收集仓内全部 ADR 目录 (仓级 docs/adrs + workspace 包级 packages/<pkg>/docs/adrs) */
256
+ function collectAdrDirs(root: string): string[] {
223
257
  const dirs = [join(root, 'docs', 'adrs')];
258
+ const seen = new Set<string>(dirs);
259
+ if (existsSync(join(root, 'package.json'))) {
260
+ try {
261
+ for (const pkg of listWorkspacePackages(root)) {
262
+ const candidate = join(root, pkg.dir, 'docs', 'adrs');
263
+ if (!seen.has(candidate)) {
264
+ seen.add(candidate);
265
+ dirs.push(candidate);
266
+ }
267
+ }
268
+ } catch {
269
+ // 迷你根无 workspaces 时走下方兜底扫描
270
+ }
271
+ }
224
272
  const packagesDir = join(root, 'packages');
225
273
  if (existsSync(packagesDir)) {
226
274
  for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {
227
- if (entry.isDirectory()) {
228
- dirs.push(join(packagesDir, entry.name, 'docs', 'adrs'));
275
+ if (!entry.isDirectory()) continue;
276
+ const candidate = join(packagesDir, entry.name, 'docs', 'adrs');
277
+ if (!seen.has(candidate)) {
278
+ seen.add(candidate);
279
+ dirs.push(candidate);
229
280
  }
230
281
  }
231
282
  }
232
- for (const dir of dirs) {
283
+ return dirs;
284
+ }
285
+
286
+ /** 收集仓内全部 ADR 编号到相对文件路径数组的映射 (用于存在性校验与重号碰撞检测) */
287
+ export function collectAdrIndex(root: string): Map<string, string[]> {
288
+ const index = new Map<string, string[]>();
289
+ for (const dir of collectAdrDirs(root)) {
233
290
  if (!existsSync(dir)) continue;
234
- for (const name of readdirSync(dir)) {
291
+ for (const name of readdirSync(dir).sort()) {
235
292
  const m = name.match(/^(\d{4})-/);
236
- if (m) numbers.add(m[1]!);
293
+ if (!m) continue;
294
+ const num = m[1]!;
295
+ const rel = relative(root, join(dir, name)).replaceAll('\\', '/');
296
+ const list = index.get(num) ?? [];
297
+ list.push(rel);
298
+ index.set(num, list);
237
299
  }
238
300
  }
239
- return numbers;
301
+ return index;
302
+ }
303
+
304
+ /** 收集仓内真实存在的 ADR 编号集合 */
305
+ export function collectAdrNumbers(root: string): Set<string> {
306
+ return new Set(collectAdrIndex(root).keys());
307
+ }
308
+
309
+ /** 校验全仓 ADR 编号是否存在跨目录重号碰撞 */
310
+ export function findDuplicateAdrIssues(
311
+ adrIndex: Map<string, string[]>,
312
+ ): RefFinding[] {
313
+ const findings: RefFinding[] = [];
314
+ for (const [num, files] of adrIndex.entries()) {
315
+ if (files.length <= 1) continue;
316
+ findings.push({
317
+ file: files[1]!,
318
+ line: 1,
319
+ kind: 'adr',
320
+ reference: `ADR ${num}`,
321
+ message: `ADR 编号重号碰撞: ${files.join(' 与 ')}`,
322
+ });
323
+ }
324
+ return findings;
240
325
  }
241
326
 
242
- /** 校验一个文件里的 ADR 编号引用 (不存在即断裂; 行级豁免词命中时跳过) */
327
+ /** 校验一个文件里的 ADR 编号引用 */
243
328
  export function findAdrIssues(
244
329
  lines: string[],
245
330
  file: string,
@@ -258,7 +343,7 @@ export function findAdrIssues(
258
343
  line: index + 1,
259
344
  kind: 'adr',
260
345
  reference: `ADR ${number}`,
261
- message: 'docs/adrs 下没有对应编号的 ADR 文件',
346
+ message: '仓级或包级 docs/adrs 下没有对应编号的 ADR 文件',
262
347
  });
263
348
  }
264
349
  }
@@ -266,13 +351,14 @@ export function findAdrIssues(
266
351
  return findings;
267
352
  }
268
353
 
269
- /** 全仓扫描三类引用 (导出供测试用临时根); 返回全部断裂 */
354
+ /** 全仓扫描引用 (导出供测试用临时根); 返回全部断裂 */
270
355
  export function findAllIssues(root: string = REPO_ROOT): RefFinding[] {
271
356
  const files = listDocFiles(root);
272
357
  const nameIndex = buildNameIndex(files);
273
- const adrNumbers = collectAdrNumbers(root);
358
+ const adrIndex = collectAdrIndex(root);
359
+ const adrNumbers = new Set(adrIndex.keys());
274
360
  const sectionsCache = new Map<string, Set<string>>();
275
- const findings: RefFinding[] = [];
361
+ const findings: RefFinding[] = [...findDuplicateAdrIssues(adrIndex)];
276
362
  for (const file of files) {
277
363
  const lines = stripFencedCode(readFileSync(join(root, file), 'utf8')).split(
278
364
  '\n',
@@ -286,12 +372,12 @@ export function findAllIssues(root: string = REPO_ROOT): RefFinding[] {
286
372
  return findings;
287
373
  }
288
374
 
289
- /** 主流程: 打印全部断裂并以退出码收口 (0 全绿 / 1 有断裂) */
375
+ /** 主流程: 打印全部断裂并以退出码收口 */
290
376
  function main(): void {
291
377
  const findings = findAllIssues();
292
378
  if (findings.length === 0) {
293
379
  process.stdout.write(
294
- '文档引用闸门全绿 ✓ (相对链接 / §章节引用 / ADR 编号)\n',
380
+ '文档引用闸门全绿 ✓ (相对链接 / 包 README npm 外链 / §章节 / ADR 唯一性)\n',
295
381
  );
296
382
  return;
297
383
  }
@@ -304,5 +390,4 @@ function main(): void {
304
390
  process.exitCode = 1;
305
391
  }
306
392
 
307
- // 仅作为入口执行时跑主流程 (被 import 时不执行, 供测试)
308
393
  if (import.meta.main) main();
@@ -1,59 +1,62 @@
1
1
  /**
2
2
  * 文档类静态闸门的共享底座: 仓库根定位与文件走查 (引用闸门 / 示例闸门 / 仓库卫生共用)。
3
- *
4
- * 走查跳过清单统一在此维护: 依赖目录与生成物 (node_modules / .git / .turbo / dist) 不含
5
- * 待查文档, mutants 为变异自证的一次性副本 (源码拷贝, 引用与示例均不适用于副本场景);
6
- * 生成器包的模板空间 (assets / template-skeletons) 的链接与示例只在新项目语境成立, 同跳。
7
3
  */
8
4
  import { readdirSync } from 'node:fs';
9
- import { dirname, join, resolve } from 'node:path';
5
+ import { dirname, join, relative, resolve } from 'node:path';
10
6
  import { fileURLToPath } from 'node:url';
11
7
 
12
8
  /** 仓库根 (scripts/ 的上一级) */
13
9
  export const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
14
10
 
15
- /** 走查跳过目录: 依赖 / 版本控制 / 构建缓存 / 生成物 / 变异副本 */
11
+ /** 走查跳过目录: 依赖 / 版本控制 / 构建缓存 / 生成物 / 变异副本 / 宿主运行时状态 */
16
12
  export const SKIP_DIRS: ReadonlySet<string> = new Set([
17
13
  'node_modules',
18
14
  '.git',
19
15
  '.turbo',
20
16
  'dist',
21
17
  'mutants',
18
+ '.claude',
22
19
  ]);
23
20
 
24
- /**
25
- * 走查跳过路径 (仓库相对目录, 以 `/` 收尾): 生成器包的模板空间 —— assets/ 是按骨架清单产出的
26
- * 构建产物 (结构即新项目根, 占位符链接指向生成后才存在的目标), scripts/template-skeletons/ 是
27
- * 按新项目布局镜像存放的骨架 (链接指向镜像后的占位路径); 二者的引用面只在新项目语境里成立。
28
- * 同款排除见 .gitignore / .prettierignore / .oxlintrc.json / tsconfig.json / bunfig.toml。
29
- */
30
- export const SKIP_PATHS: readonly string[] = [
31
- 'packages/create-clis/assets/',
32
- 'packages/create-clis/scripts/template-skeletons/',
33
- ];
21
+ /** 走查跳过路径 (仓库相对目录, POSIX 斜杠, 以 `/` 收尾) */
22
+ export const SKIP_PATHS: readonly string[] = [];
23
+
24
+ /** 走查选项 */
25
+ export interface WalkFilesOptions {
26
+ skipPaths?: readonly string[];
27
+ }
28
+
29
+ const toPosixRelative = (root: string, abs: string): string =>
30
+ relative(root, abs).replaceAll('\\', '/');
34
31
 
35
- /** 相对路径是否落在跳过面内 (目录前缀匹配) */
36
- function isSkippedPath(relativePath: string): boolean {
37
- return SKIP_PATHS.some((prefix) => `${relativePath}/`.startsWith(prefix));
32
+ function isSkippedPath(
33
+ relativePath: string,
34
+ skipPaths: readonly string[],
35
+ ): boolean {
36
+ return skipPaths.some((prefix) => `${relativePath}/`.startsWith(prefix));
38
37
  }
39
38
 
40
- /** 按扩展名走查文件, 返回仓库相对路径 (字典序, 稳定输出) */
39
+ /** 按扩展名走查文件, 返回仓库相对路径 (POSIX 斜杠, 字典序, 稳定输出) */
41
40
  export function walkFiles(
42
41
  root: string,
43
42
  extensions: readonly string[],
43
+ options: WalkFilesOptions = {},
44
44
  ): string[] {
45
+ const normalizedRoot = resolve(root);
46
+ const skipPaths = options.skipPaths ?? SKIP_PATHS;
45
47
  const out: string[] = [];
46
48
  const walk = (dir: string): void => {
47
49
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
48
50
  if (SKIP_DIRS.has(entry.name)) continue;
49
51
  const abs = join(dir, entry.name);
52
+ const rel = toPosixRelative(normalizedRoot, abs);
50
53
  if (entry.isDirectory()) {
51
- if (!isSkippedPath(abs.slice(root.length + 1))) walk(abs);
54
+ if (!isSkippedPath(rel, skipPaths)) walk(abs);
52
55
  } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
53
- out.push(abs.slice(root.length + 1));
56
+ out.push(rel);
54
57
  }
55
58
  }
56
59
  };
57
- walk(root);
60
+ walk(normalizedRoot);
58
61
  return out.sort();
59
62
  }
@@ -42,12 +42,14 @@ describe('findStrayBackups', () => {
42
42
  expect(findStrayBackups(makeRoot(['README.md', 'a/b/c.json']))).toEqual([]);
43
43
  });
44
44
 
45
- test('嵌套深处的备份同样被抓', () => {
45
+ test('嵌套深处与模板源码目录内的备份同样被抓', () => {
46
46
  const root = makeRoot([
47
47
  'docs/nested/deep/note.md.20260101_000000.modified',
48
+ 'packages/demo/template/app/lib.ts.20260101_000000.modified',
48
49
  ]);
49
50
  expect(findStrayBackups(root)).toEqual([
50
51
  'docs/nested/deep/note.md.20260101_000000.modified',
52
+ 'packages/demo/template/app/lib.ts.20260101_000000.modified',
51
53
  ]);
52
54
  });
53
55
  });
@@ -16,9 +16,13 @@ import { REPO_ROOT, walkFiles } from './lint-doc-shared.ts';
16
16
  /** 备份后缀: 与宪法「修改前置备份」的命名收尾一致 */
17
17
  const BACKUP_SUFFIXES = ['.modified', '.deleted'] as const;
18
18
 
19
- /** 全树找出散落备份 (相对路径, 供测试注入临时根) */
19
+ /**
20
+ * 全树找出散落备份 (相对路径, 供测试注入临时根)。
21
+ * 刻意传 skipPaths: []: 模板目录 (template / template-skeletons) 属源码区, 同样禁止残留备份,
22
+ * 仅跳过 node_modules / .git / .turbo / dist / mutants 等 SKIP_DIRS。
23
+ */
20
24
  export function findStrayBackups(root: string = REPO_ROOT): string[] {
21
- return walkFiles(root, BACKUP_SUFFIXES);
25
+ return walkFiles(root, BACKUP_SUFFIXES, { skipPaths: [] });
22
26
  }
23
27
 
24
28
  /** 主流程: 打印散落清单并以退出码收口 (0 无散落 / 1 有散落) */
@@ -29,7 +33,7 @@ function main(): void {
29
33
  return;
30
34
  }
31
35
  process.stderr.write(
32
- `检出 ${strays.length} 个散落备份 (备份纪律: 移出仓库至 ~/tmp/sweep_backups/, 保留相对结构):\n`,
36
+ `检出 ${strays.length} 个散落备份 (备份纪律: 移出仓库至 ~/tmp/clis_backups/, 保留相对结构):\n`,
33
37
  );
34
38
  for (const stray of strays) process.stderr.write(` ${stray}\n`);
35
39
  process.exitCode = 1;
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * 发布凭据闸门单测: 纯函数层 (远端 URL 派生 / npm trust 输出解析 / 登记对账 / OIDC 环境判定 /
3
- * 预检核对面过滤)。
3
+ * 预检核对面过滤 / ID 白名单 / Linux PTY 转义)。
4
4
  */
5
5
  import { describe, expect, test } from 'bun:test';
6
6
 
@@ -10,6 +10,8 @@ import {
10
10
  deriveRepoFromRemoteUrl,
11
11
  diffTrust,
12
12
  filterPublishable,
13
+ isValidTrustId,
14
+ parseTrustListEntries,
13
15
  parseTrustListOutput,
14
16
  ptyWrapArgs,
15
17
  } from './npm-trust-guard.ts';
@@ -111,6 +113,46 @@ describe('parseTrustListOutput', () => {
111
113
  environment: null,
112
114
  });
113
115
  });
116
+
117
+ test('多条登记按段独立解析, 字段不串味', () => {
118
+ const raw = [
119
+ 'type: github',
120
+ 'id: id-1',
121
+ 'repository: {{OWNER}}/old',
122
+ 'file: old.yml',
123
+ '',
124
+ 'type: github',
125
+ 'id: id-2',
126
+ 'repository: {{OWNER}}/{{NAME}}',
127
+ 'file: release.yml',
128
+ 'environment: release',
129
+ ].join('\n');
130
+ expect(parseTrustListEntries(raw)).toEqual([
131
+ {
132
+ type: 'github',
133
+ id: 'id-1',
134
+ file: 'old.yml',
135
+ repository: '{{OWNER}}/old',
136
+ environment: null,
137
+ },
138
+ {
139
+ type: 'github',
140
+ id: 'id-2',
141
+ file: 'release.yml',
142
+ repository: '{{OWNER}}/{{NAME}}',
143
+ environment: 'release',
144
+ },
145
+ ]);
146
+ });
147
+ });
148
+
149
+ describe('isValidTrustId', () => {
150
+ test('UUID 与常规标识符通过, 含 Shell 元字符或空白拒绝', () => {
151
+ expect(isValidTrustId('625b8bc6-f738-4aac-9a92-70ba2f01ce80')).toBe(true);
152
+ expect(isValidTrustId('id; rm -rf /')).toBe(false);
153
+ expect(isValidTrustId('$(whoami)')).toBe(false);
154
+ expect(isValidTrustId('')).toBe(false);
155
+ });
114
156
  });
115
157
 
116
158
  describe('diffTrust', () => {
@@ -136,8 +178,6 @@ describe('diffTrust', () => {
136
178
  });
137
179
 
138
180
  test('repository 失配逐条列出 (改名事故的典型形态)', () => {
139
- // 失配样本刻意取中性名 (不与仓库自身的名字重合): 它是「另一个仓库名」的任意代表,
140
- // 判定链只比较两值是否相等, 取值本身无语义; 与仓库重名反而会让模板侧的两个值塌缩成同一个
141
181
  const problems = diffTrust(
142
182
  {
143
183
  type: 'github',
@@ -192,14 +232,14 @@ describe('classifyOidcEnv', () => {
192
232
  });
193
233
 
194
234
  describe('ptyWrapArgs', () => {
195
- test('darwin 用 script -q /dev/null 包裹 (退出码透传已实测)', () => {
235
+ test('darwin 用 script -q /dev/null 包裹', () => {
196
236
  expect(ptyWrapArgs('darwin', 'npm', ['trust', 'list', '@x/y'])).toEqual({
197
237
  command: 'script',
198
238
  args: ['-q', '/dev/null', 'npm', 'trust', 'list', '@x/y'],
199
239
  });
200
240
  });
201
241
 
202
- test('linux 用 script -qec 命令串 (实用输入受控无空白)', () => {
242
+ test('linux 用 script -qec 命令串 (安全字符集保洁净)', () => {
203
243
  expect(
204
244
  ptyWrapArgs('linux', 'npm', ['trust', 'github', '--repo', '{{OWNER}}/{{NAME}}']),
205
245
  ).toEqual({
@@ -208,6 +248,15 @@ describe('ptyWrapArgs', () => {
208
248
  });
209
249
  });
210
250
 
251
+ test('linux 对含 Shell 元字符的参数做严格单引号转义防注入', () => {
252
+ expect(
253
+ ptyWrapArgs('linux', 'npm', ['trust', 'revoke', '--id=$(pwn);echo hi']),
254
+ ).toEqual({
255
+ command: 'script',
256
+ args: ['-qec', "npm trust revoke '--id=$(pwn);echo hi'", '/dev/null'],
257
+ });
258
+ });
259
+
211
260
  test('win32 无 script, 降级直跑原命令', () => {
212
261
  expect(ptyWrapArgs('win32', 'npm.cmd', ['trust', 'list'])).toEqual({
213
262
  command: 'npm.cmd',
@@ -217,14 +266,13 @@ describe('ptyWrapArgs', () => {
217
266
  });
218
267
 
219
268
  describe('filterPublishable', () => {
220
- /** 最小 WorkspacePackage 夹具 (过滤只看 manifest.private) */
221
269
  const pkg = (name: string, isPrivate = false): WorkspacePackage => ({
222
270
  name,
223
271
  dir: `packages/${name}`,
224
272
  manifest: isPrivate ? { name, private: true } : { name },
225
273
  });
226
274
 
227
- test('private 包被排除, 非 private 包保留 (核对面与发布链 ignorePrivate 同源)', () => {
275
+ test('private 包被排除, 非 private 包保留', () => {
228
276
  const packages = [
229
277
  pkg('@x/api'),
230
278
  pkg('@x/cli'),
@@ -236,7 +284,7 @@ describe('filterPublishable', () => {
236
284
  ]);
237
285
  });
238
286
 
239
- test('private 字段缺失或非 true (如 false) 均视为可发布, 不误伤', () => {
287
+ test('private 字段缺失或非 true 均视为可发布, 不误伤', () => {
240
288
  const packages: WorkspacePackage[] = [
241
289
  pkg('@x/api'),
242
290
  {