trooth 0.4.3 → 0.5.0

package/bin/lib/declarations.mjs

@@ -0,0 +1,306 @@
+// What a declaration file says, read from its parsed tree.
+// Copyright 2025-2026 Trooth, LLC. Apache-2.0.
+//
+// Every supported format is parsed first (HCL by ./hcl.mjs, JSON by
+// JSON.parse, YAML by the maintained `yaml` package) and then read here from
+// the tree, so a comment can never count, indentation cannot change a count,
+// a minified file counts the same as a pretty one, and a file that does not
+// parse is reported as invalid instead of being read.
+//
+// An unresolved expression ({ $expr: "..." }) is never promoted to a value.
+// Where it decides a fact, the fact is reported as UNRESOLVED.
+
+import { parseHcl, bodyToTree, HclParseError } from './hcl.mjs';
+import { parseAllDocuments } from 'yaml';
+
+export { HclParseError };
+
+export const isExpr = (v) => !!v && typeof v === 'object' && !Array.isArray(v) && typeof v.$expr === 'string';
+
+/* ------------------------------------------------------------ parsing ---- */
+
+export class InvalidDeclaration extends Error {
+  constructor(message) { super(message); this.name = 'InvalidDeclaration'; }
+}
+
+/** A string in Terraform's JSON syntax that holds a template is an expression. */
+function tfJsonValue(v) {
+  if (typeof v === 'string') {
+    if (/[$%]\{/.test(v)) return { $expr: v };
+    return v;
+  }
+  if (Array.isArray(v)) return v.map(tfJsonValue);
+  if (v && typeof v === 'object') {
+    const o = {};
+    for (const [k, x] of Object.entries(v)) o[k] = tfJsonValue(x);
+    return o;
+  }
+  return v;
+}
+
+const each = (v, fn) => { if (Array.isArray(v)) v.forEach((x) => each(x, fn)); else if (v && typeof v === 'object') fn(v); };
+
+/**
+ * One file's units. Each unit: { type, name, address, tree, typed }.
+ * `type` is a resource type or Kubernetes kind (null for everything else in the
+ * file), `tree` is the parsed value, `address` is how other resources refer to
+ * it. Throws InvalidDeclaration when the file does not parse.
+ */
+export function unitsOf(kind, text) {
+  if (kind === 'terraform') {
+    let items;
+    try { items = parseHcl(text); } catch (e) { throw new InvalidDeclaration(e.message); }
+    const units = [];
+    const rest = [];
+    for (const it of items) {
+      if (it.kind === 'block' && it.type === 'resource') {
+        if (it.labels.length !== 2) throw new InvalidDeclaration(`line ${it.line}: a resource block needs a type and a name`);
+        const [type, name] = it.labels;
+        units.push({ type, name, address: `${type}.${name}`, tree: bodyToTree(it.body), typed: true });
+      } else rest.push(it);
+    }
+    if (rest.length) units.push({ type: null, name: null, address: null, tree: bodyToTree(rest), typed: false });
+    return units;
+  }
+  if (kind === 'terraform-json') {
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { throw new InvalidDeclaration(`not valid JSON: ${e.message}`); }
+    if (!doc || typeof doc !== 'object') throw new InvalidDeclaration('a .tf.json file must hold a JSON object');
+    const units = [];
+    each(doc, (top) => each(top.resource, (byType) => {
+      for (const [type, byName] of Object.entries(byType)) {
+        if (!/^[a-z0-9_]+$/.test(type)) continue;
+        each(byName, (names) => {
+          for (const [name, body] of Object.entries(names)) {
+            each(body, (b) => units.push({ type, name, address: `${type}.${name}`, tree: tfJsonValue(b), typed: true }));
+          }
+        });
+      }
+    }));
+    if (!Array.isArray(doc)) {
+      const rest = { ...doc }; delete rest.resource;
+      if (Object.keys(rest).length) units.push({ type: null, name: null, address: null, tree: tfJsonValue(rest), typed: false });
+    }
+    return units;
+  }
+  if (kind === 'terraform-plan') {
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { throw new InvalidDeclaration(`not valid JSON: ${e.message}`); }
+    const units = [];
+    const walkModule = (m) => {
+      if (!m || typeof m !== 'object') return;
+      for (const r of Array.isArray(m.resources) ? m.resources : []) {
+        if (r && r.mode !== 'data' && typeof r.type === 'string') {
+          units.push({ type: r.type, name: String(r.name ?? ''), address: r.address || `${r.type}.${r.name}`, tree: r.values ?? {}, typed: true, plan: true });
+        }
+      }
+      for (const c of Array.isArray(m.child_modules) ? m.child_modules : []) walkModule(c);
+    };
+    if (doc && doc.planned_values && doc.planned_values.root_module) walkModule(doc.planned_values.root_module);
+    else {
+      for (const rc of Array.isArray(doc && doc.resource_changes) ? doc.resource_changes : []) {
+        const after = rc && rc.change ? rc.change.after : null;
+        if (rc && rc.mode !== 'data' && typeof rc.type === 'string' && after) {
+          units.push({ type: rc.type, name: String(rc.name ?? ''), address: rc.address || `${rc.type}.${rc.name}`, tree: after, typed: true, plan: true });
+        }
+      }
+    }
+    return units;
+  }
+  if (kind === 'kubernetes') {
+    const docs = parseAllDocuments(text, { strict: true, uniqueKeys: true, prettyErrors: false });
+    const list = Array.isArray(docs) ? docs : [docs];
+    const units = [];
+    for (const d of list) {
+      if (d.errors && d.errors.length) throw new InvalidDeclaration(`not valid YAML: ${d.errors[0].message.split('\n')[0]}`);
+      const v = d.toJS({ maxAliasCount: 100 });
+      if (v === null || v === undefined) continue;
+      if (typeof v !== 'object' || Array.isArray(v)) throw new InvalidDeclaration('a Kubernetes document must be a mapping');
+      const k = typeof v.kind === 'string' && /^[A-Za-z][A-Za-z0-9]*$/.test(v.kind) ? v.kind : null;
+      if (!k || typeof v.apiVersion !== 'string') throw new InvalidDeclaration('a document in a Kubernetes file has no apiVersion and kind');
+      units.push({ type: k, name: v.metadata && v.metadata.name ? String(v.metadata.name) : null, address: null, tree: v, typed: true });
+    }
+    return units;
+  }
+  if (kind === 'container') {
+    return [{ type: null, name: null, address: null, tree: dockerfileTree(text), typed: false }];
+  }
+  throw new Error(`unknown kind ${kind}`);
+}
+
+/** A Dockerfile's ENV and ARG settings as a tree. Comment lines and line
+ *  continuations are handled; every other instruction declares nothing lint
+ *  counts. A value that uses $ is unresolved. */
+function dockerfileTree(text) {
+  const tree = {};
+  const logical = [];
+  let cur = '';
+  for (const raw of text.split(/\r?\n/)) {
+    if (/^\s*#/.test(raw) && !cur) continue;
+    if (/\\\s*$/.test(raw)) { cur += raw.replace(/\\\s*$/, ' '); continue; }
+    logical.push(cur + raw); cur = '';
+  }
+  if (cur) logical.push(cur);
+  const val = (s) => {
+    let v = s;
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    return /\$/.test(v) ? { $expr: v } : v;
+  };
+  for (const l of logical) {
+    const m = /^\s*(ENV|ARG)\s+(.*)$/i.exec(l);
+    if (!m) continue;
+    const rest = m[2].trim();
+    const pairs = rest.match(/[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)/g);
+    if (pairs && pairs.join(' ').length >= rest.replace(/\s+/g, ' ').length - pairs.length) {
+      for (const p of pairs) { const i = p.indexOf('='); tree[p.slice(0, i)] = val(p.slice(i + 1)); }
+    } else {
+      const sp = /^([A-Za-z_][A-Za-z0-9_]*)(?:\s+(.*))?$/.exec(rest);
+      if (sp) tree[sp[1]] = sp[2] !== undefined ? val(sp[2].trim()) : { $expr: `ARG ${sp[1]}` };
+    }
+  }
+  return tree;
+}
+
+/* ----------------------------------------------------------- reading ---- */
+
+/** Every (key, value) pair in a tree, depth first. */
+function* pairs(tree, parent = null) {
+  if (Array.isArray(tree)) { for (const x of tree) yield* pairs(x, parent); return; }
+  if (!tree || typeof tree !== 'object' || isExpr(tree)) return;
+  for (const [k, v] of Object.entries(tree)) {
+    yield [k, v, parent];
+    yield* pairs(v, k);
+  }
+}
+
+/** Every string (literal or expression source) in a tree. */
+function* strings(tree) {
+  if (typeof tree === 'string') { yield tree; return; }
+  if (isExpr(tree)) { yield tree.$expr; return; }
+  if (Array.isArray(tree)) { for (const x of tree) yield* strings(x); return; }
+  if (tree && typeof tree === 'object') for (const v of Object.values(tree)) yield* strings(v);
+}
+
+const REGION_KEY = /^(region|location|availability_zone|aws_region|aws_default_region|zone)$/i;
+const REGION_VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{2,40}$/;
+const SECRET_KEY = /(password|passwd|secret|api[_-]?key|access[_-]?key|token|private[_-]?key)/i;
+const OPEN_CIDRS = new Set(['0.0.0.0/0', '::/0']);
+
+export function regionsIn(tree) {
+  const found = [];
+  for (const [k, v] of pairs(tree)) if (REGION_KEY.test(k) && typeof v === 'string' && REGION_VALUE.test(v)) found.push(v);
+  return found;
+}
+
+/** A credential literal: a secret-named key holding a literal string of at
+ *  least eight characters. One count per key, wherever it sits in the file. */
+export function credentialLiterals(tree) {
+  let n = 0;
+  for (const [k, v] of pairs(tree)) {
+    if (!SECRET_KEY.test(k)) continue;
+    if (typeof v === 'string' && v.length >= 8 && !/[$%]\{/.test(v)) n++;
+  }
+  return n;
+}
+
+export function opensToAnyAddress(tree) {
+  for (const s of strings(tree)) if (OPEN_CIDRS.has(s.trim())) return true;
+  return false;
+}
+
+export function markedPublic(tree) {
+  for (const [k, v] of pairs(tree)) {
+    if ((k === 'publicly_accessible' || k === 'public_network_access_enabled' || k === 'associate_public_ip_address') && (v === true || v === 'true')) return true;
+    if (k === 'acl' && typeof v === 'string' && /^public-read/.test(v)) return true;
+    if (k === 'type' && (v === 'LoadBalancer' || v === 'NodePort')) return true;
+  }
+  return false;
+}
+
+/* -------------------------------------------------------- encryption ---- */
+
+// Keys whose value is the encryption switch itself.
+const BOOL_KEY = /^(encrypted|storage_encrypted|encrypt_at_rest|encryption_enabled|enable_encryption|encrypted_at_rest|at_rest_encryption_enabled|encryption_at_rest_enabled)$/i;
+// Keys that name the key or algorithm a store is encrypted with.
+const KEY_KEY = /^(kms_key_id|kms_key_arn|kms_key_name|kms_key|kms_master_key_id|kms_key_self_link|encryption_key|encryption_key_name|disk_encryption_set_id|key_vault_key_id|sse_algorithm|default_kms_key_name)$/i;
+// Blocks whose presence configures encryption, unless they switch it off.
+const BLOCK_KEY = /^(server_side_encryption_configuration|server_side_encryption|encryption_configuration|encryption_config|encryption|encryption_at_rest|apply_server_side_encryption_by_default|disk_encryption|customer_managed_key)$/i;
+// An expression that refers to a managed resource (aws_kms_key.main.arn) or a
+// data source names a key that exists in the configuration; a variable, a
+// local or anything else is unresolved.
+const RESOURCE_REF = /^\$?\{?\s*(?:data\.)?[a-z][a-z0-9]*_[a-z0-9_]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_]+\s*\}?$/;
+
+export const ENCRYPTION = Object.freeze({
+  TRUE: 'declared',
+  FALSE: 'declared_off',
+  ABSENT: 'not_declared',
+  UNRESOLVED: 'unresolved',
+  UNSUPPORTED: 'unsupported',
+});
+
+function boolState(v) {
+  if (v === true || v === 'true') return ENCRYPTION.TRUE;
+  if (v === false || v === 'false') return ENCRYPTION.FALSE;
+  if (isExpr(v)) return ENCRYPTION.UNRESOLVED;
+  if (v === null) return ENCRYPTION.ABSENT;
+  return ENCRYPTION.UNSUPPORTED;
+}
+
+function keyState(v) {
+  if (v === null || v === '' || v === false) return ENCRYPTION.ABSENT;
+  if (typeof v === 'string') return ENCRYPTION.TRUE;
+  if (isExpr(v)) {
+    const s = v.$expr.replace(/^"\$\{|\}"$/g, '').trim();
+    return RESOURCE_REF.test(s) ? ENCRYPTION.TRUE : ENCRYPTION.UNRESOLVED;
+  }
+  return ENCRYPTION.UNSUPPORTED;
+}
+
+function blockState(v) {
+  const blocks = Array.isArray(v) ? v : [v];
+  let state = ENCRYPTION.ABSENT;
+  for (const b of blocks) {
+    if (!b || typeof b !== 'object' || isExpr(b)) { if (isExpr(b)) state = state === ENCRYPTION.TRUE ? state : ENCRYPTION.UNRESOLVED; continue; }
+    if ('enabled' in b) {
+      const s = boolState(b.enabled);
+      if (s === ENCRYPTION.FALSE) return ENCRYPTION.FALSE;
+      if (s === ENCRYPTION.UNRESOLVED) { state = ENCRYPTION.UNRESOLVED; continue; }
+    }
+    if (state !== ENCRYPTION.UNRESOLVED) state = ENCRYPTION.TRUE;
+  }
+  return state;
+}
+
+/**
+ * What one store's tree declares about encryption at rest:
+ *   declared      an explicit true, a key, or an encryption block
+ *   declared_off  an explicit false (it wins over any other signal)
+ *   not_declared  nothing about encryption (a comment is nothing)
+ *   unresolved    decided by a variable, local or other expression
+ *   unsupported   a value lint does not interpret (a number for a switch)
+ * An explicit switch decides; keys and blocks decide only when no switch is set.
+ */
+export function encryptionState(tree) {
+  const sw = [], other = [];
+  for (const [k, v] of pairs(tree)) {
+    if (BOOL_KEY.test(k)) sw.push(boolState(v));
+    else if (KEY_KEY.test(k)) other.push(keyState(v));
+    else if (BLOCK_KEY.test(k) && v && typeof v === 'object') other.push(blockState(v));
+  }
+  const decide = (list) => {
+    if (list.includes(ENCRYPTION.FALSE)) return ENCRYPTION.FALSE;
+    if (list.includes(ENCRYPTION.UNRESOLVED)) return ENCRYPTION.UNRESOLVED;
+    if (list.includes(ENCRYPTION.UNSUPPORTED)) return ENCRYPTION.UNSUPPORTED;
+    if (list.includes(ENCRYPTION.TRUE)) return ENCRYPTION.TRUE;
+    return ENCRYPTION.ABSENT;
+  };
+  const s = decide(sw);
+  if (s !== ENCRYPTION.ABSENT) return s;
+  return decide(other);
+}
+
+/** Every string and expression source in a tree, joined, for finding a
+ *  reference to another resource's address. */
+export function referenceText(tree) {
+  return [...strings(tree)].join('\n');
+}

package/bin/lib/hcl.mjs

@@ -0,0 +1,294 @@
+// A strict reader for the HCL native syntax Terraform uses (.tf files).
+// Copyright 2025-2026 Trooth, LLC. Apache-2.0.
+//
+// WHY THIS EXISTS. Up to 0.4.4, `trooth lint` read .tf files with regular
+// expressions. A regular expression cannot tell a comment from a setting or an
+// indented block from a top-level one, and it cannot tell that a file is
+// malformed, so `encrypted = false # off` and `# encrypted = true` both counted
+// as declaring encryption and a broken file read as a successful one.
+//
+// This module tokenizes and parses the syntax into a tree. It does not
+// evaluate anything: a variable, a function call, a conditional or a reference
+// is kept as an UNRESOLVED EXPRESSION ({ $expr: "<source text>" }) and is never
+// promoted to a value. Comments are dropped by the tokenizer, so nothing inside
+// one can count. A file that does not parse throws HclParseError, and the
+// caller reports it as invalid rather than as read.
+//
+// Supported: attributes, blocks with any number of labels, nested blocks,
+// strings with escapes and ${ } / %{ } templates, heredocs (<<EOF and <<-EOF),
+// numbers, true/false/null, tuples [ ], objects { }, and any other expression
+// as unresolved source text. Not supported, and reported as unresolved rather
+// than guessed: for-expressions, splat values, function results, conditionals.
+
+export class HclParseError extends Error {
+  constructor(message, line) {
+    super(`line ${line}: ${message}`);
+    this.name = 'HclParseError';
+    this.line = line;
+  }
+}
+
+const isIdentStart = (ch) => /[A-Za-z_]/.test(ch);
+const isIdentChar = (ch) => /[A-Za-z0-9_-]/.test(ch);
+
+/** Source text to tokens. Comments are skipped; newlines are kept because they
+ *  end an attribute. Throws HclParseError on an unterminated string, comment or
+ *  heredoc, or a character the syntax does not allow. */
+export function tokenize(src) {
+  const toks = [];
+  let i = 0, line = 1;
+  const n = src.length;
+  const push = (t, v, extra) => toks.push({ t, v, line, ...extra });
+  while (i < n) {
+    const ch = src[i];
+    if (ch === '\n') { push('nl', '\n'); line++; i++; continue; }
+    if (ch === ' ' || ch === '\t' || ch === '\r' || ch === '') { i++; continue; }
+    if (ch === '#' || (ch === '/' && src[i + 1] === '/')) {
+      while (i < n && src[i] !== '\n') i++;
+      continue;
+    }
+    if (ch === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      if (end < 0) throw new HclParseError('unterminated /* comment', line);
+      for (let k = i; k < end; k++) if (src[k] === '\n') line++;
+      i = end + 2;
+      continue;
+    }
+    if (ch === '"') {
+      const startLine = line;
+      let j = i + 1, value = '', interp = false, depth = 0;
+      for (;;) {
+        if (j >= n) throw new HclParseError('unterminated string', startLine);
+        const c = src[j];
+        if (c === '\n' && depth === 0) throw new HclParseError('newline inside a quoted string', startLine);
+        if (c === '\n') line++;
+        if (c === '\\' && depth === 0) {
+          const e = src[j + 1];
+          const map = { n: '\n', t: '\t', r: '\r', '"': '"', '\\': '\\' };
+          if (e in map) { value += map[e]; j += 2; continue; }
+          if (e === 'u' || e === 'U') { value += '\\' + e; j += 2; continue; }
+          throw new HclParseError(`invalid escape \\${e}`, line);
+        }
+        if ((c === '$' || c === '%') && src[j + 1] === '{' && depth === 0) {
+          if (src[j - 1] === c && src[j - 2] !== c) { value += '{'; j += 2; continue; } // $${ escapes
+          interp = true; depth = 1; value += c + '{'; j += 2; continue;
+        }
+        if (depth > 0) {
+          if (c === '{') depth++;
+          else if (c === '}') depth--;
+          else if (c === '"') {
+            // a quoted string nested inside a template expression
+            let k = j + 1;
+            while (k < n && src[k] !== '"') { if (src[k] === '\\') k++; if (src[k] === '\n') throw new HclParseError('unterminated string', startLine); k++; }
+            if (k >= n) throw new HclParseError('unterminated string', startLine);
+            value += src.slice(j, k + 1); j = k + 1; continue;
+          }
+          value += c; j++; continue;
+        }
+        if (c === '"') break;
+        value += c; j++;
+      }
+      push('str', value, { interp, raw: src.slice(i, j + 1) });
+      i = j + 1;
+      continue;
+    }
+    if (ch === '<' && src[i + 1] === '<' && /[-A-Za-z_]/.test(src[i + 2] || '')) {
+      const m = /^<<(-?)([A-Za-z_][A-Za-z0-9_-]*)[ \t]*\r?\n/.exec(src.slice(i));
+      if (m) {
+        const startLine = line;
+        const marker = m[2];
+        let j = i + m[0].length;
+        line++;
+        const lines = [];
+        let closed = false;
+        while (j <= n) {
+          let e = src.indexOf('\n', j);
+          if (e < 0) e = n;
+          const l = src.slice(j, e).replace(/\r$/, '');
+          if (l.trim() === marker) { closed = true; j = e; break; }
+          lines.push(l);
+          if (e >= n) break;
+          line++;
+          j = e + 1;
+        }
+        if (!closed) throw new HclParseError(`unterminated heredoc <<${marker}`, startLine);
+        const value = lines.join('\n');
+        push('str', value, { interp: /[$%]\{/.test(value), raw: src.slice(i, j), heredoc: true });
+        i = j;
+        continue;
+      }
+    }
+    if (/[0-9]/.test(ch)) {
+      const m = /^[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(src.slice(i));
+      push('num', Number(m[0]), { raw: m[0] });
+      i += m[0].length;
+      continue;
+    }
+    if (isIdentStart(ch)) {
+      let j = i + 1;
+      while (j < n && isIdentChar(src[j])) j++;
+      push('ident', src.slice(i, j), { raw: src.slice(i, j) });
+      i = j;
+      continue;
+    }
+    const two = src.slice(i, i + 2);
+    if (['==', '!=', '<=', '>=', '&&', '||', '=>', '...'].includes(src.slice(i, i + 3)) || ['==', '!=', '<=', '>=', '&&', '||', '=>'].includes(two)) {
+      const op = src.slice(i, i + 3) === '...' ? '...' : two;
+      push('op', op, { raw: op }); i += op.length; continue;
+    }
+    if ('{}[]()=:,.?!+-*/%<>'.includes(ch)) { push(ch, ch, { raw: ch }); i++; continue; }
+    throw new HclParseError(`unexpected character ${JSON.stringify(ch)}`, line);
+  }
+  push('eof', '');
+  return toks;
+}
+
+const OPEN = { '{': '}', '[': ']', '(': ')' };
+
+class Parser {
+  constructor(toks) { this.toks = toks; this.p = 0; }
+  peek(k = 0) { return this.toks[this.p + k]; }
+  next() { return this.toks[this.p++]; }
+  skipNl() { while (this.peek().t === 'nl') this.p++; }
+  error(msg, tok = this.peek()) { throw new HclParseError(msg, tok.line); }
+
+  /** A body: attributes and blocks until `}` (nested) or end of file (top). */
+  body(nested) {
+    const items = [];
+    for (;;) {
+      this.skipNl();
+      const tok = this.peek();
+      if (tok.t === 'eof') { if (nested) this.error('unclosed block: a } is missing'); return items; }
+      if (tok.t === '}') { if (!nested) this.error('unexpected }'); this.next(); return items; }
+      if (tok.t !== 'ident') this.error(`expected an attribute or block name, found ${JSON.stringify(tok.v)}`);
+      const name = this.next().v;
+      if (this.peek().t === '=' ) {
+        this.next();
+        const exprToks = this.collectExpr(tok.line);
+        items.push({ kind: 'attr', key: name, value: exprValue(exprToks), line: tok.line });
+        continue;
+      }
+      const labels = [];
+      while (this.peek().t === 'str' || this.peek().t === 'ident') {
+        const l = this.next();
+        if (l.t === 'str' && l.interp) this.error('a block label cannot be a template', l);
+        labels.push(l.v);
+      }
+      if (this.peek().t !== '{') this.error(`expected = or { after ${name}`);
+      this.next();
+      const inner = this.body(true);
+      items.push({ kind: 'block', type: name, labels, body: inner, line: tok.line });
+      // a block ends at a newline or the end of the enclosing body
+      const after = this.peek().t;
+      if (after !== 'nl' && after !== 'eof' && after !== '}') this.error('expected a newline after a block');
+    }
+  }
+
+  /** The tokens of one expression, up to the newline that ends it at depth 0. */
+  collectExpr(line) {
+    const out = [];
+    const stack = [];
+    for (;;) {
+      const tok = this.peek();
+      if (tok.t === 'eof') {
+        if (stack.length) this.error(`unclosed ${stack[stack.length - 1]}`, tok);
+        break;
+      }
+      if (!stack.length && (tok.t === 'nl' || tok.t === '}')) break;
+      this.next();
+      if (OPEN[tok.t]) stack.push(OPEN[tok.t]);
+      else if (tok.t === '}' || tok.t === ']' || tok.t === ')') {
+        if (stack.pop() !== tok.t) this.error(`mismatched ${tok.t}`, tok);
+      }
+      out.push(tok);
+    }
+    const meaningful = out.filter((t) => t.t !== 'nl');
+    if (!meaningful.length) throw new HclParseError('an attribute has no value', line);
+    return out;
+  }
+}
+
+const sourceOf = (toks) => toks.filter((t) => t.t !== 'nl').map((t) => (t.raw !== undefined ? t.raw : String(t.v))).join(' ')
+  .replace(/ ?\. ?/g, '.').replace(/\[ /g, '[').replace(/ \]/g, ']').replace(/\( /g, '(').replace(/ \)/g, ')');
+
+/** Split tokens on a separator at depth 0 (commas and newlines inside a tuple
+ *  or object). */
+function splitTop(toks, isSep) {
+  const parts = [];
+  let cur = [], depth = 0;
+  for (const t of toks) {
+    if (OPEN[t.t]) depth++;
+    else if (t.t === '}' || t.t === ']' || t.t === ')') depth--;
+    if (depth === 0 && isSep(t)) { if (cur.some((x) => x.t !== 'nl')) parts.push(cur); cur = []; continue; }
+    cur.push(t);
+  }
+  if (cur.some((x) => x.t !== 'nl')) parts.push(cur);
+  return parts;
+}
+
+/** Tokens of an expression to a value. Literals become JS values; tuples and
+ *  objects become arrays and objects when every member parses; anything else
+ *  becomes { $expr: source }. Nothing is evaluated. */
+export function exprValue(toks) {
+  const ts = toks.filter((t) => t.t !== 'nl');
+  if (ts.length === 1) {
+    const t = ts[0];
+    if (t.t === 'ident') {
+      if (t.v === 'true') return true;
+      if (t.v === 'false') return false;
+      if (t.v === 'null') return null;
+      return { $expr: t.v };
+    }
+    if (t.t === 'num') return t.v;
+    if (t.t === 'str') return t.interp ? { $expr: t.raw } : t.v;
+  }
+  if (ts.length === 2 && ts[0].t === '-' && ts[1].t === 'num') return -ts[1].v;
+  const first = ts[0], last = ts[ts.length - 1];
+  if (first.t === '[' && last.t === ']' && closesAt(ts, 0) === ts.length - 1) {
+    const inner = toks.slice(toks.indexOf(first) + 1, toks.lastIndexOf(last));
+    if (inner.some((t) => t.t === 'ident' && t.v === 'for')) return { $expr: sourceOf(ts) };
+    return splitTop(inner, (t) => t.t === ',').map(exprValue);
+  }
+  if (first.t === '{' && last.t === '}' && closesAt(ts, 0) === ts.length - 1) {
+    const inner = toks.slice(toks.indexOf(first) + 1, toks.lastIndexOf(last));
+    if (inner.some((t) => t.t === 'ident' && t.v === 'for')) return { $expr: sourceOf(ts) };
+    const obj = {};
+    for (const member of splitTop(inner, (t) => t.t === ',' || t.t === 'nl')) {
+      const m = member.filter((t) => t.t !== 'nl');
+      const eq = m.findIndex((t) => t.t === '=' || t.t === ':');
+      if (eq !== 1 || !(m[0].t === 'ident' || (m[0].t === 'str' && !m[0].interp))) return { $expr: sourceOf(ts) };
+      obj[m[0].v] = exprValue(m.slice(2));
+    }
+    return obj;
+  }
+  return { $expr: sourceOf(ts) };
+}
+
+function closesAt(ts, start) {
+  let depth = 0;
+  for (let k = start; k < ts.length; k++) {
+    if (OPEN[ts[k].t]) depth++;
+    else if (ts[k].t === '}' || ts[k].t === ']' || ts[k].t === ')') { depth--; if (depth === 0) return k; }
+  }
+  return -1;
+}
+
+/** Parse a whole file. Returns the list of top-level items. */
+export function parseHcl(src) {
+  return new Parser(tokenize(src)).body(false);
+}
+
+/** A block's items as a plain object tree: attributes become keys, nested
+ *  blocks become objects (an array of them when a block type repeats). */
+export function bodyToTree(items) {
+  const tree = {};
+  for (const it of items) {
+    if (it.kind === 'attr') { tree[it.key] = it.value; continue; }
+    const v = bodyToTree(it.body);
+    const key = it.type;
+    if (key in tree) tree[key] = Array.isArray(tree[key]) && tree[`__blocks_${key}`] ? [...tree[key], v] : [tree[key], v];
+    else tree[key] = v;
+    if (Array.isArray(tree[key])) Object.defineProperty(tree, `__blocks_${key}`, { value: true, enumerable: false, configurable: true });
+  }
+  return tree;
+}