parse-hcl 0.1.0

package/dist/utils/parser/valueClassifier.js

@@ -0,0 +1,434 @@
+"use strict";
+/**
+ * Value classifier for HCL expressions.
+ * Classifies raw value strings into typed Value structures and extracts references.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyValue = classifyValue;
+const hclLexer_1 = require("../lexer/hclLexer");
+/**
+ * Pattern for matching traversal expressions (e.g., aws_instance.web.id).
+ * Handles indexed access like resource[0].attr and splat expressions like resource[*].attr.
+ */
+const TRAVERSAL_PATTERN = /[A-Za-z_][\w-]*(?:\[(?:[^[\]]*|\*)])?(?:\.[A-Za-z_][\w-]*(?:\[(?:[^[\]]*|\*)])?)+/g;
+/**
+ * Pattern for matching splat expressions (e.g., aws_instance.web[*].id).
+ */
+const SPLAT_PATTERN = /\[\*]/g;
+/**
+ * Classifies a raw HCL value string into a typed Value structure.
+ * Supports literals, quoted strings, arrays, objects, and expressions.
+ *
+ * @param raw - The raw value string to classify
+ * @returns The classified Value with type information and extracted references
+ *
+ * @example
+ * ```typescript
+ * classifyValue('true')           // LiteralValue { type: 'literal', value: true }
+ * classifyValue('"hello"')        // LiteralValue { type: 'literal', value: 'hello' }
+ * classifyValue('var.region')     // ExpressionValue with variable reference
+ * classifyValue('[1, 2, 3]')      // ArrayValue with parsed elements
+ * ```
+ */
+function classifyValue(raw) {
+    const trimmed = raw.trim();
+    // Try literal classification first (booleans, numbers, null)
+    const literal = classifyLiteral(trimmed);
+    if (literal) {
+        return literal;
+    }
+    // Handle quoted strings
+    if (isQuotedString(trimmed)) {
+        const inner = unquote(trimmed);
+        if (inner.includes('${')) {
+            return classifyExpression(inner, 'template');
+        }
+        return {
+            type: 'literal',
+            value: inner,
+            raw: trimmed
+        };
+    }
+    // Handle heredocs
+    if (trimmed.startsWith('<<')) {
+        return classifyExpression(trimmed, 'template');
+    }
+    // Handle arrays with recursive parsing
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        return classifyArray(trimmed);
+    }
+    // Handle objects with recursive parsing
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+        return classifyObject(trimmed);
+    }
+    // Everything else is an expression
+    return classifyExpression(trimmed);
+}
+/**
+ * Classifies a raw value as a literal (boolean, number, or null).
+ * @param raw - The trimmed raw value
+ * @returns LiteralValue if it's a literal, null otherwise
+ */
+function classifyLiteral(raw) {
+    // Boolean literals
+    if (raw === 'true' || raw === 'false') {
+        return {
+            type: 'literal',
+            value: raw === 'true',
+            raw
+        };
+    }
+    // Numeric literals (integer and float)
+    if (/^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(raw)) {
+        return {
+            type: 'literal',
+            value: Number(raw),
+            raw
+        };
+    }
+    // Null literal
+    if (raw === 'null') {
+        return {
+            type: 'literal',
+            value: null,
+            raw
+        };
+    }
+    return null;
+}
+/**
+ * Classifies and parses an array value with recursive element parsing.
+ * @param raw - The raw array string including brackets
+ * @returns ArrayValue with parsed elements and extracted references
+ */
+function classifyArray(raw) {
+    const elements = (0, hclLexer_1.splitArrayElements)(raw);
+    const parsedElements = elements.map((elem) => classifyValue(elem));
+    const references = collectReferences(parsedElements);
+    return {
+        type: 'array',
+        value: parsedElements.length > 0 ? parsedElements : undefined,
+        raw,
+        references: references.length > 0 ? references : undefined
+    };
+}
+/**
+ * Classifies and parses an object value with recursive entry parsing.
+ * @param raw - The raw object string including braces
+ * @returns ObjectValue with parsed entries and extracted references
+ */
+function classifyObject(raw) {
+    const entries = (0, hclLexer_1.splitObjectEntries)(raw);
+    const parsedEntries = {};
+    for (const [key, value] of entries) {
+        parsedEntries[key] = classifyValue(value);
+    }
+    const references = collectReferences(Object.values(parsedEntries));
+    return {
+        type: 'object',
+        value: Object.keys(parsedEntries).length > 0 ? parsedEntries : undefined,
+        raw,
+        references: references.length > 0 ? references : undefined
+    };
+}
+/**
+ * Collects all references from an array of values.
+ * @param values - Array of Value objects
+ * @returns Deduplicated array of references
+ */
+function collectReferences(values) {
+    const refs = [];
+    for (const value of values) {
+        if (value.type === 'expression' || value.type === 'array' || value.type === 'object') {
+            if (value.references) {
+                refs.push(...value.references);
+            }
+        }
+        // Recursively collect from nested structures
+        if (value.type === 'array' && value.value) {
+            refs.push(...collectReferences(value.value));
+        }
+        if (value.type === 'object' && value.value) {
+            refs.push(...collectReferences(Object.values(value.value)));
+        }
+    }
+    return uniqueReferences(refs);
+}
+/**
+ * Classifies an expression and extracts its references.
+ * @param raw - The raw expression string
+ * @param forcedKind - Optional forced expression kind
+ * @returns ExpressionValue with kind and references
+ */
+function classifyExpression(raw, forcedKind) {
+    const kind = forcedKind || detectExpressionKind(raw);
+    const references = extractExpressionReferences(raw, kind);
+    return {
+        type: 'expression',
+        kind,
+        raw,
+        references: references.length > 0 ? references : undefined
+    };
+}
+/**
+ * Detects the kind of an expression based on its syntax.
+ * @param raw - The raw expression string
+ * @returns The detected ExpressionKind
+ */
+function detectExpressionKind(raw) {
+    // Template interpolation
+    if (raw.includes('${')) {
+        return 'template';
+    }
+    // Conditional (ternary) expression
+    if (hasConditionalOperator(raw)) {
+        return 'conditional';
+    }
+    // Function call
+    if (/^[\w.-]+\(/.test(raw)) {
+        return 'function_call';
+    }
+    // For expression (list or map comprehension)
+    if (/^\[\s*for\s+.+\s+in\s+.+:\s+/.test(raw) || /^\{\s*for\s+.+\s+in\s+.+:\s+/.test(raw)) {
+        return 'for_expr';
+    }
+    // Splat expression
+    if (SPLAT_PATTERN.test(raw)) {
+        return 'splat';
+    }
+    // Simple traversal (e.g., var.name, local.value)
+    if (/^[\w.-]+(\[[^\]]*])?$/.test(raw)) {
+        return 'traversal';
+    }
+    return 'unknown';
+}
+/**
+ * Checks if an expression contains a conditional (ternary) operator.
+ * Handles nested expressions and strings correctly.
+ * @param raw - The raw expression string
+ * @returns True if the expression is a conditional
+ */
+function hasConditionalOperator(raw) {
+    let depth = 0;
+    let inString = false;
+    let stringChar = null;
+    let questionMarkFound = false;
+    let questionMarkDepth = -1;
+    for (let i = 0; i < raw.length; i++) {
+        const char = raw[i];
+        if (!inString) {
+            if (char === '"' || char === "'") {
+                inString = true;
+                stringChar = char;
+                continue;
+            }
+            if (char === '(' || char === '[' || char === '{') {
+                depth++;
+                continue;
+            }
+            if (char === ')' || char === ']' || char === '}') {
+                depth--;
+                continue;
+            }
+            // Look for ? at depth 0
+            if (char === '?' && depth === 0) {
+                questionMarkFound = true;
+                questionMarkDepth = depth;
+                continue;
+            }
+            // Look for : after ? at the same depth
+            if (char === ':' && questionMarkFound && depth === questionMarkDepth) {
+                return true;
+            }
+        }
+        else {
+            if (char === stringChar && !(0, hclLexer_1.isEscaped)(raw, i)) {
+                inString = false;
+                stringChar = null;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Extracts references from an expression.
+ * @param raw - The raw expression string
+ * @param kind - The expression kind
+ * @returns Array of extracted references
+ */
+function extractExpressionReferences(raw, kind) {
+    const baseRefs = extractReferencesFromText(raw);
+    // For templates, also extract from interpolated expressions
+    if (kind === 'template') {
+        const interpolationMatches = raw.match(/\${([^}]+)}/g) || [];
+        const innerRefs = interpolationMatches.flatMap((expr) => extractReferencesFromText(expr.replace(/^\${|}$/g, '')));
+        return uniqueReferences([...baseRefs, ...innerRefs]);
+    }
+    return baseRefs;
+}
+/**
+ * Extracts all references from a text string.
+ * Supports: var.*, local.*, module.*, data.*, resource references,
+ * path.*, each.*, count.*, self.*
+ *
+ * @param raw - The raw text to extract references from
+ * @returns Array of extracted references
+ */
+function extractReferencesFromText(raw) {
+    const refs = [];
+    // Extract special references first (each, count, self)
+    const specialRefs = extractSpecialReferences(raw);
+    refs.push(...specialRefs);
+    // Extract traversal-based references
+    const matches = raw.match(TRAVERSAL_PATTERN) || [];
+    for (const match of matches) {
+        // Remove index notation for parsing, but track if it has splat
+        const hasSplat = match.includes('[*]');
+        const parts = match.split('.').map((part) => part.replace(/\[.*?]/g, ''));
+        // var.name
+        if (parts[0] === 'var' && parts[1]) {
+            refs.push({ kind: 'variable', name: parts[1] });
+            continue;
+        }
+        // local.name
+        if (parts[0] === 'local' && parts[1]) {
+            refs.push({ kind: 'local', name: parts[1] });
+            continue;
+        }
+        // module.name.output
+        if (parts[0] === 'module' && parts[1]) {
+            const attribute = parts.slice(2).join('.') || parts[1];
+            refs.push({ kind: 'module_output', module: parts[1], name: attribute });
+            continue;
+        }
+        // data.type.name
+        if (parts[0] === 'data' && parts[1] && parts[2]) {
+            const attribute = parts.slice(3).join('.') || undefined;
+            refs.push({
+                kind: 'data',
+                data_type: parts[1],
+                name: parts[2],
+                attribute,
+                splat: hasSplat || undefined
+            });
+            continue;
+        }
+        // path.module, path.root, path.cwd
+        if (parts[0] === 'path' && parts[1]) {
+            refs.push({ kind: 'path', name: parts[1] });
+            continue;
+        }
+        // Skip special references (handled separately)
+        if (parts[0] === 'each' || parts[0] === 'count' || parts[0] === 'self') {
+            continue;
+        }
+        // resource.type.name (e.g., aws_instance.web.id)
+        if (parts.length >= 2) {
+            const [resourceType, resourceName, ...rest] = parts;
+            const attribute = rest.length ? rest.join('.') : undefined;
+            refs.push({
+                kind: 'resource',
+                resource_type: resourceType,
+                name: resourceName,
+                attribute,
+                splat: hasSplat || undefined
+            });
+        }
+    }
+    return uniqueReferences(refs);
+}
+/**
+ * Extracts special references: each.key, each.value, count.index, self.*
+ * @param raw - The raw text to extract from
+ * @returns Array of special references
+ */
+function extractSpecialReferences(raw) {
+    const refs = [];
+    // each.key and each.value
+    const eachMatches = raw.match(/\beach\.(key|value)\b/g) || [];
+    for (const match of eachMatches) {
+        const property = match.split('.')[1];
+        refs.push({ kind: 'each', property });
+    }
+    // count.index
+    if (/\bcount\.index\b/.test(raw)) {
+        refs.push({ kind: 'count', property: 'index' });
+    }
+    // self.* (in provisioners)
+    const selfMatches = raw.match(/\bself\.[\w-]+/g) || [];
+    for (const match of selfMatches) {
+        const attribute = match.split('.')[1];
+        refs.push({ kind: 'self', attribute });
+    }
+    return refs;
+}
+/**
+ * Removes duplicate references based on their JSON representation.
+ * @param refs - Array of references (may contain duplicates)
+ * @returns Deduplicated array of references
+ */
+function uniqueReferences(refs) {
+    const seen = new Set();
+    return refs.filter((ref) => {
+        const key = JSON.stringify(ref);
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Checks if a value is a quoted string (single or double quotes).
+ * @param value - The value to check
+ * @returns True if the value is a quoted string
+ */
+function isQuotedString(value) {
+    return (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"));
+}
+/**
+ * Removes quotes from a quoted string and handles escape sequences.
+ * @param value - The quoted string
+ * @returns The unquoted string with escape sequences processed
+ */
+function unquote(value) {
+    const quote = value[0];
+    const inner = value.slice(1, -1);
+    // Process escape sequences
+    let result = '';
+    let i = 0;
+    while (i < inner.length) {
+        if (inner[i] === '\\' && i + 1 < inner.length) {
+            const next = inner[i + 1];
+            switch (next) {
+                case 'n':
+                    result += '\n';
+                    i += 2;
+                    continue;
+                case 't':
+                    result += '\t';
+                    i += 2;
+                    continue;
+                case 'r':
+                    result += '\r';
+                    i += 2;
+                    continue;
+                case '\\':
+                    result += '\\';
+                    i += 2;
+                    continue;
+                case quote:
+                    result += quote;
+                    i += 2;
+                    continue;
+                default:
+                    result += inner[i];
+                    i++;
+                    continue;
+            }
+        }
+        result += inner[i];
+        i++;
+    }
+    return result;
+}

package/dist/utils/serialization/serializer.d.ts

@@ -0,0 +1,9 @@
+import { TerraformDocument } from '../../types/blocks';
+import { TerraformExport } from '../../types/artifacts';
+export interface SerializeOptions {
+    pruneEmpty?: boolean;
+}
+export declare function toJson(document: TerraformDocument | unknown, options?: SerializeOptions): string;
+export declare function toJsonExport(document: TerraformDocument, options?: SerializeOptions): string;
+export declare function toExport(document: TerraformDocument, options?: SerializeOptions): TerraformExport;
+export declare function toYamlDocument(document: TerraformDocument | unknown, options?: SerializeOptions): string;

package/dist/utils/serialization/serializer.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJson = toJson;
+exports.toJsonExport = toJsonExport;
+exports.toExport = toExport;
+exports.toYamlDocument = toYamlDocument;
+const graphBuilder_1 = require("../graph/graphBuilder");
+const yaml_1 = require("./yaml");
+function toJson(document, options) {
+    const value = shouldPrune(options) && isTerraformDocument(document) ? pruneDocument(document) : document;
+    return JSON.stringify(value, null, 2);
+}
+function toJsonExport(document, options) {
+    return JSON.stringify(toExport(document, options), null, 2);
+}
+function toExport(document, options) {
+    const exportPayload = (0, graphBuilder_1.createExport)(document);
+    const prunedDocument = shouldPrune(options) ? pruneDocument(document) : document;
+    return { ...exportPayload, document: prunedDocument };
+}
+function toYamlDocument(document, options) {
+    const value = shouldPrune(options) && isTerraformDocument(document) ? pruneDocument(document) : document;
+    return (0, yaml_1.toYaml)(value);
+}
+function shouldPrune(options) {
+    return options?.pruneEmpty !== false;
+}
+function pruneDocument(document) {
+    return pruneValue(document) ?? {};
+}
+function pruneValue(value) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        const items = value
+            .map((item) => pruneValue(item))
+            .filter((item) => item !== undefined);
+        return items.length > 0 ? items : undefined;
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value);
+        const pruned = {};
+        for (const [key, val] of entries) {
+            const next = pruneValue(val);
+            if (next === undefined) {
+                continue;
+            }
+            if (Array.isArray(next) && next.length === 0) {
+                continue;
+            }
+            if (typeof next === 'object' && next !== null && Object.keys(next).length === 0) {
+                continue;
+            }
+            pruned[key] = next;
+        }
+        return Object.keys(pruned).length > 0 ? pruned : undefined;
+    }
+    return value;
+}
+function isTerraformDocument(doc) {
+    return Boolean(doc && typeof doc === 'object' && 'resource' in doc);
+}

package/dist/utils/serialization/yaml.d.ts

@@ -0,0 +1 @@
+export declare function toYaml(value: unknown): string;

package/dist/utils/serialization/yaml.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toYaml = toYaml;
+const PAD = '  ';
+function toYaml(value) {
+    return render(value, 0);
+}
+function render(value, level) {
+    if (isScalar(value)) {
+        return formatScalar(value);
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return `${indent(level)}[]`;
+        }
+        return value
+            .map((item) => {
+            if (isScalar(item)) {
+                return `${indent(level)}- ${formatScalar(item)}`;
+            }
+            const rendered = render(item, level + 1);
+            const lines = rendered.split('\n');
+            const first = lines[0].startsWith(indent(level + 1))
+                ? lines[0].slice(indent(level + 1).length)
+                : lines[0];
+            const head = `${indent(level)}- ${first}`;
+            const tail = lines.length > 1
+                ? lines
+                    .slice(1)
+                    .map((line) => line)
+                    .join('\n')
+                : '';
+            return tail ? `${head}\n${tail}` : head;
+        })
+            .join('\n');
+    }
+    if (isPlainObject(value)) {
+        const entries = Object.entries(value);
+        if (entries.length === 0) {
+            return `${indent(level)}{}`;
+        }
+        return entries
+            .map(([key, val]) => {
+            if (isScalar(val)) {
+                return `${indent(level)}${key}: ${formatScalar(val)}`;
+            }
+            const rendered = render(val, level + 1);
+            return `${indent(level)}${key}:\n${rendered}`;
+        })
+            .join('\n');
+    }
+    return `${indent(level)}${JSON.stringify(value)}`;
+}
+function formatScalar(value) {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'string') {
+        return needsQuoting(value) ? JSON.stringify(value) : value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function indent(level) {
+    return PAD.repeat(level);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isScalar(value) {
+    return (value === null ||
+        value === undefined ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean');
+}
+function needsQuoting(value) {
+    return /[:{}[\],&*#?|<>=%@`]/.test(value) || value.includes('"') || value.includes("'") || value.includes('\n');
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "parse-hcl",
+    "version": "0.1.0",
+    "description": "Lightweight HCL parser focused on identifying and classifying blocks. Supports common Terraform blocks (resource, variable, output, locals, etc.) for tooling and automation.",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./dist/index.js",
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./package.json": "./package.json"
+    },
+    "bin": {
+        "parse-hcl": "./dist/cli.js"
+    },
+    "repository": "https://github.com/sigmoid-hq/parse-hcl",
+    "author": "Juan Lee <juan.lee@sigmoid.us>",
+    "license": "Apache-2.0",
+    "private": false,
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "keywords": [
+        "terraform",
+        "hcl",
+        "parser",
+        "tfvars",
+        "tfstate",
+        "plan"
+    ],
+    "sideEffects": false,
+    "engines": {
+        "node": ">=18"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "build:examples": "tsc -p tsconfig.examples.json",
+        "test": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "lint": "eslint src",
+        "lint:fix": "eslint src --fix",
+        "format": "prettier --write \"src/**/*.ts\"",
+        "format:check": "prettier --check \"src/**/*.ts\"",
+        "prepublishOnly": "yarn build && yarn test && yarn lint",
+        "example": "yarn build && yarn build:examples && node dist/examples/runExample.js",
+        "cli": "yarn build && node dist/cli.js",
+        "example:usage": "yarn build && yarn build:examples && node dist/examples/usageBasic.js",
+        "example:artifacts": "yarn build && yarn build:examples && node dist/examples/usageArtifacts.js"
+    },
+    "devDependencies": {
+        "@types/node": "^25.0.1",
+        "@typescript-eslint/eslint-plugin": "^8.50.1",
+        "@typescript-eslint/parser": "^8.50.1",
+        "@vitest/coverage-v8": "^4.0.16",
+        "eslint": "^9.39.2",
+        "eslint-config-prettier": "^10.1.8",
+        "globals": "^16.5.0",
+        "prettier": "^3.7.4",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.15"
+    }
+}