@venizia/vulcan-okf 0.4.10-2 → 0.4.10-20
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 +3 -5
- package/package.json +2 -7
- package/src/check/changelogs.ts +14 -3
- 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 +5 -1
- package/src/cli.ts +2 -3
- package/src/config.ts +1 -1
- package/src/generate/contents.ts +1 -0
- package/src/generate/define.ts +14 -0
- package/src/index.ts +2 -0
- package/src/lib.ts +3 -3
- package/src/project/common/constants.ts +0 -1
- package/src/project/common/types.ts +4 -2
- package/src/project/reader.ts +6 -21
- package/src/run.ts +2 -8
- package/src/source/collectors.ts +1 -1
- package/src/spec/common/constants.ts +3 -0
- package/src/spec/common/types.ts +1 -0
- package/src/spec/conformance.ts +1 -0
- package/src/spec/frontmatter.ts +3 -0
- package/src/viz/builder.ts +0 -144
- package/src/viz/client/explorer.ts +0 -528
- package/src/viz/client/frame.ts +0 -17
- package/src/viz/client/html.ts +0 -9
- package/src/viz/client/main.ts +0 -71
- package/src/viz/client/markdown.ts +0 -162
- package/src/viz/client/strings.ts +0 -59
- package/src/viz/client/theme.ts +0 -126
- package/src/viz/common/constants.ts +0 -55
- package/src/viz/common/index.ts +0 -2
- package/src/viz/common/types.ts +0 -46
- package/src/viz/copy.ts +0 -55
- package/src/viz/index.ts +0 -1
- package/src/viz/template.html +0 -580
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# @venizia/vulcan-okf
|
|
2
2
|
|
|
3
|
-
Generator, conformance gate
|
|
3
|
+
Generator, conformance gate and coverage report for a project's knowledge bundle at
|
|
4
4
|
`.agents/knowledge/`, in the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/open-knowledge-format)
|
|
5
5
|
v0.2. Part of VULCAN; the bundle is served over MCP by `@venizia/vulcan-atlas`, not from here.
|
|
6
6
|
|
|
7
7
|
## Commands
|
|
8
8
|
|
|
9
|
-
Run through the pinned `vulcan` CLI (`bun
|
|
9
|
+
Run through the pinned `vulcan` CLI (`bun node_modules/.bin/vulcan x okf <command>`) or the project's make targets.
|
|
10
10
|
The tooling reads the project it runs in (the working directory).
|
|
11
11
|
|
|
12
12
|
| Command | What it does |
|
|
@@ -14,8 +14,7 @@ The tooling reads the project it runs in (the working directory).
|
|
|
14
14
|
| `check` | Gate: OKF v0.2 conformance (spec §11). Errors fail; soft-guidance warnings print and never fail |
|
|
15
15
|
| `check --strict` | `check` plus the house rules: every link resolves, docs style, structural coverage, freshness |
|
|
16
16
|
| `gen` | Regenerate all source-derived content |
|
|
17
|
-
| `coverage [--min <n>]` | Report the bundle against the source inventory; `--min` fails below `<n>` percent |
|
|
18
|
-
| `viz` | Build the offline graph explorer, `.agents/knowledge/viz.html` |
|
|
17
|
+
| `coverage [--min <n>]` | Report the bundle against the source inventory; `--min` fails when the structural coverage is below `<n>` percent |
|
|
19
18
|
|
|
20
19
|
## OKF v0.2 conformance (`check`)
|
|
21
20
|
|
|
@@ -83,7 +82,6 @@ The [renderers reference](../../docs/wiki/content/references/okf/renderers.md) s
|
|
|
83
82
|
| `src/coverage-report/` | `coverage`: the bundle against the source inventory |
|
|
84
83
|
| `src/lib.ts` | bundle loader: frontmatter, links, concept model |
|
|
85
84
|
| `src/spec/` | OKF v0.2 conformance - pure, never throws |
|
|
86
|
-
| `src/viz/` | explorer: builder (Bun), typed browser client, template |
|
|
87
85
|
| `src/project/` | reads the project config `vulcan x` hands okf - everything project-specific |
|
|
88
86
|
| `src/config.ts` | constants that hold for every project: pruned directories, reserved files |
|
|
89
87
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan-okf",
|
|
3
|
-
"version": "0.4.10-
|
|
4
|
-
"description": "VULCAN knowledge tooling: OKF v0.2 conformance check (plus --strict house rules), gen,
|
|
3
|
+
"version": "0.4.10-20",
|
|
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": {
|
|
7
7
|
"url": "https://github.com/VENIZIA-AI/vulcan/issues"
|
|
@@ -40,13 +40,8 @@
|
|
|
40
40
|
"force-update": "sh ../../scripts/build/force-update.sh",
|
|
41
41
|
"test": "bun test"
|
|
42
42
|
},
|
|
43
|
-
"dependencies": {
|
|
44
|
-
"cytoscape": "^3.34.4",
|
|
45
|
-
"cytoscape-fcose": "^2.2.0"
|
|
46
|
-
},
|
|
47
43
|
"devDependencies": {
|
|
48
44
|
"@types/bun": "1.4.3",
|
|
49
|
-
"@types/cytoscape-fcose": "2.2.5",
|
|
50
45
|
"@venizia/dev-configs": "0.4.7-0",
|
|
51
46
|
"eslint": "10.13.0",
|
|
52
47
|
"oxlint": "1.89.0",
|
package/src/check/changelogs.ts
CHANGED
|
@@ -5,6 +5,7 @@ import { RecordValue } from '../common/record.ts';
|
|
|
5
5
|
import { OkfProject } from '../project/index.ts';
|
|
6
6
|
|
|
7
7
|
const DATED_ENTRY = /^\d{4}-\d{2}-\d{2}-.*\.md$/;
|
|
8
|
+
const VERSION_FOLDER = /^\d+\.\d+\.\d+$/;
|
|
8
9
|
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
|
|
9
10
|
/** `'<npm name>@<version>'` - the name may be scoped, so the version is after the LAST `@`. */
|
|
10
11
|
const RELEASE_OVERRIDE = /^(.+)@([^@]+)$/;
|
|
@@ -57,9 +58,19 @@ export class ChangelogCheck {
|
|
|
57
58
|
const problems: string[] = [];
|
|
58
59
|
let tags: string[] | undefined;
|
|
59
60
|
|
|
60
|
-
|
|
61
|
-
.
|
|
62
|
-
|
|
61
|
+
const entries = readdirSync(directory, { withFileTypes: true })
|
|
62
|
+
.flatMap((dirent) => {
|
|
63
|
+
if (dirent.isDirectory() && VERSION_FOLDER.test(dirent.name)) {
|
|
64
|
+
return existsSync(join(directory, dirent.name, 'log.md'))
|
|
65
|
+
? [`${dirent.name}/log.md`]
|
|
66
|
+
: [];
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
return DATED_ENTRY.test(dirent.name) ? [dirent.name] : [];
|
|
70
|
+
})
|
|
71
|
+
.sort();
|
|
72
|
+
|
|
73
|
+
for (const file of entries) {
|
|
63
74
|
const path = relative(project.root, join(directory, file));
|
|
64
75
|
let frontmatter: TRecord;
|
|
65
76
|
|
|
@@ -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';
|
|
@@ -81,7 +82,7 @@ export class HouseCheck {
|
|
|
81
82
|
for (const file of opts.files) {
|
|
82
83
|
const prose = MarkdownText.stripCode({ text: file.text });
|
|
83
84
|
|
|
84
|
-
for (const rule of HouseCheck.styleRules({ brand: OkfProject.read().
|
|
85
|
+
for (const rule of HouseCheck.styleRules({ brand: OkfProject.read().brand })) {
|
|
85
86
|
const match = prose.match(rule.pattern);
|
|
86
87
|
|
|
87
88
|
if (match) {
|
|
@@ -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)) }),
|
package/src/cli.ts
CHANGED
|
@@ -9,14 +9,13 @@ class OkfCommands {
|
|
|
9
9
|
static readonly CHECK = 'check';
|
|
10
10
|
static readonly GEN = 'gen';
|
|
11
11
|
static readonly COVERAGE = 'coverage';
|
|
12
|
-
static readonly
|
|
13
|
-
static readonly SCHEME_SET = new Set<string>([this.CHECK, this.GEN, this.COVERAGE, this.VIZ]);
|
|
12
|
+
static readonly SCHEME_SET = new Set<string>([this.CHECK, this.GEN, this.COVERAGE]);
|
|
14
13
|
static isValid(value: string): boolean {
|
|
15
14
|
return this.SCHEME_SET.has(value);
|
|
16
15
|
}
|
|
17
16
|
}
|
|
18
17
|
|
|
19
|
-
const USAGE = 'usage: vulcan x okf <check|gen|coverage
|
|
18
|
+
const USAGE = 'usage: vulcan x okf <check|gen|coverage>';
|
|
20
19
|
|
|
21
20
|
const [command, ...rest] = process.argv.slice(2);
|
|
22
21
|
|
package/src/config.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* config.ts - okf's constants that hold for every project. Everything project-specific (paths,
|
|
3
|
-
* packages, renderers, regions,
|
|
3
|
+
* packages, renderers, regions, coverage axes, denylist, the brand)
|
|
4
4
|
* comes from the project config `vulcan x` hands okf - see project/reader.ts.
|
|
5
5
|
*/
|
|
6
6
|
|
package/src/generate/contents.ts
CHANGED
|
@@ -177,6 +177,7 @@ const insertionPointOf = (opts: { text: string }): number => {
|
|
|
177
177
|
return at + (/^\n*/.exec(opts.text.slice(at))?.[0].length ?? 0);
|
|
178
178
|
};
|
|
179
179
|
|
|
180
|
+
/** The contents list a long agent-read file carries; `vulcan sync` writes it into the `AGENTS.md` it rewrites. */
|
|
180
181
|
export class ContentsList {
|
|
181
182
|
/**
|
|
182
183
|
* The file as `okf gen` writes it: a contents list of its `##` headings near the top when it runs
|