@atolis-hq/corum 0.1.33 → 0.1.35
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 +35 -2
- package/dist/src/adapters/corum/mapper.js +99 -13
- package/dist/src/graph/index.js +293 -5
- package/dist/src/mcp/index.js +344 -14
- package/dist/src/mcp/prompts/usage-guide.js +74 -0
- package/dist/src/web/server.js +94 -28
- package/package.json +1 -1
- package/web/app.jsx +28 -8
- package/web/graph-utils.js +2 -61
- package/web/graph-utils.test.js +9 -84
- package/web/graph.jsx +39 -8
- package/web/search.jsx +18 -30
package/README.md
CHANGED
|
@@ -129,6 +129,13 @@ componentNameReplacements:
|
|
|
129
129
|
- from: ordershipping
|
|
130
130
|
to: order-shipping
|
|
131
131
|
|
|
132
|
+
# Optional: deduplicate nodes emitted by different adapters after all imports
|
|
133
|
+
# complete. For each rule, keep nodes from the primary adapter and merge/drop
|
|
134
|
+
# matching nodes from the secondary adapter.
|
|
135
|
+
deduplication:
|
|
136
|
+
- primary: openapi
|
|
137
|
+
secondary: corum
|
|
138
|
+
|
|
132
139
|
imports:
|
|
133
140
|
- adapter: openapi
|
|
134
141
|
spec: ./specs/order-shipping.openapi.yaml
|
|
@@ -149,6 +156,9 @@ imports:
|
|
|
149
156
|
```
|
|
150
157
|
|
|
151
158
|
Replacements are applied in order; the first matching `from` wins. Unmatched names are passed through unchanged.
|
|
159
|
+
Deduplication rules are applied after all adapters finish. They are intended for
|
|
160
|
+
cross-adapter reconciliation, for example keeping OpenAPI endpoints as canonical
|
|
161
|
+
while merging matching extractor-emitted Corum nodes into them.
|
|
152
162
|
|
|
153
163
|
#### `corum import openapi <spec>`
|
|
154
164
|
|
|
@@ -288,14 +298,37 @@ Or if installed globally:
|
|
|
288
298
|
|
|
289
299
|
| Tool | Description |
|
|
290
300
|
|---|---|
|
|
291
|
-
| `list_nodes` | List graph nodes
|
|
301
|
+
| `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |
|
|
292
302
|
| `list_templates` | List loaded templates with summary metadata |
|
|
293
303
|
| `get_template` | Return full details for a template |
|
|
294
|
-
| `get_cluster` | Return a root node, its
|
|
304
|
+
| `get_cluster` | Return a root node, its descendants, included external nodes, and edges |
|
|
305
|
+
| `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |
|
|
306
|
+
| `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |
|
|
307
|
+
| `get_lineage` | Traverse lineage from one or more start nodes with depth, direction, and edge/node-type filters |
|
|
308
|
+
| `get_graph_summary` | Return high-level graph statistics: node count, component count, orphan breakdown, edge counts, diagnostics |
|
|
309
|
+
| `search_nodes` | Fuzzy-search root-level nodes by ID, with optional template filters and property search |
|
|
295
310
|
| `get_linked_fields` | Return `maps-to` edges touching fields owned by a root node |
|
|
311
|
+
| `list_branches` | List available branches and their load status from the configured source |
|
|
312
|
+
| `diff_branch` | Diff a branch against the default branch |
|
|
296
313
|
|
|
297
314
|
All tools accept an optional `format` argument: `yaml` (default), `json`, or `toon`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage.
|
|
298
315
|
|
|
316
|
+
Common notes:
|
|
317
|
+
- `branch` is supported on graph-query tools when Corum is running against a source-backed graph.
|
|
318
|
+
- `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.
|
|
319
|
+
- `search_nodes` accepts `queries: string[]`.
|
|
320
|
+
- `get_graph_metadata` is the quickest way to discover valid template names, edge types, lifecycle states, stabilities, lineage directions, and output formats before constructing other calls.
|
|
321
|
+
- `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, and `reads_outbound_only`.
|
|
322
|
+
- The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.
|
|
323
|
+
|
|
324
|
+
## MCP Prompts
|
|
325
|
+
|
|
326
|
+
The server also exposes a discoverable MCP prompt:
|
|
327
|
+
|
|
328
|
+
| Prompt | Description |
|
|
329
|
+
|---|---|
|
|
330
|
+
| `usage-guide` | Orientation guide covering graph structure, recommended tool workflow, output-format choices, graph-completeness caveats, and inference guidance |
|
|
331
|
+
|
|
299
332
|
## Contributing
|
|
300
333
|
|
|
301
334
|
See [DEVELOPMENT.md](DEVELOPMENT.md) for build, test, and local development instructions.
|
|
@@ -7,6 +7,8 @@ export function mapDocument(document, specPath) {
|
|
|
7
7
|
const edges = [];
|
|
8
8
|
const diagnostics = [];
|
|
9
9
|
const allSchemas = (document.components?.schemas ?? {});
|
|
10
|
+
// Maps #/components/schemas/X and #/components/schemas/X/properties/Y to materialized node IDs
|
|
11
|
+
const refToNodeId = new Map();
|
|
10
12
|
for (const gap of document.gaps ?? []) {
|
|
11
13
|
const msg = gap.nodeId
|
|
12
14
|
? `[${gap.kind}] ${gap.nodeId}: ${gap.reason ?? ''}`
|
|
@@ -36,9 +38,50 @@ export function mapDocument(document, specPath) {
|
|
|
36
38
|
nodes.push(node);
|
|
37
39
|
if (schemaName) {
|
|
38
40
|
const expanded = new Map();
|
|
39
|
-
expandSchema(schemaName, nodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
41
|
+
expandSchema(schemaName, nodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
40
42
|
}
|
|
41
43
|
}
|
|
44
|
+
// Expand schemas referenced in edges that weren't reachable via any node's schema ref.
|
|
45
|
+
// Uses schema name as its own synthetic root so IDs are self-contained and don't collide.
|
|
46
|
+
// Enum schemas register their enum values as field nodes so edge refs to them can resolve.
|
|
47
|
+
const orphanExpanded = new Set();
|
|
48
|
+
for (const raw of document.edges ?? []) {
|
|
49
|
+
for (const endpoint of [raw.from, raw.to]) {
|
|
50
|
+
const schemaName = extractSchemaName(endpoint);
|
|
51
|
+
if (!schemaName)
|
|
52
|
+
continue;
|
|
53
|
+
const schemaRef = `#/components/schemas/${schemaName}`;
|
|
54
|
+
if (refToNodeId.has(schemaRef) || orphanExpanded.has(schemaName))
|
|
55
|
+
continue;
|
|
56
|
+
orphanExpanded.add(schemaName);
|
|
57
|
+
const schemaLocalName = schemaName.includes('.')
|
|
58
|
+
? schemaName.slice(schemaName.lastIndexOf('.') + 1)
|
|
59
|
+
: schemaName;
|
|
60
|
+
const schemaId = `${schemaLocalName}.schemas.${schemaLocalName}`;
|
|
61
|
+
refToNodeId.set(schemaRef, schemaId);
|
|
62
|
+
nodes.push(makeNode('Schema', '_', specPath, schemaId, undefined, {}));
|
|
63
|
+
const schemaDef = allSchemas[schemaName];
|
|
64
|
+
for (const fieldName of Object.keys(schemaDef?.properties ?? {})) {
|
|
65
|
+
const fieldId = `${schemaId}.fields.${fieldName}`;
|
|
66
|
+
refToNodeId.set(`${schemaRef}/properties/${fieldName}`, fieldId);
|
|
67
|
+
nodes.push(makeNode('Field', '_', specPath, fieldId, undefined, {}));
|
|
68
|
+
edges.push(makeHasFieldEdge(schemaId, fieldId));
|
|
69
|
+
}
|
|
70
|
+
if (Array.isArray(schemaDef?.enum)) {
|
|
71
|
+
for (const value of schemaDef.enum) {
|
|
72
|
+
if (typeof value !== 'string')
|
|
73
|
+
continue;
|
|
74
|
+
const fieldId = `${schemaId}.values.${value}`;
|
|
75
|
+
refToNodeId.set(`${schemaRef}/properties/${value}`, fieldId);
|
|
76
|
+
nodes.push(makeNode('EnumValue', '_', specPath, fieldId, undefined, { value }));
|
|
77
|
+
edges.push(makeHasFieldEdge(schemaId, fieldId));
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
// Build case-insensitive fallback index to handle PascalCase/camelCase mismatches
|
|
83
|
+
// between edge field refs and actual schema property names
|
|
84
|
+
const refToNodeIdLower = new Map([...refToNodeId.entries()].map(([k, v]) => [k.toLowerCase(), v]));
|
|
42
85
|
for (const raw of document.edges ?? []) {
|
|
43
86
|
if (!VALID_EDGE_TYPES.has(raw.type)) {
|
|
44
87
|
diagnostics.push({
|
|
@@ -48,7 +91,17 @@ export function mapDocument(document, specPath) {
|
|
|
48
91
|
});
|
|
49
92
|
continue;
|
|
50
93
|
}
|
|
51
|
-
|
|
94
|
+
const from = refToNodeId.get(raw.from) ?? refToNodeIdLower.get(raw.from.toLowerCase()) ?? raw.from;
|
|
95
|
+
const to = refToNodeId.get(raw.to) ?? refToNodeIdLower.get(raw.to.toLowerCase()) ?? raw.to;
|
|
96
|
+
if (from.startsWith('#/') || to.startsWith('#/')) {
|
|
97
|
+
diagnostics.push({
|
|
98
|
+
severity: 'warning',
|
|
99
|
+
file: specPath,
|
|
100
|
+
message: `edge references unresolvable node — skipping: ${from} → ${to}`,
|
|
101
|
+
});
|
|
102
|
+
continue;
|
|
103
|
+
}
|
|
104
|
+
edges.push(mapEdge({ ...raw, from, to }));
|
|
52
105
|
}
|
|
53
106
|
return { nodes, edges, diagnostics };
|
|
54
107
|
}
|
|
@@ -58,12 +111,28 @@ function schemaRefName(ref) {
|
|
|
58
111
|
return undefined;
|
|
59
112
|
return ref.slice(prefix.length);
|
|
60
113
|
}
|
|
61
|
-
function
|
|
114
|
+
function extractSchemaName(endpoint) {
|
|
115
|
+
const prefix = '#/components/schemas/';
|
|
116
|
+
if (!endpoint.startsWith(prefix))
|
|
117
|
+
return undefined;
|
|
118
|
+
return endpoint.slice(prefix.length).split('/')[0];
|
|
119
|
+
}
|
|
120
|
+
function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId) {
|
|
62
121
|
const existing = expanded.get(schemaName);
|
|
63
122
|
if (existing)
|
|
64
123
|
return existing;
|
|
65
|
-
|
|
124
|
+
// Schema names from corum extractors are sometimes prefixed with the component name
|
|
125
|
+
// (e.g. "workers.ReactToPersonCreatedCommand"). Strip the prefix so the local segment
|
|
126
|
+
// in the node ID is a simple identifier — graph serialization rejects local names
|
|
127
|
+
// that contain dots because it uses dots as a hierarchy separator.
|
|
128
|
+
const schemaLocalName = schemaName.includes('.')
|
|
129
|
+
? schemaName.slice(schemaName.lastIndexOf('.') + 1)
|
|
130
|
+
: schemaName;
|
|
131
|
+
const schemaId = `${rootNodeId}.schemas.${schemaLocalName}`;
|
|
66
132
|
expanded.set(schemaName, schemaId);
|
|
133
|
+
const schemaRef = `#/components/schemas/${schemaName}`;
|
|
134
|
+
if (!refToNodeId.has(schemaRef))
|
|
135
|
+
refToNodeId.set(schemaRef, schemaId);
|
|
67
136
|
const schemaDef = allSchemas[schemaName];
|
|
68
137
|
const schemaNode = makeNode('Schema', component, specPath, schemaId, undefined, {});
|
|
69
138
|
nodes.push(schemaNode);
|
|
@@ -71,20 +140,37 @@ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath
|
|
|
71
140
|
const localMappings = new Map();
|
|
72
141
|
for (const [fieldName, rawProp] of Object.entries(schemaDef?.properties ?? {})) {
|
|
73
142
|
const fieldId = `${schemaId}.fields.${fieldName}`;
|
|
143
|
+
const fieldRef = `${schemaRef}/properties/${fieldName}`;
|
|
144
|
+
if (!refToNodeId.has(fieldRef))
|
|
145
|
+
refToNodeId.set(fieldRef, fieldId);
|
|
74
146
|
const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
|
|
75
147
|
const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
|
|
76
|
-
fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings);
|
|
148
|
+
fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
|
|
77
149
|
nodes.push(fieldNode);
|
|
78
150
|
edges.push(makeHasFieldEdge(schemaId, fieldId));
|
|
79
151
|
}
|
|
152
|
+
// Register enum values as field refs so edges referencing them (as /properties/{value}) can resolve
|
|
153
|
+
if (Array.isArray(schemaDef?.enum)) {
|
|
154
|
+
for (const value of schemaDef.enum) {
|
|
155
|
+
if (typeof value !== 'string')
|
|
156
|
+
continue;
|
|
157
|
+
const fieldRef = `${schemaRef}/properties/${value}`;
|
|
158
|
+
if (!refToNodeId.has(fieldRef)) {
|
|
159
|
+
const fieldId = `${schemaId}.values.${value}`;
|
|
160
|
+
refToNodeId.set(fieldRef, fieldId);
|
|
161
|
+
nodes.push(makeNode('EnumValue', component, specPath, fieldId, undefined, { value }));
|
|
162
|
+
edges.push(makeHasFieldEdge(schemaId, fieldId));
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
}
|
|
80
166
|
return schemaId;
|
|
81
167
|
}
|
|
82
|
-
function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings) {
|
|
168
|
+
function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId) {
|
|
83
169
|
const nullable = !required;
|
|
84
170
|
if (typeof prop.$ref === 'string') {
|
|
85
171
|
const refName = schemaRefName(prop.$ref);
|
|
86
172
|
if (refName) {
|
|
87
|
-
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
173
|
+
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
88
174
|
return { $ref: refId, nullable, collection: 'one' };
|
|
89
175
|
}
|
|
90
176
|
return { type: 'string', nullable, collection: 'one' };
|
|
@@ -95,7 +181,7 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
|
|
|
95
181
|
if (items && typeof items.$ref === 'string') {
|
|
96
182
|
const refName = schemaRefName(items.$ref);
|
|
97
183
|
if (refName) {
|
|
98
|
-
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
184
|
+
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
99
185
|
return { $ref: refId, nullable, collection: 'array' };
|
|
100
186
|
}
|
|
101
187
|
}
|
|
@@ -103,13 +189,13 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
|
|
|
103
189
|
return { type: itemType, nullable, collection: 'array' };
|
|
104
190
|
}
|
|
105
191
|
if (type === 'object' && prop.additionalProperties !== undefined) {
|
|
106
|
-
createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings);
|
|
192
|
+
createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
|
|
107
193
|
return { $ref: `#/mappings/${fieldName}`, nullable, collection: 'one' };
|
|
108
194
|
}
|
|
109
195
|
const scalarType = mapScalar(type ?? 'string', prop.format);
|
|
110
196
|
return { type: scalarType, nullable, collection: 'one' };
|
|
111
197
|
}
|
|
112
|
-
function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings) {
|
|
198
|
+
function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId) {
|
|
113
199
|
const existing = localMappings.get(mappingName);
|
|
114
200
|
if (existing)
|
|
115
201
|
return existing;
|
|
@@ -125,7 +211,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
|
|
|
125
211
|
if (typeof addl.$ref === 'string') {
|
|
126
212
|
const refName = schemaRefName(addl.$ref);
|
|
127
213
|
if (refName) {
|
|
128
|
-
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
214
|
+
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
129
215
|
}
|
|
130
216
|
else {
|
|
131
217
|
props.type = 'string';
|
|
@@ -137,7 +223,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
|
|
|
137
223
|
if (items && typeof items.$ref === 'string') {
|
|
138
224
|
const refName = schemaRefName(items.$ref);
|
|
139
225
|
if (refName) {
|
|
140
|
-
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
226
|
+
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
141
227
|
}
|
|
142
228
|
else {
|
|
143
229
|
props.type = 'string';
|
|
@@ -149,7 +235,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
|
|
|
149
235
|
}
|
|
150
236
|
else if (addl.type === 'object' && addl.additionalProperties !== undefined) {
|
|
151
237
|
const innerName = `${mappingName}-values`;
|
|
152
|
-
props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings);
|
|
238
|
+
props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
|
|
153
239
|
}
|
|
154
240
|
else {
|
|
155
241
|
props.type = mapScalar(addl.type ?? 'string', addl.format);
|
package/dist/src/graph/index.js
CHANGED
|
@@ -1,14 +1,33 @@
|
|
|
1
1
|
import { QueryError } from '../schema/index.js';
|
|
2
|
+
export const STRUCTURAL_EDGE_TYPES = new Set(['has-field', 'has-value', 'renamed-from']);
|
|
3
|
+
export const STRUCTURAL_NODE_TEMPLATES = new Set(['Field', 'Schema', 'EnumDefinition', 'EnumValue', 'Mapping']);
|
|
4
|
+
export const SEMANTIC_EDGE_TYPES = new Set([
|
|
5
|
+
'triggers',
|
|
6
|
+
'produces',
|
|
7
|
+
'reads',
|
|
8
|
+
'calls',
|
|
9
|
+
'implements',
|
|
10
|
+
'maps-to',
|
|
11
|
+
'derived-from',
|
|
12
|
+
]);
|
|
2
13
|
export function listNodes(graph, filter = {}) {
|
|
3
14
|
return [...graph.nodesById.values()].filter(node => {
|
|
4
|
-
if (filter.
|
|
15
|
+
if (filter.templates?.length && !filter.templates.includes(node.template))
|
|
5
16
|
return false;
|
|
6
|
-
if (filter.
|
|
7
|
-
return false;
|
|
8
|
-
if (filter.state !== undefined && node.state !== filter.state)
|
|
17
|
+
if (filter.excludeTemplates?.length && filter.excludeTemplates.includes(node.template))
|
|
9
18
|
return false;
|
|
10
|
-
if (filter.
|
|
19
|
+
if (filter.component !== undefined && node.component !== filter.component)
|
|
11
20
|
return false;
|
|
21
|
+
if (filter.state !== undefined) {
|
|
22
|
+
const states = Array.isArray(filter.state) ? filter.state : [filter.state];
|
|
23
|
+
if (!states.includes(node.state))
|
|
24
|
+
return false;
|
|
25
|
+
}
|
|
26
|
+
if (filter.stability !== undefined) {
|
|
27
|
+
const stabilities = Array.isArray(filter.stability) ? filter.stability : [filter.stability];
|
|
28
|
+
if (!stabilities.includes(node.stability))
|
|
29
|
+
return false;
|
|
30
|
+
}
|
|
12
31
|
return true;
|
|
13
32
|
});
|
|
14
33
|
}
|
|
@@ -106,6 +125,17 @@ export function getLinkedFields(graph, nodeId) {
|
|
|
106
125
|
.filter((node) => node !== undefined),
|
|
107
126
|
};
|
|
108
127
|
}
|
|
128
|
+
function findParent(graph, nodeId) {
|
|
129
|
+
const parts = nodeId.split('.');
|
|
130
|
+
let endIdx = parts.length - 2;
|
|
131
|
+
while (endIdx >= 1) {
|
|
132
|
+
const candidateId = parts.slice(0, endIdx).join('.');
|
|
133
|
+
if (graph.nodesById.has(candidateId))
|
|
134
|
+
return candidateId;
|
|
135
|
+
endIdx -= 2;
|
|
136
|
+
}
|
|
137
|
+
return undefined;
|
|
138
|
+
}
|
|
109
139
|
function collectMapsTo(edge, edges, nodeIds, seen) {
|
|
110
140
|
if (edge.type !== 'maps-to' || seen.has(edge.id))
|
|
111
141
|
return;
|
|
@@ -149,3 +179,261 @@ export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRoo
|
|
|
149
179
|
});
|
|
150
180
|
return fields.length === 0 ? null : { viewingRef, overlayRefs, fields };
|
|
151
181
|
}
|
|
182
|
+
export function getGraphSummary(graph) {
|
|
183
|
+
const components = new Set();
|
|
184
|
+
for (const node of graph.nodesById.values()) {
|
|
185
|
+
if (node.component)
|
|
186
|
+
components.add(node.component);
|
|
187
|
+
}
|
|
188
|
+
const nodesWithEdges = new Set();
|
|
189
|
+
const edgesByType = {};
|
|
190
|
+
for (const edgeList of graph.edgesByFrom.values()) {
|
|
191
|
+
for (const edge of edgeList) {
|
|
192
|
+
if (!SEMANTIC_EDGE_TYPES.has(edge.type))
|
|
193
|
+
continue;
|
|
194
|
+
edgesByType[edge.type] = (edgesByType[edge.type] ?? 0) + 1;
|
|
195
|
+
nodesWithEdges.add(edge.from);
|
|
196
|
+
nodesWithEdges.add(edge.to);
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
const orphansByTemplate = {};
|
|
200
|
+
for (const node of graph.nodesById.values()) {
|
|
201
|
+
if (nodesWithEdges.has(node.id))
|
|
202
|
+
continue;
|
|
203
|
+
if (findParent(graph, node.id) !== undefined)
|
|
204
|
+
continue;
|
|
205
|
+
orphansByTemplate[node.template] = (orphansByTemplate[node.template] ?? 0) + 1;
|
|
206
|
+
}
|
|
207
|
+
return {
|
|
208
|
+
nodeCount: graph.nodesById.size,
|
|
209
|
+
componentCount: components.size,
|
|
210
|
+
orphanNodeCount: Object.values(orphansByTemplate).reduce((sum, count) => sum + count, 0),
|
|
211
|
+
orphansByTemplate,
|
|
212
|
+
edgesByType,
|
|
213
|
+
diagnosticCount: graph.diagnostics.length,
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
function fuzzyScore(query, target) {
|
|
217
|
+
const q = query.toLowerCase();
|
|
218
|
+
const s = target.toLowerCase();
|
|
219
|
+
let qi = 0;
|
|
220
|
+
let run = 0;
|
|
221
|
+
let maxRun = 0;
|
|
222
|
+
for (let i = 0; i < s.length; i++) {
|
|
223
|
+
if (qi >= q.length)
|
|
224
|
+
break;
|
|
225
|
+
if (s[i] === q[qi]) {
|
|
226
|
+
qi++;
|
|
227
|
+
run++;
|
|
228
|
+
if (run > maxRun)
|
|
229
|
+
maxRun = run;
|
|
230
|
+
}
|
|
231
|
+
else {
|
|
232
|
+
run = 0;
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
return qi === q.length ? maxRun : null;
|
|
236
|
+
}
|
|
237
|
+
export function searchNodes(graph, queries, options = {}) {
|
|
238
|
+
const { templates, excludeTemplates, limit = 10, offset = 0, searchProperties = false } = options;
|
|
239
|
+
const terms = queries.map(query => query.trim()).filter(Boolean);
|
|
240
|
+
if (terms.length === 0)
|
|
241
|
+
return [];
|
|
242
|
+
const results = [];
|
|
243
|
+
for (const node of graph.nodesById.values()) {
|
|
244
|
+
if (findParent(graph, node.id) !== undefined)
|
|
245
|
+
continue;
|
|
246
|
+
if (templates?.length && !templates.includes(node.template))
|
|
247
|
+
continue;
|
|
248
|
+
if (excludeTemplates?.length && excludeTemplates.includes(node.template))
|
|
249
|
+
continue;
|
|
250
|
+
let bestScore = 0;
|
|
251
|
+
for (const term of terms) {
|
|
252
|
+
const score = fuzzyScore(term, node.id);
|
|
253
|
+
if (score !== null && score > bestScore)
|
|
254
|
+
bestScore = score;
|
|
255
|
+
if (searchProperties) {
|
|
256
|
+
const propertyText = [node.properties.name, node.properties.description, node.properties['x-aka']]
|
|
257
|
+
.filter((value) => typeof value === 'string')
|
|
258
|
+
.join(' ');
|
|
259
|
+
if (propertyText) {
|
|
260
|
+
const propertyScore = fuzzyScore(term, propertyText);
|
|
261
|
+
if (propertyScore !== null && propertyScore > bestScore)
|
|
262
|
+
bestScore = propertyScore;
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
if (bestScore > 0)
|
|
267
|
+
results.push({ node, score: bestScore });
|
|
268
|
+
}
|
|
269
|
+
results.sort((a, b) => b.score - a.score || a.node.id.length - b.node.id.length);
|
|
270
|
+
return results.slice(offset, offset + limit);
|
|
271
|
+
}
|
|
272
|
+
export function getLineage(graph, startNodeIds, options = {}) {
|
|
273
|
+
const { depth = 2, direction = 'downstream', readsOutboundOnly = true, includeDanglingEdges = false, } = options;
|
|
274
|
+
const defaultEdgeTypes = new Set();
|
|
275
|
+
for (const edgeList of graph.edgesByFrom.values()) {
|
|
276
|
+
for (const edge of edgeList) {
|
|
277
|
+
if (!STRUCTURAL_EDGE_TYPES.has(edge.type))
|
|
278
|
+
defaultEdgeTypes.add(edge.type);
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
const edgeTypeSet = options.edgeTypes ? new Set(options.edgeTypes) : defaultEdgeTypes;
|
|
282
|
+
const inboundTypeSet = new Set([...edgeTypeSet].filter(type => !(readsOutboundOnly && type === 'reads')));
|
|
283
|
+
const useAllowlist = (options.nodeTypes?.length ?? 0) > 0;
|
|
284
|
+
const allowedTemplates = useAllowlist ? new Set(options.nodeTypes) : null;
|
|
285
|
+
const excludedTemplates = useAllowlist
|
|
286
|
+
? null
|
|
287
|
+
: options.excludeNodeTypes?.length
|
|
288
|
+
? new Set(options.excludeNodeTypes)
|
|
289
|
+
: STRUCTURAL_NODE_TEMPLATES;
|
|
290
|
+
function isIncluded(node) {
|
|
291
|
+
if (allowedTemplates)
|
|
292
|
+
return allowedTemplates.has(node.template);
|
|
293
|
+
if (excludedTemplates)
|
|
294
|
+
return !excludedTemplates.has(node.template);
|
|
295
|
+
return true;
|
|
296
|
+
}
|
|
297
|
+
const annotations = new Map();
|
|
298
|
+
const originSets = new Map();
|
|
299
|
+
function tryRecord(nodeId, originId, resultDepth, viaEdgeType, viaNodeId, dir) {
|
|
300
|
+
const previous = annotations.get(nodeId);
|
|
301
|
+
if (previous && previous.depth <= resultDepth) {
|
|
302
|
+
originSets.get(nodeId)?.add(originId);
|
|
303
|
+
return previous.depth < resultDepth;
|
|
304
|
+
}
|
|
305
|
+
annotations.set(nodeId, { originId, depth: resultDepth, viaEdgeType, viaNodeId, dir });
|
|
306
|
+
if (!originSets.has(nodeId))
|
|
307
|
+
originSets.set(nodeId, new Set());
|
|
308
|
+
originSets.get(nodeId)?.add(originId);
|
|
309
|
+
return true;
|
|
310
|
+
}
|
|
311
|
+
const validStartIds = startNodeIds.filter(id => graph.nodesById.has(id));
|
|
312
|
+
const startSet = new Set(validStartIds);
|
|
313
|
+
function runDownstream() {
|
|
314
|
+
const visited = new Set(startSet);
|
|
315
|
+
const queue = validStartIds.map(id => ({ id, originId: id, distance: 0 }));
|
|
316
|
+
while (queue.length > 0) {
|
|
317
|
+
const current = queue.shift();
|
|
318
|
+
if (!current)
|
|
319
|
+
continue;
|
|
320
|
+
if (current.distance >= depth)
|
|
321
|
+
continue;
|
|
322
|
+
for (const edge of graph.edgesByFrom.get(current.id) ?? []) {
|
|
323
|
+
if (!edgeTypeSet.has(edge.type))
|
|
324
|
+
continue;
|
|
325
|
+
const node = graph.nodesById.get(edge.to);
|
|
326
|
+
if (!node || !isIncluded(node))
|
|
327
|
+
continue;
|
|
328
|
+
if (visited.has(edge.to)) {
|
|
329
|
+
originSets.get(edge.to)?.add(current.originId);
|
|
330
|
+
continue;
|
|
331
|
+
}
|
|
332
|
+
visited.add(edge.to);
|
|
333
|
+
tryRecord(edge.to, current.originId, current.distance + 1, edge.type, current.id, 'downstream');
|
|
334
|
+
queue.push({ id: edge.to, originId: current.originId, distance: current.distance + 1 });
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
function runUpstream() {
|
|
339
|
+
const visited = new Set(startSet);
|
|
340
|
+
const queue = validStartIds.map(id => ({ id, originId: id, distance: 0 }));
|
|
341
|
+
while (queue.length > 0) {
|
|
342
|
+
const current = queue.shift();
|
|
343
|
+
if (!current)
|
|
344
|
+
continue;
|
|
345
|
+
if (current.distance >= depth)
|
|
346
|
+
continue;
|
|
347
|
+
for (const edge of graph.edgesByTo.get(current.id) ?? []) {
|
|
348
|
+
if (!inboundTypeSet.has(edge.type))
|
|
349
|
+
continue;
|
|
350
|
+
const node = graph.nodesById.get(edge.from);
|
|
351
|
+
if (!node || !isIncluded(node))
|
|
352
|
+
continue;
|
|
353
|
+
if (visited.has(edge.from)) {
|
|
354
|
+
originSets.get(edge.from)?.add(current.originId);
|
|
355
|
+
continue;
|
|
356
|
+
}
|
|
357
|
+
visited.add(edge.from);
|
|
358
|
+
tryRecord(edge.from, current.originId, current.distance + 1, edge.type, current.id, 'upstream');
|
|
359
|
+
queue.push({ id: edge.from, originId: current.originId, distance: current.distance + 1 });
|
|
360
|
+
}
|
|
361
|
+
const parentId = findParent(graph, current.id);
|
|
362
|
+
if (parentId) {
|
|
363
|
+
const parentNode = graph.nodesById.get(parentId);
|
|
364
|
+
if (!parentNode || !isIncluded(parentNode))
|
|
365
|
+
continue;
|
|
366
|
+
if (visited.has(parentId)) {
|
|
367
|
+
originSets.get(parentId)?.add(current.originId);
|
|
368
|
+
continue;
|
|
369
|
+
}
|
|
370
|
+
visited.add(parentId);
|
|
371
|
+
tryRecord(parentId, current.originId, current.distance + 1, 'parent', current.id, 'upstream');
|
|
372
|
+
queue.push({ id: parentId, originId: current.originId, distance: current.distance + 1 });
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
}
|
|
376
|
+
if (direction === 'downstream' || direction === 'both')
|
|
377
|
+
runDownstream();
|
|
378
|
+
if (direction === 'upstream' || direction === 'both')
|
|
379
|
+
runUpstream();
|
|
380
|
+
const resultNodeIds = new Set(annotations.keys());
|
|
381
|
+
const combinedSet = new Set([...startSet, ...resultNodeIds]);
|
|
382
|
+
const edges = [];
|
|
383
|
+
const seenEdgeIds = new Set();
|
|
384
|
+
for (const id of combinedSet) {
|
|
385
|
+
for (const edge of graph.edgesByFrom.get(id) ?? []) {
|
|
386
|
+
if (seenEdgeIds.has(edge.id) || !edgeTypeSet.has(edge.type))
|
|
387
|
+
continue;
|
|
388
|
+
if (combinedSet.has(edge.from) && combinedSet.has(edge.to)) {
|
|
389
|
+
edges.push(edge);
|
|
390
|
+
seenEdgeIds.add(edge.id);
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
}
|
|
394
|
+
const nodesWithEdges = new Set();
|
|
395
|
+
for (const edge of edges) {
|
|
396
|
+
nodesWithEdges.add(edge.from);
|
|
397
|
+
nodesWithEdges.add(edge.to);
|
|
398
|
+
}
|
|
399
|
+
const prunedIds = new Set([...resultNodeIds].filter(id => nodesWithEdges.has(id)));
|
|
400
|
+
let danglingEdges;
|
|
401
|
+
if (includeDanglingEdges) {
|
|
402
|
+
danglingEdges = [];
|
|
403
|
+
const danglingSeenIds = new Set();
|
|
404
|
+
for (const id of prunedIds) {
|
|
405
|
+
for (const edge of [...(graph.edgesByFrom.get(id) ?? []), ...(graph.edgesByTo.get(id) ?? [])]) {
|
|
406
|
+
if (danglingSeenIds.has(edge.id) || seenEdgeIds.has(edge.id))
|
|
407
|
+
continue;
|
|
408
|
+
if (!edgeTypeSet.has(edge.type))
|
|
409
|
+
continue;
|
|
410
|
+
const otherId = edge.from === id ? edge.to : edge.from;
|
|
411
|
+
if (!combinedSet.has(otherId)) {
|
|
412
|
+
danglingEdges.push(edge);
|
|
413
|
+
danglingSeenIds.add(edge.id);
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
const nodes = [...prunedIds].map(id => {
|
|
419
|
+
const node = graph.nodesById.get(id);
|
|
420
|
+
const annotation = annotations.get(id);
|
|
421
|
+
const origins = [...(originSets.get(id) ?? [])];
|
|
422
|
+
const result = {
|
|
423
|
+
...node,
|
|
424
|
+
origin_id: annotation.originId,
|
|
425
|
+
depth: annotation.depth,
|
|
426
|
+
via_edge_type: annotation.viaEdgeType,
|
|
427
|
+
via_node_id: annotation.viaNodeId,
|
|
428
|
+
};
|
|
429
|
+
if (origins.length > 1)
|
|
430
|
+
result.origins = origins;
|
|
431
|
+
if (direction === 'both')
|
|
432
|
+
result.direction = annotation.dir;
|
|
433
|
+
return result;
|
|
434
|
+
});
|
|
435
|
+
const result = { nodes, edges };
|
|
436
|
+
if (danglingEdges !== undefined)
|
|
437
|
+
result.dangling_edges = danglingEdges;
|
|
438
|
+
return result;
|
|
439
|
+
}
|