@venizia/vulcan-okf 0.2.0-1 → 0.2.0-2
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 +25 -15
- package/package.json +1 -1
- package/src/generate/contents.ts +28 -1
package/README.md
CHANGED
|
@@ -34,12 +34,16 @@ allowed; links inside code are examples, never edges. Files may use LF or CRLF l
|
|
|
34
34
|
|
|
35
35
|
Two mechanisms, both driven from source. Never hand-edit either.
|
|
36
36
|
|
|
37
|
-
1. **Whole generated files** -
|
|
38
|
-
with `generated.by: process:okf-gen` (§5.2). No `generated.at`: a timestamp would
|
|
39
|
-
regeneration look like a change.
|
|
40
|
-
2. **Managed regions** -
|
|
41
|
-
`<!-- okf:generated:<id> start -->` and `<!-- okf:generated:<id> end -->` inside an
|
|
42
|
-
hand-authored file.
|
|
37
|
+
1. **Whole generated files** - each renderer in `okf.renderers` writes one page, by default under
|
|
38
|
+
`reference/`, with `generated.by: process:okf-gen` (§5.2). No `generated.at`: a timestamp would
|
|
39
|
+
make every regeneration look like a change.
|
|
40
|
+
2. **Managed regions** - each `okf.regions` entry (`{ id, file, renderer }`) replaces the content
|
|
41
|
+
between `<!-- okf:generated:<id> start -->` and `<!-- okf:generated:<id> end -->` inside an
|
|
42
|
+
otherwise hand-authored file.
|
|
43
|
+
|
|
44
|
+
`gen` renders every page and region in memory first: a renderer that throws, a path outside the
|
|
45
|
+
bundle or two renderers on one path stop it before anything is written. A `gen` that changes nothing
|
|
46
|
+
prints `gen: up to date`.
|
|
43
47
|
|
|
44
48
|
`reference/public-surface.md` is generated by `@venizia/vulcan-atlas` (`vulcan x atlas surface gen`),
|
|
45
49
|
not by `gen`; its `generated:` frontmatter tells `gen` to leave it whole. Long agent-read files get a
|
|
@@ -52,14 +56,19 @@ stderr: `okf: module 'source-map' replaces the built-in renderer`.
|
|
|
52
56
|
|
|
53
57
|
## Adding a renderer
|
|
54
58
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
59
|
+
A built-in renderer (`source-map`, `makefile-targets`, `packages-table`, `binding-keys`) is listed by
|
|
60
|
+
id, with `options`. A project's own renderer is a module:
|
|
61
|
+
|
|
62
|
+
1. Default-export `defineRenderer({ id, collect, render?, region?, coverage? })` from a file in the
|
|
63
|
+
project, importing the API from `@venizia/vulcan/okf`.
|
|
64
|
+
2. `collect` extracts the fact from source, once. **`render`, `region` and `coverage` all read
|
|
65
|
+
it** - a second heuristic for the same fact drifts, and the numbers disagree.
|
|
66
|
+
3. List it in the config: `okf: { renderers: [{ id, module: '.agents/okf/<file>.ts' }] }`, and in
|
|
67
|
+
`okf.regions` when it renders a region.
|
|
68
|
+
4. Run `vulcan x okf gen`, then `vulcan x okf check --strict`: it passes, and a second `gen` prints
|
|
69
|
+
`gen: up to date`.
|
|
60
70
|
|
|
61
|
-
The
|
|
62
|
-
config is planned.
|
|
71
|
+
The [adoption guide](../../docs/wiki/content/guides/adopting-vulcan.md) shows a complete module.
|
|
63
72
|
|
|
64
73
|
## Layout
|
|
65
74
|
|
|
@@ -68,10 +77,11 @@ config is planned.
|
|
|
68
77
|
| `src/cli.ts` | `vulcan-okf` entry; spawns `src/run.ts`, the command runner |
|
|
69
78
|
| `src/index.ts` | the public API: the OKF v0.2 conformance layer |
|
|
70
79
|
| `src/source/` | source scanning and the shared fact collectors (one per fact, used by gen and coverage) |
|
|
71
|
-
| `src/generate/` | `gen`:
|
|
80
|
+
| `src/generate/` | `gen`: the built-in renderers, project modules (`defineRenderer`), regions and contents lists |
|
|
72
81
|
| `src/check/` | `check`: OKF conformance, plus the house rules under `--strict` |
|
|
73
82
|
| `src/coverage-report/` | `coverage`: the bundle against the source inventory |
|
|
74
83
|
| `src/lib.ts` | bundle loader: frontmatter, links, concept model |
|
|
75
84
|
| `src/spec/` | OKF v0.2 conformance - pure, never throws |
|
|
76
85
|
| `src/viz/` | explorer: builder (Bun), typed browser client, template |
|
|
77
|
-
| `src/
|
|
86
|
+
| `src/project/` | reads the project config `vulcan x` hands okf - everything project-specific |
|
|
87
|
+
| `src/config.ts` | constants that hold for every project: pruned directories, reserved files |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan-okf",
|
|
3
|
-
"version": "0.2.0-
|
|
3
|
+
"version": "0.2.0-2",
|
|
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": {
|
package/src/generate/contents.ts
CHANGED
|
@@ -62,6 +62,33 @@ const lineCountOf = (opts: { text: string }): number => {
|
|
|
62
62
|
return opts.text.endsWith('\n') ? count - 1 : count;
|
|
63
63
|
};
|
|
64
64
|
|
|
65
|
+
/** Emphasis as markdown renders it away: `_word_`, `**word**`, `***word***` - never `snake_case`. */
|
|
66
|
+
const EMPHASIS = /(?<![\p{L}\p{N}])([*_]{1,3})(?=\S)(.+?)(?<=\S)\1(?![\p{L}\p{N}])/gu;
|
|
67
|
+
|
|
68
|
+
const NAMED_ENTITIES: Record<string, string> = {
|
|
69
|
+
amp: '&',
|
|
70
|
+
lt: '<',
|
|
71
|
+
gt: '>',
|
|
72
|
+
quot: '"',
|
|
73
|
+
apos: "'",
|
|
74
|
+
nbsp: ' ',
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
/** A heading's text as GitHub renders it, which is what its anchor is made from: entities decoded, emphasis gone. */
|
|
78
|
+
const renderedOf = (opts: { text: string }): string =>
|
|
79
|
+
opts.text
|
|
80
|
+
.replace(EMPHASIS, '$2')
|
|
81
|
+
.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (entity, body: string) => {
|
|
82
|
+
if (body.startsWith('#')) {
|
|
83
|
+
const code =
|
|
84
|
+
body[1] === 'x' || body[1] === 'X' ? parseInt(body.slice(2), 16) : Number(body.slice(1));
|
|
85
|
+
|
|
86
|
+
return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
return NAMED_ENTITIES[body.toLowerCase()] ?? entity;
|
|
90
|
+
});
|
|
91
|
+
|
|
65
92
|
/**
|
|
66
93
|
* A heading's anchor as GitHub writes it (github-slugger): lower case; punctuation and symbols gone,
|
|
67
94
|
* `-` and `_` kept; each space a hyphen; a repeat of an earlier anchor takes `-1`, `-2`. `taken`
|
|
@@ -98,7 +125,7 @@ const headingsOf = (opts: { text: string }): { text: string; anchor: string }[]
|
|
|
98
125
|
}
|
|
99
126
|
|
|
100
127
|
const text = heading[2].replace(LINK, '$1');
|
|
101
|
-
const anchor = anchorOf({ text, taken });
|
|
128
|
+
const anchor = anchorOf({ text: renderedOf({ text }), taken });
|
|
102
129
|
|
|
103
130
|
if (heading[1] === '##') {
|
|
104
131
|
headings.push({ text, anchor });
|