@venizia/vulcan-okf 0.2.0-1 → 0.2.0-3

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
@@ -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** - 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.
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
- 1. Write a `collect*` function that extracts the fact from source.
56
- **Use it for both the renderer and the coverage counter** - a second heuristic for the same fact
57
- drifts, and the numbers disagree.
58
- 2. Write a `render*` returning `{ path, content }` and add it to `RENDERERS`.
59
- 3. Run `gen`, then `check --strict` twice: it must pass and be idempotent.
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 renderers and coverage rows are IGNIS-specific today (`src/config.ts`); making them project
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`: managed regions and the `RENDERERS` / `REGIONS` registries |
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/config.ts` | the only project-specific file: paths, section order, explorer copy |
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-1",
3
+ "version": "0.2.0-3",
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": {
@@ -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 });