@dogsbay/format-openapi 0.2.0-beta.13 → 0.2.0-beta.130

package/dist/embed.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The spec references an embed names, in order. Each is the string the
+ * viewer would request, and whether it is resolved against the page URL
+ * (`window.location.pathname + "../api.yaml"`, or any relative URL) or the
+ * site root (`/api.yaml`). URLs (`https:`) are not returned.
+ */
+export declare function embeddedSpecRefs(html: string): string[];
+export interface EmbedSpecOptions {
+    /** The source root; the spec must be inside it once symlinks resolve. */
+    srcDir: string;
+    /** The page's docname: `reference/api/ams-api` (no suffix). */
+    docname: string;
+    /** Directories copied to the site root (Sphinx `html_extra_path`). */
+    extraDirs?: readonly string[];
+    /** Directories served at `/_static/` (Sphinx `html_static_path`). */
+    staticDirs?: readonly string[];
+}
+/**
+ * The source file a spec reference loads, as a `/`-separated path relative
+ * to `srcDir`, or null.
+ *
+ * A relative reference is resolved against the page URL. Sphinx serves a
+ * page at `/reference/api/ams-api/` (dirhtml) or `/reference/api/ams-api.html`
+ * (html), and the two resolve `../` differently, so both are tried. The site
+ * path is then looked up where Sphinx would have put that file: the source
+ * tree, `html_extra_path` (copied to the root) and `html_static_path`
+ * (served at `/_static/`). Last, a file of the same name next to the page.
+ */
+export declare function resolveEmbeddedSpec(ref: string, opts: EmbedSpecOptions): string | null;

package/dist/embed.js

@@ -0,0 +1,134 @@
+/**
+ * A spec embedded in a page by a JavaScript API viewer: Swagger UI, Redoc or
+ * RapiDoc. Importers drop raw `<script>`, which leaves such a page EMPTY:
+ * the reference was never in the page, the viewer drew it in the browser
+ * from a spec file. This finds that file so the importer can emit
+ * `:::openapi{spec="…"}` instead, and the site build renders the spec.
+ *
+ * No dependencies (it is imported by format-rst and format-myst, which do not
+ * need the spec parser), and nothing is fetched: only a file in the source
+ * tree is ever returned.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join, posix, relative, sep } from "node:path";
+const SPEC_FILE = /\.(ya?ml|json)$/i;
+/** An embed is a few hundred bytes; a larger block is not scanned. Every
+ *  pattern below is also linear: `[^<>]` cannot run on into the next tag. */
+const MAX_HTML = 64 * 1024;
+/**
+ * The spec references an embed names, in order. Each is the string the
+ * viewer would request, and whether it is resolved against the page URL
+ * (`window.location.pathname + "../api.yaml"`, or any relative URL) or the
+ * site root (`/api.yaml`). URLs (`https:`) are not returned.
+ */
+export function embeddedSpecRefs(html) {
+    const refs = [];
+    if (html.length > MAX_HTML)
+        return refs;
+    const add = (ref) => {
+        if (!ref)
+            return;
+        const clean = ref.trim();
+        if (!clean || /^[a-z][a-z0-9+.-]*:|^\/\//i.test(clean))
+            return;
+        if (!SPEC_FILE.test(clean.split(/[?#]/)[0]))
+            return;
+        if (!refs.includes(clean))
+            refs.push(clean);
+    };
+    // Swagger UI: SwaggerUIBundle({ url: … }) / SwaggerUI({ url: … }), and
+    // `urls: [{ url: … }]`. The value may concatenate location.pathname with a
+    // relative literal; the literal is what matters.
+    if (/\bSwaggerUI(?:Bundle)?\s*\(/.test(html)) {
+        for (const m of html.matchAll(/\burl\s*:\s*([^,\n}]+)/g)) {
+            const literals = [...m[1].matchAll(/(["'`])((?:(?!\1)[^\\\n]|\\.)*)\1/g)].map((l) => l[2]);
+            add(literals.join(""));
+        }
+    }
+    // Redoc: Redoc.init("spec.yaml", …) and <redoc spec-url="…">.
+    for (const m of html.matchAll(/\bRedoc\.init\s*\(\s*(["'`])([^"'`\n]+)\1/g))
+        add(m[2]);
+    // Redoc and RapiDoc elements.
+    for (const m of html.matchAll(/<(?:redoc|rapi-doc)\b[^<>]*?\bspec-url\s*=\s*(["'])([^"'<>]+)\1/gi))
+        add(m[2]);
+    return refs;
+}
+/**
+ * The source file a spec reference loads, as a `/`-separated path relative
+ * to `srcDir`, or null.
+ *
+ * A relative reference is resolved against the page URL. Sphinx serves a
+ * page at `/reference/api/ams-api/` (dirhtml) or `/reference/api/ams-api.html`
+ * (html), and the two resolve `../` differently, so both are tried. The site
+ * path is then looked up where Sphinx would have put that file: the source
+ * tree, `html_extra_path` (copied to the root) and `html_static_path`
+ * (served at `/_static/`). Last, a file of the same name next to the page.
+ */
+export function resolveEmbeddedSpec(ref, opts) {
+    const path = ref.split(/[?#]/)[0].replace(/\\/g, "/");
+    const docname = opts.docname.replace(/\\/g, "/");
+    const docDir = posix.dirname(docname) === "." ? "" : posix.dirname(docname);
+    const pageDirs = docname === "index" || docname.endsWith("/index") ? [docDir] : [docname, docDir];
+    const sitePaths = [];
+    if (path.startsWith("/")) {
+        sitePaths.push(path.replace(/^\/+/, ""));
+    }
+    else {
+        for (const base of pageDirs) {
+            const joined = posix.normalize(posix.join("/", base, path));
+            // posix.join("/", …) clamps at the root; a reference that climbs above
+            // it under one URL shape is simply not that shape.
+            if (climbsAbove(base, path))
+                continue;
+            sitePaths.push(joined.replace(/^\/+/, ""));
+        }
+    }
+    const candidates = [];
+    for (const p of sitePaths) {
+        candidates.push(join(opts.srcDir, p));
+        for (const d of opts.extraDirs ?? [])
+            candidates.push(join(d, p));
+        if (p.startsWith("_static/")) {
+            for (const d of opts.staticDirs ?? [])
+                candidates.push(join(d, p.slice("_static/".length)));
+        }
+    }
+    candidates.push(join(opts.srcDir, docDir, posix.basename(path)));
+    let realRoot;
+    try {
+        realRoot = realpathSync(opts.srcDir);
+    }
+    catch {
+        return null;
+    }
+    for (const c of candidates) {
+        if (!existsSync(c))
+            continue;
+        let real;
+        try {
+            real = realpathSync(c);
+            if (!statSync(real).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (!real.startsWith(realRoot + sep))
+            continue;
+        return relative(realRoot, real).split(sep).join("/");
+    }
+    return null;
+}
+/** Does `rel`, resolved from the directory `base`, go above the root? */
+function climbsAbove(base, rel) {
+    let depth = base ? base.split("/").filter(Boolean).length : 0;
+    for (const seg of rel.split("/")) {
+        if (seg === "..") {
+            if (--depth < 0)
+                return true;
+        }
+        else if (seg && seg !== ".")
+            depth++;
+    }
+    return false;
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { SchemaProperty, Parameter, ResponseDef, CodeSample, EndpointProps, } from "./types.js";
-export { parseOpenApiSpec, detectOpenApiSource, detectSpecPath } from "./parse.js";
-export type { ParseOpenApiOptions } from "./parse.js";
+export { parseOpenApiSpec, detectOpenApiSource, detectSpecPath, openApiEmbed, loadSpec } from "./parse.js";
+export type { ParseOpenApiOptions, OpenApiEmbed, OpenApiEmbedOptions } from "./parse.js";
+export { createSpecCache, directiveOperation, embedSpec, findSpec, parseSpecText, prepareSpec, specCandidates, specToPages, VALUE_TOO_LARGE, type SpecLookup, } from "./core.js";
 export { operationToSlug, slugifyTag } from "./slug.js";
 export { resolveCodeSamples } from "./code-samples.js";
 export { plugin } from "./cli.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,6 @@
-export { parseOpenApiSpec, detectOpenApiSource, detectSpecPath } from "./parse.js";
+export { parseOpenApiSpec, detectOpenApiSource, detectSpecPath, openApiEmbed, loadSpec } from "./parse.js";
+// The Worker-safe core is also its own entry, `@dogsbay/format-openapi/core`.
+export { createSpecCache, directiveOperation, embedSpec, findSpec, parseSpecText, prepareSpec, specCandidates, specToPages, VALUE_TOO_LARGE, } from "./core.js";
 export { operationToSlug, slugifyTag } from "./slug.js";
 export { resolveCodeSamples } from "./code-samples.js";
 export { plugin } from "./cli.js";
-//# sourceMappingURL=index.js.map

package/dist/parse.d.ts

@@ -1,4 +1,6 @@
 import type { ExportPage, NavItem } from "@dogsbay/types";
+import { type OpenApiEmbed, type OpenApiEmbedOptions, type ParseOpenApiOptions } from "./core.js";
+export type { OpenApiEmbed, OpenApiEmbedOptions, ParseOpenApiOptions };
 /** Auto-detect spec location given the configured source path. */
 export declare function detectSpecPath(sourcePath: string): string | null;
 /**
@@ -7,14 +9,15 @@ export declare function detectSpecPath(sourcePath: string): string | null;
  * extension whose contents declare `openapi:`).
  */
 export declare function detectOpenApiSource(path: string): boolean;
-export interface ParseOpenApiOptions {
-    /** When the importer wants nav hrefs to start with this prefix. */
-    hrefPrefix?: string;
-    /** Sub-path within the namespace for emitted pages, e.g. "api". */
-    section?: string;
-}
 export declare function parseOpenApiSpec(sourcePath: string, options?: ParseOpenApiOptions): Promise<{
     pages: ExportPage[];
     nav: NavItem[];
 }>;
-//# sourceMappingURL=parse.d.ts.map
+/** Read a spec file (or URL) and prepare it (core.ts `prepareSpec`). */
+export declare function loadSpec(specPath: string): Promise<any>;
+/**
+ * A whole spec as the BODY of one page (core.ts `embedSpec`), read from a
+ * file. Each call parses the spec; a build that embeds one spec on several
+ * pages uses `createSpecCache` and `embedSpec` instead.
+ */
+export declare function openApiEmbed(specPath: string, options?: OpenApiEmbedOptions): Promise<OpenApiEmbed>;