sourcey 3.4.11 → 3.5.0

package/dist/index.js

@@ -1,18 +1,12 @@
 import { readFile } from "node:fs/promises";
-import { resolve, extname, posix } from "node:path";
-import { loadSpec } from "./core/loader.js";
-import { convertToOpenApi3 } from "./core/converter.js";
-import { parseSpec } from "./core/parser.js";
-import { normalizeSpec } from "./core/normalizer.js";
-import { normalizeMcpSpec } from "./core/mcp-normalizer.js";
+import { extname, resolve } from "node:path";
 import { buildSite as buildSiteHtml } from "./renderer/html-builder.js";
-import { tabPath } from "./config.js";
 import { loadConfig, configFromSpec } from "./config.js";
-import { loadMarkdownPage, slugFromPath } from "./core/markdown-loader.js";
-import { loadDoxygenTab } from "./core/doxygen-loader.js";
-import { buildNavFromSpec, buildNavFromPages, buildSiteNavigation } from "./core/navigation.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, } from "./site-assembly.js";
+import { toPublicPath } from "./site-url.js";
 /**
  * Build API documentation from a single OpenAPI/Swagger spec.
  * Wraps the spec in a single-tab site and renders through the modern layout.
@@ -24,275 +18,149 @@ export async function buildDocs(options) {
         outputDir: options.outputDir,
         skipWrite: options.skipWrite,
         embeddable: options.embeddable,
+        strictChangelog: options.strictChangelog,
     });
     const spec = result._specs?.values().next().value ?? createMinimalSpec();
-    return { spec, outputDir: result.outputDir, pageCount: result.pageCount };
+    return {
+        spec,
+        outputDir: result.outputDir,
+        pageCount: result.pageCount,
+        changelogDiagnostics: result.changelogDiagnostics,
+    };
 }
 export async function buildSiteDocs(options = {}) {
     const outputDir = resolve(options.outputDir ?? "dist");
     const config = options.config ?? await loadConfig(options.configDir);
-    const tabs = config.tabs;
-    const sitePages = [];
-    const siteTabs = [];
-    const specsBySlug = new Map();
-    // Load all specs (OpenAPI and MCP)
-    for (const tab of tabs) {
-        if (tab.openapi) {
-            const loaded = await loadSpec(tab.openapi);
-            const parsed = await parseSpec(loaded);
-            const openapi3 = await convertToOpenApi3(parsed);
-            const spec = normalizeSpec(openapi3);
-            specsBySlug.set(tab.slug, spec);
-        }
-        else if (tab.mcp) {
-            const { parse } = await import("mcp-parser");
-            const mcpSpec = await parse(tab.mcp);
-            const spec = normalizeMcpSpec(mcpSpec);
-            specsBySlug.set(tab.slug, spec);
-        }
-    }
-    // Primary spec for SpecContext on markdown pages
-    const primarySpec = specsBySlug.values().next().value ?? createMinimalSpec();
-    // Build SiteConfig from ResolvedConfig
+    const assembled = await assembleSite(config);
     const site = await buildSiteConfig(config);
-    // Process all tabs
-    for (const tab of tabs) {
-        if (tab.openapi || tab.mcp) {
-            const spec = specsBySlug.get(tab.slug);
-            const navTab = buildNavFromSpec(spec, tab.slug);
-            navTab.label = tab.label;
-            siteTabs.push(navTab);
-            sitePages.push({
-                outputPath: tabPath(tab.slug, "index.html"),
-                currentPage: { kind: "spec", spec },
-                spec,
-                tabSlug: tab.slug,
-                pageSlug: "introduction",
-            });
-        }
-        else if (tab.doxygen) {
-            const { pages, navTab } = await loadDoxygenTab(tab.doxygen, tab.slug, tab.label);
-            for (const [slug, page] of pages) {
-                sitePages.push({
-                    outputPath: tabPath(tab.slug, `${slug}.html`),
-                    currentPage: { kind: "markdown", markdown: page },
-                    spec: primarySpec,
-                    tabSlug: tab.slug,
-                    pageSlug: slug,
+    const sitePages = Array.from(assembled.pageMap.values());
+    const navigation = buildSiteNavigation(assembled.siteTabs);
+    enforceChangelogDiagnostics(assembled.changelogDiagnostics, options.strictChangelog);
+    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.prettyUrls === "strip") {
+        const rules = buildStripRedirectRules(sitePages, config.baseUrl);
+        if (rules)
+            extraFiles.set("_redirects", rules);
+    }
+    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;
+                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,
                 });
-            }
-            siteTabs.push(navTab);
+                page.ogImagePath = ogPath;
+                ogImages.set(ogPath, png);
+            }));
         }
-        else if (tab.groups) {
-            const pagesByPath = new Map();
-            for (const group of tab.groups) {
-                for (const rp of group.pages) {
-                    const slug = slugFromPath(rp.slug);
-                    const page = await loadMarkdownPage(rp.file, slug);
-                    pagesByPath.set(rp.slug, page);
-                    sitePages.push({
-                        outputPath: tabPath(tab.slug, `${slug}.html`),
-                        currentPage: { kind: "markdown", markdown: page },
-                        spec: primarySpec,
-                        tabSlug: tab.slug,
-                        pageSlug: slug,
-                    });
-                }
+    }
+    else {
+        const staticOg = config.ogImage;
+        if (staticOg.startsWith("http://") || staticOg.startsWith("https://") || staticOg.startsWith("data:")) {
+            for (const page of sitePages) {
+                page.ogImagePath = staticOg;
             }
-            const navTab = buildNavFromPages(tab, pagesByPath);
-            siteTabs.push(navTab);
         }
-    }
-    const navigation = buildSiteNavigation(siteTabs);
-    // Resolve internal links in markdown pages.
-    // Builds a map from every plausible href to the correct output path,
-    // then rewrites matching href attributes in each page's HTML.
-    resolveInternalLinks(sitePages, config);
-    // Build search index
-    const markdownPagesByTab = new Map();
-    for (const tab of tabs) {
-        if (tab.groups || tab.doxygen) {
-            const tabPages = sitePages
-                .filter((p) => p.tabSlug === tab.slug && p.currentPage.kind === "markdown")
-                .map((p) => p.currentPage.markdown);
-            markdownPagesByTab.set(tab.slug, tabPages);
+        else {
+            const ogPath = `_og/static${extname(staticOg) || ".png"}`;
+            extraFiles.set(ogPath, await readFile(staticOg));
+            for (const page of sitePages) {
+                page.ogImagePath = ogPath;
+            }
         }
     }
-    const searchIndex = buildSearchIndex(specsBySlug, markdownPagesByTab, navigation, "/", config.search.featured);
-    const llmsTxt = generateLlmsTxt(sitePages, navigation, site);
-    const llmsFullTxt = generateLlmsFullTxt(sitePages, navigation, site);
     if (!options.skipWrite) {
         await buildSiteHtml(sitePages, navigation, outputDir, site, {
             searchIndex,
             llmsTxt,
             llmsFullTxt,
             embeddable: options.embeddable,
+            ogImages,
+            extraFiles,
         });
     }
-    return { outputDir, pageCount: sitePages.length, _specs: specsBySlug };
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function createMinimalSpec() {
     return {
-        info: { title: "", version: "", description: "" },
-        servers: [],
-        tags: [],
-        operations: [],
-        schemas: {},
-        securitySchemes: {},
-        webhooks: [],
+        outputDir,
+        pageCount: sitePages.length,
+        changelogDiagnostics: assembled.changelogDiagnostics,
+        _specs: assembled.specsBySlug,
     };
 }
-async function buildSiteConfig(config) {
-    const logo = config.logo
-        ? {
-            light: await resolveAssetUrl(config.logo.light ?? ""),
-            dark: config.logo.dark ? await resolveAssetUrl(config.logo.dark) : undefined,
-            href: config.logo.href,
-        }
-        : undefined;
-    const customCSS = await loadCustomCSS(config.theme.css);
-    return {
-        name: config.name,
-        theme: config.theme,
-        logo: logo?.light ? logo : undefined,
-        favicon: config.favicon ? await resolveAssetUrl(config.favicon) : undefined,
-        repo: config.repo,
-        editBranch: config.editBranch,
-        editBasePath: config.editBasePath,
-        codeSamples: config.codeSamples,
-        navbar: config.navbar,
-        footer: config.footer,
-        customCSS: customCSS || undefined,
-    };
-}
-async function loadCustomCSS(paths) {
-    const parts = [];
-    for (const p of paths) {
-        parts.push(await readFile(p, "utf-8"));
+function describePageForOg(page, defaultSiteName, changelogPermalinkOg) {
+    if (page.currentPage.kind === "markdown") {
+        return {
+            title: page.currentPage.markdown.title,
+            description: page.currentPage.markdown.description || undefined,
+        };
     }
-    return parts.join("\n");
-}
-const MIME_TYPES = {
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".gif": "image/gif",
-    ".svg": "image/svg+xml",
-    ".webp": "image/webp",
-    ".ico": "image/x-icon",
-};
-async function resolveAssetUrl(pathOrUrl) {
-    if (!pathOrUrl || pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://") || pathOrUrl.startsWith("data:")) {
-        return pathOrUrl;
+    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,
+        };
     }
-    const abs = resolve(pathOrUrl);
-    const ext = extname(abs).toLowerCase();
-    const mime = MIME_TYPES[ext] ?? "application/octet-stream";
-    const data = await readFile(abs);
-    return `data:${mime};base64,${data.toString("base64")}`;
+    return { title: `${defaultSiteName} Reference` };
 }
-// ---------------------------------------------------------------------------
-// Internal link resolution
-// ---------------------------------------------------------------------------
 /**
- * Rewrite internal links in markdown page HTML to correct relative .html paths.
+ * Build Netlify/Cloudflare-Pages redirect rules that canonicalise every page onto
+ * its extensionless, slash-less URL. Emitted only when `prettyUrls === "strip"`.
  *
- * Authors write links like [Page](/slug) or [Page](/tab/slug). This pass
- * rewrites matching href values so they resolve on static file servers
- * that don't support extensionless URLs.
+ * For each page at `dir/slug/index.html` the user sees `/dir/slug`; redirect
+ * `/dir/slug/` and (for backwards compatibility with pre-rename bookmarks)
+ * `/dir/slug.html` onto it.
  */
-export function resolveInternalLinks(pages, config) {
-    // Build a map from every plausible clean path to the output path.
-    // e.g. "components" -> "components.html", "config/ref-theme-tokens" -> "config/ref-theme-tokens.html"
-    const pathMap = new Map();
-    for (const page of pages) {
-        const out = page.outputPath; // e.g. "components.html" or "config/ref-theme-tokens.html"
-        const clean = out.replace(/\.html$/, ""); // "components" or "config/ref-theme-tokens"
-        pathMap.set(clean, out);
-        if (page.currentPage.kind === "markdown" && page.currentPage.markdown?.sourcePath) {
-            const sourceClean = page.currentPage.markdown.sourcePath
-                .replace(/\\/g, "/")
-                .replace(/^\/+/, "")
-                .replace(/\.(md|mdx)$/, "");
-            pathMap.set(sourceClean, out);
-        }
-    }
-    // Repo source link base: e.g. "https://github.com/user/repo/tree/main"
-    const repoBase = config.repo?.replace(/\/$/, "");
-    const branch = config.editBranch;
-    const sourceBase = repoBase && branch ? `${repoBase}/tree/${branch}` : undefined;
+function buildStripRedirectRules(pages, baseUrl) {
+    const lines = [
+        "# Generated by Sourcey: pretty URL canonicalisation",
+    ];
+    const seen = new Set();
     for (const page of pages) {
-        if (page.currentPage.kind !== "markdown" || !page.currentPage.markdown)
+        const canonical = toPublicPath(page.outputPath, baseUrl, "strip");
+        if (canonical === "/" || canonical === "")
             continue;
-        const md = page.currentPage.markdown;
-        const pageDir = page.outputPath.includes("/")
-            ? page.outputPath.substring(0, page.outputPath.lastIndexOf("/"))
-            : "";
-        const depth = pageDir ? pageDir.split("/").length : 0;
-        const toRoot = depth > 0 ? "../".repeat(depth) : "";
-        md.html = md.html.replace(/href="([^"]+)"/g, (_match, href) => {
-            // Only rewrite internal non-anchor, non-protocol links
-            if (href.startsWith("http://") || href.startsWith("https://") || href.startsWith("#") || href.startsWith("mailto:")) {
-                return _match;
-            }
-            // Split off hash fragment
-            const [path, hash] = href.split("#", 2);
-            const hashSuffix = hash ? `#${hash}` : "";
-            // Normalize: strip leading slash, trailing slash, and markdown extension
-            const sourcePath = path.replace(/\\/g, "/");
-            const clean = sourcePath.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.(md|mdx)$/, "");
-            // Skip if already has .html extension
-            if (clean.endsWith(".html"))
-                return _match;
-            const candidates = new Set();
-            // Relative markdown links should resolve against the current page's
-            // source path, not just the built output path.
-            if (!sourcePath.startsWith("/") && md.sourcePath) {
-                const sourceDir = posix.dirname(md.sourcePath.replace(/\\/g, "/"));
-                candidates.add(posix.normalize(posix.join(sourceDir, clean)));
-            }
-            candidates.add(clean);
-            // Look up in path map — try the resolved path first, then
-            // progressively strip leading segments to handle deployment prefixes
-            // (e.g. "docs/components" → "components").
-            let target;
-            for (const initialCandidate of candidates) {
-                let candidate = initialCandidate;
-                while (!target && candidate && candidate !== ".") {
-                    target = pathMap.get(candidate);
-                    if (target)
-                        break;
-                    const slash = candidate.indexOf("/");
-                    if (slash === -1)
-                        break;
-                    candidate = candidate.substring(slash + 1);
-                }
-                if (target)
-                    break;
-            }
-            if (target) {
-                // Build relative path from this page to the target
-                const relativePath = toRoot + target;
-                return `href="${relativePath}${hashSuffix}"`;
-            }
-            // If the link contains ../ and we have a repo URL configured,
-            // resolve it relative to the markdown source file. Links to docs
-            // pages are already handled above (pathMap lookup catches them after
-            // .md stripping and prefix stripping). What remains are links to
-            // repo source code outside the docs directory.
-            if (sourceBase && href.includes("../") && md.sourcePath) {
-                const sourceDir = posix.dirname(md.sourcePath);
-                const resolved = posix.normalize(posix.join(sourceDir, path));
-                // Only rewrite if the path stays inside the repo root
-                if (!resolved.startsWith("..")) {
-                    return `href="${sourceBase}/${resolved}${hashSuffix}"`;
-                }
-            }
-            return _match;
-        });
+        if (seen.has(canonical))
+            continue;
+        seen.add(canonical);
+        // Trailing-slash variant (what the file system would naturally serve).
+        lines.push(`${canonical}/ ${canonical} 301`);
+        // Stale `.html` bookmarks from before the migration.
+        lines.push(`${canonical}.html ${canonical} 301`);
     }
+    return lines.length > 1 ? `${lines.join("\n")}\n` : null;
+}
+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 { resolveInternalLinks } from "./site-assembly.js";

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAwDA,eAAO,MAAM,IAAI,qDAyPf,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AA4DA,eAAO,MAAM,IAAI,qDAyPf,CAAC"}

package/dist/init.js

@@ -30,10 +30,14 @@ function findOpenAPISpecs(dir) {
                     specs.push(file);
                 }
             }
-            catch { }
+            catch {
+                // Ignore unreadable candidate files during spec auto-detection.
+            }
         }
     }
-    catch { }
+    catch {
+        // Ignore unreadable directories during spec auto-detection.
+    }
     return specs;
 }
 function isExistingProject(dir) {
@@ -120,7 +124,7 @@ export const init = defineCommand({
                 addOpenAPI = spec;
         }
         if (doxyfile) {
-            const useDoxygen = (await consola.prompt(`Found ${doxyfile} — add Doxygen API reference?`, {
+            const useDoxygen = (await consola.prompt(`Found ${doxyfile}. Add Doxygen API reference?`, {
                 type: "confirm",
                 initial: true,
             }));

package/dist/og/generate-og-image.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedTheme } from "../config.js";
+export interface OgImageOptions {
+    title: string;
+    description?: string;
+    siteName: string;
+    theme: ResolvedTheme;
+    logo?: string;
+}
+export declare function generateOgImage(options: OgImageOptions): Promise<Buffer>;
+//# sourceMappingURL=generate-og-image.d.ts.map

package/dist/og/generate-og-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-og-image.d.ts","sourceRoot":"","sources":["../../src/og/generate-og-image.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIlD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA4LD,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB9E"}