@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 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;
@@ -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) {
@@ -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 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;
@@ -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 component = entry.componentMapping.strategy === 'tag'
459
+ const rawComponent = entry.componentMapping.strategy === 'tag'
456
460
  ? operation.tags?.[0]
457
461
  : deriveComponent(urlPath, entry.componentMapping);
458
- if (component)
459
- directComponents.add(component);
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
  }
@@ -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;
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.19",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",