@crewhaus/tool-schema 0.7.0

package/dist/lib/schemadiff.js

@@ -0,0 +1,350 @@
+/**
+ * What changed between two JSON Schemas, and whether a reader survives it.
+ *
+ * ## The compatibility question this answers
+ *
+ * A change is **compatible** when every value that was valid under the old
+ * schema is still valid under the new one — the producer may have widened
+ * things, but nothing a reader already accepts has become invalid. It is
+ * **breaking** when some value valid under the old schema is now rejected.
+ * It is **unknown** when deciding that would require reasoning this package
+ * does not do: whether one regex accepts everything another does, or how two
+ * different `anyOf` unions relate.
+ *
+ * `unknown` is reported, never rounded to compatible. A schema gate that
+ * quietly passes an undecided change is worse than one that asks. That holds
+ * for keywords this file does not model at all — `patternProperties`,
+ * `contains`, `propertyNames`, `dependencies` and anything newer: a change to
+ * one of them comes back `unknown`, not as silence.
+ *
+ * Note the direction: this is compatibility for a *reader* of the data. A
+ * writer sees the mirror image — a widened type is a breaking change for
+ * whoever must now produce it.
+ */
+import { deepEqual, isPlainObject, joinPointer, preview } from "./value";
+function note(ctx, path, keyword, compat, detail) {
+    ctx.changes.push({ path, keyword, detail, compat });
+}
+function asObject(schema) {
+    return isPlainObject(schema) ? schema : null;
+}
+function typeSet(schema) {
+    const declared = schema["type"];
+    if (typeof declared === "string")
+        return new Set([declared]);
+    if (Array.isArray(declared)) {
+        return new Set(declared.filter((t) => typeof t === "string"));
+    }
+    return null;
+}
+function acceptsType(types, type) {
+    return types.has(type) || (type === "integer" && types.has("number"));
+}
+/** A bound that may only loosen: `minimum`, `minLength`, `minItems`, ... */
+function diffLowerBound(ctx, path, keyword, before, after) {
+    if (deepEqual(before, after))
+        return;
+    if (typeof after !== "number") {
+        note(ctx, path, keyword, "compatible", `${keyword} removed — the constraint is gone`);
+        return;
+    }
+    if (typeof before !== "number") {
+        note(ctx, path, keyword, "breaking", `${keyword} added (${after}) where there was no lower bound`);
+        return;
+    }
+    if (after > before)
+        note(ctx, path, keyword, "breaking", `${keyword} raised from ${before} to ${after}`);
+    else
+        note(ctx, path, keyword, "compatible", `${keyword} lowered from ${before} to ${after}`);
+}
+/** A bound that may only loosen upwards: `maximum`, `maxLength`, `maxItems`, ... */
+function diffUpperBound(ctx, path, keyword, before, after) {
+    if (deepEqual(before, after))
+        return;
+    if (typeof after !== "number") {
+        note(ctx, path, keyword, "compatible", `${keyword} removed — the constraint is gone`);
+        return;
+    }
+    if (typeof before !== "number") {
+        note(ctx, path, keyword, "breaking", `${keyword} added (${after}) where there was no upper bound`);
+        return;
+    }
+    if (after < before)
+        note(ctx, path, keyword, "breaking", `${keyword} lowered from ${before} to ${after}`);
+    else
+        note(ctx, path, keyword, "compatible", `${keyword} raised from ${before} to ${after}`);
+}
+const COMPOSITIONAL = ["allOf", "anyOf", "oneOf", "not", "if", "then", "else", "$ref"];
+/**
+ * Keywords {@link diffNode} reasons about itself, either by classifying the
+ * change or by declaring it undecidable. Anything outside this set and
+ * {@link ANNOTATIONS} is swept up at the end of the node as `unknown`, so a
+ * keyword this package has never heard of cannot make a changed schema come
+ * back "compatible".
+ */
+const MODELLED = new Set([
+    ...COMPOSITIONAL,
+    "type",
+    "enum",
+    "const",
+    "required",
+    "minimum",
+    "exclusiveMinimum",
+    "minLength",
+    "minItems",
+    "minProperties",
+    "maximum",
+    "exclusiveMaximum",
+    "maxLength",
+    "maxItems",
+    "maxProperties",
+    "pattern",
+    "format",
+    "multipleOf",
+    "uniqueItems",
+    "properties",
+    "additionalProperties",
+    "items",
+]);
+/**
+ * Keywords that carry no constraint, so changing one cannot change which
+ * values validate. Mirrors the annotation list in `./jsonschema`.
+ */
+const ANNOTATIONS = new Set([
+    "$id",
+    "$schema",
+    "$comment",
+    "title",
+    "description",
+    "default",
+    "examples",
+    "readOnly",
+    "writeOnly",
+    "deprecated",
+    "contentMediaType",
+    "contentEncoding",
+    "$defs",
+    "definitions",
+]);
+function diffNode(before, after, path, ctx) {
+    if (deepEqual(before, after))
+        return;
+    // Boolean schemas: `true` accepts everything, `false` accepts nothing.
+    if (typeof before === "boolean" || typeof after === "boolean") {
+        if (after === false)
+            note(ctx, path, "schema", "breaking", "now rejects every value (false schema)");
+        else if (before === false)
+            note(ctx, path, "schema", "compatible", "no longer rejects every value");
+        else if (after === true)
+            note(ctx, path, "schema", "compatible", "now accepts every value (true schema)");
+        else
+            note(ctx, path, "schema", "breaking", "replaced an unconstrained schema with a constrained one");
+        return;
+    }
+    const a = asObject(before);
+    const b = asObject(after);
+    if (a === null || b === null) {
+        note(ctx, path, "schema", "unknown", "one side is not a schema object");
+        return;
+    }
+    // --- type
+    const aTypes = typeSet(a);
+    const bTypes = typeSet(b);
+    if (aTypes === null && bTypes !== null) {
+        note(ctx, path, "type", "breaking", `type ${[...bTypes].join("|")} added where any type was allowed`);
+    }
+    else if (aTypes !== null && bTypes === null) {
+        note(ctx, path, "type", "compatible", `type ${[...aTypes].join("|")} removed — any type is now allowed`);
+    }
+    else if (aTypes !== null && bTypes !== null) {
+        const lost = [...aTypes].filter((t) => !acceptsType(bTypes, t));
+        const gained = [...bTypes].filter((t) => !acceptsType(aTypes, t));
+        if (lost.length > 0) {
+            note(ctx, path, "type", "breaking", `no longer accepts ${lost.join(", ")}`);
+        }
+        else if (gained.length > 0) {
+            note(ctx, path, "type", "compatible", `also accepts ${gained.join(", ")}`);
+        }
+    }
+    // --- enum and const
+    const aEnum = Array.isArray(a["enum"]) ? a["enum"] : null;
+    const bEnum = Array.isArray(b["enum"]) ? b["enum"] : null;
+    if (aEnum === null && bEnum !== null) {
+        note(ctx, path, "enum", "breaking", `enum added, limiting values to ${preview(bEnum, 80)}`);
+    }
+    else if (aEnum !== null && bEnum === null) {
+        note(ctx, path, "enum", "compatible", "enum removed — values are no longer limited");
+    }
+    else if (aEnum !== null && bEnum !== null) {
+        const removed = aEnum.filter((v) => !bEnum.some((w) => deepEqual(v, w)));
+        const added = bEnum.filter((v) => !aEnum.some((w) => deepEqual(v, w)));
+        if (removed.length > 0) {
+            note(ctx, path, "enum", "breaking", `enum values removed: ${preview(removed, 80)}`);
+        }
+        if (added.length > 0) {
+            note(ctx, path, "enum", "compatible", `enum values added: ${preview(added, 80)}`);
+        }
+    }
+    const aConst = Object.hasOwn(a, "const");
+    const bConst = Object.hasOwn(b, "const");
+    if (!deepEqual(a["const"], b["const"]) || aConst !== bConst) {
+        if (bConst && !aConst) {
+            note(ctx, path, "const", "breaking", `const added (${preview(b["const"], 60)})`);
+        }
+        else if (aConst && !bConst) {
+            note(ctx, path, "const", "compatible", "const removed");
+        }
+        else {
+            note(ctx, path, "const", "breaking", `const changed from ${preview(a["const"], 40)} to ${preview(b["const"], 40)}`);
+        }
+    }
+    // --- required
+    const aRequired = Array.isArray(a["required"])
+        ? a["required"].filter((k) => typeof k === "string")
+        : [];
+    const bRequired = Array.isArray(b["required"])
+        ? b["required"].filter((k) => typeof k === "string")
+        : [];
+    const nowRequired = bRequired.filter((k) => !aRequired.includes(k));
+    const noLongerRequired = aRequired.filter((k) => !bRequired.includes(k));
+    if (nowRequired.length > 0) {
+        note(ctx, path, "required", "breaking", `now required: ${nowRequired.join(", ")}`);
+    }
+    if (noLongerRequired.length > 0) {
+        note(ctx, path, "required", "compatible", `no longer required: ${noLongerRequired.join(", ")}`);
+    }
+    // --- bounds
+    diffLowerBound(ctx, path, "minimum", a["minimum"], b["minimum"]);
+    diffLowerBound(ctx, path, "exclusiveMinimum", a["exclusiveMinimum"], b["exclusiveMinimum"]);
+    diffLowerBound(ctx, path, "minLength", a["minLength"], b["minLength"]);
+    diffLowerBound(ctx, path, "minItems", a["minItems"], b["minItems"]);
+    diffLowerBound(ctx, path, "minProperties", a["minProperties"], b["minProperties"]);
+    diffUpperBound(ctx, path, "maximum", a["maximum"], b["maximum"]);
+    diffUpperBound(ctx, path, "exclusiveMaximum", a["exclusiveMaximum"], b["exclusiveMaximum"]);
+    diffUpperBound(ctx, path, "maxLength", a["maxLength"], b["maxLength"]);
+    diffUpperBound(ctx, path, "maxItems", a["maxItems"], b["maxItems"]);
+    diffUpperBound(ctx, path, "maxProperties", a["maxProperties"], b["maxProperties"]);
+    // --- constraints whose containment this package will not guess at
+    for (const keyword of ["pattern", "format", "multipleOf"]) {
+        const beforeValue = a[keyword];
+        const afterValue = b[keyword];
+        if (deepEqual(beforeValue, afterValue))
+            continue;
+        if (afterValue === undefined) {
+            note(ctx, path, keyword, "compatible", `${keyword} removed`);
+        }
+        else if (beforeValue === undefined) {
+            note(ctx, path, keyword, "breaking", `${keyword} added (${preview(afterValue, 40)})`);
+        }
+        else {
+            note(ctx, path, keyword, "unknown", `${keyword} changed from ${preview(beforeValue, 40)} to ${preview(afterValue, 40)} — containment is not analyzed`);
+        }
+    }
+    if (a["uniqueItems"] !== b["uniqueItems"]) {
+        if (b["uniqueItems"] === true) {
+            note(ctx, path, "uniqueItems", "breaking", "items must now be unique");
+        }
+        else {
+            note(ctx, path, "uniqueItems", "compatible", "items need no longer be unique");
+        }
+    }
+    // --- properties
+    const aProps = asObject(a["properties"]) ?? {};
+    const bProps = asObject(b["properties"]) ?? {};
+    const propsPath = joinPointer(path, "properties");
+    for (const key of Object.keys(aProps)) {
+        if (Object.hasOwn(bProps, key)) {
+            diffNode(aProps[key], bProps[key], joinPointer(propsPath, key), ctx);
+            continue;
+        }
+        if (b["additionalProperties"] === false) {
+            note(ctx, joinPointer(propsPath, key), "properties", "breaking", `property "${key}" removed while additionalProperties is false, so values carrying it are now rejected`);
+        }
+        else {
+            note(ctx, joinPointer(propsPath, key), "properties", "compatible", `property "${key}" is no longer described, but is still allowed`);
+        }
+    }
+    for (const key of Object.keys(bProps)) {
+        if (Object.hasOwn(aProps, key))
+            continue;
+        const required = bRequired.includes(key);
+        note(ctx, joinPointer(propsPath, key), "properties", required ? "breaking" : "compatible", required ? `property "${key}" added and required` : `optional property "${key}" added`);
+    }
+    // --- additionalProperties
+    if (!deepEqual(a["additionalProperties"], b["additionalProperties"])) {
+        const apPath = joinPointer(path, "additionalProperties");
+        if (b["additionalProperties"] === false) {
+            note(ctx, apPath, "additionalProperties", "breaking", "extra properties are now rejected");
+        }
+        else if (a["additionalProperties"] === false) {
+            note(ctx, apPath, "additionalProperties", "compatible", "extra properties are now allowed");
+        }
+        else if (isPlainObject(a["additionalProperties"]) &&
+            isPlainObject(b["additionalProperties"])) {
+            diffNode(a["additionalProperties"], b["additionalProperties"], apPath, ctx);
+        }
+        else {
+            note(ctx, apPath, "additionalProperties", "unknown", "the additionalProperties schema changed shape");
+        }
+    }
+    // --- items
+    const aItems = a["items"];
+    const bItems = b["items"];
+    if (!deepEqual(aItems, bItems)) {
+        const itemsPath = joinPointer(path, "items");
+        if (Array.isArray(aItems) || Array.isArray(bItems)) {
+            note(ctx, itemsPath, "items", "unknown", "tuple-form items changed — positions are not analyzed");
+        }
+        else if (aItems === undefined) {
+            note(ctx, itemsPath, "items", "breaking", "items added where any element was allowed");
+        }
+        else if (bItems === undefined) {
+            note(ctx, itemsPath, "items", "compatible", "items removed — any element is now allowed");
+        }
+        else {
+            diffNode(aItems, bItems, itemsPath, ctx);
+        }
+    }
+    // --- everything compositional
+    for (const keyword of COMPOSITIONAL) {
+        if (deepEqual(a[keyword], b[keyword]))
+            continue;
+        note(ctx, joinPointer(path, keyword), keyword, "unknown", `${keyword} changed — this diff does not reason about composed schemas`);
+    }
+    // --- anything left. `patternProperties`, `contains`, `propertyNames`,
+    // `dependencies` and friends are not modelled here, and a change to one of
+    // them can absolutely reject a value that used to pass. Reporting them as
+    // undecidable is the only honest answer; staying silent would let the
+    // verdict read "compatible".
+    for (const keyword of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
+        if (MODELLED.has(keyword) || ANNOTATIONS.has(keyword))
+            continue;
+        if (deepEqual(a[keyword], b[keyword]))
+            continue;
+        note(ctx, joinPointer(path, keyword), keyword, "unknown", `${keyword} changed — this diff does not model that keyword, so whether a reader survives it is undecided here`);
+    }
+}
+/**
+ * Diff two schemas and classify each change. See the module comment for what
+ * "compatible" means here and for the cases deliberately left `unknown`.
+ */
+export function diffSchemas(before, after) {
+    const ctx = { changes: [] };
+    diffNode(before, after, "", ctx);
+    const counts = {
+        compatible: ctx.changes.filter((c) => c.compat === "compatible").length,
+        breaking: ctx.changes.filter((c) => c.compat === "breaking").length,
+        unknown: ctx.changes.filter((c) => c.compat === "unknown").length,
+    };
+    const verdict = counts.breaking > 0 ? "breaking" : counts.unknown > 0 ? "unknown" : "compatible";
+    return {
+        // Structural identity, not "nothing was found": two schemas differing
+        // only in a `description` produce no changes, and saying they are
+        // identical would be a different claim from the one made here.
+        identical: deepEqual(before, after),
+        verdict,
+        backwardCompatible: verdict === "compatible",
+        changes: ctx.changes,
+        counts,
+    };
+}

package/dist/lib/suggest.d.ts

@@ -0,0 +1,25 @@
+/**
+ * "Did you mean" for a failed enum check.
+ *
+ * A gate that says `"complet" is not allowed` costs someone a minute; one
+ * that says `did you mean "completed"?` costs them nothing. That is the whole
+ * purpose of this file — it never changes a verdict, only the message.
+ */
+/**
+ * Optimal string alignment distance: Levenshtein plus a transposition of two
+ * adjacent characters as a single edit, so `opne` is one edit from `open`
+ * rather than two. That matters here because transposition is the most common
+ * typo and the one a plain Levenshtein threshold misses.
+ *
+ * Counted in UTF-16 units, so an astral character counts as two. It is the
+ * *restricted* variant: a substring is not edited twice, which is why this is
+ * called optimal string alignment rather than Damerau-Levenshtein.
+ */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * The closest candidate to `value`, or `null` when nothing is close enough.
+ * "Close enough" is an edit distance within a third of the longer string,
+ * which catches a typo or a case difference and rejects an unrelated word.
+ * Ties go to the earliest candidate, so the result is stable.
+ */
+export declare function closestMatch(value: string, candidates: string[]): string | null;

package/dist/lib/suggest.js

@@ -0,0 +1,65 @@
+/**
+ * "Did you mean" for a failed enum check.
+ *
+ * A gate that says `"complet" is not allowed` costs someone a minute; one
+ * that says `did you mean "completed"?` costs them nothing. That is the whole
+ * purpose of this file — it never changes a verdict, only the message.
+ */
+/**
+ * Optimal string alignment distance: Levenshtein plus a transposition of two
+ * adjacent characters as a single edit, so `opne` is one edit from `open`
+ * rather than two. That matters here because transposition is the most common
+ * typo and the one a plain Levenshtein threshold misses.
+ *
+ * Counted in UTF-16 units, so an astral character counts as two. It is the
+ * *restricted* variant: a substring is not edited twice, which is why this is
+ * called optimal string alignment rather than Damerau-Levenshtein.
+ */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Three rows: two back, one back, and the one being filled.
+    let twoBack = new Array(b.length + 1).fill(0);
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let current = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        current[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let best = Math.min(previous[j - 1] + cost, previous[j] + 1, current[j - 1] + 1);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                best = Math.min(best, twoBack[j - 2] + 1);
+            }
+            current[j] = best;
+        }
+        twoBack = previous;
+        previous = current;
+        current = new Array(b.length + 1).fill(0);
+    }
+    return previous[b.length];
+}
+/**
+ * The closest candidate to `value`, or `null` when nothing is close enough.
+ * "Close enough" is an edit distance within a third of the longer string,
+ * which catches a typo or a case difference and rejects an unrelated word.
+ * Ties go to the earliest candidate, so the result is stable.
+ */
+export function closestMatch(value, candidates) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = editDistance(value.toLowerCase(), candidate.toLowerCase());
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    if (best === null)
+        return null;
+    const tolerance = Math.max(1, Math.floor(Math.max(value.length, best.length) / 3));
+    return bestDistance <= tolerance ? best : null;
+}

package/dist/lib/summarize.d.ts

@@ -0,0 +1,28 @@
+export type FieldRow = {
+    /** Dotted path, with `[]` marking an array level: `order.items[].sku`. */
+    path: string;
+    type: string;
+    required: boolean;
+    /** Everything that narrows the value, in one phrase; empty when unconstrained. */
+    constraints: string;
+    description: string;
+};
+export type SummarizeResult = {
+    title: string;
+    rootType: string;
+    rows: FieldRow[];
+    truncated: boolean;
+};
+/**
+ * Flatten `schema` into one row per field. The root itself gets no row; its
+ * type is reported separately, because "the document is an object" is not a
+ * field.
+ */
+export declare function summarizeSchema(schema: unknown, options?: {
+    maxRows?: number;
+    maxDepth?: number;
+}): SummarizeResult;
+/** Render the field list as a GitHub-flavoured markdown table. */
+export declare function renderFieldTable(rows: FieldRow[]): string;
+/** Every local definition a schema declares, for a caller listing its parts. */
+export declare function listDefinitions(schema: unknown): string[];

package/dist/lib/summarize.js

@@ -0,0 +1,212 @@
+/**
+ * Flattening a schema into the table a person actually wants: one row per
+ * field, with its path, its type, whether it is required, and its
+ * constraints in a single readable phrase.
+ *
+ * A schema is a tree of nested objects; a field list is flat. Turning one
+ * into the other is mechanical, and doing it deterministically here means a
+ * harness can put a schema in front of a model — or a reviewer — without
+ * spending a model call on the formatting.
+ *
+ * Local `$ref` is followed. A recursive reference is reported once and not
+ * expanded, since a recursive type has no finite field list.
+ */
+import { isPlainObject, joinPointer, parsePointer, preview, resolveSegments, typeOf, } from "./value";
+const DEFAULTS = { maxRows: 300, maxDepth: 8 };
+function describeType(schema) {
+    const declared = schema["type"];
+    if (typeof declared === "string")
+        return declared;
+    if (Array.isArray(declared))
+        return declared.filter((t) => typeof t === "string").join("|");
+    if (Array.isArray(schema["enum"]))
+        return "enum";
+    if (Object.hasOwn(schema, "const"))
+        return "const";
+    for (const keyword of ["anyOf", "oneOf", "allOf"]) {
+        if (Array.isArray(schema[keyword]))
+            return keyword;
+    }
+    return "any";
+}
+function describeConstraints(schema) {
+    const parts = [];
+    if (Array.isArray(schema["enum"]))
+        parts.push(`one of ${preview(schema["enum"], 80)}`);
+    if (Object.hasOwn(schema, "const"))
+        parts.push(`const ${preview(schema["const"], 40)}`);
+    if (typeof schema["format"] === "string")
+        parts.push(`format ${schema["format"]}`);
+    if (typeof schema["pattern"] === "string")
+        parts.push(`matches /${schema["pattern"]}/`);
+    for (const [keyword, label] of [
+        ["minimum", ">="],
+        ["maximum", "<="],
+        ["exclusiveMinimum", ">"],
+        ["exclusiveMaximum", "<"],
+    ]) {
+        if (typeof schema[keyword] === "number")
+            parts.push(`${label} ${String(schema[keyword])}`);
+    }
+    if (typeof schema["multipleOf"] === "number")
+        parts.push(`multiple of ${schema["multipleOf"]}`);
+    for (const keyword of ["minLength", "maxLength", "minItems", "maxItems"]) {
+        if (typeof schema[keyword] === "number")
+            parts.push(`${keyword} ${String(schema[keyword])}`);
+    }
+    if (schema["uniqueItems"] === true)
+        parts.push("unique items");
+    if (schema["additionalProperties"] === false)
+        parts.push("no extra properties");
+    if (Object.hasOwn(schema, "default"))
+        parts.push(`default ${preview(schema["default"], 40)}`);
+    return parts.join(", ");
+}
+/** Follow a local `$ref` once. Returns null when it cannot be resolved here. */
+function deref(schema, ctx) {
+    const ref = schema["$ref"];
+    if (typeof ref !== "string" || !ref.startsWith("#"))
+        return null;
+    try {
+        const found = resolveSegments(ctx.root, parsePointer(ref));
+        return found.found && isPlainObject(found.value) ? found.value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function push(ctx, row) {
+    if (ctx.rows.length >= ctx.maxRows) {
+        ctx.truncated = true;
+        return false;
+    }
+    ctx.rows.push(row);
+    return true;
+}
+function walk(schema, path, required, depth, seenRefs, ctx) {
+    if (ctx.truncated)
+        return;
+    if (typeof schema === "boolean") {
+        push(ctx, {
+            path,
+            type: schema ? "any" : "never",
+            required,
+            constraints: schema ? "" : "accepts no value",
+            description: "",
+        });
+        return;
+    }
+    if (!isPlainObject(schema)) {
+        push(ctx, {
+            path,
+            type: typeOf(schema),
+            required,
+            constraints: "not a schema",
+            description: "",
+        });
+        return;
+    }
+    const ref = typeof schema["$ref"] === "string" ? schema["$ref"] : null;
+    if (ref !== null) {
+        if (seenRefs.includes(ref)) {
+            push(ctx, { path, type: `${ref} (recursive)`, required, constraints: "", description: "" });
+            return;
+        }
+        const target = deref(schema, ctx);
+        if (target === null) {
+            push(ctx, { path, type: ref, required, constraints: "unresolved $ref", description: "" });
+            return;
+        }
+        walk(target, path, required, depth, [...seenRefs, ref], ctx);
+        return;
+    }
+    const description = typeof schema["description"] === "string" ? schema["description"] : "";
+    if (path !== "") {
+        if (!push(ctx, {
+            path,
+            type: describeType(schema),
+            required,
+            constraints: describeConstraints(schema),
+            description,
+        })) {
+            return;
+        }
+    }
+    if (depth >= ctx.maxDepth)
+        return;
+    const properties = schema["properties"];
+    if (isPlainObject(properties)) {
+        const requiredNames = Array.isArray(schema["required"])
+            ? schema["required"].filter((k) => typeof k === "string")
+            : [];
+        for (const key of Object.keys(properties)) {
+            const childPath = path === "" ? key : `${path}.${key}`;
+            walk(properties[key], childPath, requiredNames.includes(key), depth + 1, seenRefs, ctx);
+        }
+    }
+    const items = schema["items"];
+    if (Array.isArray(items)) {
+        items.forEach((item, index) => {
+            walk(item, `${path}[${index}]`, required, depth + 1, seenRefs, ctx);
+        });
+    }
+    else if (items !== undefined) {
+        walk(items, `${path}[]`, required, depth + 1, seenRefs, ctx);
+    }
+}
+/**
+ * Flatten `schema` into one row per field. The root itself gets no row; its
+ * type is reported separately, because "the document is an object" is not a
+ * field.
+ */
+export function summarizeSchema(schema, options = {}) {
+    const ctx = {
+        root: schema,
+        rows: [],
+        maxRows: options.maxRows ?? DEFAULTS.maxRows,
+        maxDepth: options.maxDepth ?? DEFAULTS.maxDepth,
+        truncated: false,
+    };
+    walk(schema, "", false, 0, [], ctx);
+    const rootObject = isPlainObject(schema) ? schema : {};
+    return {
+        title: typeof rootObject["title"] === "string" ? rootObject["title"] : "",
+        rootType: isPlainObject(schema)
+            ? describeType(rootObject)
+            : typeof schema === "boolean"
+                ? "any"
+                : "unknown",
+        rows: ctx.rows,
+        truncated: ctx.truncated,
+    };
+}
+/** Render the field list as a GitHub-flavoured markdown table. */
+export function renderFieldTable(rows) {
+    const header = ["Field", "Type", "Required", "Constraints", "Description"];
+    const cell = (text) => text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+    const body = rows.map((row) => [
+        cell(row.path),
+        cell(row.type),
+        row.required ? "yes" : "",
+        cell(row.constraints),
+        cell(row.description),
+    ]);
+    const widths = header.map((cell, i) => Math.max(cell.length, ...body.map((line) => (line[i] ?? "").length)));
+    const line = (cells) => `| ${cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join(" | ")} |`;
+    const divider = `| ${widths.map((w) => "-".repeat(Math.max(3, w))).join(" | ")} |`;
+    return [line(header), divider, ...body.map(line)].join("\n");
+}
+/** Every local definition a schema declares, for a caller listing its parts. */
+export function listDefinitions(schema) {
+    if (!isPlainObject(schema))
+        return [];
+    const out = [];
+    for (const container of ["$defs", "definitions"]) {
+        const defs = schema[container];
+        if (!isPlainObject(defs))
+            continue;
+        for (const name of Object.keys(defs))
+            out.push(joinPointer(joinPointer("", container), name));
+    }
+    return out.sort();
+}