@atolis-hq/corum 0.1.37 → 0.1.38

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
@@ -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 root node, its descendants, included external nodes, and edges for one node's full structural detail |
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 such as schemas and fields. Use `get_lineage` for relationship traversal.
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
@@ -0,0 +1,169 @@
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 mappingsByParentId = new Map(); // parentSchemaId → mapName → Node
13
+ const semanticDescendants = [];
14
+ for (const n of cluster.descendants) {
15
+ if (!n.id.startsWith(rootPrefix)) {
16
+ semanticDescendants.push(n);
17
+ continue;
18
+ }
19
+ const suffix = n.id.slice(rootPrefix.length);
20
+ if (n.template === 'Schema') {
21
+ const m = /^schemas\.([^.]+)$/.exec(suffix);
22
+ if (m) {
23
+ schemaNames.set(m[1], true);
24
+ schemaChildIds.add(n.id);
25
+ continue;
26
+ }
27
+ }
28
+ if (n.template === 'EnumDefinition') {
29
+ const m = /^enums\.([^.]+)$/.exec(suffix);
30
+ if (m) {
31
+ enumNames.set(m[1], true);
32
+ schemaChildIds.add(n.id);
33
+ continue;
34
+ }
35
+ }
36
+ if (n.template === 'Field') {
37
+ const m = /^(.+)\.fields\.([^.]+)$/.exec(suffix);
38
+ if (m) {
39
+ const parentId = `${rootId}.${m[1]}`;
40
+ const existing = fieldsByParentId.get(parentId) ?? new Map();
41
+ existing.set(m[2], n);
42
+ fieldsByParentId.set(parentId, existing);
43
+ schemaChildIds.add(n.id);
44
+ continue;
45
+ }
46
+ }
47
+ if (n.template === 'EnumValue') {
48
+ const m = /^enums\.([^.]+)\.values\.([^.]+)$/.exec(suffix);
49
+ if (m) {
50
+ const enumId = `${rootId}.enums.${m[1]}`;
51
+ const values = valuesByEnumId.get(enumId) ?? [];
52
+ values.push(typeof n.properties.name === 'string' ? n.properties.name : m[2]);
53
+ valuesByEnumId.set(enumId, values);
54
+ schemaChildIds.add(n.id);
55
+ continue;
56
+ }
57
+ }
58
+ if (n.template === 'Mapping') {
59
+ const m = /^schemas\.([^.]+)\.mappings\.([^.]+)$/.exec(suffix);
60
+ if (m) {
61
+ const parentId = `${rootId}.schemas.${m[1]}`;
62
+ const existing = mappingsByParentId.get(parentId) ?? new Map();
63
+ existing.set(m[2], n);
64
+ mappingsByParentId.set(parentId, existing);
65
+ schemaChildIds.add(n.id);
66
+ continue;
67
+ }
68
+ }
69
+ semanticDescendants.push(n);
70
+ }
71
+ // Build schemas output
72
+ const schemas = {};
73
+ for (const localName of schemaNames.keys()) {
74
+ const schemaId = `${rootId}.schemas.${localName}`;
75
+ const fields = fieldsByParentId.get(schemaId) ?? new Map();
76
+ const mappings = mappingsByParentId.get(schemaId) ?? new Map();
77
+ const entry = {};
78
+ for (const [fieldName, fieldNode] of fields) {
79
+ entry[fieldName] = buildField(fieldNode, graph, rootId, mappings);
80
+ }
81
+ schemas[localName] = entry;
82
+ }
83
+ // Build enums output
84
+ const enums = {};
85
+ for (const localName of enumNames.keys()) {
86
+ const enumId = `${rootId}.enums.${localName}`;
87
+ enums[localName] = { values: valuesByEnumId.get(enumId) ?? [] };
88
+ }
89
+ // Filter edges: drop structural edge types and any edge originating from a schema child
90
+ const filteredEdges = cluster.edges.filter(e => !STRUCTURAL_EDGE_TYPES.has(e.type) && !schemaChildIds.has(e.from));
91
+ // Filter includedNodes: drop structural template nodes
92
+ const filteredIncludedNodes = cluster.includedNodes.filter(n => !STRUCTURAL_NODE_TEMPLATES.has(n.template));
93
+ return {
94
+ root: cluster.root,
95
+ schemas,
96
+ enums,
97
+ descendants: semanticDescendants,
98
+ edges: filteredEdges,
99
+ includedNodes: filteredIncludedNodes,
100
+ };
101
+ }
102
+ function buildField(fieldNode, graph, rootId, parentMappings) {
103
+ const props = fieldNode.properties;
104
+ const isArray = props.collection === 'array';
105
+ const isNullable = props.nullable === true;
106
+ let field = {};
107
+ const ref = typeof props.$ref === 'string' ? props.$ref : undefined;
108
+ if (ref?.startsWith('#/mappings/')) {
109
+ const mapName = ref.slice('#/mappings/'.length);
110
+ const mapNode = parentMappings.get(mapName);
111
+ if (mapNode) {
112
+ field = buildMappingField(mapNode, graph);
113
+ }
114
+ else {
115
+ field = { $ref: ref };
116
+ }
117
+ }
118
+ else if (ref) {
119
+ field = { $ref: ref };
120
+ if (isArray)
121
+ field.collection = 'array';
122
+ }
123
+ else if (typeof props.type === 'string') {
124
+ field = { type: props.type };
125
+ if (isArray)
126
+ field.collection = 'array';
127
+ }
128
+ if (isNullable)
129
+ field.nullable = true;
130
+ // Gather outbound field edges that cross the cluster boundary
131
+ const clusterPrefix = `${rootId}.`;
132
+ const fieldEdges = {};
133
+ for (const e of graph.edgesByFrom.get(fieldNode.id) ?? []) {
134
+ if (!FIELD_EDGE_TYPES.has(e.type))
135
+ continue;
136
+ if (e.to.startsWith(clusterPrefix))
137
+ continue;
138
+ const targets = fieldEdges[e.type] ?? [];
139
+ targets.push(e.to);
140
+ fieldEdges[e.type] = targets;
141
+ }
142
+ if (Object.keys(fieldEdges).length > 0)
143
+ field.edges = fieldEdges;
144
+ return field;
145
+ }
146
+ function buildMappingField(mapNode, graph) {
147
+ const props = mapNode.properties;
148
+ const key = typeof props['key-type'] === 'string' ? props['key-type'] : 'string';
149
+ const isArrayValue = props['value-collection'] === 'array';
150
+ let valueField = {};
151
+ if (typeof props.type === 'string') {
152
+ valueField = { type: props.type };
153
+ }
154
+ else if (typeof props.$ref === 'string') {
155
+ const ref = props.$ref;
156
+ const refNode = graph.nodesById.get(ref);
157
+ if (refNode?.template === 'Mapping') {
158
+ // Nested mapping — recurse once (no further recursion guard needed for realistic depths)
159
+ valueField = buildMappingField(refNode, graph);
160
+ }
161
+ else {
162
+ valueField = { $ref: ref };
163
+ }
164
+ }
165
+ const value = isArrayValue
166
+ ? { type: 'array', items: valueField }
167
+ : valueField;
168
+ return { type: 'map', key, value };
169
+ }
@@ -9,6 +9,7 @@ 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',
@@ -246,12 +247,29 @@ export function createMcpHandlers(graph, source, cache) {
246
247
  ?? [...SEMANTIC_EDGE_TYPES];
247
248
  const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
248
249
  const includeProvenance = includesProvenance(args);
249
- const clusterPayload = {
250
- root: fullNode(cluster.root, includeProvenance),
251
- descendants: cluster.descendants.map(node => fullNode(node, includeProvenance)),
252
- includedNodes: cluster.includedNodes.map(node => fullNode(node, includeProvenance)),
253
- edges: cluster.edges.map(e => mapEdge(e, includeProvenance)),
254
- };
250
+ const collapseSchemas = args.collapse_schemas !== false;
251
+ let clusterPayload;
252
+ if (collapseSchemas) {
253
+ const collapsed = collapseClusterSchemas(targetGraph, cluster);
254
+ clusterPayload = {
255
+ root: {
256
+ ...fullNode(collapsed.root, includeProvenance),
257
+ ...(Object.keys(collapsed.schemas).length > 0 ? { schemas: collapsed.schemas } : {}),
258
+ ...(Object.keys(collapsed.enums).length > 0 ? { enums: collapsed.enums } : {}),
259
+ },
260
+ descendants: collapsed.descendants.map(node => fullNode(node, includeProvenance)),
261
+ includedNodes: collapsed.includedNodes.map(node => fullNode(node, includeProvenance)),
262
+ edges: collapsed.edges.map(e => mapEdge(e, includeProvenance)),
263
+ };
264
+ }
265
+ else {
266
+ clusterPayload = {
267
+ root: fullNode(cluster.root, includeProvenance),
268
+ descendants: cluster.descendants.map(node => fullNode(node, includeProvenance)),
269
+ includedNodes: cluster.includedNodes.map(node => fullNode(node, includeProvenance)),
270
+ edges: cluster.edges.map(e => mapEdge(e, includeProvenance)),
271
+ };
272
+ }
255
273
  if (overlayRefs.length === 0 || !source || !branchRef) {
256
274
  return formatResult(clusterPayload, args.format, getCompactKeys(args));
257
275
  }
@@ -534,6 +552,7 @@ export function getMcpToolDefinitions() {
534
552
  },
535
553
  include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
536
554
  reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
555
+ 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.' },
537
556
  include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
538
557
  branch: { type: 'string', description: 'Branch ref to load the cluster from' },
539
558
  overlay_refs: {
@@ -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 (schema, fields). Prefer get_lineage for following relationships.
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 - descendants include owned schemas, fields, and enum values
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.37",
3
+ "version": "0.1.38",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",