@venizia/vulcan-okf 0.4.10-13 → 0.4.10-15
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/package.json +1 -1
- package/src/check/code-mask.ts +121 -0
- package/src/check/command.ts +19 -3
- package/src/check/docs-code.ts +369 -0
- package/src/check/house.ts +4 -0
- package/src/project/common/types.ts +2 -0
- package/src/project/reader.ts +5 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan-okf",
|
|
3
|
-
"version": "0.4.10-
|
|
3
|
+
"version": "0.4.10-15",
|
|
4
4
|
"description": "VULCAN knowledge tooling: OKF v0.2 conformance check (plus --strict house rules), gen, and coverage for a project's .agents/knowledge bundle. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/okf",
|
|
6
6
|
"bugs": {
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The syntax of a code example with its strings, template literals and comments taken out: each string
|
|
3
|
+
* becomes `''`, a template literal `` `` `` (the code of its `${}` stays), a comment disappears, and every
|
|
4
|
+
* newline stays, so a line of the result is the same line of the example. A scanner and not a parser: an
|
|
5
|
+
* example is often a fragment, which a parser may refuse and a scanner reads all the same.
|
|
6
|
+
*/
|
|
7
|
+
export class CodeMask {
|
|
8
|
+
static of(opts: { text: string }): string {
|
|
9
|
+
const { text } = opts;
|
|
10
|
+
let out = '';
|
|
11
|
+
let index = 0;
|
|
12
|
+
// One entry per open template literal: how many `{` of its `${}` expression are still open.
|
|
13
|
+
const templates: number[] = [];
|
|
14
|
+
|
|
15
|
+
const skipQuoted = (quote: string): void => {
|
|
16
|
+
index += 1;
|
|
17
|
+
|
|
18
|
+
while (index < text.length && text[index] !== quote && text[index] !== '\n') {
|
|
19
|
+
index += text[index] === '\\' ? 2 : 1;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
index += text[index] === quote ? 1 : 0;
|
|
23
|
+
out += `${quote}${quote}`;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/** Reads template text until the closing backtick (done) or a `${` (an expression opens). */
|
|
27
|
+
const readTemplate = (): void => {
|
|
28
|
+
while (index < text.length) {
|
|
29
|
+
const character = text[index];
|
|
30
|
+
|
|
31
|
+
if (character === '\\') {
|
|
32
|
+
out += text[index + 1] === '\n' ? '\n' : '';
|
|
33
|
+
index += 2;
|
|
34
|
+
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
if (character === '`') {
|
|
39
|
+
index += 1;
|
|
40
|
+
templates.pop();
|
|
41
|
+
out += '``';
|
|
42
|
+
|
|
43
|
+
return;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
if (character === '$' && text[index + 1] === '{') {
|
|
47
|
+
index += 2;
|
|
48
|
+
templates[templates.length - 1] = 1;
|
|
49
|
+
out += '(';
|
|
50
|
+
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
out += character === '\n' ? '\n' : '';
|
|
55
|
+
index += 1;
|
|
56
|
+
}
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
while (index < text.length) {
|
|
60
|
+
const character = text[index];
|
|
61
|
+
const next = text[index + 1];
|
|
62
|
+
|
|
63
|
+
if (character === '/' && next === '/') {
|
|
64
|
+
while (index < text.length && text[index] !== '\n') {
|
|
65
|
+
index += 1;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
continue;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
if (character === '/' && next === '*') {
|
|
72
|
+
const end = text.indexOf('*/', index + 2);
|
|
73
|
+
const comment = text.slice(index, end === -1 ? text.length : end + 2);
|
|
74
|
+
|
|
75
|
+
out += comment.replace(/[^\n]/g, '');
|
|
76
|
+
index += comment.length;
|
|
77
|
+
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
if (character === "'" || character === '"') {
|
|
82
|
+
skipQuoted(character);
|
|
83
|
+
|
|
84
|
+
continue;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
if (character === '`') {
|
|
88
|
+
index += 1;
|
|
89
|
+
templates.push(0);
|
|
90
|
+
readTemplate();
|
|
91
|
+
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const open = templates[templates.length - 1];
|
|
96
|
+
|
|
97
|
+
if (open !== undefined && open > 0) {
|
|
98
|
+
if (character === '{') {
|
|
99
|
+
templates[templates.length - 1] = open + 1;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
if (character === '}') {
|
|
103
|
+
templates[templates.length - 1] = open - 1;
|
|
104
|
+
|
|
105
|
+
if (open - 1 === 0) {
|
|
106
|
+
index += 1;
|
|
107
|
+
out += ')';
|
|
108
|
+
readTemplate();
|
|
109
|
+
|
|
110
|
+
continue;
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
out += character;
|
|
116
|
+
index += 1;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
return out;
|
|
120
|
+
}
|
|
121
|
+
}
|
package/src/check/command.ts
CHANGED
|
@@ -5,6 +5,7 @@ import { OkfProject } from '../project/index.ts';
|
|
|
5
5
|
import { IssueSeverities, OkfVersions, BundleConformance } from '../spec/index.ts';
|
|
6
6
|
import type { IBundleFile, IConformanceIssue } from '../spec/index.ts';
|
|
7
7
|
import { GenerationRegistry } from '../generate/index.ts';
|
|
8
|
+
import { DocsCodeCheck } from './docs-code.ts';
|
|
8
9
|
import { HouseCheck } from './house.ts';
|
|
9
10
|
import { SourceScanner } from '../source/index.ts';
|
|
10
11
|
|
|
@@ -35,10 +36,15 @@ export const check = async (opts: { strict: boolean }): Promise<void> => {
|
|
|
35
36
|
problems.push(...HouseCheck.collectProblems({ files, ...generation }));
|
|
36
37
|
}
|
|
37
38
|
|
|
38
|
-
|
|
39
|
+
const notes = warnings.map((issue) => formatIssue({ issue }));
|
|
40
|
+
|
|
41
|
+
if (opts.strict) {
|
|
42
|
+
notes.push(...DocsCodeCheck.collectWarnings());
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (notes.length) {
|
|
39
46
|
console.error(
|
|
40
|
-
`check: ${
|
|
41
|
-
warnings.map((issue) => ' - ' + formatIssue({ issue })).join('\n'),
|
|
47
|
+
`check: ${notes.length} warning(s):\n` + notes.map((note) => ' - ' + note).join('\n'),
|
|
42
48
|
);
|
|
43
49
|
}
|
|
44
50
|
|
|
@@ -57,5 +63,15 @@ export const check = async (opts: { strict: boolean }): Promise<void> => {
|
|
|
57
63
|
? `OKF v${OkfVersions.LATEST} + house rules`
|
|
58
64
|
: `OKF v${OkfVersions.LATEST}`;
|
|
59
65
|
|
|
66
|
+
const off = opts.strict ? DocsCodeCheck.offRegions() : [];
|
|
67
|
+
|
|
68
|
+
if (off.length > 0) {
|
|
69
|
+
const total = off.reduce((sum, page) => sum + page.lines.length, 0);
|
|
70
|
+
|
|
71
|
+
console.log(
|
|
72
|
+
`check: docs-code off - ${total} region(s) in ${off.length} page(s): ${off.map((page) => `${page.file} (${page.lines.length})`).join(', ')}`,
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
60
76
|
console.log(`check: OK - ${scope} - ${files.length} files, ${conceptCount} concepts`);
|
|
61
77
|
};
|
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { OkfProject } from '../project/index.ts';
|
|
3
|
+
import { CodeMask } from './code-mask.ts';
|
|
4
|
+
import { SourceScanner } from '../source/index.ts';
|
|
5
|
+
|
|
6
|
+
const CODE_LANGUAGES = new Set([
|
|
7
|
+
'ts',
|
|
8
|
+
'tsx',
|
|
9
|
+
'typescript',
|
|
10
|
+
'js',
|
|
11
|
+
'jsx',
|
|
12
|
+
'javascript',
|
|
13
|
+
'mts',
|
|
14
|
+
'cts',
|
|
15
|
+
'mjs',
|
|
16
|
+
]);
|
|
17
|
+
const FENCE = /^\s*(`{3,}|~{3,})(\S*)\s*$/;
|
|
18
|
+
const FENCE_OPEN = /^\s*(`{3,}|~{3,})(\S*)/;
|
|
19
|
+
/** The note a generator writes on a page it owns, such as `atlas api gen`: its content is the project's own source, not an example. */
|
|
20
|
+
const GENERATED_NOTE = /^>\s*Generated\b.*\bdo not edit\.?\s*$/m;
|
|
21
|
+
/** What okf generated, and what a page marks `docs-code: off` (a signature quoted from the source) until `docs-code: on`. */
|
|
22
|
+
const REGION_START = /<!--\s*(?:okf:generated:\S+\s+start|docs-code:\s*off)\s*-->/;
|
|
23
|
+
const REGION_END = /<!--\s*(?:okf:generated:\S+\s+end|docs-code:\s*on)\s*-->/;
|
|
24
|
+
/** A list of names that can rename: `import {`, `import type {`, `import A, {`, `export {`, `export type {`. `export class A {` is code, not a list. */
|
|
25
|
+
const NAME_LIST = /^\s*(?:import|export)\s+(?:type\s+)?(?:[\w$]+\s*,\s*)?\{/;
|
|
26
|
+
/** An import, or `export * as ns from`: it names modules and renames, it holds no cast. */
|
|
27
|
+
const MODULE_STATEMENT = /^\s*(?:import\b|export\s+(?:type\s+)?\*)/;
|
|
28
|
+
/** `AnyType` named in an import or export list, with or without `type`. */
|
|
29
|
+
const ANY_TYPE_NAME = /\bAnyType\b/;
|
|
30
|
+
|
|
31
|
+
/** `value as User`, `as unknown as`, `as any`, `as never`: every `as` that is not `as const`. */
|
|
32
|
+
const CAST = /\bas\s+(?!const\b)(?:unknown|any|never|[A-Za-z_$][\w$.]*|[{([])/;
|
|
33
|
+
/** `: any`, `<any>`, `, any>`, `| any`, `= any>`, `extends any`, `any[]`, and the same for `AnyType`, the Venizia alias of `any`. */
|
|
34
|
+
const ANY_TYPE =
|
|
35
|
+
/(?::\s*|<\s*|,\s*|\|\s*|&\s*|=\s*|\b(?:keyof|extends|satisfies|is|asserts)\s+)(?:any|AnyType)\b(?!\s*:)|\b(?:any|AnyType)\[\]/;
|
|
36
|
+
const CONDITIONAL_SPREAD = /\.\.\.\(.*(?:\?.*:\s*(?:\{\}|\[\])|&&\s*[{[])/;
|
|
37
|
+
/** `type Mode = 'on' | 'off'`: strings are masked to `''` before this runs. */
|
|
38
|
+
const LITERAL_UNION = /\btype\s+\w+(?:<[^>]*>)?\s*=\s*(?:\|\s*)?''\s*\|/;
|
|
39
|
+
|
|
40
|
+
const TABLE_CELL_MAX = 120;
|
|
41
|
+
const OFF_MARKER = /<!--\s*docs-code:\s*off\s*-->/;
|
|
42
|
+
const ON_MARKER = /<!--\s*docs-code:\s*on\s*-->/;
|
|
43
|
+
/** What a quoted signature never holds: a statement, a call assigned or awaited, a function or arrow body. */
|
|
44
|
+
const OFF_STATEMENT =
|
|
45
|
+
/^\s*(?:const|let|var|return|await|if|for|while|throw)\b|=\s*(?:await\s+|new\s+)?[\w$.]+\(/;
|
|
46
|
+
const OFF_BODY = /=>\s*\{|\)\s*(?::\s*[\w$.<>[\] |]+)?\s*\{/;
|
|
47
|
+
|
|
48
|
+
interface IFence {
|
|
49
|
+
character: string;
|
|
50
|
+
length: number;
|
|
51
|
+
language: string;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const cellsOf = (opts: { line: string }): string[] =>
|
|
55
|
+
opts.line
|
|
56
|
+
.trim()
|
|
57
|
+
.replace(/^\|/, '')
|
|
58
|
+
.replace(/\|$/, '')
|
|
59
|
+
.split(/(?<!\\)\|/)
|
|
60
|
+
.map((cell) => cell.trim());
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The code rules for what the wiki shows (V-C-10 and the style of the code this repository writes): a code
|
|
64
|
+
* example is a model for whoever copies it, so a fenced ts, tsx or js block holds no explicit cast, no `any`,
|
|
65
|
+
* no conditional spread and no string-literal union. A table is read for its shape: a cell over 120
|
|
66
|
+
* characters, or a continuation row with an empty first cell, is a warning, never a failure.
|
|
67
|
+
* The changelogs are not read: an entry shows an old API next to the new one.
|
|
68
|
+
*/
|
|
69
|
+
export class DocsCodeCheck {
|
|
70
|
+
/** `docs-code: <file>:<line>: <what>` for every code example that breaks a rule. */
|
|
71
|
+
static collectProblems(): string[] {
|
|
72
|
+
return DocsCodeCheck.pagesOf().flatMap((page) => DocsCodeCheck.codeProblemsOf({ page }));
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** `docs-table: <file>:<line>: <what>` for every crowded table row, and `docs-code: <file>:<line>: <what>` for an off region that holds more than a signature. */
|
|
76
|
+
static collectWarnings(): string[] {
|
|
77
|
+
return DocsCodeCheck.pagesOf().flatMap((page) => [
|
|
78
|
+
...DocsCodeCheck.tableWarningsOf({ page }),
|
|
79
|
+
...DocsCodeCheck.offWarningsOf({ page }),
|
|
80
|
+
]);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** Every page that holds a `docs-code: off` region, with the line of each: a reviewer sees every use. */
|
|
84
|
+
static offRegions(): { file: string; lines: number[] }[] {
|
|
85
|
+
return DocsCodeCheck.pagesOf().flatMap((page) => {
|
|
86
|
+
const lines = DocsCodeCheck.offRegionsIn({ lines: page.rawLines }).map(
|
|
87
|
+
(region) => region.start,
|
|
88
|
+
);
|
|
89
|
+
|
|
90
|
+
return lines.length === 0 ? [] : [{ file: page.file, lines }];
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
private static pagesOf(): { file: string; lines: string[]; rawLines: string[] }[] {
|
|
95
|
+
const { wiki, changelogs } = OkfProject.read();
|
|
96
|
+
|
|
97
|
+
if (wiki === undefined) {
|
|
98
|
+
return [];
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
return SourceScanner.walkFiles({ dir: wiki })
|
|
102
|
+
.filter((file) => file.endsWith('.md'))
|
|
103
|
+
.filter((file) => changelogs === undefined || !file.startsWith(`${changelogs}/`))
|
|
104
|
+
.map((file) => ({ file, text: readFileSync(file, 'utf8') }))
|
|
105
|
+
.filter(({ text }) => !GENERATED_NOTE.test(text))
|
|
106
|
+
.map(({ file, text }) => ({
|
|
107
|
+
file: SourceScanner.repoRelative({ path: file }),
|
|
108
|
+
lines: DocsCodeCheck.withoutGeneratedRegions({ lines: text.split('\n') }),
|
|
109
|
+
rawLines: text.split('\n'),
|
|
110
|
+
}));
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** Each `docs-code: off` region: the line of its marker and the code lines inside it with their numbers. */
|
|
114
|
+
private static offRegionsIn(opts: {
|
|
115
|
+
lines: string[];
|
|
116
|
+
}): { start: number; body: { text: string; number: number }[] }[] {
|
|
117
|
+
const regions: { start: number; body: { text: string; number: number }[] }[] = [];
|
|
118
|
+
let open: { start: number; body: { text: string; number: number }[] } | undefined;
|
|
119
|
+
|
|
120
|
+
opts.lines.forEach((text, index) => {
|
|
121
|
+
if (OFF_MARKER.test(text)) {
|
|
122
|
+
open = { start: index + 1, body: [] };
|
|
123
|
+
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
if (ON_MARKER.test(text) && open !== undefined) {
|
|
128
|
+
regions.push(open);
|
|
129
|
+
open = undefined;
|
|
130
|
+
|
|
131
|
+
return;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
if (open !== undefined && !FENCE_OPEN.test(text)) {
|
|
135
|
+
open.body.push({ text, number: index + 1 });
|
|
136
|
+
}
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
return regions;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
private static offWarningsOf(opts: { page: { file: string; rawLines: string[] } }): string[] {
|
|
143
|
+
return DocsCodeCheck.offRegionsIn({ lines: opts.page.rawLines }).flatMap((region) => {
|
|
144
|
+
const masked = CodeMask.of({ text: region.body.map((line) => line.text).join('\n') }).split(
|
|
145
|
+
'\n',
|
|
146
|
+
);
|
|
147
|
+
const found: string[] = [];
|
|
148
|
+
|
|
149
|
+
masked.forEach((line, at) => {
|
|
150
|
+
const what = OFF_BODY.test(line)
|
|
151
|
+
? 'a function body'
|
|
152
|
+
: OFF_STATEMENT.test(line)
|
|
153
|
+
? 'a statement'
|
|
154
|
+
: undefined;
|
|
155
|
+
|
|
156
|
+
if (what !== undefined) {
|
|
157
|
+
found.push(
|
|
158
|
+
`docs-code: ${opts.page.file}:${region.body[at].number}: a docs-code off region holds ${what} - off is for a quoted source signature, never an example`,
|
|
159
|
+
);
|
|
160
|
+
}
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
return found;
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** The lines with what sits between okf generated markers, or `docs-code: off` and `on`, blanked, so line numbers hold. */
|
|
168
|
+
private static withoutGeneratedRegions(opts: { lines: string[] }): string[] {
|
|
169
|
+
let inRegion = false;
|
|
170
|
+
|
|
171
|
+
return opts.lines.map((line) => {
|
|
172
|
+
if (REGION_START.test(line)) {
|
|
173
|
+
inRegion = true;
|
|
174
|
+
|
|
175
|
+
return '';
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
if (REGION_END.test(line)) {
|
|
179
|
+
inRegion = false;
|
|
180
|
+
|
|
181
|
+
return '';
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
return inRegion ? '' : line;
|
|
185
|
+
});
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** Each line with the fence it is in, `undefined` outside any; the fence lines themselves are left out. */
|
|
189
|
+
private static linesWithFence(opts: {
|
|
190
|
+
lines: string[];
|
|
191
|
+
}): { text: string; number: number; fence?: IFence }[] {
|
|
192
|
+
const found: { text: string; number: number; fence?: IFence }[] = [];
|
|
193
|
+
let fence: IFence | undefined;
|
|
194
|
+
|
|
195
|
+
opts.lines.forEach((text, index) => {
|
|
196
|
+
if (fence === undefined) {
|
|
197
|
+
const open = FENCE_OPEN.exec(text);
|
|
198
|
+
|
|
199
|
+
if (open !== null) {
|
|
200
|
+
fence = {
|
|
201
|
+
character: open[1][0],
|
|
202
|
+
length: open[1].length,
|
|
203
|
+
language: open[2].toLowerCase(),
|
|
204
|
+
};
|
|
205
|
+
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
found.push({ text, number: index + 1 });
|
|
210
|
+
|
|
211
|
+
return;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
const close = FENCE.exec(text);
|
|
215
|
+
|
|
216
|
+
if (
|
|
217
|
+
close !== null &&
|
|
218
|
+
close[2] === '' &&
|
|
219
|
+
close[1][0] === fence.character &&
|
|
220
|
+
close[1].length >= fence.length
|
|
221
|
+
) {
|
|
222
|
+
fence = undefined;
|
|
223
|
+
|
|
224
|
+
return;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
found.push({ text, number: index + 1, fence });
|
|
228
|
+
});
|
|
229
|
+
|
|
230
|
+
return found;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** Every line masked (strings, template literals and comments out); a fence is read whole, so a comment or a template can span lines. */
|
|
234
|
+
private static maskedFences(opts: { lines: { text: string; fence?: IFence }[] }): string[] {
|
|
235
|
+
const masked = opts.lines.map((line) => line.text);
|
|
236
|
+
let start = 0;
|
|
237
|
+
|
|
238
|
+
while (start < opts.lines.length) {
|
|
239
|
+
const { fence } = opts.lines[start];
|
|
240
|
+
let end = start + 1;
|
|
241
|
+
|
|
242
|
+
while (end < opts.lines.length && opts.lines[end].fence === fence) {
|
|
243
|
+
end += 1;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
if (fence !== undefined) {
|
|
247
|
+
const text = opts.lines
|
|
248
|
+
.slice(start, end)
|
|
249
|
+
.map((line) => line.text)
|
|
250
|
+
.join('\n');
|
|
251
|
+
|
|
252
|
+
CodeMask.of({ text })
|
|
253
|
+
.split('\n')
|
|
254
|
+
.forEach((line, offset) => {
|
|
255
|
+
masked[start + offset] = line;
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
start = end;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
return masked;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
private static codeProblemsOf(opts: { page: { file: string; lines: string[] } }): string[] {
|
|
266
|
+
const problems: string[] = [];
|
|
267
|
+
let inImportBraces = false;
|
|
268
|
+
|
|
269
|
+
const lines = DocsCodeCheck.linesWithFence({ lines: opts.page.lines });
|
|
270
|
+
const masked = DocsCodeCheck.maskedFences({ lines });
|
|
271
|
+
|
|
272
|
+
for (const [at, { number, fence }] of lines.entries()) {
|
|
273
|
+
if (fence === undefined || !CODE_LANGUAGES.has(fence.language)) {
|
|
274
|
+
continue;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
const syntax = masked[at];
|
|
278
|
+
const isListStart = NAME_LIST.test(syntax);
|
|
279
|
+
const isModuleLine = MODULE_STATEMENT.test(syntax);
|
|
280
|
+
const where = `docs-code: ${opts.page.file}:${number}: `;
|
|
281
|
+
|
|
282
|
+
if (isListStart || isModuleLine || inImportBraces) {
|
|
283
|
+
// `import { A as B }` and `export { A as B }` rename, they do not cast; a list can span lines.
|
|
284
|
+
inImportBraces =
|
|
285
|
+
isListStart || isModuleLine
|
|
286
|
+
? syntax.includes('{') && !syntax.includes('}')
|
|
287
|
+
: !syntax.includes('}');
|
|
288
|
+
|
|
289
|
+
if (ANY_TYPE_NAME.test(syntax)) {
|
|
290
|
+
problems.push(
|
|
291
|
+
`${where}\`AnyType\` is imported or exported - type the value, or take unknown and narrow it`,
|
|
292
|
+
);
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
continue;
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
const cast = CAST.exec(syntax);
|
|
299
|
+
|
|
300
|
+
if (cast !== null) {
|
|
301
|
+
problems.push(
|
|
302
|
+
`${where}an explicit cast (${cast[0].trim()}) - parse or narrow the value instead (V-C-10)`,
|
|
303
|
+
);
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
if (ANY_TYPE.test(syntax)) {
|
|
307
|
+
problems.push(
|
|
308
|
+
`${where}\`any\` or \`AnyType\` as a type - type it, or take unknown and narrow it`,
|
|
309
|
+
);
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
if (CONDITIONAL_SPREAD.test(syntax)) {
|
|
313
|
+
problems.push(
|
|
314
|
+
`${where}a conditional spread - build the object, then assign the optional key`,
|
|
315
|
+
);
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
if (LITERAL_UNION.test(syntax)) {
|
|
319
|
+
problems.push(`${where}a string-literal union - a const class and its value type (V-C-08)`);
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
return problems;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
private static tableWarningsOf(opts: { page: { file: string; lines: string[] } }): string[] {
|
|
327
|
+
const warnings: string[] = [];
|
|
328
|
+
let rows = 0;
|
|
329
|
+
|
|
330
|
+
for (const { text, number, fence } of DocsCodeCheck.linesWithFence({
|
|
331
|
+
lines: opts.page.lines,
|
|
332
|
+
})) {
|
|
333
|
+
if (fence !== undefined || !text.trimStart().startsWith('|')) {
|
|
334
|
+
rows = 0;
|
|
335
|
+
|
|
336
|
+
continue;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
rows += 1;
|
|
340
|
+
|
|
341
|
+
const cells = cellsOf({ line: text });
|
|
342
|
+
const isSeparator = cells.every((cell) => /^:?-{3,}:?$/.test(cell));
|
|
343
|
+
const where = `docs-table: ${opts.page.file}:${number}: `;
|
|
344
|
+
|
|
345
|
+
if (isSeparator) {
|
|
346
|
+
continue;
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
const long = cells.find((cell) => cell.length > TABLE_CELL_MAX);
|
|
350
|
+
|
|
351
|
+
if (long !== undefined) {
|
|
352
|
+
warnings.push(
|
|
353
|
+
`${where}a cell of ${long.length} characters (over ${TABLE_CELL_MAX}) - a heading and a short table, or a list`,
|
|
354
|
+
);
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
if (
|
|
358
|
+
rows > 2 &&
|
|
359
|
+
cells.length > 1 &&
|
|
360
|
+
cells[0] === '' &&
|
|
361
|
+
cells.slice(1).some((cell) => cell !== '')
|
|
362
|
+
) {
|
|
363
|
+
warnings.push(`${where}a continuation row with an empty first cell - one row for one item`);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
return warnings;
|
|
368
|
+
}
|
|
369
|
+
}
|
package/src/check/house.ts
CHANGED
|
@@ -8,6 +8,7 @@ import type { IBundleFile } from '../spec/index.ts';
|
|
|
8
8
|
import { CoverageAxes } from '../coverage-report/axes.ts';
|
|
9
9
|
import { ContentsFiles } from '../generate/contents-files.ts';
|
|
10
10
|
import { ChangelogCheck } from './changelogs.ts';
|
|
11
|
+
import { DocsCodeCheck } from './docs-code.ts';
|
|
11
12
|
import { GeneratedPages, ManagedRegion } from '../generate/index.ts';
|
|
12
13
|
import type { ILoadedRegion, ILoadedRenderer } from '../generate/index.ts';
|
|
13
14
|
import { SourceCollector, SourceScanner } from '../source/index.ts';
|
|
@@ -153,6 +154,9 @@ export class HouseCheck {
|
|
|
153
154
|
// C3: every dated changelog entry declares its packages by npm name.
|
|
154
155
|
problems.push(...ChangelogCheck.collectProblems());
|
|
155
156
|
|
|
157
|
+
// The code the wiki shows follows the code rules: no cast, no any, no conditional spread, no literal union.
|
|
158
|
+
problems.push(...DocsCodeCheck.collectProblems());
|
|
159
|
+
|
|
156
160
|
// A long agent-read file opens with its contents - an agent may read its first lines only.
|
|
157
161
|
problems.push(
|
|
158
162
|
...ContentsFiles.collectProblems({ skip: new Set(pages.map((page) => page.path)) }),
|
|
@@ -23,6 +23,8 @@ export interface IOkfRegionEntry {
|
|
|
23
23
|
export interface IOkfProject {
|
|
24
24
|
root: string;
|
|
25
25
|
bundle: string;
|
|
26
|
+
/** Absolute; `knowledge.wiki` - absent when the project keeps no wiki. */
|
|
27
|
+
wiki?: string;
|
|
26
28
|
/** Absolute; `knowledge.changelogs` - absent when the project keeps none. */
|
|
27
29
|
changelogs?: string;
|
|
28
30
|
/** `atlas.tagPattern`, the template of a release tag. */
|
package/src/project/reader.ts
CHANGED
|
@@ -161,6 +161,7 @@ export class OkfProject {
|
|
|
161
161
|
stringOf({ value: knowledge.bundle, fallback: OkfProjectConstants.DEFAULT_BUNDLE }),
|
|
162
162
|
);
|
|
163
163
|
const changelogs = knowledge.changelogs;
|
|
164
|
+
const wiki = knowledge.wiki;
|
|
164
165
|
const atlas = recordOf({ value: config.atlas });
|
|
165
166
|
|
|
166
167
|
const project: IOkfProject = {
|
|
@@ -186,6 +187,10 @@ export class OkfProject {
|
|
|
186
187
|
brand: stringOf({ value: okf.brand, fallback: brandOf({ root }) }),
|
|
187
188
|
};
|
|
188
189
|
|
|
190
|
+
if (typeof wiki === 'string') {
|
|
191
|
+
project.wiki = resolve(root, wiki);
|
|
192
|
+
}
|
|
193
|
+
|
|
189
194
|
cached = { text, root, project };
|
|
190
195
|
|
|
191
196
|
return project;
|