@o3co/ts.hocon 1.10.0 → 1.12.0

package/dist/adapters/env.d.ts

@@ -1,4 +1,4 @@
-import { C as Config } from '../config-PdhVgeLS.js';
+import { C as Config } from '../config-Dlq6rF3w.js';
 
 type EnvOptions = {
     /**
@@ -22,6 +22,16 @@ type EnvOptions = {
  * Reading a single variable needs nothing from here — HOCON's own `${?VAR}`
  * already does that. This is for mounting a whole namespace as a subtree.
  *
+ * `__` is the only path separator: a single `_` stays part of its segment
+ * (`APP_DB__MAX_CONN` → `db.max_conn`), and a literal `.` in a variable name is
+ * key text rather than a boundary, so `APP_FOO.BAR` becomes the single
+ * top-level key `foo.bar` — addressable as the quoted path `"foo.bar"` — and
+ * coexists with `APP_FOO__BAR` instead of colliding with it (F1.2).
+ *
+ * Two names that do map to one path are an error, the environment having no
+ * order to break the tie with (F1.6). Keys named `__proto__`, `constructor` or
+ * `prototype` are kept like any other (F2.9).
+ *
  * Values are always strings, and a `${...}` inside one stays literal (F0.2, F1.4).
  */
 declare function loadEnv(opts?: EnvOptions & {
@@ -35,6 +45,11 @@ declare function loadEnv(opts?: EnvOptions & {
  * double quotes with `\n \r \t \\ \"`. Multi-line values and trailing comments
  * are not supported — an unquoted value containing ` #` is an error rather than
  * a guess about whether a comment was meant. No `${...}` expansion.
+ *
+ * Names map to paths exactly as in {@link loadEnv}: `__` is the only separator,
+ * so a literal `.` stays key text (`FOO.BAR` → the single key `foo.bar`). A
+ * file has a definite line order, so a repeated name is last-wins (F0.7)
+ * rather than the collision error the process environment gets.
  */
 declare function parseDotEnv(input: string, opts?: EnvOptions): Config;
 

package/dist/adapters/env.js

@@ -513,36 +513,73 @@ function deepMergeHoconValues(base, overlay) {
 // src/internal/resolver/include-loader.ts
 import { createRequire } from "module";
 import * as nodePath from "path";
+import { pathToFileURL } from "url";
+
+// src/internal/strip-bom.ts
+function stripBom(input) {
+  return input.charCodeAt(0) === 65279 ? input.slice(1) : input;
+}
+
+// src/internal/depth.ts
+var MAX_PATH_SEGMENTS = 64;
+function tooDeep(segments) {
+  return segments > MAX_PATH_SEGMENTS;
+}
+function guardStackDepth(fn, wrap) {
+  try {
+    return fn();
+  } catch (e) {
+    if (!isStackOverflow(e)) throw e;
+    throw wrap(STACK_MESSAGE);
+  }
+}
+var STACK_MESSAGE = "input is nested too deeply for this engine's stack, or contains a cycle (flatten the document, or break the cycle)";
+function isStackOverflow(e) {
+  if (!(e instanceof RangeError)) return false;
+  const m = e.message.toLowerCase();
+  return m.includes("call stack") || // V8: "Maximum call stack size exceeded"
+  m.includes("recursion") || // SpiderMonkey: "too much recursion"
+  m.includes("stack overflow");
+}
+function depthError(message) {
+  return new ConfigError(message, "");
+}
 
 // src/internal/properties/properties.ts
 function nestPairs(pairs) {
   const root = /* @__PURE__ */ Object.create(null);
-  const sorted = [...pairs].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-  for (const [key, value] of sorted) {
-    setNested(root, key.split("."), value);
+  const sorted = [...pairs].sort(([a], [b]) => compareSegments(a, b));
+  for (const [segments, value] of sorted) {
+    setNested(root, segments, value);
   }
   return root;
 }
-var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function compareSegments(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return a.length - b.length;
+}
+function pathKey(segments) {
+  return JSON.stringify(segments);
+}
 function setNested(obj, segments, value) {
   let current = obj;
   for (let i = 0; i < segments.length - 1; i++) {
     const seg = segments[i];
-    if (seg === void 0 || DANGEROUS_KEYS.has(seg)) return;
     if (!(seg in current) || typeof current[seg] !== "object" || current[seg] === null) {
       current[seg] = /* @__PURE__ */ Object.create(null);
     }
     current = current[seg];
   }
   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;
 }
 
-// src/internal/resolver/include-loader.ts
-var _require = createRequire(import.meta.url);
-
 // src/value/numeric-array.ts
 function numericObjectToArray(value) {
   if (value.kind !== "object") return null;
@@ -1130,10 +1167,10 @@ var Config = class _Config {
     }
     if (v.kind === "object") {
       const converted = numericObjectToArray(v);
-      if (converted !== null) return converted.map(hoconToJs);
+      if (converted !== null) return converted.map((item) => hoconToJs(item));
     }
     if (v.kind !== "array") throw new ConfigError(`expected array at ${path}`, path);
-    return v.items.map(hoconToJs);
+    return v.items.map((item) => hoconToJs(item));
   }
   has(path) {
     return this.lookupNode(path) !== void 0;
@@ -1261,8 +1298,52 @@ var Config = class _Config {
       originDescription: this._originDescription
     });
   }
-  toObject() {
-    return hoconToJs(this.root);
+  /**
+   * The whole config as plain JS data: objects, arrays, strings, numbers,
+   * booleans and `null`.
+   *
+   * Keys are reproduced exactly as the config carries them, `__proto__`,
+   * `constructor` and `prototype` included: each is defined as an **own data
+   * property**, so the returned object's prototype is always
+   * `Object.prototype`, and this call writes nothing to the global one.
+   *
+   * ### Passing the result to other code
+   *
+   * A config file — especially a `.properties` file or an env namespace you
+   * merged in — can therefore hand you an own `__proto__` key, and what happens
+   * next depends entirely on how the consumer copies it:
+   *
+   * ```ts
+   * const data = cfg.toObject()
+   * { ...data }                  // safe — own properties are copied as data
+   * structuredClone(data)        // safe
+   * Object.assign({}, data)      // NOT safe — [[Set]] on the {} target hits
+   *                              // Object.prototype's __proto__ setter: the key
+   *                              // vanishes and config data becomes the result's
+   *                              // prototype
+   * deepMerge({}, data)          // NOT safe — a naive recursive merge reads
+   *                              // target['__proto__'], gets Object.prototype,
+   *                              // and writes to it: global pollution
+   * for (const k in data) …      // prefer Object.entries / Object.keys
+   * ```
+   *
+   * Those two hazards come from the **destination** object's prototype, so no
+   * option here can disarm them — copy with spread or `structuredClone` instead.
+   *
+   * What `{ nullPrototype: true }` does give you is a result that inherits
+   * nothing: every object comes back with a `null` prototype, so reading
+   * `x.__proto__`, `x.constructor` or `x.toString` yields config data or
+   * `undefined` rather than something from `Object.prototype`, and code that
+   * merges *into* this object cannot climb out of it. Keys are all still
+   * present. The trade-off is the usual one for prototype-less objects: not
+   * `instanceof Object`, and no `hasOwnProperty` of their own.
+   *
+   * Numbers follow the JS number model, so an integer wider than 2^53 rounds
+   * here even when the config holds it exactly — read those with
+   * {@link Config.getString} instead.
+   */
+  toObject(opts) {
+    return hoconToJs(this.root, opts?.nullPrototype === true);
   }
   /**
    * @internal Test-only: renders this resolved Config's value tree as canonical
@@ -1374,16 +1455,25 @@ function scalarToJs(raw, valueType) {
       return raw;
   }
 }
-function hoconToJs(v) {
+function hoconToJs(v, nullPrototype = false) {
   switch (v.kind) {
     case "scalar":
       return scalarToJs(v.raw, v.valueType);
     case "array":
-      return v.items.map(hoconToJs);
+      return v.items.map((item) => hoconToJs(item, nullPrototype));
     case "object": {
-      const obj = /* @__PURE__ */ Object.create(null);
-      for (const [k, val] of v.fields) obj[k] = hoconToJs(val);
-      return Object.assign({}, obj);
+      const entries = Array.from(v.fields, ([k, val]) => [k, hoconToJs(val, nullPrototype)]);
+      if (nullPrototype) {
+        const obj = /* @__PURE__ */ Object.create(null);
+        for (const [k, val] of entries) Object.defineProperty(obj, k, {
+          value: val,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+        return obj;
+      }
+      return Object.fromEntries(entries);
     }
   }
 }
@@ -1468,10 +1558,15 @@ function normalizeLeadingZeroNumber(raw) {
 
 // src/value-factory.ts
 function fromMap(values, originDescription) {
-  const fields = coerceObject(values, "");
+  const fields = guardStackDepth(
+    () => coerceObject(values, ""),
+    (msg) => depthError(`fromMap: ${msg}`)
+  );
   const root = { kind: "object", fields };
   return Config._fromResolvedValue(root, { originDescription });
 }
+var INT64_MAX = 9223372036854775807n;
+var INT64_MIN = -9223372036854775808n;
 function coerceObject(obj, atPath) {
   const fields = /* @__PURE__ */ new Map();
   for (const [k, v] of Object.entries(obj)) {
@@ -1500,14 +1595,14 @@ function coerceValue(v, atPath) {
           atPath
         );
       }
-      return { kind: "scalar", raw: String(v), valueType: "number" };
+      return { kind: "scalar", raw: Object.is(v, -0) ? "-0" : String(v), valueType: "number" };
     }
     case "boolean":
       return { kind: "scalar", raw: v ? "true" : "false", valueType: "boolean" };
     case "bigint": {
-      if (v > BigInt(Number.MAX_SAFE_INTEGER) || v < BigInt(Number.MIN_SAFE_INTEGER)) {
+      if (v > INT64_MAX || v < INT64_MIN) {
         throw new ConfigError(
-          `fromMap: bigint ${v} exceeds Number.MAX_SAFE_INTEGER (not representable as HOCON number) at path "${atPath}"`,
+          `fromMap: integer ${v} is out of int64 range (HOCON integers are int64; spec F0.5) at path "${atPath}"`,
           atPath
         );
       }
@@ -1548,11 +1643,12 @@ function loadEnv(opts = {}) {
     const value = source[name];
     if (value === void 0) continue;
     const path = toPath(name.slice(prefix.length));
-    const prev = seen.get(path);
+    const key = pathKey(path);
+    const prev = seen.get(key);
     if (prev !== void 0) {
-      throw new ConfigError(`loadEnv: ${prev} and ${name} both map to "${path}"`, path);
+      throw new ConfigError(`loadEnv: ${prev} and ${name} both map to "${path.join(".")}"`, path.join("."));
     }
-    seen.set(path, name);
+    seen.set(key, name);
     pairs.push([path, value]);
   }
   return fromMap(nestPairs(pairs), opts.originDescription ?? "environment variables");
@@ -1561,27 +1657,37 @@ function parseDotEnv(input, opts = {}) {
   const origin = opts.originDescription ?? ".env";
   const prefix = opts.prefix ?? "";
   const pairs = [];
-  const lines = input.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  const lines = stripBom(input).replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
   for (let i = 0; i < lines.length; i++) {
     const raw = (lines[i] ?? "").trim();
     if (raw === "" || raw.startsWith("#")) continue;
-    const line = raw.startsWith("export ") ? raw.slice("export ".length) : raw;
+    const line = stripExport(raw);
     const eq = line.indexOf("=");
     if (eq === -1) throw new ConfigError(`${origin}:${i + 1}: expected NAME=value`, "");
     const name = line.slice(0, eq).trim();
     if (name === "") throw new ConfigError(`${origin}:${i + 1}: empty variable name`, "");
-    const value = dotEnvValue(line.slice(eq + 1).replace(/^[ \t]+/, ""), origin, i + 1, name);
     if (!name.startsWith(prefix)) continue;
+    checkName(name, origin, i + 1);
+    const value = dotEnvValue(line.slice(eq + 1).replace(/^[ \t]+/, ""), origin, i + 1, name);
     pairs.push([toPath(name.slice(prefix.length)), value]);
   }
   return fromMap(nestPairs(pairs), origin);
 }
 function toPath(name) {
-  const segs = name.split(SEPARATOR).map((s) => s.toLowerCase());
+  const segs = name.split(SEPARATOR).map(asciiLower);
   if (segs.some((s) => s === "")) {
     throw new ConfigError(`env: "${name}" produces an empty path segment`, name);
   }
-  return segs.join(".");
+  if (tooDeep(segs.length)) {
+    throw new ConfigError(
+      `env: "${name}" maps to a path ${segs.length} segments deep, over the limit of ${MAX_PATH_SEGMENTS}`,
+      name
+    );
+  }
+  return segs;
+}
+function asciiLower(s) {
+  return s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
 }
 function dotEnvValue(v, origin, line, name) {
   const fail = (msg) => {
@@ -1623,6 +1729,20 @@ function dotEnvValue(v, origin, line, name) {
   }
   return trimmed;
 }
+function stripExport(line) {
+  const m = /^export[ \t]+/.exec(line);
+  return m ? line.slice(m[0].length) : line;
+}
+function checkName(name, origin, line) {
+  const bad = /\p{White_Space}|#/u.exec(name);
+  if (bad) {
+    const what = bad[0] === "#" ? "'#'" : "whitespace";
+    throw new ConfigError(
+      `${origin}:${line}: variable name "${name}" contains ${what}; the line is not NAME=value (spec F1.7)`,
+      name
+    );
+  }
+}
 export {
   loadEnv,
   parseDotEnv

package/dist/adapters/jsonc.cjs

@@ -550,8 +550,33 @@ function deepMergeHoconValues(base, overlay) {
 // src/internal/resolver/include-loader.ts
 var import_node_module = require("module");
 var nodePath = __toESM(require("path"), 1);
-var import_meta = {};
-var _require = (0, import_node_module.createRequire)(import_meta.url);
+var import_node_url = require("url");
+
+// src/internal/strip-bom.ts
+function stripBom(input) {
+  return input.charCodeAt(0) === 65279 ? input.slice(1) : input;
+}
+
+// src/internal/depth.ts
+function guardStackDepth(fn, wrap) {
+  try {
+    return fn();
+  } catch (e) {
+    if (!isStackOverflow(e)) throw e;
+    throw wrap(STACK_MESSAGE);
+  }
+}
+var STACK_MESSAGE = "input is nested too deeply for this engine's stack, or contains a cycle (flatten the document, or break the cycle)";
+function isStackOverflow(e) {
+  if (!(e instanceof RangeError)) return false;
+  const m = e.message.toLowerCase();
+  return m.includes("call stack") || // V8: "Maximum call stack size exceeded"
+  m.includes("recursion") || // SpiderMonkey: "too much recursion"
+  m.includes("stack overflow");
+}
+function depthError(message) {
+  return new ConfigError(message, "");
+}
 
 // src/value/numeric-array.ts
 function numericObjectToArray(value) {
@@ -1140,10 +1165,10 @@ var Config = class _Config {
     }
     if (v.kind === "object") {
       const converted = numericObjectToArray(v);
-      if (converted !== null) return converted.map(hoconToJs);
+      if (converted !== null) return converted.map((item) => hoconToJs(item));
     }
     if (v.kind !== "array") throw new ConfigError(`expected array at ${path}`, path);
-    return v.items.map(hoconToJs);
+    return v.items.map((item) => hoconToJs(item));
   }
   has(path) {
     return this.lookupNode(path) !== void 0;
@@ -1271,8 +1296,52 @@ var Config = class _Config {
       originDescription: this._originDescription
     });
   }
-  toObject() {
-    return hoconToJs(this.root);
+  /**
+   * The whole config as plain JS data: objects, arrays, strings, numbers,
+   * booleans and `null`.
+   *
+   * Keys are reproduced exactly as the config carries them, `__proto__`,
+   * `constructor` and `prototype` included: each is defined as an **own data
+   * property**, so the returned object's prototype is always
+   * `Object.prototype`, and this call writes nothing to the global one.
+   *
+   * ### Passing the result to other code
+   *
+   * A config file — especially a `.properties` file or an env namespace you
+   * merged in — can therefore hand you an own `__proto__` key, and what happens
+   * next depends entirely on how the consumer copies it:
+   *
+   * ```ts
+   * const data = cfg.toObject()
+   * { ...data }                  // safe — own properties are copied as data
+   * structuredClone(data)        // safe
+   * Object.assign({}, data)      // NOT safe — [[Set]] on the {} target hits
+   *                              // Object.prototype's __proto__ setter: the key
+   *                              // vanishes and config data becomes the result's
+   *                              // prototype
+   * deepMerge({}, data)          // NOT safe — a naive recursive merge reads
+   *                              // target['__proto__'], gets Object.prototype,
+   *                              // and writes to it: global pollution
+   * for (const k in data) …      // prefer Object.entries / Object.keys
+   * ```
+   *
+   * Those two hazards come from the **destination** object's prototype, so no
+   * option here can disarm them — copy with spread or `structuredClone` instead.
+   *
+   * What `{ nullPrototype: true }` does give you is a result that inherits
+   * nothing: every object comes back with a `null` prototype, so reading
+   * `x.__proto__`, `x.constructor` or `x.toString` yields config data or
+   * `undefined` rather than something from `Object.prototype`, and code that
+   * merges *into* this object cannot climb out of it. Keys are all still
+   * present. The trade-off is the usual one for prototype-less objects: not
+   * `instanceof Object`, and no `hasOwnProperty` of their own.
+   *
+   * Numbers follow the JS number model, so an integer wider than 2^53 rounds
+   * here even when the config holds it exactly — read those with
+   * {@link Config.getString} instead.
+   */
+  toObject(opts) {
+    return hoconToJs(this.root, opts?.nullPrototype === true);
   }
   /**
    * @internal Test-only: renders this resolved Config's value tree as canonical
@@ -1384,16 +1453,25 @@ function scalarToJs(raw, valueType) {
       return raw;
   }
 }
-function hoconToJs(v) {
+function hoconToJs(v, nullPrototype = false) {
   switch (v.kind) {
     case "scalar":
       return scalarToJs(v.raw, v.valueType);
     case "array":
-      return v.items.map(hoconToJs);
+      return v.items.map((item) => hoconToJs(item, nullPrototype));
     case "object": {
-      const obj = /* @__PURE__ */ Object.create(null);
-      for (const [k, val] of v.fields) obj[k] = hoconToJs(val);
-      return Object.assign({}, obj);
+      const entries = Array.from(v.fields, ([k, val]) => [k, hoconToJs(val, nullPrototype)]);
+      if (nullPrototype) {
+        const obj = /* @__PURE__ */ Object.create(null);
+        for (const [k, val] of entries) Object.defineProperty(obj, k, {
+          value: val,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+        return obj;
+      }
+      return Object.fromEntries(entries);
     }
   }
 }
@@ -1478,10 +1556,15 @@ function normalizeLeadingZeroNumber(raw) {
 
 // src/value-factory.ts
 function fromMap(values, originDescription) {
-  const fields = coerceObject(values, "");
+  const fields = guardStackDepth(
+    () => coerceObject(values, ""),
+    (msg) => depthError(`fromMap: ${msg}`)
+  );
   const root = { kind: "object", fields };
   return Config._fromResolvedValue(root, { originDescription });
 }
+var INT64_MAX = 9223372036854775807n;
+var INT64_MIN = -9223372036854775808n;
 function coerceObject(obj, atPath) {
   const fields = /* @__PURE__ */ new Map();
   for (const [k, v] of Object.entries(obj)) {
@@ -1510,14 +1593,14 @@ function coerceValue(v, atPath) {
           atPath
         );
       }
-      return { kind: "scalar", raw: String(v), valueType: "number" };
+      return { kind: "scalar", raw: Object.is(v, -0) ? "-0" : String(v), valueType: "number" };
     }
     case "boolean":
       return { kind: "scalar", raw: v ? "true" : "false", valueType: "boolean" };
     case "bigint": {
-      if (v > BigInt(Number.MAX_SAFE_INTEGER) || v < BigInt(Number.MIN_SAFE_INTEGER)) {
+      if (v > INT64_MAX || v < INT64_MIN) {
         throw new ConfigError(
-          `fromMap: bigint ${v} exceeds Number.MAX_SAFE_INTEGER (not representable as HOCON number) at path "${atPath}"`,
+          `fromMap: integer ${v} is out of int64 range (HOCON integers are int64; spec F0.5) at path "${atPath}"`,
           atPath
         );
       }
@@ -1541,7 +1624,10 @@ function coerceValue(v, atPath) {
 
 // src/adapters/jsonc.ts
 function parseJsonc(input, originDescription) {
-  const doc = JSON.parse(stripTrailingCommas(stripComments(input)));
+  const doc = guardStackDepth(
+    () => JSON.parse(stripTrailingCommas(stripComments(stripBom(input))), bigIntReviver),
+    (msg) => depthError(`jsonc: ${msg}`)
+  );
   if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
     throw new ConfigError(
       `jsonc: document root is ${Array.isArray(doc) ? "an array" : typeof doc}, but a config root must be an object (spec F0.3)`,
@@ -1550,6 +1636,50 @@ function parseJsonc(input, originDescription) {
   }
   return fromMap(doc, originDescription);
 }
+function isIntegerLiteral(source) {
+  return !/[.eE]/.test(source);
+}
+var HAS_SOURCE_TEXT_ACCESS = (() => {
+  let seen;
+  JSON.parse("1", function(_k, v, context) {
+    seen = context?.source;
+    return v;
+  });
+  return seen !== void 0;
+})();
+function bigIntReviver(key, value, context) {
+  if (typeof value !== "number" || Number.isSafeInteger(value)) return value;
+  const source = context?.source;
+  if (source === void 0) {
+    if (!Number.isInteger(value)) return value;
+    throw new ConfigError(
+      `jsonc: the integer at "${key || "<root>"}" needs more precision than a JS number holds, and this runtime does not expose JSON.parse source text (${HAS_SOURCE_TEXT_ACCESS ? "unexpected \u2014 the capability probe said otherwise" : "requires Node >= 22 or an engine with JSON.parse source access"}), so it cannot be read losslessly (spec F0.5)`,
+      key
+    );
+  }
+  if (!isIntegerLiteral(source)) return value;
+  return BigInt(source);
+}
+function isLineBreak(c) {
+  return c === "\n" || c === "\r";
+}
+function lineBreaksOf(span) {
+  let out = "";
+  for (let i = 0; i < span.length; i++) {
+    const c = span[i];
+    if (c === "\r") {
+      if (span[i + 1] === "\n") {
+        out += "\r\n";
+        i++;
+      } else {
+        out += "\r";
+      }
+    } else if (c === "\n") {
+      out += "\n";
+    }
+  }
+  return out;
+}
 function stripComments(src) {
   let out = "";
   for (let i = 0; i < src.length; ) {
@@ -1561,13 +1691,13 @@ function stripComments(src) {
       continue;
     }
     if (c === "/" && src[i + 1] === "/") {
-      while (i < src.length && src[i] !== "\n") i++;
+      while (i < src.length && !isLineBreak(src[i])) i++;
       continue;
     }
     if (c === "/" && src[i + 1] === "*") {
       const end = src.indexOf("*/", i + 2);
       if (end === -1) throw new ConfigError("jsonc: unterminated block comment", "");
-      for (const ch of src.slice(i, end + 2)) if (ch === "\n") out += "\n";
+      out += lineBreaksOf(src.slice(i, end + 2)) || " ";
       i = end + 2;
       continue;
     }

package/dist/adapters/jsonc.d.cts

@@ -1,4 +1,4 @@
-import { C as Config } from '../config-PdhVgeLS.cjs';
+import { C as Config } from '../config-Dlq6rF3w.cjs';
 
 /**
  * Read JSON with comments and trailing commas — the dialect VS Code and
@@ -10,15 +10,46 @@ import { C as Config } from '../config-PdhVgeLS.cjs';
  * of its own.)
  *
  * Comments and trailing commas are removed and `JSON.parse` does the rest, so
- * the accepted grammar is otherwise exactly the platform's JSON.
+ * the accepted grammar is otherwise exactly the platform's JSON. A comment is
+ * replaced by whitespace rather than deleted, so it separates the tokens around
+ * it and `{"a":1/*x*\/2}` is a syntax error rather than `{"a":12}` (F3.2).
  *
- * See docs/specs/format-ingestion-mapping.md items F3.x in the hocon scope.
+ * Integers are ingested losslessly (F0.5): a literal too wide for a JS `number`
+ * keeps its digits — `getString` returns them exactly — and one outside int64
+ * is refused instead of being rounded. `getNumber` and `toObject` still apply
+ * the JS number model, as they do for HOCON's own literals, so read large
+ * identifiers with `getString`.
+ *
+ * **An unpaired `\uXXXX` surrogate is accepted here and refused by go.hocon,
+ * py.hocon and rs.hocon** (F3.5). That is deliberate, and the same divergence
+ * the properties adapter already carries under F2.8: a JavaScript string is
+ * UTF-16, like Java's, so it holds a lone surrogate natively and round-trips it.
+ * A Go or Rust string cannot hold one at all — Go silently substituted U+FFFD
+ * until F3.5 — and a Python `str` can hold one but cannot encode it as UTF-8,
+ * so all three refuse rather than defer the failure. Refusing here would mean
+ * this spec overriding the host language rather than protecting the user; see
+ * S1.2.6 for the class.
+ *
+ * See the F3.x items in the format-ingestion mapping spec:
+ * https://github.com/o3co/xx.hocon/blob/main/docs/format-ingestion-mapping.md
  */
 declare function parseJsonc(input: string, originDescription?: string): Config;
 /**
  * Remove `//` line comments and block comments, leaving string literals alone.
- * Newlines inside removed spans are kept so JSON.parse still reports useful
- * positions.
+ *
+ * F3.2: a comment is replaced by *whitespace*, never the empty string — it must
+ * keep separating the tokens around it, so a `1`, a block comment and a `2` stay
+ * two tokens and fail the JSON decode instead of silently reading as `12`.
+ * Newlines inside a removed span are kept so JSON.parse still reports useful
+ * positions; a span with no newline becomes a single space.
+ *
+ * A `//` comment ends at **LF or CR** (F3.2), and at nothing else. Stopping only
+ * at LF let a CR-terminated comment eat the rest of the line, and the
+ * trailing-comma pass then tidied the remains into valid JSON — so
+ * `{"a":1,//c\r"b":2,\n"c":3}` decoded as `{"a":1,"c":3}`, losing a key with no
+ * error at all. Stopping at U+2028/U+2029 would be the mirror-image mistake:
+ * ending a comment the dialect's own parser is still inside, so the document
+ * would mean something different here than in VS Code. See {@link isLineBreak}.
  */
 declare function stripComments(src: string): string;