@atolis-hq/corum 0.1.21 → 0.1.23
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 +29 -0
- package/dist/src/adapters/corum/index.js +12 -0
- package/dist/src/adapters/corum/mapper.js +215 -0
- package/dist/src/adapters/corum/parser.js +44 -0
- package/dist/src/adapters/index.js +2 -0
- package/dist/src/bin/corum.js +28 -0
- package/dist/src/loader/edge-loader.js +2 -2
- package/dist/src/writer/graph-writer.js +4 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -98,6 +98,7 @@ Examples:
|
|
|
98
98
|
```bash
|
|
99
99
|
corum pack install domain
|
|
100
100
|
corum pack install domain@v0.1.5
|
|
101
|
+
corum pack install extract # required for corum-extract import adapter
|
|
101
102
|
```
|
|
102
103
|
|
|
103
104
|
### `corum pack list`
|
|
@@ -183,6 +184,34 @@ Options:
|
|
|
183
184
|
--graph <path> Override the graph directory
|
|
184
185
|
```
|
|
185
186
|
|
|
187
|
+
#### `corum import corum <spec>`
|
|
188
|
+
|
|
189
|
+
Import a corum interchange file (`*.corum.yaml`) produced by `corum-extract` or compatible extraction tooling.
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
corum import corum <spec> [options]
|
|
193
|
+
|
|
194
|
+
Options:
|
|
195
|
+
--graph <path> Override the graph directory
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
The interchange format is self-describing — no component mapping strategy is needed. Node IDs, template names, and field references are already corum-native. Gaps reported by the extractor (unresolved types, name collisions) are surfaced as warnings.
|
|
199
|
+
|
|
200
|
+
Requires the `extract` pack to be active in your graph:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
corum pack install extract
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
You can also configure corum imports in a config file:
|
|
207
|
+
|
|
208
|
+
```yaml
|
|
209
|
+
# .corum/imports.yaml
|
|
210
|
+
imports:
|
|
211
|
+
- adapter: corum
|
|
212
|
+
spec: path/to/output.corum.yaml
|
|
213
|
+
```
|
|
214
|
+
|
|
186
215
|
## Configuration
|
|
187
216
|
|
|
188
217
|
Run `corum init` to generate a `.corum/config.yaml` with all available options. Corum walks up from the current directory to find it, so you can place it at your project root.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { parseSpec } from './parser.js';
|
|
2
|
+
import { mapDocument } from './mapper.js';
|
|
3
|
+
export class CorumAdapter {
|
|
4
|
+
adapterId = 'corum';
|
|
5
|
+
async import(entry, _context) {
|
|
6
|
+
const { document, diagnostics } = parseSpec(entry.spec);
|
|
7
|
+
if (!document)
|
|
8
|
+
return { nodes: [], edges: [], diagnostics };
|
|
9
|
+
const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry.spec);
|
|
10
|
+
return { nodes, edges, diagnostics: [...diagnostics, ...mapDiagnostics] };
|
|
11
|
+
}
|
|
12
|
+
}
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
const VALID_EDGE_TYPES = new Set([
|
|
2
|
+
'triggers', 'produces', 'reads', 'calls', 'implements',
|
|
3
|
+
'maps-to', 'derived-from', 'renamed-from', 'has-field', 'has-value',
|
|
4
|
+
]);
|
|
5
|
+
export function mapDocument(document, specPath) {
|
|
6
|
+
const nodes = [];
|
|
7
|
+
const edges = [];
|
|
8
|
+
const diagnostics = [];
|
|
9
|
+
const allSchemas = (document.components?.schemas ?? {});
|
|
10
|
+
for (const gap of document.gaps ?? []) {
|
|
11
|
+
const msg = gap.nodeId
|
|
12
|
+
? `[${gap.kind}] ${gap.nodeId}: ${gap.reason ?? ''}`
|
|
13
|
+
: `[${gap.kind}] ${gap.reason ?? ''}`;
|
|
14
|
+
diagnostics.push({ severity: 'warning', file: specPath, message: msg });
|
|
15
|
+
}
|
|
16
|
+
for (const [nodeId, entry] of Object.entries(document.nodes)) {
|
|
17
|
+
if (!nodeId || !entry.type) {
|
|
18
|
+
diagnostics.push({ severity: 'warning', file: specPath, message: 'Node missing id or type — skipping' });
|
|
19
|
+
continue;
|
|
20
|
+
}
|
|
21
|
+
const component = nodeId.split('.')[0];
|
|
22
|
+
const properties = {};
|
|
23
|
+
let schemaName;
|
|
24
|
+
if (entry.schema?.$ref) {
|
|
25
|
+
schemaName = schemaRefName(entry.schema.$ref);
|
|
26
|
+
if (schemaName)
|
|
27
|
+
properties.schema = schemaName;
|
|
28
|
+
}
|
|
29
|
+
if (entry.title && !schemaName) {
|
|
30
|
+
properties.description = entry.title;
|
|
31
|
+
}
|
|
32
|
+
const node = makeNode(entry.type, component, specPath, nodeId, entry.provenance, properties);
|
|
33
|
+
nodes.push(node);
|
|
34
|
+
if (schemaName) {
|
|
35
|
+
const expanded = new Map();
|
|
36
|
+
expandSchema(schemaName, nodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
for (const raw of document.edges ?? []) {
|
|
40
|
+
if (!VALID_EDGE_TYPES.has(raw.type)) {
|
|
41
|
+
diagnostics.push({
|
|
42
|
+
severity: 'warning',
|
|
43
|
+
file: specPath,
|
|
44
|
+
message: `Unknown edge type '${raw.type}' from '${raw.from}' to '${raw.to}' — skipping`,
|
|
45
|
+
});
|
|
46
|
+
continue;
|
|
47
|
+
}
|
|
48
|
+
edges.push(mapEdge(raw));
|
|
49
|
+
}
|
|
50
|
+
return { nodes, edges, diagnostics };
|
|
51
|
+
}
|
|
52
|
+
function schemaRefName(ref) {
|
|
53
|
+
const prefix = '#/components/schemas/';
|
|
54
|
+
if (!ref.startsWith(prefix))
|
|
55
|
+
return undefined;
|
|
56
|
+
return ref.slice(prefix.length);
|
|
57
|
+
}
|
|
58
|
+
function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded) {
|
|
59
|
+
const existing = expanded.get(schemaName);
|
|
60
|
+
if (existing)
|
|
61
|
+
return existing;
|
|
62
|
+
const schemaId = `${rootNodeId}.schemas.${schemaName}`;
|
|
63
|
+
expanded.set(schemaName, schemaId);
|
|
64
|
+
const schemaDef = allSchemas[schemaName];
|
|
65
|
+
const schemaNode = makeNode('Schema', component, specPath, schemaId, undefined, {});
|
|
66
|
+
nodes.push(schemaNode);
|
|
67
|
+
edges.push(makeHasFieldEdge(rootNodeId, schemaId));
|
|
68
|
+
const localMappings = new Map();
|
|
69
|
+
for (const [fieldName, rawProp] of Object.entries(schemaDef?.properties ?? {})) {
|
|
70
|
+
const fieldId = `${schemaId}.fields.${fieldName}`;
|
|
71
|
+
const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
|
|
72
|
+
const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
|
|
73
|
+
fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings);
|
|
74
|
+
nodes.push(fieldNode);
|
|
75
|
+
edges.push(makeHasFieldEdge(schemaId, fieldId));
|
|
76
|
+
}
|
|
77
|
+
return schemaId;
|
|
78
|
+
}
|
|
79
|
+
function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings) {
|
|
80
|
+
const nullable = !required;
|
|
81
|
+
if (typeof prop.$ref === 'string') {
|
|
82
|
+
const refName = schemaRefName(prop.$ref);
|
|
83
|
+
if (refName) {
|
|
84
|
+
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
85
|
+
return { $ref: refId, nullable, collection: 'one' };
|
|
86
|
+
}
|
|
87
|
+
return { type: 'string', nullable, collection: 'one' };
|
|
88
|
+
}
|
|
89
|
+
const type = prop.type;
|
|
90
|
+
if (type === 'array') {
|
|
91
|
+
const items = prop.items;
|
|
92
|
+
if (items && typeof items.$ref === 'string') {
|
|
93
|
+
const refName = schemaRefName(items.$ref);
|
|
94
|
+
if (refName) {
|
|
95
|
+
const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
96
|
+
return { $ref: refId, nullable, collection: 'array' };
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
const itemType = mapScalar(items?.type ?? 'string', items?.format);
|
|
100
|
+
return { type: itemType, nullable, collection: 'array' };
|
|
101
|
+
}
|
|
102
|
+
if (type === 'object' && prop.additionalProperties !== undefined) {
|
|
103
|
+
createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings);
|
|
104
|
+
return { $ref: `#/mappings/${fieldName}`, nullable, collection: 'one' };
|
|
105
|
+
}
|
|
106
|
+
const scalarType = mapScalar(type ?? 'string', prop.format);
|
|
107
|
+
return { type: scalarType, nullable, collection: 'one' };
|
|
108
|
+
}
|
|
109
|
+
function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings) {
|
|
110
|
+
const existing = localMappings.get(mappingName);
|
|
111
|
+
if (existing)
|
|
112
|
+
return existing;
|
|
113
|
+
const mappingId = `${schemaId}.mappings.${mappingName}`;
|
|
114
|
+
localMappings.set(mappingName, mappingId);
|
|
115
|
+
const mappingNode = makeNode('Mapping', component, specPath, mappingId, undefined, {});
|
|
116
|
+
const props = {};
|
|
117
|
+
if (!addlDef || typeof addlDef === 'boolean') {
|
|
118
|
+
props.type = 'string';
|
|
119
|
+
}
|
|
120
|
+
else {
|
|
121
|
+
const addl = addlDef;
|
|
122
|
+
if (typeof addl.$ref === 'string') {
|
|
123
|
+
const refName = schemaRefName(addl.$ref);
|
|
124
|
+
if (refName) {
|
|
125
|
+
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
126
|
+
}
|
|
127
|
+
else {
|
|
128
|
+
props.type = 'string';
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
else if (addl.type === 'array') {
|
|
132
|
+
props['value-collection'] = 'array';
|
|
133
|
+
const items = addl.items;
|
|
134
|
+
if (items && typeof items.$ref === 'string') {
|
|
135
|
+
const refName = schemaRefName(items.$ref);
|
|
136
|
+
if (refName) {
|
|
137
|
+
props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded);
|
|
138
|
+
}
|
|
139
|
+
else {
|
|
140
|
+
props.type = 'string';
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
else {
|
|
144
|
+
props.type = mapScalar(items?.type ?? 'string', items?.format);
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
else if (addl.type === 'object' && addl.additionalProperties !== undefined) {
|
|
148
|
+
const innerName = `${mappingName}-values`;
|
|
149
|
+
props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings);
|
|
150
|
+
}
|
|
151
|
+
else {
|
|
152
|
+
props.type = mapScalar(addl.type ?? 'string', addl.format);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
mappingNode.properties = props;
|
|
156
|
+
nodes.push(mappingNode);
|
|
157
|
+
return mappingId;
|
|
158
|
+
}
|
|
159
|
+
function mapScalar(type, format) {
|
|
160
|
+
if (type === 'string') {
|
|
161
|
+
if (format === 'uuid')
|
|
162
|
+
return 'uuid';
|
|
163
|
+
if (format === 'date-time')
|
|
164
|
+
return 'datetime';
|
|
165
|
+
if (format === 'date')
|
|
166
|
+
return 'date';
|
|
167
|
+
return 'string';
|
|
168
|
+
}
|
|
169
|
+
if (type === 'integer')
|
|
170
|
+
return 'integer';
|
|
171
|
+
if (type === 'number')
|
|
172
|
+
return 'decimal';
|
|
173
|
+
if (type === 'boolean')
|
|
174
|
+
return 'boolean';
|
|
175
|
+
return 'string';
|
|
176
|
+
}
|
|
177
|
+
function makeNode(template, component, specPath, id, provenance, properties) {
|
|
178
|
+
return {
|
|
179
|
+
id,
|
|
180
|
+
template,
|
|
181
|
+
component,
|
|
182
|
+
state: 'implemented',
|
|
183
|
+
stability: 'unstable',
|
|
184
|
+
schemaVersion: '1',
|
|
185
|
+
lastModifiedAt: new Date().toISOString().split('T')[0],
|
|
186
|
+
extractedFrom: specPath,
|
|
187
|
+
derivation: provenance?.derivation === 'inferred' ? 'inferred' : 'determined',
|
|
188
|
+
derivedBy: provenance?.derivedBy ?? 'adapter:corum',
|
|
189
|
+
properties,
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
function makeHasFieldEdge(from, to) {
|
|
193
|
+
return {
|
|
194
|
+
id: `${from}__has-field__${to}`,
|
|
195
|
+
from,
|
|
196
|
+
to,
|
|
197
|
+
type: 'has-field',
|
|
198
|
+
state: 'implemented',
|
|
199
|
+
stability: 'unstable',
|
|
200
|
+
derivation: 'determined',
|
|
201
|
+
derivedBy: 'adapter:corum',
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
function mapEdge(raw) {
|
|
205
|
+
return {
|
|
206
|
+
id: `${raw.from}__${raw.type}__${raw.to}`,
|
|
207
|
+
from: raw.from,
|
|
208
|
+
to: raw.to,
|
|
209
|
+
type: raw.type,
|
|
210
|
+
state: 'implemented',
|
|
211
|
+
stability: 'unstable',
|
|
212
|
+
derivation: raw.provenance?.derivation === 'inferred' ? 'inferred' : 'determined',
|
|
213
|
+
derivedBy: raw.provenance?.derivedBy ?? 'adapter:corum',
|
|
214
|
+
};
|
|
215
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { parse as parseYaml } from 'yaml';
|
|
3
|
+
const SUPPORTED_VERSION = '1.0';
|
|
4
|
+
export function parseSpec(specPath) {
|
|
5
|
+
const diagnostics = [];
|
|
6
|
+
let raw;
|
|
7
|
+
try {
|
|
8
|
+
raw = parseYaml(readFileSync(specPath, 'utf-8'));
|
|
9
|
+
}
|
|
10
|
+
catch (err) {
|
|
11
|
+
diagnostics.push({
|
|
12
|
+
severity: 'error',
|
|
13
|
+
file: specPath,
|
|
14
|
+
message: `Failed to read or parse file: ${err instanceof Error ? err.message : String(err)}`,
|
|
15
|
+
});
|
|
16
|
+
return { document: null, diagnostics };
|
|
17
|
+
}
|
|
18
|
+
if (!isCorumInterchangeDocument(raw)) {
|
|
19
|
+
diagnostics.push({
|
|
20
|
+
severity: 'error',
|
|
21
|
+
file: specPath,
|
|
22
|
+
message: 'Invalid corum interchange file: missing required "corum" key or "nodes" object',
|
|
23
|
+
});
|
|
24
|
+
return { document: null, diagnostics };
|
|
25
|
+
}
|
|
26
|
+
const doc = raw;
|
|
27
|
+
if (doc.corum !== SUPPORTED_VERSION) {
|
|
28
|
+
diagnostics.push({
|
|
29
|
+
severity: 'warning',
|
|
30
|
+
file: specPath,
|
|
31
|
+
message: `Unknown corum version "${doc.corum}" — expected "${SUPPORTED_VERSION}", continuing`,
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
return { document: doc, diagnostics };
|
|
35
|
+
}
|
|
36
|
+
function isCorumInterchangeDocument(value) {
|
|
37
|
+
if (typeof value !== 'object' || value === null)
|
|
38
|
+
return false;
|
|
39
|
+
const v = value;
|
|
40
|
+
return (typeof v.corum === 'string' &&
|
|
41
|
+
typeof v.nodes === 'object' &&
|
|
42
|
+
v.nodes !== null &&
|
|
43
|
+
!Array.isArray(v.nodes));
|
|
44
|
+
}
|
|
@@ -12,3 +12,5 @@ import { OpenAPIAdapter } from './openapi/index.js';
|
|
|
12
12
|
registerAdapter(new OpenAPIAdapter());
|
|
13
13
|
import { AsyncAPIAdapter } from './asyncapi/index.js';
|
|
14
14
|
registerAdapter(new AsyncAPIAdapter());
|
|
15
|
+
import { CorumAdapter } from './corum/index.js';
|
|
16
|
+
registerAdapter(new CorumAdapter());
|
package/dist/src/bin/corum.js
CHANGED
|
@@ -47,6 +47,7 @@ program
|
|
|
47
47
|
let graph;
|
|
48
48
|
try {
|
|
49
49
|
graph = await loadGraph({ source: config.source, strict: true });
|
|
50
|
+
reportGraphDiagnostics(graph.diagnostics);
|
|
50
51
|
}
|
|
51
52
|
catch (err) {
|
|
52
53
|
process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
|
|
@@ -223,6 +224,24 @@ importCmd
|
|
|
223
224
|
process.exit(2);
|
|
224
225
|
}
|
|
225
226
|
});
|
|
227
|
+
importCmd
|
|
228
|
+
.command('corum <spec>')
|
|
229
|
+
.description('Import a corum interchange file into the graph')
|
|
230
|
+
.option('--graph <path>', 'Override CORUM_GRAPH_PATH')
|
|
231
|
+
.action(async (spec, opts) => {
|
|
232
|
+
try {
|
|
233
|
+
const runtimeConfig = buildRuntimeConfig(opts.graph);
|
|
234
|
+
const entry = { adapter: 'corum', spec: path.resolve(spec) };
|
|
235
|
+
const result = await runImport({ imports: [entry] }, runtimeConfig);
|
|
236
|
+
reportDiagnostics(result.diagnostics);
|
|
237
|
+
if (result.diagnostics.some(d => d.severity === 'error'))
|
|
238
|
+
process.exit(1);
|
|
239
|
+
}
|
|
240
|
+
catch (err) {
|
|
241
|
+
process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
|
|
242
|
+
process.exit(2);
|
|
243
|
+
}
|
|
244
|
+
});
|
|
226
245
|
const packCmd = program.command('pack').description('Manage template packs');
|
|
227
246
|
packCmd
|
|
228
247
|
.command('install <name>')
|
|
@@ -269,6 +288,15 @@ function reportDiagnostics(diagnostics) {
|
|
|
269
288
|
const warnings = diagnostics.filter(d => d.severity === 'warning').length;
|
|
270
289
|
process.stdout.write(`Import complete. ${errors} error(s), ${warnings} warning(s).\n`);
|
|
271
290
|
}
|
|
291
|
+
function reportGraphDiagnostics(diagnostics) {
|
|
292
|
+
const warnings = diagnostics.filter(d => d.severity === 'warning');
|
|
293
|
+
for (const d of warnings) {
|
|
294
|
+
process.stderr.write(`[WARN] ${d.file ?? 'graph'}: ${d.message}\n`);
|
|
295
|
+
}
|
|
296
|
+
if (warnings.length > 0) {
|
|
297
|
+
process.stderr.write(`Graph loaded with ${warnings.length} warning(s).\n`);
|
|
298
|
+
}
|
|
299
|
+
}
|
|
272
300
|
async function readPackRegistryUrl(cwd) {
|
|
273
301
|
const configPath = path.join(cwd, '.corum', 'config.yaml');
|
|
274
302
|
const text = await fsReadFile(configPath, 'utf8');
|
|
@@ -27,11 +27,11 @@ export function loadEdges(content, nodes, diagnostics) {
|
|
|
27
27
|
}
|
|
28
28
|
let unresolvedEndpoint = false;
|
|
29
29
|
if (!nodes.has(edgeRecord.from)) {
|
|
30
|
-
diagnostics.push({ severity: '
|
|
30
|
+
diagnostics.push({ severity: 'warning', file: key, message: `edge from unresolved node: ${edgeRecord.from}` });
|
|
31
31
|
unresolvedEndpoint = true;
|
|
32
32
|
}
|
|
33
33
|
if (!nodes.has(edgeRecord.to)) {
|
|
34
|
-
diagnostics.push({ severity: '
|
|
34
|
+
diagnostics.push({ severity: 'warning', file: key, message: `edge to unresolved node: ${edgeRecord.to}` });
|
|
35
35
|
unresolvedEndpoint = true;
|
|
36
36
|
}
|
|
37
37
|
if (unresolvedEndpoint)
|
|
@@ -22,10 +22,10 @@ export function serializeGraph(graph, options = {}) {
|
|
|
22
22
|
}
|
|
23
23
|
function clusterPath(node) {
|
|
24
24
|
const parts = node.id.split('.');
|
|
25
|
-
if (parts.length
|
|
26
|
-
throw new Error(`clusterPath: expected 3-segment root node ID, got: ${node.id}`);
|
|
27
|
-
const [component, template,
|
|
28
|
-
return `components/${component}/${template}s/${
|
|
25
|
+
if (parts.length < 3)
|
|
26
|
+
throw new Error(`clusterPath: expected at least 3-segment root node ID, got: ${node.id}`);
|
|
27
|
+
const [component, template, ...rest] = parts;
|
|
28
|
+
return `components/${component}/${template}s/${rest.join('/')}.yaml`;
|
|
29
29
|
}
|
|
30
30
|
export async function saveGraph(graph, options) {
|
|
31
31
|
const { sourceGraphPath, outputGraphPath, replace = true } = options;
|