@sanity/ailf 0.1.0

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

@@ -0,0 +1,620 @@
+/**
+ * SanityDocFetcher — full adapter for the DocFetcher port.
+ *
+ * Fetches documentation from the Sanity Content Lake with support for:
+ * - Basic slug-based fetching (GROQ → Portable Text → Markdown)
+ * - Perspective-aware fetching (content release diffing)
+ * - Document overlays (replace/append canonical docs by document ID)
+ * - Direct URL fetching (markdown endpoints + content negotiation)
+ * - Custom HTTP headers
+ * - Document manifest (traceability: _id, _rev, slug, title)
+ * - Release impact metadata (added/modified/removed/unchanged)
+ *
+ * The pipeline step (FetchDocsStep) calls ctx.docFetcher.fetch() and
+ * writes the returned metadata to disk for downstream consumption.
+ */
+import { mkdirSync, writeFileSync } from "fs";
+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";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Escape `{{` and `}}` so Promptfoo's Nunjucks template engine doesn't
+ * try to interpret them as template variables (e.g. Vue `{{ post.title }}`
+ * in Nuxt docs would break Nunjucks parsing).
+ */
+function escapeNunjucks(text) {
+    return text.replace(/\{\{|\}\}/g, (match) => match === "{{" ? '{{ "{{" }}' : '{{ "}}" }}');
+}
+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}`;
+}
+/**
+ * Bridge DocSourceConfig (domain type) to getSanityClient overrides.
+ *
+ * DocSourceConfig is the port's domain type; the Sanity client expects
+ * its own config shape. This bridges the gap.
+ */
+function toSanityOverrides(source) {
+    if (!source)
+        return undefined;
+    const overrides = {};
+    if (source.dataset)
+        overrides.dataset = source.dataset;
+    if (source.projectId)
+        overrides.projectId = source.projectId;
+    return Object.keys(overrides).length > 0 ? overrides : undefined;
+}
+// ---------------------------------------------------------------------------
+// SanityDocFetcher
+// ---------------------------------------------------------------------------
+export class SanityDocFetcher {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async fetch(tasks, source) {
+        // 1. Collect all unique slugs and IDs across every task.
+        // ID refs are resolved to slugs via a batch query so the rest of the
+        // slug-based pipeline works unchanged.
+        const allSlugs = new Set();
+        const idRefs = [];
+        const pathRefs = [];
+        const perspectiveRefs = [];
+        for (const task of tasks) {
+            for (const ref of task.canonicalDocs) {
+                if (isSlugRef(ref)) {
+                    allSlugs.add(ref.slug);
+                }
+                else if (isIdRef(ref)) {
+                    idRefs.push({ id: ref.id, taskId: task.id });
+                }
+                else if (isPathRef(ref)) {
+                    pathRefs.push({ path: ref.path, taskId: task.id });
+                }
+                else if (isPerspectiveRef(ref)) {
+                    perspectiveRefs.push({
+                        perspective: ref.perspective,
+                        taskId: task.id,
+                    });
+                }
+                else {
+                    console.warn(`    [warn] Skipping unsupported canonical doc ref: ${canonicalDocRefLabel(ref)}`);
+                }
+            }
+        }
+        // Resolve ID refs → slugs via batch query
+        const idToSlug = await this.resolveIdRefsToSlugs(idRefs, source);
+        for (const slug of idToSlug.values()) {
+            allSlugs.add(slug);
+        }
+        // Resolve path refs → slugs
+        const pathToSlug = await this.resolvePathRefsToSlugs(pathRefs, source);
+        for (const slug of pathToSlug.values()) {
+            allSlugs.add(slug);
+        }
+        // Resolve perspective refs → slugs (one-to-many: each release expands
+        // to all articles versioned within it)
+        const perspectiveToSlugs = await this.resolvePerspectiveRefsToSlugs(perspectiveRefs, source);
+        for (const slugs of perspectiveToSlugs.values()) {
+            for (const slug of slugs) {
+                allSlugs.add(slug);
+            }
+        }
+        const metadata = {};
+        // 2. Fetch document manifest (traceability metadata)
+        const manifest = await this.fetchManifest(allSlugs, source);
+        if (manifest.length > 0) {
+            metadata.manifest = manifest;
+        }
+        // 3. Perspective diffing — identify which docs changed in the release
+        let releaseImpact;
+        if (source?.perspective) {
+            releaseImpact = await this.identifyAffectedDocs([...allSlugs], source);
+            metadata.releaseImpact = releaseImpact;
+            const affected = releaseImpact.added.length +
+                releaseImpact.modified.length +
+                releaseImpact.removed.length;
+            console.log(`  Perspective diff: ${affected} of ${allSlugs.size} canonical docs affected`);
+            if (releaseImpact.added.length > 0)
+                console.log(`    Added:    ${releaseImpact.added.join(", ")}`);
+            if (releaseImpact.modified.length > 0)
+                console.log(`    Modified: ${releaseImpact.modified.join(", ")}`);
+            if (releaseImpact.removed.length > 0)
+                console.log(`    Removed:  ${releaseImpact.removed.join(", ")}`);
+        }
+        // 4. Document overlay — resolve document IDs against canonical set
+        let documentOverlay;
+        if (source?.documentIds && source.documentIds.length > 0) {
+            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,
+                documentIds: source.documentIds,
+                replacedSlugs: [...documentOverlay.replacements.keys()],
+            };
+            metadata.documentOverlay = summary;
+            console.log(`  Document overlay: ${documentOverlay.replacements.size} replacement(s), ${documentOverlay.appendedContent.length} appended`);
+        }
+        // 5. URL content fetch — fetch direct URLs
+        const urlContent = [];
+        if (source?.urls && source.urls.length > 0) {
+            const urlFetchMeta = [];
+            console.log(`  Fetching ${source.urls.length} direct URL(s)...`);
+            for (const url of source.urls) {
+                const result = await fetchUrlContent(url, source.headers);
+                urlFetchMeta.push({
+                    contentLength: result.content?.length,
+                    error: result.error,
+                    method: result.method,
+                    status: result.status,
+                    url: result.url,
+                });
+                if (result.content) {
+                    urlContent.push(result.content);
+                    const tokens = estimateTokens(result.content);
+                    console.log(`    ✅ ${url} (via ${result.method}, ~${tokens} tokens)`);
+                }
+                else {
+                    console.warn(`    ⚠️  ${url}: ${result.error}`);
+                }
+            }
+            const fetched = urlFetchMeta.filter((m) => m.method !== "failed");
+            const failures = urlFetchMeta.filter((m) => m.method === "failed");
+            metadata.urlFetch = {
+                failures: failures.map((f) => ({ error: f.error, url: f.url })),
+                fetchedUrls: fetched,
+                totalFailed: failures.length,
+                totalFetched: fetched.length,
+            };
+        }
+        // 6. Fetch canonical docs and assemble per-task contexts
+        //
+        // Build a per-slug perspective map so each slug is fetched with the
+        // right perspective client. Sources:
+        //   a) release impact diff (added/modified slugs → source perspective)
+        //   b) perspective ref expansion (expanded slugs → ref's perspective)
+        // When both set a perspective for the same slug, the ref-level
+        // perspective wins (it's more specific).
+        const slugPerspective = new Map();
+        // Source-level perspective affects release-impacted slugs
+        if (source?.perspective) {
+            for (const slug of [
+                ...(releaseImpact?.added ?? []),
+                ...(releaseImpact?.modified ?? []),
+            ]) {
+                slugPerspective.set(slug, source.perspective);
+            }
+        }
+        // Perspective ref expansion — each slug gets its ref's perspective
+        for (const [perspectiveId, slugs] of perspectiveToSlugs) {
+            for (const slug of slugs) {
+                slugPerspective.set(slug, perspectiveId);
+            }
+        }
+        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 canonicalDir = join(this.rootDir, "contexts", "canonical");
+        mkdirSync(canonicalDir, { recursive: true });
+        const contexts = tasks.map((task) => {
+            const parts = [];
+            const slugs = [];
+            for (const ref of task.canonicalDocs) {
+                // Perspective refs expand to multiple slugs
+                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;
+                }
+                let slug;
+                if (isSlugRef(ref)) {
+                    slug = ref.slug;
+                }
+                else if (isIdRef(ref)) {
+                    slug = idToSlug.get(ref.id);
+                }
+                else if (isPathRef(ref)) {
+                    slug = pathToSlug.get(ref.path);
+                }
+                if (!slug)
+                    continue;
+                if (removedSlugs.has(slug))
+                    continue;
+                const content = contentBySlug.get(slug) ?? "";
+                if (content) {
+                    parts.push(content);
+                    slugs.push(slug);
+                }
+            }
+            // Append extra documents from overlay that didn't match canonical slugs
+            if (documentOverlay && documentOverlay.appendedContent.length > 0) {
+                parts.push(...documentOverlay.appendedContent);
+            }
+            // Append URL-fetched content
+            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");
+            return {
+                taskId: task.id,
+                content: combined,
+                slugs,
+                tokenCount: estimateTokens(combined),
+            };
+        });
+        const hasMetadata = Object.keys(metadata).length > 0;
+        return {
+            contexts,
+            ...(hasMetadata ? { metadata } : {}),
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Private: Fetch document manifest
+    // -----------------------------------------------------------------------
+    async fetchManifest(allSlugs, source) {
+        const client = source?.perspective
+            ? createPerspectiveClient(source.perspective, source)
+            : getSanityClient(toSanityOverrides(source));
+        const allMetadata = await client.fetch(ARTICLES_METADATA_BY_SLUGS_QUERY, { slugs: [...allSlugs] });
+        return allMetadata
+            .map((m) => ({ _id: m._id, _rev: m._rev, slug: m.slug, title: m.title }))
+            .sort((a, b) => a.slug.localeCompare(b.slug));
+    }
+    // -----------------------------------------------------------------------
+    // Private: Resolve ID refs to slugs
+    // -----------------------------------------------------------------------
+    /**
+     * Batch-resolve document ID refs to their article slugs.
+     *
+     * 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.
+     */
+    async resolveIdRefsToSlugs(idRefs, source) {
+        const result = new Map();
+        if (idRefs.length === 0)
+            return result;
+        const uniqueIds = [...new Set(idRefs.map((r) => r.id))];
+        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);
+            }
+            else {
+                console.warn(`    [warn] No article found for document ID "${id}" (referenced by task "${taskId}")`);
+            }
+        }
+        if (result.size > 0) {
+            console.log(`  Resolved ${result.size} document ID ref(s) to slugs`);
+        }
+        return result;
+    }
+    // -----------------------------------------------------------------------
+    // Private: Resolve path refs to slugs
+    // -----------------------------------------------------------------------
+    /**
+     * Resolve path-based canonical doc references to their article slugs.
+     *
+     * Handles two path formats:
+     * - Simple path: "webhooks" → resolves as slug lookup
+     * - Section-qualified path: "content-lake/webhooks" → matches section + slug
+     *
+     * @see docs/design-docs/canonical-doc-resolution.md
+     */
+    async resolvePathRefsToSlugs(pathRefs, source) {
+        const result = new Map();
+        if (pathRefs.length === 0)
+            return result;
+        const client = source?.perspective
+            ? createPerspectiveClient(source.perspective, source)
+            : getSanityClient(toSanityOverrides(source));
+        for (const { path, taskId } of pathRefs) {
+            const segments = path.split("/").filter(Boolean);
+            const articleSlug = segments[segments.length - 1];
+            const sectionSlug = segments.length > 1 ? segments.slice(0, -1).join("/") : undefined;
+            let article;
+            if (sectionSlug) {
+                // Section-qualified path: disambiguate by section
+                article = await client.fetch(ARTICLE_SLUG_BY_SECTION_PATH_QUERY, {
+                    articleSlug,
+                    sectionSlug,
+                });
+                if (!article) {
+                    // Fallback: try without section qualifier (section slug might differ)
+                    article = await client.fetch(ARTICLE_SLUG_BY_PATH_QUERY, { slug: articleSlug });
+                    if (article) {
+                        console.warn(`    [warn] Path "${path}" section "${sectionSlug}" didn't match (article found in section "${article.sectionSlug ?? "unknown"}")`);
+                    }
+                }
+            }
+            else {
+                // Simple path: resolve by slug directly
+                article = await client.fetch(ARTICLE_SLUG_BY_PATH_QUERY, { slug: articleSlug });
+            }
+            if (article) {
+                result.set(path, article.slug);
+            }
+            else {
+                console.warn(`    [warn] No article found for path "${path}" (referenced by task "${taskId}")`);
+            }
+        }
+        if (result.size > 0) {
+            console.log(`  Resolved ${result.size} path ref(s) to slugs`);
+        }
+        return result;
+    }
+    // -----------------------------------------------------------------------
+    // Private: Resolve perspective refs to slugs (one-to-many)
+    // -----------------------------------------------------------------------
+    /**
+     * Expand perspective canonical doc refs to the article slugs within
+     * each content release.
+     *
+     * Each perspective ref resolves to ALL article documents versioned in
+     * that release. This is the one-to-many expansion described in the
+     * canonical-doc-resolution design doc.
+     *
+     * The perspective value from the ref is used as both the release ID
+     * for the versioned document query AND the client perspective for
+     * fetching content. If a source-level perspective is also set, the
+     * ref-level perspective takes precedence for its own resolution.
+     *
+     * @see docs/design-docs/canonical-doc-resolution.md
+     */
+    async resolvePerspectiveRefsToSlugs(perspectiveRefs, source) {
+        const result = new Map();
+        if (perspectiveRefs.length === 0)
+            return result;
+        // Deduplicate by perspective ID (multiple tasks may reference the same release)
+        const uniquePerspectives = [
+            ...new Set(perspectiveRefs.map((r) => r.perspective)),
+        ];
+        for (const perspectiveId of uniquePerspectives) {
+            // Create a client with this specific perspective so versioned docs are visible
+            const client = createPerspectiveClient(perspectiveId, source);
+            const articles = await client.fetch(ARTICLES_IN_RELEASE_QUERY, { releaseId: perspectiveId });
+            if (articles.length === 0) {
+                const taskIds = perspectiveRefs
+                    .filter((r) => r.perspective === perspectiveId)
+                    .map((r) => r.taskId);
+                console.warn(`    [warn] No articles found in release "${perspectiveId}" (referenced by task(s): ${taskIds.join(", ")})`);
+                result.set(perspectiveId, []);
+                continue;
+            }
+            const slugs = articles
+                .map((a) => a.slug)
+                .filter((s) => Boolean(s));
+            result.set(perspectiveId, slugs);
+            console.log(`  Expanded perspective "${perspectiveId}" → ${slugs.length} article(s): ${slugs.join(", ")}`);
+        }
+        return result;
+    }
+    // -----------------------------------------------------------------------
+    // Private: Perspective diffing
+    // -----------------------------------------------------------------------
+    async identifyAffectedDocs(canonicalSlugs, source) {
+        if (!source.perspective) {
+            return {
+                added: [],
+                modified: [],
+                removed: [],
+                unchanged: [...canonicalSlugs],
+            };
+        }
+        const publishedClient = createPublishedClient(source);
+        const perspectiveClient = createPerspectiveClient(source.perspective, source);
+        const [publishedMeta, perspectiveMeta] = await Promise.all([
+            publishedClient.fetch(ARTICLES_METADATA_BY_SLUGS_QUERY, { slugs: canonicalSlugs }),
+            perspectiveClient.fetch(ARTICLES_METADATA_BY_SLUGS_QUERY, { slugs: canonicalSlugs }),
+        ]);
+        const publishedMap = new Map(publishedMeta.map((d) => [d.slug, d]));
+        const perspectiveMap = new Map(perspectiveMeta.map((d) => [d.slug, d]));
+        const added = [];
+        const modified = [];
+        const removed = [];
+        const unchanged = [];
+        for (const slug of canonicalSlugs) {
+            const pub = publishedMap.get(slug);
+            const persp = perspectiveMap.get(slug);
+            if (!pub && persp) {
+                added.push(slug);
+            }
+            else if (pub && !persp) {
+                removed.push(slug);
+            }
+            else if (pub && persp && pub._rev !== persp._rev) {
+                modified.push(slug);
+            }
+            else {
+                unchanged.push(slug);
+            }
+        }
+        return { added, modified, removed, unchanged };
+    }
+    // -----------------------------------------------------------------------
+    // Private: Document overlay
+    // -----------------------------------------------------------------------
+    async resolveDocumentOverlay(documentIds, canonicalSlugs, source) {
+        const overlay = {
+            appendedContent: [],
+            replacements: new Map(),
+        };
+        if (documentIds.length === 0)
+            return overlay;
+        const results = await Promise.all(documentIds.map(async (id) => {
+            const doc = await this.fetchArticleById(id, source);
+            return { doc, id };
+        }));
+        for (const { doc, id } of results) {
+            if (!doc) {
+                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}"`);
+            }
+            else {
+                overlay.appendedContent.push(content);
+                const slugInfo = doc.slug ? ` (slug: "${doc.slug}")` : "";
+                console.log(`    📄 Document ${id} → appended as additional context${slugInfo}`);
+            }
+        }
+        return overlay;
+    }
+    // -----------------------------------------------------------------------
+    // Private: Fetch individual articles
+    // -----------------------------------------------------------------------
+    async fetchArticleById(id, source) {
+        const client = source.perspective
+            ? createPerspectiveClient(source.perspective, source)
+            : getSanityClient(toSanityOverrides(source));
+        return client.fetch(ARTICLE_BY_ID_QUERY, { id });
+    }
+    async fetchArticleBySlug(slug) {
+        const client = getSanityClient();
+        const doc = await client.fetch(ARTICLE_BY_SLUG_QUERY, { slug });
+        if (!doc) {
+            console.warn(`    [warn] No article found for slug "${slug}"`);
+            return "";
+        }
+        return formatArticle(doc);
+    }
+    async fetchArticleBySlugWithPerspective(slug, source) {
+        if (!source.perspective) {
+            return this.fetchArticleBySlug(slug);
+        }
+        const client = createPerspectiveClient(source.perspective, source);
+        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 formatArticle(doc);
+    }
+    // -----------------------------------------------------------------------
+    // Private: Fetch all canonical docs with perspective/overlay awareness
+    // -----------------------------------------------------------------------
+    async fetchCanonicalDocs(allSlugs, affectedSlugs, removedSlugs, overlay, source, slugPerspective) {
+        const contentBySlug = 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));
+            }
+            else 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
+                // source-level --sanity-perspective is set.
+                const perspective = slugPerspective?.get(slug) ?? source?.perspective;
+                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);
+                }
+                else {
+                    // No perspective available — fetch from published
+                    console.log(`      Fetching: ${slug}`);
+                    const content = await this.fetchArticleBySlug(slug);
+                    contentBySlug.set(slug, content);
+                }
+            }
+            else {
+                console.log(`      Fetching: ${slug}`);
+                const content = await this.fetchArticleBySlug(slug);
+                contentBySlug.set(slug, content);
+            }
+        }
+        return contentBySlug;
+    }
+    // -----------------------------------------------------------------------
+    // Public non-port methods — opt-in CLI features
+    // -----------------------------------------------------------------------
+    /**
+     * Generate feature-area context files (one per GROQ feature area query).
+     *
+     * This is NOT part of the DocFetcher port — it's an opt-in CLI feature
+     * used by `ailf fetch-docs --include-feature-areas`.
+     */
+    async fetchFeatureAreaContexts(source) {
+        const client = getSanityClient(toSanityOverrides(source), source);
+        const contextsDir = join(this.rootDir, "contexts");
+        mkdirSync(contextsDir, { recursive: true });
+        console.log("Generating feature-area contexts...\n");
+        for (const feature of ALL_FEATURE_AREAS) {
+            const query = FEATURE_AREA_QUERIES[feature];
+            const docs = await client.fetch(query);
+            if (docs.length === 0) {
+                console.warn(`  [warn] No articles found for "${feature}"`);
+                continue;
+            }
+            const combined = docs.map(formatArticle).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`);
+        }
+    }
+    /**
+     * Generate a full corpus context file (all articles in one markdown file).
+     *
+     * This is NOT part of the DocFetcher port — it's an opt-in CLI feature
+     * used by `ailf fetch-docs --include-corpus`.
+     */
+    async fetchFullCorpus(source) {
+        const client = getSanityClient(toSanityOverrides(source), source);
+        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 outDir = join(this.rootDir, "contexts");
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(join(outDir, "full-corpus.md"), escapeNunjucks(corpus), "utf-8");
+        console.log(`  full-corpus.md: ${docs.length} articles, ~${estimateTokens(corpus)} tokens`);
+    }
+}

package/dist/adapters/eval-runners/index.d.ts

@@ -0,0 +1 @@
+export { PromptfooEvalAdapter } from "./promptfoo-eval-adapter.js";

package/dist/adapters/eval-runners/index.js

@@ -0,0 +1 @@
+export { PromptfooEvalAdapter } from "./promptfoo-eval-adapter.js";

package/dist/adapters/eval-runners/promptfoo-eval-adapter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Adapter: Run evaluation via Promptfoo CLI subprocess.
+ *
+ * This wraps the current execSync-based eval execution behind the
+ * EvalRunner port interface, enabling mock-based testing of the
+ * pipeline orchestrator.
+ */
+import type { EvalRunConfig, EvalRunner, StepResult } from "../../_vendor/ailf-core/index.d.ts";
+export declare class PromptfooEvalAdapter implements EvalRunner {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    run(config: EvalRunConfig): Promise<StepResult>;
+    extractShareUrl(outputPath: string): string | undefined;
+}