@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.
- package/dist/src/adapters/asyncapi/index.js +1 -1
- package/dist/src/adapters/asyncapi/mapper.js +34 -6
- package/dist/src/adapters/corum/index.js +2 -2
- package/dist/src/adapters/corum/mapper.js +40 -20
- package/dist/src/adapters/openapi/index.js +1 -1
- package/dist/src/adapters/openapi/mapper.js +72 -16
- package/dist/src/adapters/shared/schema-reuse.js +23 -0
- package/dist/src/bin/corum.js +27 -6
- package/dist/src/graph/index.js +57 -29
- package/dist/src/graph/roles.js +66 -0
- package/dist/src/graph/schema-collapse.js +62 -72
- package/dist/src/import/config.js +3 -0
- package/dist/src/import/edge-casing.js +47 -0
- package/dist/src/import/runner.js +55 -7
- package/dist/src/import/schema-promotion.js +103 -0
- package/dist/src/linter/index.js +221 -0
- package/dist/src/loader/cluster-loader.js +52 -30
- package/dist/src/loader/constants.js +20 -16
- package/dist/src/loader/edge-loader.js +25 -5
- package/dist/src/loader/edge-type-loader.js +72 -0
- package/dist/src/loader/id-grammar.js +68 -0
- package/dist/src/loader/index.js +6 -1
- package/dist/src/loader/template-props.js +60 -0
- package/dist/src/mcp/index.js +60 -39
- package/dist/src/mcp/serializers.js +2 -1
- package/dist/src/pack/installer.js +15 -2
- package/dist/src/source/file-source.js +104 -29
- package/dist/src/source/git-source.js +101 -41
- package/dist/src/source/safe-path.js +26 -0
- package/dist/src/web/server.js +27 -46
- package/dist/src/writer/graph-writer.js +44 -6
- package/package.json +1 -1
|
@@ -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
|
|
261
|
-
|
|
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,
|
|
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
|
|
67
|
-
|
|
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
|
|
175
|
-
|
|
176
|
-
if (
|
|
177
|
-
|
|
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
|
-
|
|
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 (
|
|
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(
|
|
500
|
-
|
|
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
|
+
}
|
package/dist/src/bin/corum.js
CHANGED
|
@@ -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(
|
|
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');
|