@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 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.
@@ -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
- edges.push(mapEdge(raw));
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 expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded) {
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
- const schemaId = `${rootNodeId}.schemas.${schemaName}`;
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);
@@ -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,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
+ }