@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/real-hcl-analyzer-DBOPXSWJ.js

@@ -0,0 +1,725 @@
+import {
+  ASTEngine
+} from "./chunk-V44PGPA6.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-MLKGABMK.js";
+
+// src/ast/real-hcl-analyzer.ts
+var TYPE_NAME_BLOCKS = /* @__PURE__ */ new Set(["resource", "data"]);
+var SINGLE_LABEL_BLOCKS = /* @__PURE__ */ new Set(["variable", "output", "module", "provider"]);
+var TOP_LEVEL_KINDS = {
+  resource: ASTEngine.SymbolKind.Class,
+  data: ASTEngine.SymbolKind.Class,
+  variable: ASTEngine.SymbolKind.Variable,
+  output: ASTEngine.SymbolKind.Variable,
+  module: ASTEngine.SymbolKind.Module,
+  provider: ASTEngine.SymbolKind.Module,
+  terraform: ASTEngine.SymbolKind.Module,
+  locals: ASTEngine.SymbolKind.Module
+};
+var TERRAFORM_TOP_LEVEL = new Set(Object.keys(TOP_LEVEL_KINDS));
+var TERRAFRAMEWORK_NAME = "Terraform";
+var BUILTIN_ROOTS = /* @__PURE__ */ new Set(["count", "each", "self", "path", "terraform"]);
+var FUNCTION_DECL_BLOCKS = /* @__PURE__ */ new Set(["function"]);
+var TARGET_BLOCK = "target";
+var INHERITS_ATTRIBUTE = "inherits";
+var OVERRIDE_BLOCK_KIND = {
+  override_resource: "resource",
+  override_data: "data",
+  override_module: "module"
+};
+var RealHclAnalyzer = class {
+  /** Per-analysis memo for `subtreeSize`, keyed by tree-sitter node id. */
+  sizeCache = /* @__PURE__ */ new Map();
+  analyze(rootNode, content, filePath) {
+    this.sizeCache.clear();
+    const symbols = [];
+    const relationships = [];
+    const imports = [];
+    const exports = [];
+    const errors = [];
+    const relKeys = /* @__PURE__ */ new Set();
+    const addRelationship = (source, target, type, lineNumber, metadata = {}) => {
+      const key = `${source}\0${type}\0${target}\0${lineNumber}`;
+      if (relKeys.has(key)) return;
+      relKeys.add(key);
+      if (!metadata.evidenceClass) {
+        metadata.evidenceClass = type === ASTEngine.RelationshipType.Contains ? "structural" : type === ASTEngine.RelationshipType.Imports ? "import_based" : type === ASTEngine.RelationshipType.Uses ? "builtin_qualified" : type === ASTEngine.RelationshipType.References ? "reference_qualified" : "structural";
+      }
+      relationships.push({ source, target, type, confidence: 1, line_number: lineNumber, metadata });
+    };
+    const terraformBlocks = /* @__PURE__ */ new Map();
+    const rootName = this.documentName(filePath);
+    const rootRange = this.nodeToRange(rootNode);
+    symbols.push({
+      name: rootName,
+      qualifiedName: rootName,
+      kind: ASTEngine.SymbolKind.Module,
+      range: rootRange,
+      scope: "",
+      visibility: "public",
+      metadata: { hclRoot: true, hclLanguage: "hcl" }
+    });
+    exports.push({ name: rootName, kind: ASTEngine.SymbolKind.Module, range: rootRange, visibility: "public" });
+    const functionDecls = /* @__PURE__ */ new Map();
+    const pendingCalls = [];
+    const targetDecls = /* @__PURE__ */ new Map();
+    const pendingInherits = [];
+    const stack = [
+      {
+        node: rootNode,
+        blockPath: [],
+        blockKind: void 0,
+        taken: /* @__PURE__ */ new Map([[rootName, 1]]),
+        iterators: /* @__PURE__ */ new Set(),
+        shadowed: /* @__PURE__ */ new Map(),
+        overrideKind: null,
+        enclosingBlockType: ""
+      }
+    ];
+    const pushChildren = (node, blockPath, blockKind, taken, iterators, shadowed, overrideKind, enclosingBlockType) => {
+      for (let i = node.namedChildCount - 1; i >= 0; i--) {
+        const child = node.namedChild(i);
+        if (child) stack.push({ node: child, blockPath, blockKind, taken, iterators, shadowed, overrideKind, enclosingBlockType });
+      }
+    };
+    while (stack.length > 0) {
+      const { node, blockPath, blockKind, taken, iterators, shadowed, overrideKind, enclosingBlockType } = stack.pop();
+      const type = node.type;
+      if (type === "block") {
+        let blockTypeIndex = -1;
+        for (let i = 0; i < node.namedChildCount; i++) {
+          if (node.namedChild(i)?.type === "identifier") {
+            blockTypeIndex = i;
+            break;
+          }
+        }
+        const blockType = blockTypeIndex >= 0 ? node.namedChild(blockTypeIndex).text : "";
+        const labels = [];
+        for (let i = 0; i < node.namedChildCount; i++) {
+          if (i === blockTypeIndex) continue;
+          const child = node.namedChild(i);
+          if (!child) continue;
+          if (child.type === "string_lit") labels.push(this.readStringLit(child));
+          else if (child.type === "identifier") labels.push(child.text);
+        }
+        if (!blockType) {
+          pushChildren(node, blockPath, blockKind, taken, iterators, shadowed, overrideKind, enclosingBlockType);
+          continue;
+        }
+        const address = this.blockAddress(blockType, labels);
+        const name = this.disambiguate(address, taken);
+        const kind = TOP_LEVEL_KINDS[blockType] ?? ASTEngine.SymbolKind.Class;
+        const qualified = [...blockPath, name].join(".");
+        const ownerPath = blockPath.length > 0 ? blockPath.join(".") : rootName;
+        const ownerLeaf = blockPath.length > 0 ? blockPath[blockPath.length - 1] : rootName;
+        if (TERRAFORM_TOP_LEVEL.has(blockType)) {
+          terraformBlocks.set(blockType, (terraformBlocks.get(blockType) ?? 0) + 1);
+        }
+        const isFunctionDecl = FUNCTION_DECL_BLOCKS.has(blockType);
+        if (isFunctionDecl && labels.length > 0 && !functionDecls.has(labels[0])) {
+          functionDecls.set(labels[0], name);
+        }
+        if (blockType === TARGET_BLOCK && labels.length > 0 && !targetDecls.has(labels[0])) {
+          targetDecls.set(labels[0], address);
+        }
+        symbols.push({
+          name,
+          qualifiedName: qualified,
+          kind,
+          complexity: this.subtreeSize(node),
+          range: this.nodeToRange(node),
+          scope: ownerPath,
+          visibility: "public",
+          ownerName: ownerLeaf,
+          ownerKind: blockPath.length > 0 ? blockKind : ASTEngine.SymbolKind.Module,
+          metadata: {
+            hclBlockType: blockType,
+            hclLabels: labels,
+            hclBlockKind: TERRAFORM_TOP_LEVEL.has(blockType) ? blockType : "nested",
+            hclAddress: address,
+            // Ordinal among the entities sharing this address in this scope,
+            // where the document root occupies slot 0 when its name collides
+            // with the block's own address (`moved.tf` holding `moved {}`).
+            hclDuplicateIndex: name === address ? 0 : (taken.get(address) ?? 1) - 1,
+            ...isFunctionDecl ? { hclFunctionDecl: true } : {}
+          }
+        });
+        addRelationship(ownerPath, qualified, ASTEngine.RelationshipType.Contains, node.startPosition.row + 1, {
+          hclSite: "block"
+        });
+        if (blockType === "resource" || blockType === "data") {
+          const providerType = labels[0];
+          if (providerType) {
+            addRelationship(rootName, providerType, ASTEngine.RelationshipType.Instantiates, node.startPosition.row + 1, {
+              hclSite: "provider-type",
+              instanceType: providerType,
+              instanceKind: blockType,
+              instanceName: labels[1] ?? "",
+              evidenceClass: "structural"
+            });
+          }
+        }
+        if (blockType === "module") {
+          const source = this.findModuleSource(node);
+          imports.push({
+            module: labels[0] ?? address,
+            path: source,
+            range: this.nodeToRange(node)
+          });
+          if (source) {
+            addRelationship(qualified, source, ASTEngine.RelationshipType.Imports, this.findModuleSourceLine(node) ?? node.startPosition.row + 1, {
+              hclSite: "module-source"
+            });
+          }
+        }
+        if (blockType === "include") {
+          const part = this.findIncludePath(node);
+          if (part) {
+            addRelationship(ownerPath, part.symbol, ASTEngine.RelationshipType.PartOf, part.line, {
+              hclSite: "terragrunt-include",
+              // MANDATORY on every `part_of` row (types.ts): the direction is the
+              // directive's own — THIS file carries the included file as a part.
+              partRole: "library",
+              partPath: part.text,
+              partSymbol: part.symbol,
+              isHclIncludePart: true,
+              evidenceClass: "include_literal"
+            });
+          }
+        }
+        let childIterators = iterators;
+        let childShadowed = shadowed;
+        if (blockType === "dynamic") {
+          const found = /* @__PURE__ */ new Set();
+          this.findDynamicIterators(node, labels, found);
+          if (found.size > 0) {
+            childIterators = new Set(iterators);
+            childShadowed = new Map(shadowed);
+            for (const it of found) {
+              childIterators.add(it);
+              childShadowed.set(it, (childShadowed.get(it) ?? 0) + 1);
+            }
+          }
+        }
+        pushChildren(node, [...blockPath, name], kind, /* @__PURE__ */ new Map(), childIterators, childShadowed, OVERRIDE_BLOCK_KIND[blockType] ?? null, blockType);
+        continue;
+      }
+      if (type === "attribute") {
+        const keyNode = this.findChild(node, (n) => n.type === "identifier");
+        const key = keyNode?.text ?? "";
+        if (key) {
+          const ownerPath = blockPath.length > 0 ? blockPath.join(".") : rootName;
+          const ownerLeaf = blockPath.length > 0 ? blockPath[blockPath.length - 1] : rootName;
+          const name = blockPath.length === 0 && key === rootName ? `${key}#2` : key;
+          const qualified = [...blockPath, name].join(".") || name;
+          const expr = this.findChild(node, (n) => n.type === "expression");
+          const valueNode = expr ? expr.namedChild(0) : void 0;
+          if (enclosingBlockType === TARGET_BLOCK && key === INHERITS_ATTRIBUTE) {
+            for (const parent of this.readStringList(expr)) {
+              pendingInherits.push({ parent, line: keyNode.startPosition.row + 1, owner: ownerPath });
+            }
+          }
+          symbols.push({
+            name,
+            qualifiedName: qualified,
+            kind: ASTEngine.SymbolKind.Property,
+            complexity: this.subtreeSize(node),
+            range: this.nodeToRange(node),
+            scope: ownerPath,
+            visibility: "public",
+            ownerName: ownerLeaf,
+            ownerKind: blockPath.length > 0 ? blockKind : ASTEngine.SymbolKind.Module,
+            metadata: { hclValueKind: this.readValueKind(expr), hclAddress: key }
+          });
+          addRelationship(ownerPath, qualified, ASTEngine.RelationshipType.Contains, keyNode.startPosition.row + 1, {
+            hclSite: "attribute"
+          });
+          if (expr) {
+            const refs = [];
+            this.extractReferences(expr, iterators, shadowed, refs, pendingCalls, ownerPath);
+            if (overrideKind !== null && key === "target") {
+              for (const ref of refs) {
+                if (BUILTIN_ROOTS.has(ref.path.split(".")[0])) continue;
+                addRelationship(ownerPath, ref.path, ASTEngine.RelationshipType.Overrides, keyNode.startPosition.row + 1, {
+                  hclSite: "override-target",
+                  hclOverrideKind: overrideKind,
+                  evidenceClass: "structural"
+                });
+              }
+            } else {
+              for (const ref of refs) {
+                const root = ref.path.split(".")[0];
+                const builtin = BUILTIN_ROOTS.has(root);
+                addRelationship(
+                  ownerPath,
+                  ref.path,
+                  builtin ? ASTEngine.RelationshipType.Uses : ASTEngine.RelationshipType.References,
+                  ref.line,
+                  {
+                    hclSite: builtin ? "builtin-use" : "reference",
+                    ...builtin ? { hclBuiltin: true, languageNamespace: [...BUILTIN_ROOTS] } : {}
+                  }
+                );
+              }
+            }
+          }
+        }
+        continue;
+      }
+      pushChildren(node, blockPath, blockKind, taken, iterators, shadowed, overrideKind, enclosingBlockType);
+    }
+    for (const site of pendingInherits) {
+      const declared = targetDecls.get(site.parent);
+      if (!declared) continue;
+      addRelationship(site.owner, declared, ASTEngine.RelationshipType.Extends, site.line, {
+        hclSite: "inherits",
+        // The spelling AT the inheritance site, kept because the target is the parent
+        // DECLARATION's address (`target._common`) rather than the bare label `_common`.
+        hclInheritedTarget: site.parent,
+        evidenceClass: "structural"
+      });
+    }
+    for (const site of pendingCalls) {
+      const declared = functionDecls.get(site.callee);
+      if (!declared) continue;
+      addRelationship(site.owner, declared, ASTEngine.RelationshipType.Calls, site.line, {
+        hclSite: "function-call",
+        // The spelling AT the call site, kept because the target is the
+        // declaration's index identity (`function.bindir`) rather than the bare
+        // name the file writes.
+        hclCallee: site.callee,
+        evidenceClass: "structural"
+      });
+    }
+    for (const s of symbols) {
+      if (s.metadata?.hclRoot === true) continue;
+      if (s.scope === rootName) {
+        exports.push({ name: s.name, kind: s.kind, range: s.range, visibility: "public" });
+        addRelationship(rootName, s.name, ASTEngine.RelationshipType.Exports, s.range.startLine, {
+          hclSite: "export"
+        });
+      }
+    }
+    return {
+      language: "hcl",
+      symbols,
+      relationships,
+      imports,
+      exports,
+      errors,
+      metadata: {
+        complexity: symbols.length,
+        linesOfCode: content.split("\n").length,
+        patterns: [],
+        framework: "HCL/Terraform",
+        // The M60.R8 three-key family contract, and all three agree:
+        // `framework` names the language's host ecosystem, `detectedFrameworks`
+        // is ALWAYS an array (`[]` when nothing was detected) and
+        // `frameworkPatterns` is aligned with it by `framework` name. Before this
+        // the analyzer published only `framework`, which the gate records as
+        // `missing-contract-key` and a consumer joining the two arrays by name
+        // cannot do.
+        //
+        // The detection is structural, not an extension guess: HCL is the host
+        // language of several distinct ecosystems, and the corpus proves they
+        // need telling apart — consul's agent config and packer's
+        // `.pkr.hcl` templates are HCL with no Terraform block in sight, while
+        // `terraform@db4eef4` is Terraform throughout. `data`, `variable`,
+        // `output`, `module`, `provider`, `terraform` and `locals` are the
+        // Terraform top-level block set; a document declaring none of them is
+        // published as HCL with an empty detection list rather than being
+        // claimed as Terraform on the strength of its extension.
+        detectedFrameworks: terraformBlocks.size > 0 ? [TERRAFRAMEWORK_NAME] : [],
+        frameworkPatterns: terraformBlocks.size > 0 ? [
+          {
+            framework: TERRAFRAMEWORK_NAME,
+            patterns: [...terraformBlocks.entries()].sort((a, b) => a[0] < b[0] ? -1 : 1).map(([blockType, count]) => ({ blockType, count }))
+          }
+        ] : [],
+        hasFrameworkIntelligence: true,
+        hasTypeInference: false
+      }
+    };
+  }
+  /**
+   * Terraform's native address for a block, with a `blockType` fallback so a
+   * label-less `data {}` / `resource "x" {}` never produces an empty name.
+   */
+  blockAddress(blockType, labels) {
+    if (TYPE_NAME_BLOCKS.has(blockType)) {
+      if (labels.length >= 2) return `${labels[0]}.${labels[1]}`;
+      if (labels.length === 1) return `${labels[0]}`;
+      return blockType;
+    }
+    if (SINGLE_LABEL_BLOCKS.has(blockType)) {
+      return labels[0] ?? blockType;
+    }
+    return labels.length > 0 ? `${blockType}.${labels.join(".")}` : blockType;
+  }
+  /**
+   * Make a leaf name unique among its siblings. Terraform repeats `locals`,
+   * `moved`, `removed`, `import` and aliased `provider` blocks by design, and
+   * the HashiCorp DSLs repeat label-less blocks (waypoint's `parameter`).
+   * The first use keeps the bare address; later siblings get `#2`, `#3`, …
+   */
+  disambiguate(address, taken) {
+    const seen = taken.get(address) ?? 0;
+    taken.set(address, seen + 1);
+    if (seen === 0) return address;
+    let n = seen + 1;
+    let candidate = `${address}#${n}`;
+    while (taken.has(candidate)) {
+      n += 1;
+      candidate = `${address}#${n}`;
+    }
+    taken.set(candidate, 1);
+    return candidate;
+  }
+  /**
+   * The grammar node type that actually describes the value — unwrapping the
+   * `operation` container so a comparison is reported as `binary_operation`
+   * rather than as a node type that names no value kind.
+   */
+  readValueKind(expr) {
+    if (!expr) return "missing_expression";
+    const value = expr.namedChild(0);
+    if (!value) return "empty_expression";
+    if (value.type === "operation") {
+      const inner = value.namedChild(0);
+      return inner ? inner.type : "operation";
+    }
+    return value.type;
+  }
+  /**
+   * Walk an expression subtree and collect dotted reference paths with the line
+   * each name is written on.
+   *
+   * A path is a maximal run of `variable_expr` (base identifier) followed by
+   * `get_attr` accessors. The grammar places that run as a set of SIBLINGS under
+   * whatever node owns the expression — `expression` for a plain value, but
+   * `binary_operation` / `unary_operation` under an `operation` wrapper for
+   * arithmetic and comparison, and `expression` again inside each
+   * `template_interpolation`. So the run is read from ANY node's children, and
+   * a parent that is itself part of a run is not re-read.
+   *
+   * `index` / `splat` / `attr_splat` / `full_splat` end the run without
+   * contributing a segment: Terraform resolves `aws_instance.web[*].id` and
+   * `var.list[0]` against the address accumulated so far, so publishing
+   * `aws_instance.web` / `var.list` is the edge Terraform itself means.
+   *
+   * Real Terraform references are always qualified (`var.x`, `aws_instance.web.id`),
+   * so a bare single-identifier path is a type-constraint keyword (`type = string`)
+   * or a function name — not a reference — and is skipped. `loopVars` carries
+   * `for`-intro identifiers and `dynamic` iterators so block-locals are never
+   * mistaken for module/resource references.
+   *
+   * `callSites` collects every `function_call` CALLEE with the line it is
+   * written on, and nothing decides here whether it becomes an edge: a callee is
+   * only callable if a `function` block declares it, and that map is complete
+   * only after the DFS finishes (a call may precede its declaration). So the
+   * candidate is recorded and resolved by the caller.
+   */
+  extractReferences(node, loopVars, shadowed, out, callSites, owner) {
+    const type = node.type;
+    if (type === "function_call") {
+      const callee = this.findChild(node, (n) => n.type === "identifier");
+      if (callee) callSites.push({ callee: callee.text, line: callee.startPosition.row + 1, owner });
+    }
+    if (type === "for_expr" || type === "for_tuple_expr" || type === "for_object_expr") {
+      const childLoopVars = new Set(loopVars);
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type !== "for_intro") continue;
+        for (let j = 0; j < child.namedChildCount; j++) {
+          const intro = child.namedChild(j);
+          if (intro?.type === "identifier") childLoopVars.add(intro.text);
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child) this.extractReferences(child, childLoopVars, shadowed, out, callSites, owner);
+      }
+      return;
+    }
+    if (type === "object_elem") {
+      const val = node.childForFieldName?.("val");
+      if (val) this.extractReferences(val, loopVars, shadowed, out, callSites, owner);
+      return;
+    }
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+      if (child.type !== "variable_expr" && child.type !== "get_attr") {
+        if (child.isNamed) this.extractReferences(child, loopVars, shadowed, out, callSites, owner);
+        continue;
+      }
+      const parts = [];
+      const nameLines = [];
+      let j = i;
+      for (; j < node.childCount; j++) {
+        const c = node.child(j);
+        if (!c || c.type !== "variable_expr" && c.type !== "get_attr") break;
+        const id = this.findChild(c, (n) => n.type === "identifier");
+        if (!id) break;
+        parts.push(id.text);
+        nameLines.push(id.startPosition.row + 1);
+      }
+      if (parts.length >= 2 && !loopVars.has(parts[0])) {
+        out.push({ path: parts.join("."), line: nameLines[0] });
+      }
+      i = j - 1;
+    }
+  }
+  /**
+   * The loop local(s) a `dynamic` block binds: the `iterator` attribute's value
+   * when present, otherwise the block's own first label — Terraform's documented
+   * default, so `dynamic "egress" { content { x = egress.cidr } }` reads a
+   * block-local, not a project symbol. Without the label fallback the emitter
+   * published a false `egress.cidr` (caught by hcl/dynamic-iterator-scope).
+   */
+  findDynamicIterators(blockNode, labels, out) {
+    const body = this.findChild(blockNode, (n) => n.type === "body");
+    if (!body) return;
+    for (let i = 0; i < body.namedChildCount; i++) {
+      const attr = body.namedChild(i);
+      if (attr?.type !== "attribute") continue;
+      const key = this.findChild(attr, (n) => n.type === "identifier");
+      if (key?.text !== "iterator") continue;
+      const expr = this.findChild(attr, (n) => n.type === "expression");
+      const ve = expr?.namedChild(0);
+      if (ve?.type !== "variable_expr") continue;
+      const id = this.findChild(ve, (n) => n.type === "identifier");
+      if (id) {
+        out.add(id.text);
+        return;
+      }
+    }
+    if (labels.length > 0) out.add(labels[0]);
+  }
+  /** Read a `string_lit` label/value without source-text regex (grammar field). */
+  readStringLit(node) {
+    const literal = this.findChild(node, (n) => n.type === "template_literal");
+    if (literal) return literal.text;
+    return node.text;
+  }
+  /**
+   * The string LITERALS of a value, in source order: `["_common"]` yields one, `["binary",
+   * "_platforms"]` yields two, and a bare `"x"` yields one. Only `string_lit` counts — an
+   * interpolated `quoted_template` names a COMPUTED value, not a declaration, and resolving it
+   * would be a guess dressed as an edge.
+   */
+  readStringList(expr) {
+    if (!expr) return [];
+    const out = [];
+    const visit = (n) => {
+      if (n.type === "string_lit") {
+        out.push(this.readStringLit(n));
+        return;
+      }
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const c = n.namedChild(i);
+        if (c) visit(c);
+      }
+    };
+    visit(expr);
+    return out;
+  }
+  /** Find a module block's `source` attribute value (unquoted via grammar field). */
+  findModuleSource(blockNode) {
+    const body = this.findChild(blockNode, (n) => n.type === "body");
+    if (!body) return void 0;
+    for (let i = 0; i < body.namedChildCount; i++) {
+      const attr = body.namedChild(i);
+      if (attr?.type !== "attribute") continue;
+      const key = this.findChild(attr, (n) => n.type === "identifier");
+      if (key?.text !== "source") continue;
+      const expr = this.findChild(attr, (n) => n.type === "expression");
+      if (!expr) return void 0;
+      const literal = this.findDescendant(expr, (n) => n.type === "template_literal");
+      if (literal) return literal.text;
+      return expr.text;
+    }
+    return void 0;
+  }
+  /** The line a module block's `source = …` key is written on. */
+  findModuleSourceLine(blockNode) {
+    const body = this.findChild(blockNode, (n) => n.type === "body");
+    if (!body) return null;
+    for (let i = 0; i < body.namedChildCount; i++) {
+      const attr = body.namedChild(i);
+      if (attr?.type !== "attribute") continue;
+      const key = this.findChild(attr, (n) => n.type === "identifier");
+      if (key?.text !== "source") continue;
+      return key.startPosition.row + 1;
+    }
+    return null;
+  }
+  /** The document's root name, from the file stem (JSON/YAML convention). */
+  documentName(filePath) {
+    const slash = filePath.lastIndexOf("/");
+    const base = slash >= 0 ? filePath.slice(slash + 1) : filePath;
+    const lower = base.toLowerCase();
+    for (const suffix of [".tfvars", ".tofu", ".hcl", ".tf"]) {
+      if (lower.endsWith(suffix)) {
+        const stem = base.slice(0, base.length - suffix.length);
+        return stem.length > 0 ? stem : base;
+      }
+    }
+    return base.length > 0 ? base : "hcl";
+  }
+  /**
+   * A terragrunt `include` block's `path`, ONLY when it is a single STRING
+   * LITERAL — `{ text, symbol, line }`, or null when the block names nothing
+   * this parse can know.
+   *
+   * WHAT IS REFUSED AND WHY. A computed value is not a file: `find_in_parent_folders()`
+   * is a function call whose result depends on the working directory tree, and
+   * `"${get_terragrunt_dir()}/root.hcl"` is an interpolated template whose static
+   * `root.hcl` half is one segment of a computed path. Publishing either would be a
+   * `part_of` whose target is an expression — an edge to nothing — so both publish
+   * NOTHING rather than a guess. The guard is structural (node types), not a
+   * spelling test: any interpolation, call, variable read, index, arithmetic or
+   * conditional anywhere in the value marks it computed.
+   *
+   * The SYMBOL is the included file's root-module symbol spelling: the basename's
+   * stem, with the same extension suffixes `documentName()` strips — because the
+   * arbiter resolves a target string against symbol names, and every HCL file's
+   * root symbol is named from its stem (`root.hcl` → `root`). The path itself is
+   * returned separately for `metadata.partPath`.
+   */
+  findIncludePath(blockNode) {
+    const body = this.findChild(blockNode, (n) => n.type === "body");
+    if (!body) return null;
+    for (let i = 0; i < body.namedChildCount; i++) {
+      const attr = body.namedChild(i);
+      if (attr?.type !== "attribute") continue;
+      const key = this.findChild(attr, (n) => n.type === "identifier");
+      if (key?.text !== "path") continue;
+      const expr = this.findChild(attr, (n) => n.type === "expression");
+      if (!expr) return null;
+      if (this.expressionIsComputed(expr)) return null;
+      const literal = this.findDescendant(expr, (n) => n.type === "template_literal");
+      if (!literal) return null;
+      const text = literal.text;
+      const symbol = this.includePartSymbol(text);
+      if (!symbol) return null;
+      return { text, symbol, line: key.startPosition.row + 1 };
+    }
+    return null;
+  }
+  /**
+   * True when the value is a runtime expression rather than a literal this parse
+   * can name. Kept as a node-type walk (never source text): the grammar's own
+   * vocabulary is the contract, so a future construct cannot slip past a spelling
+   * test.
+   */
+  expressionIsComputed(expr) {
+    const COMPUTED = /* @__PURE__ */ new Set([
+      "template_interpolation",
+      "function_call",
+      "variable_expr",
+      "get_attr",
+      "index",
+      "legacy_index",
+      "splat",
+      "attr_splat",
+      "full_splat",
+      "for_expr",
+      "conditional",
+      "binary_operation",
+      "unary_operation"
+    ]);
+    let computed = false;
+    const visit = (n) => {
+      if (computed || !n) return;
+      if (COMPUTED.has(n.type)) {
+        computed = true;
+        return;
+      }
+      for (let i = 0; i < n.namedChildCount; i++) visit(n.namedChild(i));
+    };
+    visit(expr);
+    return computed;
+  }
+  /**
+   * The symbol-shaped target for an included file's path: its basename's stem.
+   * `./lib/root.hcl` → `root`, `root.hcl` → `root`, `x` → `x`.
+   *
+   * A name carrying characters that can only come from an expression or a glob
+   * (`$`, braces, quotes, `*`, `?`, shell metacharacters) is refused: the
+   * `expressionIsComputed` walk already excludes interpolations, so this is the
+   * second guard that keeps a path-shaped or glob-shaped string out of the target
+   * slot. Empty is refused for the same reason a label-less block names nothing.
+   */
+  includePartSymbol(pathText) {
+    const slash = pathText.lastIndexOf("/");
+    const base = slash >= 0 ? pathText.slice(slash + 1) : pathText;
+    if (base.length === 0) return "";
+    for (let i = 0; i < base.length; i++) {
+      const c = base.charCodeAt(i);
+      if (c <= 32 || c === 34 || c === 39 || c === 96 || c === 36 || c === 40 || c === 41 || c === 123 || c === 125 || c === 91 || c === 93 || c === 42 || c === 63 || c === 59 || c === 124 || c === 38 || c === 60 || c === 62 || c === 92 || c === 126) {
+        return "";
+      }
+    }
+    const lower = base.toLowerCase();
+    for (const suffix of [".tfvars", ".tofu", ".hcl", ".tf"]) {
+      if (lower.endsWith(suffix)) {
+        const stem = base.slice(0, base.length - suffix.length);
+        return stem.length > 0 ? stem : "";
+      }
+    }
+    return base;
+  }
+  /**
+   * Nodes in a symbol's own subtree. Memoised on node id so the whole analysis
+   * stays O(nodes): the DFS already visits every node once, and a block's count
+   * deliberately includes its nested blocks — that is what makes "the biggest
+   * declaration in this file" a comparable number.
+   */
+  subtreeSize(node) {
+    const cached = this.sizeCache.get(node.id);
+    if (cached !== void 0) return cached;
+    let total = 1;
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child) total += this.subtreeSize(child);
+    }
+    this.sizeCache.set(node.id, total);
+    return total;
+  }
+  nodeToRange(node) {
+    return {
+      startLine: node.startPosition.row + 1,
+      startColumn: node.startPosition.column + 1,
+      endLine: node.endPosition.row + 1,
+      endColumn: node.endPosition.column + 1,
+      startIndex: node.startIndex,
+      endIndex: node.endIndex
+    };
+  }
+  findChild(node, predicate) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child && predicate(child)) return child;
+    }
+    return null;
+  }
+  findDescendant(node, predicate) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      if (predicate(child)) return child;
+      const found = this.findDescendant(child, predicate);
+      if (found) return found;
+    }
+    return null;
+  }
+};
+export {
+  RealHclAnalyzer
+};