@sanity/ailf 4.1.0 → 4.3.0

package/dist/adapters/doc-fetchers/sanity-doc-fetcher.js

@@ -18,8 +18,9 @@ import { join } from "path";
 import { canonicalDocRefLabel, isIdRef, isPathRef, isPerspectiveRef, isSlugRef, } from "../../_vendor/ailf-core/index.js";
 import { fetchUrlContent, } from "../../pipeline/fetch-url-content.js";
 import { createPerspectiveClient, createPublishedClient, getSanityClient, } from "../../sanity/client.js";
-import { toMarkdown } from "../../sanity/portable-text.js";
-import { ALL_ARTICLES_QUERY, ALL_FEATURE_AREAS, ARTICLE_BY_ID_QUERY, ARTICLE_BY_SLUG_QUERY, ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY, ARTICLE_SLUG_BY_PATH_QUERY, ARTICLE_SLUG_BY_SECTION_PATH_QUERY, ARTICLES_IN_RELEASE_QUERY, ARTICLES_METADATA_BY_SLUGS_QUERY, FEATURE_AREA_QUERIES, } from "../../sanity/queries.js";
+import { extractSymbolsForDoc, renderDocument, } from "../../sanity/document-renderers.js";
+import { mergeSymbolIndexes, renderSymbolIndex, symbolIndexTierBreakdown, } from "../../sanity/symbol-index.js";
+import { ALL_ARTICLES_QUERY, ALL_FEATURE_AREAS, ARTICLE_BY_ID_QUERY, ARTICLE_BY_SLUG_QUERY, ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY, ARTICLE_SLUG_BY_PATH_QUERY, ARTICLE_SLUG_BY_SECTION_PATH_QUERY, ARTICLES_IN_RELEASE_QUERY, ARTICLES_METADATA_BY_SLUGS_QUERY, DOCS_BY_IDS_QUERY, FEATURE_AREA_QUERIES, } from "../../sanity/queries.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -34,11 +35,14 @@ function escapeNunjucks(text) {
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
-function formatArticle(doc) {
-    const sectionLabel = doc.section ? `Section: ${doc.section.title}\n` : "";
-    const desc = doc.description ? `${doc.description}\n\n` : "";
-    const markdown = toMarkdown(doc.content ?? []);
-    return `## ${doc.title}\n\n${sectionLabel}${desc}${markdown}`;
+/**
+ * Read a `DocumentForRender` field that the GROQ projection set as a
+ * scalar string, gracefully returning `undefined` when the projection
+ * shape is empty/unexpected (defensive for partial overlay docs).
+ */
+function readString(doc, key) {
+    const value = doc[key];
+    return typeof value === "string" ? value : undefined;
 }
 /**
  * Bridge DocSourceConfig (domain type) to getSanityClient overrides.
@@ -99,9 +103,11 @@ export class SanityDocFetcher {
                 }
             }
         }
-        // Resolve ID refs → slugs via batch query
-        const idToSlug = await this.resolveIdRefsToSlugs(idRefs, source);
-        for (const slug of idToSlug.values()) {
+        // Resolve ID refs. Articles get added to allSlugs (legacy slug-flow takes
+        // over for fetch + render). Non-articles render directly via the renderer
+        // registry and bypass the slug-keyed content map.
+        const idResolution = await this.resolveIdRefs(idRefs, source);
+        for (const slug of idResolution.idToSlug.values()) {
             allSlugs.add(slug);
         }
         // Resolve path refs → slugs
@@ -118,8 +124,14 @@ export class SanityDocFetcher {
             }
         }
         const metadata = {};
-        // 2. Fetch document manifest (traceability metadata)
+        // 2. Fetch document manifest (traceability metadata). Articles flow
+        // through fetchManifest; non-article id-refs contribute their own
+        // entries from the resolution we already did above.
         const manifest = await this.fetchManifest(allSlugs, source);
+        for (const extra of idResolution.extraManifest) {
+            manifest.push(extra);
+        }
+        manifest.sort((a, b) => a.slug.localeCompare(b.slug));
         if (manifest.length > 0) {
             metadata.manifest = manifest;
         }
@@ -145,12 +157,12 @@ export class SanityDocFetcher {
             console.log(`  Resolving ${source.documentIds.length} document ID(s) against canonical set...`);
             documentOverlay = await this.resolveDocumentOverlay(source.documentIds, allSlugs, source);
             const summary = {
-                appendedCount: documentOverlay.appendedContent.length,
+                appendedCount: documentOverlay.appendedDocs.length,
                 documentIds: source.documentIds,
                 replacedSlugs: [...documentOverlay.replacements.keys()],
             };
             metadata.documentOverlay = summary;
-            console.log(`  Document overlay: ${documentOverlay.replacements.size} replacement(s), ${documentOverlay.appendedContent.length} appended`);
+            console.log(`  Document overlay: ${documentOverlay.replacements.size} replacement(s), ${documentOverlay.appendedDocs.length} appended`);
         }
         // 5. URL content fetch — fetch direct URLs
         const urlContent = [];
@@ -210,66 +222,145 @@ export class SanityDocFetcher {
         }
         const affectedSlugs = new Set(slugPerspective.keys());
         const removedSlugs = new Set(releaseImpact?.removed ?? []);
-        const contentBySlug = await this.fetchCanonicalDocs(allSlugs, affectedSlugs, removedSlugs, documentOverlay, source, slugPerspective);
-        // 7. Assemble per-task context, write files, build DocContext[]
+        const docsBySlug = await this.fetchCanonicalDocs(allSlugs, affectedSlugs, removedSlugs, documentOverlay, source, slugPerspective);
+        // 7. Assemble per-task context + symbol index. Both surfaces dispatch
+        // through the renderer registry uniformly — the slug-flow, id-ref flow,
+        // and overlay flow all produce `DocumentForRender` objects here, and the
+        // registry decides how to render Markdown and extract symbols per
+        // `_type`. Per-task assembly aggregates symbols across all references
+        // attached to the task, writes:
+        //   - `contexts/canonical/<task.id>.md` — existing rendered-doc
+        //     artifact, consumed by Promptfoo `vars.docs`.
+        //   - `contexts/canonical-symbols/<task.id>.md` — W0197 symbol-index
+        //     artifact, written only when the task produced ≥1 symbol.
+        //   - `contexts/canonical-symbols/manifest.json` — per-task manifest
+        //     listing which tasks produced indexes (with counts + tier
+        //     breakdowns). The grader-context consumer reads this manifest
+        //     to decide between symbol-index and full-doc injection.
         const canonicalDir = join(this.rootDir, "contexts", "canonical");
+        const symbolsDir = join(this.rootDir, "contexts", "canonical-symbols");
         mkdirSync(canonicalDir, { recursive: true });
-        const contexts = tasks.map((task) => {
-            const parts = [];
-            const slugs = [];
-            for (const ref of task.context?.docs ?? []) {
-                // Perspective refs expand to multiple slugs
+        mkdirSync(symbolsDir, { recursive: true });
+        const renderCtx = { fetchUrl: this.fetchAttachmentBody };
+        const renderAndExtract = async (doc) => {
+            const rendered = await renderDocument(doc, renderCtx);
+            const symbols = await extractSymbolsForDoc(doc, renderCtx);
+            return { markdown: rendered.content, symbols, slug: rendered.slug };
+        };
+        const consumeDoc = async (doc, fallbackSlug) => {
+            const { markdown, symbols, slug } = await renderAndExtract(doc);
+            if (!markdown)
+                return null;
+            return { markdown, slug: fallbackSlug ?? slug, symbols };
+        };
+        const symbolIndexManifest = [];
+        const contexts = await Promise.all(tasks.map(async (task) => {
+            // Resolve each ref to a "consumed" record (or null). Refs that
+            // hit the slug-flow / overlay path render+extract via the
+            // registry; non-article id-refs were already rendered+extracted
+            // in resolveIdRefs and live in contentById.
+            const refResolutions = await Promise.all((task.context?.docs ?? []).map(async (ref) => {
                 if (isPerspectiveRef(ref)) {
                     const expanded = perspectiveToSlugs.get(ref.perspective) ?? [];
-                    for (const slug of expanded) {
-                        if (removedSlugs.has(slug))
-                            continue;
-                        const content = contentBySlug.get(slug) ?? "";
-                        if (content) {
-                            parts.push(content);
-                            slugs.push(slug);
-                        }
-                    }
-                    continue;
+                    const docs = expanded
+                        .filter((slug) => !removedSlugs.has(slug))
+                        .map((slug) => ({ slug, doc: docsBySlug.get(slug) }))
+                        .filter((e) => e.doc !== undefined);
+                    const consumed = await Promise.all(docs.map((e) => consumeDoc(e.doc, e.slug)));
+                    return consumed.filter((c) => c !== null);
+                }
+                if (isIdRef(ref) && idResolution.contentById.has(ref.id)) {
+                    const entry = idResolution.contentById.get(ref.id);
+                    return [
+                        {
+                            markdown: entry.content,
+                            slug: entry.slug,
+                            symbols: entry.symbolIndex,
+                        },
+                    ];
                 }
                 let slug;
                 if (isSlugRef(ref)) {
                     slug = ref.slug;
                 }
                 else if (isIdRef(ref)) {
-                    slug = idToSlug.get(ref.id);
+                    slug = idResolution.idToSlug.get(ref.id);
                 }
                 else if (isPathRef(ref)) {
                     slug = pathToSlug.get(ref.path);
                 }
                 if (!slug)
-                    continue;
+                    return null;
                 if (removedSlugs.has(slug))
-                    continue;
-                const content = contentBySlug.get(slug) ?? "";
-                if (content) {
-                    parts.push(content);
-                    slugs.push(slug);
+                    return null;
+                const doc = docsBySlug.get(slug);
+                if (!doc)
+                    return null;
+                const consumed = await consumeDoc(doc, slug);
+                return consumed ? [consumed] : null;
+            }));
+            // Overlay docs (appended) flow through the same registry dispatch.
+            const overlayConsumed = [];
+            if (documentOverlay && documentOverlay.appendedDocs.length > 0) {
+                const consumed = await Promise.all(documentOverlay.appendedDocs.map((doc) => consumeDoc(doc)));
+                for (const c of consumed) {
+                    if (c)
+                        overlayConsumed.push(c);
                 }
             }
-            // Append extra documents from overlay that didn't match canonical slugs
-            if (documentOverlay && documentOverlay.appendedContent.length > 0) {
-                parts.push(...documentOverlay.appendedContent);
+            const parts = [];
+            const slugs = [];
+            const taskIndexes = [];
+            const consumed = [
+                ...refResolutions.flat().filter((c) => c !== null),
+                ...overlayConsumed,
+            ];
+            for (const c of consumed) {
+                parts.push(c.markdown);
+                slugs.push(c.slug);
+                if (c.symbols.symbols.length > 0)
+                    taskIndexes.push(c.symbols);
             }
-            // Append URL-fetched content
+            // Append URL-fetched content. URLs are raw markdown blobs from
+            // external sources (no Sanity doc shape), so they don't contribute
+            // to the per-task symbol index.
             if (urlContent.length > 0) {
                 parts.push(...urlContent);
             }
             const combined = escapeNunjucks(parts.join("\n\n---\n\n"));
             const contextPath = join(canonicalDir, `${task.id}.md`);
             writeFileSync(contextPath, combined, "utf-8");
+            // Aggregate per-task symbol index. Always emit a manifest entry —
+            // entry presence is the consumer's signal that extraction ran.
+            // The per-task .md file is only written when the index is
+            // non-empty; a missing file under an entry-present manifest is
+            // permitted (consumer treats it the same as count zero).
+            const merged = mergeSymbolIndexes(taskIndexes);
+            const tierBreakdown = symbolIndexTierBreakdown(merged);
+            const symbolsRelativePath = `contexts/canonical-symbols/${task.id}.md`;
+            if (merged.symbols.length > 0) {
+                const indexMarkdown = renderSymbolIndex(merged, task.title);
+                writeFileSync(join(symbolsDir, `${task.id}.md`), indexMarkdown, "utf-8");
+            }
+            symbolIndexManifest.push({
+                taskId: task.id,
+                path: symbolsRelativePath,
+                symbolCount: merged.symbols.length,
+                tierBreakdown,
+            });
             return {
                 taskId: task.id,
                 content: combined,
                 slugs,
                 tokenCount: estimateTokens(combined),
             };
-        });
+        }));
+        // Persist the symbol-index manifest so the literacy compiler can read
+        // it to decide between symbol-index and full-doc grader-context
+        // injection per task. Sorted for stable diffs across runs.
+        symbolIndexManifest.sort((a, b) => a.taskId.localeCompare(b.taskId));
+        writeFileSync(join(symbolsDir, "manifest.json"), JSON.stringify({ entries: symbolIndexManifest }, null, 2), "utf-8");
+        metadata.symbolIndexes = symbolIndexManifest;
         const hasMetadata = Object.keys(metadata).length > 0;
         return {
             contexts,
@@ -289,40 +380,130 @@ export class SanityDocFetcher {
             .sort((a, b) => a.slug.localeCompare(b.slug));
     }
     // -----------------------------------------------------------------------
-    // Private: Resolve ID refs to slugs
+    // Private: Resolve ID refs (type-agnostic)
     // -----------------------------------------------------------------------
     /**
-     * Batch-resolve document ID refs to their article slugs.
+     * Batch-resolve document ID refs without filtering on `_type`.
+     *
+     * Articles are routed back into the slug-flow (so manifest, perspective
+     * diffing, and overlay handling continue to work unchanged). Non-articles
+     * are rendered eagerly via the renderer registry — `typesReference` gets
+     * a high-fidelity formatter; anything else falls through to the default
+     * walker so authors can pin marketing pages, glossary entries, etc.
+     * without an AILF code change.
      *
-     * This bridges IdDocRef entries into the slug-based fetch pipeline.
-     * Articles are queried by _id and their slugs are returned for use
-     * in the existing slug-based content map.
+     * Three log shapes:
+     *   - `info` — doc rendered with the default formatter (suggests a
+     *     dedicated renderer would improve fidelity)
+     *   - `warn` — registered renderer produced empty content (W0195 AC#3)
+     *   - `warn` — id had no matching document (existed/wrong tenant/typo)
      */
-    async resolveIdRefsToSlugs(idRefs, source) {
-        const result = new Map();
+    async resolveIdRefs(idRefs, source) {
+        const idToSlug = new Map();
+        const contentById = new Map();
+        const extraManifest = [];
         if (idRefs.length === 0)
-            return result;
+            return { idToSlug, contentById, extraManifest };
         const uniqueIds = [...new Set(idRefs.map((r) => r.id))];
+        const taskByRef = new Map();
+        for (const { id, taskId } of idRefs) {
+            const existing = taskByRef.get(id) ?? [];
+            existing.push(taskId);
+            taskByRef.set(id, existing);
+        }
         const client = source?.perspective
             ? createPerspectiveClient(source.perspective, source)
             : getSanityClient(toSanityOverrides(source));
-        // Batch query: fetch slug for each document ID
-        const articles = await client.fetch(`*[_type == "article" && _id in $ids] { _id, "slug": slug.current }`, { ids: uniqueIds });
-        const idToSlugMap = new Map(articles.map((a) => [a._id, a.slug]));
-        for (const { id, taskId } of idRefs) {
-            const slug = idToSlugMap.get(id);
-            if (slug) {
-                result.set(id, slug);
+        const docs = await client.fetch(DOCS_BY_IDS_QUERY, {
+            ids: uniqueIds,
+        });
+        const docsById = new Map(docs.map((d) => [d._id, d]));
+        let articleCount = 0;
+        let highFidelity = 0;
+        let defaultFidelity = 0;
+        for (const id of uniqueIds) {
+            const taskIds = taskByRef.get(id) ?? [];
+            const doc = docsById.get(id);
+            if (!doc) {
+                console.warn(`    [warn] doc "${id}" not found (referenced by task(s): ${taskIds.join(", ")})`);
+                continue;
+            }
+            // Article id-refs flow back into the slug-keyed pipeline so manifest,
+            // perspective diff, and document overlay continue to work. The slug
+            // projection in DOCS_BY_IDS_QUERY mirrors ARTICLE_PROJECTION.
+            if (doc._type === "article") {
+                const slug = doc.slug;
+                if (typeof slug === "string" && slug.length > 0) {
+                    idToSlug.set(id, slug);
+                    articleCount += 1;
+                }
+                else {
+                    console.warn(`    [warn] article "${id}" has no slug (referenced by task(s): ${taskIds.join(", ")})`);
+                }
+                continue;
+            }
+            const renderCtx = { fetchUrl: this.fetchAttachmentBody };
+            const rendered = await renderDocument(doc, renderCtx);
+            if (!rendered.content) {
+                console.warn(`    [warn] doc "${id}" resolved as "${doc._type}" but produced empty context (referenced by task(s): ${taskIds.join(", ")})`);
+                continue;
+            }
+            const symbolIndex = await extractSymbolsForDoc(doc, renderCtx);
+            contentById.set(id, {
+                content: rendered.content,
+                slug: rendered.slug,
+                type: doc._type,
+                symbolIndex,
+            });
+            const _rev = doc._rev;
+            const title = doc.title;
+            extraManifest.push({
+                _id: doc._id,
+                _rev: typeof _rev === "string" ? _rev : "",
+                slug: rendered.slug,
+                title: typeof title === "string" ? title : `(${doc._type})`,
+            });
+            if (rendered.fidelity === "default") {
+                console.log(`    [info] doc "${id}" rendered with default formatter — a dedicated renderer for "${doc._type}" would likely improve grader fidelity`);
+                defaultFidelity += 1;
             }
             else {
-                console.warn(`    [warn] No article found for document ID "${id}" (referenced by task "${taskId}")`);
+                highFidelity += 1;
             }
         }
-        if (result.size > 0) {
-            console.log(`  Resolved ${result.size} document ID ref(s) to slugs`);
+        if (articleCount > 0) {
+            console.log(`  Resolved ${articleCount} article id ref(s) to slugs`);
         }
-        return result;
+        if (highFidelity + defaultFidelity > 0) {
+            console.log(`  Resolved ${highFidelity + defaultFidelity} non-article id ref(s) (${highFidelity} high-fidelity, ${defaultFidelity} default)`);
+        }
+        return { idToSlug, contentById, extraManifest };
     }
+    /**
+     * Fetch the raw body of a Sanity file asset URL, used by the
+     * `typesReference` renderer to inline typedoc JSON. Returns `null`
+     * on any HTTP/network failure rather than throwing — the renderer
+     * surfaces a placeholder so the rest of the context still renders.
+     *
+     * Wrapped in a 30s `AbortSignal.timeout` so a slow CDN can't hang the
+     * eval pipeline indefinitely. Timeouts surface as a single `null`
+     * return like any other fetch failure.
+     */
+    fetchAttachmentBody = async (url) => {
+        try {
+            const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+            if (!response.ok) {
+                console.warn(`    [warn] attachment fetch failed for ${url}: HTTP ${response.status}`);
+                return null;
+            }
+            return await response.text();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`    [warn] attachment fetch failed for ${url}: ${msg}`);
+            return null;
+        }
+    };
     // -----------------------------------------------------------------------
     // Private: Resolve path refs to slugs
     // -----------------------------------------------------------------------
@@ -470,7 +651,7 @@ export class SanityDocFetcher {
     // -----------------------------------------------------------------------
     async resolveDocumentOverlay(documentIds, canonicalSlugs, source) {
         const overlay = {
-            appendedContent: [],
+            appendedDocs: [],
             replacements: new Map(),
         };
         if (documentIds.length === 0)
@@ -484,16 +665,14 @@ export class SanityDocFetcher {
                 console.warn(`    [warn] No article found for document ID "${id}"`);
                 continue;
             }
-            const content = formatArticle(doc);
-            if (!content)
-                continue;
-            if (doc.slug && canonicalSlugs.has(doc.slug)) {
-                overlay.replacements.set(doc.slug, content);
-                console.log(`    📄 Document ${id} → replaces canonical doc "${doc.slug}"`);
+            const slug = readString(doc, "slug");
+            if (slug && canonicalSlugs.has(slug)) {
+                overlay.replacements.set(slug, doc);
+                console.log(`    📄 Document ${id} → replaces canonical doc "${slug}"`);
             }
             else {
-                overlay.appendedContent.push(content);
-                const slugInfo = doc.slug ? ` (slug: "${doc.slug}")` : "";
+                overlay.appendedDocs.push(doc);
+                const slugInfo = slug ? ` (slug: "${slug}")` : "";
                 console.log(`    📄 Document ${id} → appended as additional context${slugInfo}`);
             }
         }
@@ -513,9 +692,9 @@ export class SanityDocFetcher {
         const doc = await client.fetch(ARTICLE_BY_SLUG_QUERY, { slug });
         if (!doc) {
             console.warn(`    [warn] No article found for slug "${slug}"`);
-            return "";
+            return null;
         }
-        return formatArticle(doc);
+        return doc;
     }
     async fetchArticleBySlugWithPerspective(slug, source) {
         if (!source.perspective) {
@@ -525,24 +704,26 @@ export class SanityDocFetcher {
         const doc = await client.fetch(ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY, { slug });
         if (!doc) {
             console.warn(`    [warn] No article found for slug "${slug}" in perspective "${source.perspective}"`);
-            return "";
+            return null;
         }
-        return formatArticle(doc);
+        return doc;
     }
     // -----------------------------------------------------------------------
     // Private: Fetch all canonical docs with perspective/overlay awareness
     // -----------------------------------------------------------------------
     async fetchCanonicalDocs(allSlugs, affectedSlugs, removedSlugs, overlay, source, slugPerspective) {
-        const contentBySlug = new Map();
+        const docsBySlug = new Map();
         for (const slug of allSlugs) {
             if (removedSlugs.has(slug))
                 continue;
             // Check if this slug has a document overlay replacement
             if (overlay?.replacements.has(slug)) {
                 console.log(`      Fetching: ${slug} (from document overlay)`);
-                contentBySlug.set(slug, overlay.replacements.get(slug));
+                docsBySlug.set(slug, overlay.replacements.get(slug));
+                continue;
             }
-            else if (affectedSlugs.has(slug)) {
+            let doc;
+            if (affectedSlugs.has(slug)) {
                 // Use the per-slug perspective when available; fall back to
                 // source-level perspective. This ensures perspective-ref-expanded
                 // slugs are fetched from their specific release even when no
@@ -551,23 +732,22 @@ export class SanityDocFetcher {
                 if (perspective && source) {
                     const perspectiveSource = { ...source, perspective };
                     console.log(`      Fetching: ${slug} (from perspective: ${perspective})`);
-                    const content = await this.fetchArticleBySlugWithPerspective(slug, perspectiveSource);
-                    contentBySlug.set(slug, content);
+                    doc = await this.fetchArticleBySlugWithPerspective(slug, perspectiveSource);
                 }
                 else {
                     // No perspective available — fetch from published
                     console.log(`      Fetching: ${slug}`);
-                    const content = await this.fetchArticleBySlug(slug);
-                    contentBySlug.set(slug, content);
+                    doc = await this.fetchArticleBySlug(slug);
                 }
             }
             else {
                 console.log(`      Fetching: ${slug}`);
-                const content = await this.fetchArticleBySlug(slug);
-                contentBySlug.set(slug, content);
+                doc = await this.fetchArticleBySlug(slug);
             }
+            if (doc)
+                docsBySlug.set(slug, doc);
         }
-        return contentBySlug;
+        return docsBySlug;
     }
     // -----------------------------------------------------------------------
     // Public non-port methods — opt-in CLI features
@@ -590,7 +770,8 @@ export class SanityDocFetcher {
                 console.warn(`  [warn] No articles found for "${feature}"`);
                 continue;
             }
-            const combined = docs.map(formatArticle).join("\n\n---\n\n");
+            const rendered = await Promise.all(docs.map((d) => renderDocument(d, { fetchUrl: this.fetchAttachmentBody })));
+            const combined = rendered.map((r) => r.content).join("\n\n---\n\n");
             const outPath = join(contextsDir, `${feature}.md`);
             writeFileSync(outPath, escapeNunjucks(combined), "utf-8");
             console.log(`  ${feature}: ${docs.length} articles, ~${estimateTokens(combined)} tokens`);
@@ -607,16 +788,16 @@ export class SanityDocFetcher {
         const baseUrl = source?.baseUrl ?? "https://www.sanity.io/docs";
         console.log("\nGenerating full corpus...");
         const docs = await client.fetch(ALL_ARTICLES_QUERY);
-        const corpus = docs
-            .map((d) => {
-            const markdown = toMarkdown(d.content ?? []);
-            return (`## ${d.title}\n\n` +
-                // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string title should fall back to "General"
-                `Section: ${d.section?.title || "General"}\n` +
-                `URL: ${baseUrl}/${d.slug}\n\n` +
-                markdown);
-        })
-            .join("\n\n---\n\n");
+        const rendered = await Promise.all(docs.map(async (d) => {
+            const result = await renderDocument(d, {
+                fetchUrl: this.fetchAttachmentBody,
+            });
+            // Corpus output prepends the article URL line so the dataset can
+            // be consumed by RAG retrievers that key on canonical URL.
+            const slug = readString(d, "slug") ?? result.slug;
+            return `URL: ${baseUrl}/${slug}\n\n${result.content}`;
+        }));
+        const corpus = rendered.join("\n\n---\n\n");
         const outDir = join(this.rootDir, "contexts");
         mkdirSync(outDir, { recursive: true });
         writeFileSync(join(outDir, "full-corpus.md"), escapeNunjucks(corpus), "utf-8");

package/dist/adapters/index.d.ts

@@ -9,3 +9,4 @@ export { SanityDocFetcher } from "./doc-fetchers/index.js";
 export { PromptfooEvalAdapter } from "./eval-runners/index.js";
 export { ConsoleLogger, type ConsoleLoggerOptions, JsonLogger, QuietLogger, } from "./loggers/index.js";
 export { CliConfigAdapter, FileConfigAdapter } from "./config-sources/index.js";
+export { DtsPackageSurface, InMemoryPackageSurface, type DtsPackageSurfaceOptions, type PackageRootResolver, parseDtsExports, type ParsedDtsExports, } from "./package-surface/index.js";

package/dist/adapters/index.js

@@ -9,3 +9,4 @@ export { SanityDocFetcher } from "./doc-fetchers/index.js";
 export { PromptfooEvalAdapter } from "./eval-runners/index.js";
 export { ConsoleLogger, JsonLogger, QuietLogger, } from "./loggers/index.js";
 export { CliConfigAdapter, FileConfigAdapter } from "./config-sources/index.js";
+export { DtsPackageSurface, InMemoryPackageSurface, parseDtsExports, } from "./package-surface/index.js";

package/dist/adapters/package-surface/dts-package-surface.d.ts

@@ -0,0 +1,46 @@
+/**
+ * DtsPackageSurface — `PackageSurfaceResolver` adapter that reads installed
+ * package `.d.ts` files from `node_modules`.
+ *
+ * Resolution flow:
+ *   1. Find the package's root directory via the configured resolver
+ *      (default uses `createRequire` against the working directory).
+ *   2. Read its `package.json` to capture the resolved `version` and the
+ *      `.d.ts` entry path (`types`, `typings`, or `exports["."].types`).
+ *   3. Parse the entry `.d.ts` for top-level export declarations.
+ *   4. Follow ONE hop of `export * from "./relative"` re-exports — direct
+ *      siblings only, no transitive walking.
+ *   5. Cache the result by package name for the resolver's lifetime.
+ *
+ * Throws `PackageSurfaceResolverError` with a typed `reason` when the
+ * package isn't installed or its types entry can't be resolved. Callers
+ * (the W0198 preflight) catch the error and convert it into per-binding
+ * `unresolved` findings rather than `missing` deductions.
+ */
+import { type PackageSurface, type PackageSurfaceResolver } from "../../_vendor/ailf-core/index.d.ts";
+/**
+ * Resolves a package's installed root directory (the directory whose
+ * `package.json` describes it). Returns `null` when the package isn't
+ * installed in the configured lookup path.
+ */
+export type PackageRootResolver = (pkg: string) => string | null;
+export interface DtsPackageSurfaceOptions {
+    /**
+     * How to find a package's root directory. Defaults to a `createRequire`
+     * walk from `resolveFromDir` (or the current working directory).
+     * Tests pass a fixture-aware resolver so they don't depend on real
+     * `node_modules` contents.
+     */
+    resolvePackageRoot?: PackageRootResolver;
+    /**
+     * Directory whose `node_modules` chain is searched by the default
+     * resolver. Ignored when `resolvePackageRoot` is supplied.
+     */
+    resolveFromDir?: string;
+}
+export declare class DtsPackageSurface implements PackageSurfaceResolver {
+    private readonly resolveRoot;
+    private readonly cache;
+    constructor(opts?: DtsPackageSurfaceOptions);
+    resolveExports(pkg: string): Promise<PackageSurface>;
+}