sourcey 3.6.3 → 3.6.5

package/dist/index.js

@@ -1,11 +1,7 @@
-import { readFile } from "node:fs/promises";
-import { extname, resolve } from "node:path";
-import { buildSite as buildSiteHtml } from "./renderer/html-builder.js";
+import { resolve } from "node:path";
 import { loadConfig, configFromSpec } from "./config.js";
-import { buildSiteNavigation } from "./core/navigation.js";
-import { buildSearchIndex } from "./core/search-indexer.js";
-import { generateLlmsTxt, generateLlmsFullTxt } from "./renderer/llms.js";
-import { assembleSite, buildSiteConfig, collectDocsPagesByTab, createMinimalSpec, enforceChangelogDiagnostics, enforceGodocDiagnostics, enforceRustdocDiagnostics, } from "./site-assembly.js";
+import { buildSourceySite, writeSourceySite } from "./site.js";
+import { createMinimalSpec } from "./site-assembly.js";
 /**
  * Build API documentation from a single OpenAPI/Swagger spec.
  * Wraps the spec in a single-tab site and renders through the modern layout.
@@ -30,117 +26,25 @@ export async function buildDocs(options) {
 export async function buildSiteDocs(options = {}) {
     const outputDir = resolve(options.outputDir ?? "dist");
     const config = options.config ?? (await loadConfig(options.configDir));
-    const assembled = await assembleSite(config);
-    const site = await buildSiteConfig(config);
-    const sitePages = Array.from(assembled.pageMap.values());
-    const navigation = buildSiteNavigation(assembled.siteTabs);
-    enforceChangelogDiagnostics(assembled.changelogDiagnostics, options.strictChangelog);
-    enforceGodocDiagnostics(assembled.godocDiagnostics);
-    enforceRustdocDiagnostics(assembled.rustdocDiagnostics);
-    const docsPagesByTab = collectDocsPagesByTab(assembled.pageMap, config.tabs);
-    const searchIndex = buildSearchIndex(assembled.specsBySlug, docsPagesByTab, navigation, config.baseUrl || "/", config.search.featured, config.prettyUrls);
-    const llmsTxt = generateLlmsTxt(sitePages, navigation, site);
-    const llmsFullTxt = generateLlmsFullTxt(sitePages, navigation, site);
-    const extraFiles = new Map(assembled.extraFiles);
-    const ogImages = new Map();
-    if (!config.ogImage) {
-        const { generateOgImage } = await import("./og/generate-og-image.js");
-        const CONCURRENCY = 8;
-        for (let i = 0; i < sitePages.length; i += CONCURRENCY) {
-            const batch = sitePages.slice(i, i + CONCURRENCY);
-            await Promise.all(batch.map(async (page) => {
-                const ogMeta = describePageForOg(page, config.name || "API", config.changelog.ogImages);
-                if (!ogMeta)
-                    return;
-                try {
-                    const ogPath = `_og/${page.outputPath.replace(/\.html$/, ".png")}`;
-                    const png = await generateOgImage({
-                        title: ogMeta.title,
-                        description: ogMeta.description,
-                        siteName: config.name,
-                        theme: config.theme,
-                        logo: site.logo?.light,
-                    });
-                    page.ogImagePath = ogPath;
-                    ogImages.set(ogPath, png);
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    console.warn(`Sourcey: skipping OG image for ${page.outputPath}: ${message}`);
-                }
-            }));
-        }
-    }
-    else {
-        const staticOg = config.ogImage;
-        if (staticOg.startsWith("http://") ||
-            staticOg.startsWith("https://") ||
-            staticOg.startsWith("data:")) {
-            for (const page of sitePages) {
-                page.ogImagePath = staticOg;
-            }
-        }
-        else {
-            const ogPath = `_og/static${extname(staticOg) || ".png"}`;
-            extraFiles.set(ogPath, await readFile(staticOg));
-            for (const page of sitePages) {
-                page.ogImagePath = ogPath;
-            }
-        }
-    }
+    const sourceySite = await buildSourceySite({
+        config,
+        outputDir,
+        strictChangelog: options.strictChangelog,
+        generateOgImages: options.generateOgImages,
+    });
     if (!options.skipWrite) {
-        await buildSiteHtml(sitePages, navigation, outputDir, site, {
-            searchIndex,
-            llmsTxt,
-            llmsFullTxt,
-            embeddable: options.embeddable,
-            ogImages,
-            extraFiles,
-        });
+        await writeSourceySite(sourceySite, { embeddable: options.embeddable });
     }
     return {
         outputDir,
-        pageCount: sitePages.length,
-        changelogDiagnostics: assembled.changelogDiagnostics,
-        godocDiagnostics: assembled.godocDiagnostics,
-        rustdocDiagnostics: assembled.rustdocDiagnostics,
-        _specs: assembled.specsBySlug,
+        pageCount: sourceySite.pageCount,
+        changelogDiagnostics: sourceySite.changelogDiagnostics,
+        godocDiagnostics: sourceySite.godocDiagnostics,
+        rustdocDiagnostics: sourceySite.rustdocDiagnostics,
+        _specs: sourceySite.specsBySlug,
     };
 }
-function describePageForOg(page, defaultSiteName, changelogPermalinkOg) {
-    if (page.currentPage.kind === "markdown") {
-        return {
-            title: page.currentPage.markdown.title,
-            description: page.currentPage.markdown.description || undefined,
-        };
-    }
-    if (page.currentPage.kind === "changelog") {
-        const changelog = page.currentPage.changelog;
-        if (changelog.permalinkVersionId) {
-            if (!changelogPermalinkOg)
-                return null;
-            const version = changelog.changelog.versions.find((candidate) => candidate.id === changelog.permalinkVersionId);
-            if (!version)
-                return null;
-            return {
-                title: `${version.version ?? "Unreleased"} - ${changelog.title}`,
-                description: version.summary || summarizeVersion(version),
-            };
-        }
-        return {
-            title: changelog.title,
-            description: changelog.description || changelog.changelog.description,
-        };
-    }
-    return { title: `${defaultSiteName} Reference` };
-}
-function summarizeVersion(version) {
-    if (version.summary)
-        return version.summary;
-    const texts = version.sections.flatMap((section) => section.entries.map((entry) => entry.text));
-    const summary = texts.slice(0, 3).join(" ");
-    return summary || undefined;
-}
 export { defineConfig } from "./config.js";
 export { doxygen, godoc, markdown, mcp, mkdocs, openapi, rustdoc } from "./adapters/index.js";
 export { resolveInternalLinks } from "./site-assembly.js";
+export { buildSourceySite, collectSourceyWatchPaths, writeSourceySite } from "./site.js";

package/dist/renderer/static-files.d.ts

@@ -0,0 +1,6 @@
+import type { PrettyUrls } from "../site-url.js";
+export declare function outputPathFromRequestPath(pathname: string, baseUrl: string): string;
+export declare function outputPathCandidatesForRequest(pathname: string, baseUrl: string, prettyUrls: PrettyUrls): string[];
+export declare function requestPathMatchesBase(pathname: string, baseUrl: string): boolean;
+export declare function contentTypeForPath(path: string): string;
+//# sourceMappingURL=static-files.d.ts.map

package/dist/renderer/static-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-files.d.ts","sourceRoot":"","sources":["../../src/renderer/static-files.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGjD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcnF;AAED,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,GACrB,MAAM,EAAE,CAYV;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAMjF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwCvD"}

package/dist/renderer/static-files.js

@@ -0,0 +1,76 @@
+import { extname } from "node:path";
+import { normalizeBaseUrl, stripBaseUrl } from "../site-url.js";
+export function outputPathFromRequestPath(pathname, baseUrl) {
+    let path = pathname;
+    const normalizedBase = normalizeBaseUrl(baseUrl);
+    if (normalizedBase && path.startsWith(normalizedBase)) {
+        path = path.slice(normalizedBase.length);
+    }
+    try {
+        path = decodeURIComponent(path);
+    }
+    catch {
+        // Keep the raw path; a malformed escape cannot match generated output.
+    }
+    return path.replace(/^\/+/, "");
+}
+export function outputPathCandidatesForRequest(pathname, baseUrl, prettyUrls) {
+    const requestPath = stripBaseUrl(pathname, baseUrl);
+    const clean = outputPathFromRequestPath(requestPath, "");
+    if (!clean)
+        return ["index.html"];
+    if (extname(clean))
+        return [clean];
+    const candidates = prettyUrls === "strip"
+        ? [`${clean}.html`, `${clean}/index.html`]
+        : [`${clean}/index.html`, `${clean}.html`];
+    return [...candidates, clean];
+}
+export function requestPathMatchesBase(pathname, baseUrl) {
+    const normalizedBase = normalizeBaseUrl(baseUrl);
+    if (!normalizedBase)
+        return true;
+    const bareBase = normalizedBase.slice(0, -1);
+    return pathname === bareBase || pathname === normalizedBase || pathname.startsWith(normalizedBase);
+}
+export function contentTypeForPath(path) {
+    switch (extname(path).toLowerCase()) {
+        case ".css":
+            return "text/css; charset=utf-8";
+        case ".js":
+        case ".mjs":
+            return "text/javascript; charset=utf-8";
+        case ".json":
+            return "application/json; charset=utf-8";
+        case ".svg":
+            return "image/svg+xml";
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".webp":
+            return "image/webp";
+        case ".avif":
+            return "image/avif";
+        case ".ico":
+            return "image/x-icon";
+        case ".txt":
+        case ".xml":
+            return "text/plain; charset=utf-8";
+        case ".pdf":
+            return "application/pdf";
+        case ".woff":
+            return "font/woff";
+        case ".woff2":
+            return "font/woff2";
+        case ".mp4":
+            return "video/mp4";
+        case ".webm":
+            return "video/webm";
+        default:
+            return "application/octet-stream";
+    }
+}

package/dist/site.d.ts

@@ -0,0 +1,38 @@
+import type { ResolvedConfig } from "./config.js";
+import type { ChangelogDiagnostic } from "./core/types.js";
+import type { GodocLoaderDiagnostic } from "./core/godoc-loader.js";
+import type { RustdocLoaderDiagnostic } from "./core/rustdoc-loader.js";
+import type { SiteNavigation } from "./core/navigation.js";
+import type { SiteConfig } from "./renderer/context.js";
+import type { SitePage } from "./renderer/html-builder.js";
+export interface SourceySiteOptions {
+    configDir?: string;
+    config?: ResolvedConfig;
+    outputDir?: string;
+    strictChangelog?: boolean;
+    generateOgImages?: boolean;
+}
+export interface SourceySiteArtifacts {
+    config: ResolvedConfig;
+    outputDir: string;
+    site: SiteConfig;
+    navigation: SiteNavigation;
+    pages: SitePage[];
+    pageCount: number;
+    searchIndex: string;
+    llmsTxt: string;
+    llmsFullTxt: string;
+    extraFiles: Map<string, string | Buffer>;
+    ogImages: Map<string, Buffer>;
+    changelogDiagnostics: ChangelogDiagnostic[];
+    godocDiagnostics: GodocLoaderDiagnostic[];
+    rustdocDiagnostics: RustdocLoaderDiagnostic[];
+    specsBySlug: Map<string, import("./core/types.js").NormalizedSpec>;
+}
+export interface SourceySiteWriteOptions {
+    embeddable?: boolean;
+}
+export declare function buildSourceySite(options?: SourceySiteOptions): Promise<SourceySiteArtifacts>;
+export declare function writeSourceySite(site: SourceySiteArtifacts, options?: SourceySiteWriteOptions): Promise<void>;
+export declare function collectSourceyWatchPaths(config: ResolvedConfig, configPath?: string): string[];
+//# sourceMappingURL=site.d.ts.map

package/dist/site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../src/site.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,KAAK,EAAE,mBAAmB,EAA8B,MAAM,iBAAiB,CAAC;AACvF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAW3D,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,gBAAgB,EAAE,qBAAqB,EAAE,CAAC;IAC1C,kBAAkB,EAAE,uBAAuB,EAAE,CAAC;IAC9C,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,iBAAiB,EAAE,cAAc,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAiD/B;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,EACtB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,EAAE,CA0BV"}

package/dist/site.js

@@ -0,0 +1,159 @@
+import { readFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { buildSiteNavigation } from "./core/navigation.js";
+import { buildSearchIndex } from "./core/search-indexer.js";
+import { buildSite as buildSiteHtml } from "./renderer/html-builder.js";
+import { generateLlmsFullTxt, generateLlmsTxt } from "./renderer/llms.js";
+import { assembleSite, buildSiteConfig, collectDocsPagesByTab, enforceChangelogDiagnostics, enforceGodocDiagnostics, enforceRustdocDiagnostics, } from "./site-assembly.js";
+export async function buildSourceySite(options = {}) {
+    const outputDir = resolve(options.outputDir ?? "dist");
+    const config = options.config ?? (await loadConfig(options.configDir));
+    const assembled = await assembleSite(config);
+    const site = await buildSiteConfig(config);
+    const pages = Array.from(assembled.pageMap.values());
+    const navigation = buildSiteNavigation(assembled.siteTabs);
+    enforceChangelogDiagnostics(assembled.changelogDiagnostics, options.strictChangelog);
+    enforceGodocDiagnostics(assembled.godocDiagnostics);
+    enforceRustdocDiagnostics(assembled.rustdocDiagnostics);
+    const docsPagesByTab = collectDocsPagesByTab(assembled.pageMap, config.tabs);
+    const searchIndex = buildSearchIndex(assembled.specsBySlug, docsPagesByTab, navigation, config.baseUrl || "/", config.search.featured, config.prettyUrls);
+    const llmsTxt = generateLlmsTxt(pages, navigation, site);
+    const llmsFullTxt = generateLlmsFullTxt(pages, navigation, site);
+    const extraFiles = new Map(assembled.extraFiles);
+    const ogImages = new Map();
+    if (options.generateOgImages !== false) {
+        await attachOgImages(pages, config, site, extraFiles, ogImages);
+    }
+    return {
+        config,
+        outputDir,
+        site,
+        navigation,
+        pages,
+        pageCount: pages.length,
+        searchIndex,
+        llmsTxt,
+        llmsFullTxt,
+        extraFiles,
+        ogImages,
+        changelogDiagnostics: assembled.changelogDiagnostics,
+        godocDiagnostics: assembled.godocDiagnostics,
+        rustdocDiagnostics: assembled.rustdocDiagnostics,
+        specsBySlug: assembled.specsBySlug,
+    };
+}
+export async function writeSourceySite(site, options = {}) {
+    await buildSiteHtml(site.pages, site.navigation, site.outputDir, site.site, {
+        searchIndex: site.searchIndex,
+        llmsTxt: site.llmsTxt,
+        llmsFullTxt: site.llmsFullTxt,
+        embeddable: options.embeddable,
+        ogImages: site.ogImages,
+        extraFiles: site.extraFiles,
+    });
+}
+export function collectSourceyWatchPaths(config, configPath) {
+    const paths = new Set();
+    if (configPath)
+        paths.add(resolve(configPath));
+    for (const tab of config.tabs) {
+        for (const watchPath of tab.source.watchPaths ?? []) {
+            paths.add(resolve(watchPath));
+        }
+        if (tab.source.kind === "rustdoc") {
+            paths.add(resolve(tab.source.config.manifest));
+            if (tab.source.config.snapshot) {
+                paths.add(resolve(tab.source.config.snapshot));
+            }
+        }
+        if (tab.source.kind === "markdown") {
+            for (const group of tab.source.groups) {
+                for (const page of group.pages) {
+                    paths.add(resolve(page.file));
+                }
+            }
+        }
+    }
+    return Array.from(paths);
+}
+async function attachOgImages(pages, config, site, extraFiles, ogImages) {
+    if (config.ogImage) {
+        const staticOg = config.ogImage;
+        if (staticOg.startsWith("http://") ||
+            staticOg.startsWith("https://") ||
+            staticOg.startsWith("data:")) {
+            for (const page of pages) {
+                page.ogImagePath = staticOg;
+            }
+        }
+        else {
+            const ogPath = `_og/static${extname(staticOg) || ".png"}`;
+            extraFiles.set(ogPath, await readFile(staticOg));
+            for (const page of pages) {
+                page.ogImagePath = ogPath;
+            }
+        }
+        return;
+    }
+    const { generateOgImage } = await import("./og/generate-og-image.js");
+    const concurrency = 8;
+    for (let i = 0; i < pages.length; i += concurrency) {
+        const batch = pages.slice(i, i + concurrency);
+        await Promise.all(batch.map(async (page) => {
+            const ogMeta = describePageForOg(page, config.name || "API", config.changelog.ogImages);
+            if (!ogMeta)
+                return;
+            try {
+                const ogPath = `_og/${page.outputPath.replace(/\.html$/, ".png")}`;
+                const png = await generateOgImage({
+                    title: ogMeta.title,
+                    description: ogMeta.description,
+                    siteName: config.name,
+                    theme: config.theme,
+                    logo: site.logo?.light,
+                });
+                page.ogImagePath = ogPath;
+                ogImages.set(ogPath, png);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`Sourcey: skipping OG image for ${page.outputPath}: ${message}`);
+            }
+        }));
+    }
+}
+function describePageForOg(page, defaultSiteName, changelogPermalinkOg) {
+    if (page.currentPage.kind === "markdown") {
+        return {
+            title: page.currentPage.markdown.title,
+            description: page.currentPage.markdown.description || undefined,
+        };
+    }
+    if (page.currentPage.kind === "changelog") {
+        const changelog = page.currentPage.changelog;
+        if (changelog.permalinkVersionId) {
+            if (!changelogPermalinkOg)
+                return null;
+            const version = changelog.changelog.versions.find((candidate) => candidate.id === changelog.permalinkVersionId);
+            if (!version)
+                return null;
+            return {
+                title: `${version.version ?? "Unreleased"} - ${changelog.title}`,
+                description: version.summary || summarizeVersion(version),
+            };
+        }
+        return {
+            title: changelog.title,
+            description: changelog.description || changelog.changelog.description,
+        };
+    }
+    return { title: `${defaultSiteName} Reference` };
+}
+function summarizeVersion(version) {
+    if (version.summary)
+        return version.summary;
+    const texts = version.sections.flatMap((section) => section.entries.map((entry) => entry.text));
+    const summary = texts.slice(0, 3).join(" ");
+    return summary || undefined;
+}