specthread 0.1.5 → 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.
Files changed (69) hide show
  1. package/README.md +88 -13
  2. package/dist/bin/check.js +9 -34
  3. package/dist/bin/cli.js +4 -4
  4. package/dist/bin/generate.js +32 -19
  5. package/dist/bin/open-project.d.ts +5 -0
  6. package/dist/bin/open-project.js +26 -0
  7. package/dist/checks/changelog.js +5 -4
  8. package/dist/checks/headings.d.ts +0 -1
  9. package/dist/checks/headings.js +13 -4
  10. package/dist/checks/links.js +7 -4
  11. package/dist/checks/markers.d.ts +3 -1
  12. package/dist/checks/markers.js +33 -18
  13. package/dist/checks/pending.js +54 -22
  14. package/dist/checks/references.js +2 -2
  15. package/dist/checks/sections.js +3 -5
  16. package/dist/checks/style.d.ts +0 -8
  17. package/dist/checks/style.js +23 -43
  18. package/dist/checks/timestamps.js +5 -5
  19. package/dist/checks/toc.js +4 -6
  20. package/dist/commands/config-template.d.ts +8 -0
  21. package/{scaffold/config.jsonc → dist/commands/config-template.js} +48 -40
  22. package/dist/commands/init.js +92 -42
  23. package/dist/config-loader.d.ts +22 -1
  24. package/dist/config-loader.js +192 -25
  25. package/dist/config.schema.d.ts +16 -35
  26. package/dist/config.schema.js +1 -7
  27. package/dist/constants/docs.d.ts +7 -2
  28. package/dist/constants/docs.js +7 -3
  29. package/dist/constants/exit.d.ts +12 -0
  30. package/dist/constants/exit.js +12 -0
  31. package/dist/constants/paths.d.ts +25 -0
  32. package/dist/constants/paths.js +25 -0
  33. package/dist/constants/patterns.d.ts +12 -3
  34. package/dist/constants/patterns.js +15 -3
  35. package/dist/constants/rules.d.ts +7 -3
  36. package/dist/constants/rules.js +7 -3
  37. package/dist/gen/pending-section.js +18 -14
  38. package/dist/gen/references.js +9 -5
  39. package/dist/gen/summary.d.ts +1 -1
  40. package/dist/gen/summary.js +9 -6
  41. package/dist/gen/toc.js +4 -1
  42. package/dist/run-check.d.ts +5 -0
  43. package/dist/run-check.js +35 -0
  44. package/dist/types.d.ts +4 -2
  45. package/dist/utils/ignore.d.ts +2 -8
  46. package/dist/utils/ignore.js +23 -6
  47. package/dist/utils/parse.js +11 -19
  48. package/dist/utils/path-match.d.ts +19 -0
  49. package/dist/utils/path-match.js +27 -0
  50. package/dist/utils/report.d.ts +1 -7
  51. package/dist/utils/report.js +10 -3
  52. package/dist/utils/resolve.js +15 -1
  53. package/dist/utils/root.d.ts +2 -0
  54. package/dist/utils/root.js +19 -0
  55. package/dist/utils/scan.d.ts +1 -3
  56. package/dist/utils/scan.js +22 -24
  57. package/dist/utils/scope.d.ts +37 -11
  58. package/dist/utils/scope.js +60 -24
  59. package/package.json +2 -2
  60. package/scaffold/AGENTS.md +4 -6
  61. package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
  62. package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +4 -2
  63. package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
  64. package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
  65. package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
  66. package/scaffold/pending.md +1 -1
  67. package/scaffold/project.md +1 -1
  68. package/scaffold/rules.md +28 -27
  69. package/scaffold/templates/plan.md +3 -7
@@ -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}/`);
@@ -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
- * 종료 코드를 돌려준다 - 지적이 있으면 1. 재편이 끝나면 이 값으로 종료 게이트에 넣는다.
5
+ * 종료 코드를 돌려준다 - 지적이 있으면 `EXIT.FINDINGS`.
12
6
  * 규칙별 집계가 있어야 어느 규칙이 소음을 내는지 보고 판단할 수 있다.
13
7
  */
14
8
  export declare const report: (findings: Finding[], summary: {
@@ -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
- * 종료 코드를 돌려준다 - 지적이 있으면 1. 재편이 끝나면 이 값으로 종료 게이트에 넣는다.
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 0;
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 1;
44
+ return EXIT.FINDINGS;
38
45
  };
@@ -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
- const docName = span?.target ?? nearestDocName(line.slice(0, m.index), knownStems);
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,2 @@
1
+ /** start 에서 위로 올라가며 설정 파일이 있는 디렉터리를 찾는다. 없으면 null */
2
+ export declare const findRoot: (start?: string) => string | null;
@@ -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
+ };
@@ -1,7 +1,5 @@
1
1
  import type { DocIndex, FileKind } from "../types.ts";
2
2
  import type { FileKindsConfig, SpecthreadConfig } from "../config.schema.ts";
3
- /** 프로젝트 루트 절대 경로. 색인 경로를 여기 기준 상대 경로로 통일하는 데 쓴다 */
4
- export declare const REPO_ROOT: string;
5
3
  /** config.fileKinds 에서 확장자 → kind 역매핑을 만든다 */
6
4
  export declare const buildExtMap: (kinds: FileKindsConfig) => Map<string, FileKind>;
7
5
  /** doc 확장자 Set. 링크 대상이 문서인지 판정할 때 쓴다 */
@@ -12,4 +10,4 @@ export declare const docExtSet: (kinds: FileKindsConfig) => Set<string>;
12
10
  * 참조 해소 문맥을 먼저 만들어야 하므로 문서 목록을 두 번 본다 - 한 번은 이름 색인을
13
11
  * 위해, 한 번은 실제 파싱을 위해. 코드와 JSON 은 헤딩이 없어서 빈 값으로 채운다.
14
12
  */
15
- export declare const buildIndex: (config: SpecthreadConfig) => DocIndex;
13
+ export declare const buildIndex: (root: string, config: SpecthreadConfig) => DocIndex;
@@ -4,12 +4,11 @@
4
4
  * 검사기와 생성기가 모두 이 색인 하나를 쓴다.
5
5
  */
6
6
  import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
7
- import { join, relative, normalize } from "node:path";
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
13
  export const buildExtMap = (kinds) => {
15
14
  const map = new Map();
@@ -44,16 +43,16 @@ const walk = (dir, out = []) => {
44
43
  return out;
45
44
  };
46
45
  /**
47
- * config.path 에서 대상 파일을 모은다.
46
+ * config.path 에서 대상 파일을 모은다. 규약 파일은 `path` 에 없어도 더한다.
48
47
  *
49
48
  * 값이 디렉터리면 재귀 스캔, 파일이면 직접 로드. 파싱 전략은 확장자로 결정한다.
50
- * 인식하지 못하는 확장자는 건너뛴다.
49
+ * 인식하지 못하는 확장자는 건너뛴다. 색인 경로는 OS 와 관계없이 `/` 로 잇는다.
51
50
  */
52
- const collectTargets = (pathConfig, extMap) => {
51
+ const collectTargets = (root, pathConfig, extMap) => {
53
52
  const out = [];
54
53
  const seen = new Set();
55
54
  const add = (abs) => {
56
- const rel = relative(REPO_ROOT, abs);
55
+ const rel = relative(root, abs).split(sep).join("/");
57
56
  if (seen.has(rel))
58
57
  return;
59
58
  const kind = kindFromPath(rel, extMap);
@@ -62,18 +61,17 @@ const collectTargets = (pathConfig, extMap) => {
62
61
  seen.add(rel);
63
62
  out.push({ path: rel, kind });
64
63
  };
65
- for (const paths of Object.values(pathConfig)) {
66
- for (const entry of paths) {
67
- const abs = join(REPO_ROOT, entry);
68
- if (!existsSync(abs))
69
- continue;
70
- if (statSync(abs).isDirectory()) {
71
- for (const file of walk(abs))
72
- add(file);
73
- }
74
- else {
75
- add(abs);
76
- }
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);
77
75
  }
78
76
  }
79
77
  return out;
@@ -84,16 +82,16 @@ const collectTargets = (pathConfig, extMap) => {
84
82
  * 참조 해소 문맥을 먼저 만들어야 하므로 문서 목록을 두 번 본다 - 한 번은 이름 색인을
85
83
  * 위해, 한 번은 실제 파싱을 위해. 코드와 JSON 은 헤딩이 없어서 빈 값으로 채운다.
86
84
  */
87
- export const buildIndex = (config) => {
85
+ export const buildIndex = (root, config) => {
88
86
  const extMap = buildExtMap(config.fileKinds);
89
- const targets = collectTargets(config.path, extMap);
87
+ const targets = collectTargets(root, config.path, extMap);
90
88
  const mdPaths = targets.filter((t) => t.kind === "doc").map((t) => t.path);
91
89
  const ctx = makeRefContext(mdPaths, config.ignoreDocNames);
92
90
  const files = new Map();
93
91
  for (const { path, kind } of targets) {
94
- const lines = readFileSync(join(REPO_ROOT, path), "utf8").split("\n");
92
+ const lines = readFileSync(join(root, path), "utf8").split("\n");
95
93
  const sectionRefs = parseSectionRefs(path, kind, lines, ctx);
96
- const ignored = parseIgnoredLines(lines);
94
+ const ignored = parseIgnoredLines(lines, kind);
97
95
  if (kind === "doc") {
98
96
  files.set(path, { ...parseMarkdown(path, lines), sectionRefs, ignored });
99
97
  }
@@ -116,5 +114,5 @@ export const buildIndex = (config) => {
116
114
  });
117
115
  }
118
116
  }
119
- return { files, docsByName: ctx.nameMap, config };
117
+ return { root, files, docsByName: ctx.nameMap, config };
120
118
  };
@@ -3,15 +3,14 @@
3
3
  *
4
4
  * 변경 이력 절은 과거 상태를 적은 곳이다. 지워진 문서를 가리키는 것이 정상이므로
5
5
  * 링크·절 참조 검사에서 뺀다. 지키게 하면 이력을 고쳐 써야 하는데, 그건
6
- * [`docs/system/rules.md`](../../docs/system/rules.md) §2-1 이 이력에 사건 기록을
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 isTargetDoc: (file: IndexedFile, config: SpecthreadConfig) => boolean;
39
- /** 참조 절을 생성·검사할 문서인지. skipRefs 에 등록된 경로는 제외한다 */
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
- * skipCheck 의 객체 항목에 걸리는 지적인지.
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
- * `{ path, only }` 는 해당 경로에서 `only` 에 나열된 규칙군만 유지한다는 뜻이다.
49
- * 그 밖의 규칙군에 속하는 지적은 여기서 걸러진다.
74
+ * 지적이 달린 파일 기준으로 판정한다. 색인 단계에서 파일을 빼면 그 파일을 가리키는 링크·절
75
+ * 참조와 마커 집계가 함께 사라진다.
50
76
  */
51
- export declare const isWorkExempt: (finding: Finding, config: SpecthreadConfig) => boolean;
77
+ export declare const isSkipped: (finding: Finding, config: SpecthreadConfig) => boolean;
@@ -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 !== null &&
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 !== null && line >= file.tocBlock.start && line <= file.tocBlock.end;
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 !== null &&
22
- line >= file.refSection.start &&
23
- line <= file.refSection.end;
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 isTargetDoc = (file, config) => file.kind === 'doc' && isCheckTarget(file.path, config);
33
- /** 참조 절을 생성·검사할 문서인지. skipRefs 에 등록된 경로는 제외한다 */
34
- export const wantsRefSection = (file, config) => isTargetDoc(file, config) && !config.skipRefs.includes(file.path);
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
- * skipCheck 의 객체 항목에 걸리는 지적인지.
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
- * `{ path, only }` 는 해당 경로에서 `only` 에 나열된 규칙군만 유지한다는 뜻이다.
46
- * 그 밖의 규칙군에 속하는 지적은 여기서 걸러진다.
88
+ * 지적이 달린 파일 기준으로 판정한다. 색인 단계에서 파일을 빼면 그 파일을 가리키는 링크·절
89
+ * 참조와 마커 집계가 함께 사라진다.
47
90
  */
48
- export const isWorkExempt = (finding, config) => config.skipCheck.some((entry) => {
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.1.5",
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/bin/check.ts",
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"
@@ -27,16 +27,14 @@ Spec-Driven Development (SDD) 템플릿. 문서가 단일 진실 원천이고
27
27
 
28
28
  ## 3. 문서 체계
29
29
 
30
- 아래는 기본 경로다. `config.jsonc` 에서 override 했으면 그쪽이 우선한다.
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
- - **목차**: `## 1.` 이상 모든 번호 헤딩을 나열한다. 꼬리 절 (참조, 미확정 사항, 변경 이력) 은 무번호.
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`로 한번에 해결할 수 있다고 안내한다.
@@ -1,4 +1,5 @@
1
1
  ---
2
+ name: gen
2
3
  description: 참조 절·목차·요약 표를 생성하고 결과를 안내한다
3
4
  ---
4
5
 
@@ -25,9 +26,9 @@ npx specthread gen --write
25
26
  | 항목 | 동작 | 조건 |
26
27
  |------|------|------|
27
28
  | 참조 절 | 본문 링크를 모아 `## 참조` 절을 채움 | `features.references: true` |
28
- | 목차 | 번호 헤딩을 모아 목차 블록을 갱신 | 항상 |
29
+ | 목차 | `##` 헤딩을 모아 목차 블록을 갱신 | 항상 |
29
30
  | 미확정 사항 절 | `specthread/pending.md` 항목을 문서별 `## 미확정 사항` 절에 반영 | `features.markers: true` |
30
- | 요약 표 | 미확정 사항 절 머리에 종류·시점·마커 수 표를 채움 | `features.markers: true` |
31
+ | 요약 표 | `specthread/pending.md` 의 번호 절 머리에 id·항목·해결 예정·걸린 곳 표를 채움 | `features.markers: true` |
31
32
 
32
33
  ## 행동 지침
33
34
 
@@ -37,5 +38,6 @@ npx specthread gen --write
37
38
  4. 변경이 있으면:
38
39
  - 어떤 파일의 어떤 절이 갱신되는지 요약한다.
39
40
  - 사용자에게 적용 여부를 확인한다.
41
+ 5. "꼬리 절 순서가 어긋나 건너뜀" 이 나오면 그 파일의 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴 뒤 다시 실행한다.
40
42
  - 승인하면 `npx specthread gen --write`를 실행한다.
41
43
  5. 적용 후 `npx specthread check`를 실행해서 생성 관련 지적(`toc/stale`, `reference/stale`, `pending/section-stale`)이 해소되었는지 확인한다.
@@ -1,4 +1,5 @@
1
1
  ---
2
+ name: plan-close
2
3
  description: 완료된 작업의 내용을 spec에 반영하고 work 문서를 삭제한다
3
4
  ---
4
5
 
@@ -1,4 +1,5 @@
1
1
  ---
2
+ name: plan-open
2
3
  description: 작업 계획 문서를 작성하고 검수를 거쳐 확정한다
3
4
  ---
4
5
 
@@ -1,4 +1,5 @@
1
1
  ---
2
+ name: plan-run
2
3
  description: 확정된 계획 문서에 따라 작업을 실행하고 미결 사항을 기록한다
3
4
  ---
4
5
 
@@ -18,7 +18,7 @@
18
18
  | 이 문서 | 항목별 설명·맥락·참조 | 사람 |
19
19
  | 각 문서 `## 미확정 사항` | 해당 문서에 걸린 항목 목록 | 도구 생성 |
20
20
 
21
- **종류마다 `##` 섹션이 하나씩 생긴다.** 종류 값은 `config.markers.types` 가 정의하며, 섹션 안은 id 순 정렬이다. 항목 형식은 [`rules.md` §4-2](./rules.md#4-2-관리-문서) 가 갖는다.
21
+ **종류마다 `##` 섹션을 하나씩 둔다.** 섹션은 사람이 만들고, 종류 값은 `config.markers.types` 에 있어야 한다. 섹션 안은 id 순 정렬이다. 항목 형식은 [`rules.md` §4-2](./rules.md#4-2-관리-문서) 가 갖는다.
22
22
 
23
23
  **섹션 머리 표가 색인이다.** 손으로 고치지 않는다 -- 도구가 항목에서 만든다.
24
24
 
@@ -28,7 +28,7 @@
28
28
 
29
29
  ### 2-2. 미확정 사항 파일
30
30
 
31
- 이름은 [`pending.md`](./pending.md) 다. `config.jsonc` 에서 경로를 override 할 수 있다.
31
+ 이름은 [`pending.md`](./pending.md) 다. 경로는 `specthread/pending.md` 고정이다.
32
32
 
33
33
  ## 참조
34
34