@dogsbay/literal 0.0.0-stage → 0.2.0-beta.133

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @dogsbay/literal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read a JavaScript or TypeScript config module as data, without running it. No Node, no
+dependencies: it runs in a browser on someone else's repository.
+
+```ts
+import { evaluateModule, UNRESOLVED } from "@dogsbay/literal";
+
+const { value, unresolved } = evaluateModule(source); // the module's default export
+```
+
+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 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.
+
+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
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @dogsbay/literal — a tolerant, execution-free evaluator for the literal subset of a
+ * TypeScript/JavaScript module: config written as code, read as data.
+ *
+ * Why this exists: documentation tools keep their configuration in code. VitePress keeps
+ * the sidebar INSIDE `.vitepress/config.ts`; Docusaurus keeps it in `sidebars.js`. A real
+ * config imports theme packages, plugins and helpers, so *executing* it needs the source
+ * repo's `node_modules` installed and runs arbitrary code from that repo — on someone
+ * else's repo, in the CLI or in the playground's browser. No Node, no dependencies.
+ * (Moved out of format-vitepress on 2026-10-21 so every importer reads config one way.)
+ *
+ * So we read it instead. This module understands:
+ *
+ *   - object / array / string / number / boolean / null literals
+ *   - template literals with no `${}` interpolation
+ *   - `...spread` of anything else this module can evaluate
+ *   - module-level `const X = <literal>` identifier references
+ *   - 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`), 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
+ * not read (`EvalResult.unresolved`), because a sidebar that quietly lost a
+ * section looks exactly like a sidebar that never had one.
+ *
+ * The parser never desyncs: an expression it does not understand is skipped
+ * by balancing delimiters, so the surrounding object continues to parse.
+ */
+/** Sentinel for an expression this evaluator cannot read. */
+export declare const UNRESOLVED: unique symbol;
+export type LiteralValue = string | number | boolean | null | typeof UNRESOLVED | LiteralValue[] | {
+    [key: string]: LiteralValue;
+};
+export interface EvalResult {
+    /** The module's default export, evaluated as far as possible. */
+    value: LiteralValue;
+    /** 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.
+ *
+ * Falls back to the binding named by `fallbackExport` (default `config`) when
+ * there is no `export default`, which covers
+ * `const config = { … }; export { config }`.
+ */
+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;
+export declare function asString(v: LiteralValue): string | undefined;

package/dist/index.js

@@ -0,0 +1,1060 @@
+/**
+ * @dogsbay/literal — a tolerant, execution-free evaluator for the literal subset of a
+ * TypeScript/JavaScript module: config written as code, read as data.
+ *
+ * Why this exists: documentation tools keep their configuration in code. VitePress keeps
+ * the sidebar INSIDE `.vitepress/config.ts`; Docusaurus keeps it in `sidebars.js`. A real
+ * config imports theme packages, plugins and helpers, so *executing* it needs the source
+ * repo's `node_modules` installed and runs arbitrary code from that repo — on someone
+ * else's repo, in the CLI or in the playground's browser. No Node, no dependencies.
+ * (Moved out of format-vitepress on 2026-10-21 so every importer reads config one way.)
+ *
+ * So we read it instead. This module understands:
+ *
+ *   - object / array / string / number / boolean / null literals
+ *   - template literals with no `${}` interpolation
+ *   - `...spread` of anything else this module can evaluate
+ *   - module-level `const X = <literal>` identifier references
+ *   - 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`), 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
+ * not read (`EvalResult.unresolved`), because a sidebar that quietly lost a
+ * section looks exactly like a sidebar that never had one.
+ *
+ * The parser never desyncs: an expression it does not understand is skipped
+ * by balancing delimiters, so the surrounding object continues to parse.
+ */
+/** Sentinel for an expression this evaluator cannot read. */
+export const UNRESOLVED = Symbol("dogsbay.literal.unresolved");
+const IDENT_START = /[A-Za-z_$]/;
+const IDENT_PART = /[A-Za-z0-9_$]/;
+/**
+ * Positions after which a `/` begins a regex literal rather than division.
+ * Without this, `/['"]/ ` would open a phantom string and swallow the rest of
+ * the file.
+ */
+const REGEX_PRECEDERS = new Set([
+    "(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "=>", "+", "-",
+    "*", "%", "<", ">", "===", "!==", "==", "!=", "&&", "||", "??",
+]);
+const REGEX_PRECEDING_KEYWORDS = new Set([
+    "return", "typeof", "instanceof", "in", "of", "new", "delete", "void",
+    "case", "do", "else", "yield", "await",
+]);
+function tokenize(src) {
+    const toks = [];
+    let i = 0;
+    let line = 1;
+    const n = src.length;
+    const prevSignificant = () => toks[toks.length - 1];
+    while (i < n) {
+        const c = src[i];
+        if (c === "\n") {
+            line++;
+            i++;
+            continue;
+        }
+        if (c === " " || c === "\t" || c === "\r") {
+            i++;
+            continue;
+        }
+        // Comments
+        if (c === "/" && src[i + 1] === "/") {
+            while (i < n && src[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c === "/" && src[i + 1] === "*") {
+            i += 2;
+            while (i < n && !(src[i] === "*" && src[i + 1] === "/")) {
+                if (src[i] === "\n")
+                    line++;
+                i++;
+            }
+            i += 2;
+            continue;
+        }
+        // Regex literal (only where a value may start)
+        if (c === "/") {
+            const p = prevSignificant();
+            const isRegexPos = !p ||
+                (p.kind === "punct" && REGEX_PRECEDERS.has(p.text)) ||
+                (p.kind === "ident" && REGEX_PRECEDING_KEYWORDS.has(p.text));
+            if (isRegexPos) {
+                const start = i;
+                i++;
+                let inClass = false;
+                while (i < n) {
+                    const d = src[i];
+                    if (d === "\\") {
+                        i += 2;
+                        continue;
+                    }
+                    if (d === "[")
+                        inClass = true;
+                    else if (d === "]")
+                        inClass = false;
+                    else if (d === "/" && !inClass)
+                        break;
+                    else if (d === "\n")
+                        break; // unterminated — bail rather than run away
+                    i++;
+                }
+                i++; // closing slash
+                while (i < n && /[gimsuyd]/.test(src[i]))
+                    i++;
+                toks.push({ kind: "punct", text: "/regex/", start, line });
+                continue;
+            }
+        }
+        // Strings
+        if (c === '"' || c === "'") {
+            const start = i;
+            const quote = c;
+            i++;
+            let out = "";
+            while (i < n && src[i] !== quote) {
+                if (src[i] === "\\") {
+                    out += unescapeChar(src[i + 1]);
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === "\n")
+                    line++;
+                out += src[i];
+                i++;
+            }
+            i++;
+            toks.push({ kind: "str", text: out, start, line });
+            continue;
+        }
+        // Template literal
+        if (c === "`") {
+            const start = i;
+            i++;
+            let out = "";
+            let pure = true;
+            while (i < n && src[i] !== "`") {
+                if (src[i] === "\\") {
+                    out += unescapeChar(src[i + 1]);
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === "$" && src[i + 1] === "{") {
+                    pure = false;
+                    // Skip the interpolation, balancing braces (and nested templates).
+                    i += 2;
+                    let depth = 1;
+                    while (i < n && depth > 0) {
+                        if (src[i] === "{")
+                            depth++;
+                        else if (src[i] === "}")
+                            depth--;
+                        else if (src[i] === "\n")
+                            line++;
+                        i++;
+                    }
+                    continue;
+                }
+                if (src[i] === "\n")
+                    line++;
+                out += src[i];
+                i++;
+            }
+            i++;
+            toks.push({ kind: "template", text: out, pure, start, line });
+            continue;
+        }
+        // Numbers
+        if (/[0-9]/.test(c) || (c === "." && /[0-9]/.test(src[i + 1] ?? ""))) {
+            const start = i;
+            while (i < n && /[0-9a-fA-FxXoObBeE._+-]/.test(src[i])) {
+                // `+`/`-` only continue a number inside an exponent.
+                if ((src[i] === "+" || src[i] === "-") && !/[eE]/.test(src[i - 1]))
+                    break;
+                i++;
+            }
+            toks.push({ kind: "num", text: src.slice(start, i), start, line });
+            continue;
+        }
+        // Identifiers / keywords
+        if (IDENT_START.test(c)) {
+            const start = i;
+            while (i < n && IDENT_PART.test(src[i]))
+                i++;
+            toks.push({ kind: "ident", text: src.slice(start, i), start, line });
+            continue;
+        }
+        // Punctuation — longest match first so `=>` and `...` stay single tokens.
+        const three = src.slice(i, i + 3);
+        const two = src.slice(i, i + 2);
+        if (three === "..." || three === "===" || three === "!==") {
+            toks.push({ kind: "punct", text: three, start: i, line });
+            i += 3;
+            continue;
+        }
+        if (["=>", "==", "!=", "&&", "||", "??", "?.", "<=", ">=", "++", "--"].includes(two)) {
+            toks.push({ kind: "punct", text: two, start: i, line });
+            i += 2;
+            continue;
+        }
+        toks.push({ kind: "punct", text: c, start: i, line });
+        i++;
+    }
+    return toks;
+}
+function unescapeChar(c) {
+    switch (c) {
+        case "n":
+            return "\n";
+        case "t":
+            return "\t";
+        case "r":
+            return "\r";
+        case "0":
+            return "\0";
+        case undefined:
+            return "";
+        default:
+            return c;
+    }
+}
+// ── Parser / evaluator ────────────────────────────────────────────────────
+const OPENERS = { "{": "}", "[": "]", "(": ")" };
+/**
+ * Tokens that, appearing straight after a value, prove the expression is a
+ * computation rather than a literal. `[` is included: `nav[0]` is a computed
+ * index, and silently yielding `nav` returns a whole well-formed sidebar from
+ * the wrong node of the tree.
+ */
+const OPERATORS = new Set([
+    "+", "-", "*", "/", "%", "?", ":", "|", "&", "^",
+    "||", "&&", "??", "==", "!=", "===", "!==", "<", ">", "<=", ">=", "[",
+]);
+const CLOSERS = new Set(["}", "]", ")"]);
+/**
+ * The most values one result may expand to. A config is someone else's code: shared consts
+ * (`const s1 = { items: [s0, s0] }`, eighteen levels) are cheap here, where a reference is
+ * reused, and exponential for every caller that walks the result (184 MB of nav from a
+ * 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) {
+            this.report(i, `a value that expands to more than ${MAX_VALUES} entries`);
+            return UNRESOLVED;
+        }
+        this.sizes.set(out, size);
+        return out;
+    }
+    tok(i) {
+        return this.toks[i];
+    }
+    is(i, text) {
+        const t = this.toks[i];
+        return !!t && t.text === text && (t.kind === "punct" || t.kind === "ident");
+    }
+    report(i, what) {
+        const t = this.toks[i];
+        const where = t ? ` (line ${t.line})` : "";
+        const msg = `${what}${where}`;
+        if (!this.unresolved.includes(msg))
+            this.unresolved.push(msg);
+    }
+    /**
+     * Skip a balanced expression starting at `i`, stopping at a top-level `,`
+     * or a closer. Returns the index just past it. This is what keeps an
+     * unreadable expression from desyncing the enclosing object.
+     */
+    /**
+     * Skip `i` forward by at least one token.
+     *
+     * `skipValue` deliberately returns `i` UNCHANGED when it is already sitting
+     * on a closer, so every caller that loops must force progress or it spins
+     * forever. A computed key like `{ [base + "/"]: [...] }` leaves `k` on the
+     * `]` and hung the whole import with no output — a config that never
+     * returns is strictly worse than one that fails.
+     */
+    advance(i) {
+        const next = this.skipValue(i);
+        return next === i ? i + 1 : next;
+    }
+    skipValue(i) {
+        let depth = 0;
+        while (i < this.toks.length) {
+            const t = this.toks[i];
+            if (depth === 0 && t.kind === "punct" && (t.text === "," || CLOSERS.has(t.text))) {
+                return i;
+            }
+            if (t.kind === "punct" && OPENERS[t.text])
+                depth++;
+            else if (t.kind === "punct" && CLOSERS.has(t.text))
+                depth--;
+            i++;
+        }
+        return i;
+    }
+    /** Skip a TS type annotation from `:` until `=`, `=>`, `,` or a closer. */
+    /**
+     * Skip a balanced `<…>` type-argument list, returning the index just past
+     * `>`. `skipTypeAnnotation` cannot do this: it only stops at depth 0, so
+     * after `>` closed the generics it kept going into the argument list and
+     * swallowed the whole call — losing the entire config of a site using
+     * VitePress's own documented `defineConfigWithTheme<ThemeConfig>({…})`.
+     */
+    skipAngles(i) {
+        if (!this.is(i, "<"))
+            return i;
+        let depth = 0;
+        while (i < this.toks.length) {
+            const t = this.toks[i];
+            if (t.kind === "punct" && t.text === "<")
+                depth++;
+            else if (t.kind === "punct" && t.text === ">") {
+                depth--;
+                if (depth === 0)
+                    return i + 1;
+            }
+            else if (t.kind === "punct" && (t.text === "(" || t.text === "{")) {
+                // A `(`/`{` inside what we assumed were generics means it was not a
+                // type-argument list at all. Bail rather than run away.
+                return i;
+            }
+            i++;
+        }
+        return i;
+    }
+    /**
+     * From a `:` type annotation on a BINDING, find its `=`.
+     *
+     * A function type contains `=>` (`const s: () => Item[] = () => [...]`), and
+     * `skipTypeAnnotation` stops there — so the binding was never recorded and
+     * the sidebar it held was lost. `=>` is one token, so scanning for an exact
+     * `=` at depth 0 skips it naturally.
+     */
+    skipToAssign(i) {
+        let depth = 0;
+        while (i < this.toks.length) {
+            const t = this.toks[i];
+            if (depth === 0 && t.kind === "punct" && t.text === "=")
+                return i;
+            if (t.kind === "punct" && (OPENERS[t.text] || t.text === "<"))
+                depth++;
+            else if (t.kind === "punct" && (CLOSERS.has(t.text) || t.text === ">")) {
+                if (depth === 0)
+                    return i;
+                depth--;
+            }
+            i++;
+        }
+        return i;
+    }
+    skipTypeAnnotation(i) {
+        let depth = 0;
+        while (i < this.toks.length) {
+            const t = this.toks[i];
+            if (depth === 0 && t.kind === "punct" && (t.text === "=" || t.text === "=>"))
+                return i;
+            if (depth === 0 && t.kind === "punct" && (t.text === "," || CLOSERS.has(t.text)))
+                return i;
+            if (t.kind === "punct" && (OPENERS[t.text] || t.text === "<"))
+                depth++;
+            else if (t.kind === "punct" && (CLOSERS.has(t.text) || t.text === ">"))
+                depth--;
+            i++;
+        }
+        return i;
+    }
+    /** Index the module's top-level `const`/`function`/`export default`. */
+    collectBindings() {
+        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++;
+                continue;
+            }
+            if (t.kind === "punct" && CLOSERS.has(t.text)) {
+                depth--;
+                continue;
+            }
+            if (depth !== 0)
+                continue;
+            if (t.kind !== "ident")
+                continue;
+            // `export default <expr>` — also the wrapped `export default defineConfig({…})`.
+            if (t.text === "export" && this.is(i + 1, "default")) {
+                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);
+            if (!kw || kw.kind !== "ident")
+                continue;
+            if (kw.text === "const" || kw.text === "let" || kw.text === "var") {
+                const name = this.tok(j + 1);
+                if (!name || name.kind !== "ident")
+                    continue;
+                let k = j + 2;
+                if (this.is(k, ":"))
+                    k = this.skipToAssign(k + 1);
+                if (!this.is(k, "="))
+                    continue;
+                this.bindings.set(name.text, { at: k + 1 });
+                continue;
+            }
+            if (kw.text === "function") {
+                // `function f() { … return <expr> … }`
+                let k = j + 1;
+                if (this.is(k, "*"))
+                    k++;
+                const name = this.tok(k);
+                if (!name || name.kind !== "ident")
+                    continue;
+                const bodyStart = this.findFunctionBody(k + 1);
+                if (bodyStart < 0)
+                    continue;
+                const ret = this.findReturn(bodyStart);
+                if (ret >= 0)
+                    this.bindings.set(name.text, { at: ret });
+            }
+        }
+    }
+    /** From after a function name, find the index just past `{` of its body. */
+    findFunctionBody(i) {
+        // params
+        if (!this.is(i, "(")) {
+            // Possibly a generic `<T>` first.
+            if (this.is(i, "<"))
+                i = this.skipTypeAnnotation(i);
+            if (!this.is(i, "("))
+                return -1;
+        }
+        i = this.skipBalanced(i);
+        if (this.is(i, ":"))
+            i = this.skipTypeAnnotation(i + 1);
+        if (!this.is(i, "{"))
+            return -1;
+        return i + 1;
+    }
+    /** Index just past the group opened at `i`. */
+    skipBalanced(i) {
+        if (!this.toks[i] || !OPENERS[this.toks[i].text])
+            return i;
+        let depth = 0;
+        while (i < this.toks.length) {
+            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)
+                    return i + 1;
+            }
+            i++;
+        }
+        return i;
+    }
+    /** First `return` at body depth 0, from `i` (already inside the body). */
+    findReturn(i) {
+        let depth = 0;
+        while (i < this.toks.length) {
+            const t = this.toks[i];
+            if (t.kind === "punct" && OPENERS[t.text])
+                depth++;
+            else if (t.kind === "punct" && CLOSERS.has(t.text)) {
+                if (depth === 0)
+                    return -1; // end of function body
+                depth--;
+            }
+            else if (depth === 0 && t.kind === "ident" && t.text === "return") {
+                return i + 1;
+            }
+            i++;
+        }
+        return -1;
+    }
+    /** Evaluate a named module binding (memoized, cycle-safe). */
+    resolveBinding(name) {
+        const b = this.bindings.get(name);
+        if (!b)
+            return UNRESOLVED;
+        if (b.computing)
+            return UNRESOLVED;
+        if (b.value !== undefined)
+            return b.value;
+        b.computing = true;
+        const v = b.from !== undefined ? this.required(b.from, b.at) : this.parseValue(b.at).value;
+        b.computing = false;
+        b.value = v;
+        return v;
+    }
+    hasBinding(name) {
+        return this.bindings.has(name);
+    }
+    /**
+     * The default export, with one extra allowance: VitePress accepts a config
+     * that is a FUNCTION of the build context (`export default ({ mode }) => ({…})`
+     * — vitest's shape). We cannot supply that context, so we read the function's
+     * return expression directly.
+     *
+     * This is deliberately scoped to the default export. Treating any
+     * parameterized arrow as its own body would evaluate `.map(x => …)`
+     * callbacks as data, which is how a wrong value gets into a sidebar.
+     */
+    resolveDefaultExport() {
+        const b = this.bindings.get("default");
+        if (!b)
+            return UNRESOLVED;
+        let k = b.at;
+        if (this.is(k, "async"))
+            k++;
+        if (this.is(k, "function")) {
+            let j = k + 1;
+            if (this.toks[j]?.kind === "ident")
+                j++;
+            const body = this.findFunctionBody(j);
+            const ret = body < 0 ? -1 : this.findReturn(body);
+            return ret < 0 ? UNRESOLVED : this.parseValue(ret).value;
+        }
+        if (this.is(k, "(")) {
+            let j = this.skipBalanced(k);
+            if (this.is(j, ":"))
+                j = this.skipTypeAnnotation(j + 1);
+            if (this.is(j, "=>")) {
+                const body = j + 1;
+                if (this.is(body, "{")) {
+                    const ret = this.findReturn(body + 1);
+                    return ret < 0 ? UNRESOLVED : this.parseValue(ret).value;
+                }
+                return this.parseValue(body).value;
+            }
+        }
+        return this.resolveBinding("default");
+    }
+    /** 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 };
+        // Unary minus on a number.
+        if (t.kind === "punct" && t.text === "-" && this.toks[i + 1]?.kind === "num") {
+            return this.postfix(-Number(this.toks[i + 1].text), i + 2);
+        }
+        if (t.kind === "str")
+            return this.postfix(t.text, i + 1);
+        if (t.kind === "num")
+            return this.postfix(Number(t.text), i + 1);
+        if (t.kind === "template") {
+            if (t.pure)
+                return this.postfix(t.text, i + 1);
+            this.report(i, "template literal with interpolation");
+            return { value: UNRESOLVED, next: this.skipValue(i) };
+        }
+        if (t.kind === "ident") {
+            if (t.text === "true")
+                return this.postfix(true, i + 1);
+            if (t.text === "false")
+                return this.postfix(false, i + 1);
+            if (t.text === "null")
+                return this.postfix(null, i + 1);
+            if (t.text === "undefined")
+                return this.postfix(UNRESOLVED, i + 1);
+            // Arrow with no params: `() => <expr>` is handled at `(`; a single
+            // bare param `x => …` is a function value we cannot call — unresolved.
+            if (this.is(i + 1, "=>")) {
+                this.report(i, `arrow function \`${t.text} => …\``);
+                return { value: UNRESOLVED, next: this.skipValue(i) };
+            }
+            // Call expression.
+            if (this.is(i + 1, "(") || this.is(i + 1, "<")) {
+                return this.parseCall(t.text, i);
+            }
+            // Identifier reference.
+            if (this.bindings.has(t.text)) {
+                return this.postfix(this.resolveBinding(t.text), i + 1);
+            }
+            // An imported or otherwise unknown identifier.
+            this.report(i, `identifier \`${t.text}\` (imported or computed)`);
+            return { value: UNRESOLVED, next: this.skipValue(i) };
+        }
+        if (t.kind === "punct") {
+            if (t.text === "[")
+                return this.parseArray(i);
+            if (t.text === "{")
+                return this.parseObject(i);
+            if (t.text === "(")
+                return this.parseParenOrArrow(i);
+        }
+        this.report(i, `unsupported expression starting with \`${t.text}\``);
+        return { value: UNRESOLVED, next: this.skipValue(i) };
+    }
+    /**
+     * `(…)` is either a parenthesized expression, or the parameter list of an
+     * arrow function. A ZERO-ARG arrow is callable by this evaluator, so it is
+     * treated as its own body: `const f = () => [ … ]` binds `f` to the array.
+     */
+    parseParenOrArrow(i) {
+        const afterParens = this.skipBalanced(i);
+        let k = afterParens;
+        if (this.is(k, ":"))
+            k = this.skipTypeAnnotation(k + 1);
+        if (this.is(k, "=>")) {
+            const zeroArg = this.is(i + 1, ")");
+            if (!zeroArg) {
+                this.report(i, "arrow function with parameters");
+                return { value: UNRESOLVED, next: this.skipValue(i) };
+            }
+            let body = k + 1;
+            if (this.is(body, "{")) {
+                const ret = this.findReturn(body + 1);
+                if (ret < 0) {
+                    this.report(i, "arrow function body with no literal `return`");
+                    return { value: UNRESOLVED, next: this.skipValue(i) };
+                }
+                const v = this.parseValue(ret).value;
+                return { value: v, next: this.skipBalanced(body) };
+            }
+            const { value } = this.parseValue(body);
+            return { value, next: this.skipValue(body) };
+        }
+        // Plain parenthesized expression.
+        const inner = this.parseValue(i + 1);
+        return this.postfix(inner.value, afterParens);
+    }
+    /**
+     * A call. Two shapes are readable:
+     *   - zero args on a module-level function/arrow → its literal body
+     *     (hono: `sidebar: { '/': sidebars() }`)
+     *   - one literal argument on an unknown function → the argument
+     *     (`defineConfig({…})`, `defineConfigWithTheme({…})`, `withMermaid({…})`)
+     */
+    parseCall(name, i) {
+        let open = i + 1;
+        if (this.is(open, "<"))
+            open = this.skipAngles(open); // generic type args
+        if (!this.is(open, "(")) {
+            this.report(i, `call to \`${name}\``);
+            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)) {
+                return this.postfix(this.resolveBinding(name), after);
+            }
+            this.report(i, `call to unknown function \`${name}()\``);
+            return { value: UNRESOLVED, next: after };
+        }
+        // A single-argument call on an unknown function is unwrapped ONLY in the
+        // config-wrapper shape: the argument is an object literal, or another call
+        // (wrappers nest — vitest's export is
+        // `withPwa(extendConfig(defineConfig({…})))`).
+        //
+        // It must NOT unwrap a single ARRAY argument. `vitepress-sidebar`, the most
+        // common sidebar plugin, is called `generateSidebar([{…}, {…}])` — and
+        // returning its options array as the sidebar produced a complete,
+        // plausible-looking nav made of plugin CONFIG, reported as fully resolved.
+        // A wrong sidebar that declares itself correct is the worst output this
+        // module can produce.
+        const arg = this.toks[open + 1];
+        const isObjectLiteral = arg?.kind === "punct" && arg.text === "{";
+        const isNestedCall = arg?.kind === "ident" && (this.is(open + 2, "(") || this.is(open + 2, "<"));
+        if (isObjectLiteral || isNestedCall) {
+            const { value, next } = this.parseValue(open + 1);
+            if (this.is(next, ")"))
+                return this.postfix(value, after);
+        }
+        this.report(i, `call to \`${name}(…)\``);
+        return { value: UNRESOLVED, next: after };
+    }
+    parseArray(i) {
+        const out = [];
+        let size = 1;
+        let k = i + 1;
+        while (k < this.toks.length && !this.is(k, "]")) {
+            if (this.is(k, ",")) {
+                k++;
+                continue;
+            }
+            if (this.is(k, "...")) {
+                const { value, next } = this.parseValue(k + 1);
+                // One at a time, and only while within budget: `push(...value)` overflowed the stack
+                if (Array.isArray(value)) {
+                    for (const v of value) {
+                        if (size > MAX_VALUES)
+                            break;
+                        out.push(v);
+                        size += this.sizeOf(v);
+                    }
+                }
+                else if (value !== UNRESOLVED)
+                    this.report(k, "spread of a non-array");
+                k = next;
+                continue;
+            }
+            const { value, next } = this.parseValue(k);
+            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);
+    }
+    parseObject(i) {
+        const out = {};
+        let k = i + 1;
+        while (k < this.toks.length && !this.is(k, "}")) {
+            if (this.is(k, ",") || this.is(k, ";")) {
+                k++;
+                continue;
+            }
+            if (this.is(k, "...")) {
+                const { value, next } = this.parseValue(k + 1);
+                // `typeof x === "object"` already excludes the UNRESOLVED symbol.
+                if (value && typeof value === "object" && !Array.isArray(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");
+                }
+                k = next;
+                continue;
+            }
+            // Key.
+            const kt = this.toks[k];
+            if (!kt)
+                break;
+            let key = null;
+            if (kt.kind === "str" || kt.kind === "template")
+                key = kt.text;
+            else if (kt.kind === "ident" || kt.kind === "num")
+                key = kt.text;
+            else if (kt.kind === "punct" && kt.text === "[") {
+                // Computed key — read it if it is a literal, else skip the entry.
+                const { value, next } = this.parseValue(k + 1);
+                k = next;
+                if (this.is(k, "]"))
+                    k++;
+                key = typeof value === "string" || typeof value === "number" ? String(value) : null;
+                if (key === null) {
+                    this.report(kt.start, "computed object key");
+                    k = this.is(k, ":") ? this.advance(k + 1) : this.advance(k);
+                    continue;
+                }
+                if (this.is(k, ":")) {
+                    const v = this.parseValue(k + 1);
+                    setKey(out, key, v.value);
+                    k = v.next;
+                }
+                continue;
+            }
+            else {
+                // Something unexpected in key position — skip one entry.
+                k = this.advance(k);
+                continue;
+            }
+            k++;
+            // Method shorthand `name() { … }` — a function, not data.
+            if (this.is(k, "(")) {
+                const bodyStart = this.findFunctionBody(k);
+                k = bodyStart < 0 ? this.skipValue(k) : this.skipBalanced(bodyStart - 1);
+                continue;
+            }
+            if (!this.is(k, ":")) {
+                // Shorthand `{ foo }`.
+                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);
+            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))
+            size += this.sizeOf(v);
+        return this.postfix(this.bounded(out, size, i), k + 1);
+    }
+    /**
+     * Postfix operators after a value: TS `as`/`satisfies`, and member access
+     * into a value we already have.
+     */
+    postfix(value, i) {
+        let v = value;
+        let k = i;
+        for (;;) {
+            if (this.is(k, "as") || this.is(k, "satisfies")) {
+                k = this.skipTypeAnnotation(k + 1);
+                continue;
+            }
+            if (this.is(k, "!")) {
+                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 || !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,
+                    // which is precisely the silent omission this module forbids.
+                    this.report(k, `property access \`.${prop}\` on a value this reader could not resolve`);
+                    v = UNRESOLVED;
+                }
+                else {
+                    v = obj[prop];
+                }
+                k += 2;
+                continue;
+            }
+            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 —
+        // `link: base + '/a'` became `link: "/guide"`, and `sidebar: nav[0].items`
+        // became the whole `nav` array — with nothing recorded as unresolved.
+        if (OPERATORS.has(this.toks[k]?.text ?? "") && this.toks[k]?.kind === "punct") {
+            this.report(k, `expression using \`${this.toks[k].text}\` (computed, not a literal)`);
+            return { value: UNRESOLVED, next: this.skipValue(k) };
+        }
+        return { value: v, next: k };
+    }
+}
+/**
+ * Evaluate a module's default export as far as the literal subset allows.
+ *
+ * Falls back to the binding named by `fallbackExport` (default `config`) when
+ * there is no `export default`, which covers
+ * `const config = { … }; export { config }`.
+ */
+export function evaluateModule(source, fallbackExport = "config", opts = {}) {
+    const ev = new Evaluator(source, opts);
+    let value = UNRESOLVED;
+    if (ev.hasBinding("default"))
+        value = ev.resolveDefaultExport();
+    if (value === UNRESOLVED && ev.hasBinding(fallbackExport)) {
+        value = ev.resolveBinding(fallbackExport);
+    }
+    return { value, unresolved: ev.unresolved };
+}
+/** Narrowing helper: a plain object with no UNRESOLVED identity. */
+export function asObject(v) {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+        return v;
+    }
+    return undefined;
+}
+export function asArray(v) {
+    return Array.isArray(v) ? v : undefined;
+}
+export function asString(v) {
+    return typeof v === "string" ? v : undefined;
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@dogsbay/literal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.133",
+  "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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/literal"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }