@stainless-api/docs 0.1.0-beta.125 → 0.1.0-beta.127

package/shared/getProsePages.test.ts

@@ -0,0 +1,130 @@
+import type { Dirent } from 'fs';
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { join } from 'path';
+
+vi.mock('fs/promises', () => ({
+  readdir: vi.fn(),
+  readFile: vi.fn(),
+}));
+
+import { readdir, readFile } from 'fs/promises';
+import { getProsePages } from './getProsePages';
+
+const mockedReaddir = vi.mocked(readdir);
+const mockedReadFile = vi.mocked(readFile);
+
+function fakeDirent(parentPath: string, name: string, isFile = true): Dirent {
+  return {
+    name,
+    parentPath,
+    path: parentPath,
+    isFile: () => isFile,
+    isDirectory: () => !isFile,
+    isBlockDevice: () => false,
+    isCharacterDevice: () => false,
+    isFIFO: () => false,
+    isSocket: () => false,
+    isSymbolicLink: () => false,
+  } as Dirent;
+}
+
+function stubManifest(apiReferencePages: string[]) {
+  mockedReadFile.mockResolvedValue(JSON.stringify({ astroBase: '/', apiReferencePages }));
+}
+
+function stubReaddir(dirents: Dirent[]) {
+  // readdir has many overloads; cast to match the withFileTypes variant
+  mockedReaddir.mockResolvedValue(dirents as unknown as Awaited<ReturnType<typeof readdir>>);
+}
+
+describe('getProsePages', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    // Default: no manifest
+    mockedReadFile.mockRejectedValue(new Error('ENOENT'));
+  });
+
+  it('does not return API reference pages as prose when basePath is ""', async () => {
+    stubManifest(['resources/users/index.html', 'resources/users/methods/create/index.html']);
+    stubReaddir([
+      fakeDirent('/out/guides', 'intro.html'),
+      fakeDirent('/out/resources/users', 'index.html'),
+      fakeDirent('/out/resources/users/methods/create', 'index.html'),
+    ]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    // resources/users/** are API reference pages, not prose
+    expect(result).not.toContainEqual(join('/out/resources/users', 'index.html'));
+    expect(result).not.toContainEqual(join('/out/resources/users/methods/create', 'index.html'));
+    expect(result).toContainEqual(join('/out/guides', 'intro.html'));
+  });
+
+  it('returns all HTML files when no manifest exists', async () => {
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/guides', 'intro.html')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
+  });
+
+  it('returns all HTML files when manifest has empty apiReferencePages', async () => {
+    stubManifest([]);
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/guides', 'intro.html')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
+  });
+
+  it('excludes files listed in the manifest', async () => {
+    stubManifest(['api/resources/users/index.html', 'api/resources/users/methods/create/index.html']);
+    stubReaddir([
+      fakeDirent('/out', 'index.html'),
+      fakeDirent('/out/guides', 'intro.html'),
+      fakeDirent('/out/api/resources/users', 'index.html'),
+      fakeDirent('/out/api/resources/users/methods/create', 'index.html'),
+    ]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
+  });
+
+  it('excludes non-HTML files', async () => {
+    stubReaddir([
+      fakeDirent('/out', 'index.html'),
+      fakeDirent('/out', 'style.css'),
+      fakeDirent('/out', 'app.js'),
+    ]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html')]);
+  });
+
+  it('excludes directories', async () => {
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out', 'guides', false)]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html')]);
+  });
+
+  it('returns empty when all HTML files are in the manifest', async () => {
+    stubManifest(['index.html', 'resources/users/index.html']);
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/resources/users', 'index.html')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([]);
+  });
+
+  it('returns empty when output has no HTML files', async () => {
+    stubReaddir([fakeDirent('/out', 'style.css')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([]);
+  });
+});

package/shared/getProsePages.ts

@@ -1,6 +1,8 @@
-import { readdir } from 'fs/promises';
+import { readdir, readFile } from 'fs/promises';
 import { join, relative } from 'path';
 
+const MANIFEST_PATH = '_stainless/stl-manifest.json';
+
 /**
  * Get all prose pages after a build, by reading all HTML files from the
  * given output directory, and not from assets.
@@ -10,14 +12,11 @@ import { join, relative } from 'path';
  * Other astro integrations may hijack the "[...slug]" entrypoint, and any files
  * previously in the [...slug] asset map entry would be lost (this is where starlight stores
  * its prose HTML files).
+ *
+ * API reference pages are excluded using the manifest written by the API
+ * reference plugin at build time, rather than guessing based on path prefix.
  */
-export async function getProsePages({
-  apiReferenceBasePath,
-  outputBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-  outputBasePath: string;
-}): Promise<string[]> {
+export async function getProsePages({ outputBasePath }: { outputBasePath: string }): Promise<string[]> {
   const allFiles = await readdir(outputBasePath, {
     recursive: true,
     withFileTypes: true,
@@ -27,15 +26,22 @@ export async function getProsePages({
     .filter((file) => file.isFile() && file.name.endsWith('.html'))
     .map((file) => join(file.parentPath, file.name));
 
-  if (!apiReferenceBasePath) return htmlFiles;
-  // Normalize by removing leading/trailing slashes from apiReferenceBasePath
-  const normalizedApiPath = apiReferenceBasePath.replace(/^\/+/g, '').replace(/\/+$/g, '');
-  const pagesToRender = htmlFiles.filter((absPath) => {
+  const apiReferencePages = await readApiReferencePagesFromManifest(outputBasePath);
+  if (apiReferencePages.size === 0) return htmlFiles;
+
+  return htmlFiles.filter((absPath) => {
     const relPath = relative(outputBasePath, absPath);
-    // Filter out API reference pages
-    if (relPath === normalizedApiPath || relPath.startsWith(`${normalizedApiPath}/`)) return false;
-    return true;
+    return !apiReferencePages.has(relPath);
   });
+}
 
-  return pagesToRender;
+async function readApiReferencePagesFromManifest(outputBasePath: string): Promise<Set<string>> {
+  try {
+    const raw = await readFile(join(outputBasePath, MANIFEST_PATH), 'utf-8');
+    const manifest = JSON.parse(raw) as { apiReferencePages?: string[] };
+    const pages = manifest.apiReferencePages ?? [];
+    return new Set(pages);
+  } catch {
+    return new Set();
+  }
 }

package/stl-docs/index.ts

@@ -303,17 +303,17 @@ export function stainlessDocs(config: StainlessDocsUserConfig): AstroIntegration
     stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
     conditionalIntegration({
       condition: !config.experimental?.disableProseMarkdownRendering,
-      integration: stainlessDocsMarkdownRenderer({ apiReferenceBasePath }),
+      integration: stainlessDocsMarkdownRenderer(),
       reason: 'disabled by experimental config "disableProseMarkdownRendering"',
     }),
     conditionalIntegration({
       condition: !config.experimental?.disableStainlessProseIndexing,
-      integration: stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
+      integration: stainlessDocsAlgoliaProseIndexing(),
       reason: 'disabled by experimental config "disableStainlessProseIndexing"',
     }),
     conditionalIntegration({
       condition: !config.experimental?.disableStainlessProseIndexing,
-      integration: stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
+      integration: stainlessDocsVectorProseIndexing(normalizedConfig),
       reason: 'disabled by experimental config "disableStainlessProseIndexing"',
     }),
   ];

package/stl-docs/proseDocSync.ts

@@ -304,10 +304,7 @@ async function syncProseDocuments(opts: {
 
 // ─── Astro integration ──────────────────────────────────────────────
 
-export function stainlessDocsVectorProseIndexing(
-  config: NormalizedStainlessDocsConfig,
-  apiReferenceBasePath: string | null,
-): AstroIntegration {
+export function stainlessDocsVectorProseIndexing(config: NormalizedStainlessDocsConfig): AstroIntegration {
   return {
     name: 'stl-docs-prose-indexing',
     hooks: {
@@ -331,7 +328,7 @@ export function stainlessDocsVectorProseIndexing(
           return;
         }
 
-        const pages = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        const pages = await getProsePages({ outputBasePath });
         if (pages.length === 0) {
           logger.info('No prose pages found to index for vector search');
           return;

package/stl-docs/proseMarkdown/proseMarkdownIntegration.ts

@@ -6,11 +6,7 @@ import { getSharedLogger } from '../../shared/getSharedLogger';
 import { bold } from '../../shared/terminalUtils';
 import { getProsePages } from '../../shared/getProsePages';
 
-export function stainlessDocsMarkdownRenderer({
-  apiReferenceBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-}): AstroIntegration {
+export function stainlessDocsMarkdownRenderer(): AstroIntegration {
   return {
     name: 'stl-docs-md',
     hooks: {
@@ -23,7 +19,7 @@ export function stainlessDocsMarkdownRenderer({
       'astro:build:done': async ({ logger: localLogger, dir }) => {
         const logger = getSharedLogger({ fallback: localLogger });
         const outputBasePath = dir.pathname;
-        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        const pagesToRender = await getProsePages({ outputBasePath });
 
         logger.info(bold(`Building ${pagesToRender.length} Markdown pages for prose content`));
 

package/stl-docs/proseSearchIndexing.ts

@@ -174,11 +174,7 @@ export function* indexHTML(
   }
 }
 
-export function stainlessDocsAlgoliaProseIndexing({
-  apiReferenceBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-}): AstroIntegration {
+export function stainlessDocsAlgoliaProseIndexing(): AstroIntegration {
   return {
     name: 'stl-docs-prose-indexing',
     hooks: {
@@ -197,7 +193,7 @@ export function stainlessDocsAlgoliaProseIndexing({
           return;
         }
 
-        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        const pagesToRender = await getProsePages({ outputBasePath });
         logger.info(bold(`Indexing ${pagesToRender.length} prose pages for algolia search`));
 
         const objects = [];