@atolis-hq/corum 0.1.38 → 0.1.40

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.
@@ -1,15 +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
+ import { CORE_EDGE_TYPE_MAP } from '../loader/constants.js';
3
+ import { getDataTemplates, getStructuralTemplates, templateHasRole } from './roles.js';
4
+ /** Templates whose nodes are structural children, derived from declared template roles. */
5
+ export function getStructuralNodeTemplates(graph) {
6
+ return getStructuralTemplates(graph.templates);
7
+ }
8
+ export function getEdgeTypeDef(graph, type) {
9
+ return (graph.edgeTypes ?? CORE_EDGE_TYPE_MAP).get(type);
10
+ }
11
+ /** Structural edges encode containment (has-field, has-value, pack-declared structural types). */
12
+ export function isStructuralEdgeType(graph, type) {
13
+ return getEdgeTypeDef(graph, type)?.category === 'structural';
14
+ }
15
+ /**
16
+ * Visible edges appear in summaries, lineage defaults, and collapsed cluster
17
+ * views: everything that is neither structural containment nor hidden
18
+ * bookkeeping (e.g. renamed-from).
19
+ */
20
+ export function isVisibleEdgeType(graph, type) {
21
+ const def = getEdgeTypeDef(graph, type);
22
+ if (!def)
23
+ return true;
24
+ return def.category !== 'structural' && def.hidden !== true;
25
+ }
26
+ export function getVisibleEdgeTypes(graph) {
27
+ return [...(graph.edgeTypes ?? CORE_EDGE_TYPE_MAP).values()]
28
+ .filter(def => def.category !== 'structural' && def.hidden !== true)
29
+ .map(def => def.name);
30
+ }
13
31
  export function listNodes(graph, filter = {}) {
14
32
  return [...graph.nodesById.values()].filter(node => {
15
33
  if (filter.templates?.length && !filter.templates.includes(node.template))
@@ -50,6 +68,13 @@ export function getCluster(graph, nodeId) {
50
68
  }
51
69
  return { root, children, edges };
52
70
  }
71
+ // Shared data-type templates (role type-container/enum-container) whose structural children
72
+ // (fields, values) and referenced types are included when expanding external node references
73
+ // into a cluster view. Operational templates (DomainEvent, Command, APIEndpoint, etc.) are
74
+ // excluded — callers get only their root metadata, not their internal schema trees.
75
+ function isDataNodeTemplate(graph, templateName) {
76
+ return getDataTemplates(graph.templates).has(templateName);
77
+ }
53
78
  export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
54
79
  const cluster = getCluster(graph, nodeId);
55
80
  if (includeEdgeTypes.length === 0) {
@@ -62,50 +87,103 @@ export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
62
87
  }
63
88
  const clusterIds = new Set([cluster.root.id, ...cluster.children.map(node => node.id)]);
64
89
  const requestedTypes = new Set(includeEdgeTypes);
65
- // reads edges are directional (consumer → type); only follow outbound so viewing a shared
66
- // Schema doesn't pull in every endpoint that references it
67
- const inboundTypes = new Set([...requestedTypes].filter(t => t !== 'reads'));
68
- const includedNodeIds = new Set();
90
+ // reads and uses-type edges are directional (consumer → type); only follow outbound so
91
+ // viewing a shared Schema doesn't pull in every endpoint that references it
92
+ const inboundTypes = new Set([...requestedTypes].filter(t => t !== 'reads' && t !== 'uses-type'));
69
93
  const edges = [...cluster.edges];
70
94
  const seen = new Set(cluster.edges.map(edge => edge.id));
71
95
  for (const id of clusterIds) {
72
96
  for (const edge of graph.edgesByFrom.get(id) ?? []) {
73
- collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph);
97
+ if (!requestedTypes.has(edge.type) || seen.has(edge.id))
98
+ continue;
99
+ edges.push(edge);
100
+ seen.add(edge.id);
74
101
  }
75
102
  for (const edge of graph.edgesByTo.get(id) ?? []) {
76
- collectIncludedEdge(edge, inboundTypes, clusterIds, includedNodeIds, edges, seen, graph);
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))
103
+ if (!inboundTypes.has(edge.type) || seen.has(edge.id))
86
104
  continue;
87
- processedOutbound.add(id);
88
- for (const edge of graph.edgesByFrom.get(id) ?? []) {
89
- collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph);
90
- }
105
+ edges.push(edge);
106
+ seen.add(edge.id);
91
107
  }
92
108
  }
93
109
  return {
94
110
  root: cluster.root,
95
111
  descendants: cluster.children,
96
- includedNodes: [...includedNodeIds]
97
- .map(id => graph.nodesById.get(id))
98
- .filter((node) => node !== undefined),
112
+ // includedNodes is intentionally empty — callers compose this from the dangling edges
113
+ // using expandExternalNodes so each layer can apply its own inclusion policy.
114
+ includedNodes: [],
99
115
  edges,
100
116
  };
101
117
  }
118
+ /**
119
+ * Expands a set of external node IDs (typically from dangling semantic edges) into a flat
120
+ * list of nodes suitable for use as `includedNodes` in a cluster view response.
121
+ *
122
+ * Each ID is first resolved to its cluster root so that structural child IDs from
123
+ * edges like `maps-to` (which point to e.g. `Schema.X.fields.Y`) are collapsed to
124
+ * the owning cluster root (`Schema.X`) before processing.
125
+ *
126
+ * Policy:
127
+ * - Schema and EnumDefinition nodes: include structural children (fields/values) and
128
+ * follow their outbound `uses-type` edges one hop to collect referenced data types.
129
+ * - All other templates: include only the root node (metadata for connectivity panels).
130
+ */
131
+ export function expandExternalNodes(graph, externalIds) {
132
+ const result = new Set();
133
+ const dataQueue = [];
134
+ for (const rawId of externalIds) {
135
+ const immediateParent = findParent(graph, rawId);
136
+ if (immediateParent !== undefined) {
137
+ // rawId is a structural child (field/value targeted by maps-to).
138
+ // Include just this specific node — don't walk up and expand the entire parent tree.
139
+ if (!graph.nodesById.has(rawId) || result.has(rawId))
140
+ continue;
141
+ result.add(rawId);
142
+ continue;
143
+ }
144
+ // rawId has no structural parent — it's a root or standalone node (reads/calls/etc. target).
145
+ if (!graph.nodesById.has(rawId) || result.has(rawId))
146
+ continue;
147
+ result.add(rawId);
148
+ const node = graph.nodesById.get(rawId);
149
+ if (isDataNodeTemplate(graph, node.template))
150
+ dataQueue.push(rawId);
151
+ }
152
+ for (const id of dataQueue) {
153
+ // Include structural children (fields, values, mappings)
154
+ const prefix = `${id}.`;
155
+ for (const childId of graph.nodesById.keys()) {
156
+ if (childId.startsWith(prefix))
157
+ result.add(childId);
158
+ }
159
+ // Follow outbound uses-type one hop to collect referenced enum/schema types
160
+ for (const edge of graph.edgesByFrom.get(id) ?? []) {
161
+ if (edge.type !== 'uses-type' || result.has(edge.to))
162
+ continue;
163
+ const target = graph.nodesById.get(edge.to);
164
+ if (!target)
165
+ continue;
166
+ result.add(edge.to);
167
+ if (isDataNodeTemplate(graph, target.template)) {
168
+ const targetPrefix = `${edge.to}.`;
169
+ for (const childId of graph.nodesById.keys()) {
170
+ if (childId.startsWith(targetPrefix))
171
+ result.add(childId);
172
+ }
173
+ }
174
+ }
175
+ }
176
+ return [...result]
177
+ .map(id => graph.nodesById.get(id))
178
+ .filter((node) => node !== undefined);
179
+ }
102
180
  export function getLinkedFields(graph, nodeId) {
103
181
  const root = graph.nodesById.get(nodeId);
104
182
  if (!root)
105
183
  throw new QueryError(`Node not found: ${nodeId}`);
106
184
  const prefix = `${nodeId}.`;
107
185
  const ownedFieldIds = new Set([...graph.nodesById.entries()]
108
- .filter(([id, node]) => id.startsWith(prefix) && node.template === 'Field')
186
+ .filter(([id, node]) => id.startsWith(prefix) && templateHasRole(graph.templates, node.template, 'field'))
109
187
  .map(([id]) => id));
110
188
  const edges = [];
111
189
  const nodeIds = new Set();
@@ -126,6 +204,12 @@ export function getLinkedFields(graph, nodeId) {
126
204
  };
127
205
  }
128
206
  function findParent(graph, nodeId) {
207
+ const node = graph.nodesById.get(nodeId);
208
+ if (node?.parentId !== undefined && graph.nodesById.has(node.parentId)) {
209
+ return node.parentId;
210
+ }
211
+ // Fallback for nodes without a materialised parentId (e.g. adapter output
212
+ // before a load round-trip): walk the ID hierarchy in 2-segment strides.
129
213
  const parts = nodeId.split('.');
130
214
  let endIdx = parts.length - 2;
131
215
  while (endIdx >= 1) {
@@ -144,22 +228,6 @@ function collectMapsTo(edge, edges, nodeIds, seen) {
144
228
  nodeIds.add(edge.to);
145
229
  seen.add(edge.id);
146
230
  }
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
231
  const OVERLAY_EXCLUDED = new Set(['local', 'shared']);
164
232
  export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRootId) {
165
233
  const overlay = multi.overlay(viewingRef);
@@ -198,7 +266,7 @@ export function getGraphSummary(graph) {
198
266
  const edgesByType = {};
199
267
  for (const edgeList of graph.edgesByFrom.values()) {
200
268
  for (const edge of edgeList) {
201
- if (!SEMANTIC_EDGE_TYPES.has(edge.type))
269
+ if (!isVisibleEdgeType(graph, edge.type))
202
270
  continue;
203
271
  edgesByType[edge.type] = (edgesByType[edge.type] ?? 0) + 1;
204
272
  nodesWithEdges.add(edge.from);
@@ -287,19 +355,21 @@ export function getLineage(graph, startNodeIds, options = {}) {
287
355
  const defaultEdgeTypes = new Set();
288
356
  for (const edgeList of graph.edgesByFrom.values()) {
289
357
  for (const edge of edgeList) {
290
- if (!STRUCTURAL_EDGE_TYPES.has(edge.type))
358
+ if (isVisibleEdgeType(graph, edge.type))
291
359
  defaultEdgeTypes.add(edge.type);
292
360
  }
293
361
  }
294
362
  const edgeTypeSet = options.edgeTypes ? new Set(options.edgeTypes) : defaultEdgeTypes;
295
- const inboundTypeSet = new Set([...edgeTypeSet].filter(type => !(readsOutboundOnly && type === 'reads')));
363
+ // reads and uses-type are directional (consumer → type); readsOutboundOnly (default true)
364
+ // excludes both from inbound traversal so a shared type doesn't pull in every consumer
365
+ const inboundTypeSet = new Set([...edgeTypeSet].filter(type => !(readsOutboundOnly && (type === 'reads' || type === 'uses-type'))));
296
366
  const useAllowlist = (options.nodeTypes?.length ?? 0) > 0;
297
367
  const allowedTemplates = useAllowlist ? new Set(options.nodeTypes) : null;
298
368
  const excludedTemplates = useAllowlist
299
369
  ? null
300
370
  : options.excludeNodeTypes?.length
301
371
  ? new Set(options.excludeNodeTypes)
302
- : STRUCTURAL_NODE_TEMPLATES;
372
+ : getStructuralNodeTemplates(graph);
303
373
  function isIncluded(node) {
304
374
  if (allowedTemplates)
305
375
  return allowedTemplates.has(node.template);
@@ -0,0 +1,66 @@
1
+ const STRUCTURAL_ROLES = new Set(['field', 'value', 'type-container', 'enum-container', 'mapping']);
2
+ const DATA_ROLES = new Set(['type-container', 'enum-container']);
3
+ /** Resolve a template's role, walking the extends chain (nearest declaration wins). */
4
+ export function getTemplateRole(templates, templateName) {
5
+ const seen = new Set();
6
+ let current = templates.get(templateName);
7
+ while (current && !seen.has(current.name)) {
8
+ seen.add(current.name);
9
+ const role = current.info?.role;
10
+ if (typeof role === 'string')
11
+ return role;
12
+ current = current.extends ? templates.get(current.extends) : undefined;
13
+ }
14
+ return undefined;
15
+ }
16
+ export function templateHasRole(templates, templateName, role) {
17
+ return getTemplateRole(templates, templateName) === role;
18
+ }
19
+ /**
20
+ * Resolve a template's declared `edge-types` constraints, walking the
21
+ * `extends` chain (nearest declaration wins, matching getTemplateRole).
22
+ * Returns undefined when neither the template nor any ancestor declares an
23
+ * `edge-types` block — such templates are unconstrained for edge endpoint
24
+ * linting purposes.
25
+ */
26
+ export function getEdgeTypeConstraints(templates, templateName) {
27
+ const seen = new Set();
28
+ let current = templates.get(templateName);
29
+ while (current && !seen.has(current.name)) {
30
+ seen.add(current.name);
31
+ const declared = current['edge-types'];
32
+ if (declared)
33
+ return declared;
34
+ current = current.extends ? templates.get(current.extends) : undefined;
35
+ }
36
+ return undefined;
37
+ }
38
+ const structuralCache = new WeakMap();
39
+ const dataCache = new WeakMap();
40
+ /** Templates whose nodes are materialised structural children (hidden from top-level listings). */
41
+ export function getStructuralTemplates(templates) {
42
+ let cached = structuralCache.get(templates);
43
+ if (!cached) {
44
+ cached = collectByRoles(templates, STRUCTURAL_ROLES);
45
+ structuralCache.set(templates, cached);
46
+ }
47
+ return cached;
48
+ }
49
+ /** Templates representing shared data types whose children are expanded in cluster views. */
50
+ export function getDataTemplates(templates) {
51
+ let cached = dataCache.get(templates);
52
+ if (!cached) {
53
+ cached = collectByRoles(templates, DATA_ROLES);
54
+ dataCache.set(templates, cached);
55
+ }
56
+ return cached;
57
+ }
58
+ function collectByRoles(templates, roles) {
59
+ const result = new Set();
60
+ for (const name of templates.keys()) {
61
+ const role = getTemplateRole(templates, name);
62
+ if (role !== undefined && roles.has(role))
63
+ result.add(name);
64
+ }
65
+ return result;
66
+ }
@@ -1,78 +1,88 @@
1
- import { STRUCTURAL_EDGE_TYPES, STRUCTURAL_NODE_TEMPLATES } from './index.js';
1
+ import { getStructuralNodeTemplates, isVisibleEdgeType } from './index.js';
2
+ import { getTemplateRole } from './roles.js';
2
3
  const FIELD_EDGE_TYPES = new Set(['maps-to', 'derived-from']);
3
4
  export function collapseClusterSchemas(graph, cluster) {
4
5
  const rootId = cluster.root.id;
5
6
  const rootPrefix = `${rootId}.`;
6
7
  // Indexes keyed by local name or parent ID
7
8
  const schemaChildIds = new Set();
8
- const schemaNames = new Map(); // localName → exists
9
- const enumNames = new Map(); // localName → exists
9
+ const schemaNames = new Map(); // localName → nodeId
10
+ const enumNames = new Map(); // localName → nodeId
10
11
  const fieldsByParentId = new Map(); // parentId → fieldName → Node
11
12
  const valuesByEnumId = new Map(); // enumId → value names
13
+ const valuesBySchemaId = new Map(); // schemaId → value names (enum-like schemas)
12
14
  const mappingsByParentId = new Map(); // parentSchemaId → mapName → Node
13
15
  const semanticDescendants = [];
16
+ // Classification is role- and ownership-driven: a node's template role
17
+ // (resolved through the extends chain) decides how it collapses, and its
18
+ // materialised parentId decides where. Section names never matter here, so
19
+ // packs may own schemas/fields under any section name.
20
+ const localName = (n) => n.id.slice(n.id.lastIndexOf('.') + 1);
21
+ const parentRole = (n) => {
22
+ const parent = n.parentId !== undefined ? graph.nodesById.get(n.parentId) : undefined;
23
+ return parent ? getTemplateRole(graph.templates, parent.template) : undefined;
24
+ };
14
25
  for (const n of cluster.descendants) {
15
26
  if (!n.id.startsWith(rootPrefix)) {
16
27
  semanticDescendants.push(n);
17
28
  continue;
18
29
  }
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
- }
30
+ const role = getTemplateRole(graph.templates, n.template);
31
+ if (role === 'type-container' && n.parentId === rootId) {
32
+ schemaNames.set(localName(n), n.id);
33
+ schemaChildIds.add(n.id);
34
+ continue;
27
35
  }
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
- }
36
+ if (role === 'enum-container' && n.parentId === rootId) {
37
+ enumNames.set(localName(n), n.id);
38
+ schemaChildIds.add(n.id);
39
+ continue;
35
40
  }
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
- }
41
+ if (role === 'field' && n.parentId !== undefined) {
42
+ const existing = fieldsByParentId.get(n.parentId) ?? new Map();
43
+ existing.set(localName(n), n);
44
+ fieldsByParentId.set(n.parentId, existing);
45
+ schemaChildIds.add(n.id);
46
+ continue;
46
47
  }
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);
48
+ if (role === 'value' && n.parentId !== undefined) {
49
+ const owner = parentRole(n);
50
+ if (owner === 'enum-container') {
51
+ const values = valuesByEnumId.get(n.parentId) ?? [];
52
+ values.push(typeof n.properties.name === 'string' ? n.properties.name : localName(n));
53
+ valuesByEnumId.set(n.parentId, values);
54
54
  schemaChildIds.add(n.id);
55
55
  continue;
56
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);
57
+ // Enum-like schemas: value nodes owned directly by a type-container
58
+ if (owner === 'type-container') {
59
+ const values = valuesBySchemaId.get(n.parentId) ?? [];
60
+ values.push(typeof n.properties.name === 'string' ? n.properties.name : localName(n));
61
+ valuesBySchemaId.set(n.parentId, values);
65
62
  schemaChildIds.add(n.id);
66
63
  continue;
67
64
  }
68
65
  }
66
+ if (role === 'mapping' && n.parentId !== undefined && parentRole(n) === 'type-container') {
67
+ const existing = mappingsByParentId.get(n.parentId) ?? new Map();
68
+ existing.set(localName(n), n);
69
+ mappingsByParentId.set(n.parentId, existing);
70
+ schemaChildIds.add(n.id);
71
+ continue;
72
+ }
69
73
  semanticDescendants.push(n);
70
74
  }
71
75
  // Build schemas output
72
76
  const schemas = {};
73
- for (const localName of schemaNames.keys()) {
74
- const schemaId = `${rootId}.schemas.${localName}`;
77
+ const schemaEnums = {};
78
+ for (const [localName, schemaId] of schemaNames) {
75
79
  const fields = fieldsByParentId.get(schemaId) ?? new Map();
80
+ // Enum-like schema: has EnumValue children but no Field children
81
+ const schemaValues = valuesBySchemaId.get(schemaId);
82
+ if (schemaValues && fields.size === 0) {
83
+ schemaEnums[localName] = { values: schemaValues };
84
+ continue;
85
+ }
76
86
  const mappings = mappingsByParentId.get(schemaId) ?? new Map();
77
87
  const entry = {};
78
88
  for (const [fieldName, fieldNode] of fields) {
@@ -82,17 +92,18 @@ export function collapseClusterSchemas(graph, cluster) {
82
92
  }
83
93
  // Build enums output
84
94
  const enums = {};
85
- for (const localName of enumNames.keys()) {
86
- const enumId = `${rootId}.enums.${localName}`;
95
+ for (const [localName, enumId] of enumNames) {
87
96
  enums[localName] = { values: valuesByEnumId.get(enumId) ?? [] };
88
97
  }
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));
98
+ // Filter edges: drop structural/hidden edge types and any edge originating from a schema child
99
+ const filteredEdges = cluster.edges.filter(e => isVisibleEdgeType(graph, e.type) && !schemaChildIds.has(e.from));
91
100
  // Filter includedNodes: drop structural template nodes
92
- const filteredIncludedNodes = cluster.includedNodes.filter(n => !STRUCTURAL_NODE_TEMPLATES.has(n.template));
101
+ const structuralTemplates = getStructuralNodeTemplates(graph);
102
+ const filteredIncludedNodes = cluster.includedNodes.filter(n => !structuralTemplates.has(n.template));
93
103
  return {
94
104
  root: cluster.root,
95
105
  schemas,
106
+ schemaEnums,
96
107
  enums,
97
108
  descendants: semanticDescendants,
98
109
  edges: filteredEdges,
@@ -105,15 +116,13 @@ function buildField(fieldNode, graph, rootId, parentMappings) {
105
116
  const isNullable = props.nullable === true;
106
117
  let field = {};
107
118
  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
- }
119
+ // Local refs (#/{section}/{name}) to a sibling mapping node collapse inline.
120
+ // Mapping-ness comes from the collected role-mapping siblings, not from the
121
+ // section name in the ref.
122
+ const localRefMatch = ref !== undefined ? /^#\/[^/]+\/(.+)$/.exec(ref) : null;
123
+ const mapNode = localRefMatch ? parentMappings.get(localRefMatch[1]) : undefined;
124
+ if (ref !== undefined && mapNode) {
125
+ field = buildMappingField(mapNode, graph, new Set([mapNode.id]));
117
126
  }
118
127
  else if (ref) {
119
128
  field = { $ref: ref };
@@ -143,7 +152,7 @@ function buildField(fieldNode, graph, rootId, parentMappings) {
143
152
  field.edges = fieldEdges;
144
153
  return field;
145
154
  }
146
- function buildMappingField(mapNode, graph) {
155
+ function buildMappingField(mapNode, graph, seen) {
147
156
  const props = mapNode.properties;
148
157
  const key = typeof props['key-type'] === 'string' ? props['key-type'] : 'string';
149
158
  const isArrayValue = props['value-collection'] === 'array';
@@ -154,9 +163,9 @@ function buildMappingField(mapNode, graph) {
154
163
  else if (typeof props.$ref === 'string') {
155
164
  const ref = props.$ref;
156
165
  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);
166
+ if (refNode && getTemplateRole(graph.templates, refNode.template) === 'mapping' && !seen.has(refNode.id)) {
167
+ seen.add(refNode.id);
168
+ valueField = buildMappingField(refNode, graph, seen);
160
169
  }
161
170
  else {
162
171
  valueField = { $ref: ref };
@@ -1,13 +1,37 @@
1
1
  import { parse as parseYaml } from 'yaml';
2
2
  import path from 'node:path';
3
3
  import { loadGraph } from '../loader/index.js';
4
+ import { isStructuralEdgeType } from '../graph/index.js';
4
5
  import { serializeGraph } from '../writer/graph-writer.js';
5
6
  import { getAdapter } from '../adapters/index.js';
6
7
  import { diffNodes } from '../reconcile/index.js';
7
8
  import { deduplicateResults } from './dedup.js';
8
- export async function runImport(config, runtimeConfig) {
9
+ export async function runImport(config, runtimeConfig, options = {}) {
9
10
  const allDiagnostics = [];
10
- const graph = await loadGraph({ source: runtimeConfig.source });
11
+ const source = runtimeConfig.source;
12
+ const defaultBranch = await source.defaultBranch();
13
+ const targetBranch = options.branch ?? defaultBranch;
14
+ if (runtimeConfig.kind === 'git' && targetBranch === defaultBranch) {
15
+ return {
16
+ diagnostics: [{
17
+ severity: 'error',
18
+ file: runtimeConfig.graphPath,
19
+ message: `git sources are read-only on the default branch '${defaultBranch}' — pass --branch <name> to import into a design branch`,
20
+ }],
21
+ };
22
+ }
23
+ let targetBranchExists = targetBranch === defaultBranch;
24
+ if (!targetBranchExists) {
25
+ try {
26
+ targetBranchExists = (await source.listBranches()).includes(targetBranch);
27
+ }
28
+ catch {
29
+ targetBranchExists = false;
30
+ }
31
+ }
32
+ // Diff against the branch we are importing into, so repeated imports to the
33
+ // same design branch stay idempotent; a new branch starts from the default.
34
+ const graph = await loadGraph({ source, ref: targetBranchExists ? targetBranch : defaultBranch });
11
35
  const entryResults = [];
12
36
  for (const entry of config.imports) {
13
37
  const packConfig = await loadPackAdapterConfig(runtimeConfig, entry.adapter);
@@ -37,14 +61,13 @@ export async function runImport(config, runtimeConfig) {
37
61
  allDiagnostics.push(...diagnostics);
38
62
  entryResults.splice(0, entryResults.length, ...deduped);
39
63
  }
40
- const STRUCTURAL_EDGE_TYPES = new Set(['has-field', 'has-value']);
41
64
  for (const er of entryResults) {
42
65
  const { toAdd, toUpdate, toRemove } = diffNodes(er.nodes, graph.nodesById, er.specPath);
43
66
  for (const node of [...toAdd, ...toUpdate, ...toRemove]) {
44
67
  graph.nodesById.set(node.id, node);
45
68
  }
46
69
  for (const edge of er.edges) {
47
- if (STRUCTURAL_EDGE_TYPES.has(edge.type))
70
+ if (isStructuralEdgeType(graph, edge.type))
48
71
  continue;
49
72
  const existing = graph.edgesByFrom.get(edge.from) ?? [];
50
73
  if (!existing.some(e => e.id === edge.id)) {
@@ -56,7 +79,7 @@ export async function runImport(config, runtimeConfig) {
56
79
  }
57
80
  const graphPath = runtimeConfig.kind === 'filesystem' ? runtimeConfig.graphPath : undefined;
58
81
  const contentMap = serializeGraph(graph, { sourceGraphPath: graphPath, outputGraphPath: graphPath });
59
- await runtimeConfig.source.commit(await runtimeConfig.source.defaultBranch(), contentMap, 'corum import', { replaceGraphContent: true });
82
+ await source.commit(targetBranch, contentMap, 'corum import', { replaceGraphContent: true, ...(targetBranchExists ? {} : { createBranchIfMissing: true }) });
60
83
  return { diagnostics: allDiagnostics };
61
84
  }
62
85
  async function loadPackAdapterConfig(runtimeConfig, adapterId) {