@webpieces/docs-site 0.0.1

package/src/spec/SpecReader.d.ts

@@ -0,0 +1,46 @@
+import { ApiSpec } from './ApiSpec';
+import { JsonNode } from './JsonNode';
+/** The section untagged operations land in, so an operation is never unreachable from the nav. */
+export declare const UNTAGGED_SECTION = "Operations";
+/**
+ * Reads one OpenAPI 3.0-or-3.1 document into an {@link ApiSpec}.
+ *
+ * ## Nothing here is SORTED
+ *
+ * Both orders in the finished site are published decisions somebody made, so neither is re-derived:
+ * the reference order is the document's own `tags[]`, and the prose order is `docs.manifest.json`.
+ * Alphabetising either is not a cleanup — it reorders partner-facing navigation.
+ *
+ * A tag that appears on an operation without being declared in `tags[]` still gets its own section,
+ * appended in first-seen order. A tag missing from the sidebar is an operation a partner cannot
+ * find, which reads exactly like an operation that does not exist.
+ *
+ * ## Webhooks
+ *
+ * A top-level `webhooks:` entry files into the SAME section as the operations sharing its tag, and
+ * is APPENDED after them, because the events are what happens as a result of the calls above.
+ */
+export declare class SpecReader {
+    private readonly shape;
+    read(root: JsonNode): ApiSpec;
+    private readServers;
+    private readSecuritySchemes;
+    private readSchemas;
+    private readSections;
+    /** `tags[]` first, in its published order, then any tag only an operation mentions. */
+    private sectionOrder;
+    private tagDescription;
+    private readOperations;
+    private readWebhooks;
+    private readOperation;
+    private tagOf;
+    private requestSchemaOf;
+    private responsesOf;
+    /**
+     * The credentials this operation needs: its own `security` when it states one, the document's
+     * otherwise. An operation stating `security: []` needs none, and that empty array is the
+     * OpenAPI spelling of "no credential" rather than of "inherit" — so it must not fall back.
+     */
+    private operationSecurityKeys;
+    private securityKeysIn;
+}

package/src/spec/SpecReader.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecReader = exports.UNTAGGED_SECTION = void 0;
+const ApiSpec_1 = require("./ApiSpec");
+const SchemaShape_1 = require("./SchemaShape");
+const Slug_1 = require("./Slug");
+const HTTP_METHODS = [
+    'get',
+    'put',
+    'post',
+    'delete',
+    'options',
+    'head',
+    'patch',
+    'trace',
+];
+/** The section untagged operations land in, so an operation is never unreachable from the nav. */
+exports.UNTAGGED_SECTION = 'Operations';
+/**
+ * Reads one OpenAPI 3.0-or-3.1 document into an {@link ApiSpec}.
+ *
+ * ## Nothing here is SORTED
+ *
+ * Both orders in the finished site are published decisions somebody made, so neither is re-derived:
+ * the reference order is the document's own `tags[]`, and the prose order is `docs.manifest.json`.
+ * Alphabetising either is not a cleanup — it reorders partner-facing navigation.
+ *
+ * A tag that appears on an operation without being declared in `tags[]` still gets its own section,
+ * appended in first-seen order. A tag missing from the sidebar is an operation a partner cannot
+ * find, which reads exactly like an operation that does not exist.
+ *
+ * ## Webhooks
+ *
+ * A top-level `webhooks:` entry files into the SAME section as the operations sharing its tag, and
+ * is APPENDED after them, because the events are what happens as a result of the calls above.
+ */
+class SpecReader {
+    shape = new SchemaShape_1.SchemaShape();
+    read(root) {
+        const schemas = this.readSchemas(root);
+        const sections = this.readSections(root);
+        return new ApiSpec_1.ApiSpec(root.at('info').text('title') ?? 'API reference', root.at('info').text('version') ?? '', root.at('info').text('description') ?? '', this.readServers(root), sections, this.readSecuritySchemes(root), schemas, this.securityKeysIn(root));
+    }
+    readServers(root) {
+        return root
+            .list('servers')
+            .map((entry) => new ApiSpec_1.ServerInfo(entry.text('url') ?? '', entry.text('description')));
+    }
+    readSecuritySchemes(root) {
+        const declared = root.at('components').at('securitySchemes');
+        return declared
+            .entries()
+            .map((entry) => new ApiSpec_1.SecuritySchemeInfo(entry.key, entry.value.text('type') ?? '', entry.value.text('in') ?? '', entry.value.text('name') ?? '', entry.value.text('description')));
+    }
+    readSchemas(root) {
+        const slugs = new Slug_1.Slug();
+        return root
+            .at('components')
+            .at('schemas')
+            .entries()
+            .map((entry) => new ApiSpec_1.NamedSchema(entry.key, slugs.unique(entry.key), entry.value, this.shape.hasOwnPage(entry.value)));
+    }
+    readSections(root) {
+        const slugs = new Slug_1.Slug();
+        const operations = this.readOperations(root, slugs);
+        const webhooks = this.readWebhooks(root, slugs);
+        const order = this.sectionOrder(root, operations, webhooks);
+        const sections = [];
+        for (const tag of order) {
+            const inTag = operations.filter((one) => one.tag === tag);
+            const eventsInTag = webhooks.filter((one) => one.tag === tag);
+            sections.push(new ApiSpec_1.TagSection(tag, this.tagDescription(root, tag), [...inTag, ...eventsInTag]));
+        }
+        return sections;
+    }
+    /** `tags[]` first, in its published order, then any tag only an operation mentions. */
+    sectionOrder(root, operations, webhooks) {
+        const order = [];
+        for (const declared of root.list('tags')) {
+            const name = declared.text('name');
+            if (name !== undefined && !order.includes(name)) {
+                order.push(name);
+            }
+        }
+        for (const one of [...operations, ...webhooks]) {
+            if (!order.includes(one.tag)) {
+                order.push(one.tag);
+            }
+        }
+        return order.filter((tag) => [...operations, ...webhooks].some((one) => one.tag === tag));
+    }
+    tagDescription(root, tag) {
+        for (const declared of root.list('tags')) {
+            if (declared.text('name') === tag) {
+                return declared.text('description') ?? '';
+            }
+        }
+        return '';
+    }
+    readOperations(root, slugs) {
+        const found = [];
+        for (const pathEntry of root.at('paths').entries()) {
+            for (const methodEntry of pathEntry.value.entries()) {
+                if (!HTTP_METHODS.includes(methodEntry.key)) {
+                    continue;
+                }
+                found.push(this.readOperation(root, methodEntry.value, slugs, methodEntry.key.toUpperCase(), pathEntry.key, false));
+            }
+        }
+        return found;
+    }
+    readWebhooks(root, slugs) {
+        const found = [];
+        for (const eventEntry of root.at('webhooks').entries()) {
+            for (const methodEntry of eventEntry.value.entries()) {
+                if (!HTTP_METHODS.includes(methodEntry.key)) {
+                    continue;
+                }
+                found.push(this.readOperation(root, methodEntry.value, slugs, '', eventEntry.key, true));
+            }
+        }
+        return found;
+    }
+    readOperation(root, node, slugs, httpMethod, pathOrEvent, isWebhook) {
+        const name = node.text('summary') ?? node.text('operationId') ?? pathOrEvent;
+        return new ApiSpec_1.OperationInfo(name, slugs.unique(name), httpMethod, isWebhook ? '' : pathOrEvent, node.text('description') ?? '', this.tagOf(node), this.requestSchemaOf(node), this.responsesOf(node), isWebhook, isWebhook ? [] : this.operationSecurityKeys(root, node), isWebhook ? pathOrEvent : '');
+    }
+    tagOf(node) {
+        for (const tag of node.list('tags')) {
+            const name = tag.asText();
+            if (name !== undefined) {
+                return name;
+            }
+        }
+        return exports.UNTAGGED_SECTION;
+    }
+    requestSchemaOf(node) {
+        const schema = node.at('requestBody').at('content').at('application/json').at('schema');
+        return schema.isObject() ? schema : undefined;
+    }
+    responsesOf(node) {
+        return node
+            .at('responses')
+            .entries()
+            .map((entry) => {
+            const schema = entry.value.at('content').at('application/json').at('schema');
+            return new ApiSpec_1.ResponseInfo(entry.key, entry.value.text('description') ?? '', schema.isObject() ? schema : undefined);
+        });
+    }
+    /**
+     * The credentials this operation needs: its own `security` when it states one, the document's
+     * otherwise. An operation stating `security: []` needs none, and that empty array is the
+     * OpenAPI spelling of "no credential" rather than of "inherit" — so it must not fall back.
+     */
+    operationSecurityKeys(root, node) {
+        if (Array.isArray(node.at('security').raw)) {
+            return this.securityKeysIn(node);
+        }
+        return this.securityKeysIn(root);
+    }
+    securityKeysIn(holder) {
+        const keys = [];
+        for (const requirement of holder.list('security')) {
+            for (const key of requirement.keys()) {
+                if (!keys.includes(key)) {
+                    keys.push(key);
+                }
+            }
+        }
+        return keys;
+    }
+}
+exports.SpecReader = SpecReader;
+//# sourceMappingURL=SpecReader.js.map

package/src/spec/SpecReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecReader.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/SpecReader.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ApiSpec,\n    NamedSchema,\n    OperationInfo,\n    ResponseInfo,\n    SecuritySchemeInfo,\n    ServerInfo,\n    TagSection,\n} from './ApiSpec';\nimport { JsonEntry, JsonNode } from './JsonNode';\nimport { SchemaShape } from './SchemaShape';\nimport { Slug } from './Slug';\n\nconst HTTP_METHODS: readonly string[] = [\n    'get',\n    'put',\n    'post',\n    'delete',\n    'options',\n    'head',\n    'patch',\n    'trace',\n];\n\n/** The section untagged operations land in, so an operation is never unreachable from the nav. */\nexport const UNTAGGED_SECTION = 'Operations';\n\n/**\n * Reads one OpenAPI 3.0-or-3.1 document into an {@link ApiSpec}.\n *\n * ## Nothing here is SORTED\n *\n * Both orders in the finished site are published decisions somebody made, so neither is re-derived:\n * the reference order is the document's own `tags[]`, and the prose order is `docs.manifest.json`.\n * Alphabetising either is not a cleanup — it reorders partner-facing navigation.\n *\n * A tag that appears on an operation without being declared in `tags[]` still gets its own section,\n * appended in first-seen order. A tag missing from the sidebar is an operation a partner cannot\n * find, which reads exactly like an operation that does not exist.\n *\n * ## Webhooks\n *\n * A top-level `webhooks:` entry files into the SAME section as the operations sharing its tag, and\n * is APPENDED after them, because the events are what happens as a result of the calls above.\n */\nexport class SpecReader {\n    private readonly shape = new SchemaShape();\n\n    read(root: JsonNode): ApiSpec {\n        const schemas = this.readSchemas(root);\n        const sections = this.readSections(root);\n        return new ApiSpec(\n            root.at('info').text('title') ?? 'API reference',\n            root.at('info').text('version') ?? '',\n            root.at('info').text('description') ?? '',\n            this.readServers(root),\n            sections,\n            this.readSecuritySchemes(root),\n            schemas,\n            this.securityKeysIn(root),\n        );\n    }\n\n    private readServers(root: JsonNode): readonly ServerInfo[] {\n        return root\n            .list('servers')\n            .map(\n                (entry: JsonNode): ServerInfo =>\n                    new ServerInfo(entry.text('url') ?? '', entry.text('description')),\n            );\n    }\n\n    private readSecuritySchemes(root: JsonNode): readonly SecuritySchemeInfo[] {\n        const declared = root.at('components').at('securitySchemes');\n        return declared\n            .entries()\n            .map(\n                (entry: JsonEntry): SecuritySchemeInfo =>\n                    new SecuritySchemeInfo(\n                        entry.key,\n                        entry.value.text('type') ?? '',\n                        entry.value.text('in') ?? '',\n                        entry.value.text('name') ?? '',\n                        entry.value.text('description'),\n                    ),\n            );\n    }\n\n    private readSchemas(root: JsonNode): readonly NamedSchema[] {\n        const slugs = new Slug();\n        return root\n            .at('components')\n            .at('schemas')\n            .entries()\n            .map(\n                (entry: JsonEntry): NamedSchema =>\n                    new NamedSchema(\n                        entry.key,\n                        slugs.unique(entry.key),\n                        entry.value,\n                        this.shape.hasOwnPage(entry.value),\n                    ),\n            );\n    }\n\n    private readSections(root: JsonNode): readonly TagSection[] {\n        const slugs = new Slug();\n        const operations = this.readOperations(root, slugs);\n        const webhooks = this.readWebhooks(root, slugs);\n        const order = this.sectionOrder(root, operations, webhooks);\n        const sections: TagSection[] = [];\n        for (const tag of order) {\n            const inTag = operations.filter((one: OperationInfo): boolean => one.tag === tag);\n            const eventsInTag = webhooks.filter((one: OperationInfo): boolean => one.tag === tag);\n            sections.push(\n                new TagSection(tag, this.tagDescription(root, tag), [...inTag, ...eventsInTag]),\n            );\n        }\n        return sections;\n    }\n\n    /** `tags[]` first, in its published order, then any tag only an operation mentions. */\n    private sectionOrder(\n        root: JsonNode,\n        operations: readonly OperationInfo[],\n        webhooks: readonly OperationInfo[],\n    ): readonly string[] {\n        const order: string[] = [];\n        for (const declared of root.list('tags')) {\n            const name = declared.text('name');\n            if (name !== undefined && !order.includes(name)) {\n                order.push(name);\n            }\n        }\n        for (const one of [...operations, ...webhooks]) {\n            if (!order.includes(one.tag)) {\n                order.push(one.tag);\n            }\n        }\n        return order.filter((tag: string): boolean =>\n            [...operations, ...webhooks].some((one: OperationInfo): boolean => one.tag === tag),\n        );\n    }\n\n    private tagDescription(root: JsonNode, tag: string): string {\n        for (const declared of root.list('tags')) {\n            if (declared.text('name') === tag) {\n                return declared.text('description') ?? '';\n            }\n        }\n        return '';\n    }\n\n    private readOperations(root: JsonNode, slugs: Slug): readonly OperationInfo[] {\n        const found: OperationInfo[] = [];\n        for (const pathEntry of root.at('paths').entries()) {\n            for (const methodEntry of pathEntry.value.entries()) {\n                if (!HTTP_METHODS.includes(methodEntry.key)) {\n                    continue;\n                }\n                found.push(\n                    this.readOperation(\n                        root,\n                        methodEntry.value,\n                        slugs,\n                        methodEntry.key.toUpperCase(),\n                        pathEntry.key,\n                        false,\n                    ),\n                );\n            }\n        }\n        return found;\n    }\n\n    private readWebhooks(root: JsonNode, slugs: Slug): readonly OperationInfo[] {\n        const found: OperationInfo[] = [];\n        for (const eventEntry of root.at('webhooks').entries()) {\n            for (const methodEntry of eventEntry.value.entries()) {\n                if (!HTTP_METHODS.includes(methodEntry.key)) {\n                    continue;\n                }\n                found.push(\n                    this.readOperation(root, methodEntry.value, slugs, '', eventEntry.key, true),\n                );\n            }\n        }\n        return found;\n    }\n\n    private readOperation(\n        root: JsonNode,\n        node: JsonNode,\n        slugs: Slug,\n        httpMethod: string,\n        pathOrEvent: string,\n        isWebhook: boolean,\n    ): OperationInfo {\n        const name = node.text('summary') ?? node.text('operationId') ?? pathOrEvent;\n        return new OperationInfo(\n            name,\n            slugs.unique(name),\n            httpMethod,\n            isWebhook ? '' : pathOrEvent,\n            node.text('description') ?? '',\n            this.tagOf(node),\n            this.requestSchemaOf(node),\n            this.responsesOf(node),\n            isWebhook,\n            isWebhook ? [] : this.operationSecurityKeys(root, node),\n            isWebhook ? pathOrEvent : '',\n        );\n    }\n\n    private tagOf(node: JsonNode): string {\n        for (const tag of node.list('tags')) {\n            const name = tag.asText();\n            if (name !== undefined) {\n                return name;\n            }\n        }\n        return UNTAGGED_SECTION;\n    }\n\n    private requestSchemaOf(node: JsonNode): JsonNode | undefined {\n        const schema = node.at('requestBody').at('content').at('application/json').at('schema');\n        return schema.isObject() ? schema : undefined;\n    }\n\n    private responsesOf(node: JsonNode): readonly ResponseInfo[] {\n        return node\n            .at('responses')\n            .entries()\n            .map((entry: JsonEntry): ResponseInfo => {\n                const schema = entry.value.at('content').at('application/json').at('schema');\n                return new ResponseInfo(\n                    entry.key,\n                    entry.value.text('description') ?? '',\n                    schema.isObject() ? schema : undefined,\n                );\n            });\n    }\n\n    /**\n     * The credentials this operation needs: its own `security` when it states one, the document's\n     * otherwise. An operation stating `security: []` needs none, and that empty array is the\n     * OpenAPI spelling of \"no credential\" rather than of \"inherit\" — so it must not fall back.\n     */\n    private operationSecurityKeys(root: JsonNode, node: JsonNode): readonly string[] {\n        if (Array.isArray(node.at('security').raw)) {\n            return this.securityKeysIn(node);\n        }\n        return this.securityKeysIn(root);\n    }\n\n    private securityKeysIn(holder: JsonNode): readonly string[] {\n        const keys: string[] = [];\n        for (const requirement of holder.list('security')) {\n            for (const key of requirement.keys()) {\n                if (!keys.includes(key)) {\n                    keys.push(key);\n                }\n            }\n        }\n        return keys;\n    }\n}\n"]}