@atolis-hq/corum 0.1.34 → 0.1.36

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
@@ -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, optionally filtered by `template`, `component`, `state`, or `stability` |
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 owned children, and internal edges |
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.
@@ -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.template !== undefined && node.template !== filter.template)
15
+ if (filter.templates?.length && !filter.templates.includes(node.template))
5
16
  return false;
6
- if (filter.component !== undefined && node.component !== filter.component)
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.stability !== undefined && node.stability !== filter.stability)
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,274 @@ 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
+ const nodesByComponent = {};
185
+ const nodesByTemplate = {};
186
+ const nodesByState = {};
187
+ const nodesByStability = {};
188
+ for (const node of graph.nodesById.values()) {
189
+ if (node.component) {
190
+ components.add(node.component);
191
+ nodesByComponent[node.component] = (nodesByComponent[node.component] ?? 0) + 1;
192
+ }
193
+ nodesByTemplate[node.template] = (nodesByTemplate[node.template] ?? 0) + 1;
194
+ nodesByState[node.state] = (nodesByState[node.state] ?? 0) + 1;
195
+ nodesByStability[node.stability] = (nodesByStability[node.stability] ?? 0) + 1;
196
+ }
197
+ const nodesWithEdges = new Set();
198
+ const edgesByType = {};
199
+ for (const edgeList of graph.edgesByFrom.values()) {
200
+ for (const edge of edgeList) {
201
+ if (!SEMANTIC_EDGE_TYPES.has(edge.type))
202
+ continue;
203
+ edgesByType[edge.type] = (edgesByType[edge.type] ?? 0) + 1;
204
+ nodesWithEdges.add(edge.from);
205
+ nodesWithEdges.add(edge.to);
206
+ }
207
+ }
208
+ const orphansByTemplate = {};
209
+ for (const node of graph.nodesById.values()) {
210
+ if (nodesWithEdges.has(node.id))
211
+ continue;
212
+ if (findParent(graph, node.id) !== undefined)
213
+ continue;
214
+ orphansByTemplate[node.template] = (orphansByTemplate[node.template] ?? 0) + 1;
215
+ }
216
+ return {
217
+ nodeCount: graph.nodesById.size,
218
+ componentCount: components.size,
219
+ nodesByComponent,
220
+ nodesByTemplate,
221
+ nodesByState,
222
+ nodesByStability,
223
+ orphanNodeCount: Object.values(orphansByTemplate).reduce((sum, count) => sum + count, 0),
224
+ orphansByTemplate,
225
+ edgesByType,
226
+ diagnosticCount: graph.diagnostics.length,
227
+ };
228
+ }
229
+ function fuzzyScore(query, target) {
230
+ const q = query.toLowerCase();
231
+ const s = target.toLowerCase();
232
+ let qi = 0;
233
+ let run = 0;
234
+ let maxRun = 0;
235
+ for (let i = 0; i < s.length; i++) {
236
+ if (qi >= q.length)
237
+ break;
238
+ if (s[i] === q[qi]) {
239
+ qi++;
240
+ run++;
241
+ if (run > maxRun)
242
+ maxRun = run;
243
+ }
244
+ else {
245
+ run = 0;
246
+ }
247
+ }
248
+ return qi === q.length ? maxRun : null;
249
+ }
250
+ export function searchNodes(graph, queries, options = {}) {
251
+ const { templates, excludeTemplates, limit = 10, offset = 0, searchProperties = false } = options;
252
+ const terms = queries.map(query => query.trim()).filter(Boolean);
253
+ if (terms.length === 0)
254
+ return [];
255
+ const results = [];
256
+ for (const node of graph.nodesById.values()) {
257
+ if (findParent(graph, node.id) !== undefined)
258
+ continue;
259
+ if (templates?.length && !templates.includes(node.template))
260
+ continue;
261
+ if (excludeTemplates?.length && excludeTemplates.includes(node.template))
262
+ continue;
263
+ let bestScore = 0;
264
+ for (const term of terms) {
265
+ const score = fuzzyScore(term, node.id);
266
+ if (score !== null && score > bestScore)
267
+ bestScore = score;
268
+ if (searchProperties) {
269
+ const propertyText = [node.properties.name, node.properties.description, node.properties['x-aka']]
270
+ .filter((value) => typeof value === 'string')
271
+ .join(' ');
272
+ if (propertyText) {
273
+ const propertyScore = fuzzyScore(term, propertyText);
274
+ if (propertyScore !== null && propertyScore > bestScore)
275
+ bestScore = propertyScore;
276
+ }
277
+ }
278
+ }
279
+ if (bestScore > 0)
280
+ results.push({ node, score: bestScore });
281
+ }
282
+ results.sort((a, b) => b.score - a.score || a.node.id.length - b.node.id.length);
283
+ return results.slice(offset, offset + limit);
284
+ }
285
+ export function getLineage(graph, startNodeIds, options = {}) {
286
+ const { depth = 2, direction = 'downstream', readsOutboundOnly = true, includeDanglingEdges = false, } = options;
287
+ const defaultEdgeTypes = new Set();
288
+ for (const edgeList of graph.edgesByFrom.values()) {
289
+ for (const edge of edgeList) {
290
+ if (!STRUCTURAL_EDGE_TYPES.has(edge.type))
291
+ defaultEdgeTypes.add(edge.type);
292
+ }
293
+ }
294
+ const edgeTypeSet = options.edgeTypes ? new Set(options.edgeTypes) : defaultEdgeTypes;
295
+ const inboundTypeSet = new Set([...edgeTypeSet].filter(type => !(readsOutboundOnly && type === 'reads')));
296
+ const useAllowlist = (options.nodeTypes?.length ?? 0) > 0;
297
+ const allowedTemplates = useAllowlist ? new Set(options.nodeTypes) : null;
298
+ const excludedTemplates = useAllowlist
299
+ ? null
300
+ : options.excludeNodeTypes?.length
301
+ ? new Set(options.excludeNodeTypes)
302
+ : STRUCTURAL_NODE_TEMPLATES;
303
+ function isIncluded(node) {
304
+ if (allowedTemplates)
305
+ return allowedTemplates.has(node.template);
306
+ if (excludedTemplates)
307
+ return !excludedTemplates.has(node.template);
308
+ return true;
309
+ }
310
+ const annotations = new Map();
311
+ const originSets = new Map();
312
+ function tryRecord(nodeId, originId, resultDepth, viaEdgeType, viaNodeId, dir) {
313
+ const previous = annotations.get(nodeId);
314
+ if (previous && previous.depth <= resultDepth) {
315
+ originSets.get(nodeId)?.add(originId);
316
+ return previous.depth < resultDepth;
317
+ }
318
+ annotations.set(nodeId, { originId, depth: resultDepth, viaEdgeType, viaNodeId, dir });
319
+ if (!originSets.has(nodeId))
320
+ originSets.set(nodeId, new Set());
321
+ originSets.get(nodeId)?.add(originId);
322
+ return true;
323
+ }
324
+ const validStartIds = startNodeIds.filter(id => graph.nodesById.has(id));
325
+ const startSet = new Set(validStartIds);
326
+ function runDownstream() {
327
+ const visited = new Set(startSet);
328
+ const queue = validStartIds.map(id => ({ id, originId: id, distance: 0 }));
329
+ while (queue.length > 0) {
330
+ const current = queue.shift();
331
+ if (!current)
332
+ continue;
333
+ if (current.distance >= depth)
334
+ continue;
335
+ for (const edge of graph.edgesByFrom.get(current.id) ?? []) {
336
+ if (!edgeTypeSet.has(edge.type))
337
+ continue;
338
+ const node = graph.nodesById.get(edge.to);
339
+ if (!node || !isIncluded(node))
340
+ continue;
341
+ if (visited.has(edge.to)) {
342
+ originSets.get(edge.to)?.add(current.originId);
343
+ continue;
344
+ }
345
+ visited.add(edge.to);
346
+ tryRecord(edge.to, current.originId, current.distance + 1, edge.type, current.id, 'downstream');
347
+ queue.push({ id: edge.to, originId: current.originId, distance: current.distance + 1 });
348
+ }
349
+ }
350
+ }
351
+ function runUpstream() {
352
+ const visited = new Set(startSet);
353
+ const queue = validStartIds.map(id => ({ id, originId: id, distance: 0 }));
354
+ while (queue.length > 0) {
355
+ const current = queue.shift();
356
+ if (!current)
357
+ continue;
358
+ if (current.distance >= depth)
359
+ continue;
360
+ for (const edge of graph.edgesByTo.get(current.id) ?? []) {
361
+ if (!inboundTypeSet.has(edge.type))
362
+ continue;
363
+ const node = graph.nodesById.get(edge.from);
364
+ if (!node || !isIncluded(node))
365
+ continue;
366
+ if (visited.has(edge.from)) {
367
+ originSets.get(edge.from)?.add(current.originId);
368
+ continue;
369
+ }
370
+ visited.add(edge.from);
371
+ tryRecord(edge.from, current.originId, current.distance + 1, edge.type, current.id, 'upstream');
372
+ queue.push({ id: edge.from, originId: current.originId, distance: current.distance + 1 });
373
+ }
374
+ const parentId = findParent(graph, current.id);
375
+ if (parentId) {
376
+ const parentNode = graph.nodesById.get(parentId);
377
+ if (!parentNode || !isIncluded(parentNode))
378
+ continue;
379
+ if (visited.has(parentId)) {
380
+ originSets.get(parentId)?.add(current.originId);
381
+ continue;
382
+ }
383
+ visited.add(parentId);
384
+ tryRecord(parentId, current.originId, current.distance + 1, 'parent', current.id, 'upstream');
385
+ queue.push({ id: parentId, originId: current.originId, distance: current.distance + 1 });
386
+ }
387
+ }
388
+ }
389
+ if (direction === 'downstream' || direction === 'both')
390
+ runDownstream();
391
+ if (direction === 'upstream' || direction === 'both')
392
+ runUpstream();
393
+ const resultNodeIds = new Set(annotations.keys());
394
+ const combinedSet = new Set([...startSet, ...resultNodeIds]);
395
+ const edges = [];
396
+ const seenEdgeIds = new Set();
397
+ for (const id of combinedSet) {
398
+ for (const edge of graph.edgesByFrom.get(id) ?? []) {
399
+ if (seenEdgeIds.has(edge.id) || !edgeTypeSet.has(edge.type))
400
+ continue;
401
+ if (combinedSet.has(edge.from) && combinedSet.has(edge.to)) {
402
+ edges.push(edge);
403
+ seenEdgeIds.add(edge.id);
404
+ }
405
+ }
406
+ }
407
+ const nodesWithEdges = new Set();
408
+ for (const edge of edges) {
409
+ nodesWithEdges.add(edge.from);
410
+ nodesWithEdges.add(edge.to);
411
+ }
412
+ const prunedIds = new Set([...resultNodeIds].filter(id => nodesWithEdges.has(id)));
413
+ let danglingEdges;
414
+ if (includeDanglingEdges) {
415
+ danglingEdges = [];
416
+ const danglingSeenIds = new Set();
417
+ for (const id of prunedIds) {
418
+ for (const edge of [...(graph.edgesByFrom.get(id) ?? []), ...(graph.edgesByTo.get(id) ?? [])]) {
419
+ if (danglingSeenIds.has(edge.id) || seenEdgeIds.has(edge.id))
420
+ continue;
421
+ if (!edgeTypeSet.has(edge.type))
422
+ continue;
423
+ const otherId = edge.from === id ? edge.to : edge.from;
424
+ if (!combinedSet.has(otherId)) {
425
+ danglingEdges.push(edge);
426
+ danglingSeenIds.add(edge.id);
427
+ }
428
+ }
429
+ }
430
+ }
431
+ const nodes = [...prunedIds].map(id => {
432
+ const node = graph.nodesById.get(id);
433
+ const annotation = annotations.get(id);
434
+ const origins = [...(originSets.get(id) ?? [])];
435
+ const result = {
436
+ ...node,
437
+ origin_id: annotation.originId,
438
+ depth: annotation.depth,
439
+ via_edge_type: annotation.viaEdgeType,
440
+ via_node_id: annotation.viaNodeId,
441
+ };
442
+ if (origins.length > 1)
443
+ result.origins = origins;
444
+ if (direction === 'both')
445
+ result.direction = annotation.dir;
446
+ return result;
447
+ });
448
+ const result = { nodes, edges };
449
+ if (danglingEdges !== undefined)
450
+ result.dangling_edges = danglingEdges;
451
+ return result;
452
+ }