specthread 0.1.5 → 0.2.1

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 (75) hide show
  1. package/README.md +171 -66
  2. package/dist/bin/check.js +9 -34
  3. package/dist/bin/cli.js +5 -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 +15 -6
  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 +57 -23
  14. package/dist/checks/references.js +2 -2
  15. package/dist/checks/sections.js +3 -6
  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 +121 -47
  23. package/dist/commands/upgrade-prompt.d.ts +12 -0
  24. package/dist/commands/upgrade-prompt.js +147 -0
  25. package/dist/config-loader.d.ts +44 -1
  26. package/dist/config-loader.js +219 -36
  27. package/dist/config.schema.d.ts +16 -35
  28. package/dist/config.schema.js +1 -7
  29. package/dist/constants/docs.d.ts +8 -4
  30. package/dist/constants/docs.js +8 -5
  31. package/dist/constants/exit.d.ts +12 -0
  32. package/dist/constants/exit.js +12 -0
  33. package/dist/constants/paths.d.ts +25 -0
  34. package/dist/constants/paths.js +25 -0
  35. package/dist/constants/patterns.d.ts +13 -6
  36. package/dist/constants/patterns.js +16 -6
  37. package/dist/constants/rules.d.ts +7 -3
  38. package/dist/constants/rules.js +7 -3
  39. package/dist/gen/pending-section.js +20 -16
  40. package/dist/gen/references.js +13 -9
  41. package/dist/gen/summary.d.ts +1 -1
  42. package/dist/gen/summary.js +11 -7
  43. package/dist/gen/toc.js +5 -2
  44. package/dist/run-check.d.ts +5 -0
  45. package/dist/run-check.js +35 -0
  46. package/dist/types.d.ts +6 -4
  47. package/dist/utils/anchor.d.ts +1 -1
  48. package/dist/utils/anchor.js +1 -1
  49. package/dist/utils/ignore.d.ts +2 -8
  50. package/dist/utils/ignore.js +23 -6
  51. package/dist/utils/parse.d.ts +6 -6
  52. package/dist/utils/parse.js +18 -27
  53. package/dist/utils/path-match.d.ts +19 -0
  54. package/dist/utils/path-match.js +27 -0
  55. package/dist/utils/report.d.ts +1 -7
  56. package/dist/utils/report.js +10 -3
  57. package/dist/utils/resolve.d.ts +15 -5
  58. package/dist/utils/resolve.js +63 -25
  59. package/dist/utils/root.d.ts +2 -0
  60. package/dist/utils/root.js +19 -0
  61. package/dist/utils/scan.d.ts +1 -3
  62. package/dist/utils/scan.js +28 -26
  63. package/dist/utils/scope.d.ts +37 -11
  64. package/dist/utils/scope.js +60 -24
  65. package/package.json +3 -3
  66. package/scaffold/AGENTS.md +4 -6
  67. package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
  68. package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +5 -3
  69. package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
  70. package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
  71. package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
  72. package/scaffold/pending.md +1 -1
  73. package/scaffold/project.md +1 -1
  74. package/scaffold/rules.md +28 -27
  75. package/scaffold/templates/plan.md +3 -7
@@ -9,7 +9,7 @@
9
9
  * 어느 파일을 열어야 하는지 나온다. 한 파일이 한 군을 갖고, 한 군은 여러 검사를 갖는다 -
10
10
  * 같은 파싱을 반복하지 않기 위해서다.
11
11
  *
12
- * 규칙 본문은 `docs/system/rules.md` 가 갖고 각 절이 자기 id 를 병기한다.
12
+ * 규칙 본문은 `specthread/rules.md` 가 갖고 각 절이 자기 id 를 병기한다.
13
13
  */
14
14
  export declare const RULE: {
15
15
  readonly CHANGELOG: {
@@ -23,6 +23,8 @@ export declare const RULE: {
23
23
  readonly NUMBERED_TAIL: 'heading/numbered-tail';
24
24
  /** 꼬리 절 예약어를 본문 절이 쓴다 */
25
25
  readonly TAIL_NAME_REUSED: 'heading/tail-name-reused';
26
+ /** 꼬리 절이 참조 → 미확정 사항 → 변경 이력 순서가 아니다 */
27
+ readonly TAIL_ORDER: 'heading/tail-order';
26
28
  };
27
29
  readonly LINK: {
28
30
  /** 링크 대상 파일이 없다 */
@@ -35,6 +37,8 @@ export declare const RULE: {
35
37
  readonly ORPHAN: 'marker/orphan';
36
38
  /** 관리 문서 항목을 가리키는 마커가 없다 */
37
39
  readonly UNMARKED: 'marker/unmarked';
40
+ /** 마커나 관리 문서 항목의 종류가 `markers.types` 에 없다 */
41
+ readonly UNKNOWN_TYPE: 'marker/unknown-type';
38
42
  };
39
43
  readonly PENDING: {
40
44
  /** 항목 첫 줄에 본문이 이어붙었다 */
@@ -45,6 +49,8 @@ export declare const RULE: {
45
49
  readonly WORK_LINK: 'pending/work-link';
46
50
  /** 시점 표기가 형식에 안 맞는다 */
47
51
  readonly TIMEPOINT: 'pending/timepoint';
52
+ /** 해결 예정 라벨이 `markers.timepoints` 에 없다 */
53
+ readonly UNKNOWN_TIMEPOINT: 'pending/unknown-timepoint';
48
54
  /** 항목이 `li` 로 적혀 있다. 관리 문서 항목은 헤딩이라 앵커를 갖는다 */
49
55
  readonly ITEM_SHAPE: 'pending/item-shape';
50
56
  /** 절 머리 요약 표가 없다 */
@@ -73,8 +79,6 @@ export declare const RULE: {
73
79
  readonly NO_DOC_NAME: 'section-ref/no-doc-name';
74
80
  };
75
81
  readonly STYLE: {
76
- /** em dash 를 썼다 */
77
- readonly EM_DASH: 'style/em-dash';
78
82
  /** 코드에 있는 검사 id 가 규칙 문서에 선언되지 않았다 */
79
83
  readonly RULE_UNDECLARED: 'style/rule-undeclared';
80
84
  };
@@ -9,7 +9,7 @@
9
9
  * 어느 파일을 열어야 하는지 나온다. 한 파일이 한 군을 갖고, 한 군은 여러 검사를 갖는다 -
10
10
  * 같은 파싱을 반복하지 않기 위해서다.
11
11
  *
12
- * 규칙 본문은 `docs/system/rules.md` 가 갖고 각 절이 자기 id 를 병기한다.
12
+ * 규칙 본문은 `specthread/rules.md` 가 갖고 각 절이 자기 id 를 병기한다.
13
13
  */
14
14
  export const RULE = {
15
15
  CHANGELOG: {
@@ -23,6 +23,8 @@ export const RULE = {
23
23
  NUMBERED_TAIL: 'heading/numbered-tail',
24
24
  /** 꼬리 절 예약어를 본문 절이 쓴다 */
25
25
  TAIL_NAME_REUSED: 'heading/tail-name-reused',
26
+ /** 꼬리 절이 참조 → 미확정 사항 → 변경 이력 순서가 아니다 */
27
+ TAIL_ORDER: 'heading/tail-order',
26
28
  },
27
29
  LINK: {
28
30
  /** 링크 대상 파일이 없다 */
@@ -35,6 +37,8 @@ export const RULE = {
35
37
  ORPHAN: 'marker/orphan',
36
38
  /** 관리 문서 항목을 가리키는 마커가 없다 */
37
39
  UNMARKED: 'marker/unmarked',
40
+ /** 마커나 관리 문서 항목의 종류가 `markers.types` 에 없다 */
41
+ UNKNOWN_TYPE: 'marker/unknown-type',
38
42
  },
39
43
  PENDING: {
40
44
  /** 항목 첫 줄에 본문이 이어붙었다 */
@@ -45,6 +49,8 @@ export const RULE = {
45
49
  WORK_LINK: 'pending/work-link',
46
50
  /** 시점 표기가 형식에 안 맞는다 */
47
51
  TIMEPOINT: 'pending/timepoint',
52
+ /** 해결 예정 라벨이 `markers.timepoints` 에 없다 */
53
+ UNKNOWN_TIMEPOINT: 'pending/unknown-timepoint',
48
54
  /** 항목이 `li` 로 적혀 있다. 관리 문서 항목은 헤딩이라 앵커를 갖는다 */
49
55
  ITEM_SHAPE: 'pending/item-shape',
50
56
  /** 절 머리 요약 표가 없다 */
@@ -73,8 +79,6 @@ export const RULE = {
73
79
  NO_DOC_NAME: 'section-ref/no-doc-name',
74
80
  },
75
81
  STYLE: {
76
- /** em dash 를 썼다 */
77
- EM_DASH: 'style/em-dash',
78
82
  /** 코드에 있는 검사 id 가 규칙 문서에 선언되지 않았다 */
79
83
  RULE_UNDECLARED: 'style/rule-undeclared',
80
84
  },
@@ -2,28 +2,28 @@
2
2
  * 미확정 사항 절 생성 - 관리 문서 항목의 백링크를 문서 기준으로 뒤집는다.
3
3
  *
4
4
  * 각 관리 문서 항목의 `참조:` 줄이 어느 문서를 가리키는지 이미 안다. 그것을 대상
5
- * 문서 기준으로 재정렬하면 그 문서의 미확정 목록이 나온다 (`docs/system/rules.md` §4).
5
+ * 문서 기준으로 재정렬하면 그 문서의 미확정 목록이 나온다 (`specthread/rules.md` §4).
6
6
  * 목차·참조 절과 같은 방식이다 - 정본은 관리 문서이고 여기는 생성 뷰다.
7
7
  *
8
8
  * **이미 절을 가진 문서만 채운다.** 참조는 _이 항목이 이 문서와 관련 있다_ 는
9
- * 인용이지 _이 문서가 이 미확정을 소유한다_ 는 선언이 아니다. `STATUS.md` 처럼
10
- * 배경으로 인용될 뿐인 문서에 절을 새로 만들면 소유하지 않는 것을 소유한 듯 보인다.
9
+ * 인용이지 _이 문서가 이 미확정을 소유한다_ 는 선언이 아니다. 배경으로 인용될 뿐인
10
+ * 문서에 절을 새로 만들면 소유하지 않는 것을 소유한 것으로 보인다.
11
11
  *
12
12
  * **소비자가 둘이다.** `bin/generate.ts` 가 파일에 쓰고, `checks/pending.ts` 가 같은
13
13
  * 함수를 불러 지금 내용과 비교한다.
14
14
  */
15
- import { dirname, join, normalize, relative } from 'node:path';
16
- const ITEM_HEADING = /^###\s+`\[([a-z]+::[a-z0-9][a-z0-9-]*)\]`\s*(.*)$/;
15
+ import { basename, dirname, join, normalize, relative } from 'node:path';
16
+ import { PENDING_PATH } from '../constants/paths.js';
17
+ import { ITEM_HEADING } from '../constants/patterns.js';
18
+ import { eachContentLine } from '../utils/parse.js';
19
+ import { inChangeLog, isWorkDoc } from '../utils/scope.js';
17
20
  const REF_LINK = /\]\(([^)\s]+)\)/g;
18
21
  /** 관리 문서를 훑어 항목마다 (제목·앵커) 와 `참조:` 가 가리키는 대상 파일 집합을 뽑는다 */
19
22
  const parseItems = (pending) => {
20
23
  const out = [];
21
24
  let current = null;
22
- let inChangeLog = false;
23
- pending.lines.forEach((raw, i) => {
24
- if (/^## 변경 이력/.test(raw))
25
- inChangeLog = true;
26
- if (inChangeLog)
25
+ eachContentLine(pending.lines, (raw, i) => {
26
+ if (inChangeLog(pending, i + 1))
27
27
  return;
28
28
  const h = ITEM_HEADING.exec(raw);
29
29
  if (h !== null) {
@@ -68,17 +68,18 @@ export const invertByTarget = (pending) => {
68
68
  export const pendingSectionBlock = (file, byTarget, index) => {
69
69
  if (file.pendingSection === null)
70
70
  return [];
71
- if (file.path.startsWith(index.config.work))
71
+ if (isWorkDoc(file.path, index.config))
72
72
  return [];
73
73
  const items = byTarget.get(file.path) ?? [];
74
- const rel = relative(dirname(file.path), index.config.pending);
74
+ const rel = relative(dirname(file.path), PENDING_PATH);
75
75
  const link = rel.startsWith('.') ? rel : `./${rel}`;
76
+ const name = basename(PENDING_PATH);
76
77
  if (items.length === 0) {
77
- return ['', `해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([\`pending.md\`](${link})).`, ''];
78
+ return ['', `해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([\`${name}\`](${link})).`, ''];
78
79
  }
79
80
  return [
80
81
  '',
81
- `> **정본은 [\`pending.md\`](${link}) 다.** 이 절은 그 항목을 이 문서 기준으로 되짚은 생성 뷰다.`,
82
+ `> **정본은 [\`${name}\`](${link}) 다.** 이 절은 그 항목을 이 문서 기준으로 되짚은 생성 뷰다.`,
82
83
  '',
83
84
  ...items.map((it) => `- [\`${it.slug}\`](${link}#${it.anchor}) ${it.title}`),
84
85
  '',
@@ -86,15 +87,18 @@ export const pendingSectionBlock = (file, byTarget, index) => {
86
87
  };
87
88
  /** 미확정 사항 절을 채운 문서 줄 목록. 바꿀 것이 없으면 null */
88
89
  export const applyPendingSection = (file, lines, index) => {
89
- if (file.path === index.config.pending)
90
+ if (file.path === PENDING_PATH)
90
91
  return null;
91
- const pending = index.files.get(index.config.pending);
92
+ const pending = index.files.get(PENDING_PATH);
92
93
  if (pending === undefined)
93
94
  return null;
94
95
  const block = pendingSectionBlock(file, invertByTarget(pending), index);
95
96
  if (block.length === 0 || file.pendingSection === null)
96
97
  return null;
97
98
  const { start, end } = file.pendingSection;
99
+ // 억제된 블록은 손으로 관리하는 것이다
100
+ if (file.ignored.has(start))
101
+ return null;
98
102
  const current = lines.slice(start - 1, end);
99
103
  if (current.join('\n') === block.join('\n'))
100
104
  return null;
@@ -2,7 +2,7 @@
2
2
  * 참조 절 생성 - 본문 링크를 대상별로 모아 문서 하단 `## 참조` 절을 채운다.
3
3
  *
4
4
  * 참조 절은 **이 문서를 이해하려면 읽어야 하는 대상 목록** 이고, 대상의 어느 절을
5
- * 읽어야 하는지는 본문 인라인 링크가 갖는다 (`docs/system/rules.md` §3-3). 그래서
5
+ * 읽어야 하는지는 본문 인라인 링크가 갖는다 (`specthread/rules.md` §3-3). 그래서
6
6
  * 라벨의 `§` 표기와 앵커는 떼고 파일만 남긴다 - 같은 대상을 한 줄로 합칠 때 서로
7
7
  * 다른 앵커 중 하나를 고를 근거도 없다.
8
8
  *
@@ -14,6 +14,7 @@
14
14
  * _무엇이 옳은 내용인가_ 를 한곳에서만 정의하려면 이 방향이 맞다.
15
15
  */
16
16
  import { basename, dirname, extname, join, normalize } from "node:path";
17
+ import { TAIL } from "../constants/docs.js";
17
18
  import { docExtSet } from "../utils/scan.js";
18
19
  import { wantsRefSection } from "../utils/scope.js";
19
20
  /** 코드·데이터 대상인지. doc 확장자가 아니고 디렉터리도 아니면 코드로 본다 */
@@ -24,8 +25,8 @@ const isCode = (path, docExts) => {
24
25
  /**
25
26
  * 링크 대상의 리포 루트 기준 위치. 같은 파일 이름이 겹칠 때 라벨로 쓴다.
26
27
  *
27
- * 앞머리만 떼면 구분이 사라진다 - `client/README.md` 안에서 `../CLAUDE.md` 와
28
- * `./CLAUDE.md` 는 서로 다른 파일인데 둘 다 `CLAUDE.md` 가 된다.
28
+ * 앞머리만 떼면 구분이 사라진다 - `docs/guide.md` 안에서 `../README.md` 와
29
+ * `./README.md` 는 서로 다른 파일인데 둘 다 `README.md` 가 된다.
29
30
  */
30
31
  const repoPath = (from, target) => normalize(join(dirname(from), target));
31
32
  /**
@@ -65,8 +66,8 @@ const collect = (file) => {
65
66
  /**
66
67
  * 대상별 표시 이름.
67
68
  *
68
- * 기본은 파일 이름이고, 한 문서 안에서 같은 이름이 둘 이상 나오면 리포 안 위치를
69
- * 알 만큼 앞을 붙인다 - `CLAUDE.md` 는 루트와 client 두 곳에 있다.
69
+ * 기본은 파일 이름이고, 한 문서 안에서 같은 이름이 둘 이상 나오면 리포 루트 기준
70
+ * 경로로 표시한다. 루트와 `docs/` 의 `README.md` 처럼 이름이 같은 파일을 구분하기 위해서다.
70
71
  */
71
72
  const labels = (from, targets) => {
72
73
  const seen = new Map();
@@ -114,21 +115,21 @@ export const referenceBlock = (file, config) => {
114
115
  /**
115
116
  * 참조 절을 새로 넣은 줄 목록.
116
117
  *
117
- * 꼬리 절 순서가 참조 → 미확정 사항 → 변경 이력 이므로 (`docs/system/rules.md`
118
- * 규칙 8) 뒤 두 개 중 먼저 오는 것 앞에 놓는다. 꼬리 절이 하나도 없으면 파일 끝에
118
+ * 꼬리 절 순서가 참조 → 미확정 사항 → 변경 이력 이므로 (`specthread/rules.md`
119
+ * §2-5) 뒤 두 개 중 먼저 오는 것 앞에 놓는다. 꼬리 절이 하나도 없으면 파일 끝에
119
120
  * 붙이고, 이때만 앞에 빈 줄을 하나 둔다 - 다른 자리는 앞 절이 이미 빈 줄로 끝난다.
120
121
  */
121
122
  const insert = (file, lines, block) => {
122
123
  const nextTail = file.headings.find((h) => h.level === 2 && h.tail);
123
124
  if (nextTail !== undefined) {
124
125
  const at = nextTail.line - 1;
125
- return [...lines.slice(0, at), "## 참조", ...block, ...lines.slice(at)];
126
+ return [...lines.slice(0, at), `## ${TAIL.REFS}`, ...block, ...lines.slice(at)];
126
127
  }
127
128
  // 파일 끝 빈 줄은 버린다. 블록이 빈 줄로 끝나므로 줄바꿈은 그쪽이 갖는다
128
129
  let end = lines.length;
129
130
  while (end > 0 && lines[end - 1].trim() === "")
130
131
  end--;
131
- return [...lines.slice(0, end), "", "## 참조", ...block];
132
+ return [...lines.slice(0, end), "", `## ${TAIL.REFS}`, ...block];
132
133
  };
133
134
  /**
134
135
  * 참조 절을 채우거나 새로 넣은 문서 줄 목록. 바꿀 것이 없으면 null.
@@ -141,6 +142,9 @@ export const applyReferences = (file, lines, index) => {
141
142
  if (file.refSection === null)
142
143
  return insert(file, lines, block);
143
144
  const { start, end } = file.refSection;
145
+ // 억제된 블록은 손으로 관리하는 것이다
146
+ if (file.ignored.has(start))
147
+ return null;
144
148
  const current = lines.slice(start - 1, end);
145
149
  // 이미 맞으면 건드리지 않는다. 생성기를 두 번 돌려도 결과가 같아야 한다
146
150
  if (current.join("\n") === block.join("\n"))
@@ -1,6 +1,6 @@
1
1
  import type { DocIndex, IndexedFile } from '../types.ts';
2
2
  /** 관리 문서인지. 표는 그 한 파일에만 붙는다 */
3
- export declare const isPendingDoc: (file: IndexedFile, index: DocIndex) => boolean;
3
+ export declare const isPendingDoc: (file: IndexedFile) => boolean;
4
4
  /** 표 한 행이 되는 항목 하나 */
5
5
  export interface SummaryRow {
6
6
  slug: string;
@@ -12,18 +12,19 @@
12
12
  * **소비자가 둘이다.** `bin/generate.ts` 가 파일에 쓰고, `checks/pending.ts` 가 같은
13
13
  * 함수를 불러 지금 내용과 비교한다.
14
14
  */
15
- import { TIMEPOINT } from '../constants/patterns.js';
15
+ import { PENDING_PATH } from '../constants/paths.js';
16
+ import { ITEM_HEADING, TIMEPOINT } from '../constants/patterns.js';
16
17
  import { slugify } from '../utils/anchor.js';
18
+ import { eachContentLine } from '../utils/parse.js';
19
+ import { isWorkDoc } from '../utils/scope.js';
17
20
  /** 관리 문서인지. 표는 그 한 파일에만 붙는다 */
18
- export const isPendingDoc = (file, index) => file.path === index.config.pending;
19
- /** 항목 헤딩. id 와 제목을 함께 캡처한다 */
20
- const ITEM_HEADING = /^###\s+`\[([a-z]+::[a-z0-9][a-z0-9-]*)\]`\s*(.*)$/;
21
+ export const isPendingDoc = (file) => file.path === PENDING_PATH;
21
22
  /** 항목 첫 본문 줄의 시점 표기 */
22
23
  const TIMEPOINT_LINE = new RegExp(`^${TIMEPOINT.source}$`);
23
24
  const sections = (lines) => {
24
25
  const out = [];
25
26
  let cur = null;
26
- lines.forEach((line, i) => {
27
+ eachContentLine(lines, (line, i) => {
27
28
  if (/^##\s+\d/.test(line)) {
28
29
  cur = { heading: i + 1, blockStart: i + 2, blockEnd: i + 1, items: [] };
29
30
  out.push(cur);
@@ -49,7 +50,7 @@ const sections = (lines) => {
49
50
  const markerSites = (index) => {
50
51
  const out = new Map();
51
52
  for (const file of index.files.values()) {
52
- if (file.path.startsWith(index.config.work))
53
+ if (isWorkDoc(file.path, index.config))
53
54
  continue;
54
55
  for (const marker of file.markers) {
55
56
  if (marker.slug === '')
@@ -107,7 +108,7 @@ export const summaryBlocks = (lines, index) => {
107
108
  * 절이 여럿이라 **아래 절부터** 갈아끼운다. 위를 먼저 고치면 아래 절의 줄 번호가 밀린다.
108
109
  */
109
110
  export const applySummary = (file, lines, index) => {
110
- if (!isPendingDoc(file, index))
111
+ if (!isPendingDoc(file))
111
112
  return null;
112
113
  const blocks = summaryBlocks(lines, index);
113
114
  if (blocks.length === 0)
@@ -115,6 +116,9 @@ export const applySummary = (file, lines, index) => {
115
116
  let next = lines;
116
117
  let changed = false;
117
118
  for (const { blockStart, blockEnd, block } of [...blocks].reverse()) {
119
+ // 억제된 표는 손으로 관리하는 것이다
120
+ if (file.ignored.has(blockStart))
121
+ continue;
118
122
  const current = next.slice(blockStart - 1, blockEnd);
119
123
  if (current.join('\n') === block.join('\n'))
120
124
  continue;
package/dist/gen/toc.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * 목차 생성 - `##` 헤딩을 모아 제목 아래 블록을 채운다.
3
3
  *
4
4
  * 목차는 같은 정보가 두 곳에 생기는 대표 사례라 손으로 관리하면 반드시 어긋난다
5
- * (`docs/system/rules.md` §2-2). 여기서 만드는 문자열이 검사기의 기대값도 된다.
5
+ * (`specthread/rules.md` §2-2). 여기서 만드는 문자열이 검사기의 기대값도 된다.
6
6
  *
7
7
  * **소비자가 둘이다.** `bin/generate.ts` 가 파일에 쓰고, `checks/toc.ts` 가 같은 함수를
8
8
  * 불러 지금 내용과 비교한다. 검사기가 생성기를 부르는 것이 거꾸로 보이지만,
@@ -49,6 +49,9 @@ export const applyToc = (file, lines) => {
49
49
  return null;
50
50
  if (file.tocBlock !== null) {
51
51
  const { start, end } = file.tocBlock;
52
+ // 억제된 블록은 손으로 관리하는 것이다
53
+ if (file.ignored.has(start))
54
+ return null;
52
55
  const current = lines.slice(start - 1, end);
53
56
  // 이미 맞으면 건드리지 않는다. 생성기를 두 번 돌려도 결과가 같아야 한다
54
57
  if (current.join("\n") === block.join("\n")) {
@@ -56,7 +59,7 @@ export const applyToc = (file, lines) => {
56
59
  }
57
60
  return [...lines.slice(0, start - 1), ...block, ...lines.slice(end)];
58
61
  }
59
- // 제목 줄은 색인에서 꺼낸다. 본문을 다시 훑으면 펜스 안 `# ` 를 제목으로 볼 수 있다
62
+ // 제목 줄은 색인에서 꺼낸다. 본문을 다시 훑으면 코드블록 안 `# ` 를 제목으로 볼 수 있다
60
63
  return [
61
64
  ...lines.slice(0, title.line),
62
65
  "",
@@ -0,0 +1,5 @@
1
+ import type { DocIndex, Finding } from './types.ts';
2
+ /** 활성 검사의 지적 전부. 범위 판정 전이다 */
3
+ export declare const collectFindings: (index: DocIndex) => Finding[];
4
+ /** skipCheck·기본 제외·인라인 억제를 거친 지적 */
5
+ export declare const runCheck: (index: DocIndex) => Finding[];
@@ -0,0 +1,35 @@
1
+ /**
2
+ * 검사 실행 - 색인에 활성 검사를 모두 걸고 범위 밖 지적을 거른다.
3
+ *
4
+ * 진입점 (`bin/check.ts`) 과 테스트가 같은 경로로 검사를 돌리도록 분리해 둔다.
5
+ */
6
+ import { checkChangeLog } from './checks/changelog.js';
7
+ import { checkHeadings } from './checks/headings.js';
8
+ import { checkLinks } from './checks/links.js';
9
+ import { checkMarkers } from './checks/markers.js';
10
+ import { checkPending } from './checks/pending.js';
11
+ import { checkReferences } from './checks/references.js';
12
+ import { checkSectionRefs } from './checks/sections.js';
13
+ import { checkRuleDeclared } from './checks/style.js';
14
+ import { checkTimestamps } from './checks/timestamps.js';
15
+ import { checkToc } from './checks/toc.js';
16
+ import { isIgnored } from './utils/ignore.js';
17
+ import { isSkipped } from './utils/scope.js';
18
+ /** 활성 검사의 지적 전부. 범위 판정 전이다 */
19
+ export const collectFindings = (index) => {
20
+ const { features } = index.config;
21
+ return [
22
+ ...checkHeadings(index),
23
+ ...checkToc(index),
24
+ ...(features.references ? checkReferences(index) : []),
25
+ ...checkLinks(index),
26
+ ...checkSectionRefs(index),
27
+ ...checkChangeLog(index),
28
+ ...checkTimestamps(index),
29
+ ...(features.markers ? checkPending(index) : []),
30
+ ...(features.markers ? checkMarkers(index) : []),
31
+ ...checkRuleDeclared(index),
32
+ ];
33
+ };
34
+ /** skipCheck·기본 제외·인라인 억제를 거친 지적 */
35
+ export const runCheck = (index) => collectFindings(index).filter((f) => !isSkipped(f, index.config) && !isIgnored(index, f));
package/dist/types.d.ts CHANGED
@@ -5,8 +5,8 @@ import type { SpecthreadConfig } from './config.schema.ts';
5
5
  * 앵커가 붙은 링크의 라벨 구간과 그 링크 대상.
6
6
  *
7
7
  * 라벨 안에 놓인 `§N` 은 라벨 글자가 아니라 **링크 대상 경로** 로 풀어야 한다.
8
- * `` [`CLAUDE.md` §1](../../CLAUDE.md#1-절대-원칙) `` 에서 라벨만 보면 루트와 client
9
- * 중 어느 `CLAUDE.md` 인지 알 수 없지만 대상 경로는 알려준다.
8
+ * `` [`README.md` §1](../README.md#1-개요) `` 에서 라벨만 보면 어느 디렉터리의
9
+ * `README.md` 인지 알 수 없지만 대상 경로는 알려준다.
10
10
  */
11
11
  export interface AnchorLabelSpan {
12
12
  start: number;
@@ -57,7 +57,7 @@ export interface SectionRef {
57
57
  /**
58
58
  * 앵커 링크 안에 놓인 참조인지.
59
59
  *
60
- * 다른 문서의 절은 앵커 링크로 가리켜야 한다 (`docs/system/rules.md` §3-5).
60
+ * 다른 문서의 절은 앵커 링크로 가리켜야 한다 (`specthread/rules.md` §3-5).
61
61
  * 링크 없이 `§N` 만 적은 것을 가려내는 데 쓴다.
62
62
  */
63
63
  linked: boolean;
@@ -108,10 +108,12 @@ export interface IndexedFile {
108
108
  }
109
109
  /** 색인 전체 */
110
110
  export interface DocIndex {
111
+ /** 프로젝트 루트 절대 경로. 색인 경로는 여기 기준 상대 경로다 */
112
+ root: string;
111
113
  files: Map<string, IndexedFile>;
112
114
  /** 문서 basename·stem → 경로 목록. § 참조 해소에 쓴다 */
113
115
  docsByName: Map<string, string[]>;
114
- /** 로드된 설정. 검사기·생성기가 규약 경로 등에 접근할 때 쓴다 */
116
+ /** 로드된 설정 */
115
117
  config: SpecthreadConfig;
116
118
  }
117
119
  /** 지적 하나. `rule` 로 집계하고 `file`·`line` 으로 자리를 가리킨다 */
@@ -12,7 +12,7 @@ export declare const slugify: (text: string) => string;
12
12
  /**
13
13
  * 헤딩 원문에서 앞머리 번호를 떼어낸다. `6-1. 기본 데미지` → `6-1` + `기본 데미지`
14
14
  *
15
- * 중간 자리에 문자가 오는 `1-B-1` 도 받는다 - `CLAUDE.md` §7 이 정한 형태다.
15
+ * 중간 자리에 문자가 오는 `1-B-1` 도 받는다.
16
16
  */
17
17
  export declare const splitHeadingNum: (raw: string) => {
18
18
  num: string | null;
@@ -16,7 +16,7 @@ export const slugify = (text) => text
16
16
  /**
17
17
  * 헤딩 원문에서 앞머리 번호를 떼어낸다. `6-1. 기본 데미지` → `6-1` + `기본 데미지`
18
18
  *
19
- * 중간 자리에 문자가 오는 `1-B-1` 도 받는다 - `CLAUDE.md` §7 이 정한 형태다.
19
+ * 중간 자리에 문자가 오는 `1-B-1` 도 받는다.
20
20
  */
21
21
  export const splitHeadingNum = (raw) => {
22
22
  const m = /^(\d+(?:-[0-9A-Za-z]+)*)\.\s+(.*)$/.exec(raw);
@@ -1,11 +1,5 @@
1
- /**
2
- * 인라인 억제 - `@specthread-ignore` 로 특정 줄의 지적을 막는다.
3
- *
4
- * 같은 줄이나 바로 윗줄에 `@specthread-ignore` 가 있으면 그 줄의 지적을 건너뛴다.
5
- * eslint-disable-next-line 과 같은 모델이다.
6
- */
7
- import type { DocIndex, Finding } from "../types.ts";
1
+ import type { DocIndex, FileKind, Finding } from "../types.ts";
8
2
  /** 줄 배열에서 억제된 줄 번호(1-indexed)를 모은다 */
9
- export declare const parseIgnoredLines: (lines: string[]) => Set<number>;
3
+ export declare const parseIgnoredLines: (lines: string[], kind?: FileKind) => Set<number>;
10
4
  /** 인라인 억제에 해당하는 지적인지 */
11
5
  export declare const isIgnored: (index: DocIndex, finding: Finding) => boolean;
@@ -1,14 +1,31 @@
1
- const IGNORE = /@specthread-ignore/;
1
+ /**
2
+ * 인라인 억제 - `@specthread-ignore` 로 특정 줄의 지적을 막는다.
3
+ *
4
+ * 같은 줄이나 바로 윗줄에 `@specthread-ignore` 가 있으면 그 줄의 지적을 건너뛴다.
5
+ * eslint-disable-next-line 과 같은 모델이다.
6
+ *
7
+ * 주석 안에 적은 것만 억제로 본다. 코드 스팬·코드블록 안은 표기를 설명하는 글이다.
8
+ */
9
+ import { codeSpanMask, eachContentLine } from "./parse.js";
10
+ /** 주석 여는 표기 뒤의 억제 토큰. `<!--`, `//`, `/*`, `#` */
11
+ const IGNORE = /(?:<!--|\/\/|\/\*|#)\s*@specthread-ignore\b/;
2
12
  /** 줄 배열에서 억제된 줄 번호(1-indexed)를 모은다 */
3
- export const parseIgnoredLines = (lines) => {
13
+ export const parseIgnoredLines = (lines, kind = "source") => {
4
14
  const ignored = new Set();
5
- for (let i = 0; i < lines.length; i++) {
6
- if (!IGNORE.test(lines[i]))
7
- continue;
15
+ const scan = (line, i) => {
16
+ const m = IGNORE.exec(line);
17
+ if (m === null)
18
+ return;
19
+ if (kind === "doc" && codeSpanMask(line)[m.index])
20
+ return;
8
21
  ignored.add(i + 1);
9
22
  if (i + 1 < lines.length)
10
23
  ignored.add(i + 2);
11
- }
24
+ };
25
+ if (kind === "doc")
26
+ eachContentLine(lines, scan);
27
+ else
28
+ lines.forEach((l, i) => scan(l, i));
12
29
  return ignored;
13
30
  };
14
31
  /** 인라인 억제에 해당하는 지적인지 */
@@ -1,8 +1,8 @@
1
1
  import type { AnchorLabelSpan, FileKind, Heading, IndexedFile, Marker, Range } from "../types.ts";
2
2
  /**
3
- * 펜스 코드블록 바깥의 줄만 넘겨준다.
3
+ * 코드블록 바깥의 줄만 넘겨준다.
4
4
  *
5
- * 펜스 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
5
+ * 코드블록을 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
6
6
  * 하므로 언어 표기가 붙은 ` ```markdown ` 도 그대로 잡힌다.
7
7
  */
8
8
  export declare const eachContentLine: (lines: string[], fn: (line: string, index: number) => void) => void;
@@ -10,14 +10,14 @@ export declare const eachContentLine: (lines: string[], fn: (line: string, index
10
10
  * 인라인 백틱 코드 스팬 위치. 각 문자가 코드 안인지 표시한다.
11
11
  *
12
12
  * 백틱 안 `§1-A-3` 은 표기법을 인용한 것이지 참조가 아니다. 반대로
13
- * `` `skill-tree.md §4` `` 처럼 문서명을 함께 담은 것은 실 참조라서, 스팬 안에
14
- * 문서명이 있는지로 갈라야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
13
+ * `` `auth.md §4` `` 처럼 문서명을 함께 담은 것은 실제 참조라서, 스팬 안에
14
+ * 문서명이 있는지로 구분해야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
15
15
  */
16
16
  export declare const codeSpanMask: (line: string) => boolean[];
17
17
  /**
18
18
  * 앵커가 붙은 마크다운 링크의 라벨 구간.
19
19
  *
20
- * `[`battle.md` §7](./battle.md#7-승리---패배-조건)` 처럼 라벨 안에 놓인 `§` 는 이미
20
+ * `[`auth.md` §3](./auth.md#3-인증-흐름)` 처럼 라벨 안에 놓인 `§` 는 이미
21
21
  * 앵커로 걸린 참조라 정상이다. 반대로 라벨 밖 `§` 는 링크 없이 적은 것이다.
22
22
  * 절 참조 파서가 이 구간으로 둘을 가른다.
23
23
  */
@@ -27,7 +27,7 @@ export declare const linkTargetSpans: (line: string) => Range[];
27
27
  /**
28
28
  * 마커를 모은다.
29
29
  *
30
- * doc 은 펜스 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
30
+ * doc 은 코드블록 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
31
31
  * source 는 전부 훑는다. JSON 계열 파일은 `"_pending"` 키 패턴을 추가로 잡는다.
32
32
  */
33
33
  export declare const parseMarkers: (lines: string[], kind: FileKind, path?: string) => Marker[];
@@ -2,22 +2,22 @@
2
2
  * 마크다운 한 파일에서 색인 재료를 뽑는다 - 헤딩·링크·마커·미확정 항목과
3
3
  * 생성기가 덮어쓸 블록의 위치.
4
4
  *
5
- * 펜스 코드블록 안은 전부 무시한다. 템플릿이 골격을 코드블록으로 담고 있어서
6
- * 추적하지 않으면 헤딩 88 개와 링크 90 개가 오탐으로 잡힌다.
5
+ * 코드블록 안은 전부 무시한다. 템플릿과 규칙 문서는 골격과 예시를 코드블록에 담는다.
7
6
  */
8
- import { TAIL_NAMES } from "../constants/docs.js";
7
+ import { TAIL, TAIL_NAMES } from "../constants/docs.js";
8
+ import { MARKER, PENDING_ITEM, PENDING_JSON } from "../constants/patterns.js";
9
9
  import { slugify, splitHeadingNum } from "./anchor.js";
10
10
  /**
11
11
  * 꼬리 절 이름. 하나가 나오면 그 뒤는 전부 꼬리다.
12
12
  *
13
- * 꼬리 절은 문서 맨 끝에 순서대로 오므로 (`docs/system/rules.md` 규칙 8) 첫 꼬리
13
+ * 꼬리 절은 문서 맨 끝에 순서대로 오므로 (`specthread/rules.md` §2-5) 첫 꼬리
14
14
  * 헤딩부터 파일 끝까지를 꼬리로 보면 된다. 하위 절 (`### 문서` 등) 도 따라 잡힌다.
15
15
  */
16
16
  const TAIL_SET = new Set(TAIL_NAMES);
17
17
  /**
18
- * 펜스 코드블록 바깥의 줄만 넘겨준다.
18
+ * 코드블록 바깥의 줄만 넘겨준다.
19
19
  *
20
- * 펜스 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
20
+ * 코드블록을 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
21
21
  * 하므로 언어 표기가 붙은 ` ```markdown ` 도 그대로 잡힌다.
22
22
  */
23
23
  export const eachContentLine = (lines, fn) => {
@@ -35,8 +35,8 @@ export const eachContentLine = (lines, fn) => {
35
35
  * 인라인 백틱 코드 스팬 위치. 각 문자가 코드 안인지 표시한다.
36
36
  *
37
37
  * 백틱 안 `§1-A-3` 은 표기법을 인용한 것이지 참조가 아니다. 반대로
38
- * `` `skill-tree.md §4` `` 처럼 문서명을 함께 담은 것은 실 참조라서, 스팬 안에
39
- * 문서명이 있는지로 갈라야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
38
+ * `` `auth.md §4` `` 처럼 문서명을 함께 담은 것은 실제 참조라서, 스팬 안에
39
+ * 문서명이 있는지로 구분해야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
40
40
  */
41
41
  export const codeSpanMask = (line) => {
42
42
  const mask = new Array(line.length).fill(false);
@@ -57,7 +57,7 @@ export const codeSpanMask = (line) => {
57
57
  /**
58
58
  * 앵커가 붙은 마크다운 링크의 라벨 구간.
59
59
  *
60
- * `[`battle.md` §7](./battle.md#7-승리---패배-조건)` 처럼 라벨 안에 놓인 `§` 는 이미
60
+ * `[`auth.md` §3](./auth.md#3-인증-흐름)` 처럼 라벨 안에 놓인 `§` 는 이미
61
61
  * 앵커로 걸린 참조라 정상이다. 반대로 라벨 밖 `§` 는 링크 없이 적은 것이다.
62
62
  * 절 참조 파서가 이 구간으로 둘을 가른다.
63
63
  */
@@ -84,18 +84,6 @@ export const linkTargetSpans = (line) => {
84
84
  }
85
85
  return spans;
86
86
  };
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
87
  /** 마크다운 링크. 대상에 공백이 없다고 보고 잡는다 */
100
88
  const LINK = /\[([^\]]*)\]\(([^)\s]+)\)/g;
101
89
  /** 변경 이력 표의 첫 칸 날짜 */
@@ -105,7 +93,7 @@ const UNCOMMENTABLE_EXTS = new Set([".json"]);
105
93
  /**
106
94
  * 마커를 모은다.
107
95
  *
108
- * doc 은 펜스 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
96
+ * doc 은 코드블록 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
109
97
  * source 는 전부 훑는다. JSON 계열 파일은 `"_pending"` 키 패턴을 추가로 잡는다.
110
98
  */
111
99
  export const parseMarkers = (lines, kind, path) => {
@@ -251,22 +239,25 @@ export const parseMarkdown = (path, lines) => {
251
239
  dated.push({ line: i + 1, date: date[1] });
252
240
  }
253
241
  });
254
- const changeLogRange = tailRange(headings, "변경 이력", lines.length);
242
+ const changeLogRange = tailRange(headings, TAIL.CHANGELOG, lines.length);
255
243
  // 본문에도 날짜 표가 있을 수 있어서 변경 이력 절 안의 것만 센다
256
244
  const inLog = (line) => changeLogRange !== null &&
257
245
  line >= changeLogRange.start &&
258
246
  line <= changeLogRange.end;
247
+ // 변경 이력은 과거 기록이고 목차는 헤딩의 사본이라 마커로 세지 않는다
248
+ const tocBlock = findTocBlock(lines);
249
+ const inToc = (line) => tocBlock !== null && line >= tocBlock.start && line <= tocBlock.end;
259
250
  return {
260
251
  path,
261
252
  kind: "doc",
262
253
  lines,
263
254
  headings,
264
255
  links,
265
- markers: parseMarkers(lines, "doc", path),
256
+ markers: parseMarkers(lines, "doc", path).filter((m) => !inLog(m.line) && !inToc(m.line)),
266
257
  pendingItems,
267
- tocBlock: findTocBlock(lines),
268
- refSection: tailRange(headings, "참조", lines.length),
269
- pendingSection: tailRange(headings, "미확정 사항", lines.length),
258
+ tocBlock,
259
+ refSection: tailRange(headings, TAIL.REFS, lines.length),
260
+ pendingSection: tailRange(headings, TAIL.PENDING, lines.length),
270
261
  changeLogRange,
271
262
  changeLogDates: dated.filter((d) => inLog(d.line)).map((d) => d.date),
272
263
  };