@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 +2 -4
- package/package.json +2 -7
- package/src/check/house.ts +1 -1
- package/src/cli.ts +2 -3
- package/src/config.ts +1 -1
- package/src/lib.ts +3 -3
- package/src/project/common/constants.ts +0 -1
- package/src/project/common/types.ts +2 -2
- package/src/project/reader.ts +1 -21
- package/src/run.ts +2 -8
- package/src/source/collectors.ts +1 -1
- package/src/viz/builder.ts +0 -144
- package/src/viz/client/explorer.ts +0 -528
- package/src/viz/client/frame.ts +0 -17
- package/src/viz/client/html.ts +0 -9
- package/src/viz/client/main.ts +0 -71
- package/src/viz/client/markdown.ts +0 -162
- package/src/viz/client/strings.ts +0 -59
- package/src/viz/client/theme.ts +0 -126
- package/src/viz/common/constants.ts +0 -55
- package/src/viz/common/index.ts +0 -2
- package/src/viz/common/types.ts +0 -46
- package/src/viz/copy.ts +0 -55
- package/src/viz/index.ts +0 -1
- package/src/viz/template.html +0 -580
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @venizia/vulcan-okf
|
|
2
2
|
|
|
3
|
-
Generator, conformance gate
|
|
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-
|
|
4
|
-
"description": "VULCAN knowledge tooling: OKF v0.2 conformance check (plus --strict house rules), gen,
|
|
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",
|
package/src/check/house.ts
CHANGED
|
@@ -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().
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
80
|
-
*
|
|
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
|
-
|
|
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
|
}
|
package/src/project/reader.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
36
|
+
console.error('usage: vulcan x okf <check|gen|coverage>');
|
|
43
37
|
process.exit(2);
|
|
44
38
|
}
|
|
45
39
|
}
|
package/src/source/collectors.ts
CHANGED
package/src/viz/builder.ts
DELETED
|
@@ -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
|
-
};
|