@venizia/vulcan-okf 0.1.0-2 → 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 CHANGED
@@ -41,8 +41,14 @@ Two mechanisms, both driven from source. Never hand-edit either.
41
41
  `<!-- okf:generated:<id> start -->` and `<!-- okf:generated:<id> end -->` inside an otherwise
42
42
  hand-authored file.
43
43
 
44
- `reference/public-surface.md`, `symbols.json` and `releases.json` are generated by
45
- `@venizia/vulcan-atlas` (`vulcan x atlas surface|symbols|releases gen`), not by `gen`.
44
+ `reference/public-surface.md` is generated by `@venizia/vulcan-atlas` (`vulcan x atlas surface gen`),
45
+ not by `gen`; its `generated:` frontmatter tells `gen` to leave it whole. Long agent-read files get a
46
+ generated contents list near the top; a file with `generated:` frontmatter and the bundle's `log.md`
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`.
46
52
 
47
53
  ## Adding a renderer
48
54
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan-okf",
3
- "version": "0.1.0-2",
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": {
@@ -0,0 +1,126 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
3
+ import { join, relative } from 'node:path';
4
+ import { readOkfProject } from '../project/index.ts';
5
+ import type { IOkfProject } from '../project/index.ts';
6
+
7
+ const DATED_ENTRY = /^\d{4}-\d{2}-\d{2}-.*\.md$/;
8
+ const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
9
+ /** `'<npm name>@<version>'` - the name may be scoped, so the version is after the LAST `@`. */
10
+ const RELEASE_OVERRIDE = /^(.+)@([^@]+)$/;
11
+
12
+ type TRecord = Record<string, unknown>;
13
+
14
+ const isRecord = (opts: { value: unknown }): opts is { value: TRecord } =>
15
+ typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
16
+
17
+ const frontmatterOf = (opts: { text: string }): TRecord => {
18
+ const block = FRONTMATTER.exec(opts.text)?.[1];
19
+ const parsed = { value: block === undefined ? undefined : Bun.YAML.parse(block) };
20
+
21
+ return isRecord(parsed) ? parsed.value : {};
22
+ };
23
+
24
+ /** The tag a release override names, by the project's template; a `<date>` part matches any date. */
25
+ const tagPatternOf = (opts: { project: IOkfProject; dir: string; version: string }): RegExp => {
26
+ const escaped = opts.project.tagPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
27
+
28
+ return new RegExp(
29
+ `^${escaped
30
+ .replace(/<(?:dir|package)>/g, opts.dir)
31
+ .replace(/<version>/g, opts.version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
32
+ .replace(/<date>/g, '\\d{4}-\\d{2}-\\d{2}')}$`,
33
+ );
34
+ };
35
+
36
+ /** `git tag`, read once, only when an override needs it. */
37
+ const tagsOf = (opts: { root: string }): string[] => {
38
+ const result = spawnSync('git', ['tag', '--list'], { cwd: opts.root, encoding: 'utf8' });
39
+
40
+ return result.status === 0 ? (result.stdout ?? '').split('\n').filter(tag => tag.length > 0) : [];
41
+ };
42
+
43
+ /**
44
+ * Project Contract v1, C3: every dated changelog entry declares the packages it covers by npm name -
45
+ * atlas reads that list and never the prose. An optional `release: '<npm name>@<version>'` places an
46
+ * entry git would place wrong (a backfill); it must name a tag that exists.
47
+ */
48
+ export const collectChangelogProblems = (): string[] => {
49
+ const project = readOkfProject();
50
+ const directory = project.changelogs;
51
+
52
+ if (directory === undefined || !existsSync(directory)) {
53
+ return [];
54
+ }
55
+
56
+ const names = new Map(project.packages.map(entry => [entry.name, entry.dir]));
57
+ const problems: string[] = [];
58
+ let tags: string[] | undefined;
59
+
60
+ for (const file of readdirSync(directory)
61
+ .filter(name => DATED_ENTRY.test(name))
62
+ .sort()) {
63
+ const path = relative(project.root, join(directory, file));
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
+
76
+ // `packages: []` is a decision - an entry about no package, such as repository tooling. Only a
77
+ // missing list is undecided.
78
+ if (!Array.isArray(frontmatter.packages)) {
79
+ problems.push(
80
+ `changelog: ${path} declares no packages - add \`packages: [<npm name>, ...]\` (\`vulcan x atlas changelogs migrate\` fills it)`,
81
+ );
82
+ continue;
83
+ }
84
+
85
+ const declared: unknown[] = frontmatter.packages;
86
+
87
+ for (const name of declared) {
88
+ if (typeof name !== 'string' || !names.has(name)) {
89
+ problems.push(
90
+ `changelog: ${path} names '${String(name)}', not a declared package's npm name`,
91
+ );
92
+ }
93
+ }
94
+
95
+ if (typeof frontmatter.release !== 'string') {
96
+ continue;
97
+ }
98
+
99
+ const override = RELEASE_OVERRIDE.exec(frontmatter.release);
100
+ const dir = override === null ? undefined : names.get(override[1]);
101
+
102
+ if (override === null || dir === undefined) {
103
+ problems.push(
104
+ `changelog: ${path}: release '${frontmatter.release}' is not '<declared npm name>@<version>'`,
105
+ );
106
+ continue;
107
+ }
108
+
109
+ tags ??= tagsOf({ root: project.root });
110
+
111
+ const pattern = tagPatternOf({ project, dir, version: override[2] });
112
+
113
+ if (!tags.some(tag => pattern.test(tag))) {
114
+ const expected = project.tagPattern
115
+ .replace(/<(?:dir|package)>/g, dir)
116
+ .replace(/<version>/g, override[2])
117
+ .replace(/<date>/g, 'YYYY-MM-DD');
118
+
119
+ problems.push(
120
+ `changelog: ${path}: release '${frontmatter.release}' names no tag (${expected})`,
121
+ );
122
+ }
123
+ }
124
+
125
+ return problems;
126
+ };
@@ -1,22 +1,27 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { join, relative } from 'node:path';
3
- import { BUNDLE, RESERVED_FILES } from '../config.ts';
3
+ import { RESERVED_FILES } from '../config.ts';
4
+ import { readOkfProject } from '../project/index.ts';
4
5
  import { IssueSeverities, OkfVersions, checkBundle } from '../spec/index.ts';
5
6
  import type { IBundleFile, IConformanceIssue } from '../spec/index.ts';
7
+ import { loadGeneration } from '../generate/index.ts';
6
8
  import { collectHouseProblems } from './house.ts';
7
9
  import { repoRelative, walkFiles } from '../source/index.ts';
8
10
 
9
11
  export const readBundleFiles = (): IBundleFile[] =>
10
- walkFiles({ dir: BUNDLE })
12
+ walkFiles({ dir: readOkfProject().bundle })
11
13
  .filter(file => file.endsWith('.md'))
12
- .map(file => ({ path: relative(BUNDLE, file), text: readFileSync(file, 'utf8') }));
14
+ .map(file => ({
15
+ path: relative(readOkfProject().bundle, file),
16
+ text: readFileSync(file, 'utf8'),
17
+ }));
13
18
 
14
19
  export const formatIssue = (opts: { issue: IConformanceIssue }): string =>
15
- `${repoRelative({ path: join(BUNDLE, opts.issue.file) })}: ${opts.issue.rule} ${opts.issue.message}`;
20
+ `${repoRelative({ path: join(readOkfProject().bundle, opts.issue.file) })}: ${opts.issue.rule} ${opts.issue.message}`;
16
21
 
17
22
  /** The house rules on top of OKF conformance: links resolve, docs style, structural coverage, freshness. */
18
23
 
19
- export const check = (opts: { strict: boolean }): void => {
24
+ export const check = async (opts: { strict: boolean }): Promise<void> => {
20
25
  const files = readBundleFiles();
21
26
  const issues = checkBundle({ files });
22
27
  const warnings = issues.filter(issue => issue.severity === IssueSeverities.WARNING);
@@ -25,7 +30,7 @@ export const check = (opts: { strict: boolean }): void => {
25
30
  .map(issue => formatIssue({ issue }));
26
31
 
27
32
  if (opts.strict) {
28
- problems.push(...collectHouseProblems({ files }));
33
+ problems.push(...collectHouseProblems({ files, ...(await loadGeneration()) }));
29
34
  }
30
35
 
31
36
  if (warnings.length) {
@@ -1,11 +1,16 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import { BUNDLE, REGENERATE_HINT } from '../config.ts';
3
+ import { REGENERATE_HINT } from '../config.ts';
4
+ import { readOkfProject } from '../project/index.ts';
4
5
  import { loadConcepts, stripCode } from '../lib.ts';
5
6
  import type { Concept } from '../lib.ts';
6
7
  import type { IBundleFile } from '../spec/index.ts';
7
- import { REGIONS, RENDERERS, extractRegion } from '../generate/index.ts';
8
- import { exampleDirs, packageDirs, repoRelative } from '../source/index.ts';
8
+ import { collectCoverageAxes } from '../coverage-report/axes.ts';
9
+ import { collectContentsProblems } from '../generate/contents-files.ts';
10
+ import { collectChangelogProblems } from './changelogs.ts';
11
+ import { extractRegion, renderPages } from '../generate/index.ts';
12
+ import type { ILoadedRegion, ILoadedRenderer } from '../generate/index.ts';
13
+ import { brandSpelling, repoRelative } from '../source/index.ts';
9
14
 
10
15
  // --- docs style ---
11
16
 
@@ -13,10 +18,21 @@ import { exampleDirs, packageDirs, repoRelative } from '../source/index.ts';
13
18
  * Repo docs rules, enforced on prose (see check step 3). To write a forbidden literal - as the
14
19
  * concept defining these rules must - put it in a code span; `stripCode` removes those first.
15
20
  */
16
- export const STYLE_RULES: { pattern: RegExp; message: string }[] = [
17
- { pattern: /[—–]/, message: 'use a hyphen, not an em-dash or en-dash' },
18
- { pattern: /\bIgnis\b/, message: 'the brand is always written IGNIS' },
19
- ];
21
+ export const styleRules = (opts: { brand: string }): { pattern: RegExp; message: string }[] => {
22
+ const spelling = brandSpelling({ brand: opts.brand });
23
+
24
+ return [
25
+ { pattern: /[—–]/, message: 'use a hyphen, not an em-dash or en-dash' },
26
+ ...(spelling === undefined
27
+ ? []
28
+ : [
29
+ {
30
+ pattern: new RegExp(spelling.source),
31
+ message: `the brand is always written ${opts.brand}`,
32
+ },
33
+ ]),
34
+ ];
35
+ };
20
36
 
21
37
  // --- freshness ---
22
38
 
@@ -32,7 +48,11 @@ export const sameContent = (opts: { left: string; right: string }): boolean => {
32
48
  return normalize(opts.left) === normalize(opts.right);
33
49
  };
34
50
 
35
- export const collectHouseProblems = (opts: { files: IBundleFile[] }): string[] => {
51
+ export const collectHouseProblems = (opts: {
52
+ files: IBundleFile[];
53
+ renderers: ILoadedRenderer[];
54
+ regions: ILoadedRegion[];
55
+ }): string[] => {
36
56
  const problems: string[] = [];
37
57
 
38
58
  // A concept that fails to load is already reported by the spec layer; links need the loaded set.
@@ -60,12 +80,12 @@ export const collectHouseProblems = (opts: { files: IBundleFile[] }): string[] =
60
80
  for (const file of opts.files) {
61
81
  const prose = stripCode({ text: file.text });
62
82
 
63
- for (const rule of STYLE_RULES) {
83
+ for (const rule of styleRules({ brand: readOkfProject().viz.brand })) {
64
84
  const match = prose.match(rule.pattern);
65
85
 
66
86
  if (match) {
67
87
  problems.push(
68
- `${repoRelative({ path: join(BUNDLE, file.path) })}: ${rule.message} (found "${match[0]}")`,
88
+ `${repoRelative({ path: join(readOkfProject().bundle, file.path) })}: ${rule.message} (found "${match[0]}")`,
69
89
  );
70
90
  }
71
91
  }
@@ -73,18 +93,21 @@ export const collectHouseProblems = (opts: { files: IBundleFile[] }): string[] =
73
93
 
74
94
  const paths = new Set(opts.files.map(file => file.path));
75
95
 
76
- for (const [items, section] of [
77
- [packageDirs(), 'packages'],
78
- [exampleDirs(), 'examples'],
79
- ] as const) {
80
- for (const name of items) {
96
+ const { axes, problems: axisProblems } = collectCoverageAxes();
97
+
98
+ problems.push(...axisProblems);
99
+
100
+ for (const axis of axes) {
101
+ const section = axis.name;
102
+
103
+ for (const name of axis.items) {
81
104
  if (!paths.has(`${section}/${name}.md`)) {
82
105
  problems.push(`coverage: ${section}/${name} has no concept (${section}/${name}.md)`);
83
106
  }
84
107
  }
85
108
  }
86
109
 
87
- for (const region of REGIONS) {
110
+ for (const region of opts.regions) {
88
111
  if (!existsSync(region.file)) {
89
112
  problems.push(
90
113
  `freshness: region '${region.id}' host file missing (${repoRelative({ path: region.file })})`,
@@ -92,15 +115,30 @@ export const collectHouseProblems = (opts: { files: IBundleFile[] }): string[] =
92
115
  continue;
93
116
  }
94
117
 
95
- const actual = extractRegion({ text: readFileSync(region.file, 'utf8'), id: region.id });
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
+ }
96
133
 
97
- if (actual === null || !sameContent({ left: actual, right: region.render() })) {
134
+ if (!sameContent({ left: actual, right: region.render() })) {
98
135
  problems.push(`freshness: region '${region.id}' is stale - ${REGENERATE_HINT}`);
99
136
  }
100
137
  }
101
138
 
102
- for (const renderer of RENDERERS) {
103
- const { path, content } = renderer.render();
139
+ const pages = renderPages({ renderers: opts.renderers });
140
+
141
+ for (const { path, content } of pages) {
104
142
  const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
105
143
 
106
144
  if (!sameContent({ left: current, right: content })) {
@@ -108,6 +146,12 @@ export const collectHouseProblems = (opts: { files: IBundleFile[] }): string[] =
108
146
  }
109
147
  }
110
148
 
149
+ // C3: every dated changelog entry declares its packages by npm name.
150
+ problems.push(...collectChangelogProblems());
151
+
152
+ // A long agent-read file opens with its contents - an agent may read its first lines only.
153
+ problems.push(...collectContentsProblems({ skip: new Set(pages.map(page => page.path)) }));
154
+
111
155
  return problems;
112
156
  };
113
157
 
package/src/config.ts CHANGED
@@ -1,20 +1,8 @@
1
1
  /**
2
- * config.ts - the ONLY repo-specific configuration for the OKF knowledge tooling.
3
- *
4
- * Everything that knows the shape of THIS repository lives here: paths, denylists,
5
- * section order/labels, and the coverage axes. Porting the bundle to another repo
6
- * means editing this file; the scope folders, lib.ts and viz/ stay untouched.
7
- *
8
- * Renderers themselves are code, not config - they live in the RENDERERS registry in
9
- * generate/renderers.ts and read their paths from here.
2
+ * config.ts - okf's constants that hold for every project. Everything project-specific (paths,
3
+ * packages, renderers, regions, sections, coverage axes, denylist, the explorer's brand and copy)
4
+ * comes from the project config `vulcan x` hands okf - see project/reader.ts.
10
5
  */
11
- import { resolve } from 'node:path';
12
-
13
- import type { IVizCopy, TLocale } from './viz/common/index.ts';
14
-
15
- // The project the tooling reads: the directory it runs in, as every VULCAN tool.
16
- export const REPO = process.cwd();
17
- export const BUNDLE = resolve(REPO, '.agents/knowledge');
18
6
 
19
7
  /** Directories never walked when scanning source. */
20
8
  export const PRUNE_DIRS = new Set([
@@ -29,82 +17,8 @@ export const PRUNE_DIRS = new Set([
29
17
  '__tests__',
30
18
  ]);
31
19
 
32
- export const PATHS = {
33
- packages: resolve(REPO, 'packages'),
34
- examples: resolve(REPO, 'examples'),
35
- docs: resolve(REPO, 'docs/wiki'),
36
- coreComponents: resolve(REPO, 'packages/core-server/src/components'),
37
- coreBindings: resolve(REPO, 'packages/kernel/src/common/bindings.ts'),
38
- helpersModules: resolve(REPO, 'packages/helpers/src/modules'),
39
- helpersUtilities: resolve(REPO, 'packages/helpers/src/utilities'),
40
- makefile: resolve(REPO, 'Makefile'),
41
- } as const;
42
-
43
- /**
44
- * Scaffold or non-concept directories. Empty today - every packages/* and examples/*
45
- * dir is a real artifact that earns a concept. Add names here rather than special-casing
46
- * them in the renderers.
47
- */
48
- export const PACKAGE_DENYLIST = new Set<string>([]);
49
- export const EXAMPLE_DENYLIST = new Set<string>([]);
50
-
51
- /** Bundle sections, in display order (viz + index). Unknown sections sort in after these. */
52
- export const SECTION_ORDER = [
53
- 'overview',
54
- 'architecture',
55
- 'packages',
56
- 'conventions',
57
- 'process',
58
- 'examples',
59
- 'reference',
60
- ] as const;
61
-
62
- export const SECTION_LABELS: Record<string, string> = {
63
- overview: 'Overview',
64
- architecture: 'Architecture',
65
- packages: 'Packages',
66
- conventions: 'Conventions',
67
- process: 'Process',
68
- examples: 'Examples',
69
- reference: 'Reference',
70
- };
71
-
72
20
  /** Reserved OKF filenames that carry no `type:` frontmatter and are never counted as concepts. */
73
21
  export const RESERVED_FILES = new Set(['index.md', 'log.md']);
74
22
 
75
- /** The explorer's brand, shown in the page title and the top bar. */
76
- export const VIZ_BRAND = 'IGNIS';
77
-
78
- /** The explorer's project prose, per locale. Section keys match SECTION_ORDER. */
79
- export const VIZ_COPY: Record<TLocale, IVizCopy> = {
80
- en: {
81
- heading: 'Understand IGNIS, one concept at a time.',
82
- tagline:
83
- 'The IGNIS framework, end to end - packages, architecture, conventions, process and examples.',
84
- sectionDescriptions: {
85
- overview: 'Start here - what IGNIS is and how to work in it.',
86
- architecture: 'How the pieces fit: DI, lifecycle, repositories, and cross-cutting design.',
87
- packages: 'The published framework packages.',
88
- conventions: 'How the code is written - patterns, style, and gotchas.',
89
- process: 'How the team works - build, test, release, git.',
90
- examples: 'Runnable apps that exercise the framework.',
91
- reference: 'Look-ups - generated catalogs, glossary, key files.',
92
- },
93
- },
94
- vi: {
95
- heading: 'Hiểu IGNIS, từng khái niệm một.',
96
- tagline: 'Toàn bộ framework IGNIS - package, kiến trúc, quy ước, quy trình và ví dụ.',
97
- sectionDescriptions: {
98
- overview: 'Bắt đầu ở đây - IGNIS là gì và cách làm việc.',
99
- architecture: 'Cách các phần ghép lại: DI, vòng đời, repository, thiết kế xuyên suốt.',
100
- packages: 'Các package của framework.',
101
- conventions: 'Cách viết code - pattern, style, và các bẫy.',
102
- process: 'Cách team làm việc - build, test, release, git.',
103
- examples: 'Các app chạy được minh hoạ framework.',
104
- reference: 'Tra cứu - catalog sinh tự động, glossary, file quan trọng.',
105
- },
106
- },
107
- };
108
-
109
23
  /** What a stale check tells the person: the tool command works in any project, a make target may not exist. */
110
24
  export const REGENERATE_HINT = 'run `vulcan x okf gen`';
@@ -0,0 +1,34 @@
1
+ import { statSync } from 'node:fs';
2
+ import { basename, join } from 'node:path';
3
+ import { readOkfProject } from '../project/index.ts';
4
+
5
+ /**
6
+ * 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
8
+ * matches no directory is a problem - an axis that covers nothing passes by accident.
9
+ */
10
+ export const collectCoverageAxes = (): {
11
+ axes: { name: string; items: string[] }[];
12
+ problems: string[];
13
+ } => {
14
+ const project = readOkfProject();
15
+ const axes: { name: string; items: string[] }[] = [];
16
+ const problems: string[] = [];
17
+
18
+ for (const axis of project.coverage) {
19
+ const matched = [
20
+ ...new Bun.Glob(axis.path).scanSync({ cwd: project.root, onlyFiles: false, dot: false }),
21
+ ].filter(path => statSync(join(project.root, path)).isDirectory());
22
+
23
+ if (matched.length === 0) {
24
+ problems.push(`coverage: axis '${axis.name}' (${axis.path}) matches no directory`);
25
+ continue;
26
+ }
27
+
28
+ const items = matched.map(path => basename(path)).filter(name => !project.denylist.has(name));
29
+
30
+ axes.push({ name: axis.name, items: [...new Set(items)].sort() });
31
+ }
32
+
33
+ return { axes, problems };
34
+ };
@@ -1,13 +1,7 @@
1
+ import { loadGeneration } from '../generate/index.ts';
1
2
  import { loadConceptsOrExit } from '../lib.ts';
2
- import {
3
- collectBindingKeys,
4
- collectComponents,
5
- collectHelperModules,
6
- collectMakefileTargets,
7
- collectSourceMap,
8
- exampleDirs,
9
- packageDirs,
10
- } from '../source/index.ts';
3
+ import { packageDirs } from '../source/index.ts';
4
+ import { collectCoverageAxes } from './axes.ts';
11
5
 
12
6
  // --- coverage ---
13
7
 
@@ -19,7 +13,7 @@ export const pad = (opts: { value: string; width: number }): string => {
19
13
  return (opts.value + ' '.repeat(opts.width)).slice(0, opts.width);
20
14
  };
21
15
 
22
- export const coverage = (): void => {
16
+ export const coverage = async (): Promise<void> => {
23
17
  const concepts = loadConceptsOrExit().filter(concept => !concept.reserved);
24
18
  const ids = new Set(concepts.map(concept => concept.id));
25
19
 
@@ -50,17 +44,21 @@ export const coverage = (): void => {
50
44
  );
51
45
  };
52
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
+
53
54
  lines.push('STRUCTURAL (target 100% - one curated concept each)');
54
- struct({
55
- name: 'packages',
56
- items: packageDirs(),
57
- covered: name => hasId({ id: '/packages/' + name }),
58
- });
59
- struct({
60
- name: 'examples',
61
- items: exampleDirs(),
62
- covered: name => hasId({ id: '/examples/' + name }),
63
- });
55
+ for (const axis of axes) {
56
+ struct({
57
+ name: axis.name,
58
+ items: axis.items,
59
+ covered: item => hasId({ id: `/${axis.name}/${item}` }),
60
+ });
61
+ }
64
62
 
65
63
  // Reference axes - advisory; exhaustive coverage comes from generation.
66
64
  lines.push('', 'REFERENCE (advisory - generated)');
@@ -71,35 +69,22 @@ export const coverage = (): void => {
71
69
  );
72
70
  };
73
71
 
74
- const components = collectComponents();
75
- const helperModules = collectHelperModules();
76
- const bindingClasses = collectBindingKeys();
77
-
78
- ref({
79
- name: 'components',
80
- count: components.reduce((sum, entry) => sum + entry.classes.length, 0),
81
- generated: hasId({ id: '/reference/components' }),
82
- });
83
- ref({
84
- name: 'helper modules',
85
- count: helperModules.length,
86
- generated: hasId({ id: '/reference/helpers' }),
87
- });
88
- ref({
89
- name: 'binding keys',
90
- count: bindingClasses.reduce((sum, entry) => sum + entry.keys.length, 0),
91
- generated: hasId({ id: '/reference/binding-keys' }),
92
- });
93
- ref({
94
- name: 'make targets',
95
- count: collectMakefileTargets().length,
96
- generated: hasId({ id: '/reference/makefile-targets' }),
97
- });
98
- ref({
99
- name: 'source files',
100
- count: collectSourceMap().reduce((sum, entry) => sum + entry.total, 0),
101
- generated: hasId({ id: '/reference/source-map' }),
102
- });
72
+ // One row per configured renderer that reports one, from the same facts its table renders.
73
+ for (const { renderer, context } of (await loadGeneration()).renderers) {
74
+ if (renderer.coverage === undefined) {
75
+ continue;
76
+ }
77
+
78
+ const facts = renderer.collect({ context });
79
+ const row = renderer.coverage({ facts });
80
+ const path = renderer.render?.({ context, facts }).path;
81
+
82
+ ref({
83
+ name: row.name,
84
+ count: row.count,
85
+ generated: path !== undefined && hasId({ id: '/' + path.replace(/\.md$/, '') }),
86
+ });
87
+ }
103
88
 
104
89
  // Knowledge types (Diátaxis / arc42).
105
90
  const types: Record<string, number> = {};
@@ -1 +1,2 @@
1
+ export * from './axes.ts';
1
2
  export * from './command.ts';