@atolis-hq/corum 0.1.18 → 0.1.19
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 +33 -0
- package/dist/src/adapters/asyncapi/index.js +1 -1
- package/dist/src/adapters/asyncapi/mapper.js +8 -5
- package/dist/src/adapters/openapi/index.js +1 -1
- package/dist/src/adapters/openapi/mapper.js +12 -8
- package/dist/src/bin/corum.js +3 -1
- package/dist/src/import/config.js +10 -1
- package/dist/src/import/runner.js +5 -1
- package/package.json +1 -1
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
|
|
223
|
-
if (!
|
|
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;
|
|
@@ -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
|
|
292
|
-
if (!
|
|
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) {
|
|
@@ -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) {
|
|
@@ -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
|
|
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;
|
|
@@ -438,7 +442,7 @@ function emitFields(schema, parentId, section, rootId, packConfig, specPath, nod
|
|
|
438
442
|
edges.push({ id: `${parentId}__has-field__${fieldId}`, from: parentId, to: fieldId, type: 'has-field', state: 'implemented', stability: 'unstable' });
|
|
439
443
|
}
|
|
440
444
|
}
|
|
441
|
-
function deriveComponentForSchema(name, document, entry, visited = new Set()) {
|
|
445
|
+
function deriveComponentForSchema(name, document, entry, componentNameReplacements, visited = new Set()) {
|
|
442
446
|
if (visited.has(name))
|
|
443
447
|
return undefined;
|
|
444
448
|
visited.add(name);
|
|
@@ -452,11 +456,11 @@ function deriveComponentForSchema(name, document, entry, visited = new Set()) {
|
|
|
452
456
|
if (!operation)
|
|
453
457
|
continue;
|
|
454
458
|
if (referencesSchema(operation, name)) {
|
|
455
|
-
const
|
|
459
|
+
const rawComponent = entry.componentMapping.strategy === 'tag'
|
|
456
460
|
? operation.tags?.[0]
|
|
457
461
|
: deriveComponent(urlPath, entry.componentMapping);
|
|
458
|
-
if (
|
|
459
|
-
directComponents.add(
|
|
462
|
+
if (rawComponent)
|
|
463
|
+
directComponents.add(applyComponentNameReplacements(rawComponent, componentNameReplacements));
|
|
460
464
|
}
|
|
461
465
|
}
|
|
462
466
|
}
|
|
@@ -468,7 +472,7 @@ function deriveComponentForSchema(name, document, entry, visited = new Set()) {
|
|
|
468
472
|
if (schemaName === name || isRefSchema(schema))
|
|
469
473
|
continue;
|
|
470
474
|
if (JSON.stringify(schema).includes(`"#/components/schemas/${name}"`)) {
|
|
471
|
-
const comp = deriveComponentForSchema(schemaName, document, entry, visited);
|
|
475
|
+
const comp = deriveComponentForSchema(schemaName, document, entry, componentNameReplacements, visited);
|
|
472
476
|
if (comp)
|
|
473
477
|
return comp;
|
|
474
478
|
}
|
package/dist/src/bin/corum.js
CHANGED
|
@@ -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
|
-
|
|
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, {
|
|
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;
|