@venizia/vulcan-okf 0.2.0-0 → 0.2.0-1
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 +5 -1
- package/package.json +1 -1
- package/src/check/changelogs.ts +14 -2
- package/src/check/house.ts +21 -3
- package/src/coverage-report/axes.ts +14 -6
- package/src/coverage-report/command.ts +8 -1
- package/src/generate/command.ts +22 -14
- package/src/generate/contents.ts +92 -32
- package/src/generate/regions.ts +23 -22
- package/src/generate/registry.ts +13 -0
- package/src/project/reader.ts +13 -4
- package/src/source/collectors.ts +5 -3
package/README.md
CHANGED
|
@@ -44,7 +44,11 @@ Two mechanisms, both driven from source. Never hand-edit either.
|
|
|
44
44
|
`reference/public-surface.md` is generated by `@venizia/vulcan-atlas` (`vulcan x atlas surface gen`),
|
|
45
45
|
not by `gen`; its `generated:` frontmatter tells `gen` to leave it whole. Long agent-read files get a
|
|
46
46
|
generated contents list near the top; a file with `generated:` frontmatter and the bundle's `log.md`
|
|
47
|
-
get none.
|
|
47
|
+
get none. The id `contents` is reserved for that list: a region named `contents` stops `gen`.
|
|
48
|
+
|
|
49
|
+
A project module (`okf.renderers[]` with `module`) may take the id of a built-in renderer such as
|
|
50
|
+
`source-map`. The module then replaces the built-in, and `gen`, `check` and `coverage` say so once on
|
|
51
|
+
stderr: `okf: module 'source-map' replaces the built-in renderer`.
|
|
48
52
|
|
|
49
53
|
## Adding a renderer
|
|
50
54
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan-okf",
|
|
3
|
-
"version": "0.2.0-
|
|
3
|
+
"version": "0.2.0-1",
|
|
4
4
|
"description": "VULCAN knowledge tooling: OKF v0.2 conformance check (plus --strict house rules), gen, coverage and the offline graph explorer for a project's .agents/knowledge bundle. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/okf",
|
|
6
6
|
"repository": {
|
package/src/check/changelogs.ts
CHANGED
|
@@ -61,7 +61,18 @@ export const collectChangelogProblems = (): string[] => {
|
|
|
61
61
|
.filter(name => DATED_ENTRY.test(name))
|
|
62
62
|
.sort()) {
|
|
63
63
|
const path = relative(project.root, join(directory, file));
|
|
64
|
-
|
|
64
|
+
let frontmatter: TRecord;
|
|
65
|
+
|
|
66
|
+
// One broken entry is one problem; the rest of the directory is still checked.
|
|
67
|
+
try {
|
|
68
|
+
frontmatter = frontmatterOf({ text: readFileSync(join(directory, file), 'utf8') });
|
|
69
|
+
} catch (error) {
|
|
70
|
+
problems.push(
|
|
71
|
+
`changelog: ${path}: the frontmatter is not valid YAML (${error instanceof Error ? error.message : String(error)})`,
|
|
72
|
+
);
|
|
73
|
+
continue;
|
|
74
|
+
}
|
|
75
|
+
|
|
65
76
|
// `packages: []` is a decision - an entry about no package, such as repository tooling. Only a
|
|
66
77
|
// missing list is undecided.
|
|
67
78
|
if (!Array.isArray(frontmatter.packages)) {
|
|
@@ -102,7 +113,8 @@ export const collectChangelogProblems = (): string[] => {
|
|
|
102
113
|
if (!tags.some(tag => pattern.test(tag))) {
|
|
103
114
|
const expected = project.tagPattern
|
|
104
115
|
.replace(/<(?:dir|package)>/g, dir)
|
|
105
|
-
.replace(/<version>/g, override[2])
|
|
116
|
+
.replace(/<version>/g, override[2])
|
|
117
|
+
.replace(/<date>/g, 'YYYY-MM-DD');
|
|
106
118
|
|
|
107
119
|
problems.push(
|
|
108
120
|
`changelog: ${path}: release '${frontmatter.release}' names no tag (${expected})`,
|
package/src/check/house.ts
CHANGED
|
@@ -93,7 +93,11 @@ export const collectHouseProblems = (opts: {
|
|
|
93
93
|
|
|
94
94
|
const paths = new Set(opts.files.map(file => file.path));
|
|
95
95
|
|
|
96
|
-
|
|
96
|
+
const { axes, problems: axisProblems } = collectCoverageAxes();
|
|
97
|
+
|
|
98
|
+
problems.push(...axisProblems);
|
|
99
|
+
|
|
100
|
+
for (const axis of axes) {
|
|
97
101
|
const section = axis.name;
|
|
98
102
|
|
|
99
103
|
for (const name of axis.items) {
|
|
@@ -111,9 +115,23 @@ export const collectHouseProblems = (opts: {
|
|
|
111
115
|
continue;
|
|
112
116
|
}
|
|
113
117
|
|
|
114
|
-
|
|
118
|
+
let actual: string;
|
|
119
|
+
|
|
120
|
+
// Broken markers are the person's to fix by hand - gen refuses them, so never call them stale.
|
|
121
|
+
try {
|
|
122
|
+
actual = extractRegion({
|
|
123
|
+
text: readFileSync(region.file, 'utf8'),
|
|
124
|
+
id: region.id,
|
|
125
|
+
file: repoRelative({ path: region.file }),
|
|
126
|
+
});
|
|
127
|
+
} catch (error) {
|
|
128
|
+
problems.push(
|
|
129
|
+
`freshness: ${(error instanceof Error ? error.message : String(error)).replace(/^okf: /, '')}`,
|
|
130
|
+
);
|
|
131
|
+
continue;
|
|
132
|
+
}
|
|
115
133
|
|
|
116
|
-
if (
|
|
134
|
+
if (!sameContent({ left: actual, right: region.render() })) {
|
|
117
135
|
problems.push(`freshness: region '${region.id}' is stale - ${REGENERATE_HINT}`);
|
|
118
136
|
}
|
|
119
137
|
}
|
|
@@ -5,22 +5,30 @@ import { readOkfProject } from '../project/index.ts';
|
|
|
5
5
|
/**
|
|
6
6
|
* The structural coverage axes (`okf.coverage`): each `path` globs directories under the root, and
|
|
7
7
|
* every matched directory, minus the denylist, needs a concept at `<name>/<directory>.md`. A path that
|
|
8
|
-
* matches no directory
|
|
8
|
+
* matches no directory is a problem - an axis that covers nothing passes by accident.
|
|
9
9
|
*/
|
|
10
|
-
export const collectCoverageAxes = (): {
|
|
10
|
+
export const collectCoverageAxes = (): {
|
|
11
|
+
axes: { name: string; items: string[] }[];
|
|
12
|
+
problems: string[];
|
|
13
|
+
} => {
|
|
11
14
|
const project = readOkfProject();
|
|
15
|
+
const axes: { name: string; items: string[] }[] = [];
|
|
16
|
+
const problems: string[] = [];
|
|
12
17
|
|
|
13
|
-
|
|
18
|
+
for (const axis of project.coverage) {
|
|
14
19
|
const matched = [
|
|
15
20
|
...new Bun.Glob(axis.path).scanSync({ cwd: project.root, onlyFiles: false, dot: false }),
|
|
16
21
|
].filter(path => statSync(join(project.root, path)).isDirectory());
|
|
17
22
|
|
|
18
23
|
if (matched.length === 0) {
|
|
19
|
-
|
|
24
|
+
problems.push(`coverage: axis '${axis.name}' (${axis.path}) matches no directory`);
|
|
25
|
+
continue;
|
|
20
26
|
}
|
|
21
27
|
|
|
22
28
|
const items = matched.map(path => basename(path)).filter(name => !project.denylist.has(name));
|
|
23
29
|
|
|
24
|
-
|
|
25
|
-
}
|
|
30
|
+
axes.push({ name: axis.name, items: [...new Set(items)].sort() });
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
return { axes, problems };
|
|
26
34
|
};
|
|
@@ -44,8 +44,15 @@ export const coverage = async (): Promise<void> => {
|
|
|
44
44
|
);
|
|
45
45
|
};
|
|
46
46
|
|
|
47
|
+
const { axes, problems } = collectCoverageAxes();
|
|
48
|
+
|
|
49
|
+
// The report would count an axis that covers nothing as fully covered.
|
|
50
|
+
if (problems.length > 0) {
|
|
51
|
+
throw new Error(`okf: ${problems.join('; ')}`);
|
|
52
|
+
}
|
|
53
|
+
|
|
47
54
|
lines.push('STRUCTURAL (target 100% - one curated concept each)');
|
|
48
|
-
for (const axis of
|
|
55
|
+
for (const axis of axes) {
|
|
49
56
|
struct({
|
|
50
57
|
name: axis.name,
|
|
51
58
|
items: axis.items,
|
package/src/generate/command.ts
CHANGED
|
@@ -6,15 +6,22 @@ import { renderPages } from './pages.ts';
|
|
|
6
6
|
import { loadGeneration } from './registry.ts';
|
|
7
7
|
import { repoRelative } from '../source/index.ts';
|
|
8
8
|
|
|
9
|
+
/** The file as it is on disk, or undefined when it does not exist yet. */
|
|
10
|
+
const currentOf = (opts: { path: string }): string | undefined =>
|
|
11
|
+
existsSync(opts.path) ? readFileSync(opts.path, 'utf8') : undefined;
|
|
12
|
+
|
|
9
13
|
/**
|
|
10
14
|
* Writes exactly the configured regions and renderers, then the contents lists. Everything renders in
|
|
11
15
|
* memory first, so a failure writes nothing; the contents lists go last, so one `gen` is a fixed point
|
|
12
|
-
* - they see what the regions wrote, and skip every page a renderer owns.
|
|
16
|
+
* - they see what the regions wrote, and skip every page a renderer owns. Only a file whose content
|
|
17
|
+
* changed is written and named, so a run with nothing to do says so in one line.
|
|
13
18
|
*/
|
|
14
19
|
export const gen = async (): Promise<void> => {
|
|
15
20
|
const { renderers, regions } = await loadGeneration();
|
|
16
21
|
const regionWrites = regions.flatMap(region => {
|
|
17
|
-
|
|
22
|
+
const current = currentOf({ path: region.file });
|
|
23
|
+
|
|
24
|
+
if (current === undefined) {
|
|
18
25
|
console.warn(
|
|
19
26
|
`gen: skipped region '${region.id}' - ${repoRelative({ path: region.file })} does not exist yet`,
|
|
20
27
|
);
|
|
@@ -22,18 +29,17 @@ export const gen = async (): Promise<void> => {
|
|
|
22
29
|
return [];
|
|
23
30
|
}
|
|
24
31
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
},
|
|
34
|
-
];
|
|
32
|
+
const text = replaceRegion({
|
|
33
|
+
text: current,
|
|
34
|
+
id: region.id,
|
|
35
|
+
file: repoRelative({ path: region.file }),
|
|
36
|
+
body: region.render(),
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
return text === current ? [] : [{ region, text }];
|
|
35
40
|
});
|
|
36
|
-
const
|
|
41
|
+
const rendered = renderPages({ renderers });
|
|
42
|
+
const pages = rendered.filter(page => currentOf({ path: page.path }) !== page.content);
|
|
37
43
|
|
|
38
44
|
for (const { region, text } of regionWrites) {
|
|
39
45
|
writeFileSync(region.file, text);
|
|
@@ -47,7 +53,7 @@ export const gen = async (): Promise<void> => {
|
|
|
47
53
|
}
|
|
48
54
|
|
|
49
55
|
// Every project's long agent-read files carry a contents list, whatever it renders.
|
|
50
|
-
const contents = writeContents({ skip: new Set(
|
|
56
|
+
const contents = writeContents({ skip: new Set(rendered.map(page => page.path)) });
|
|
51
57
|
|
|
52
58
|
for (const file of contents) {
|
|
53
59
|
console.log(`gen: wrote the contents list of ${file}`);
|
|
@@ -55,5 +61,7 @@ export const gen = async (): Promise<void> => {
|
|
|
55
61
|
|
|
56
62
|
if (renderers.length === 0 && regions.length === 0 && contents.length === 0) {
|
|
57
63
|
console.log('gen: nothing configured - okf.renderers and okf.regions are empty');
|
|
64
|
+
} else if (regionWrites.length === 0 && pages.length === 0 && contents.length === 0) {
|
|
65
|
+
console.log('gen: up to date');
|
|
58
66
|
}
|
|
59
67
|
};
|
package/src/generate/contents.ts
CHANGED
|
@@ -7,36 +7,106 @@ import { markers } from './regions.ts';
|
|
|
7
7
|
*/
|
|
8
8
|
export const CONTENTS_MIN_LINES = 100;
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
const
|
|
10
|
+
/** The managed region okf writes the contents list into; no `okf.regions` entry may take it. */
|
|
11
|
+
export const CONTENTS_ID = 'contents';
|
|
12
12
|
const FRONTMATTER = /^---\n[\s\S]*?\n---\n/;
|
|
13
|
+
/** A fence line: up to three spaces, a run of three or more backticks or tildes, then the rest. */
|
|
14
|
+
const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
|
|
15
|
+
const HEADING = /^(#{1,6})[ \t]+(.+?)[ \t]*$/;
|
|
16
|
+
/** A link, inline or by reference: its text is what the heading shows. */
|
|
17
|
+
const LINK = /\[([^\]]*)\](?:\([^)]*\)|\[[^\]]*\])/g;
|
|
18
|
+
/** What GitHub strips from a heading for its anchor: punctuation but `-` and `_`, symbols, separators but the space. */
|
|
19
|
+
const ANCHOR_STRIPPED =
|
|
20
|
+
/(?![ -])(?!\p{Alphabetic})[\p{No}\p{Pd}\p{Ps}\p{Pe}\p{Pi}\p{Pf}\p{Po}\p{S}\p{C}\p{Z}]/gu;
|
|
13
21
|
|
|
14
|
-
/**
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
22
|
+
/**
|
|
23
|
+
* The lines outside code fences, by index. A fence closes only on its own character, at least as long
|
|
24
|
+
* as it opened, with nothing after it - so a ```` block can quote a ``` one (CommonMark).
|
|
25
|
+
*/
|
|
26
|
+
const unfencedLines = (opts: { lines: string[] }): { index: number; line: string }[] => {
|
|
27
|
+
const unfenced: { index: number; line: string }[] = [];
|
|
28
|
+
let open: string | undefined;
|
|
29
|
+
|
|
30
|
+
for (const [index, line] of opts.lines.entries()) {
|
|
31
|
+
const fence = FENCE.exec(line);
|
|
32
|
+
|
|
33
|
+
if (open !== undefined) {
|
|
34
|
+
if (
|
|
35
|
+
fence !== null &&
|
|
36
|
+
fence[1][0] === open[0] &&
|
|
37
|
+
fence[1].length >= open.length &&
|
|
38
|
+
fence[2].trim() === ''
|
|
39
|
+
) {
|
|
40
|
+
open = undefined;
|
|
41
|
+
}
|
|
18
42
|
|
|
19
|
-
for (const line of opts.text.split('\n')) {
|
|
20
|
-
if (FENCE.test(line)) {
|
|
21
|
-
fenced = !fenced;
|
|
22
43
|
continue;
|
|
23
44
|
}
|
|
24
45
|
|
|
25
|
-
|
|
26
|
-
|
|
46
|
+
// A backtick fence's info string holds no backtick; a line that does is inline code.
|
|
47
|
+
if (fence !== null && !(fence[1][0] === '`' && fence[2].includes('`'))) {
|
|
48
|
+
open = fence[1];
|
|
49
|
+
continue;
|
|
27
50
|
}
|
|
51
|
+
|
|
52
|
+
unfenced.push({ index, line });
|
|
28
53
|
}
|
|
29
54
|
|
|
30
|
-
return
|
|
55
|
+
return unfenced;
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
/** The lines a file has, as `wc -l` counts them: a final newline ends the last line, it opens none. */
|
|
59
|
+
const lineCountOf = (opts: { text: string }): number => {
|
|
60
|
+
const count = opts.text.split('\n').length;
|
|
61
|
+
|
|
62
|
+
return opts.text.endsWith('\n') ? count - 1 : count;
|
|
63
|
+
};
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* A heading's anchor as GitHub writes it (github-slugger): lower case; punctuation and symbols gone,
|
|
67
|
+
* `-` and `_` kept; each space a hyphen; a repeat of an earlier anchor takes `-1`, `-2`. `taken`
|
|
68
|
+
* holds the anchors the page has used so far, every heading level counted.
|
|
69
|
+
*/
|
|
70
|
+
const anchorOf = (opts: { text: string; taken: Map<string, number> }): string => {
|
|
71
|
+
const { taken } = opts;
|
|
72
|
+
const slug = opts.text.toLowerCase().replace(ANCHOR_STRIPPED, '').replace(/ /g, '-');
|
|
73
|
+
let anchor = slug;
|
|
74
|
+
|
|
75
|
+
while (taken.has(anchor)) {
|
|
76
|
+
const count = (taken.get(slug) ?? 0) + 1;
|
|
77
|
+
|
|
78
|
+
taken.set(slug, count);
|
|
79
|
+
anchor = `${slug}-${count}`;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
taken.set(anchor, 0);
|
|
83
|
+
|
|
84
|
+
return anchor;
|
|
31
85
|
};
|
|
32
86
|
|
|
33
|
-
/**
|
|
34
|
-
const
|
|
35
|
-
opts.
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
87
|
+
/** The `##` headings outside code fences and frontmatter, in order: the text each shows, its anchor. */
|
|
88
|
+
const headingsOf = (opts: { text: string }): { text: string; anchor: string }[] => {
|
|
89
|
+
const body = opts.text.slice(FRONTMATTER.exec(opts.text)?.[0].length ?? 0);
|
|
90
|
+
const taken = new Map<string, number>();
|
|
91
|
+
const headings: { text: string; anchor: string }[] = [];
|
|
92
|
+
|
|
93
|
+
for (const { line } of unfencedLines({ lines: body.split('\n') })) {
|
|
94
|
+
const heading = HEADING.exec(line);
|
|
95
|
+
|
|
96
|
+
if (heading === null) {
|
|
97
|
+
continue;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const text = heading[2].replace(LINK, '$1');
|
|
101
|
+
const anchor = anchorOf({ text, taken });
|
|
102
|
+
|
|
103
|
+
if (heading[1] === '##') {
|
|
104
|
+
headings.push({ text, anchor });
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
return headings;
|
|
109
|
+
};
|
|
40
110
|
|
|
41
111
|
/**
|
|
42
112
|
* The text with the contents region and the blank line after it taken out. A marker counts only on a
|
|
@@ -46,20 +116,10 @@ const anchorOf = (opts: { heading: string }): string =>
|
|
|
46
116
|
const withoutContents = (opts: { text: string }): string => {
|
|
47
117
|
const { start, end } = markers({ id: CONTENTS_ID });
|
|
48
118
|
const lines = opts.text.split('\n');
|
|
49
|
-
let fenced = false;
|
|
50
119
|
let startLine = -1;
|
|
51
120
|
let endLine = -1;
|
|
52
121
|
|
|
53
|
-
for (const
|
|
54
|
-
if (FENCE.test(line)) {
|
|
55
|
-
fenced = !fenced;
|
|
56
|
-
continue;
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
if (fenced) {
|
|
60
|
-
continue;
|
|
61
|
-
}
|
|
62
|
-
|
|
122
|
+
for (const { index, line } of unfencedLines({ lines })) {
|
|
63
123
|
if (startLine === -1 && line === start) {
|
|
64
124
|
startLine = index;
|
|
65
125
|
} else if (startLine !== -1 && line === end) {
|
|
@@ -103,12 +163,12 @@ export const withContents = (opts: { text: string }): string => {
|
|
|
103
163
|
const bare = withoutContents({ text: opts.text });
|
|
104
164
|
const headings = headingsOf({ text: bare });
|
|
105
165
|
|
|
106
|
-
if (bare
|
|
166
|
+
if (lineCountOf({ text: bare }) <= CONTENTS_MIN_LINES || headings.length === 0) {
|
|
107
167
|
return bare;
|
|
108
168
|
}
|
|
109
169
|
|
|
110
170
|
const { start, end } = markers({ id: CONTENTS_ID });
|
|
111
|
-
const list = headings.map(heading => `- [${heading}](#${
|
|
171
|
+
const list = headings.map(heading => `- [${heading.text}](#${heading.anchor})`).join('\n');
|
|
112
172
|
const block = `${start}\n**Contents**\n\n${list}\n${end}\n\n`;
|
|
113
173
|
const at = insertionPointOf({ text: bare });
|
|
114
174
|
|
package/src/generate/regions.ts
CHANGED
|
@@ -7,56 +7,57 @@ export const markers = (opts: { id: string }): { start: string; end: string } =>
|
|
|
7
7
|
};
|
|
8
8
|
};
|
|
9
9
|
|
|
10
|
-
/**
|
|
10
|
+
/**
|
|
11
|
+
* Locate a managed region, rejecting malformed or duplicated markers rather than corrupting the file.
|
|
12
|
+
* `file` is the host file as the person sees it, named in every error.
|
|
13
|
+
*/
|
|
11
14
|
export const locateRegion = (opts: {
|
|
12
15
|
text: string;
|
|
13
16
|
id: string;
|
|
17
|
+
file: string;
|
|
14
18
|
}): { start: string; end: string; startAt: number; endAt: number } => {
|
|
15
|
-
const { text, id } = opts;
|
|
19
|
+
const { text, id, file } = opts;
|
|
16
20
|
|
|
17
21
|
const { start, end } = markers({ id });
|
|
18
22
|
const startAt = text.indexOf(start);
|
|
19
23
|
const endAt = text.indexOf(end);
|
|
24
|
+
const region = `okf: ${file}: managed region '${id}'`;
|
|
20
25
|
|
|
21
26
|
if (startAt === -1 || endAt === -1) {
|
|
22
|
-
throw new Error(
|
|
27
|
+
throw new Error(`${region} is missing its markers - add ${start} and ${end}`);
|
|
23
28
|
}
|
|
24
29
|
|
|
25
30
|
if (text.indexOf(start, startAt + 1) !== -1) {
|
|
26
|
-
throw new Error(
|
|
31
|
+
throw new Error(`${region} is malformed - a duplicate start marker`);
|
|
27
32
|
}
|
|
28
33
|
|
|
29
34
|
if (text.indexOf(end, endAt + 1) !== -1) {
|
|
30
|
-
throw new Error(
|
|
35
|
+
throw new Error(`${region} is malformed - a duplicate end marker`);
|
|
31
36
|
}
|
|
32
37
|
|
|
33
38
|
if (startAt + start.length > endAt) {
|
|
34
|
-
throw new Error(
|
|
39
|
+
throw new Error(`${region} is malformed - the end marker precedes the start marker`);
|
|
35
40
|
}
|
|
36
41
|
|
|
37
42
|
return { start, end, startAt, endAt };
|
|
38
43
|
};
|
|
39
44
|
|
|
40
|
-
export const replaceRegion = (opts: {
|
|
41
|
-
|
|
45
|
+
export const replaceRegion = (opts: {
|
|
46
|
+
text: string;
|
|
47
|
+
id: string;
|
|
48
|
+
file: string;
|
|
49
|
+
body: string;
|
|
50
|
+
}): string => {
|
|
51
|
+
const { text, id, file, body } = opts;
|
|
42
52
|
|
|
43
|
-
const { start, startAt, endAt } = locateRegion({ text, id });
|
|
53
|
+
const { start, startAt, endAt } = locateRegion({ text, id, file });
|
|
44
54
|
|
|
45
55
|
return text.slice(0, startAt + start.length) + '\n' + body + '\n' + text.slice(endAt);
|
|
46
56
|
};
|
|
47
57
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
let located;
|
|
52
|
-
|
|
53
|
-
try {
|
|
54
|
-
located = locateRegion({ text, id });
|
|
55
|
-
} catch (error) {
|
|
56
|
-
console.warn(`okf: ${(error as Error).message}`);
|
|
57
|
-
|
|
58
|
-
return null;
|
|
59
|
-
}
|
|
58
|
+
/** The region's current body; throws like `locateRegion` when its markers are broken. */
|
|
59
|
+
export const extractRegion = (opts: { text: string; id: string; file: string }): string => {
|
|
60
|
+
const { start, startAt, endAt } = locateRegion(opts);
|
|
60
61
|
|
|
61
|
-
return text.slice(
|
|
62
|
+
return opts.text.slice(startAt + start.length, endAt).trim();
|
|
62
63
|
};
|
package/src/generate/registry.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
|
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { readOkfProject } from '../project/index.ts';
|
|
4
4
|
import type { IOkfRendererEntry } from '../project/index.ts';
|
|
5
|
+
import { CONTENTS_ID } from './contents.ts';
|
|
5
6
|
import { createRenderContext } from './define.ts';
|
|
6
7
|
import type { IRenderContext, IRenderer } from './define.ts';
|
|
7
8
|
import { BUILT_IN_RENDERERS } from './renderers.ts';
|
|
@@ -78,6 +79,12 @@ const loadRenderer = async (opts: {
|
|
|
78
79
|
entry: IOkfRendererEntry;
|
|
79
80
|
}): Promise<ILoadedRenderer> => {
|
|
80
81
|
const { entry } = opts;
|
|
82
|
+
|
|
83
|
+
// Allowed - a project may own a built-in's output - but never silent.
|
|
84
|
+
if (entry.module !== undefined && Object.hasOwn(BUILT_IN_RENDERERS, entry.id)) {
|
|
85
|
+
console.warn(`okf: module '${entry.id}' replaces the built-in renderer`);
|
|
86
|
+
}
|
|
87
|
+
|
|
81
88
|
const renderer =
|
|
82
89
|
entry.module === undefined
|
|
83
90
|
? builtInRenderer({ id: entry.id })
|
|
@@ -106,6 +113,12 @@ export const loadGeneration = async (): Promise<{
|
|
|
106
113
|
}
|
|
107
114
|
|
|
108
115
|
const regions = project.regions.map(region => {
|
|
116
|
+
if (region.id === CONTENTS_ID) {
|
|
117
|
+
throw new Error(
|
|
118
|
+
`okf: region id '${CONTENTS_ID}' is reserved for the contents list okf writes - rename the region`,
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
|
|
109
122
|
const loaded = renderers.find(candidate => candidate.renderer.id === region.renderer) ?? {
|
|
110
123
|
renderer: builtInRenderer({ id: region.renderer }),
|
|
111
124
|
context: createRenderContext({ options: {} }),
|
package/src/project/reader.ts
CHANGED
|
@@ -99,6 +99,17 @@ const coverageOf = (opts: { value: unknown }): { name: string; path: string }[]
|
|
|
99
99
|
: [];
|
|
100
100
|
});
|
|
101
101
|
|
|
102
|
+
/** The handoff, parsed: only `vulcan x` writes it, so anything else is okf run by hand. */
|
|
103
|
+
const parsedOf = (opts: { text: string }): unknown => {
|
|
104
|
+
try {
|
|
105
|
+
return JSON.parse(opts.text);
|
|
106
|
+
} catch (error) {
|
|
107
|
+
throw new Error('okf: VULCAN_CONFIG is not valid JSON - run okf through `vulcan x`', {
|
|
108
|
+
cause: error,
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
};
|
|
112
|
+
|
|
102
113
|
/** The last handoff read and what it gave: okf reads its project once per process. */
|
|
103
114
|
let cached: { text: string; root: string; project: IOkfProject } | undefined;
|
|
104
115
|
|
|
@@ -111,16 +122,14 @@ export const readOkfProject = (): IOkfProject => {
|
|
|
111
122
|
const root = process.env[OkfProjectConstants.ROOT_ENV];
|
|
112
123
|
|
|
113
124
|
if (text === undefined || root === undefined) {
|
|
114
|
-
throw new Error(
|
|
115
|
-
'okf: no project config - run through `vulcan x okf` (or add .configs/vulcan.config.ts)',
|
|
116
|
-
);
|
|
125
|
+
throw new Error('okf: no project config - run through `vulcan x okf`');
|
|
117
126
|
}
|
|
118
127
|
|
|
119
128
|
if (cached?.text === text && cached.root === root) {
|
|
120
129
|
return cached.project;
|
|
121
130
|
}
|
|
122
131
|
|
|
123
|
-
const config = recordOf({ value:
|
|
132
|
+
const config = recordOf({ value: parsedOf({ text }) });
|
|
124
133
|
const knowledge = recordOf({ value: config.knowledge });
|
|
125
134
|
const okf = recordOf({ value: config.okf });
|
|
126
135
|
const sections = recordOf({ value: okf.sections });
|
package/src/source/collectors.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
-
import { join, relative } from 'node:path';
|
|
2
|
+
import { isAbsolute, join, relative } from 'node:path';
|
|
3
3
|
import { readOkfProject } from '../project/index.ts';
|
|
4
4
|
import type { BindingClass, MakeTarget, SourceMapEntry } from './common/types.ts';
|
|
5
5
|
import { listDirs, listPackages, sourceFiles } from './scanner.ts';
|
|
@@ -100,10 +100,12 @@ export const collectMakefileTargets = (): MakeTarget[] => {
|
|
|
100
100
|
.filter(Boolean);
|
|
101
101
|
|
|
102
102
|
for (const makefile of makefiles) {
|
|
103
|
-
|
|
103
|
+
// make lists an include by the path it was given: relative to the root, or absolute.
|
|
104
|
+
const file = isAbsolute(makefile) ? makefile : projectPath({ path: makefile });
|
|
104
105
|
const makefileText = existsSync(file) ? readFileSync(file, 'utf8') : '';
|
|
105
106
|
|
|
106
|
-
|
|
107
|
+
// A `;` starts an inline recipe: a `##` after it is the recipe's, never the description.
|
|
108
|
+
for (const row of makefileText.matchAll(/^([a-z][\w-]*):[^#=;\n]*##\s*(.+)$/gm)) {
|
|
107
109
|
commented.set(row[1], row[2].trim());
|
|
108
110
|
}
|
|
109
111
|
}
|