@webpieces/docs-site 0.0.1

package/src/cli/WpDocsSiteMain.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WpDocsSiteMain = void 0;
+const DocsSiteCli_1 = require("./DocsSiteCli");
+const DevServer_1 = require("../serve/DevServer");
+const DocsSiteError_1 = require("../DocsSiteError");
+/**
+ * The body of the `wp-docs-site` bin: argument handling, the SINGLE top-level handler, and the exit
+ * code — with nothing that touches the process itself, so the suite runs the whole command.
+ *
+ * Everything below here THROWS {@link DocsSiteError} and prints nothing, so this is the only
+ * renderer of a failure and the only writer of an exit code (`.claude/review/error-output.md`). It
+ * renders from the error's FIELDS — the message, the location, the cure — rather than from a string
+ * somebody baked a cure into, so one audience's formatting never freezes into a thrower.
+ */
+class WpDocsSiteMain {
+    cli = new DocsSiteCli_1.DocsSiteCli();
+    /** @returns the process exit code. 0 on success, 1 on a stated failure. */
+    async run(argv, cwd, out) {
+        if (this.cli.wantsHelp(argv)) {
+            out.write(`${DocsSiteCli_1.USAGE}\n`);
+            return 0;
+        }
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the single top-level handler
+        try {
+            const result = this.cli.run(argv, cwd);
+            out.write(`wrote ${result.written.length} files to ${result.outDir}\n`);
+            await this.preview(result, out);
+            return 0;
+            // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us
+        }
+        catch (err) {
+            //const error = toError(err);
+            out.write(`${this.render(err)}\n`);
+            return 1;
+        }
+    }
+    /**
+     * `--serve` starts the localhost preview and RESOLVES when it is listening, rather than blocking
+     * forever. The bin keeps the process alive because the socket is open, and the suite can start
+     * one, read a page and stop it — a run method that never returned would be untestable.
+     */
+    async preview(result, out) {
+        if (!result.serve) {
+            return;
+        }
+        const server = new DevServer_1.DevServer(result.outDir);
+        await server.start(result.port);
+        out.write(`preview (not a host, loopback only) at ${server.url()}\n`);
+    }
+    // webpieces-disable no-any-unknown -- a caught value; this method is the audience-facing narrowing of it
+    render(err) {
+        if (!(err instanceof DocsSiteError_1.DocsSiteError)) {
+            return `wp-docs-site failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        return [`wp-docs-site refused: ${err.message}`, `  ${err.cure}`].join('\n');
+    }
+}
+exports.WpDocsSiteMain = WpDocsSiteMain;
+//# sourceMappingURL=WpDocsSiteMain.js.map

package/src/cli/WpDocsSiteMain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WpDocsSiteMain.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/cli/WpDocsSiteMain.ts"],"names":[],"mappings":";;;AAAA,+CAA8D;AAC9D,kDAA+C;AAC/C,oDAAiD;AAEjD;;;;;;;;GAQG;AACH,MAAa,cAAc;IACN,GAAG,GAAG,IAAI,yBAAW,EAAE,CAAC;IAEzC,2EAA2E;IAC3E,KAAK,CAAC,GAAG,CAAC,IAAuB,EAAE,GAAW,EAAE,GAA0B;QACtE,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,KAAK,CAAC,GAAG,mBAAK,IAAI,CAAC,CAAC;YACxB,OAAO,CAAC,CAAC;QACb,CAAC;QACD,sGAAsG;QACtG,IAAI,CAAC;YACD,MAAM,MAAM,GAAc,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAClD,GAAG,CAAC,KAAK,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;YACxE,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAChC,OAAO,CAAC,CAAC;YACT,uFAAuF;QAC3F,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,6BAA6B;YAC7B,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,CAAC,CAAC;QACb,CAAC;IACL,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,OAAO,CAAC,MAAiB,EAAE,GAA0B;QAC/D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO;QACX,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,qBAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,GAAG,CAAC,KAAK,CAAC,0CAA0C,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;IAED,yGAAyG;IACjG,MAAM,CAAC,GAAY;QACvB,IAAI,CAAC,CAAC,GAAG,YAAY,6BAAa,CAAC,EAAE,CAAC;YAClC,OAAO,wBAAwB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACtF,CAAC;QACD,OAAO,CAAC,yBAAyB,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;CACJ;AA5CD,wCA4CC","sourcesContent":["import { CliResult, DocsSiteCli, USAGE } from './DocsSiteCli';\nimport { DevServer } from '../serve/DevServer';\nimport { DocsSiteError } from '../DocsSiteError';\n\n/**\n * The body of the `wp-docs-site` bin: argument handling, the SINGLE top-level handler, and the exit\n * code — with nothing that touches the process itself, so the suite runs the whole command.\n *\n * Everything below here THROWS {@link DocsSiteError} and prints nothing, so this is the only\n * renderer of a failure and the only writer of an exit code (`.claude/review/error-output.md`). It\n * renders from the error's FIELDS — the message, the location, the cure — rather than from a string\n * somebody baked a cure into, so one audience's formatting never freezes into a thrower.\n */\nexport class WpDocsSiteMain {\n    private readonly cli = new DocsSiteCli();\n\n    /** @returns the process exit code. 0 on success, 1 on a stated failure. */\n    async run(argv: readonly string[], cwd: string, out: NodeJS.WritableStream): Promise<number> {\n        if (this.cli.wantsHelp(argv)) {\n            out.write(`${USAGE}\\n`);\n            return 0;\n        }\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the single top-level handler\n        try {\n            const result: CliResult = this.cli.run(argv, cwd);\n            out.write(`wrote ${result.written.length} files to ${result.outDir}\\n`);\n            await this.preview(result, out);\n            return 0;\n            // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us\n        } catch (err: unknown) {\n            //const error = toError(err);\n            out.write(`${this.render(err)}\\n`);\n            return 1;\n        }\n    }\n\n    /**\n     * `--serve` starts the localhost preview and RESOLVES when it is listening, rather than blocking\n     * forever. The bin keeps the process alive because the socket is open, and the suite can start\n     * one, read a page and stop it — a run method that never returned would be untestable.\n     */\n    private async preview(result: CliResult, out: NodeJS.WritableStream): Promise<void> {\n        if (!result.serve) {\n            return;\n        }\n        const server = new DevServer(result.outDir);\n        await server.start(result.port);\n        out.write(`preview (not a host, loopback only) at ${server.url()}\\n`);\n    }\n\n    // webpieces-disable no-any-unknown -- a caught value; this method is the audience-facing narrowing of it\n    private render(err: unknown): string {\n        if (!(err instanceof DocsSiteError)) {\n            return `wp-docs-site failed: ${err instanceof Error ? err.message : String(err)}`;\n        }\n        return [`wp-docs-site refused: ${err.message}`, `  ${err.cure}`].join('\\n');\n    }\n}\n"]}

package/src/cli/wp-docs-site.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/cli/wp-docs-site.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const WpDocsSiteMain_1 = require("./WpDocsSiteMain");
+/**
+ * The `wp-docs-site` bin. It is a few lines because everything it does lives in
+ * {@link WpDocsSiteMain}, which the suite runs exactly as a user does — a bin whose body is only
+ * reachable by spawning a process is a bin nothing tests.
+ *
+ * The bin is declared in `publishConfig.bin`, never at the top level
+ * (`.claude/rules/packaging-and-bins.md`): pnpm chmods every `bin` target while linking a package
+ * from its SOURCE directory, where `src/` holds only `.ts` until tsc runs, so a top-level `bin`
+ * makes every `pnpm install` print an ENOENT warning. `scripts/publish-packages.sh` hoists it into
+ * the PUBLISHED manifest, and fails the release if it ever goes missing.
+ */
+// webpieces-disable no-process-exit-outside-main -- this IS main; WpDocsSiteMain never touches the process
+void new WpDocsSiteMain_1.WpDocsSiteMain()
+    .run(process.argv.slice(2), process.cwd(), process.stdout)
+    .then((code) => {
+    process.exitCode = code;
+});
+//# sourceMappingURL=wp-docs-site.js.map

package/src/cli/wp-docs-site.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wp-docs-site.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/cli/wp-docs-site.ts"],"names":[],"mappings":";;;AACA,qDAAkD;AAElD;;;;;;;;;;GAUG;AACH,2GAA2G;AAC3G,KAAK,IAAI,+BAAc,EAAE;KACpB,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC;KACzD,IAAI,CAAC,CAAC,IAAY,EAAQ,EAAE;IACzB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC5B,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { WpDocsSiteMain } from './WpDocsSiteMain';\n\n/**\n * The `wp-docs-site` bin. It is a few lines because everything it does lives in\n * {@link WpDocsSiteMain}, which the suite runs exactly as a user does — a bin whose body is only\n * reachable by spawning a process is a bin nothing tests.\n *\n * The bin is declared in `publishConfig.bin`, never at the top level\n * (`.claude/rules/packaging-and-bins.md`): pnpm chmods every `bin` target while linking a package\n * from its SOURCE directory, where `src/` holds only `.ts` until tsc runs, so a top-level `bin`\n * makes every `pnpm install` print an ENOENT warning. `scripts/publish-packages.sh` hoists it into\n * the PUBLISHED manifest, and fails the release if it ever goes missing.\n */\n// webpieces-disable no-process-exit-outside-main -- this IS main; WpDocsSiteMain never touches the process\nvoid new WpDocsSiteMain()\n    .run(process.argv.slice(2), process.cwd(), process.stdout)\n    .then((code: number): void => {\n        process.exitCode = code;\n    });\n"]}

package/src/emit/SiteWriter.d.ts

@@ -0,0 +1,13 @@
+import { RenderedSite } from '../render/SitePage';
+/**
+ * Writes a {@link RenderedSite} to a directory.
+ *
+ * The directory is created if it is not there, and files are overwritten in place. Nothing is
+ * DELETED: a renderer that cleans its output directory is one mistyped `--out` away from removing
+ * somebody's source tree, and the cost of the alternative is a stale page nobody links to.
+ */
+export declare class SiteWriter {
+    /** @returns every absolute path written, in the order it was written. */
+    write(outDir: string, site: RenderedSite): readonly string[];
+    private writeOne;
+}

package/src/emit/SiteWriter.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SiteWriter = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+/**
+ * Writes a {@link RenderedSite} to a directory.
+ *
+ * The directory is created if it is not there, and files are overwritten in place. Nothing is
+ * DELETED: a renderer that cleans its output directory is one mistyped `--out` away from removing
+ * somebody's source tree, and the cost of the alternative is a stale page nobody links to.
+ */
+class SiteWriter {
+    /** @returns every absolute path written, in the order it was written. */
+    write(outDir, site) {
+        const written = [];
+        for (const page of site.pages) {
+            written.push(this.writeOne(outDir, page.url, page.html));
+        }
+        for (const asset of site.assets) {
+            written.push(this.writeOne(outDir, asset.url, asset.contents));
+        }
+        return written;
+    }
+    writeOne(outDir, url, contents) {
+        const file = path.join(outDir, ...url.split('/'));
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, contents, 'utf8');
+        return file;
+    }
+}
+exports.SiteWriter = SiteWriter;
+//# sourceMappingURL=SiteWriter.js.map

package/src/emit/SiteWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SiteWriter.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/emit/SiteWriter.ts"],"names":[],"mappings":";;;;AAAA,oDAA8B;AAC9B,wDAAkC;AAGlC;;;;;;GAMG;AACH,MAAa,UAAU;IACnB,yEAAyE;IACzE,KAAK,CAAC,MAAc,EAAE,IAAkB;QACpC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAEO,QAAQ,CAAC,MAAc,EAAE,GAAW,EAAE,QAAgB;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ;AAnBD,gCAmBC","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { RenderedSite } from '../render/SitePage';\n\n/**\n * Writes a {@link RenderedSite} to a directory.\n *\n * The directory is created if it is not there, and files are overwritten in place. Nothing is\n * DELETED: a renderer that cleans its output directory is one mistyped `--out` away from removing\n * somebody's source tree, and the cost of the alternative is a stale page nobody links to.\n */\nexport class SiteWriter {\n    /** @returns every absolute path written, in the order it was written. */\n    write(outDir: string, site: RenderedSite): readonly string[] {\n        const written: string[] = [];\n        for (const page of site.pages) {\n            written.push(this.writeOne(outDir, page.url, page.html));\n        }\n        for (const asset of site.assets) {\n            written.push(this.writeOne(outDir, asset.url, asset.contents));\n        }\n        return written;\n    }\n\n    private writeOne(outDir: string, url: string, contents: string): string {\n        const file = path.join(outDir, ...url.split('/'));\n        fs.mkdirSync(path.dirname(file), { recursive: true });\n        fs.writeFileSync(file, contents, 'utf8');\n        return file;\n    }\n}\n"]}

package/src/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@webpieces/docs-site` — a static, three-pane API reference site from any OpenAPI 3.0-or-3.1
+ * document plus a directory of markdown prose.
+ *
+ * **Node builtins only.** No framework, no markdown library, no bundler, so adding docs to an
+ * upstream project never grows that project's dependency surface and this package's own build stays
+ * `tsc`. It also does NOT depend on `@webpieces/openapi-generator`, deliberately: the document is
+ * read structurally, so "generated by us" is not a precondition for "renderable by us".
+ *
+ * It ships the `wp-docs-site` bin.
+ */
+export { DocsSiteError } from './DocsSiteError';
+export { JsonEntry, JsonNode } from './spec/JsonNode';
+export type { JsonMap, JsonValue } from './spec/JsonNode';
+export { ApiSpec, NamedSchema, OperationInfo, ResponseInfo, SecuritySchemeInfo, ServerInfo, TagSection, } from './spec/ApiSpec';
+export { RefTarget, SchemaLens } from './spec/SchemaLens';
+export { SchemaShape } from './spec/SchemaShape';
+export { Slug } from './spec/Slug';
+export { SpecLoader } from './spec/SpecLoader';
+export { SpecReader, UNTAGGED_SECTION } from './spec/SpecReader';
+export { FieldNode, FieldTreeBuilder, SchemaVariant } from './spec/FieldTree';
+export { ExampleBuilder } from './spec/ExampleBuilder';
+export { DocsManifest, ProsePage, ProsePageEntry } from './manifest/DocsManifest';
+export { MANIFEST_FILE, ProseLoader } from './manifest/ProseLoader';
+export { Markdown } from './markdown/Markdown';
+export { CodeSample, CodeSampleBuilder, SampleHeader } from './samples/CodeSamples';
+export { Html } from './render/Html';
+export { GUIDES_GROUP, NavBuilder, NavGroup, NavLink, NavModel, SCHEMAS_GROUP, } from './render/NavModel';
+export { SiteUrls } from './render/SiteUrls';
+export { Layout } from './render/Layout';
+export { COLLAPSE_ALL_LABEL, CardRenderer, REQUEST_LABEL } from './render/CardRenderer';
+export { FieldTreeRenderer, POSSIBLE_VALUES } from './render/FieldTreeRenderer';
+export { OperationPageRenderer, WEBHOOK_BADGE } from './render/OperationPageRenderer';
+export { RenderedSite, SiteAsset, SitePage } from './render/SitePage';
+export { OVERVIEW_TITLE, SiteRenderer } from './render/SiteRenderer';
+export { SiteStyles } from './assets/SiteStyles';
+export { SiteScript } from './assets/SiteScript';
+export { SiteWriter } from './emit/SiteWriter';
+export { DevServer, LOOPBACK } from './serve/DevServer';
+export { CliResult, DocsSiteCli, USAGE } from './cli/DocsSiteCli';
+export { WpDocsSiteMain } from './cli/WpDocsSiteMain';

package/src/index.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERVIEW_TITLE = exports.SitePage = exports.SiteAsset = exports.RenderedSite = exports.WEBHOOK_BADGE = exports.OperationPageRenderer = exports.POSSIBLE_VALUES = exports.FieldTreeRenderer = exports.REQUEST_LABEL = exports.CardRenderer = exports.COLLAPSE_ALL_LABEL = exports.Layout = exports.SiteUrls = exports.SCHEMAS_GROUP = exports.NavModel = exports.NavLink = exports.NavGroup = exports.NavBuilder = exports.GUIDES_GROUP = exports.Html = exports.SampleHeader = exports.CodeSampleBuilder = exports.CodeSample = exports.Markdown = exports.ProseLoader = exports.MANIFEST_FILE = exports.ProsePageEntry = exports.ProsePage = exports.DocsManifest = exports.ExampleBuilder = exports.SchemaVariant = exports.FieldTreeBuilder = exports.FieldNode = exports.UNTAGGED_SECTION = exports.SpecReader = exports.SpecLoader = exports.Slug = exports.SchemaShape = exports.SchemaLens = exports.RefTarget = exports.TagSection = exports.ServerInfo = exports.SecuritySchemeInfo = exports.ResponseInfo = exports.OperationInfo = exports.NamedSchema = exports.ApiSpec = exports.JsonNode = exports.JsonEntry = exports.DocsSiteError = void 0;
+exports.WpDocsSiteMain = exports.USAGE = exports.DocsSiteCli = exports.CliResult = exports.LOOPBACK = exports.DevServer = exports.SiteWriter = exports.SiteScript = exports.SiteStyles = exports.SiteRenderer = void 0;
+/**
+ * `@webpieces/docs-site` — a static, three-pane API reference site from any OpenAPI 3.0-or-3.1
+ * document plus a directory of markdown prose.
+ *
+ * **Node builtins only.** No framework, no markdown library, no bundler, so adding docs to an
+ * upstream project never grows that project's dependency surface and this package's own build stays
+ * `tsc`. It also does NOT depend on `@webpieces/openapi-generator`, deliberately: the document is
+ * read structurally, so "generated by us" is not a precondition for "renderable by us".
+ *
+ * It ships the `wp-docs-site` bin.
+ */
+var DocsSiteError_1 = require("./DocsSiteError");
+Object.defineProperty(exports, "DocsSiteError", { enumerable: true, get: function () { return DocsSiteError_1.DocsSiteError; } });
+var JsonNode_1 = require("./spec/JsonNode");
+Object.defineProperty(exports, "JsonEntry", { enumerable: true, get: function () { return JsonNode_1.JsonEntry; } });
+Object.defineProperty(exports, "JsonNode", { enumerable: true, get: function () { return JsonNode_1.JsonNode; } });
+var ApiSpec_1 = require("./spec/ApiSpec");
+Object.defineProperty(exports, "ApiSpec", { enumerable: true, get: function () { return ApiSpec_1.ApiSpec; } });
+Object.defineProperty(exports, "NamedSchema", { enumerable: true, get: function () { return ApiSpec_1.NamedSchema; } });
+Object.defineProperty(exports, "OperationInfo", { enumerable: true, get: function () { return ApiSpec_1.OperationInfo; } });
+Object.defineProperty(exports, "ResponseInfo", { enumerable: true, get: function () { return ApiSpec_1.ResponseInfo; } });
+Object.defineProperty(exports, "SecuritySchemeInfo", { enumerable: true, get: function () { return ApiSpec_1.SecuritySchemeInfo; } });
+Object.defineProperty(exports, "ServerInfo", { enumerable: true, get: function () { return ApiSpec_1.ServerInfo; } });
+Object.defineProperty(exports, "TagSection", { enumerable: true, get: function () { return ApiSpec_1.TagSection; } });
+var SchemaLens_1 = require("./spec/SchemaLens");
+Object.defineProperty(exports, "RefTarget", { enumerable: true, get: function () { return SchemaLens_1.RefTarget; } });
+Object.defineProperty(exports, "SchemaLens", { enumerable: true, get: function () { return SchemaLens_1.SchemaLens; } });
+var SchemaShape_1 = require("./spec/SchemaShape");
+Object.defineProperty(exports, "SchemaShape", { enumerable: true, get: function () { return SchemaShape_1.SchemaShape; } });
+var Slug_1 = require("./spec/Slug");
+Object.defineProperty(exports, "Slug", { enumerable: true, get: function () { return Slug_1.Slug; } });
+var SpecLoader_1 = require("./spec/SpecLoader");
+Object.defineProperty(exports, "SpecLoader", { enumerable: true, get: function () { return SpecLoader_1.SpecLoader; } });
+var SpecReader_1 = require("./spec/SpecReader");
+Object.defineProperty(exports, "SpecReader", { enumerable: true, get: function () { return SpecReader_1.SpecReader; } });
+Object.defineProperty(exports, "UNTAGGED_SECTION", { enumerable: true, get: function () { return SpecReader_1.UNTAGGED_SECTION; } });
+var FieldTree_1 = require("./spec/FieldTree");
+Object.defineProperty(exports, "FieldNode", { enumerable: true, get: function () { return FieldTree_1.FieldNode; } });
+Object.defineProperty(exports, "FieldTreeBuilder", { enumerable: true, get: function () { return FieldTree_1.FieldTreeBuilder; } });
+Object.defineProperty(exports, "SchemaVariant", { enumerable: true, get: function () { return FieldTree_1.SchemaVariant; } });
+var ExampleBuilder_1 = require("./spec/ExampleBuilder");
+Object.defineProperty(exports, "ExampleBuilder", { enumerable: true, get: function () { return ExampleBuilder_1.ExampleBuilder; } });
+var DocsManifest_1 = require("./manifest/DocsManifest");
+Object.defineProperty(exports, "DocsManifest", { enumerable: true, get: function () { return DocsManifest_1.DocsManifest; } });
+Object.defineProperty(exports, "ProsePage", { enumerable: true, get: function () { return DocsManifest_1.ProsePage; } });
+Object.defineProperty(exports, "ProsePageEntry", { enumerable: true, get: function () { return DocsManifest_1.ProsePageEntry; } });
+var ProseLoader_1 = require("./manifest/ProseLoader");
+Object.defineProperty(exports, "MANIFEST_FILE", { enumerable: true, get: function () { return ProseLoader_1.MANIFEST_FILE; } });
+Object.defineProperty(exports, "ProseLoader", { enumerable: true, get: function () { return ProseLoader_1.ProseLoader; } });
+var Markdown_1 = require("./markdown/Markdown");
+Object.defineProperty(exports, "Markdown", { enumerable: true, get: function () { return Markdown_1.Markdown; } });
+var CodeSamples_1 = require("./samples/CodeSamples");
+Object.defineProperty(exports, "CodeSample", { enumerable: true, get: function () { return CodeSamples_1.CodeSample; } });
+Object.defineProperty(exports, "CodeSampleBuilder", { enumerable: true, get: function () { return CodeSamples_1.CodeSampleBuilder; } });
+Object.defineProperty(exports, "SampleHeader", { enumerable: true, get: function () { return CodeSamples_1.SampleHeader; } });
+var Html_1 = require("./render/Html");
+Object.defineProperty(exports, "Html", { enumerable: true, get: function () { return Html_1.Html; } });
+var NavModel_1 = require("./render/NavModel");
+Object.defineProperty(exports, "GUIDES_GROUP", { enumerable: true, get: function () { return NavModel_1.GUIDES_GROUP; } });
+Object.defineProperty(exports, "NavBuilder", { enumerable: true, get: function () { return NavModel_1.NavBuilder; } });
+Object.defineProperty(exports, "NavGroup", { enumerable: true, get: function () { return NavModel_1.NavGroup; } });
+Object.defineProperty(exports, "NavLink", { enumerable: true, get: function () { return NavModel_1.NavLink; } });
+Object.defineProperty(exports, "NavModel", { enumerable: true, get: function () { return NavModel_1.NavModel; } });
+Object.defineProperty(exports, "SCHEMAS_GROUP", { enumerable: true, get: function () { return NavModel_1.SCHEMAS_GROUP; } });
+var SiteUrls_1 = require("./render/SiteUrls");
+Object.defineProperty(exports, "SiteUrls", { enumerable: true, get: function () { return SiteUrls_1.SiteUrls; } });
+var Layout_1 = require("./render/Layout");
+Object.defineProperty(exports, "Layout", { enumerable: true, get: function () { return Layout_1.Layout; } });
+var CardRenderer_1 = require("./render/CardRenderer");
+Object.defineProperty(exports, "COLLAPSE_ALL_LABEL", { enumerable: true, get: function () { return CardRenderer_1.COLLAPSE_ALL_LABEL; } });
+Object.defineProperty(exports, "CardRenderer", { enumerable: true, get: function () { return CardRenderer_1.CardRenderer; } });
+Object.defineProperty(exports, "REQUEST_LABEL", { enumerable: true, get: function () { return CardRenderer_1.REQUEST_LABEL; } });
+var FieldTreeRenderer_1 = require("./render/FieldTreeRenderer");
+Object.defineProperty(exports, "FieldTreeRenderer", { enumerable: true, get: function () { return FieldTreeRenderer_1.FieldTreeRenderer; } });
+Object.defineProperty(exports, "POSSIBLE_VALUES", { enumerable: true, get: function () { return FieldTreeRenderer_1.POSSIBLE_VALUES; } });
+var OperationPageRenderer_1 = require("./render/OperationPageRenderer");
+Object.defineProperty(exports, "OperationPageRenderer", { enumerable: true, get: function () { return OperationPageRenderer_1.OperationPageRenderer; } });
+Object.defineProperty(exports, "WEBHOOK_BADGE", { enumerable: true, get: function () { return OperationPageRenderer_1.WEBHOOK_BADGE; } });
+var SitePage_1 = require("./render/SitePage");
+Object.defineProperty(exports, "RenderedSite", { enumerable: true, get: function () { return SitePage_1.RenderedSite; } });
+Object.defineProperty(exports, "SiteAsset", { enumerable: true, get: function () { return SitePage_1.SiteAsset; } });
+Object.defineProperty(exports, "SitePage", { enumerable: true, get: function () { return SitePage_1.SitePage; } });
+var SiteRenderer_1 = require("./render/SiteRenderer");
+Object.defineProperty(exports, "OVERVIEW_TITLE", { enumerable: true, get: function () { return SiteRenderer_1.OVERVIEW_TITLE; } });
+Object.defineProperty(exports, "SiteRenderer", { enumerable: true, get: function () { return SiteRenderer_1.SiteRenderer; } });
+var SiteStyles_1 = require("./assets/SiteStyles");
+Object.defineProperty(exports, "SiteStyles", { enumerable: true, get: function () { return SiteStyles_1.SiteStyles; } });
+var SiteScript_1 = require("./assets/SiteScript");
+Object.defineProperty(exports, "SiteScript", { enumerable: true, get: function () { return SiteScript_1.SiteScript; } });
+var SiteWriter_1 = require("./emit/SiteWriter");
+Object.defineProperty(exports, "SiteWriter", { enumerable: true, get: function () { return SiteWriter_1.SiteWriter; } });
+var DevServer_1 = require("./serve/DevServer");
+Object.defineProperty(exports, "DevServer", { enumerable: true, get: function () { return DevServer_1.DevServer; } });
+Object.defineProperty(exports, "LOOPBACK", { enumerable: true, get: function () { return DevServer_1.LOOPBACK; } });
+var DocsSiteCli_1 = require("./cli/DocsSiteCli");
+Object.defineProperty(exports, "CliResult", { enumerable: true, get: function () { return DocsSiteCli_1.CliResult; } });
+Object.defineProperty(exports, "DocsSiteCli", { enumerable: true, get: function () { return DocsSiteCli_1.DocsSiteCli; } });
+Object.defineProperty(exports, "USAGE", { enumerable: true, get: function () { return DocsSiteCli_1.USAGE; } });
+var WpDocsSiteMain_1 = require("./cli/WpDocsSiteMain");
+Object.defineProperty(exports, "WpDocsSiteMain", { enumerable: true, get: function () { return WpDocsSiteMain_1.WpDocsSiteMain; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/docs/docs-site/src/index.ts"],"names":[],"mappings":";;;;AAAA;;;;;;;;;;GAUG;AACH,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AACtB,4CAAsD;AAA7C,qGAAA,SAAS,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAE5B,0CAQwB;AAPpB,kGAAA,OAAO,OAAA;AACP,sGAAA,WAAW,OAAA;AACX,wGAAA,aAAa,OAAA;AACb,uGAAA,YAAY,OAAA;AACZ,6GAAA,kBAAkB,OAAA;AAClB,qGAAA,UAAU,OAAA;AACV,qGAAA,UAAU,OAAA;AAEd,gDAA0D;AAAjD,uGAAA,SAAS,OAAA;AAAE,wGAAA,UAAU,OAAA;AAC9B,kDAAiD;AAAxC,0GAAA,WAAW,OAAA;AACpB,oCAAmC;AAA1B,4FAAA,IAAI,OAAA;AACb,gDAA+C;AAAtC,wGAAA,UAAU,OAAA;AACnB,gDAAiE;AAAxD,wGAAA,UAAU,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AACrC,8CAA8E;AAArE,sGAAA,SAAS,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAAE,0GAAA,aAAa,OAAA;AACnD,wDAAuD;AAA9C,gHAAA,cAAc,OAAA;AACvB,wDAAkF;AAAzE,4GAAA,YAAY,OAAA;AAAE,yGAAA,SAAS,OAAA;AAAE,8GAAA,cAAc,OAAA;AAChD,sDAAoE;AAA3D,4GAAA,aAAa,OAAA;AAAE,0GAAA,WAAW,OAAA;AACnC,gDAA+C;AAAtC,oGAAA,QAAQ,OAAA;AACjB,qDAAoF;AAA3E,yGAAA,UAAU,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,2GAAA,YAAY,OAAA;AACpD,sCAAqC;AAA5B,4FAAA,IAAI,OAAA;AACb,8CAO2B;AANvB,wGAAA,YAAY,OAAA;AACZ,sGAAA,UAAU,OAAA;AACV,oGAAA,QAAQ,OAAA;AACR,mGAAA,OAAO,OAAA;AACP,oGAAA,QAAQ,OAAA;AACR,yGAAA,aAAa,OAAA;AAEjB,8CAA6C;AAApC,oGAAA,QAAQ,OAAA;AACjB,0CAAyC;AAAhC,gGAAA,MAAM,OAAA;AACf,sDAAwF;AAA/E,kHAAA,kBAAkB,OAAA;AAAE,4GAAA,YAAY,OAAA;AAAE,6GAAA,aAAa,OAAA;AACxD,gEAAgF;AAAvE,sHAAA,iBAAiB,OAAA;AAAE,oHAAA,eAAe,OAAA;AAC3C,wEAAsF;AAA7E,8HAAA,qBAAqB,OAAA;AAAE,sHAAA,aAAa,OAAA;AAC7C,8CAAsE;AAA7D,wGAAA,YAAY,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAC1C,sDAAqE;AAA5D,8GAAA,cAAc,OAAA;AAAE,4GAAA,YAAY,OAAA;AACrC,kDAAiD;AAAxC,wGAAA,UAAU,OAAA;AACnB,kDAAiD;AAAxC,wGAAA,UAAU,OAAA;AACnB,gDAA+C;AAAtC,wGAAA,UAAU,OAAA;AACnB,+CAAwD;AAA/C,sGAAA,SAAS,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAC5B,iDAAkE;AAAzD,wGAAA,SAAS,OAAA;AAAE,0GAAA,WAAW,OAAA;AAAE,oGAAA,KAAK,OAAA;AACtC,uDAAsD;AAA7C,gHAAA,cAAc,OAAA","sourcesContent":["/**\n * `@webpieces/docs-site` — a static, three-pane API reference site from any OpenAPI 3.0-or-3.1\n * document plus a directory of markdown prose.\n *\n * **Node builtins only.** No framework, no markdown library, no bundler, so adding docs to an\n * upstream project never grows that project's dependency surface and this package's own build stays\n * `tsc`. It also does NOT depend on `@webpieces/openapi-generator`, deliberately: the document is\n * read structurally, so \"generated by us\" is not a precondition for \"renderable by us\".\n *\n * It ships the `wp-docs-site` bin.\n */\nexport { DocsSiteError } from './DocsSiteError';\nexport { JsonEntry, JsonNode } from './spec/JsonNode';\nexport type { JsonMap, JsonValue } from './spec/JsonNode';\nexport {\n    ApiSpec,\n    NamedSchema,\n    OperationInfo,\n    ResponseInfo,\n    SecuritySchemeInfo,\n    ServerInfo,\n    TagSection,\n} from './spec/ApiSpec';\nexport { RefTarget, SchemaLens } from './spec/SchemaLens';\nexport { SchemaShape } from './spec/SchemaShape';\nexport { Slug } from './spec/Slug';\nexport { SpecLoader } from './spec/SpecLoader';\nexport { SpecReader, UNTAGGED_SECTION } from './spec/SpecReader';\nexport { FieldNode, FieldTreeBuilder, SchemaVariant } from './spec/FieldTree';\nexport { ExampleBuilder } from './spec/ExampleBuilder';\nexport { DocsManifest, ProsePage, ProsePageEntry } from './manifest/DocsManifest';\nexport { MANIFEST_FILE, ProseLoader } from './manifest/ProseLoader';\nexport { Markdown } from './markdown/Markdown';\nexport { CodeSample, CodeSampleBuilder, SampleHeader } from './samples/CodeSamples';\nexport { Html } from './render/Html';\nexport {\n    GUIDES_GROUP,\n    NavBuilder,\n    NavGroup,\n    NavLink,\n    NavModel,\n    SCHEMAS_GROUP,\n} from './render/NavModel';\nexport { SiteUrls } from './render/SiteUrls';\nexport { Layout } from './render/Layout';\nexport { COLLAPSE_ALL_LABEL, CardRenderer, REQUEST_LABEL } from './render/CardRenderer';\nexport { FieldTreeRenderer, POSSIBLE_VALUES } from './render/FieldTreeRenderer';\nexport { OperationPageRenderer, WEBHOOK_BADGE } from './render/OperationPageRenderer';\nexport { RenderedSite, SiteAsset, SitePage } from './render/SitePage';\nexport { OVERVIEW_TITLE, SiteRenderer } from './render/SiteRenderer';\nexport { SiteStyles } from './assets/SiteStyles';\nexport { SiteScript } from './assets/SiteScript';\nexport { SiteWriter } from './emit/SiteWriter';\nexport { DevServer, LOOPBACK } from './serve/DevServer';\nexport { CliResult, DocsSiteCli, USAGE } from './cli/DocsSiteCli';\nexport { WpDocsSiteMain } from './cli/WpDocsSiteMain';\n"]}

package/src/manifest/DocsManifest.d.ts

@@ -0,0 +1,28 @@
+/** One prose page named by `docs.manifest.json`, in the order the manifest names it. */
+export declare class ProsePageEntry {
+    readonly file: string;
+    readonly title: string;
+    constructor(file: string, title: string);
+}
+/**
+ * `docs.manifest.json` — the ORDER of the prose pages, and nothing else.
+ *
+ * It exists for the same reason the OpenAPI document's `tags[]` does: the order is a teaching
+ * decision somebody made, and neither directory listing order nor alphabetical order is it.
+ * Alphabetising this array is not a cleanup — it reorders the pages a partner reads first.
+ */
+export declare class DocsManifest {
+    /** Overrides the document's `info.title` in the site header. Empty means "use the document's". */
+    readonly title: string;
+    readonly pages: readonly ProsePageEntry[];
+    constructor(
+    /** Overrides the document's `info.title` in the site header. Empty means "use the document's". */
+    title: string, pages: readonly ProsePageEntry[]);
+}
+/** One prose page, loaded: its heading, its URL segment and its markdown source. */
+export declare class ProsePage {
+    readonly title: string;
+    readonly slug: string;
+    readonly markdown: string;
+    constructor(title: string, slug: string, markdown: string);
+}

package/src/manifest/DocsManifest.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProsePage = exports.DocsManifest = exports.ProsePageEntry = void 0;
+/** One prose page named by `docs.manifest.json`, in the order the manifest names it. */
+class ProsePageEntry {
+    file;
+    title;
+    constructor(file, title) {
+        this.file = file;
+        this.title = title;
+    }
+}
+exports.ProsePageEntry = ProsePageEntry;
+/**
+ * `docs.manifest.json` — the ORDER of the prose pages, and nothing else.
+ *
+ * It exists for the same reason the OpenAPI document's `tags[]` does: the order is a teaching
+ * decision somebody made, and neither directory listing order nor alphabetical order is it.
+ * Alphabetising this array is not a cleanup — it reorders the pages a partner reads first.
+ */
+class DocsManifest {
+    title;
+    pages;
+    constructor(
+    /** Overrides the document's `info.title` in the site header. Empty means "use the document's". */
+    title, pages) {
+        this.title = title;
+        this.pages = pages;
+    }
+}
+exports.DocsManifest = DocsManifest;
+/** One prose page, loaded: its heading, its URL segment and its markdown source. */
+class ProsePage {
+    title;
+    slug;
+    markdown;
+    constructor(title, slug, markdown) {
+        this.title = title;
+        this.slug = slug;
+        this.markdown = markdown;
+    }
+}
+exports.ProsePage = ProsePage;
+//# sourceMappingURL=DocsManifest.js.map

package/src/manifest/DocsManifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsManifest.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/manifest/DocsManifest.ts"],"names":[],"mappings":";;;AAAA,wFAAwF;AACxF,MAAa,cAAc;IAEV;IACA;IAFb,YACa,IAAY,EACZ,KAAa;QADb,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;IACvB,CAAC;CACP;AALD,wCAKC;AAED;;;;;;GAMG;AACH,MAAa,YAAY;IAGR;IACA;IAHb;IACI,kGAAkG;IACzF,KAAa,EACb,KAAgC;QADhC,UAAK,GAAL,KAAK,CAAQ;QACb,UAAK,GAAL,KAAK,CAA2B;IAC1C,CAAC;CACP;AAND,oCAMC;AAED,oFAAoF;AACpF,MAAa,SAAS;IAEL;IACA;IACA;IAHb,YACa,KAAa,EACb,IAAY,EACZ,QAAgB;QAFhB,UAAK,GAAL,KAAK,CAAQ;QACb,SAAI,GAAJ,IAAI,CAAQ;QACZ,aAAQ,GAAR,QAAQ,CAAQ;IAC1B,CAAC;CACP;AAND,8BAMC","sourcesContent":["/** One prose page named by `docs.manifest.json`, in the order the manifest names it. */\nexport class ProsePageEntry {\n    constructor(\n        readonly file: string,\n        readonly title: string,\n    ) {}\n}\n\n/**\n * `docs.manifest.json` — the ORDER of the prose pages, and nothing else.\n *\n * It exists for the same reason the OpenAPI document's `tags[]` does: the order is a teaching\n * decision somebody made, and neither directory listing order nor alphabetical order is it.\n * Alphabetising this array is not a cleanup — it reorders the pages a partner reads first.\n */\nexport class DocsManifest {\n    constructor(\n        /** Overrides the document's `info.title` in the site header. Empty means \"use the document's\". */\n        readonly title: string,\n        readonly pages: readonly ProsePageEntry[],\n    ) {}\n}\n\n/** One prose page, loaded: its heading, its URL segment and its markdown source. */\nexport class ProsePage {\n    constructor(\n        readonly title: string,\n        readonly slug: string,\n        readonly markdown: string,\n    ) {}\n}\n"]}

package/src/manifest/ProseLoader.d.ts

@@ -0,0 +1,23 @@
+import { ProsePage } from './DocsManifest';
+/** The one filename this package looks for inside a prose directory. */
+export declare const MANIFEST_FILE = "docs.manifest.json";
+/**
+ * Loads `docs.manifest.json` and the markdown it names.
+ *
+ * A page the manifest names but the directory does not hold is a HARD FAILURE, not a skipped entry.
+ * Skipping it would publish a site whose navigation silently lost a page somebody wrote, and the
+ * only way anybody notices is a partner asking where the guide went.
+ *
+ * A markdown file the manifest does NOT name is simply not published: the manifest is the published
+ * list, so adding a file to the directory is not the same act as publishing it.
+ */
+export declare class ProseLoader {
+    /** @param directory the `--prose` directory, or `undefined` when the run has no prose at all. */
+    load(directory: string | undefined): readonly ProsePage[];
+    /** The manifest's own `title`, or the empty string when there is no manifest. */
+    titleOf(directory: string | undefined): string;
+    private manifestOf;
+    private pagesOf;
+    private read;
+    private parse;
+}

package/src/manifest/ProseLoader.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProseLoader = exports.MANIFEST_FILE = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+const DocsManifest_1 = require("./DocsManifest");
+const DocsSiteError_1 = require("../DocsSiteError");
+const JsonNode_1 = require("../spec/JsonNode");
+const Slug_1 = require("../spec/Slug");
+/** The one filename this package looks for inside a prose directory. */
+exports.MANIFEST_FILE = 'docs.manifest.json';
+/**
+ * Loads `docs.manifest.json` and the markdown it names.
+ *
+ * A page the manifest names but the directory does not hold is a HARD FAILURE, not a skipped entry.
+ * Skipping it would publish a site whose navigation silently lost a page somebody wrote, and the
+ * only way anybody notices is a partner asking where the guide went.
+ *
+ * A markdown file the manifest does NOT name is simply not published: the manifest is the published
+ * list, so adding a file to the directory is not the same act as publishing it.
+ */
+class ProseLoader {
+    /** @param directory the `--prose` directory, or `undefined` when the run has no prose at all. */
+    load(directory) {
+        if (directory === undefined) {
+            return [];
+        }
+        return this.pagesOf(directory, this.manifestOf(directory));
+    }
+    /** The manifest's own `title`, or the empty string when there is no manifest. */
+    titleOf(directory) {
+        if (directory === undefined) {
+            return '';
+        }
+        return this.manifestOf(directory).title;
+    }
+    manifestOf(directory) {
+        const file = path.join(directory, exports.MANIFEST_FILE);
+        const root = new JsonNode_1.JsonNode(this.parse(file, this.read(file)));
+        const pages = [];
+        for (const entry of root.list('pages')) {
+            const name = entry.text('file');
+            if (name === undefined) {
+                throw new DocsSiteError_1.DocsSiteError(`a ${exports.MANIFEST_FILE} page entry has no "file"`, file, 'Give every entry of "pages" a "file" naming a markdown file in this directory.');
+            }
+            pages.push(new DocsManifest_1.ProsePageEntry(name, entry.text('title') ?? name));
+        }
+        return new DocsManifest_1.DocsManifest(root.text('title') ?? '', pages);
+    }
+    pagesOf(directory, manifest) {
+        const slugs = new Slug_1.Slug();
+        return manifest.pages.map((entry) => {
+            const file = path.join(directory, entry.file);
+            if (!fs.existsSync(file)) {
+                throw new DocsSiteError_1.DocsSiteError(`${exports.MANIFEST_FILE} names a page that is not there: ${entry.file}`, file, `Add ${entry.file} to ${directory}, or remove it from "pages" in ${exports.MANIFEST_FILE}.`);
+            }
+            return new DocsManifest_1.ProsePage(entry.title, slugs.unique(entry.title), this.read(file));
+        });
+    }
+    read(file) {
+        if (!fs.existsSync(file)) {
+            throw new DocsSiteError_1.DocsSiteError(`no ${path.basename(file)} there`, file, `Point --prose at a directory holding ${exports.MANIFEST_FILE}, or leave --prose off to publish the reference alone.`);
+        }
+        return fs.readFileSync(file, 'utf8');
+    }
+    // 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(`${exports.MANIFEST_FILE} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, file, 'Fix the JSON syntax and re-run.');
+        }
+    }
+}
+exports.ProseLoader = ProseLoader;
+//# sourceMappingURL=ProseLoader.js.map

package/src/manifest/ProseLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProseLoader.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/manifest/ProseLoader.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { DocsManifest, ProsePage, ProsePageEntry } from './DocsManifest';\nimport { DocsSiteError } from '../DocsSiteError';\nimport { JsonNode } from '../spec/JsonNode';\nimport { Slug } from '../spec/Slug';\n\n/** The one filename this package looks for inside a prose directory. */\nexport const MANIFEST_FILE = 'docs.manifest.json';\n\n/**\n * Loads `docs.manifest.json` and the markdown it names.\n *\n * A page the manifest names but the directory does not hold is a HARD FAILURE, not a skipped entry.\n * Skipping it would publish a site whose navigation silently lost a page somebody wrote, and the\n * only way anybody notices is a partner asking where the guide went.\n *\n * A markdown file the manifest does NOT name is simply not published: the manifest is the published\n * list, so adding a file to the directory is not the same act as publishing it.\n */\nexport class ProseLoader {\n    /** @param directory the `--prose` directory, or `undefined` when the run has no prose at all. */\n    load(directory: string | undefined): readonly ProsePage[] {\n        if (directory === undefined) {\n            return [];\n        }\n        return this.pagesOf(directory, this.manifestOf(directory));\n    }\n\n    /** The manifest's own `title`, or the empty string when there is no manifest. */\n    titleOf(directory: string | undefined): string {\n        if (directory === undefined) {\n            return '';\n        }\n        return this.manifestOf(directory).title;\n    }\n\n    private manifestOf(directory: string): DocsManifest {\n        const file = path.join(directory, MANIFEST_FILE);\n        const root = new JsonNode(this.parse(file, this.read(file)));\n        const pages: ProsePageEntry[] = [];\n        for (const entry of root.list('pages')) {\n            const name = entry.text('file');\n            if (name === undefined) {\n                throw new DocsSiteError(\n                    `a ${MANIFEST_FILE} page entry has no \"file\"`,\n                    file,\n                    'Give every entry of \"pages\" a \"file\" naming a markdown file in this directory.',\n                );\n            }\n            pages.push(new ProsePageEntry(name, entry.text('title') ?? name));\n        }\n        return new DocsManifest(root.text('title') ?? '', pages);\n    }\n\n    private pagesOf(directory: string, manifest: DocsManifest): readonly ProsePage[] {\n        const slugs = new Slug();\n        return manifest.pages.map((entry: ProsePageEntry): ProsePage => {\n            const file = path.join(directory, entry.file);\n            if (!fs.existsSync(file)) {\n                throw new DocsSiteError(\n                    `${MANIFEST_FILE} names a page that is not there: ${entry.file}`,\n                    file,\n                    `Add ${entry.file} to ${directory}, or remove it from \"pages\" in ${MANIFEST_FILE}.`,\n                );\n            }\n            return new ProsePage(entry.title, slugs.unique(entry.title), this.read(file));\n        });\n    }\n\n    private read(file: string): string {\n        if (!fs.existsSync(file)) {\n            throw new DocsSiteError(\n                `no ${path.basename(file)} there`,\n                file,\n                `Point --prose at a directory holding ${MANIFEST_FILE}, or leave --prose off to publish the reference alone.`,\n            );\n        }\n        return fs.readFileSync(file, 'utf8');\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                `${MANIFEST_FILE} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,\n                file,\n                'Fix the JSON syntax and re-run.',\n            );\n        }\n    }\n}\n"]}

package/src/markdown/Markdown.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A DOCUMENTED SUBSET of CommonMark, over trusted, PR-reviewed input — the JSDoc a developer wrote
+ * and the markdown files a manifest names. It is not a CommonMark implementation and does not try to
+ * be; #985 puts a full one explicitly out of scope, because the alternative to ~180 lines here is a
+ * dependency in every upstream project that wants an API reference.
+ *
+ * What it renders:
+ *
+ * | block | spelling |
+ * |---|---|
+ * | heading | `#` through `######` |
+ * | fenced code | ` ``` ` with an optional language word |
+ * | table | a `\|` row, then a `\|---\|` row, then rows |
+ * | list | `- ` / `* ` for bullets, `1. ` for numbers |
+ * | blockquote | `> ` |
+ * | rule | `---` on its own line |
+ * | paragraph | anything else, blank-line separated |
+ *
+ * and inline: `` `code` ``, `**bold**`, `*italic*`, `[text](url)`.
+ *
+ * **Everything is HTML-escaped first**, before any inline pattern runs, so a `<` in a JSDoc body is
+ * text rather than the start of a tag. That ordering is the whole safety argument: escape-then-mark
+ * cannot produce a tag the source did not ask for, while mark-then-escape would escape the tags this
+ * renderer just wrote.
+ */
+export declare class Markdown {
+    private readonly html;
+    /** The rendered HTML for a markdown document. */
+    render(source: string): string;
+    /** Inline markdown only — for a place that is already one line, like a table cell. */
+    inline(source: string): string;
+    /** @returns the index of the first line AFTER the block this consumed. */
+    private block;
+    private fence;
+    private heading;
+    private table;
+    private list;
+    private quote;
+    private paragraph;
+    /** True when the line at `index` begins a block that a paragraph must not swallow. */
+    private startsBlock;
+    private isDivider;
+    private isBullet;
+    private isNumber;
+    private itemTextOf;
+    private cells;
+}