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.
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 +10 -6
  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 +19 -10
  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 +7 -5
  56. package/dist/utils/scan.js +25 -25
  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
@@ -4,7 +4,7 @@
4
4
  * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다. `TAIL_NAMES` 가
5
5
  * `utils/parse.ts` 와 `checks/headings.ts` 에 각각 있어 실제로 그 상태였다.
6
6
  *
7
- * 규칙 본문은 `docs/system/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
7
+ * 규칙 본문은 `specthread/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
8
8
  */
9
9
  /**
10
10
  * 꼬리 절 예약어 (`rules.md` §2-5).
@@ -12,5 +12,9 @@
12
12
  * 파서가 꼬리 절 경계를 잡는 데 쓰고, 검사기가 본문 절이 이 이름을 쓰는지 본다.
13
13
  * 순서가 곧 문서 안 등장 순서다.
14
14
  */
15
- // locale: ko
16
- export const TAIL_NAMES = ['참조', '미확정 사항', '변경 이력'];
15
+ export const TAIL = {
16
+ REFS: '참조',
17
+ PENDING: '미확정 사항',
18
+ CHANGELOG: '변경 이력',
19
+ };
20
+ export const TAIL_NAMES = [TAIL.REFS, TAIL.PENDING, TAIL.CHANGELOG];
@@ -0,0 +1,12 @@
1
+ /**
2
+ * 종료 코드. 지적이 있는 것과 실행 자체가 실패한 것을 나눠, CI 가 설정 오류를
3
+ * 문서 문제로 오인하지 않게 한다.
4
+ */
5
+ export declare const EXIT: {
6
+ /** 지적 없음 */
7
+ readonly OK: 0;
8
+ /** 지적이 있다 */
9
+ readonly FINDINGS: 1;
10
+ /** 실행 실패. 설정 파일이 없거나 읽지 못했거나, 명령을 모른다 */
11
+ readonly FAILURE: 2;
12
+ };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * 종료 코드. 지적이 있는 것과 실행 자체가 실패한 것을 나눠, CI 가 설정 오류를
3
+ * 문서 문제로 오인하지 않게 한다.
4
+ */
5
+ export const EXIT = {
6
+ /** 지적 없음 */
7
+ OK: 0,
8
+ /** 지적이 있다 */
9
+ FINDINGS: 1,
10
+ /** 실행 실패. 설정 파일이 없거나 읽지 못했거나, 명령을 모른다 */
11
+ FAILURE: 2,
12
+ };
@@ -0,0 +1,25 @@
1
+ /**
2
+ * 규약 경로 - 도구가 직접 읽고 쓰는 파일의 위치.
3
+ *
4
+ * 설정으로 열어 두지 않는다. init·스킬·AGENTS.md 가 모두 이 위치를 전제한다.
5
+ */
6
+ export declare const SPECTHREAD_DIR = "specthread";
7
+ export declare const CONFIG_PATH = "specthread/config.jsonc";
8
+ export declare const LOCAL_CONFIG_PATH = "specthread/config.local.jsonc";
9
+ /** 규칙 문서 */
10
+ export declare const RULES_PATH = "specthread/rules.md";
11
+ /** 미확정 사항 정본 */
12
+ export declare const PENDING_PATH = "specthread/pending.md";
13
+ /** 프로젝트 맥락 문서 */
14
+ export declare const PROJECT_PATH = "specthread/project.md";
15
+ /** 문서 템플릿 폴더 */
16
+ export declare const TEMPLATES_DIR = "specthread/templates";
17
+ /** `path` 와 관계없이 항상 색인한다. 이 파일들을 읽는 검사가 스캔 범위에 좌우되지 않게 한다 */
18
+ export declare const CONVENTION_FILES: readonly ["specthread/rules.md", "specthread/pending.md", "specthread/project.md"];
19
+ /**
20
+ * 항상 검사·생성에서 뺀다. 색인에는 남는다.
21
+ *
22
+ * 템플릿과 설정 파일은 예시를 담는다. `skipCheck` 배열은 덮어쓰기라 사용자가 하나만 적어도
23
+ * 기본값이 사라지므로, 그 배열에 넣지 않고 코드가 항상 더한다.
24
+ */
25
+ export declare const DEFAULT_EXCLUDES: readonly ["specthread/templates", "specthread/config.jsonc", "specthread/config.local.jsonc"];
@@ -0,0 +1,25 @@
1
+ /**
2
+ * 규약 경로 - 도구가 직접 읽고 쓰는 파일의 위치.
3
+ *
4
+ * 설정으로 열어 두지 않는다. init·스킬·AGENTS.md 가 모두 이 위치를 전제한다.
5
+ */
6
+ export const SPECTHREAD_DIR = "specthread";
7
+ export const CONFIG_PATH = `${SPECTHREAD_DIR}/config.jsonc`;
8
+ export const LOCAL_CONFIG_PATH = `${SPECTHREAD_DIR}/config.local.jsonc`;
9
+ /** 규칙 문서 */
10
+ export const RULES_PATH = `${SPECTHREAD_DIR}/rules.md`;
11
+ /** 미확정 사항 정본 */
12
+ export const PENDING_PATH = `${SPECTHREAD_DIR}/pending.md`;
13
+ /** 프로젝트 맥락 문서 */
14
+ export const PROJECT_PATH = `${SPECTHREAD_DIR}/project.md`;
15
+ /** 문서 템플릿 폴더 */
16
+ export const TEMPLATES_DIR = `${SPECTHREAD_DIR}/templates`;
17
+ /** `path` 와 관계없이 항상 색인한다. 이 파일들을 읽는 검사가 스캔 범위에 좌우되지 않게 한다 */
18
+ export const CONVENTION_FILES = [RULES_PATH, PENDING_PATH, PROJECT_PATH];
19
+ /**
20
+ * 항상 검사·생성에서 뺀다. 색인에는 남는다.
21
+ *
22
+ * 템플릿과 설정 파일은 예시를 담는다. `skipCheck` 배열은 덮어쓰기라 사용자가 하나만 적어도
23
+ * 기본값이 사라지므로, 그 배열에 넣지 않고 코드가 항상 더한다.
24
+ */
25
+ export const DEFAULT_EXCLUDES = [TEMPLATES_DIR, CONFIG_PATH, LOCAL_CONFIG_PATH];
@@ -7,12 +7,21 @@
7
7
  *
8
8
  * 한 검사만 쓰는 정규식은 그 파일에 둔다. 여기 모으면 어디서 쓰는지 알 수 없어진다.
9
9
  */
10
+ /** 코드·문서 마커. 종류와 slug 를 캡처한다 */
11
+ export declare const MARKER: RegExp;
12
+ /** JSON 안 마커. 데이터에는 주석을 못 달아서 필드로 표기한다 */
13
+ export declare const PENDING_JSON: RegExp;
14
+ /** 관리 문서 항목 헤딩. id (`종류::slug`) 와 제목을 캡처한다 */
15
+ export declare const ITEM_HEADING: RegExp;
16
+ /** `li` 로 적힌 항목. 정본에서는 헤딩이어야 한다 */
17
+ export declare const ITEM_AS_LI: RegExp;
10
18
  /**
11
- * em dash. 리터럴로 적으면 치환 훅이 그 파일을 고쳐 검사를 무력화한다.
19
+ * 미확정 항목 세 모양. 종류와 slug 를 캡처한다.
12
20
  *
13
- * 훅 설정에 기대지 않고 손상을 막으려고 이스케이프로 둔다.
21
+ * 관리 문서 항목은 `###` 헤딩 (`` `[slug]` ``), 문서 미확정 사항 절은 생성된 백링크
22
+ * (`` [`slug`](...) ``), 둘 다 아닌 `li` (`` - `[slug]` ``) 는 낡은 형식이다.
14
23
  */
15
- export declare const EM_DASH = "\u2014";
24
+ export declare const PENDING_ITEM: RegExp;
16
25
  /**
17
26
  * 관리 문서 항목의 시점 표기 (`rules.md` §4-2).
18
27
  *
@@ -7,12 +7,24 @@
7
7
  *
8
8
  * 한 검사만 쓰는 정규식은 그 파일에 둔다. 여기 모으면 어디서 쓰는지 알 수 없어진다.
9
9
  */
10
+ /** 마커·항목 id 의 두 부분. 종류는 영소문자, slug 는 영소문자·숫자·하이픈 */
11
+ const KIND = '[a-z]+';
12
+ const SLUG = '[a-z0-9][a-z0-9-]*';
13
+ /** 코드·문서 마커. 종류와 slug 를 캡처한다 */
14
+ export const MARKER = new RegExp(`PENDING::(${KIND})::(${SLUG})`, 'g');
15
+ /** JSON 안 마커. 데이터에는 주석을 못 달아서 필드로 표기한다 */
16
+ export const PENDING_JSON = new RegExp(`"_pending"\\s*:\\s*"(${KIND})::(${SLUG})"`, 'g');
17
+ /** 관리 문서 항목 헤딩. id (`종류::slug`) 와 제목을 캡처한다 */
18
+ export const ITEM_HEADING = new RegExp(`^###\\s+\`\\[(${KIND}::${SLUG})\\]\`\\s*(.*)$`);
19
+ /** `li` 로 적힌 항목. 정본에서는 헤딩이어야 한다 */
20
+ export const ITEM_AS_LI = new RegExp(`^\\s*-\\s+\`\\[${KIND}::${SLUG}\\]\``);
10
21
  /**
11
- * em dash. 리터럴로 적으면 치환 훅이 그 파일을 고쳐 검사를 무력화한다.
22
+ * 미확정 항목 세 모양. 종류와 slug 를 캡처한다.
12
23
  *
13
- * 훅 설정에 기대지 않고 손상을 막으려고 이스케이프로 둔다.
24
+ * 관리 문서 항목은 `###` 헤딩 (`` `[slug]` ``), 문서 미확정 사항 절은 생성된 백링크
25
+ * (`` [`slug`](...) ``), 둘 다 아닌 `li` (`` - `[slug]` ``) 는 낡은 형식이다.
14
26
  */
15
- export const EM_DASH = '\u2014';
27
+ export const PENDING_ITEM = new RegExp(`^(?:\\s*-|###)\\s+[\`\\[]+(${KIND})::(${SLUG})[\`\\]]+`);
16
28
  /**
17
29
  * 관리 문서 항목의 시점 표기 (`rules.md` §4-2).
18
30
  *
@@ -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,7 +2,7 @@
2
2
  * 미확정 사항 절 생성 - 관리 문서 항목의 백링크를 문서 기준으로 뒤집는다.
3
3
  *
4
4
  * 각 관리 문서 항목의 `참조:` 줄이 어느 문서를 가리키는지 이미 안다. 그것을 대상
5
- * 문서 기준으로 재정렬하면 그 문서의 미확정 목록이 나온다 (`docs/system/rules.md` §4).
5
+ * 문서 기준으로 재정렬하면 그 문서의 미확정 목록이 나온다 (`specthread/rules.md` §4).
6
6
  * 목차·참조 절과 같은 방식이다 - 정본은 관리 문서이고 여기는 생성 뷰다.
7
7
  *
8
8
  * **이미 절을 가진 문서만 채운다.** 참조는 _이 항목이 이 문서와 관련 있다_ 는
@@ -12,18 +12,18 @@
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
  *
@@ -13,10 +13,15 @@
13
13
  * 불러 지금 내용과 비교한다. 검사기가 생성기를 부르는 것이 거꾸로 보이지만,
14
14
  * _무엇이 옳은 내용인가_ 를 한곳에서만 정의하려면 이 방향이 맞다.
15
15
  */
16
- import { basename, dirname, join, normalize } from "node:path";
16
+ import { basename, dirname, extname, join, normalize } from "node:path";
17
+ import { TAIL } from "../constants/docs.js";
18
+ import { docExtSet } from "../utils/scan.js";
17
19
  import { wantsRefSection } from "../utils/scope.js";
18
- /** 코드·데이터 대상인지. 나머지 (`.md` · 디렉터리) 는 문서 쪽으로 간다 */
19
- const isCode = (path) => /\.(ts|tsx|json)$/.test(path);
20
+ /** 코드·데이터 대상인지. doc 확장자가 아니고 디렉터리도 아니면 코드로 본다 */
21
+ const isCode = (path, docExts) => {
22
+ const ext = extname(path).toLowerCase();
23
+ return ext !== "" && !docExts.has(ext);
24
+ };
20
25
  /**
21
26
  * 링크 대상의 리포 루트 기준 위치. 같은 파일 이름이 겹칠 때 라벨로 쓴다.
22
27
  *
@@ -96,8 +101,9 @@ export const referenceBlock = (file, config) => {
96
101
  return [];
97
102
  const label = labels(file.path, targets);
98
103
  const render = (list) => list.map((t) => line(t, label.get(t.path) ?? t.path));
99
- const docs = targets.filter((t) => !isCode(t.path));
100
- const code = targets.filter((t) => isCode(t.path));
104
+ const exts = docExtSet(config.fileKinds);
105
+ const docs = targets.filter((t) => !isCode(t.path, exts));
106
+ const code = targets.filter((t) => isCode(t.path, exts));
101
107
  const out = [""];
102
108
  // 비는 갈래는 제목도 내지 않는다. 빈 제목만 남으면 아직 안 채운 것처럼 읽힌다
103
109
  if (docs.length > 0)
@@ -109,21 +115,21 @@ export const referenceBlock = (file, config) => {
109
115
  /**
110
116
  * 참조 절을 새로 넣은 줄 목록.
111
117
  *
112
- * 꼬리 절 순서가 참조 → 미확정 사항 → 변경 이력 이므로 (`docs/system/rules.md`
113
- * 규칙 8) 뒤 두 개 중 먼저 오는 것 앞에 놓는다. 꼬리 절이 하나도 없으면 파일 끝에
118
+ * 꼬리 절 순서가 참조 → 미확정 사항 → 변경 이력 이므로 (`specthread/rules.md`
119
+ * §2-5) 뒤 두 개 중 먼저 오는 것 앞에 놓는다. 꼬리 절이 하나도 없으면 파일 끝에
114
120
  * 붙이고, 이때만 앞에 빈 줄을 하나 둔다 - 다른 자리는 앞 절이 이미 빈 줄로 끝난다.
115
121
  */
116
122
  const insert = (file, lines, block) => {
117
123
  const nextTail = file.headings.find((h) => h.level === 2 && h.tail);
118
124
  if (nextTail !== undefined) {
119
125
  const at = nextTail.line - 1;
120
- return [...lines.slice(0, at), "## 참조", ...block, ...lines.slice(at)];
126
+ return [...lines.slice(0, at), `## ${TAIL.REFS}`, ...block, ...lines.slice(at)];
121
127
  }
122
128
  // 파일 끝 빈 줄은 버린다. 블록이 빈 줄로 끝나므로 줄바꿈은 그쪽이 갖는다
123
129
  let end = lines.length;
124
130
  while (end > 0 && lines[end - 1].trim() === "")
125
131
  end--;
126
- return [...lines.slice(0, end), "", "## 참조", ...block];
132
+ return [...lines.slice(0, end), "", `## ${TAIL.REFS}`, ...block];
127
133
  };
128
134
  /**
129
135
  * 참조 절을 채우거나 새로 넣은 문서 줄 목록. 바꿀 것이 없으면 null.
@@ -136,6 +142,9 @@ export const applyReferences = (file, lines, index) => {
136
142
  if (file.refSection === null)
137
143
  return insert(file, lines, block);
138
144
  const { start, end } = file.refSection;
145
+ // 억제된 블록은 손으로 관리하는 것이다
146
+ if (file.ignored.has(start))
147
+ return null;
139
148
  const current = lines.slice(start - 1, end);
140
149
  // 이미 맞으면 건드리지 않는다. 생성기를 두 번 돌려도 결과가 같아야 한다
141
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,12 +12,12 @@
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 { isWorkDoc } from '../utils/scope.js';
17
19
  /** 관리 문서인지. 표는 그 한 파일에만 붙는다 */
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*(.*)$/;
20
+ export const isPendingDoc = (file) => file.path === PENDING_PATH;
21
21
  /** 항목 첫 본문 줄의 시점 표기 */
22
22
  const TIMEPOINT_LINE = new RegExp(`^${TIMEPOINT.source}$`);
23
23
  const sections = (lines) => {
@@ -49,7 +49,7 @@ const sections = (lines) => {
49
49
  const markerSites = (index) => {
50
50
  const out = new Map();
51
51
  for (const file of index.files.values()) {
52
- if (file.path.startsWith(index.config.work))
52
+ if (isWorkDoc(file.path, index.config))
53
53
  continue;
54
54
  for (const marker of file.markers) {
55
55
  if (marker.slug === '')
@@ -107,7 +107,7 @@ export const summaryBlocks = (lines, index) => {
107
107
  * 절이 여럿이라 **아래 절부터** 갈아끼운다. 위를 먼저 고치면 아래 절의 줄 번호가 밀린다.
108
108
  */
109
109
  export const applySummary = (file, lines, index) => {
110
- if (!isPendingDoc(file, index))
110
+ if (!isPendingDoc(file))
111
111
  return null;
112
112
  const blocks = summaryBlocks(lines, index);
113
113
  if (blocks.length === 0)
@@ -115,6 +115,9 @@ export const applySummary = (file, lines, index) => {
115
115
  let next = lines;
116
116
  let changed = false;
117
117
  for (const { blockStart, blockEnd, block } of [...blocks].reverse()) {
118
+ // 억제된 표는 손으로 관리하는 것이다
119
+ if (file.ignored.has(blockStart))
120
+ continue;
118
121
  const current = next.slice(blockStart - 1, blockEnd);
119
122
  if (current.join('\n') === block.join('\n'))
120
123
  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")) {
@@ -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
@@ -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` 으로 자리를 가리킨다 */
@@ -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
  /** 인라인 억제에 해당하는 지적인지 */