@venizia/vulcan-okf 0.4.8 → 0.4.9-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/package.json +3 -4
- package/src/check/changelogs.ts +74 -74
- package/src/check/command.ts +14 -12
- package/src/check/house.ts +116 -108
- package/src/cli.ts +3 -1
- package/src/common/record.ts +6 -0
- package/src/coverage-report/axes.ts +72 -66
- package/src/coverage-report/command.ts +14 -12
- package/src/generate/command.ts +15 -13
- package/src/generate/contents-files.ts +34 -30
- package/src/generate/contents.ts +27 -22
- package/src/generate/define.ts +25 -23
- package/src/generate/pages.ts +39 -37
- package/src/generate/regions.ts +51 -53
- package/src/generate/registry.ts +56 -51
- package/src/generate/renderers.ts +7 -10
- package/src/lib.ts +84 -82
- package/src/project/reader.ts +74 -71
- package/src/source/collectors.ts +190 -182
- package/src/source/scanner.ts +65 -61
- package/src/spec/conformance.ts +28 -27
- package/src/spec/frontmatter.ts +26 -27
- package/src/viz/builder.ts +93 -93
- package/src/viz/client/explorer.ts +25 -25
- package/src/viz/client/frame.ts +14 -12
- package/src/viz/client/html.ts +8 -4
- package/src/viz/client/main.ts +2 -2
- package/src/viz/client/markdown.ts +96 -94
- package/src/viz/client/strings.ts +12 -10
- package/src/viz/client/theme.ts +3 -3
- package/src/viz/common/constants.ts +0 -1
- package/src/viz/copy.ts +17 -19
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { statSync } from 'node:fs';
|
|
2
2
|
import { basename, join } from 'node:path';
|
|
3
|
-
import {
|
|
3
|
+
import { OkfProject } from '../project/index.ts';
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
interface ICoverageAxis {
|
|
6
6
|
name: string;
|
|
7
7
|
items: string[];
|
|
8
8
|
/** Each item's directory from the project root. */
|
|
@@ -13,76 +13,82 @@ export interface ICoverageAxis {
|
|
|
13
13
|
const resourceKeyOf = (opts: { value: string }): string =>
|
|
14
14
|
opts.value.replace(/^\.\//, '').replace(/\/+$/, '');
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
.
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
* THE coverage rule, shared by `coverage` and `check --strict`: an axis item is covered by a concept
|
|
28
|
-
* at `/<axis>/<item>` (`ids`), or by any concept whose `resource` is the item's directory.
|
|
29
|
-
*/
|
|
30
|
-
export const isItemCovered = (opts: {
|
|
31
|
-
axis: ICoverageAxis;
|
|
32
|
-
item: string;
|
|
33
|
-
ids: Set<string>;
|
|
34
|
-
resources: Set<string>;
|
|
35
|
-
}): boolean =>
|
|
36
|
-
opts.ids.has(`/${opts.axis.name}/${opts.item}`) ||
|
|
37
|
-
opts.resources.has(opts.axis.paths[opts.item] ?? opts.item);
|
|
16
|
+
export class CoverageAxes {
|
|
17
|
+
/** The `resource` of every concept, as keys for `isItemCovered`; reserved files (index, log) cover nothing. */
|
|
18
|
+
static resourceKeysOf(opts: {
|
|
19
|
+
concepts: { resource: string; reserved: boolean }[];
|
|
20
|
+
}): Set<string> {
|
|
21
|
+
return new Set(
|
|
22
|
+
opts.concepts
|
|
23
|
+
.filter((concept) => !concept.reserved && concept.resource !== '')
|
|
24
|
+
.map((concept) => resourceKeyOf({ value: concept.resource })),
|
|
25
|
+
);
|
|
26
|
+
}
|
|
38
27
|
|
|
39
|
-
/**
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
28
|
+
/**
|
|
29
|
+
* THE coverage rule, shared by `coverage` and `check --strict`: an axis item is covered by a concept
|
|
30
|
+
* at `/<axis>/<item>` (`ids`), or by any concept whose `resource` is the item's directory.
|
|
31
|
+
*/
|
|
32
|
+
static isItemCovered(opts: {
|
|
33
|
+
axis: ICoverageAxis;
|
|
34
|
+
item: string;
|
|
35
|
+
ids: Set<string>;
|
|
36
|
+
resources: Set<string>;
|
|
37
|
+
}): boolean {
|
|
38
|
+
return (
|
|
39
|
+
opts.ids.has(`/${opts.axis.name}/${opts.item}`) ||
|
|
40
|
+
opts.resources.has(opts.axis.paths[opts.item] ?? opts.item)
|
|
41
|
+
);
|
|
42
|
+
}
|
|
52
43
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
44
|
+
/**
|
|
45
|
+
* The structural coverage axes (`okf.coverage`): each `path` globs directories under the root, and
|
|
46
|
+
* every matched directory, minus the denylist, the axis's own `denylist` and its `exclude` globs, needs a concept at `<name>/<directory>.md` - or any
|
|
47
|
+
* concept whose frontmatter `resource` is the directory (`paths` maps each item to it). A path that
|
|
48
|
+
* matches no directory is a problem - an axis that covers nothing passes by accident.
|
|
49
|
+
*/
|
|
50
|
+
static collect(): {
|
|
51
|
+
axes: ICoverageAxis[];
|
|
52
|
+
problems: string[];
|
|
53
|
+
} {
|
|
54
|
+
const project = OkfProject.read();
|
|
55
|
+
const axes: ICoverageAxis[] = [];
|
|
56
|
+
const problems: string[] = [];
|
|
57
57
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
58
|
+
for (const axis of project.coverage) {
|
|
59
|
+
const matched = [
|
|
60
|
+
...new Bun.Glob(axis.path).scanSync({ cwd: project.root, onlyFiles: false, dot: false }),
|
|
61
|
+
].filter((path) => statSync(join(project.root, path)).isDirectory());
|
|
62
62
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
!axis.denylist.includes(basename(path)) &&
|
|
68
|
-
!excluded.some((glob) => glob.match(path)),
|
|
69
|
-
);
|
|
63
|
+
if (matched.length === 0) {
|
|
64
|
+
problems.push(`coverage: axis '${axis.name}' (${axis.path}) matches no directory`);
|
|
65
|
+
continue;
|
|
66
|
+
}
|
|
70
67
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
68
|
+
const excluded = axis.exclude.map((pattern) => new Bun.Glob(pattern));
|
|
69
|
+
const kept = matched.filter(
|
|
70
|
+
(path) =>
|
|
71
|
+
!project.denylist.has(basename(path)) &&
|
|
72
|
+
!axis.denylist.includes(basename(path)) &&
|
|
73
|
+
!excluded.some((glob) => glob.match(path)),
|
|
74
74
|
);
|
|
75
|
-
continue;
|
|
76
|
-
}
|
|
77
75
|
|
|
78
|
-
|
|
76
|
+
if (kept.length === 0) {
|
|
77
|
+
problems.push(
|
|
78
|
+
`coverage: axis '${axis.name}' (${axis.path}) has no directory left after exclude/denylist`,
|
|
79
|
+
);
|
|
80
|
+
continue;
|
|
81
|
+
}
|
|
79
82
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
83
|
+
const items = [...new Set(kept.map((path) => basename(path)))].sort();
|
|
84
|
+
|
|
85
|
+
axes.push({
|
|
86
|
+
name: axis.name,
|
|
87
|
+
items,
|
|
88
|
+
paths: Object.fromEntries(kept.map((path) => [basename(path), path])),
|
|
89
|
+
});
|
|
90
|
+
}
|
|
86
91
|
|
|
87
|
-
|
|
88
|
-
}
|
|
92
|
+
return { axes, problems };
|
|
93
|
+
}
|
|
94
|
+
}
|
|
@@ -1,24 +1,24 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
1
|
+
import { GenerationRegistry } from '../generate/index.ts';
|
|
2
|
+
import { ConceptLoader } from '../lib.ts';
|
|
3
|
+
import { SourceScanner } from '../source/index.ts';
|
|
4
|
+
import { CoverageAxes } from './axes.ts';
|
|
5
5
|
|
|
6
6
|
// --- coverage ---
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
const percent = (opts: { value: number; total: number }): number => {
|
|
9
9
|
return opts.total ? Math.round((opts.value / opts.total) * 100) : 100;
|
|
10
10
|
};
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
const pad = (opts: { value: string; width: number }): string => {
|
|
13
13
|
return (opts.value + ' '.repeat(opts.width)).slice(0, opts.width);
|
|
14
14
|
};
|
|
15
15
|
|
|
16
16
|
export const coverage = async (): Promise<void> => {
|
|
17
|
-
const concepts =
|
|
17
|
+
const concepts = ConceptLoader.loadOrExit().filter((concept) => !concept.reserved);
|
|
18
18
|
const ids = new Set(concepts.map((concept) => concept.id));
|
|
19
19
|
|
|
20
20
|
const hasId = (opts: { id: string }): boolean => ids.has(opts.id);
|
|
21
|
-
const resources = resourceKeysOf({ concepts });
|
|
21
|
+
const resources = CoverageAxes.resourceKeysOf({ concepts });
|
|
22
22
|
const lines: string[] = [];
|
|
23
23
|
let structCovered = 0;
|
|
24
24
|
let structTotal = 0;
|
|
@@ -45,7 +45,7 @@ export const coverage = async (): Promise<void> => {
|
|
|
45
45
|
);
|
|
46
46
|
};
|
|
47
47
|
|
|
48
|
-
const { axes, problems } =
|
|
48
|
+
const { axes, problems } = CoverageAxes.collect();
|
|
49
49
|
|
|
50
50
|
// The report would count an axis that covers nothing as fully covered.
|
|
51
51
|
if (problems.length > 0) {
|
|
@@ -57,7 +57,7 @@ export const coverage = async (): Promise<void> => {
|
|
|
57
57
|
struct({
|
|
58
58
|
name: axis.name,
|
|
59
59
|
items: axis.items,
|
|
60
|
-
covered: (item) => isItemCovered({ axis, item, ids, resources }),
|
|
60
|
+
covered: (item) => CoverageAxes.isItemCovered({ axis, item, ids, resources }),
|
|
61
61
|
});
|
|
62
62
|
}
|
|
63
63
|
|
|
@@ -70,8 +70,10 @@ export const coverage = async (): Promise<void> => {
|
|
|
70
70
|
);
|
|
71
71
|
};
|
|
72
72
|
|
|
73
|
+
const generation = await GenerationRegistry.load();
|
|
74
|
+
|
|
73
75
|
// One row per configured renderer that reports one, from the same facts its table renders.
|
|
74
|
-
for (const { renderer, context } of
|
|
76
|
+
for (const { renderer, context } of generation.renderers) {
|
|
75
77
|
if (renderer.coverage === undefined) {
|
|
76
78
|
continue;
|
|
77
79
|
}
|
|
@@ -96,7 +98,7 @@ export const coverage = async (): Promise<void> => {
|
|
|
96
98
|
types[concept.type] = (types[concept.type] || 0) + 1;
|
|
97
99
|
}
|
|
98
100
|
|
|
99
|
-
const playbookTarget = packageDirs().length;
|
|
101
|
+
const playbookTarget = SourceScanner.packageDirs().length;
|
|
100
102
|
|
|
101
103
|
lines.push('', 'KNOWLEDGE TYPES (Diátaxis / arc42)');
|
|
102
104
|
lines.push(
|
package/src/generate/command.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { dirname } from 'node:path';
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
3
|
+
import { ManagedRegion } from './regions.ts';
|
|
4
|
+
import { ContentsFiles } from './contents-files.ts';
|
|
5
|
+
import { GeneratedPages } from './pages.ts';
|
|
6
|
+
import { GenerationRegistry } from './registry.ts';
|
|
7
7
|
import { BUILT_IN_RENDERERS } from './renderers.ts';
|
|
8
|
-
import {
|
|
8
|
+
import { SourceScanner } from '../source/index.ts';
|
|
9
9
|
|
|
10
10
|
/** The file as it is on disk, or undefined when it does not exist yet. */
|
|
11
11
|
const currentOf = (opts: { path: string }): string | undefined =>
|
|
@@ -18,43 +18,45 @@ const currentOf = (opts: { path: string }): string | undefined =>
|
|
|
18
18
|
* changed is written and named, so a run with nothing to do says so in one line.
|
|
19
19
|
*/
|
|
20
20
|
export const gen = async (): Promise<void> => {
|
|
21
|
-
const { renderers, regions } = await
|
|
21
|
+
const { renderers, regions } = await GenerationRegistry.load();
|
|
22
22
|
const regionWrites = regions.flatMap((region) => {
|
|
23
23
|
const current = currentOf({ path: region.file });
|
|
24
24
|
|
|
25
25
|
if (current === undefined) {
|
|
26
26
|
console.warn(
|
|
27
|
-
`gen: skipped region '${region.id}' - ${repoRelative({ path: region.file })} does not exist yet`,
|
|
27
|
+
`gen: skipped region '${region.id}' - ${SourceScanner.repoRelative({ path: region.file })} does not exist yet`,
|
|
28
28
|
);
|
|
29
29
|
|
|
30
30
|
return [];
|
|
31
31
|
}
|
|
32
32
|
|
|
33
|
-
const text =
|
|
33
|
+
const text = ManagedRegion.replace({
|
|
34
34
|
text: current,
|
|
35
35
|
id: region.id,
|
|
36
|
-
file: repoRelative({ path: region.file }),
|
|
36
|
+
file: SourceScanner.repoRelative({ path: region.file }),
|
|
37
37
|
body: region.render(),
|
|
38
38
|
});
|
|
39
39
|
|
|
40
40
|
return text === current ? [] : [{ region, text }];
|
|
41
41
|
});
|
|
42
|
-
const rendered =
|
|
42
|
+
const rendered = GeneratedPages.render({ renderers });
|
|
43
43
|
const pages = rendered.filter((page) => currentOf({ path: page.path }) !== page.content);
|
|
44
44
|
|
|
45
45
|
for (const { region, text } of regionWrites) {
|
|
46
46
|
writeFileSync(region.file, text);
|
|
47
|
-
console.log(
|
|
47
|
+
console.log(
|
|
48
|
+
`gen: wrote region '${region.id}' (${SourceScanner.repoRelative({ path: region.file })})`,
|
|
49
|
+
);
|
|
48
50
|
}
|
|
49
51
|
|
|
50
52
|
for (const page of pages) {
|
|
51
53
|
mkdirSync(dirname(page.path), { recursive: true });
|
|
52
54
|
writeFileSync(page.path, page.content);
|
|
53
|
-
console.log(`gen: wrote ${repoRelative({ path: page.path })}`);
|
|
55
|
+
console.log(`gen: wrote ${SourceScanner.repoRelative({ path: page.path })}`);
|
|
54
56
|
}
|
|
55
57
|
|
|
56
58
|
// Every project's long agent-read files carry a contents list, whatever it renders.
|
|
57
|
-
const contents =
|
|
59
|
+
const contents = ContentsFiles.write({ skip: new Set(rendered.map((page) => page.path)) });
|
|
58
60
|
|
|
59
61
|
for (const file of contents) {
|
|
60
62
|
console.log(`gen: wrote the contents list of ${file}`);
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { join, relative } from 'node:path';
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
3
|
+
import { OkfProject } from '../project/index.ts';
|
|
4
|
+
import { SourceScanner } from '../source/index.ts';
|
|
5
|
+
import { ContentsList } from './contents.ts';
|
|
6
6
|
|
|
7
7
|
/** The frontmatter block, LF or CRLF. */
|
|
8
8
|
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
|
|
@@ -16,8 +16,8 @@ const LOG_FILE = 'log.md';
|
|
|
16
16
|
|
|
17
17
|
/** The files agents read: the bundle's own Markdown, then `okf.contents.files` (AGENTS.md, rules.md); `skip` holds the pages a renderer owns. */
|
|
18
18
|
const contentsTargets = (opts: { skip: Set<string> }): string[] => {
|
|
19
|
-
const project =
|
|
20
|
-
const bundle = walkFiles({ dir: project.bundle }).filter(
|
|
19
|
+
const project = OkfProject.read();
|
|
20
|
+
const bundle = SourceScanner.walkFiles({ dir: project.bundle }).filter(
|
|
21
21
|
(file) =>
|
|
22
22
|
file.endsWith('.md') &&
|
|
23
23
|
!opts.skip.has(file) &&
|
|
@@ -28,32 +28,36 @@ const contentsTargets = (opts: { skip: Set<string> }): string[] => {
|
|
|
28
28
|
return [...bundle.sort(), ...project.contentsFiles.filter((file) => existsSync(file))];
|
|
29
29
|
};
|
|
30
30
|
|
|
31
|
-
const shown = (opts: { file: string }): string => relative(
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
31
|
+
const shown = (opts: { file: string }): string => relative(OkfProject.read().root, opts.file);
|
|
32
|
+
|
|
33
|
+
export class ContentsFiles {
|
|
34
|
+
/** Every agent-read file whose contents list is missing or stale - `check --strict` fails on them. */
|
|
35
|
+
static collectProblems(opts: { skip: Set<string> }): string[] {
|
|
36
|
+
return contentsTargets(opts)
|
|
37
|
+
.filter((file) => {
|
|
38
|
+
const text = readFileSync(file, 'utf8');
|
|
39
|
+
|
|
40
|
+
return ContentsList.withContents({ text }) !== text;
|
|
41
|
+
})
|
|
42
|
+
.map(
|
|
43
|
+
(file) =>
|
|
44
|
+
`contents: ${shown({ file })} has no fresh contents list - run \`vulcan x okf gen\``,
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Writes every contents list `gen` owes; the files written, from the root. */
|
|
49
|
+
static write(opts: { skip: Set<string> }): string[] {
|
|
50
|
+
return contentsTargets(opts).flatMap((file) => {
|
|
37
51
|
const text = readFileSync(file, 'utf8');
|
|
52
|
+
const next = ContentsList.withContents({ text });
|
|
38
53
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
(file) =>
|
|
43
|
-
`contents: ${shown({ file })} has no fresh contents list - run \`vulcan x okf gen\``,
|
|
44
|
-
);
|
|
45
|
-
|
|
46
|
-
/** Writes every contents list `gen` owes; the files written, from the root. */
|
|
47
|
-
export const writeContents = (opts: { skip: Set<string> }): string[] =>
|
|
48
|
-
contentsTargets(opts).flatMap((file) => {
|
|
49
|
-
const text = readFileSync(file, 'utf8');
|
|
50
|
-
const next = withContents({ text });
|
|
51
|
-
|
|
52
|
-
if (next === text) {
|
|
53
|
-
return [];
|
|
54
|
-
}
|
|
54
|
+
if (next === text) {
|
|
55
|
+
return [];
|
|
56
|
+
}
|
|
55
57
|
|
|
56
|
-
|
|
58
|
+
writeFileSync(file, next);
|
|
57
59
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
+
return [shown({ file })];
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
}
|
package/src/generate/contents.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { ManagedRegion } from './regions.ts';
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* An agent may preview a file's first lines only (Anthropic's skill guidance: "include a table of
|
|
@@ -141,7 +141,7 @@ const headingsOf = (opts: { text: string }): { text: string; anchor: string }[]
|
|
|
141
141
|
* every word of it.
|
|
142
142
|
*/
|
|
143
143
|
const withoutContents = (opts: { text: string }): string => {
|
|
144
|
-
const { start, end } = markers({ id: CONTENTS_ID });
|
|
144
|
+
const { start, end } = ManagedRegion.markers({ id: CONTENTS_ID });
|
|
145
145
|
const lines = opts.text.split('\n');
|
|
146
146
|
let startLine = -1;
|
|
147
147
|
let endLine = -1;
|
|
@@ -177,27 +177,32 @@ const insertionPointOf = (opts: { text: string }): number => {
|
|
|
177
177
|
return at + (/^\n*/.exec(opts.text.slice(at))?.[0].length ?? 0);
|
|
178
178
|
};
|
|
179
179
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
180
|
+
export class ContentsList {
|
|
181
|
+
/**
|
|
182
|
+
* The file as `okf gen` writes it: a contents list of its `##` headings near the top when it runs
|
|
183
|
+
* past `CONTENTS_MIN_LINES`, none when it does not. A fixed point - a second pass changes nothing.
|
|
184
|
+
*/
|
|
185
|
+
static withContents(opts: { text: string }): string {
|
|
186
|
+
// A CRLF file is read as LF and written back with its own endings.
|
|
187
|
+
if (opts.text.includes('\r\n')) {
|
|
188
|
+
return ContentsList.withContents({ text: opts.text.replace(/\r\n/g, '\n') }).replace(
|
|
189
|
+
/\n/g,
|
|
190
|
+
'\r\n',
|
|
191
|
+
);
|
|
192
|
+
}
|
|
189
193
|
|
|
190
|
-
|
|
191
|
-
|
|
194
|
+
const bare = withoutContents({ text: opts.text });
|
|
195
|
+
const headings = headingsOf({ text: bare });
|
|
192
196
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
197
|
+
if (lineCountOf({ text: bare }) <= CONTENTS_MIN_LINES || headings.length === 0) {
|
|
198
|
+
return bare;
|
|
199
|
+
}
|
|
196
200
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
+
const { start, end } = ManagedRegion.markers({ id: CONTENTS_ID });
|
|
202
|
+
const list = headings.map((heading) => `- [${heading.text}](#${heading.anchor})`).join('\n');
|
|
203
|
+
const block = `${start}\n**Contents**\n\n${list}\n${end}\n\n`;
|
|
204
|
+
const at = insertionPointOf({ text: bare });
|
|
201
205
|
|
|
202
|
-
|
|
203
|
-
}
|
|
206
|
+
return bare.slice(0, at) + block + bare.slice(at);
|
|
207
|
+
}
|
|
208
|
+
}
|
package/src/generate/define.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
3
|
+
import { OkfProject } from '../project/index.ts';
|
|
4
|
+
import { SourceScanner } from '../source/index.ts';
|
|
5
5
|
|
|
6
6
|
/** Reading the project's source - every `dir` is relative to the project root. */
|
|
7
7
|
export interface IRenderSource {
|
|
@@ -64,7 +64,7 @@ const namesPerDir = (opts: {
|
|
|
64
64
|
.map((dir) => {
|
|
65
65
|
const names = new Set<string>();
|
|
66
66
|
|
|
67
|
-
for (const file of sourceFiles({ dir: join(opts.root, dir) })) {
|
|
67
|
+
for (const file of SourceScanner.sourceFiles({ dir: join(opts.root, dir) })) {
|
|
68
68
|
for (const match of readFileSync(file, 'utf8').matchAll(pattern)) {
|
|
69
69
|
if (match[1] !== undefined) {
|
|
70
70
|
names.add(match[1]);
|
|
@@ -96,24 +96,26 @@ const page: IRenderPage = {
|
|
|
96
96
|
`> Generated from source - do not edit; run \`make okf-gen\`.${opts.seeAlso === '' ? '' : ` ${opts.seeAlso}`}\n\n`,
|
|
97
97
|
};
|
|
98
98
|
|
|
99
|
-
export
|
|
100
|
-
|
|
99
|
+
export class RenderContext {
|
|
100
|
+
static create(opts: { options: Record<string, unknown> }): IRenderContext {
|
|
101
|
+
const { root, bundle } = OkfProject.read();
|
|
101
102
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
}
|
|
103
|
+
return {
|
|
104
|
+
root,
|
|
105
|
+
bundle,
|
|
106
|
+
options: opts.options,
|
|
107
|
+
source: {
|
|
108
|
+
listDirs: ({ dir }) => SourceScanner.listDirs({ dir: join(root, dir) }),
|
|
109
|
+
sourceFiles: ({ dir }) => SourceScanner.sourceFiles({ dir: join(root, dir) }),
|
|
110
|
+
exportedClasses: ({ dirs, suffix }) =>
|
|
111
|
+
namesPerDir({
|
|
112
|
+
root,
|
|
113
|
+
dirs,
|
|
114
|
+
pattern: new RegExp(`export\\s+(?:abstract\\s+)?class\\s+(\\w+${suffix})\\b`),
|
|
115
|
+
}).map((entry) => ({ dir: entry.dir, classes: entry.names })),
|
|
116
|
+
exportedNames: ({ dirs, pattern }) => namesPerDir({ root, dirs, pattern }),
|
|
117
|
+
},
|
|
118
|
+
page,
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
}
|
package/src/generate/pages.ts
CHANGED
|
@@ -3,7 +3,7 @@ import type { IRenderedFile } from './define.ts';
|
|
|
3
3
|
import type { ILoadedRenderer } from './registry.ts';
|
|
4
4
|
|
|
5
5
|
/** One page a renderer owns, rendered in memory: `path` is absolute, inside the bundle. */
|
|
6
|
-
|
|
6
|
+
interface IRenderedPage {
|
|
7
7
|
id: string;
|
|
8
8
|
path: string;
|
|
9
9
|
content: string;
|
|
@@ -12,48 +12,50 @@ export interface IRenderedPage {
|
|
|
12
12
|
const messageOf = (error: unknown): string =>
|
|
13
13
|
error instanceof Error ? error.message : String(error);
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
15
|
+
export class GeneratedPages {
|
|
16
|
+
/**
|
|
17
|
+
* Every page of every renderer, rendered before anything is written: a renderer that throws, a path
|
|
18
|
+
* outside the bundle, or two pages (of two renderers, or of one) on one path stop the run with an
|
|
19
|
+
* `okf:` error naming the renderer - never a partial write. `gen` writes these pages; `check`
|
|
20
|
+
* compares them.
|
|
21
|
+
*/
|
|
22
|
+
static render(opts: { renderers: ILoadedRenderer[] }): IRenderedPage[] {
|
|
23
|
+
const pages: IRenderedPage[] = [];
|
|
24
|
+
|
|
25
|
+
for (const { renderer, context } of opts.renderers) {
|
|
26
|
+
if (renderer.render === undefined) {
|
|
27
|
+
continue;
|
|
28
|
+
}
|
|
28
29
|
|
|
29
|
-
|
|
30
|
+
let rendered: IRenderedFile | IRenderedFile[];
|
|
30
31
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
32
|
+
try {
|
|
33
|
+
rendered = renderer.render({ context, facts: renderer.collect({ context }) });
|
|
34
|
+
} catch (error) {
|
|
35
|
+
throw new Error(`okf: renderer '${renderer.id}' failed: ${messageOf(error)}`, {
|
|
36
|
+
cause: error,
|
|
37
|
+
});
|
|
38
|
+
}
|
|
38
39
|
|
|
39
|
-
|
|
40
|
-
|
|
40
|
+
for (const file of Array.isArray(rendered) ? rendered : [rendered]) {
|
|
41
|
+
const path = resolve(context.bundle, file.path);
|
|
41
42
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
43
|
+
if (!path.startsWith(`${resolve(context.bundle)}${sep}`)) {
|
|
44
|
+
throw new Error(`okf: renderer '${renderer.id}' writes ${file.path}, outside the bundle`);
|
|
45
|
+
}
|
|
45
46
|
|
|
46
|
-
|
|
47
|
+
const owner = pages.find((page) => page.path === path);
|
|
47
48
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
49
|
+
if (owner !== undefined) {
|
|
50
|
+
throw new Error(
|
|
51
|
+
`okf: renderers '${owner.id}' and '${renderer.id}' both write ${relative(resolve(context.bundle), path)}`,
|
|
52
|
+
);
|
|
53
|
+
}
|
|
53
54
|
|
|
54
|
-
|
|
55
|
+
pages.push({ id: renderer.id, path, content: file.content });
|
|
56
|
+
}
|
|
55
57
|
}
|
|
56
|
-
}
|
|
57
58
|
|
|
58
|
-
|
|
59
|
-
}
|
|
59
|
+
return pages;
|
|
60
|
+
}
|
|
61
|
+
}
|