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
@@ -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
  *
@@ -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 확장자가 아니고 디렉터리도 아니면 코드로 본다 */
@@ -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,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
  /** 인라인 억제에 해당하는 지적인지 */
@@ -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
- * 꼬리 절은 문서 맨 끝에 순서대로 오므로 (`docs/system/rules.md` 규칙 8) 첫 꼬리
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, "변경 이력", lines.length);
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: findTocBlock(lines),
268
- refSection: tailRange(headings, "참조", lines.length),
269
- pendingSection: tailRange(headings, "미확정 사항", lines.length),
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
  };