@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.
- package/LICENSE +9 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +9 -0
- package/README.md +57 -2
- package/dist/graph/compiler.d.ts +14 -0
- package/dist/graph/compiler.js +75 -0
- package/dist/graph/files.d.ts +7 -0
- package/dist/graph/files.js +102 -0
- package/dist/graph/index.d.ts +9 -0
- package/dist/graph/index.js +7 -0
- package/dist/graph/memory.d.ts +41 -0
- package/dist/graph/memory.js +144 -0
- package/dist/graph/metadata.d.ts +3 -0
- package/dist/graph/metadata.js +16 -0
- package/dist/graph/model.d.ts +88 -0
- package/dist/graph/model.js +18 -0
- package/dist/graph/project.d.ts +3 -0
- package/dist/graph/project.js +242 -0
- package/dist/graph/publish.d.ts +38 -0
- package/dist/graph/publish.js +56 -0
- package/dist/graph/query-core.d.ts +72 -0
- package/dist/graph/query-core.js +124 -0
- package/dist/graph/query-guide.d.ts +4 -0
- package/dist/graph/query-guide.js +35 -0
- package/dist/graph/query-reference.d.ts +4 -0
- package/dist/graph/query-reference.js +99 -0
- package/dist/graph/query.d.ts +59 -0
- package/dist/graph/query.js +191 -0
- package/dist/graph/schema.d.ts +5 -0
- package/dist/graph/schema.js +86 -0
- package/dist/graph/snapshot.d.ts +9 -0
- package/dist/graph/snapshot.js +115 -0
- package/dist/graph/sqlite-guide.d.ts +2 -0
- package/dist/graph/sqlite-guide.js +123 -0
- package/dist/graph/sqlite.d.ts +4 -0
- package/dist/graph/sqlite.js +4 -0
- package/dist/graph/version.d.ts +7 -0
- package/dist/graph/version.js +7 -0
- package/dist/graph/wasm.d.ts +23 -0
- package/dist/graph/wasm.js +60 -0
- package/dist/index.d.mts +9 -0
- package/dist/index.mjs +9 -0
- package/dist/okf/bundle.d.mts +2 -0
- package/dist/okf/bundle.mjs +58 -0
- package/dist/okf/document.d.mts +8 -0
- package/dist/okf/document.mjs +109 -0
- package/dist/okf/links.d.mts +11 -0
- package/dist/okf/links.mjs +91 -0
- package/dist/okf/markdown.d.mts +8 -0
- package/dist/okf/markdown.mjs +45 -0
- package/dist/okf/metadata.d.mts +18 -0
- package/dist/okf/metadata.mjs +127 -0
- package/dist/site/generate.d.mts +8 -0
- package/dist/site/generate.mjs +187 -0
- package/dist/site/ownership.d.ts +4 -0
- package/dist/site/ownership.js +78 -0
- package/dist/types.d.ts +78 -0
- package/dist/types.js +1 -0
- 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,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,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
|
+
}
|