@atolis-hq/corum 0.1.13 → 0.1.15

package/dist/src/adapters/openapi/mapper.js

@@ -18,6 +18,16 @@ export function deriveScalarType(type, format, scalarTypes) {
 export function isRefSchema(schema) {
     return typeof schema === 'object' && schema !== null && '$ref' in schema;
 }
+// Unwrap allOf: [{$ref}] — the OpenAPI 3.0 pattern for nullable/described refs
+function resolveAllOfRef(schema) {
+    if (isRefSchema(schema))
+        return schema;
+    const s = schema;
+    if (Array.isArray(s.allOf) && s.allOf.length === 1 && isRefSchema(s.allOf[0])) {
+        return s.allOf[0];
+    }
+    return schema;
+}
 export function deriveNodeId(kind, component, name, parentId, section) {
     if (kind === 'operation')
         return `${component}.APIEndpoint.${name}`;
@@ -26,24 +36,56 @@ export function deriveNodeId(kind, component, name, parentId, section) {
 export function refName(ref) {
     return ref.split('/').pop() ?? ref;
 }
+function emitReadsEdge(from, to, edges) {
+    const id = `${from}__reads__${to}`;
+    if (!edges.some(e => e.id === id)) {
+        edges.push({ id, from, to, type: 'reads', state: 'implemented', stability: 'unstable' });
+    }
+}
 export function mapDocument(document, entry, packConfig) {
     const nodes = [];
     const edges = [];
     const diagnostics = [];
     const sharedSchemas = new Map();
+    const sourceSchemas = new Map();
+    for (const [name, schema] of Object.entries(document.components?.schemas ?? {})) {
+        if (!isRefSchema(schema))
+            sourceSchemas.set(name, schema);
+    }
+    // Schemas referenced by 2+ operations become shared files; single-use schemas are inlined
+    const opCounts = countSchemaOperationUsage(document);
+    const sharedSchemaNames = collectAllSharedSchemaNames(document, opCounts);
+    // Pass 1: register all enum and shared-schema IDs upfront so cross-references
+    // resolve correctly regardless of definition order in the spec.
+    if (document.components?.schemas) {
+        for (const [name, schema] of Object.entries(document.components.schemas)) {
+            if (isRefSchema(schema))
+                continue;
+            const s = schema;
+            const component = deriveComponentForSchema(name, document, entry);
+            if (!component)
+                continue;
+            if (s.type !== 'object' && s.enum) {
+                sharedSchemas.set(name, `${component}.EnumDefinition.${name}`);
+            }
+            else if (sharedSchemaNames.has(name)) {
+                sharedSchemas.set(name, `${component}.Schema.${name}`);
+            }
+        }
+    }
+    // Pass 2: emit nodes and fields now that all IDs are registered.
     if (document.components?.schemas) {
         for (const [name, schema] of Object.entries(document.components.schemas)) {
             if (isRefSchema(schema))
                 continue;
             const s = schema;
             if (s.type !== 'object' && s.enum) {
-                const component = deriveComponentForSchema(name, document, entry);
-                if (!component)
+                const enumId = sharedSchemas.get(name);
+                if (!enumId)
                     continue;
-                const enumId = `${component}.EnumDefinition.${name}`;
+                const [component] = enumId.split('.');
                 const enumNode = makeNode(packConfig.constructs.enumDefinition?.template ?? 'EnumDefinition', component, entry.spec, enumId);
                 nodes.push(enumNode);
-                sharedSchemas.set(name, enumId);
                 s.enum.forEach((value) => {
                     const valueId = deriveNodeId('enumValue', undefined, String(value), enumId, 'values');
                     const valueNode = makeNode(packConfig.constructs.enumValue?.template ?? 'EnumValue', component, entry.spec, valueId);
@@ -53,16 +95,17 @@ export function mapDocument(document, entry, packConfig) {
                 });
                 continue;
             }
-            const component = deriveComponentForSchema(name, document, entry);
-            if (!component) {
+            if (!sharedSchemaNames.has(name))
+                continue;
+            const schemaId = sharedSchemas.get(name);
+            if (!schemaId) {
                 diagnostics.push({ severity: 'warning', file: entry.spec, message: `Cannot derive component for schema ${name}, skipping` });
                 continue;
             }
-            const schemaId = `${component}.Schema.${name}`;
-            sharedSchemas.set(name, schemaId);
+            const [component] = schemaId.split('.');
             const node = makeNode(packConfig.constructs.requestSchema?.template ?? 'Schema', component, entry.spec, schemaId);
             nodes.push(node);
-            emitFields(s, schemaId, 'fields', packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas);
+            emitFields(s, schemaId, 'fields', undefined, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, new Map());
         }
     }
     for (const [urlPath, pathItem] of Object.entries(document.paths ?? {})) {
@@ -92,11 +135,12 @@ export function mapDocument(document, entry, packConfig) {
             const parameters = extractParameters(pathItem, operation, packConfig, entry.spec, diagnostics);
             if (parameters)
                 endpointNode.properties.parameters = parameters;
+            const localSchemas = new Map();
             const requestBody = operation.requestBody;
             if (requestBody?.content) {
                 const jsonContent = requestBody.content['application/json'];
                 if (jsonContent?.schema) {
-                    const ref = emitSchemaNode(jsonContent.schema, `${operationId}-request`, endpointId, 'schemas', packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas);
+                    const ref = emitSchemaNode(jsonContent.schema, `${operationId}-request`, endpointId, 'schemas', endpointId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
                     if (ref)
                         endpointNode.properties.request = ref;
                 }
@@ -106,7 +150,7 @@ export function mapDocument(document, entry, packConfig) {
                 const responseObj = response;
                 const jsonContent = responseObj.content?.['application/json'];
                 if (jsonContent?.schema) {
-                    const ref = emitSchemaNode(jsonContent.schema, `${operationId}-response-${status}`, endpointId, 'schemas', packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas);
+                    const ref = emitSchemaNode(jsonContent.schema, `${operationId}-response-${status}`, endpointId, 'schemas', endpointId, packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
                     if (ref)
                         responses[status] = ref;
                 }
@@ -117,6 +161,54 @@ export function mapDocument(document, entry, packConfig) {
     }
     return { nodes, edges, diagnostics };
 }
+function countSchemaOperationUsage(document) {
+    const counts = new Map();
+    const schemaNames = Object.keys(document.components?.schemas ?? {});
+    for (const [, pathItem] of Object.entries(document.paths ?? {})) {
+        if (!pathItem)
+            continue;
+        const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+        for (const method of methods) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const opJson = JSON.stringify(operation);
+            for (const name of schemaNames) {
+                if (opJson.includes(`"#/components/schemas/${name}"`)) {
+                    counts.set(name, (counts.get(name) ?? 0) + 1);
+                }
+            }
+        }
+    }
+    return counts;
+}
+// Schemas referenced by 2+ operations are shared. Schemas referenced by shared schemas are also shared.
+function collectAllSharedSchemaNames(document, opCounts) {
+    const shared = new Set();
+    for (const [name, count] of opCounts) {
+        if (count > 1)
+            shared.add(name);
+    }
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [candidateName] of Object.entries(document.components?.schemas ?? {})) {
+            if (shared.has(candidateName))
+                continue;
+            for (const sharedName of shared) {
+                const sharedSchema = document.components?.schemas?.[sharedName];
+                if (isRefSchema(sharedSchema))
+                    continue;
+                if (JSON.stringify(sharedSchema).includes(`"#/components/schemas/${candidateName}"`)) {
+                    shared.add(candidateName);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    return shared;
+}
 function extractParameters(pathItem, operation, packConfig, specPath, diagnostics) {
     const pathItemParams = (pathItem.parameters ?? []);
     const operationParams = (operation.parameters ?? []);
@@ -137,18 +229,16 @@ function extractParameters(pathItem, operation, packConfig, specPath, diagnostic
         if (!schema)
             continue;
         let type;
-        let cardinality;
+        let collection;
         if (schema.type === 'array') {
-            cardinality = 'many';
+            collection = 'array';
             const items = schema.items;
             type = deriveScalarType(items?.type ?? 'string', items?.format, packConfig.scalarTypes) ?? 'string';
         }
         else if (schema.enum) {
-            cardinality = 'one';
             type = 'string';
         }
         else {
-            cardinality = 'one';
             const derived = deriveScalarType(schema.type ?? 'string', schema.format, packConfig.scalarTypes);
             if (!derived) {
                 diagnostics.push({ severity: 'warning', file: specPath, message: `Unknown type for parameter ${name}: ${schema.type}/${schema.format}, defaulting to string` });
@@ -162,7 +252,7 @@ function extractParameters(pathItem, operation, packConfig, specPath, diagnostic
             location: param.in,
             type,
             required: param.required ?? false,
-            cardinality,
+            ...(collection ? { collection } : {}),
         };
     }
     return Object.keys(parameters).length > 0 ? parameters : undefined;
@@ -182,52 +272,165 @@ function makeNode(template, component, specPath, id) {
         properties: {},
     };
 }
-function emitSchemaNode(schema, name, parentId, section, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas) {
+function emitSchemaNode(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
+    schema = resolveAllOfRef(schema);
     if (isRefSchema(schema)) {
-        return sharedSchemas.get(refName(schema.$ref));
+        const schemaName = refName(schema.$ref);
+        const globalId = sharedSchemas.get(schemaName);
+        if (globalId) {
+            if (rootId)
+                emitReadsEdge(rootId, globalId, edges);
+            return globalId;
+        }
+        if (localSchemas.has(schemaName))
+            return localSchemas.get(schemaName);
+        const sourceSchema = sourceSchemas.get(schemaName);
+        if (sourceSchema) {
+            const effectiveParent = rootId ?? parentId;
+            return createInlineSchema(sourceSchema, schemaName, effectiveParent, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+        }
+        return undefined;
     }
+    if (localSchemas.has(name))
+        return localSchemas.get(name);
+    return createInlineSchema(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+}
+function createInlineSchema(schema, name, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
     const schemaId = deriveNodeId('schema', undefined, name, parentId, section);
     const [component] = parentId.split('.');
     const node = makeNode(packConfig.constructs.requestSchema?.template ?? 'Schema', component, specPath, schemaId);
     nodes.push(node);
     edges.push({ id: `${parentId}__has-field__${schemaId}`, from: parentId, to: schemaId, type: 'has-field', state: 'implemented', stability: 'unstable' });
-    emitFields(schema, schemaId, 'fields', packConfig, specPath, nodes, edges, diagnostics, sharedSchemas);
-    return `#/${section}/${name}`;
+    const localRef = `#/${section}/${name}`;
+    localSchemas.set(name, localRef);
+    emitFields(schema, schemaId, 'fields', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+    return localRef;
 }
-function emitFields(schema, parentId, section, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas) {
-    for (const [fieldName, fieldSchema] of Object.entries(schema.properties ?? {})) {
+function resolveFieldRef(schemaName, collection, required, rootId, readsSource, refSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
+    const extra = { nullable: !required };
+    if (collection !== 'one')
+        extra.collection = collection;
+    const globalId = sharedSchemas.get(schemaName);
+    if (globalId) {
+        emitReadsEdge(readsSource, globalId, edges);
+        return { $ref: globalId, ...extra };
+    }
+    if (localSchemas.has(schemaName))
+        return { $ref: localSchemas.get(schemaName), ...extra };
+    if (rootId) {
+        const localRef = emitSchemaNode(refSchema, schemaName, rootId, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+        if (localRef)
+            return { $ref: localRef, ...extra };
+    }
+    return { $ref: schemaName, ...extra };
+}
+function emitFields(schema, parentId, section, rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas) {
+    // readsSource: when in endpoint context use rootId, otherwise use the schema itself
+    const readsSource = rootId ?? parentId;
+    for (const [fieldName, rawFieldSchema] of Object.entries(schema.properties ?? {})) {
+        const fieldSchema = resolveAllOfRef(rawFieldSchema);
         const fieldId = deriveNodeId('field', undefined, fieldName, parentId, section);
         const [component] = parentId.split('.');
         const fieldNode = makeNode(packConfig.constructs.schemaProperty?.template ?? 'Field', component, specPath, fieldId);
         const required = Array.isArray(schema.required) && schema.required.includes(fieldName);
         if (isRefSchema(fieldSchema)) {
-            const ref = refName(fieldSchema.$ref);
-            fieldNode.properties = { $ref: sharedSchemas.get(ref) ?? ref, nullable: !required, cardinality: 'one' };
+            fieldNode.properties = resolveFieldRef(refName(fieldSchema.$ref), 'one', required, rootId, readsSource, fieldSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
         }
         else {
             const fs = fieldSchema;
             if (fs.enum && fs.type !== 'object') {
                 const enumRef = sharedSchemas.get(fieldName);
-                fieldNode.properties = { ...(enumRef ? { $ref: enumRef } : { type: 'string' }), nullable: !required, cardinality: 'one' };
+                fieldNode.properties = { ...(enumRef ? { $ref: enumRef } : { type: 'string' }), nullable: !required };
             }
             else if (fs.type === 'array') {
-                const items = fs.items;
-                if (isRefSchema(items)) {
-                    fieldNode.properties = { objectRef: refName(items.$ref), nullable: !required, cardinality: 'many' };
+                const rawItems = fs.items;
+                const items = rawItems ? resolveAllOfRef(rawItems) : undefined;
+                if (!items) {
+                    fieldNode.properties = { type: 'string', nullable: !required, collection: 'array' };
+                }
+                else if (isRefSchema(items)) {
+                    fieldNode.properties = resolveFieldRef(refName(items.$ref), 'array', required, rootId, readsSource, items, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+                }
+                else {
+                    const itemType = deriveScalarType(items.type ?? 'string', items.format, packConfig.scalarTypes);
+                    fieldNode.properties = { type: itemType ?? 'string', nullable: !required, collection: 'array' };
+                }
+            }
+            else if (fs.type === 'object' && fs.properties) {
+                // Anonymous object with named properties → inline as sibling schema
+                if (rootId) {
+                    const localRef = emitSchemaNode(fs, fieldName, rootId, 'schemas', rootId, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+                    fieldNode.properties = localRef
+                        ? { $ref: localRef, nullable: !required }
+                        : { type: 'string', nullable: !required };
+                }
+                else {
+                    diagnostics.push({ severity: 'warning', file: specPath, message: `Inline object for field ${fieldId} has no endpoint context; treating as string` });
+                    fieldNode.properties = { type: 'string', nullable: !required };
+                }
+            }
+            else if (fs.type === 'object' && fs.additionalProperties) {
+                // Map/dictionary: keyed collection
+                const addlRaw = fs.additionalProperties;
+                if (typeof addlRaw === 'boolean') {
+                    fieldNode.properties = { type: 'string', nullable: !required, collection: 'map' };
                 }
                 else {
-                    const itemType = deriveScalarType(items?.type ?? 'string', items?.format, packConfig.scalarTypes);
-                    fieldNode.properties = { type: itemType ?? 'string', nullable: !required, cardinality: 'many' };
+                    const addlSchema = resolveAllOfRef(addlRaw);
+                    if (isRefSchema(addlSchema)) {
+                        fieldNode.properties = resolveFieldRef(refName(addlSchema.$ref), 'map', required, rootId, readsSource, addlSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+                    }
+                    else {
+                        const addlObj = addlSchema;
+                        if (addlObj.type === 'object') {
+                            const innerAddl = addlObj.additionalProperties;
+                            if (!innerAddl || typeof innerAddl === 'boolean') {
+                                fieldNode.properties = { type: 'string', nullable: !required, collection: 'map-of-map' };
+                            }
+                            else {
+                                const innerSchema = resolveAllOfRef(innerAddl);
+                                if (isRefSchema(innerSchema)) {
+                                    fieldNode.properties = resolveFieldRef(refName(innerSchema.$ref), 'map-of-map', required, rootId, readsSource, innerSchema, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+                                }
+                                else {
+                                    const inner = innerSchema;
+                                    const scalarType = deriveScalarType(inner.type ?? 'string', inner.format, packConfig.scalarTypes);
+                                    if (scalarType) {
+                                        fieldNode.properties = { type: scalarType, nullable: !required, collection: 'map-of-map' };
+                                    }
+                                    else {
+                                        diagnostics.push({ severity: 'warning', file: specPath, message: `[WARN] Double-nested map for field ${fieldId}; inner value type not representable, using string` });
+                                        fieldNode.properties = { type: 'string', nullable: !required, collection: 'map-of-map' };
+                                    }
+                                }
+                            }
+                        }
+                        else if (addlObj.type === 'array') {
+                            const rawItems = addlObj.items;
+                            const items = rawItems ? resolveAllOfRef(rawItems) : undefined;
+                            if (items && isRefSchema(items)) {
+                                fieldNode.properties = resolveFieldRef(refName(items.$ref), 'map-of-array', required, rootId, readsSource, items, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas, sourceSchemas, localSchemas);
+                            }
+                            else {
+                                const scalarType = items ? deriveScalarType(items.type ?? 'string', items.format, packConfig.scalarTypes) : undefined;
+                                fieldNode.properties = { type: scalarType ?? 'string', nullable: !required, collection: 'map-of-array' };
+                            }
+                        }
+                        else {
+                            const scalarType = deriveScalarType(addlObj.type ?? 'string', addlObj.format, packConfig.scalarTypes);
+                            fieldNode.properties = { type: scalarType ?? 'string', nullable: !required, collection: 'map' };
+                        }
+                    }
                 }
             }
             else {
                 const scalarType = deriveScalarType(fs.type ?? 'string', fs.format, packConfig.scalarTypes);
                 if (scalarType) {
-                    fieldNode.properties = { type: scalarType, nullable: !required, cardinality: 'one' };
+                    fieldNode.properties = { type: scalarType, nullable: !required };
                 }
                 else {
                     diagnostics.push({ severity: 'warning', file: specPath, message: `Unknown type for field ${fieldId}: ${fs.type}/${fs.format}` });
-                    fieldNode.properties = { type: 'string', nullable: !required, cardinality: 'one' };
+                    fieldNode.properties = { type: 'string', nullable: !required };
                 }
             }
         }
@@ -239,7 +442,6 @@ function deriveComponentForSchema(name, document, entry, visited = new Set()) {
     if (visited.has(name))
         return undefined;
     visited.add(name);
-    // Direct: collect all components whose operations reference this schema
     const directComponents = new Set();
     for (const [urlPath, pathItem] of Object.entries(document.paths ?? {})) {
         if (!pathItem)
@@ -262,7 +464,6 @@ function deriveComponentForSchema(name, document, entry, visited = new Set()) {
         return 'shared';
     if (directComponents.size === 1)
         return [...directComponents][0];
-    // Indirect: find another component schema that references this one and use its component
     for (const [schemaName, schema] of Object.entries(document.components?.schemas ?? {})) {
         if (schemaName === name || isRefSchema(schema))
             continue;

package/dist/src/graph/index.js

@@ -43,15 +43,32 @@ export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
     }
     const clusterIds = new Set([cluster.root.id, ...cluster.children.map(node => node.id)]);
     const requestedTypes = new Set(includeEdgeTypes);
+    // reads edges are directional (consumer → type); only follow outbound so viewing a shared
+    // Schema doesn't pull in every endpoint that references it
+    const inboundTypes = new Set([...requestedTypes].filter(t => t !== 'reads'));
     const includedNodeIds = new Set();
     const edges = [...cluster.edges];
     const seen = new Set(cluster.edges.map(edge => edge.id));
     for (const id of clusterIds) {
         for (const edge of graph.edgesByFrom.get(id) ?? []) {
-            collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen);
+            collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph);
         }
         for (const edge of graph.edgesByTo.get(id) ?? []) {
-            collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen);
+            collectIncludedEdge(edge, inboundTypes, clusterIds, includedNodeIds, edges, seen, graph);
+        }
+    }
+    // BFS over included nodes (outbound only) to transitively pull in referenced schemas
+    const processedOutbound = new Set(clusterIds);
+    let prevSize = 0;
+    while (includedNodeIds.size > prevSize) {
+        prevSize = includedNodeIds.size;
+        for (const id of includedNodeIds) {
+            if (processedOutbound.has(id))
+                continue;
+            processedOutbound.add(id);
+            for (const edge of graph.edgesByFrom.get(id) ?? []) {
+                collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph);
+            }
         }
     }
     return {
@@ -97,15 +114,21 @@ function collectMapsTo(edge, edges, nodeIds, seen) {
     nodeIds.add(edge.to);
     seen.add(edge.id);
 }
-function collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen) {
+function collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph) {
     if (!requestedTypes.has(edge.type) || seen.has(edge.id))
         return;
     edges.push(edge);
     seen.add(edge.id);
-    if (!clusterIds.has(edge.from))
-        includedNodeIds.add(edge.from);
-    if (!clusterIds.has(edge.to))
-        includedNodeIds.add(edge.to);
+    for (const endId of [edge.from, edge.to]) {
+        if (clusterIds.has(endId))
+            continue;
+        includedNodeIds.add(endId);
+        const prefix = `${endId}.`;
+        for (const id of graph.nodesById.keys()) {
+            if (id.startsWith(prefix))
+                includedNodeIds.add(id);
+        }
+    }
 }
 const OVERLAY_EXCLUDED = new Set(['local', 'shared']);
 export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRootId) {

package/dist/src/import/runner.js

@@ -28,6 +28,18 @@ export async function runImport(config, runtimeConfig) {
         for (const node of [...toAdd, ...toUpdate, ...toRemove]) {
             graph.nodesById.set(node.id, node);
         }
+        const STRUCTURAL_EDGE_TYPES = new Set(['has-field', 'has-value']);
+        for (const edge of result.edges) {
+            if (STRUCTURAL_EDGE_TYPES.has(edge.type))
+                continue;
+            const existing = graph.edgesByFrom.get(edge.from) ?? [];
+            if (!existing.some(e => e.id === edge.id)) {
+                const updated = [...existing, edge];
+                graph.edgesByFrom.set(edge.from, updated);
+                const byTo = graph.edgesByTo.get(edge.to) ?? [];
+                graph.edgesByTo.set(edge.to, [...byTo, edge]);
+            }
+        }
     }
     const graphPath = runtimeConfig.kind === 'filesystem' ? runtimeConfig.graphPath : undefined;
     const contentMap = serializeGraph(graph, { sourceGraphPath: graphPath, outputGraphPath: graphPath });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolis-hq/corum",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "repository": {
     "type": "git",

package/web/app.jsx

@@ -376,7 +376,7 @@ function NodePage({ nodeId, templates, onNavigate, refreshToken, viewingRef, ove
     const overlayParam = overlayRefs && overlayRefs.length > 0
       ? '&' + overlayRefs.map(ref => `overlayRefs=${encodeURIComponent(ref)}`).join('&')
       : '';
-    fetch(`/api/cluster?nodeId=${encodeURIComponent(nodeId)}&includeEdges=maps-to${refParam}${overlayParam}`)
+    fetch(`/api/cluster?nodeId=${encodeURIComponent(nodeId)}&includeEdges=maps-to,reads${refParam}${overlayParam}`)
       .then(response => response.ok ? response.json() : Promise.reject(response.status))
       .then(setCluster)
       .catch(err => setError(String(err)));
@@ -402,12 +402,15 @@ function NodePage({ nodeId, templates, onNavigate, refreshToken, viewingRef, ove
   const displayedNodeIds = new Set([
     root.id,
     ...Array.from(displayChildren.values()).reduce((all, group) => all.concat(group), []).map(child => child.id),
+    ...includedNodes.map(n => n.id),
   ]);
   const rootSpecializedTemplates = new Set(['Schema', 'EnumDefinition']);
   const rootSpecializedNodes = rootSpecializedTemplates.has(root.template) ? [[root.template, [root]]] : [];
   const childDisplayEntries = [...displayChildren.entries()]
     .filter(([templateName]) => templateName !== 'Field' && templateName !== 'EnumValue');
   const displayEntries = [...rootSpecializedNodes, ...childDisplayEntries];
+  const includedSchemaNodes = includedNodes.filter(n => n.template === 'Schema');
+  const includedEnumNodes = includedNodes.filter(n => n.template === 'EnumDefinition');
 
   function handlePropertyNavigate(targetNodeId) {
     if (displayedNodeIds.has(targetNodeId)) {
@@ -465,6 +468,28 @@ function NodePage({ nodeId, templates, onNavigate, refreshToken, viewingRef, ove
             overlayRefs={cluster.overlay ? cluster.overlay.overlayRefs : null}
           />
         ))}
+      {includedSchemaNodes.length > 0 && (
+        <SchemaCard
+          key="__shared-schemas__"
+          title="Schema"
+          nodes={includedSchemaNodes}
+          allNodes={[root, ...descendants, ...includedNodes]}
+          edges={edges}
+          anchorIdForNode={anchorIdForNode}
+          isShared={true}
+        />
+      )}
+      {includedEnumNodes.length > 0 && (
+        <SchemaCard
+          key="__shared-enums__"
+          title="EnumDefinition"
+          nodes={includedEnumNodes}
+          allNodes={[root, ...descendants, ...includedNodes]}
+          edges={edges}
+          anchorIdForNode={anchorIdForNode}
+          isShared={true}
+        />
+      )}
     </div>
   );
 }

package/web/primitives.jsx

@@ -197,17 +197,27 @@ function refName(ref) {
 }
 
 function refLocalSchemaName(ref) {
-  if (typeof ref === 'string') return ref.startsWith('#/schemas/') ? ref.slice(10) : null;
-  if (ref && typeof ref === 'object' && 'display' in ref) return ref.display;
-  return null;
+  if (typeof ref !== 'string') {
+    if (ref && typeof ref === 'object' && 'display' in ref) {
+      const d = String(ref.display);
+      const dot = d.lastIndexOf('.');
+      return dot >= 0 ? d.slice(dot + 1) : d;
+    }
+    return null;
+  }
+  if (ref.startsWith('#/schemas/')) return ref.slice(10);
+  // Global node ID (e.g. "component.Schema.TypeName") — local name is the final segment
+  const lastDot = ref.lastIndexOf('.');
+  return lastDot >= 0 ? ref.slice(lastDot + 1) : null;
 }
 
 function fieldType(properties) {
-  const cardinality = properties?.cardinality === 'many' ? '[]' : '';
-  if (properties?.type) return `${properties.type}${cardinality}`;
+  const c = properties?.collection;
+  const suffix = c === 'array' ? '[]' : c === 'map' ? '{}' : c === 'map-of-map' ? '{{}}' : c === 'map-of-array' ? '{[]}' : '';
+  if (properties?.type) return `${properties.type}${suffix}`;
   const ref = properties?.['$ref'];
-  if (ref) return `${refName(ref)}${cardinality}`;
-  return cardinality ? `unknown${cardinality}` : 'unknown';
+  if (ref) return `${refName(ref)}${suffix}`;
+  return suffix ? `unknown${suffix}` : 'unknown';
 }
 
 function fieldRequirement(properties) {
@@ -217,7 +227,7 @@ function fieldRequirement(properties) {
 }
 
 function fieldCardinality(properties) {
-  return properties?.cardinality ?? '-';
+  return properties?.collection ?? 'one';
 }
 
 function fieldDetails(properties) {
@@ -253,7 +263,11 @@ function enumValueEnumName(nodeId) {
   const valueMarker = '.values.';
   const enumIdx = nodeId.indexOf(enumMarker);
   const valueIdx = nodeId.indexOf(valueMarker);
-  if (enumIdx < 0 || valueIdx < 0) return null;
+  if (valueIdx < 0) return null;
+  if (enumIdx < 0) {
+    // Standalone EnumDefinition node: e.g. component.EnumDefinition.Name.values.X → 'Name'
+    return nodeId.slice(0, valueIdx).split('.').pop() ?? null;
+  }
   return nodeId.slice(enumIdx + enumMarker.length, valueIdx);
 }
 
@@ -266,7 +280,11 @@ function enumValueDescription(node) {
 }
 
 function buildSchemaModel(schemaNodes, allNodes) {
-  const schemasByName = new Map(schemaNodes.map(node => [localSchemaName(node.id), node]));
+  // Include all Schema nodes from allNodes so canExpand works for included/referenced schemas
+  const allSchemaNodes = (allNodes ?? []).filter(n => n.template === 'Schema');
+  const schemasByName = new Map(allSchemaNodes.map(node => [localSchemaName(node.id), node]));
+  // Ensure the primary schemaNodes are always present (they may not be in allNodes)
+  for (const node of schemaNodes) schemasByName.set(localSchemaName(node.id), node);
   const fieldsBySchema = new Map();
   const referencedSchemas = new Set();
 
@@ -317,7 +335,8 @@ function SchemaFieldRows({ schemaName, model, prefix = '', depth = 0, visited =
         const canExpand = localRef !== null && model.schemasByName.has(localRef) && !visited.has(localRef);
         const childSchemaNode = canExpand ? model.schemasByName.get(localRef) : null;
         const childGhostFields = childSchemaNode ? overlayFieldsForSchema(overlayFields, childSchemaNode.id) : [];
-        const childPrefix = `${prefix}${name}${field.properties?.cardinality === 'many' ? '[].' : '.'}`;
+        const c = field.properties?.collection;
+        const childPrefix = `${prefix}${name}${c === 'map-of-map' || c === 'map-of-array' ? '[][].' : c === 'array' || c === 'map' ? '[].' : '.'}`;
         const nextVisited = new Set(visited);
         nextVisited.add(schemaName);
         const links = edges.filter(e =>
@@ -454,7 +473,7 @@ function OverlayLegend({ overlayRefs }) {
   );
 }
 
-function SchemaCard({ title, nodes, allNodes, edges, anchorIdForNode, overlayFields, overlayRefs }) {
+function SchemaCard({ title, nodes, allNodes, edges, anchorIdForNode, overlayFields, overlayRefs, isShared }) {
   if (!nodes || nodes.length === 0) return null;
 
   if (title === 'EnumDefinition') {
@@ -469,7 +488,7 @@ function SchemaCard({ title, nodes, allNodes, edges, anchorIdForNode, overlayFie
 
     return (
       <div className="card enum-card">
-        <div className="card-head">Enums</div>
+        <div className="card-head">{isShared ? 'Shared Enums' : 'Enums'}</div>
         <div className="card-body">
           {nodes.map(enumNode => {
             const enumName = localEnumName(enumNode.id);
@@ -513,7 +532,7 @@ function SchemaCard({ title, nodes, allNodes, edges, anchorIdForNode, overlayFie
     const model = buildSchemaModel(nodes, allNodes ?? nodes);
     return (
       <div className="card schema-card">
-        <div className="card-head">Schemas</div>
+        <div className="card-head">{isShared ? 'Shared Schemas' : 'Schemas'}</div>
         <div className="card-body">
           {model.topSchemas.map(schema => {
             const schemaName = localSchemaName(schema.id);
@@ -521,8 +540,9 @@ function SchemaCard({ title, nodes, allNodes, edges, anchorIdForNode, overlayFie
             return (
               <div key={schema.id} className="schema-section" id={anchorIdForNode ? anchorIdForNode(schema.id) : undefined}>
                 <div className="schema-section-head">
-                  <div>
+                  <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
                     <div className="schema-title">{schemaName}</div>
+                    {isShared && <span className="tag" style={{ fontSize: 10, padding: '1px 6px', background: 'var(--ink-4)', color: 'var(--bg)' }}>shared</span>}
                     {schema.properties?.description && <div className="label-sm">{schema.properties.description}</div>}
                   </div>
                   <div className="label-sm mono">{schema.id}</div>
@@ -532,7 +552,7 @@ function SchemaCard({ title, nodes, allNodes, edges, anchorIdForNode, overlayFie
                   <div />
                   <div className="label-xs">Name</div>
                   <div className="label-xs">Type</div>
-                  <div className="label-xs">Cardinality</div>
+                  <div className="label-xs">Collection</div>
                   <div className="label-xs">Req</div>
                   <div className="label-xs">State</div>
                   <div className="label-xs">Links</div>