@atolis-hq/corum 0.1.37 → 0.1.39
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 +2 -2
- package/dist/src/adapters/corum/mapper.js +307 -72
- package/dist/src/graph/index.js +77 -35
- package/dist/src/graph/schema-collapse.js +188 -0
- package/dist/src/mcp/index.js +96 -23
- package/dist/src/mcp/prompts/usage-guide.js +7 -2
- package/dist/src/web/server.js +14 -2
- package/package.json +1 -1
- package/web/app.jsx +6 -2
- package/web/primitives.jsx +2 -1
package/README.md
CHANGED
|
@@ -301,7 +301,7 @@ Or if installed globally:
|
|
|
301
301
|
| `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |
|
|
302
302
|
| `list_templates` | List loaded templates with summary metadata |
|
|
303
303
|
| `get_template` | Return full details for a template |
|
|
304
|
-
| `get_cluster` | Return a
|
|
304
|
+
| `get_cluster` | Return a node's structural contents. By default, schema and enum child nodes are collapsed into compact `schemas` and `enums` blocks on the root. Pass `collapse_schemas: false` to restore the full node-per-field representation |
|
|
305
305
|
| `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |
|
|
306
306
|
| `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |
|
|
307
307
|
| `get_lineage` | Traverse lineage from one or more start nodes. Lean nodes and no `edges` by default; opt in to fuller payloads when needed |
|
|
@@ -324,7 +324,7 @@ Common notes:
|
|
|
324
324
|
- `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.
|
|
325
325
|
- `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.
|
|
326
326
|
- Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
|
|
327
|
-
- Use `get_cluster` only when you need full structural contents for one node
|
|
327
|
+
- Use `get_cluster` only when you need full structural contents for one node. By default it returns compact `schemas` and `enums` blocks on the root rather than individual field nodes, which keeps response size manageable for large aggregates. Use `get_lineage` for relationship traversal.
|
|
328
328
|
- 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.
|
|
329
329
|
|
|
330
330
|
## MCP Prompts
|
|
@@ -2,6 +2,7 @@ const VALID_EDGE_TYPES = new Set([
|
|
|
2
2
|
'triggers', 'produces', 'reads', 'calls', 'implements',
|
|
3
3
|
'maps-to', 'derived-from', 'renamed-from', 'has-field', 'has-value',
|
|
4
4
|
]);
|
|
5
|
+
const UNRESOLVED_COMPONENT = '_unresolved';
|
|
5
6
|
export function mapDocument(document, specPath) {
|
|
6
7
|
const nodes = [];
|
|
7
8
|
const edges = [];
|
|
@@ -9,6 +10,10 @@ export function mapDocument(document, specPath) {
|
|
|
9
10
|
const allSchemas = (document.components?.schemas ?? {});
|
|
10
11
|
// Maps #/components/schemas/X and #/components/schemas/X/properties/Y to materialized node IDs
|
|
11
12
|
const refToNodeId = new Map();
|
|
13
|
+
const rootNodeIds = getRootNodeIds(document.nodes);
|
|
14
|
+
// Pre-pass: determine canonical component for each schema (shared if referenced by 2+ components)
|
|
15
|
+
const schemaComponents = computeSchemaComponents(document, allSchemas);
|
|
16
|
+
const schemaUsage = computeSchemaUsage(document, allSchemas, rootNodeIds);
|
|
12
17
|
for (const gap of document.gaps ?? []) {
|
|
13
18
|
const msg = gap.nodeId
|
|
14
19
|
? `[${gap.kind}] ${gap.nodeId}: ${gap.reason ?? ''}`
|
|
@@ -20,7 +25,8 @@ export function mapDocument(document, specPath) {
|
|
|
20
25
|
diagnostics.push({ severity: 'warning', file: specPath, message: 'Node missing id or type — skipping' });
|
|
21
26
|
continue;
|
|
22
27
|
}
|
|
23
|
-
const
|
|
28
|
+
const normalizedNodeId = normalizeNodeId(nodeId);
|
|
29
|
+
const component = componentFromNodeId(normalizedNodeId);
|
|
24
30
|
const properties = {};
|
|
25
31
|
let schemaName;
|
|
26
32
|
if (entry.schema?.$ref) {
|
|
@@ -34,50 +40,40 @@ export function mapDocument(document, specPath) {
|
|
|
34
40
|
if (entry['x-aka']?.length) {
|
|
35
41
|
properties['x-aka'] = entry['x-aka'];
|
|
36
42
|
}
|
|
37
|
-
const node = makeNode(entry.type, component, specPath,
|
|
43
|
+
const node = makeNode(entry.type, component, specPath, normalizedNodeId, entry.provenance, properties);
|
|
38
44
|
nodes.push(node);
|
|
39
45
|
if (schemaName) {
|
|
40
46
|
const expanded = new Map();
|
|
41
|
-
expandSchema(schemaName,
|
|
47
|
+
expandSchema(schemaName, normalizedNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
|
|
42
48
|
}
|
|
43
49
|
}
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
}
|
|
50
|
+
for (const schemaName of Object.keys(allSchemas)) {
|
|
51
|
+
const schemaRef = `#/components/schemas/${schemaName}`;
|
|
52
|
+
if (refToNodeId.has(schemaRef))
|
|
53
|
+
continue;
|
|
54
|
+
const ownership = determineSchemaOwnership(schemaName, schemaUsage);
|
|
55
|
+
if (ownership.kind === 'unused') {
|
|
56
|
+
diagnostics.push({
|
|
57
|
+
severity: 'warning',
|
|
58
|
+
file: specPath,
|
|
59
|
+
message: `Skipping unused schema '${schemaName}' because no node or edge refers to it`,
|
|
60
|
+
});
|
|
61
|
+
continue;
|
|
80
62
|
}
|
|
63
|
+
if (ownership.kind === 'unresolved') {
|
|
64
|
+
diagnostics.push({
|
|
65
|
+
severity: 'warning',
|
|
66
|
+
file: specPath,
|
|
67
|
+
message: `Schema '${schemaName}' is only referenced by unresolved schema edges; keeping it under ${UNRESOLVED_COMPONENT}`,
|
|
68
|
+
});
|
|
69
|
+
materializeStandaloneSchema(schemaName, UNRESOLVED_COMPONENT, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents);
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
if (ownership.kind === 'inline') {
|
|
73
|
+
expandSchema(schemaName, ownership.rootNodeId, allSchemas, nodes, edges, specPath, ownership.component, new Map(), refToNodeId, schemaComponents);
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
materializeStandaloneSchema(schemaName, ownership.component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents);
|
|
81
77
|
}
|
|
82
78
|
// Build case-insensitive fallback index to handle PascalCase/camelCase mismatches
|
|
83
79
|
// between edge field refs and actual schema property names
|
|
@@ -91,8 +87,8 @@ export function mapDocument(document, specPath) {
|
|
|
91
87
|
});
|
|
92
88
|
continue;
|
|
93
89
|
}
|
|
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;
|
|
90
|
+
const from = refToNodeId.get(raw.from) ?? refToNodeIdLower.get(raw.from.toLowerCase()) ?? normalizeNodeId(raw.from);
|
|
91
|
+
const to = refToNodeId.get(raw.to) ?? refToNodeIdLower.get(raw.to.toLowerCase()) ?? normalizeNodeId(raw.to);
|
|
96
92
|
if (from.startsWith('#/') || to.startsWith('#/')) {
|
|
97
93
|
diagnostics.push({
|
|
98
94
|
severity: 'warning',
|
|
@@ -105,6 +101,153 @@ export function mapDocument(document, specPath) {
|
|
|
105
101
|
}
|
|
106
102
|
return { nodes, edges, diagnostics };
|
|
107
103
|
}
|
|
104
|
+
// Pre-pass: walk every node's schema tree to determine which component each schema belongs to.
|
|
105
|
+
// If a schema is referenced by nodes in 2+ different components it is assigned 'shared'.
|
|
106
|
+
function computeSchemaComponents(document, allSchemas) {
|
|
107
|
+
const result = new Map();
|
|
108
|
+
for (const [nodeId, entry] of Object.entries(document.nodes)) {
|
|
109
|
+
const rootName = entry.schema?.$ref ? schemaRefName(entry.schema.$ref) : undefined;
|
|
110
|
+
if (!rootName)
|
|
111
|
+
continue;
|
|
112
|
+
const component = componentFromNodeId(normalizeNodeId(nodeId));
|
|
113
|
+
const visited = new Set();
|
|
114
|
+
collectSchemaRefNames(rootName, allSchemas, visited);
|
|
115
|
+
for (const name of visited) {
|
|
116
|
+
const existing = result.get(name);
|
|
117
|
+
if (!existing)
|
|
118
|
+
result.set(name, component);
|
|
119
|
+
else if (existing !== component)
|
|
120
|
+
result.set(name, 'shared');
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
return result;
|
|
124
|
+
}
|
|
125
|
+
function getRootNodeIds(nodes) {
|
|
126
|
+
const nodeIds = Object.keys(nodes).map(normalizeNodeId);
|
|
127
|
+
return nodeIds
|
|
128
|
+
.filter(nodeId => !nodeIds.some(other => other !== nodeId && nodeId.startsWith(`${other}.`)))
|
|
129
|
+
.sort((a, b) => b.length - a.length);
|
|
130
|
+
}
|
|
131
|
+
function computeSchemaUsage(document, allSchemas, rootNodeIds) {
|
|
132
|
+
const usage = {
|
|
133
|
+
rootsBySchema: new Map(),
|
|
134
|
+
directEdgeSchemas: new Set(),
|
|
135
|
+
};
|
|
136
|
+
const schemaLinks = new Map();
|
|
137
|
+
for (const [nodeId, entry] of Object.entries(document.nodes)) {
|
|
138
|
+
const rootName = entry.schema?.$ref ? schemaRefName(entry.schema.$ref) : undefined;
|
|
139
|
+
if (!rootName)
|
|
140
|
+
continue;
|
|
141
|
+
const normalizedNodeId = normalizeNodeId(nodeId);
|
|
142
|
+
const visited = new Set();
|
|
143
|
+
collectSchemaRefNames(rootName, allSchemas, visited);
|
|
144
|
+
for (const name of visited)
|
|
145
|
+
addSchemaUsage(usage, name, normalizedNodeId);
|
|
146
|
+
}
|
|
147
|
+
for (const [schemaName, rawSchema] of Object.entries(allSchemas)) {
|
|
148
|
+
for (const refName of collectDirectSchemaRefs(rawSchema)) {
|
|
149
|
+
addSchemaLink(schemaLinks, schemaName, refName);
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
for (const edge of document.edges ?? []) {
|
|
153
|
+
const fromSchema = extractSchemaName(edge.from);
|
|
154
|
+
const toSchema = extractSchemaName(edge.to);
|
|
155
|
+
if (fromSchema && toSchema) {
|
|
156
|
+
usage.directEdgeSchemas.add(fromSchema);
|
|
157
|
+
usage.directEdgeSchemas.add(toSchema);
|
|
158
|
+
addSchemaLink(schemaLinks, fromSchema, toSchema);
|
|
159
|
+
continue;
|
|
160
|
+
}
|
|
161
|
+
if (fromSchema) {
|
|
162
|
+
usage.directEdgeSchemas.add(fromSchema);
|
|
163
|
+
const owner = resolveOwningRootNodeId(normalizeNodeId(edge.to), rootNodeIds);
|
|
164
|
+
if (owner)
|
|
165
|
+
addSchemaUsage(usage, fromSchema, owner);
|
|
166
|
+
}
|
|
167
|
+
if (toSchema) {
|
|
168
|
+
usage.directEdgeSchemas.add(toSchema);
|
|
169
|
+
const owner = resolveOwningRootNodeId(normalizeNodeId(edge.from), rootNodeIds);
|
|
170
|
+
if (owner)
|
|
171
|
+
addSchemaUsage(usage, toSchema, owner);
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
let changed = true;
|
|
175
|
+
while (changed) {
|
|
176
|
+
changed = false;
|
|
177
|
+
for (const [schemaName, linkedNames] of schemaLinks) {
|
|
178
|
+
const ownUsage = usage.rootsBySchema.get(schemaName);
|
|
179
|
+
if (!ownUsage)
|
|
180
|
+
continue;
|
|
181
|
+
for (const linkedName of linkedNames) {
|
|
182
|
+
const beforeSize = usage.rootsBySchema.get(linkedName)?.size ?? 0;
|
|
183
|
+
for (const rootNodeId of ownUsage)
|
|
184
|
+
addSchemaUsage(usage, linkedName, rootNodeId);
|
|
185
|
+
if ((usage.rootsBySchema.get(linkedName)?.size ?? 0) !== beforeSize)
|
|
186
|
+
changed = true;
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
return usage;
|
|
191
|
+
}
|
|
192
|
+
function collectSchemaRefNames(schemaName, allSchemas, visited) {
|
|
193
|
+
if (visited.has(schemaName))
|
|
194
|
+
return;
|
|
195
|
+
visited.add(schemaName);
|
|
196
|
+
const def = allSchemas[schemaName];
|
|
197
|
+
for (const prop of Object.values(def?.properties ?? {})) {
|
|
198
|
+
const p = prop;
|
|
199
|
+
const ref = typeof p.$ref === 'string' ? schemaRefName(p.$ref) : undefined;
|
|
200
|
+
if (ref)
|
|
201
|
+
collectSchemaRefNames(ref, allSchemas, visited);
|
|
202
|
+
if (p.type === 'array') {
|
|
203
|
+
const items = p.items;
|
|
204
|
+
const itemRef = items && typeof items.$ref === 'string' ? schemaRefName(items.$ref) : undefined;
|
|
205
|
+
if (itemRef)
|
|
206
|
+
collectSchemaRefNames(itemRef, allSchemas, visited);
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
function collectDirectSchemaRefs(value) {
|
|
211
|
+
const refs = new Set();
|
|
212
|
+
collectDirectSchemaRefsInto(value, refs);
|
|
213
|
+
return refs;
|
|
214
|
+
}
|
|
215
|
+
function collectDirectSchemaRefsInto(value, refs) {
|
|
216
|
+
if (!value || typeof value !== 'object')
|
|
217
|
+
return;
|
|
218
|
+
if (Array.isArray(value)) {
|
|
219
|
+
for (const item of value)
|
|
220
|
+
collectDirectSchemaRefsInto(item, refs);
|
|
221
|
+
return;
|
|
222
|
+
}
|
|
223
|
+
const record = value;
|
|
224
|
+
const refName = typeof record.$ref === 'string' ? schemaRefName(record.$ref) : undefined;
|
|
225
|
+
if (refName)
|
|
226
|
+
refs.add(refName);
|
|
227
|
+
collectDirectSchemaRefsInto(record.properties, refs);
|
|
228
|
+
collectDirectSchemaRefsInto(record.items, refs);
|
|
229
|
+
collectDirectSchemaRefsInto(record.additionalProperties, refs);
|
|
230
|
+
collectDirectSchemaRefsInto(record.allOf, refs);
|
|
231
|
+
collectDirectSchemaRefsInto(record.anyOf, refs);
|
|
232
|
+
collectDirectSchemaRefsInto(record.oneOf, refs);
|
|
233
|
+
}
|
|
234
|
+
function addSchemaUsage(usage, schemaName, rootNodeId) {
|
|
235
|
+
const roots = usage.rootsBySchema.get(schemaName) ?? new Set();
|
|
236
|
+
roots.add(rootNodeId);
|
|
237
|
+
usage.rootsBySchema.set(schemaName, roots);
|
|
238
|
+
}
|
|
239
|
+
function addSchemaLink(schemaLinks, from, to) {
|
|
240
|
+
if (from === to)
|
|
241
|
+
return;
|
|
242
|
+
const fromSet = schemaLinks.get(from) ?? new Set();
|
|
243
|
+
fromSet.add(to);
|
|
244
|
+
schemaLinks.set(from, fromSet);
|
|
245
|
+
}
|
|
246
|
+
function resolveOwningRootNodeId(nodeId, rootNodeIds) {
|
|
247
|
+
if (nodeId.startsWith('#/'))
|
|
248
|
+
return undefined;
|
|
249
|
+
return rootNodeIds.find(rootNodeId => nodeId === rootNodeId || nodeId.startsWith(`${rootNodeId}.`));
|
|
250
|
+
}
|
|
108
251
|
function schemaRefName(ref) {
|
|
109
252
|
const prefix = '#/components/schemas/';
|
|
110
253
|
if (!ref.startsWith(prefix))
|
|
@@ -117,7 +260,82 @@ function extractSchemaName(endpoint) {
|
|
|
117
260
|
return undefined;
|
|
118
261
|
return endpoint.slice(prefix.length).split('/')[0];
|
|
119
262
|
}
|
|
120
|
-
function
|
|
263
|
+
function normalizeNodeId(nodeId) {
|
|
264
|
+
if (nodeId.startsWith('#/'))
|
|
265
|
+
return nodeId;
|
|
266
|
+
const parts = nodeId.split('.');
|
|
267
|
+
if (parts.length === 0)
|
|
268
|
+
return nodeId;
|
|
269
|
+
parts[0] = normalizeComponent(parts[0]);
|
|
270
|
+
return parts.join('.');
|
|
271
|
+
}
|
|
272
|
+
function componentFromNodeId(nodeId) {
|
|
273
|
+
return normalizeComponent(nodeId.split('.')[0] ?? '');
|
|
274
|
+
}
|
|
275
|
+
function normalizeComponent(component) {
|
|
276
|
+
return component === '_' || component.trim() === '' ? UNRESOLVED_COMPONENT : component;
|
|
277
|
+
}
|
|
278
|
+
function determineSchemaOwnership(schemaName, usage) {
|
|
279
|
+
const rootNodeIds = [...(usage.rootsBySchema.get(schemaName) ?? [])];
|
|
280
|
+
if (rootNodeIds.length === 0) {
|
|
281
|
+
return usage.directEdgeSchemas.has(schemaName) ? { kind: 'unresolved' } : { kind: 'unused' };
|
|
282
|
+
}
|
|
283
|
+
if (rootNodeIds.length === 1) {
|
|
284
|
+
return {
|
|
285
|
+
kind: 'inline',
|
|
286
|
+
rootNodeId: rootNodeIds[0],
|
|
287
|
+
component: componentFromNodeId(rootNodeIds[0]),
|
|
288
|
+
};
|
|
289
|
+
}
|
|
290
|
+
const components = new Set(rootNodeIds.map(componentFromNodeId));
|
|
291
|
+
return {
|
|
292
|
+
kind: 'shared',
|
|
293
|
+
component: components.size === 1 ? [...components][0] : 'shared',
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
function localSchemaName(schemaName) {
|
|
297
|
+
return schemaName.includes('.')
|
|
298
|
+
? schemaName.slice(schemaName.lastIndexOf('.') + 1)
|
|
299
|
+
: schemaName;
|
|
300
|
+
}
|
|
301
|
+
function materializeStandaloneSchema(schemaName, component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents) {
|
|
302
|
+
const schemaLocalName = localSchemaName(schemaName);
|
|
303
|
+
const schemaDef = allSchemas[schemaName];
|
|
304
|
+
const isEnumSchema = Array.isArray(schemaDef?.enum) && !schemaDef?.properties;
|
|
305
|
+
const template = isEnumSchema ? 'EnumDefinition' : 'Schema';
|
|
306
|
+
const schemaId = `${component}.${template}.${schemaLocalName}`;
|
|
307
|
+
const schemaRef = `#/components/schemas/${schemaName}`;
|
|
308
|
+
if (refToNodeId.has(schemaRef))
|
|
309
|
+
return refToNodeId.get(schemaRef);
|
|
310
|
+
refToNodeId.set(schemaRef, schemaId);
|
|
311
|
+
nodes.push(makeNode(template, component, specPath, schemaId, undefined, {}));
|
|
312
|
+
if (isEnumSchema) {
|
|
313
|
+
for (const value of schemaDef.enum) {
|
|
314
|
+
if (typeof value !== 'string')
|
|
315
|
+
continue;
|
|
316
|
+
const valueId = `${schemaId}.values.${value}`;
|
|
317
|
+
refToNodeId.set(`${schemaRef}/properties/${value}`, valueId);
|
|
318
|
+
nodes.push(makeNode('EnumValue', component, specPath, valueId, undefined, { value }));
|
|
319
|
+
edges.push(makeHasValueEdge(schemaId, valueId));
|
|
320
|
+
}
|
|
321
|
+
return schemaId;
|
|
322
|
+
}
|
|
323
|
+
const expanded = new Map([[schemaName, schemaId]]);
|
|
324
|
+
const localMappings = new Map();
|
|
325
|
+
for (const [fieldName, rawProp] of Object.entries(schemaDef?.properties ?? {})) {
|
|
326
|
+
const fieldId = `${schemaId}.fields.${fieldName}`;
|
|
327
|
+
const fieldRef = `${schemaRef}/properties/${fieldName}`;
|
|
328
|
+
if (!refToNodeId.has(fieldRef))
|
|
329
|
+
refToNodeId.set(fieldRef, fieldId);
|
|
330
|
+
const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
|
|
331
|
+
const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
|
|
332
|
+
fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, schemaId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
|
|
333
|
+
nodes.push(fieldNode);
|
|
334
|
+
edges.push(makeHasFieldEdge(schemaId, fieldId));
|
|
335
|
+
}
|
|
336
|
+
return schemaId;
|
|
337
|
+
}
|
|
338
|
+
function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents = new Map()) {
|
|
121
339
|
const existing = expanded.get(schemaName);
|
|
122
340
|
if (existing)
|
|
123
341
|
return existing;
|
|
@@ -125,17 +343,36 @@ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath
|
|
|
125
343
|
// (e.g. "workers.ReactToPersonCreatedCommand"). Strip the prefix so the local segment
|
|
126
344
|
// in the node ID is a simple identifier — graph serialization rejects local names
|
|
127
345
|
// that contain dots because it uses dots as a hierarchy separator.
|
|
128
|
-
const schemaLocalName = schemaName
|
|
129
|
-
|
|
130
|
-
|
|
346
|
+
const schemaLocalName = localSchemaName(schemaName);
|
|
347
|
+
const schemaDef = allSchemas[schemaName];
|
|
348
|
+
const isEnumSchema = Array.isArray(schemaDef?.enum) && !schemaDef?.properties;
|
|
349
|
+
const schemaRef = `#/components/schemas/${schemaName}`;
|
|
350
|
+
if (isEnumSchema) {
|
|
351
|
+
// Enum schemas become standalone EnumDefinition cluster roots, matching the OpenAPI/AsyncAPI
|
|
352
|
+
// adapters. Using refToNodeId as shared dedup so only one node is created per mapDocument call
|
|
353
|
+
// even though `expanded` is scoped per parent node.
|
|
354
|
+
const enumComponent = schemaComponents.get(schemaName) ?? component;
|
|
355
|
+
const enumId = `${enumComponent}.EnumDefinition.${schemaLocalName}`;
|
|
356
|
+
expanded.set(schemaName, enumId);
|
|
357
|
+
if (!refToNodeId.has(schemaRef)) {
|
|
358
|
+
refToNodeId.set(schemaRef, enumId);
|
|
359
|
+
nodes.push(makeNode('EnumDefinition', enumComponent, specPath, enumId, undefined, {}));
|
|
360
|
+
for (const value of schemaDef.enum) {
|
|
361
|
+
if (typeof value !== 'string')
|
|
362
|
+
continue;
|
|
363
|
+
const valueId = `${enumId}.values.${value}`;
|
|
364
|
+
refToNodeId.set(`${schemaRef}/properties/${value}`, valueId);
|
|
365
|
+
nodes.push(makeNode('EnumValue', enumComponent, specPath, valueId, undefined, { value }));
|
|
366
|
+
edges.push(makeHasValueEdge(enumId, valueId));
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
return refToNodeId.get(schemaRef);
|
|
370
|
+
}
|
|
131
371
|
const schemaId = `${rootNodeId}.schemas.${schemaLocalName}`;
|
|
132
372
|
expanded.set(schemaName, schemaId);
|
|
133
|
-
const schemaRef = `#/components/schemas/${schemaName}`;
|
|
134
373
|
if (!refToNodeId.has(schemaRef))
|
|
135
374
|
refToNodeId.set(schemaRef, schemaId);
|
|
136
|
-
|
|
137
|
-
const schemaNode = makeNode('Schema', component, specPath, schemaId, undefined, {});
|
|
138
|
-
nodes.push(schemaNode);
|
|
375
|
+
nodes.push(makeNode('Schema', component, specPath, schemaId, undefined, {}));
|
|
139
376
|
edges.push(makeHasFieldEdge(rootNodeId, schemaId));
|
|
140
377
|
const localMappings = new Map();
|
|
141
378
|
for (const [fieldName, rawProp] of Object.entries(schemaDef?.properties ?? {})) {
|
|
@@ -145,32 +382,18 @@ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath
|
|
|
145
382
|
refToNodeId.set(fieldRef, fieldId);
|
|
146
383
|
const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
|
|
147
384
|
const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
|
|
148
|
-
fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
|
|
385
|
+
fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
|
|
149
386
|
nodes.push(fieldNode);
|
|
150
387
|
edges.push(makeHasFieldEdge(schemaId, fieldId));
|
|
151
388
|
}
|
|
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
|
-
}
|
|
166
389
|
return schemaId;
|
|
167
390
|
}
|
|
168
|
-
function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId) {
|
|
391
|
+
function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents) {
|
|
169
392
|
const nullable = !required;
|
|
170
393
|
if (typeof prop.$ref === 'string') {
|
|
171
394
|
const refName = schemaRefName(prop.$ref);
|
|
172
395
|
if (refName) {
|
|
173
|
-
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
396
|
+
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
|
|
174
397
|
return { $ref: refId, nullable, collection: 'one' };
|
|
175
398
|
}
|
|
176
399
|
return { type: 'string', nullable, collection: 'one' };
|
|
@@ -181,7 +404,7 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
|
|
|
181
404
|
if (items && typeof items.$ref === 'string') {
|
|
182
405
|
const refName = schemaRefName(items.$ref);
|
|
183
406
|
if (refName) {
|
|
184
|
-
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
407
|
+
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
|
|
185
408
|
return { $ref: refId, nullable, collection: 'array' };
|
|
186
409
|
}
|
|
187
410
|
}
|
|
@@ -189,13 +412,13 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
|
|
|
189
412
|
return { type: itemType, nullable, collection: 'array' };
|
|
190
413
|
}
|
|
191
414
|
if (type === 'object' && prop.additionalProperties !== undefined) {
|
|
192
|
-
createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
|
|
415
|
+
createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
|
|
193
416
|
return { $ref: `#/mappings/${fieldName}`, nullable, collection: 'one' };
|
|
194
417
|
}
|
|
195
418
|
const scalarType = mapScalar(type ?? 'string', prop.format);
|
|
196
419
|
return { type: scalarType, nullable, collection: 'one' };
|
|
197
420
|
}
|
|
198
|
-
function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId) {
|
|
421
|
+
function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents) {
|
|
199
422
|
const existing = localMappings.get(mappingName);
|
|
200
423
|
if (existing)
|
|
201
424
|
return existing;
|
|
@@ -211,7 +434,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
|
|
|
211
434
|
if (typeof addl.$ref === 'string') {
|
|
212
435
|
const refName = schemaRefName(addl.$ref);
|
|
213
436
|
if (refName) {
|
|
214
|
-
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
437
|
+
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
|
|
215
438
|
}
|
|
216
439
|
else {
|
|
217
440
|
props.type = 'string';
|
|
@@ -223,7 +446,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
|
|
|
223
446
|
if (items && typeof items.$ref === 'string') {
|
|
224
447
|
const refName = schemaRefName(items.$ref);
|
|
225
448
|
if (refName) {
|
|
226
|
-
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
|
|
449
|
+
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
|
|
227
450
|
}
|
|
228
451
|
else {
|
|
229
452
|
props.type = 'string';
|
|
@@ -235,7 +458,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
|
|
|
235
458
|
}
|
|
236
459
|
else if (addl.type === 'object' && addl.additionalProperties !== undefined) {
|
|
237
460
|
const innerName = `${mappingName}-values`;
|
|
238
|
-
props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
|
|
461
|
+
props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
|
|
239
462
|
}
|
|
240
463
|
else {
|
|
241
464
|
props.type = mapScalar(addl.type ?? 'string', addl.format);
|
|
@@ -290,6 +513,18 @@ function makeHasFieldEdge(from, to) {
|
|
|
290
513
|
derivedBy: 'adapter:corum',
|
|
291
514
|
};
|
|
292
515
|
}
|
|
516
|
+
function makeHasValueEdge(from, to) {
|
|
517
|
+
return {
|
|
518
|
+
id: `${from}__has-value__${to}`,
|
|
519
|
+
from,
|
|
520
|
+
to,
|
|
521
|
+
type: 'has-value',
|
|
522
|
+
state: 'implemented',
|
|
523
|
+
stability: 'unstable',
|
|
524
|
+
derivation: 'determined',
|
|
525
|
+
derivedBy: 'adapter:corum',
|
|
526
|
+
};
|
|
527
|
+
}
|
|
293
528
|
function mapEdge(raw) {
|
|
294
529
|
return {
|
|
295
530
|
id: `${raw.from}__${raw.type}__${raw.to}`,
|
package/dist/src/graph/index.js
CHANGED
|
@@ -50,6 +50,11 @@ export function getCluster(graph, nodeId) {
|
|
|
50
50
|
}
|
|
51
51
|
return { root, children, edges };
|
|
52
52
|
}
|
|
53
|
+
// Shared data-type templates whose structural children (fields, values) and referenced types
|
|
54
|
+
// are included when expanding external node references into a cluster view.
|
|
55
|
+
// Operational templates (DomainEvent, Command, APIEndpoint, etc.) are excluded — callers get
|
|
56
|
+
// only their root metadata, not their internal schema trees.
|
|
57
|
+
const DATA_NODE_TEMPLATES = new Set(['Schema', 'EnumDefinition']);
|
|
53
58
|
export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
|
|
54
59
|
const cluster = getCluster(graph, nodeId);
|
|
55
60
|
if (includeEdgeTypes.length === 0) {
|
|
@@ -65,40 +70,93 @@ export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
|
|
|
65
70
|
// reads edges are directional (consumer → type); only follow outbound so viewing a shared
|
|
66
71
|
// Schema doesn't pull in every endpoint that references it
|
|
67
72
|
const inboundTypes = new Set([...requestedTypes].filter(t => t !== 'reads'));
|
|
68
|
-
const includedNodeIds = new Set();
|
|
69
73
|
const edges = [...cluster.edges];
|
|
70
74
|
const seen = new Set(cluster.edges.map(edge => edge.id));
|
|
71
75
|
for (const id of clusterIds) {
|
|
72
76
|
for (const edge of graph.edgesByFrom.get(id) ?? []) {
|
|
73
|
-
|
|
77
|
+
if (!requestedTypes.has(edge.type) || seen.has(edge.id))
|
|
78
|
+
continue;
|
|
79
|
+
edges.push(edge);
|
|
80
|
+
seen.add(edge.id);
|
|
74
81
|
}
|
|
75
82
|
for (const edge of graph.edgesByTo.get(id) ?? []) {
|
|
76
|
-
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
// BFS over included nodes (outbound only) to transitively pull in referenced schemas
|
|
80
|
-
const processedOutbound = new Set(clusterIds);
|
|
81
|
-
let prevSize = 0;
|
|
82
|
-
while (includedNodeIds.size > prevSize) {
|
|
83
|
-
prevSize = includedNodeIds.size;
|
|
84
|
-
for (const id of includedNodeIds) {
|
|
85
|
-
if (processedOutbound.has(id))
|
|
83
|
+
if (!inboundTypes.has(edge.type) || seen.has(edge.id))
|
|
86
84
|
continue;
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph);
|
|
90
|
-
}
|
|
85
|
+
edges.push(edge);
|
|
86
|
+
seen.add(edge.id);
|
|
91
87
|
}
|
|
92
88
|
}
|
|
93
89
|
return {
|
|
94
90
|
root: cluster.root,
|
|
95
91
|
descendants: cluster.children,
|
|
96
|
-
includedNodes
|
|
97
|
-
|
|
98
|
-
|
|
92
|
+
// includedNodes is intentionally empty — callers compose this from the dangling edges
|
|
93
|
+
// using expandExternalNodes so each layer can apply its own inclusion policy.
|
|
94
|
+
includedNodes: [],
|
|
99
95
|
edges,
|
|
100
96
|
};
|
|
101
97
|
}
|
|
98
|
+
/**
|
|
99
|
+
* Expands a set of external node IDs (typically from dangling semantic edges) into a flat
|
|
100
|
+
* list of nodes suitable for use as `includedNodes` in a cluster view response.
|
|
101
|
+
*
|
|
102
|
+
* Each ID is first resolved to its cluster root so that structural child IDs from
|
|
103
|
+
* edges like `maps-to` (which point to e.g. `Schema.X.fields.Y`) are collapsed to
|
|
104
|
+
* the owning cluster root (`Schema.X`) before processing.
|
|
105
|
+
*
|
|
106
|
+
* Policy:
|
|
107
|
+
* - Schema and EnumDefinition nodes: include structural children (fields/values) and
|
|
108
|
+
* follow their outbound `reads` edges one hop to collect referenced data types.
|
|
109
|
+
* - All other templates: include only the root node (metadata for connectivity panels).
|
|
110
|
+
*/
|
|
111
|
+
export function expandExternalNodes(graph, externalIds) {
|
|
112
|
+
const result = new Set();
|
|
113
|
+
const dataQueue = [];
|
|
114
|
+
for (const rawId of externalIds) {
|
|
115
|
+
const immediateParent = findParent(graph, rawId);
|
|
116
|
+
if (immediateParent !== undefined) {
|
|
117
|
+
// rawId is a structural child (field/value targeted by maps-to).
|
|
118
|
+
// Include just this specific node — don't walk up and expand the entire parent tree.
|
|
119
|
+
if (!graph.nodesById.has(rawId) || result.has(rawId))
|
|
120
|
+
continue;
|
|
121
|
+
result.add(rawId);
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
// rawId has no structural parent — it's a root or standalone node (reads/calls/etc. target).
|
|
125
|
+
if (!graph.nodesById.has(rawId) || result.has(rawId))
|
|
126
|
+
continue;
|
|
127
|
+
result.add(rawId);
|
|
128
|
+
const node = graph.nodesById.get(rawId);
|
|
129
|
+
if (DATA_NODE_TEMPLATES.has(node.template))
|
|
130
|
+
dataQueue.push(rawId);
|
|
131
|
+
}
|
|
132
|
+
for (const id of dataQueue) {
|
|
133
|
+
// Include structural children (fields, values, mappings)
|
|
134
|
+
const prefix = `${id}.`;
|
|
135
|
+
for (const childId of graph.nodesById.keys()) {
|
|
136
|
+
if (childId.startsWith(prefix))
|
|
137
|
+
result.add(childId);
|
|
138
|
+
}
|
|
139
|
+
// Follow outbound reads one hop to collect referenced enum/schema types
|
|
140
|
+
for (const edge of graph.edgesByFrom.get(id) ?? []) {
|
|
141
|
+
if (edge.type !== 'reads' || result.has(edge.to))
|
|
142
|
+
continue;
|
|
143
|
+
const target = graph.nodesById.get(edge.to);
|
|
144
|
+
if (!target)
|
|
145
|
+
continue;
|
|
146
|
+
result.add(edge.to);
|
|
147
|
+
if (DATA_NODE_TEMPLATES.has(target.template)) {
|
|
148
|
+
const targetPrefix = `${edge.to}.`;
|
|
149
|
+
for (const childId of graph.nodesById.keys()) {
|
|
150
|
+
if (childId.startsWith(targetPrefix))
|
|
151
|
+
result.add(childId);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
return [...result]
|
|
157
|
+
.map(id => graph.nodesById.get(id))
|
|
158
|
+
.filter((node) => node !== undefined);
|
|
159
|
+
}
|
|
102
160
|
export function getLinkedFields(graph, nodeId) {
|
|
103
161
|
const root = graph.nodesById.get(nodeId);
|
|
104
162
|
if (!root)
|
|
@@ -144,22 +202,6 @@ function collectMapsTo(edge, edges, nodeIds, seen) {
|
|
|
144
202
|
nodeIds.add(edge.to);
|
|
145
203
|
seen.add(edge.id);
|
|
146
204
|
}
|
|
147
|
-
function collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph) {
|
|
148
|
-
if (!requestedTypes.has(edge.type) || seen.has(edge.id))
|
|
149
|
-
return;
|
|
150
|
-
edges.push(edge);
|
|
151
|
-
seen.add(edge.id);
|
|
152
|
-
for (const endId of [edge.from, edge.to]) {
|
|
153
|
-
if (clusterIds.has(endId))
|
|
154
|
-
continue;
|
|
155
|
-
includedNodeIds.add(endId);
|
|
156
|
-
const prefix = `${endId}.`;
|
|
157
|
-
for (const id of graph.nodesById.keys()) {
|
|
158
|
-
if (id.startsWith(prefix))
|
|
159
|
-
includedNodeIds.add(id);
|
|
160
|
-
}
|
|
161
|
-
}
|
|
162
|
-
}
|
|
163
205
|
const OVERLAY_EXCLUDED = new Set(['local', 'shared']);
|
|
164
206
|
export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRootId) {
|
|
165
207
|
const overlay = multi.overlay(viewingRef);
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
import { STRUCTURAL_EDGE_TYPES, STRUCTURAL_NODE_TEMPLATES } from './index.js';
|
|
2
|
+
const FIELD_EDGE_TYPES = new Set(['maps-to', 'derived-from']);
|
|
3
|
+
export function collapseClusterSchemas(graph, cluster) {
|
|
4
|
+
const rootId = cluster.root.id;
|
|
5
|
+
const rootPrefix = `${rootId}.`;
|
|
6
|
+
// Indexes keyed by local name or parent ID
|
|
7
|
+
const schemaChildIds = new Set();
|
|
8
|
+
const schemaNames = new Map(); // localName → exists
|
|
9
|
+
const enumNames = new Map(); // localName → exists
|
|
10
|
+
const fieldsByParentId = new Map(); // parentId → fieldName → Node
|
|
11
|
+
const valuesByEnumId = new Map(); // enumId → value names
|
|
12
|
+
const valuesBySchemaId = new Map(); // schemaId → value names (enum-like schemas)
|
|
13
|
+
const mappingsByParentId = new Map(); // parentSchemaId → mapName → Node
|
|
14
|
+
const semanticDescendants = [];
|
|
15
|
+
for (const n of cluster.descendants) {
|
|
16
|
+
if (!n.id.startsWith(rootPrefix)) {
|
|
17
|
+
semanticDescendants.push(n);
|
|
18
|
+
continue;
|
|
19
|
+
}
|
|
20
|
+
const suffix = n.id.slice(rootPrefix.length);
|
|
21
|
+
if (n.template === 'Schema') {
|
|
22
|
+
const m = /^schemas\.([^.]+)$/.exec(suffix);
|
|
23
|
+
if (m) {
|
|
24
|
+
schemaNames.set(m[1], true);
|
|
25
|
+
schemaChildIds.add(n.id);
|
|
26
|
+
continue;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
if (n.template === 'EnumDefinition') {
|
|
30
|
+
const m = /^enums\.([^.]+)$/.exec(suffix);
|
|
31
|
+
if (m) {
|
|
32
|
+
enumNames.set(m[1], true);
|
|
33
|
+
schemaChildIds.add(n.id);
|
|
34
|
+
continue;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
if (n.template === 'Field') {
|
|
38
|
+
const m = /^(.+)\.fields\.([^.]+)$/.exec(suffix);
|
|
39
|
+
if (m) {
|
|
40
|
+
const parentId = `${rootId}.${m[1]}`;
|
|
41
|
+
const existing = fieldsByParentId.get(parentId) ?? new Map();
|
|
42
|
+
existing.set(m[2], n);
|
|
43
|
+
fieldsByParentId.set(parentId, existing);
|
|
44
|
+
schemaChildIds.add(n.id);
|
|
45
|
+
continue;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
if (n.template === 'EnumValue') {
|
|
49
|
+
const enumM = /^enums\.([^.]+)\.values\.([^.]+)$/.exec(suffix);
|
|
50
|
+
if (enumM) {
|
|
51
|
+
const enumId = `${rootId}.enums.${enumM[1]}`;
|
|
52
|
+
const values = valuesByEnumId.get(enumId) ?? [];
|
|
53
|
+
values.push(typeof n.properties.name === 'string' ? n.properties.name : enumM[2]);
|
|
54
|
+
valuesByEnumId.set(enumId, values);
|
|
55
|
+
schemaChildIds.add(n.id);
|
|
56
|
+
continue;
|
|
57
|
+
}
|
|
58
|
+
// Also handle EnumValue nodes under schemas section (enum-like schemas)
|
|
59
|
+
const schemaM = /^schemas\.([^.]+)\.values\.([^.]+)$/.exec(suffix);
|
|
60
|
+
if (schemaM) {
|
|
61
|
+
const schemaId = `${rootId}.schemas.${schemaM[1]}`;
|
|
62
|
+
const values = valuesBySchemaId.get(schemaId) ?? [];
|
|
63
|
+
values.push(typeof n.properties.name === 'string' ? n.properties.name : schemaM[2]);
|
|
64
|
+
valuesBySchemaId.set(schemaId, values);
|
|
65
|
+
schemaChildIds.add(n.id);
|
|
66
|
+
continue;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
if (n.template === 'Mapping') {
|
|
70
|
+
const m = /^schemas\.([^.]+)\.mappings\.([^.]+)$/.exec(suffix);
|
|
71
|
+
if (m) {
|
|
72
|
+
const parentId = `${rootId}.schemas.${m[1]}`;
|
|
73
|
+
const existing = mappingsByParentId.get(parentId) ?? new Map();
|
|
74
|
+
existing.set(m[2], n);
|
|
75
|
+
mappingsByParentId.set(parentId, existing);
|
|
76
|
+
schemaChildIds.add(n.id);
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
semanticDescendants.push(n);
|
|
81
|
+
}
|
|
82
|
+
// Build schemas output
|
|
83
|
+
const schemas = {};
|
|
84
|
+
const schemaEnums = {};
|
|
85
|
+
for (const localName of schemaNames.keys()) {
|
|
86
|
+
const schemaId = `${rootId}.schemas.${localName}`;
|
|
87
|
+
const fields = fieldsByParentId.get(schemaId) ?? new Map();
|
|
88
|
+
// Enum-like schema: has EnumValue children but no Field children
|
|
89
|
+
const schemaValues = valuesBySchemaId.get(schemaId);
|
|
90
|
+
if (schemaValues && fields.size === 0) {
|
|
91
|
+
schemaEnums[localName] = { values: schemaValues };
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
const mappings = mappingsByParentId.get(schemaId) ?? new Map();
|
|
95
|
+
const entry = {};
|
|
96
|
+
for (const [fieldName, fieldNode] of fields) {
|
|
97
|
+
entry[fieldName] = buildField(fieldNode, graph, rootId, mappings);
|
|
98
|
+
}
|
|
99
|
+
schemas[localName] = entry;
|
|
100
|
+
}
|
|
101
|
+
// Build enums output
|
|
102
|
+
const enums = {};
|
|
103
|
+
for (const localName of enumNames.keys()) {
|
|
104
|
+
const enumId = `${rootId}.enums.${localName}`;
|
|
105
|
+
enums[localName] = { values: valuesByEnumId.get(enumId) ?? [] };
|
|
106
|
+
}
|
|
107
|
+
// Filter edges: drop structural edge types and any edge originating from a schema child
|
|
108
|
+
const filteredEdges = cluster.edges.filter(e => !STRUCTURAL_EDGE_TYPES.has(e.type) && !schemaChildIds.has(e.from));
|
|
109
|
+
// Filter includedNodes: drop structural template nodes
|
|
110
|
+
const filteredIncludedNodes = cluster.includedNodes.filter(n => !STRUCTURAL_NODE_TEMPLATES.has(n.template));
|
|
111
|
+
return {
|
|
112
|
+
root: cluster.root,
|
|
113
|
+
schemas,
|
|
114
|
+
schemaEnums,
|
|
115
|
+
enums,
|
|
116
|
+
descendants: semanticDescendants,
|
|
117
|
+
edges: filteredEdges,
|
|
118
|
+
includedNodes: filteredIncludedNodes,
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
function buildField(fieldNode, graph, rootId, parentMappings) {
|
|
122
|
+
const props = fieldNode.properties;
|
|
123
|
+
const isArray = props.collection === 'array';
|
|
124
|
+
const isNullable = props.nullable === true;
|
|
125
|
+
let field = {};
|
|
126
|
+
const ref = typeof props.$ref === 'string' ? props.$ref : undefined;
|
|
127
|
+
if (ref?.startsWith('#/mappings/')) {
|
|
128
|
+
const mapName = ref.slice('#/mappings/'.length);
|
|
129
|
+
const mapNode = parentMappings.get(mapName);
|
|
130
|
+
if (mapNode) {
|
|
131
|
+
field = buildMappingField(mapNode, graph);
|
|
132
|
+
}
|
|
133
|
+
else {
|
|
134
|
+
field = { $ref: ref };
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
else if (ref) {
|
|
138
|
+
field = { $ref: ref };
|
|
139
|
+
if (isArray)
|
|
140
|
+
field.collection = 'array';
|
|
141
|
+
}
|
|
142
|
+
else if (typeof props.type === 'string') {
|
|
143
|
+
field = { type: props.type };
|
|
144
|
+
if (isArray)
|
|
145
|
+
field.collection = 'array';
|
|
146
|
+
}
|
|
147
|
+
if (isNullable)
|
|
148
|
+
field.nullable = true;
|
|
149
|
+
// Gather outbound field edges that cross the cluster boundary
|
|
150
|
+
const clusterPrefix = `${rootId}.`;
|
|
151
|
+
const fieldEdges = {};
|
|
152
|
+
for (const e of graph.edgesByFrom.get(fieldNode.id) ?? []) {
|
|
153
|
+
if (!FIELD_EDGE_TYPES.has(e.type))
|
|
154
|
+
continue;
|
|
155
|
+
if (e.to.startsWith(clusterPrefix))
|
|
156
|
+
continue;
|
|
157
|
+
const targets = fieldEdges[e.type] ?? [];
|
|
158
|
+
targets.push(e.to);
|
|
159
|
+
fieldEdges[e.type] = targets;
|
|
160
|
+
}
|
|
161
|
+
if (Object.keys(fieldEdges).length > 0)
|
|
162
|
+
field.edges = fieldEdges;
|
|
163
|
+
return field;
|
|
164
|
+
}
|
|
165
|
+
function buildMappingField(mapNode, graph) {
|
|
166
|
+
const props = mapNode.properties;
|
|
167
|
+
const key = typeof props['key-type'] === 'string' ? props['key-type'] : 'string';
|
|
168
|
+
const isArrayValue = props['value-collection'] === 'array';
|
|
169
|
+
let valueField = {};
|
|
170
|
+
if (typeof props.type === 'string') {
|
|
171
|
+
valueField = { type: props.type };
|
|
172
|
+
}
|
|
173
|
+
else if (typeof props.$ref === 'string') {
|
|
174
|
+
const ref = props.$ref;
|
|
175
|
+
const refNode = graph.nodesById.get(ref);
|
|
176
|
+
if (refNode?.template === 'Mapping') {
|
|
177
|
+
// Nested mapping — recurse once (no further recursion guard needed for realistic depths)
|
|
178
|
+
valueField = buildMappingField(refNode, graph);
|
|
179
|
+
}
|
|
180
|
+
else {
|
|
181
|
+
valueField = { $ref: ref };
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
const value = isArrayValue
|
|
185
|
+
? { type: 'array', items: valueField }
|
|
186
|
+
: valueField;
|
|
187
|
+
return { type: 'map', key, value };
|
|
188
|
+
}
|
package/dist/src/mcp/index.js
CHANGED
|
@@ -3,12 +3,13 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
|
3
3
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
4
4
|
import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
|
|
5
5
|
import { pathToFileURL } from 'node:url';
|
|
6
|
-
import { computeClusterOverlay, getClusterView, getGraphSummary, getLineage, getLinkedFields, listNodes, SEMANTIC_EDGE_TYPES, searchNodes, STRUCTURAL_NODE_TEMPLATES, } from '../graph/index.js';
|
|
6
|
+
import { computeClusterOverlay, expandExternalNodes, getClusterView, getGraphSummary, getLineage, getLinkedFields, listNodes, SEMANTIC_EDGE_TYPES, searchNodes, STRUCTURAL_NODE_TEMPLATES, } from '../graph/index.js';
|
|
7
7
|
import { loadGraph, loadMultiGraph } from '../loader/index.js';
|
|
8
8
|
import { QueryError } from '../schema/index.js';
|
|
9
9
|
import { createGraphRuntimeConfig } from '../source/config.js';
|
|
10
10
|
import { startGraphFileWatcher, startWebServer } from '../web/server.js';
|
|
11
11
|
import { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
|
|
12
|
+
import { collapseClusterSchemas } from '../graph/schema-collapse.js';
|
|
12
13
|
import { compactKeys, getSerializer } from './serializers.js';
|
|
13
14
|
const EDGE_TYPES = [
|
|
14
15
|
'triggers',
|
|
@@ -88,18 +89,16 @@ function fullNode(node, includeProvenance) {
|
|
|
88
89
|
...(includeProvenance ? withProvenance(node) : {}),
|
|
89
90
|
};
|
|
90
91
|
}
|
|
91
|
-
function mapEdge(edge,
|
|
92
|
-
const out = {
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
stability: edge.stability,
|
|
99
|
-
};
|
|
92
|
+
function mapEdge(edge, options = {}) {
|
|
93
|
+
const out = {};
|
|
94
|
+
if (options.includeId)
|
|
95
|
+
out.id = edge.id;
|
|
96
|
+
out.from = edge.from;
|
|
97
|
+
out.to = edge.to;
|
|
98
|
+
out.type = edge.type;
|
|
100
99
|
if (edge.notes !== undefined)
|
|
101
100
|
out.notes = edge.notes;
|
|
102
|
-
if (includeProvenance) {
|
|
101
|
+
if (options.includeProvenance) {
|
|
103
102
|
if (edge.derivation !== undefined)
|
|
104
103
|
out.derivation = edge.derivation;
|
|
105
104
|
if (edge.derivedBy !== undefined)
|
|
@@ -107,6 +106,12 @@ function mapEdge(edge, includeProvenance) {
|
|
|
107
106
|
}
|
|
108
107
|
return out;
|
|
109
108
|
}
|
|
109
|
+
function getEdgeOutputOptions(args) {
|
|
110
|
+
return {
|
|
111
|
+
includeProvenance: includesProvenance(args),
|
|
112
|
+
includeId: args.include_edge_ids === true,
|
|
113
|
+
};
|
|
114
|
+
}
|
|
110
115
|
function mapLineageNode(node, includeProvenance, lean) {
|
|
111
116
|
const base = {
|
|
112
117
|
id: String(node.id),
|
|
@@ -244,14 +249,71 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
244
249
|
const run = async (targetGraph, branchRef) => {
|
|
245
250
|
const edgeTypes = parseEdgeTypes(args.edge_types)
|
|
246
251
|
?? [...SEMANTIC_EDGE_TYPES];
|
|
247
|
-
const
|
|
252
|
+
const rawCluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
|
|
253
|
+
const clusterIds = new Set([rawCluster.root.id, ...rawCluster.descendants.map(n => n.id)]);
|
|
254
|
+
const externalIds = new Set();
|
|
255
|
+
for (const edge of rawCluster.edges) {
|
|
256
|
+
if (!clusterIds.has(edge.from))
|
|
257
|
+
externalIds.add(edge.from);
|
|
258
|
+
if (!clusterIds.has(edge.to))
|
|
259
|
+
externalIds.add(edge.to);
|
|
260
|
+
}
|
|
261
|
+
const cluster = { ...rawCluster, includedNodes: expandExternalNodes(targetGraph, externalIds) };
|
|
248
262
|
const includeProvenance = includesProvenance(args);
|
|
249
|
-
const
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
263
|
+
const collapseSchemas = args.collapse_schemas !== false;
|
|
264
|
+
const includeEdges = args.include_edges === true;
|
|
265
|
+
const includeDescendants = args.include_descendants !== false;
|
|
266
|
+
const nodeTypes = toStringArray(args.node_types);
|
|
267
|
+
const edgeOptions = getEdgeOutputOptions(args);
|
|
268
|
+
let clusterPayload;
|
|
269
|
+
if (collapseSchemas) {
|
|
270
|
+
const collapsed = collapseClusterSchemas(targetGraph, cluster);
|
|
271
|
+
let filteredDescendants = collapsed.descendants;
|
|
272
|
+
let filteredIncludedNodes = collapsed.includedNodes;
|
|
273
|
+
if (!includeDescendants) {
|
|
274
|
+
filteredDescendants = [];
|
|
275
|
+
filteredIncludedNodes = [];
|
|
276
|
+
}
|
|
277
|
+
else if (nodeTypes) {
|
|
278
|
+
const typeSet = new Set(nodeTypes);
|
|
279
|
+
filteredDescendants = filteredDescendants.filter(n => typeSet.has(n.template));
|
|
280
|
+
filteredIncludedNodes = filteredIncludedNodes.filter(n => typeSet.has(n.template));
|
|
281
|
+
}
|
|
282
|
+
const mergedSchemas = { ...collapsed.schemas, ...collapsed.schemaEnums };
|
|
283
|
+
clusterPayload = {
|
|
284
|
+
root: {
|
|
285
|
+
...fullNode(collapsed.root, includeProvenance),
|
|
286
|
+
...(Object.keys(mergedSchemas).length > 0 ? { schemas: mergedSchemas } : {}),
|
|
287
|
+
...(Object.keys(collapsed.enums).length > 0 ? { enums: collapsed.enums } : {}),
|
|
288
|
+
},
|
|
289
|
+
...(includeDescendants ? {
|
|
290
|
+
descendants: filteredDescendants.map(node => fullNode(node, includeProvenance)),
|
|
291
|
+
includedNodes: filteredIncludedNodes.map(node => fullNode(node, includeProvenance)),
|
|
292
|
+
} : {}),
|
|
293
|
+
...(includeEdges ? { edges: collapsed.edges.map(e => mapEdge(e, edgeOptions)) } : {}),
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
else {
|
|
297
|
+
let filteredDescendants = cluster.descendants;
|
|
298
|
+
let filteredIncludedNodes = cluster.includedNodes;
|
|
299
|
+
if (!includeDescendants) {
|
|
300
|
+
filteredDescendants = [];
|
|
301
|
+
filteredIncludedNodes = [];
|
|
302
|
+
}
|
|
303
|
+
else if (nodeTypes) {
|
|
304
|
+
const typeSet = new Set(nodeTypes);
|
|
305
|
+
filteredDescendants = filteredDescendants.filter(n => typeSet.has(n.template));
|
|
306
|
+
filteredIncludedNodes = filteredIncludedNodes.filter(n => typeSet.has(n.template));
|
|
307
|
+
}
|
|
308
|
+
clusterPayload = {
|
|
309
|
+
root: fullNode(cluster.root, includeProvenance),
|
|
310
|
+
...(includeDescendants ? {
|
|
311
|
+
descendants: filteredDescendants.map(node => fullNode(node, includeProvenance)),
|
|
312
|
+
includedNodes: filteredIncludedNodes.map(node => fullNode(node, includeProvenance)),
|
|
313
|
+
} : {}),
|
|
314
|
+
...(includeEdges ? { edges: cluster.edges.map(e => mapEdge(e, edgeOptions)) } : {}),
|
|
315
|
+
};
|
|
316
|
+
}
|
|
255
317
|
if (overlayRefs.length === 0 || !source || !branchRef) {
|
|
256
318
|
return formatResult(clusterPayload, args.format, getCompactKeys(args));
|
|
257
319
|
}
|
|
@@ -355,11 +417,12 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
355
417
|
const lean = args.lean !== false;
|
|
356
418
|
const includeEdges = args.include_edges === true;
|
|
357
419
|
const includeProvenance = includesProvenance(args);
|
|
420
|
+
const edgeOptions = getEdgeOutputOptions(args);
|
|
358
421
|
const payload = {
|
|
359
422
|
nodes: lineage.nodes.map(node => mapLineageNode(node, includeProvenance, lean)),
|
|
360
423
|
};
|
|
361
424
|
if (includeEdges)
|
|
362
|
-
payload.edges = lineage.edges.map(e => mapEdge(e,
|
|
425
|
+
payload.edges = lineage.edges.map(e => mapEdge(e, edgeOptions));
|
|
363
426
|
if (args.include_dangling_edges === true && lineage.dangling_edges)
|
|
364
427
|
payload.dangling_edges = lineage.dangling_edges;
|
|
365
428
|
return formatResult(payload, args.format, getCompactKeys(args));
|
|
@@ -378,8 +441,9 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
378
441
|
const run = (targetGraph) => {
|
|
379
442
|
const linked = getLinkedFields(targetGraph, String(args.node_id));
|
|
380
443
|
const incProv = includesProvenance(args);
|
|
444
|
+
const edgeOptions = getEdgeOutputOptions(args);
|
|
381
445
|
return formatResult({
|
|
382
|
-
edges: linked.edges.map(e => mapEdge(e,
|
|
446
|
+
edges: linked.edges.map(e => mapEdge(e, edgeOptions)),
|
|
383
447
|
nodes: linked.nodes.map(node => fullNode(node, incProv)),
|
|
384
448
|
}, args.format, getCompactKeys(args));
|
|
385
449
|
};
|
|
@@ -521,7 +585,7 @@ export function getMcpToolDefinitions() {
|
|
|
521
585
|
},
|
|
522
586
|
{
|
|
523
587
|
name: 'get_cluster',
|
|
524
|
-
description: 'Use when you need the full structural contents of a single node - its schema, fields, and owned children. Not suited for following relationships across the graph; use get_lineage for that.
|
|
588
|
+
description: 'Use when you need the full structural contents of a single node - its schema, fields, and owned children. Not suited for following relationships across the graph; use get_lineage for that.\n\nBy default returns only the root node with its collapsed schema and enums blocks (descendants and edges excluded). Pass include_descendants: true to include owned operations/commands/events. Pass include_edges: true to include the edge list.',
|
|
525
589
|
inputSchema: {
|
|
526
590
|
type: 'object',
|
|
527
591
|
required: ['node_id'],
|
|
@@ -532,8 +596,15 @@ export function getMcpToolDefinitions() {
|
|
|
532
596
|
items: { type: 'string' },
|
|
533
597
|
description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
|
|
534
598
|
},
|
|
535
|
-
|
|
536
|
-
|
|
599
|
+
collapse_schemas: { type: 'boolean', description: 'Collapse schema/enum child nodes into compact schemas and enums blocks on the root. Structural edges and schema child nodes are removed from descendants. Default true.' },
|
|
600
|
+
include_descendants: { type: 'boolean', description: 'Include descendant nodes (operations, commands, events, and cross-component nodes). Default true.' },
|
|
601
|
+
node_types: {
|
|
602
|
+
type: 'array',
|
|
603
|
+
items: { type: 'string' },
|
|
604
|
+
description: 'Allowlist of node templates to include in the descendant set. Useful for limiting to specific types (e.g. ["DomainOperation", "DomainEvent"]).',
|
|
605
|
+
},
|
|
606
|
+
include_edges: { type: 'boolean', description: 'Include the edge list in the response. Default false.' },
|
|
607
|
+
include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
|
|
537
608
|
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
538
609
|
branch: { type: 'string', description: 'Branch ref to load the cluster from' },
|
|
539
610
|
overlay_refs: {
|
|
@@ -604,6 +675,7 @@ export function getMcpToolDefinitions() {
|
|
|
604
675
|
reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
|
|
605
676
|
lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
|
|
606
677
|
include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
|
|
678
|
+
include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
|
|
607
679
|
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
608
680
|
branch: { type: 'string', description: 'Branch ref to load the lineage from' },
|
|
609
681
|
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
@@ -619,6 +691,7 @@ export function getMcpToolDefinitions() {
|
|
|
619
691
|
required: ['node_id'],
|
|
620
692
|
properties: {
|
|
621
693
|
node_id: { type: 'string', description: 'Fully qualified root node ID' },
|
|
694
|
+
include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
|
|
622
695
|
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
623
696
|
branch: { type: 'string', description: 'Branch ref to load linked fields from' },
|
|
624
697
|
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
@@ -43,7 +43,7 @@ When likely relationships are absent, treat naming, shared component context, sc
|
|
|
43
43
|
|
|
44
44
|
5. Use direction "upstream" from a DomainModel node to find all writers to that aggregate.
|
|
45
45
|
|
|
46
|
-
6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail
|
|
46
|
+
6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail. Prefer get_lineage for following relationships.
|
|
47
47
|
|
|
48
48
|
7. Add include_provenance: true only when you need to bridge a finding to the source codebase.
|
|
49
49
|
|
|
@@ -84,5 +84,10 @@ Field-level mappings between nodes:
|
|
|
84
84
|
get_linked_fields - returns all maps-to edges touching fields owned by a root node
|
|
85
85
|
|
|
86
86
|
Schema / field details:
|
|
87
|
-
get_cluster -
|
|
87
|
+
get_cluster - root includes compact schemas and enums blocks by default. Each schema entry
|
|
88
|
+
is a map of field name to { type?, $ref?, collection?, nullable?, edges? }. Local references
|
|
89
|
+
use $ref: '#/schemas/name' or $ref: '#/enums/name' pointing into the same blocks. Mapping
|
|
90
|
+
fields appear as { type: map, key: string, value: { ... } } inline on the field. Field-level
|
|
91
|
+
cross-cluster edges (maps-to, derived-from) appear as an edges block on the field. Pass
|
|
92
|
+
collapse_schemas: false to get the full structural node-per-field representation instead.
|
|
88
93
|
`.trim();
|
package/dist/src/web/server.js
CHANGED
|
@@ -5,7 +5,7 @@ import { existsSync, readFileSync, readdirSync, watch } from 'node:fs';
|
|
|
5
5
|
import { readdir } from 'node:fs/promises';
|
|
6
6
|
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
7
7
|
import { parse as parseYaml } from 'yaml';
|
|
8
|
-
import { computeClusterOverlay, getClusterView, getGraphSummary, getLineage, listNodes, searchNodes, } from '../graph/index.js';
|
|
8
|
+
import { computeClusterOverlay, getClusterView, getGraphSummary, expandExternalNodes, getLineage, listNodes, searchNodes, } from '../graph/index.js';
|
|
9
9
|
import { loadGraph, loadMultiGraph } from '../loader/index.js';
|
|
10
10
|
import { VALID_EDGE_TYPE_SET } from '../loader/constants.js';
|
|
11
11
|
import { getOwnedSections } from '../loader/pack-loader.js';
|
|
@@ -514,10 +514,22 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
|
|
|
514
514
|
const multi = await multiCache.get();
|
|
515
515
|
overlay = computeClusterOverlay(multi, req.query.ref, overlayRefs, nodeId);
|
|
516
516
|
}
|
|
517
|
+
// Compute included nodes from dangling semantic edges: data-type nodes (Schema,
|
|
518
|
+
// EnumDefinition) are expanded with structural children; operational nodes get
|
|
519
|
+
// root metadata only (for connectivity panels).
|
|
520
|
+
const clusterIds = new Set([cluster.root.id, ...cluster.descendants.map(n => n.id)]);
|
|
521
|
+
const externalIds = new Set();
|
|
522
|
+
for (const edge of cluster.edges) {
|
|
523
|
+
if (!clusterIds.has(edge.from))
|
|
524
|
+
externalIds.add(edge.from);
|
|
525
|
+
if (!clusterIds.has(edge.to))
|
|
526
|
+
externalIds.add(edge.to);
|
|
527
|
+
}
|
|
528
|
+
const includedNodes = expandExternalNodes(targetGraph, externalIds);
|
|
517
529
|
res.json({
|
|
518
530
|
root: summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, cluster.root)),
|
|
519
531
|
descendants: cluster.descendants.map(child => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, child))),
|
|
520
|
-
includedNodes:
|
|
532
|
+
includedNodes: includedNodes.map(node => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, node))),
|
|
521
533
|
edges: cluster.edges,
|
|
522
534
|
overlay,
|
|
523
535
|
});
|
package/package.json
CHANGED
package/web/app.jsx
CHANGED
|
@@ -843,8 +843,12 @@ function NodePage({ nodeId, templates, onNavigate, refreshToken, viewingRef, ove
|
|
|
843
843
|
const childDisplayEntries = [...displayChildren.entries()]
|
|
844
844
|
.filter(([templateName]) => templateName !== 'Field' && templateName !== 'EnumValue' && templateName !== 'Mapping');
|
|
845
845
|
const displayEntries = [...rootSpecializedNodes, ...childDisplayEntries];
|
|
846
|
-
|
|
847
|
-
|
|
846
|
+
// includedNodes now contains only directly-connected external nodes:
|
|
847
|
+
// - Schema / EnumDefinition: with structural children (fields/values) and referenced types
|
|
848
|
+
// - All other templates (DomainEvent, Command, etc.): root metadata only for connectivity panel
|
|
849
|
+
// This is computed server-side via expandExternalNodes, so no client-side filtering is needed.
|
|
850
|
+
const includedSchemaNodes = includedNodes.filter(n => n.template === 'Schema' && !n.parentId);
|
|
851
|
+
const includedEnumNodes = includedNodes.filter(n => n.template === 'EnumDefinition' && !n.parentId);
|
|
848
852
|
|
|
849
853
|
function handlePropertyNavigate(targetNodeId) {
|
|
850
854
|
if (displayedNodeIds.has(targetNodeId)) {
|
package/web/primitives.jsx
CHANGED
|
@@ -472,7 +472,8 @@ function SchemaFieldRows({ schemaNodeId, model, prefix = '', depth = 0, visited
|
|
|
472
472
|
const childSchemaNode = !canExpandMapping
|
|
473
473
|
? (refNodeId ? (model.schemasById?.get(refNodeId) ?? null) : (localRef ? (model.schemasByName.get(localRef) ?? null) : null))
|
|
474
474
|
: null;
|
|
475
|
-
const
|
|
475
|
+
const childHasFields = childSchemaNode ? (model.fieldsBySchema.get(childSchemaNode.id) ?? []).length > 0 : false;
|
|
476
|
+
const canExpand = !!childSchemaNode && !visited.has(childSchemaNode.id) && childHasFields;
|
|
476
477
|
const isExpandable = canExpand || canExpandMapping;
|
|
477
478
|
const childGhostFields = childSchemaNode ? overlayFieldsForSchema(overlayFields, childSchemaNode.id) : [];
|
|
478
479
|
const c = field.properties?.collection;
|