sourcey 3.4.10 → 3.5.0

package/dist/renderer/llms.js

@@ -1,8 +1,10 @@
 import { htmlId } from "../utils/html-id.js";
+import { toPublicPath } from "../site-url.js";
 export function generateLlmsTxt(pages, navigation, site) {
     const lines = [];
     const title = resolveSiteTitle(pages, site);
     const summary = resolveSiteSummary(pages, site);
+    const href = (page) => toPublicPath(page.outputPath, site.baseUrl, site.prettyUrls);
     lines.push(`# ${title}`);
     lines.push("");
     if (summary) {
@@ -19,22 +21,33 @@ export function generateLlmsTxt(pages, navigation, site) {
             if (page.currentPage.kind === "markdown" && page.currentPage.markdown) {
                 const doc = page.currentPage.markdown;
                 const desc = doc.description || excerpt(stripHtml(doc.html));
-                lines.push(`- [${doc.title}](${page.outputPath})${desc ? `: ${desc}` : ""}`);
+                lines.push(`- [${doc.title}](${href(page)})${desc ? `: ${desc}` : ""}`);
                 continue;
             }
-            const spec = page.currentPage.spec ?? page.spec;
-            const overview = spec.info.description ? firstLine(spec.info.description) : `${spec.operations.length} documented operations`;
-            lines.push(`- [${spec.info.title}](${page.outputPath})${overview ? `: ${overview}` : ""}`);
+            if (page.currentPage.kind === "changelog" && page.currentPage.changelog && !page.currentPage.changelog.permalinkVersionId) {
+                const doc = page.currentPage.changelog;
+                const desc = doc.description || excerpt(summarizeChangelog(doc));
+                lines.push(`- [${doc.title}](${href(page)})${desc ? `: ${desc}` : ""}`);
+                continue;
+            }
+            const spec = page.currentPage.kind === "spec" ? page.currentPage.spec : page.spec;
+            const overview = spec.info.summary
+                ? firstLine(spec.info.summary)
+                : spec.info.description
+                    ? firstLine(spec.info.description)
+                    : `${spec.operations.length} documented operations`;
+            lines.push(`- [${spec.info.title}](${href(page)})${overview ? `: ${overview}` : ""}`);
             for (const op of spec.operations) {
                 if (op.hidden)
                     continue;
                 const opLabel = op.summary ?? operationDisplayName(op);
                 const opSummary = [operationKind(op), firstLine(op.description)].filter(Boolean).join(" — ");
-                lines.push(`- [${opLabel}](${page.outputPath}#${operationAnchor(op)})${opSummary ? `: ${opSummary}` : ""}`);
+                lines.push(`- [${opLabel}](${href(page)}#${operationAnchor(op)})${opSummary ? `: ${opSummary}` : ""}`);
             }
         }
         lines.push("");
     }
+    appendChangelogSummary(lines, pages);
     return lines.join("\n");
 }
 export function generateLlmsFullTxt(pages, navigation, site) {
@@ -55,20 +68,25 @@ export function generateLlmsFullTxt(pages, navigation, site) {
         lines.push("");
         for (const page of tabPages) {
             if (page.currentPage.kind === "markdown" && page.currentPage.markdown) {
-                appendMarkdownPage(lines, page);
+                appendMarkdownPage(lines, page, site);
+            }
+            else if (page.currentPage.kind === "changelog" && page.currentPage.changelog && !page.currentPage.changelog.permalinkVersionId) {
+                appendChangelogPage(lines, page, site);
             }
             else {
-                appendSpecPage(lines, page);
+                appendSpecPage(lines, page, site);
             }
         }
     }
     return lines.join("\n");
 }
-function appendMarkdownPage(lines, page) {
+function appendMarkdownPage(lines, page, site) {
+    if (page.currentPage.kind !== "markdown")
+        return;
     const doc = page.currentPage.markdown;
     lines.push(`### ${doc.title}`);
     lines.push("");
-    lines.push(`Path: \`${page.outputPath}\``);
+    lines.push(`Path: \`${toPublicPath(page.outputPath, site.baseUrl, site.prettyUrls)}\``);
     lines.push("");
     if (doc.description) {
         lines.push(doc.description);
@@ -80,15 +98,73 @@ function appendMarkdownPage(lines, page) {
         lines.push("");
     }
 }
-function appendSpecPage(lines, page) {
-    const spec = page.currentPage.spec ?? page.spec;
+function appendChangelogPage(lines, page, site) {
+    if (page.currentPage.kind !== "changelog")
+        return;
+    const doc = page.currentPage.changelog;
+    lines.push(`### ${doc.title}`);
+    lines.push("");
+    lines.push(`Path: \`${toPublicPath(page.outputPath, site.baseUrl, site.prettyUrls)}\``);
+    lines.push("");
+    if (doc.description) {
+        lines.push(doc.description);
+        lines.push("");
+    }
+    for (const version of doc.changelog.versions) {
+        const heading = version.date
+            ? `${version.version ?? "Unreleased"} (${version.date})`
+            : (version.version ?? "Unreleased");
+        lines.push(`#### ${heading}`);
+        lines.push("");
+        if (version.summary) {
+            lines.push(version.summary);
+            lines.push("");
+        }
+        for (const section of version.sections) {
+            for (const entry of section.entries) {
+                lines.push(`- ${section.label}: ${entry.text}`);
+            }
+        }
+        lines.push("");
+    }
+}
+function appendChangelogSummary(lines, pages) {
+    const changelogPages = pages.filter((page) => page.currentPage.kind === "changelog" && !page.currentPage.changelog?.permalinkVersionId);
+    if (!changelogPages.length)
+        return;
+    lines.push("## Changelog");
+    lines.push("");
+    for (const page of changelogPages) {
+        if (page.currentPage.kind !== "changelog")
+            continue;
+        const doc = page.currentPage.changelog;
+        for (const version of doc.changelog.versions) {
+            const heading = version.date
+                ? `${version.version ?? "Unreleased"} (${version.date})`
+                : (version.version ?? "Unreleased");
+            lines.push(`### ${heading}`);
+            for (const section of version.sections) {
+                for (const entry of section.entries) {
+                    lines.push(`${section.label}: ${entry.text}`);
+                }
+            }
+            lines.push("");
+        }
+    }
+}
+function appendSpecPage(lines, page, site) {
+    const spec = page.currentPage.kind === "spec" ? page.currentPage.spec : page.spec;
     lines.push(`### ${spec.info.title}`);
     lines.push("");
-    lines.push(`Path: \`${page.outputPath}\``);
+    lines.push(`Path: \`${toPublicPath(page.outputPath, site.baseUrl, site.prettyUrls)}\``);
     if (spec.info.version) {
         lines.push(`Version: ${spec.info.version}`);
     }
     lines.push("");
+    if (spec.info.summary) {
+        lines.push(spec.info.summary);
+        lines.push("");
+    }
     if (spec.info.description) {
         lines.push(spec.info.description);
         lines.push("");
@@ -128,7 +204,9 @@ function appendOperation(lines, op) {
         lines.push("Parameters:");
         for (const param of op.parameters) {
             const req = param.required ? "required" : "optional";
-            const type = param.schema ? formatSchemaType(param.schema) : "unknown";
+            const type = param.schema
+                ? formatSchemaType(param.schema)
+                : firstContentSchemaType(param.content);
             const desc = param.description ? ` — ${firstLine(param.description)}` : "";
             lines.push(`- \`${param.name}\` (${param.in}, ${type}, ${req})${desc}`);
         }
@@ -160,22 +238,34 @@ function resolveSiteTitle(pages, site) {
     if (site.name && site.name !== "API Reference")
         return site.name;
     const specPages = pages.filter((page) => page.currentPage.kind === "spec");
-    if (specPages.length === 1) {
-        const spec = specPages[0].currentPage.spec ?? specPages[0].spec;
+    if (specPages.length === 1 && specPages[0].currentPage.kind === "spec") {
+        const spec = specPages[0].currentPage.spec;
         if (spec.info.title)
             return spec.info.title;
     }
-    const firstMarkdown = pages.find((page) => page.currentPage.kind === "markdown" && page.currentPage.markdown);
-    if (firstMarkdown?.currentPage.markdown?.title)
-        return firstMarkdown.currentPage.markdown.title;
+    for (const page of pages) {
+        if (page.currentPage.kind === "markdown" && page.currentPage.markdown.title) {
+            return page.currentPage.markdown.title;
+        }
+        if (page.currentPage.kind === "changelog" && page.currentPage.changelog.title) {
+            return page.currentPage.changelog.title;
+        }
+    }
     return site.name || "Documentation";
 }
 function resolveSiteSummary(pages, site) {
-    const firstMarkdown = pages.find((page) => page.currentPage.kind === "markdown" && page.currentPage.markdown?.description);
-    if (firstMarkdown?.currentPage.markdown?.description)
-        return firstMarkdown.currentPage.markdown.description;
+    for (const page of pages) {
+        if (page.currentPage.kind === "markdown" && page.currentPage.markdown.description) {
+            return page.currentPage.markdown.description;
+        }
+        if (page.currentPage.kind === "changelog" && page.currentPage.changelog.description) {
+            return page.currentPage.changelog.description;
+        }
+    }
     const firstSpec = pages.find((page) => page.currentPage.kind === "spec");
-    const spec = firstSpec ? (firstSpec.currentPage.spec ?? firstSpec.spec) : undefined;
+    const spec = firstSpec?.currentPage.kind === "spec" ? firstSpec.currentPage.spec : undefined;
+    if (spec?.info.summary)
+        return spec.info.summary;
     if (spec?.info.description)
         return spec.info.description;
     return site.name ? `${site.name} documentation generated by Sourcey.` : undefined;
@@ -201,9 +291,28 @@ function operationKind(op) {
 function operationAnchor(op) {
     return `operation-${htmlId(op.path)}-${htmlId(op.method)}`;
 }
+function summarizeChangelog(page) {
+    return page.changelog.versions
+        .slice(0, 2)
+        .flatMap((version) => version.sections.flatMap((section) => section.entries.map((entry) => entry.text)))
+        .join(" ");
+}
 function formatResponse(response) {
-    const desc = response.description ? firstLine(response.description) : "";
-    return desc ? `${response.statusCode}: ${desc}` : response.statusCode;
+    const parts = [
+        response.summary ? firstLine(response.summary) : "",
+        response.description ? firstLine(response.description) : "",
+    ].filter(Boolean);
+    return parts.length ? `${response.statusCode}: ${parts.join(" - ")}` : response.statusCode;
+}
+function firstContentSchemaType(content) {
+    if (!content)
+        return "unknown";
+    for (const [mediaType, entry] of Object.entries(content)) {
+        if (entry.schema)
+            return formatSchemaType(entry.schema);
+        return mediaType;
+    }
+    return "unknown";
 }
 function formatSchemaType(schema) {
     if (Array.isArray(schema.type))

package/dist/site-assembly.d.ts

@@ -0,0 +1,25 @@
+import type { PrettyUrls, ResolvedConfig, ResolvedTab } from "./config.js";
+import type { DocsPage } from "./core/markdown-loader.js";
+import type { SiteTab } from "./core/navigation.js";
+import type { ChangelogDiagnostic, NormalizedSpec } from "./core/types.js";
+import type { SitePage } from "./renderer/html-builder.js";
+import type { SiteConfig } from "./renderer/context.js";
+export interface SiteAssembly {
+    siteTabs: SiteTab[];
+    primarySpec: NormalizedSpec;
+    specsBySlug: Map<string, NormalizedSpec>;
+    pageMap: Map<string, SitePage>;
+    changelogDiagnostics: ChangelogDiagnostic[];
+    extraFiles: Map<string, string | Buffer>;
+}
+export declare function assembleSite(config: ResolvedConfig): Promise<SiteAssembly>;
+export declare function collectDocsPagesByTab(pageMap: Map<string, SitePage>, tabs: ResolvedTab[]): Map<string, DocsPage[]>;
+export declare function rebuildMarkdownTabNavigation(pageMap: Map<string, SitePage>, siteTabs: SiteTab[], tabs: ResolvedTab[], tabSlug: string, prettyUrls: PrettyUrls): void;
+export declare function enforceChangelogDiagnostics(diagnostics: ChangelogDiagnostic[], strictChangelog?: boolean): void;
+export declare function formatChangelogDiagnostic(diagnostic: ChangelogDiagnostic): string;
+export declare function formatChangelogFailure(diagnostic: ChangelogDiagnostic): string;
+export declare function formatChangelogDiagnostics(diagnostics: ChangelogDiagnostic[]): string[];
+export declare function buildSiteConfig(config: ResolvedConfig): Promise<SiteConfig>;
+export declare function createMinimalSpec(): NormalizedSpec;
+export declare function resolveInternalLinks(pages: SitePage[], config: ResolvedConfig): void;
+//# sourceMappingURL=site-assembly.d.ts.map

package/dist/site-assembly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-assembly.d.ts","sourceRoot":"","sources":["../src/site-assembly.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,KAAK,EAAiB,QAAQ,EAAgB,MAAM,2BAA2B,CAAC;AACvF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAA8B,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,EAAE,cAAc,CAAC;IAC5B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACzC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/B,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC1C;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAgGhF;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAC9B,IAAI,EAAE,WAAW,EAAE,GAClB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAgBzB;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,EAAE,WAAW,EAAE,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,GACrB,IAAI,CAsBN;AAED,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,mBAAmB,EAAE,EAClC,eAAe,UAAQ,GACtB,IAAI,CAYN;AAED,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,mBAAmB,GAAG,MAAM,CAIjF;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,mBAAmB,GAAG,MAAM,CAI9E;AAED,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAEvF;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA4BjF;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAUlD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAuEpF"}