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.
- package/README.md +22 -14
- package/README.zh-CN.md +22 -14
- package/assets/manifest.json +7 -2
- package/assets/template/.github/ISSUE_TEMPLATE/bug_report.yml +15 -29
- package/assets/template/.github/ISSUE_TEMPLATE/feature_request.yml +6 -12
- package/assets/template/.github/PULL_REQUEST_TEMPLATE.md +3 -3
- package/assets/template/.github/workflows/ci.yml +69 -7
- package/assets/template/.github/workflows/release.yml +23 -23
- package/assets/template/.gitignorerc.json +1 -8
- package/assets/template/.oxlintrc.json +1 -6
- package/assets/template/.prettierignore +0 -1
- package/assets/template/.releaserc.json +6 -1
- package/assets/template/.vscode/launch.json +1 -1
- package/assets/template/.vscode/settings.json +1 -0
- package/assets/template/.vscode/tasks.json +45 -0
- package/assets/template/AGENTS.md +4 -4
- package/assets/template/CONTRIBUTING.md +6 -4
- package/assets/template/CONTRIBUTING.zh-CN.md +6 -4
- package/assets/template/_gitignore +7 -405
- package/assets/template/bunfig.toml +2 -11
- package/assets/template/docs/README.md +6 -6
- package/assets/template/docs/adrs/README.md +4 -2
- package/assets/template/docs/development.md +15 -9
- package/assets/template/lefthook.yml +20 -30
- package/assets/template/package.json +5 -6
- package/assets/template/packages/{{NAME}}/README.md +4 -4
- package/assets/template/packages/{{NAME}}/README.zh-CN.md +2 -2
- package/assets/template/packages/{{NAME}}/package.json +3 -1
- package/assets/template/packages/{{NAME}}/scripts/build.ts +50 -14
- package/assets/template/packages/{{NAME}}/scripts/verify-release.test.ts +140 -15
- package/assets/template/packages/{{NAME}}/scripts/verify-release.ts +27 -14
- package/assets/template/packages/{{NAME}}/tsconfig.build.json +1 -1
- package/assets/template/packages/{{NAME}}-cli/README.md +9 -6
- package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +6 -3
- package/assets/template/packages/{{NAME}}-cli/bin/bunfig.toml +3 -0
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}} +43 -21
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd +8 -17
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts +6 -3
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs +189 -107
- package/assets/template/packages/{{NAME}}-cli/package.json +3 -2
- package/assets/template/packages/{{NAME}}-cli/scripts/release-artifact.ts +24 -73
- package/assets/template/packages/{{NAME}}-cli/scripts/release.fixtures.ts +8 -3
- package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.test.ts +16 -10
- package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.ts +8 -52
- package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts +3 -3
- package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.ts +8 -68
- package/assets/template/packages/{{NAME}}-cli/src/cli.ts +51 -11
- package/assets/template/scripts/ci.ts +285 -64
- package/assets/template/scripts/install-git-hooks.mjs +10 -0
- package/assets/template/scripts/install-git-hooks.test.ts +1 -1
- package/assets/template/scripts/lib/npm-trust-parse.ts +169 -0
- package/assets/template/scripts/lib/release-cli.ts +299 -0
- package/assets/template/scripts/lib/release-verify.ts +148 -15
- package/assets/template/scripts/lib/workspace.test.ts +63 -1
- package/assets/template/scripts/lib/workspace.ts +132 -42
- package/assets/template/scripts/lint-dependency-direction.test.ts +131 -0
- package/assets/template/scripts/lint-dependency-direction.ts +130 -0
- package/assets/template/scripts/lint-doc-examples.test.ts +45 -9
- package/assets/template/scripts/lint-doc-examples.ts +227 -50
- package/assets/template/scripts/lint-doc-references.test.ts +36 -0
- package/assets/template/scripts/lint-doc-references.ts +142 -57
- package/assets/template/scripts/lint-doc-shared.ts +26 -23
- package/assets/template/scripts/lint-stray-backups.test.ts +3 -1
- package/assets/template/scripts/lint-stray-backups.ts +7 -3
- package/assets/template/scripts/npm-trust-guard.test.ts +56 -8
- package/assets/template/scripts/npm-trust-guard.ts +116 -200
- package/assets/template/scripts/safe-install.ts +28 -23
- package/assets/template/scripts/transcription/api-harness.ts +28 -206
- package/assets/template/scripts/transcription/compare.test.ts +84 -0
- package/assets/template/scripts/transcription/compare.ts +4 -4
- package/assets/template/scripts/transcription/corpus.ts +9 -3
- package/assets/template/scripts/transcription/fixture.ts +2 -4
- package/assets/template/scripts/transcription/make-mutants.ts +116 -37
- package/assets/template/scripts/transcription/run-conformance.ts +57 -34
- package/assets/template/scripts/transcription/validate-coverage.test.ts +11 -14
- package/assets/template/scripts/transcription/validate-coverage.ts +8 -10
- package/assets/template/scripts/transcription/validate.ts +18 -3
- package/assets/template/tsconfig.json +2 -20
- package/assets/template/turbo.jsonc +7 -52
- package/bin/bunfig.toml +3 -0
- package/bin/create-clis.mjs +165 -104
- package/dist/create-clis.js +48 -87681
- package/dist/manifest.json +3 -3
- package/package.json +9 -5
- package/assets/template/packages/{{NAME}}/docs/README.md +0 -21
- package/assets/template/packages/{{NAME}}-cli/docs/README.md +0 -21
- package/bin/create-clis +0 -35
- package/bin/create-clis.cmd +0 -32
|
@@ -1,29 +1,25 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* 文档引用闸门: 相对链接 / §章节引用 / ADR
|
|
2
|
+
* 文档引用闸门: 相对链接 / §章节引用 / ADR 编号与重号检测 / 包 README npm 外链防 404。
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
4
|
+
* 两级文档模型 (ADR 0019 / docs/designs/docs-layering.md):
|
|
5
|
+
* - 仓库级: `docs/` (纯工程治理、通用设计、仓级 ADR)
|
|
6
|
+
* - 包级: `packages/<pkg>/docs/` (单包及产品主包的全部设计、协议与 ADR)
|
|
6
7
|
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
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
|
|
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/
|
|
42
|
-
覆盖表: 'docs/
|
|
43
|
-
安全防护: 'docs/
|
|
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 到仓库相对路径的索引
|
|
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`
|
|
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
|
-
/** 解析 § 引用的目标文档:
|
|
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
|
-
|
|
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
|
-
/**
|
|
221
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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)
|
|
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
|
|
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
|
|
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
|
-
/** 主流程: 打印全部断裂并以退出码收口
|
|
375
|
+
/** 主流程: 打印全部断裂并以退出码收口 */
|
|
290
376
|
function main(): void {
|
|
291
377
|
const findings = findAllIssues();
|
|
292
378
|
if (findings.length === 0) {
|
|
293
379
|
process.stdout.write(
|
|
294
|
-
'文档引用闸门全绿 ✓ (相对链接 /
|
|
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
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
|
|
37
|
-
|
|
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(
|
|
54
|
+
if (!isSkippedPath(rel, skipPaths)) walk(abs);
|
|
52
55
|
} else if (extensions.some((ext) => entry.name.endsWith(ext))) {
|
|
53
|
-
out.push(
|
|
56
|
+
out.push(rel);
|
|
54
57
|
}
|
|
55
58
|
}
|
|
56
59
|
};
|
|
57
|
-
walk(
|
|
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/
|
|
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 包保留
|
|
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
|
|
287
|
+
test('private 字段缺失或非 true 均视为可发布, 不误伤', () => {
|
|
240
288
|
const packages: WorkspacePackage[] = [
|
|
241
289
|
pkg('@x/api'),
|
|
242
290
|
{
|