@venizia/vulcan-okf 0.2.0-3 → 0.2.0-5
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 +2 -1
- package/package.json +4 -4
- package/src/check/house.ts +4 -3
- package/src/coverage-report/axes.ts +45 -5
- package/src/coverage-report/command.ts +7 -4
- package/src/generate/define.ts +3 -2
- package/src/generate/index.ts +0 -1
- package/src/generate/pages.ts +19 -15
- package/src/lib.ts +0 -11
- package/src/source/scanner.ts +0 -8
- package/src/generate/common/index.ts +0 -1
- package/src/generate/common/types.ts +0 -1
package/README.md
CHANGED
|
@@ -34,7 +34,8 @@ allowed; links inside code are examples, never edges. Files may use LF or CRLF l
|
|
|
34
34
|
|
|
35
35
|
Two mechanisms, both driven from source. Never hand-edit either.
|
|
36
36
|
|
|
37
|
-
1. **Whole generated files** - each renderer in `okf.renderers` writes one page,
|
|
37
|
+
1. **Whole generated files** - each renderer in `okf.renderers` writes one page - or, when its
|
|
38
|
+
`render` returns an array, one page per entry - by default under
|
|
38
39
|
`reference/`, with `generated.by: process:okf-gen` (§5.2). No `generated.at`: a timestamp would
|
|
39
40
|
make every regeneration look like a change.
|
|
40
41
|
2. **Managed regions** - each `okf.regions` entry (`{ id, file, renderer }`) replaces the content
|
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-5",
|
|
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": {
|
|
@@ -43,8 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
"dependencies": {
|
|
45
45
|
"cytoscape": "^3.34.4",
|
|
46
|
-
"cytoscape-fcose": "^2.2.0"
|
|
47
|
-
"typescript": "^6.0.3"
|
|
46
|
+
"cytoscape-fcose": "^2.2.0"
|
|
48
47
|
},
|
|
49
48
|
"devDependencies": {
|
|
50
49
|
"@types/bun": "1.4.1",
|
|
@@ -53,7 +52,8 @@
|
|
|
53
52
|
"eslint": "10.10.0",
|
|
54
53
|
"oxfmt": "0.73.0",
|
|
55
54
|
"oxlint": "1.88.0",
|
|
56
|
-
"oxlint-tsgolint": "7.0.2004"
|
|
55
|
+
"oxlint-tsgolint": "7.0.2004",
|
|
56
|
+
"typescript": "^6.0.3"
|
|
57
57
|
},
|
|
58
58
|
"sideEffects": false
|
|
59
59
|
}
|
package/src/check/house.ts
CHANGED
|
@@ -5,7 +5,7 @@ import { readOkfProject } from '../project/index.ts';
|
|
|
5
5
|
import { loadConcepts, stripCode } from '../lib.ts';
|
|
6
6
|
import type { Concept } from '../lib.ts';
|
|
7
7
|
import type { IBundleFile } from '../spec/index.ts';
|
|
8
|
-
import { collectCoverageAxes } from '../coverage-report/axes.ts';
|
|
8
|
+
import { collectCoverageAxes, isItemCovered, resourceKeysOf } from '../coverage-report/axes.ts';
|
|
9
9
|
import { collectContentsProblems } from '../generate/contents-files.ts';
|
|
10
10
|
import { collectChangelogProblems } from './changelogs.ts';
|
|
11
11
|
import { extractRegion, renderPages } from '../generate/index.ts';
|
|
@@ -91,7 +91,8 @@ export const collectHouseProblems = (opts: {
|
|
|
91
91
|
}
|
|
92
92
|
}
|
|
93
93
|
|
|
94
|
-
const
|
|
94
|
+
const filePaths = new Set(opts.files.map(file => `/${file.path.replace(/\.md$/, '')}`));
|
|
95
|
+
const resources = resourceKeysOf({ concepts });
|
|
95
96
|
|
|
96
97
|
const { axes, problems: axisProblems } = collectCoverageAxes();
|
|
97
98
|
|
|
@@ -101,7 +102,7 @@ export const collectHouseProblems = (opts: {
|
|
|
101
102
|
const section = axis.name;
|
|
102
103
|
|
|
103
104
|
for (const name of axis.items) {
|
|
104
|
-
if (!
|
|
105
|
+
if (!isItemCovered({ axis, item: name, ids: filePaths, resources })) {
|
|
105
106
|
problems.push(`coverage: ${section}/${name} has no concept (${section}/${name}.md)`);
|
|
106
107
|
}
|
|
107
108
|
}
|
|
@@ -2,17 +2,52 @@ import { statSync } from 'node:fs';
|
|
|
2
2
|
import { basename, join } from 'node:path';
|
|
3
3
|
import { readOkfProject } from '../project/index.ts';
|
|
4
4
|
|
|
5
|
+
export interface ICoverageAxis {
|
|
6
|
+
name: string;
|
|
7
|
+
items: string[];
|
|
8
|
+
/** Each item's directory from the project root. */
|
|
9
|
+
paths: Record<string, string>;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/** A `resource` as a key: no leading `./`, no trailing slash. */
|
|
13
|
+
const resourceKeyOf = (opts: { value: string }): string =>
|
|
14
|
+
opts.value.replace(/^\.\//, '').replace(/\/+$/, '');
|
|
15
|
+
|
|
16
|
+
/** The `resource` of every concept, as keys for `isItemCovered`; reserved files (index, log) cover nothing. */
|
|
17
|
+
export const resourceKeysOf = (opts: {
|
|
18
|
+
concepts: { resource: string; reserved: boolean }[];
|
|
19
|
+
}): Set<string> =>
|
|
20
|
+
new Set(
|
|
21
|
+
opts.concepts
|
|
22
|
+
.filter(concept => !concept.reserved && concept.resource !== '')
|
|
23
|
+
.map(concept => resourceKeyOf({ value: concept.resource })),
|
|
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);
|
|
38
|
+
|
|
5
39
|
/**
|
|
6
40
|
* The structural coverage axes (`okf.coverage`): each `path` globs directories under the root, and
|
|
7
|
-
* every matched directory, minus the denylist, needs a concept at `<name>/<directory>.md
|
|
41
|
+
* every matched directory, minus the denylist, needs a concept at `<name>/<directory>.md` - or any
|
|
42
|
+
* concept whose frontmatter `resource` is the directory (`paths` maps each item to it). A path that
|
|
8
43
|
* matches no directory is a problem - an axis that covers nothing passes by accident.
|
|
9
44
|
*/
|
|
10
45
|
export const collectCoverageAxes = (): {
|
|
11
|
-
axes:
|
|
46
|
+
axes: ICoverageAxis[];
|
|
12
47
|
problems: string[];
|
|
13
48
|
} => {
|
|
14
49
|
const project = readOkfProject();
|
|
15
|
-
const axes:
|
|
50
|
+
const axes: ICoverageAxis[] = [];
|
|
16
51
|
const problems: string[] = [];
|
|
17
52
|
|
|
18
53
|
for (const axis of project.coverage) {
|
|
@@ -25,9 +60,14 @@ export const collectCoverageAxes = (): {
|
|
|
25
60
|
continue;
|
|
26
61
|
}
|
|
27
62
|
|
|
28
|
-
const
|
|
63
|
+
const kept = matched.filter(path => !project.denylist.has(basename(path)));
|
|
64
|
+
const items = [...new Set(kept.map(path => basename(path)))].sort();
|
|
29
65
|
|
|
30
|
-
axes.push({
|
|
66
|
+
axes.push({
|
|
67
|
+
name: axis.name,
|
|
68
|
+
items,
|
|
69
|
+
paths: Object.fromEntries(kept.map(path => [basename(path), path])),
|
|
70
|
+
});
|
|
31
71
|
}
|
|
32
72
|
|
|
33
73
|
return { axes, problems };
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { loadGeneration } from '../generate/index.ts';
|
|
2
2
|
import { loadConceptsOrExit } from '../lib.ts';
|
|
3
3
|
import { packageDirs } from '../source/index.ts';
|
|
4
|
-
import { collectCoverageAxes } from './axes.ts';
|
|
4
|
+
import { collectCoverageAxes, isItemCovered, resourceKeysOf } from './axes.ts';
|
|
5
5
|
|
|
6
6
|
// --- coverage ---
|
|
7
7
|
|
|
@@ -18,6 +18,7 @@ export const coverage = async (): Promise<void> => {
|
|
|
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
22
|
const lines: string[] = [];
|
|
22
23
|
let structCovered = 0;
|
|
23
24
|
let structTotal = 0;
|
|
@@ -56,7 +57,7 @@ export const coverage = async (): Promise<void> => {
|
|
|
56
57
|
struct({
|
|
57
58
|
name: axis.name,
|
|
58
59
|
items: axis.items,
|
|
59
|
-
covered: item =>
|
|
60
|
+
covered: item => isItemCovered({ axis, item, ids, resources }),
|
|
60
61
|
});
|
|
61
62
|
}
|
|
62
63
|
|
|
@@ -77,12 +78,14 @@ export const coverage = async (): Promise<void> => {
|
|
|
77
78
|
|
|
78
79
|
const facts = renderer.collect({ context });
|
|
79
80
|
const row = renderer.coverage({ facts });
|
|
80
|
-
const
|
|
81
|
+
const rendered = renderer.render?.({ context, facts });
|
|
82
|
+
const paths = rendered === undefined ? [] : [rendered].flat().map(file => file.path);
|
|
81
83
|
|
|
82
84
|
ref({
|
|
83
85
|
name: row.name,
|
|
84
86
|
count: row.count,
|
|
85
|
-
generated:
|
|
87
|
+
generated:
|
|
88
|
+
paths.length > 0 && paths.every(path => hasId({ id: '/' + path.replace(/\.md$/, '') })),
|
|
86
89
|
});
|
|
87
90
|
}
|
|
88
91
|
|
package/src/generate/define.ts
CHANGED
|
@@ -36,12 +36,13 @@ export interface IRenderedFile {
|
|
|
36
36
|
/**
|
|
37
37
|
* A renderer: `collect` is the one extraction of its facts; `render` (a whole file), `region` (a
|
|
38
38
|
* managed region) and `coverage` (the report's reference row) all read those facts, so a table and
|
|
39
|
-
* its count can never disagree.
|
|
39
|
+
* its count can never disagree. `render` returns one file or a list of them - a renderer may own any
|
|
40
|
+
* number of pages.
|
|
40
41
|
*/
|
|
41
42
|
export interface IRenderer<TFacts = unknown> {
|
|
42
43
|
id: string;
|
|
43
44
|
collect(opts: { context: IRenderContext }): TFacts;
|
|
44
|
-
render?(opts: { context: IRenderContext; facts: TFacts }): IRenderedFile;
|
|
45
|
+
render?(opts: { context: IRenderContext; facts: TFacts }): IRenderedFile | IRenderedFile[];
|
|
45
46
|
region?(opts: { context: IRenderContext; facts: TFacts }): string;
|
|
46
47
|
coverage?(opts: { facts: TFacts }): { name: string; count: number };
|
|
47
48
|
}
|
package/src/generate/index.ts
CHANGED
package/src/generate/pages.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { relative, resolve, sep } from 'node:path';
|
|
2
|
+
import type { IRenderedFile } from './define.ts';
|
|
2
3
|
import type { ILoadedRenderer } from './registry.ts';
|
|
3
4
|
|
|
4
5
|
/** One page a renderer owns, rendered in memory: `path` is absolute, inside the bundle. */
|
|
@@ -12,9 +13,10 @@ const messageOf = (error: unknown): string =>
|
|
|
12
13
|
error instanceof Error ? error.message : String(error);
|
|
13
14
|
|
|
14
15
|
/**
|
|
15
|
-
* Every renderer
|
|
16
|
-
* the bundle, or two renderers on one path stop the run with an
|
|
17
|
-
* never a partial write. `gen` writes these pages; `check`
|
|
16
|
+
* Every page of every renderer, rendered before anything is written: a renderer that throws, a path
|
|
17
|
+
* outside the bundle, or two pages (of two renderers, or of one) on one path stop the run with an
|
|
18
|
+
* `okf:` error naming the renderer - never a partial write. `gen` writes these pages; `check`
|
|
19
|
+
* compares them.
|
|
18
20
|
*/
|
|
19
21
|
export const renderPages = (opts: { renderers: ILoadedRenderer[] }): IRenderedPage[] => {
|
|
20
22
|
const pages: IRenderedPage[] = [];
|
|
@@ -24,7 +26,7 @@ export const renderPages = (opts: { renderers: ILoadedRenderer[] }): IRenderedPa
|
|
|
24
26
|
continue;
|
|
25
27
|
}
|
|
26
28
|
|
|
27
|
-
let rendered:
|
|
29
|
+
let rendered: IRenderedFile | IRenderedFile[];
|
|
28
30
|
|
|
29
31
|
try {
|
|
30
32
|
rendered = renderer.render({ context, facts: renderer.collect({ context }) });
|
|
@@ -34,21 +36,23 @@ export const renderPages = (opts: { renderers: ILoadedRenderer[] }): IRenderedPa
|
|
|
34
36
|
});
|
|
35
37
|
}
|
|
36
38
|
|
|
37
|
-
const
|
|
39
|
+
for (const file of Array.isArray(rendered) ? rendered : [rendered]) {
|
|
40
|
+
const path = resolve(context.bundle, file.path);
|
|
38
41
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
+
if (!path.startsWith(`${resolve(context.bundle)}${sep}`)) {
|
|
43
|
+
throw new Error(`okf: renderer '${renderer.id}' writes ${file.path}, outside the bundle`);
|
|
44
|
+
}
|
|
42
45
|
|
|
43
|
-
|
|
46
|
+
const owner = pages.find(page => page.path === path);
|
|
44
47
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
48
|
+
if (owner !== undefined) {
|
|
49
|
+
throw new Error(
|
|
50
|
+
`okf: renderers '${owner.id}' and '${renderer.id}' both write ${relative(resolve(context.bundle), path)}`,
|
|
51
|
+
);
|
|
52
|
+
}
|
|
50
53
|
|
|
51
|
-
|
|
54
|
+
pages.push({ id: renderer.id, path, content: file.content });
|
|
55
|
+
}
|
|
52
56
|
}
|
|
53
57
|
|
|
54
58
|
return pages;
|
package/src/lib.ts
CHANGED
|
@@ -178,14 +178,3 @@ export const loadConceptsOrExit = (): Concept[] => {
|
|
|
178
178
|
process.exit(1);
|
|
179
179
|
}
|
|
180
180
|
};
|
|
181
|
-
|
|
182
|
-
/** Normalize a user-supplied id to canonical form ("/packages/core-server"). */
|
|
183
|
-
export const normalizeId = (opts: { raw: string }): string => {
|
|
184
|
-
let id = opts.raw.trim().replace(/\.md$/, '');
|
|
185
|
-
|
|
186
|
-
if (!id.startsWith('/')) {
|
|
187
|
-
id = '/' + id;
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
return id;
|
|
191
|
-
};
|
package/src/source/scanner.ts
CHANGED
|
@@ -77,11 +77,3 @@ export const listPackages = (): { dir: string; path: string }[] => {
|
|
|
77
77
|
};
|
|
78
78
|
|
|
79
79
|
export const packageDirs = (): string[] => listPackages().map(entry => entry.dir);
|
|
80
|
-
|
|
81
|
-
export const exampleDirs = (): string[] => {
|
|
82
|
-
const project = readOkfProject();
|
|
83
|
-
|
|
84
|
-
return listDirs({ dir: join(project.root, 'examples') }).filter(
|
|
85
|
-
name => !project.denylist.has(name),
|
|
86
|
-
);
|
|
87
|
-
};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export * from './types.ts';
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export type GeneratedFile = { path: string; content: string };
|