parse-hcl 0.1.0

package/dist/utils/graph/graphBuilder.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Dependency graph builder for Terraform documents.
+ * Creates a directed graph of dependencies between Terraform elements.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDependencyGraph = buildDependencyGraph;
+exports.createExport = createExport;
+/** Current graph export version */
+const GRAPH_VERSION = '1.0.0';
+/**
+ * Builds a dependency graph from a parsed Terraform document.
+ * Analyzes all blocks and their references to construct nodes and edges.
+ *
+ * @param document - The parsed Terraform document
+ * @returns A complete dependency graph with nodes, edges, and orphan references
+ *
+ * @example
+ * ```typescript
+ * const parser = new TerraformParser();
+ * const doc = parser.parseFile('main.tf');
+ * const graph = buildDependencyGraph(doc);
+ *
+ * // Visualize dependencies
+ * for (const edge of graph.edges) {
+ *   console.log(`${edge.from} -> ${edge.to}`);
+ * }
+ * ```
+ */
+function buildDependencyGraph(document) {
+    const nodes = new Map();
+    const edges = [];
+    const orphanReferences = [];
+    const edgeKeys = new Set();
+    // First pass: populate all declared nodes
+    populateNodes(document, nodes);
+    /**
+     * Adds edges from a source node to all referenced targets.
+     */
+    const addEdges = (fromNode, refs, source) => {
+        if (!fromNode || refs.length === 0) {
+            return;
+        }
+        for (const ref of refs) {
+            const target = ensureTargetNode(ref, nodes);
+            if (!target) {
+                orphanReferences.push(ref);
+                continue;
+            }
+            // Deduplicate edges
+            const key = `${fromNode.id}->${target.id}:${JSON.stringify(ref)}`;
+            if (edgeKeys.has(key)) {
+                continue;
+            }
+            edgeKeys.add(key);
+            edges.push({
+                from: fromNode.id,
+                to: target.id,
+                reference: ref,
+                source
+            });
+        }
+    };
+    // Process terraform settings
+    for (const block of document.terraform) {
+        const node = nodes.get(nodeId('terraform', 'settings'));
+        addEdges(node, referencesFromAttributes(block.properties), block.source);
+    }
+    // Process providers
+    for (const provider of document.provider) {
+        const node = nodes.get(nodeId('provider', provider.name, provider.alias));
+        addEdges(node, referencesFromAttributes(provider.properties), provider.source);
+    }
+    // Process variables (references in default values)
+    for (const variable of document.variable) {
+        const node = nodes.get(nodeId('variable', variable.name));
+        addEdges(node, referencesFromValue(variable.default), variable.source);
+    }
+    // Process outputs
+    for (const output of document.output) {
+        const node = nodes.get(nodeId('output', output.name));
+        addEdges(node, referencesFromValue(output.value), output.source);
+    }
+    // Process modules
+    for (const module of document.module) {
+        const node = nodes.get(nodeId('module', module.name));
+        addEdges(node, referencesFromAttributes(module.properties), module.source);
+    }
+    // Process resources
+    for (const resource of document.resource) {
+        const node = nodes.get(nodeId('resource', resource.type, resource.name));
+        addEdges(node, referencesFromAttributes(resource.properties), resource.source);
+        addEdges(node, referencesFromAttributes(resource.meta), resource.source);
+        // Process dynamic blocks
+        for (const dyn of resource.dynamic_blocks) {
+            addEdges(node, referencesFromValue(dyn.for_each), resource.source);
+            addEdges(node, referencesFromAttributes(dyn.content), resource.source);
+        }
+        // Process nested blocks
+        addEdges(node, referencesFromNestedBlocks(resource.blocks), resource.source);
+    }
+    // Process data sources
+    for (const data of document.data) {
+        const node = nodes.get(nodeId('data', data.dataType, data.name));
+        addEdges(node, referencesFromAttributes(data.properties), data.source);
+        addEdges(node, referencesFromNestedBlocks(data.blocks), data.source);
+    }
+    // Process locals
+    for (const local of document.locals) {
+        const node = nodes.get(nodeId('locals', local.name));
+        addEdges(node, referencesFromValue(local.value), local.source);
+    }
+    // Process other blocks (moved/import/check/terraform_data/unknown)
+    const otherBlocks = [
+        ...document.moved,
+        ...document.import,
+        ...document.check,
+        ...document.terraform_data,
+        ...document.unknown
+    ];
+    for (const block of otherBlocks) {
+        // These blocks don't have nodes, but we track their references
+        const allRefs = [
+            ...referencesFromAttributes(block.properties),
+            ...referencesFromNestedBlocks(block.blocks)
+        ];
+        // Add edges from the block type as a pseudo-node
+        const blockNode = nodes.get(nodeId(block.type, block.labels[0] || 'default'));
+        if (!blockNode) {
+            // Create a node for this block
+            const newNode = {
+                id: nodeId(block.type, block.labels[0] || 'default'),
+                kind: block.type,
+                name: block.labels[0] || 'default',
+                source: block.source
+            };
+            nodes.set(newNode.id, newNode);
+            addEdges(newNode, allRefs, block.source);
+        }
+        else {
+            addEdges(blockNode, allRefs, block.source);
+        }
+    }
+    return {
+        nodes: Array.from(nodes.values()),
+        edges,
+        orphanReferences
+    };
+}
+/**
+ * Creates a complete export containing the document and its dependency graph.
+ *
+ * @param document - The parsed Terraform document
+ * @returns TerraformExport with version, document, and graph
+ */
+function createExport(document) {
+    return {
+        version: GRAPH_VERSION,
+        document,
+        graph: buildDependencyGraph(document)
+    };
+}
+/**
+ * Populates the node map with all declared elements from the document.
+ */
+function populateNodes(document, nodes) {
+    const addNode = (node) => {
+        if (!nodes.has(node.id)) {
+            nodes.set(node.id, node);
+        }
+    };
+    // Always add terraform settings node
+    addNode({
+        id: nodeId('terraform', 'settings'),
+        kind: 'terraform',
+        name: 'settings'
+    });
+    // Add provider nodes
+    for (const provider of document.provider) {
+        addNode({
+            id: nodeId('provider', provider.name, provider.alias),
+            kind: 'provider',
+            name: provider.alias || provider.name,
+            type: provider.name,
+            source: provider.source
+        });
+    }
+    // Add variable nodes
+    for (const variable of document.variable) {
+        addNode({
+            id: nodeId('variable', variable.name),
+            kind: 'variable',
+            name: variable.name,
+            source: variable.source
+        });
+    }
+    // Add output nodes
+    for (const output of document.output) {
+        addNode({
+            id: nodeId('output', output.name),
+            kind: 'output',
+            name: output.name,
+            source: output.source
+        });
+    }
+    // Add module nodes
+    for (const module of document.module) {
+        addNode({
+            id: nodeId('module', module.name),
+            kind: 'module',
+            name: module.name,
+            source: module.source
+        });
+    }
+    // Add resource nodes
+    for (const resource of document.resource) {
+        addNode({
+            id: nodeId('resource', resource.type, resource.name),
+            kind: 'resource',
+            name: resource.name,
+            type: resource.type,
+            source: resource.source
+        });
+    }
+    // Add data source nodes
+    for (const data of document.data) {
+        addNode({
+            id: nodeId('data', data.dataType, data.name),
+            kind: 'data',
+            name: data.name,
+            type: data.dataType,
+            source: data.source
+        });
+    }
+    // Add local value nodes
+    for (const local of document.locals) {
+        addNode({
+            id: nodeId('locals', local.name),
+            kind: 'locals',
+            name: local.name,
+            source: local.source
+        });
+    }
+}
+/**
+ * Extracts all references from a record of attributes.
+ */
+function referencesFromAttributes(attributes) {
+    if (!attributes) {
+        return [];
+    }
+    return Object.values(attributes).flatMap((value) => referencesFromValue(value));
+}
+/**
+ * Recursively extracts references from nested blocks.
+ */
+function referencesFromNestedBlocks(blocks) {
+    const refs = [];
+    for (const block of blocks) {
+        refs.push(...referencesFromAttributes(block.attributes));
+        refs.push(...referencesFromNestedBlocks(block.blocks));
+    }
+    return refs;
+}
+/**
+ * Extracts all references from a value (recursively for arrays and objects).
+ */
+function referencesFromValue(value) {
+    if (!value) {
+        return [];
+    }
+    const direct = value.references ?? [];
+    if (value.type === 'object' && value.value) {
+        return [...direct, ...referencesFromAttributes(value.value)];
+    }
+    if (value.type === 'array' && Array.isArray(value.value)) {
+        return [
+            ...direct,
+            ...value.value.flatMap((item) => referencesFromValue(item))
+        ];
+    }
+    return direct;
+}
+/**
+ * Creates a node ID from kind and name components.
+ */
+function nodeId(kind, primary, secondary) {
+    return [kind, primary, secondary].filter(Boolean).join('.');
+}
+/**
+ * Ensures a target node exists for a reference, creating a placeholder if needed.
+ */
+function ensureTargetNode(ref, nodes) {
+    const existing = nodes.get(referenceToId(ref));
+    if (existing) {
+        return existing;
+    }
+    const placeholder = referenceToNode(ref);
+    if (!placeholder) {
+        return undefined;
+    }
+    nodes.set(placeholder.id, placeholder);
+    return placeholder;
+}
+/**
+ * Converts a reference to its corresponding node ID.
+ */
+function referenceToId(ref) {
+    switch (ref.kind) {
+        case 'variable':
+            return nodeId('variable', ref.name);
+        case 'local':
+            return nodeId('locals', ref.name);
+        case 'module_output':
+            return nodeId('module_output', ref.module, ref.name);
+        case 'data':
+            return nodeId('data', ref.data_type, ref.name);
+        case 'resource':
+            return nodeId('resource', ref.resource_type, ref.name);
+        case 'path':
+            return nodeId('path', ref.name);
+        case 'each':
+            return nodeId('each', ref.property);
+        case 'count':
+            return nodeId('count', ref.property);
+        case 'self':
+            return nodeId('self', ref.attribute);
+        default:
+            return '';
+    }
+}
+/**
+ * Converts a reference to a placeholder node.
+ */
+function referenceToNode(ref) {
+    switch (ref.kind) {
+        case 'variable':
+            return { id: referenceToId(ref), kind: 'variable', name: ref.name };
+        case 'local':
+            return { id: referenceToId(ref), kind: 'locals', name: ref.name };
+        case 'module_output':
+            return {
+                id: referenceToId(ref),
+                kind: 'module_output',
+                name: ref.name,
+                type: ref.module
+            };
+        case 'data':
+            return {
+                id: referenceToId(ref),
+                kind: 'data',
+                name: ref.name,
+                type: ref.data_type
+            };
+        case 'resource':
+            return {
+                id: referenceToId(ref),
+                kind: 'resource',
+                name: ref.name,
+                type: ref.resource_type
+            };
+        case 'path':
+            return { id: referenceToId(ref), kind: 'path', name: ref.name };
+        case 'each':
+            return { id: referenceToId(ref), kind: 'each', name: ref.property };
+        case 'count':
+            return { id: referenceToId(ref), kind: 'count', name: ref.property };
+        case 'self':
+            return { id: referenceToId(ref), kind: 'self', name: ref.attribute };
+        default:
+            return { id: `external.${JSON.stringify(ref)}`, kind: 'external', name: 'external' };
+    }
+}

package/dist/utils/lexer/blockScanner.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Scanner for identifying top-level HCL blocks in Terraform configuration files.
+ * Handles block detection, label extraction, and body isolation.
+ */
+import { HclBlock } from '../../types/blocks';
+/**
+ * Options for block scanning.
+ */
+export interface ScanOptions {
+    /** Whether to throw ParseError on syntax errors (default: false, logs warning instead) */
+    strict?: boolean;
+}
+/**
+ * Scanner for extracting top-level HCL blocks from Terraform files.
+ *
+ * @example
+ * ```typescript
+ * const scanner = new BlockScanner();
+ * const blocks = scanner.scan(hclContent, 'main.tf');
+ * for (const block of blocks) {
+ *   console.log(`Found ${block.kind} block: ${block.labels.join('.')}`);
+ * }
+ * ```
+ */
+export declare class BlockScanner {
+    /**
+     * Scans HCL content and extracts all top-level blocks.
+     *
+     * @param content - The HCL source content to scan
+     * @param source - The source file path (for error reporting)
+     * @param options - Scanning options
+     * @returns Array of parsed HCL blocks
+     * @throws {ParseError} If strict mode is enabled and syntax errors are found
+     */
+    scan(content: string, source: string, options?: ScanOptions): HclBlock[];
+}

package/dist/utils/lexer/blockScanner.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Scanner for identifying top-level HCL blocks in Terraform configuration files.
+ * Handles block detection, label extraction, and body isolation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockScanner = void 0;
+const errors_1 = require("../common/errors");
+const hclLexer_1 = require("./hclLexer");
+const logger_1 = require("../common/logger");
+/**
+ * Set of known Terraform block types.
+ * Unknown block types are categorized as 'unknown'.
+ */
+const KNOWN_BLOCKS = new Set([
+    'terraform',
+    'locals',
+    'provider',
+    'variable',
+    'output',
+    'module',
+    'resource',
+    'data',
+    'moved',
+    'import',
+    'check',
+    'terraform_data'
+]);
+/**
+ * Scanner for extracting top-level HCL blocks from Terraform files.
+ *
+ * @example
+ * ```typescript
+ * const scanner = new BlockScanner();
+ * const blocks = scanner.scan(hclContent, 'main.tf');
+ * for (const block of blocks) {
+ *   console.log(`Found ${block.kind} block: ${block.labels.join('.')}`);
+ * }
+ * ```
+ */
+class BlockScanner {
+    /**
+     * Scans HCL content and extracts all top-level blocks.
+     *
+     * @param content - The HCL source content to scan
+     * @param source - The source file path (for error reporting)
+     * @param options - Scanning options
+     * @returns Array of parsed HCL blocks
+     * @throws {ParseError} If strict mode is enabled and syntax errors are found
+     */
+    scan(content, source, options) {
+        const blocks = [];
+        const length = content.length;
+        let index = 0;
+        const strict = options?.strict ?? false;
+        while (index < length) {
+            index = (0, hclLexer_1.skipWhitespaceAndComments)(content, index);
+            // Skip standalone strings (not part of block headers)
+            if ((0, hclLexer_1.isQuote)(content[index])) {
+                index = (0, hclLexer_1.skipString)(content, index);
+                continue;
+            }
+            const identifierStart = index;
+            const keyword = (0, hclLexer_1.readIdentifier)(content, index);
+            if (!keyword) {
+                index++;
+                continue;
+            }
+            index += keyword.length;
+            index = (0, hclLexer_1.skipWhitespaceAndComments)(content, index);
+            // Read block labels (quoted strings)
+            const labels = [];
+            while ((0, hclLexer_1.isQuote)(content[index])) {
+                const { text, end } = (0, hclLexer_1.readQuotedString)(content, index);
+                labels.push(text);
+                index = (0, hclLexer_1.skipWhitespaceAndComments)(content, end);
+            }
+            // Check for opening brace
+            if (content[index] !== '{') {
+                // Not a block header, continue searching
+                index = identifierStart + keyword.length;
+                continue;
+            }
+            const braceIndex = index;
+            const endIndex = (0, hclLexer_1.findMatchingBrace)(content, braceIndex);
+            if (endIndex === -1) {
+                const location = (0, errors_1.offsetToLocation)(content, braceIndex);
+                const message = `Unclosed block '${keyword}': missing closing '}'`;
+                if (strict) {
+                    throw new errors_1.ParseError(message, source, location);
+                }
+                logger_1.logger.warn(`${message} in ${source}:${location.line}:${location.column}`);
+                break;
+            }
+            const raw = normalizeRaw(content.slice(identifierStart, endIndex + 1));
+            const body = content.slice(braceIndex + 1, endIndex);
+            const kind = (KNOWN_BLOCKS.has(keyword) ? keyword : 'unknown');
+            blocks.push({
+                kind,
+                keyword,
+                labels,
+                body: body.trim(),
+                raw,
+                source
+            });
+            index = endIndex + 1;
+        }
+        return blocks;
+    }
+}
+exports.BlockScanner = BlockScanner;
+/**
+ * Normalizes raw block content for consistent formatting.
+ * - Removes common leading indentation
+ * - Normalizes whitespace around '=' operators
+ * - Trims trailing whitespace from lines
+ *
+ * @param raw - The raw block content
+ * @returns Normalized block content
+ */
+function normalizeRaw(raw) {
+    const trimmed = raw.trim();
+    const lines = trimmed.split(/\r?\n/);
+    if (lines.length === 1) {
+        return lines[0];
+    }
+    // Calculate minimum indentation (excluding first line and empty lines)
+    const indents = lines
+        .slice(1)
+        .filter((line) => line.trim().length > 0)
+        .map((line) => (line.match(/^(\s*)/)?.[1].length ?? 0));
+    const minIndent = indents.length ? Math.min(...indents) : 0;
+    // Normalize alignment around '=' operators
+    const normalizeAlignment = (line) => line
+        .replace(/\s{2,}=\s*/g, ' = ')
+        .replace(/\s*=\s{2,}/g, ' = ')
+        .trimEnd();
+    const normalized = lines.map((line, index) => {
+        const withoutIndent = index === 0 ? line.trimStart() : line.slice(Math.min(minIndent, line.length));
+        return normalizeAlignment(withoutIndent);
+    });
+    return normalized.join('\n');
+}

package/dist/utils/lexer/hclLexer.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared lexer utilities for HCL parsing.
+ * Provides common functions for tokenization and string handling.
+ */
+/**
+ * Result of reading a quoted string from source.
+ */
+export interface QuotedStringResult {
+    /** The unquoted string content */
+    text: string;
+    /** The index after the closing quote */
+    end: number;
+}
+/**
+ * Result of reading a raw value from source.
+ */
+export interface ValueReadResult {
+    /** The raw value text (trimmed) */
+    raw: string;
+    /** The index after the value */
+    end: number;
+}
+/**
+ * Checks if a character is a quote character (single or double).
+ * @param char - The character to check
+ * @returns True if the character is a quote
+ */
+export declare function isQuote(char: string | undefined): boolean;
+/**
+ * Checks if a character at a given position is escaped by counting preceding backslashes.
+ * Handles consecutive backslashes correctly (e.g., \\\\ is two escaped backslashes).
+ * @param text - The source text
+ * @param index - The index of the character to check
+ * @returns True if the character is escaped
+ */
+export declare function isEscaped(text: string, index: number): boolean;
+/**
+ * Skips whitespace and comments (line and block comments).
+ * Handles "//", block comments, and "#" style comments.
+ * @param text - The source text
+ * @param start - The starting index
+ * @returns The index of the next non-whitespace, non-comment character
+ */
+export declare function skipWhitespaceAndComments(text: string, start: number): number;
+/**
+ * Skips a quoted string, handling escape sequences correctly.
+ * @param text - The source text
+ * @param start - The index of the opening quote
+ * @returns The index after the closing quote
+ */
+export declare function skipString(text: string, start: number): number;
+/**
+ * Skips a heredoc string (<<EOF or <<-EOF style).
+ * @param text - The source text
+ * @param start - The index of the first '<'
+ * @returns The index after the heredoc terminator
+ */
+export declare function skipHeredoc(text: string, start: number): number;
+/**
+ * Finds the matching closing brace for an opening brace.
+ * Handles nested braces, strings, comments, and heredocs.
+ * @param content - The source text
+ * @param startIndex - The index of the opening brace
+ * @returns The index of the matching closing brace, or -1 if not found
+ */
+export declare function findMatchingBrace(content: string, startIndex: number): number;
+/**
+ * Finds the matching closing bracket for an opening bracket.
+ * Handles nested brackets of all types [], {}, ().
+ * @param content - The source text
+ * @param startIndex - The index of the opening bracket
+ * @param openChar - The opening bracket character
+ * @param closeChar - The closing bracket character
+ * @returns The index of the matching closing bracket, or -1 if not found
+ */
+export declare function findMatchingBracket(content: string, startIndex: number, openChar: string, closeChar: string): number;
+/**
+ * Reads an identifier from the source text.
+ * Identifiers start with a letter or underscore, followed by letters, digits, underscores, or hyphens.
+ * @param text - The source text
+ * @param start - The starting index
+ * @returns The identifier string, or empty string if no identifier found
+ */
+export declare function readIdentifier(text: string, start: number): string;
+/**
+ * Reads an identifier that may contain dots (for attribute access).
+ * @param text - The source text
+ * @param start - The starting index
+ * @returns The identifier string, or empty string if no identifier found
+ */
+export declare function readDottedIdentifier(text: string, start: number): string;
+/**
+ * Reads a quoted string and returns its unescaped content.
+ * @param text - The source text
+ * @param start - The index of the opening quote
+ * @returns The unquoted string and the index after the closing quote
+ */
+export declare function readQuotedString(text: string, start: number): QuotedStringResult;
+/**
+ * Reads a value from HCL source (handles multiline values in brackets).
+ * @param text - The source text
+ * @param start - The starting index (after the '=' sign)
+ * @returns The raw value text and the index after the value
+ */
+export declare function readValue(text: string, start: number): ValueReadResult;
+/**
+ * Splits an array literal into its elements.
+ * Handles nested arrays, objects, and strings correctly.
+ * @param raw - The raw array string including brackets
+ * @returns Array of raw element strings
+ */
+export declare function splitArrayElements(raw: string): string[];
+/**
+ * Splits an object literal into key-value pairs.
+ * Handles nested objects, arrays, and strings correctly.
+ * @param raw - The raw object string including braces
+ * @returns Array of [key, value] tuples
+ */
+export declare function splitObjectEntries(raw: string): Array<[string, string]>;