specthread 0.1.4 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -13
- package/dist/bin/check.js +9 -34
- package/dist/bin/cli.js +4 -4
- package/dist/bin/generate.js +32 -19
- package/dist/bin/open-project.d.ts +5 -0
- package/dist/bin/open-project.js +26 -0
- package/dist/checks/changelog.js +5 -4
- package/dist/checks/headings.d.ts +0 -1
- package/dist/checks/headings.js +13 -4
- package/dist/checks/links.js +10 -6
- package/dist/checks/markers.d.ts +3 -1
- package/dist/checks/markers.js +33 -18
- package/dist/checks/pending.js +54 -22
- package/dist/checks/references.js +2 -2
- package/dist/checks/sections.js +3 -5
- package/dist/checks/style.d.ts +0 -8
- package/dist/checks/style.js +23 -43
- package/dist/checks/timestamps.js +5 -5
- package/dist/checks/toc.js +4 -6
- package/dist/commands/config-template.d.ts +8 -0
- package/{scaffold/config.jsonc → dist/commands/config-template.js} +48 -40
- package/dist/commands/init.js +92 -42
- package/dist/config-loader.d.ts +22 -1
- package/dist/config-loader.js +192 -25
- package/dist/config.schema.d.ts +16 -35
- package/dist/config.schema.js +1 -7
- package/dist/constants/docs.d.ts +7 -2
- package/dist/constants/docs.js +7 -3
- package/dist/constants/exit.d.ts +12 -0
- package/dist/constants/exit.js +12 -0
- package/dist/constants/paths.d.ts +25 -0
- package/dist/constants/paths.js +25 -0
- package/dist/constants/patterns.d.ts +12 -3
- package/dist/constants/patterns.js +15 -3
- package/dist/constants/rules.d.ts +7 -3
- package/dist/constants/rules.js +7 -3
- package/dist/gen/pending-section.js +18 -14
- package/dist/gen/references.js +19 -10
- package/dist/gen/summary.d.ts +1 -1
- package/dist/gen/summary.js +9 -6
- package/dist/gen/toc.js +4 -1
- package/dist/run-check.d.ts +5 -0
- package/dist/run-check.js +35 -0
- package/dist/types.d.ts +4 -2
- package/dist/utils/ignore.d.ts +2 -8
- package/dist/utils/ignore.js +23 -6
- package/dist/utils/parse.js +11 -19
- package/dist/utils/path-match.d.ts +19 -0
- package/dist/utils/path-match.js +27 -0
- package/dist/utils/report.d.ts +1 -7
- package/dist/utils/report.js +10 -3
- package/dist/utils/resolve.js +15 -1
- package/dist/utils/root.d.ts +2 -0
- package/dist/utils/root.js +19 -0
- package/dist/utils/scan.d.ts +7 -5
- package/dist/utils/scan.js +25 -25
- package/dist/utils/scope.d.ts +37 -11
- package/dist/utils/scope.js +60 -24
- package/package.json +2 -2
- package/scaffold/AGENTS.md +4 -6
- package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
- package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +4 -2
- package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
- package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
- package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
- package/scaffold/pending.md +1 -1
- package/scaffold/project.md +1 -1
- package/scaffold/rules.md +28 -27
- package/scaffold/templates/plan.md +3 -7
package/dist/constants/docs.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다. `TAIL_NAMES` 가
|
|
5
5
|
* `utils/parse.ts` 와 `checks/headings.ts` 에 각각 있어 실제로 그 상태였다.
|
|
6
6
|
*
|
|
7
|
-
* 규칙 본문은 `
|
|
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
|
-
|
|
16
|
-
|
|
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,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
|
-
*
|
|
19
|
+
* 미확정 항목 세 모양. 종류와 slug 를 캡처한다.
|
|
12
20
|
*
|
|
13
|
-
*
|
|
21
|
+
* 관리 문서 항목은 `###` 헤딩 (`` `[slug]` ``), 문서 미확정 사항 절은 생성된 백링크
|
|
22
|
+
* (`` [`slug`](...) ``), 둘 다 아닌 `li` (`` - `[slug]` ``) 는 낡은 형식이다.
|
|
14
23
|
*/
|
|
15
|
-
export declare const
|
|
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
|
-
*
|
|
22
|
+
* 미확정 항목 세 모양. 종류와 slug 를 캡처한다.
|
|
12
23
|
*
|
|
13
|
-
*
|
|
24
|
+
* 관리 문서 항목은 `###` 헤딩 (`` `[slug]` ``), 문서 미확정 사항 절은 생성된 백링크
|
|
25
|
+
* (`` [`slug`](...) ``), 둘 다 아닌 `li` (`` - `[slug]` ``) 는 낡은 형식이다.
|
|
14
26
|
*/
|
|
15
|
-
export const
|
|
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
|
-
* 규칙 본문은 `
|
|
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
|
};
|
package/dist/constants/rules.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* 어느 파일을 열어야 하는지 나온다. 한 파일이 한 군을 갖고, 한 군은 여러 검사를 갖는다 -
|
|
10
10
|
* 같은 파싱을 반복하지 않기 위해서다.
|
|
11
11
|
*
|
|
12
|
-
* 규칙 본문은 `
|
|
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
|
-
* 문서 기준으로 재정렬하면 그 문서의 미확정 목록이 나온다 (`
|
|
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
|
-
|
|
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
|
-
|
|
23
|
-
|
|
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
|
|
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),
|
|
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 ['', `해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([\`
|
|
78
|
+
return ['', `해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([\`${name}\`](${link})).`, ''];
|
|
78
79
|
}
|
|
79
80
|
return [
|
|
80
81
|
'',
|
|
81
|
-
`> **정본은 [\`
|
|
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 ===
|
|
90
|
+
if (file.path === PENDING_PATH)
|
|
90
91
|
return null;
|
|
91
|
-
const pending = index.files.get(
|
|
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;
|
package/dist/gen/references.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* 참조 절 생성 - 본문 링크를 대상별로 모아 문서 하단 `## 참조` 절을 채운다.
|
|
3
3
|
*
|
|
4
4
|
* 참조 절은 **이 문서를 이해하려면 읽어야 하는 대상 목록** 이고, 대상의 어느 절을
|
|
5
|
-
* 읽어야 하는지는 본문 인라인 링크가 갖는다 (`
|
|
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
|
-
/** 코드·데이터 대상인지.
|
|
19
|
-
const isCode = (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
|
|
100
|
-
const
|
|
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
|
-
* 꼬리 절 순서가 참조 → 미확정 사항 → 변경 이력 이므로 (`
|
|
113
|
-
*
|
|
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),
|
|
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), "",
|
|
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"))
|
package/dist/gen/summary.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { DocIndex, IndexedFile } from '../types.ts';
|
|
2
2
|
/** 관리 문서인지. 표는 그 한 파일에만 붙는다 */
|
|
3
|
-
export declare const isPendingDoc: (file: IndexedFile
|
|
3
|
+
export declare const isPendingDoc: (file: IndexedFile) => boolean;
|
|
4
4
|
/** 표 한 행이 되는 항목 하나 */
|
|
5
5
|
export interface SummaryRow {
|
|
6
6
|
slug: string;
|
package/dist/gen/summary.js
CHANGED
|
@@ -12,12 +12,12 @@
|
|
|
12
12
|
* **소비자가 둘이다.** `bin/generate.ts` 가 파일에 쓰고, `checks/pending.ts` 가 같은
|
|
13
13
|
* 함수를 불러 지금 내용과 비교한다.
|
|
14
14
|
*/
|
|
15
|
-
import {
|
|
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
|
|
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
|
|
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
|
|
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
|
-
* (`
|
|
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,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
|
-
* 다른 문서의 절은 앵커 링크로 가리켜야 한다 (`
|
|
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` 으로 자리를 가리킨다 */
|
package/dist/utils/ignore.d.ts
CHANGED
|
@@ -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;
|
package/dist/utils/ignore.js
CHANGED
|
@@ -1,14 +1,31 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
/** 인라인 억제에 해당하는 지적인지 */
|