@venizia/vulcan-okf 0.4.10-2 → 0.4.10-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
|
@@ -6,7 +6,7 @@ v0.2. Part of VULCAN; the bundle is served over MCP by `@venizia/vulcan-atlas`,
|
|
|
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 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan-okf",
|
|
3
|
-
"version": "0.4.10-
|
|
3
|
+
"version": "0.4.10-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
|
"bugs": {
|
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
|
|
|
@@ -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 } {
|