@atolis-hq/corum 0.1.18 → 0.1.20

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
@@ -116,6 +116,39 @@ Import specifications into the graph.
116
116
  corum import --config <path> Import using a config YAML file
117
117
  ```
118
118
 
119
+ #### Import config file
120
+
121
+ The `--config` flag accepts a YAML file that can combine multiple imports in a single run and configure cross-adapter options:
122
+
123
+ ```yaml
124
+ # Optional: remap extracted component names before node IDs are built.
125
+ # Useful when the same component appears under different names in different specs
126
+ # (e.g. "order-shipping" from a URI segment vs "ordershipping" from a topic name).
127
+ componentNameReplacements:
128
+ - from: ordershipping
129
+ to: order-shipping
130
+
131
+ imports:
132
+ - adapter: openapi
133
+ spec: ./specs/order-shipping.openapi.yaml
134
+ componentMapping:
135
+ strategy: uri-segment
136
+ segment: 0
137
+
138
+ - adapter: asyncapi
139
+ spec: ./specs/order-shipping.asyncapi.yaml
140
+ componentMapping:
141
+ strategy: channel-segment
142
+ separator: "."
143
+ segment: 0
144
+ messageNaming:
145
+ strategy: name-segment
146
+ separator: "."
147
+ segment: -1
148
+ ```
149
+
150
+ Replacements are applied in order; the first matching `from` wins. Unmatched names are passed through unchanged.
151
+
119
152
  #### `corum import openapi <spec>`
120
153
 
121
154
  Import an OpenAPI spec directly.
@@ -6,7 +6,7 @@ export class AsyncAPIAdapter {
6
6
  const { document, diagnostics } = await parseSpec(entry.spec);
7
7
  if (!document)
8
8
  return { nodes: [], edges: [], diagnostics };
9
- const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry, context.packConfig);
9
+ const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry, context.packConfig, context.componentNameReplacements);
10
10
  return { nodes, edges, diagnostics: [...diagnostics, ...mapDiagnostics] };
11
11
  }
12
12
  }
@@ -1,3 +1,4 @@
1
+ import { applyComponentNameReplacements } from '../../import/config.js';
1
2
  export function extractValue(strategy, operation, message) {
2
3
  switch (strategy.strategy) {
3
4
  case 'channel-segment': {
@@ -204,7 +205,7 @@ export function extractHeaders(rawHeaders, scalarTypes, specPath) {
204
205
  }
205
206
  return { headers, diagnostics };
206
207
  }
207
- export function mapDocument(document, entry, packConfig) {
208
+ export function mapDocument(document, entry, packConfig, componentNameReplacements = []) {
208
209
  const nodes = [];
209
210
  const edges = [];
210
211
  const diagnostics = [];
@@ -219,9 +220,10 @@ export function mapDocument(document, entry, packConfig) {
219
220
  const schemaComponents = new Map();
220
221
  for (const operation of document.allOperations()) {
221
222
  for (const message of operation.messages().all()) {
222
- const component = extractValue(entry.componentMapping, operation, message);
223
- if (!component)
223
+ const rawComponent = extractValue(entry.componentMapping, operation, message);
224
+ if (!rawComponent)
224
225
  continue;
226
+ const component = applyComponentNameReplacements(rawComponent, componentNameReplacements);
225
227
  const msgName = message.name() ?? message.id();
226
228
  if (!msgName)
227
229
  continue;
@@ -280,7 +282,7 @@ export function mapDocument(document, entry, packConfig) {
280
282
  continue;
281
283
  const [component] = registeredId.split('.');
282
284
  nodes.push(makeNode(packConfig.constructs['payloadSchema']?.template ?? 'Schema', component, entry.spec, registeredId));
283
- emitFields(s, registeredId, 'fields', undefined, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map());
285
+ emitFields(s, registeredId, 'fields', undefined, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map(), new Map());
284
286
  }
285
287
  const seenMessages = new Map();
286
288
  const allOperations = document.allOperations().all();
@@ -288,11 +290,12 @@ export function mapDocument(document, entry, packConfig) {
288
290
  for (const operation of operations) {
289
291
  const channelAddress = operation.channels().all()[0]?.address() ?? '';
290
292
  for (const message of operation.messages().all()) {
291
- const component = extractValue(entry.componentMapping, operation, message);
292
- if (!component) {
293
+ const rawComponent = extractValue(entry.componentMapping, operation, message);
294
+ if (!rawComponent) {
293
295
  diagnostics.push({ severity: 'warning', file: entry.spec, message: `Cannot derive component for message on channel "${channelAddress}" — skipping` });
294
296
  continue;
295
297
  }
298
+ const component = applyComponentNameReplacements(rawComponent, componentNameReplacements);
296
299
  const namingCtx = entry.messageNaming ? { strategy: entry.messageNaming, operation } : undefined;
297
300
  const nameResult = deriveMessageName(message, namingCtx, entry.spec);
298
301
  if (!nameResult) {
@@ -335,7 +338,7 @@ export function mapDocument(document, entry, packConfig) {
335
338
  const schemaId = deriveNodeId('schema', component, schemaKey, { parentId: eventId, section: 'schemas' });
336
339
  nodes.push(makeNode(packConfig.constructs['payloadSchema']?.template ?? 'Schema', component, entry.spec, schemaId));
337
340
  edges.push({ id: `${eventId}__has-field__${schemaId}`, from: eventId, to: schemaId, type: 'has-field', state: 'implemented', stability: 'unstable' });
338
- emitFields(sourceSchema, schemaId, 'fields', eventId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map());
341
+ emitFields(sourceSchema, schemaId, 'fields', eventId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map(), new Map());
339
342
  properties.payload = `#/schemas/${schemaKey}`;
340
343
  }
341
344
  }
@@ -344,7 +347,7 @@ export function mapDocument(document, entry, packConfig) {
344
347
  const schemaId = deriveNodeId('schema', component, messageName, { parentId: eventId, section: 'schemas' });
345
348
  nodes.push(makeNode(packConfig.constructs['payloadSchema']?.template ?? 'Schema', component, entry.spec, schemaId));
346
349
  edges.push({ id: `${eventId}__has-field__${schemaId}`, from: eventId, to: schemaId, type: 'has-field', state: 'implemented', stability: 'unstable' });
347
- emitFields(rawPayload, schemaId, 'fields', eventId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map());
350
+ emitFields(rawPayload, schemaId, 'fields', eventId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map(), new Map());
348
351
  properties.payload = `#/schemas/${messageName}`;
349
352
  }
350
353
  else {
@@ -404,7 +407,7 @@ function resolveAllOfRef(schema) {
404
407
  return s.allOf[0];
405
408
  return schema;
406
409
  }
407
- function resolveSchemaRef(schemaName, nullable, collection, readsSource, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
410
+ function resolveSchemaRef(schemaName, nullable, collection, readsSource, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
408
411
  const extra = { nullable };
409
412
  if (collection)
410
413
  extra.collection = collection;
@@ -424,14 +427,61 @@ function resolveSchemaRef(schemaName, nullable, collection, readsSource, rootId,
424
427
  edges.push({ id: `${rootId}__has-field__${inlineId}`, from: rootId, to: inlineId, type: 'has-field', state: 'implemented', stability: 'unstable' });
425
428
  const localRef = `#/schemas/${schemaName}`;
426
429
  localSchemas.set(schemaName, localRef);
427
- emitFields(src, inlineId, 'fields', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
430
+ emitFields(src, inlineId, 'fields', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
428
431
  }
429
432
  return { $ref: localSchemas.get(schemaName) ?? `#/schemas/${schemaName}`, ...extra };
430
433
  }
431
434
  }
432
435
  return { $ref: schemaName, ...extra };
433
436
  }
434
- function emitFields(schema, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
437
+ function createMapping(mappingName, addlRaw, parentId, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
438
+ const existingId = localMappings.get(mappingName);
439
+ if (existingId)
440
+ return existingId;
441
+ const mappingId = `${parentId}.mappings.${mappingName}`;
442
+ const mappingNode = makeNode('Mapping', component, specPath, mappingId);
443
+ const props = {};
444
+ if (!addlRaw || typeof addlRaw === 'boolean') {
445
+ props['type'] = 'string';
446
+ }
447
+ else {
448
+ const addl = addlRaw;
449
+ if (addl.$ref) {
450
+ const schemaName = refName(addl.$ref);
451
+ const globalId = sharedSchemas.get(schemaName);
452
+ props['$ref'] = globalId ?? schemaName;
453
+ }
454
+ else if (addl.type === 'array') {
455
+ props['value-collection'] = 'array';
456
+ const items = addl.items ? resolveAllOfRef(addl.items) : undefined;
457
+ if (items && isRefSchema(items)) {
458
+ const schemaName = refName(items.$ref);
459
+ const globalId = sharedSchemas.get(schemaName);
460
+ props['$ref'] = globalId ?? schemaName;
461
+ }
462
+ else if (items) {
463
+ const it = items;
464
+ props['type'] = deriveScalarType(it.type ?? 'string', it.format, packConfig.scalarTypes) ?? 'string';
465
+ }
466
+ else {
467
+ props['type'] = 'string';
468
+ }
469
+ }
470
+ else if (addl.type === 'object' && addl.additionalProperties) {
471
+ const innerName = `${mappingName}-values`;
472
+ const innerId = createMapping(innerName, addl.additionalProperties, parentId, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
473
+ props['$ref'] = innerId;
474
+ }
475
+ else {
476
+ props['type'] = deriveScalarType(addl.type ?? 'string', addl.format, packConfig.scalarTypes) ?? 'string';
477
+ }
478
+ }
479
+ mappingNode.properties = props;
480
+ nodes.push(mappingNode);
481
+ localMappings.set(mappingName, mappingId);
482
+ return mappingId;
483
+ }
484
+ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
435
485
  const readsSource = rootId ?? parentId;
436
486
  const [component] = parentId.split('.');
437
487
  for (const [fieldName, rawFieldSchema] of Object.entries(schema.properties ?? {})) {
@@ -445,7 +495,7 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
445
495
  ? resolvedSchemaId
446
496
  : (isRefSchema(fieldSchema) ? refName(fieldSchema.$ref) : undefined);
447
497
  if (schemaName !== undefined) {
448
- fieldNode.properties = resolveSchemaRef(schemaName, !required, undefined, readsSource, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
498
+ fieldNode.properties = resolveSchemaRef(schemaName, !required, undefined, readsSource, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
449
499
  }
450
500
  else {
451
501
  const fs = fieldSchema;
@@ -464,7 +514,7 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
464
514
  fieldNode.properties = { type: 'string', nullable, collection: 'array' };
465
515
  }
466
516
  else if (isRefSchema(items)) {
467
- fieldNode.properties = resolveSchemaRef(refName(items.$ref), nullable, 'array', readsSource, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
517
+ fieldNode.properties = resolveSchemaRef(refName(items.$ref), nullable, 'array', readsSource, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
468
518
  if (!fieldNode.properties.$ref)
469
519
  fieldNode.properties = { type: 'string', nullable, collection: 'array' };
470
520
  }
@@ -474,21 +524,21 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
474
524
  }
475
525
  }
476
526
  else if (rawType === 'object' && fs.properties) {
477
- if (rootId) {
478
- const inlineId = deriveNodeId('schema', component, fieldName, { parentId: rootId, section: 'schemas' });
479
- if (!nodes.some(n => n.id === inlineId)) {
480
- nodes.push(makeNode(packConfig.constructs['payloadSchema']?.template ?? 'Schema', component, specPath, inlineId));
481
- edges.push({ id: `${rootId}__has-field__${inlineId}`, from: rootId, to: inlineId, type: 'has-field', state: 'implemented', stability: 'unstable' });
482
- const localRef = `#/schemas/${fieldName}`;
483
- localSchemas.set(fieldName, localRef);
484
- emitFields(fs, inlineId, 'fields', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
485
- }
486
- fieldNode.properties = { $ref: localSchemas.get(fieldName) ?? `#/schemas/${fieldName}`, nullable };
487
- }
488
- else {
489
- diagnostics.push({ severity: 'warning', file: specPath, message: `Inline object field "${fieldId}" has no event context — treating as string` });
490
- fieldNode.properties = { type: 'string', nullable };
527
+ const schemaParent = rootId ?? parentId;
528
+ const inlineId = deriveNodeId('schema', component, fieldName, { parentId: schemaParent, section: 'schemas' });
529
+ if (!nodes.some(n => n.id === inlineId)) {
530
+ nodes.push(makeNode(packConfig.constructs['payloadSchema']?.template ?? 'Schema', component, specPath, inlineId));
531
+ edges.push({ id: `${schemaParent}__has-field__${inlineId}`, from: schemaParent, to: inlineId, type: 'has-field', state: 'implemented', stability: 'unstable' });
532
+ const localRef = `#/schemas/${fieldName}`;
533
+ localSchemas.set(fieldName, localRef);
534
+ emitFields(fs, inlineId, 'fields', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
491
535
  }
536
+ fieldNode.properties = { $ref: localSchemas.get(fieldName) ?? `#/schemas/${fieldName}`, nullable };
537
+ }
538
+ else if (rawType === 'object' && fs.additionalProperties) {
539
+ // Map/dictionary: emit a Mapping node scoped to the parent schema, ref it from the field
540
+ createMapping(fieldName, fs.additionalProperties, parentId, rootId, component, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
541
+ fieldNode.properties = { $ref: `#/mappings/${fieldName}`, nullable };
492
542
  }
493
543
  else {
494
544
  const scalarType = deriveScalarType(rawType, fs.format, packConfig.scalarTypes);
@@ -6,7 +6,7 @@ export class OpenAPIAdapter {
6
6
  const { document, diagnostics } = await parseSpec(entry.spec);
7
7
  if (!document)
8
8
  return { nodes: [], edges: [], diagnostics };
9
- const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry, context.packConfig);
9
+ const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry, context.packConfig, context.componentNameReplacements);
10
10
  return { nodes, edges, diagnostics: [...diagnostics, ...mapDiagnostics] };
11
11
  }
12
12
  }
@@ -1,3 +1,4 @@
1
+ import { applyComponentNameReplacements } from '../../import/config.js';
1
2
  export function deriveComponent(path, mapping) {
2
3
  if (mapping.strategy === 'hardcoded')
3
4
  return mapping.component;
@@ -42,7 +43,7 @@ function emitReadsEdge(from, to, edges) {
42
43
  edges.push({ id, from, to, type: 'reads', state: 'implemented', stability: 'unstable' });
43
44
  }
44
45
  }
45
- export function mapDocument(document, entry, packConfig) {
46
+ export function mapDocument(document, entry, packConfig, componentNameReplacements = []) {
46
47
  const nodes = [];
47
48
  const edges = [];
48
49
  const diagnostics = [];
@@ -62,7 +63,7 @@ export function mapDocument(document, entry, packConfig) {
62
63
  if (isRefSchema(schema))
63
64
  continue;
64
65
  const s = schema;
65
- const component = deriveComponentForSchema(name, document, entry);
66
+ const component = deriveComponentForSchema(name, document, entry, componentNameReplacements);
66
67
  if (!component)
67
68
  continue;
68
69
  if (s.type !== 'object' && s.enum) {
@@ -105,7 +106,7 @@ export function mapDocument(document, entry, packConfig) {
105
106
  const [component] = schemaId.split('.');
106
107
  const node = makeNode(packConfig.constructs.requestSchema?.template ?? 'Schema', component, entry.spec, schemaId);
107
108
  nodes.push(node);
108
- emitFields(s, schemaId, 'fields', undefined, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map());
109
+ emitFields(s, schemaId, 'fields', undefined, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map(), new Map());
109
110
  }
110
111
  }
111
112
  for (const [urlPath, pathItem] of Object.entries(document.paths ?? {})) {
@@ -117,9 +118,12 @@ export function mapDocument(document, entry, packConfig) {
117
118
  if (!operation)
118
119
  continue;
119
120
  const operationId = operation.operationId ?? `${method}-${urlPath.replace(/\//g, '-').replace(/^-/, '')}`;
120
- const component = entry.componentMapping.strategy === 'tag'
121
+ const rawComponent = entry.componentMapping.strategy === 'tag'
121
122
  ? operation.tags?.[0]
122
123
  : deriveComponent(urlPath, entry.componentMapping);
124
+ const component = rawComponent !== undefined
125
+ ? applyComponentNameReplacements(rawComponent, componentNameReplacements)
126
+ : undefined;
123
127
  if (!component) {
124
128
  diagnostics.push({ severity: 'warning', file: entry.spec, message: `Cannot derive component for ${method.toUpperCase()} ${urlPath}, skipping` });
125
129
  continue;
@@ -136,11 +140,12 @@ export function mapDocument(document, entry, packConfig) {
136
140
  if (parameters)
137
141
  endpointNode.properties.parameters = parameters;
138
142
  const localSchemas = new Map();
143
+ const localMappings = new Map();
139
144
  const requestBody = operation.requestBody;
140
145
  if (requestBody?.content) {
141
146
  const jsonContent = requestBody.content['application/json'];
142
147
  if (jsonContent?.schema) {
143
- const ref = emitSchemaNode(jsonContent.schema, `${operationId}-request`, endpointId, 'schemas', endpointId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
148
+ const ref = emitSchemaNode(jsonContent.schema, `${operationId}-request`, endpointId, 'schemas', endpointId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
144
149
  if (ref)
145
150
  endpointNode.properties.request = ref;
146
151
  }
@@ -150,7 +155,7 @@ export function mapDocument(document, entry, packConfig) {
150
155
  const responseObj = response;
151
156
  const jsonContent = responseObj.content?.['application/json'];
152
157
  if (jsonContent?.schema) {
153
- const ref = emitSchemaNode(jsonContent.schema, `${operationId}-response-${status}`, endpointId, 'schemas', endpointId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
158
+ const ref = emitSchemaNode(jsonContent.schema, `${operationId}-response-${status}`, endpointId, 'schemas', endpointId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
154
159
  if (ref)
155
160
  responses[status] = ref;
156
161
  }
@@ -272,7 +277,7 @@ function makeNode(template, component, specPath, id) {
272
277
  properties: {},
273
278
  };
274
279
  }
275
- function emitSchemaNode(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
280
+ function emitSchemaNode(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
276
281
  schema = resolveAllOfRef(schema);
277
282
  if (isRefSchema(schema)) {
278
283
  const schemaName = refName(schema.$ref);
@@ -287,15 +292,15 @@ function emitSchemaNode(schema, name, parentId, section, rootId, packConfig, spe
287
292
  const sourceSchema = sourceSchemas.get(schemaName);
288
293
  if (sourceSchema) {
289
294
  const effectiveParent = rootId ?? parentId;
290
- return createInlineSchema(sourceSchema, schemaName, effectiveParent, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
295
+ return createInlineSchema(sourceSchema, schemaName, effectiveParent, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
291
296
  }
292
297
  return undefined;
293
298
  }
294
299
  if (localSchemas.has(name))
295
300
  return localSchemas.get(name);
296
- return createInlineSchema(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
301
+ return createInlineSchema(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
297
302
  }
298
- function createInlineSchema(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
303
+ function createInlineSchema(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
299
304
  const schemaId = deriveNodeId('schema', undefined, name, parentId, section);
300
305
  const [component] = parentId.split('.');
301
306
  const node = makeNode(packConfig.constructs.requestSchema?.template ?? 'Schema', component, specPath, schemaId);
@@ -303,10 +308,10 @@ function createInlineSchema(schema, name, parentId, section, rootId, packConfig,
303
308
  edges.push({ id: `${parentId}__has-field__${schemaId}`, from: parentId, to: schemaId, type: 'has-field', state: 'implemented', stability: 'unstable' });
304
309
  const localRef = `#/${section}/${name}`;
305
310
  localSchemas.set(name, localRef);
306
- emitFields(schema, schemaId, 'fields', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
311
+ emitFields(schema, schemaId, 'fields', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
307
312
  return localRef;
308
313
  }
309
- function resolveFieldRef(schemaName, collection, required, rootId, readsSource, refSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
314
+ function resolveFieldRef(schemaName, collection, required, rootId, readsSource, refSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
310
315
  const extra = { nullable: !required };
311
316
  if (collection !== 'one')
312
317
  extra.collection = collection;
@@ -318,13 +323,94 @@ function resolveFieldRef(schemaName, collection, required, rootId, readsSource,
318
323
  if (localSchemas.has(schemaName))
319
324
  return { $ref: localSchemas.get(schemaName), ...extra };
320
325
  if (rootId) {
321
- const localRef = emitSchemaNode(refSchema, schemaName, rootId, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
326
+ const localRef = emitSchemaNode(refSchema, schemaName, rootId, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
322
327
  if (localRef)
323
328
  return { $ref: localRef, ...extra };
324
329
  }
325
330
  return { $ref: schemaName, ...extra };
326
331
  }
327
- function emitFields(schema, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
332
+ function createMapping(mappingName, addlRaw, parentId, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
333
+ const existingId = localMappings.get(mappingName);
334
+ if (existingId)
335
+ return existingId;
336
+ const [component] = parentId.split('.');
337
+ const mappingId = `${parentId}.mappings.${mappingName}`;
338
+ const mappingNode = makeNode('Mapping', component, specPath, mappingId);
339
+ const props = {};
340
+ if (typeof addlRaw === 'boolean' || addlRaw === undefined) {
341
+ props['type'] = 'string';
342
+ }
343
+ else {
344
+ const addlSchema = resolveAllOfRef(addlRaw);
345
+ if (isRefSchema(addlSchema)) {
346
+ const valueSchemaName = refName(addlSchema.$ref);
347
+ const globalId = sharedSchemas.get(valueSchemaName);
348
+ if (globalId) {
349
+ props['$ref'] = globalId;
350
+ }
351
+ else {
352
+ const localRef = localSchemas.get(valueSchemaName);
353
+ if (localRef) {
354
+ props['$ref'] = localRef;
355
+ }
356
+ else if (rootId) {
357
+ const emitted = emitSchemaNode(addlSchema, valueSchemaName, rootId, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
358
+ props['$ref'] = emitted ?? valueSchemaName;
359
+ }
360
+ else {
361
+ props['$ref'] = valueSchemaName;
362
+ }
363
+ }
364
+ }
365
+ else {
366
+ const addlObj = addlSchema;
367
+ if (addlObj.type === 'array') {
368
+ const rawItems = addlObj.items;
369
+ const items = rawItems ? resolveAllOfRef(rawItems) : undefined;
370
+ props['value-collection'] = 'array';
371
+ if (items && isRefSchema(items)) {
372
+ const valueSchemaName = refName(items.$ref);
373
+ const globalId = sharedSchemas.get(valueSchemaName);
374
+ if (globalId) {
375
+ props['$ref'] = globalId;
376
+ }
377
+ else {
378
+ const localRef = localSchemas.get(valueSchemaName);
379
+ if (localRef) {
380
+ props['$ref'] = localRef;
381
+ }
382
+ else if (rootId) {
383
+ const emitted = emitSchemaNode(items, valueSchemaName, rootId, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
384
+ props['$ref'] = emitted ?? valueSchemaName;
385
+ }
386
+ else {
387
+ props['$ref'] = valueSchemaName;
388
+ }
389
+ }
390
+ }
391
+ else {
392
+ const scalarType = items ? deriveScalarType(items.type ?? 'string', items.format, packConfig.scalarTypes) : undefined;
393
+ props['type'] = scalarType ?? 'string';
394
+ }
395
+ }
396
+ else if (addlObj.type === 'object' && addlObj.additionalProperties) {
397
+ // map-of-map: inner additionalProperties → second Mapping node
398
+ const innerName = `${mappingName}-values`;
399
+ const innerRef = createMapping(innerName, addlObj.additionalProperties, parentId, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
400
+ props['$ref'] = innerRef;
401
+ }
402
+ else {
403
+ const scalarType = deriveScalarType(addlObj.type ?? 'string', addlObj.format, packConfig.scalarTypes);
404
+ props['type'] = scalarType ?? 'string';
405
+ }
406
+ }
407
+ }
408
+ mappingNode.properties = props;
409
+ nodes.push(mappingNode);
410
+ localMappings.set(mappingName, mappingId);
411
+ return mappingId;
412
+ }
413
+ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings) {
328
414
  // readsSource: when in endpoint context use rootId, otherwise use the schema itself
329
415
  const readsSource = rootId ?? parentId;
330
416
  for (const [fieldName, rawFieldSchema] of Object.entries(schema.properties ?? {})) {
@@ -334,7 +420,7 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
334
420
  const fieldNode = makeNode(packConfig.constructs.schemaProperty?.template ?? 'Field', component, specPath, fieldId);
335
421
  const required = Array.isArray(schema.required) && schema.required.includes(fieldName);
336
422
  if (isRefSchema(fieldSchema)) {
337
- fieldNode.properties = resolveFieldRef(refName(fieldSchema.$ref), 'one', required, rootId, readsSource, fieldSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
423
+ fieldNode.properties = resolveFieldRef(refName(fieldSchema.$ref), 'one', required, rootId, readsSource, fieldSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
338
424
  }
339
425
  else {
340
426
  const fs = fieldSchema;
@@ -349,7 +435,7 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
349
435
  fieldNode.properties = { type: 'string', nullable: !required, collection: 'array' };
350
436
  }
351
437
  else if (isRefSchema(items)) {
352
- fieldNode.properties = resolveFieldRef(refName(items.$ref), 'array', required, rootId, readsSource, items, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
438
+ fieldNode.properties = resolveFieldRef(refName(items.$ref), 'array', required, rootId, readsSource, items, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
353
439
  }
354
440
  else {
355
441
  const itemType = deriveScalarType(items.type ?? 'string', items.format, packConfig.scalarTypes);
@@ -358,70 +444,16 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
358
444
  }
359
445
  else if (fs.type === 'object' && fs.properties) {
360
446
  // Anonymous object with named properties → inline as sibling schema
361
- if (rootId) {
362
- const localRef = emitSchemaNode(fs, fieldName, rootId, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
363
- fieldNode.properties = localRef
364
- ? { $ref: localRef, nullable: !required }
365
- : { type: 'string', nullable: !required };
366
- }
367
- else {
368
- diagnostics.push({ severity: 'warning', file: specPath, message: `Inline object for field ${fieldId} has no endpoint context; treating as string` });
369
- fieldNode.properties = { type: 'string', nullable: !required };
370
- }
447
+ const schemaParent = rootId ?? parentId;
448
+ const localRef = emitSchemaNode(fs, fieldName, schemaParent, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
449
+ fieldNode.properties = localRef
450
+ ? { $ref: localRef, nullable: !required }
451
+ : { type: 'string', nullable: !required };
371
452
  }
372
453
  else if (fs.type === 'object' && fs.additionalProperties) {
373
- // Map/dictionary: keyed collection
374
- const addlRaw = fs.additionalProperties;
375
- if (typeof addlRaw === 'boolean') {
376
- fieldNode.properties = { type: 'string', nullable: !required, collection: 'map' };
377
- }
378
- else {
379
- const addlSchema = resolveAllOfRef(addlRaw);
380
- if (isRefSchema(addlSchema)) {
381
- fieldNode.properties = resolveFieldRef(refName(addlSchema.$ref), 'map', required, rootId, readsSource, addlSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
382
- }
383
- else {
384
- const addlObj = addlSchema;
385
- if (addlObj.type === 'object') {
386
- const innerAddl = addlObj.additionalProperties;
387
- if (!innerAddl || typeof innerAddl === 'boolean') {
388
- fieldNode.properties = { type: 'string', nullable: !required, collection: 'map-of-map' };
389
- }
390
- else {
391
- const innerSchema = resolveAllOfRef(innerAddl);
392
- if (isRefSchema(innerSchema)) {
393
- fieldNode.properties = resolveFieldRef(refName(innerSchema.$ref), 'map-of-map', required, rootId, readsSource, innerSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
394
- }
395
- else {
396
- const inner = innerSchema;
397
- const scalarType = deriveScalarType(inner.type ?? 'string', inner.format, packConfig.scalarTypes);
398
- if (scalarType) {
399
- fieldNode.properties = { type: scalarType, nullable: !required, collection: 'map-of-map' };
400
- }
401
- else {
402
- diagnostics.push({ severity: 'warning', file: specPath, message: `[WARN] Double-nested map for field ${fieldId}; inner value type not representable, using string` });
403
- fieldNode.properties = { type: 'string', nullable: !required, collection: 'map-of-map' };
404
- }
405
- }
406
- }
407
- }
408
- else if (addlObj.type === 'array') {
409
- const rawItems = addlObj.items;
410
- const items = rawItems ? resolveAllOfRef(rawItems) : undefined;
411
- if (items && isRefSchema(items)) {
412
- fieldNode.properties = resolveFieldRef(refName(items.$ref), 'map-of-array', required, rootId, readsSource, items, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
413
- }
414
- else {
415
- const scalarType = items ? deriveScalarType(items.type ?? 'string', items.format, packConfig.scalarTypes) : undefined;
416
- fieldNode.properties = { type: scalarType ?? 'string', nullable: !required, collection: 'map-of-array' };
417
- }
418
- }
419
- else {
420
- const scalarType = deriveScalarType(addlObj.type ?? 'string', addlObj.format, packConfig.scalarTypes);
421
- fieldNode.properties = { type: scalarType ?? 'string', nullable: !required, collection: 'map' };
422
- }
423
- }
424
- }
454
+ // Map/dictionary: emit a Mapping node scoped to the parent schema, ref it from the field
455
+ createMapping(fieldName, fs.additionalProperties, parentId, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas, localMappings);
456
+ fieldNode.properties = { $ref: `#/mappings/${fieldName}`, nullable: !required };
425
457
  }
426
458
  else {
427
459
  const scalarType = deriveScalarType(fs.type ?? 'string', fs.format, packConfig.scalarTypes);
@@ -438,7 +470,7 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
438
470
  edges.push({ id: `${parentId}__has-field__${fieldId}`, from: parentId, to: fieldId, type: 'has-field', state: 'implemented', stability: 'unstable' });
439
471
  }
440
472
  }
441
- function deriveComponentForSchema(name, document, entry, visited = new Set()) {
473
+ function deriveComponentForSchema(name, document, entry, componentNameReplacements, visited = new Set()) {
442
474
  if (visited.has(name))
443
475
  return undefined;
444
476
  visited.add(name);
@@ -452,11 +484,11 @@ function deriveComponentForSchema(name, document, entry, visited = new Set()) {
452
484
  if (!operation)
453
485
  continue;
454
486
  if (referencesSchema(operation, name)) {
455
- const component = entry.componentMapping.strategy === 'tag'
487
+ const rawComponent = entry.componentMapping.strategy === 'tag'
456
488
  ? operation.tags?.[0]
457
489
  : deriveComponent(urlPath, entry.componentMapping);
458
- if (component)
459
- directComponents.add(component);
490
+ if (rawComponent)
491
+ directComponents.add(applyComponentNameReplacements(rawComponent, componentNameReplacements));
460
492
  }
461
493
  }
462
494
  }
@@ -468,7 +500,7 @@ function deriveComponentForSchema(name, document, entry, visited = new Set()) {
468
500
  if (schemaName === name || isRefSchema(schema))
469
501
  continue;
470
502
  if (JSON.stringify(schema).includes(`"#/components/schemas/${name}"`)) {
471
- const comp = deriveComponentForSchema(schemaName, document, entry, visited);
503
+ const comp = deriveComponentForSchema(schemaName, document, entry, componentNameReplacements, visited);
472
504
  if (comp)
473
505
  return comp;
474
506
  }
@@ -22,7 +22,8 @@ const program = new Command();
22
22
  program
23
23
  .name('corum')
24
24
  .description('Corum graph CLI')
25
- .version(version);
25
+ .version(version)
26
+ .addHelpText('after', '\nFull documentation: https://github.com/atolis-hq/corum#readme');
26
27
  program
27
28
  .command('mcp')
28
29
  .description('Start the MCP stdio server (+ web UI by default)')
@@ -145,6 +146,7 @@ const importCmd = program.command('import')
145
146
  .description('Import specifications into the graph')
146
147
  .option('--config <path>', 'Path to import config YAML')
147
148
  .option('--graph <path>', 'Override CORUM_GRAPH_PATH')
149
+ .addHelpText('after', '\nFor import config file format and options, see: https://github.com/atolis-hq/corum#readme')
148
150
  .action(async (opts) => {
149
151
  if (!opts.config) {
150
152
  importCmd.help();
@@ -11,7 +11,16 @@ export function loadImportConfig(filePath) {
11
11
  if (!isImportConfig(raw)) {
12
12
  throw new Error(`Invalid import config: must have an "imports" array`);
13
13
  }
14
- return raw;
14
+ const cfg = raw;
15
+ for (const replacement of cfg.componentNameReplacements ?? []) {
16
+ if (!replacement.from || !replacement.to) {
17
+ throw new Error(`Invalid import config: componentNameReplacements entries must have non-empty "from" and "to"`);
18
+ }
19
+ }
20
+ return cfg;
21
+ }
22
+ export function applyComponentNameReplacements(name, replacements) {
23
+ return replacements.find(r => r.from === name)?.to ?? name;
15
24
  }
16
25
  function isImportConfig(value) {
17
26
  return (typeof value === 'object' &&
@@ -20,7 +20,11 @@ export async function runImport(config, runtimeConfig) {
20
20
  const specPath = path.resolve(entry.spec);
21
21
  const resolvedEntry = { ...entry, spec: specPath };
22
22
  const adapter = getAdapter(resolvedEntry.adapter);
23
- const result = await adapter.import(resolvedEntry, { packConfig, templates: graph.templates });
23
+ const result = await adapter.import(resolvedEntry, {
24
+ packConfig,
25
+ templates: graph.templates,
26
+ componentNameReplacements: config.componentNameReplacements ?? [],
27
+ });
24
28
  allDiagnostics.push(...result.diagnostics);
25
29
  if (result.diagnostics.some(d => d.severity === 'error'))
26
30
  continue;
@@ -67,16 +67,36 @@ function summarizeNodeForNavigation(graph, node) {
67
67
  ...(ownership ?? {}),
68
68
  };
69
69
  }
70
+ function resolveLocalRef(graph, nodeId, section, name) {
71
+ // Walk up the node ID hierarchy to find the nearest ancestor owning section.name.
72
+ // This handles refs on both root nodes and nested Field nodes correctly.
73
+ let ancestor = nodeId.replace(/\.fields\.[^.]+$/, '');
74
+ while (ancestor.length > 0) {
75
+ const candidate = `${ancestor}.${section}.${name}`;
76
+ if (graph.nodesById.has(candidate))
77
+ return candidate;
78
+ const dot = ancestor.lastIndexOf('.');
79
+ if (dot === -1)
80
+ break;
81
+ ancestor = ancestor.slice(0, dot);
82
+ }
83
+ return undefined;
84
+ }
70
85
  function resolveNodeRef(graph, node, rawValue) {
71
86
  if (rawValue.startsWith('#/schemas/')) {
72
87
  const name = rawValue.slice(10);
73
- const id = `${node.id}.schemas.${name}`;
74
- return graph.nodesById.has(id) ? { display: name, nodeId: id } : { display: name };
88
+ const id = resolveLocalRef(graph, node.id, 'schemas', name);
89
+ return id ? { display: name, nodeId: id } : { display: name };
75
90
  }
76
91
  if (rawValue.startsWith('#/enums/')) {
77
92
  const name = rawValue.slice(8);
78
- const id = `${node.id}.enums.${name}`;
79
- return graph.nodesById.has(id) ? { display: name, nodeId: id } : { display: name };
93
+ const id = resolveLocalRef(graph, node.id, 'enums', name);
94
+ return id ? { display: name, nodeId: id } : { display: name };
95
+ }
96
+ if (rawValue.startsWith('#/mappings/')) {
97
+ const name = rawValue.slice(11);
98
+ const id = resolveLocalRef(graph, node.id, 'mappings', name);
99
+ return id ? { display: name, nodeId: id } : { display: name };
80
100
  }
81
101
  if (graph.nodesById.has(rawValue))
82
102
  return { display: rawValue, nodeId: rawValue };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.18",
3
+ "version": "0.1.20",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
package/web/app.jsx CHANGED
@@ -420,7 +420,7 @@ function NodePage({ nodeId, templates, onNavigate, refreshToken, viewingRef, ove
420
420
  const rootSpecializedTemplates = new Set(['Schema', 'EnumDefinition']);
421
421
  const rootSpecializedNodes = rootSpecializedTemplates.has(root.template) ? [[root.template, [root]]] : [];
422
422
  const childDisplayEntries = [...displayChildren.entries()]
423
- .filter(([templateName]) => templateName !== 'Field' && templateName !== 'EnumValue');
423
+ .filter(([templateName]) => templateName !== 'Field' && templateName !== 'EnumValue' && templateName !== 'Mapping');
424
424
  const displayEntries = [...rootSpecializedNodes, ...childDisplayEntries];
425
425
  const includedSchemaNodes = includedNodes.filter(n => n.template === 'Schema');
426
426
  const includedEnumNodes = includedNodes.filter(n => n.template === 'EnumDefinition');
@@ -212,7 +212,7 @@ function fieldLocalName(nodeId) {
212
212
  }
213
213
 
214
214
  function clusterNodeId(nodeId) {
215
- const sectionMatch = nodeId.match(/\.(schemas|enums|operations)\./);
215
+ const sectionMatch = nodeId.match(/\.(schemas|enums|mappings|operations)\./);
216
216
  if (sectionMatch && sectionMatch.index !== undefined) {
217
217
  return nodeId.slice(0, sectionMatch.index);
218
218
  }
@@ -221,7 +221,7 @@ function clusterNodeId(nodeId) {
221
221
 
222
222
  function refName(ref, compact = false) {
223
223
  if (typeof ref === 'string') {
224
- const full = ref.replace(/^#\/(schemas|enums)\//, '');
224
+ const full = ref.replace(/^#\/(schemas|enums|mappings)\//, '');
225
225
  if (compact) {
226
226
  const dot = full.lastIndexOf('.');
227
227
  return dot >= 0 ? full.slice(dot + 1) : full;
@@ -249,6 +249,7 @@ function refLocalSchemaName(ref) {
249
249
  return null;
250
250
  }
251
251
  if (ref.startsWith('#/schemas/')) return ref.slice(10);
252
+ if (ref.startsWith('#/mappings/')) return ref.slice(11);
252
253
  // Global node ID (e.g. "component.Schema.TypeName") — local name is the final segment
253
254
  const lastDot = ref.lastIndexOf('.');
254
255
  return lastDot >= 0 ? ref.slice(lastDot + 1) : null;
@@ -256,7 +257,7 @@ function refLocalSchemaName(ref) {
256
257
 
257
258
  function fieldType(properties, compact = false) {
258
259
  const c = properties?.collection;
259
- const suffix = c === 'array' ? '[]' : c === 'map' ? '{}' : c === 'map-of-map' ? '{{}}' : c === 'map-of-array' ? '{[]}' : '';
260
+ const suffix = c === 'array' ? '[]' : '';
260
261
  if (properties?.type) return `${properties.type}${suffix}`;
261
262
  const ref = properties?.['$ref'];
262
263
  if (ref) return `${refName(ref, compact)}${suffix}`;
@@ -325,7 +326,9 @@ function enumValueDescription(node) {
325
326
  function buildSchemaModel(schemaNodes, allNodes) {
326
327
  // Include all Schema nodes from allNodes so canExpand works for included/referenced schemas
327
328
  const allSchemaNodes = (allNodes ?? []).filter(n => n.template === 'Schema');
329
+ const allMappingNodes = (allNodes ?? []).filter(n => n.template === 'Mapping');
328
330
  const schemasByName = new Map(allSchemaNodes.map(node => [localSchemaName(node.id), node]));
331
+ const mappingsByNodeId = new Map(allMappingNodes.map(node => [node.id, node]));
329
332
  // Ensure the primary schemaNodes are always present (they may not be in allNodes)
330
333
  for (const node of schemaNodes) schemasByName.set(localSchemaName(node.id), node);
331
334
  const fieldsBySchema = new Map();
@@ -348,11 +351,86 @@ function buildSchemaModel(schemaNodes, allNodes) {
348
351
  const topSchemas = schemaNodes.filter(node => !referencedSchemas.has(localSchemaName(node.id)));
349
352
  return {
350
353
  schemasByName,
354
+ mappingsByNodeId,
351
355
  fieldsBySchema,
352
356
  topSchemas: topSchemas.length > 0 ? topSchemas : schemaNodes,
353
357
  };
354
358
  }
355
359
 
360
+ function MappingInlineRows({ mappingNode, depth, model, edges, compact, visited = new Set() }) {
361
+ const [valueCollapsed, setValueCollapsed] = React.useState(false);
362
+ const keyType = mappingNode.properties?.['key-type'];
363
+ const keyRef = mappingNode.properties?.['key-ref'];
364
+ const valueType = mappingNode.properties?.['type'];
365
+ const valueRef = mappingNode.properties?.['$ref'];
366
+ const valueRefNodeId = valueRef && typeof valueRef === 'object' && 'nodeId' in valueRef
367
+ ? valueRef.nodeId : null;
368
+ const valueLocalRef = valueRef ? refLocalSchemaName(valueRef) : null;
369
+ const valueSchema = (valueLocalRef && model.schemasByName.has(valueLocalRef))
370
+ ? model.schemasByName.get(valueLocalRef) : null;
371
+ const valueMappingNode = (valueRefNodeId && model.mappingsByNodeId?.has(valueRefNodeId))
372
+ ? model.mappingsByNodeId.get(valueRefNodeId) : null;
373
+ const valueCanExpandSchema = !!valueSchema && !visited.has(valueLocalRef);
374
+ const valueCanExpandMapping = !!valueMappingNode && !visited.has(valueRefNodeId);
375
+ const valueCanExpand = valueCanExpandSchema || valueCanExpandMapping;
376
+ const keyDisplay = keyType ?? (keyRef ? refName(keyRef, compact) : 'string');
377
+ const valueDisplay = valueType ?? (valueRef ? refName(valueRef, compact) : '-');
378
+ const valueCollection = mappingNode.properties?.['value-collection'];
379
+ const nextVisited = new Set(visited);
380
+ if (valueLocalRef) nextVisited.add(valueLocalRef);
381
+ if (valueRefNodeId) nextVisited.add(valueRefNodeId);
382
+
383
+ return (
384
+ <>
385
+ <div className="field-row nested mapping-meta" style={{ '--field-depth': depth }}>
386
+ <div className="gutter" />
387
+ <div className="name">_key</div>
388
+ <div className="type">{keyDisplay}</div>
389
+ <div className="cardinality">-</div>
390
+ <div className="req">-</div>
391
+ <div className="state" />
392
+ <div className="lineage" />
393
+ </div>
394
+ <div className="field-row nested mapping-meta" style={{ '--field-depth': depth }}>
395
+ <div
396
+ className="gutter"
397
+ style={valueCanExpand ? { cursor: 'pointer' } : undefined}
398
+ onClick={valueCanExpand ? () => setValueCollapsed(prev => !prev) : undefined}
399
+ >
400
+ {valueCanExpand && <Icon name={valueCollapsed ? 'caret-right' : 'caret-down'} size={11} />}
401
+ </div>
402
+ <div className="name">_value</div>
403
+ <div className="type">{valueDisplay}</div>
404
+ <div className="cardinality">{valueCollection ?? 'one'}</div>
405
+ <div className="req">-</div>
406
+ <div className="state" />
407
+ <div className="lineage" />
408
+ </div>
409
+ {valueCanExpand && !valueCollapsed && (
410
+ valueCanExpandSchema ? (
411
+ <SchemaFieldRows
412
+ schemaName={valueLocalRef}
413
+ model={model}
414
+ depth={depth + 1}
415
+ visited={nextVisited}
416
+ edges={edges}
417
+ compact={compact}
418
+ />
419
+ ) : (
420
+ <MappingInlineRows
421
+ mappingNode={valueMappingNode}
422
+ depth={depth + 1}
423
+ model={model}
424
+ edges={edges}
425
+ compact={compact}
426
+ visited={nextVisited}
427
+ />
428
+ )
429
+ )}
430
+ </>
431
+ );
432
+ }
433
+
356
434
  function SchemaFieldRows({ schemaName, model, prefix = '', depth = 0, visited = new Set(), edges = [], overlayFields, overlayRefs, compact = false }) {
357
435
  const [collapsed, setCollapsed] = React.useState(new Set());
358
436
  const fields = model.fieldsBySchema.get(schemaName) ?? [];
@@ -376,11 +454,15 @@ function SchemaFieldRows({ schemaName, model, prefix = '', depth = 0, visited =
376
454
  const name = fieldLocalName(field.id);
377
455
  const ref = field.properties?.['$ref'];
378
456
  const localRef = refLocalSchemaName(ref);
379
- const canExpand = localRef !== null && model.schemasByName.has(localRef) && !visited.has(localRef);
380
- const childSchemaNode = canExpand ? model.schemasByName.get(localRef) : null;
457
+ const refNodeId = ref && typeof ref === 'object' && 'nodeId' in ref ? ref.nodeId : null;
458
+ const mappingNode = refNodeId ? (model.mappingsByNodeId?.get(refNodeId) ?? null) : null;
459
+ const canExpandMapping = !!mappingNode;
460
+ const childSchemaNode = (!canExpandMapping && localRef) ? (model.schemasByName.get(localRef) ?? null) : null;
461
+ const canExpand = !!childSchemaNode && !visited.has(localRef);
462
+ const isExpandable = canExpand || canExpandMapping;
381
463
  const childGhostFields = childSchemaNode ? overlayFieldsForSchema(overlayFields, childSchemaNode.id) : [];
382
464
  const c = field.properties?.collection;
383
- const childPrefix = `${prefix}${name}${c === 'map-of-map' || c === 'map-of-array' ? '[][].' : c === 'array' || c === 'map' ? '[].' : '.'}`;
465
+ const childPrefix = `${prefix}${name}${c === 'array' ? '[].' : '.'}`;
384
466
  const nextVisited = new Set(visited);
385
467
  nextVisited.add(schemaName);
386
468
  const links = edges.filter(e =>
@@ -397,18 +479,18 @@ function SchemaFieldRows({ schemaName, model, prefix = '', depth = 0, visited =
397
479
  <div className={`field-row${depth > 0 ? ' nested' : ''}`} style={{ '--field-depth': depth }}>
398
480
  <div
399
481
  className="gutter"
400
- style={canExpand ? { cursor: 'pointer' } : undefined}
401
- onClick={canExpand ? () => setCollapsed(prev => {
482
+ style={isExpandable ? { cursor: 'pointer' } : undefined}
483
+ onClick={isExpandable ? () => setCollapsed(prev => {
402
484
  const next = new Set(prev);
403
485
  next.has(field.id) ? next.delete(field.id) : next.add(field.id);
404
486
  return next;
405
487
  }) : undefined}
406
488
  >
407
- {canExpand && <Icon name={isCollapsed ? 'caret-right' : 'caret-down'} size={11} />}
489
+ {isExpandable && <Icon name={isCollapsed ? 'caret-right' : 'caret-down'} size={11} />}
408
490
  </div>
409
491
  <div className="name">{compact ? name : `${prefix}${name}`}</div>
410
492
  <div className="type" title={typeFull !== typeDisplay ? typeFull : undefined}>{typeDisplay}</div>
411
- <div className="cardinality">{fieldCardinality(field.properties)}</div>
493
+ <div className="cardinality">{canExpandMapping ? 'map' : fieldCardinality(field.properties)}</div>
412
494
  <div className="req">{fieldRequirement(field.properties)}</div>
413
495
  <div className="state"><StateTag state={field.state} /></div>
414
496
  <div className="lineage">
@@ -431,23 +513,33 @@ function SchemaFieldRows({ schemaName, model, prefix = '', depth = 0, visited =
431
513
  : fieldDetails(field.properties, compact)}
432
514
  </div>
433
515
  </div>
434
- {canExpand && !isCollapsed && (
435
- <>
436
- <SchemaFieldRows
437
- schemaName={localRef}
438
- model={model}
439
- prefix={childPrefix}
516
+ {isExpandable && !isCollapsed && (
517
+ canExpandMapping ? (
518
+ <MappingInlineRows
519
+ mappingNode={mappingNode}
440
520
  depth={depth + 1}
441
- visited={nextVisited}
521
+ model={model}
442
522
  edges={edges}
443
- overlayFields={overlayFields}
444
- overlayRefs={overlayRefs}
445
523
  compact={compact}
446
524
  />
447
- {childGhostFields.length > 0 && (
448
- <GhostFieldRows fields={childGhostFields} overlayRefs={overlayRefs} prefix={childPrefix} depth={depth + 1} compact={compact} />
449
- )}
450
- </>
525
+ ) : (
526
+ <>
527
+ <SchemaFieldRows
528
+ schemaName={localRef}
529
+ model={model}
530
+ prefix={childPrefix}
531
+ depth={depth + 1}
532
+ visited={nextVisited}
533
+ edges={edges}
534
+ overlayFields={overlayFields}
535
+ overlayRefs={overlayRefs}
536
+ compact={compact}
537
+ />
538
+ {childGhostFields.length > 0 && (
539
+ <GhostFieldRows fields={childGhostFields} overlayRefs={overlayRefs} prefix={childPrefix} depth={depth + 1} compact={compact} />
540
+ )}
541
+ </>
542
+ )
451
543
  )}
452
544
  </React.Fragment>
453
545
  );
package/web/style.css CHANGED
@@ -785,6 +785,11 @@ button {
785
785
  .signal-dot-0 { background: var(--accent); }
786
786
  .signal-dot-1 { background: #5c7aa8; }
787
787
 
788
+ .field-row.mapping-meta .name {
789
+ color: var(--ink-3);
790
+ font-weight: 500;
791
+ }
792
+
788
793
  .field-row.overlay-ghost {
789
794
  opacity: 0.7;
790
795
  background: color-mix(in oklch, var(--ink) 6%, var(--paper));