parse-hcl 0.1.0

package/dist/types/artifacts.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for Terraform artifacts (state files, plans, tfvars) and dependency graphs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/blocks.d.ts

@@ -0,0 +1,419 @@
+/**
+ * Type definitions for Terraform HCL block structures.
+ * Provides comprehensive type coverage for all Terraform configuration elements.
+ */
+/**
+ * Known Terraform block types.
+ * - `terraform`: Terraform settings and required providers
+ * - `provider`: Provider configuration
+ * - `variable`: Input variable declarations
+ * - `output`: Output value declarations
+ * - `module`: Module calls
+ * - `resource`: Managed resource definitions
+ * - `data`: Data source definitions
+ * - `locals`: Local value definitions
+ * - `moved`: Resource move declarations
+ * - `import`: Import declarations
+ * - `check`: Check assertions
+ * - `terraform_data`: Terraform data resources
+ * - `unknown`: Unrecognized block types
+ */
+export type BlockKind = 'terraform' | 'provider' | 'variable' | 'output' | 'module' | 'resource' | 'data' | 'locals' | 'moved' | 'import' | 'check' | 'terraform_data' | 'unknown';
+/**
+ * Types of expressions in HCL.
+ * - `traversal`: Attribute access (e.g., `var.name`, `local.value`)
+ * - `function_call`: Function invocation (e.g., `length(var.list)`)
+ * - `template`: String interpolation (e.g., `"${var.name}"`)
+ * - `for_expr`: For expressions/comprehensions
+ * - `conditional`: Ternary conditional (e.g., `var.enabled ? "yes" : "no"`)
+ * - `splat`: Splat expressions (e.g., `aws_instance.web[*].id`)
+ * - `unknown`: Unrecognized expression type
+ */
+export type ExpressionKind = 'traversal' | 'function_call' | 'template' | 'for_expr' | 'conditional' | 'splat' | 'unknown';
+/**
+ * Reference to a Terraform configuration element.
+ * Used for dependency tracking and graph building.
+ */
+export type Reference = {
+    kind: 'variable';
+    name: string;
+} | {
+    kind: 'local';
+    name: string;
+} | {
+    kind: 'module_output';
+    module: string;
+    name: string;
+} | {
+    kind: 'data';
+    data_type: string;
+    name: string;
+    attribute?: string;
+    splat?: boolean;
+} | {
+    kind: 'resource';
+    resource_type: string;
+    name: string;
+    attribute?: string;
+    splat?: boolean;
+} | {
+    kind: 'path';
+    name: string;
+} | {
+    kind: 'each';
+    property: 'key' | 'value';
+} | {
+    kind: 'count';
+    property: 'index';
+} | {
+    kind: 'self';
+    attribute: string;
+};
+/**
+ * A literal value (string, number, boolean, or null).
+ */
+export interface LiteralValue {
+    type: 'literal';
+    /** The parsed literal value */
+    value: string | number | boolean | null;
+    /** The original raw text */
+    raw: string;
+}
+/**
+ * An object/map value with key-value pairs.
+ */
+export interface ObjectValue {
+    type: 'object';
+    /** Parsed object entries (if successfully parsed) */
+    value?: Record<string, Value>;
+    /** The original raw text */
+    raw: string;
+    /** References found within the object */
+    references?: Reference[];
+}
+/**
+ * An array/list value with elements.
+ */
+export interface ArrayValue {
+    type: 'array';
+    /** Parsed array elements (if successfully parsed) */
+    value?: Value[];
+    /** The original raw text */
+    raw: string;
+    /** References found within the array */
+    references?: Reference[];
+}
+/**
+ * An expression value (traversals, function calls, templates, etc.).
+ */
+export interface ExpressionValue {
+    type: 'expression';
+    /** The kind of expression */
+    kind: ExpressionKind;
+    /** The original raw text */
+    raw: string;
+    /** References found within the expression */
+    references?: Reference[];
+    /** Additional parsed data (for specific expression types) */
+    parsed?: Record<string, unknown>;
+}
+/**
+ * Union type for all possible HCL values.
+ */
+export type Value = LiteralValue | ObjectValue | ArrayValue | ExpressionValue;
+/**
+ * Parsed body of an HCL block containing attributes and nested blocks.
+ */
+export interface ParsedBody {
+    /** Key-value attribute assignments */
+    attributes: Record<string, Value>;
+    /** Nested block definitions */
+    blocks: NestedBlock[];
+}
+/**
+ * A nested block within a parent block.
+ */
+export interface NestedBlock {
+    /** The block type identifier */
+    type: string;
+    /** Block labels (e.g., for provisioner blocks) */
+    labels: string[];
+    /** Attribute assignments within the block */
+    attributes: Record<string, Value>;
+    /** Further nested blocks */
+    blocks: NestedBlock[];
+    /** The original raw text */
+    raw: string;
+}
+/**
+ * A raw HCL block as extracted by the scanner.
+ */
+export interface HclBlock {
+    /** The classified block kind */
+    kind: BlockKind;
+    /** The original keyword used */
+    keyword: string;
+    /** Block labels (e.g., resource type and name) */
+    labels: string[];
+    /** The block body content (without braces) */
+    body: string;
+    /** The complete raw block text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Terraform settings block (terraform { ... }).
+ */
+export interface TerraformSettingsBlock {
+    /** All properties defined in the block */
+    properties: Record<string, Value>;
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Provider configuration block.
+ */
+export interface ProviderBlock {
+    /** Provider name (e.g., "aws", "google") */
+    name: string;
+    /** Provider alias (for multiple provider configurations) */
+    alias?: string;
+    /** All properties defined in the block */
+    properties: Record<string, Value>;
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Module call block.
+ */
+export interface ModuleBlock {
+    /** Module name (the label) */
+    name: string;
+    /** All properties defined in the block (including source, version, etc.) */
+    properties: Record<string, Value>;
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Resource definition block.
+ */
+export interface ResourceBlock {
+    /** Resource type (e.g., "aws_instance", "google_compute_instance") */
+    type: string;
+    /** Resource name (the second label) */
+    name: string;
+    /** Resource properties (excluding meta-arguments) */
+    properties: Record<string, Value>;
+    /** Nested blocks within the resource */
+    blocks: NestedBlock[];
+    /** Dynamic blocks within the resource */
+    dynamic_blocks: DynamicBlock[];
+    /** Meta-arguments (count, for_each, provider, depends_on, lifecycle) */
+    meta: Record<string, Value>;
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Dynamic block definition within a resource.
+ */
+export interface DynamicBlock {
+    /** The label (block type being generated) */
+    label: string;
+    /** The for_each expression */
+    for_each?: Value;
+    /** The iterator variable name */
+    iterator?: string;
+    /** The content block attributes */
+    content: Record<string, Value>;
+    /** The original raw text */
+    raw: string;
+}
+/**
+ * Data source definition block.
+ */
+export interface DataBlock {
+    /** Data source type (e.g., "aws_ami", "google_compute_image") */
+    dataType: string;
+    /** Data source name (the second label) */
+    name: string;
+    /** Data source properties */
+    properties: Record<string, Value>;
+    /** Nested blocks within the data source */
+    blocks: NestedBlock[];
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Parsed type constraint for a variable.
+ */
+export interface TypeConstraint {
+    /** The base type name (string, number, bool, list, map, object, set, tuple, any) */
+    base: string;
+    /** Element type for collection types */
+    element?: TypeConstraint;
+    /** Element types for tuple types */
+    elements?: TypeConstraint[];
+    /** Attribute types for object types */
+    attributes?: Record<string, TypeConstraint>;
+    /** Whether the type is optional (for object attributes) */
+    optional?: boolean;
+    /** The original raw type expression */
+    raw: string;
+}
+/**
+ * Validation rule for a variable.
+ */
+export interface VariableValidation {
+    /** The condition expression (must evaluate to true) */
+    condition?: Value;
+    /** The error message to display when condition is false */
+    error_message?: Value;
+}
+/**
+ * Variable definition block.
+ */
+export interface VariableBlock {
+    /** Variable name */
+    name: string;
+    /** Variable description */
+    description?: string;
+    /** Type constraint expression */
+    type?: string;
+    /** Parsed type constraint (if type is provided) */
+    typeConstraint?: TypeConstraint;
+    /** Default value */
+    default?: Value;
+    /** Validation rules */
+    validation?: VariableValidation;
+    /** Whether the variable is sensitive */
+    sensitive?: boolean;
+    /** Whether the variable is nullable */
+    nullable?: boolean;
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Output definition block.
+ */
+export interface OutputBlock {
+    /** Output name */
+    name: string;
+    /** Output description */
+    description?: string;
+    /** The output value expression */
+    value?: Value;
+    /** Whether the output is sensitive */
+    sensitive?: boolean;
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * A single local value definition.
+ */
+export interface LocalValue {
+    /** Local value name */
+    name: string;
+    /** The value type classification */
+    type: Value['type'];
+    /** The parsed value */
+    value: Value;
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * A generic block for less common block types (moved, import, check, etc.).
+ */
+export interface GenericBlock {
+    /** The block type */
+    type: string;
+    /** Block labels */
+    labels: string[];
+    /** Block properties */
+    properties: Record<string, Value>;
+    /** Nested blocks */
+    blocks: NestedBlock[];
+    /** The original raw text */
+    raw: string;
+    /** Source file path */
+    source: string;
+}
+/**
+ * Complete Terraform document containing all parsed blocks.
+ */
+export interface TerraformDocument {
+    /** Terraform settings blocks */
+    terraform: TerraformSettingsBlock[];
+    /** Provider configurations */
+    provider: ProviderBlock[];
+    /** Variable declarations */
+    variable: VariableBlock[];
+    /** Output declarations */
+    output: OutputBlock[];
+    /** Module calls */
+    module: ModuleBlock[];
+    /** Resource definitions */
+    resource: ResourceBlock[];
+    /** Data source definitions */
+    data: DataBlock[];
+    /** Local value definitions */
+    locals: LocalValue[];
+    /** Moved declarations */
+    moved: GenericBlock[];
+    /** Import declarations */
+    import: GenericBlock[];
+    /** Check assertions */
+    check: GenericBlock[];
+    /** Terraform data resources */
+    terraform_data: GenericBlock[];
+    /** Unrecognized blocks */
+    unknown: GenericBlock[];
+}
+/**
+ * Creates an empty TerraformDocument with all arrays initialized.
+ * @returns A new empty TerraformDocument
+ */
+export declare function createEmptyDocument(): TerraformDocument;
+/**
+ * Result of parsing a single file.
+ */
+export interface FileParseResult {
+    /** The file path */
+    path: string;
+    /** The parsed document */
+    document: TerraformDocument;
+}
+/**
+ * Options for directory parsing.
+ */
+export interface DirectoryParseOptions {
+    /** Whether to aggregate all files into a combined document (default: true) */
+    aggregate?: boolean;
+    /** Whether to include per-file results (default: true) */
+    includePerFile?: boolean;
+}
+/**
+ * Result of parsing a directory.
+ */
+export interface DirectoryParseResult {
+    /** Combined document from all files (if aggregate is true) */
+    combined?: TerraformDocument;
+    /** Per-file parsing results (if includePerFile is true) */
+    files: FileParseResult[];
+}

package/dist/types/blocks.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Type definitions for Terraform HCL block structures.
+ * Provides comprehensive type coverage for all Terraform configuration elements.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmptyDocument = createEmptyDocument;
+/**
+ * Creates an empty TerraformDocument with all arrays initialized.
+ * @returns A new empty TerraformDocument
+ */
+function createEmptyDocument() {
+    return {
+        terraform: [],
+        provider: [],
+        variable: [],
+        output: [],
+        module: [],
+        resource: [],
+        data: [],
+        locals: [],
+        moved: [],
+        import: [],
+        check: [],
+        terraform_data: [],
+        unknown: []
+    };
+}

package/dist/utils/common/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Represents a location in source code with line, column, and absolute offset.
+ */
+export interface SourceLocation {
+    /** 1-based line number */
+    line: number;
+    /** 1-based column number */
+    column: number;
+    /** 0-based character offset from start of content */
+    offset: number;
+}
+/**
+ * Represents a range in source code from start to end positions.
+ */
+export interface SourceRange {
+    start: SourceLocation;
+    end: SourceLocation;
+}
+/**
+ * Error thrown when HCL parsing fails.
+ * Contains location information for debugging.
+ */
+export declare class ParseError extends Error {
+    /** The source file path where the error occurred */
+    readonly source: string;
+    /** The location in the source where the error occurred */
+    readonly location: SourceLocation;
+    /** Optional end location for range-based errors */
+    readonly endLocation?: SourceLocation;
+    constructor(message: string, source: string, location: SourceLocation, endLocation?: SourceLocation);
+}
+/**
+ * Calculates line and column numbers from a character offset.
+ * @param content - The full source content
+ * @param offset - The 0-based character offset
+ * @returns The source location with line, column, and offset
+ */
+export declare function offsetToLocation(content: string, offset: number): SourceLocation;
+/**
+ * Creates a SourceRange from start and end offsets.
+ * @param content - The full source content
+ * @param startOffset - The 0-based start offset
+ * @param endOffset - The 0-based end offset
+ * @returns The source range
+ */
+export declare function offsetsToRange(content: string, startOffset: number, endOffset: number): SourceRange;

package/dist/utils/common/errors.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseError = void 0;
+exports.offsetToLocation = offsetToLocation;
+exports.offsetsToRange = offsetsToRange;
+/**
+ * Error thrown when HCL parsing fails.
+ * Contains location information for debugging.
+ */
+class ParseError extends Error {
+    constructor(message, source, location, endLocation) {
+        const locationStr = `${source}:${location.line}:${location.column}`;
+        super(`${message} at ${locationStr}`);
+        this.name = 'ParseError';
+        this.source = source;
+        this.location = location;
+        this.endLocation = endLocation;
+    }
+}
+exports.ParseError = ParseError;
+/**
+ * Calculates line and column numbers from a character offset.
+ * @param content - The full source content
+ * @param offset - The 0-based character offset
+ * @returns The source location with line, column, and offset
+ */
+function offsetToLocation(content, offset) {
+    let line = 1;
+    let column = 1;
+    const safeOffset = Math.min(offset, content.length);
+    for (let i = 0; i < safeOffset; i++) {
+        if (content[i] === '\n') {
+            line++;
+            column = 1;
+        }
+        else {
+            column++;
+        }
+    }
+    return { line, column, offset: safeOffset };
+}
+/**
+ * Creates a SourceRange from start and end offsets.
+ * @param content - The full source content
+ * @param startOffset - The 0-based start offset
+ * @param endOffset - The 0-based end offset
+ * @returns The source range
+ */
+function offsetsToRange(content, startOffset, endOffset) {
+    return {
+        start: offsetToLocation(content, startOffset),
+        end: offsetToLocation(content, endOffset)
+    };
+}

package/dist/utils/common/fs.d.ts

@@ -0,0 +1,5 @@
+export declare function readTextFile(filePath: string): string;
+export declare function readJsonFile<T = unknown>(filePath: string): T;
+export declare function listTerraformFiles(dirPath: string): string[];
+export declare function pathExists(targetPath: string): boolean;
+export declare function isDirectory(targetPath: string): boolean;

package/dist/utils/common/fs.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readTextFile = readTextFile;
+exports.readJsonFile = readJsonFile;
+exports.listTerraformFiles = listTerraformFiles;
+exports.pathExists = pathExists;
+exports.isDirectory = isDirectory;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const IGNORED_DIRS = new Set(['.terraform', '.git', 'node_modules']);
+function readTextFile(filePath) {
+    return fs_1.default.readFileSync(filePath, 'utf-8');
+}
+function readJsonFile(filePath) {
+    return JSON.parse(readTextFile(filePath));
+}
+function listTerraformFiles(dirPath) {
+    const files = [];
+    const stack = [dirPath];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const entries = fs_1.default.readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path_1.default.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name)) {
+                    continue;
+                }
+                stack.push(fullPath);
+                continue;
+            }
+            if (entry.isFile() &&
+                (entry.name.endsWith('.tf') || entry.name.endsWith('.tf.json'))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    return files.sort();
+}
+function pathExists(targetPath) {
+    return fs_1.default.existsSync(targetPath);
+}
+function isDirectory(targetPath) {
+    return fs_1.default.existsSync(targetPath) && fs_1.default.statSync(targetPath).isDirectory();
+}

package/dist/utils/common/logger.d.ts

@@ -0,0 +1,5 @@
+export declare const logger: {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+};

package/dist/utils/common/logger.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/* Simple logger used inside the parser. */
+exports.logger = {
+    debug: (...args) => {
+        if (process.env.TF_PARSER_DEBUG) {
+            console.debug('[parser:debug]', ...args);
+        }
+    },
+    info: (...args) => {
+        console.info('[parser:info]', ...args);
+    },
+    warn: (...args) => {
+        console.warn('[parser:warn]', ...args);
+    }
+};

package/dist/utils/common/valueHelpers.d.ts

@@ -0,0 +1,4 @@
+import { Value } from '../../types/blocks';
+export declare function literalString(value?: Value): string | undefined;
+export declare function literalBoolean(value?: Value): boolean | undefined;
+export declare function literalNumber(value?: Value): number | undefined;

package/dist/utils/common/valueHelpers.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.literalString = literalString;
+exports.literalBoolean = literalBoolean;
+exports.literalNumber = literalNumber;
+function literalString(value) {
+    if (value?.type === 'literal' && typeof value.value === 'string') {
+        return value.value;
+    }
+    return undefined;
+}
+function literalBoolean(value) {
+    if (value?.type === 'literal' && typeof value.value === 'boolean') {
+        return value.value;
+    }
+    return undefined;
+}
+function literalNumber(value) {
+    if (value?.type === 'literal' && typeof value.value === 'number') {
+        return value.value;
+    }
+    return undefined;
+}

package/dist/utils/graph/graphBuilder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Dependency graph builder for Terraform documents.
+ * Creates a directed graph of dependencies between Terraform elements.
+ */
+import { DependencyGraph, TerraformExport } from '../../types/artifacts';
+import { TerraformDocument } from '../../types/blocks';
+/**
+ * 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}`);
+ * }
+ * ```
+ */
+export declare function buildDependencyGraph(document: TerraformDocument): DependencyGraph;
+/**
+ * Creates a complete export containing the document and its dependency graph.
+ *
+ * @param document - The parsed Terraform document
+ * @returns TerraformExport with version, document, and graph
+ */
+export declare function createExport(document: TerraformDocument): TerraformExport;