@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/pretty.js

@@ -0,0 +1,476 @@
+/**
+ * Pretty — formats JavaScript data structures with highlighting.
+ *
+ * Lives in `core/` beside `markup` and `emoji` because it does their job: turn
+ * foreign input into `RichText`. It composes no other renderable — the trait
+ * every file in `renderables/` shares and this one does not — and its imports
+ * are core primitives only. `Console.print` accepts `unknown` and must turn any
+ * of it into something renderable, so the formatter has to sit where `console`
+ * can reach it without an upward edge. [LAW:one-way-deps]
+ *
+ * Two traversals share this file, and the split is the whole design. `_format`
+ * lays a value out across lines; `_oneLine` answers only "does this fit on one
+ * line, and if so what is it?". They meet at `_shape`, which describes a
+ * container without committing to either layout. One traversal answering both
+ * questions is what made this formatter exponential: every child was rendered
+ * once to probe it and again to place it, so a node at depth d was visited 2^d
+ * times.
+ */
+import { cellLen } from "./cells.js";
+import { RichText } from "./text.js";
+import { ReprHighlighter } from "./highlighter.js";
+const reprHighlighter = new ReprHighlighter();
+const rootFrame = (maxWidth) => ({
+    inset: 0,
+    level: 0,
+    maxWidth,
+    column: 0,
+    reserve: 0,
+    open: new WeakSet(),
+});
+/**
+ * The column reached after `text` is appended to a line currently at `column`.
+ *
+ * A hole's formatted value can itself span multiple lines — a nested
+ * container that failed its own compact try. What comes after it (a Map
+ * entry's tail, the next hole) sits after `text`'s *last* line, not at
+ * `column + cellLen(text)`, so a multi-line insert resets the column to that
+ * last line's width instead of accumulating across lines that were never on
+ * the same row.
+ */
+function lineColumn(column, text) {
+    const lastNewline = text.lastIndexOf("\n");
+    return lastNewline === -1 ? column + cellLen(text) : cellLen(text.slice(lastNewline + 1));
+}
+/**
+ * The text, when it is a single line no wider than `budget` — otherwise `null`.
+ *
+ * The one definition of "fits on one line" in this file, and it has to name
+ * both halves: `cellLen` scores a newline as zero cells, so a width check alone
+ * accepted multi-line text as compact. That is how a `Map` nested in an object
+ * used to render as `{ m: Map {` — a one-line object with an expansion wedged
+ * inside it and the closing brace back at column 0.
+ */
+function fitOneLine(text, budget) {
+    return text.includes("\n") || cellLen(text) > budget ? null : text;
+}
+/**
+ * The elements of an indexed sequence, or `null` for anything that isn't one.
+ *
+ * A typed array is an array with a fixed element type, and neither of the two
+ * questions asked elsewhere in this file recognises it: `Array.isArray` says
+ * false, and its own `toString` answers the bare `1,2,3` — no brackets, nothing
+ * for the highlighter to colour per element. Both spellings reach the one arm
+ * that knows what a sequence looks like. `DataView` is excluded because it is a
+ * window onto bytes, not a sequence of values.
+ *
+ * Returned as `ArrayLike` rather than a materialised array because both
+ * spellings already are one. Converting here would box every element of a
+ * multi-megabyte `Buffer` to keep the first `maxLength` of them — bounding the
+ * output while leaving the cost of producing it unbounded.
+ */
+function indexedElements(value) {
+    if (Array.isArray(value))
+        return value;
+    if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+        return value;
+    }
+    return null;
+}
+/**
+ * The first `limit` items of a sequence, pulled and no more.
+ *
+ * A `Map` or `Set` reaches its size through `.size`, which iterates nothing, so
+ * spreading one only ever served to throw the tail away — `print` of a
+ * half-million-entry cache walked all of it to show a hundred. `Infinity` is
+ * the unbounded case and never breaks.
+ */
+function take(source, limit) {
+    const taken = [];
+    if (limit <= 0)
+        return taken;
+    for (const item of source) {
+        taken.push(item);
+        if (taken.length >= limit)
+            break;
+    }
+    return taken;
+}
+/**
+ * What a value renders as when reading it threw instead of producing it.
+ *
+ * `Pretty` reflects on data it did not create, and every reflection it performs
+ * — a property getter, `Object.keys`, an iterator, `toString` — can throw. The
+ * message travels into the output, so the failure stays visible and attributed
+ * to the position that produced it. [LAW:no-silent-failure] the error is
+ * carried rather than swallowed; a marker naming its cause is not an
+ * answer-shaped void, and a diagnostic that takes the program down over one
+ * lazily-computed field is unusable on the objects it is most wanted for.
+ */
+function threw(error) {
+    return `[Threw: ${error instanceof Error ? error.message : String(error)}]`;
+}
+/**
+ * Does this value carry its own string form, or must we reflect on its keys?
+ *
+ * A `Date`, an `Error`, a `RegExp`, or any object that defines `toString`
+ * answers the display question itself, and reflecting on such a value throws
+ * that answer away — `Object.keys(new Date())` is empty, so key-reflection
+ * renders it `{}`. Inheriting `Object.prototype.toString` is the opposite
+ * signal: it yields `[object Object]`, a non-answer, so the keys are all the
+ * information there is.
+ *
+ * Both clauses are load-bearing. The identity check separates the two
+ * populations; the `typeof` check is what makes `Object.create(null)` — which
+ * has no `toString` at all — reflect rather than throw.
+ */
+function describesItself(value) {
+    const asRecord = value;
+    return (typeof asRecord[Symbol.toPrimitive] === "function" ||
+        (typeof asRecord.toString === "function" &&
+            asRecord.toString !== Object.prototype.toString));
+}
+/** What joins a container's positions on one line. Its width is charged for, so it is named once. */
+const SEPARATOR = ", ";
+/**
+ * What joins a container's positions across lines, once it has expanded —
+ * `SEPARATOR` without the trailing space a newline already provides.
+ * rich-pretty-xms: named, and derived rather than a second hand-typed
+ * literal, so the width it costs a non-last slot's own compact try —
+ * reserved via `Frame.reserve` — cannot drift from what `_formatObject`
+ * actually joins with.
+ */
+const EXPAND_SEPARATOR = SEPARATOR.trimEnd();
+/** The marker for positions the bound dropped, or nothing when it dropped none. */
+const elided = (dropped) => dropped > 0 ? [{ head: `... +${dropped}`, holes: [] }] : [];
+export class Pretty {
+    data;
+    indent;
+    expandAll;
+    maxLength;
+    maxString;
+    maxDepth;
+    indentGuides;
+    highlighter;
+    constructor(data, options) {
+        this.data = data;
+        this.indent = options?.indent ?? 4;
+        this.expandAll = options?.expandAll ?? false;
+        this.maxLength = options?.maxLength;
+        this.maxString = options?.maxString;
+        this.maxDepth = options?.maxDepth ?? Infinity;
+        this.indentGuides = options?.indentGuides !== false;
+        this.highlighter = options?.highlighter ?? reprHighlighter;
+    }
+    *render(options) {
+        yield* this.toText(options).render(options);
+    }
+    /** The value laid out for `options.maxWidth` and highlighted: the text this renders. */
+    toText(options) {
+        const formatted = this._format(this.data, rootFrame(options.maxWidth));
+        const text = new RichText(formatted, { end: "" });
+        this.highlighter.highlight(text);
+        if (this.indentGuides) {
+            this._addIndentGuides(text);
+        }
+        return text;
+    }
+    measure(_options) {
+        const formatted = this._format(this.data, rootFrame(_options.maxWidth));
+        const lines = formatted.split("\n");
+        let max = 0;
+        for (const line of lines) {
+            max = Math.max(max, cellLen(line));
+        }
+        return { minimum: 1, maximum: Math.min(max, _options.maxWidth) };
+    }
+    /**
+     * The text a value shows without being reflected on, or `null` when it is an
+     * object and the shape arms own it.
+     *
+     * Every kind answered here renders the same wherever it sits — no
+     * indentation, no width to fit — which is why one method serves both
+     * traversals.
+     */
+    _scalar(value) {
+        if (value === null)
+            return "null";
+        if (value === undefined)
+            return "undefined";
+        switch (typeof value) {
+            case "string": {
+                // The dropped count is an annotation about the value, not part of it,
+                // so it goes after the closing quote — the way `maxLength`'s `... +N`
+                // sits beside the kept entries rather than inside the last one. Inside
+                // the quotes it reads as content, and copying it out yields a string
+                // the program never held.
+                if (this.maxString === undefined || value.length <= this.maxString) {
+                    return JSON.stringify(value);
+                }
+                return JSON.stringify(value.slice(0, this.maxString)) + `+${value.length - this.maxString}`;
+            }
+            case "number":
+            case "bigint":
+            case "boolean":
+                return String(value);
+            case "symbol":
+                return value.toString();
+            case "function":
+                return `[Function: ${value.name || "anonymous"}]`;
+        }
+        return null;
+    }
+    /**
+     * A container, or the text standing in for one that is empty or past the
+     * depth cap.
+     *
+     * `positions` is a thunk because both of those answers are reachable from
+     * `size` alone, and reaching a position is not free: a `Map` or `Set` reaches
+     * its own through an iterator, so enumerating one only to elide it drains a
+     * container to print `Set {...}`. `size` also says how many positions were
+     * dropped, which is where the elision marker comes from — one derivation, so
+     * the count and the bound cannot disagree.
+     */
+    _container(open, close, pad, size, level, positions) {
+        if (size === 0)
+            return { kind: "text", text: open + close };
+        if (level >= this.maxDepth)
+            return { kind: "text", text: open + "..." + close };
+        const slots = positions();
+        return { kind: "container", open, close, pad, slots: [...slots, ...elided(size - slots.length)] };
+    }
+    /**
+     * The brackets and positions of an object, layout-free. See `Shape`.
+     *
+     * `bound` is the most positions the caller could ever use. Laying out passes
+     * `Infinity`, because it prints every position it is handed. A probe passes
+     * what is left of its line, which is already more positions than a fitting
+     * one could hold — `SEPARATOR` charges two cells apiece, so a container with
+     * more positions than `budget` overruns however narrow its contents are.
+     * Reaching past it only ever feeds a join that returns `null`, and reaching a
+     * position is what drains a `Map` or `Set`.
+     */
+    _shape(value, level, bound) {
+        // Clamped because a probe's budget goes negative once a line is overrun,
+        // and `slice` reads a negative end as counting from the far end — it would
+        // keep all but the last few keys where the other arms take none.
+        const cap = Math.max(0, Math.min(this.maxLength ?? Infinity, bound));
+        const elements = indexedElements(value);
+        if (elements !== null) {
+            return this._container("[", "]", "", elements.length, level, () => {
+                // Positions rather than values: each index is read in its own slot, so
+                // one throwing accessor costs its own slot, not the whole sequence.
+                const shown = Math.min(elements.length, cap);
+                return Array.from({ length: shown }, (_, i) => ({
+                    head: "",
+                    holes: [{ read: () => elements[i], tail: "" }],
+                }));
+            });
+        }
+        if (value instanceof Map) {
+            return this._container("Map {", "}", " ", value.size, level, () => take(value.entries(), cap).map(([k, v]) => ({
+                head: "",
+                holes: [{ read: () => k, tail: " => " }, { read: () => v, tail: "" }],
+            })));
+        }
+        if (value instanceof Set) {
+            return this._container("Set {", "}", " ", value.size, level, () => take(value, cap).map((v) => ({
+                head: "",
+                holes: [{ read: () => v, tail: "" }],
+            })));
+        }
+        // Objects that answer the display question themselves. Sits below the
+        // Array/Map/Set arms deliberately: an array also overrides `toString`, but
+        // "1,2,3" is a poorer answer than the structural form above.
+        if (describesItself(value))
+            return { kind: "text", text: String(value) };
+        // Plain objects — no self-description, so the keys are the whole story.
+        const obj = value;
+        const keys = Object.keys(obj);
+        return this._container("{", "}", " ", keys.length, level, () => keys.slice(0, cap).map((k) => ({
+            head: `${k}: `,
+            holes: [{ read: () => obj[k], tail: "" }],
+        })));
+    }
+    /** The laid-out form of a value, expanded across lines wherever one line will not do. */
+    _format(value, at) {
+        const scalar = this._scalar(value);
+        if (scalar !== null)
+            return scalar;
+        const object = value;
+        if (at.open.has(object))
+            return "[Circular]";
+        at.open.add(object);
+        try {
+            return this._formatObject(object, at);
+        }
+        catch (error) {
+            // The container's *shape* would not be read — `Object.keys`, an iterator,
+            // `toString`. Nothing can be enumerated, so the whole container degrades;
+            // a value that merely would not be read degrades alone, in its own slot.
+            return threw(error);
+        }
+        finally {
+            at.open.delete(object);
+        }
+    }
+    /** The arms for a non-null object, with `value` already on the open path. */
+    _formatObject(value, at) {
+        const shape = this._shape(value, at.level, Infinity);
+        if (shape.kind === "text")
+            return shape.text;
+        if (!this.expandAll) {
+            // rich-pretty-xms: budget from `at.column` and `at.reserve`, not from
+            // `at.inset` alone. `at.column` is where *this* value's text actually
+            // starts on its line, which already includes whatever `_expandSlot`
+            // prepended for us (a key and its separator, a Map entry's `" => "`,
+            // ...); `at.reserve` is what a fixed piece of literal text — the rest
+            // of this hole's own tail, or the trailing `,` a non-last slot gets
+            // joined with — is known to cost right after, before this value's own
+            // text even starts. Deriving the budget from the indent alone assumed
+            // nothing precedes *or follows* the value on its line, which is only
+            // true at the root and for the last hole of an array's last element.
+            const compact = this._joinOneLine(shape, {
+                level: at.level + 1,
+                budget: at.maxWidth - at.column - at.reserve,
+                open: at.open,
+            });
+            if (compact !== null)
+                return compact;
+        }
+        const indentStr = " ".repeat(this.indent * at.inset);
+        const innerIndent = " ".repeat(this.indent * (at.inset + 1));
+        // Every non-last slot gets `EXPAND_SEPARATOR` appended right after it
+        // below, on the same line as whatever its own last character was — the
+        // last slot doesn't. Two frames, not one per slot: `reserve` is the only
+        // field that varies, and it only ever takes these two values.
+        const base = { inset: at.inset + 1, level: at.level + 1, maxWidth: at.maxWidth, column: cellLen(innerIndent), open: at.open };
+        const midFrame = { ...base, reserve: cellLen(EXPAND_SEPARATOR) };
+        const lastFrame = { ...base, reserve: 0 };
+        const lastSlot = shape.slots.length - 1;
+        const parts = shape.slots.map((slot, i) => innerIndent + this._expandSlot(slot, i === lastSlot ? lastFrame : midFrame));
+        return shape.open + "\n" + parts.join(EXPAND_SEPARATOR + "\n") + "\n" + indentStr + shape.close;
+    }
+    /**
+     * One position, with every value in it laid out.
+     *
+     * `at.column` is where `slot.head` begins. Rather than hand-tracking a
+     * second, parallel "column so far" alongside `out` — two values a future
+     * edit could update out of step, silently reintroducing a stale-budget bug
+     * of the same shape this file just fixed — each hole derives its own
+     * column fresh from `out` via `lineColumn`, the one place "text just
+     * emitted" becomes "column now". [LAW:one-source-of-truth] `out` is
+     * already the complete record; `column` is a read of it, not a second copy
+     * of the same fact. `_joinOneLine`'s probe sibling tracks the analogous
+     * thing via `budget` shrinking instead, because a probe already discards
+     * anything that overruns and so never needs to know where a multi-line
+     * insert's last line ends.
+     *
+     * Each hole's `reserve` is its own `tail` plus, only for the slot's last
+     * hole, whatever `at.reserve` already asked this whole slot to leave room
+     * for (`_formatObject`'s trailing `,`). An earlier hole's tail is never
+     * folded into a later hole's reserve — it is spent, not carried, the moment
+     * `out` grows past it.
+     */
+    _expandSlot(slot, at) {
+        let out = slot.head;
+        const lastHole = slot.holes.length - 1;
+        for (let i = 0; i < slot.holes.length; i++) {
+            const hole = slot.holes[i];
+            // This is the read that costs the least when it fails: neighbours are
+            // unaffected, so `{ a: 1, b: [Threw: …], c: 3 }` still shows everything
+            // that could be read.
+            let text;
+            try {
+                const reserve = cellLen(hole.tail) + (i === lastHole ? at.reserve : 0);
+                text = this._format(hole.read(), { ...at, column: lineColumn(at.column, out), reserve });
+            }
+            catch (error) {
+                text = threw(error);
+            }
+            out += text + hole.tail;
+        }
+        return out;
+    }
+    /** The one-line form of a value, or `null` when it will not fit `at.budget`. */
+    _oneLine(value, at) {
+        const scalar = this._scalar(value);
+        if (scalar !== null)
+            return fitOneLine(scalar, at.budget);
+        const object = value;
+        if (at.open.has(object))
+            return fitOneLine("[Circular]", at.budget);
+        at.open.add(object);
+        try {
+            const shape = this._shape(object, at.level, at.budget);
+            if (shape.kind === "text")
+                return fitOneLine(shape.text, at.budget);
+            return this._joinOneLine(shape, { level: at.level + 1, budget: at.budget, open: at.open });
+        }
+        catch (error) {
+            return fitOneLine(threw(error), at.budget);
+        }
+        finally {
+            at.open.delete(object);
+        }
+    }
+    /**
+     * A container's positions on one line, or `null` as soon as they overrun.
+     *
+     * The budget is spent as it goes and each position is asked for only what is
+     * left, so a subtree that has already outgrown the line is abandoned where it
+     * outgrew it rather than formatted in full and then measured.
+     *
+     * The brackets are charged before anything is read, and that ordering is what
+     * bounds the traversal: a budget checked only against the finished text still
+     * reads the whole subtree to produce text it then throws away. Charged first,
+     * every level costs at least the two cells of its own brackets, so a probe
+     * descends at most `budget / 2` levels however deep the data goes.
+     */
+    _joinOneLine(shape, at) {
+        let used = cellLen(shape.open) + cellLen(shape.close) + 2 * cellLen(shape.pad);
+        if (used > at.budget)
+            return null;
+        const pieces = [];
+        for (const slot of shape.slots) {
+            used += pieces.length > 0 ? cellLen(SEPARATOR) : 0;
+            const piece = this._slotOneLine(slot, { ...at, budget: at.budget - used });
+            if (piece === null)
+                return null;
+            used += cellLen(piece);
+            pieces.push(piece);
+        }
+        return shape.open + shape.pad + pieces.join(SEPARATOR) + shape.pad + shape.close;
+    }
+    /** One position on one line, or `null` when any value in it will not fit. */
+    _slotOneLine(slot, at) {
+        let out = slot.head;
+        for (const hole of slot.holes) {
+            const left = at.budget - cellLen(out);
+            let text;
+            try {
+                text = this._oneLine(hole.read(), { ...at, budget: left });
+            }
+            catch (error) {
+                text = fitOneLine(threw(error), left);
+            }
+            if (text === null)
+                return null;
+            out += text + hole.tail;
+        }
+        return fitOneLine(out, at.budget);
+    }
+    _addIndentGuides(text) {
+        const lines = text.plain.split("\n");
+        let offset = 0;
+        for (const line of lines) {
+            const leadingSpaces = line.length - line.trimStart().length;
+            for (let i = 0; i < leadingSpaces; i += this.indent) {
+                if (i + offset < text.length) {
+                    text.stylize("repr.indent", offset + i, offset + i + 1);
+                }
+            }
+            offset += line.length + 1; // +1 for newline
+        }
+    }
+}