specthread 0.1.4 → 0.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 +88 -13
- package/dist/bin/check.js +9 -34
- package/dist/bin/cli.js +4 -4
- package/dist/bin/generate.js +32 -19
- package/dist/bin/open-project.d.ts +5 -0
- package/dist/bin/open-project.js +26 -0
- package/dist/checks/changelog.js +5 -4
- package/dist/checks/headings.d.ts +0 -1
- package/dist/checks/headings.js +13 -4
- package/dist/checks/links.js +10 -6
- package/dist/checks/markers.d.ts +3 -1
- package/dist/checks/markers.js +33 -18
- package/dist/checks/pending.js +54 -22
- package/dist/checks/references.js +2 -2
- package/dist/checks/sections.js +3 -5
- package/dist/checks/style.d.ts +0 -8
- package/dist/checks/style.js +23 -43
- package/dist/checks/timestamps.js +5 -5
- package/dist/checks/toc.js +4 -6
- package/dist/commands/config-template.d.ts +8 -0
- package/{scaffold/config.jsonc → dist/commands/config-template.js} +48 -40
- package/dist/commands/init.js +92 -42
- package/dist/config-loader.d.ts +22 -1
- package/dist/config-loader.js +192 -25
- package/dist/config.schema.d.ts +16 -35
- package/dist/config.schema.js +1 -7
- package/dist/constants/docs.d.ts +7 -2
- package/dist/constants/docs.js +7 -3
- package/dist/constants/exit.d.ts +12 -0
- package/dist/constants/exit.js +12 -0
- package/dist/constants/paths.d.ts +25 -0
- package/dist/constants/paths.js +25 -0
- package/dist/constants/patterns.d.ts +12 -3
- package/dist/constants/patterns.js +15 -3
- package/dist/constants/rules.d.ts +7 -3
- package/dist/constants/rules.js +7 -3
- package/dist/gen/pending-section.js +18 -14
- package/dist/gen/references.js +19 -10
- package/dist/gen/summary.d.ts +1 -1
- package/dist/gen/summary.js +9 -6
- package/dist/gen/toc.js +4 -1
- package/dist/run-check.d.ts +5 -0
- package/dist/run-check.js +35 -0
- package/dist/types.d.ts +4 -2
- package/dist/utils/ignore.d.ts +2 -8
- package/dist/utils/ignore.js +23 -6
- package/dist/utils/parse.js +11 -19
- package/dist/utils/path-match.d.ts +19 -0
- package/dist/utils/path-match.js +27 -0
- package/dist/utils/report.d.ts +1 -7
- package/dist/utils/report.js +10 -3
- package/dist/utils/resolve.js +15 -1
- package/dist/utils/root.d.ts +2 -0
- package/dist/utils/root.js +19 -0
- package/dist/utils/scan.d.ts +7 -5
- package/dist/utils/scan.js +25 -25
- package/dist/utils/scope.d.ts +37 -11
- package/dist/utils/scope.js +60 -24
- package/package.json +2 -2
- package/scaffold/AGENTS.md +4 -6
- package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
- package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +4 -2
- package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
- package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
- package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
- package/scaffold/pending.md +1 -1
- package/scaffold/project.md +1 -1
- package/scaffold/rules.md +28 -27
- package/scaffold/templates/plan.md +3 -7
package/dist/utils/parse.js
CHANGED
|
@@ -5,12 +5,13 @@
|
|
|
5
5
|
* 펜스 코드블록 안은 전부 무시한다. 템플릿이 골격을 코드블록으로 담고 있어서
|
|
6
6
|
* 추적하지 않으면 헤딩 88 개와 링크 90 개가 오탐으로 잡힌다.
|
|
7
7
|
*/
|
|
8
|
-
import { TAIL_NAMES } from "../constants/docs.js";
|
|
8
|
+
import { TAIL, TAIL_NAMES } from "../constants/docs.js";
|
|
9
|
+
import { MARKER, PENDING_ITEM, PENDING_JSON } from "../constants/patterns.js";
|
|
9
10
|
import { slugify, splitHeadingNum } from "./anchor.js";
|
|
10
11
|
/**
|
|
11
12
|
* 꼬리 절 이름. 하나가 나오면 그 뒤는 전부 꼬리다.
|
|
12
13
|
*
|
|
13
|
-
* 꼬리 절은 문서 맨 끝에 순서대로 오므로 (`
|
|
14
|
+
* 꼬리 절은 문서 맨 끝에 순서대로 오므로 (`specthread/rules.md` §2-5) 첫 꼬리
|
|
14
15
|
* 헤딩부터 파일 끝까지를 꼬리로 보면 된다. 하위 절 (`### 문서` 등) 도 따라 잡힌다.
|
|
15
16
|
*/
|
|
16
17
|
const TAIL_SET = new Set(TAIL_NAMES);
|
|
@@ -84,18 +85,6 @@ export const linkTargetSpans = (line) => {
|
|
|
84
85
|
}
|
|
85
86
|
return spans;
|
|
86
87
|
};
|
|
87
|
-
/** 마커. 종류와 slug 를 함께 캡처한다 */
|
|
88
|
-
const MARKER = /PENDING::([a-z]+)::([a-z0-9][a-z0-9-]*)/g;
|
|
89
|
-
/** JSON 안 마커. 데이터에는 주석을 못 달아서 필드로 표기한다 */
|
|
90
|
-
const PENDING_JSON = /"_pending"\s*:\s*"([a-z]+)::([a-z0-9][a-z0-9-]*)"/g;
|
|
91
|
-
/**
|
|
92
|
-
* 미확정 항목. 마커와 달리 `PENDING` 접두가 없다.
|
|
93
|
-
*
|
|
94
|
-
* 세 모양을 받는다 - 관리 문서 항목은 `###` 헤딩 (`` `[slug]` ``), 문서 미확정 사항
|
|
95
|
-
* 절은 생성된 백링크 (`` [`slug`](...) ``), 둘 다 아닌 `li` (`` - `[slug]` ``) 는
|
|
96
|
-
* 낡은 형식이다. 형식 판정은 `checks/pending.ts` 가 하고 여기는 세는 일만 한다.
|
|
97
|
-
*/
|
|
98
|
-
const PENDING_ITEM = /^(?:\s*-|###)\s+[`\[]+([a-z]+)::([a-z0-9][a-z0-9-]*)[`\]]+/;
|
|
99
88
|
/** 마크다운 링크. 대상에 공백이 없다고 보고 잡는다 */
|
|
100
89
|
const LINK = /\[([^\]]*)\]\(([^)\s]+)\)/g;
|
|
101
90
|
/** 변경 이력 표의 첫 칸 날짜 */
|
|
@@ -251,22 +240,25 @@ export const parseMarkdown = (path, lines) => {
|
|
|
251
240
|
dated.push({ line: i + 1, date: date[1] });
|
|
252
241
|
}
|
|
253
242
|
});
|
|
254
|
-
const changeLogRange = tailRange(headings,
|
|
243
|
+
const changeLogRange = tailRange(headings, TAIL.CHANGELOG, lines.length);
|
|
255
244
|
// 본문에도 날짜 표가 있을 수 있어서 변경 이력 절 안의 것만 센다
|
|
256
245
|
const inLog = (line) => changeLogRange !== null &&
|
|
257
246
|
line >= changeLogRange.start &&
|
|
258
247
|
line <= changeLogRange.end;
|
|
248
|
+
// 변경 이력은 과거 기록이고 목차는 헤딩의 사본이라 마커로 세지 않는다
|
|
249
|
+
const tocBlock = findTocBlock(lines);
|
|
250
|
+
const inToc = (line) => tocBlock !== null && line >= tocBlock.start && line <= tocBlock.end;
|
|
259
251
|
return {
|
|
260
252
|
path,
|
|
261
253
|
kind: "doc",
|
|
262
254
|
lines,
|
|
263
255
|
headings,
|
|
264
256
|
links,
|
|
265
|
-
markers: parseMarkers(lines, "doc", path),
|
|
257
|
+
markers: parseMarkers(lines, "doc", path).filter((m) => !inLog(m.line) && !inToc(m.line)),
|
|
266
258
|
pendingItems,
|
|
267
|
-
tocBlock
|
|
268
|
-
refSection: tailRange(headings,
|
|
269
|
-
pendingSection: tailRange(headings,
|
|
259
|
+
tocBlock,
|
|
260
|
+
refSection: tailRange(headings, TAIL.REFS, lines.length),
|
|
261
|
+
pendingSection: tailRange(headings, TAIL.PENDING, lines.length),
|
|
270
262
|
changeLogRange,
|
|
271
263
|
changeLogDates: dated.filter((d) => inLog(d.line)).map((d) => d.date),
|
|
272
264
|
};
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 설정에 적힌 경로와 색인 경로의 대조.
|
|
3
|
+
*
|
|
4
|
+
* skipCheck·skipRefs·work 는 모두 "이 경로 아래" 를 뜻하므로 같은 함수로 판정한다.
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* 설정에 적힌 경로를 색인 경로와 같은 형태로 만든다.
|
|
8
|
+
*
|
|
9
|
+
* 색인 경로는 루트 기준 상대 경로이고 `./` 도 끝 `/` 도 없다. 역슬래시는 `/` 로 바꾼다.
|
|
10
|
+
* 빈 문자열은 루트 전체다.
|
|
11
|
+
*/
|
|
12
|
+
export declare const normalizeConfigPath: (raw: string) => string;
|
|
13
|
+
/**
|
|
14
|
+
* path 가 base 아래에 있는지. 디렉터리 경계로 판정한다.
|
|
15
|
+
*
|
|
16
|
+
* `docs` 는 `docs/a.md` 를 포함하고 `docs-old/a.md` 는 포함하지 않는다. 파일 경로를
|
|
17
|
+
* 정확히 적으면 그 파일 하나에 해당한다. base 는 정규화된 값이어야 한다.
|
|
18
|
+
*/
|
|
19
|
+
export declare const underPath: (path: string, base: string) => boolean;
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 설정에 적힌 경로와 색인 경로의 대조.
|
|
3
|
+
*
|
|
4
|
+
* skipCheck·skipRefs·work 는 모두 "이 경로 아래" 를 뜻하므로 같은 함수로 판정한다.
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* 설정에 적힌 경로를 색인 경로와 같은 형태로 만든다.
|
|
8
|
+
*
|
|
9
|
+
* 색인 경로는 루트 기준 상대 경로이고 `./` 도 끝 `/` 도 없다. 역슬래시는 `/` 로 바꾼다.
|
|
10
|
+
* 빈 문자열은 루트 전체다.
|
|
11
|
+
*/
|
|
12
|
+
export const normalizeConfigPath = (raw) => {
|
|
13
|
+
let p = raw.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
|
|
14
|
+
while (p.startsWith("./"))
|
|
15
|
+
p = p.slice(2);
|
|
16
|
+
if (p === ".")
|
|
17
|
+
p = "";
|
|
18
|
+
p = p.replace(/^\/+/, "").replace(/\/+$/, "");
|
|
19
|
+
return p;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* path 가 base 아래에 있는지. 디렉터리 경계로 판정한다.
|
|
23
|
+
*
|
|
24
|
+
* `docs` 는 `docs/a.md` 를 포함하고 `docs-old/a.md` 는 포함하지 않는다. 파일 경로를
|
|
25
|
+
* 정확히 적으면 그 파일 하나에 해당한다. base 는 정규화된 값이어야 한다.
|
|
26
|
+
*/
|
|
27
|
+
export const underPath = (path, base) => base === "" || path === base || path.startsWith(`${base}/`);
|
package/dist/utils/report.d.ts
CHANGED
|
@@ -1,14 +1,8 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* 검사 결과 출력. 파일별로 묶고 규칙별 집계를 붙인다.
|
|
3
|
-
*
|
|
4
|
-
* **터미널 꾸미기는 이 파일에만 둔다.** 다른 곳에서 ANSI 문자열을 만들면 제어 문자가
|
|
5
|
-
* 소스 곳곳에 박혀 눈에 안 보이고, grep·sed 같은 도구가 그 파일을 못 다루게 된다.
|
|
6
|
-
*/
|
|
7
1
|
import type { Finding } from "../types.ts";
|
|
8
2
|
/**
|
|
9
3
|
* 지적을 파일별로 묶어 출력하고 규칙별 집계를 붙인다.
|
|
10
4
|
*
|
|
11
|
-
* 종료 코드를 돌려준다 - 지적이 있으면
|
|
5
|
+
* 종료 코드를 돌려준다 - 지적이 있으면 `EXIT.FINDINGS`.
|
|
12
6
|
* 규칙별 집계가 있어야 어느 규칙이 소음을 내는지 보고 판단할 수 있다.
|
|
13
7
|
*/
|
|
14
8
|
export declare const report: (findings: Finding[], summary: {
|
package/dist/utils/report.js
CHANGED
|
@@ -1,3 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 검사 결과 출력. 파일별로 묶고 규칙별 집계를 붙인다.
|
|
3
|
+
*
|
|
4
|
+
* **터미널 꾸미기는 이 파일에만 둔다.** 다른 곳에서 ANSI 문자열을 만들면 제어 문자가
|
|
5
|
+
* 소스 곳곳에 박혀 눈에 안 보이고, grep·sed 같은 도구가 그 파일을 못 다루게 된다.
|
|
6
|
+
*/
|
|
7
|
+
import { EXIT } from "../constants/exit.js";
|
|
1
8
|
/** 터미널 강조. 규칙 이름을 흐리게 두어 메시지가 먼저 읽히게 한다 */
|
|
2
9
|
const BOLD = "\x1b[1m";
|
|
3
10
|
const DIM = "\x1b[2m";
|
|
@@ -5,7 +12,7 @@ const RESET = "\x1b[0m";
|
|
|
5
12
|
/**
|
|
6
13
|
* 지적을 파일별로 묶어 출력하고 규칙별 집계를 붙인다.
|
|
7
14
|
*
|
|
8
|
-
* 종료 코드를 돌려준다 - 지적이 있으면
|
|
15
|
+
* 종료 코드를 돌려준다 - 지적이 있으면 `EXIT.FINDINGS`.
|
|
9
16
|
* 규칙별 집계가 있어야 어느 규칙이 소음을 내는지 보고 판단할 수 있다.
|
|
10
17
|
*/
|
|
11
18
|
export const report = (findings, summary) => {
|
|
@@ -14,7 +21,7 @@ export const report = (findings, summary) => {
|
|
|
14
21
|
console.log(` ${line}`);
|
|
15
22
|
if (findings.length === 0) {
|
|
16
23
|
console.log(`\n${BOLD}지적 없음${RESET}`);
|
|
17
|
-
return
|
|
24
|
+
return EXIT.OK;
|
|
18
25
|
}
|
|
19
26
|
const byFile = new Map();
|
|
20
27
|
for (const f of findings) {
|
|
@@ -34,5 +41,5 @@ export const report = (findings, summary) => {
|
|
|
34
41
|
console.log(`\n${BOLD}규칙별${RESET}`);
|
|
35
42
|
for (const [rule, n] of [...byRule.entries()].sort((a, b) => b[1] - a[1]))
|
|
36
43
|
console.log(` ${String(n).padStart(5)} ${rule}`);
|
|
37
|
-
return
|
|
44
|
+
return EXIT.FINDINGS;
|
|
38
45
|
};
|
package/dist/utils/resolve.js
CHANGED
|
@@ -89,6 +89,13 @@ const nearestDocName = (left, knownStems) => {
|
|
|
89
89
|
const best = candidates.reduce((a, b) => (b.end > a.end ? b : a));
|
|
90
90
|
return /[가-힣]/.test(left.slice(best.end)) ? null : best.text;
|
|
91
91
|
};
|
|
92
|
+
/**
|
|
93
|
+
* 링크 대상을 상대 경로 표기로 맞춘다.
|
|
94
|
+
*
|
|
95
|
+
* 링크 대상은 항상 그 문서 기준 상대 경로다. `./` 가 없는 `b.md` 를 그대로 넘기면
|
|
96
|
+
* 파일 이름 색인으로 찾게 되어, 같은 이름의 문서가 여럿이면 다른 문서로 풀린다.
|
|
97
|
+
*/
|
|
98
|
+
const asRelativePath = (target) => /^\.{1,2}\//.test(target) ? target : `./${target}`;
|
|
92
99
|
/**
|
|
93
100
|
* 색인 대상 문서 목록만으로 참조 해소 문맥을 만든다. 테스트에서도 이걸 쓴다.
|
|
94
101
|
*
|
|
@@ -122,7 +129,14 @@ export const parseSectionRefs = (path, kind, lines, { mdPaths, nameMap, knownSte
|
|
|
122
129
|
// 링크로 바꾸라고 요구하는 것 자체가 성립하지 않는다 (`rules.md` §3-5 가 코드
|
|
123
130
|
// 주석에 링크가 없다고 인정한 것과 같은 상황). 절 존재 검사는 그대로 받는다
|
|
124
131
|
const linked = span !== undefined || mask?.[m.index] === true;
|
|
125
|
-
|
|
132
|
+
// 같은 문서 앵커 (`(#...)`) 는 대상 경로가 비어 있다. 자기 문서 참조다
|
|
133
|
+
if (span?.target === "") {
|
|
134
|
+
out.push({ num: m[1], targetFile: path, rawTarget: null, reason: "resolved", linked, line: i + 1 });
|
|
135
|
+
continue;
|
|
136
|
+
}
|
|
137
|
+
const docName = span === undefined
|
|
138
|
+
? nearestDocName(line.slice(0, m.index), knownStems)
|
|
139
|
+
: asRelativePath(span.target);
|
|
126
140
|
// 백틱 안에 문서명 없이 들어앉은 `§N` 은 표기법 인용이라 참조가 아니다
|
|
127
141
|
if (mask?.[m.index] && docName === null) {
|
|
128
142
|
continue;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 프로젝트 루트 찾기.
|
|
3
|
+
*
|
|
4
|
+
* 설정 파일이 있는 디렉터리가 루트다. 하위 디렉터리에서 실행해도 같은 범위를 검사한다.
|
|
5
|
+
*/
|
|
6
|
+
import { existsSync } from "node:fs";
|
|
7
|
+
import { dirname, join, resolve } from "node:path";
|
|
8
|
+
import { CONFIG_PATH } from "../constants/paths.js";
|
|
9
|
+
/** start 에서 위로 올라가며 설정 파일이 있는 디렉터리를 찾는다. 없으면 null */
|
|
10
|
+
export const findRoot = (start = process.cwd()) => {
|
|
11
|
+
let dir = resolve(start);
|
|
12
|
+
while (!existsSync(join(dir, CONFIG_PATH))) {
|
|
13
|
+
const parent = dirname(dir);
|
|
14
|
+
if (parent === dir)
|
|
15
|
+
return null;
|
|
16
|
+
dir = parent;
|
|
17
|
+
}
|
|
18
|
+
return dir;
|
|
19
|
+
};
|
package/dist/utils/scan.d.ts
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
|
-
import type { DocIndex } from "../types.ts";
|
|
2
|
-
import type { SpecthreadConfig } from "../config.schema.ts";
|
|
3
|
-
/**
|
|
4
|
-
export declare const
|
|
1
|
+
import type { DocIndex, FileKind } from "../types.ts";
|
|
2
|
+
import type { FileKindsConfig, SpecthreadConfig } from "../config.schema.ts";
|
|
3
|
+
/** config.fileKinds 에서 확장자 → kind 역매핑을 만든다 */
|
|
4
|
+
export declare const buildExtMap: (kinds: FileKindsConfig) => Map<string, FileKind>;
|
|
5
|
+
/** doc 확장자 Set. 링크 대상이 문서인지 판정할 때 쓴다 */
|
|
6
|
+
export declare const docExtSet: (kinds: FileKindsConfig) => Set<string>;
|
|
5
7
|
/**
|
|
6
8
|
* 색인을 만든다. 검사기와 생성기의 유일한 입력이다.
|
|
7
9
|
*
|
|
8
10
|
* 참조 해소 문맥을 먼저 만들어야 하므로 문서 목록을 두 번 본다 - 한 번은 이름 색인을
|
|
9
11
|
* 위해, 한 번은 실제 파싱을 위해. 코드와 JSON 은 헤딩이 없어서 빈 값으로 채운다.
|
|
10
12
|
*/
|
|
11
|
-
export declare const buildIndex: (config: SpecthreadConfig) => DocIndex;
|
|
13
|
+
export declare const buildIndex: (root: string, config: SpecthreadConfig) => DocIndex;
|
package/dist/utils/scan.js
CHANGED
|
@@ -4,14 +4,13 @@
|
|
|
4
4
|
* 검사기와 생성기가 모두 이 색인 하나를 쓴다.
|
|
5
5
|
*/
|
|
6
6
|
import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
|
|
7
|
-
import { join, relative,
|
|
7
|
+
import { join, relative, sep } from "node:path";
|
|
8
|
+
import { CONVENTION_FILES } from "../constants/paths.js";
|
|
8
9
|
import { parseIgnoredLines } from "./ignore.js";
|
|
9
10
|
import { parseMarkdown, parseMarkers } from "./parse.js";
|
|
10
11
|
import { makeRefContext, parseSectionRefs } from "./resolve.js";
|
|
11
|
-
/** 프로젝트 루트 절대 경로. 색인 경로를 여기 기준 상대 경로로 통일하는 데 쓴다 */
|
|
12
|
-
export const REPO_ROOT = normalize(process.cwd());
|
|
13
12
|
/** config.fileKinds 에서 확장자 → kind 역매핑을 만든다 */
|
|
14
|
-
const buildExtMap = (kinds) => {
|
|
13
|
+
export const buildExtMap = (kinds) => {
|
|
15
14
|
const map = new Map();
|
|
16
15
|
for (const ext of kinds.doc)
|
|
17
16
|
map.set(ext.toLowerCase(), "doc");
|
|
@@ -19,6 +18,8 @@ const buildExtMap = (kinds) => {
|
|
|
19
18
|
map.set(ext.toLowerCase(), "source");
|
|
20
19
|
return map;
|
|
21
20
|
};
|
|
21
|
+
/** doc 확장자 Set. 링크 대상이 문서인지 판정할 때 쓴다 */
|
|
22
|
+
export const docExtSet = (kinds) => new Set(kinds.doc.map((e) => e.toLowerCase()));
|
|
22
23
|
/** 확장자로 파일 종류를 결정한다. config.fileKinds 기반 */
|
|
23
24
|
const kindFromPath = (file, extMap) => {
|
|
24
25
|
const dot = file.lastIndexOf(".");
|
|
@@ -42,16 +43,16 @@ const walk = (dir, out = []) => {
|
|
|
42
43
|
return out;
|
|
43
44
|
};
|
|
44
45
|
/**
|
|
45
|
-
* config.path 에서 대상 파일을 모은다.
|
|
46
|
+
* config.path 에서 대상 파일을 모은다. 규약 파일은 `path` 에 없어도 더한다.
|
|
46
47
|
*
|
|
47
48
|
* 값이 디렉터리면 재귀 스캔, 파일이면 직접 로드. 파싱 전략은 확장자로 결정한다.
|
|
48
|
-
* 인식하지 못하는 확장자는 건너뛴다.
|
|
49
|
+
* 인식하지 못하는 확장자는 건너뛴다. 색인 경로는 OS 와 관계없이 `/` 로 잇는다.
|
|
49
50
|
*/
|
|
50
|
-
const collectTargets = (pathConfig, extMap) => {
|
|
51
|
+
const collectTargets = (root, pathConfig, extMap) => {
|
|
51
52
|
const out = [];
|
|
52
53
|
const seen = new Set();
|
|
53
54
|
const add = (abs) => {
|
|
54
|
-
const rel = relative(
|
|
55
|
+
const rel = relative(root, abs).split(sep).join("/");
|
|
55
56
|
if (seen.has(rel))
|
|
56
57
|
return;
|
|
57
58
|
const kind = kindFromPath(rel, extMap);
|
|
@@ -60,18 +61,17 @@ const collectTargets = (pathConfig, extMap) => {
|
|
|
60
61
|
seen.add(rel);
|
|
61
62
|
out.push({ path: rel, kind });
|
|
62
63
|
};
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
}
|
|
64
|
+
const entries = [...Object.values(pathConfig).flat(), ...CONVENTION_FILES];
|
|
65
|
+
for (const entry of entries) {
|
|
66
|
+
const abs = join(root, entry);
|
|
67
|
+
if (!existsSync(abs))
|
|
68
|
+
continue;
|
|
69
|
+
if (statSync(abs).isDirectory()) {
|
|
70
|
+
for (const file of walk(abs))
|
|
71
|
+
add(file);
|
|
72
|
+
}
|
|
73
|
+
else {
|
|
74
|
+
add(abs);
|
|
75
75
|
}
|
|
76
76
|
}
|
|
77
77
|
return out;
|
|
@@ -82,16 +82,16 @@ const collectTargets = (pathConfig, extMap) => {
|
|
|
82
82
|
* 참조 해소 문맥을 먼저 만들어야 하므로 문서 목록을 두 번 본다 - 한 번은 이름 색인을
|
|
83
83
|
* 위해, 한 번은 실제 파싱을 위해. 코드와 JSON 은 헤딩이 없어서 빈 값으로 채운다.
|
|
84
84
|
*/
|
|
85
|
-
export const buildIndex = (config) => {
|
|
85
|
+
export const buildIndex = (root, config) => {
|
|
86
86
|
const extMap = buildExtMap(config.fileKinds);
|
|
87
|
-
const targets = collectTargets(config.path, extMap);
|
|
87
|
+
const targets = collectTargets(root, config.path, extMap);
|
|
88
88
|
const mdPaths = targets.filter((t) => t.kind === "doc").map((t) => t.path);
|
|
89
89
|
const ctx = makeRefContext(mdPaths, config.ignoreDocNames);
|
|
90
90
|
const files = new Map();
|
|
91
91
|
for (const { path, kind } of targets) {
|
|
92
|
-
const lines = readFileSync(join(
|
|
92
|
+
const lines = readFileSync(join(root, path), "utf8").split("\n");
|
|
93
93
|
const sectionRefs = parseSectionRefs(path, kind, lines, ctx);
|
|
94
|
-
const ignored = parseIgnoredLines(lines);
|
|
94
|
+
const ignored = parseIgnoredLines(lines, kind);
|
|
95
95
|
if (kind === "doc") {
|
|
96
96
|
files.set(path, { ...parseMarkdown(path, lines), sectionRefs, ignored });
|
|
97
97
|
}
|
|
@@ -114,5 +114,5 @@ export const buildIndex = (config) => {
|
|
|
114
114
|
});
|
|
115
115
|
}
|
|
116
116
|
}
|
|
117
|
-
return { files, docsByName: ctx.nameMap, config };
|
|
117
|
+
return { root, files, docsByName: ctx.nameMap, config };
|
|
118
118
|
};
|
package/dist/utils/scope.d.ts
CHANGED
|
@@ -3,15 +3,14 @@
|
|
|
3
3
|
*
|
|
4
4
|
* 변경 이력 절은 과거 상태를 적은 곳이다. 지워진 문서를 가리키는 것이 정상이므로
|
|
5
5
|
* 링크·절 참조 검사에서 뺀다. 지키게 하면 이력을 고쳐 써야 하는데, 그건
|
|
6
|
-
*
|
|
7
|
-
*
|
|
6
|
+
* `specthread/rules.md` §2-4 가 이력에 사건 기록을 남기라고 한 것과 어긋난다.
|
|
7
|
+
* 참조 절과 미확정 사항 절은 현재 상태라 검사한다.
|
|
8
8
|
*/
|
|
9
9
|
import type { SpecthreadConfig } from "../config.schema.ts";
|
|
10
|
+
import type { RuleGroup, RuleId } from "../constants/rules.ts";
|
|
10
11
|
import type { Finding, Heading, IndexedFile } from "../types.ts";
|
|
11
12
|
/** 변경 이력 절 안의 줄인지 */
|
|
12
13
|
export declare const inChangeLog: (file: IndexedFile, line: number) => boolean;
|
|
13
|
-
/** 규칙을 적용할 파일인지. skipCheck 의 string 항목(경로 접두사)에 걸리면 제외 */
|
|
14
|
-
export declare const isCheckTarget: (path: string, config: SpecthreadConfig) => boolean;
|
|
15
14
|
/**
|
|
16
15
|
* 목차 블록 안의 줄인지.
|
|
17
16
|
*
|
|
@@ -27,6 +26,14 @@ export declare const inToc: (file: IndexedFile, line: number) => boolean;
|
|
|
27
26
|
* 기계 생성물이 스스로 깨진 참조로 잡힌다.
|
|
28
27
|
*/
|
|
29
28
|
export declare const inRefSection: (file: IndexedFile, line: number) => boolean;
|
|
29
|
+
/**
|
|
30
|
+
* 미확정 사항 절 안의 줄인지.
|
|
31
|
+
*
|
|
32
|
+
* 관리 문서 항목의 제목을 옮겨 온 생성 뷰다. 제목 안의 링크·절 참조·날짜는 관리 문서 기준으로
|
|
33
|
+
* 적힌 것이라, 이 문서 기준으로 검사하면 이 문서에서는 고칠 수 없는 지적이 된다. 원문은
|
|
34
|
+
* 관리 문서에서 검사한다.
|
|
35
|
+
*/
|
|
36
|
+
export declare const inPendingSection: (file: IndexedFile, line: number) => boolean;
|
|
30
37
|
/**
|
|
31
38
|
* 헤딩 줄인지.
|
|
32
39
|
*
|
|
@@ -34,18 +41,37 @@ export declare const inRefSection: (file: IndexedFile, line: number) => boolean;
|
|
|
34
41
|
* 규칙 1 위반이라 그 규칙을 보는 검사가 따로 잡아야 한다.
|
|
35
42
|
*/
|
|
36
43
|
export declare const isHeadingLine: (file: IndexedFile, line: number) => boolean;
|
|
37
|
-
/**
|
|
38
|
-
export declare const
|
|
39
|
-
/**
|
|
44
|
+
/** 마크다운 문서인지. 헤딩·목차·꼬리 절을 갖는 것은 문서뿐이다 */
|
|
45
|
+
export declare const isDoc: (file: IndexedFile) => boolean;
|
|
46
|
+
/** 작업 문서인지. 흡수 후 사라지므로 미확정 사항 절을 만들지 않는다 */
|
|
47
|
+
export declare const isWorkDoc: (path: string, config: SpecthreadConfig) => boolean;
|
|
48
|
+
/** 참조 절을 생성·검사할 문서인지. skipRefs 경로 아래의 문서는 제외한다 */
|
|
40
49
|
export declare const wantsRefSection: (file: IndexedFile, config: SpecthreadConfig) => boolean;
|
|
41
50
|
/** 문서 제목 헤딩 목록. 하나여야 정상이다 */
|
|
42
51
|
export declare const titleHeadings: (file: IndexedFile) => Heading[];
|
|
43
52
|
/** 문서 제목의 헤딩. 하나가 아니면 null */
|
|
44
53
|
export declare const singleTitle: (file: IndexedFile) => Heading | null;
|
|
45
54
|
/**
|
|
46
|
-
*
|
|
55
|
+
* 꼬리 절이 참조 → 미확정 사항 → 변경 이력 순서인지. 없는 절은 건너뛴다.
|
|
56
|
+
*
|
|
57
|
+
* 생성기는 원본 줄 번호로 범위를 교체하며 이 순서를 전제한다.
|
|
58
|
+
*/
|
|
59
|
+
export declare const tailOrderOk: (headings: Heading[]) => boolean;
|
|
60
|
+
/** 규칙 id 의 군 */
|
|
61
|
+
export declare const groupOf: (rule: RuleId) => RuleGroup;
|
|
62
|
+
/**
|
|
63
|
+
* 이 파일에서 유지할 규칙군. null 이면 전부, 빈 집합이면 하나도 없음.
|
|
64
|
+
*
|
|
65
|
+
* skipCheck 문자열 항목은 `{ path, only: [] }` 와 같다. 기본 제외가 앞에 붙는다.
|
|
66
|
+
* 여러 항목이 걸리면 모두 허용하는 군만 남는다.
|
|
67
|
+
*/
|
|
68
|
+
export declare const allowedGroups: (path: string, config: SpecthreadConfig) => Set<RuleGroup> | null;
|
|
69
|
+
/** 이 파일에서 이 군을 검사·생성하는지 */
|
|
70
|
+
export declare const groupAllowed: (path: string, group: RuleGroup, config: SpecthreadConfig) => boolean;
|
|
71
|
+
/**
|
|
72
|
+
* skipCheck 에 걸려 버릴 지적인지.
|
|
47
73
|
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
74
|
+
* 지적이 달린 파일 기준으로 판정한다. 색인 단계에서 파일을 빼면 그 파일을 가리키는 링크·절
|
|
75
|
+
* 참조와 마커 집계가 함께 사라진다.
|
|
50
76
|
*/
|
|
51
|
-
export declare const
|
|
77
|
+
export declare const isSkipped: (finding: Finding, config: SpecthreadConfig) => boolean;
|
package/dist/utils/scope.js
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
|
+
import { TAIL_NAMES } from "../constants/docs.js";
|
|
2
|
+
import { DEFAULT_EXCLUDES } from "../constants/paths.js";
|
|
3
|
+
import { underPath } from "./path-match.js";
|
|
4
|
+
const inRange = (range, line) => range !== null && line >= range.start && line <= range.end;
|
|
1
5
|
/** 변경 이력 절 안의 줄인지 */
|
|
2
|
-
export const inChangeLog = (file, line) => file.changeLogRange
|
|
3
|
-
line >= file.changeLogRange.start &&
|
|
4
|
-
line <= file.changeLogRange.end;
|
|
5
|
-
/** 규칙을 적용할 파일인지. skipCheck 의 string 항목(경로 접두사)에 걸리면 제외 */
|
|
6
|
-
export const isCheckTarget = (path, config) => !config.skipCheck.some((entry) => typeof entry === "string" && path.startsWith(entry));
|
|
6
|
+
export const inChangeLog = (file, line) => inRange(file.changeLogRange, line);
|
|
7
7
|
/**
|
|
8
8
|
* 목차 블록 안의 줄인지.
|
|
9
9
|
*
|
|
10
10
|
* 목차는 헤딩을 복사해 기계가 만든다. 제목에 `§` 가 들어 있으면 목차에도 실려
|
|
11
11
|
* 같은 지적이 두 번 나온다. 생성물은 원본만 검사한다.
|
|
12
12
|
*/
|
|
13
|
-
export const inToc = (file, line) => file.tocBlock
|
|
13
|
+
export const inToc = (file, line) => inRange(file.tocBlock, line);
|
|
14
14
|
/**
|
|
15
15
|
* 참조 절 안의 줄인지.
|
|
16
16
|
*
|
|
@@ -18,9 +18,15 @@ export const inToc = (file, line) => file.tocBlock !== null && line >= file.tocB
|
|
|
18
18
|
* 같은 줄 왼쪽 문서명을 대상으로 삼는 해소 규칙과 방향이 반대다. 그대로 두면
|
|
19
19
|
* 기계 생성물이 스스로 깨진 참조로 잡힌다.
|
|
20
20
|
*/
|
|
21
|
-
export const inRefSection = (file, line) => file.refSection
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
export const inRefSection = (file, line) => inRange(file.refSection, line);
|
|
22
|
+
/**
|
|
23
|
+
* 미확정 사항 절 안의 줄인지.
|
|
24
|
+
*
|
|
25
|
+
* 관리 문서 항목의 제목을 옮겨 온 생성 뷰다. 제목 안의 링크·절 참조·날짜는 관리 문서 기준으로
|
|
26
|
+
* 적힌 것이라, 이 문서 기준으로 검사하면 이 문서에서는 고칠 수 없는 지적이 된다. 원문은
|
|
27
|
+
* 관리 문서에서 검사한다.
|
|
28
|
+
*/
|
|
29
|
+
export const inPendingSection = (file, line) => inRange(file.pendingSection, line);
|
|
24
30
|
/**
|
|
25
31
|
* 헤딩 줄인지.
|
|
26
32
|
*
|
|
@@ -28,10 +34,12 @@ export const inRefSection = (file, line) => file.refSection !== null &&
|
|
|
28
34
|
* 규칙 1 위반이라 그 규칙을 보는 검사가 따로 잡아야 한다.
|
|
29
35
|
*/
|
|
30
36
|
export const isHeadingLine = (file, line) => file.headings.some((h) => h.line === line);
|
|
31
|
-
/**
|
|
32
|
-
export const
|
|
33
|
-
/**
|
|
34
|
-
export const
|
|
37
|
+
/** 마크다운 문서인지. 헤딩·목차·꼬리 절을 갖는 것은 문서뿐이다 */
|
|
38
|
+
export const isDoc = (file) => file.kind === "doc";
|
|
39
|
+
/** 작업 문서인지. 흡수 후 사라지므로 미확정 사항 절을 만들지 않는다 */
|
|
40
|
+
export const isWorkDoc = (path, config) => underPath(path, config.work);
|
|
41
|
+
/** 참조 절을 생성·검사할 문서인지. skipRefs 경로 아래의 문서는 제외한다 */
|
|
42
|
+
export const wantsRefSection = (file, config) => isDoc(file) && !config.skipRefs.some((base) => underPath(file.path, base));
|
|
35
43
|
/** 문서 제목 헤딩 목록. 하나여야 정상이다 */
|
|
36
44
|
export const titleHeadings = (file) => file.headings.filter((h) => h.level === 1);
|
|
37
45
|
/** 문서 제목의 헤딩. 하나가 아니면 null */
|
|
@@ -40,16 +48,44 @@ export const singleTitle = (file) => {
|
|
|
40
48
|
return titles.length === 1 ? titles[0] : null;
|
|
41
49
|
};
|
|
42
50
|
/**
|
|
43
|
-
*
|
|
51
|
+
* 꼬리 절이 참조 → 미확정 사항 → 변경 이력 순서인지. 없는 절은 건너뛴다.
|
|
52
|
+
*
|
|
53
|
+
* 생성기는 원본 줄 번호로 범위를 교체하며 이 순서를 전제한다.
|
|
54
|
+
*/
|
|
55
|
+
export const tailOrderOk = (headings) => {
|
|
56
|
+
const order = headings
|
|
57
|
+
.filter((h) => h.level === 2 && h.tail)
|
|
58
|
+
.map((h) => TAIL_NAMES.indexOf(h.title));
|
|
59
|
+
return order.every((n, i) => i === 0 || n > order[i - 1]);
|
|
60
|
+
};
|
|
61
|
+
/** 규칙 id 의 군 */
|
|
62
|
+
export const groupOf = (rule) => rule.split("/")[0];
|
|
63
|
+
/**
|
|
64
|
+
* 이 파일에서 유지할 규칙군. null 이면 전부, 빈 집합이면 하나도 없음.
|
|
65
|
+
*
|
|
66
|
+
* skipCheck 문자열 항목은 `{ path, only: [] }` 와 같다. 기본 제외가 앞에 붙는다.
|
|
67
|
+
* 여러 항목이 걸리면 모두 허용하는 군만 남는다.
|
|
68
|
+
*/
|
|
69
|
+
export const allowedGroups = (path, config) => {
|
|
70
|
+
let allowed = null;
|
|
71
|
+
for (const entry of [...DEFAULT_EXCLUDES, ...config.skipCheck]) {
|
|
72
|
+
const base = typeof entry === "string" ? entry : entry.path;
|
|
73
|
+
if (!underPath(path, base))
|
|
74
|
+
continue;
|
|
75
|
+
const only = typeof entry === "string" ? [] : entry.only;
|
|
76
|
+
allowed = allowed === null ? new Set(only) : new Set(only.filter((g) => allowed?.has(g)));
|
|
77
|
+
}
|
|
78
|
+
return allowed;
|
|
79
|
+
};
|
|
80
|
+
/** 이 파일에서 이 군을 검사·생성하는지 */
|
|
81
|
+
export const groupAllowed = (path, group, config) => {
|
|
82
|
+
const allowed = allowedGroups(path, config);
|
|
83
|
+
return allowed === null || allowed.has(group);
|
|
84
|
+
};
|
|
85
|
+
/**
|
|
86
|
+
* skipCheck 에 걸려 버릴 지적인지.
|
|
44
87
|
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
88
|
+
* 지적이 달린 파일 기준으로 판정한다. 색인 단계에서 파일을 빼면 그 파일을 가리키는 링크·절
|
|
89
|
+
* 참조와 마커 집계가 함께 사라진다.
|
|
47
90
|
*/
|
|
48
|
-
export const
|
|
49
|
-
if (typeof entry === "string")
|
|
50
|
-
return false;
|
|
51
|
-
if (!finding.file.startsWith(entry.path))
|
|
52
|
-
return false;
|
|
53
|
-
const group = finding.rule.split("/")[0];
|
|
54
|
-
return !entry.only.some((g) => g === group);
|
|
55
|
-
});
|
|
91
|
+
export const isSkipped = (finding, config) => !groupAllowed(finding.file, groupOf(finding.rule), config);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specthread",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Spec-Driven Development (SDD) template. Docs are the single source of truth; code implements docs.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"release:patch": "npm version patch && npm publish && git push --tags",
|
|
25
25
|
"release:minor": "npm version minor && npm publish && git push --tags",
|
|
26
26
|
"release:major": "npm version major && npm publish && git push --tags",
|
|
27
|
-
"docs:check": "node tools/docs/
|
|
27
|
+
"docs:check": "node --test tools/docs/__tests__/scaffold.test.ts",
|
|
28
28
|
"docs:generate": "node tools/docs/bin/generate.ts",
|
|
29
29
|
"docs:test": "node --test \"tools/docs/__tests__/*.test.ts\"",
|
|
30
30
|
"docs:typecheck": "tsc -p tools/tsconfig.json"
|
package/scaffold/AGENTS.md
CHANGED
|
@@ -27,16 +27,14 @@ Spec-Driven Development (SDD) 템플릿. 문서가 단일 진실 원천이고
|
|
|
27
27
|
|
|
28
28
|
## 3. 문서 체계
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
아래 경로는 고정이다.
|
|
31
31
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
32
|
+
| 경로 | 역할 |
|
|
33
|
+
| ----------------------- | ---------------------------------- |
|
|
34
34
|
| `specthread/rules.md` | 문서 형식 규칙 (코어) |
|
|
35
35
|
| `specthread/project.md` | 설정값의 맥락과 프로젝트 고유 설명 |
|
|
36
36
|
| `specthread/pending.md` | 미확정 사항 정본 |
|
|
37
37
|
|
|
38
|
-
문서 유형 정의 (어떤 경로가 어떤 템플릿을 쓰는지) 는 `config.docTypes` 가 정본이다.
|
|
39
|
-
|
|
40
38
|
`docs/` 안 문서를 편집할 때는 `rules.md` 를 먼저 읽는다.
|
|
41
39
|
|
|
42
40
|
## 4. 미확정 마커
|
|
@@ -60,7 +58,7 @@ Markdown 문서 본문에 `PENDING::design::slug` 인용
|
|
|
60
58
|
|
|
61
59
|
`docs/` 안 문서에 적용되는 핵심 규칙. 전체 규칙은 `rules.md`.
|
|
62
60
|
|
|
63
|
-
- **목차**:
|
|
61
|
+
- **목차**: 모든 `##` 헤딩을 나열한다. 꼬리 절 (참조, 미확정 사항, 변경 이력) 은 무번호이고 이 순서로 둔다.
|
|
64
62
|
- **변경 이력**: 문서 하단에 `| 날짜 | 내용 |` 표. 한 커밋이 한 줄.
|
|
65
63
|
- **참조 절**: 도구가 본문 링크를 모아 생성한다. 사람이 쓰지 않는다.
|
|
66
64
|
- **빈 섹션**: `해당 없음 - <이유>`. 제목만 두지 않는다.
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
+
name: check
|
|
2
3
|
description: 문서 정합성 검사를 실행하고 결과를 해석한다
|
|
3
4
|
---
|
|
4
5
|
|
|
@@ -16,7 +17,7 @@ npx specthread check
|
|
|
16
17
|
|
|
17
18
|
출력은 두 부분으로 나뉜다:
|
|
18
19
|
|
|
19
|
-
1. **색인 요약** - 검사 대상 규모 (
|
|
20
|
+
1. **색인 요약** - 검사 대상 규모 (문서/소스 수, 헤딩/링크/절 참조 수, 마커/미확정 항목 수, 인라인 억제 수)
|
|
20
21
|
2. **지적 목록** - 파일별 줄 번호 + 규칙 ID + 메시지
|
|
21
22
|
|
|
22
23
|
## 규칙 ID별 해결 방법
|
|
@@ -27,14 +28,16 @@ npx specthread check
|
|
|
27
28
|
| `reference/stale` | 참조 절이 본문 링크와 어긋남 | `npx specthread gen --write` |
|
|
28
29
|
| `pending/section-stale` | 미확정 사항 절이 관리 문서와 어긋남 | `npx specthread gen --write` |
|
|
29
30
|
| `heading/tail-name-reused` | 본문 절 제목이 꼬리 절 이름과 같음 | 절 제목 변경 |
|
|
31
|
+
| `heading/tail-order` | 꼬리 절 순서가 참조 → 미확정 사항 → 변경 이력이 아님 | 절 순서 변경 후 `npx specthread gen --write` |
|
|
30
32
|
| `section-ref/not-linked` | 다른 문서 절 참조에 앵커 링크가 없음 | 앵커 링크로 변환 |
|
|
31
33
|
| `marker/orphan` | 마커를 가리키는 관리 문서 항목 없음 | `specthread/pending.md`에 항목 추가 |
|
|
34
|
+
| `marker/unknown-type` | 마커·항목의 종류가 `config.markers.types` 에 없음 | 종류를 고치거나 `types` 에 추가 |
|
|
35
|
+
| `pending/unknown-timepoint` | 해결 예정 라벨이 `config.markers.timepoints` 에 없음 | 라벨을 고치거나 `timepoints` 에 추가 |
|
|
32
36
|
| `changelog/order` | 변경 이력 날짜 순서 어긋남 | 날짜 순 정렬 |
|
|
33
|
-
| `style/em-dash` | em dash 사용 | 하이픈으로 교체 |
|
|
34
37
|
|
|
35
38
|
## 행동 지침
|
|
36
39
|
|
|
37
|
-
1. 검사를 실행한다.
|
|
40
|
+
1. 검사를 실행한다. 설정을 읽지 못해 종료 코드 2 로 끝나면, 출력된 파일과 키를 고친 뒤 다시 실행한다.
|
|
38
41
|
2. 지적이 0건이면 "문서 정합성 검사 통과"로 끝낸다.
|
|
39
42
|
3. 지적이 있으면:
|
|
40
43
|
- `toc/stale`, `reference/stale`, `pending/section-stale`은 `npx specthread gen --write`로 한번에 해결할 수 있다고 안내한다.
|