first commit

docs/foundation/bitpacker/bitpacker-validation/src/validation/find-array-length-errors.md

@@ -0,0 +1,64 @@
+# findArrayLengthErrors
+
+## Purpose
+
+Per-array length-rule detector used by the recursive `validateData` walker. Given a `BitPackerSchema` array shape (`[schema]` for variable-length, `[maxLength, schema]` for max-bounded), this function checks the corresponding `data` array against the rule and pushes rows into the validator's error accumulator if the length is out of bounds. Splitting the check out of `validateData` keeps the main walker's switch ladder readable and lets the array-specific logic evolve independently of the rest of the validator.
+
+The function is hot-path machinery; it accepts the same context shape as `validateData` (the mutable error/warning arrays + per-call options) and returns `void`. It does NOT recurse into the array elements — that's the walker's job after the length check passes.
+
+## Features
+
+- Detects `data.length > maxLength` violations for max-bounded arrays
+- Detects non-array `data` against an array schema
+- Pushes `ValidationReportItem` rows with `code: "ARRAY_TOO_LONG"` or `"INVALID_TYPE"`
+- Honours `maxErrors` short-circuit
+- Path-aware: passes the current `path` through to the row's `path` field
+
+## Usage: Basic Example
+
+```ts
+import { findArrayLengthErrors, type ValidationReportItem } from "@suaveplan/bitpacker-validation";
+
+const errors: ValidationReportItem[] = [];
+findArrayLengthErrors(
+    [10, 255], // schema: max 10 uint8 entries
+    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], // data: 11 entries
+    "items",
+    { errors, warnings: [], maxErrors: 10, checkExtraFields: false, strictMode: false }
+);
+console.log(errors[0].code); // "ARRAY_TOO_LONG"
+console.log(errors[0].path); // "items"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    findArrayLengthErrors,
+    ErrorCodes,
+    type ValidationReportItem,
+} from "@suaveplan/bitpacker-validation";
+
+const errors: ValidationReportItem[] = [];
+findArrayLengthErrors(
+    [100, "uuid"],
+    "not-an-array",
+    "users",
+    { errors, warnings: [], maxErrors: 1, checkExtraFields: false, strictMode: false }
+);
+// errors[0].code === ErrorCodes.INVALID_TYPE
+// errors[0].path === "users"
+```
+
+## API Reference
+
+### `findArrayLengthErrors(schema: ArraySchema, data: unknown, path: string, ctx: ValidationContext): void`
+
+Checks `data` against the length rule encoded in `schema`. If `schema = [innerSchema]`, any array length is valid. If `schema = [maxLength, innerSchema]`, length must be `≤ maxLength`. Pushes rows into `ctx.errors` on violations.
+
+## Implementation Notes
+
+- **No element-level validation.** This function only handles the length rule. Element validation (each item against `innerSchema`) is the caller's responsibility — typically the recursive `validateData` walker after this check passes.
+- **`maxLength: 0` is valid.** A zero max-length means an empty-array-only schema. Non-empty arrays produce `ARRAY_TOO_LONG` errors. Consumers wanting "no constraint" use the variable-length form `[schema]` instead.
+- **Type errors short-circuit length checks.** A non-array `data` produces a single `INVALID_TYPE` row and the function returns; it does NOT report a derivative `ARRAY_TOO_LONG` for a non-array.
+- **`maxErrors` is enforced.** Once `ctx.errors.length >= ctx.maxErrors`, the function returns without pushing additional rows.