@maroonedog/luq 2.0.0 → 2.2.0

package/dist/presets/presets.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.everydayRules = exports.arrays = exports.numbers = exports.strings = exports.presence = void 0;
+// ===========================================================================
+// L7  src/presets/presets.ts — 事前定義したプラグイン束。
+//
+// なぜ要るのか。プラグインを1つずつ import するのは「使った分しか入らない」
+// を成り立たせている仕組みそのものだが、最初の一本を書くのに15行の use() を
+// 並べさせるのは、その正しさの押し付けである。
+//
+// なぜ「小さいのを複数」なのか。全部入りを1つ置くと、5個しか要らない人が
+// 40個分のバイトを払う。束は型としてはただの `PluginBag` なので、必要な束
+// だけを `useAll()` すればよく、混ぜても first-wins で衝突しない:
+//
+//     Builder().useAll(presence).useAll(strings).for<User>()
+//
+// 何を入れるかはリポジトリ内の使用実績から決めた (test/ と docs-site/ の
+// use() を数えたもの)。required 138 / stringMin 95 / numberMin 43 /
+// stringEmail 33 / optional 26 という並びで、上位が束の中身になっている。
+//
+// バイト数は config/size-budget.json が測る。プリセットは便利さと引き換えに
+// バイトを払うものなので、いくら払うかは書いてあるべきである。
+// ===========================================================================
+const required_1 = require("../plugins/required");
+const optional_1 = require("../plugins/optional");
+const nullable_1 = require("../plugins/nullable");
+const string_min_1 = require("../plugins/string-min");
+const string_max_1 = require("../plugins/string-max");
+const string_pattern_1 = require("../plugins/string-pattern");
+const string_email_1 = require("../plugins/string-email");
+const number_min_1 = require("../plugins/number-min");
+const number_max_1 = require("../plugins/number-max");
+const number_integer_1 = require("../plugins/number-integer");
+const array_min_length_1 = require("../plugins/array-min-length");
+const array_max_length_1 = require("../plugins/array-max-length");
+const array_each_1 = require("../plugins/array-each");
+/**
+ * 在る・無い・null。ほぼ全ての宣言がこの三つのどれかを使う。
+ * 使用実績: required 138 / optional 26 / nullable 12。
+ */
+exports.presence = Object.freeze({
+    required: required_1.requiredPlugin,
+    optional: optional_1.optionalPlugin,
+    nullable: nullable_1.nullablePlugin,
+});
+/** 文字列の定番。使用実績: stringMin 95 / stringEmail 33 / stringPattern 12。 */
+exports.strings = Object.freeze({
+    stringMin: string_min_1.stringMinPlugin,
+    stringMax: string_max_1.stringMaxPlugin,
+    stringPattern: string_pattern_1.stringPatternPlugin,
+    stringEmail: string_email_1.stringEmailPlugin,
+});
+/** 数値の定番。使用実績: numberMin 43 / numberMax 8。 */
+exports.numbers = Object.freeze({
+    numberMin: number_min_1.numberMinPlugin,
+    numberMax: number_max_1.numberMaxPlugin,
+    numberInteger: number_integer_1.numberIntegerPlugin,
+});
+/** 配列の定番。要素ごとの規則は arrayEach が運ぶ。 */
+exports.arrays = Object.freeze({
+    arrayMinLength: array_min_length_1.arrayMinLengthPlugin,
+    arrayMaxLength: array_max_length_1.arrayMaxLengthPlugin,
+    arrayEach: array_each_1.arrayEachPlugin,
+});
+/**
+ * 上の四つを合わせたもの。13プラグイン、gzip で +1,452 B。
+ *
+ * 名前が「common」でないのは、それが何も言っていないからである
+ * (lint の禁止語彙にも入っている)。入っているのは presence と、文字列・数値・
+ * 配列それぞれの定番で、毎日書くのはこの範囲だ、という主張がこの名前である。
+ *
+ * これでも「全部入り」ではない。全部入りが要るなら `@maroonedog/luq/plugins`
+ * のバレルがあり、そちらは 77 個ぶん、gzip で +17,986 B を払う。
+ */
+exports.everydayRules = Object.freeze({
+    ...exports.presence,
+    ...exports.strings,
+    ...exports.numbers,
+    ...exports.arrays,
+});

package/dist/presets/presets.mjs

@@ -0,0 +1,77 @@
+// ===========================================================================
+// L7  src/presets/presets.ts — 事前定義したプラグイン束。
+//
+// なぜ要るのか。プラグインを1つずつ import するのは「使った分しか入らない」
+// を成り立たせている仕組みそのものだが、最初の一本を書くのに15行の use() を
+// 並べさせるのは、その正しさの押し付けである。
+//
+// なぜ「小さいのを複数」なのか。全部入りを1つ置くと、5個しか要らない人が
+// 40個分のバイトを払う。束は型としてはただの `PluginBag` なので、必要な束
+// だけを `useAll()` すればよく、混ぜても first-wins で衝突しない:
+//
+//     Builder().useAll(presence).useAll(strings).for<User>()
+//
+// 何を入れるかはリポジトリ内の使用実績から決めた (test/ と docs-site/ の
+// use() を数えたもの)。required 138 / stringMin 95 / numberMin 43 /
+// stringEmail 33 / optional 26 という並びで、上位が束の中身になっている。
+//
+// バイト数は config/size-budget.json が測る。プリセットは便利さと引き換えに
+// バイトを払うものなので、いくら払うかは書いてあるべきである。
+// ===========================================================================
+import { requiredPlugin } from "../plugins/required/index.mjs";
+import { optionalPlugin } from "../plugins/optional/index.mjs";
+import { nullablePlugin } from "../plugins/nullable/index.mjs";
+import { stringMinPlugin } from "../plugins/string-min/index.mjs";
+import { stringMaxPlugin } from "../plugins/string-max/index.mjs";
+import { stringPatternPlugin } from "../plugins/string-pattern/index.mjs";
+import { stringEmailPlugin } from "../plugins/string-email/index.mjs";
+import { numberMinPlugin } from "../plugins/number-min/index.mjs";
+import { numberMaxPlugin } from "../plugins/number-max/index.mjs";
+import { numberIntegerPlugin } from "../plugins/number-integer/index.mjs";
+import { arrayMinLengthPlugin } from "../plugins/array-min-length/index.mjs";
+import { arrayMaxLengthPlugin } from "../plugins/array-max-length/index.mjs";
+import { arrayEachPlugin } from "../plugins/array-each/index.mjs";
+/**
+ * 在る・無い・null。ほぼ全ての宣言がこの三つのどれかを使う。
+ * 使用実績: required 138 / optional 26 / nullable 12。
+ */
+export const presence = Object.freeze({
+    required: requiredPlugin,
+    optional: optionalPlugin,
+    nullable: nullablePlugin,
+});
+/** 文字列の定番。使用実績: stringMin 95 / stringEmail 33 / stringPattern 12。 */
+export const strings = Object.freeze({
+    stringMin: stringMinPlugin,
+    stringMax: stringMaxPlugin,
+    stringPattern: stringPatternPlugin,
+    stringEmail: stringEmailPlugin,
+});
+/** 数値の定番。使用実績: numberMin 43 / numberMax 8。 */
+export const numbers = Object.freeze({
+    numberMin: numberMinPlugin,
+    numberMax: numberMaxPlugin,
+    numberInteger: numberIntegerPlugin,
+});
+/** 配列の定番。要素ごとの規則は arrayEach が運ぶ。 */
+export const arrays = Object.freeze({
+    arrayMinLength: arrayMinLengthPlugin,
+    arrayMaxLength: arrayMaxLengthPlugin,
+    arrayEach: arrayEachPlugin,
+});
+/**
+ * 上の四つを合わせたもの。13プラグイン、gzip で +1,452 B。
+ *
+ * 名前が「common」でないのは、それが何も言っていないからである
+ * (lint の禁止語彙にも入っている)。入っているのは presence と、文字列・数値・
+ * 配列それぞれの定番で、毎日書くのはこの範囲だ、という主張がこの名前である。
+ *
+ * これでも「全部入り」ではない。全部入りが要るなら `@maroonedog/luq/plugins`
+ * のバレルがあり、そちらは 77 個ぶん、gzip で +17,986 B を払う。
+ */
+export const everydayRules = Object.freeze({
+    ...presence,
+    ...strings,
+    ...numbers,
+    ...arrays,
+});

package/dist/runtime/create-field-validator.js

@@ -56,15 +56,31 @@ function createSubjectComposer(template) {
         const write = (0, create_value_writer_1.createValueWriter)(template);
         return (siblings, value) => write(siblings ?? {}, value);
     }
-    return (siblings, value) => mergeOntoSiblings(siblings, nestValue(template, 0, value));
+    const nest = compileNester(template);
+    return (siblings, value) => mergeOntoSiblings(siblings, nest(value));
 }
-function nestValue(template, from, value) {
-    const segment = template[from];
-    if (segment === undefined)
-        return value;
-    if (segment.kind === "each")
-        return [nestValue(template, from + 1, value)];
-    return { [segment.key]: nestValue(template, from + 1, value) };
+/**
+ * テンプレートを **一度だけ** 歩いて、包む関数に畳んでおく。
+ *
+ * 以前はここが `nestValue(template, 0, value)` で、検証のたびにテンプレートを
+ * 歩き直して `segment.kind` を読み直していた。src/compile/validation-plan.types.ts
+ * が書いているとおり「実行時はルールが何であるかを決め直してはならない。
+ * 決めるのはコンパイルが済ませたこと」であり、ここはその例外になっていた。
+ * 非ワイルドカードの経路 (createValueWriter) は最初からこの形である。
+ */
+function compileNester(template) {
+    let nest = (value) => value;
+    for (let index = template.length - 1; index >= 0; index -= 1) {
+        const segment = template[index];
+        if (segment === undefined)
+            continue;
+        const inner = nest;
+        nest =
+            segment.kind === "each"
+                ? (value) => [inner(value)]
+                : ((key) => (value) => ({ [key]: inner(value) }))(segment.key);
+    }
+    return nest;
 }
 /** The wrapper wins on the key it names; every other sibling survives. */
 function mergeOntoSiblings(siblings, fragment) {

package/dist/runtime/create-field-validator.mjs

@@ -53,15 +53,31 @@ function createSubjectComposer(template) {
         const write = createValueWriter(template);
         return (siblings, value) => write(siblings ?? {}, value);
     }
-    return (siblings, value) => mergeOntoSiblings(siblings, nestValue(template, 0, value));
+    const nest = compileNester(template);
+    return (siblings, value) => mergeOntoSiblings(siblings, nest(value));
 }
-function nestValue(template, from, value) {
-    const segment = template[from];
-    if (segment === undefined)
-        return value;
-    if (segment.kind === "each")
-        return [nestValue(template, from + 1, value)];
-    return { [segment.key]: nestValue(template, from + 1, value) };
+/**
+ * テンプレートを **一度だけ** 歩いて、包む関数に畳んでおく。
+ *
+ * 以前はここが `nestValue(template, 0, value)` で、検証のたびにテンプレートを
+ * 歩き直して `segment.kind` を読み直していた。src/compile/validation-plan.types.ts
+ * が書いているとおり「実行時はルールが何であるかを決め直してはならない。
+ * 決めるのはコンパイルが済ませたこと」であり、ここはその例外になっていた。
+ * 非ワイルドカードの経路 (createValueWriter) は最初からこの形である。
+ */
+function compileNester(template) {
+    let nest = (value) => value;
+    for (let index = template.length - 1; index >= 0; index -= 1) {
+        const segment = template[index];
+        if (segment === undefined)
+            continue;
+        const inner = nest;
+        nest =
+            segment.kind === "each"
+                ? (value) => [inner(value)]
+                : ((key) => (value) => ({ [key]: inner(value) }))(segment.key);
+    }
+    return nest;
 }
 /** The wrapper wins on the key it names; every other sibling survives. */
 function mergeOntoSiblings(siblings, fragment) {

package/dist/runtime/create-validator.js

@@ -39,7 +39,34 @@ function rejectMissingRoot() {
 function hasRejectingIssue(issues) {
     return issues.some((issue) => issue.severity === "error");
 }
-function runRoot(plan, value, options, targets, shouldApplyTransforms) {
+/**
+ * 再帰しないプランのための、共有の何もしないランナー。
+ *
+ * createRecursionRunner は WeakSet と四つのクロージャを作る。プランに
+ * 再帰規則が一つも無くても validate() のたびに作っていて、それが固定コストの
+ * 88% を占めていた — 計測で 9.7%。プランが再帰を含むかは build() 時に
+ * 分かることで、実行時に問い直すことではない。
+ *
+ * 呼ばれることはない。呼ばれるのは field.recursion が null でない場合だけで、
+ * そのときは planCanRecurse が true を返しているので本物が渡っている。
+ */
+const NO_RECURSION = () => { };
+/**
+ * ルートのランナーが要るか。
+ *
+ * 見るのはルートの直下と配列ノードの要素だけでよい。合成 (oneOf など) の
+ * 枝は run-branch が自前のランナーを作って入れ子のプランを回すので、
+ * ここで渡すものを使わない。
+ */
+function planCanRecurse(plan) {
+    return (plan.fields.some((field) => field.recursion !== null) ||
+        plan.arrays.some(nodeCanRecurse));
+}
+function nodeCanRecurse(node) {
+    return (node.elementFields.some((field) => field.recursion !== null) ||
+        node.nested.some(nodeCanRecurse));
+}
+function runRoot(plan, value, options, targets, shouldApplyTransforms, canRecurse) {
     if (value === null || value === undefined)
         return rejectMissingRoot();
     const sink = new issue_sink_1.IssueSink((0, issue_sink_1.resolveAbortPolicy)(options));
@@ -48,11 +75,13 @@ function runRoot(plan, value, options, targets, shouldApplyTransforms) {
         sink,
         indices: new index_stack_1.IndexStack(),
         shouldApplyTransforms,
-        runRecursion: (0, run_recursion_1.createRecursionRunner)({
-            root: value,
-            sink,
-            external: options?.external,
-        }),
+        runRecursion: canRecurse
+            ? (0, run_recursion_1.createRecursionRunner)({
+                root: value,
+                sink,
+                external: options?.external,
+            })
+            : NO_RECURSION,
         external: options?.external,
     }, targets);
     const issues = Object.freeze(sink.issues);
@@ -63,8 +92,9 @@ function runRoot(plan, value, options, targets, shouldApplyTransforms) {
 function createValidator(plan) {
     const parseTargets = (0, output_writer_1.createPlanWriteTargets)(plan);
     const shouldWriteOutput = parseTargets !== null;
+    const canRecurse = planCanRecurse(plan);
     return {
-        validate: (value, options) => runRoot(plan, value, options, output_writer_1.NO_WRITE_TARGETS, false),
-        parse: (value, options) => runRoot(plan, value, options, parseTargets ?? output_writer_1.NO_WRITE_TARGETS, shouldWriteOutput),
+        validate: (value, options) => runRoot(plan, value, options, output_writer_1.NO_WRITE_TARGETS, false, canRecurse),
+        parse: (value, options) => runRoot(plan, value, options, parseTargets ?? output_writer_1.NO_WRITE_TARGETS, shouldWriteOutput, canRecurse),
     };
 }

package/dist/runtime/create-validator.mjs

@@ -34,7 +34,34 @@ function rejectMissingRoot() {
 export function hasRejectingIssue(issues) {
     return issues.some((issue) => issue.severity === "error");
 }
-function runRoot(plan, value, options, targets, shouldApplyTransforms) {
+/**
+ * 再帰しないプランのための、共有の何もしないランナー。
+ *
+ * createRecursionRunner は WeakSet と四つのクロージャを作る。プランに
+ * 再帰規則が一つも無くても validate() のたびに作っていて、それが固定コストの
+ * 88% を占めていた — 計測で 9.7%。プランが再帰を含むかは build() 時に
+ * 分かることで、実行時に問い直すことではない。
+ *
+ * 呼ばれることはない。呼ばれるのは field.recursion が null でない場合だけで、
+ * そのときは planCanRecurse が true を返しているので本物が渡っている。
+ */
+const NO_RECURSION = () => { };
+/**
+ * ルートのランナーが要るか。
+ *
+ * 見るのはルートの直下と配列ノードの要素だけでよい。合成 (oneOf など) の
+ * 枝は run-branch が自前のランナーを作って入れ子のプランを回すので、
+ * ここで渡すものを使わない。
+ */
+function planCanRecurse(plan) {
+    return (plan.fields.some((field) => field.recursion !== null) ||
+        plan.arrays.some(nodeCanRecurse));
+}
+function nodeCanRecurse(node) {
+    return (node.elementFields.some((field) => field.recursion !== null) ||
+        node.nested.some(nodeCanRecurse));
+}
+function runRoot(plan, value, options, targets, shouldApplyTransforms, canRecurse) {
     if (value === null || value === undefined)
         return rejectMissingRoot();
     const sink = new IssueSink(resolveAbortPolicy(options));
@@ -43,11 +70,13 @@ function runRoot(plan, value, options, targets, shouldApplyTransforms) {
         sink,
         indices: new IndexStack(),
         shouldApplyTransforms,
-        runRecursion: createRecursionRunner({
-            root: value,
-            sink,
-            external: options?.external,
-        }),
+        runRecursion: canRecurse
+            ? createRecursionRunner({
+                root: value,
+                sink,
+                external: options?.external,
+            })
+            : NO_RECURSION,
         external: options?.external,
     }, targets);
     const issues = Object.freeze(sink.issues);
@@ -58,8 +87,9 @@ function runRoot(plan, value, options, targets, shouldApplyTransforms) {
 export function createValidator(plan) {
     const parseTargets = createPlanWriteTargets(plan);
     const shouldWriteOutput = parseTargets !== null;
+    const canRecurse = planCanRecurse(plan);
     return {
-        validate: (value, options) => runRoot(plan, value, options, NO_WRITE_TARGETS, false),
-        parse: (value, options) => runRoot(plan, value, options, parseTargets ?? NO_WRITE_TARGETS, shouldWriteOutput),
+        validate: (value, options) => runRoot(plan, value, options, NO_WRITE_TARGETS, false, canRecurse),
+        parse: (value, options) => runRoot(plan, value, options, parseTargets ?? NO_WRITE_TARGETS, shouldWriteOutput, canRecurse),
     };
 }

package/dist/runtime/decide-presence.js

@@ -6,7 +6,8 @@ const create_issue_1 = require("./create-issue");
 function decidePresence(field, value, ruleContext, sink) {
     const policy = selectPolicy(field, ruleContext);
     const isMissing = value === undefined || (policy.emptyStringIsMissing && value === "");
-    if (!isMissing && value !== null)
+    // null continues to the checks when the subject says null is a value.
+    if (!isMissing && (value !== null || policy.nullIsValue))
         return true;
     const isAllowed = isMissing ? policy.allowUndefined : policy.allowNull;
     return reportUnlessAllowed(policy, isAllowed, value, ruleContext.path, sink);

package/dist/runtime/decide-presence.mjs

@@ -3,7 +3,8 @@ import { createIssue } from "./create-issue.mjs";
 export function decidePresence(field, value, ruleContext, sink) {
     const policy = selectPolicy(field, ruleContext);
     const isMissing = value === undefined || (policy.emptyStringIsMissing && value === "");
-    if (!isMissing && value !== null)
+    // null continues to the checks when the subject says null is a value.
+    if (!isMissing && (value !== null || policy.nullIsValue))
         return true;
     const isAllowed = isMissing ? policy.allowUndefined : policy.allowNull;
     return reportUnlessAllowed(policy, isAllowed, value, ruleContext.path, sink);

package/dist/runtime/field-rule-context.d.ts

@@ -0,0 +1,32 @@
+import type { ArrayItemContext, RuleContext } from "../types";
+import type { IndexStack } from "./index-stack";
+export declare class FieldRuleContext implements RuleContext {
+    readonly root: unknown;
+    private readonly indices;
+    /** Built at compile time, relative to the subject this field reads from. */
+    private readonly ownPath;
+    readonly item: ArrayItemContext | undefined;
+    readonly external: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * The path once something has asked for it. `null` rather than `""` because
+     * the empty string is a real path — the root.
+     *
+     * It is remembered because the index stack underneath is MUTABLE and is
+     * popped when the element ends. A rule that kept its context and read `path`
+     * afterwards would otherwise see wherever the runner had moved on to.
+     * Reading it during the rule's own call — which is what every rule does —
+     * pins it.
+     */
+    private rendered;
+    constructor(root: unknown, indices: IndexStack, 
+    /** Built at compile time, relative to the subject this field reads from. */
+    ownPath: string, item: ArrayItemContext | undefined, external: Readonly<Record<string, unknown>> | undefined);
+    get path(): string;
+    /**
+     * Serialising a context is a thing people do when they log a failure, and a
+     * prototype getter would silently drop `path` from the output. This pins the
+     * JSON shape to the four DECLARED members and, as a side effect, stops the
+     * internals above from reaching a log line.
+     */
+    toJSON(): Record<string, unknown>;
+}

package/dist/runtime/field-rule-context.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldRuleContext = void 0;
+class FieldRuleContext {
+    constructor(root, indices, 
+    /** Built at compile time, relative to the subject this field reads from. */
+    ownPath, item, external) {
+        this.root = root;
+        this.indices = indices;
+        this.ownPath = ownPath;
+        this.item = item;
+        this.external = external;
+        /**
+         * The path once something has asked for it. `null` rather than `""` because
+         * the empty string is a real path — the root.
+         *
+         * It is remembered because the index stack underneath is MUTABLE and is
+         * popped when the element ends. A rule that kept its context and read `path`
+         * afterwards would otherwise see wherever the runner had moved on to.
+         * Reading it during the rule's own call — which is what every rule does —
+         * pins it.
+         */
+        this.rendered = null;
+    }
+    get path() {
+        const already = this.rendered;
+        if (already !== null)
+            return already;
+        const built = this.indices.renderFieldPath(this.ownPath);
+        this.rendered = built;
+        return built;
+    }
+    /**
+     * Serialising a context is a thing people do when they log a failure, and a
+     * prototype getter would silently drop `path` from the output. This pins the
+     * JSON shape to the four DECLARED members and, as a side effect, stops the
+     * internals above from reaching a log line.
+     */
+    toJSON() {
+        return {
+            root: this.root,
+            path: this.path,
+            item: this.item,
+            external: this.external,
+        };
+    }
+}
+exports.FieldRuleContext = FieldRuleContext;

package/dist/runtime/field-rule-context.mjs

@@ -0,0 +1,44 @@
+export class FieldRuleContext {
+    constructor(root, indices, 
+    /** Built at compile time, relative to the subject this field reads from. */
+    ownPath, item, external) {
+        this.root = root;
+        this.indices = indices;
+        this.ownPath = ownPath;
+        this.item = item;
+        this.external = external;
+        /**
+         * The path once something has asked for it. `null` rather than `""` because
+         * the empty string is a real path — the root.
+         *
+         * It is remembered because the index stack underneath is MUTABLE and is
+         * popped when the element ends. A rule that kept its context and read `path`
+         * afterwards would otherwise see wherever the runner had moved on to.
+         * Reading it during the rule's own call — which is what every rule does —
+         * pins it.
+         */
+        this.rendered = null;
+    }
+    get path() {
+        const already = this.rendered;
+        if (already !== null)
+            return already;
+        const built = this.indices.renderFieldPath(this.ownPath);
+        this.rendered = built;
+        return built;
+    }
+    /**
+     * Serialising a context is a thing people do when they log a failure, and a
+     * prototype getter would silently drop `path` from the output. This pins the
+     * JSON shape to the four DECLARED members and, as a side effect, stops the
+     * internals above from reaching a log line.
+     */
+    toJSON() {
+        return {
+            root: this.root,
+            path: this.path,
+            item: this.item,
+            external: this.external,
+        };
+    }
+}

package/dist/runtime/index-stack.d.ts

@@ -1,11 +1,30 @@
-import type { PathSegment } from "../path/path-segment.types";
 export declare class IndexStack {
-    private readonly prefixes;
+    private readonly nodePaths;
     private readonly openIndices;
+    /**
+     * The rendered prefix, or `null` when it has not been asked for since the
+     * last push or pop. `null` and not `""` because the empty string is a real
+     * answer — the root.
+     *
+     * Invalidating rather than recomputing on push is the point: an element that
+     * raises no issue never renders its own prefix at all.
+     */
+    private currentPrefix;
     /** How many array levels are currently open. */
     get depth(): number;
     /** The open indices, outermost first: `[0, 2]` inside `grid[0][2]`. */
     get indices(): readonly number[];
+    /**
+     * The prefix for the currently open frames — `""` when none are open,
+     * `items[0]` inside one, `grid[0][2]` inside two.
+     *
+     * Indexed, never `nodePaths[nodePaths.length - 1]`. That expression at
+     * depth 0 is `nodePaths[-1]`, which is not an element read at all: -1 is
+     * outside the array, so V8 falls back to a named-property lookup and walks
+     * the prototype chain. The `prefix` getter used to be written that way and
+     * it took 12% of the array shape's self time.
+     */
+    private readTop;
     /** `""` at the root, `items[0]` inside the first element of `items`. */
     get prefix(): string;
     /**
@@ -21,8 +40,14 @@ export declare class IndexStack {
     push(nodePath: string, index: number): void;
     /** An unbalanced pop means a runner lost track of its own nesting. */
     pop(): void;
-    /** The issue path of a field read from the subject at the current level. */
-    renderFieldPath(template: readonly PathSegment[]): string;
+    /**
+     * The issue path of a field read from the subject at the current level.
+     *
+     * `renderedPath` was built once, at compile time. This used to walk the
+     * template on every call, which for an array meant rebuilding the same
+     * string once per element.
+     */
+    renderFieldPath(renderedPath: string): string;
 }
 /** `""` is the root path, so it never contributes a separator dot. */
 export declare function joinIssuePath(prefix: string, own: string): string;