@atolis-hq/corum 0.1.39 → 0.1.41

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.
@@ -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, context.componentNameReplacements);
9
+ const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry, context.packConfig, context.componentNameReplacements, context.existingSchemas);
10
10
  return { nodes, edges, diagnostics: [...diagnostics, ...mapDiagnostics] };
11
11
  }
12
12
  }
@@ -1,4 +1,6 @@
1
1
  import { applyComponentNameReplacements } from '../../import/config.js';
2
+ import { sanitizeIdSegment } from '../../loader/id-grammar.js';
3
+ import { shapeDriftDiagnostic } from '../shared/schema-reuse.js';
2
4
  export function extractValue(strategy, operation, message) {
3
5
  switch (strategy.strategy) {
4
6
  case 'channel-segment': {
@@ -76,9 +78,11 @@ export function classifyEvent(classification, operation, message) {
76
78
  return value === classification.domainValue ? 'DomainEvent' : 'IntegrationEvent';
77
79
  }
78
80
  export function deriveNodeId(kind, component, name, opts) {
81
+ // Spec-supplied names (message names, schema names) may contain dots or other
82
+ // characters reserved by the node ID grammar — sanitise them to one segment.
79
83
  if (kind === 'event')
80
- return `${component}.${opts?.template ?? 'IntegrationEvent'}.${name}`;
81
- return `${opts.parentId}.${opts.section}.${name}`;
84
+ return `${sanitizeIdSegment(component)}.${opts?.template ?? 'IntegrationEvent'}.${sanitizeIdSegment(name)}`;
85
+ return `${opts.parentId}.${opts.section}.${sanitizeIdSegment(name)}`;
82
86
  }
83
87
  // Extract the original component schema name from a resolved schema object.
84
88
  // @asyncapi/parser resolves $refs inline but tags each resolved object with
@@ -205,12 +209,13 @@ export function extractHeaders(rawHeaders, scalarTypes, specPath) {
205
209
  }
206
210
  return { headers, diagnostics };
207
211
  }
208
- export function mapDocument(document, entry, packConfig, componentNameReplacements = []) {
212
+ export function mapDocument(document, entry, packConfig, componentNameReplacements = [], existingSchemas = new Map()) {
209
213
  const nodes = [];
210
214
  const edges = [];
211
215
  const diagnostics = [];
212
216
  const sharedSchemas = new Map();
213
217
  const sourceSchemas = new Map();
218
+ const reusedSchemaNames = new Set();
214
219
  const rawDoc = document.json();
215
220
  for (const [name, schema] of Object.entries(rawDoc.components?.schemas ?? {})) {
216
221
  sourceSchemas.set(name, schema);
@@ -257,8 +262,18 @@ export function mapDocument(document, entry, packConfig, componentNameReplacemen
257
262
  if (s.enum) {
258
263
  sharedSchemas.set(name, `${component}.EnumDefinition.${name}`);
259
264
  }
260
- else if (sharedSchemaNames.has(name)) {
261
- sharedSchemas.set(name, `${component}.Schema.${name}`);
265
+ else {
266
+ const candidateId = `${component}.Schema.${name}`;
267
+ // ADR-009b rule 1: reuse an existing standalone schema before inlining —
268
+ // never demote it, and never duplicate it, even if this document would
269
+ // otherwise treat it as single-use.
270
+ if (existingSchemas.has(candidateId)) {
271
+ sharedSchemas.set(name, candidateId);
272
+ reusedSchemaNames.add(name);
273
+ }
274
+ else if (sharedSchemaNames.has(name)) {
275
+ sharedSchemas.set(name, candidateId);
276
+ }
262
277
  }
263
278
  }
264
279
  for (const [name, schema] of Object.entries(rawDoc.components?.schemas ?? {})) {
@@ -278,11 +293,24 @@ export function mapDocument(document, entry, packConfig, componentNameReplacemen
278
293
  }
279
294
  continue;
280
295
  }
281
- if (!sharedSchemaNames.has(name))
296
+ if (!sharedSchemaNames.has(name) && !reusedSchemaNames.has(name))
282
297
  continue;
283
298
  const [component] = registeredId.split('.');
299
+ if (reusedSchemaNames.has(name)) {
300
+ // ADR-009b rule 2: shape-drift warning — surface contract drift instead of
301
+ // silently merging it. Never create a duplicate/inline node for a reused schema.
302
+ const incomingFields = new Set(Object.keys(s.properties ?? {}));
303
+ const existingFields = existingSchemas.get(registeredId);
304
+ if (existingFields) {
305
+ const drift = shapeDriftDiagnostic(name, registeredId, incomingFields, existingFields, entry.spec);
306
+ if (drift)
307
+ diagnostics.push(drift);
308
+ }
309
+ continue;
310
+ }
284
311
  nodes.push(makeNode(packConfig.constructs['payloadSchema']?.template ?? 'Schema', component, entry.spec, registeredId));
285
312
  emitFields(s, registeredId, 'fields', undefined, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map(), new Map());
313
+ existingSchemas.set(registeredId, new Set(Object.keys(s.properties ?? {})));
286
314
  }
287
315
  const seenMessages = new Map();
288
316
  const allOperations = document.allOperations().all();
@@ -2,11 +2,11 @@ import { parseSpec } from './parser.js';
2
2
  import { mapDocument } from './mapper.js';
3
3
  export class CorumAdapter {
4
4
  adapterId = 'corum';
5
- async import(entry, _context) {
5
+ async import(entry, context) {
6
6
  const { document, diagnostics } = parseSpec(entry.spec);
7
7
  if (!document)
8
8
  return { nodes: [], edges: [], diagnostics };
9
- const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry.spec);
9
+ const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry.spec, context.existingSchemas);
10
10
  return { nodes, edges, diagnostics: [...diagnostics, ...mapDiagnostics] };
11
11
  }
12
12
  }
@@ -1,9 +1,10 @@
1
+ import { shapeDriftDiagnostic } from '../shared/schema-reuse.js';
1
2
  const VALID_EDGE_TYPES = new Set([
2
- 'triggers', 'produces', 'reads', 'calls', 'implements',
3
+ 'triggers', 'produces', 'reads', 'uses-type', 'calls', 'implements',
3
4
  'maps-to', 'derived-from', 'renamed-from', 'has-field', 'has-value',
4
5
  ]);
5
6
  const UNRESOLVED_COMPONENT = '_unresolved';
6
- export function mapDocument(document, specPath) {
7
+ export function mapDocument(document, specPath, existingSchemas = new Map()) {
7
8
  const nodes = [];
8
9
  const edges = [];
9
10
  const diagnostics = [];
@@ -44,7 +45,7 @@ export function mapDocument(document, specPath) {
44
45
  nodes.push(node);
45
46
  if (schemaName) {
46
47
  const expanded = new Map();
47
- expandSchema(schemaName, normalizedNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
48
+ expandSchema(schemaName, normalizedNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents, existingSchemas, diagnostics);
48
49
  }
49
50
  }
50
51
  for (const schemaName of Object.keys(allSchemas)) {
@@ -66,14 +67,14 @@ export function mapDocument(document, specPath) {
66
67
  file: specPath,
67
68
  message: `Schema '${schemaName}' is only referenced by unresolved schema edges; keeping it under ${UNRESOLVED_COMPONENT}`,
68
69
  });
69
- materializeStandaloneSchema(schemaName, UNRESOLVED_COMPONENT, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents);
70
+ materializeStandaloneSchema(schemaName, UNRESOLVED_COMPONENT, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents, existingSchemas, diagnostics);
70
71
  continue;
71
72
  }
72
73
  if (ownership.kind === 'inline') {
73
- expandSchema(schemaName, ownership.rootNodeId, allSchemas, nodes, edges, specPath, ownership.component, new Map(), refToNodeId, schemaComponents);
74
+ expandSchema(schemaName, ownership.rootNodeId, allSchemas, nodes, edges, specPath, ownership.component, new Map(), refToNodeId, schemaComponents, existingSchemas, diagnostics);
74
75
  continue;
75
76
  }
76
- materializeStandaloneSchema(schemaName, ownership.component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents);
77
+ materializeStandaloneSchema(schemaName, ownership.component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents, existingSchemas, diagnostics);
77
78
  }
78
79
  // Build case-insensitive fallback index to handle PascalCase/camelCase mismatches
79
80
  // between edge field refs and actual schema property names
@@ -298,7 +299,7 @@ function localSchemaName(schemaName) {
298
299
  ? schemaName.slice(schemaName.lastIndexOf('.') + 1)
299
300
  : schemaName;
300
301
  }
301
- function materializeStandaloneSchema(schemaName, component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents) {
302
+ function materializeStandaloneSchema(schemaName, component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents, existingSchemas, diagnostics) {
302
303
  const schemaLocalName = localSchemaName(schemaName);
303
304
  const schemaDef = allSchemas[schemaName];
304
305
  const isEnumSchema = Array.isArray(schemaDef?.enum) && !schemaDef?.properties;
@@ -315,7 +316,7 @@ function materializeStandaloneSchema(schemaName, component, allSchemas, nodes, e
315
316
  continue;
316
317
  const valueId = `${schemaId}.values.${value}`;
317
318
  refToNodeId.set(`${schemaRef}/properties/${value}`, valueId);
318
- nodes.push(makeNode('EnumValue', component, specPath, valueId, undefined, { value }));
319
+ nodes.push(makeNode('EnumValue', component, specPath, valueId, undefined, { name: value }));
319
320
  edges.push(makeHasValueEdge(schemaId, valueId));
320
321
  }
321
322
  return schemaId;
@@ -329,13 +330,16 @@ function materializeStandaloneSchema(schemaName, component, allSchemas, nodes, e
329
330
  refToNodeId.set(fieldRef, fieldId);
330
331
  const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
331
332
  const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
332
- fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, schemaId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
333
+ fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, schemaId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents, existingSchemas, diagnostics);
333
334
  nodes.push(fieldNode);
334
335
  edges.push(makeHasFieldEdge(schemaId, fieldId));
335
336
  }
337
+ // ADR-009b rule 1 support: register this newly-materialized standalone schema
338
+ // so later same-run entries (and expandSchema's reuse-before-inline check) see it.
339
+ existingSchemas.set(schemaId, new Set(Object.keys(schemaDef?.properties ?? {})));
336
340
  return schemaId;
337
341
  }
338
- function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents = new Map()) {
342
+ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents = new Map(), existingSchemas = new Map(), diagnostics = []) {
339
343
  const existing = expanded.get(schemaName);
340
344
  if (existing)
341
345
  return existing;
@@ -362,12 +366,28 @@ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath
362
366
  continue;
363
367
  const valueId = `${enumId}.values.${value}`;
364
368
  refToNodeId.set(`${schemaRef}/properties/${value}`, valueId);
365
- nodes.push(makeNode('EnumValue', enumComponent, specPath, valueId, undefined, { value }));
369
+ nodes.push(makeNode('EnumValue', enumComponent, specPath, valueId, undefined, { name: value }));
366
370
  edges.push(makeHasValueEdge(enumId, valueId));
367
371
  }
368
372
  }
369
373
  return refToNodeId.get(schemaRef);
370
374
  }
375
+ // ADR-009b rule 1: reuse an existing standalone schema before inlining it under
376
+ // this root — never create a duplicate copy of a schema that already stands
377
+ // alone (whether in the target graph or materialized earlier in this same run).
378
+ const reuseComponent = schemaComponents.get(schemaName) ?? component;
379
+ const reuseCandidateId = `${reuseComponent}.Schema.${schemaLocalName}`;
380
+ const existingFields = existingSchemas.get(reuseCandidateId);
381
+ if (existingFields) {
382
+ expanded.set(schemaName, reuseCandidateId);
383
+ if (!refToNodeId.has(schemaRef))
384
+ refToNodeId.set(schemaRef, reuseCandidateId);
385
+ const incomingFields = new Set(Object.keys(schemaDef?.properties ?? {}));
386
+ const drift = shapeDriftDiagnostic(schemaName, reuseCandidateId, incomingFields, existingFields, specPath);
387
+ if (drift)
388
+ diagnostics.push(drift);
389
+ return reuseCandidateId;
390
+ }
371
391
  const schemaId = `${rootNodeId}.schemas.${schemaLocalName}`;
372
392
  expanded.set(schemaName, schemaId);
373
393
  if (!refToNodeId.has(schemaRef))
@@ -382,18 +402,18 @@ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath
382
402
  refToNodeId.set(fieldRef, fieldId);
383
403
  const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
384
404
  const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
385
- fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
405
+ fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents, existingSchemas, diagnostics);
386
406
  nodes.push(fieldNode);
387
407
  edges.push(makeHasFieldEdge(schemaId, fieldId));
388
408
  }
389
409
  return schemaId;
390
410
  }
391
- function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents) {
411
+ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents, existingSchemas, diagnostics) {
392
412
  const nullable = !required;
393
413
  if (typeof prop.$ref === 'string') {
394
414
  const refName = schemaRefName(prop.$ref);
395
415
  if (refName) {
396
- const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
416
+ const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents, existingSchemas, diagnostics);
397
417
  return { $ref: refId, nullable, collection: 'one' };
398
418
  }
399
419
  return { type: 'string', nullable, collection: 'one' };
@@ -404,7 +424,7 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
404
424
  if (items && typeof items.$ref === 'string') {
405
425
  const refName = schemaRefName(items.$ref);
406
426
  if (refName) {
407
- const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
427
+ const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents, existingSchemas, diagnostics);
408
428
  return { $ref: refId, nullable, collection: 'array' };
409
429
  }
410
430
  }
@@ -412,13 +432,13 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
412
432
  return { type: itemType, nullable, collection: 'array' };
413
433
  }
414
434
  if (type === 'object' && prop.additionalProperties !== undefined) {
415
- createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
435
+ createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents, existingSchemas, diagnostics);
416
436
  return { $ref: `#/mappings/${fieldName}`, nullable, collection: 'one' };
417
437
  }
418
438
  const scalarType = mapScalar(type ?? 'string', prop.format);
419
439
  return { type: scalarType, nullable, collection: 'one' };
420
440
  }
421
- function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents) {
441
+ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents, existingSchemas, diagnostics) {
422
442
  const existing = localMappings.get(mappingName);
423
443
  if (existing)
424
444
  return existing;
@@ -434,7 +454,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
434
454
  if (typeof addl.$ref === 'string') {
435
455
  const refName = schemaRefName(addl.$ref);
436
456
  if (refName) {
437
- props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
457
+ props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents, existingSchemas, diagnostics);
438
458
  }
439
459
  else {
440
460
  props.type = 'string';
@@ -446,7 +466,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
446
466
  if (items && typeof items.$ref === 'string') {
447
467
  const refName = schemaRefName(items.$ref);
448
468
  if (refName) {
449
- props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
469
+ props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents, existingSchemas, diagnostics);
450
470
  }
451
471
  else {
452
472
  props.type = 'string';
@@ -458,7 +478,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
458
478
  }
459
479
  else if (addl.type === 'object' && addl.additionalProperties !== undefined) {
460
480
  const innerName = `${mappingName}-values`;
461
- props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
481
+ props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents, existingSchemas, diagnostics);
462
482
  }
463
483
  else {
464
484
  props.type = mapScalar(addl.type ?? 'string', addl.format);
@@ -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, context.componentNameReplacements);
9
+ const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry, context.packConfig, context.componentNameReplacements, context.existingSchemas);
10
10
  return { nodes, edges, diagnostics: [...diagnostics, ...mapDiagnostics] };
11
11
  }
12
12
  }
@@ -1,4 +1,6 @@
1
1
  import { applyComponentNameReplacements } from '../../import/config.js';
2
+ import { sanitizeIdSegment } from '../../loader/id-grammar.js';
3
+ import { shapeDriftDiagnostic } from '../shared/schema-reuse.js';
2
4
  export function deriveComponent(path, mapping) {
3
5
  if (mapping.strategy === 'hardcoded')
4
6
  return mapping.component;
@@ -30,19 +32,22 @@ function resolveAllOfRef(schema) {
30
32
  return schema;
31
33
  }
32
34
  export function deriveNodeId(kind, component, name, parentId, section) {
35
+ // Spec-supplied names (operationIds, schema names) may contain dots or other
36
+ // characters reserved by the node ID grammar — sanitise them to one segment.
33
37
  if (kind === 'operation')
34
- return `${component}.APIEndpoint.${name}`;
35
- return `${parentId}.${section}.${name}`;
38
+ return `${sanitizeIdSegment(component ?? '')}.APIEndpoint.${sanitizeIdSegment(name)}`;
39
+ return `${parentId}.${section}.${sanitizeIdSegment(name)}`;
36
40
  }
37
41
  export function refName(ref) {
38
42
  return ref.split('/').pop() ?? ref;
39
43
  }
40
- export function mapDocument(document, entry, packConfig, componentNameReplacements = []) {
44
+ export function mapDocument(document, entry, packConfig, componentNameReplacements = [], existingSchemas = new Map()) {
41
45
  const nodes = [];
42
46
  const edges = [];
43
47
  const diagnostics = [];
44
48
  const sharedSchemas = new Map();
45
49
  const sourceSchemas = new Map();
50
+ const reusedSchemaNames = new Set();
46
51
  for (const [name, schema] of Object.entries(document.components?.schemas ?? {})) {
47
52
  if (!isRefSchema(schema))
48
53
  sourceSchemas.set(name, schema);
@@ -63,8 +68,18 @@ export function mapDocument(document, entry, packConfig, componentNameReplacemen
63
68
  if (s.type !== 'object' && s.enum) {
64
69
  sharedSchemas.set(name, `${component}.EnumDefinition.${name}`);
65
70
  }
66
- else if (sharedSchemaNames.has(name)) {
67
- sharedSchemas.set(name, `${component}.Schema.${name}`);
71
+ else {
72
+ const candidateId = `${component}.Schema.${name}`;
73
+ // ADR-009b rule 1: reuse an existing standalone schema before inlining —
74
+ // never demote it, and never duplicate it, even if this document would
75
+ // otherwise treat it as single-use.
76
+ if (existingSchemas.has(candidateId)) {
77
+ sharedSchemas.set(name, candidateId);
78
+ reusedSchemaNames.add(name);
79
+ }
80
+ else if (sharedSchemaNames.has(name)) {
81
+ sharedSchemas.set(name, candidateId);
82
+ }
68
83
  }
69
84
  }
70
85
  }
@@ -90,17 +105,30 @@ export function mapDocument(document, entry, packConfig, componentNameReplacemen
90
105
  });
91
106
  continue;
92
107
  }
93
- if (!sharedSchemaNames.has(name))
108
+ if (!sharedSchemaNames.has(name) && !reusedSchemaNames.has(name))
94
109
  continue;
95
110
  const schemaId = sharedSchemas.get(name);
96
111
  if (!schemaId) {
97
112
  diagnostics.push({ severity: 'warning', file: entry.spec, message: `Cannot derive component for schema ${name}, skipping` });
98
113
  continue;
99
114
  }
115
+ if (reusedSchemaNames.has(name)) {
116
+ // ADR-009b rule 2: shape-drift warning — surface contract drift instead of
117
+ // silently merging it. Never create a duplicate/inline node for a reused schema.
118
+ const incomingFields = new Set(Object.keys(s.properties ?? {}));
119
+ const existingFields = existingSchemas.get(schemaId);
120
+ if (existingFields) {
121
+ const drift = shapeDriftDiagnostic(name, schemaId, incomingFields, existingFields, entry.spec);
122
+ if (drift)
123
+ diagnostics.push(drift);
124
+ }
125
+ continue;
126
+ }
100
127
  const [component] = schemaId.split('.');
101
128
  const node = makeNode(packConfig.constructs.requestSchema?.template ?? 'Schema', component, entry.spec, schemaId);
102
129
  nodes.push(node);
103
130
  emitFields(s, schemaId, 'fields', undefined, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map(), new Map());
131
+ existingSchemas.set(schemaId, new Set(Object.keys(s.properties ?? {})));
104
132
  }
105
133
  }
106
134
  for (const [urlPath, pathItem] of Object.entries(document.paths ?? {})) {
@@ -160,9 +188,29 @@ export function mapDocument(document, entry, packConfig, componentNameReplacemen
160
188
  }
161
189
  return { nodes, edges, diagnostics };
162
190
  }
191
+ // Structural walk of $ref values — visits every object/array reachable from the
192
+ // root and calls `visit` on any literal `#/components/schemas/{name}` ref found.
193
+ // Never treats plain strings (descriptions, examples, defaults) as refs.
194
+ function walkRefs(node, visit) {
195
+ if (Array.isArray(node)) {
196
+ for (const item of node)
197
+ walkRefs(item, visit);
198
+ return;
199
+ }
200
+ if (typeof node !== 'object' || node === null)
201
+ return;
202
+ const obj = node;
203
+ const ref = obj['$ref'];
204
+ if (typeof ref === 'string' && ref.startsWith('#/components/schemas/')) {
205
+ visit(ref.slice('#/components/schemas/'.length));
206
+ }
207
+ for (const value of Object.values(obj)) {
208
+ walkRefs(value, visit);
209
+ }
210
+ }
163
211
  function countSchemaOperationUsage(document) {
164
212
  const counts = new Map();
165
- const schemaNames = Object.keys(document.components?.schemas ?? {});
213
+ const schemaNames = new Set(Object.keys(document.components?.schemas ?? {}));
166
214
  for (const [, pathItem] of Object.entries(document.paths ?? {})) {
167
215
  if (!pathItem)
168
216
  continue;
@@ -171,11 +219,13 @@ function countSchemaOperationUsage(document) {
171
219
  const operation = pathItem[method];
172
220
  if (!operation)
173
221
  continue;
174
- const opJson = JSON.stringify(operation);
175
- for (const name of schemaNames) {
176
- if (opJson.includes(`"#/components/schemas/${name}"`)) {
177
- counts.set(name, (counts.get(name) ?? 0) + 1);
178
- }
222
+ const referenced = new Set();
223
+ walkRefs(operation, (name) => {
224
+ if (schemaNames.has(name))
225
+ referenced.add(name);
226
+ });
227
+ for (const name of referenced) {
228
+ counts.set(name, (counts.get(name) ?? 0) + 1);
179
229
  }
180
230
  }
181
231
  }
@@ -198,7 +248,10 @@ function collectAllSharedSchemaNames(document, opCounts) {
198
248
  const sharedSchema = document.components?.schemas?.[sharedName];
199
249
  if (isRefSchema(sharedSchema))
200
250
  continue;
201
- if (JSON.stringify(sharedSchema).includes(`"#/components/schemas/${candidateName}"`)) {
251
+ let references = false;
252
+ walkRefs(sharedSchema, (name) => { if (name === candidateName)
253
+ references = true; });
254
+ if (references) {
202
255
  shared.add(candidateName);
203
256
  changed = true;
204
257
  break;
@@ -488,7 +541,7 @@ function deriveComponentForSchema(name, document, entry, componentNameReplacemen
488
541
  for (const [schemaName, schema] of Object.entries(document.components?.schemas ?? {})) {
489
542
  if (schemaName === name || isRefSchema(schema))
490
543
  continue;
491
- if (JSON.stringify(schema).includes(`"#/components/schemas/${name}"`)) {
544
+ if (referencesSchema(schema, name)) {
492
545
  const comp = deriveComponentForSchema(schemaName, document, entry, componentNameReplacements, visited);
493
546
  if (comp)
494
547
  return comp;
@@ -496,6 +549,9 @@ function deriveComponentForSchema(name, document, entry, componentNameReplacemen
496
549
  }
497
550
  return undefined;
498
551
  }
499
- function referencesSchema(operation, schemaName) {
500
- return JSON.stringify(operation).includes(`"#/components/schemas/${schemaName}"`);
552
+ function referencesSchema(container, schemaName) {
553
+ let found = false;
554
+ walkRefs(container, (name) => { if (name === schemaName)
555
+ found = true; });
556
+ return found;
501
557
  }
@@ -0,0 +1,23 @@
1
+ export function setsEqual(a, b) {
2
+ if (a.size !== b.size)
3
+ return false;
4
+ for (const value of a)
5
+ if (!b.has(value))
6
+ return false;
7
+ return true;
8
+ }
9
+ /**
10
+ * ADR-009b rule 2: when an adapter reuses an existing standalone schema
11
+ * instead of inlining a duplicate, warn if the incoming field set differs
12
+ * from the existing node's — this is the signal for cross-source contract
13
+ * drift that reuse-before-inline would otherwise merge silently.
14
+ */
15
+ export function shapeDriftDiagnostic(schemaName, standaloneId, incomingFields, existingFields, specPath) {
16
+ if (setsEqual(incomingFields, existingFields))
17
+ return undefined;
18
+ return {
19
+ severity: 'warning',
20
+ file: specPath,
21
+ message: `Schema "${schemaName}" reused from existing standalone schema ${standaloneId}, but its field set differs (shape drift): incoming [${[...incomingFields].sort().join(', ')}] vs existing [${[...existingFields].sort().join(', ')}]`,
22
+ };
23
+ }
@@ -59,6 +59,23 @@ program
59
59
  port: opts.port,
60
60
  });
61
61
  });
62
+ program
63
+ .command('lint')
64
+ .description('Lint the graph and report diagnostics')
65
+ .option('--graph <path>', 'Override graph path')
66
+ .action(async (opts) => {
67
+ const config = buildRuntimeConfig(opts.graph);
68
+ try {
69
+ const graph = await loadGraph({ source: config.source, strict: false });
70
+ reportDiagnostics(graph.diagnostics, 'Lint complete');
71
+ if (graph.diagnostics.some(d => d.severity === 'error'))
72
+ process.exit(1);
73
+ }
74
+ catch (err) {
75
+ process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
76
+ process.exit(2);
77
+ }
78
+ });
62
79
  const CONFIG_TEMPLATE = `# Corum project configuration
63
80
  # Uncomment and set the options relevant to your setup.
64
81
  # All values can be overridden by environment variables (CORUM_*) or CLI flags.
@@ -147,6 +164,7 @@ const importCmd = program.command('import')
147
164
  .description('Import specifications into the graph')
148
165
  .option('--config <path>', 'Path to import config YAML')
149
166
  .option('--graph <path>', 'Override CORUM_GRAPH_PATH')
167
+ .option('-b, --branch <name>', 'Target branch to commit the import to (required for git sources)')
150
168
  .addHelpText('after', '\nFor import config file format and options, see: https://github.com/atolis-hq/corum#readme')
151
169
  .action(async (opts) => {
152
170
  if (!opts.config) {
@@ -156,7 +174,7 @@ const importCmd = program.command('import')
156
174
  try {
157
175
  const runtimeConfig = buildRuntimeConfig(opts.graph);
158
176
  const config = loadImportConfig(path.resolve(opts.config));
159
- const result = await runImport(config, runtimeConfig);
177
+ const result = await runImport(config, runtimeConfig, { branch: opts.branch });
160
178
  reportDiagnostics(result.diagnostics);
161
179
  if (result.diagnostics.some(d => d.severity === 'error'))
162
180
  process.exit(1);
@@ -174,11 +192,12 @@ importCmd
174
192
  .option('--pattern <regex>', 'Regex pattern (uri-segment strategy)')
175
193
  .option('--component <name>', 'Component name (hardcoded strategy)')
176
194
  .option('--graph <path>', 'Override CORUM_GRAPH_PATH')
195
+ .option('-b, --branch <name>', 'Target branch to commit the import to (required for git sources)')
177
196
  .action(async (spec, opts) => {
178
197
  try {
179
198
  const runtimeConfig = buildRuntimeConfig(opts.graph);
180
199
  const entry = buildOpenAPIConfig(spec, opts.componentStrategy, opts.segment, opts.pattern, opts.component);
181
- const result = await runImport({ imports: [entry] }, runtimeConfig);
200
+ const result = await runImport({ imports: [entry] }, runtimeConfig, { branch: opts.branch });
182
201
  reportDiagnostics(result.diagnostics);
183
202
  if (result.diagnostics.some(d => d.severity === 'error'))
184
203
  process.exit(1);
@@ -199,6 +218,7 @@ importCmd
199
218
  .option('--event-classification <mode>', 'Event classification: always-integration, always-domain', 'always-integration')
200
219
  .option('--include-consumed', 'Also import receive (consumed) operations', false)
201
220
  .option('--graph <path>', 'Override CORUM_GRAPH_PATH')
221
+ .option('-b, --branch <name>', 'Target branch to commit the import to (required for git sources)')
202
222
  .action(async (spec, opts) => {
203
223
  try {
204
224
  const runtimeConfig = buildRuntimeConfig(opts.graph);
@@ -214,7 +234,7 @@ importCmd
214
234
  if (opts.includeConsumed) {
215
235
  entry.includeConsumed = true;
216
236
  }
217
- const result = await runImport({ imports: [entry] }, runtimeConfig);
237
+ const result = await runImport({ imports: [entry] }, runtimeConfig, { branch: opts.branch });
218
238
  reportDiagnostics(result.diagnostics);
219
239
  if (result.diagnostics.some(d => d.severity === 'error'))
220
240
  process.exit(1);
@@ -228,11 +248,12 @@ importCmd
228
248
  .command('corum <spec>')
229
249
  .description('Import a corum interchange file into the graph')
230
250
  .option('--graph <path>', 'Override CORUM_GRAPH_PATH')
251
+ .option('-b, --branch <name>', 'Target branch to commit the import to (required for git sources)')
231
252
  .action(async (spec, opts) => {
232
253
  try {
233
254
  const runtimeConfig = buildRuntimeConfig(opts.graph);
234
255
  const entry = { adapter: 'corum', spec: path.resolve(spec) };
235
- const result = await runImport({ imports: [entry] }, runtimeConfig);
256
+ const result = await runImport({ imports: [entry] }, runtimeConfig, { branch: opts.branch });
236
257
  reportDiagnostics(result.diagnostics);
237
258
  if (result.diagnostics.some(d => d.severity === 'error'))
238
259
  process.exit(1);
@@ -279,14 +300,14 @@ function buildRuntimeConfig(graphOverride) {
279
300
  process.env.CORUM_GRAPH_PATH = path.resolve(graphOverride);
280
301
  return createGraphRuntimeConfig();
281
302
  }
282
- function reportDiagnostics(diagnostics) {
303
+ function reportDiagnostics(diagnostics, label = 'Import complete') {
283
304
  for (const d of diagnostics) {
284
305
  const prefix = d.severity === 'error' ? 'ERROR' : 'WARN';
285
306
  process.stderr.write(`[${prefix}] ${d.file}: ${d.message}\n`);
286
307
  }
287
308
  const errors = diagnostics.filter(d => d.severity === 'error').length;
288
309
  const warnings = diagnostics.filter(d => d.severity === 'warning').length;
289
- process.stdout.write(`Import complete. ${errors} error(s), ${warnings} warning(s).\n`);
310
+ process.stdout.write(`${label}. ${errors} error(s), ${warnings} warning(s).\n`);
290
311
  }
291
312
  function reportGraphDiagnostics(diagnostics) {
292
313
  const warnings = diagnostics.filter(d => d.severity === 'warning');