# 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.