create-clis 0.1.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/LICENSE +21 -0
- package/README.md +113 -0
- package/README.zh-CN.md +113 -0
- package/assets/manifest.json +99 -0
- package/assets/template/.editorconfig +12 -0
- package/assets/template/.gitattributes +18 -0
- package/assets/template/.github/ISSUE_TEMPLATE/bug_report.yml +86 -0
- package/assets/template/.github/ISSUE_TEMPLATE/feature_request.yml +45 -0
- package/assets/template/.github/PULL_REQUEST_TEMPLATE.md +26 -0
- package/assets/template/.github/workflows/ci.yml +42 -0
- package/assets/template/.github/workflows/release.yml +65 -0
- package/assets/template/.gitignorerc.json +21 -0
- package/assets/template/.nvmrc +1 -0
- package/assets/template/.oxlintrc.json +52 -0
- package/assets/template/.prettierignore +11 -0
- package/assets/template/.prettierrc +11 -0
- package/assets/template/.releaserc.json +17 -0
- package/assets/template/.vscode/extensions.json +8 -0
- package/assets/template/.vscode/launch.json +13 -0
- package/assets/template/.vscode/settings.json +14 -0
- package/assets/template/AGENTS.md +25 -0
- package/assets/template/CODE_OF_CONDUCT.md +91 -0
- package/assets/template/CONTRIBUTING.md +85 -0
- package/assets/template/CONTRIBUTING.zh-CN.md +85 -0
- package/assets/template/LICENSE +21 -0
- package/assets/template/README.md +22 -0
- package/assets/template/README.zh-CN.md +22 -0
- package/assets/template/SECURITY.md +21 -0
- package/assets/template/_gitignore +409 -0
- package/assets/template/_npmrc +6 -0
- package/assets/template/bunfig.toml +16 -0
- package/assets/template/docs/README.md +30 -0
- package/assets/template/docs/adrs/README.md +7 -0
- package/assets/template/docs/designs/README.md +11 -0
- package/assets/template/docs/designs/tech-debt.md +22 -0
- package/assets/template/docs/development.md +59 -0
- package/assets/template/lefthook.yml +55 -0
- package/assets/template/package.json +38 -0
- package/assets/template/packages/{{NAME}}/CHANGELOG.md +3 -0
- package/assets/template/packages/{{NAME}}/LICENSE +21 -0
- package/assets/template/packages/{{NAME}}/README.md +33 -0
- package/assets/template/packages/{{NAME}}/README.zh-CN.md +33 -0
- package/assets/template/packages/{{NAME}}/docs/README.md +21 -0
- package/assets/template/packages/{{NAME}}/package.json +40 -0
- package/assets/template/packages/{{NAME}}/scripts/build.ts +82 -0
- package/assets/template/packages/{{NAME}}/scripts/verify-release.test.ts +214 -0
- package/assets/template/packages/{{NAME}}/scripts/verify-release.ts +152 -0
- package/assets/template/packages/{{NAME}}/src/index.ts +15 -0
- package/assets/template/packages/{{NAME}}/tsconfig.build.json +12 -0
- package/assets/template/packages/{{NAME}}/tsconfig.json +5 -0
- package/assets/template/packages/{{NAME}}-cli/CHANGELOG.md +3 -0
- package/assets/template/packages/{{NAME}}-cli/LICENSE +21 -0
- package/assets/template/packages/{{NAME}}-cli/README.md +35 -0
- package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +35 -0
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}} +30 -0
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd +30 -0
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts +23 -0
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs +212 -0
- package/assets/template/packages/{{NAME}}-cli/docs/README.md +21 -0
- package/assets/template/packages/{{NAME}}-cli/package.json +48 -0
- package/assets/template/packages/{{NAME}}-cli/scripts/release-artifact.ts +141 -0
- package/assets/template/packages/{{NAME}}-cli/scripts/release.fixtures.ts +70 -0
- package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.test.ts +444 -0
- package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.ts +72 -0
- package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts +126 -0
- package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.ts +81 -0
- package/assets/template/packages/{{NAME}}-cli/src/cli.ts +36 -0
- package/assets/template/packages/{{NAME}}-cli/tsconfig.json +4 -0
- package/assets/template/scripts/ci.ts +163 -0
- package/assets/template/scripts/install-git-hooks.mjs +122 -0
- package/assets/template/scripts/install-git-hooks.test.ts +418 -0
- package/assets/template/scripts/lib/git-env.ts +21 -0
- package/assets/template/scripts/lib/release-verify.ts +431 -0
- package/assets/template/scripts/lib/tmp-root.ts +17 -0
- package/assets/template/scripts/lib/workspace.test.ts +92 -0
- package/assets/template/scripts/lib/workspace.ts +100 -0
- package/assets/template/scripts/lint-doc-examples.test.ts +129 -0
- package/assets/template/scripts/lint-doc-examples.ts +249 -0
- package/assets/template/scripts/lint-doc-references.test.ts +158 -0
- package/assets/template/scripts/lint-doc-references.ts +308 -0
- package/assets/template/scripts/lint-doc-shared.ts +59 -0
- package/assets/template/scripts/lint-stray-backups.test.ts +53 -0
- package/assets/template/scripts/lint-stray-backups.ts +39 -0
- package/assets/template/scripts/npm-trust-guard.test.ts +253 -0
- package/assets/template/scripts/npm-trust-guard.ts +533 -0
- package/assets/template/scripts/safe-install.ts +39 -0
- package/assets/template/scripts/transcription/api-harness.ts +219 -0
- package/assets/template/scripts/transcription/compare.ts +421 -0
- package/assets/template/scripts/transcription/corpus.ts +208 -0
- package/assets/template/scripts/transcription/fixture.ts +290 -0
- package/assets/template/scripts/transcription/make-mutants.ts +425 -0
- package/assets/template/scripts/transcription/report.ts +86 -0
- package/assets/template/scripts/transcription/run-conformance.ts +344 -0
- package/assets/template/scripts/transcription/validate-coverage.test.ts +119 -0
- package/assets/template/scripts/transcription/validate-coverage.ts +144 -0
- package/assets/template/scripts/transcription/validate.ts +366 -0
- package/assets/template/tsconfig.json +46 -0
- package/assets/template/turbo.jsonc +60 -0
- package/bin/create-clis +35 -0
- package/bin/create-clis.cmd +32 -0
- package/bin/create-clis.mjs +219 -0
- package/dist/create-clis.js +87682 -0
- package/dist/manifest.json +7 -0
- package/package.json +57 -0
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 文档引用闸门: 相对链接 / §章节引用 / ADR 编号的静态一致性。
|
|
3
|
+
*
|
|
4
|
+
* 动机: 连续两轮全仓漂移审计 (2026-09-30) 反复检出三类引用断裂 (死链 / 幽灵章节 / 幽灵
|
|
5
|
+
* ADR), 三类均为确定性可判的事实, 不该等下一轮人工审计才暴露, 故落为提交时闸门。
|
|
6
|
+
*
|
|
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 的任一子节与指向该节同义)。
|
|
20
|
+
*
|
|
21
|
+
* 用法: bun scripts/lint-doc-references.ts
|
|
22
|
+
* 退出码: 0 全绿; 1 存在断裂 (逐条打印 file:line 定位)。
|
|
23
|
+
*/
|
|
24
|
+
import { existsSync, readFileSync, readdirSync } from 'node:fs';
|
|
25
|
+
import { dirname, join, resolve } from 'node:path';
|
|
26
|
+
|
|
27
|
+
import { REPO_ROOT, walkFiles } from './lint-doc-shared.ts';
|
|
28
|
+
|
|
29
|
+
/** 一条断裂发现 */
|
|
30
|
+
export interface RefFinding {
|
|
31
|
+
file: string;
|
|
32
|
+
line: number;
|
|
33
|
+
kind: 'link' | 'section' | 'adr';
|
|
34
|
+
reference: string;
|
|
35
|
+
message: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** 文档别名表: 直角引号里的文档「别称」到仓库相对路径; 实测出现即增补 */
|
|
39
|
+
export const DOC_ALIASES: Readonly<Record<string, string>> = {
|
|
40
|
+
'可编程 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',
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/** ADR 引用的行级豁免词: 文档正在陈述「该 ADR 尚不存在」时不算断裂 */
|
|
47
|
+
const ADR_LINE_EXEMPT_MARKERS = ['不存在', '未创建', '待创建', '历史'] as const;
|
|
48
|
+
|
|
49
|
+
/** §引用解析窗口: § 之前多少字符内找目标文档线索 */
|
|
50
|
+
const SECTION_TARGET_WINDOW = 30;
|
|
51
|
+
|
|
52
|
+
/** 走查全部 .md (共享走查的文档薄壳; 保留独立导出供测试注入临时根) */
|
|
53
|
+
export function listDocFiles(root: string): string[] {
|
|
54
|
+
return walkFiles(root, ['.md']);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* 围栏代码块内容置空 (保行数, 保行号): ``` 或 ~~~ 围栏, 支持带语言标注的开启行。
|
|
59
|
+
* 引用检查在置空后的文本上做, 示例代码里的路径 / § 不参与判定。
|
|
60
|
+
*/
|
|
61
|
+
export function stripFencedCode(content: string): string {
|
|
62
|
+
let fence: string | null = null;
|
|
63
|
+
return content
|
|
64
|
+
.split('\n')
|
|
65
|
+
.map((line) => {
|
|
66
|
+
const m = line.match(/^\s*(`{3,}|~{3,})/);
|
|
67
|
+
if (fence === null && m) {
|
|
68
|
+
fence = m[1]![0]!;
|
|
69
|
+
return '';
|
|
70
|
+
}
|
|
71
|
+
if (fence !== null) {
|
|
72
|
+
if (m && m[1]![0] === fence) fence = null;
|
|
73
|
+
return '';
|
|
74
|
+
}
|
|
75
|
+
return line;
|
|
76
|
+
})
|
|
77
|
+
.join('\n');
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** 文件名 stem 到仓库相对路径的索引 (同 stem 多值时全部保留, 解析时优先同目录) */
|
|
81
|
+
export function buildNameIndex(files: string[]): Map<string, string[]> {
|
|
82
|
+
const index = new Map<string, string[]>();
|
|
83
|
+
for (const file of files) {
|
|
84
|
+
const stem = file.split('/').pop()!.replace(/\.md$/, '');
|
|
85
|
+
const list = index.get(stem) ?? [];
|
|
86
|
+
list.push(file);
|
|
87
|
+
index.set(stem, list);
|
|
88
|
+
}
|
|
89
|
+
return index;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** 收集一个文档的节号集合 (`## N.` / `### N.M` / `#### N.M.K` 的 N 与 N.M 与 N.M.K) */
|
|
93
|
+
export function collectSectionNumbers(content: string): Set<string> {
|
|
94
|
+
const numbers = new Set<string>();
|
|
95
|
+
for (const m of content.matchAll(/^#{2,5}\s+(\d+(?:\.\d+)*)[.、\s]/gm)) {
|
|
96
|
+
numbers.add(m[1]!);
|
|
97
|
+
}
|
|
98
|
+
return numbers;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** 校验一个文件里的相对链接 (存在性; 外链 / 纯锚点 / 代码块 / 尖括号占位跳过) */
|
|
102
|
+
export function findLinkIssues(
|
|
103
|
+
lines: string[],
|
|
104
|
+
file: string,
|
|
105
|
+
root: string,
|
|
106
|
+
): RefFinding[] {
|
|
107
|
+
const findings: RefFinding[] = [];
|
|
108
|
+
const dir = dirname(file);
|
|
109
|
+
for (const [index, line] of lines.entries()) {
|
|
110
|
+
for (const m of line.matchAll(/\]\(([^)\s]+)\)/g)) {
|
|
111
|
+
const raw = m[1]!;
|
|
112
|
+
if (raw.startsWith('#') || raw.includes('://') || raw.startsWith('<')) {
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
// 带 scheme 的非 URL 形态 (mailto: 等) 跳过
|
|
116
|
+
if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(raw) && !raw.startsWith('.')) {
|
|
117
|
+
continue;
|
|
118
|
+
}
|
|
119
|
+
const [pathPart, anchor] = raw.split('#');
|
|
120
|
+
if (!pathPart) continue;
|
|
121
|
+
let decoded = pathPart;
|
|
122
|
+
try {
|
|
123
|
+
decoded = decodeURIComponent(pathPart);
|
|
124
|
+
} catch {
|
|
125
|
+
// 非标准编码: 按原样解析
|
|
126
|
+
}
|
|
127
|
+
// 协议相对形态 (//host) 不参与; 以 / 开头按仓库根解析 (GitHub 渲染语义); 其余相对本文件
|
|
128
|
+
if (decoded.startsWith('//')) continue;
|
|
129
|
+
const target = decoded.startsWith('/')
|
|
130
|
+
? join(root, decoded)
|
|
131
|
+
: resolve(root, dir, decoded);
|
|
132
|
+
if (!existsSync(target)) {
|
|
133
|
+
findings.push({
|
|
134
|
+
file,
|
|
135
|
+
line: index + 1,
|
|
136
|
+
kind: 'link',
|
|
137
|
+
reference: raw,
|
|
138
|
+
message: `相对链接目标不存在${anchor === undefined ? '' : ' (锚点部分未单独校验)'}`,
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return findings;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** 解析 § 引用的目标文档: 窗口内的 `x.md` 文件名或已知别名; 无线索返回 null (跳过) */
|
|
147
|
+
export function resolveSectionTarget(
|
|
148
|
+
line: string,
|
|
149
|
+
refIndex: number,
|
|
150
|
+
dir: string,
|
|
151
|
+
nameIndex: Map<string, string[]>,
|
|
152
|
+
): string | null {
|
|
153
|
+
const before = line.slice(
|
|
154
|
+
Math.max(0, refIndex - SECTION_TARGET_WINDOW),
|
|
155
|
+
refIndex,
|
|
156
|
+
);
|
|
157
|
+
// 候选文件名要求前置分隔符 (不认窗口起点): 窗口截断会把长名切成残片
|
|
158
|
+
// (api-surface.md → rface.md), 残片按 stem 查索引必然落空, 必须由右向左取
|
|
159
|
+
// 第一个「能在索引里解析出真实文档」的名字 (离 § 最近者优先)
|
|
160
|
+
const names: string[] = [];
|
|
161
|
+
for (const m of before.matchAll(/[^A-Za-z0-9._-]([A-Za-z0-9_-]+\.md)/g)) {
|
|
162
|
+
names.push(m[1]!);
|
|
163
|
+
}
|
|
164
|
+
for (const name of names.reverse()) {
|
|
165
|
+
const candidates = nameIndex.get(name.replace(/\.md$/, ''));
|
|
166
|
+
if (candidates && candidates.length > 0) {
|
|
167
|
+
// 同目录优先, 其次全仓首个 (文档内引用自己的兄弟文档是主流形态)
|
|
168
|
+
return candidates.find((c) => c.startsWith(dir + '/')) ?? candidates[0]!;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
for (const [alias, target] of Object.entries(DOC_ALIASES)) {
|
|
172
|
+
if (before.includes(alias)) return target;
|
|
173
|
+
}
|
|
174
|
+
return null;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** 校验一个文件里的 §章节引用 (仅目标明确形态; 节号须在目标文档的标题编号集合内) */
|
|
178
|
+
export function findSectionIssues(
|
|
179
|
+
lines: string[],
|
|
180
|
+
file: string,
|
|
181
|
+
root: string,
|
|
182
|
+
nameIndex: Map<string, string[]>,
|
|
183
|
+
sectionsCache: Map<string, Set<string>>,
|
|
184
|
+
): RefFinding[] {
|
|
185
|
+
const findings: RefFinding[] = [];
|
|
186
|
+
const dir = dirname(file);
|
|
187
|
+
const sectionsOf = (rel: string): Set<string> | null => {
|
|
188
|
+
const cached = sectionsCache.get(rel);
|
|
189
|
+
if (cached) return cached;
|
|
190
|
+
const abs = join(root, rel);
|
|
191
|
+
if (!existsSync(abs)) return null;
|
|
192
|
+
const numbers = collectSectionNumbers(readFileSync(abs, 'utf8'));
|
|
193
|
+
sectionsCache.set(rel, numbers);
|
|
194
|
+
return numbers;
|
|
195
|
+
};
|
|
196
|
+
for (const [index, line] of lines.entries()) {
|
|
197
|
+
for (const m of line.matchAll(/§(\d+(?:\.\d+)*)/g)) {
|
|
198
|
+
const number = m[1]!;
|
|
199
|
+
const target = resolveSectionTarget(line, m.index, dir, nameIndex);
|
|
200
|
+
if (target === null) continue;
|
|
201
|
+
const sections = sectionsOf(target);
|
|
202
|
+
if (sections === null) continue; // 目标文档不存在由链接类检查负责
|
|
203
|
+
const hit = [...sections].some(
|
|
204
|
+
(n) => n === number || n.startsWith(number + '.'),
|
|
205
|
+
);
|
|
206
|
+
if (!hit) {
|
|
207
|
+
findings.push({
|
|
208
|
+
file,
|
|
209
|
+
line: index + 1,
|
|
210
|
+
kind: 'section',
|
|
211
|
+
reference: `§${number}`,
|
|
212
|
+
message: `目标文档 ${target} 的标题编号里没有 §${number}`,
|
|
213
|
+
});
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
return findings;
|
|
218
|
+
}
|
|
219
|
+
|
|
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>();
|
|
223
|
+
const dirs = [join(root, 'docs', 'adrs')];
|
|
224
|
+
const packagesDir = join(root, 'packages');
|
|
225
|
+
if (existsSync(packagesDir)) {
|
|
226
|
+
for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {
|
|
227
|
+
if (entry.isDirectory()) {
|
|
228
|
+
dirs.push(join(packagesDir, entry.name, 'docs', 'adrs'));
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
for (const dir of dirs) {
|
|
233
|
+
if (!existsSync(dir)) continue;
|
|
234
|
+
for (const name of readdirSync(dir)) {
|
|
235
|
+
const m = name.match(/^(\d{4})-/);
|
|
236
|
+
if (m) numbers.add(m[1]!);
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
return numbers;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** 校验一个文件里的 ADR 编号引用 (不存在即断裂; 行级豁免词命中时跳过) */
|
|
243
|
+
export function findAdrIssues(
|
|
244
|
+
lines: string[],
|
|
245
|
+
file: string,
|
|
246
|
+
adrNumbers: Set<string>,
|
|
247
|
+
): RefFinding[] {
|
|
248
|
+
const findings: RefFinding[] = [];
|
|
249
|
+
for (const [index, line] of lines.entries()) {
|
|
250
|
+
if (ADR_LINE_EXEMPT_MARKERS.some((marker) => line.includes(marker))) {
|
|
251
|
+
continue;
|
|
252
|
+
}
|
|
253
|
+
for (const m of line.matchAll(/ADR[ -]?(\d{3,4})/g)) {
|
|
254
|
+
const number = String(Number(m[1])).padStart(4, '0');
|
|
255
|
+
if (!adrNumbers.has(number)) {
|
|
256
|
+
findings.push({
|
|
257
|
+
file,
|
|
258
|
+
line: index + 1,
|
|
259
|
+
kind: 'adr',
|
|
260
|
+
reference: `ADR ${number}`,
|
|
261
|
+
message: 'docs/adrs 下没有对应编号的 ADR 文件',
|
|
262
|
+
});
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
return findings;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** 全仓扫描三类引用 (导出供测试用临时根); 返回全部断裂 */
|
|
270
|
+
export function findAllIssues(root: string = REPO_ROOT): RefFinding[] {
|
|
271
|
+
const files = listDocFiles(root);
|
|
272
|
+
const nameIndex = buildNameIndex(files);
|
|
273
|
+
const adrNumbers = collectAdrNumbers(root);
|
|
274
|
+
const sectionsCache = new Map<string, Set<string>>();
|
|
275
|
+
const findings: RefFinding[] = [];
|
|
276
|
+
for (const file of files) {
|
|
277
|
+
const lines = stripFencedCode(readFileSync(join(root, file), 'utf8')).split(
|
|
278
|
+
'\n',
|
|
279
|
+
);
|
|
280
|
+
findings.push(
|
|
281
|
+
...findLinkIssues(lines, file, root),
|
|
282
|
+
...findSectionIssues(lines, file, root, nameIndex, sectionsCache),
|
|
283
|
+
...findAdrIssues(lines, file, adrNumbers),
|
|
284
|
+
);
|
|
285
|
+
}
|
|
286
|
+
return findings;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** 主流程: 打印全部断裂并以退出码收口 (0 全绿 / 1 有断裂) */
|
|
290
|
+
function main(): void {
|
|
291
|
+
const findings = findAllIssues();
|
|
292
|
+
if (findings.length === 0) {
|
|
293
|
+
process.stdout.write(
|
|
294
|
+
'文档引用闸门全绿 ✓ (相对链接 / §章节引用 / ADR 编号)\n',
|
|
295
|
+
);
|
|
296
|
+
return;
|
|
297
|
+
}
|
|
298
|
+
process.stderr.write(`文档引用闸门检出 ${findings.length} 处断裂:\n`);
|
|
299
|
+
for (const finding of findings) {
|
|
300
|
+
process.stderr.write(
|
|
301
|
+
` ${finding.file}:${finding.line} [${finding.kind}] ${finding.reference} ${finding.message}\n`,
|
|
302
|
+
);
|
|
303
|
+
}
|
|
304
|
+
process.exitCode = 1;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// 仅作为入口执行时跑主流程 (被 import 时不执行, 供测试)
|
|
308
|
+
if (import.meta.main) main();
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 文档类静态闸门的共享底座: 仓库根定位与文件走查 (引用闸门 / 示例闸门 / 仓库卫生共用)。
|
|
3
|
+
*
|
|
4
|
+
* 走查跳过清单统一在此维护: 依赖目录与生成物 (node_modules / .git / .turbo / dist) 不含
|
|
5
|
+
* 待查文档, mutants 为变异自证的一次性副本 (源码拷贝, 引用与示例均不适用于副本场景);
|
|
6
|
+
* 生成器包的模板空间 (assets / template-skeletons) 的链接与示例只在新项目语境成立, 同跳。
|
|
7
|
+
*/
|
|
8
|
+
import { readdirSync } from 'node:fs';
|
|
9
|
+
import { dirname, join, resolve } from 'node:path';
|
|
10
|
+
import { fileURLToPath } from 'node:url';
|
|
11
|
+
|
|
12
|
+
/** 仓库根 (scripts/ 的上一级) */
|
|
13
|
+
export const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
14
|
+
|
|
15
|
+
/** 走查跳过目录: 依赖 / 版本控制 / 构建缓存 / 生成物 / 变异副本 */
|
|
16
|
+
export const SKIP_DIRS: ReadonlySet<string> = new Set([
|
|
17
|
+
'node_modules',
|
|
18
|
+
'.git',
|
|
19
|
+
'.turbo',
|
|
20
|
+
'dist',
|
|
21
|
+
'mutants',
|
|
22
|
+
]);
|
|
23
|
+
|
|
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
|
+
];
|
|
34
|
+
|
|
35
|
+
/** 相对路径是否落在跳过面内 (目录前缀匹配) */
|
|
36
|
+
function isSkippedPath(relativePath: string): boolean {
|
|
37
|
+
return SKIP_PATHS.some((prefix) => `${relativePath}/`.startsWith(prefix));
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** 按扩展名走查文件, 返回仓库相对路径 (字典序, 稳定输出) */
|
|
41
|
+
export function walkFiles(
|
|
42
|
+
root: string,
|
|
43
|
+
extensions: readonly string[],
|
|
44
|
+
): string[] {
|
|
45
|
+
const out: string[] = [];
|
|
46
|
+
const walk = (dir: string): void => {
|
|
47
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
48
|
+
if (SKIP_DIRS.has(entry.name)) continue;
|
|
49
|
+
const abs = join(dir, entry.name);
|
|
50
|
+
if (entry.isDirectory()) {
|
|
51
|
+
if (!isSkippedPath(abs.slice(root.length + 1))) walk(abs);
|
|
52
|
+
} else if (extensions.some((ext) => entry.name.endsWith(ext))) {
|
|
53
|
+
out.push(abs.slice(root.length + 1));
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
walk(root);
|
|
58
|
+
return out.sort();
|
|
59
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 仓库卫生闸门单测: 临时根上验证「散落备份抓得住、正常文件不误伤」。
|
|
3
|
+
*/
|
|
4
|
+
import { afterAll, describe, expect, test } from 'bun:test';
|
|
5
|
+
|
|
6
|
+
import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
|
|
7
|
+
import { dirname, join } from 'node:path';
|
|
8
|
+
|
|
9
|
+
import { makeTmpRoot } from './lib/tmp-root.ts';
|
|
10
|
+
import { findStrayBackups } from './lint-stray-backups.ts';
|
|
11
|
+
|
|
12
|
+
const roots: string[] = [];
|
|
13
|
+
function makeRoot(files: string[]): string {
|
|
14
|
+
const root = makeTmpRoot('stray-');
|
|
15
|
+
roots.push(root);
|
|
16
|
+
for (const rel of files) {
|
|
17
|
+
const abs = join(root, rel);
|
|
18
|
+
mkdirSync(dirname(abs), { recursive: true });
|
|
19
|
+
writeFileSync(abs, 'x');
|
|
20
|
+
}
|
|
21
|
+
return root;
|
|
22
|
+
}
|
|
23
|
+
afterAll(() => {
|
|
24
|
+
for (const root of roots) rmSync(root, { recursive: true, force: true });
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
describe('findStrayBackups', () => {
|
|
28
|
+
test('抓到 .modified / .deleted 收尾的文件, 正常文件不误伤', () => {
|
|
29
|
+
const root = makeRoot([
|
|
30
|
+
'docs/note.md',
|
|
31
|
+
'docs/note.md.20260930_120000.modified',
|
|
32
|
+
'packages/a/src/x.ts.20260929_090000.deleted',
|
|
33
|
+
'scripts/plain.ts',
|
|
34
|
+
]);
|
|
35
|
+
expect(findStrayBackups(root)).toEqual([
|
|
36
|
+
'docs/note.md.20260930_120000.modified',
|
|
37
|
+
'packages/a/src/x.ts.20260929_090000.deleted',
|
|
38
|
+
]);
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
test('空树与仅正常文件时零输出', () => {
|
|
42
|
+
expect(findStrayBackups(makeRoot(['README.md', 'a/b/c.json']))).toEqual([]);
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
test('嵌套深处的备份同样被抓', () => {
|
|
46
|
+
const root = makeRoot([
|
|
47
|
+
'docs/nested/deep/note.md.20260101_000000.modified',
|
|
48
|
+
]);
|
|
49
|
+
expect(findStrayBackups(root)).toEqual([
|
|
50
|
+
'docs/nested/deep/note.md.20260101_000000.modified',
|
|
51
|
+
]);
|
|
52
|
+
});
|
|
53
|
+
});
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 仓库卫生闸门: 工作树内不得出现备份文件 (*.modified / *.deleted)。
|
|
3
|
+
*
|
|
4
|
+
* 动机: 备份纪律要求备份落 ~/tmp (ADR 0009 补记), 但 2026-09-30 漂移清偿时实测工作树内
|
|
5
|
+
* 散落 7 个 .modified: 它们被 .gitignore 忽略、git status 看不见, 却不属于仓库; 包目录
|
|
6
|
+
* 下的备份还会借 npm pack 的 README* 强制收录规则混进发行物 (既有的「包根杂质常驻回归」
|
|
7
|
+
* 只兜包目录)。本闸门做全树兜底: 出现即红灯, 把清理成本压回发生的那一刻。
|
|
8
|
+
*
|
|
9
|
+
* 判据: 全树走查中文件名以 .modified / .deleted 收尾者 (共享跳过面之外的任何位置)。
|
|
10
|
+
*
|
|
11
|
+
* 用法: bun scripts/lint-stray-backups.ts
|
|
12
|
+
* 退出码: 0 无散落; 1 有散落 (逐条打印路径)。
|
|
13
|
+
*/
|
|
14
|
+
import { REPO_ROOT, walkFiles } from './lint-doc-shared.ts';
|
|
15
|
+
|
|
16
|
+
/** 备份后缀: 与宪法「修改前置备份」的命名收尾一致 */
|
|
17
|
+
const BACKUP_SUFFIXES = ['.modified', '.deleted'] as const;
|
|
18
|
+
|
|
19
|
+
/** 全树找出散落备份 (相对路径, 供测试注入临时根) */
|
|
20
|
+
export function findStrayBackups(root: string = REPO_ROOT): string[] {
|
|
21
|
+
return walkFiles(root, BACKUP_SUFFIXES);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** 主流程: 打印散落清单并以退出码收口 (0 无散落 / 1 有散落) */
|
|
25
|
+
function main(): void {
|
|
26
|
+
const strays = findStrayBackups();
|
|
27
|
+
if (strays.length === 0) {
|
|
28
|
+
process.stdout.write('仓库卫生闸门全绿 ✓ (无散落 .modified / .deleted)\n');
|
|
29
|
+
return;
|
|
30
|
+
}
|
|
31
|
+
process.stderr.write(
|
|
32
|
+
`检出 ${strays.length} 个散落备份 (备份纪律: 移出仓库至 ~/tmp/sweep_backups/, 保留相对结构):\n`,
|
|
33
|
+
);
|
|
34
|
+
for (const stray of strays) process.stderr.write(` ${stray}\n`);
|
|
35
|
+
process.exitCode = 1;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// 仅作为入口执行时跑主流程 (被 import 时不执行, 供测试)
|
|
39
|
+
if (import.meta.main) main();
|