@venizia/vulcan-okf 0.2.0-4 → 0.2.0-6

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 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, by default under
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-4",
3
+ "version": "0.2.0-6",
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": {
@@ -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 paths = new Set(opts.files.map(file => file.path));
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 (!paths.has(`${section}/${name}.md`)) {
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`. A path that
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: { name: string; items: string[] }[];
46
+ axes: ICoverageAxis[];
12
47
  problems: string[];
13
48
  } => {
14
49
  const project = readOkfProject();
15
- const axes: { name: string; items: string[] }[] = [];
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 items = matched.map(path => basename(path)).filter(name => !project.denylist.has(name));
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({ name: axis.name, items: [...new Set(items)].sort() });
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 => hasId({ id: `/${axis.name}/${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 path = renderer.render?.({ context, facts }).path;
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: path !== undefined && hasId({ id: '/' + path.replace(/\.md$/, '') }),
87
+ generated:
88
+ paths.length > 0 && paths.every(path => hasId({ id: '/' + path.replace(/\.md$/, '') })),
86
89
  });
87
90
  }
88
91
 
@@ -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
  }
@@ -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's page, rendered before anything is written: a renderer that throws, a path outside
16
- * the bundle, or two renderers on one path stop the run with an `okf:` error naming the renderer -
17
- * never a partial write. `gen` writes these pages; `check` compares them.
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: { path: string; content: string };
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 path = resolve(context.bundle, rendered.path);
39
+ for (const file of Array.isArray(rendered) ? rendered : [rendered]) {
40
+ const path = resolve(context.bundle, file.path);
38
41
 
39
- if (!path.startsWith(`${resolve(context.bundle)}${sep}`)) {
40
- throw new Error(`okf: renderer '${renderer.id}' writes ${rendered.path}, outside the bundle`);
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
- const owner = pages.find(page => page.path === path);
46
+ const owner = pages.find(page => page.path === path);
44
47
 
45
- if (owner !== undefined) {
46
- throw new Error(
47
- `okf: renderers '${owner.id}' and '${renderer.id}' both write ${relative(resolve(context.bundle), path)}`,
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
- pages.push({ id: renderer.id, path, content: rendered.content });
54
+ pages.push({ id: renderer.id, path, content: file.content });
55
+ }
52
56
  }
53
57
 
54
58
  return pages;