@o3co/ts.hocon 1.1.0 → 1.3.0

package/dist/index.cjs

@@ -43,6 +43,27 @@ module.exports = __toCommonJS(src_exports);
 
 // src/coerce.ts
 var DECIMAL_NUMBER_RE = /^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+function isHoconWs(cp) {
+  if (cp === 9 || cp === 10 || cp === 11 || cp === 12 || cp === 13) return true;
+  if (cp >= 28 && cp <= 31) return true;
+  if (cp === 32 || cp === 160 || cp === 65279) return true;
+  if (cp === 5760) return true;
+  if (cp >= 8192 && cp <= 8202) return true;
+  if (cp === 8232 || cp === 8233 || cp === 8239 || cp === 8287) return true;
+  if (cp === 12288) return true;
+  return false;
+}
+function trimHoconWs(s) {
+  let start = 0;
+  let end = s.length;
+  while (start < end && isHoconWs(s.charCodeAt(start))) {
+    start++;
+  }
+  while (end > start && isHoconWs(s.charCodeAt(end - 1))) {
+    end--;
+  }
+  return s.slice(start, end);
+}
 var TRUTHY = /* @__PURE__ */ new Set(["true", "yes", "on"]);
 var FALSY = /* @__PURE__ */ new Set(["false", "no", "off"]);
 function coerceBoolean(value) {
@@ -88,22 +109,29 @@ var OUTPUT_DURATION_UNITS = {
   d: 864e5
 };
 function parseDuration(value, outputUnit = "ms") {
-  const trimmed = value.trim();
+  const trimmed = trimHoconWs(value);
   let i = 0;
   while (i < trimmed.length) {
     const ch = trimmed[i];
-    if (ch !== "-" && ch !== "." && (ch < "0" || ch > "9")) break;
+    if (i === 0 && (ch === "-" || ch === "+")) {
+      i++;
+      continue;
+    }
+    if (ch !== "." && (ch < "0" || ch > "9")) break;
     i++;
   }
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimmed.slice(i).trim().toLowerCase();
+  const unit = trimHoconWs(trimmed.slice(i)).toLowerCase();
+  const divisor = OUTPUT_DURATION_UNITS[outputUnit];
+  if (divisor === void 0) return NaN;
+  if (unit === "") {
+    return num / divisor;
+  }
   const mult = DURATION_UNITS[unit];
   if (mult === void 0) return NaN;
   const ms = num * mult;
-  const divisor = OUTPUT_DURATION_UNITS[outputUnit];
-  if (divisor === void 0) return NaN;
   return ms / divisor;
 }
 var BYTE_UNITS = {
@@ -134,6 +162,22 @@ var BYTE_UNITS = {
   TiB: 1099511627776,
   tebibyte: 1099511627776,
   tebibytes: 1099511627776,
+  // S21.4 — HOCON.md L1385: single-letter abbreviations → powers of two (java -Xmx convention).
+  // Lightbend typesafe-config 1.4.3 verified: 1K=1024, 1M=1048576, etc.
+  // Both upper- and lowercase accepted per Lightbend behaviour.
+  // Z/Y (2^70/2^80) are deferred — they overflow MAX_SAFE_INTEGER and require BigInt accessor.
+  K: 1024,
+  k: 1024,
+  M: 1024 ** 2,
+  m: 1024 ** 2,
+  G: 1024 ** 3,
+  g: 1024 ** 3,
+  T: 1024 ** 4,
+  t: 1024 ** 4,
+  P: 1024 ** 5,
+  p: 1024 ** 5,
+  E: 1024 ** 6,
+  e: 1024 ** 6,
   // lowercase short-form aliases
   b: 1,
   kb: 1e3,
@@ -157,25 +201,39 @@ var OUTPUT_BYTE_UNITS = {
   TiB: 1099511627776
 };
 function parseBytes(value, outputUnit = "B") {
-  const trimmed = value.trim();
+  const trimmed = trimHoconWs(value);
   let i = 0;
   while (i < trimmed.length) {
     const ch = trimmed[i];
-    if (ch !== "-" && ch !== "." && (ch < "0" || ch > "9")) break;
+    if (i === 0 && (ch === "-" || ch === "+")) {
+      i++;
+      continue;
+    }
+    if (ch !== "." && (ch < "0" || ch > "9")) break;
     i++;
   }
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimmed.slice(i).trim();
+  const unit = trimHoconWs(trimmed.slice(i));
+  const divisor = OUTPUT_BYTE_UNITS[outputUnit];
+  if (divisor === void 0) return NaN;
+  if (unit === "") {
+    const bytes2 = Math.trunc(num);
+    if (Math.abs(bytes2) > Number.MAX_SAFE_INTEGER) {
+      throw new RangeError("byte size overflows representable range (max 2^53-1 bytes)");
+    }
+    return bytes2 / divisor;
+  }
   let mult = BYTE_UNITS[unit];
   if (mult === void 0) {
     mult = BYTE_UNITS[unit.toLowerCase()];
   }
   if (mult === void 0) return NaN;
   const bytes = num * mult;
-  const divisor = OUTPUT_BYTE_UNITS[outputUnit];
-  if (divisor === void 0) return NaN;
+  if (Math.abs(bytes) > Number.MAX_SAFE_INTEGER) {
+    throw new RangeError("byte size overflows representable range (max 2^53-1 bytes)");
+  }
   const result = bytes / divisor;
   return outputUnit === "B" ? Math.round(result) : result;
 }
@@ -208,6 +266,23 @@ var ConfigError = class extends Error {
   }
 };
 
+// src/value/numeric-array.ts
+function numericObjectToArray(value) {
+  if (value.kind !== "object") return null;
+  if (value.fields.size === 0) return null;
+  const canonicalInt = /^(0|[1-9][0-9]*)$/;
+  const eligible = [];
+  for (const [key, val] of value.fields) {
+    if (!canonicalInt.test(key)) continue;
+    const n = Number(key);
+    if (!Number.isInteger(n) || n > 2147483647) continue;
+    eligible.push({ n, v: val });
+  }
+  if (eligible.length === 0) return null;
+  eligible.sort((a, b) => a.n - b.n);
+  return eligible.map((e) => e.v);
+}
+
 // src/config.ts
 var Config = class _Config {
   constructor(root) {
@@ -250,6 +325,7 @@ var Config = class _Config {
     }
     const result = parseBytes(v.raw, unit);
     if (Number.isNaN(result)) throw new ConfigError(`invalid byte size at ${path2}: ${JSON.stringify(v.raw)}`, path2);
+    if (result < 0) throw new ConfigError(`byte size must be non-negative at ${path2}: ${JSON.stringify(v.raw)}`, path2);
     return result;
   }
   getConfig(path2) {
@@ -261,6 +337,10 @@ var Config = class _Config {
   getList(path2) {
     const v = this.lookupNode(path2);
     if (v === void 0) throw new ConfigError(`path not found: ${path2}`, path2);
+    if (v.kind === "object") {
+      const converted = numericObjectToArray(v);
+      if (converted !== null) return converted.map(hoconToJs);
+    }
     if (v.kind !== "array") throw new ConfigError(`expected array at ${path2}`, path2);
     return v.items.map(hoconToJs);
   }
@@ -373,6 +453,20 @@ function deepMergeHocon(receiver, fallback) {
 }
 
 // src/internal/lexer/lexer.ts
+function isHoconWhitespace(ch) {
+  const cp = ch.codePointAt(0) ?? -1;
+  if (cp === 9 || cp === 10 || cp === 11 || cp === 12 || cp === 13) return true;
+  if (cp >= 28 && cp <= 31) return true;
+  if (cp === 32 || cp === 160 || cp === 65279) return true;
+  if (cp === 5760) return true;
+  if (cp >= 8192 && cp <= 8202) return true;
+  if (cp === 8232 || cp === 8233 || cp === 8239 || cp === 8287) return true;
+  if (cp === 12288) return true;
+  return false;
+}
+function isHoconNewline(ch) {
+  return ch === "\n";
+}
 var SINGLE_CHAR_TOKENS = {
   "{": "lbrace",
   "}": "rbrace",
@@ -395,18 +489,18 @@ var Lexer = class {
     while (this.pos < this.input.length) {
       const sl = this.line, sc = this.col;
       const ch = this.peek();
-      if (ch === " " || ch === "	" || ch === "\r") {
-        this.advance();
-        this.hadSpace = true;
-        continue;
-      }
-      if (ch === "\n") {
+      if (isHoconNewline(ch)) {
         this.advance();
         if (this.tokens[this.tokens.length - 1]?.kind !== "newline") {
           this.push("newline", "\n", sl, sc);
         }
         continue;
       }
+      if (isHoconWhitespace(ch)) {
+        this.advance();
+        this.hadSpace = true;
+        continue;
+      }
       if (ch === "/" && this.peek(1) === "/") {
         while (this.pos < this.input.length && this.peek() !== "\n") this.advance();
         this.hadSpace = true;
@@ -436,16 +530,16 @@ var Lexer = class {
       if (ch === "$" && this.peek(1) === "{") {
         this.advance();
         this.advance();
-        const optional = this.peek() === "?";
-        if (optional) this.advance();
-        let path2 = "";
-        while (this.pos < this.input.length && this.peek() !== "}") {
-          if (this.peek() === "\n") throw new ParseError("unterminated substitution", sl, sc);
-          path2 += this.advance();
-        }
-        if (this.peek() !== "}") throw new ParseError("unterminated substitution", sl, sc);
-        this.advance();
-        this.push(optional ? "opt_subst" : "subst", path2.trim(), sl, sc);
+        const payload = this.parseSubstBody(sl, sc);
+        const value = payload.segments.map((s) => {
+          const t = s.text;
+          if (t === "" || t.includes(".") || t.includes(" ") || t.includes("	") || t.includes('"') || t.includes("\\") || t !== t.trim()) {
+            const escaped = t.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+            return `"${escaped}"`;
+          }
+          return t;
+        }).join(".");
+        this.pushSubst(payload, value, sl, sc);
         continue;
       }
       if (ch === '"' && this.peek(1) === '"' && this.peek(2) === '"') {
@@ -480,58 +574,7 @@ var Lexer = class {
       }
       if (ch === '"') {
         this.advance();
-        let value = "";
-        while (this.pos < this.input.length && this.peek() !== '"') {
-          if (this.peek() === "\n") throw new ParseError("unterminated string", sl, sc);
-          if (this.peek() === "\\") {
-            this.advance();
-            const esc = this.advance();
-            switch (esc) {
-              case "n":
-                value += "\n";
-                break;
-              case "t":
-                value += "	";
-                break;
-              case "r":
-                value += "\r";
-                break;
-              case '"':
-                value += '"';
-                break;
-              case "\\":
-                value += "\\";
-                break;
-              case "/":
-                value += "/";
-                break;
-              case "b":
-                value += "\b";
-                break;
-              case "f":
-                value += "\f";
-                break;
-              case "u": {
-                if (this.pos + 4 > this.input.length) {
-                  throw new ParseError("Invalid unicode escape: not enough characters", this.line, this.col);
-                }
-                const hex = this.input.slice(this.pos, this.pos + 4);
-                if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
-                  throw new ParseError(`Invalid unicode escape: \\u${hex}`, this.line, this.col);
-                }
-                value += String.fromCharCode(parseInt(hex, 16));
-                for (let i = 0; i < 4; i++) this.advance();
-                break;
-              }
-              default:
-                throw new ParseError(`Unknown escape sequence: \\${esc}`, this.line, this.col);
-            }
-          } else {
-            value += this.advance();
-          }
-        }
-        if (this.peek() !== '"') throw new ParseError("unterminated string", sl, sc);
-        this.advance();
+        const value = this.readQuotedStringBody(sl, sc);
         this.push("string", value, sl, sc, true);
         continue;
       }
@@ -565,22 +608,255 @@ var Lexer = class {
     this.tokens.push({ kind, value, line: l, col: c, isQuoted, precedingSpace: this.hadSpace });
     this.hadSpace = false;
   }
+  pushSubst(payload, value, l, c) {
+    this.tokens.push({ kind: "subst", value, line: l, col: c, isQuoted: false, precedingSpace: this.hadSpace, subst: payload });
+    this.hadSpace = false;
+  }
+  /**
+   * Read body of a quoted string. Opening `"` must already be consumed.
+   * Returns decoded string. Throws ParseError on unterminated/invalid-escape.
+   * openLine/openCol are the position of the opening `"` for error reporting.
+   */
+  readQuotedStringBody(openLine, openCol) {
+    let value = "";
+    while (this.pos < this.input.length && this.peek() !== '"') {
+      if (this.peek() === "\n") throw new ParseError("unterminated string", openLine, openCol);
+      if (this.peek() === "\\") {
+        const escCol = this.col;
+        this.advance();
+        if (this.pos >= this.input.length) {
+          throw new ParseError("unterminated string", openLine, openCol);
+        }
+        const esc = this.advance();
+        switch (esc) {
+          case "n":
+            value += "\n";
+            break;
+          case "t":
+            value += "	";
+            break;
+          case "r":
+            value += "\r";
+            break;
+          case '"':
+            value += '"';
+            break;
+          case "\\":
+            value += "\\";
+            break;
+          case "/":
+            value += "/";
+            break;
+          case "b":
+            value += "\b";
+            break;
+          case "f":
+            value += "\f";
+            break;
+          case "u": {
+            if (this.pos + 4 > this.input.length) {
+              throw new ParseError("invalid unicode escape", openLine, escCol);
+            }
+            const hex = this.input.slice(this.pos, this.pos + 4);
+            if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+              throw new ParseError("invalid unicode escape", openLine, escCol);
+            }
+            const code = parseInt(hex, 16);
+            value += String.fromCharCode(code);
+            for (let i = 0; i < 4; i++) this.advance();
+            break;
+          }
+          default:
+            throw new ParseError(`unknown escape sequence: \\${esc}`, openLine, escCol);
+        }
+      } else {
+        value += this.advance();
+      }
+    }
+    if (this.pos >= this.input.length || this.peek() !== '"') {
+      throw new ParseError("unterminated string", openLine, openCol);
+    }
+    this.advance();
+    return value;
+  }
+  /**
+   * Parse the body of a `${...}` substitution (called after `${` has been consumed).
+   * Implements Appendix A state machine from the cross-language spec.
+   *
+   * S13c extension: if the segment-collection loop encounters `[`, it delegates to
+   * `parseListSuffix()` which consumes the literal `[]` and sets `listSuffix=true`.
+   * ASCII space/tab before `[` is buffered in `pendingWs` and discarded (E7).
+   */
+  parseSubstBody(startLine, startCol) {
+    let optional = false;
+    if (this.peek() === "?") {
+      this.advance();
+      optional = true;
+    }
+    let curText = "";
+    let curStarted = false;
+    let curLine = 0;
+    let curCol = 0;
+    let pendingWs = "";
+    const segments = [];
+    let lastDot = null;
+    let listSuffix = false;
+    while (true) {
+      if (this.pos >= this.input.length) {
+        throw new ParseError("unterminated substitution", startLine, startCol);
+      }
+      const ch = this.peek();
+      if (ch === "}") {
+        this.advance();
+        pendingWs = "";
+        break;
+      } else if (ch === "[") {
+        if (!curStarted) {
+          throw new ParseError("empty segment before '[]' suffix in substitution path", startLine, this.col);
+        }
+        for (const w of pendingWs) {
+          if (w !== " " && w !== "	") {
+            throw new ParseError(
+              `only ASCII space or tab allowed between substitution path and '[]' suffix (got ${JSON.stringify(w)}, HOCON extra-spec E7)`,
+              startLine,
+              this.col
+            );
+          }
+        }
+        segments.push({ text: curText, line: curLine, col: curCol });
+        pendingWs = "";
+        listSuffix = this.parseListSuffix(startLine);
+        break;
+      } else if (ch === '"') {
+        const qLine = startLine;
+        const qCol = this.col;
+        if (curStarted) {
+          curText += pendingWs;
+        }
+        pendingWs = "";
+        this.advance();
+        const decoded = this.readQuotedStringBody(qLine, qCol);
+        curText += decoded;
+        if (!curStarted) {
+          curLine = qLine;
+          curCol = qCol;
+          curStarted = true;
+        }
+      } else if (isUnquotedSubstChar(ch)) {
+        if (ch === "-" && !curStarted && !isDecimalDigit(this.peek(1))) {
+          const after = this.peek(1) === "" ? "EOF" : JSON.stringify(this.peek(1));
+          throw new ParseError(
+            `unquoted path segment cannot begin with '-' unless followed by a digit (got '-' then ${after}, HOCON.md L270-276)`,
+            startLine,
+            this.col
+          );
+        }
+        const uCol = this.col;
+        if (curStarted) {
+          curText += pendingWs;
+        }
+        pendingWs = "";
+        if (!curStarted) {
+          curLine = startLine;
+          curCol = uCol;
+          curStarted = true;
+        }
+        while (this.pos < this.input.length && isUnquotedSubstChar(this.peek())) {
+          curText += this.advance();
+        }
+      } else if (ch === ".") {
+        const dotCol = this.col;
+        pendingWs = "";
+        if (!curStarted) {
+          throw new ParseError("empty segment in path", startLine, dotCol);
+        }
+        segments.push({ text: curText, line: curLine, col: curCol });
+        curText = "";
+        curStarted = false;
+        curLine = 0;
+        curCol = 0;
+        lastDot = [startLine, dotCol];
+        this.advance();
+      } else if (isHoconNewline(ch)) {
+        throw new ParseError("unterminated substitution", startLine, startCol);
+      } else if (isHoconWhitespace(ch)) {
+        pendingWs += ch;
+        this.advance();
+      } else {
+        throw new ParseError(`unexpected character in substitution path: ${JSON.stringify(ch)}`, startLine, this.col);
+      }
+    }
+    if (!listSuffix) {
+      if (curStarted) {
+        segments.push({ text: curText, line: curLine, col: curCol });
+      } else if (segments.length === 0) {
+        throw new ParseError("empty substitution path", startLine, startCol);
+      } else {
+        const [errLine, errCol] = lastDot ?? [startLine, startCol];
+        throw new ParseError("empty segment in path", errLine, errCol);
+      }
+    }
+    return { segments, optional, listSuffix };
+  }
+  /**
+   * Consume the literal `[]` suffix inside a substitution body.
+   * Called after the `[` has been detected (but not yet consumed).
+   * Requires the next character to be `[`, then exactly `]`, then `}`.
+   * Whitespace inside `[]` is not permitted (per spec Decision §1).
+   * Returns true (always — only called when listSuffix path is taken).
+   */
+  parseListSuffix(startLine) {
+    this.advance();
+    const afterBracket = this.peek();
+    if (afterBracket !== "]") {
+      const desc = afterBracket === "" ? "EOF" : JSON.stringify(afterBracket);
+      throw new ParseError(
+        `expected ']' after '[' in substitution list suffix (got ${desc})`,
+        startLine,
+        this.col
+      );
+    }
+    this.advance();
+    if (this.peek() !== "}") {
+      const desc = this.peek() === "" ? "EOF" : JSON.stringify(this.peek());
+      throw new ParseError(
+        `expected '}' after '[]' in substitution list suffix (got ${desc})`,
+        startLine,
+        this.col
+      );
+    }
+    this.advance();
+    return true;
+  }
 };
 function tokenize(input) {
   return new Lexer(input).tokenize();
 }
+function isUnquotedSubstChar(ch) {
+  if (ch === "" || isHoconWhitespace(ch)) return false;
+  if ('"\\'.includes(ch)) return false;
+  if ("{}[]".includes(ch)) return false;
+  if (":=,+#`^?!@*&$.".includes(ch)) return false;
+  return true;
+}
+function isDecimalDigit(ch) {
+  return ch >= "0" && ch <= "9";
+}
 function isUnquotedStart(ch) {
-  return ch !== "" && !'{}[],:=+#\n\r	 "$?!@*&^\\'.includes(ch);
+  if (ch === "" || isHoconWhitespace(ch)) return false;
+  if ('{}[],:=+#"$?!@*&^\\'.includes(ch)) return false;
+  return true;
 }
 function isUnquotedContinue(ch, nextFn) {
-  if (ch === "" || '{}[],:=\n\r	 #"$?!@*&^\\'.includes(ch) || ch === " ") return false;
+  if (ch === "" || isHoconWhitespace(ch)) return false;
+  if ('{}[],:=#"$?!@*&^\\'.includes(ch)) return false;
   if (ch === "+" && nextFn() === "=") return false;
   if (ch === "/" && nextFn() === "/") return false;
   return true;
 }
 
 // src/internal/parser/parser.ts
-var EOF_TOKEN = { kind: "eof", value: "", line: 0, col: 0, isQuoted: false, precedingSpace: false };
+var EOF_TOKEN = { kind: "eof", value: "", line: 0, col: 0, isQuoted: false, precedingSpace: false, subst: void 0 };
 var Parser = class {
   constructor(tokens) {
     this.tokens = tokens;
@@ -638,6 +914,14 @@ var Parser = class {
       const t = this.peek();
       if (t.kind === "eof" || t.kind === "rbrace") break;
       if (t.kind === "unquoted" && t.value === "include") {
+        const next = this.peek(1);
+        if (next.kind === "equals" || next.kind === "colon" || next.kind === "plus_equals" || next.kind === "lbrace") {
+          throw new ParseError(
+            `'include' is reserved at the start of a key path expression; use "include" (quoted) to use it as a key`,
+            t.line,
+            t.col
+          );
+        }
         this.advance();
         fields.push(this.parseInclude());
         this.skip("newline");
@@ -646,7 +930,14 @@ var Parser = class {
         continue;
       }
       const keyPos = this.currentPos();
-      const key = this.parseKey();
+      const { segments: key, firstWasQuoted } = this.parseKey();
+      if (key[0] === "include" && !firstWasQuoted) {
+        throw new ParseError(
+          `'include' is reserved at the start of a key path expression; use "include".foo (quoted) or rename the key`,
+          keyPos.line,
+          keyPos.col
+        );
+      }
       this.skip("newline");
       let append = false;
       const sep = this.peek();
@@ -676,18 +967,31 @@ var Parser = class {
   parseKey() {
     const segments = [];
     let trailingDot = false;
+    let firstWasQuoted = false;
     while (true) {
       const t = this.peek();
       if (t.kind === "string") {
         this.advance();
+        if (segments.length === 0) firstWasQuoted = true;
         segments.push(t.value);
         trailingDot = false;
       } else if (t.kind === "unquoted") {
         this.advance();
-        const parts = t.value.split(".");
+        const raw = t.value.startsWith(".") && segments.length > 0 && !t.precedingSpace ? t.value.slice(1) : t.value;
+        const parts = raw.split(".");
         const filtered = parts.filter((s) => s.length > 0);
+        for (const seg of filtered) {
+          if (seg[0] === "-" && !(seg.length >= 2 && seg[1] >= "0" && seg[1] <= "9")) {
+            const after = seg.length >= 2 ? JSON.stringify(seg[1]) : "EOF";
+            throw new ParseError(
+              `unquoted key segment cannot begin with '-' unless followed by a digit (got '-' then ${after} in ${JSON.stringify(seg)}, HOCON.md L270-276)`,
+              t.line,
+              t.col
+            );
+          }
+        }
         segments.push(...filtered);
-        trailingDot = t.value.endsWith(".");
+        trailingDot = raw.endsWith(".");
       } else {
         if (segments.length === 0) throw new ParseError(`expected key, got ${t.kind}`, t.line, t.col);
         break;
@@ -699,9 +1003,13 @@ var Parser = class {
         trailingDot = true;
         continue;
       }
+      if (next.kind === "unquoted" && next.value.startsWith(".") && !next.precedingSpace) {
+        trailingDot = true;
+        continue;
+      }
       break;
     }
-    return segments;
+    return { segments, firstWasQuoted };
   }
   parseInclude() {
     const p = this.currentPos();
@@ -774,9 +1082,13 @@ var Parser = class {
       } else if (t.kind === "lbracket") {
         this.advance();
         node = this.parseArray();
-      } else if (t.kind === "subst" || t.kind === "opt_subst") {
+      } else if (t.kind === "subst") {
         this.advance();
-        node = { kind: "subst", path: t.value, optional: t.kind === "opt_subst", pos: { line: t.line, col: t.col } };
+        if (!t.subst) {
+          throw new ParseError(`internal: subst token missing payload`, t.line, t.col);
+        }
+        const payload = t.subst;
+        node = { kind: "subst", segments: payload.segments, optional: payload.optional, listSuffix: payload.listSuffix, pos: { line: t.line, col: t.col } };
       } else if (t.kind === "string" || t.kind === "triple_string") {
         this.advance();
         node = { kind: "scalar", raw: t.value, valueType: "string", pos: { line: t.line, col: t.col } };
@@ -827,6 +1139,20 @@ function parseTokens(tokens) {
   return new Parser(tokens).parse();
 }
 
+// src/internal/parser/empty-check.ts
+function hasContentTokens(tokens) {
+  return tokens.some((t) => t.kind !== "eof" && t.kind !== "newline");
+}
+function assertNonEmptyDocument(tokens, sourceDescriptor) {
+  if (!hasContentTokens(tokens)) {
+    throw new ParseError(
+      `empty file is not a valid HOCON document (HOCON.md L130): ${sourceDescriptor}`,
+      1,
+      1
+    );
+  }
+}
+
 // src/internal/resolver/types.ts
 var separatorValues = /* @__PURE__ */ new WeakSet();
 function isSubst(v) {
@@ -846,64 +1172,20 @@ function makeResObj() {
 }
 
 // src/internal/resolver/utils.ts
-function parseSubstPath(raw) {
-  const segments = [];
-  let i = 0;
-  while (i < raw.length) {
-    while (i < raw.length && (raw[i] === " " || raw[i] === "	")) i++;
-    if (i >= raw.length) break;
-    if (raw[i] === '"') {
-      i++;
-      let seg = "";
-      while (i < raw.length && raw[i] !== '"') {
-        if (raw[i] === "\\" && i + 1 < raw.length && (raw[i + 1] === '"' || raw[i + 1] === "\\")) {
-          seg += raw[i + 1];
-          i += 2;
-        } else {
-          seg += raw[i];
-          i++;
-        }
-      }
-      if (i < raw.length) i++;
-      segments.push(seg);
-      while (i < raw.length && (raw[i] === " " || raw[i] === "	")) i++;
-      if (i < raw.length && raw[i] === ".") i++;
-    } else if (raw[i] === ".") {
-      segments.push("");
-      i++;
-    } else {
-      let seg = "";
-      while (i < raw.length && raw[i] !== ".") {
-        seg += raw[i];
-        i++;
-      }
-      segments.push(seg.trim());
-      if (i < raw.length && raw[i] === ".") i++;
-    }
-  }
-  return segments;
-}
 function segmentsToKey(segments) {
   return segments.map((s) => {
-    if (s === "" || /[^a-zA-Z0-9\-_]/.test(s)) {
-      return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    const t = s.text;
+    if (t === "" || /[^a-zA-Z0-9\-_]/.test(t)) {
+      return `"${t.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
     }
-    return s;
+    return t;
   }).join(".");
 }
 function lookupPath(root, segments) {
   const [head, ...tail] = segments;
-  if (head === void 0 || head === "") {
-    if (segments.length > 0) {
-      const val2 = root.fields.get("");
-      if (val2 === void 0) return void 0;
-      if (tail.length === 0) return val2;
-      if (isResObj(val2)) return lookupPath(val2, tail);
-      return void 0;
-    }
-    return void 0;
-  }
-  const val = root.fields.get(head);
+  if (head === void 0) return void 0;
+  const key = head.text;
+  const val = root.fields.get(key);
   if (val === void 0) return void 0;
   if (tail.length === 0) return val;
   if (isResObj(val)) return lookupPath(val, tail);
@@ -912,7 +1194,7 @@ function lookupPath(root, segments) {
 function lookupResObj(root, segments) {
   let cur = root;
   for (const seg of segments) {
-    const val = cur.fields.get(seg);
+    const val = cur.fields.get(seg.text);
     if (val === void 0 || !isResObj(val)) return void 0;
     cur = val;
   }
@@ -972,6 +1254,7 @@ var nodePath = __toESM(require("path"), 1);
 // src/internal/properties/properties.ts
 function parseProperties(input) {
   const root = /* @__PURE__ */ Object.create(null);
+  const pairs = [];
   for (const line of input.split("\n")) {
     const trimmed = line.trim();
     if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("!")) continue;
@@ -980,6 +1263,10 @@ function parseProperties(input) {
     const key = trimmed.slice(0, sepIdx).trim();
     const value = trimmed.slice(sepIdx + 1).trim();
     if (key === "") continue;
+    pairs.push([key, value]);
+  }
+  pairs.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  for (const [key, value] of pairs) {
     setNested(root, key.split("."), value);
   }
   return root;
@@ -1003,6 +1290,7 @@ function setNested(obj, segments, value) {
   }
   const last = segments[segments.length - 1];
   if (last === void 0 || DANGEROUS_KEYS.has(last)) return;
+  if (typeof current[last] === "object" && current[last] !== null) return;
   current[last] = value;
 }
 function propertiesToHoconValue(input) {
@@ -1116,7 +1404,9 @@ var IncludeLoader = class {
     if (candidate.endsWith(".properties")) {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
-    const ast = parseTokens(tokenize(content));
+    const tokens = tokenize(content);
+    assertNonEmptyDocument(tokens, candidate);
+    const ast = parseTokens(tokens);
     return this.onBuildResObj(ast, {
       env,
       baseDir: nodePath.dirname(candidate),
@@ -1140,7 +1430,9 @@ var IncludeLoader = class {
     if (candidate.endsWith(".properties")) {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
-    const ast = parseTokens(tokenize(content));
+    const tokens = tokenize(content);
+    assertNonEmptyDocument(tokens, candidate);
+    const ast = parseTokens(tokens);
     return this.onBuildResObjAsync(ast, {
       env,
       baseDir: nodePath.dirname(candidate),
@@ -1189,7 +1481,7 @@ var StructureBuilder = class _StructureBuilder {
       return;
     }
     const [head, ...tail] = field.key;
-    if (!head) return;
+    if (head === void 0) return;
     if (tail.length > 0) {
       const syntheticAst = {
         kind: "object",
@@ -1231,7 +1523,7 @@ var StructureBuilder = class _StructureBuilder {
       return;
     }
     const [head, ...tail] = field.key;
-    if (!head) return;
+    if (head === void 0) return;
     if (tail.length > 0) {
       const syntheticAst = {
         kind: "object",
@@ -1277,9 +1569,9 @@ var StructureBuilder = class _StructureBuilder {
         return inner;
       }
       case "subst":
-        return { _kind: "subst-placeholder", segments: parseSubstPath(ast.path), optional: ast.optional, line: ast.pos.line, col: ast.pos.col, prefixLen: 0 };
+        return { _kind: "subst-placeholder", segments: ast.segments, optional: ast.optional, listSuffix: ast.listSuffix, line: ast.pos.line, col: ast.pos.col, prefixLen: 0 };
       case "concat":
-        return { _kind: "concat-placeholder", nodes: ast.nodes.map((n) => this.astToResolverValue(n, pathPrefix)) };
+        return { _kind: "concat-placeholder", nodes: ast.nodes.map((n) => this.astToResolverValue(n, pathPrefix)), line: ast.pos.line, col: ast.pos.col };
       case "include":
         return { kind: "scalar", raw: "null", valueType: "null" };
     }
@@ -1301,13 +1593,13 @@ var StructureBuilder = class _StructureBuilder {
       case "object":
         return await this.buildAsync(ast, pathPrefix);
       case "subst":
-        return { _kind: "subst-placeholder", segments: parseSubstPath(ast.path), optional: ast.optional, line: ast.pos.line, col: ast.pos.col, prefixLen: 0 };
+        return { _kind: "subst-placeholder", segments: ast.segments, optional: ast.optional, listSuffix: ast.listSuffix, line: ast.pos.line, col: ast.pos.col, prefixLen: 0 };
       case "concat": {
         const nodes = [];
         for (const n of ast.nodes) {
           nodes.push(await this.astToResolverValueAsync(n, pathPrefix));
         }
-        return { _kind: "concat-placeholder", nodes };
+        return { _kind: "concat-placeholder", nodes, line: ast.pos.line, col: ast.pos.col };
       }
       case "include":
         return { kind: "scalar", raw: "null", valueType: "null" };
@@ -1316,7 +1608,8 @@ var StructureBuilder = class _StructureBuilder {
   // ---- Relativize substitution paths for nested includes ----
   relativizeSubstPaths(val, prefixSegments) {
     if (isSubst(val)) {
-      val.segments = [...prefixSegments, ...val.segments];
+      const prefixAsSegments = prefixSegments.map((text) => ({ text, line: 0, col: 0 }));
+      val.segments = [...prefixAsSegments, ...val.segments];
       val.prefixLen += prefixSegments.length;
       return;
     }
@@ -1359,6 +1652,19 @@ var SubstitutionResolver = class {
     this.opts = opts;
     this.resolving = /* @__PURE__ */ new Set();
     this.cache = /* @__PURE__ */ new Map();
+    // Tracks ConcatPlaceholder nodes currently being iterated by resolveConcat.
+    // Used by isSelfRef detection: fires only when found === a concat currently
+    // mid-iteration (i.e. we are inside found's own resolution), preventing the
+    // "foofoo" double-count without misfiring when an external field looks up the
+    // same concat via a substitution (multi-reviewer convergence fix).
+    //
+    // Spec deviation: the S13a.13 spec ★1 decision #1 specified path-equality
+    // preservation for self-ref detection. Round-2 multi-agent-review surfaced a
+    // false-positive on external lookups (`a = ${?a}foo; b = ${a}`), so the
+    // criterion was tightened to node-membership-in-iterating-set — strictly
+    // narrower than path-equality. Spec amendment deferred to a follow-up
+    // xx.hocon PR (see Phase 6 #3f close-out notes).
+    this.resolvingConcats = /* @__PURE__ */ new WeakSet();
   }
   resolve() {
     return this.resolveResObj(this.root);
@@ -1397,7 +1703,14 @@ var SubstitutionResolver = class {
   }
   resolveVal(v, scope) {
     if (isSubst(v)) return this.resolveSubst(v, scope);
-    if (isConcat(v)) return this.resolveConcat(v.nodes, scope);
+    if (isConcat(v)) {
+      this.resolvingConcats.add(v);
+      try {
+        return this.resolveConcat(v.nodes, scope, v.line, v.col);
+      } finally {
+        this.resolvingConcats.delete(v);
+      }
+    }
     if (isAppend(v)) return this.resolveAppend(v, scope);
     if (isResObj(v)) return this.resolveResObj(v);
     const hv = v;
@@ -1411,23 +1724,20 @@ var SubstitutionResolver = class {
     }
     return hv;
   }
-  segmentsEqual(a, b) {
-    return a.length === b.length && a.every((seg, i) => seg === b[i]);
-  }
   resolveSubst(s, scope) {
-    const key = segmentsToKey(s.segments);
+    const key = s.listSuffix ? `${segmentsToKey(s.segments)}[]` : segmentsToKey(s.segments);
     if (this.cache.has(key)) return this.cache.get(key);
     if (this.resolving.has(key)) {
       let prior;
-      if (s.prefixLen > 0) {
-        const leafSeg = s.segments[s.segments.length - 1] ?? "";
+      if (s.segments.length > 1) {
+        const leafSeg = s.segments[s.segments.length - 1]?.text ?? "";
         const parentScope = lookupResObj(
           this.root,
           s.segments.slice(0, s.segments.length - 1)
         );
         prior = parentScope?.priorValues.get(leafSeg);
       } else {
-        const rootSeg = s.segments[0] ?? "";
+        const rootSeg = s.segments[0]?.text ?? "";
         prior = scope.priorValues.get(rootSeg) ?? this.root.priorValues.get(rootSeg);
       }
       if (prior !== void 0) {
@@ -1451,34 +1761,36 @@ var SubstitutionResolver = class {
     try {
       const found = lookupPath(this.root, s.segments);
       if (found !== void 0) {
-        if (isSubst(found) || isConcat(found)) {
-          const isSelfRef = isSubst(found) ? this.segmentsEqual(found.segments, s.segments) : isConcat(found) && found.nodes.some(
-            (n) => isSubst(n) && this.segmentsEqual(n.segments, s.segments)
-          );
-          if (isSelfRef) {
-            let prior;
-            if (s.prefixLen > 0) {
-              const leafSeg = s.segments[s.segments.length - 1] ?? "";
-              const parentScope = lookupResObj(
-                this.root,
-                s.segments.slice(0, s.segments.length - 1)
-              );
-              prior = parentScope?.priorValues.get(leafSeg);
-            } else {
-              const rootSeg = s.segments[0] ?? "";
-              prior = scope.priorValues.get(rootSeg) ?? this.root.priorValues.get(rootSeg);
-            }
-            if (prior !== void 0) {
-              const result2 = this.resolveVal(prior, scope);
-              if (result2 !== void 0) this.cache.set(key, result2);
-              return result2;
-            }
+        if (isConcat(found) && this.resolvingConcats.has(found)) {
+          let prior;
+          if (s.segments.length > 1) {
+            const leafSeg = s.segments[s.segments.length - 1]?.text ?? "";
+            const parentScope = lookupResObj(
+              this.root,
+              s.segments.slice(0, s.segments.length - 1)
+            );
+            prior = parentScope?.priorValues.get(leafSeg);
+          } else {
+            const rootSeg = s.segments[0]?.text ?? "";
+            prior = scope.priorValues.get(rootSeg) ?? this.root.priorValues.get(rootSeg);
+          }
+          if (prior !== void 0) {
+            const result2 = this.resolveVal(prior, scope);
+            if (result2 !== void 0) this.cache.set(key, result2);
+            return result2;
           }
+          if (s.optional) return void 0;
+          throw new ResolveError(
+            `could not resolve substitution: \${${key}}`,
+            key,
+            s.line,
+            s.col
+          );
         }
         let result = this.resolveVal(found, scope);
         const effectiveLen = s.segments.length - s.prefixLen;
         if (effectiveLen === 1 && result !== void 0 && result.kind === "object") {
-          const leafSeg = s.segments[s.segments.length - 1] ?? "";
+          const leafSeg = s.segments[s.segments.length - 1]?.text ?? "";
           let prior;
           if (s.prefixLen > 0) {
             const parentScope = lookupResObj(
@@ -1502,8 +1814,23 @@ var SubstitutionResolver = class {
         if (result !== void 0) this.cache.set(key, result);
         return result;
       }
-      const envKey = s.segments.join(".");
-      const envVal = this.opts.env[envKey] ?? (s.prefixLen > 0 ? this.opts.env[s.segments.slice(s.prefixLen).join(".")] : void 0);
+      if (s.listSuffix) {
+        const result = this.resolveEnvList(s);
+        if (result !== void 0) {
+          this.cache.set(key, result);
+          return result;
+        }
+        if (s.optional) return void 0;
+        const envBase = s.segments.map((seg) => seg.text).join(".");
+        throw new ResolveError(
+          `could not resolve substitution: \${${key}} (no environment variables ${envBase}_0, ${envBase}_1, \u2026 set)`,
+          key,
+          s.line,
+          s.col
+        );
+      }
+      const envKey = s.segments.map((seg) => seg.text).join(".");
+      const envVal = this.opts.env[envKey] ?? (s.prefixLen > 0 ? this.opts.env[s.segments.slice(s.prefixLen).map((seg) => seg.text).join(".")] : void 0);
       if (envVal !== void 0) {
         const result = { kind: "scalar", raw: envVal, valueType: "string" };
         this.cache.set(key, result);
@@ -1520,37 +1847,106 @@ var SubstitutionResolver = class {
       this.resolving.delete(key);
     }
   }
-  resolveConcat(nodes, scope) {
+  /**
+   * S13c: scan environment for NAME_0, NAME_1, … and return an Array<Scalar(String)>.
+   *
+   * Candidate bases follow the same fully-qualified→bare order used by the scalar
+   * env fallback. The first base whose _0 key is present wins entirely — no
+   * cross-base merging (spec §Relativized fallback precedence rules).
+   *
+   * Returns the HoconValue Array if any candidate base has _0, or undefined if
+   * none do (caller applies optional/required handling).
+   */
+  resolveEnvList(s) {
+    const bases = this.candidateBases(s);
+    for (const base of bases) {
+      const key0 = base + "_0";
+      if (!(key0 in this.opts.env)) continue;
+      const items = [];
+      for (let i = 0; ; i++) {
+        const k = base + "_" + i;
+        if (!(k in this.opts.env)) break;
+        items.push({ kind: "scalar", raw: this.opts.env[k], valueType: "string" });
+      }
+      return { kind: "array", items };
+    }
+    return void 0;
+  }
+  /**
+   * Return the candidate base names for env-var-list lookup, in precedence order.
+   * Mirrors the fully-qualified→bare fallback used by the scalar env path.
+   */
+  candidateBases(s) {
+    const full = s.segments.map((seg) => seg.text).join(".");
+    if (s.prefixLen === 0) return [full];
+    const bare = s.segments.slice(s.prefixLen).map((seg) => seg.text).join(".");
+    return [full, bare];
+  }
+  resolveConcat(nodes, scope, line = 0, col = 0) {
     const resolved = nodes.map((n) => this.resolveVal(n, scope)).filter((v) => v !== void 0);
     if (resolved.length === 0) return { kind: "scalar", raw: "null", valueType: "null" };
     if (resolved.length === 1) return resolved[0];
     const nonSep = resolved.filter((v) => !separatorValues.has(v));
-    if (nonSep.length > 0 && nonSep.every((v) => v.kind === "object")) {
-      const merged = /* @__PURE__ */ new Map();
-      for (const v of nonSep) {
-        if (v.kind === "object") {
-          for (const [k, val] of v.fields) {
-            const existing = merged.get(k);
-            if (existing?.kind === "object" && val.kind === "object") {
-              merged.set(k, deepMergeHoconValues(existing, val));
-            } else {
-              merged.set(k, val);
-            }
-          }
+    if (nonSep.length === 0) {
+      const str = resolved.map((v) => v.kind === "scalar" ? v.raw : JSON.stringify(v)).join("");
+      return { kind: "scalar", raw: str, valueType: "string" };
+    }
+    const joinPair = (left, right) => {
+      if (left.kind === "object" && right.kind === "object") {
+        return deepMergeHoconValues(left, right);
+      }
+      if (left.kind === "array" && right.kind === "object") {
+        const converted = numericObjectToArray(right);
+        if (converted !== null) {
+          return { kind: "array", items: [...left.items, ...converted] };
         }
+        throw new ResolveError(
+          "cannot concatenate array with object: value concatenation requires same-kind operands (S10.4)",
+          "",
+          line,
+          col
+        );
       }
-      return { kind: "object", fields: merged };
-    }
-    if (resolved.some((v) => v.kind === "array")) {
-      const items = [];
-      for (const v of resolved) {
-        if (v.kind === "array") items.push(...v.items);
-        else items.push(v);
+      if (left.kind === "object" && right.kind === "array") {
+        const converted = numericObjectToArray(left);
+        if (converted !== null) {
+          return { kind: "array", items: [...converted, ...right.items] };
+        }
+        throw new ResolveError(
+          "cannot concatenate object with array: value concatenation requires same-kind operands (S10.4)",
+          "",
+          line,
+          col
+        );
       }
-      return { kind: "array", items };
+      if (left.kind === "array" && right.kind === "array") {
+        return { kind: "array", items: [...left.items, ...right.items] };
+      }
+      if (left.kind === "array" || right.kind === "array") {
+        throw new ResolveError(
+          `cannot concatenate ${left.kind} with ${right.kind}: arrays and objects may not appear in string value concatenation (S10.13)`,
+          "",
+          line,
+          col
+        );
+      }
+      if (left.kind === "object" || right.kind === "object") {
+        throw new ResolveError(
+          `cannot concatenate ${left.kind} with ${right.kind}: arrays and objects may not appear in string value concatenation (S10.13)`,
+          "",
+          line,
+          col
+        );
+      }
+      return { kind: "scalar", raw: left.raw + right.raw, valueType: "string" };
+    };
+    const [head, ...tail] = nonSep;
+    const folded = tail.reduce(joinPair, head);
+    if (folded.kind === "scalar") {
+      const str = resolved.map((v) => v.kind === "scalar" ? v.raw : JSON.stringify(v)).join("");
+      return { kind: "scalar", raw: str, valueType: "string" };
     }
-    const str = resolved.map((v) => v.kind === "scalar" ? v.raw : JSON.stringify(v)).join("");
-    return { kind: "scalar", raw: str, valueType: "string" };
+    return folded;
   }
   resolveAppend(a, scope) {
     const existing = this.resolveVal(a.existing, scope) ?? { kind: "array", items: [] };
@@ -1587,6 +1983,7 @@ async function defaultReadFile(filePath) {
 }
 function buildResolveContext(input, opts) {
   const tokens = tokenize(input);
+  assertNonEmptyDocument(tokens, "input");
   const ast = parseTokens(tokens);
   const resolveOpts = {
     env: getEnv(opts),