@nifrajs/schema 3.3.0 → 4.0.0

package/src/openapi.ts

@@ -1,4 +1,11 @@
 import type { ContractShape } from "@nifrajs/core/contract"
+import { type ProjectEvidenceSnapshot, reflectedRoutesFromEvidence } from "@nifrajs/core/evidence"
+import {
+  compileRoutePattern,
+  expandOptionalParams,
+  type ParamConstraint,
+  type RoutePatternSegment,
+} from "@nifrajs/core/pattern"
 import {
   type JsonSchema,
   type ReflectedRouteSchema,
@@ -50,6 +57,11 @@ export interface ToOpenAPIOptions {
   readonly securitySchemes?: Readonly<Record<string, Record<string, unknown>>>
   /** Document-wide security requirement; a per-operation `security` (incl. `[]` for public) overrides it. */
   readonly security?: readonly SecurityRequirement[]
+  /**
+   * Reuse a canonical token-only route-evidence pass. This is useful for build artifacts and CLI
+   * projections that already evaluated the project; it never supplies runtime validators.
+   */
+  readonly evidence?: ProjectEvidenceSnapshot
   /**
    * Per-operation overrides, shallow-merged over the generated operation. Keyed by `operationId`
    * (contract op name) or `"METHOD /path"` (e.g. `"GET /users/:id"`). The escape hatch for detail that
@@ -80,7 +92,7 @@ export interface ToOpenAPIOptions {
 
 interface OpenAPIParameter {
   readonly name: string
-  readonly in: "path" | "query" | "header"
+  readonly in: "path" | "query" | "header" | "cookie"
   readonly required: boolean
   readonly schema: JsonSchema
 }
@@ -175,26 +187,47 @@ class SchemaStore {
   }
 }
 
-/** Name of a path segment's parameter, or `undefined` for a static segment. */
-function segmentParam(segment: string): string | undefined {
-  if (segment.startsWith(":")) return segment.slice(1)
-  if (segment.startsWith("*")) return segment.length > 1 ? segment.slice(1) : "wildcard"
-  return undefined
+interface PathParameter {
+  readonly name: string
+  readonly constraint: ParamConstraint | undefined
 }
 
-/** `/users/:id/*rest` → `/users/{id}/{rest}` (OpenAPI path templating). */
-function toTemplatedPath(path: string): string {
-  return path
-    .split("/")
-    .map((segment) => {
-      const param = segmentParam(segment)
-      return param === undefined ? segment : `{${param}}`
-    })
+/**
+ * `/users/:id/*rest` as `/users/{id}/{rest}`, with its params in order. Split by the router's own
+ * compiler, so names and constraints end where the router ends them.
+ */
+function templatedPath(path: string): {
+  readonly template: string
+  readonly parameters: readonly PathParameter[]
+} {
+  const parameters: PathParameter[] = []
+  const take = (name: string, constraint?: ParamConstraint): string => {
+    parameters.push({ name, constraint })
+    return `{${name}}`
+  }
+  let segments: readonly RoutePatternSegment[]
+  try {
+    segments = compileRoutePattern(path).segments
+  } catch {
+    return { template: path, parameters }
+  }
+  const template = segments
+    .map((segment) =>
+      segment.kind === "static"
+        ? segment.value
+        : segment.kind === "param"
+          ? take(segment.name)
+          : segment.kind === "wildcard"
+            ? take(segment.name === "*" ? "wildcard" : segment.name)
+            : segment.parts
+                .map((part) => (part.t === "lit" ? part.v : take(part.name, part.c)))
+                .join(""),
+    )
     .join("/")
+  return { template: `/${template}`, parameters }
 }
 
 function pathParameters(path: string, paramsSchema?: SchemaReflection): OpenAPIParameter[] {
-  const params: OpenAPIParameter[] = []
   // Build a lookup of per-field schemas from the declared params schema (if any).
   const fieldSchemas = new Map<string, JsonSchema>()
   if (paramsSchema?.fields !== undefined) {
@@ -202,16 +235,20 @@ function pathParameters(path: string, paramsSchema?: SchemaReflection): OpenAPIP
       fieldSchemas.set(field.name, field.schema)
     }
   }
-  for (const segment of path.split("/")) {
-    const name = segmentParam(segment)
-    if (name !== undefined) {
-      // Merge the declared constraint (uuid format, integer type, etc.) when present;
-      // fall back to the bare { type: "string" } derived from the URL pattern.
-      const schema = fieldSchemas.get(name) ?? { type: "string" as const }
-      params.push({ name, in: "path", required: true, schema })
-    }
-  }
-  return params
+  // A declared field schema (uuid format, integer type, etc.) wins. Without one, a constraint in
+  // the path says what the router accepts; without either, the parameter is any string.
+  return templatedPath(path).parameters.map(({ name, constraint }) => ({
+    name,
+    in: "path",
+    required: true,
+    schema:
+      fieldSchemas.get(name) ??
+      (constraint === undefined
+        ? { type: "string" }
+        : constraint.oneOf === undefined
+          ? { type: "string", pattern: `^${constraint.source}$` }
+          : { type: "string", enum: constraint.oneOf }),
+  }))
 }
 
 function queryParameters(schema: SchemaReflection | undefined): OpenAPIParameter[] {
@@ -237,11 +274,23 @@ function headerParameters(schema: SchemaReflection | undefined): OpenAPIParamete
   }))
 }
 
+/** Cookie names are case-sensitive, so each declared field keeps its name as written. */
+function cookieParameters(schema: SchemaReflection | undefined): OpenAPIParameter[] {
+  if (schema?.fields === undefined) return []
+  return schema.fields.map((field) => ({
+    name: field.name,
+    in: "cookie" as const,
+    required: field.required,
+    schema: field.schema,
+  }))
+}
+
 interface OperationInput {
   readonly path: string
   readonly body: SchemaReflection | undefined
   readonly query: SchemaReflection | undefined
   readonly headers: SchemaReflection | undefined
+  readonly cookies?: SchemaReflection | undefined
   /** Reflected params schema - per-field constraints merge into path parameters. */
   readonly params: SchemaReflection | undefined
   readonly response: SchemaReflection | undefined
@@ -341,6 +390,30 @@ function buildResponses(
   return responses
 }
 
+const isBinary = (schema: unknown): boolean =>
+  typeof schema === "object" &&
+  schema !== null &&
+  (schema as { type?: unknown }).type === "string" &&
+  (schema as { format?: unknown }).format === "binary"
+
+/**
+ * Whether a body schema declares a file field (a binary string, or a list of them) - the shape
+ * `t.form` produces. JSON cannot carry a file, so such a body is `multipart/form-data`. Read off
+ * the plain JSON Schema so a document built from a stored evidence snapshot agrees with a live one.
+ */
+function hasFileField(schema: JsonSchema | undefined): boolean {
+  if (typeof schema !== "object" || schema === null) return false
+  const properties = (schema as { properties?: unknown }).properties
+  if (typeof properties !== "object" || properties === null) return false
+  return Object.values(properties).some(
+    (property) =>
+      isBinary(property) ||
+      (typeof property === "object" &&
+        property !== null &&
+        isBinary((property as { items?: unknown }).items)),
+  )
+}
+
 function buildOperation(input: OperationInput, store: SchemaStore): OpenAPIOperation {
   const operation: OpenAPIOperation = { responses: buildResponses(input, store) }
   if (input.operationId !== undefined) operation.operationId = input.operationId
@@ -354,21 +427,36 @@ function buildOperation(input: OperationInput, store: SchemaStore): OpenAPIOpera
     ...pathParameters(input.path, input.params),
     ...queryParameters(input.query),
     ...headerParameters(input.headers),
+    ...cookieParameters(input.cookies),
   ]
   if (parameters.length > 0) operation.parameters = parameters
 
   if (input.body !== undefined) {
     const schema = store.collect(input.body.jsonSchema)
     if (schema !== undefined) {
-      operation.requestBody = {
-        required: true,
-        content: { [input.requestContentType ?? "application/json"]: { schema } },
-      }
+      const contentType =
+        input.requestContentType ??
+        (hasFileField(input.body.jsonSchema) ? "multipart/form-data" : "application/json")
+      const content: Record<string, { schema: typeof schema }> = { [contentType]: { schema } }
+      // A body schema with a parser of its own reads those media types too: one entry each, in a
+      // fixed order so a live document and one built from a stored snapshot are the same document.
+      for (const type of [...(input.body.mediaTypes ?? [])].sort()) content[type] ??= { schema }
+      operation.requestBody = { required: true, content }
     }
   }
   return operation
 }
 
+const PATH_ITEM_METHODS: ReadonlySet<string> = new Set([
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+])
+
 function addOperation(
   paths: Record<string, Record<string, OpenAPIOperation>>,
   method: string,
@@ -376,7 +464,10 @@ function addOperation(
   store: SchemaStore,
   operations: ToOpenAPIOptions["operations"],
 ): void {
-  const templated = toTemplatedPath(input.path)
+  // A path item has a field for each standard method and no place for any other, so a route
+  // registered under a custom method is left out of the document.
+  if (!PATH_ITEM_METHODS.has(method.toLowerCase())) return
+  const templated = templatedPath(input.path).template
   const pathItem = paths[templated] ?? {}
   paths[templated] = pathItem
   let operation = buildOperation(input, store)
@@ -402,7 +493,11 @@ export function toOpenAPI(
   const store = new SchemaStore()
 
   if (isApp(input)) {
-    for (const route of reflectRoutes(input)) {
+    const routes =
+      options.evidence === undefined
+        ? reflectRoutes(input)
+        : reflectedRoutesFromEvidence(options.evidence)
+    for (const route of routes) {
       addOperation(
         paths,
         route.method,
@@ -411,6 +506,7 @@ export function toOpenAPI(
           body: route.schema?.body,
           query: route.schema?.query,
           headers: route.schema?.headers,
+          cookies: route.schema?.cookies,
           params: route.schema?.params,
           // A route may now declare a `response` contract - emit it as the 200 body schema.
           response: route.schema?.response,
@@ -426,44 +522,54 @@ export function toOpenAPI(
     }
   } else {
     for (const [name, op] of Object.entries(input)) {
-      addOperation(
-        paths,
-        op.method,
-        {
-          path: op.path,
-          body: op.body === undefined ? undefined : reflectSchema(op.body),
-          query: op.query === undefined ? undefined : reflectSchema(op.query),
-          headers: op.headers === undefined ? undefined : reflectSchema(op.headers),
-          params: op.params === undefined ? undefined : reflectSchema(op.params),
-          response: op.response === undefined ? undefined : reflectSchema(op.response),
-          operationId: name,
-          summary: op.summary,
-          description: op.description,
-          tags: op.tags,
-          deprecated: op.deprecated,
-          security: op.security,
-          requestContentType: op.requestContentType,
-          responseContentType: op.responseContentType,
-          responses:
-            op.responses === undefined
-              ? undefined
-              : Object.fromEntries(
-                  Object.entries(op.responses).map(([status, response]) => {
-                    const { schema, ...metadata } = response
-                    return [
-                      status,
-                      {
-                        ...metadata,
-                        ...(schema === undefined ? {} : { schema: reflectSchema(schema) }),
-                      },
-                    ]
-                  }),
-                ),
-          inferredResponses: options.inferredResponses?.[`${op.method.toUpperCase()} ${op.path}`],
-        },
-        store,
-        options.operations,
-      )
+      // A path ending in optional params is one operation per concrete path it serves. Operation ids
+      // are unique in a document, so the contract name goes to the full path and the shorter ones
+      // carry none; a shorter path declares only the parameters it has.
+      const forms = expandOptionalParams(op.path)
+      const responses =
+        op.responses === undefined
+          ? undefined
+          : Object.fromEntries(
+              Object.entries(op.responses).map(([status, response]) => {
+                const { schema, ...metadata } = response
+                return [
+                  status,
+                  {
+                    ...metadata,
+                    ...(schema === undefined ? {} : { schema: reflectSchema(schema) }),
+                  },
+                ]
+              }),
+            )
+      for (const path of forms) {
+        addOperation(
+          paths,
+          op.method,
+          {
+            path,
+            body: op.body === undefined ? undefined : reflectSchema(op.body),
+            query: op.query === undefined ? undefined : reflectSchema(op.query),
+            headers: op.headers === undefined ? undefined : reflectSchema(op.headers),
+            cookies: op.cookies === undefined ? undefined : reflectSchema(op.cookies),
+            params: op.params === undefined ? undefined : reflectSchema(op.params),
+            response: op.response === undefined ? undefined : reflectSchema(op.response),
+            operationId: path === forms[forms.length - 1] ? name : undefined,
+            summary: op.summary,
+            description: op.description,
+            tags: op.tags,
+            deprecated: op.deprecated,
+            security: op.security,
+            requestContentType: op.requestContentType,
+            responseContentType: op.responseContentType,
+            responses,
+            inferredResponses:
+              options.inferredResponses?.[`${op.method.toUpperCase()} ${path}`] ??
+              options.inferredResponses?.[`${op.method.toUpperCase()} ${op.path}`],
+          },
+          store,
+          options.operations,
+        )
+      }
     }
   }
 
@@ -485,3 +591,14 @@ export function toOpenAPI(
     ...(Object.keys(components).length > 0 ? { components } : {}),
   }
 }
+
+/** Generate OpenAPI from an existing canonical project-evidence snapshot without loading a server. */
+export function toOpenAPIFromEvidence(
+  evidence: ProjectEvidenceSnapshot,
+  options: Omit<ToOpenAPIOptions, "evidence"> = {},
+): OpenAPIDocument {
+  const app = {
+    routes: () => reflectedRoutesFromEvidence(evidence),
+  } as unknown as Server
+  return toOpenAPI(app, { ...options, evidence })
+}

package/src/t.ts

@@ -1,26 +1,66 @@
 import {
   type ArrayOptions,
+  CloneType,
   type IntegerOptions,
+  Kind,
   type NumberOptions,
   type ObjectOptions,
+  type Static,
   type StringOptions,
+  type TArray,
   type TLiteralValue,
   type TSchema,
   type TUnion,
+  type TUnsafe,
   Type,
+  TypeRegistry,
 } from "@sinclair/typebox"
 import { fromTypeBox, type NifraSchema } from "./adapter.ts"
+import { fileOps, refuseFile } from "./file-kind.ts"
 
 type Props = Record<string, NifraSchema>
 
-/** Pull each property's raw TypeBox schema out of its `NifraSchema` wrapper. */
-function unwrap<P extends Props>(props: P): { [K in keyof P]: P[K]["jsonSchema"] } {
+/** A value `defer()` from `@nifrajs/web` marked to stream in after the page shell. */
+export interface DeferredValue<T> {
+  readonly __nifra_deferred: true
+  readonly id: number
+  readonly promise: Promise<T>
+}
+
+const DEFERRED_KIND = "NifraDeferred"
+/** Where `@nifrajs/web`'s output guard finds the inner schema's validate. Registered for two copies. */
+const DEFERRED_VALIDATE = Symbol.for("nifra.schema.deferredValidate")
+
+const isDeferredValue = (_: unknown, value: unknown): boolean =>
+  typeof value === "object" &&
+  value !== null &&
+  (value as { readonly __nifra_deferred?: unknown }).__nifra_deferred === true &&
+  typeof (value as { readonly promise?: { readonly then?: unknown } }).promise?.then === "function"
+
+/**
+ * Pull each property's raw TypeBox schema out of its `NifraSchema` wrapper. `where` names the calling
+ * constructor: these objects are checked as JSON, so a file field is refused here (it belongs in
+ * `t.form` from `@nifrajs/schema/form`) instead of failing every request later.
+ */
+function unwrap<P extends Props>(where: string, props: P): { [K in keyof P]: P[K]["jsonSchema"] } {
   const out: Record<string, TSchema> = {}
   // Object.entries → own enumerable string keys only (no prototype walk).
-  for (const [key, schema] of Object.entries(props)) out[key] = schema.jsonSchema
+  for (const [key, schema] of Object.entries(props)) {
+    refuseFile(where, schema.jsonSchema)
+    out[key] = schema.jsonSchema
+  }
   return out as { [K in keyof P]: P[K]["jsonSchema"] }
 }
 
+/** An open object whose scalar fields are coerced from strings - the shape of every request input
+ * that arrives as name/value text (a query string, a `Cookie` header). */
+const textFields =
+  (where: string) =>
+  <P extends Props>(props: P, options?: ObjectOptions) =>
+    fromTypeBox(Type.Object(unwrap(where, props), { additionalProperties: true, ...options }), {
+      coerce: true,
+    })
+
 /**
  * The built-in schema builder. Each constructor returns a `NifraSchema` - a
  * Standard Schema whose validated output type flows into `c.body`/`c.query`, and
@@ -46,16 +86,33 @@ export const t = {
   // properties (no mass-assignment). Use `t.looseObject` (or pass `{ additionalProperties: true }`) to
   // opt into an open object; an explicit `options.additionalProperties` always wins over the default.
   object: <P extends Props>(props: P, options?: ObjectOptions) =>
-    fromTypeBox(Type.Object(unwrap(props), { additionalProperties: false, ...options })),
+    fromTypeBox(
+      Type.Object(unwrap("t.object", props), { additionalProperties: false, ...options }),
+    ),
   /** Like `t.object` but ACCEPTS (and passes through) unknown fields - the explicit opt-out of the
    * strict default. Prefer `t.object` unless you genuinely need an open object. */
   looseObject: <P extends Props>(props: P, options?: ObjectOptions) =>
-    fromTypeBox(Type.Object(unwrap(props), { additionalProperties: true, ...options })),
-  array: <T extends TSchema>(item: NifraSchema<T>, options?: ArrayOptions) =>
+    fromTypeBox(
+      Type.Object(unwrap("t.looseObject", props), { additionalProperties: true, ...options }),
+    ),
+  /**
+   * A list. A list of `t.file()` (from `@nifrajs/schema/form`) honors `minItems` / `maxItems` and is
+   * used inside `t.form`.
+   */
+  array: <T extends TSchema>(
+    item: NifraSchema<T>,
+    options?: ArrayOptions,
+  ): NifraSchema<TArray<T>> =>
+    (fileOps("t.array", item)?.array(item, options) as NifraSchema<TArray<T>> | undefined) ??
     fromTypeBox(Type.Array(item.jsonSchema, options)),
-  /** Marks a property optional inside `t.object`; standalone it is `T | undefined`. */
-  optional: <T extends TSchema>(schema: NifraSchema<T>) =>
-    fromTypeBox(Type.Optional(schema.jsonSchema)),
+  /** Marks a property optional inside `t.object` / `t.form`; standalone it is `T | undefined`. */
+  optional: <T extends TSchema>(schema: NifraSchema<T>) => {
+    const plain = () => fromTypeBox(Type.Optional(schema.jsonSchema))
+    return (
+      (fileOps("t.optional", schema)?.optional(schema) as ReturnType<typeof plain> | undefined) ??
+      plain()
+    )
+  },
   // `const S` captures the argument as a tuple; the explicit return type then maps
   // over that captured tuple (`S[K]["jsonSchema"]`) so the union's `Static` is
   // `A | B`, not `unknown` - the value-level `.map` can't preserve per-element
@@ -63,17 +120,25 @@ export const t = {
   // (order/length are preserved by `map`, so the tuple shape is sound).
   union: <const S extends readonly NifraSchema[]>(schemas: S) =>
     fromTypeBox(
-      Type.Union((schemas as readonly NifraSchema[]).map((schema) => schema.jsonSchema)),
+      Type.Union(
+        (schemas as readonly NifraSchema[]).map((schema) => {
+          refuseFile("t.union", schema.jsonSchema)
+          return schema.jsonSchema
+        }),
+      ),
     ) as NifraSchema<TUnion<{ -readonly [K in keyof S]: S[K]["jsonSchema"] }>>,
-  record: <T extends TSchema>(value: NifraSchema<T>, options?: ObjectOptions) =>
-    fromTypeBox(Type.Record(Type.String(), value.jsonSchema, options)),
+  record: <T extends TSchema>(value: NifraSchema<T>, options?: ObjectOptions) => {
+    refuseFile("t.record", value.jsonSchema)
+    return fromTypeBox(Type.Record(Type.String(), value.jsonSchema, options))
+  },
 
   // Composed from TypeBox directly (not `t.object`/`t.array`) so the `t` literal doesn't reference
   // itself during inference. Cursor pagination - not OFFSET - is the production default: stable under
   // concurrent inserts and O(1) per page. Build pages with `paginate()` + `encodeCursor`/`decodeCursor`.
   /** A cursor-pagination response envelope: `{ items: T[]; nextCursor: string | null }` (`null` = last page). */
-  paginated: <T extends TSchema>(item: NifraSchema<T>, options?: ObjectOptions) =>
-    fromTypeBox(
+  paginated: <T extends TSchema>(item: NifraSchema<T>, options?: ObjectOptions) => {
+    refuseFile("t.paginated", item.jsonSchema)
+    return fromTypeBox(
       Type.Object(
         {
           items: Type.Array(item.jsonSchema),
@@ -81,7 +146,8 @@ export const t = {
         },
         { additionalProperties: false, ...options },
       ),
-    ),
+    )
+  },
   /** A request query schema for cursor pagination: `{ cursor?: string; limit?: number }`. `maxLimit`
    * caps `limit` - a larger value fails validation (a 422), so a client can't request an unbounded page.
    * `coerce` is on because query values arrive as strings (`?limit=20` → `"20"`); it's what makes `limit`
@@ -106,8 +172,42 @@ export const t = {
    * traffic appends params your schema never declares, causing 422s that never appear in dev/CI). Pass
    * `{ additionalProperties: false }` to enforce a strict allowlist. This is the query-slot constructor;
    * `t.object` stays the constructor for body slots (no coercion, a JSON body is already typed). */
-  query: <P extends Props>(props: P, options?: ObjectOptions) =>
-    fromTypeBox(Type.Object(unwrap(props), { additionalProperties: true, ...options }), {
-      coerce: true,
-    }),
+  query: textFields("t.query"),
+  /** A request-cookie schema for the `cookies` route slot, with the same string->scalar COERCION as
+   * `t.query` (cookie values always arrive as strings). **Open by default**: a browser sends every
+   * cookie the site has set - analytics, consent, other routes' sessions - so a strict allowlist
+   * would 422 real traffic. Declare the cookies the route reads; the rest pass through. */
+  cookies: textFields("t.cookies"),
+
+  /**
+   * A loader value marked with `defer()`, streamed in after the shell. `inner` describes what the
+   * promise resolves to; `@nifrajs/web` projects and validates the resolved value by it before it
+   * streams, so a deferred value is held to the same output contract as the rest of the data.
+   */
+  deferred: <T extends TSchema>(
+    inner: NifraSchema<T>,
+  ): NifraSchema<TUnsafe<DeferredValue<Static<T>>>> => {
+    refuseFile("t.deferred", inner.jsonSchema)
+    if (!TypeRegistry.Has(DEFERRED_KIND)) TypeRegistry.Set(DEFERRED_KIND, isDeferredValue)
+    return fromTypeBox(
+      Type.Unsafe<DeferredValue<Static<T>>>({
+        [Kind]: DEFERRED_KIND,
+        "x-nifra-deferred": true,
+        inner: inner.jsonSchema,
+        [DEFERRED_VALIDATE]: inner["~standard"].validate,
+      }),
+    )
+  },
+  /**
+   * Allow a field with a sensitive name (`token`, `password`, `apiKey`, ...) in an output schema.
+   * An output schema that declares one without this fails at route load; `reason` records why this
+   * value may reach the browser, for the reviewer who finds it later.
+   */
+  declassified: <T extends TSchema>(reason: string, schema: NifraSchema<T>): NifraSchema<T> => {
+    if (typeof reason !== "string" || reason.trim() === "") {
+      throw new TypeError("t.declassified: give the reason this field may reach the browser")
+    }
+    refuseFile("t.declassified", schema.jsonSchema)
+    return fromTypeBox(CloneType(schema.jsonSchema, { "x-nifra-declassified": reason }) as T)
+  },
 } as const