@atolis-hq/corum 0.1.0

package/dist/src/graph/index.js

@@ -0,0 +1,128 @@
+import { QueryError } from '../schema/index.js';
+export function listNodes(graph, filter = {}) {
+    return [...graph.nodesById.values()].filter(node => {
+        if (filter.template !== undefined && node.template !== filter.template)
+            return false;
+        if (filter.component !== undefined && node.component !== filter.component)
+            return false;
+        if (filter.state !== undefined && node.state !== filter.state)
+            return false;
+        if (filter.stability !== undefined && node.stability !== filter.stability)
+            return false;
+        return true;
+    });
+}
+export function getCluster(graph, nodeId) {
+    const root = graph.nodesById.get(nodeId);
+    if (!root)
+        throw new QueryError(`Node not found: ${nodeId}`);
+    const prefix = `${nodeId}.`;
+    const children = [...graph.nodesById.values()].filter(node => node.id.startsWith(prefix));
+    const clusterIds = new Set([nodeId, ...children.map(node => node.id)]);
+    const edges = [];
+    const seen = new Set();
+    for (const id of clusterIds) {
+        for (const edge of graph.edgesByFrom.get(id) ?? []) {
+            if (clusterIds.has(edge.to) && !seen.has(edge.id)) {
+                edges.push(edge);
+                seen.add(edge.id);
+            }
+        }
+    }
+    return { root, children, edges };
+}
+export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
+    const cluster = getCluster(graph, nodeId);
+    if (includeEdgeTypes.length === 0) {
+        return {
+            root: cluster.root,
+            descendants: cluster.children,
+            includedNodes: [],
+            edges: cluster.edges,
+        };
+    }
+    const clusterIds = new Set([cluster.root.id, ...cluster.children.map(node => node.id)]);
+    const requestedTypes = new Set(includeEdgeTypes);
+    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);
+        }
+        for (const edge of graph.edgesByTo.get(id) ?? []) {
+            collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen);
+        }
+    }
+    return {
+        root: cluster.root,
+        descendants: cluster.children,
+        includedNodes: [...includedNodeIds]
+            .map(id => graph.nodesById.get(id))
+            .filter((node) => node !== undefined),
+        edges,
+    };
+}
+export function getLinkedFields(graph, nodeId) {
+    const root = graph.nodesById.get(nodeId);
+    if (!root)
+        throw new QueryError(`Node not found: ${nodeId}`);
+    const prefix = `${nodeId}.`;
+    const ownedFieldIds = new Set([...graph.nodesById.entries()]
+        .filter(([id, node]) => id.startsWith(prefix) && node.template === 'Field')
+        .map(([id]) => id));
+    const edges = [];
+    const nodeIds = new Set();
+    const seen = new Set();
+    for (const fieldId of ownedFieldIds) {
+        for (const edge of graph.edgesByFrom.get(fieldId) ?? []) {
+            collectMapsTo(edge, edges, nodeIds, seen);
+        }
+        for (const edge of graph.edgesByTo.get(fieldId) ?? []) {
+            collectMapsTo(edge, edges, nodeIds, seen);
+        }
+    }
+    return {
+        edges,
+        nodes: [...nodeIds]
+            .map(id => graph.nodesById.get(id))
+            .filter((node) => node !== undefined),
+    };
+}
+function collectMapsTo(edge, edges, nodeIds, seen) {
+    if (edge.type !== 'maps-to' || seen.has(edge.id))
+        return;
+    edges.push(edge);
+    nodeIds.add(edge.from);
+    nodeIds.add(edge.to);
+    seen.add(edge.id);
+}
+function collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen) {
+    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);
+}
+const OVERLAY_EXCLUDED = new Set(['local', 'shared']);
+export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRootId) {
+    const overlay = multi.overlay(viewingRef);
+    const prefix = `${clusterRootId}.`;
+    const fields = [...overlay.nodes.values()]
+        .filter(node => {
+        if (OVERLAY_EXCLUDED.has(node.ghostState))
+            return false;
+        if (!node.id.startsWith(prefix))
+            return false;
+        return overlayRefs.some(ref => node.presence.has(ref));
+    })
+        .map(node => {
+        const sourceRef = overlayRefs.find(ref => node.presence.has(ref)) ?? viewingRef;
+        const sourceNode = node.presence.get(sourceRef) ?? [...node.presence.values()][0];
+        return { id: node.id, ghostState: node.ghostState, sourceRef, node: sourceNode };
+    });
+    return fields.length === 0 ? null : { viewingRef, overlayRefs, fields };
+}

package/dist/src/graph/overlay.js

@@ -0,0 +1,136 @@
+import { QueryError } from '../schema/index.js';
+export function computeOverlay(viewingRef, defaultBranch, allBranches) {
+    const branches = uniqueBranches([defaultBranch, ...allBranches]);
+    if (!branches.some(branch => branch.ref === viewingRef)) {
+        throw new QueryError(`branch '${viewingRef}' not found in loaded branches`);
+    }
+    const nodes = new Map();
+    for (const id of collectNodeIds(branches)) {
+        const presence = new Map();
+        for (const branch of branches) {
+            const node = branch.graph.nodesById.get(id);
+            if (node)
+                presence.set(branch.ref, node);
+        }
+        nodes.set(id, {
+            id,
+            presence,
+            ghostState: classifyPresence(viewingRef, defaultBranch.ref, presence, nodesEqual),
+        });
+    }
+    const edges = new Map();
+    for (const id of collectEdgeIds(branches)) {
+        const presence = new Map();
+        for (const branch of branches) {
+            const edge = findEdge(branch, id);
+            if (edge)
+                presence.set(branch.ref, edge);
+        }
+        edges.set(id, {
+            id,
+            presence,
+            ghostState: classifyPresence(viewingRef, defaultBranch.ref, presence, edgesEqual),
+        });
+    }
+    return { viewingRef, nodes, edges };
+}
+export function computeDiff(branch, defaultBranch) {
+    const added = [];
+    const modified = [];
+    const removed = [];
+    for (const [id, node] of branch.graph.nodesById) {
+        const defaultNode = defaultBranch.graph.nodesById.get(id);
+        if (!defaultNode) {
+            added.push(node);
+        }
+        else if (!nodesEqual(node, defaultNode)) {
+            modified.push(node);
+        }
+    }
+    for (const [id, node] of defaultBranch.graph.nodesById) {
+        if (!branch.graph.nodesById.has(id))
+            removed.push(node);
+    }
+    return { added, modified, removed };
+}
+function classifyPresence(viewingRef, defaultRef, presence, equal) {
+    const viewingItem = presence.get(viewingRef);
+    if (viewingItem) {
+        const others = [...presence.entries()].filter(([ref]) => ref !== viewingRef);
+        if (others.length === 0)
+            return 'local';
+        return others.every(([, item]) => equal(viewingItem, item)) ? 'shared' : 'local-modified';
+    }
+    const defaultItem = presence.get(defaultRef);
+    const nonDefault = [...presence.entries()].filter(([ref]) => ref !== defaultRef && ref !== viewingRef);
+    if (defaultItem && nonDefault.length === 0)
+        return 'default-only';
+    if (!defaultItem && nonDefault.length === 1)
+        return 'ghost-single';
+    const otherItems = [...presence.values()];
+    const first = otherItems[0];
+    return first && otherItems.every(item => equal(first, item)) ? 'ghost-consensus' : 'ghost-conflict';
+}
+function nodesEqual(a, b) {
+    return deepEqual(a.properties, b.properties)
+        && a.state === b.state
+        && a.stability === b.stability;
+}
+function edgesEqual(a, b) {
+    return a.type === b.type
+        && a.state === b.state
+        && a.stability === b.stability
+        && a.notes === b.notes;
+}
+function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    const aRecord = a;
+    const bRecord = b;
+    const aKeys = Object.keys(aRecord);
+    const bKeys = Object.keys(bRecord);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every(key => Object.prototype.hasOwnProperty.call(bRecord, key) && deepEqual(aRecord[key], bRecord[key]));
+}
+function uniqueBranches(branches) {
+    const byRef = new Map();
+    for (const branch of branches) {
+        if (!byRef.has(branch.ref))
+            byRef.set(branch.ref, branch);
+    }
+    return [...byRef.values()];
+}
+function collectNodeIds(branches) {
+    const ids = new Set();
+    for (const branch of branches) {
+        for (const id of branch.graph.nodesById.keys())
+            ids.add(id);
+    }
+    return ids;
+}
+function collectEdgeIds(branches) {
+    const ids = new Set();
+    for (const branch of branches) {
+        for (const edgeList of branch.graph.edgesByFrom.values()) {
+            for (const edge of edgeList)
+                ids.add(edge.id);
+        }
+    }
+    return ids;
+}
+function findEdge(branch, edgeId) {
+    for (const edgeList of branch.graph.edgesByFrom.values()) {
+        const edge = edgeList.find(item => item.id === edgeId);
+        if (edge)
+            return edge;
+    }
+    return undefined;
+}

package/dist/src/import/config.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+export function loadImportConfig(filePath) {
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse import config: ${err}`);
+    }
+    if (!isImportConfig(raw)) {
+        throw new Error(`Invalid import config: must have an "imports" array`);
+    }
+    return raw;
+}
+function isImportConfig(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'imports' in value &&
+        Array.isArray(value.imports));
+}
+export function buildOpenAPIConfig(spec, strategy, segment, pattern, component) {
+    let componentMapping;
+    if (strategy === 'hardcoded') {
+        if (!component)
+            throw new Error('--component required for hardcoded strategy');
+        componentMapping = { strategy: 'hardcoded', component };
+    }
+    else if (strategy === 'tag') {
+        componentMapping = { strategy: 'tag' };
+    }
+    else if (pattern) {
+        componentMapping = { strategy: 'uri-segment', pattern };
+    }
+    else {
+        componentMapping = { strategy: 'uri-segment', segment: segment ?? 0 };
+    }
+    return { adapter: 'openapi', spec, componentMapping };
+}

package/dist/src/import/runner.js

@@ -0,0 +1,56 @@
+import { parse as parseYaml } from 'yaml';
+import path from 'node:path';
+import { loadGraph } from '../loader/index.js';
+import { serializeGraph } from '../writer/graph-writer.js';
+import { getAdapter } from '../adapters/index.js';
+import { diffNodes } from '../reconcile/index.js';
+export async function runImport(config, runtimeConfig) {
+    const allDiagnostics = [];
+    const graph = await loadGraph({ source: runtimeConfig.source });
+    for (const entry of config.imports) {
+        const packConfig = await loadPackAdapterConfig(runtimeConfig, entry.adapter);
+        if (!packConfig) {
+            allDiagnostics.push({
+                severity: 'error',
+                file: runtimeConfig.graphPath,
+                message: `No ${entry.adapter} adapter config found in active packs — is the ${entry.adapter === 'openapi' ? 'rest' : entry.adapter} pack active?`,
+            });
+            continue;
+        }
+        const specPath = path.resolve(entry.spec);
+        const resolvedEntry = { ...entry, spec: specPath };
+        const adapter = getAdapter(resolvedEntry.adapter);
+        const result = await adapter.import(resolvedEntry, { packConfig, templates: graph.templates });
+        allDiagnostics.push(...result.diagnostics);
+        if (result.diagnostics.some(d => d.severity === 'error'))
+            continue;
+        const { toAdd, toUpdate, toRemove } = diffNodes(result.nodes, graph.nodesById, specPath);
+        for (const node of [...toAdd, ...toUpdate, ...toRemove]) {
+            graph.nodesById.set(node.id, node);
+        }
+    }
+    const graphPath = runtimeConfig.kind === 'filesystem' ? runtimeConfig.graphPath : undefined;
+    const contentMap = serializeGraph(graph, { sourceGraphPath: graphPath, outputGraphPath: graphPath });
+    await runtimeConfig.source.commit(await runtimeConfig.source.defaultBranch(), contentMap, 'corum import', { replaceGraphContent: true });
+    return { diagnostics: allDiagnostics };
+}
+async function loadPackAdapterConfig(runtimeConfig, adapterId) {
+    let packContent;
+    try {
+        packContent = await runtimeConfig.source.loadPackContent(await runtimeConfig.source.defaultBranch());
+    }
+    catch {
+        return null;
+    }
+    for (const [key, content] of packContent) {
+        if (key.endsWith(`/adapters/${adapterId}.yaml`)) {
+            try {
+                return parseYaml(content);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}

package/dist/src/loader/cluster-loader.js

@@ -0,0 +1,120 @@
+import { parse as parseYaml } from 'yaml';
+import { getOwnedSections } from './pack-loader.js';
+import { listYamlKeys, readYaml } from '../source/content-utils.js';
+import { STRUCTURAL_EDGE_BY_ITEM_TEMPLATE, VALID_STABILITY_SET, VALID_STATE_SET } from './constants.js';
+export function loadClusters(content, templates, diagnostics) {
+    const result = { nodes: new Map(), edgesByFrom: new Map(), edgesByTo: new Map() };
+    for (const key of listYamlKeys(content, 'components')) {
+        let raw;
+        try {
+            raw = parseYaml(readYaml(content, key));
+        }
+        catch (err) {
+            diagnostics.push({ severity: 'error', file: key, message: `failed to parse YAML: ${err}` });
+            continue;
+        }
+        const record = raw;
+        const meta = record.metadata;
+        if (typeof record.id !== 'string' ||
+            typeof record.template !== 'string' ||
+            typeof record.schemaVersion !== 'string' ||
+            !isRecord(meta) ||
+            typeof meta.component !== 'string' ||
+            typeof meta.lastModifiedAt !== 'string') {
+            diagnostics.push({ severity: 'error', file: key, message: 'cluster missing required root fields' });
+            continue;
+        }
+        const root = {
+            id: record.id,
+            template: record.template,
+            component: meta.component,
+            state: asState(meta.state, 'proposed'),
+            stability: asStability(meta.stability, 'unstable'),
+            schemaVersion: record.schemaVersion,
+            lastModifiedAt: meta.lastModifiedAt,
+            ...(typeof meta.extractedFrom === 'string' && { extractedFrom: meta.extractedFrom }),
+            ...(typeof meta.derivation === 'string' && { derivation: meta.derivation }),
+            ...(typeof meta.derivedBy === 'string' && { derivedBy: meta.derivedBy }),
+            properties: isRecord(record.properties) ? record.properties : {},
+        };
+        addNode(result, root, key, diagnostics);
+        materialiseChildren(result, root, record, templates, key, diagnostics);
+    }
+    return result;
+}
+function materialiseChildren(result, parent, source, templates, filePath, diagnostics) {
+    const template = templates.get(parent.template);
+    if (!template) {
+        diagnostics.push({ severity: 'error', file: filePath, nodeId: parent.id, message: `unknown template: ${parent.template}` });
+        return;
+    }
+    for (const [sectionName, childTemplateName] of Object.entries(getOwnedSections(template))) {
+        const section = source[sectionName];
+        if (!isRecord(section))
+            continue;
+        for (const [localName, value] of Object.entries(section)) {
+            if (!isRecord(value)) {
+                diagnostics.push({
+                    severity: 'error',
+                    file: filePath,
+                    nodeId: `${parent.id}.${sectionName}.${localName}`,
+                    message: `owned item in ${sectionName} must be an object`,
+                });
+                continue;
+            }
+            const childId = `${parent.id}.${sectionName}.${localName}`;
+            const child = {
+                id: childId,
+                template: childTemplateName,
+                component: parent.component,
+                state: asState(value.state, parent.state),
+                stability: asStability(value.stability, parent.stability),
+                schemaVersion: parent.schemaVersion,
+                lastModifiedAt: parent.lastModifiedAt,
+                properties: stripOwnedSections(value, childTemplateName, templates),
+            };
+            addNode(result, child, filePath, diagnostics);
+            const edgeType = STRUCTURAL_EDGE_BY_ITEM_TEMPLATE[childTemplateName];
+            if (edgeType) {
+                addEdge(result, {
+                    id: `${parent.id}__${edgeType}__${child.id}`,
+                    from: parent.id,
+                    to: child.id,
+                    type: edgeType,
+                    state: child.state,
+                    stability: child.stability,
+                });
+            }
+            materialiseChildren(result, child, value, templates, filePath, diagnostics);
+        }
+    }
+}
+function stripOwnedSections(value, templateName, templates) {
+    const ownedSections = new Set(Object.keys(getOwnedSections(templates.get(templateName) ?? ({ name: templateName, info: { version: 'unknown' } }))));
+    const nodeMetadata = new Set(['state', 'stability']);
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !ownedSections.has(key) && !nodeMetadata.has(key)));
+}
+function addNode(result, node, file, diagnostics) {
+    if (result.nodes.has(node.id)) {
+        diagnostics.push({ severity: 'error', file, nodeId: node.id, message: `duplicate node id: ${node.id}` });
+        return;
+    }
+    result.nodes.set(node.id, node);
+}
+function addEdge(result, edge) {
+    const from = result.edgesByFrom.get(edge.from) ?? [];
+    from.push(edge);
+    result.edgesByFrom.set(edge.from, from);
+    const to = result.edgesByTo.get(edge.to) ?? [];
+    to.push(edge);
+    result.edgesByTo.set(edge.to, to);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asState(value, fallback) {
+    return typeof value === 'string' && VALID_STATE_SET.has(value) ? value : fallback;
+}
+function asStability(value, fallback) {
+    return typeof value === 'string' && VALID_STABILITY_SET.has(value) ? value : fallback;
+}

package/dist/src/loader/constants.js

@@ -0,0 +1,32 @@
+export const VALID_STATES = [
+    'draft',
+    'proposed',
+    'agreed',
+    'future',
+    'removed',
+    'implemented',
+];
+export const VALID_STABILITIES = [
+    'unstable',
+    'stable',
+    'deprecated',
+];
+export const VALID_EDGE_TYPES = [
+    'triggers',
+    'produces',
+    'reads',
+    'calls',
+    'implements',
+    'maps-to',
+    'derived-from',
+    'renamed-from',
+    'has-field',
+    'has-value',
+];
+export const VALID_STATE_SET = new Set(VALID_STATES);
+export const VALID_STABILITY_SET = new Set(VALID_STABILITIES);
+export const VALID_EDGE_TYPE_SET = new Set(VALID_EDGE_TYPES);
+export const STRUCTURAL_EDGE_BY_ITEM_TEMPLATE = {
+    Field: 'has-field',
+    EnumValue: 'has-value',
+};

package/dist/src/loader/edge-loader.js

@@ -0,0 +1,59 @@
+import { parse as parseYaml } from 'yaml';
+import { VALID_EDGE_TYPE_SET } from './constants.js';
+import { listYamlKeys, readYaml } from '../source/content-utils.js';
+export function loadEdges(content, nodes, diagnostics) {
+    const result = { edgesByFrom: new Map(), edgesByTo: new Map() };
+    for (const key of listYamlKeys(content, 'edges')) {
+        let raw;
+        try {
+            raw = parseYaml(readYaml(content, key));
+        }
+        catch (err) {
+            diagnostics.push({ severity: 'error', file: key, message: `failed to parse YAML: ${err}` });
+            continue;
+        }
+        const edgeList = raw.edges ?? [];
+        for (const edgeRaw of edgeList) {
+            const edgeRecord = edgeRaw;
+            if (typeof edgeRecord.from !== 'string' ||
+                typeof edgeRecord.to !== 'string' ||
+                typeof edgeRecord.type !== 'string') {
+                diagnostics.push({ severity: 'error', file: key, message: 'edge missing required from, to, or type' });
+                continue;
+            }
+            if (!VALID_EDGE_TYPE_SET.has(edgeRecord.type)) {
+                diagnostics.push({ severity: 'error', file: key, message: `invalid edge type: ${edgeRecord.type}` });
+                continue;
+            }
+            let unresolvedEndpoint = false;
+            if (!nodes.has(edgeRecord.from)) {
+                diagnostics.push({ severity: 'error', file: key, message: `edge from unresolved node: ${edgeRecord.from}` });
+                unresolvedEndpoint = true;
+            }
+            if (!nodes.has(edgeRecord.to)) {
+                diagnostics.push({ severity: 'error', file: key, message: `edge to unresolved node: ${edgeRecord.to}` });
+                unresolvedEndpoint = true;
+            }
+            if (unresolvedEndpoint)
+                continue;
+            addEdge(result, {
+                id: `${edgeRecord.from}__${edgeRecord.type}__${edgeRecord.to}`,
+                from: edgeRecord.from,
+                to: edgeRecord.to,
+                type: edgeRecord.type,
+                state: typeof edgeRecord.state === 'string' ? edgeRecord.state : 'proposed',
+                stability: typeof edgeRecord.stability === 'string' ? edgeRecord.stability : 'unstable',
+                notes: typeof edgeRecord.notes === 'string' ? edgeRecord.notes : undefined,
+            });
+        }
+    }
+    return result;
+}
+function addEdge(result, edge) {
+    const from = result.edgesByFrom.get(edge.from) ?? [];
+    from.push(edge);
+    result.edgesByFrom.set(edge.from, from);
+    const to = result.edgesByTo.get(edge.to) ?? [];
+    to.push(edge);
+    result.edgesByTo.set(edge.to, to);
+}

package/dist/src/loader/fs-utils.js

@@ -0,0 +1,20 @@
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+export function walkYamlFiles(dir) {
+    const result = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            result.push(...walkYamlFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.yaml')) {
+            result.push(fullPath);
+        }
+    }
+    return result;
+}
+export function isPackRef(value) {
+    return typeof value === 'object' &&
+        value !== null &&
+        typeof value.path === 'string';
+}