@venizia/vulcan-okf 0.4.10-3 → 0.4.10-4

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
@@ -1,6 +1,6 @@
1
1
  # @venizia/vulcan-okf
2
2
 
3
- Generator, conformance gate, coverage report and graph explorer for a project's knowledge bundle at
3
+ Generator, conformance gate and coverage report for a project's knowledge bundle at
4
4
  `.agents/knowledge/`, in the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/open-knowledge-format)
5
5
  v0.2. Part of VULCAN; the bundle is served over MCP by `@venizia/vulcan-atlas`, not from here.
6
6
 
@@ -14,8 +14,7 @@ The tooling reads the project it runs in (the working directory).
14
14
  | `check` | Gate: OKF v0.2 conformance (spec §11). Errors fail; soft-guidance warnings print and never fail |
15
15
  | `check --strict` | `check` plus the house rules: every link resolves, docs style, structural coverage, freshness |
16
16
  | `gen` | Regenerate all source-derived content |
17
- | `coverage [--min <n>]` | Report the bundle against the source inventory; `--min` fails below `<n>` percent |
18
- | `viz` | Build the offline graph explorer, `.agents/knowledge/viz.html` |
17
+ | `coverage [--min <n>]` | Report the bundle against the source inventory; `--min` fails when the structural coverage is below `<n>` percent |
19
18
 
20
19
  ## OKF v0.2 conformance (`check`)
21
20
 
@@ -83,7 +82,6 @@ The [renderers reference](../../docs/wiki/content/references/okf/renderers.md) s
83
82
  | `src/coverage-report/` | `coverage`: the bundle against the source inventory |
84
83
  | `src/lib.ts` | bundle loader: frontmatter, links, concept model |
85
84
  | `src/spec/` | OKF v0.2 conformance - pure, never throws |
86
- | `src/viz/` | explorer: builder (Bun), typed browser client, template |
87
85
  | `src/project/` | reads the project config `vulcan x` hands okf - everything project-specific |
88
86
  | `src/config.ts` | constants that hold for every project: pruned directories, reserved files |
89
87
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@venizia/vulcan-okf",
3
- "version": "0.4.10-3",
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.",
3
+ "version": "0.4.10-4",
4
+ "description": "VULCAN knowledge tooling: OKF v0.2 conformance check (plus --strict house rules), gen, and coverage for a project's .agents/knowledge bundle. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/okf",
6
6
  "bugs": {
7
7
  "url": "https://github.com/VENIZIA-AI/vulcan/issues"
@@ -40,13 +40,8 @@
40
40
  "force-update": "sh ../../scripts/build/force-update.sh",
41
41
  "test": "bun test"
42
42
  },
43
- "dependencies": {
44
- "cytoscape": "^3.34.4",
45
- "cytoscape-fcose": "^2.2.0"
46
- },
47
43
  "devDependencies": {
48
44
  "@types/bun": "1.4.3",
49
- "@types/cytoscape-fcose": "2.2.5",
50
45
  "@venizia/dev-configs": "0.4.7-0",
51
46
  "eslint": "10.13.0",
52
47
  "oxlint": "1.89.0",
@@ -81,7 +81,7 @@ export class HouseCheck {
81
81
  for (const file of opts.files) {
82
82
  const prose = MarkdownText.stripCode({ text: file.text });
83
83
 
84
- for (const rule of HouseCheck.styleRules({ brand: OkfProject.read().viz.brand })) {
84
+ for (const rule of HouseCheck.styleRules({ brand: OkfProject.read().brand })) {
85
85
  const match = prose.match(rule.pattern);
86
86
 
87
87
  if (match) {
package/src/cli.ts CHANGED
@@ -9,14 +9,13 @@ class OkfCommands {
9
9
  static readonly CHECK = 'check';
10
10
  static readonly GEN = 'gen';
11
11
  static readonly COVERAGE = 'coverage';
12
- static readonly VIZ = 'viz';
13
- static readonly SCHEME_SET = new Set<string>([this.CHECK, this.GEN, this.COVERAGE, this.VIZ]);
12
+ static readonly SCHEME_SET = new Set<string>([this.CHECK, this.GEN, this.COVERAGE]);
14
13
  static isValid(value: string): boolean {
15
14
  return this.SCHEME_SET.has(value);
16
15
  }
17
16
  }
18
17
 
19
- const USAGE = 'usage: vulcan x okf <check|gen|coverage|viz>';
18
+ const USAGE = 'usage: vulcan x okf <check|gen|coverage>';
20
19
 
21
20
  const [command, ...rest] = process.argv.slice(2);
22
21
 
package/src/config.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
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)
3
+ * packages, renderers, regions, coverage axes, denylist, the brand)
4
4
  * comes from the project config `vulcan x` hands okf - see project/reader.ts.
5
5
  */
6
6
 
package/src/lib.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * lib.ts - shared loader/parser for the OKF knowledge bundle.
3
- * Used by the generator, the viz builder, and the MCP server.
3
+ * Used by the generator, the checks and the coverage report.
4
4
  *
5
5
  * Repo-specific paths and denylists live in ./config.ts.
6
6
  */
@@ -76,8 +76,8 @@ export class MarkdownText {
76
76
  * Strip fenced and inline code before scanning for links.
77
77
  *
78
78
  * A markdown link inside a code fence is an example, not a real edge: leaving it in
79
- * made `check` report broken links for illustrative snippets and made viz draw edges
80
- * that do not exist. Fences are replaced (not deleted) so nothing outside them shifts.
79
+ * made `check` report broken links for illustrative snippets.
80
+ * Fences are replaced (not deleted) so nothing outside them shifts.
81
81
  */
82
82
  static stripCode(opts: { text: string }): string {
83
83
  return opts.text
@@ -3,7 +3,6 @@ export class OkfProjectConstants {
3
3
  static readonly CONFIG_ENV = 'VULCAN_CONFIG';
4
4
  static readonly ROOT_ENV = 'VULCAN_PROJECT_ROOT';
5
5
  static readonly DEFAULT_BUNDLE = '.agents/knowledge';
6
- static readonly DEFAULT_VIZ_OUTPUT = '.agents/knowledge/viz.html';
7
6
  static readonly DEFAULT_TAG_PATTERN = '<dir>-v<version>';
8
7
  /** Agent-read files outside the bundle that get a contents list when they grow long. */
9
8
  static readonly DEFAULT_CONTENTS_FILES = ['AGENTS.md', '.agents/rules.md'];
@@ -34,9 +34,9 @@ export interface IOkfProject {
34
34
  packages: IOkfPackage[];
35
35
  renderers: IOkfRendererEntry[];
36
36
  regions: IOkfRegionEntry[];
37
- sections: { order: string[]; labels: Record<string, string> };
38
37
  /** `exclude`: globs from the root dropped from the axis; `denylist`: directory names dropped from this axis only. */
39
38
  coverage: { name: string; path: string; exclude: string[]; denylist: string[] }[];
40
39
  denylist: Set<string>;
41
- viz: { outputs: string[]; brand: string; copy?: Record<string, unknown> };
40
+ /** How the project's name is written in prose: `okf.brand`, else the root package name without scope, upper-cased. */
41
+ brand: string;
42
42
  }
@@ -156,18 +156,12 @@ export class OkfProject {
156
156
  const config = recordOf({ value: parsedOf({ text }) });
157
157
  const knowledge = recordOf({ value: config.knowledge });
158
158
  const okf = recordOf({ value: config.okf });
159
- const sections = recordOf({ value: okf.sections });
160
- const viz = recordOf({ value: okf.viz });
161
159
  const bundle = resolve(
162
160
  root,
163
161
  stringOf({ value: knowledge.bundle, fallback: OkfProjectConstants.DEFAULT_BUNDLE }),
164
162
  );
165
- const outputs = stringsOf({ value: viz.outputs });
166
163
  const changelogs = knowledge.changelogs;
167
164
  const atlas = recordOf({ value: config.atlas });
168
- const copy = RecordValue.isRecord({ value: viz.copy })
169
- ? recordOf({ value: viz.copy })
170
- : undefined;
171
165
 
172
166
  const project: IOkfProject = {
173
167
  root,
@@ -187,23 +181,9 @@ export class OkfProject {
187
181
  packages: packagesOf({ value: config.packages, root }),
188
182
  renderers: renderersOf({ value: okf.renderers }),
189
183
  regions: regionsOf({ value: okf.regions, bundle }),
190
- sections: {
191
- order: stringsOf({ value: sections.order }),
192
- labels: Object.fromEntries(
193
- Object.entries(recordOf({ value: sections.labels })).filter(
194
- (entry): entry is [string, string] => typeof entry[1] === 'string',
195
- ),
196
- ),
197
- },
198
184
  coverage: coverageOf({ value: okf.coverage }),
199
185
  denylist: new Set(stringsOf({ value: okf.denylist })),
200
- viz: {
201
- outputs: (outputs.length > 0 ? outputs : [OkfProjectConstants.DEFAULT_VIZ_OUTPUT]).map(
202
- (output) => resolve(root, output),
203
- ),
204
- brand: stringOf({ value: viz.brand, fallback: brandOf({ root }) }),
205
- ...(copy === undefined ? {} : { copy }),
206
- },
186
+ brand: stringOf({ value: okf.brand, fallback: brandOf({ root }) }),
207
187
  };
208
188
 
209
189
  cached = { text, root, project };
package/src/run.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env bun
2
2
  /**
3
- * The okf command runner: `cli.ts` spawns it with `gen | check [--strict] | coverage | viz`.
3
+ * The okf command runner: `cli.ts` spawns it with `gen | check [--strict] | coverage`.
4
4
  *
5
5
  * Source-derived content is either a whole generated file (reference/*) or lives inside a managed
6
6
  * region delimited by `<!-- okf:generated:<id> start -->` and `<!-- okf:generated:<id> end -->`.
@@ -10,7 +10,6 @@
10
10
  import { check } from './check/index.ts';
11
11
  import { coverage } from './coverage-report/index.ts';
12
12
  import { gen } from './generate/index.ts';
13
- import { buildViz } from './viz/index.ts';
14
13
 
15
14
  /** A project the user must fix (no config, a bad renderer module): its message, never a stack. */
16
15
  const isProjectError = (opts: { error: unknown }): opts is { error: Error } =>
@@ -33,13 +32,8 @@ const runCommand = async (opts: { command: string | undefined; argv: string[] })
33
32
  break;
34
33
  }
35
34
 
36
- case 'viz': {
37
- await buildViz();
38
- break;
39
- }
40
-
41
35
  default: {
42
- console.error('usage: vulcan x okf <check|gen|coverage|viz>');
36
+ console.error('usage: vulcan x okf <check|gen|coverage>');
43
37
  process.exit(2);
44
38
  }
45
39
  }
@@ -226,7 +226,7 @@ export class SourceCollector {
226
226
  description: firstSentence({
227
227
  text: SourceCollector.sanitizeProse({
228
228
  text: parsed.description ?? '',
229
- brand: OkfProject.read().viz.brand,
229
+ brand: OkfProject.read().brand,
230
230
  }),
231
231
  }),
232
232
  });
@@ -1,144 +0,0 @@
1
- import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
- import { dirname, join, relative } from 'node:path';
3
-
4
- import { OkfProject } from '../project/index.ts';
5
- import type { Concept } from '../lib.ts';
6
- import { ConceptLoader } from '../lib.ts';
7
- import { HtmlText } from './client/html.ts';
8
- import { VizTemplateTokens } from './common/index.ts';
9
- import { VizCopy } from './copy.ts';
10
- import type { IVizData, IVizEdge, IVizNode, IVizSection } from './common/index.ts';
11
-
12
- const TEMPLATE_FILE = join(import.meta.dir, 'template.html');
13
- const CLIENT_ENTRY = join(import.meta.dir, 'client', 'main.ts');
14
- const toSectionTitle = (opts: { key: string; labels: Record<string, string> }): string =>
15
- opts.labels[opts.key] ??
16
- opts.key.replace(
17
- /(^|-)([a-z])/g,
18
- (_, separator: string, letter: string) => `${separator ? ' ' : ''}${letter.toUpperCase()}`,
19
- );
20
-
21
- const extractSection = (opts: { id: string }): string => opts.id.split('/')[1] || 'overview';
22
-
23
- /** A `</script` inside an inline script ends the element early; `<\/` means the same to JS and JSON. */
24
- const escapeScriptClose = (opts: { text: string }): string =>
25
- opts.text.replace(/<\/(script)/gi, '<\\/$1');
26
-
27
- export class VizBuilder {
28
- static buildData(opts: { concepts: Concept[] }): IVizData {
29
- const concepts = opts.concepts.filter((concept) => !concept.reserved);
30
- const ids = new Set(concepts.map((concept) => concept.id));
31
-
32
- const nodes: IVizNode[] = concepts.map((concept) => ({
33
- id: concept.id,
34
- type: concept.type,
35
- title: concept.title,
36
- description: concept.description,
37
- resource: concept.resource,
38
- tags: concept.tags,
39
- body: concept.body,
40
- group: extractSection({ id: concept.id }),
41
- degree: 0,
42
- }));
43
- const nodeById = new Map(nodes.map((node) => [node.id, node]));
44
-
45
- const edges: IVizEdge[] = [];
46
- const seen = new Set<string>();
47
-
48
- for (const concept of concepts) {
49
- for (const target of concept.links) {
50
- const key = `${concept.id} ${target}`;
51
-
52
- if (target === concept.id || !ids.has(target) || seen.has(key)) {
53
- continue;
54
- }
55
-
56
- seen.add(key);
57
- edges.push({ source: concept.id, target });
58
-
59
- for (const end of [concept.id, target]) {
60
- const node = nodeById.get(end);
61
-
62
- if (node) {
63
- node.degree++;
64
- }
65
- }
66
- }
67
- }
68
-
69
- const project = OkfProject.read();
70
- const known = new Set(project.sections.order);
71
- const present = new Set(nodes.map((node) => node.group));
72
- const ordered = [
73
- ...project.sections.order.filter((section) => present.has(section)),
74
- ...[...present].filter((section) => !known.has(section)).sort(),
75
- ];
76
- const sections: IVizSection[] = ordered.map((key) => ({
77
- key,
78
- label: toSectionTitle({ key, labels: project.sections.labels }),
79
- count: nodes.filter((node) => node.group === key).length,
80
- }));
81
-
82
- return {
83
- brand: project.viz.brand,
84
- nodes,
85
- edges,
86
- sections,
87
- copy: VizCopy.resolve({ brand: project.viz.brand, copy: project.viz.copy }),
88
- };
89
- }
90
-
91
- /** Function replacers, so a `$&` or `$'` in the data is inserted literally. */
92
- static assembleHtml(opts: { template: string; data: IVizData; clientScript: string }): string {
93
- return opts.template
94
- .replaceAll(VizTemplateTokens.BRAND, () => HtmlText.escape({ text: opts.data.brand }))
95
- .replaceAll(VizTemplateTokens.DATA, () =>
96
- escapeScriptClose({ text: JSON.stringify(opts.data) }),
97
- )
98
- .replaceAll(VizTemplateTokens.CLIENT, () => escapeScriptClose({ text: opts.clientScript }));
99
- }
100
-
101
- static async bundleClient(): Promise<string> {
102
- const result = await Bun.build({
103
- entrypoints: [CLIENT_ENTRY],
104
- target: 'browser',
105
- format: 'iife',
106
- minify: true,
107
- });
108
- const [output] = result.outputs;
109
-
110
- if (!result.success || output === undefined) {
111
- const reasons = result.logs.map((log) => String(log)).join('\n');
112
-
113
- console.error(
114
- `[VizBuilder.bundleClient] failed to bundle ${relative(OkfProject.read().root, CLIENT_ENTRY)}\n${reasons}`,
115
- );
116
- process.exit(1);
117
- }
118
-
119
- return output.text();
120
- }
121
- }
122
-
123
- export const buildViz = async (): Promise<void> => {
124
- const data = VizBuilder.buildData({ concepts: ConceptLoader.loadOrExit() });
125
- const clientScript = await VizBuilder.bundleClient();
126
- const html = VizBuilder.assembleHtml({
127
- template: readFileSync(TEMPLATE_FILE, 'utf8'),
128
- data,
129
- clientScript,
130
- });
131
-
132
- const project = OkfProject.read();
133
-
134
- // The same page to every configured output (the bundle's copy, a wiki's public copy, ...).
135
- for (const out of project.viz.outputs) {
136
- mkdirSync(dirname(out), { recursive: true });
137
- writeFileSync(out, html);
138
-
139
- console.log(`viz: wrote ${relative(project.root, out)}`);
140
- }
141
- console.log(
142
- `viz: ${data.nodes.length} nodes, ${data.edges.length} edges, ${data.sections.length} sections`,
143
- );
144
- };