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

package/README.md

@@ -1,3 +1,22 @@
-# 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 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.*`).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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`)
+ *   - TS noise: type annotations, `as const`, `as T`, `satisfies T`, generics
+ *
+ * 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[];
+}
+/**
+ * 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): 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,877 @@
+/**
+ * @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`)
+ *   - TS noise: type annotations, `as const`, `as T`, `satisfies T`, generics
+ *
+ * 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;
+class Evaluator {
+    toks;
+    bindings = new Map();
+    /** Each array or object built here → the values it expands to, itself included. */
+    sizes = new WeakMap();
+    unresolved = [];
+    sizeOf(v) {
+        return v !== null && typeof v === "object" ? (this.sizes.get(v) ?? 1) : 1;
+    }
+    /** `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;
+    }
+    constructor(src) {
+        this.toks = tokenize(src);
+        this.collectBindings();
+    }
+    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;
+            }
+            // 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 = 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) {
+        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);
+        // 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;
+        }
+        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)) {
+                    Object.assign(out, value);
+                }
+                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);
+                    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 }`.
+                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;
+            k = v.next === k + 1 ? this.skipValue(k + 1) : v.next;
+        }
+        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;
+            }
+            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) {
+                    // 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;
+        }
+        // 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") {
+    const ev = new Evaluator(source);
+    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.132",
+  "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"
+  }
 }