sourcey 3.5.10 → 3.6.1

package/dist/core/navigation.js

@@ -73,31 +73,32 @@ export function buildNavFromSpec(spec, tabSlug, prettyUrls = false) {
  * Groups come from the config; items come from loaded page data.
  */
 export function buildNavFromPages(tab, pagesByPath, prettyUrls = false) {
-    const groups = [];
-    if (tab.groups) {
-        for (const group of tab.groups) {
+    const navGroups = [];
+    const sourceGroups = tab.source.kind === "markdown" ? tab.source.groups : tab.groups;
+    if (sourceGroups) {
+        for (const group of sourceGroups) {
             const items = [];
             for (const rp of group.pages) {
                 const page = pagesByPath.get(rp.slug);
                 if (!page)
                     continue;
                 items.push({
-                    label: page.title,
+                    label: rp.label ?? page.title,
                     href: navHref(pageOutputPath(tab.slug, page.slug, prettyUrls), prettyUrls),
                     id: page.slug,
                 });
             }
-            groups.push({ label: group.label, items });
+            navGroups.push({ label: group.label, items });
         }
     }
-    const firstItem = groups[0]?.items[0];
+    const firstItem = navGroups[0]?.items[0];
     const href = firstItem?.href ?? (tab.slug ? `${tab.slug}/` : "");
     return {
         label: tab.label,
         slug: tab.slug,
         href,
         kind: "docs",
-        groups,
+        groups: navGroups,
     };
 }
 /**

package/dist/core/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/core/parser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBvE"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/core/parser.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CA+BvE"}

package/dist/core/parser.js

@@ -1,4 +1,6 @@
 import { $RefParser } from "@apidevtools/json-schema-ref-parser";
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 /**
  * Dereference a loaded spec document.
@@ -10,7 +12,21 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 export async function parseSpec(loaded) {
     try {
         const parser = new $RefParser();
-        const dereferenced = await parser.dereference(resolveDocumentUri(loaded), structuredClone(loaded.raw), { dereference: { circular: "ignore" } });
+        const dereferenced = await parser.dereference(resolveDocumentUri(loaded), structuredClone(loaded.raw), {
+            dereference: {
+                circular: "ignore",
+                onDereference(ref, value) {
+                    const refName = refNameFromRef(ref);
+                    if (refName && isRecord(value) && typeof value["x-ref-name"] !== "string") {
+                        value["x-ref-name"] = refName;
+                    }
+                },
+            },
+            resolve: {
+                http: false,
+                file: createConfinedFileResolver(loaded),
+            },
+        });
         return {
             document: dereferenced,
             source: loaded.source,
@@ -21,6 +37,63 @@ export async function parseSpec(loaded) {
         throw new Error(`Failed to parse OpenAPI spec: ${message}`);
     }
 }
+function createConfinedFileResolver(loaded) {
+    const root = localSpecRoot(loaded.source);
+    if (!root)
+        return false;
+    return {
+        order: 1,
+        canRead(file) {
+            return filePathFromRef(file.url) !== null;
+        },
+        async read(file) {
+            const filePath = filePathFromRef(file.url);
+            if (!filePath)
+                throw new Error(`Unsupported external $ref URI: ${file.url}`);
+            const resolved = resolve(filePath);
+            if (!isWithinRoot(root, resolved)) {
+                throw new Error(`External $ref resolves outside the spec directory: ${file.url}`);
+            }
+            return readFile(resolved);
+        },
+    };
+}
+function localSpecRoot(source) {
+    if (source.startsWith("http://") || source.startsWith("https://"))
+        return null;
+    return dirname(resolve(source));
+}
+function filePathFromRef(refUrl) {
+    const withoutHash = refUrl.split("#", 1)[0];
+    if (!withoutHash)
+        return null;
+    if (/^file:/i.test(withoutHash)) {
+        try {
+            return fileURLToPath(withoutHash);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (/^[a-z][a-z\d+.-]*:/i.test(withoutHash))
+        return null;
+    return resolve(withoutHash);
+}
+function isWithinRoot(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function refNameFromRef(ref) {
+    const pointer = ref.includes("#") ? ref.slice(ref.indexOf("#") + 1) : ref;
+    const segments = pointer.split("/").filter(Boolean);
+    const raw = segments.at(-1);
+    if (!raw)
+        return null;
+    return raw.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function resolveDocumentUri(loaded) {
     const self = typeof loaded.raw["$self"] === "string" ? loaded.raw["$self"] : undefined;
     if (!self)
@@ -30,9 +103,7 @@ function resolveDocumentUri(loaded) {
             return new URL(self, loaded.source).toString();
         }
         const resolved = new URL(self, pathToFileURL(loaded.source));
-        return resolved.protocol === "file:"
-            ? fileURLToPath(resolved)
-            : resolved.toString();
+        return resolved.protocol === "file:" ? fileURLToPath(resolved) : resolved.toString();
     }
     catch {
         return loaded.source;

package/dist/core/rustdoc-introspector.d.ts

@@ -0,0 +1,29 @@
+import type { ResolvedRustdocConfig } from "../config.js";
+import type { RustdocDiagnostic, RustdocSpec } from "./rustdoc-types.js";
+export declare class RustdocIntrospectorError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(code: string, message: string, cause?: Error);
+}
+export interface IntrospectOptions {
+    config: ResolvedRustdocConfig;
+    /** Override cargo binary; defaults to "cargo" on PATH. */
+    cargoBinary?: string;
+    /** Override rustup binary; defaults to "rustup" on PATH. */
+    rustupBinary?: string;
+}
+export interface IntrospectResult {
+    spec: RustdocSpec;
+    diagnostics: RustdocDiagnostic[];
+    /** Mode actually used (after auto resolution). */
+    modeUsed: "live" | "snapshot";
+}
+/**
+ * Run the bundled Rust helper or load a committed snapshot, return a
+ * parsed RustdocSpec plus any diagnostics. Mode is resolved per the
+ * spec's auto fallback policy.
+ */
+export declare function runIntrospector(opts: IntrospectOptions): Promise<IntrospectResult>;
+/** Resolved helper entry paths, exported for tests that pin runtime. */
+export declare const __rustdocHelperCandidatesForTests: string[];
+//# sourceMappingURL=rustdoc-introspector.d.ts.map

package/dist/core/rustdoc-introspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rustdoc-introspector.d.ts","sourceRoot":"","sources":["../../src/core/rustdoc-introspector.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAQzE,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;gBACvB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAMzD;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAexF;AAwPD,wEAAwE;AACxE,eAAO,MAAM,iCAAiC,UAG7C,CAAC"}

package/dist/core/rustdoc-introspector.js

@@ -0,0 +1,236 @@
+import { spawn, spawnSync } from "node:child_process";
+import { access, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+import { RUSTDOC_DIAGNOSTIC_CODES, SPEC_VERSION } from "./rustdoc-types.js";
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const PACKAGED_HELPER_DIR = join(MODULE_DIR, "sourcey-rustdoc");
+const DEV_HELPER_DIR = resolve(MODULE_DIR, "../../rust/sourcey-rustdoc");
+const HELPER_MANIFEST = "Cargo.toml";
+const HELPER_ENTRY = "src/main.rs";
+export class RustdocIntrospectorError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = "RustdocIntrospectorError";
+        this.code = code;
+        this.cause = cause;
+    }
+}
+/**
+ * Run the bundled Rust helper or load a committed snapshot, return a
+ * parsed RustdocSpec plus any diagnostics. Mode is resolved per the
+ * spec's auto fallback policy.
+ */
+export async function runIntrospector(opts) {
+    const cfg = opts.config;
+    const mode = await resolveMode(cfg, opts);
+    if (mode === "snapshot") {
+        const result = await loadSnapshot(cfg);
+        if (cfg.mode === "auto") {
+            result.diagnostics.unshift({
+                severity: "info",
+                code: RUSTDOC_DIAGNOSTIC_CODES.AUTO_FELL_BACK_TO_SNAPSHOT,
+                message: `Rustdoc auto mode did not find "${cfg.toolchain}" and used the configured snapshot.`,
+            });
+        }
+        return result;
+    }
+    return runLive(cfg, opts);
+}
+async function resolveMode(cfg, opts) {
+    if (cfg.mode === "live")
+        return "live";
+    if (cfg.mode === "snapshot") {
+        if (!cfg.snapshot) {
+            throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.NO_VIABLE_MODE, "Rustdoc adapter mode is 'snapshot' but no snapshot path was configured.");
+        }
+        return "snapshot";
+    }
+    // auto
+    const nightlyAvailable = await probeNightly(opts.rustupBinary ?? "rustup", cfg.toolchain);
+    if (nightlyAvailable)
+        return "live";
+    if (cfg.snapshot)
+        return "snapshot";
+    throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.NO_VIABLE_MODE, `Rustdoc adapter "auto" mode found neither the "${cfg.toolchain}" toolchain nor a configured snapshot. ` +
+        `Either run \`rustup toolchain install ${cfg.toolchain}\` or set { mode: "snapshot", snapshot: "./snapshots/rustdoc.json" }.`);
+}
+async function probeNightly(rustupBinary, toolchain) {
+    try {
+        const result = spawnSync(rustupBinary, ["toolchain", "list"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (result.status !== 0 || !result.stdout)
+            return false;
+        return result.stdout.split("\n").some((line) => line.includes(toolchain));
+    }
+    catch {
+        return false;
+    }
+}
+async function loadSnapshot(cfg) {
+    const snapshotPath = cfg.snapshot;
+    if (!snapshotPath) {
+        throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.NO_VIABLE_MODE, "Snapshot mode requires `snapshot` to point at a committed rustdoc.json.");
+    }
+    let raw;
+    try {
+        if (/\.gz$/i.test(snapshotPath)) {
+            const buf = await readFile(snapshotPath);
+            raw = gunzipSync(buf).toString("utf8");
+        }
+        else {
+            raw = await readFile(snapshotPath, "utf8");
+        }
+    }
+    catch (err) {
+        throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.INVALID_SNAPSHOT_SCHEMA, `Could not read snapshot at ${snapshotPath}: ${err.message}`, err);
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.INVALID_SNAPSHOT_SCHEMA, `Snapshot at ${snapshotPath} is not valid JSON: ${err.message}`, err);
+    }
+    validateSpec(spec, snapshotPath);
+    return {
+        spec,
+        diagnostics: collectDiagnostics(spec),
+        modeUsed: "snapshot",
+    };
+}
+async function runLive(cfg, opts) {
+    const helperDir = await resolveHelperDir();
+    const cargoBinary = opts.cargoBinary ?? "cargo";
+    const args = buildArgs(cfg, helperDir);
+    const { stdout, stderr, code } = await runCargo(cargoBinary, args, helperDir);
+    if (code !== 0) {
+        throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.HELPER_FAILED, `sourcey-rustdoc helper exited with code ${code}:\n${stderr.trim()}`);
+    }
+    let spec;
+    try {
+        spec = JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.HELPER_FAILED, `Could not parse helper output as JSON: ${err.message}\n` +
+            `stdout (first 200 chars): ${stdout.slice(0, 200)}`, err);
+    }
+    validateSpec(spec, "live invocation");
+    return {
+        spec,
+        diagnostics: collectDiagnostics(spec),
+        modeUsed: "live",
+    };
+}
+function buildArgs(cfg, helperDir) {
+    void helperDir;
+    const args = [
+        "run",
+        "--release",
+        "--quiet",
+        "--",
+        "--manifest",
+        cfg.manifest,
+        "--toolchain",
+        cfg.toolchain,
+        "--output",
+        "-",
+    ];
+    for (const crateName of cfg.crates) {
+        args.push("--crate", crateName);
+    }
+    if (cfg.features.all) {
+        args.push("--all-features");
+    }
+    else {
+        if (cfg.features.default === false) {
+            args.push("--no-default-features");
+        }
+        for (const feature of cfg.features.list) {
+            args.push("--features", feature);
+        }
+    }
+    if (cfg.includePrivate)
+        args.push("--include-private");
+    if (cfg.includeHidden)
+        args.push("--include-hidden");
+    if (cfg.target)
+        args.push("--target", cfg.target);
+    return args;
+}
+async function resolveHelperDir() {
+    const candidates = [PACKAGED_HELPER_DIR, DEV_HELPER_DIR];
+    for (const candidate of candidates) {
+        try {
+            await access(join(candidate, HELPER_MANIFEST));
+            await access(join(candidate, HELPER_ENTRY));
+            return candidate;
+        }
+        catch {
+            // try next
+        }
+    }
+    throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.HELPER_MISSING, "Sourcey's Rust documentation helper is missing. Checked:\n" +
+        candidates.map((c) => `- ${join(c, HELPER_ENTRY)}`).join("\n") +
+        "\nReinstall sourcey or run `npm run build`.");
+}
+function runCargo(binary, args, cwd) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        let child;
+        try {
+            child = spawn(binary, args, { cwd, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (err) {
+            rejectPromise(new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.HELPER_FAILED, `Could not launch cargo (${binary}). Install Rust from https://rustup.rs, or use mode: "snapshot" with a committed rustdoc.json.`, err));
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                rejectPromise(new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.HELPER_FAILED, `Could not launch cargo (${binary}). Install Rust from https://rustup.rs, or use mode: "snapshot" with a committed rustdoc.json.`, err));
+                return;
+            }
+            rejectPromise(new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.HELPER_FAILED, err.message, err));
+        });
+        child.on("close", (code) => {
+            resolvePromise({
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                code: code ?? -1,
+            });
+        });
+    });
+}
+function validateSpec(spec, source) {
+    if (spec.version !== SPEC_VERSION) {
+        throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.INVALID_SNAPSHOT_SCHEMA, `Rustdoc snapshot from ${source} reports version ${spec.version}; this sourcey expects ${SPEC_VERSION}.`);
+    }
+    if (!Array.isArray(spec.crates)) {
+        throw new RustdocIntrospectorError(RUSTDOC_DIAGNOSTIC_CODES.INVALID_SNAPSHOT_SCHEMA, `Rustdoc snapshot from ${source} is missing the \`crates\` array.`);
+    }
+}
+function collectDiagnostics(spec) {
+    const out = [];
+    for (const d of spec.diagnostics ?? []) {
+        out.push(d);
+    }
+    for (const c of spec.crates) {
+        for (const d of c.diagnostics) {
+            out.push({ ...d, crate_name: d.crate_name ?? c.name });
+        }
+    }
+    return out;
+}
+/** Resolved helper entry paths, exported for tests that pin runtime. */
+export const __rustdocHelperCandidatesForTests = [
+    join(PACKAGED_HELPER_DIR, HELPER_ENTRY),
+    join(DEV_HELPER_DIR, HELPER_ENTRY),
+];

package/dist/core/rustdoc-loader.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvedRustdocConfig } from "../config.js";
+import type { MarkdownPage } from "./markdown-loader.js";
+import type { SiteTab } from "./navigation.js";
+export interface RustdocLoaderDiagnostic {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    crate?: string;
+    file?: string;
+    line?: number;
+}
+export interface RustdocLoaderResult {
+    pages: Map<string, MarkdownPage>;
+    navTab: SiteTab;
+    diagnostics: RustdocLoaderDiagnostic[];
+}
+export interface RustdocSourceLinkOptions {
+    repo?: string;
+    editBranch?: string;
+    editBasePath?: string;
+}
+/** Load a rustdoc tab from the configured manifest or snapshot. */
+export declare function loadRustdocTab(config: ResolvedRustdocConfig, tabSlug: string, tabLabel: string, sourceLinks?: RustdocSourceLinkOptions): Promise<RustdocLoaderResult>;
+export declare const RUST_SEARCH_CATEGORIES: readonly ["rust function", "rust method", "rust struct", "rust enum", "rust trait", "rust trait alias", "rust type alias", "rust constant", "rust static", "rust macro", "rust proc-macro", "rust associated type", "rust associated constant", "rust module", "rust doctest", "rust re-export", "rust variant", "rust struct field", "rust union", "rust impl", "rust primitive", "rust extern type"];
+//# sourceMappingURL=rustdoc-loader.d.ts.map

package/dist/core/rustdoc-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rustdoc-loader.d.ts","sourceRoot":"","sources":["../../src/core/rustdoc-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAgC,MAAM,sBAAsB,CAAC;AACvF,OAAO,KAAK,EAAE,OAAO,EAA6B,MAAM,iBAAiB,CAAC;AAa1E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,uBAAuB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,mEAAmE;AACnE,wBAAsB,cAAc,CAClC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,wBAA6B,GACzC,OAAO,CAAC,mBAAmB,CAAC,CA0F9B;AA2ZD,eAAO,MAAM,sBAAsB,wYAuBzB,CAAC"}