@sanity/ailf 4.2.0 → 4.3.1

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

@@ -18,8 +18,8 @@ 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 { renderDocument, } from "../../sanity/document-renderers.js";
-import { toMarkdown } from "../../sanity/portable-text.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
@@ -35,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.
@@ -154,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 = [];
@@ -219,37 +222,62 @@ 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);
                 }
-                // Non-article id-refs bypass the slug-keyed content map: their
-                // rendered Markdown was produced by `resolveIdRefs` and is cached
-                // by document `_id`. Article id-refs continue to go through the
-                // slug-flow below (consistent with overlay/perspective handling).
                 if (isIdRef(ref) && idResolution.contentById.has(ref.id)) {
                     const entry = idResolution.contentById.get(ref.id);
-                    parts.push(entry.content);
-                    slugs.push(entry.slug);
-                    continue;
+                    return [
+                        {
+                            markdown: entry.content,
+                            slug: entry.slug,
+                            symbols: entry.symbolIndex,
+                        },
+                    ];
                 }
                 let slug;
                 if (isSlugRef(ref)) {
@@ -262,33 +290,77 @@ export class SanityDocFetcher {
                     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,
@@ -370,17 +442,18 @@ export class SanityDocFetcher {
                 }
                 continue;
             }
-            const rendered = await renderDocument(doc, {
-                fetchUrl: this.fetchAttachmentBody,
-            });
+            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;
@@ -411,10 +484,14 @@ export class SanityDocFetcher {
      * `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);
+            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;
@@ -574,7 +651,7 @@ export class SanityDocFetcher {
     // -----------------------------------------------------------------------
     async resolveDocumentOverlay(documentIds, canonicalSlugs, source) {
         const overlay = {
-            appendedContent: [],
+            appendedDocs: [],
             replacements: new Map(),
         };
         if (documentIds.length === 0)
@@ -588,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}`);
             }
         }
@@ -617,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) {
@@ -629,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
@@ -655,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
@@ -694,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`);
@@ -711,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>;
+}

package/dist/adapters/package-surface/dts-package-surface.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PackageSurfaceResolverError, } from "../../_vendor/ailf-core/index.js";
+import { parseDtsExports } from "./parse-dts-exports.js";
+export class DtsPackageSurface {
+    resolveRoot;
+    cache = new Map();
+    constructor(opts = {}) {
+        this.resolveRoot =
+            opts.resolvePackageRoot ??
+                makeDefaultPackageRootResolver(opts.resolveFromDir ?? process.cwd());
+    }
+    async resolveExports(pkg) {
+        const cached = this.cache.get(pkg);
+        if (cached)
+            return cached;
+        const root = this.resolveRoot(pkg);
+        if (!root) {
+            throw new PackageSurfaceResolverError("package-not-installed", pkg, `Package "${pkg}" was not resolvable from the configured lookup path.`);
+        }
+        const pkgJsonPath = join(root, "package.json");
+        if (!existsSync(pkgJsonPath)) {
+            throw new PackageSurfaceResolverError("package-not-installed", pkg, `Package "${pkg}" has no package.json at "${pkgJsonPath}".`);
+        }
+        const pkgJson = readPackageJson(pkgJsonPath, pkg);
+        const version = pkgJson.version ?? "0.0.0";
+        const typesEntry = resolveTypesEntry(pkgJson, root);
+        if (!typesEntry) {
+            throw new PackageSurfaceResolverError("types-entry-missing", pkg, `Package "${pkg}@${version}" does not declare a \`types\` entry ` +
+                `(checked package.json \`types\`, \`typings\`, and \`exports["."].types\`).`);
+        }
+        const symbols = readSurface(pkg, version, typesEntry);
+        const surface = {
+            pkg,
+            version,
+            symbols,
+        };
+        this.cache.set(pkg, surface);
+        return surface;
+    }
+}
+function readPackageJson(path, pkg) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        throw new PackageSurfaceResolverError("parse-failed", pkg, `Failed to parse "${path}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Pick the `.d.ts` entry the resolver should parse. Order:
+ *   1. `package.json#types`
+ *   2. `package.json#typings`
+ *   3. `exports["."].types` (string or object form)
+ */
+function resolveTypesEntry(pkgJson, root) {
+    const candidates = [];
+    if (typeof pkgJson.types === "string")
+        candidates.push(pkgJson.types);
+    if (typeof pkgJson.typings === "string")
+        candidates.push(pkgJson.typings);
+    const dotExport = pkgJson.exports && typeof pkgJson.exports === "object"
+        ? pkgJson.exports["."]
+        : undefined;
+    if (typeof dotExport === "string") {
+        if (dotExport.endsWith(".d.ts"))
+            candidates.push(dotExport);
+    }
+    else if (dotExport && typeof dotExport === "object") {
+        const typesField = dotExport.types;
+        if (typeof typesField === "string")
+            candidates.push(typesField);
+        else if (typesField && typeof typesField === "object") {
+            // Conditional `types` entry (rare) — pick any string leaf.
+            for (const v of Object.values(typesField)) {
+                if (typeof v === "string") {
+                    candidates.push(v);
+                    break;
+                }
+            }
+        }
+    }
+    for (const candidate of candidates) {
+        const abs = isAbsolute(candidate) ? candidate : join(root, candidate);
+        if (existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+function readSurface(pkg, version, entryPath) {
+    const names = new Set();
+    const visited = new Set();
+    const parseFile = (path, hops) => {
+        if (visited.has(path))
+            return;
+        visited.add(path);
+        let src;
+        try {
+            src = readFileSync(path, "utf-8");
+        }
+        catch (err) {
+            throw new PackageSurfaceResolverError("parse-failed", pkg, `Failed to read "${path}" for "${pkg}@${version}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const parsed = parseDtsExports(src);
+        for (const name of parsed.names)
+            names.add(name);
+        if (hops <= 0)
+            return;
+        const baseDir = dirname(path);
+        for (const spec of parsed.reExports) {
+            if (!spec.startsWith("."))
+                continue; // bare specifier — out of scope
+            const resolved = resolveRelativeDts(baseDir, spec);
+            if (resolved)
+                parseFile(resolved, hops - 1);
+        }
+    };
+    parseFile(entryPath, /* hops */ 1);
+    return [...names].sort().map((name) => ({ name, source: "types" }));
+}
+/**
+ * Resolve a relative re-export specifier to an existing `.d.ts` file.
+ * Tries `<spec>.d.ts`, `<spec>/index.d.ts`, and `<spec>` literally.
+ */
+function resolveRelativeDts(baseDir, spec) {
+    const base = resolve(baseDir, spec);
+    const candidates = [
+        base.endsWith(".d.ts") ? base : null,
+        `${base}.d.ts`,
+        join(base, "index.d.ts"),
+    ].filter((p) => p !== null);
+    for (const path of candidates) {
+        if (existsSync(path))
+            return path;
+    }
+    return null;
+}
+function makeDefaultPackageRootResolver(fromDir) {
+    // `createRequire` needs a file URL or path that ends with a slash so
+    // it knows it's a directory, not a file.
+    const anchor = fromDir.endsWith("/") ? fromDir : `${fromDir}/`;
+    const req = createRequire(pathToFileURL(anchor));
+    return (pkg) => {
+        try {
+            const pkgJsonPath = req.resolve(`${pkg}/package.json`);
+            return dirname(pkgJsonPath);
+        }
+        catch {
+            return null;
+        }
+    };
+}

package/dist/adapters/package-surface/in-memory-package-surface.d.ts

@@ -0,0 +1,15 @@
+/**
+ * InMemoryPackageSurface — `PackageSurfaceResolver` test double.
+ *
+ * Backed by a plain `Map<string, PackageSurface>`; calls for unknown
+ * packages throw the same `package-not-installed` error the
+ * `DtsPackageSurface` adapter throws, so test scenarios for the
+ * `unresolved` path need no special handling.
+ */
+import { type PackageSurface, type PackageSurfaceResolver } from "../../_vendor/ailf-core/index.d.ts";
+export declare class InMemoryPackageSurface implements PackageSurfaceResolver {
+    private readonly surfaces;
+    constructor(surfaces?: Iterable<PackageSurface>);
+    set(surface: PackageSurface): void;
+    resolveExports(pkg: string): Promise<PackageSurface>;
+}