parse-hcl 0.1.0 → 0.2.0

package/README.md

@@ -49,6 +49,12 @@ pnpm add parse-hcl
 
 The `parse-hcl` CLI provides instant Terraform configuration analysis from your terminal.
 
+### Command Synopsis
+
+```bash
+parse-hcl --file <path> | --dir <path> [--format json|yaml] [--graph] [--no-prune]
+```
+
 ### Basic Commands
 
 ```bash
@@ -75,6 +81,9 @@ parse-hcl --file plan.json
 
 # Keep empty arrays/objects in output
 parse-hcl --file main.tf --no-prune
+
+# Save to custom path and also print
+parse-hcl --file main.tf --out ./out/result.json --stdout
 ```
 
 ### Options Reference
@@ -86,6 +95,26 @@ parse-hcl --file main.tf --no-prune
 | `--format <type>` | Output format: `json` or `yaml` | `json` |
 | `--graph` | Include dependency graph (nodes, edges, references) | `false` |
 | `--no-prune` | Keep empty arrays and objects in output | `false` |
+| `--out <path>` | Save output to file (or directory for combined output) | `./parse-hcl-output*.{json,yaml}` |
+| `--out-dir <dir>` | Save per-file results under this directory (directory mode) | `./parse-hcl-output/files` |
+| `--split` / `--no-split` | Enable/disable per-file saving in directory mode | `true` |
+| `--stdout` / `--no-stdout` | Also print to stdout (default off) | `false` |
+
+### Behavior and Defaults
+
+- Pass either `--file` or `--dir`; if both are present, `--file` is used. Missing inputs print usage to stderr and exit with code `1`.
+- **Default output is files, stdout off.**  
+  - Single file: writes `./parse-hcl-output.{json|yaml}`.  
+  - Directory: writes combined `./parse-hcl-output.combined.{json|yaml}` and per-file under `./parse-hcl-output/files/<relative-path>.{json|yaml}`.  
+  - Add `--stdout` to also print.
+- `--out` overrides the combined/single output path. If it points to a directory, the tool writes `output.{json|yaml}` (single file) or `combined.{json|yaml}` (directory). If no extension is given, one is added based on `--format`.
+- `--out-dir` sets the root for per-file outputs (directory mode). If omitted but `--out` is provided, per-file results go under `per-file/` next to the `--out` target. Disable per-file writes with `--no-split`.
+- `--file` auto-detects artifacts: paths containing `tfvars` use the tfvars parser, `.tfstate` uses the state parser, and `plan.json` uses the plan parser. Other files are treated as Terraform configs. The `--graph` flag only applies to Terraform configs; artifact parsers ignore it and emit the raw parse.
+- `--dir` walks recursively, parsing only `.tf` and `.tf.json` files while skipping `.terraform`, `.git`, and `node_modules`. Default output contains `combined` (aggregated document) and `files` (per-file results). With `--graph`, the dependency graph is built from the aggregated document.
+- When split outputs are enabled, each `files` entry includes `relative_path`, `output_path`, and `output_dir` (all relative). Module blocks include `source_raw` (as written) and, when local, `source_output_dir`, pointing to the per-file output directory for that module.
+- Warnings and usage go to stderr. The CLI exits non-zero on invalid arguments or parsing failures.
+- `--format` applies to every output shape; `--no-prune` keeps empty arrays/objects that are removed by default for compactness.
+- Run without a global install via `npx parse-hcl ...` or `yarn dlx parse-hcl ...`.
 
 ### Output Formats
 
@@ -154,6 +183,13 @@ variable:
       value: us-east-1
 ```
 
+**Default saved files (no flags):**
+```bash
+$ ls parse-hcl-output*
+parse-hcl-output.combined.json
+parse-hcl-output/files/main.tf.json
+```
+
 **Graph Output:**
 ```bash
 $ parse-hcl --file main.tf --graph --format json

package/dist/cli.js

@@ -4,12 +4,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const terraformParser_1 = require("./services/terraformParser");
 const artifactParsers_1 = require("./services/artifactParsers");
 const serializer_1 = require("./utils/serialization/serializer");
+const outputMetadata_1 = require("./utils/outputMetadata");
+const DEFAULT_SINGLE_BASENAME = 'parse-hcl-output';
+const DEFAULT_COMBINED_BASENAME = 'parse-hcl-output.combined';
+const DEFAULT_PER_FILE_DIR = 'parse-hcl-output/files';
 function parseArgs(argv) {
-    const opts = { format: 'json', graph: false, prune: true };
+    const opts = { format: 'json', graph: false, prune: true, split: true, stdout: false };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === '--file' && argv[i + 1]) {
@@ -30,6 +35,24 @@ function parseArgs(argv) {
         else if (arg === '--no-prune') {
             opts.prune = false;
         }
+        else if (arg === '--out' && argv[i + 1]) {
+            opts.out = argv[++i];
+        }
+        else if (arg === '--out-dir' && argv[i + 1]) {
+            opts.outDir = argv[++i];
+        }
+        else if (arg === '--split') {
+            opts.split = true;
+        }
+        else if (arg === '--no-split') {
+            opts.split = false;
+        }
+        else if (arg === '--stdout') {
+            opts.stdout = true;
+        }
+        else if (arg === '--no-stdout') {
+            opts.stdout = false;
+        }
     }
     return opts;
 }
@@ -37,51 +60,124 @@ function main() {
     const opts = parseArgs(process.argv.slice(2));
     const parser = new terraformParser_1.TerraformParser();
     if (!opts.file && !opts.dir) {
-        console.error('Usage: parse-hcl --file <path> | --dir <path> [--format json|yaml] [--graph] [--no-prune]');
+        console.error('Usage: parse-hcl --file <path> | --dir <path> [--format json|yaml] [--graph] [--no-prune] [--out <path>] [--out-dir <dir>] [--stdout]');
         process.exit(1);
     }
     if (opts.file) {
         const filePath = path_1.default.resolve(opts.file);
         const ext = path_1.default.extname(filePath);
         if (ext.includes('tfvars')) {
-            emit(tfvarsParse(filePath), opts);
+            const data = tfvarsParse(filePath);
+            emitSingle(filePath, data, opts);
             return;
         }
         if (ext === '.tfstate') {
-            emit(new artifactParsers_1.TfStateParser().parseFile(filePath), opts);
+            const data = new artifactParsers_1.TfStateParser().parseFile(filePath);
+            emitSingle(filePath, data, opts);
             return;
         }
         if (ext === '.json' && filePath.endsWith('plan.json')) {
-            emit(new artifactParsers_1.TfPlanParser().parseFile(filePath), opts);
+            const data = new artifactParsers_1.TfPlanParser().parseFile(filePath);
+            emitSingle(filePath, data, opts);
             return;
         }
         const doc = parser.parseFile(filePath);
-        emit(doc, opts);
+        emitSingle(filePath, doc, opts);
         return;
     }
     if (opts.dir) {
         const dirPath = path_1.default.resolve(opts.dir);
         const result = parser.parseDirectory(dirPath);
-        const combined = result.combined ?? parser.combine(result.files.map((f) => f.document));
-        emit(opts.graph ? (0, serializer_1.toExport)(combined, { pruneEmpty: opts.prune }) : result, opts);
+        const combinedDoc = result.combined ?? parser.combine(result.files.map((f) => f.document));
+        emitDirectory(dirPath, result.files, combinedDoc, opts);
     }
 }
 function tfvarsParse(filePath) {
     return new artifactParsers_1.TfVarsParser().parseFile(filePath);
 }
-function emit(data, opts) {
+function emitSingle(filePath, data, opts) {
+    const rendered = render(data, opts);
+    const ext = getExt(opts.format);
+    const defaultName = `${DEFAULT_SINGLE_BASENAME}${ext}`;
+    const targetPath = resolveOutPath(opts.out, defaultName, opts.format);
+    writeFile(targetPath, rendered);
+    if (opts.stdout) {
+        console.info(rendered);
+    }
+}
+function emitDirectory(dirPath, files, combinedDoc, opts) {
+    const ext = getExt(opts.format);
+    const perFileBase = opts.split ? resolvePerFileBase(opts) : undefined;
+    (0, outputMetadata_1.annotateOutputMetadata)({
+        dirPath,
+        files,
+        perFileBase,
+        ext,
+        cwd: process.cwd()
+    });
+    const combinedData = opts.graph ? combinedDoc : { combined: combinedDoc, files: opts.split ? files : [] };
+    const combinedRendered = render(combinedData, opts);
+    const combinedDefaultName = `${DEFAULT_COMBINED_BASENAME}${ext}`;
+    const combinedTarget = resolveOutPath(opts.out, combinedDefaultName, opts.format, true);
+    writeFile(combinedTarget, combinedRendered);
+    if (opts.split && perFileBase) {
+        files.forEach((file) => {
+            const relPath = file.relative_path ?? path_1.default.relative(dirPath, path_1.default.resolve(file.path));
+            const perFileTarget = path_1.default.join(perFileBase, `${relPath}${ext}`);
+            const rendered = render(file.document, opts);
+            writeFile(perFileTarget, rendered);
+        });
+    }
+    if (opts.stdout) {
+        console.info(combinedRendered);
+    }
+}
+function render(data, opts) {
     if (opts.graph && !isTerraformDoc(data)) {
         console.warn('Graph export requested but input is not a Terraform document; emitting raw output.');
     }
     if (opts.format === 'yaml') {
-        console.info((0, serializer_1.toYamlDocument)(data, { pruneEmpty: opts.prune }));
-        return;
+        return (0, serializer_1.toYamlDocument)(data, { pruneEmpty: opts.prune });
     }
     if (opts.graph && isTerraformDoc(data)) {
-        console.info((0, serializer_1.toJsonExport)(data, { pruneEmpty: opts.prune }));
-        return;
+        return (0, serializer_1.toJsonExport)(data, { pruneEmpty: opts.prune });
+    }
+    return (0, serializer_1.toJson)(data, { pruneEmpty: opts.prune });
+}
+function resolveOutPath(out, defaultName, format, isDirMode = false) {
+    const resolvedDefault = path_1.default.resolve(defaultName);
+    if (!out) {
+        return resolvedDefault;
     }
-    console.info((0, serializer_1.toJson)(data, { pruneEmpty: opts.prune }));
+    const resolvedOut = path_1.default.resolve(out);
+    if (fs_1.default.existsSync(resolvedOut) && fs_1.default.statSync(resolvedOut).isDirectory()) {
+        const name = isDirMode ? `combined${getExt(format)}` : `output${getExt(format)}`;
+        return path_1.default.join(resolvedOut, name);
+    }
+    if (!path_1.default.extname(resolvedOut)) {
+        return `${resolvedOut}${getExt(format)}`;
+    }
+    return resolvedOut;
+}
+function resolvePerFileBase(opts) {
+    if (opts.outDir) {
+        return path_1.default.resolve(opts.outDir);
+    }
+    if (opts.out) {
+        const resolvedOut = path_1.default.resolve(opts.out);
+        if (fs_1.default.existsSync(resolvedOut) && fs_1.default.statSync(resolvedOut).isDirectory()) {
+            return path_1.default.join(resolvedOut, 'per-file');
+        }
+        return path_1.default.join(path_1.default.dirname(resolvedOut), 'per-file');
+    }
+    return path_1.default.resolve(DEFAULT_PER_FILE_DIR);
+}
+function writeFile(targetPath, contents) {
+    fs_1.default.mkdirSync(path_1.default.dirname(targetPath), { recursive: true });
+    fs_1.default.writeFileSync(targetPath, contents, 'utf-8');
+}
+function getExt(format) {
+    return format === 'yaml' ? '.yaml' : '.json';
 }
 function isTerraformDoc(data) {
     return Boolean(data && typeof data === 'object' && 'resource' in data);

package/dist/types/blocks.d.ts

@@ -196,6 +196,10 @@ export interface ModuleBlock {
     name: string;
     /** All properties defined in the block (including source, version, etc.) */
     properties: Record<string, Value>;
+    /** Raw source string as written in HCL (useful when a resolved output dir is added) */
+    source_raw?: string;
+    /** Relative path to the per-file parse output for the referenced source directory (when available) */
+    source_output_dir?: string;
     /** The original raw text */
     raw: string;
     /** Source file path */
@@ -396,6 +400,12 @@ export declare function createEmptyDocument(): TerraformDocument;
 export interface FileParseResult {
     /** The file path */
     path: string;
+    /** Path relative to the parsed directory root */
+    relative_path?: string;
+    /** Relative path (from cwd) to the per-file parse output */
+    output_path?: string;
+    /** Relative directory containing the per-file parse output */
+    output_dir?: string;
     /** The parsed document */
     document: TerraformDocument;
 }

package/dist/utils/outputMetadata.d.ts

@@ -0,0 +1,20 @@
+import { FileParseResult } from '../types/blocks';
+type FileWithMetadata = FileParseResult & {
+    relative_path?: string;
+    output_path?: string;
+    output_dir?: string;
+};
+interface MetadataOptions {
+    dirPath: string;
+    files: FileWithMetadata[];
+    perFileBase?: string;
+    ext: '.json' | '.yaml';
+    cwd?: string;
+}
+/**
+ * Attaches relative path metadata to per-file results and module blocks.
+ * - Adds relative paths for files and their output targets (when split outputs are enabled).
+ * - Adds `source_output_dir` to module blocks that point to local directories within the parsed tree.
+ */
+export declare function annotateOutputMetadata(options: MetadataOptions): void;
+export {};

package/dist/utils/outputMetadata.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.annotateOutputMetadata = annotateOutputMetadata;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const valueHelpers_1 = require("./common/valueHelpers");
+/**
+ * Attaches relative path metadata to per-file results and module blocks.
+ * - Adds relative paths for files and their output targets (when split outputs are enabled).
+ * - Adds `source_output_dir` to module blocks that point to local directories within the parsed tree.
+ */
+function annotateOutputMetadata(options) {
+    const root = path_1.default.resolve(options.dirPath);
+    const cwd = options.cwd ? path_1.default.resolve(options.cwd) : process.cwd();
+    const perFileBase = options.perFileBase ? path_1.default.resolve(options.perFileBase) : undefined;
+    for (const file of options.files) {
+        const absPath = path_1.default.resolve(file.path);
+        const relPath = path_1.default.relative(root, absPath);
+        file.relative_path = relPath;
+        if (perFileBase) {
+            const perFileTarget = path_1.default.join(perFileBase, `${relPath}${options.ext}`);
+            const outputPath = normalizeRelative(cwd, perFileTarget);
+            file.output_path = outputPath;
+            file.output_dir = path_1.default.dirname(outputPath);
+        }
+    }
+    for (const file of options.files) {
+        const fileDir = path_1.default.dirname(path_1.default.resolve(file.path));
+        for (const mod of file.document.module) {
+            const sourceRaw = getRawSource(mod.properties.source);
+            if (sourceRaw) {
+                mod.source_raw = sourceRaw;
+            }
+            if (!perFileBase) {
+                continue;
+            }
+            const sourceLiteral = (0, valueHelpers_1.literalString)(mod.properties.source);
+            if (!sourceLiteral || !isLocalPath(sourceLiteral)) {
+                continue;
+            }
+            const resolvedSource = path_1.default.resolve(fileDir, sourceLiteral);
+            if (!fs_1.default.existsSync(resolvedSource) || !fs_1.default.statSync(resolvedSource).isDirectory()) {
+                continue;
+            }
+            const relToRoot = path_1.default.relative(root, resolvedSource);
+            if (relToRoot.startsWith('..') || path_1.default.isAbsolute(relToRoot)) {
+                continue;
+            }
+            const outputDir = path_1.default.join(perFileBase, relToRoot);
+            mod.source_output_dir = normalizeRelative(cwd, outputDir);
+        }
+    }
+}
+function isLocalPath(source) {
+    if (source.includes('://') || source.includes('::')) {
+        return false;
+    }
+    return source.startsWith('.') || path_1.default.isAbsolute(source);
+}
+function normalizeRelative(from, to) {
+    const rel = path_1.default.relative(from, to);
+    return rel || '.';
+}
+function getRawSource(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value.type === 'literal' && typeof value.value === 'string') {
+        return value.value;
+    }
+    if ('raw' in value && typeof value.raw === 'string') {
+        return value.raw;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "parse-hcl",
-    "version": "0.1.0",
+    "version": "0.2.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",