@astrokjs/okf 0.0.0-stage → 0.1.0-beta.1

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.
Files changed (59) hide show
  1. package/LICENSE +9 -0
  2. package/LICENSE-APACHE +202 -0
  3. package/LICENSE-MIT +9 -0
  4. package/README.md +57 -2
  5. package/dist/graph/compiler.d.ts +14 -0
  6. package/dist/graph/compiler.js +75 -0
  7. package/dist/graph/files.d.ts +7 -0
  8. package/dist/graph/files.js +102 -0
  9. package/dist/graph/index.d.ts +9 -0
  10. package/dist/graph/index.js +7 -0
  11. package/dist/graph/memory.d.ts +41 -0
  12. package/dist/graph/memory.js +144 -0
  13. package/dist/graph/metadata.d.ts +3 -0
  14. package/dist/graph/metadata.js +16 -0
  15. package/dist/graph/model.d.ts +88 -0
  16. package/dist/graph/model.js +18 -0
  17. package/dist/graph/project.d.ts +3 -0
  18. package/dist/graph/project.js +242 -0
  19. package/dist/graph/publish.d.ts +38 -0
  20. package/dist/graph/publish.js +56 -0
  21. package/dist/graph/query-core.d.ts +72 -0
  22. package/dist/graph/query-core.js +124 -0
  23. package/dist/graph/query-guide.d.ts +4 -0
  24. package/dist/graph/query-guide.js +35 -0
  25. package/dist/graph/query-reference.d.ts +4 -0
  26. package/dist/graph/query-reference.js +99 -0
  27. package/dist/graph/query.d.ts +59 -0
  28. package/dist/graph/query.js +191 -0
  29. package/dist/graph/schema.d.ts +5 -0
  30. package/dist/graph/schema.js +86 -0
  31. package/dist/graph/snapshot.d.ts +9 -0
  32. package/dist/graph/snapshot.js +115 -0
  33. package/dist/graph/sqlite-guide.d.ts +2 -0
  34. package/dist/graph/sqlite-guide.js +123 -0
  35. package/dist/graph/sqlite.d.ts +4 -0
  36. package/dist/graph/sqlite.js +4 -0
  37. package/dist/graph/version.d.ts +7 -0
  38. package/dist/graph/version.js +7 -0
  39. package/dist/graph/wasm.d.ts +23 -0
  40. package/dist/graph/wasm.js +60 -0
  41. package/dist/index.d.mts +9 -0
  42. package/dist/index.mjs +9 -0
  43. package/dist/okf/bundle.d.mts +2 -0
  44. package/dist/okf/bundle.mjs +58 -0
  45. package/dist/okf/document.d.mts +8 -0
  46. package/dist/okf/document.mjs +109 -0
  47. package/dist/okf/links.d.mts +11 -0
  48. package/dist/okf/links.mjs +91 -0
  49. package/dist/okf/markdown.d.mts +8 -0
  50. package/dist/okf/markdown.mjs +45 -0
  51. package/dist/okf/metadata.d.mts +18 -0
  52. package/dist/okf/metadata.mjs +127 -0
  53. package/dist/site/generate.d.mts +8 -0
  54. package/dist/site/generate.mjs +187 -0
  55. package/dist/site/ownership.d.ts +4 -0
  56. package/dist/site/ownership.js +78 -0
  57. package/dist/types.d.ts +78 -0
  58. package/dist/types.js +1 -0
  59. package/package.json +58 -4
@@ -0,0 +1,144 @@
1
+ import { GraphQueries, bounded, indexedNode, citation, searchTerms, normalizeFamily, validateFilters, } from "./query-core.js";
2
+ import { readSnapshot, JSON_SCHEMA_VERSION } from "./snapshot.js";
3
+ const normalize = (text) => text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
4
+ const compareEdges = (a, b) => {
5
+ for (const key of ['source', 'target', 'relation', 'id']) {
6
+ if (a[key] !== b[key])
7
+ return a[key] < b[key] ? -1 : 1;
8
+ }
9
+ return 0;
10
+ };
11
+ /** SQL-free graph queries; only open/fromBundle dynamically load Node build tools. */
12
+ export class KnowledgeGraph extends GraphQueries {
13
+ graph;
14
+ nodes;
15
+ sourceNodes;
16
+ relations;
17
+ adjacent = new Map();
18
+ evidence = new Map();
19
+ constructor(snapshot) {
20
+ super();
21
+ this.graph = snapshot;
22
+ this.nodes = new Map(snapshot.nodes.map((n) => [n.id, n]));
23
+ this.sourceNodes = new Map(snapshot.nodes.flatMap((node) => node.sourcePath === null ? [] : [[node.sourcePath, node]]));
24
+ this.relations = new Map(snapshot.relations.map((r) => [r.id, r]));
25
+ for (const edge of [...snapshot.edges].sort(compareEdges)) {
26
+ for (const id of new Set([edge.source, edge.target])) {
27
+ const values = this.adjacent.get(id) ?? [];
28
+ values.push(edge);
29
+ this.adjacent.set(id, values);
30
+ }
31
+ }
32
+ for (const item of [...snapshot.evidence].sort((a, b) => a.sourcePath < b.sourcePath
33
+ ? -1
34
+ : a.sourcePath > b.sourcePath
35
+ ? 1
36
+ : (a.sourceLine ?? 0) - (b.sourceLine ?? 0) || (a.id < b.id ? -1 : 1))) {
37
+ const values = this.evidence.get(item.edgeId) ?? [];
38
+ values.push(item);
39
+ this.evidence.set(item.edgeId, values);
40
+ }
41
+ }
42
+ static fromGraph(graph, metadata = {}) {
43
+ return this.fromJSON({
44
+ ...graph,
45
+ format: 'okf-graph',
46
+ schemaVersion: JSON_SCHEMA_VERSION,
47
+ metadata,
48
+ });
49
+ }
50
+ static fromJSON(value) {
51
+ return new KnowledgeGraph(readSnapshot(value));
52
+ }
53
+ static async fromBundle(bundle) {
54
+ const { projectGraph } = await import("./project.js");
55
+ const { graphMetadata } = await import("./metadata.js");
56
+ const graph = projectGraph(bundle);
57
+ return this.fromGraph(graph, graphMetadata(graph));
58
+ }
59
+ static async open(root = 'knowledge') {
60
+ const { readBundle } = await import('../okf/bundle.mjs');
61
+ return this.fromBundle((await readBundle(root)));
62
+ }
63
+ get runtime() {
64
+ return { engine: 'okf-memory', wasm: false };
65
+ }
66
+ close() {
67
+ /* No external resources; same lifecycle as the optional SQL adapter. */
68
+ }
69
+ getNode(id) {
70
+ const node = this.nodes.get(id);
71
+ return node ? indexedNode(structuredClone(node)) : null;
72
+ }
73
+ search(text, { limit = 20 } = {}) {
74
+ bounded(limit, 20, 100, 'limit');
75
+ const terms = searchTerms(text).map(normalize);
76
+ if (!terms.length)
77
+ return [];
78
+ const matches = [];
79
+ for (const node of this.nodes.values()) {
80
+ if (node.kind === 'directory')
81
+ continue;
82
+ const fields = [node.title, node.description, node.body].map((value) => normalize(value).match(/[\p{L}\p{N}]+/gu) ?? []);
83
+ if (!terms.every((term) => fields.some((words) => words.includes(term))))
84
+ continue;
85
+ const score = -terms.reduce((sum, term) => sum +
86
+ fields.reduce((n, words, i) => n + words.filter((word) => word === term).length * [5, 2, 1][i], 0), 0);
87
+ matches.push({
88
+ node: indexedNode(structuredClone(node)),
89
+ score,
90
+ excerpt: node.body.slice(0, 240),
91
+ });
92
+ }
93
+ return matches
94
+ .sort((a, b) => a.score - b.score || (a.node.id < b.node.id ? -1 : 1))
95
+ .slice(0, limit);
96
+ }
97
+ neighbors(id, options = {}) {
98
+ this.requireNode(id);
99
+ validateFilters(options);
100
+ const direction = options.direction ?? 'out';
101
+ const family = normalizeFamily(options.family);
102
+ const limit = bounded(options.limit, 100, 5000, 'limit');
103
+ const matches = [];
104
+ for (const edge of this.adjacent.get(id) ?? []) {
105
+ const relation = this.relations.get(edge.relation);
106
+ if ((family !== undefined && relation.family !== family) ||
107
+ (options.relation !== undefined && edge.relation !== options.relation) ||
108
+ (options.origin !== undefined && edge.origin !== options.origin) ||
109
+ (options.context !== undefined && !edge.contexts.includes(options.context)))
110
+ continue;
111
+ if (relation.family !== 'near' &&
112
+ ((direction === 'out' && edge.source !== id) || (direction === 'in' && edge.target !== id)))
113
+ continue;
114
+ const outgoing = edge.source === id && (direction !== 'in' || relation.family === 'near');
115
+ matches.push({
116
+ edge: structuredClone(edge),
117
+ node: this.requireNode(outgoing ? edge.target : edge.source),
118
+ direction: outgoing ? 'out' : 'in',
119
+ label: outgoing ? relation.name : relation.inverse,
120
+ stType: relation.stType === null
121
+ ? null
122
+ : relation.stType === 0
123
+ ? 0
124
+ : relation.stType * (outgoing ? 1 : -1),
125
+ evidence: (this.evidence.get(edge.id) ?? []).map((e) => {
126
+ const source = this.sourceNodes.get(e.sourcePath);
127
+ return citation(structuredClone(e), source ? indexedNode(source) : undefined);
128
+ }),
129
+ });
130
+ if (matches.length > limit)
131
+ break;
132
+ }
133
+ return { items: matches.slice(0, limit), truncated: matches.length > limit };
134
+ }
135
+ integrity() {
136
+ return { ok: true };
137
+ } // Construction validates all references and evidence.
138
+ export() {
139
+ return {
140
+ ...structuredClone(this.graph),
141
+ nodes: this.graph.nodes.map((n) => indexedNode(structuredClone(n))),
142
+ };
143
+ }
144
+ }
@@ -0,0 +1,3 @@
1
+ import type { Graph } from './model.js';
2
+ export declare const COMPILER_VERSION = "2";
3
+ export declare function graphMetadata(graph: Graph): Record<string, string>;
@@ -0,0 +1,16 @@
1
+ import { hash } from "./project.js";
2
+ import { OKF_SPEC } from "./version.js";
3
+ import { GRAPH_MODEL } from "./model.js";
4
+ export const COMPILER_VERSION = '2';
5
+ export function graphMetadata(graph) {
6
+ return {
7
+ compiler_version: COMPILER_VERSION,
8
+ source_hash: hash(JSON.stringify(graph.sources)),
9
+ graph_model: GRAPH_MODEL,
10
+ okf_spec_version: OKF_SPEC.version,
11
+ okf_spec_revision: OKF_SPEC.revision,
12
+ okf_spec_url: OKF_SPEC.url,
13
+ okf_spec_checked_on: OKF_SPEC.checkedOn,
14
+ bundle_declared_okf_version: JSON.stringify(graph.nodes.find((node) => node.id === 'index')?.metadata.okf_version ?? null),
15
+ };
16
+ }
@@ -0,0 +1,88 @@
1
+ export type Family = 'reference' | 'near' | 'leads_to' | 'contains' | 'expresses';
2
+ export type GraphKind = 'event' | 'thing' | 'concept';
3
+ export declare const GRAPH_MODEL = "gamma34/0.1";
4
+ export declare function semanticIdentity(metadata: Record<string, unknown>): {
5
+ graphModel: string | null;
6
+ graphKind: GraphKind | null;
7
+ };
8
+ export type Origin = 'structural' | 'explicit' | 'inferred';
9
+ export interface GraphNode {
10
+ /** Optional canonical publication routes; absent in source-only graphs. */
11
+ url?: string | null;
12
+ sourceUrl?: string | null;
13
+ graphModel: string | null;
14
+ graphKind: GraphKind | null;
15
+ id: string;
16
+ kind: 'concept' | 'index' | 'log' | 'directory';
17
+ title: string;
18
+ description: string;
19
+ type: string | null;
20
+ body: string;
21
+ metadata: Record<string, unknown>;
22
+ sourcePath: string | null;
23
+ }
24
+ export interface Relation {
25
+ id: string;
26
+ name: string;
27
+ inverse: string;
28
+ family: Family;
29
+ stType: number | null;
30
+ }
31
+ export interface GraphEdge {
32
+ id: string;
33
+ source: string;
34
+ target: string;
35
+ relation: string;
36
+ origin: Origin;
37
+ weight: number;
38
+ confidence: number | null;
39
+ contexts: string[];
40
+ }
41
+ export interface Evidence {
42
+ id: string;
43
+ edgeId: string;
44
+ sourcePath: string;
45
+ sourceFragment: string | null;
46
+ sourceLine: number | null;
47
+ sourceColumn: number | null;
48
+ targetFragment: string | null;
49
+ kind: 'markdown_link' | 'directory_membership' | 'graph_relation' | 'metadata_path';
50
+ detail: string | null;
51
+ }
52
+ export interface Graph {
53
+ sources: {
54
+ path: string;
55
+ hash: string;
56
+ }[];
57
+ nodes: GraphNode[];
58
+ relations: Relation[];
59
+ edges: GraphEdge[];
60
+ evidence: Evidence[];
61
+ diagnostics: string[];
62
+ }
63
+ export interface BundleDocument {
64
+ id: string;
65
+ path: string;
66
+ kind: 'concept' | 'index' | 'log';
67
+ title: string;
68
+ description: string;
69
+ type: string | null;
70
+ metadata: Record<string, unknown>;
71
+ body: string;
72
+ source: string;
73
+ headings: string[];
74
+ links: {
75
+ target?: string;
76
+ sourceFragment?: string | null;
77
+ fragment?: string | null;
78
+ line?: number;
79
+ column?: number;
80
+ }[];
81
+ }
82
+ export interface Bundle {
83
+ documents: BundleDocument[];
84
+ assets: Map<string, Uint8Array>;
85
+ errors: string[];
86
+ warnings: string[];
87
+ }
88
+ export declare const ST_TYPES: Record<Family, number | null>;
@@ -0,0 +1,18 @@
1
+ export const GRAPH_MODEL = 'gamma34/0.1';
2
+ export function semanticIdentity(metadata) {
3
+ const graphModel = typeof metadata.graph_model === 'string' ? metadata.graph_model : null;
4
+ const value = metadata.graph_kind;
5
+ return {
6
+ graphModel,
7
+ graphKind: graphModel === GRAPH_MODEL && (value === 'event' || value === 'thing' || value === 'concept')
8
+ ? value
9
+ : null,
10
+ };
11
+ }
12
+ export const ST_TYPES = {
13
+ reference: null,
14
+ near: 0,
15
+ leads_to: 1,
16
+ contains: 2,
17
+ expresses: 3,
18
+ };
@@ -0,0 +1,3 @@
1
+ import type { Bundle, Graph } from './model.js';
2
+ export declare const hash: (value: string) => string;
3
+ export declare function projectGraph(bundle: Bundle): Graph;
@@ -0,0 +1,242 @@
1
+ import { createHash } from 'node:crypto';
2
+ import path from 'node:path';
3
+ import { metadataPaths } from '../okf/metadata.mjs';
4
+ import { resolvePathField, resolveLink } from '../okf/links.mjs';
5
+ import { ST_TYPES, GRAPH_MODEL, semanticIdentity } from "./model.js";
6
+ export const hash = (value) => createHash('sha256').update(value).digest('hex');
7
+ const directoryId = (dir) => '@directory/' + (dir === '.' ? '' : dir + '/');
8
+ const sorted = (values) => [...values].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
9
+ export function projectGraph(bundle) {
10
+ if (bundle.errors.length)
11
+ throw new Error(bundle.errors.join('\n'));
12
+ const nodes = new Map();
13
+ const edges = new Map();
14
+ const evidence = new Map();
15
+ const relations = new Map([
16
+ [
17
+ 'structural:references',
18
+ {
19
+ id: 'structural:references',
20
+ name: 'references',
21
+ inverse: 'referenced_by',
22
+ family: 'reference',
23
+ stType: null,
24
+ },
25
+ ],
26
+ [
27
+ 'structural:contains',
28
+ {
29
+ id: 'structural:contains',
30
+ name: 'contains',
31
+ inverse: 'part_of',
32
+ family: 'contains',
33
+ stType: 2,
34
+ },
35
+ ],
36
+ ]);
37
+ const diagnostics = [...bundle.warnings];
38
+ const byPath = new Map(bundle.documents.map((document) => [document.path, document]));
39
+ const addEdge = (input, proof) => {
40
+ const id = hash(JSON.stringify(input));
41
+ edges.set(id, { id, ...input });
42
+ const evidenceId = hash(JSON.stringify([id, proof]));
43
+ evidence.set(evidenceId, { id: evidenceId, edgeId: id, ...proof });
44
+ };
45
+ const structural = (source, target, relation) => ({
46
+ source,
47
+ target,
48
+ relation,
49
+ origin: 'structural',
50
+ weight: 1,
51
+ confidence: null,
52
+ contexts: [],
53
+ });
54
+ function addDirectory(dir) {
55
+ const id = directoryId(dir);
56
+ if (!nodes.has(id))
57
+ nodes.set(id, {
58
+ id,
59
+ graphModel: null,
60
+ graphKind: null,
61
+ kind: 'directory',
62
+ title: dir === '.' ? 'Knowledge bundle' : path.posix.basename(dir),
63
+ description: '',
64
+ type: null,
65
+ body: '',
66
+ metadata: {},
67
+ sourcePath: null,
68
+ });
69
+ }
70
+ addDirectory('.');
71
+ for (const document of bundle.documents) {
72
+ const model = document.metadata.graph_model;
73
+ if (model !== undefined && (typeof model !== 'string' || !model.trim()))
74
+ throw new Error(`${document.path}: graph_model must be a non-empty string`);
75
+ if (model === undefined && document.metadata.graph_kind !== undefined)
76
+ throw new Error(`${document.path}: graph_kind requires graph_model`);
77
+ if (model === GRAPH_MODEL &&
78
+ document.kind === 'concept' &&
79
+ !semanticIdentity(document.metadata).graphKind)
80
+ throw new Error(`${document.path}: graph_kind must be event, thing, or concept for ${GRAPH_MODEL}`);
81
+ if (model !== undefined && model !== GRAPH_MODEL)
82
+ diagnostics.push(`${document.path}: unsupported graph_model ${model}; semantic extension preserved without interpretation`);
83
+ nodes.set(document.id, {
84
+ ...semanticIdentity(document.metadata),
85
+ id: document.id,
86
+ kind: document.kind,
87
+ title: document.title,
88
+ description: document.description,
89
+ type: document.type,
90
+ metadata: document.metadata,
91
+ body: document.body,
92
+ sourcePath: document.path,
93
+ });
94
+ }
95
+ for (const document of bundle.documents) {
96
+ const proof = {
97
+ sourcePath: document.path,
98
+ sourceFragment: null,
99
+ sourceLine: null,
100
+ sourceColumn: null,
101
+ targetFragment: null,
102
+ kind: 'directory_membership',
103
+ detail: 'Canonical source path hierarchy',
104
+ };
105
+ let dir = path.posix.dirname(document.path);
106
+ addDirectory(dir);
107
+ addEdge(structural(directoryId(dir), document.id, 'structural:contains'), proof);
108
+ while (dir !== '.') {
109
+ const parent = path.posix.dirname(dir);
110
+ addDirectory(parent);
111
+ addEdge(structural(directoryId(parent), directoryId(dir), 'structural:contains'), proof);
112
+ dir = parent;
113
+ }
114
+ for (const link of document.links) {
115
+ if (!link.target || !nodes.has(link.target))
116
+ continue;
117
+ addEdge(structural(document.id, link.target, 'structural:references'), {
118
+ sourcePath: document.path,
119
+ sourceFragment: link.sourceFragment ?? null,
120
+ sourceLine: link.line ?? null,
121
+ sourceColumn: link.column ?? null,
122
+ targetFragment: link.fragment ?? null,
123
+ kind: 'markdown_link',
124
+ detail: null,
125
+ });
126
+ }
127
+ if (document.kind === 'concept')
128
+ for (const { field, href } of metadataPaths(document.metadata)) {
129
+ const resolved = resolvePathField(href, document.path, byPath, bundle.assets, byPath.get('index.md')?.metadata.okf_version);
130
+ if (resolved.warning)
131
+ diagnostics.push(`${document.path}: ${field}: ${resolved.warning}`);
132
+ // Indexes, logs and assets are navigable, but are not concept targets.
133
+ if (!resolved.target || nodes.get(resolved.target)?.kind !== 'concept')
134
+ continue;
135
+ addEdge(structural(document.id, resolved.target, 'structural:references'), {
136
+ sourcePath: document.path,
137
+ sourceFragment: null,
138
+ sourceLine: null,
139
+ sourceColumn: null,
140
+ targetFragment: resolved.fragment ?? null,
141
+ kind: 'metadata_path',
142
+ detail: field,
143
+ });
144
+ }
145
+ if (document.metadata.graph_model !== undefined &&
146
+ document.metadata.graph_model !== GRAPH_MODEL)
147
+ continue;
148
+ const extensions = document.metadata.graph_relations;
149
+ if (extensions === undefined)
150
+ continue;
151
+ const fail = (message) => {
152
+ throw new Error(`${document.path}: graph_relations ${message}`);
153
+ };
154
+ if (!Array.isArray(extensions))
155
+ fail('must be a list');
156
+ for (const [position, raw] of extensions.entries()) {
157
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw))
158
+ fail(`[${position}] must be a mapping`);
159
+ const relation = raw;
160
+ const text = (name) => typeof relation[name] === 'string' && relation[name].trim()
161
+ ? relation[name]
162
+ : fail(`[${position}].${name} must be a non-empty string`);
163
+ const targetHref = text('target');
164
+ const name = text('relation');
165
+ const inputFamily = text('family');
166
+ const family = (inputFamily === 'similar' ? 'near' : inputFamily);
167
+ if (!Object.hasOwn(ST_TYPES, family) || family === 'reference')
168
+ fail(`[${position}].family must be similar (or near), leads_to, contains, or expresses`);
169
+ const inverse = relation.inverse === undefined
170
+ ? family === 'near'
171
+ ? name
172
+ : `inverse:${name}`
173
+ : text('inverse');
174
+ if (family === 'near' && inverse !== name)
175
+ fail('similarity must use the same relation name in both directions');
176
+ const origin = relation.origin === undefined
177
+ ? 'explicit'
178
+ : relation.origin === 'explicit' || relation.origin === 'inferred'
179
+ ? relation.origin
180
+ : fail('origin must be explicit or inferred');
181
+ const confidence = relation.confidence === undefined ? null : relation.confidence;
182
+ if (confidence !== null &&
183
+ (typeof confidence !== 'number' ||
184
+ !Number.isFinite(confidence) ||
185
+ confidence < 0 ||
186
+ confidence > 1))
187
+ fail('confidence must be a number between 0 and 1');
188
+ if (origin === 'inferred' && (confidence === null || !relation.evidence))
189
+ fail('inferred relations require confidence and evidence');
190
+ const detail = relation.evidence === undefined ? `graph_relations[${position}]` : text('evidence');
191
+ const weight = relation.weight === undefined ? 1 : relation.weight;
192
+ if (typeof weight !== 'number' || !Number.isFinite(weight) || weight < 0)
193
+ fail('weight must be a finite non-negative number');
194
+ const contextsValue = relation.contexts ?? [];
195
+ if (!Array.isArray(contextsValue) ||
196
+ !contextsValue.every((value) => typeof value === 'string' && value.trim()))
197
+ fail('contexts must be a list of non-empty strings');
198
+ const contexts = [...new Set(contextsValue)].sort();
199
+ const resolved = resolveLink(targetHref, document.path, byPath, bundle.assets);
200
+ if (resolved.external || !resolved.targetPath || !resolved.targetPath.endsWith('.md'))
201
+ fail('target must be a Markdown path inside the bundle');
202
+ const id = `semantic:${name}`;
203
+ const definition = { id, name, inverse, family, stType: ST_TYPES[family] };
204
+ if (relations.has(id) && JSON.stringify(relations.get(id)) !== JSON.stringify(definition))
205
+ fail(`conflicting definitions for relation ${name}`);
206
+ relations.set(id, definition);
207
+ if (resolved.warning)
208
+ diagnostics.push(`${document.path}: graph_relations[${position}]: ${resolved.warning}`);
209
+ if (!('target' in resolved) || !resolved.target)
210
+ continue;
211
+ addEdge({
212
+ source: document.id,
213
+ target: resolved.target,
214
+ relation: id,
215
+ origin,
216
+ contexts,
217
+ weight: weight,
218
+ confidence: confidence,
219
+ }, {
220
+ sourcePath: document.path,
221
+ sourceFragment: null,
222
+ sourceLine: null,
223
+ sourceColumn: null,
224
+ targetFragment: resolved.fragment ?? null,
225
+ kind: 'graph_relation',
226
+ detail,
227
+ });
228
+ }
229
+ }
230
+ return {
231
+ sources: bundle.documents
232
+ .map((d) => ({ path: d.path, hash: hash(d.source) }))
233
+ .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
234
+ nodes: sorted(nodes.values()),
235
+ relations: sorted(relations.values()),
236
+ edges: sorted(edges.values()),
237
+ evidence: [...evidence.values()].sort((a, b) => a.sourcePath.localeCompare(b.sourcePath, 'en') ||
238
+ (a.sourceLine ?? 0) - (b.sourceLine ?? 0) ||
239
+ a.id.localeCompare(b.id, 'en')),
240
+ diagnostics: [...new Set(diagnostics)].sort(),
241
+ };
242
+ }
@@ -0,0 +1,38 @@
1
+ import type { Bundle } from './model.js';
2
+ export declare function publishIndex({ root, publicDir, sqlite, bundle, base, }?: {
3
+ root?: string;
4
+ publicDir?: string;
5
+ sqlite?: boolean;
6
+ bundle?: Bundle;
7
+ base?: string;
8
+ }): Promise<{
9
+ graph: {
10
+ nodes: {
11
+ url: string | null;
12
+ sourceUrl: string | null;
13
+ graphModel: string | null;
14
+ graphKind: import("./model.js").GraphKind | null;
15
+ id: string;
16
+ kind: "concept" | "index" | "log" | "directory";
17
+ title: string;
18
+ description: string;
19
+ type: string | null;
20
+ body: string;
21
+ metadata: Record<string, unknown>;
22
+ sourcePath: string | null;
23
+ }[];
24
+ format: "okf-graph";
25
+ schemaVersion: number;
26
+ metadata: Record<string, string>;
27
+ sources: {
28
+ path: string;
29
+ hash: string;
30
+ }[];
31
+ relations: import("./model.js").Relation[];
32
+ edges: import("./model.js").GraphEdge[];
33
+ evidence: import("./model.js").Evidence[];
34
+ diagnostics: string[];
35
+ };
36
+ json: string;
37
+ database: string | null;
38
+ }>;
@@ -0,0 +1,56 @@
1
+ import path from 'node:path';
2
+ import { readFile } from 'node:fs/promises';
3
+ import { KnowledgeGraph } from "./memory.js";
4
+ import { publishFiles, assertOutside } from "./files.js";
5
+ import { queryGuide } from "./query-guide.js";
6
+ import { pageUrl } from '../okf/links.mjs';
7
+ import { normalizeBase, withBase } from '../site/generate.mjs';
8
+ import { queryReference } from "./query-reference.js";
9
+ export async function publishIndex({ root = 'knowledge', publicDir = '.generated/public', sqlite = false, bundle, base = '/', } = {}) {
10
+ base = normalizeBase(base);
11
+ const rebase = (text) => base === '/'
12
+ ? text
13
+ : text.replace(/(?<![\w./])\/(?:okf|graph)\//g, (match) => base.slice(0, -1) + match);
14
+ const json = path.join(publicDir, 'graph/graph.json');
15
+ const database = path.join(publicDir, 'graph/knowledge.sqlite');
16
+ const guide = path.join(publicDir, 'llms.txt');
17
+ const reference = path.join(publicDir, 'graph/query-guide.md');
18
+ const sqlGuide = path.join(publicDir, 'graph/sqlite-query.txt');
19
+ for (const output of [json, database, guide, reference, sqlGuide])
20
+ await assertOutside(root, output);
21
+ const index = bundle ? await KnowledgeGraph.fromBundle(bundle) : await KnowledgeGraph.open(root);
22
+ const exported = index.export();
23
+ const snapshot = {
24
+ ...exported,
25
+ nodes: exported.nodes.map((node) => ({
26
+ ...node,
27
+ url: node.sourcePath ? withBase(pageUrl(node.sourcePath), base) : null,
28
+ sourceUrl: node.sourcePath
29
+ ? withBase('/okf/' + node.sourcePath.split('/').map(encodeURIComponent).join('/'), base)
30
+ : null,
31
+ })),
32
+ };
33
+ const jsonText = JSON.stringify(snapshot, null, 2) + '\n';
34
+ const outputs = new Map();
35
+ if (sqlite) {
36
+ const { serializeGraph } = await import("./compiler.js");
37
+ const { sqliteQueryGuide } = await import("./sqlite-guide.js");
38
+ const previous = await readFile(database).catch((error) => {
39
+ if (error.code !== 'ENOENT')
40
+ throw error;
41
+ return undefined;
42
+ });
43
+ const bytes = await serializeGraph(snapshot, previous);
44
+ outputs.set(database, bytes);
45
+ outputs.set(sqlGuide, rebase(sqliteQueryGuide()));
46
+ }
47
+ else {
48
+ outputs.set(database, null);
49
+ outputs.set(sqlGuide, null);
50
+ }
51
+ outputs.set(json, jsonText);
52
+ outputs.set(guide, rebase(queryGuide({ sqlite })));
53
+ outputs.set(reference, rebase(queryReference({ sqlite })));
54
+ await publishFiles(outputs);
55
+ return { graph: snapshot, json, database: sqlite ? database : null };
56
+ }