@venizia/vulcan-okf 0.4.10-1 → 0.4.10-10
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 +3 -5
- 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/generate/contents.ts +1 -0
- package/src/generate/define.ts +14 -0
- package/src/index.ts +2 -0
- 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/spec/common/constants.ts +3 -0
- package/src/spec/common/types.ts +1 -0
- package/src/spec/conformance.ts +1 -0
- package/src/spec/frontmatter.ts +3 -0
- 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,12 +1,12 @@
|
|
|
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
|
|
|
7
7
|
## Commands
|
|
8
8
|
|
|
9
|
-
Run through the pinned `vulcan` CLI (`bun x vulcan x okf <command>`) or the project's make targets.
|
|
9
|
+
Run through the pinned `vulcan` CLI (`bun x --no-install vulcan x okf <command>`) or the project's make targets.
|
|
10
10
|
The tooling reads the project it runs in (the working directory).
|
|
11
11
|
|
|
12
12
|
| Command | What it does |
|
|
@@ -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-10",
|
|
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/generate/contents.ts
CHANGED
|
@@ -177,6 +177,7 @@ const insertionPointOf = (opts: { text: string }): number => {
|
|
|
177
177
|
return at + (/^\n*/.exec(opts.text.slice(at))?.[0].length ?? 0);
|
|
178
178
|
};
|
|
179
179
|
|
|
180
|
+
/** The contents list a long agent-read file carries; `vulcan sync` writes it into the `AGENTS.md` it rewrites. */
|
|
180
181
|
export class ContentsList {
|
|
181
182
|
/**
|
|
182
183
|
* The file as `okf gen` writes it: a contents list of its `##` headings near the top when it runs
|
package/src/generate/define.ts
CHANGED
|
@@ -5,7 +5,9 @@ import { SourceScanner } from '../source/index.ts';
|
|
|
5
5
|
|
|
6
6
|
/** Reading the project's source - every `dir` is relative to the project root. */
|
|
7
7
|
export interface IRenderSource {
|
|
8
|
+
/** The folders directly under `dir`, sorted, without the pruned ones (`node_modules`, `.git`, ...). */
|
|
8
9
|
listDirs(opts: { dir: string }): string[];
|
|
10
|
+
/** Every `.ts` file under `dir`, declaration files excluded, in path order; none when `dir` does not exist. */
|
|
9
11
|
sourceFiles(opts: { dir: string }): string[];
|
|
10
12
|
/** Exported classes named `<anything><suffix>`, abstract ones included, per configured dir. */
|
|
11
13
|
exportedClasses(opts: { dirs: string[]; suffix: string }): { dir: string; classes: string[] }[];
|
|
@@ -15,13 +17,19 @@ export interface IRenderSource {
|
|
|
15
17
|
|
|
16
18
|
/** The frame of a generated reference file. */
|
|
17
19
|
export interface IRenderPage {
|
|
20
|
+
/** The front matter of a generated file: `type: Reference`, the given fields, and the `generated` marker. */
|
|
18
21
|
header(opts: { title: string; description: string; resource: string; tags: string[] }): string;
|
|
22
|
+
/** The line under the front matter that says the file is generated and must not be edited; `seeAlso` is appended when not empty. */
|
|
19
23
|
note(opts: { seeAlso: string }): string;
|
|
20
24
|
}
|
|
21
25
|
|
|
26
|
+
/** What a renderer gets: the project, the okf config entry that names it, and the helpers to read source and to frame a page. */
|
|
22
27
|
export interface IRenderContext {
|
|
28
|
+
/** The absolute path of the project root. */
|
|
23
29
|
root: string;
|
|
30
|
+
/** The absolute path of the knowledge bundle. */
|
|
24
31
|
bundle: string;
|
|
32
|
+
/** The `options` of the `okf.renderers` entry that names this renderer; `{}` when it has none. */
|
|
25
33
|
options: Record<string, unknown>;
|
|
26
34
|
source: IRenderSource;
|
|
27
35
|
page: IRenderPage;
|
|
@@ -30,6 +38,7 @@ export interface IRenderContext {
|
|
|
30
38
|
/** `path` is relative to the bundle. */
|
|
31
39
|
export interface IRenderedFile {
|
|
32
40
|
path: string;
|
|
41
|
+
/** The whole text of the file. */
|
|
33
42
|
content: string;
|
|
34
43
|
}
|
|
35
44
|
|
|
@@ -40,10 +49,15 @@ export interface IRenderedFile {
|
|
|
40
49
|
* number of pages.
|
|
41
50
|
*/
|
|
42
51
|
export interface IRenderer<TFacts = unknown> {
|
|
52
|
+
/** The name the `okf.renderers` entry and the managed regions use for this renderer; a module must define the id its entry names. */
|
|
43
53
|
id: string;
|
|
54
|
+
/** Reads the project once and returns the facts that `render`, `region` and `coverage` all use. */
|
|
44
55
|
collect(opts: { context: IRenderContext }): TFacts;
|
|
56
|
+
/** The whole file (or files) this renderer owns, written under the bundle. */
|
|
45
57
|
render?(opts: { context: IRenderContext; facts: TFacts }): IRenderedFile | IRenderedFile[];
|
|
58
|
+
/** The text of one managed region, between its markers in a hand-written page. */
|
|
46
59
|
region?(opts: { context: IRenderContext; facts: TFacts }): string;
|
|
60
|
+
/** The row this renderer adds to the coverage report: what it counts and how many. */
|
|
47
61
|
coverage?(opts: { facts: TFacts }): { name: string; count: number };
|
|
48
62
|
}
|
|
49
63
|
|
package/src/index.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
/** The OKF v0.2 conformance layer: pure, never throws - the part of okf other tools build on. */
|
|
2
2
|
export * from './spec/index.ts';
|
|
3
3
|
|
|
4
|
+
export { ContentsList } from './generate/contents.ts';
|
|
5
|
+
|
|
4
6
|
/** The renderer API a project module builds on (`okf.renderers[].module`). */
|
|
5
7
|
export { defineRenderer } from './generate/define.ts';
|
|
6
8
|
export type {
|
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
|
@@ -15,6 +15,7 @@ export class ConceptStatuses {
|
|
|
15
15
|
}
|
|
16
16
|
}
|
|
17
17
|
|
|
18
|
+
/** How serious a conformance issue is: an `error` breaks OKF v0.2, a `warning` is soft guidance. */
|
|
18
19
|
export class IssueSeverities {
|
|
19
20
|
static readonly ERROR = 'error';
|
|
20
21
|
static readonly WARNING = 'warning';
|
|
@@ -24,6 +25,7 @@ export class IssueSeverities {
|
|
|
24
25
|
}
|
|
25
26
|
}
|
|
26
27
|
|
|
28
|
+
/** The two file names OKF v0.2 reserves in every folder of a bundle: `index.md` (a contents list) and `log.md` (a change log); neither is a concept. */
|
|
27
29
|
export class ReservedFiles {
|
|
28
30
|
static readonly INDEX = 'index.md';
|
|
29
31
|
static readonly LOG = 'log.md';
|
|
@@ -33,6 +35,7 @@ export class ReservedFiles {
|
|
|
33
35
|
}
|
|
34
36
|
}
|
|
35
37
|
|
|
38
|
+
/** Fixed names of the spec: the root index file and the `okf_version` key of its front matter. */
|
|
36
39
|
export class SpecConstants {
|
|
37
40
|
static readonly ROOT_INDEX = ReservedFiles.INDEX;
|
|
38
41
|
static readonly VERSION_KEY = 'okf_version';
|
package/src/spec/common/types.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { TConstValue } from '../../common/index.ts';
|
|
2
2
|
import type { IssueSeverities } from './constants.ts';
|
|
3
3
|
|
|
4
|
+
/** `error` or `warning`: a value of `IssueSeverities`. */
|
|
4
5
|
export type TIssueSeverity = TConstValue<typeof IssueSeverities>;
|
|
5
6
|
|
|
6
7
|
/** A markdown file of the bundle; `path` is relative to the bundle root, `/`-separated. */
|
package/src/spec/conformance.ts
CHANGED
|
@@ -301,6 +301,7 @@ const checkLog = (opts: { file: IBundleFile }): IConformanceIssue[] => {
|
|
|
301
301
|
return issues;
|
|
302
302
|
};
|
|
303
303
|
|
|
304
|
+
/** The OKF v0.2 conformance check of a whole bundle. */
|
|
304
305
|
export class BundleConformance {
|
|
305
306
|
/** OKF v0.2 conformance (§11) plus soft guidance. Never throws: every finding is an issue. */
|
|
306
307
|
static check(opts: { files: IBundleFile[] }): IConformanceIssue[] {
|
package/src/spec/frontmatter.ts
CHANGED
|
@@ -2,10 +2,13 @@ import { RecordValue } from '../common/record.ts';
|
|
|
2
2
|
|
|
3
3
|
const FRONTMATTER = /^---\n([\s\S]*?)\n---(?:\n|$)([\s\S]*)$/;
|
|
4
4
|
|
|
5
|
+
/** A parsed front matter block: a YAML mapping with string keys. */
|
|
5
6
|
export type TYamlMapping = Record<string, unknown>;
|
|
6
7
|
|
|
8
|
+
/** The result of parsing a front matter block: the mapping, or why it is not one. */
|
|
7
9
|
export type TParsedYaml = { ok: true; data: TYamlMapping } | { ok: false; reason: string };
|
|
8
10
|
|
|
11
|
+
/** Splits the YAML front matter from the body of a bundle file and parses it as a mapping (OKF v0.2 §4). */
|
|
9
12
|
export class OkfFrontmatter {
|
|
10
13
|
/** §4: the block between the first two `---` lines. Line endings are normalized, so CRLF files parse too. */
|
|
11
14
|
static split(opts: { text: string }): { yaml: string | undefined; body: string } {
|
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
|
-
};
|