RobinTail / express-zod-api / 30998016093 / 5

100%

master: 100%

push

github

feat: Warn about unacceptable query/path params (#3596)

## What

Adds a startup warning for `query` and `path` parameters whose schema
can never be satisfied, because values in those positions always arrive
as strings.

Fixes #3577.

## Why

`Documentation` emits the Zod type as-is (`z.number()` → `type:
number`), so a `GET` endpoint with `z.number()` in `query`/`path`
advertises a contract that rejects every possible request with 400 — and
no warning fired, even though `z.bigint()` in the same position does
warn about the JSON-incompatible payload. This adds the missing
diagnostics while being coercion-aware (`z.coerce.number()` is the
documented workaround and must not be flagged).

## What changed

- `diagnostics.ts`: `Diagnostics` now receives `config`; new
`#checkStringOnlyParams` derives the stuck parameters entirely from the
flattened JSON Schema depiction of the input
(`flattenIO(z.toJSONSchema(..., { override }))`), mirroring the
documentation location logic (skipping headers/cookies). The `override`
stamps a custom `x-coerce` marker onto coercing schemas, so the
coercion-aware conclusion is drawn from the JSON depiction rather than
from Zod defs. This also covers input schemas that are more complex than
an object intersection (top-level transforms/refinements, records),
which `getObjectProperties` could not handle.
- `deep-checks.ts`: new JSON-Schema-driven `isStringSatisfiable(schema)`
(a property is satisfiable when its type accepts strings, is
unconstrained, or is marked `x-coerce`, with `anyOf`/`oneOf`/`allOf`
support) and `stringifyType(schema)` for a readable type label in the
message. Unsupported/unknown/complex types are treated as satisfiable to
avoid false positives (e.g. `bigint` is already covered by the
JSON-incompatible warning).
- `routing.ts`: passes `config` into `new Diagnostics(...)`.
- `tests/routing.spec.ts`: covers query/path
`number`/`int`/`boolean`/`literal(42)` (warn), a top-level-transformed
input (warn),
`z.coerce... (continued)

1052 of 1103 branches covered (95.38%)

1512 of 1512 relevant lines covered (100.0%)

92.21 hits per line