@maroonedog/luq 2.2.0 → 2.3.1

package/dist/plugins/object-additional-properties/select-additional-keys.mjs

@@ -1,22 +1,22 @@
 // ===========================================================================
 // L7  src/plugins/object-additional-properties/select-additional-keys.ts
 //
-// 「additional なキー」を選ぶ規則。boolean 形とスキーマ形の両方が使う。
+// Which keys count as "additional". Used by both the boolean form and the
+// schema form.
 //
-// Draft-07 §6.5.4 は additionalProperties の対象を「properties にも
-// patternProperties にも該当しないキー」と定めている。パターンを見落とすと
-// `{"patternProperties":{"^v":{}},"additionalProperties":false}` が
-// {"vroom":2} を誤って拒否する (スイートの
-// "patternProperties are not additional properties" がそれを突く)。
+// Draft-07 §6.5.4 defines them as the keys matched by neither `properties`
+// nor `patternProperties`. Miss the patterns and
+// `{"patternProperties":{"^v":{}},"additionalProperties":false}` wrongly
+// rejects {"vroom":2}.
 // ===========================================================================
 /**
- * パターンは build 時に一度だけコンパイルする。実行時は回すだけ、という
- * 設計に合わせるためで、キーごとに new RegExp すると O(キー数 x パターン数)
- * のコンパイルが毎回走る。
+ * Patterns are compiled once, at build time, matching the design where
+ * validation only runs what was already assembled. Compiling per key would
+ * cost O(keys × patterns) compilations on every call.
  *
- * 壊れた正規表現は無視する。スキーマ側の誤りでビルド全体を落とすより、
- * そのパターンが誰にも一致しないほうがまし (Draft-07 は ECMA-262 の
- * 正規表現を求めるが、方言差で通らないものが現実には来る)。
+ * A broken pattern is ignored rather than fatal. Draft-07 asks for ECMA-262
+ * regular expressions and real documents arrive with dialect differences;
+ * having that one pattern match nothing beats refusing the whole build.
  */
 export function compilePatterns(patterns) {
     if (patterns === undefined || patterns.length === 0)
@@ -28,19 +28,19 @@ export function compilePatterns(patterns) {
         }
         catch {
             try {
-                // "u" が付くと通らない書き方が現実にはある。付けずにもう一度試す。
+                // Some real patterns fail only under "u". Try again without it.
                 compiled.push(new RegExp(pattern));
             }
             catch {
-                // どちらでも駄目なら、このパターンは一致しないものとして扱う。
+                // Failing both ways, treat this pattern as matching nothing.
             }
         }
     }
     return Object.freeze(compiled);
 }
 /**
- * 宣言済みのキー名にも、どのパターンにも該当しないキーを返す。
- * 返る配列は入力の列挙順を保つ (issue のメッセージが安定する)。
+ * Returns the keys matched by neither a declared name nor any pattern,
+ * preserving the input's enumeration order so issue output stays stable.
  */
 export function selectAdditionalKeys(value, known, patterns) {
     return Object.keys(value).filter((key) => !known.has(key) && !patterns.some((pattern) => pattern.test(key)));

package/dist/plugins/stitch/stitch.d.ts

@@ -5,11 +5,10 @@ import type { FieldRefs, StitchOut } from "../../plugin-kit/marker.types";
  * The bundle handed to the check at RUN TIME, keyed by the path exactly as
  * declared.
  *
- * 呼び出し側がこれを見ることはもう無い。`.stitch(["price"], ...)` と書いた
- * 時点でパスの集合は分かっているので、述語が受け取る束の型は
- * `PickPaths<TRoot, F>` として組まれる (src/chain/chain-method.types.ts の
- * StitchOut の腕)。この型が残っているのは、実行時に集める側が「キーは
- * パス文字列」という事実を書き留めておく場所だからである。
+ * Callers no longer see this type. Writing `.stitch(["price"], ...)` already
+ * fixes the set of paths, so the bundle the predicate receives is typed per
+ * key from those paths. What survives here is the run-time side's record of
+ * one fact: the keys are the path strings.
  */
 export type StitchFieldValues = Readonly<Record<string, unknown>>;
 /**
@@ -22,19 +21,16 @@ export type StitchFieldValues = Readonly<Record<string, unknown>>;
  */
 export type StitchFieldsOf<TRoot, TFields extends readonly string[]> = PickPaths<TRoot, TFields>;
 /**
- * 1.x の `{ valid, message? }`、名前も形もそのまま。実体は src/types の
- * CrossFieldOutcome で、チェーン層が呼び出し側の型を組むのに参照する —
- * L3 から L7 を import しないための置き場である。
+ * The legacy `{ valid, message? }`, name and shape unchanged. It is declared
+ * where the chain layer can reach it, so that layer never has to import a
+ * plugin to build a caller-facing type.
  */
 export type StitchOutcome = CrossFieldOutcome;
 /**
- * 実行時に build() が受け取る形。**呼び出し側が見る型ではない。**
+ * The shape build() receives at run time. **Not the type a caller sees.**
  *
- * `.stitch(["price", "quantity"], ...)` と書いた時点でパスの集合は分かって
- * いるので、述語が受け取る束は `PickPaths<TRoot, F>` として組まれ、キーごとに
- * 値の型が付く (src/chain/chain-method.types.ts の StitchOut の腕)。
- * ここが `Record<string, unknown>` のままだったのが、その腕を足すまでの
- * stitch である。
+ * Writing `.stitch(["price", "quantity"], ...)` already fixes the set of
+ * paths, so the bundle the predicate receives is typed per key.
  */
 export type StitchCheck = (fieldValues: StitchFieldValues, value: unknown, root: unknown) => StitchOutcome;
 /** 1.x's messageFactory context for this plugin, minus the re-run. */

package/dist/plugins/stitch-with/stitch-with.d.ts

@@ -1,6 +1,6 @@
 import type { MessageContextExtra } from "../../types";
 import type { BundleOut, NarrowedChain } from "../../plugin-kit/marker.types";
-/** 別名 -> ルートのパス。実行時はただの文字列の対応表である。 */
+/** Alias to a path from the root. At run time, a table of strings. */
 export type BundleAliasMap = Readonly<Record<string, string>>;
 export interface StitchWithExtra extends MessageContextExtra {
     readonly aliases: readonly string[];

package/dist/plugins/stitch-with/stitch-with.js

@@ -3,38 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.stitchWithPlugin = void 0;
 // ===========================================================================
 // L7  src/plugins/stitch-with/stitch-with.ts — EXPERIMENTAL.
-// `stitch` の型付き後継。クロスフィールド検証のためのメソッドである。
+// The typed successor to `stitch`, for cross-field validation.
 //
-// stitch の核は「**複数のフィールドを1つの判定にまとめる**」ことなので、
-// 主体は束そのものであって、別名ごとではない。別名ごとにルールを並べる形も
-// 書けるが、それでは `total === price * quantity` が書けず、stitch では
-// なくなる。
+// The point of stitching is to bring SEVERAL FIELDS INTO ONE JUDGEMENT, so
+// the subject is the bundle itself and not each alias. Listing rules per alias
+// is writable but cannot express `total === price * quantity`, at which point
+// it is no longer stitching.
 //
-// stitch との違いは一点だけである。stitch は束を
-// `Readonly<Record<string, unknown>>` として手書きの述語に渡すので、束の中身に
-// ついて型が何も言わない。ここでは束が対応表から組まれて **型が付く**:
+// One difference from `stitch`. There the bundle reaches the predicate as
+// `Readonly<Record<string, unknown>>`, so the type says nothing about its
+// contents. Here the bundle is assembled from a mapping and IS TYPED:
 //
 //     .v("total", (b) => b.number.stitchWith(
 //       { cost: "price", count: "quantity" },
 //       (f) => f.object.custom((bundle) => bundle.cost * bundle.count === 100)
 //     ))
 //
-// `bundle` は `{ cost: number; count: number }` であって Record ではない。
-// メンバー名を綴り違えれば、型を取り違えれば、コンパイルエラーになる。
+// `bundle` is `{ cost: number; count: number }`, not a Record. Misspell a
+// member or mistake its type and it fails to compile.
 //
-// なぜ別名を経由するのか。束をパス文字列でキーすると、その文字列は宣言の場で
-// **パスとして** 解釈される: `"user.name"` は束の中の `user.name` を探しに
-// 行き、束は平たいので見つからない (実測して分かった)。別名は素の識別子なので
-// その衝突が起きず、参照できるのは宣言した別名だけになる。
+// Why aliases rather than paths as keys. A path string used as a bundle key is
+// interpreted AS A PATH where it is declared, so `"user.name"` goes looking
+// for `user.name` inside the bundle and never finds it, the bundle being
+// flat. An alias is a bare identifier, so that collision cannot happen and the
+// only things referable are the aliases actually declared.
 //
-// このファイルに判定は無い。サブチェーンは NarrowedChain と同じ経路で
-// `readonly Rule[]` に解決され、branch がそれを枝にし、エンジンが走らせる。
-// 束専用の収集器をコアに置く案も作って動かしたが、実測でコアが 220 B 増えた
-// (7,590 -> 7,810 B)。stitchWith を使わない利用者が払う形なので採らなかった。
-// 既存の経路に乗せると追加は 0 B である。
-//
-// 1.x が同じ責務の実装を3つ持っていたのは、ここで「もう1つ書く」を選んだ
-// からである。
+// No judgement happens in this file. The sub-chain resolves to
+// `readonly Rule[]` through the same route a narrowed chain takes, and the
+// engine runs it. A bundle-specific collector in the core was built and
+// measured; it added bytes to everyone who never stitches, so this rides the
+// existing route instead and adds none.
 // ===========================================================================
 const types_1 = require("../../types");
 const create_rule_1 = require("../../plugin-kit/create-rule");
@@ -57,7 +55,7 @@ function readMembers(aliasMap) {
         read: (0, index_1.createValueReader)((0, index_1.parseFieldPath)(path)),
     })));
 }
-/** ルートから束を組む。枝の主体はこのオブジェクトになる。 */
+/** Assembles the bundle from the root; this object is the branch's subject. */
 function collectBundle(members, root) {
     const bundle = {};
     for (const member of members)
@@ -76,7 +74,7 @@ exports.stitchWithPlugin = (0, plugin_definition_1.definePlugin)()({
             messageFactory: ctx.messageFactory,
             severity: ctx.severity,
             branches: [(0, create_rule_1.branch)(BUNDLE_BRANCH_LABEL, rules)],
-            // 主体の値は見ない。見るのはルートから組んだ束だけである。
+            // The field's own value is not read. Only the assembled bundle is.
             combine: (runners) => {
                 const runner = runners[0];
                 if (runner === undefined)

package/dist/plugins/stitch-with/stitch-with.mjs

@@ -1,37 +1,35 @@
 // ===========================================================================
 // L7  src/plugins/stitch-with/stitch-with.ts — EXPERIMENTAL.
-// `stitch` の型付き後継。クロスフィールド検証のためのメソッドである。
+// The typed successor to `stitch`, for cross-field validation.
 //
-// stitch の核は「**複数のフィールドを1つの判定にまとめる**」ことなので、
-// 主体は束そのものであって、別名ごとではない。別名ごとにルールを並べる形も
-// 書けるが、それでは `total === price * quantity` が書けず、stitch では
-// なくなる。
+// The point of stitching is to bring SEVERAL FIELDS INTO ONE JUDGEMENT, so
+// the subject is the bundle itself and not each alias. Listing rules per alias
+// is writable but cannot express `total === price * quantity`, at which point
+// it is no longer stitching.
 //
-// stitch との違いは一点だけである。stitch は束を
-// `Readonly<Record<string, unknown>>` として手書きの述語に渡すので、束の中身に
-// ついて型が何も言わない。ここでは束が対応表から組まれて **型が付く**:
+// One difference from `stitch`. There the bundle reaches the predicate as
+// `Readonly<Record<string, unknown>>`, so the type says nothing about its
+// contents. Here the bundle is assembled from a mapping and IS TYPED:
 //
 //     .v("total", (b) => b.number.stitchWith(
 //       { cost: "price", count: "quantity" },
 //       (f) => f.object.custom((bundle) => bundle.cost * bundle.count === 100)
 //     ))
 //
-// `bundle` は `{ cost: number; count: number }` であって Record ではない。
-// メンバー名を綴り違えれば、型を取り違えれば、コンパイルエラーになる。
+// `bundle` is `{ cost: number; count: number }`, not a Record. Misspell a
+// member or mistake its type and it fails to compile.
 //
-// なぜ別名を経由するのか。束をパス文字列でキーすると、その文字列は宣言の場で
-// **パスとして** 解釈される: `"user.name"` は束の中の `user.name` を探しに
-// 行き、束は平たいので見つからない (実測して分かった)。別名は素の識別子なので
-// その衝突が起きず、参照できるのは宣言した別名だけになる。
+// Why aliases rather than paths as keys. A path string used as a bundle key is
+// interpreted AS A PATH where it is declared, so `"user.name"` goes looking
+// for `user.name` inside the bundle and never finds it, the bundle being
+// flat. An alias is a bare identifier, so that collision cannot happen and the
+// only things referable are the aliases actually declared.
 //
-// このファイルに判定は無い。サブチェーンは NarrowedChain と同じ経路で
-// `readonly Rule[]` に解決され、branch がそれを枝にし、エンジンが走らせる。
-// 束専用の収集器をコアに置く案も作って動かしたが、実測でコアが 220 B 増えた
-// (7,590 -> 7,810 B)。stitchWith を使わない利用者が払う形なので採らなかった。
-// 既存の経路に乗せると追加は 0 B である。
-//
-// 1.x が同じ責務の実装を3つ持っていたのは、ここで「もう1つ書く」を選んだ
-// からである。
+// No judgement happens in this file. The sub-chain resolves to
+// `readonly Rule[]` through the same route a narrowed chain takes, and the
+// engine runs it. A bundle-specific collector in the core was built and
+// measured; it added bytes to everyone who never stitches, so this rides the
+// existing route instead and adds none.
 // ===========================================================================
 import { PASS, fail, isPlainObject } from "../../types/index.mjs";
 import { branch, composite } from "../../plugin-kit/create-rule.mjs";
@@ -54,7 +52,7 @@ function readMembers(aliasMap) {
         read: createValueReader(parseFieldPath(path)),
     })));
 }
-/** ルートから束を組む。枝の主体はこのオブジェクトになる。 */
+/** Assembles the bundle from the root; this object is the branch's subject. */
 function collectBundle(members, root) {
     const bundle = {};
     for (const member of members)
@@ -73,7 +71,7 @@ export const stitchWithPlugin = /*#__PURE__*/ definePlugin()({
             messageFactory: ctx.messageFactory,
             severity: ctx.severity,
             branches: [branch(BUNDLE_BRANCH_LABEL, rules)],
-            // 主体の値は見ない。見るのはルートから組んだ束だけである。
+            // The field's own value is not read. Only the assembled bundle is.
             combine: (runners) => {
                 const runner = runners[0];
                 if (runner === undefined)

package/dist/plugins/string-min/string-min.js

@@ -23,17 +23,15 @@ exports.stringMinPlugin = (0, plugin_definition_1.definePlugin)()({
             code: ctx.code,
             messageFactory: ctx.messageFactory,
             severity: ctx.severity,
-            // min に届いた時点で止める。全長を数える必要があるのは**落ちる**
-            // ときだけで、そのときは値が min より短いのだから走査も短い。
-            // 元は countCodePoints を最大二度呼び、どちらも文字列を最後まで
-            // 歩いていた。符号位置で数えるのは変えない (UTF-16 単位ではない) —
-            // 変えているのは、いつ止めるかだけである。受理パスで 12.7%。
+            // Stops as soon as min is reached. The full length is only needed to
+            // REPORT a failure, and a failing value is shorter than min, so that
+            // walk is short too. Counting is still by code point, not UTF-16 unit;
+            // the only thing that changed is when it stops.
             run: (value) => {
                 if (!(0, types_1.isString)(value))
                     return types_1.PASS;
-                // min が 0 なら空文字列も通る。ループは空文字列で一度も回らないので、
-                // この行が無いと `""` が actual 0 で落ちる — 早期脱出に書き換えた
-                // ときに実際に開いた穴で、既存のテストは一件も気づかなかった。
+                // min of 0 admits the empty string. The loop body never runs on an
+                // empty string, so without this line the empty string fails with 0.
                 if (min === 0)
                     return types_1.PASS;
                 let count = 0;

package/dist/plugins/string-min/string-min.mjs

@@ -20,17 +20,15 @@ export const stringMinPlugin = /*#__PURE__*/ definePlugin()({
             code: ctx.code,
             messageFactory: ctx.messageFactory,
             severity: ctx.severity,
-            // min に届いた時点で止める。全長を数える必要があるのは**落ちる**
-            // ときだけで、そのときは値が min より短いのだから走査も短い。
-            // 元は countCodePoints を最大二度呼び、どちらも文字列を最後まで
-            // 歩いていた。符号位置で数えるのは変えない (UTF-16 単位ではない) —
-            // 変えているのは、いつ止めるかだけである。受理パスで 12.7%。
+            // Stops as soon as min is reached. The full length is only needed to
+            // REPORT a failure, and a failing value is shorter than min, so that
+            // walk is short too. Counting is still by code point, not UTF-16 unit;
+            // the only thing that changed is when it stops.
             run: (value) => {
                 if (!isString(value))
                     return PASS;
-                // min が 0 なら空文字列も通る。ループは空文字列で一度も回らないので、
-                // この行が無いと `""` が actual 0 で落ちる — 早期脱出に書き換えた
-                // ときに実際に開いた穴で、既存のテストは一件も気づかなかった。
+                // min of 0 admits the empty string. The loop body never runs on an
+                // empty string, so without this line the empty string fails with 0.
                 if (min === 0)
                     return PASS;
                 let count = 0;

package/dist/presets/presets.d.ts

@@ -1,6 +1,5 @@
 /**
- * 在る・無い・null。ほぼ全ての宣言がこの三つのどれかを使う。
- * 使用実績: required 138 / optional 26 / nullable 12。
+ * Present, absent, null. Nearly every declaration uses one of the three.
  */
 export declare const presence: Readonly<{
     required: import("..").PluginDefinition<"required", "required", readonly import("..").TypeName[], {
@@ -19,7 +18,7 @@ export declare const presence: Readonly<{
         context: import("..").MessageContextExtra;
     }>;
 }>;
-/** 文字列の定番。使用実績: stringMin 95 / stringEmail 33 / stringPattern 12。 */
+/** The everyday string checks. */
 export declare const strings: Readonly<{
     stringMin: import("..").PluginDefinition<"stringMin", "min", readonly ["string"], {
         args: readonly [min: number];
@@ -46,7 +45,7 @@ export declare const strings: Readonly<{
         };
     }>;
 }>;
-/** 数値の定番。使用実績: numberMin 43 / numberMax 8。 */
+/** The everyday number checks. */
 export declare const numbers: Readonly<{
     numberMin: import("..").PluginDefinition<"numberMin", "min", readonly ["number"], {
         args: readonly [min: number, exclusive?: boolean];
@@ -64,7 +63,7 @@ export declare const numbers: Readonly<{
         context: import("..").MessageContextExtra;
     }>;
 }>;
-/** 配列の定番。要素ごとの規則は arrayEach が運ぶ。 */
+/** The everyday array checks. Per-element rules ride on arrayEach. */
 export declare const arrays: Readonly<{
     arrayMinLength: import("..").PluginDefinition<"arrayMinLength", "minLength", readonly ["array", "tuple"], {
         args: readonly [min: number];
@@ -83,14 +82,14 @@ export declare const arrays: Readonly<{
     }>;
 }>;
 /**
- * 上の四つを合わせたもの。13プラグイン、gzip で +1,452 B。
+ * The four bundles above, together.
  *
- * 名前が「common」でないのは、それが何も言っていないからである
- * (lint の禁止語彙にも入っている)。入っているのは presence と、文字列・数値・
- * 配列それぞれの定番で、毎日書くのはこの範囲だ、という主張がこの名前である。
+ * Not called "common", because that name says nothing — and lint bans it. It
+ * holds presence plus the everyday string, number and array checks, and the
+ * name is the claim that this is the range people write day to day.
  *
- * これでも「全部入り」ではない。全部入りが要るなら `@maroonedog/luq/plugins`
- * のバレルがあり、そちらは 77 個ぶん、gzip で +17,986 B を払う。
+ * Still not everything. For everything there is the `@maroonedog/luq/plugins`
+ * barrel, which costs accordingly.
  */
 export declare const everydayRules: Readonly<{
     arrayMinLength: import("..").PluginDefinition<"arrayMinLength", "minLength", readonly ["array", "tuple"], {

package/dist/presets/presets.js

@@ -2,24 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.everydayRules = exports.arrays = exports.numbers = exports.strings = exports.presence = void 0;
 // ===========================================================================
-// L7  src/presets/presets.ts — 事前定義したプラグイン束。
+// L7  src/presets/presets.ts — predefined plugin bundles.
 //
-// なぜ要るのか。プラグインを1つずつ import するのは「使った分しか入らない」
-// を成り立たせている仕組みそのものだが、最初の一本を書くのに15行の use() を
-// 並べさせるのは、その正しさの押し付けである。
+// Why they exist. Importing plugins one at a time is the very mechanism behind
+// "you only ship what you used", but making someone write fifteen use() lines
+// for their first validator is imposing that correctness on them.
 //
-// なぜ「小さいのを複数」なのか。全部入りを1つ置くと、5個しか要らない人が
-// 40個分のバイトを払う。束は型としてはただの `PluginBag` なので、必要な束
-// だけを `useAll()` すればよく、混ぜても first-wins で衝突しない:
+// Why several small ones rather than one big one. A single everything-bundle
+// bills the person who needs five plugins for forty. A bundle is just a
+// `PluginBag`, so useAll() takes only the ones wanted, and mixing them is
+// first-wins rather than a collision:
 //
 //     Builder().useAll(presence).useAll(strings).for<User>()
 //
-// 何を入れるかはリポジトリ内の使用実績から決めた (test/ と docs-site/ の
-// use() を数えたもの)。required 138 / stringMin 95 / numberMin 43 /
-// stringEmail 33 / optional 26 という並びで、上位が束の中身になっている。
+// Membership was chosen from how often each plugin is actually used across
+// this repository, most-used first.
 //
-// バイト数は config/size-budget.json が測る。プリセットは便利さと引き換えに
-// バイトを払うものなので、いくら払うかは書いてあるべきである。
+// What a bundle costs in bytes is measured by the size budget. A preset trades
+// bytes for convenience, so the price should be measured rather than asserted.
 // ===========================================================================
 const required_1 = require("../plugins/required");
 const optional_1 = require("../plugins/optional");
@@ -35,42 +35,41 @@ 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。
+ * Present, absent, null. Nearly every declaration uses one of the three.
  */
 exports.presence = Object.freeze({
     required: required_1.requiredPlugin,
     optional: optional_1.optionalPlugin,
     nullable: nullable_1.nullablePlugin,
 });
-/** 文字列の定番。使用実績: stringMin 95 / stringEmail 33 / stringPattern 12。 */
+/** The everyday string checks. */
 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。 */
+/** The everyday number checks. */
 exports.numbers = Object.freeze({
     numberMin: number_min_1.numberMinPlugin,
     numberMax: number_max_1.numberMaxPlugin,
     numberInteger: number_integer_1.numberIntegerPlugin,
 });
-/** 配列の定番。要素ごとの規則は arrayEach が運ぶ。 */
+/** The everyday array checks. Per-element rules ride on 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。
+ * The four bundles above, together.
  *
- * 名前が「common」でないのは、それが何も言っていないからである
- * (lint の禁止語彙にも入っている)。入っているのは presence と、文字列・数値・
- * 配列それぞれの定番で、毎日書くのはこの範囲だ、という主張がこの名前である。
+ * Not called "common", because that name says nothing — and lint bans it. It
+ * holds presence plus the everyday string, number and array checks, and the
+ * name is the claim that this is the range people write day to day.
  *
- * これでも「全部入り」ではない。全部入りが要るなら `@maroonedog/luq/plugins`
- * のバレルがあり、そちらは 77 個ぶん、gzip で +17,986 B を払う。
+ * Still not everything. For everything there is the `@maroonedog/luq/plugins`
+ * barrel, which costs accordingly.
  */
 exports.everydayRules = Object.freeze({
     ...exports.presence,

package/dist/presets/presets.mjs

@@ -1,22 +1,22 @@
 // ===========================================================================
-// L7  src/presets/presets.ts — 事前定義したプラグイン束。
+// L7  src/presets/presets.ts — predefined plugin bundles.
 //
-// なぜ要るのか。プラグインを1つずつ import するのは「使った分しか入らない」
-// を成り立たせている仕組みそのものだが、最初の一本を書くのに15行の use() を
-// 並べさせるのは、その正しさの押し付けである。
+// Why they exist. Importing plugins one at a time is the very mechanism behind
+// "you only ship what you used", but making someone write fifteen use() lines
+// for their first validator is imposing that correctness on them.
 //
-// なぜ「小さいのを複数」なのか。全部入りを1つ置くと、5個しか要らない人が
-// 40個分のバイトを払う。束は型としてはただの `PluginBag` なので、必要な束
-// だけを `useAll()` すればよく、混ぜても first-wins で衝突しない:
+// Why several small ones rather than one big one. A single everything-bundle
+// bills the person who needs five plugins for forty. A bundle is just a
+// `PluginBag`, so useAll() takes only the ones wanted, and mixing them is
+// first-wins rather than a collision:
 //
 //     Builder().useAll(presence).useAll(strings).for<User>()
 //
-// 何を入れるかはリポジトリ内の使用実績から決めた (test/ と docs-site/ の
-// use() を数えたもの)。required 138 / stringMin 95 / numberMin 43 /
-// stringEmail 33 / optional 26 という並びで、上位が束の中身になっている。
+// Membership was chosen from how often each plugin is actually used across
+// this repository, most-used first.
 //
-// バイト数は config/size-budget.json が測る。プリセットは便利さと引き換えに
-// バイトを払うものなので、いくら払うかは書いてあるべきである。
+// What a bundle costs in bytes is measured by the size budget. A preset trades
+// bytes for convenience, so the price should be measured rather than asserted.
 // ===========================================================================
 import { requiredPlugin } from "../plugins/required/index.mjs";
 import { optionalPlugin } from "../plugins/optional/index.mjs";
@@ -32,42 +32,41 @@ 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。
+ * Present, absent, null. Nearly every declaration uses one of the three.
  */
 export const presence = Object.freeze({
     required: requiredPlugin,
     optional: optionalPlugin,
     nullable: nullablePlugin,
 });
-/** 文字列の定番。使用実績: stringMin 95 / stringEmail 33 / stringPattern 12。 */
+/** The everyday string checks. */
 export const strings = Object.freeze({
     stringMin: stringMinPlugin,
     stringMax: stringMaxPlugin,
     stringPattern: stringPatternPlugin,
     stringEmail: stringEmailPlugin,
 });
-/** 数値の定番。使用実績: numberMin 43 / numberMax 8。 */
+/** The everyday number checks. */
 export const numbers = Object.freeze({
     numberMin: numberMinPlugin,
     numberMax: numberMaxPlugin,
     numberInteger: numberIntegerPlugin,
 });
-/** 配列の定番。要素ごとの規則は arrayEach が運ぶ。 */
+/** The everyday array checks. Per-element rules ride on arrayEach. */
 export const arrays = Object.freeze({
     arrayMinLength: arrayMinLengthPlugin,
     arrayMaxLength: arrayMaxLengthPlugin,
     arrayEach: arrayEachPlugin,
 });
 /**
- * 上の四つを合わせたもの。13プラグイン、gzip で +1,452 B。
+ * The four bundles above, together.
  *
- * 名前が「common」でないのは、それが何も言っていないからである
- * (lint の禁止語彙にも入っている)。入っているのは presence と、文字列・数値・
- * 配列それぞれの定番で、毎日書くのはこの範囲だ、という主張がこの名前である。
+ * Not called "common", because that name says nothing — and lint bans it. It
+ * holds presence plus the everyday string, number and array checks, and the
+ * name is the claim that this is the range people write day to day.
  *
- * これでも「全部入り」ではない。全部入りが要るなら `@maroonedog/luq/plugins`
- * のバレルがあり、そちらは 77 個ぶん、gzip で +17,986 B を払う。
+ * Still not everything. For everything there is the `@maroonedog/luq/plugins`
+ * barrel, which costs accordingly.
  */
 export const everydayRules = Object.freeze({
     ...presence,

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

@@ -60,13 +60,11 @@ function createSubjectComposer(template) {
     return (siblings, value) => mergeOntoSiblings(siblings, nest(value));
 }
 /**
- * テンプレートを **一度だけ** 歩いて、包む関数に畳んでおく。
+ * Walks the template **once** and folds it into a wrapping function.
  *
- * 以前はここが `nestValue(template, 0, value)` で、検証のたびにテンプレートを
- * 歩き直して `segment.kind` を読み直していた。src/compile/validation-plan.types.ts
- * が書いているとおり「実行時はルールが何であるかを決め直してはならない。
- * 決めるのはコンパイルが済ませたこと」であり、ここはその例外になっていた。
- * 非ワイルドカードの経路 (createValueWriter) は最初からこの形である。
+ * Walking it per validation re-read each segment's kind every time, which is
+ * exactly the thing validation time must not do: what something IS was settled
+ * at compile time. The non-wildcard route was always shaped this way.
  */
 function compileNester(template) {
     let nest = (value) => value;

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

@@ -57,13 +57,11 @@ function createSubjectComposer(template) {
     return (siblings, value) => mergeOntoSiblings(siblings, nest(value));
 }
 /**
- * テンプレートを **一度だけ** 歩いて、包む関数に畳んでおく。
+ * Walks the template **once** and folds it into a wrapping function.
  *
- * 以前はここが `nestValue(template, 0, value)` で、検証のたびにテンプレートを
- * 歩き直して `segment.kind` を読み直していた。src/compile/validation-plan.types.ts
- * が書いているとおり「実行時はルールが何であるかを決め直してはならない。
- * 決めるのはコンパイルが済ませたこと」であり、ここはその例外になっていた。
- * 非ワイルドカードの経路 (createValueWriter) は最初からこの形である。
+ * Walking it per validation re-read each segment's kind every time, which is
+ * exactly the thing validation time must not do: what something IS was settled
+ * at compile time. The non-wildcard route was always shaped this way.
  */
 function compileNester(template) {
     let nest = (value) => value;