@sanity/ailf 0.1.0

package/dist/lib/compare.js

@@ -0,0 +1,170 @@
+/**
+ * compare.ts
+ *
+ * CLI for structured comparison between two evaluation runs.
+ *
+ * Usage:
+ *   pnpm compare                                # compare current vs latest baseline
+ *   pnpm compare --baseline <path>              # compare current vs specific file
+ *   pnpm compare --baseline <path> --experiment <path>  # compare two specific files
+ *   pnpm compare --threshold 5                  # custom noise threshold
+ *   pnpm compare --output /tmp/comparison.json  # write JSON report to file
+ *   pnpm compare --format json                  # output raw JSON (default: table)
+ *
+ * Reads: results/latest/score-summary.json (as experiment, unless --experiment)
+ * Reads: results/baselines/<latest>.json (as baseline, unless --baseline)
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { formatComparisonTable, } from "../_vendor/ailf-core/index.js";
+import { compare } from "../pipeline/compare.js";
+import { DEFAULT_NOISE_THRESHOLD, } from "../pipeline/types.js";
+// Re-export pure formatters from core for backward compatibility.
+export { formatComparisonMarkdown, formatComparisonTable, } from "../_vendor/ailf-core/index.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..", "..");
+const BASELINES_DIR = join(ROOT, "results", "baselines");
+const SCORE_SUMMARY_PATH = join(ROOT, "results", "latest", "score-summary.json");
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+function getFlag(name) {
+    return args.includes(`--${name}`);
+}
+function getOption(name) {
+    const idx = args.indexOf(`--${name}`);
+    return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+const baselinePath = getOption("baseline");
+const experimentPath = getOption("experiment");
+const thresholdStr = getOption("threshold");
+const threshold = thresholdStr
+    ? parseFloat(thresholdStr)
+    : DEFAULT_NOISE_THRESHOLD;
+const outputPath = getOption("output");
+const format = getOption("format") ?? "table";
+const showHelp = getFlag("help") || getFlag("h");
+if (showHelp) {
+    console.log(`
+Usage: pnpm compare [options]
+
+Compare two evaluation score summaries and produce structured deltas.
+
+Options:
+  --baseline <path>     Baseline score-summary.json (default: latest baseline)
+  --experiment <path>   Experiment score-summary.json (default: results/latest/score-summary.json)
+  --threshold <n>       Noise threshold for unchanged classification (default: ${DEFAULT_NOISE_THRESHOLD})
+  --output <path>       Write JSON report to file
+  --format <fmt>        Output format: table (default) or json
+  --help, -h            Show this help
+
+Examples:
+  pnpm compare                           # current scores vs latest baseline
+  pnpm compare --threshold 5             # wider noise band
+  pnpm compare --format json             # machine-readable output
+  pnpm compare --baseline results/baselines/20260310_02_43_44.json
+  pnpm compare --baseline before.json --experiment after.json
+`);
+    process.exit(0);
+}
+// ---------------------------------------------------------------------------
+// File loading helpers
+// ---------------------------------------------------------------------------
+/**
+ * formatComparisonMarkdown — re-exported from @sanity/ailf-core above.
+ * formatComparisonTable — re-exported from @sanity/ailf-core above.
+ */
+function findLatestBaseline() {
+    if (!existsSync(BASELINES_DIR))
+        return null;
+    const files = readdirSync(BASELINES_DIR)
+        .filter((f) => f.endsWith(".json"))
+        .sort()
+        .reverse();
+    return files.length > 0 ? join(BASELINES_DIR, files[0]) : null;
+}
+function loadSummary(path) {
+    if (!existsSync(path)) {
+        console.error(`❌ File not found: ${path}`);
+        process.exit(1);
+    }
+    const raw = readFileSync(path, "utf-8");
+    return JSON.parse(raw);
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+export function main() {
+    // Resolve experiment path
+    const expPath = experimentPath ?? SCORE_SUMMARY_PATH;
+    const experiment = loadSummary(expPath);
+    // Resolve baseline path
+    let basePath;
+    if (baselinePath) {
+        basePath = resolve(baselinePath);
+    }
+    else {
+        const latest = findLatestBaseline();
+        if (!latest) {
+            console.error("❌ No baselines found. Run 'pnpm baseline:save' first, or use --baseline <path>.");
+            process.exit(1);
+        }
+        basePath = latest;
+    }
+    const baseline = loadSummary(basePath);
+    // Try to load grader consistency data for empirical thresholds
+    const consistencyPath = join(ROOT, "results", "latest", "grader-consistency.json");
+    let graderConsistency;
+    if (existsSync(consistencyPath) && !thresholdStr) {
+        try {
+            const consistencyRaw = JSON.parse(readFileSync(consistencyPath, "utf-8"));
+            if (consistencyRaw.recommendedThreshold && consistencyRaw.perDimension) {
+                graderConsistency =
+                    consistencyRaw;
+                console.log(`  📊 Using empirical noise threshold: ±${graderConsistency.recommendedThreshold.toFixed(1)} (from grader consistency data)`);
+            }
+        }
+        catch {
+            // Non-fatal — fall back to default threshold
+        }
+    }
+    console.log(`  Baseline:   ${basePath}`);
+    console.log(`  Experiment: ${expPath}`);
+    if (!graderConsistency) {
+        console.log(`  Threshold:  ±${threshold} (default — run --grader-replications for empirical threshold)`);
+    }
+    console.log("");
+    const report = compare(baseline, experiment, {
+        graderConsistency,
+        noiseThreshold: threshold,
+    });
+    if (format === "json") {
+        const json = JSON.stringify(report, null, 2);
+        if (outputPath) {
+            writeFileSync(outputPath, json);
+            console.log(`  ✅ Comparison report written to ${outputPath}`);
+        }
+        else {
+            console.log(json);
+        }
+    }
+    else {
+        const table = formatComparisonTable(report);
+        console.log(table);
+        if (outputPath) {
+            const json = JSON.stringify(report, null, 2);
+            writeFileSync(outputPath, json);
+            console.log(`  ✅ Comparison report also written to ${outputPath}`);
+        }
+    }
+    // Write comparison report to results/latest for other steps to consume
+    const latestComparisonPath = join(ROOT, "results", "latest", "comparison-report.json");
+    writeFileSync(latestComparisonPath, JSON.stringify(report, null, 2));
+}
+// Only run when invoked directly
+if (process.argv[1]?.endsWith("compare.ts") ||
+    process.argv[1]?.endsWith("compare.js")) {
+    main();
+}

package/dist/lib/coverage-audit.d.ts

@@ -0,0 +1,4 @@
+export { countReferencedDocs, countTasksByArea, formatCoverageConsole, formatCoverageMarkdown, loadFeatureRegistry, runCoverageAudit, } from "../pipeline/coverage-audit.js";
+export type { CoverageAuditReport, ProductFeature } from "../pipeline/types.js";
+/** @deprecated Use pipeline functions directly with explicit rootDir */
+export declare function main(): void;

package/dist/lib/coverage-audit.js

@@ -0,0 +1,42 @@
+/**
+ * lib/coverage-audit.ts — DEPRECATED re-export shim.
+ * @deprecated Import from ../pipeline/coverage-audit.js instead.
+ */
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+export { countReferencedDocs, countTasksByArea, formatCoverageConsole, formatCoverageMarkdown, loadFeatureRegistry, runCoverageAudit, } from "../pipeline/coverage-audit.js";
+import { countReferencedDocs, formatCoverageConsole, formatCoverageMarkdown, runCoverageAudit, } from "../pipeline/coverage-audit.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "../..");
+/** @deprecated Use pipeline functions directly with explicit rootDir */
+export function main() {
+    const args = process.argv.slice(2);
+    const formatArg = args.includes("--format")
+        ? args[args.indexOf("--format") + 1]
+        : undefined;
+    const jsonOutput = args.includes("--json");
+    const report = runCoverageAudit(ROOT);
+    if (!report) {
+        console.error("❌ Coverage audit failed.");
+        process.exit(1);
+    }
+    if (jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else if (formatArg === "md" || formatArg === "markdown") {
+        console.log(formatCoverageMarkdown(report));
+    }
+    else {
+        console.log(formatCoverageConsole(report));
+    }
+    if (!jsonOutput && formatArg !== "md") {
+        const docStats = countReferencedDocs(ROOT);
+        console.log("DOCUMENT UTILIZATION:");
+        console.log(`  ${docStats.total} unique document slugs referenced across evaluation tasks`);
+        console.log("");
+    }
+}
+if (process.argv[1]?.endsWith("coverage-audit.ts") ||
+    process.argv[1]?.endsWith("coverage-audit.js")) {
+    main();
+}

package/dist/lib/discovery-report.d.ts

@@ -0,0 +1,13 @@
+/**
+ * lib/discovery-report.ts — DEPRECATED re-export shim.
+ *
+ * The real implementation has moved to pipeline/discovery-report.ts.
+ *
+ * @deprecated Import from ../pipeline/discovery-report.js instead.
+ */
+export { formatDiscoveryMarkdown, generateDiscoveryReport, type DiscoveryReport, type InvisibleDoc, } from "../pipeline/discovery-report.js";
+/**
+ * Legacy main() entry point.
+ * @deprecated Use generateDiscoveryReport() + formatDiscoveryMarkdown() directly.
+ */
+export declare function main(): void;

package/dist/lib/discovery-report.js

@@ -0,0 +1,57 @@
+/**
+ * lib/discovery-report.ts — DEPRECATED re-export shim.
+ *
+ * The real implementation has moved to pipeline/discovery-report.ts.
+ *
+ * @deprecated Import from ../pipeline/discovery-report.js instead.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export { formatDiscoveryMarkdown, generateDiscoveryReport, } from "../pipeline/discovery-report.js";
+import { formatDiscoveryMarkdown, generateDiscoveryReport, } from "../pipeline/discovery-report.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..", "..");
+/**
+ * Legacy main() entry point.
+ * @deprecated Use generateDiscoveryReport() + formatDiscoveryMarkdown() directly.
+ */
+export function main() {
+    const args = process.argv.slice(2);
+    let output;
+    const areaFilter = [];
+    let summaryPath = join(ROOT, "results", "latest", "score-summary.json");
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--output" && args[i + 1]) {
+            output = args[++i];
+        }
+        else if (args[i] === "--area" && args[i + 1]) {
+            areaFilter.push(...args[++i].split(","));
+        }
+        else if (args[i] === "--input" && args[i + 1]) {
+            summaryPath = args[++i];
+        }
+        else if (!args[i].startsWith("-")) {
+            summaryPath = args[i];
+        }
+    }
+    if (!existsSync(summaryPath)) {
+        console.error(`❌ Score summary not found: ${summaryPath}`);
+        console.error("Run an agentic evaluation first: pnpm pipeline -- --mode agentic");
+        process.exit(1);
+    }
+    const summary = JSON.parse(readFileSync(summaryPath, "utf-8"));
+    const report = generateDiscoveryReport(summary, areaFilter.length > 0 ? areaFilter : undefined);
+    const markdown = formatDiscoveryMarkdown(report);
+    if (output) {
+        writeFileSync(output, markdown, "utf-8");
+        console.log(`✅ Discovery report written to ${output}`);
+    }
+    else {
+        console.log(markdown);
+    }
+}
+if (process.argv[1]?.endsWith("discovery-report.ts") ||
+    process.argv[1]?.endsWith("discovery-report.js")) {
+    main();
+}

package/dist/lib/fetch-docs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Fetch-docs.ts — CLI entry point for documentation fetching.
+ *
+ * This is a standalone script for direct CLI invocation:
+ *   npx tsx src/lib/fetch-docs.ts [--source name] [--include-feature-areas] [--include-corpus]
+ *
+ * The pipeline uses ctx.docFetcher (SanityDocFetcher adapter) directly via
+ * FetchDocsStep — this file is NOT called by the pipeline.
+ *
+ * Capabilities:
+ *   1. Canonical contexts     — delegates to SanityDocFetcher adapter (always)
+ *   2. Feature-area contexts  — one file per GROQ feature area query
+ *      (opt-in via --include-feature-areas)
+ *   3. Full corpus            — all articles in one file
+ *      (opt-in via --include-corpus)
+ */
+import "dotenv/config";
+import { type ResolvedSourceConfig } from "../sources.js";
+/** Options for the fetch-docs main() function. */
+export interface FetchDocsOptions {
+    /** Fetch full corpus (for retrieval experiments) */
+    includeCorpus?: boolean;
+    /** Fetch feature-area contexts in addition to canonical contexts */
+    includeFeatureAreas?: boolean;
+    /** Pre-resolved source config (skips loadSource() call) */
+    resolvedSource?: ResolvedSourceConfig;
+    /** Documentation source name (e.g., "branch", "local") */
+    source?: string;
+}
+export declare function main(options?: FetchDocsOptions): Promise<void>;

package/dist/lib/fetch-docs.js

@@ -0,0 +1,171 @@
+/**
+ * Fetch-docs.ts — CLI entry point for documentation fetching.
+ *
+ * This is a standalone script for direct CLI invocation:
+ *   npx tsx src/lib/fetch-docs.ts [--source name] [--include-feature-areas] [--include-corpus]
+ *
+ * The pipeline uses ctx.docFetcher (SanityDocFetcher adapter) directly via
+ * FetchDocsStep — this file is NOT called by the pipeline.
+ *
+ * Capabilities:
+ *   1. Canonical contexts     — delegates to SanityDocFetcher adapter (always)
+ *   2. Feature-area contexts  — one file per GROQ feature area query
+ *      (opt-in via --include-feature-areas)
+ *   3. Full corpus            — all articles in one file
+ *      (opt-in via --include-corpus)
+ */
+// oxlint-disable-next-line import/no-unassigned-import -- side-effect: loads .env into process.env
+import "dotenv/config";
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { SanityDocFetcher } from "../adapters/doc-fetchers/sanity-doc-fetcher.js";
+import { YamlTaskSource } from "../adapters/task-sources/index.js";
+import { getSanityClient } from "../sanity/client.js";
+import { toMarkdown } from "../sanity/portable-text.js";
+import { ALL_ARTICLES_QUERY, ALL_FEATURE_AREAS, FEATURE_AREA_QUERIES, } from "../sanity/queries.js";
+import { loadSource } from "../sources.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const ROOT = join(dirname(new URL(import.meta.url).pathname), "..", "..");
+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}`;
+}
+// ---------------------------------------------------------------------------
+// Feature-area contexts (opt-in, not part of the port)
+// ---------------------------------------------------------------------------
+async function generateFeatureAreaContexts(source) {
+    const client = getSanityClient(undefined, source);
+    const contextsDir = join(ROOT, "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));
+        console.log(`  ${feature}: ${docs.length} articles, ~${estimateTokens(combined)} tokens`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Full corpus (opt-in, not part of the port)
+// ---------------------------------------------------------------------------
+async function generateFullCorpus(source) {
+    const client = getSanityClient(undefined, source);
+    console.log("\nGenerating full corpus...");
+    const docs = await client.fetch(ALL_ARTICLES_QUERY);
+    const corpus = docs
+        .map((d) => {
+        const ptBlocks = d.content ?? [];
+        const markdown = toMarkdown(ptBlocks);
+        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: ${source.baseUrl}/${d.slug}\n\n` +
+            markdown);
+    })
+        .join("\n\n---\n\n");
+    const outDir = join(ROOT, "contexts");
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, "full-corpus.md"), escapeNunjucks(corpus));
+    console.log(`  full-corpus.md: ${docs.length} articles, ~${estimateTokens(corpus)} tokens`);
+}
+export async function main(options) {
+    console.log("=== ai-literacy-framework — Documentation Fetcher ===\n");
+    const args = process.argv.slice(2);
+    // Options win over argv (backward compatible)
+    const includeFeatureAreas = options?.includeFeatureAreas ?? args.includes("--include-feature-areas");
+    const includeCorpus = options?.includeCorpus ?? args.includes("--include-corpus");
+    // Pre-resolved source wins over name-based lookup (backward compatible)
+    const sourceIdx = args.indexOf("--source");
+    const sourceName = options?.source ?? (sourceIdx !== -1 ? args[sourceIdx + 1] : undefined);
+    const source = options?.resolvedSource ?? loadSource(sourceName);
+    console.log(`  Source: ${sourceName ?? "default (production)"}`);
+    console.log(`  Base URL: ${source.baseUrl}`);
+    if (source.dataset) {
+        console.log(`  Dataset: ${source.dataset}`);
+    }
+    if (source.perspective) {
+        console.log(`  Perspective: ${source.perspective}`);
+    }
+    if (source.documentIds && source.documentIds.length > 0) {
+        console.log(`  Documents: ${source.documentIds.length} document ID(s)`);
+        for (const id of source.documentIds) {
+            console.log(`             ${id}`);
+        }
+    }
+    if (source.urls.length > 0) {
+        console.log(`  URLs:      ${source.urls.length} direct URL(s)`);
+        for (const u of source.urls) {
+            console.log(`             ${u}`);
+        }
+    }
+    console.log();
+    if (includeFeatureAreas) {
+        await generateFeatureAreaContexts(source);
+    }
+    // Canonical contexts — delegate to the SanityDocFetcher adapter
+    const taskSource = new YamlTaskSource(ROOT);
+    const tasks = await taskSource.loadTasks();
+    const tasksWithDocs = tasks.filter((t) => t.canonicalDocs.length > 0);
+    if (tasksWithDocs.length > 0) {
+        console.log("\nGenerating canonical (gold-retrieval) contexts...\n");
+        const fetcher = new SanityDocFetcher(ROOT);
+        const result = await fetcher.fetch(tasksWithDocs, source);
+        // Write metadata files inline (CLI mode)
+        const contextsDir = join(ROOT, "contexts");
+        mkdirSync(contextsDir, { recursive: true });
+        if (result.metadata?.manifest) {
+            const path = join(contextsDir, "document-manifest.json");
+            writeFileSync(path, JSON.stringify(result.metadata.manifest, null, 2));
+            console.log(`\n  📋 Document manifest: ${result.metadata.manifest.length} docs → contexts/document-manifest.json`);
+        }
+        if (result.metadata?.releaseImpact) {
+            const path = join(contextsDir, "release-impact.json");
+            writeFileSync(path, JSON.stringify(result.metadata.releaseImpact, null, 2));
+            console.log("  📄 Release impact written to contexts/release-impact.json");
+        }
+        if (result.metadata?.documentOverlay) {
+            const path = join(contextsDir, "document-overlay.json");
+            writeFileSync(path, JSON.stringify(result.metadata.documentOverlay, null, 2));
+            console.log("  📄 Document overlay written to contexts/document-overlay.json");
+        }
+        if (result.metadata?.urlFetch) {
+            const path = join(contextsDir, "url-fetch.json");
+            writeFileSync(path, JSON.stringify(result.metadata.urlFetch, null, 2));
+            console.log("  📄 URL fetch metadata written to contexts/url-fetch.json");
+        }
+        console.log(`\n  Canonical contexts: ${result.contexts.length} tasks`);
+        for (const ctx of result.contexts) {
+            console.log(`    ${ctx.taskId}: ${ctx.slugs.length} doc(s), ~${ctx.tokenCount ?? 0} tokens`);
+        }
+    }
+    if (includeCorpus) {
+        await generateFullCorpus(source);
+    }
+    console.log("\nDone!");
+}
+// ---------------------------------------------------------------------------
+// Main — only run when invoked directly
+// ---------------------------------------------------------------------------
+if (process.argv[1]?.endsWith("fetch-docs.ts") ||
+    process.argv[1]?.endsWith("fetch-docs.js")) {
+    main().catch((err) => {
+        console.error("Fatal error:", err);
+        process.exit(1);
+    });
+}

package/dist/lib/generate-configs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * lib/generate-configs.ts — DEPRECATED re-export shim.
+ *
+ * The real implementation has moved to pipeline/generate-configs.ts.
+ * This shim preserves backward compatibility for:
+ *   - Direct CLI invocation: `tsx src/lib/generate-configs.ts`
+ *   - Test imports that haven't been updated yet
+ *
+ * TODO: Update all importers to use pipeline/generate-configs.ts, then delete this file.
+ *
+ * @deprecated Import from ../pipeline/generate-configs.js instead.
+ */
+export { discoverTaskFiles, extractModelName, extractProvider, generateConfigs, loadPrompts, mergeConfig, modelMatchesMode, type GenerateConfigsOptions, } from "../pipeline/generate-configs.js";
+import type { GenerateConfigsOptions } from "../pipeline/generate-configs.js";
+/**
+ * Legacy main() entry point — wraps generateConfigs() with env var fallbacks.
+ *
+ * Only used for direct CLI invocation (`tsx src/lib/generate-configs.ts`).
+ * Command handlers and orchestration steps should call generateConfigs() directly.
+ *
+ * @deprecated Use generateConfigs() from pipeline/generate-configs.ts instead.
+ */
+export declare function main(options?: Omit<GenerateConfigsOptions, "rootDir"> & {
+    rootDir?: string;
+}): void;

package/dist/lib/generate-configs.js

@@ -0,0 +1,42 @@
+/**
+ * lib/generate-configs.ts — DEPRECATED re-export shim.
+ *
+ * The real implementation has moved to pipeline/generate-configs.ts.
+ * This shim preserves backward compatibility for:
+ *   - Direct CLI invocation: `tsx src/lib/generate-configs.ts`
+ *   - Test imports that haven't been updated yet
+ *
+ * TODO: Update all importers to use pipeline/generate-configs.ts, then delete this file.
+ *
+ * @deprecated Import from ../pipeline/generate-configs.js instead.
+ */
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+// Re-export everything from the real implementation
+export { discoverTaskFiles, extractModelName, extractProvider, generateConfigs, loadPrompts, mergeConfig, modelMatchesMode, } from "../pipeline/generate-configs.js";
+import { generateConfigs } from "../pipeline/generate-configs.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "../..");
+/**
+ * Legacy main() entry point — wraps generateConfigs() with env var fallbacks.
+ *
+ * Only used for direct CLI invocation (`tsx src/lib/generate-configs.ts`).
+ * Command handlers and orchestration steps should call generateConfigs() directly.
+ *
+ * @deprecated Use generateConfigs() from pipeline/generate-configs.ts instead.
+ */
+export function main(options) {
+    generateConfigs({
+        rootDir: options?.rootDir ?? ROOT,
+        allowedOrigins: options?.allowedOrigins,
+        filter: options?.filter,
+        resolvedSource: options?.resolvedSource,
+        searchMode: options?.searchMode,
+        source: options?.source ?? process.argv[2] ?? process.env.DOC_SOURCE,
+    });
+}
+// Only run when invoked directly (not when imported for testing)
+if (process.argv[1]?.endsWith("generate-configs.ts") ||
+    process.argv[1]?.endsWith("generate-configs.js")) {
+    main();
+}

package/dist/lib/grader-api.d.ts

@@ -0,0 +1,21 @@
+/**
+ * lib/grader-api.ts — DEPRECATED re-export shim.
+ *
+ * The real implementation has moved to pipeline/grader-api.ts.
+ * This shim preserves backward compatibility for:
+ *   - Direct CLI invocation and other lib/ files that import from here
+ *   - Test imports that haven't been updated yet
+ *
+ * TODO: Update all importers to use pipeline/grader-api.ts, then delete this file.
+ *
+ * @deprecated Import from ../pipeline/grader-api.js instead.
+ */
+export { extractScore, gradeOnce, resolveProvider, } from "../pipeline/grader-api.js";
+/**
+ * Backward-compatible loadGraderModel that uses EVAL_ROOT.
+ * @deprecated Use loadGraderModel(rootDir) from pipeline/grader-api.js instead.
+ */
+export declare function loadGraderModel(): {
+    id: string;
+    label: string;
+};

package/dist/lib/grader-api.js

@@ -0,0 +1,34 @@
+/**
+ * lib/grader-api.ts — DEPRECATED re-export shim.
+ *
+ * The real implementation has moved to pipeline/grader-api.ts.
+ * This shim preserves backward compatibility for:
+ *   - Direct CLI invocation and other lib/ files that import from here
+ *   - Test imports that haven't been updated yet
+ *
+ * TODO: Update all importers to use pipeline/grader-api.ts, then delete this file.
+ *
+ * @deprecated Import from ../pipeline/grader-api.js instead.
+ */
+import { config as dotenvConfig } from "dotenv";
+import { existsSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+// Re-export everything from the real implementation
+export { extractScore, gradeOnce, resolveProvider, } from "../pipeline/grader-api.js";
+import { loadGraderModel as _loadGraderModel } from "../pipeline/grader-api.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const EVAL_ROOT = resolve(__dirname, "..", "..");
+// Load root .env (two levels above packages/eval/) so API keys are available
+// even when this module is invoked via `tsx` from packages/eval/.
+const rootEnvPath = resolve(EVAL_ROOT, "..", "..", ".env");
+if (existsSync(rootEnvPath)) {
+    dotenvConfig({ override: true, path: rootEnvPath });
+}
+/**
+ * Backward-compatible loadGraderModel that uses EVAL_ROOT.
+ * @deprecated Use loadGraderModel(rootDir) from pipeline/grader-api.js instead.
+ */
+export function loadGraderModel() {
+    return _loadGraderModel(EVAL_ROOT);
+}

package/dist/lib/grader-compare.d.ts

@@ -0,0 +1,19 @@
+/**
+ * lib/grader-compare.ts — DEPRECATED re-export shim.
+ *
+ * The real implementation has moved to pipeline/grader-compare-runner.ts.
+ * The pure analysis functions live in pipeline/grader-comparison.ts.
+ * This shim preserves backward compatibility for direct CLI invocation.
+ *
+ * TODO: Update all importers to use pipeline/ modules, then delete this file.
+ *
+ * @deprecated Import from ../pipeline/grader-compare-runner.js instead.
+ */
+import "dotenv/config";
+export { formatComparisonReport, runGraderCompare, type GraderCompareRunnerOptions, } from "../pipeline/grader-compare-runner.js";
+export { compareGraders, type GraderComparison, type GraderScore, type GraderScoreSet, } from "../pipeline/grader-comparison.js";
+/**
+ * Legacy main() entry point.
+ * @deprecated Use runGraderCompare() from pipeline/grader-compare-runner.js instead.
+ */
+export declare function main(): Promise<void>;