@terra-graph/core 1.0.0-rc.4

package/dist/esm/Graph/GraphResolver.d.ts

@@ -0,0 +1,21 @@
+import { AdapterOperations } from './Operations/Operations.js';
+import { BaseRule } from './Rules/Rule.js';
+import { TgGraph } from './TgGraph.js';
+export type PhaseRunnerContext = {
+    logger?: (message: string) => void;
+    errorHandler?: (error: Error) => void;
+};
+export type GraphResolverInput = {
+    graph: TgGraph;
+    phases: BaseRule[][];
+};
+export declare class GraphResolver {
+    private readonly adapter;
+    private context?;
+    constructor(adapter: AdapterOperations, context?: PhaseRunnerContext | undefined);
+    resolve(input: GraphResolverInput): AdapterOperations;
+    private modify;
+    private log;
+    private handleError;
+    private logMessage;
+}

package/dist/esm/Graph/GraphResolver.js

@@ -0,0 +1,76 @@
+import { RuleMatchError, RuleModifyError } from './RuleError.js';
+export class GraphResolver {
+    adapter;
+    context;
+    constructor(adapter, context) {
+        this.adapter = adapter;
+        this.context = context;
+    }
+    resolve(input) {
+        let adapter = this.adapter.withTgGraph(input.graph);
+        const phases = input.phases ?? [];
+        for (const [index, phase] of phases.entries()) {
+            const phaseLabel = `phase-${index + 1}`;
+            this.log(this.context, `applying ${phaseLabel}: ${adapter.nodeIds().length} nodes`);
+            adapter = this.modify(adapter, phase, this.context, phaseLabel);
+        }
+        return adapter;
+    }
+    modify(adapter, rules, context, logPrefix = 'phase') {
+        let updated = adapter;
+        const nodeIds = adapter.nodeIds();
+        for (const nodeId of nodeIds) {
+            for (const rule of rules) {
+                const node = updated.getNodeAttributes(nodeId);
+                if (!node) {
+                    break;
+                }
+                try {
+                    if (rule.match(nodeId, node, updated)) {
+                        if (rule.describe) {
+                            this.log(context, this.logMessage(`${logPrefix}:match`, rule.describe(nodeId, node), nodeId));
+                        }
+                        try {
+                            if (!rule.supports(updated)) {
+                                continue;
+                            }
+                            updated = rule.apply(nodeId, node, updated);
+                        }
+                        catch (e) {
+                            throw new RuleModifyError({ cause: e }, {
+                                nodeId: nodeId,
+                                nodeAttributes: node,
+                            });
+                        }
+                    }
+                }
+                catch (e) {
+                    if (!(e instanceof RuleModifyError)) {
+                        // biome-ignore lint/suspicious/noCatchAssign: <explanation>
+                        e = new RuleMatchError({ cause: e }, {
+                            nodeId: nodeId,
+                            nodeAttributes: node,
+                        });
+                    }
+                    this.handleError(context, e);
+                }
+            }
+        }
+        return updated;
+    }
+    log(context, message) {
+        if (context?.logger) {
+            context.logger(message);
+        }
+    }
+    handleError(context, error) {
+        if (context?.errorHandler) {
+            context.errorHandler(error);
+            return;
+        }
+        throw error;
+    }
+    logMessage(prefix, msg, nodeName) {
+        return ` -> [${prefix}][${msg}]: ${nodeName}`;
+    }
+}

package/dist/esm/Graph/GraphResolver.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/Graph/GraphResolver.test.js

@@ -0,0 +1,271 @@
+import { DirectedGraph } from 'graphology';
+import { mock } from 'jest-mock-extended';
+import { GraphologyAdapter } from './Adapters/GraphologyAdapter.js';
+import { GraphResolver } from './GraphResolver.js';
+import { RuleModifyError } from './RuleError.js';
+import { RemoveNode } from './Rules/Node/RemoveNode.js';
+import { NodeRule } from './Rules/Rule.js';
+import { TG_SCHEMA_VERSION, asNodeId } from './TgGraph.js';
+describe('GraphResolver.resolve', () => {
+    const createGraph = () => {
+        const a = asNodeId('resolver.node-a');
+        const b = asNodeId('resolver.node-b');
+        return {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [a]: { id: a, label: 'resolver.node-a' },
+                [b]: { id: b, label: 'resolver.node-b' },
+            },
+            edges: [],
+        };
+    };
+    class CountingRule extends NodeRule {
+        applyCalls = 0;
+        apply(nodeId, _node, graph) {
+            if (!this.wasMatched(nodeId)) {
+                return graph;
+            }
+            this.applyCalls += 1;
+            return graph;
+        }
+    }
+    class ThrowingMatchRule extends NodeRule {
+        apply(_nodeId, _node, graph) {
+            return graph;
+        }
+        matches(_nodeId, _node, _graph) {
+            throw new Error('match failed');
+        }
+    }
+    class ThrowingApplyRule extends NodeRule {
+        throwCalls = 0;
+        apply(nodeId, _node, _graph) {
+            this.throwCalls += 1;
+            throw new Error(`apply failed on ${nodeId}`);
+        }
+    }
+    class UnsupportedApplyRule extends NodeRule {
+        applyCalls = 0;
+        supports() {
+            return false;
+        }
+        apply(_nodeId, _node, _graph) {
+            this.applyCalls += 1;
+            return _graph;
+        }
+    }
+    it('shoud initialize the adapter and skip processing when there are no rules', () => {
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()), mock());
+        const input = createGraph();
+        const result = resolver.resolve({
+            graph: input,
+            phases: [],
+        });
+        const tg = result.toTgGraph();
+        const expectedNodeIds = Object.keys(input.nodes);
+        expect(tg.edges).toHaveLength(0);
+        expect(Object.keys(tg.nodes)).toHaveLength(expectedNodeIds.length);
+        for (const nodeId of expectedNodeIds) {
+            expect(tg.nodes[nodeId]).toEqual({
+                id: nodeId,
+            });
+        }
+    });
+    it('shoud treat missing phases as an empty plan', () => {
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()));
+        const input = createGraph();
+        const result = resolver.resolve({
+            graph: input,
+            phases: undefined,
+        });
+        expect(result.nodeIds()).toHaveLength(2);
+    });
+    it('shoud default logPrefix when calling modify directly', () => {
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(createGraph());
+        const resolver = new GraphResolver(adapter);
+        const result = resolver.modify(adapter, [], undefined);
+        expect(result).toBe(adapter);
+    });
+    it('shoud apply rules across all phases and all matching nodes', () => {
+        const adapter = new GraphologyAdapter(new DirectedGraph());
+        const resolver = new GraphResolver(adapter);
+        const input = createGraph();
+        const phaseOne = new CountingRule({
+            node: { any: true },
+        });
+        const phaseTwo = new CountingRule({
+            node: { any: true },
+        });
+        const result = resolver.resolve({
+            graph: input,
+            phases: [[phaseOne], [phaseTwo]],
+        });
+        expect(result.nodeIds()).toHaveLength(2);
+        expect(phaseOne.applyCalls).toBe(2);
+        expect(phaseTwo.applyCalls).toBe(2);
+    });
+    it('shoud skip applying a node when the node fails rule matching', () => {
+        const adapter = new GraphologyAdapter(new DirectedGraph());
+        const resolver = new GraphResolver(adapter);
+        const input = createGraph();
+        const matcher = new CountingRule({
+            node: { nodeId: { eq: String(asNodeId('resolver.node-a')) } },
+        });
+        const result = resolver.resolve({
+            graph: input,
+            phases: [[matcher]],
+        });
+        expect(result.nodeIds()).toHaveLength(2);
+        expect(matcher.applyCalls).toBe(1);
+    });
+    it('shoud report phase progress through the logger', () => {
+        const logger = jest.fn();
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()), { logger });
+        const input = createGraph();
+        const result = resolver.resolve({
+            graph: input,
+            phases: [
+                [new RemoveNode({ node: { any: true } })],
+                [new RemoveNode({ node: { any: true } })],
+            ],
+        });
+        expect(logger).toHaveBeenCalledWith('applying phase-1: 2 nodes');
+        expect(logger).toHaveBeenCalledWith('applying phase-2: 0 nodes');
+        expect(result.nodeIds()).toHaveLength(0);
+    });
+    it('shoud skip match logging when describe is missing', () => {
+        const logger = jest.fn();
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()), { logger });
+        const input = createGraph();
+        class SilentRule extends NodeRule {
+            apply(_nodeId, _node, graph) {
+                return graph;
+            }
+        }
+        const rule = new SilentRule({ node: { any: true } });
+        rule.describe = undefined;
+        resolver.resolve({
+            graph: input,
+            phases: [[rule]],
+        });
+        expect(logger).toHaveBeenCalledWith('applying phase-1: 2 nodes');
+        expect(logger).toHaveBeenCalledTimes(1);
+    });
+    it('shoud skip rules when supports returns false', () => {
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()));
+        const input = createGraph();
+        const rule = new UnsupportedApplyRule({
+            node: { any: true },
+        });
+        const result = resolver.resolve({
+            graph: input,
+            phases: [[rule]],
+        });
+        expect(result.nodeIds()).toHaveLength(2);
+        expect(rule.applyCalls).toBe(0);
+    });
+    it('shoud stop applying later rules for a node after removeNode', () => {
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()));
+        const input = createGraph();
+        const throwingRule = new ThrowingApplyRule({
+            node: { any: true },
+        });
+        const result = resolver.resolve({
+            graph: input,
+            phases: [[new RemoveNode({ node: { any: true } }), throwingRule]],
+        });
+        expect(result.nodeIds()).toHaveLength(0);
+        expect(throwingRule.throwCalls).toBe(0);
+    });
+    it('shoud wrap match failures when no error handler is provided', () => {
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()));
+        const input = createGraph();
+        const rule = new ThrowingMatchRule({
+            node: { any: true },
+        });
+        expect(() => resolver.resolve({
+            graph: input,
+            phases: [[rule]],
+        })).toThrow('Rule was unable to match node');
+    });
+    it('shoud wrap apply failures when no error handler is provided', () => {
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()));
+        const input = createGraph();
+        const rule = new ThrowingApplyRule({
+            node: { any: true },
+        });
+        expect(() => resolver.resolve({
+            graph: input,
+            phases: [[rule]],
+        })).toThrow('Rule was unable to modify node');
+    });
+    it('shoud pass RuleMatch errors through without wrapping when already a RuleModifyError', () => {
+        class DirectModifyMatchRule extends NodeRule {
+            apply(_nodeId, _node, graph) {
+                return graph;
+            }
+            matches(nodeId, node, _graph) {
+                throw new RuleModifyError({ cause: new Error('inner match failure') }, {
+                    nodeId: nodeId,
+                    nodeAttributes: node,
+                });
+            }
+        }
+        const errorHandler = jest.fn();
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()), {
+            errorHandler,
+        });
+        const input = createGraph();
+        const result = resolver.resolve({
+            graph: input,
+            phases: [[new DirectModifyMatchRule({ node: { any: true } })]],
+        });
+        expect(result.nodeIds()).toHaveLength(2);
+        expect(errorHandler).toHaveBeenCalledTimes(2);
+        expect(errorHandler).toHaveBeenCalledWith(expect.objectContaining({
+            message: expect.stringContaining('Rule was unable to modify node'),
+        }));
+    });
+    it('shoud delegate rule errors to the provided error handler', () => {
+        const errorHandler = jest.fn();
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()), {
+            errorHandler,
+        });
+        const input = createGraph();
+        const matchErrorRule = new ThrowingMatchRule({
+            node: { any: true },
+        });
+        const applyErrorRule = new ThrowingApplyRule({
+            node: { any: true },
+        });
+        const result = resolver.resolve({
+            graph: input,
+            phases: [[matchErrorRule], [applyErrorRule]],
+        });
+        expect(errorHandler).toHaveBeenCalledTimes(4);
+        expect(result.nodeIds()).toHaveLength(2);
+    });
+    it('shoud continue execution after handler-covered match and apply errors', () => {
+        const errorHandler = jest.fn();
+        const resolver = new GraphResolver(new GraphologyAdapter(new DirectedGraph()), {
+            errorHandler,
+        });
+        const input = createGraph();
+        const matchErrorRule = new ThrowingMatchRule({
+            node: { any: true },
+        });
+        const recoverRule = new RemoveNode({
+            node: { any: true },
+        });
+        const applyErrorRule = new ThrowingApplyRule({
+            node: { any: true },
+        });
+        const result = resolver.resolve({
+            graph: input,
+            phases: [[matchErrorRule], [applyErrorRule, recoverRule]],
+        });
+        expect(errorHandler).toHaveBeenCalledTimes(4);
+        expect(result.nodeIds()).toHaveLength(0);
+    });
+});

package/dist/esm/Graph/Importer.d.ts

@@ -0,0 +1,7 @@
+import type { TgGraph } from './TgGraph.js';
+export type ImportContext = {
+    description?: Record<string, string>;
+};
+export interface Importer {
+    fromString(input: string, context?: ImportContext): TgGraph;
+}

package/dist/esm/Graph/Importer.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/Graph/Importers/TerraformDotImporter.d.ts

@@ -0,0 +1,12 @@
+import { ImportContext, Importer } from '../Importer.js';
+import { TgGraph } from '../TgGraph.js';
+export declare class TerraformDotImporter implements Importer {
+    fromString(input: string, context?: ImportContext): TgGraph;
+    private resolveNodeId;
+    private resolveAddress;
+    private normalizeAddress;
+    private extractModulePrefix;
+    private resolveKind;
+    private describeNode;
+    private parentModuleHelpers;
+}

package/dist/esm/Graph/Importers/TerraformDotImporter.js

@@ -0,0 +1,238 @@
+import dot from 'graphlib-dot';
+import { DotAdapter } from '../Adapters/DotAdapter.js';
+import { TG_SCHEMA_VERSION, edgeIdFrom, tgNodeIdFrom, } from '../TgGraph.js';
+export class TerraformDotImporter {
+    fromString(input, context = {}) {
+        const graph = dot.read(input);
+        const nodes = {};
+        const edges = [];
+        const nodeIdMap = new Map();
+        for (const rawNodeId of graph.nodes()) {
+            const attributes = (graph.node(rawNodeId) ?? {});
+            const { label, ...adapterAttributes } = attributes;
+            const address = this.resolveAddress(rawNodeId, typeof label === 'string' ? label : undefined);
+            const kind = this.resolveKind(address);
+            const nodeDetails = this.describeNode(address, kind);
+            const id = tgNodeIdFrom(kind, address);
+            const node = {
+                id,
+                terraform: nodeDetails,
+            };
+            if (Object.keys(adapterAttributes).length > 0) {
+                node.adapter = {
+                    [DotAdapter.name]: adapterAttributes,
+                };
+            }
+            nodes[id] = node;
+            nodeIdMap.set(rawNodeId, id);
+        }
+        for (const edge of graph.edges()) {
+            const from = this.resolveNodeId(edge.v, graph.node(edge.v), nodeIdMap);
+            const to = this.resolveNodeId(edge.w, graph.node(edge.w), nodeIdMap);
+            const suffix = edge.name === undefined ? undefined : String(edge.name);
+            const edgeId = edgeIdFrom(from, to, suffix);
+            const attributes = (graph.edge(edge) ?? {});
+            let edgeAttributes;
+            if (Object.keys(attributes).length > 0) {
+                edgeAttributes = {
+                    adapter: {
+                        [DotAdapter.name]: attributes,
+                    },
+                };
+            }
+            edges.push({
+                id: edgeId,
+                from,
+                to,
+                attributes: edgeAttributes,
+            });
+        }
+        return {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: context.description ?? {},
+            nodes,
+            edges,
+        };
+    }
+    resolveNodeId(rawNodeId, nodeAttributes, nodeIdMap) {
+        const existing = nodeIdMap.get(rawNodeId);
+        if (existing) {
+            return existing;
+        }
+        const label = nodeAttributes?.label;
+        const address = this.resolveAddress(rawNodeId, typeof label === 'string' ? label : undefined);
+        const kind = this.resolveKind(address);
+        const nodeId = tgNodeIdFrom(kind, address);
+        nodeIdMap.set(rawNodeId, nodeId);
+        return nodeId;
+    }
+    resolveAddress(rawNodeId, label) {
+        const normalizedRaw = this.normalizeAddress(rawNodeId);
+        if (normalizedRaw.startsWith('cluster_module.')) {
+            return `module.${normalizedRaw.slice('cluster_module.'.length)}`;
+        }
+        if (!label) {
+            return normalizedRaw;
+        }
+        const normalizedLabel = this.normalizeAddress(label);
+        if (normalizedRaw.startsWith('module.') &&
+            !normalizedLabel.startsWith('module.')) {
+            const modulePrefix = this.extractModulePrefix(normalizedRaw);
+            if (modulePrefix) {
+                return `${modulePrefix}.${normalizedLabel}`;
+            }
+        }
+        return normalizedRaw;
+    }
+    normalizeAddress(value) {
+        return value
+            .trim()
+            .replace(/^\[root\]\s*/, '')
+            .replace(/\s+\([^)]*\)$/, '');
+    }
+    extractModulePrefix(value) {
+        const segments = value.split('.');
+        let index = 0;
+        while (segments[index] === 'module' && segments[index + 1]) {
+            index += 2;
+        }
+        if (index === 0) {
+            return undefined;
+        }
+        return segments.slice(0, index).join('.');
+    }
+    resolveKind(address) {
+        if (address === 'root') {
+            return 'root';
+        }
+        const segments = address.split('.');
+        let index = 0;
+        while (segments[index] === 'module' && segments[index + 1]) {
+            index += 2;
+        }
+        const head = segments[index] ?? '';
+        if (head === 'data') {
+            return 'data';
+        }
+        if (head === 'local') {
+            return 'local';
+        }
+        if (head === 'var') {
+            return 'var';
+        }
+        if (head === 'output') {
+            return 'output';
+        }
+        if (head === 'meta') {
+            return 'meta';
+        }
+        if (head.startsWith('provider[') || address.startsWith('provider[')) {
+            return 'provider';
+        }
+        if (address.startsWith('module.') && index >= segments.length) {
+            return 'module';
+        }
+        return segments.length > 1 ? 'resource' : 'terraform';
+    }
+    describeNode(address, kind) {
+        const segments = address.split('.');
+        let index = 0;
+        while (segments[index] === 'module' && segments[index + 1]) {
+            index += 2;
+        }
+        const moduleAddress = index > 0 ? segments.slice(0, index).join('.') : undefined;
+        const tail = segments.slice(index);
+        if (kind === 'resource') {
+            return {
+                kind,
+                address,
+                moduleAddress,
+                ...this.parentModuleHelpers(moduleAddress),
+                resource: tail[0],
+                name: tail[1],
+            };
+        }
+        if (kind === 'data') {
+            return {
+                kind,
+                address,
+                moduleAddress,
+                ...this.parentModuleHelpers(moduleAddress),
+                resource: tail[1],
+                name: tail[2],
+            };
+        }
+        if (kind === 'local' || kind === 'var' || kind === 'output') {
+            return {
+                kind,
+                address,
+                moduleAddress,
+                ...this.parentModuleHelpers(moduleAddress),
+                resource: kind,
+                name: tail[1] ?? tail[0],
+            };
+        }
+        if (kind === 'module') {
+            const moduleSegments = segments.slice(0, index);
+            const parentModuleAddress = moduleSegments.length > 2
+                ? moduleSegments.slice(0, moduleSegments.length - 2).join('.')
+                : undefined;
+            return {
+                kind,
+                address,
+                moduleAddress: parentModuleAddress,
+                ...this.parentModuleHelpers(parentModuleAddress),
+                resource: 'module',
+                name: moduleSegments[moduleSegments.length - 1] ?? address,
+            };
+        }
+        if (kind === 'provider') {
+            return {
+                kind,
+                address,
+                moduleAddress,
+                ...this.parentModuleHelpers(moduleAddress),
+                resource: 'provider',
+                name: tail.join('.') || address,
+            };
+        }
+        if (kind === 'root') {
+            return {
+                kind,
+                address,
+                moduleAddress,
+                ...this.parentModuleHelpers(moduleAddress),
+                resource: 'root',
+                name: 'root',
+            };
+        }
+        if (kind === 'meta') {
+            return {
+                kind,
+                address,
+                moduleAddress,
+                ...this.parentModuleHelpers(moduleAddress),
+                resource: 'meta',
+                name: tail.join('.') || address,
+            };
+        }
+        return {
+            kind,
+            address,
+            moduleAddress,
+            ...this.parentModuleHelpers(moduleAddress),
+            resource: 'terraform',
+            name: address,
+        };
+    }
+    parentModuleHelpers(moduleAddress) {
+        if (!moduleAddress) {
+            return {};
+        }
+        const parts = moduleAddress.split('.');
+        return {
+            parentModuleName: parts[parts.length - 1] ?? moduleAddress,
+            parentModuleNodeId: tgNodeIdFrom('module', moduleAddress),
+        };
+    }
+}

package/dist/esm/Graph/Importers/TerraformDotImporter.test.d.ts

@@ -0,0 +1 @@
+export {};