@webpieces/docs-site 0.0.1

package/src/spec/JsonNode.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonEntry = exports.JsonNode = void 0;
+/**
+ * A READER over one JSON value, and the reason this package can render a document it did not
+ * generate.
+ *
+ * The alternative — importing `@webpieces/openapi-generator`'s document classes, which are
+ * structurally identical — would make "generated by us" a precondition for "renderable by us"
+ * (issue #985). So the document is read STRUCTURALLY: every accessor asks "is there a string at this
+ * key", never "is this an instance of our class", and a key that is absent or the wrong shape comes
+ * back `undefined` instead of throwing. A conforming document written by any other tool reads the
+ * same way.
+ *
+ * It is deliberately total rather than validating. A docs site that refuses to render because one
+ * optional `description` was a number is worse than one that renders the rest: the reader loses a
+ * whole reference over a field they were not looking at.
+ */
+class JsonNode {
+    raw;
+    // webpieces-disable no-any-unknown -- the document is FOREIGN input; narrowing it is this class's whole job
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /** True when this node is a JSON object (and not an array, and not null). */
+    isObject() {
+        return typeof this.raw === 'object' && this.raw !== null && !Array.isArray(this.raw);
+    }
+    /** The keys of this object, in document order. Empty for anything that is not an object. */
+    keys() {
+        if (!this.isObject()) {
+            return [];
+        }
+        return Object.keys(this.raw);
+    }
+    /** The child at `key`, always a node — an absent key reads as a node over `undefined`. */
+    at(key) {
+        if (!this.isObject()) {
+            return new JsonNode(undefined);
+        }
+        return new JsonNode(this.raw[key]);
+    }
+    /** The string at `key`, or `undefined` when it is absent or is not a string. */
+    text(key) {
+        const value = this.at(key).raw;
+        return typeof value === 'string' ? value : undefined;
+    }
+    /** This node itself as a string, or `undefined`. */
+    asText() {
+        return typeof this.raw === 'string' ? this.raw : undefined;
+    }
+    /** The boolean at `key`, or `undefined`. A missing flag is not `false`; the caller decides. */
+    flag(key) {
+        const value = this.at(key).raw;
+        return typeof value === 'boolean' ? value : undefined;
+    }
+    /** The number at `key`, or `undefined`. */
+    number(key) {
+        const value = this.at(key).raw;
+        return typeof value === 'number' ? value : undefined;
+    }
+    /** The array at `key` as nodes. Empty when absent or not an array. */
+    list(key) {
+        return this.at(key).asList();
+    }
+    /** This node itself as an array of nodes. Empty when it is not an array. */
+    asList() {
+        if (!Array.isArray(this.raw)) {
+            return [];
+        }
+        return this.raw.map((entry) => new JsonNode(entry));
+    }
+    /** Every own entry of this object as `[key, node]`, in document order. */
+    entries() {
+        return this.keys().map((key) => new JsonEntry(key, this.at(key)));
+    }
+    /** True when this node holds nothing at all — an absent key, or an explicit `null`. */
+    isAbsent() {
+        return this.raw === undefined || this.raw === null;
+    }
+}
+exports.JsonNode = JsonNode;
+/** One `[key, value]` pair of a JSON object, as a class because it is data. */
+class JsonEntry {
+    key;
+    value;
+    constructor(key, value) {
+        this.key = key;
+        this.value = value;
+    }
+}
+exports.JsonEntry = JsonEntry;
+//# sourceMappingURL=JsonNode.js.map

package/src/spec/JsonNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonNode.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/JsonNode.ts"],"names":[],"mappings":"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","sourcesContent":["/** Everything an OpenAPI document can hold. It is JSON, so this is the whole value space. */\nexport type JsonValue = string | number | boolean | null | JsonValue[] | JsonMap;\n\n/** The object case of {@link JsonValue}, named so the recursive alias can refer to it. */\nexport type JsonMap = { [key: string]: JsonValue };\n\n/**\n * A READER over one JSON value, and the reason this package can render a document it did not\n * generate.\n *\n * The alternative — importing `@webpieces/openapi-generator`'s document classes, which are\n * structurally identical — would make \"generated by us\" a precondition for \"renderable by us\"\n * (issue #985). So the document is read STRUCTURALLY: every accessor asks \"is there a string at this\n * key\", never \"is this an instance of our class\", and a key that is absent or the wrong shape comes\n * back `undefined` instead of throwing. A conforming document written by any other tool reads the\n * same way.\n *\n * It is deliberately total rather than validating. A docs site that refuses to render because one\n * optional `description` was a number is worse than one that renders the rest: the reader loses a\n * whole reference over a field they were not looking at.\n */\nexport class JsonNode {\n    // webpieces-disable no-any-unknown -- the document is FOREIGN input; narrowing it is this class's whole job\n    constructor(readonly raw: unknown) {}\n\n    /** True when this node is a JSON object (and not an array, and not null). */\n    isObject(): boolean {\n        return typeof this.raw === 'object' && this.raw !== null && !Array.isArray(this.raw);\n    }\n\n    /** The keys of this object, in document order. Empty for anything that is not an object. */\n    keys(): readonly string[] {\n        if (!this.isObject()) {\n            return [];\n        }\n        return Object.keys(this.raw as JsonMap);\n    }\n\n    /** The child at `key`, always a node — an absent key reads as a node over `undefined`. */\n    at(key: string): JsonNode {\n        if (!this.isObject()) {\n            return new JsonNode(undefined);\n        }\n        return new JsonNode((this.raw as JsonMap)[key]);\n    }\n\n    /** The string at `key`, or `undefined` when it is absent or is not a string. */\n    text(key: string): string | undefined {\n        const value = this.at(key).raw;\n        return typeof value === 'string' ? value : undefined;\n    }\n\n    /** This node itself as a string, or `undefined`. */\n    asText(): string | undefined {\n        return typeof this.raw === 'string' ? this.raw : undefined;\n    }\n\n    /** The boolean at `key`, or `undefined`. A missing flag is not `false`; the caller decides. */\n    flag(key: string): boolean | undefined {\n        const value = this.at(key).raw;\n        return typeof value === 'boolean' ? value : undefined;\n    }\n\n    /** The number at `key`, or `undefined`. */\n    number(key: string): number | undefined {\n        const value = this.at(key).raw;\n        return typeof value === 'number' ? value : undefined;\n    }\n\n    /** The array at `key` as nodes. Empty when absent or not an array. */\n    list(key: string): readonly JsonNode[] {\n        return this.at(key).asList();\n    }\n\n    /** This node itself as an array of nodes. Empty when it is not an array. */\n    asList(): readonly JsonNode[] {\n        if (!Array.isArray(this.raw)) {\n            return [];\n        }\n        return (this.raw as JsonValue[]).map((entry: JsonValue): JsonNode => new JsonNode(entry));\n    }\n\n    /** Every own entry of this object as `[key, node]`, in document order. */\n    entries(): readonly JsonEntry[] {\n        return this.keys().map((key: string): JsonEntry => new JsonEntry(key, this.at(key)));\n    }\n\n    /** True when this node holds nothing at all — an absent key, or an explicit `null`. */\n    isAbsent(): boolean {\n        return this.raw === undefined || this.raw === null;\n    }\n}\n\n/** One `[key, value]` pair of a JSON object, as a class because it is data. */\nexport class JsonEntry {\n    constructor(\n        readonly key: string,\n        readonly value: JsonNode,\n    ) {}\n}\n"]}

package/src/spec/SchemaLens.d.ts

@@ -0,0 +1,57 @@
+import { ApiSpec, NamedSchema } from './ApiSpec';
+import { JsonNode } from './JsonNode';
+import { SchemaShape } from './SchemaShape';
+/** What a `$ref` (in any of its three spellings) points at, plus whether the site said it may be null. */
+export declare class RefTarget {
+    readonly name: string;
+    readonly nullable: boolean;
+    constructor(name: string, nullable: boolean);
+}
+/**
+ * Everything "what does this schema node SAY" — reference reading and the type label.
+ *
+ * ## A reference arrives in three shapes, and reading only `$ref` drops two
+ *
+ * | shape | written by |
+ * |---|---|
+ * | `{ "$ref": "…", "description": "…" }` | OpenAPI 3.1, where prose beside a `$ref` is legal |
+ * | `{ "anyOf": [{ "$ref": "…" }, { "type": "null" }] }` | OpenAPI 3.1's nullable reference |
+ * | `{ "allOf": [{ "$ref": "…" }], "description": "…" }` | OpenAPI 3.0, whose `$ref` siblings are ignored |
+ *
+ * All three render, because this package renders any conforming document and the third one is what
+ * every 3.0 generator in the world emits. Reading only the first would silently drop a field's whole
+ * type on a 3.0 document — the field would render with no type at all, which a reader reads as "we
+ * forgot to document it".
+ */
+export declare class SchemaLens {
+    private readonly spec;
+    private readonly shape;
+    constructor(spec: ApiSpec);
+    /** What a node says about itself, with no catalog needed — see {@link SchemaShape}. */
+    shapeOf(): SchemaShape;
+    /** The reference this node makes, in whichever of the three shapes it was written. */
+    refTargetOf(node: JsonNode): RefTarget | undefined;
+    /**
+     * The schema a node ultimately describes: the reference target when it is one, else the node.
+     * An UNDEFINED `$ref` resolves to the node itself, so a dangling pointer renders inline as
+     * whatever it says rather than becoming a dead link.
+     */
+    resolve(node: JsonNode): JsonNode;
+    /** The named schema a node refers to, when the document actually defines it. */
+    named(node: JsonNode): NamedSchema | undefined;
+    /** The prose for a field: what the USE SITE says, falling back to what the TYPE says. */
+    describe(node: JsonNode): string;
+    /**
+     * The type label a reader sees. `format` renders inside angle brackets — `string<date-time>` —
+     * so the format is visibly a refinement of the type rather than a second type.
+     */
+    label(node: JsonNode): string;
+    private labelOfInline;
+    /** The `oneOf` branches of a node, resolved through a `$ref` if it is one. Empty when it is not a union. */
+    branchesOf(node: JsonNode): readonly JsonNode[];
+    /** The complete `Possible values:` list, from the node or from the type it refers to. */
+    enumValuesOf(node: JsonNode): readonly string[];
+    private stringsIn;
+    private singleRefIn;
+    private nameOfPointer;
+}

package/src/spec/SchemaLens.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaLens = exports.RefTarget = void 0;
+const SchemaShape_1 = require("./SchemaShape");
+/** What a `$ref` (in any of its three spellings) points at, plus whether the site said it may be null. */
+class RefTarget {
+    name;
+    nullable;
+    constructor(name, nullable) {
+        this.name = name;
+        this.nullable = nullable;
+    }
+}
+exports.RefTarget = RefTarget;
+const SCHEMA_POINTER = '#/components/schemas/';
+/**
+ * Everything "what does this schema node SAY" — reference reading and the type label.
+ *
+ * ## A reference arrives in three shapes, and reading only `$ref` drops two
+ *
+ * | shape | written by |
+ * |---|---|
+ * | `{ "$ref": "…", "description": "…" }` | OpenAPI 3.1, where prose beside a `$ref` is legal |
+ * | `{ "anyOf": [{ "$ref": "…" }, { "type": "null" }] }` | OpenAPI 3.1's nullable reference |
+ * | `{ "allOf": [{ "$ref": "…" }], "description": "…" }` | OpenAPI 3.0, whose `$ref` siblings are ignored |
+ *
+ * All three render, because this package renders any conforming document and the third one is what
+ * every 3.0 generator in the world emits. Reading only the first would silently drop a field's whole
+ * type on a 3.0 document — the field would render with no type at all, which a reader reads as "we
+ * forgot to document it".
+ */
+class SchemaLens {
+    spec;
+    shape = new SchemaShape_1.SchemaShape();
+    constructor(spec) {
+        this.spec = spec;
+    }
+    /** What a node says about itself, with no catalog needed — see {@link SchemaShape}. */
+    shapeOf() {
+        return this.shape;
+    }
+    /** The reference this node makes, in whichever of the three shapes it was written. */
+    refTargetOf(node) {
+        const direct = this.nameOfPointer(node.text('$ref'));
+        if (direct !== undefined) {
+            return new RefTarget(direct, this.shape.isNullable(node));
+        }
+        const wrapped = this.singleRefIn(node.list('allOf'));
+        if (wrapped !== undefined) {
+            return new RefTarget(wrapped, this.shape.isNullable(node));
+        }
+        const nullable = this.singleRefIn(node.list('anyOf'));
+        if (nullable !== undefined) {
+            return new RefTarget(nullable, true);
+        }
+        return undefined;
+    }
+    /**
+     * The schema a node ultimately describes: the reference target when it is one, else the node.
+     * An UNDEFINED `$ref` resolves to the node itself, so a dangling pointer renders inline as
+     * whatever it says rather than becoming a dead link.
+     */
+    resolve(node) {
+        const target = this.refTargetOf(node);
+        if (target === undefined) {
+            return node;
+        }
+        const named = this.spec.schemaNamed(target.name);
+        return named === undefined ? node : named.node;
+    }
+    /** The named schema a node refers to, when the document actually defines it. */
+    named(node) {
+        const target = this.refTargetOf(node);
+        if (target === undefined) {
+            return undefined;
+        }
+        return this.spec.schemaNamed(target.name);
+    }
+    /** The prose for a field: what the USE SITE says, falling back to what the TYPE says. */
+    describe(node) {
+        const own = node.text('description');
+        if (own !== undefined && own !== '') {
+            return own;
+        }
+        const named = this.named(node);
+        return named === undefined ? '' : (named.node.text('description') ?? '');
+    }
+    /**
+     * The type label a reader sees. `format` renders inside angle brackets — `string<date-time>` —
+     * so the format is visibly a refinement of the type rather than a second type.
+     */
+    label(node) {
+        const named = this.named(node);
+        if (named !== undefined) {
+            return named.name;
+        }
+        const target = this.refTargetOf(node);
+        if (target !== undefined) {
+            return target.name;
+        }
+        return this.labelOfInline(node);
+    }
+    labelOfInline(node) {
+        const declared = this.shape.declaredType(node);
+        if (declared === 'array') {
+            return `array<${this.label(node.at('items'))}>`;
+        }
+        if (declared === 'object' && node.at('additionalProperties').isObject()) {
+            return `map<string, ${this.label(node.at('additionalProperties'))}>`;
+        }
+        const branches = this.branchesOf(node);
+        if (branches.length > 0) {
+            return branches.map((branch) => this.label(branch)).join(' | ');
+        }
+        const format = node.text('format');
+        if (declared !== undefined && format !== undefined) {
+            return `${declared}<${format}>`;
+        }
+        return declared ?? 'object';
+    }
+    /** The `oneOf` branches of a node, resolved through a `$ref` if it is one. Empty when it is not a union. */
+    branchesOf(node) {
+        const resolved = this.resolve(node);
+        const branches = resolved.list('oneOf');
+        return branches.length > 0 ? branches : [];
+    }
+    /** The complete `Possible values:` list, from the node or from the type it refers to. */
+    enumValuesOf(node) {
+        const own = this.stringsIn(node.list('enum'));
+        if (own.length > 0) {
+            return own;
+        }
+        return this.stringsIn(this.resolve(node).list('enum'));
+    }
+    stringsIn(nodes) {
+        const values = [];
+        for (const entry of nodes) {
+            const raw = entry.raw;
+            if (typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean') {
+                values.push(String(raw));
+            }
+        }
+        return values;
+    }
+    singleRefIn(branches) {
+        for (const branch of branches) {
+            const name = this.nameOfPointer(branch.text('$ref'));
+            if (name !== undefined) {
+                return name;
+            }
+        }
+        return undefined;
+    }
+    nameOfPointer(pointer) {
+        if (pointer === undefined || !pointer.startsWith(SCHEMA_POINTER)) {
+            return undefined;
+        }
+        return pointer.slice(SCHEMA_POINTER.length);
+    }
+}
+exports.SchemaLens = SchemaLens;
+//# sourceMappingURL=SchemaLens.js.map

package/src/spec/SchemaLens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaLens.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/SchemaLens.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiSpec, NamedSchema } from './ApiSpec';\nimport { JsonNode } from './JsonNode';\nimport { SchemaShape } from './SchemaShape';\n\n/** What a `$ref` (in any of its three spellings) points at, plus whether the site said it may be null. */\nexport class RefTarget {\n    constructor(\n        readonly name: string,\n        readonly nullable: boolean,\n    ) {}\n}\n\nconst SCHEMA_POINTER = '#/components/schemas/';\n\n/**\n * Everything \"what does this schema node SAY\" — reference reading and the type label.\n *\n * ## A reference arrives in three shapes, and reading only `$ref` drops two\n *\n * | shape | written by |\n * |---|---|\n * | `{ \"$ref\": \"…\", \"description\": \"…\" }` | OpenAPI 3.1, where prose beside a `$ref` is legal |\n * | `{ \"anyOf\": [{ \"$ref\": \"…\" }, { \"type\": \"null\" }] }` | OpenAPI 3.1's nullable reference |\n * | `{ \"allOf\": [{ \"$ref\": \"…\" }], \"description\": \"…\" }` | OpenAPI 3.0, whose `$ref` siblings are ignored |\n *\n * All three render, because this package renders any conforming document and the third one is what\n * every 3.0 generator in the world emits. Reading only the first would silently drop a field's whole\n * type on a 3.0 document — the field would render with no type at all, which a reader reads as \"we\n * forgot to document it\".\n */\nexport class SchemaLens {\n    private readonly shape = new SchemaShape();\n\n    constructor(private readonly spec: ApiSpec) {}\n\n    /** What a node says about itself, with no catalog needed — see {@link SchemaShape}. */\n    shapeOf(): SchemaShape {\n        return this.shape;\n    }\n\n    /** The reference this node makes, in whichever of the three shapes it was written. */\n    refTargetOf(node: JsonNode): RefTarget | undefined {\n        const direct = this.nameOfPointer(node.text('$ref'));\n        if (direct !== undefined) {\n            return new RefTarget(direct, this.shape.isNullable(node));\n        }\n        const wrapped = this.singleRefIn(node.list('allOf'));\n        if (wrapped !== undefined) {\n            return new RefTarget(wrapped, this.shape.isNullable(node));\n        }\n        const nullable = this.singleRefIn(node.list('anyOf'));\n        if (nullable !== undefined) {\n            return new RefTarget(nullable, true);\n        }\n        return undefined;\n    }\n\n    /**\n     * The schema a node ultimately describes: the reference target when it is one, else the node.\n     * An UNDEFINED `$ref` resolves to the node itself, so a dangling pointer renders inline as\n     * whatever it says rather than becoming a dead link.\n     */\n    resolve(node: JsonNode): JsonNode {\n        const target = this.refTargetOf(node);\n        if (target === undefined) {\n            return node;\n        }\n        const named = this.spec.schemaNamed(target.name);\n        return named === undefined ? node : named.node;\n    }\n\n    /** The named schema a node refers to, when the document actually defines it. */\n    named(node: JsonNode): NamedSchema | undefined {\n        const target = this.refTargetOf(node);\n        if (target === undefined) {\n            return undefined;\n        }\n        return this.spec.schemaNamed(target.name);\n    }\n\n    /** The prose for a field: what the USE SITE says, falling back to what the TYPE says. */\n    describe(node: JsonNode): string {\n        const own = node.text('description');\n        if (own !== undefined && own !== '') {\n            return own;\n        }\n        const named = this.named(node);\n        return named === undefined ? '' : (named.node.text('description') ?? '');\n    }\n\n    /**\n     * The type label a reader sees. `format` renders inside angle brackets — `string<date-time>` —\n     * so the format is visibly a refinement of the type rather than a second type.\n     */\n    label(node: JsonNode): string {\n        const named = this.named(node);\n        if (named !== undefined) {\n            return named.name;\n        }\n        const target = this.refTargetOf(node);\n        if (target !== undefined) {\n            return target.name;\n        }\n        return this.labelOfInline(node);\n    }\n\n    private labelOfInline(node: JsonNode): string {\n        const declared = this.shape.declaredType(node);\n        if (declared === 'array') {\n            return `array<${this.label(node.at('items'))}>`;\n        }\n        if (declared === 'object' && node.at('additionalProperties').isObject()) {\n            return `map<string, ${this.label(node.at('additionalProperties'))}>`;\n        }\n        const branches = this.branchesOf(node);\n        if (branches.length > 0) {\n            return branches.map((branch: JsonNode): string => this.label(branch)).join(' | ');\n        }\n        const format = node.text('format');\n        if (declared !== undefined && format !== undefined) {\n            return `${declared}<${format}>`;\n        }\n        return declared ?? 'object';\n    }\n\n    /** The `oneOf` branches of a node, resolved through a `$ref` if it is one. Empty when it is not a union. */\n    branchesOf(node: JsonNode): readonly JsonNode[] {\n        const resolved = this.resolve(node);\n        const branches = resolved.list('oneOf');\n        return branches.length > 0 ? branches : [];\n    }\n\n    /** The complete `Possible values:` list, from the node or from the type it refers to. */\n    enumValuesOf(node: JsonNode): readonly string[] {\n        const own = this.stringsIn(node.list('enum'));\n        if (own.length > 0) {\n            return own;\n        }\n        return this.stringsIn(this.resolve(node).list('enum'));\n    }\n\n    private stringsIn(nodes: readonly JsonNode[]): readonly string[] {\n        const values: string[] = [];\n        for (const entry of nodes) {\n            const raw = entry.raw;\n            if (typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean') {\n                values.push(String(raw));\n            }\n        }\n        return values;\n    }\n\n    private singleRefIn(branches: readonly JsonNode[]): string | undefined {\n        for (const branch of branches) {\n            const name = this.nameOfPointer(branch.text('$ref'));\n            if (name !== undefined) {\n                return name;\n            }\n        }\n        return undefined;\n    }\n\n    private nameOfPointer(pointer: string | undefined): string | undefined {\n        if (pointer === undefined || !pointer.startsWith(SCHEMA_POINTER)) {\n            return undefined;\n        }\n        return pointer.slice(SCHEMA_POINTER.length);\n    }\n}\n"]}

package/src/spec/SchemaShape.d.ts

@@ -0,0 +1,22 @@
+import { JsonNode } from './JsonNode';
+/**
+ * What a schema node says about ITSELF, with no catalog of named schemas needed to answer.
+ *
+ * It is separate from `SchemaLens` because `SpecReader` has to answer "does this named schema
+ * deserve a page" while it is still BUILDING the list of named schemas — there is no `ApiSpec` to
+ * hand a lens yet. Folding these three questions into the lens would mean constructing a lens over a
+ * half-built spec, which is the kind of ordering dependency that works until somebody reorders two
+ * lines.
+ */
+export declare class SchemaShape {
+    /** True when a NAMED schema deserves its own page: objects and object unions, never scalars. */
+    hasOwnPage(node: JsonNode): boolean;
+    /**
+     * The declared `type`, with 3.1's `type: [T, "null"]` reduced to `T`. A nullable field's type
+     * column shows the NON-null type: "it is a string, and it may be absent" is one fact about the
+     * field, not two types.
+     */
+    declaredType(node: JsonNode): string | undefined;
+    /** True when the node states, in either dialect, that null is allowed. */
+    isNullable(node: JsonNode): boolean;
+}

package/src/spec/SchemaShape.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaShape = void 0;
+/**
+ * What a schema node says about ITSELF, with no catalog of named schemas needed to answer.
+ *
+ * It is separate from `SchemaLens` because `SpecReader` has to answer "does this named schema
+ * deserve a page" while it is still BUILDING the list of named schemas — there is no `ApiSpec` to
+ * hand a lens yet. Folding these three questions into the lens would mean constructing a lens over a
+ * half-built spec, which is the kind of ordering dependency that works until somebody reorders two
+ * lines.
+ */
+class SchemaShape {
+    /** True when a NAMED schema deserves its own page: objects and object unions, never scalars. */
+    hasOwnPage(node) {
+        if (node.at('properties').isObject()) {
+            return true;
+        }
+        if (node.at('oneOf').asList().length > 0 || node.at('allOf').asList().length > 0) {
+            return true;
+        }
+        return this.declaredType(node) === 'object';
+    }
+    /**
+     * The declared `type`, with 3.1's `type: [T, "null"]` reduced to `T`. A nullable field's type
+     * column shows the NON-null type: "it is a string, and it may be absent" is one fact about the
+     * field, not two types.
+     */
+    declaredType(node) {
+        const direct = node.text('type');
+        if (direct !== undefined) {
+            return direct;
+        }
+        for (const entry of node.list('type')) {
+            const name = entry.asText();
+            if (name !== undefined && name !== 'null') {
+                return name;
+            }
+        }
+        return undefined;
+    }
+    /** True when the node states, in either dialect, that null is allowed. */
+    isNullable(node) {
+        if (node.flag('nullable') === true) {
+            return true;
+        }
+        for (const entry of node.list('type')) {
+            if (entry.asText() === 'null') {
+                return true;
+            }
+        }
+        for (const branch of node.list('anyOf')) {
+            if (branch.text('type') === 'null') {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+exports.SchemaShape = SchemaShape;
+//# sourceMappingURL=SchemaShape.js.map

package/src/spec/SchemaShape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaShape.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/SchemaShape.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;GAQG;AACH,MAAa,WAAW;IACpB,gGAAgG;IAChG,UAAU,CAAC,IAAc;QACrB,IAAI,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/E,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,IAAc;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC5B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAC;YAChB,CAAC;QACL,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,0EAA0E;IAC1E,UAAU,CAAC,IAAc;QACrB,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;gBAC5B,OAAO,IAAI,CAAC;YAChB,CAAC;QACL,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;gBACjC,OAAO,IAAI,CAAC;YAChB,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ;AAhDD,kCAgDC","sourcesContent":["import { JsonNode } from './JsonNode';\n\n/**\n * What a schema node says about ITSELF, with no catalog of named schemas needed to answer.\n *\n * It is separate from `SchemaLens` because `SpecReader` has to answer \"does this named schema\n * deserve a page\" while it is still BUILDING the list of named schemas — there is no `ApiSpec` to\n * hand a lens yet. Folding these three questions into the lens would mean constructing a lens over a\n * half-built spec, which is the kind of ordering dependency that works until somebody reorders two\n * lines.\n */\nexport class SchemaShape {\n    /** True when a NAMED schema deserves its own page: objects and object unions, never scalars. */\n    hasOwnPage(node: JsonNode): boolean {\n        if (node.at('properties').isObject()) {\n            return true;\n        }\n        if (node.at('oneOf').asList().length > 0 || node.at('allOf').asList().length > 0) {\n            return true;\n        }\n        return this.declaredType(node) === 'object';\n    }\n\n    /**\n     * The declared `type`, with 3.1's `type: [T, \"null\"]` reduced to `T`. A nullable field's type\n     * column shows the NON-null type: \"it is a string, and it may be absent\" is one fact about the\n     * field, not two types.\n     */\n    declaredType(node: JsonNode): string | undefined {\n        const direct = node.text('type');\n        if (direct !== undefined) {\n            return direct;\n        }\n        for (const entry of node.list('type')) {\n            const name = entry.asText();\n            if (name !== undefined && name !== 'null') {\n                return name;\n            }\n        }\n        return undefined;\n    }\n\n    /** True when the node states, in either dialect, that null is allowed. */\n    isNullable(node: JsonNode): boolean {\n        if (node.flag('nullable') === true) {\n            return true;\n        }\n        for (const entry of node.list('type')) {\n            if (entry.asText() === 'null') {\n                return true;\n            }\n        }\n        for (const branch of node.list('anyOf')) {\n            if (branch.text('type') === 'null') {\n                return true;\n            }\n        }\n        return false;\n    }\n}\n"]}

package/src/spec/Slug.d.ts

@@ -0,0 +1,16 @@
+/**
+ * URL slugs. One pre-rendered HTML file per URL means the slug IS the filename, so it has to be
+ * stable, lower-case and free of anything a filesystem or a static host treats specially.
+ *
+ * Uniqueness is enforced rather than hoped for: two operations that kebab to the same string would
+ * otherwise silently overwrite each other's page, and the missing one looks exactly like an
+ * operation that was never documented. Uniqueness is per INSTANCE, so operations and schemas —
+ * which live in different directories — do not collide with each other for no reason.
+ */
+export declare class Slug {
+    private readonly taken;
+    /** `fetchOrders` -> `fetch-orders`, `order.state-changed` -> `order-state-changed`. */
+    kebab(name: string): string;
+    /** The kebab of `name`, suffixed `-2`, `-3`, … if this instance has already handed it out. */
+    unique(name: string): string;
+}

package/src/spec/Slug.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Slug = void 0;
+/**
+ * URL slugs. One pre-rendered HTML file per URL means the slug IS the filename, so it has to be
+ * stable, lower-case and free of anything a filesystem or a static host treats specially.
+ *
+ * Uniqueness is enforced rather than hoped for: two operations that kebab to the same string would
+ * otherwise silently overwrite each other's page, and the missing one looks exactly like an
+ * operation that was never documented. Uniqueness is per INSTANCE, so operations and schemas —
+ * which live in different directories — do not collide with each other for no reason.
+ */
+class Slug {
+    taken = new Set();
+    /** `fetchOrders` -> `fetch-orders`, `order.state-changed` -> `order-state-changed`. */
+    kebab(name) {
+        const spaced = name
+            .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2');
+        const cleaned = spaced
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+        return cleaned === '' ? 'page' : cleaned;
+    }
+    /** The kebab of `name`, suffixed `-2`, `-3`, … if this instance has already handed it out. */
+    unique(name) {
+        const base = this.kebab(name);
+        if (!this.taken.has(base)) {
+            this.taken.add(base);
+            return base;
+        }
+        let counter = 2;
+        while (this.taken.has(`${base}-${counter}`)) {
+            counter++;
+        }
+        const chosen = `${base}-${counter}`;
+        this.taken.add(chosen);
+        return chosen;
+    }
+}
+exports.Slug = Slug;
+//# sourceMappingURL=Slug.js.map

package/src/spec/Slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Slug.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/Slug.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAa,IAAI;IACI,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAE3C,uFAAuF;IACvF,KAAK,CAAC,IAAY;QACd,MAAM,MAAM,GAAG,IAAI;aACd,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;aACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,OAAO,GAAG,MAAM;aACjB,WAAW,EAAE;aACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;aAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAC7B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7C,CAAC;IAED,8FAA8F;IAC9F,MAAM,CAAC,IAAY;QACf,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrB,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC,EAAE,CAAC;YAC1C,OAAO,EAAE,CAAC;QACd,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvB,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ;AA9BD,oBA8BC","sourcesContent":["/**\n * URL slugs. One pre-rendered HTML file per URL means the slug IS the filename, so it has to be\n * stable, lower-case and free of anything a filesystem or a static host treats specially.\n *\n * Uniqueness is enforced rather than hoped for: two operations that kebab to the same string would\n * otherwise silently overwrite each other's page, and the missing one looks exactly like an\n * operation that was never documented. Uniqueness is per INSTANCE, so operations and schemas —\n * which live in different directories — do not collide with each other for no reason.\n */\nexport class Slug {\n    private readonly taken = new Set<string>();\n\n    /** `fetchOrders` -> `fetch-orders`, `order.state-changed` -> `order-state-changed`. */\n    kebab(name: string): string {\n        const spaced = name\n            .replace(/([a-z0-9])([A-Z])/g, '$1-$2')\n            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2');\n        const cleaned = spaced\n            .toLowerCase()\n            .replace(/[^a-z0-9]+/g, '-')\n            .replace(/^-+|-+$/g, '');\n        return cleaned === '' ? 'page' : cleaned;\n    }\n\n    /** The kebab of `name`, suffixed `-2`, `-3`, … if this instance has already handed it out. */\n    unique(name: string): string {\n        const base = this.kebab(name);\n        if (!this.taken.has(base)) {\n            this.taken.add(base);\n            return base;\n        }\n        let counter = 2;\n        while (this.taken.has(`${base}-${counter}`)) {\n            counter++;\n        }\n        const chosen = `${base}-${counter}`;\n        this.taken.add(chosen);\n        return chosen;\n    }\n}\n"]}

package/src/spec/SpecLoader.d.ts

@@ -0,0 +1,26 @@
+import { JsonNode } from './JsonNode';
+/**
+ * Reads the OpenAPI document off disk.
+ *
+ * It accepts 3.0 and 3.1 alike, and beyond the version it validates NOTHING: this package renders
+ * any CONFORMING document, and a renderer that re-validates is a second opinion about the spec that
+ * some other tool's document will eventually fail for no reason a reader can act on.
+ *
+ * ## Why SWAGGER 2.0 is refused rather than attempted
+ *
+ * 2.0 is a different document: schemas live in `definitions`, not `components.schemas`, and there is
+ * no `webhooks` block. Reading one with this reader finds none of those keys and succeeds — writing
+ * a site with every operation's fields missing and no schema pages, which is indistinguishable from
+ * a contract nobody documented. So the version is checked for `3.`, and a 2.0 document is refused
+ * with the converter named. A wrong site is worse than no site, because only one of the two sends
+ * somebody looking for the bug.
+ */
+export declare class SpecLoader {
+    load(file: string): JsonNode;
+    /**
+     * A Swagger 2.0 document is named in the message, because "declares no openapi version" would
+     * send somebody looking for a missing key in a file that is simply a different format.
+     */
+    private wrongDocumentMessage;
+    private parse;
+}

package/src/spec/SpecLoader.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecLoader = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const DocsSiteError_1 = require("../DocsSiteError");
+const JsonNode_1 = require("./JsonNode");
+/**
+ * Reads the OpenAPI document off disk.
+ *
+ * It accepts 3.0 and 3.1 alike, and beyond the version it validates NOTHING: this package renders
+ * any CONFORMING document, and a renderer that re-validates is a second opinion about the spec that
+ * some other tool's document will eventually fail for no reason a reader can act on.
+ *
+ * ## Why SWAGGER 2.0 is refused rather than attempted
+ *
+ * 2.0 is a different document: schemas live in `definitions`, not `components.schemas`, and there is
+ * no `webhooks` block. Reading one with this reader finds none of those keys and succeeds — writing
+ * a site with every operation's fields missing and no schema pages, which is indistinguishable from
+ * a contract nobody documented. So the version is checked for `3.`, and a 2.0 document is refused
+ * with the converter named. A wrong site is worse than no site, because only one of the two sends
+ * somebody looking for the bug.
+ */
+class SpecLoader {
+    load(file) {
+        if (!fs.existsSync(file)) {
+            throw new DocsSiteError_1.DocsSiteError('no OpenAPI document there', file, 'Point --spec at a generated OpenAPI 3.0 or 3.1 JSON document.');
+        }
+        const root = new JsonNode_1.JsonNode(this.parse(file, fs.readFileSync(file, 'utf8')));
+        const version = root.text('openapi');
+        if (version === undefined) {
+            throw new DocsSiteError_1.DocsSiteError(this.wrongDocumentMessage(root), file, 'Point --spec at the OpenAPI document itself — for a webpieces app, one of the files wp-openapi wrote.');
+        }
+        if (!version.startsWith('3.')) {
+            throw new DocsSiteError_1.DocsSiteError(`this renders OpenAPI 3.0 and 3.1, and that document declares "${version}"`, file, 'Convert the document to 3.0 or 3.1 first — 3.x keeps its schemas under components.schemas, which is where this reads them.');
+        }
+        return root;
+    }
+    /**
+     * A Swagger 2.0 document is named in the message, because "declares no openapi version" would
+     * send somebody looking for a missing key in a file that is simply a different format.
+     */
+    wrongDocumentMessage(root) {
+        const swagger = root.text('swagger');
+        if (swagger !== undefined) {
+            return `that is a Swagger ${swagger} document, and this renders OpenAPI 3.0 and 3.1`;
+        }
+        return 'that JSON file declares no "openapi" version, so it is not an OpenAPI document';
+    }
+    // webpieces-disable no-any-unknown -- JSON.parse returns a foreign value; JsonNode is the narrowing
+    parse(file, source) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- re-thrown below as a stated failure
+        try {
+            return JSON.parse(source);
+            // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us
+        }
+        catch (err) {
+            //const error = toError(err);
+            throw new DocsSiteError_1.DocsSiteError(`the OpenAPI document is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, file, 'Regenerate the document, or fix the JSON syntax, and re-run.');
+        }
+    }
+}
+exports.SpecLoader = SpecLoader;
+//# sourceMappingURL=SpecLoader.js.map

package/src/spec/SpecLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecLoader.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/SpecLoader.ts"],"names":[],"mappings":";;;;AAAA,oDAA8B;AAC9B,oDAAiD;AACjD,yCAAsC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,MAAa,UAAU;IACnB,IAAI,CAAC,IAAY;QACb,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,6BAAa,CACnB,2BAA2B,EAC3B,IAAI,EACJ,+DAA+D,CAClE,CAAC;QACN,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,mBAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,6BAAa,CACnB,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAC/B,IAAI,EACJ,uGAAuG,CAC1G,CAAC;QACN,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,6BAAa,CACnB,iEAAiE,OAAO,GAAG,EAC3E,IAAI,EACJ,4HAA4H,CAC/H,CAAC;QACN,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,oBAAoB,CAAC,IAAc;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,qBAAqB,OAAO,iDAAiD,CAAC;QACzF,CAAC;QACD,OAAO,gFAAgF,CAAC;IAC5F,CAAC;IAED,oGAAoG;IAC5F,KAAK,CAAC,IAAY,EAAE,MAAc;QACtC,qGAAqG;QACrG,IAAI,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC1B,uFAAuF;QAC3F,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,6BAA6B;YAC7B,MAAM,IAAI,6BAAa,CACnB,2CAA2C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAC7F,IAAI,EACJ,8DAA8D,CACjE,CAAC;QACN,CAAC;IACL,CAAC;CACJ;AAvDD,gCAuDC","sourcesContent":["import * as fs from 'node:fs';\nimport { DocsSiteError } from '../DocsSiteError';\nimport { JsonNode } from './JsonNode';\n\n/**\n * Reads the OpenAPI document off disk.\n *\n * It accepts 3.0 and 3.1 alike, and beyond the version it validates NOTHING: this package renders\n * any CONFORMING document, and a renderer that re-validates is a second opinion about the spec that\n * some other tool's document will eventually fail for no reason a reader can act on.\n *\n * ## Why SWAGGER 2.0 is refused rather than attempted\n *\n * 2.0 is a different document: schemas live in `definitions`, not `components.schemas`, and there is\n * no `webhooks` block. Reading one with this reader finds none of those keys and succeeds — writing\n * a site with every operation's fields missing and no schema pages, which is indistinguishable from\n * a contract nobody documented. So the version is checked for `3.`, and a 2.0 document is refused\n * with the converter named. A wrong site is worse than no site, because only one of the two sends\n * somebody looking for the bug.\n */\nexport class SpecLoader {\n    load(file: string): JsonNode {\n        if (!fs.existsSync(file)) {\n            throw new DocsSiteError(\n                'no OpenAPI document there',\n                file,\n                'Point --spec at a generated OpenAPI 3.0 or 3.1 JSON document.',\n            );\n        }\n        const root = new JsonNode(this.parse(file, fs.readFileSync(file, 'utf8')));\n        const version = root.text('openapi');\n        if (version === undefined) {\n            throw new DocsSiteError(\n                this.wrongDocumentMessage(root),\n                file,\n                'Point --spec at the OpenAPI document itself — for a webpieces app, one of the files wp-openapi wrote.',\n            );\n        }\n        if (!version.startsWith('3.')) {\n            throw new DocsSiteError(\n                `this renders OpenAPI 3.0 and 3.1, and that document declares \"${version}\"`,\n                file,\n                'Convert the document to 3.0 or 3.1 first — 3.x keeps its schemas under components.schemas, which is where this reads them.',\n            );\n        }\n        return root;\n    }\n\n    /**\n     * A Swagger 2.0 document is named in the message, because \"declares no openapi version\" would\n     * send somebody looking for a missing key in a file that is simply a different format.\n     */\n    private wrongDocumentMessage(root: JsonNode): string {\n        const swagger = root.text('swagger');\n        if (swagger !== undefined) {\n            return `that is a Swagger ${swagger} document, and this renders OpenAPI 3.0 and 3.1`;\n        }\n        return 'that JSON file declares no \"openapi\" version, so it is not an OpenAPI document';\n    }\n\n    // webpieces-disable no-any-unknown -- JSON.parse returns a foreign value; JsonNode is the narrowing\n    private parse(file: string, source: string): unknown {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- re-thrown below as a stated failure\n        try {\n            return JSON.parse(source);\n            // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us\n        } catch (err: unknown) {\n            //const error = toError(err);\n            throw new DocsSiteError(\n                `the OpenAPI document is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,\n                file,\n                'Regenerate the document, or fix the JSON syntax, and re-run.',\n            );\n        }\n    }\n}\n"]}