@dogsbay/literal 0.2.0-beta.132 → 0.2.0-beta.134

package/README.md

@@ -11,11 +11,24 @@ const { value, unresolved } = evaluateModule(source); // the module's default ex
 
 It understands object, array, string, number, boolean and null literals; template strings
 with no `${}`; spreads; module-level `const` references; zero-argument helpers that return a
-literal; wrapper calls such as `defineConfig({…})`; member access; and TypeScript type noise.
-Anything else becomes `UNRESOLVED` and is listed in `unresolved`: never a plausible wrong
-value, never a silent omission.
+literal; wrapper calls such as `defineConfig({…})`; member access and literal indexes
+(`releases[0]["x"]`); `"a" + "b"` (strings only); `module.exports =`; and TypeScript type
+noise. Anything else becomes `UNRESOLVED` and is listed in `unresolved`: never a plausible
+wrong value, never a silent omission.
 
-Used by the Dogsbay VitePress importer (`.vitepress/config.*`).
+Other modules (`require("./x")`, `import x from "./x"`) are read only through a resolver you
+pass, which decides what a path means and what may be read:
+
+```ts
+evaluateModule(source, "sidebars", { require: (spec) => readModule(spec) }); // value or undefined
+```
+
+Someone else's code can be hostile, so there are limits: a value that expands past 100,000
+entries (shared `const`s doubling, required modules included), a string past 1 MB, or nesting
+past 500 levels is `UNRESOLVED`; a `__proto__` key is data, never a prototype.
+
+Used by the Dogsbay VitePress importer (`.vitepress/config.*`) and Docusaurus importer
+(`sidebars*.js`, `variables.js`).
 
 ## License
 

package/dist/index.d.ts

@@ -18,8 +18,13 @@
  *   - zero-arg calls to module-level `function f() { return <literal> }` and
  *     `const f = () => <literal>` (hono's `sidebar: { '/': sidebars() }`)
  *   - wrapper calls with a single literal argument (`defineConfig({…})`)
- *   - member access into an already-evaluated object (`shared.themeConfig`)
+ *   - member access into an already-evaluated object (`shared.themeConfig`), and a LITERAL
+ *     index (`releases[0]`, `x["key"]`); a computed index (`nav[i]`) is unresolved
  *   - TS noise: type annotations, `as const`, `as T`, `satisfies T`, generics
+ *   - CommonJS: `module.exports = <expr>` is the default export
+ *   - `require("./x")` and `import x from "./x"`, through a resolver the CALLER supplies
+ *     (`EvaluateOptions.require`): this module reads no files and decides no paths
+ *   - `"a" + "b"`: concatenation of two strings, nothing else (camunda's `root_dir + "x"`)
  *
  * Anything else evaluates to the `UNRESOLVED` sentinel — never to a plausible
  * wrong value and never to a silent omission. Callers report what they could
@@ -40,6 +45,14 @@ export interface EvalResult {
     /** Human-readable descriptions of expressions that could not be read. */
     unresolved: string[];
 }
+export interface EvaluateOptions {
+    /**
+     * The default export of the module `spec` names (`require("./x")`, `import x from "./x"`),
+     * or undefined when there is none. The caller resolves the path, decides what may be read,
+     * and bounds how deep modules nest; reading a module is the caller's call, never this one's.
+     */
+    require?: (spec: string) => LiteralValue | undefined;
+}
 /**
  * Evaluate a module's default export as far as the literal subset allows.
  *
@@ -47,7 +60,7 @@ export interface EvalResult {
  * there is no `export default`, which covers
  * `const config = { … }; export { config }`.
  */
-export declare function evaluateModule(source: string, fallbackExport?: string): EvalResult;
+export declare function evaluateModule(source: string, fallbackExport?: string, opts?: EvaluateOptions): EvalResult;
 /** Narrowing helper: a plain object with no UNRESOLVED identity. */
 export declare function asObject(v: LiteralValue): Record<string, LiteralValue> | undefined;
 export declare function asArray(v: LiteralValue): LiteralValue[] | undefined;

package/dist/index.js

@@ -18,8 +18,13 @@
  *   - zero-arg calls to module-level `function f() { return <literal> }` and
  *     `const f = () => <literal>` (hono's `sidebar: { '/': sidebars() }`)
  *   - wrapper calls with a single literal argument (`defineConfig({…})`)
- *   - member access into an already-evaluated object (`shared.themeConfig`)
+ *   - member access into an already-evaluated object (`shared.themeConfig`), and a LITERAL
+ *     index (`releases[0]`, `x["key"]`); a computed index (`nav[i]`) is unresolved
  *   - TS noise: type annotations, `as const`, `as T`, `satisfies T`, generics
+ *   - CommonJS: `module.exports = <expr>` is the default export
+ *   - `require("./x")` and `import x from "./x"`, through a resolver the CALLER supplies
+ *     (`EvaluateOptions.require`): this module reads no files and decides no paths
+ *   - `"a" + "b"`: concatenation of two strings, nothing else (camunda's `root_dir + "x"`)
  *
  * Anything else evaluates to the `UNRESOLVED` sentinel — never to a plausible
  * wrong value and never to a silent omission. Callers report what they could
@@ -244,15 +249,106 @@ const CLOSERS = new Set(["}", "]", ")"]);
  * 1 KB config), and spreads (`[...a, ...a]`) copy for real.
  */
 const MAX_VALUES = 100_000;
+/** The longest string `+` may build: `const b = a + a` doubles, thirty times is a gigabyte. */
+const MAX_STRING = 1024 * 1024;
+/** How deeply values may nest: past this a parser or a consumer walking it runs out of stack. */
+const MAX_DEPTH = 500;
+/**
+ * Assign a key the way a literal does: `{ "__proto__": x }` is an own property. Plain
+ * assignment would set the object's prototype instead, so a sidebar item could inherit a
+ * `type` or `items` that no key in the source gave it.
+ */
+function setKey(out, key, value) {
+    if (key === "__proto__")
+        Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+    else
+        out[key] = value;
+}
 class Evaluator {
+    opts;
     toks;
     bindings = new Map();
     /** Each array or object built here → the values it expands to, itself included. */
     sizes = new WeakMap();
+    depth = 0;
     unresolved = [];
+    constructor(src, opts = {}) {
+        this.opts = opts;
+        this.toks = tokenize(src);
+        this.collectBindings();
+        this.reportMutations();
+    }
+    /**
+     * A top-level statement that changes a binding after it is defined — `module.exports.y = 2`,
+     * `exports.y = 2`, `s.items = […]`, `s.items.push(…)` — is not read: the value is read as
+     * declared, so the change is REPORTED, never silently missing (review 2026-10-21).
+     */
+    reportMutations() {
+        let depth = 0;
+        for (let i = 0; i < this.toks.length; i++) {
+            const t = this.toks[i];
+            if (t.kind === "punct" && OPENERS[t.text])
+                depth++;
+            else if (t.kind === "punct" && CLOSERS.has(t.text))
+                depth--;
+            if (depth !== 0 || t.kind !== "ident" || !(this.is(i + 1, ".") || this.is(i + 1, "[")))
+                continue;
+            const prev = this.toks[i - 1];
+            // The start of a statement: the file's start, after `;` or `}`, or on a new line
+            if (prev && !(prev.kind === "punct" && (prev.text === ";" || prev.text === "}")) && prev.line === t.line)
+                continue;
+            if (prev && prev.kind === "punct" && prev.text === ".")
+                continue;
+            const name = t.text;
+            const known = name === "exports" || name === "module" || this.bindings.has(name);
+            if (!known)
+                continue;
+            if (name === "module" && this.is(i + 2, "exports") && this.is(i + 3, "="))
+                continue; // the export itself
+            this.report(i, `a statement that changes \`${name}\` after it is defined (read as declared, without the change)`);
+        }
+    }
+    /** What `v` costs against MAX_VALUES. A long string costs more than one value. */
     sizeOf(v) {
+        if (typeof v === "string")
+            return 1 + (v.length >> 10);
         return v !== null && typeof v === "object" ? (this.sizes.get(v) ?? 1) : 1;
     }
+    /**
+     * The size of a value this evaluator did not build (another module's), measured once per
+     * object: a module required twice is shared, not copied, and counts as what it expands to.
+     * MAX_VALUES + 1 for anything over the budget or nested past MAX_DEPTH.
+     */
+    measure(v, depth = 0) {
+        if (v === null || typeof v !== "object")
+            return this.sizeOf(v);
+        const known = this.sizes.get(v);
+        if (known !== undefined)
+            return known;
+        if (depth > MAX_DEPTH)
+            return MAX_VALUES + 1;
+        let size = 1;
+        for (const c of Array.isArray(v) ? v : Object.values(v)) {
+            size += this.measure(c, depth + 1);
+            if (size > MAX_VALUES)
+                break;
+        }
+        this.sizes.set(v, size);
+        return size;
+    }
+    /** `require(spec)` / `import … from spec`, through the caller's resolver, within budget. */
+    required(spec, i) {
+        const value = this.opts.require?.(spec);
+        if (value === undefined || value === UNRESOLVED) {
+            this.report(i, `module "${spec}" ${this.opts.require ? "could not be read" : "(no module resolver)"}`);
+            return UNRESOLVED;
+        }
+        if (this.measure(value) > MAX_VALUES) {
+            this.report(i, `module "${spec}": a value that expands to more than ${MAX_VALUES} entries or nests past ${MAX_DEPTH} levels`);
+            return UNRESOLVED;
+        }
+        return value;
+    }
     /** `out` when it expands to at most MAX_VALUES values, else UNRESOLVED and a report. */
     bounded(out, size, i) {
         if (size > MAX_VALUES) {
@@ -262,10 +358,6 @@ class Evaluator {
         this.sizes.set(out, size);
         return out;
     }
-    constructor(src) {
-        this.toks = tokenize(src);
-        this.collectBindings();
-    }
     tok(i) {
         return this.toks[i];
     }
@@ -406,6 +498,23 @@ class Evaluator {
                 this.bindings.set("default", { at: i + 2 });
                 continue;
             }
+            // CommonJS `module.exports = <expr>` is the default export (Docusaurus sidebars).
+            if (t.text === "module" && this.is(i + 1, ".") && this.is(i + 2, "exports") && this.is(i + 3, "=")) {
+                this.bindings.set("default", { at: i + 4 });
+                continue;
+            }
+            // `import x from "spec"` (and the default of `import x, { … } from "spec"`). Named and
+            // namespace imports are not read: an identifier from one is reported where it is used.
+            if (t.text === "import" && this.toks[i + 1]?.kind === "ident" && !this.is(i + 1, "type")) {
+                const name = this.toks[i + 1].text;
+                let k = i + 2;
+                if (this.is(k, ","))
+                    k = this.skipBalanced(k + 1);
+                const spec = this.toks[k + 1];
+                if (this.is(k, "from") && spec?.kind === "str")
+                    this.bindings.set(name, { at: k + 1, from: spec.text });
+                continue;
+            }
             // Skip the `export` modifier so `export const x = …` is indexed too.
             const j = t.text === "export" ? i + 1 : i;
             const kw = this.tok(j);
@@ -504,7 +613,7 @@ class Evaluator {
         if (b.value !== undefined)
             return b.value;
         b.computing = true;
-        const v = this.parseValue(b.at).value;
+        const v = b.from !== undefined ? this.required(b.from, b.at) : this.parseValue(b.at).value;
         b.computing = false;
         b.value = v;
         return v;
@@ -554,6 +663,19 @@ class Evaluator {
     }
     /** Parse the expression at `i`. Returns its value and the next index. */
     parseValue(i) {
+        if (this.depth >= MAX_DEPTH) {
+            this.report(i, `a value nested more than ${MAX_DEPTH} levels deep`);
+            return { value: UNRESOLVED, next: this.skipValue(i) };
+        }
+        this.depth++;
+        try {
+            return this.parseValueAt(i);
+        }
+        finally {
+            this.depth--;
+        }
+    }
+    parseValueAt(i) {
         const t = this.toks[i];
         if (!t)
             return { value: UNRESOLVED, next: i };
@@ -658,6 +780,14 @@ class Evaluator {
             return { value: UNRESOLVED, next: this.skipValue(i) };
         }
         const after = this.skipBalanced(open);
+        // `require("./x")`: one string argument, nothing else
+        if (name === "require" && !this.bindings.has("require")) {
+            const spec = this.toks[open + 1];
+            if (spec?.kind === "str" && this.is(open + 2, ")"))
+                return this.postfix(this.required(spec.text, i), after);
+            this.report(i, "`require` of something other than one string");
+            return { value: UNRESOLVED, next: after };
+        }
         // Zero args → the callee's own literal body.
         if (this.is(open + 1, ")")) {
             if (this.bindings.has(name)) {
@@ -717,6 +847,13 @@ class Evaluator {
             out.push(value);
             size += this.sizeOf(value);
             k = next === k ? k + 1 : next;
+            // Elements are separated by commas. Whatever else follows a value was not read as part
+            // of it (review 2026-10-21: `.concat("x")`'s argument became an element of its own)
+            if (k < this.toks.length && !this.is(k, ",") && !this.is(k, "]")) {
+                this.report(k, `unexpected \`${this.toks[k].text}\` after an array element`);
+                out[out.length - 1] = UNRESOLVED;
+                k = this.advance(k);
+            }
         }
         return this.postfix(this.bounded(out, size, i), k + 1);
     }
@@ -732,7 +869,8 @@ class Evaluator {
                 const { value, next } = this.parseValue(k + 1);
                 // `typeof x === "object"` already excludes the UNRESOLVED symbol.
                 if (value && typeof value === "object" && !Array.isArray(value)) {
-                    Object.assign(out, value);
+                    for (const [key, v] of Object.entries(value))
+                        setKey(out, key, v);
                 }
                 else if (value !== UNRESOLVED) {
                     this.report(k, "spread of a non-object");
@@ -763,7 +901,7 @@ class Evaluator {
                 }
                 if (this.is(k, ":")) {
                     const v = this.parseValue(k + 1);
-                    out[key] = v.value;
+                    setKey(out, key, v.value);
                     k = v.next;
                 }
                 continue;
@@ -782,14 +920,19 @@ class Evaluator {
             }
             if (!this.is(k, ":")) {
                 // Shorthand `{ foo }`.
-                out[key] = this.bindings.has(key) ? this.resolveBinding(key) : UNRESOLVED;
+                setKey(out, key, this.bindings.has(key) ? this.resolveBinding(key) : UNRESOLVED);
                 if (!this.bindings.has(key))
                     this.report(k, `shorthand property \`${key}\``);
                 continue;
             }
             const v = this.parseValue(k + 1);
-            out[key] = v.value;
+            setKey(out, key, v.value);
             k = v.next === k + 1 ? this.skipValue(k + 1) : v.next;
+            if (k < this.toks.length && !this.is(k, ",") && !this.is(k, "}") && !this.is(k, ";")) {
+                this.report(k, `unexpected \`${this.toks[k].text}\` after property \`${key}\``);
+                setKey(out, key, UNRESOLVED);
+                k = this.advance(k);
+            }
         }
         let size = 1;
         for (const v of Object.values(out))
@@ -812,12 +955,36 @@ class Evaluator {
                 k++;
                 continue;
             }
+            // A call on a value (`a.concat(…)`, `"ab"("y")`): its result is computed. The arguments
+            // are skipped with it, or they were read as the next element of the enclosing list.
+            if (this.is(k, "(")) {
+                this.report(k, "a call on a value (computed, not a literal)");
+                v = UNRESOLVED;
+                k = this.skipBalanced(k);
+                continue;
+            }
+            // `x[0]`, `x["key"]`: a literal index into a value we have. The index is read, never
+            // computed: `nav[i]` stays unresolved (below), and so does a key the value does not own.
+            if (this.is(k, "[") && (this.toks[k + 1]?.kind === "num" || this.toks[k + 1]?.kind === "str") && this.is(k + 2, "]")) {
+                const index = this.toks[k + 1].kind === "num" ? Number(this.toks[k + 1].text) : this.toks[k + 1].text;
+                const own = Array.isArray(v) ? (typeof index === "number" && Number.isInteger(index) && index >= 0 && index < v.length ? v[index] : undefined)
+                    : v !== null && typeof v === "object" && Object.hasOwn(v, String(index)) ? v[String(index)]
+                        : undefined;
+                if (own === undefined) {
+                    this.report(k, `index \`[${this.toks[k + 1].text}]\` into a value that does not have it`);
+                    v = UNRESOLVED;
+                }
+                else
+                    v = own;
+                k += 3;
+                continue;
+            }
             if ((this.is(k, ".") || this.is(k, "?.")) && this.toks[k + 1]?.kind === "ident") {
                 const prop = this.toks[k + 1].text;
                 const obj = v && typeof v === "object" && !Array.isArray(v)
                     ? v
                     : undefined;
-                if (!obj || obj[prop] === undefined) {
+                if (!obj || !Object.hasOwn(obj, prop)) {
                     // Includes every METHOD call — `.map(…)`, `.concat(…)`. Reporting
                     // matters: `config.ts` drops UNRESOLVED leaves, so an unreported
                     // one vanishes from the config AND from the "could not read" list,
@@ -833,6 +1000,22 @@ class Evaluator {
             }
             break;
         }
+        // `"a" + "b"`: two strings and nothing else. The right side is read as a value, so
+        // `a + b + c` folds from the right, which for strings is the same thing; a number on either
+        // side (`1 + 2 + "x"` is "3x", not "12x") or any other operator after it is unresolved.
+        if (typeof v === "string" && this.is(k, "+") && this.toks[k]?.kind === "punct") {
+            const right = this.parseValue(k + 1);
+            if (typeof right.value !== "string") {
+                if (right.value !== UNRESOLVED)
+                    this.report(k, "`+` with something other than a string");
+                return { value: UNRESOLVED, next: right.next };
+            }
+            if (v.length + right.value.length > MAX_STRING) {
+                this.report(k, `a string longer than ${MAX_STRING} characters`);
+                return { value: UNRESOLVED, next: right.next };
+            }
+            return { value: v + right.value, next: right.next };
+        }
         // An operator after the value means the real expression is a computation
         // (`base + '/a'`, `isProd ? a : b`, `a || fallback`, `nav[0].items`).
         // Returning just the LEFT operand handed back a confident, wrong answer —
@@ -852,8 +1035,8 @@ class Evaluator {
  * there is no `export default`, which covers
  * `const config = { … }; export { config }`.
  */
-export function evaluateModule(source, fallbackExport = "config") {
-    const ev = new Evaluator(source);
+export function evaluateModule(source, fallbackExport = "config", opts = {}) {
+    const ev = new Evaluator(source, opts);
     let value = UNRESOLVED;
     if (ev.hasBinding("default"))
         value = ev.resolveDefaultExport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/literal",
-  "version": "0.2.0-beta.132",
+  "version": "0.2.0-beta.134",
   "description": "Read a JavaScript/TypeScript config module as data without running it: object and array literals, spreads, module-level constants, zero-argument helpers and wrapper calls; anything else is reported, never guessed. No Node, no dependencies",
   "type": "module",
   "main": "dist/index.js",