@maroonedog/luq 2.0.0 → 2.1.0

package/README.md

@@ -6,13 +6,42 @@
 [![npm version](https://img.shields.io/npm/v/@maroonedog/luq.svg)](https://www.npmjs.com/package/@maroonedog/luq)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-**A TypeScript validation library that validates the types you already have.**
+**A TypeScript validation library where the wrong rule does not compile.**
 
 </div>
 
-Luq takes a type you wrote — not a schema you rewrote — and lets you declare
-rules against its field paths. Every rule you can call is a plugin you imported
-by name, so the bundle contains what you used and nothing else.
+Your types were probably not written by you. `openapi-typescript` generates
+them from a spec you do not own. Prisma and Drizzle generate them from the
+schema of record. protobuf and GraphQL codegen generate them for services in
+four languages at once. Increasingly, a model generates the code that uses them.
+
+A validator whose schema is the source of truth assumes you are the one who
+decides the shape. When you are not, it asks you to write that shape a second
+time and keep the copy in step by hand — and nothing checks that the two still
+agree. They drift, and the first sign is a value that passed the copy and does
+not fit the original.
+
+Luq runs the other way. It takes the type you already have and lets you declare
+rules against its field paths. What makes those declarations worth writing is
+that the compiler checks them against the type: a rule that does not apply to
+the field it is written on is a compile error, not a rule that quietly never
+fires.
+
+That matters most when the code calling this library is generated rather than
+typed by hand. A generator that picks the wrong rule, misspells a path or drops
+an array wildcard gets a red squiggle, not a validator that passes everything.
+
+| Mistake | Result |
+|---|---|
+| A slot unrelated to the field's type (`b.string` on a `number`) | compile error |
+| A missing `[*]` (`"items.name"`) | compile error |
+| Descending into a built-in (`"when.getTime"` on a `Date`) | compile error |
+| A method that does not exist inside an element sub-chain | compile error |
+| A JSON Schema keyword bound to a chain method that does not exist | compile error |
+| A documented example drifting from the API | fails CI |
+
+Every rule you can call is a plugin you imported by name, so the bundle contains
+what you used and nothing else.
 
 Every number on this page was measured on this repository. Where a measurement
 is worse than the 1.x release, it is written down as worse. The provenance of
@@ -21,7 +50,7 @@ each figure is named next to it.
 ## Install
 
 ```bash
-npm install @maroonedog/luq@alpha
+npm install @maroonedog/luq
 ```
 
 ## Quick start
@@ -179,17 +208,78 @@ Measured Draft-07 conformance against the official
 [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
 (required tests only, skipped cases counted as **failures**):
 
-**828 / 929 = 89.13%.** A validator that returned `true` unconditionally would
-score 551 / 929 = 59.31% on this corpus, which is the number the 89% should be
-read against. Full breakdown, including every one of the 101 failures:
+**929 / 929 = 100.00%.** Read that against the floor, not against zero: a
+validator that returned `true` unconditionally scores 551 / 929 = 59.31% on
+this corpus. The skip list is empty, and its `cause` union is `never`, so
+excluding a case again means adding a name to a type. Full breakdown, including
+what closed each cause and what is still bounded:
 [docs/json-schema-conformance.md](docs/json-schema-conformance.md).
 
+External `$ref` resolves against a map of documents **you** already have —
+`jsonSchemaFullFeature(document, { externalDocuments })`. Luq never fetches, so
+a URI written in a schema cannot make the process open a socket, conversion
+stays synchronous, and nothing is evaluated.
+
 `jsonSchemaFullFeature` bundles 49 plugins so one import covers a whole
 document. `@maroonedog/luq/plugins/jsonSchema` adds a chain method instead, so a
 single declared field can be constrained by a document; it takes the plugin bag
 explicitly. It is billed as the tree-shakeable half, and measured below, it is
 not — use it for the chain method, not to save bytes.
 
+## Standard Schema
+
+Luq implements [Standard Schema v1](https://standardschema.dev). Anything that
+accepts a Standard Schema — tRPC, TanStack Form, Hono, t3-env — accepts a Luq
+validator wherever it accepts a zod schema.
+
+```ts
+import { Builder } from "@maroonedog/luq";
+import { requiredPlugin } from "@maroonedog/luq/plugins/required";
+import { stringMinPlugin } from "@maroonedog/luq/plugins/stringMin";
+import { toStandardSchema } from "@maroonedog/luq/standard-schema";
+
+type Account = { handle: string };
+
+const standard = toStandardSchema(
+  Builder()
+    .use(requiredPlugin)
+    .use(stringMinPlugin)
+    .for<Account>()
+    .v("handle", (b) => b.string.required().min(2))
+    .build()
+);
+
+// `standard` is still the Validator — `validate`, `parse`, `pick` and `pickAll`
+// are all there — and it now also satisfies Standard Schema v1, so it can be
+// handed to tRPC, TanStack Form, Hono or t3-env unchanged.
+const outcome = standard["~standard"].validate({ handle: "j" });
+
+if (outcome.issues === undefined) {
+  console.error(outcome.value.handle);
+} else {
+  for (const issue of outcome.issues) {
+    console.error(issue.message, issue.path);
+  }
+}
+```
+
+Three decisions the spec leaves open, made explicit here:
+
+- `validate` calls Luq's `parse()`, not `validate()`. The spec's success result
+  is `{ value: Output }`, and `Output` is the value *after* validation — so a
+  `transform` has to be applied, and only `parse()` applies it.
+- It collects every issue rather than stopping at the first. The consumer of
+  this seam is a form, and returning one issue at a time produces a UI where
+  fixing an error reveals the next one. Callers who want the fast path use the
+  `Validator` directly.
+- `InferInput` is the type you wrote in `.for<T>()`, not a type inferred back
+  out of a schema value.
+
+It is a subpath, not part of `build()`. Measured: the core gzips to 7,420 B and
+carrying `~standard` on every validator adds 312 B — 4.2% charged to everyone,
+including the people who never pass a validator to tRPC. Importing the subpath
+costs those 312 B only when you import it, and nothing when you don't.
+
 ## Your own rules
 
 ```ts
@@ -374,8 +464,8 @@ the 84 keys** against the published declarations under **both** `node16` and
   every subpath, method and slot
 - **[Breaking changes from 1.x](docs/migration/breaking-changes.md)** — every
   incompatibility with the fix beside it
-- **[Draft-07 conformance](docs/json-schema-conformance.md)** — the 89.13% and
-  all 101 failures
+- **[Draft-07 conformance](docs/json-schema-conformance.md)** — the 100% and
+  what closed each of the ten causes that used to fail
 
 ## About the "universal platform" goal
 

package/dist/chain/create-chain-node.js

@@ -22,6 +22,7 @@ exports.readChainRules = readChainRules;
 // needs no assertion and no runtime shape check.
 // ===========================================================================
 const types_1 = require("../types");
+const create_rule_1 = require("../plugin-kit/create-rule");
 const refine_methods_types_1 = require("./refine-methods.types");
 const attach_slot_methods_1 = require("./attach-slot-methods");
 const chainRulesByNode = new WeakMap();
@@ -52,13 +53,33 @@ function buildRuleContext(wiring, plugin, rawOptions) {
         declaredSiblingKeys: wiring.context.declaredSiblingKeys,
     };
 }
+/**
+ * The presence rule a `judgesNull` plugin brings with it. It forbids
+ * NOTHING — it only says that null must reach the checks instead of ending
+ * the field, which is the one thing a check cannot say for itself.
+ */
+function nullIsAValue(severity) {
+    return (0, create_rule_1.presence)({
+        code: "type",
+        severity,
+        allowUndefined: true,
+        allowNull: true,
+        emptyStringIsMissing: false,
+        nullIsValue: true,
+        describe: (messageContext) => `${messageContext.path} must not be null`,
+        buildMessageContext: () => ({}),
+    });
+}
 function createSlotMethod(wiring, slot, rules, plugin) {
     const arity = Math.max(plugin.build.length - 1, 0);
     return (...args) => {
         const rawOptions = args.length > arity ? args[arity] : undefined;
         const resolved = wiring.resolveArguments(plugin, args.slice(0, arity));
         const rule = plugin.build(buildRuleContext(wiring, plugin, rawOptions), ...resolved);
-        return createChainNode(wiring, slot, [...rules, rule]);
+        const added = plugin.judgesNull === true
+            ? [nullIsAValue(wiring.context.config.defaultSeverity), rule]
+            : [rule];
+        return createChainNode(wiring, slot, [...rules, ...added]);
     };
 }
 function attachRefineMethods(target, wiring, rules) {

package/dist/chain/create-chain-node.mjs

@@ -17,6 +17,7 @@
 // needs no assertion and no runtime shape check.
 // ===========================================================================
 import { isPlainObject, isString } from "../types/index.mjs";
+import { presence } from "../plugin-kit/create-rule.mjs";
 import { REFINE_METHOD_SLOTS } from "./refine-methods.types.mjs";
 import { attachSlotMethods } from "./attach-slot-methods.mjs";
 const chainRulesByNode = new WeakMap();
@@ -47,13 +48,33 @@ function buildRuleContext(wiring, plugin, rawOptions) {
         declaredSiblingKeys: wiring.context.declaredSiblingKeys,
     };
 }
+/**
+ * The presence rule a `judgesNull` plugin brings with it. It forbids
+ * NOTHING — it only says that null must reach the checks instead of ending
+ * the field, which is the one thing a check cannot say for itself.
+ */
+function nullIsAValue(severity) {
+    return presence({
+        code: "type",
+        severity,
+        allowUndefined: true,
+        allowNull: true,
+        emptyStringIsMissing: false,
+        nullIsValue: true,
+        describe: (messageContext) => `${messageContext.path} must not be null`,
+        buildMessageContext: () => ({}),
+    });
+}
 function createSlotMethod(wiring, slot, rules, plugin) {
     const arity = Math.max(plugin.build.length - 1, 0);
     return (...args) => {
         const rawOptions = args.length > arity ? args[arity] : undefined;
         const resolved = wiring.resolveArguments(plugin, args.slice(0, arity));
         const rule = plugin.build(buildRuleContext(wiring, plugin, rawOptions), ...resolved);
-        return createChainNode(wiring, slot, [...rules, rule]);
+        const added = plugin.judgesNull === true
+            ? [nullIsAValue(wiring.context.config.defaultSeverity), rule]
+            : [rule];
+        return createChainNode(wiring, slot, [...rules, ...added]);
     };
 }
 function attachRefineMethods(target, wiring, rules) {

package/dist/compile/resolve-conditional-presence.js

@@ -33,6 +33,7 @@ function toPolicy(rule, allowance) {
         allowUndefined: allowance.allowUndefined,
         allowNull: allowance.allowNull,
         emptyStringIsMissing: allowance.emptyStringIsMissing,
+        nullIsValue: allowance.nullIsValue === true,
         // Wrapped rather than aliased, so a `describe` written as an object
         // method keeps its receiver.
         describe: (messageContext) => rule.describe(messageContext),

package/dist/compile/resolve-conditional-presence.mjs

@@ -29,6 +29,7 @@ function toPolicy(rule, allowance) {
         allowUndefined: allowance.allowUndefined,
         allowNull: allowance.allowNull,
         emptyStringIsMissing: allowance.emptyStringIsMissing,
+        nullIsValue: allowance.nullIsValue === true,
         // Wrapped rather than aliased, so a `describe` written as an object
         // method keeps its receiver.
         describe: (messageContext) => rule.describe(messageContext),

package/dist/compile/resolve-presence.js

@@ -11,6 +11,7 @@ const OPEN_POLICY = {
     allowUndefined: true,
     allowNull: true,
     emptyStringIsMissing: false,
+    nullIsValue: false,
     describe: () => "This field declares no presence rule",
 };
 exports.OPEN_PRESENCE = Object.freeze(OPEN_POLICY);
@@ -24,6 +25,9 @@ function resolvePresence(rules) {
         allowUndefined: rules.some((rule) => rule.allowUndefined),
         allowNull: rules.some((rule) => rule.allowNull),
         emptyStringIsMissing: rules.some((rule) => rule.emptyStringIsMissing),
+        // One rule saying "null is a value here" is enough: the checks then run
+        // and decide, which is strictly more judgement, never less.
+        nullIsValue: rules.some((rule) => rule.nullIsValue === true),
         describe: (ctx) => strictest.describe(ctx),
     };
     return Object.freeze(policy);

package/dist/compile/resolve-presence.mjs

@@ -7,6 +7,7 @@ const OPEN_POLICY = {
     allowUndefined: true,
     allowNull: true,
     emptyStringIsMissing: false,
+    nullIsValue: false,
     describe: () => "This field declares no presence rule",
 };
 export const OPEN_PRESENCE = Object.freeze(OPEN_POLICY);
@@ -20,6 +21,9 @@ export function resolvePresence(rules) {
         allowUndefined: rules.some((rule) => rule.allowUndefined),
         allowNull: rules.some((rule) => rule.allowNull),
         emptyStringIsMissing: rules.some((rule) => rule.emptyStringIsMissing),
+        // One rule saying "null is a value here" is enough: the checks then run
+        // and decide, which is strictly more judgement, never less.
+        nullIsValue: rules.some((rule) => rule.nullIsValue === true),
         describe: (ctx) => strictest.describe(ctx),
     };
     return Object.freeze(policy);

package/dist/compile/validation-plan.types.d.ts

@@ -23,6 +23,16 @@ export interface PresencePolicy {
     readonly allowUndefined: boolean;
     readonly allowNull: boolean;
     readonly emptyStringIsMissing: boolean;
+    /**
+     * True when `null` is a VALUE this subject has to judge, rather than an
+     * absence presence may settle. Draft-07 sub-schemas need it: `false`,
+     * `{"not": {}}` and an `enum` without null all forbid null WITHOUT saying
+     * anything about `type`, and presence — which runs first — was answering
+     * for them. `[null]` passed `{"items":{"not":{}}}` because no check ever
+     * ran. Only src/json-schema/ sets it; a field the user declared keeps the
+     * builder's meaning, where `.nullable()` ends the field.
+     */
+    readonly nullIsValue: boolean;
     describe(ctx: MessageContext): string;
 }
 /**

package/dist/json-schema/build-from-schema.js

@@ -8,7 +8,7 @@ const create_field_builder_1 = require("../builder/create-field-builder");
 const type_erasure_1 = require("../core/type-erasure");
 const create_structural_context_1 = require("./create-structural-context");
 const declare_presence_1 = require("./declare-presence");
-const declare_value_keywords_1 = require("./declare-value-keywords");
+const ref_scope_1 = require("./ref-scope");
 const draft07_types_1 = require("./draft07.types");
 const flatten_schema_1 = require("./flatten-schema");
 const schema_to_declarations_1 = require("./schema-to-declarations");
@@ -25,11 +25,10 @@ class NotASchemaError extends Error {
 exports.NotASchemaError = NotASchemaError;
 /** The rules ONE declared path carries: its presence policy and its schema. */
 function collectDeclaredRules(declaration, bag, root, chain) {
-    const context = (0, create_structural_context_1.createStructuralContext)({ bag, root, chain }, declaration.schema, Object.freeze([]));
+    const context = (0, create_structural_context_1.createStructuralContext)({ bag, scope: (0, ref_scope_1.createLocalScope)(root), chain }, declaration.schema, Object.freeze([]));
     return Object.freeze([
         ...(0, declare_presence_1.declarePresenceRules)({
             isRequired: declaration.isRequired,
-            allowsNull: (0, declare_value_keywords_1.permitsNull)(declaration.schema),
             severity: chain.config.defaultSeverity,
         }),
         ...(0, schema_to_declarations_1.expandSchemaRules)(declaration.schema, context),

package/dist/json-schema/build-from-schema.mjs

@@ -2,7 +2,7 @@ import { createFieldBuilderSurface } from "../builder/create-field-builder.mjs";
 import { eraseSchemaValidator } from "../core/type-erasure.mjs";
 import { createStructuralContext } from "./create-structural-context.mjs";
 import { declarePresenceRules } from "./declare-presence.mjs";
-import { permitsNull } from "./declare-value-keywords.mjs";
+import { createLocalScope } from "./ref-scope.mjs";
 import { isDraft07Schema } from "./draft07.types.mjs";
 import { flattenSchema } from "./flatten-schema.mjs";
 import { expandSchemaRules, readChildSchemas } from "./schema-to-declarations.mjs";
@@ -18,11 +18,10 @@ export class NotASchemaError extends Error {
 }
 /** The rules ONE declared path carries: its presence policy and its schema. */
 function collectDeclaredRules(declaration, bag, root, chain) {
-    const context = createStructuralContext({ bag, root, chain }, declaration.schema, Object.freeze([]));
+    const context = createStructuralContext({ bag, scope: createLocalScope(root), chain }, declaration.schema, Object.freeze([]));
     return Object.freeze([
         ...declarePresenceRules({
             isRequired: declaration.isRequired,
-            allowsNull: permitsNull(declaration.schema),
             severity: chain.config.defaultSeverity,
         }),
         ...expandSchemaRules(declaration.schema, context),

package/dist/json-schema/collect-definitions.d.ts

@@ -1,4 +1,5 @@
 import type { Draft07Schema, Draft07SchemaObject } from "./draft07.types";
+import type { RefScope } from "./ref-scope";
 /** The two container spellings, in the order a pointer would try them. */
 export declare const DEFINITION_CONTAINERS: readonly string[];
 export declare function isDefinitionContainer(keyword: string): boolean;
@@ -10,6 +11,35 @@ export declare function toSchemaObject(schema: Draft07Schema): Draft07SchemaObje
  * this draft `$ref` replaces the object it appears in.
  */
 export declare function resolveSchemaNode(schema: Draft07Schema, root: Draft07Schema): Draft07SchemaObject;
+/** What a node resolved to, and the scope that is in force INSIDE it. */
+export interface ResolvedNode {
+    readonly node: Draft07SchemaObject;
+    readonly scope: RefScope;
+}
+/**
+ * The scope-aware form, and the one the converter uses.
+ *
+ * The returned scope is not the one passed in: following a `$ref` can cross
+ * into another document, and a `$ref` written inside THAT document resolves
+ * against ITS base. Returning only the node — which is what the root-taking
+ * form above can do — loses that, and is why a two-document schema resolved
+ * its second hop against the first document.
+ */
+export declare function resolveSchemaNodeInScope(schema: Draft07Schema, scope: RefScope): ResolvedNode;
+/**
+ * The ONE place a base URI advances. It was also being done by the caller,
+ * and doing it in both meant a relative `$id` was applied twice: a `$ref`
+ * of "nested/foo.json" under `$id: "nested/"` went looking for
+ * ".../nested/nested/foo.json".
+ *
+ * A base-setting `$id` starts a new RESOURCE, so the node also becomes the
+ * document that `#/definitions/x` written under it resolves against. Moving
+ * the base without moving the document is why
+ * `{"$id":"a.json","properties":{"foo":{"$id":"b.json","definitions":{...},
+ * "allOf":[{"$ref":"#/definitions/inner"}]}}}` looked for `inner` in the
+ * OUTER document, where it does not exist.
+ */
+export declare function advanceBase(scope: RefScope, node: Draft07SchemaObject): RefScope;
 /**
  * The pointer a node forwards to, or undefined. Used by the flattener to spot
  * a recursive definition BEFORE it walks into it: `#/definitions/node` inside

package/dist/json-schema/collect-definitions.js

@@ -4,10 +4,14 @@ exports.DEFINITION_CONTAINERS = void 0;
 exports.isDefinitionContainer = isDefinitionContainer;
 exports.toSchemaObject = toSchemaObject;
 exports.resolveSchemaNode = resolveSchemaNode;
+exports.resolveSchemaNodeInScope = resolveSchemaNodeInScope;
+exports.advanceBase = advanceBase;
 exports.readRefPointer = readRefPointer;
 exports.collectDefinitionNames = collectDefinitionNames;
 const draft07_types_1 = require("./draft07.types");
+const ref_scope_1 = require("./ref-scope");
 const resolve_ref_1 = require("./resolve-ref");
+const uri_reference_1 = require("./uri-reference");
 /** `true`: matches every instance. */
 const ALWAYS_SCHEMA = Object.freeze({});
 /** `false`: matches nothing. `not` of the empty schema, so no new rule kind. */
@@ -36,10 +40,50 @@ function toSchemaObject(schema) {
  * this draft `$ref` replaces the object it appears in.
  */
 function resolveSchemaNode(schema, root) {
+    return resolveSchemaNodeInScope(schema, (0, ref_scope_1.createLocalScope)(root)).node;
+}
+/**
+ * The scope-aware form, and the one the converter uses.
+ *
+ * The returned scope is not the one passed in: following a `$ref` can cross
+ * into another document, and a `$ref` written inside THAT document resolves
+ * against ITS base. Returning only the node — which is what the root-taking
+ * form above can do — loses that, and is why a two-document schema resolved
+ * its second hop against the first document.
+ */
+function resolveSchemaNodeInScope(schema, scope) {
     const node = toSchemaObject(schema);
-    if (node.$ref === undefined)
-        return node;
-    return toSchemaObject((0, resolve_ref_1.resolveRef)(node.$ref, root));
+    if (node.$ref === undefined) {
+        // A node's own `$id` moves the base for everything inside it (§8.2).
+        return { node, scope: advanceBase(scope, node) };
+    }
+    // Following a `$ref` lands in whatever base the TARGET lives in, and
+    // resolve-ref already knows it — for a document fetched by URI that is the
+    // retrieval URI, which the draft says wins over the document's own `$id`.
+    const resolved = (0, resolve_ref_1.resolveRefInScope)(node.$ref, scope);
+    return { node: toSchemaObject(resolved.schema), scope: resolved.scope };
+}
+/**
+ * The ONE place a base URI advances. It was also being done by the caller,
+ * and doing it in both meant a relative `$id` was applied twice: a `$ref`
+ * of "nested/foo.json" under `$id: "nested/"` went looking for
+ * ".../nested/nested/foo.json".
+ *
+ * A base-setting `$id` starts a new RESOURCE, so the node also becomes the
+ * document that `#/definitions/x` written under it resolves against. Moving
+ * the base without moving the document is why
+ * `{"$id":"a.json","properties":{"foo":{"$id":"b.json","definitions":{...},
+ * "allOf":[{"$ref":"#/definitions/inner"}]}}}` looked for `inner` in the
+ * OUTER document, where it does not exist.
+ */
+function advanceBase(scope, node) {
+    const id = node.$id;
+    if (typeof id !== "string" || id === "")
+        return scope;
+    const baseUri = (0, uri_reference_1.nextBaseUri)(scope.baseUri, id);
+    if (baseUri === scope.baseUri)
+        return scope;
+    return { ...scope, baseUri, document: node };
 }
 /**
  * The pointer a node forwards to, or undefined. Used by the flattener to spot

package/dist/json-schema/collect-definitions.mjs

@@ -1,5 +1,7 @@
 import { isSchemaObject } from "./draft07.types.mjs";
-import { resolveRef } from "./resolve-ref.mjs";
+import { createLocalScope } from "./ref-scope.mjs";
+import { resolveRefInScope } from "./resolve-ref.mjs";
+import { nextBaseUri } from "./uri-reference.mjs";
 /** `true`: matches every instance. */
 const ALWAYS_SCHEMA = Object.freeze({});
 /** `false`: matches nothing. `not` of the empty schema, so no new rule kind. */
@@ -28,10 +30,50 @@ export function toSchemaObject(schema) {
  * this draft `$ref` replaces the object it appears in.
  */
 export function resolveSchemaNode(schema, root) {
+    return resolveSchemaNodeInScope(schema, createLocalScope(root)).node;
+}
+/**
+ * The scope-aware form, and the one the converter uses.
+ *
+ * The returned scope is not the one passed in: following a `$ref` can cross
+ * into another document, and a `$ref` written inside THAT document resolves
+ * against ITS base. Returning only the node — which is what the root-taking
+ * form above can do — loses that, and is why a two-document schema resolved
+ * its second hop against the first document.
+ */
+export function resolveSchemaNodeInScope(schema, scope) {
     const node = toSchemaObject(schema);
-    if (node.$ref === undefined)
-        return node;
-    return toSchemaObject(resolveRef(node.$ref, root));
+    if (node.$ref === undefined) {
+        // A node's own `$id` moves the base for everything inside it (§8.2).
+        return { node, scope: advanceBase(scope, node) };
+    }
+    // Following a `$ref` lands in whatever base the TARGET lives in, and
+    // resolve-ref already knows it — for a document fetched by URI that is the
+    // retrieval URI, which the draft says wins over the document's own `$id`.
+    const resolved = resolveRefInScope(node.$ref, scope);
+    return { node: toSchemaObject(resolved.schema), scope: resolved.scope };
+}
+/**
+ * The ONE place a base URI advances. It was also being done by the caller,
+ * and doing it in both meant a relative `$id` was applied twice: a `$ref`
+ * of "nested/foo.json" under `$id: "nested/"` went looking for
+ * ".../nested/nested/foo.json".
+ *
+ * A base-setting `$id` starts a new RESOURCE, so the node also becomes the
+ * document that `#/definitions/x` written under it resolves against. Moving
+ * the base without moving the document is why
+ * `{"$id":"a.json","properties":{"foo":{"$id":"b.json","definitions":{...},
+ * "allOf":[{"$ref":"#/definitions/inner"}]}}}` looked for `inner` in the
+ * OUTER document, where it does not exist.
+ */
+export function advanceBase(scope, node) {
+    const id = node.$id;
+    if (typeof id !== "string" || id === "")
+        return scope;
+    const baseUri = nextBaseUri(scope.baseUri, id);
+    if (baseUri === scope.baseUri)
+        return scope;
+    return { ...scope, baseUri, document: node };
 }
 /**
  * The pointer a node forwards to, or undefined. Used by the flattener to spot

package/dist/json-schema/collect-sub-schema-rules.d.ts

@@ -2,5 +2,16 @@ import type { CompositeBranch, Rule } from "../plugin-kit/compiled-rule";
 import type { Draft07Schema } from "./draft07.types";
 import type { StructuralContext } from "./structural-expansion.types";
 export declare function collectSubSchemaRules(schema: Draft07Schema, context: StructuralContext): readonly Rule[];
-/** Every branch of every composite is built here, so a branch is one shape. */
+/**
+ * Every branch of every composite is built here, so a branch is one shape.
+ *
+ * The call is to the function above and NOT to `context.collectSubSchemaRules`,
+ * and the difference is load-bearing. `context` is already the child context
+ * that createStructuralContext produced by DESCENDING through this schema, so
+ * a `$ref` here is already recorded in `visitedRefs`. Going through the
+ * context would descend the same `$ref` a second time, the recursion guard
+ * would see it as a cycle, and the branch would come back with no rules at all
+ * — `{"items":[{"$ref":"#/definitions/x"}]}` constrained nothing while the
+ * inline form `{"items":[{"type":"integer"}]}` worked.
+ */
 export declare function toSchemaBranch(label: string, schema: Draft07Schema, context: StructuralContext): CompositeBranch;

package/dist/json-schema/collect-sub-schema-rules.js

@@ -24,18 +24,15 @@ const create_rule_1 = require("../plugin-kit/create-rule");
 const types_1 = require("../types");
 const collect_definitions_1 = require("./collect-definitions");
 const declare_presence_1 = require("./declare-presence");
-const declare_value_keywords_1 = require("./declare-value-keywords");
 const flatten_array_schema_1 = require("./flatten-array-schema");
 const schema_to_declarations_1 = require("./schema-to-declarations");
 const NO_BRANCH_FIELDS = Object.freeze([]);
 function toBranchField(child, context) {
-    const node = (0, collect_definitions_1.resolveSchemaNode)(child.schema, context.root);
     return {
         path: child.step,
         rules: Object.freeze([
             ...(0, declare_presence_1.declarePresenceRules)({
                 isRequired: child.isRequired,
-                allowsNull: (0, declare_value_keywords_1.permitsNull)(node),
                 severity: context.build.config.defaultSeverity,
             }),
             ...context.collectSubSchemaRules(child.schema),
@@ -56,9 +53,31 @@ function composeProperties(children, context) {
         }),
     ];
 }
+/**
+ * Every sub-schema subject gets the same one-line statement: null is a VALUE
+ * here, so the checks run on it.
+ *
+ * src/runtime/run-field.ts settles presence BEFORE any check, and a subject
+ * with no presence rule carries OPEN_PRESENCE, which ends the field on null.
+ * A branch subject and an array element both arrive without one, so every
+ * check the sub-schema declared was skipped for null: `[null]` passed
+ * `{"items":{"type":"boolean"}}`, and `additionalItems: false` accepted a
+ * trailing null. Deciding it from `type` alone is not enough either —
+ * `false`, `{"not": {}}` and an `enum` without null forbid null while
+ * saying nothing about `type`.
+ */
+function declareOwnNullPolicy(context) {
+    return (0, declare_presence_1.declarePresenceRules)({
+        isRequired: false,
+        severity: context.build.config.defaultSeverity,
+    });
+}
 function collectSubSchemaRules(schema, context) {
-    const node = (0, collect_definitions_1.resolveSchemaNode)(schema, context.root);
-    const rules = [...(0, schema_to_declarations_1.expandSchemaRules)(node, context)];
+    const node = (0, collect_definitions_1.resolveSchemaNodeInScope)(schema, context.scope).node;
+    const rules = [
+        ...declareOwnNullPolicy(context),
+        ...(0, schema_to_declarations_1.expandSchemaRules)(node, context),
+    ];
     const children = (0, schema_to_declarations_1.readChildSchemas)(node);
     const properties = children.filter((child) => child.step !== flatten_array_schema_1.EACH_STEP);
     if (properties.length > 0) {
@@ -72,11 +91,22 @@ function collectSubSchemaRules(schema, context) {
     }
     return Object.freeze(rules);
 }
-/** Every branch of every composite is built here, so a branch is one shape. */
+/**
+ * Every branch of every composite is built here, so a branch is one shape.
+ *
+ * The call is to the function above and NOT to `context.collectSubSchemaRules`,
+ * and the difference is load-bearing. `context` is already the child context
+ * that createStructuralContext produced by DESCENDING through this schema, so
+ * a `$ref` here is already recorded in `visitedRefs`. Going through the
+ * context would descend the same `$ref` a second time, the recursion guard
+ * would see it as a cycle, and the branch would come back with no rules at all
+ * — `{"items":[{"$ref":"#/definitions/x"}]}` constrained nothing while the
+ * inline form `{"items":[{"type":"integer"}]}` worked.
+ */
 function toSchemaBranch(label, schema, context) {
     return {
         label,
-        rules: context.collectSubSchemaRules(schema),
+        rules: collectSubSchemaRules(schema, context),
         fields: NO_BRANCH_FIELDS,
     };
 }