@venizia/vulcan-okf 0.0.0-stage → 0.1.0-0
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/LICENSE.md +23 -0
- package/README.md +70 -2
- package/package.json +58 -4
- package/src/check/command.ts +54 -0
- package/src/check/house.ts +114 -0
- package/src/check/index.ts +2 -0
- package/src/cli.ts +32 -0
- package/src/config.ts +110 -0
- package/src/coverage-report/command.ts +161 -0
- package/src/coverage-report/index.ts +1 -0
- package/src/generate/command.ts +33 -0
- package/src/generate/common/index.ts +1 -0
- package/src/generate/common/types.ts +1 -0
- package/src/generate/index.ts +4 -0
- package/src/generate/regions.ts +62 -0
- package/src/generate/renderers.ts +216 -0
- package/src/index.ts +2 -0
- package/src/lib.ts +190 -0
- package/src/run.ts +45 -0
- package/src/source/collectors.ts +213 -0
- package/src/source/common/index.ts +1 -0
- package/src/source/common/types.ts +9 -0
- package/src/source/index.ts +3 -0
- package/src/source/scanner.ts +60 -0
- package/src/spec/common/constants.ts +44 -0
- package/src/spec/common/index.ts +2 -0
- package/src/spec/common/types.ts +18 -0
- package/src/spec/conformance.ts +322 -0
- package/src/spec/frontmatter.ts +39 -0
- package/src/spec/index.ts +3 -0
- package/src/viz/builder.ts +132 -0
- package/src/viz/client/explorer.ts +528 -0
- package/src/viz/client/frame.ts +15 -0
- package/src/viz/client/html.ts +5 -0
- package/src/viz/client/main.ts +71 -0
- package/src/viz/client/markdown.ts +158 -0
- package/src/viz/client/strings.ts +57 -0
- package/src/viz/client/theme.ts +124 -0
- package/src/viz/common/constants.ts +32 -0
- package/src/viz/common/index.ts +2 -0
- package/src/viz/common/types.ts +44 -0
- package/src/viz/index.ts +1 -0
- package/src/viz/template.html +140 -0
package/LICENSE.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# VULCAN License
|
|
2
|
+
|
|
3
|
+
## MIT License
|
|
4
|
+
|
|
5
|
+
Copyright (c) 2025 VENIZIA Ltd. Co.
|
|
6
|
+
|
|
7
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
8
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
9
|
+
in the Software without restriction, including without limitation the rights
|
|
10
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
11
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
12
|
+
furnished to do so, subject to the following conditions:
|
|
13
|
+
|
|
14
|
+
The above copyright notice and this permission notice shall be included in all
|
|
15
|
+
copies or substantial portions of the Software.
|
|
16
|
+
|
|
17
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
18
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
20
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
21
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
22
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
23
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,71 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @venizia/vulcan-okf
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Generator, conformance gate, coverage report and graph explorer for a project's knowledge bundle at
|
|
4
|
+
`.agents/knowledge/`, in the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/open-knowledge-format)
|
|
5
|
+
v0.2. Part of VULCAN; the bundle is served over MCP by `@venizia/vulcan-atlas`, not from here.
|
|
6
|
+
|
|
7
|
+
## Commands
|
|
8
|
+
|
|
9
|
+
Run through the pinned `vulcan` CLI (`bun x vulcan x okf <command>`) or the project's make targets.
|
|
10
|
+
The tooling reads the project it runs in (the working directory).
|
|
11
|
+
|
|
12
|
+
| Command | What it does |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `check` | Gate: OKF v0.2 conformance (spec §11). Errors fail; soft-guidance warnings print and never fail |
|
|
15
|
+
| `check --strict` | `check` plus the house rules: every link resolves, docs style, structural coverage, freshness |
|
|
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` |
|
|
19
|
+
|
|
20
|
+
## OKF v0.2 conformance (`check`)
|
|
21
|
+
|
|
22
|
+
Exactly the spec, never stricter:
|
|
23
|
+
|
|
24
|
+
- Every non-reserved `.md` file has a parseable YAML frontmatter block with a non-empty top-level `type` (§11.1, §11.2).
|
|
25
|
+
- `index.md` carries no frontmatter; the bundle-root one may carry `okf_version` alone (§8, §12).
|
|
26
|
+
- `log.md` date headings open with a real `YYYY-MM-DD`, newest first (§9). Text after the date is tolerated - the spec is silent on it.
|
|
27
|
+
- Never rejected (§11): unknown types, unknown keys, missing optional fields, broken links, missing `index.md`.
|
|
28
|
+
- Warnings (soft guidance): `status` outside draft/stable/deprecated (§5.4), timestamps that are not ISO 8601 datetimes with an offset (§5), a `sources` entry without `resource` (§5.1), actors that are not `<producer>/<version>`, `human:<id>` or `process:<id>` (§7), an older `okf_version` (§12).
|
|
29
|
+
|
|
30
|
+
Links are bundle-absolute (`/x.md`, recommended) or relative (`./x.md`, `../x.md`, `x.md`), anchors
|
|
31
|
+
allowed; links inside code are examples, never edges. Files may use LF or CRLF line endings.
|
|
32
|
+
|
|
33
|
+
## What is generated vs hand-authored
|
|
34
|
+
|
|
35
|
+
Two mechanisms, both driven from source. Never hand-edit either.
|
|
36
|
+
|
|
37
|
+
1. **Whole generated files** - the `RENDERERS` registry in `src/generate/renderers.ts` writes `reference/*.md`, each
|
|
38
|
+
with `generated.by: process:okf-gen` (§5.2). No `generated.at`: a timestamp would make every
|
|
39
|
+
regeneration look like a change.
|
|
40
|
+
2. **Managed regions** - the `REGIONS` registry replaces content between
|
|
41
|
+
`<!-- okf:generated:<id> start -->` and `<!-- okf:generated:<id> end -->` inside an otherwise
|
|
42
|
+
hand-authored file.
|
|
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`.
|
|
46
|
+
|
|
47
|
+
## Adding a renderer
|
|
48
|
+
|
|
49
|
+
1. Write a `collect*` function that extracts the fact from source.
|
|
50
|
+
**Use it for both the renderer and the coverage counter** - a second heuristic for the same fact
|
|
51
|
+
drifts, and the numbers disagree.
|
|
52
|
+
2. Write a `render*` returning `{ path, content }` and add it to `RENDERERS`.
|
|
53
|
+
3. Run `gen`, then `check --strict` twice: it must pass and be idempotent.
|
|
54
|
+
|
|
55
|
+
The renderers and coverage rows are IGNIS-specific today (`src/config.ts`); making them project
|
|
56
|
+
config is planned.
|
|
57
|
+
|
|
58
|
+
## Layout
|
|
59
|
+
|
|
60
|
+
| Path | Role |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `src/cli.ts` | `vulcan-okf` entry; spawns `src/run.ts`, the command runner |
|
|
63
|
+
| `src/index.ts` | the public API: the OKF v0.2 conformance layer |
|
|
64
|
+
| `src/source/` | source scanning and the shared fact collectors (one per fact, used by gen and coverage) |
|
|
65
|
+
| `src/generate/` | `gen`: managed regions and the `RENDERERS` / `REGIONS` registries |
|
|
66
|
+
| `src/check/` | `check`: OKF conformance, plus the house rules under `--strict` |
|
|
67
|
+
| `src/coverage-report/` | `coverage`: the bundle against the source inventory |
|
|
68
|
+
| `src/lib.ts` | bundle loader: frontmatter, links, concept model |
|
|
69
|
+
| `src/spec/` | OKF v0.2 conformance - pure, never throws |
|
|
70
|
+
| `src/viz/` | explorer: builder (Bun), typed browser client, template |
|
|
71
|
+
| `src/config.ts` | the only project-specific file: paths, section order, explorer copy |
|
package/package.json
CHANGED
|
@@ -1,6 +1,60 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan-okf",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0-0",
|
|
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
|
+
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/okf",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/VENIZIA-AI/vulcan.git",
|
|
9
|
+
"directory": "packages/okf"
|
|
10
|
+
},
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/VENIZIA-AI/vulcan/issues"
|
|
13
|
+
},
|
|
14
|
+
"author": {
|
|
15
|
+
"name": "VENIZIA AI Developer",
|
|
16
|
+
"email": "developer@venizia.ai",
|
|
17
|
+
"url": "https://venizia.ai"
|
|
18
|
+
},
|
|
19
|
+
"license": "MIT",
|
|
20
|
+
"type": "module",
|
|
21
|
+
"engines": {
|
|
22
|
+
"bun": ">=1.4"
|
|
23
|
+
},
|
|
24
|
+
"bin": {
|
|
25
|
+
"vulcan-okf": "./src/cli.ts"
|
|
26
|
+
},
|
|
27
|
+
"exports": {
|
|
28
|
+
".": "./src/index.ts",
|
|
29
|
+
"./package.json": "./package.json"
|
|
30
|
+
},
|
|
31
|
+
"files": [
|
|
32
|
+
"README.md",
|
|
33
|
+
"LICENSE.md",
|
|
34
|
+
"src",
|
|
35
|
+
"!src/__tests__"
|
|
36
|
+
],
|
|
37
|
+
"publishConfig": {
|
|
38
|
+
"access": "public"
|
|
39
|
+
},
|
|
40
|
+
"scripts": {
|
|
41
|
+
"force-update": "sh ../../scripts/force-update.sh",
|
|
42
|
+
"test": "NODE_ENV=test bun test --env-file=.env.test"
|
|
43
|
+
},
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"cytoscape": "^3.34.4",
|
|
46
|
+
"cytoscape-fcose": "^2.2.0",
|
|
47
|
+
"typescript": "^6.0.3"
|
|
48
|
+
},
|
|
49
|
+
"devDependencies": {
|
|
50
|
+
"@types/bun": "1.4.1",
|
|
51
|
+
"@types/cytoscape-fcose": "2.2.5",
|
|
52
|
+
"@venizia/dev-configs": "0.3.1-0",
|
|
53
|
+
"@venizia/ignis-helpers": "^0.2.2-5",
|
|
54
|
+
"eslint": "10.10.0",
|
|
55
|
+
"oxfmt": "0.73.0",
|
|
56
|
+
"oxlint": "1.88.0",
|
|
57
|
+
"oxlint-tsgolint": "7.0.2004"
|
|
58
|
+
},
|
|
59
|
+
"sideEffects": false
|
|
60
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { join, relative } from 'node:path';
|
|
3
|
+
import { BUNDLE, RESERVED_FILES } from '../config.ts';
|
|
4
|
+
import { IssueSeverities, OkfVersions, checkBundle } from '../spec/index.ts';
|
|
5
|
+
import type { IBundleFile, IConformanceIssue } from '../spec/index.ts';
|
|
6
|
+
import { collectHouseProblems } from './house.ts';
|
|
7
|
+
import { repoRelative, walkFiles } from '../source/index.ts';
|
|
8
|
+
|
|
9
|
+
export const readBundleFiles = (): IBundleFile[] =>
|
|
10
|
+
walkFiles({ dir: BUNDLE })
|
|
11
|
+
.filter(file => file.endsWith('.md'))
|
|
12
|
+
.map(file => ({ path: relative(BUNDLE, file), text: readFileSync(file, 'utf8') }));
|
|
13
|
+
|
|
14
|
+
export const formatIssue = (opts: { issue: IConformanceIssue }): string =>
|
|
15
|
+
`${repoRelative({ path: join(BUNDLE, opts.issue.file) })}: ${opts.issue.rule} ${opts.issue.message}`;
|
|
16
|
+
|
|
17
|
+
/** The house rules on top of OKF conformance: links resolve, docs style, structural coverage, freshness. */
|
|
18
|
+
|
|
19
|
+
export const check = (opts: { strict: boolean }): void => {
|
|
20
|
+
const files = readBundleFiles();
|
|
21
|
+
const issues = checkBundle({ files });
|
|
22
|
+
const warnings = issues.filter(issue => issue.severity === IssueSeverities.WARNING);
|
|
23
|
+
const problems = issues
|
|
24
|
+
.filter(issue => issue.severity === IssueSeverities.ERROR)
|
|
25
|
+
.map(issue => formatIssue({ issue }));
|
|
26
|
+
|
|
27
|
+
if (opts.strict) {
|
|
28
|
+
problems.push(...collectHouseProblems({ files }));
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
if (warnings.length) {
|
|
32
|
+
console.error(
|
|
33
|
+
`check: ${warnings.length} warning(s):\n` +
|
|
34
|
+
warnings.map(issue => ' - ' + formatIssue({ issue })).join('\n'),
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
if (problems.length) {
|
|
39
|
+
console.error(
|
|
40
|
+
`check: ${problems.length} problem(s):\n` +
|
|
41
|
+
problems.map(problem => ' - ' + problem).join('\n'),
|
|
42
|
+
);
|
|
43
|
+
process.exit(1);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const conceptCount = files.filter(
|
|
47
|
+
file => !RESERVED_FILES.has(file.path.split('/').pop() ?? ''),
|
|
48
|
+
).length;
|
|
49
|
+
const scope = opts.strict
|
|
50
|
+
? `OKF v${OkfVersions.LATEST} + house rules`
|
|
51
|
+
: `OKF v${OkfVersions.LATEST}`;
|
|
52
|
+
|
|
53
|
+
console.log(`check: OK - ${scope} - ${files.length} files, ${conceptCount} concepts`);
|
|
54
|
+
};
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { BUNDLE, REGENERATE_HINT } from '../config.ts';
|
|
4
|
+
import { loadConcepts, stripCode } from '../lib.ts';
|
|
5
|
+
import type { Concept } from '../lib.ts';
|
|
6
|
+
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';
|
|
9
|
+
|
|
10
|
+
// --- docs style ---
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Repo docs rules, enforced on prose (see check step 3). To write a forbidden literal - as the
|
|
14
|
+
* concept defining these rules must - put it in a code span; `stripCode` removes those first.
|
|
15
|
+
*/
|
|
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
|
+
];
|
|
20
|
+
|
|
21
|
+
// --- freshness ---
|
|
22
|
+
|
|
23
|
+
/** Compare generated content ignoring trailing whitespace, so an editor's final newline is not "stale". */
|
|
24
|
+
export const sameContent = (opts: { left: string; right: string }): boolean => {
|
|
25
|
+
const normalize = (value: string) =>
|
|
26
|
+
value
|
|
27
|
+
.split('\n')
|
|
28
|
+
.map(line => line.replace(/\s+$/, ''))
|
|
29
|
+
.join('\n')
|
|
30
|
+
.trim();
|
|
31
|
+
|
|
32
|
+
return normalize(opts.left) === normalize(opts.right);
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
export const collectHouseProblems = (opts: { files: IBundleFile[] }): string[] => {
|
|
36
|
+
const problems: string[] = [];
|
|
37
|
+
|
|
38
|
+
// A concept that fails to load is already reported by the spec layer; links need the loaded set.
|
|
39
|
+
let concepts: Concept[] = [];
|
|
40
|
+
|
|
41
|
+
try {
|
|
42
|
+
concepts = loadConcepts();
|
|
43
|
+
} catch (error) {
|
|
44
|
+
console.error(
|
|
45
|
+
`check: links skipped - ${error instanceof Error ? error.message : String(error)}`,
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const ids = new Set(concepts.map(concept => concept.id));
|
|
50
|
+
|
|
51
|
+
for (const concept of concepts) {
|
|
52
|
+
for (const target of concept.links) {
|
|
53
|
+
if (!ids.has(target)) {
|
|
54
|
+
problems.push(`${repoRelative({ path: concept.file })}: broken link -> ${target}.md`);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// Prose only: code is stripped, so the concept that defines a style rule can still quote what it forbids.
|
|
60
|
+
for (const file of opts.files) {
|
|
61
|
+
const prose = stripCode({ text: file.text });
|
|
62
|
+
|
|
63
|
+
for (const rule of STYLE_RULES) {
|
|
64
|
+
const match = prose.match(rule.pattern);
|
|
65
|
+
|
|
66
|
+
if (match) {
|
|
67
|
+
problems.push(
|
|
68
|
+
`${repoRelative({ path: join(BUNDLE, file.path) })}: ${rule.message} (found "${match[0]}")`,
|
|
69
|
+
);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const paths = new Set(opts.files.map(file => file.path));
|
|
75
|
+
|
|
76
|
+
for (const [items, section] of [
|
|
77
|
+
[packageDirs(), 'packages'],
|
|
78
|
+
[exampleDirs(), 'examples'],
|
|
79
|
+
] as const) {
|
|
80
|
+
for (const name of items) {
|
|
81
|
+
if (!paths.has(`${section}/${name}.md`)) {
|
|
82
|
+
problems.push(`coverage: ${section}/${name} has no concept (${section}/${name}.md)`);
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
for (const region of REGIONS) {
|
|
88
|
+
if (!existsSync(region.file)) {
|
|
89
|
+
problems.push(
|
|
90
|
+
`freshness: region '${region.id}' host file missing (${repoRelative({ path: region.file })})`,
|
|
91
|
+
);
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const actual = extractRegion({ text: readFileSync(region.file, 'utf8'), id: region.id });
|
|
96
|
+
|
|
97
|
+
if (actual === null || !sameContent({ left: actual, right: region.render() })) {
|
|
98
|
+
problems.push(`freshness: region '${region.id}' is stale - ${REGENERATE_HINT}`);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
for (const renderer of RENDERERS) {
|
|
103
|
+
const { path, content } = renderer.render();
|
|
104
|
+
const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
|
|
105
|
+
|
|
106
|
+
if (!sameContent({ left: current, right: content })) {
|
|
107
|
+
problems.push(`freshness: ${repoRelative({ path })} is stale - ${REGENERATE_HINT}`);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
return problems;
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
/** OKF conformance (errors fail, warnings print); `strict` adds the house rules. */
|
package/src/cli.ts
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* vulcan-okf - one entry for the knowledge-bundle tooling. `run.ts` runs as a child process, so it
|
|
4
|
+
* reads its own `process.argv`.
|
|
5
|
+
*/
|
|
6
|
+
import { join } from 'node:path';
|
|
7
|
+
|
|
8
|
+
class OkfCommands {
|
|
9
|
+
static readonly CHECK = 'check';
|
|
10
|
+
static readonly GEN = 'gen';
|
|
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]);
|
|
14
|
+
static isValid(value: string): boolean {
|
|
15
|
+
return this.SCHEME_SET.has(value);
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const USAGE = 'usage: vulcan x okf <check|gen|coverage|viz>';
|
|
20
|
+
|
|
21
|
+
const [command, ...rest] = process.argv.slice(2);
|
|
22
|
+
|
|
23
|
+
if (command === undefined || !OkfCommands.isValid(command)) {
|
|
24
|
+
console.error(USAGE);
|
|
25
|
+
process.exit(2);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
const child = Bun.spawn([process.execPath, join(import.meta.dir, 'run.ts'), command, ...rest], {
|
|
29
|
+
stdio: ['inherit', 'inherit', 'inherit'],
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
process.exit(await child.exited);
|
package/src/config.ts
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
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.
|
|
10
|
+
*/
|
|
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
|
+
|
|
19
|
+
/** Directories never walked when scanning source. */
|
|
20
|
+
export const PRUNE_DIRS = new Set([
|
|
21
|
+
'node_modules',
|
|
22
|
+
'dist',
|
|
23
|
+
'.git',
|
|
24
|
+
'.turbo',
|
|
25
|
+
'coverage',
|
|
26
|
+
'.cache',
|
|
27
|
+
'.vitepress',
|
|
28
|
+
'.claude',
|
|
29
|
+
'__tests__',
|
|
30
|
+
]);
|
|
31
|
+
|
|
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
|
+
/** Reserved OKF filenames that carry no `type:` frontmatter and are never counted as concepts. */
|
|
73
|
+
export const RESERVED_FILES = new Set(['index.md', 'log.md']);
|
|
74
|
+
|
|
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
|
+
/** What a stale check tells the person: the tool command works in any project, a make target may not exist. */
|
|
110
|
+
export const REGENERATE_HINT = 'run `vulcan x okf gen`';
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
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';
|
|
11
|
+
|
|
12
|
+
// --- coverage ---
|
|
13
|
+
|
|
14
|
+
export const percent = (opts: { value: number; total: number }): number => {
|
|
15
|
+
return opts.total ? Math.round((opts.value / opts.total) * 100) : 100;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
export const pad = (opts: { value: string; width: number }): string => {
|
|
19
|
+
return (opts.value + ' '.repeat(opts.width)).slice(0, opts.width);
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
export const coverage = (): void => {
|
|
23
|
+
const concepts = loadConceptsOrExit().filter(concept => !concept.reserved);
|
|
24
|
+
const ids = new Set(concepts.map(concept => concept.id));
|
|
25
|
+
|
|
26
|
+
const hasId = (opts: { id: string }): boolean => ids.has(opts.id);
|
|
27
|
+
const lines: string[] = [];
|
|
28
|
+
let structCovered = 0;
|
|
29
|
+
let structTotal = 0;
|
|
30
|
+
|
|
31
|
+
const struct = (opts: {
|
|
32
|
+
name: string;
|
|
33
|
+
items: string[];
|
|
34
|
+
covered: (item: string) => boolean;
|
|
35
|
+
}): void => {
|
|
36
|
+
const { name, items, covered } = opts;
|
|
37
|
+
|
|
38
|
+
const missing = items.filter(item => !covered(item));
|
|
39
|
+
const value = items.length - missing.length;
|
|
40
|
+
|
|
41
|
+
structCovered += value;
|
|
42
|
+
structTotal += items.length;
|
|
43
|
+
|
|
44
|
+
lines.push(
|
|
45
|
+
` ${pad({ value: name, width: 15 })} ${pad({ value: `${value}/${items.length}`, width: 8 })} ` +
|
|
46
|
+
`${pad({ value: percent({ value, total: items.length }) + '%', width: 5 })}` +
|
|
47
|
+
(missing.length
|
|
48
|
+
? ` missing: ${missing.slice(0, 8).join(', ')}${missing.length > 8 ? ' …' : ''}`
|
|
49
|
+
: ''),
|
|
50
|
+
);
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
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
|
+
});
|
|
64
|
+
|
|
65
|
+
// Reference axes - advisory; exhaustive coverage comes from generation.
|
|
66
|
+
lines.push('', 'REFERENCE (advisory - generated)');
|
|
67
|
+
const ref = (opts: { name: string; count: number; generated: boolean }): void => {
|
|
68
|
+
lines.push(
|
|
69
|
+
` ${pad({ value: opts.name, width: 15 })} ${pad({ value: String(opts.count), width: 6 })} ` +
|
|
70
|
+
`${opts.generated ? 'generated' : 'NOT generated'}`,
|
|
71
|
+
);
|
|
72
|
+
};
|
|
73
|
+
|
|
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
|
+
});
|
|
103
|
+
|
|
104
|
+
// Knowledge types (Diátaxis / arc42).
|
|
105
|
+
const types: Record<string, number> = {};
|
|
106
|
+
|
|
107
|
+
for (const concept of concepts) {
|
|
108
|
+
types[concept.type] = (types[concept.type] || 0) + 1;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const playbookTarget = packageDirs().length;
|
|
112
|
+
|
|
113
|
+
lines.push('', 'KNOWLEDGE TYPES (Diátaxis / arc42)');
|
|
114
|
+
lines.push(
|
|
115
|
+
' ' +
|
|
116
|
+
Object.entries(types)
|
|
117
|
+
.sort((a, b) => b[1] - a[1])
|
|
118
|
+
.map(([type, count]) => `${type}:${count}`)
|
|
119
|
+
.join(' '),
|
|
120
|
+
);
|
|
121
|
+
lines.push(
|
|
122
|
+
` how-to (Playbook) ${types['Playbook'] || 0} (target >= ${playbookTarget})` +
|
|
123
|
+
`${(types['Playbook'] || 0) < playbookTarget ? ' <- gap' : ''}`,
|
|
124
|
+
);
|
|
125
|
+
lines.push(
|
|
126
|
+
` tutorial ${types['Tutorial'] || 0} (target 1)${!types['Tutorial'] ? ' <- gap' : ''}`,
|
|
127
|
+
);
|
|
128
|
+
lines.push(
|
|
129
|
+
` glossary ${types['Glossary'] || 0} (target 1)${!types['Glossary'] ? ' <- gap' : ''}`,
|
|
130
|
+
);
|
|
131
|
+
|
|
132
|
+
console.log(`\nCOVERAGE - ${concepts.length} curated concepts\n`);
|
|
133
|
+
console.log(lines.join('\n'));
|
|
134
|
+
console.log(
|
|
135
|
+
`\nstructural: ${structCovered}/${structTotal} ${percent({ value: structCovered, total: structTotal })}%`,
|
|
136
|
+
);
|
|
137
|
+
|
|
138
|
+
const minIndex = process.argv.indexOf('--min');
|
|
139
|
+
|
|
140
|
+
if (minIndex === -1) {
|
|
141
|
+
return;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
// `--min 0` must mean 0. `Number(x) || 100` silently turned a valid 0 into 100.
|
|
145
|
+
const raw = process.argv[minIndex + 1];
|
|
146
|
+
const min = Number(raw);
|
|
147
|
+
|
|
148
|
+
if (raw === undefined || !Number.isFinite(min)) {
|
|
149
|
+
console.error(
|
|
150
|
+
`\ncoverage: --min needs a number, got ${raw === undefined ? '(nothing)' : `"${raw}"`}`,
|
|
151
|
+
);
|
|
152
|
+
process.exit(2);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
const structPercent = percent({ value: structCovered, total: structTotal });
|
|
156
|
+
|
|
157
|
+
if (structPercent < min) {
|
|
158
|
+
console.error(`\ncoverage gate FAILED: structural ${structPercent}% < ${min}%`);
|
|
159
|
+
process.exit(1);
|
|
160
|
+
}
|
|
161
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './command.ts';
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { replaceRegion } from './regions.ts';
|
|
4
|
+
import { REGIONS, RENDERERS } from './renderers.ts';
|
|
5
|
+
import { repoRelative } from '../source/index.ts';
|
|
6
|
+
|
|
7
|
+
export const gen = (): void => {
|
|
8
|
+
for (const region of REGIONS) {
|
|
9
|
+
if (!existsSync(region.file)) {
|
|
10
|
+
console.warn(
|
|
11
|
+
`gen: skipped region '${region.id}' - ${repoRelative({ path: region.file })} does not exist yet`,
|
|
12
|
+
);
|
|
13
|
+
continue;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
const next = replaceRegion({
|
|
17
|
+
text: readFileSync(region.file, 'utf8'),
|
|
18
|
+
id: region.id,
|
|
19
|
+
body: region.render(),
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
writeFileSync(region.file, next);
|
|
23
|
+
console.log(`gen: wrote region '${region.id}' (${repoRelative({ path: region.file })})`);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
for (const renderer of RENDERERS) {
|
|
27
|
+
const { path, content } = renderer.render();
|
|
28
|
+
|
|
29
|
+
mkdirSync(join(path, '..'), { recursive: true });
|
|
30
|
+
writeFileSync(path, content);
|
|
31
|
+
console.log(`gen: wrote ${repoRelative({ path })}`);
|
|
32
|
+
}
|
|
33
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './types.ts';
|