@sanity/ailf 0.1.0

package/dist/report-store.js

@@ -0,0 +1,208 @@
+/**
+ * report-store.ts
+ *
+ * Persistent report store backed by the Sanity Content Lake.
+ * Provides write, read, and lineage-query operations for evaluation reports.
+ *
+ * The Sanity Content Lake is the system of record (P1: immutable events).
+ * Reports are stored as typed documents in the shared dataset, enabling
+ * GROQ queries, Studio dashboards, and webhook-driven notifications.
+ *
+ * If Sanity is unreachable, the store logs a warning and returns gracefully
+ * (P5: local-first — the pipeline never fails because of a store write).
+ *
+ * @see docs/design-docs/report-store/architecture.md
+ * @see docs/design-docs/report-store/domain-model.md
+ */
+import { getSanityClient } from "./sanity/client.js";
+import { compare } from "./pipeline/compare.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const REPORT_TYPE = "ailf.report";
+// ---------------------------------------------------------------------------
+// Report Store
+// ---------------------------------------------------------------------------
+export class ReportStore {
+    client;
+    constructor(options = {}) {
+        if (options.client) {
+            this.client = options.client;
+        }
+        else {
+            this.client = getSanityClient({
+                ...(options.dataset ? { dataset: options.dataset } : {}),
+                ...(options.projectId ? { projectId: options.projectId } : {}),
+                ...(options.token ? { token: options.token } : {}),
+            });
+        }
+    }
+    /**
+     * Auto-compare: find the most recent comparable report and compute
+     * a ComparisonReport using the existing compare() primitive.
+     *
+     * @returns The comparison report, or null if no baseline found or on error
+     */
+    async autoCompare(currentSummary, provenance, completedAt) {
+        const baseline = await this.findComparableBaseline({
+            before: completedAt,
+            mode: provenance.mode,
+            source: { name: provenance.source.name },
+        });
+        if (!baseline) {
+            return null;
+        }
+        try {
+            return compare(baseline.summary, currentSummary);
+        }
+        catch (error) {
+            console.warn(`  ⚠️  Auto-comparison failed: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Find a report by its evaluation fingerprint (cross-environment cache lookup).
+     *
+     * Returns the most recent non-debug report whose provenance contains a
+     * matching `evalFingerprint`. Used by the pipeline to skip the expensive
+     * eval step when identical inputs have already been evaluated.
+     *
+     * @returns The cached report, or null if no match or on error
+     * @see docs/design-docs/content-lake-eval-caching.md
+     */
+    async findByFingerprint(fingerprint) {
+        try {
+            const groq = `*[_type == $type
+        && provenance.evalFingerprint == $fingerprint
+      ] | order(completedAt desc) [0]`;
+            const doc = await this.client.fetch(groq, { fingerprint, type: REPORT_TYPE });
+            return doc ? toReport(doc) : null;
+        }
+        catch (error) {
+            console.warn(`  ⚠️  Failed to query cached report by fingerprint: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Find the most recent comparable report for auto-comparison.
+     *
+     * Uses GROQ to match on key provenance dimensions (mode, source name)
+     * and returns the most recent report before the given timestamp.
+     *
+     * "Comparable" means: same evaluation mode + same source name.
+     * More granular matching (areas, models) can be added as needed.
+     *
+     * @see docs/design-docs/report-store/architecture.md — Auto-comparison
+     */
+    async findComparableBaseline(query) {
+        try {
+            const groq = `*[_type == $type
+        && provenance.mode == $mode
+        ${query.source?.name ? "&& provenance.source.name == $sourceName" : ""}
+        ${query.before ? "&& completedAt < $before" : ""}
+      ] | order(completedAt desc) [0]`;
+            const params = {
+                mode: query.mode,
+                type: REPORT_TYPE,
+            };
+            if (query.source?.name) {
+                params.sourceName = query.source.name;
+            }
+            if (query.before) {
+                params.before = query.before;
+            }
+            const doc = await this.client.fetch(groq, params);
+            return doc ? toReport(doc) : null;
+        }
+        catch (error) {
+            console.warn(`  ⚠️  Failed to query comparable baseline: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Read a report by its ID.
+     */
+    async read(id) {
+        try {
+            const doc = await this.client.fetch(`*[_type == $type && reportId == $id][0]`, { id, type: REPORT_TYPE });
+            return doc ? toReport(doc) : null;
+        }
+        catch (error) {
+            console.warn(`  ⚠️  Failed to read report from Sanity: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Write a report to the Sanity Content Lake.
+     *
+     * Creates an immutable `ailf.report` document. The document _id is
+     * prefixed with `report-` for easy GROQ filtering.
+     *
+     * @returns The report ID on success, null on failure (logged, not thrown)
+     */
+    async write(report) {
+        try {
+            await this.client.create({
+                _id: `report-${report.id}`,
+                _type: REPORT_TYPE,
+                comparison: report.comparison ?? null,
+                completedAt: report.completedAt,
+                durationMs: report.durationMs,
+                provenance: report.provenance,
+                reportId: report.id,
+                summary: report.summary,
+                tag: report.tag ?? null,
+            });
+            return report.id;
+        }
+        catch (error) {
+            console.warn(`  ⚠️  Failed to write report to Sanity: ${error instanceof Error ? error.message : String(error)}`);
+            console.warn("  Report was not persisted. Pipeline results are still available locally.");
+            return null;
+        }
+    }
+}
+/**
+ * Generate a UUID v7 (time-sortable) for report identification.
+ *
+ * UUID v7 encodes the current timestamp in the high bits, making reports
+ * naturally sort by creation time in both GROQ and string comparisons.
+ *
+ * Uses crypto.randomUUID() as a base and overwrites the timestamp portion.
+ */
+export function generateReportId() {
+    const now = Date.now();
+    const uuid = crypto.randomUUID();
+    // UUID v7: encode 48-bit timestamp in the first 12 hex chars
+    const hex = now.toString(16).padStart(12, "0");
+    const v7 = hex.slice(0, 8) +
+        "-" +
+        hex.slice(8, 12) +
+        "-7" +
+        uuid.slice(15, 18) +
+        "-" +
+        uuid.slice(19, 23) +
+        "-" +
+        uuid.slice(24);
+    return v7;
+}
+// ---------------------------------------------------------------------------
+// Sanity document → Report mapping
+// ---------------------------------------------------------------------------
+/**
+ * Convert a raw Sanity document to a typed Report.
+ *
+ * The Sanity document shape mirrors the Report type but includes Sanity
+ * metadata (_id, _type, _rev, etc.) that we strip.
+ */
+function toReport(doc) {
+    return {
+        comparison: doc.comparison,
+        completedAt: doc.completedAt,
+        durationMs: doc.durationMs,
+        id: doc.reportId,
+        provenance: doc.provenance,
+        summary: doc.summary,
+        tag: doc.tag,
+    };
+}

package/dist/sanity/client.d.ts

@@ -0,0 +1,38 @@
+import { type SanityClient } from "@sanity/client";
+import type { ResolvedSourceConfig } from "../sources.js";
+export interface SanityConfig {
+    apiVersion: string;
+    dataset: string;
+    perspective?: string[];
+    projectId: string;
+    token?: string;
+    useCdn: boolean;
+}
+/**
+ * Create a Sanity client configured for a specific perspective.
+ *
+ * Unlike getSanityClient(), this always creates a fresh (uncached) client.
+ * Used for perspective diffing — comparing published vs. perspective content.
+ *
+ * @param perspective - The perspective ID (e.g., "agent-c7OKTk"). Stacked
+ *   on top of "published" as [perspectiveId, "published"].
+ * @param source - Optional ResolvedSourceConfig for projectId/dataset overrides.
+ */
+export declare function createPerspectiveClient(perspective: string, source?: ResolvedSourceConfig): SanityClient;
+/**
+ * Create a Sanity client that reads only published content (no perspectives).
+ *
+ * Unlike getSanityClient(), this always creates a fresh (uncached) client.
+ * Used for perspective diffing — fetching the "before" state.
+ *
+ * @param source - Optional ResolvedSourceConfig for projectId/dataset overrides.
+ */
+export declare function createPublishedClient(source?: ResolvedSourceConfig): SanityClient;
+/**
+ * Create or return a cached Sanity client.
+ *
+ * When a ResolvedSourceConfig is provided, its projectId, dataset, and perspective
+ * override the defaults. For release perspectives, the perspective is
+ * passed as a stacked array: [perspectiveId, "published"].
+ */
+export declare function getSanityClient(overrides?: Partial<SanityConfig>, source?: ResolvedSourceConfig): SanityClient;

package/dist/sanity/client.js

@@ -0,0 +1,86 @@
+import { createClient } from "@sanity/client";
+/**
+ * Build the default Sanity client config by reading process.env at call time.
+ *
+ * IMPORTANT: This is a function, not a module-level const. In ESM, static
+ * imports are resolved before module-level code runs. If this were a const,
+ * it would capture process.env values at import time — before dotenv has
+ * loaded the .env file. By deferring to call time, we ensure env vars set
+ * by dotenvConfig() in cli.ts (or migration scripts) are always picked up.
+ */
+function getDefaultConfig() {
+    return {
+        apiVersion: new Date().toISOString().split("T")[0],
+        // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to default
+        dataset: process.env.SANITY_DATASET || "next",
+        // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to default
+        projectId: process.env.SANITY_PROJECT_ID || "3do82whm",
+        token: process.env.SANITY_API_TOKEN,
+        useCdn: false,
+    };
+}
+let _client = null;
+/**
+ * Create a Sanity client configured for a specific perspective.
+ *
+ * Unlike getSanityClient(), this always creates a fresh (uncached) client.
+ * Used for perspective diffing — comparing published vs. perspective content.
+ *
+ * @param perspective - The perspective ID (e.g., "agent-c7OKTk"). Stacked
+ *   on top of "published" as [perspectiveId, "published"].
+ * @param source - Optional ResolvedSourceConfig for projectId/dataset overrides.
+ */
+export function createPerspectiveClient(perspective, source) {
+    const config = {
+        ...getDefaultConfig(),
+        ...(source?.dataset ? { dataset: source.dataset } : {}),
+        ...(source?.projectId ? { projectId: source.projectId } : {}),
+        perspective: [perspective, "published"],
+    };
+    return createClient(config);
+}
+/**
+ * Create a Sanity client that reads only published content (no perspectives).
+ *
+ * Unlike getSanityClient(), this always creates a fresh (uncached) client.
+ * Used for perspective diffing — fetching the "before" state.
+ *
+ * @param source - Optional ResolvedSourceConfig for projectId/dataset overrides.
+ */
+export function createPublishedClient(source) {
+    const config = {
+        ...getDefaultConfig(),
+        ...(source?.dataset ? { dataset: source.dataset } : {}),
+        ...(source?.projectId ? { projectId: source.projectId } : {}),
+        perspective: ["published"],
+    };
+    return createClient(config);
+}
+/**
+ * Create or return a cached Sanity client.
+ *
+ * When a ResolvedSourceConfig is provided, its projectId, dataset, and perspective
+ * override the defaults. For release perspectives, the perspective is
+ * passed as a stacked array: [perspectiveId, "published"].
+ */
+export function getSanityClient(overrides, source) {
+    // If a source is provided, always create a fresh client (don't cache)
+    if (source) {
+        const config = {
+            ...getDefaultConfig(),
+            ...overrides,
+            ...(source.dataset ? { dataset: source.dataset } : {}),
+            ...(source.projectId ? { projectId: source.projectId } : {}),
+            ...(source.perspective
+                ? { perspective: [source.perspective, "published"] }
+                : {}),
+        };
+        return createClient(config);
+    }
+    if (_client && !overrides) {
+        return _client;
+    }
+    const config = { ...getDefaultConfig(), ...overrides };
+    _client = createClient(config);
+    return _client;
+}

package/dist/sanity/portable-text.d.ts

@@ -0,0 +1,11 @@
+type PortableTextArray = PortableTextBlock[];
+interface PortableTextBlock {
+    [key: string]: unknown;
+    _key?: string;
+    _type: string;
+}
+/**
+ * Convert a Sanity Portable Text `content` array to well-structured Markdown.
+ */
+export declare function toMarkdown(blocks: PortableTextArray): string;
+export {};

package/dist/sanity/portable-text.js

@@ -0,0 +1,211 @@
+/**
+ * Portable-text.ts
+ *
+ * Converts Sanity Portable Text `content` arrays into well-structured
+ * Markdown using @portabletext/markdown. Includes custom renderers for the
+ * doc-platform's bespoke block types.
+ *
+ * Block type inventory (content field):
+ *
+ *   Standard:       block
+ *   Code:           codeBlock
+ *   Tables:         propertiesTable, tableBlock, methodTable
+ *   Callouts:       docsCallout
+ *   Cards/Links:    docsCardCollection, docsCallToAction
+ *   Media:          image, muxVideo, youtube, youtubePlaylist, codesandbox
+ *   Other:          docsPaidFeature, button, methodHeading
+ */
+import { DefaultHorizontalRuleRenderer, DefaultImageRenderer, portableTextToMarkdown, } from "@portabletext/markdown";
+// ---------------------------------------------------------------------------
+// Recursive helper – convert nested PT to markdown
+// ---------------------------------------------------------------------------
+/**
+ * Convert a Sanity Portable Text `content` array to well-structured Markdown.
+ */
+export function toMarkdown(blocks) {
+    if (!blocks || blocks.length === 0) {
+        return "";
+    }
+    return portableTextToMarkdown(blocks, {
+        // --- Custom mark renderers ---
+        marks: {
+            link: renderLink,
+        },
+        // --- Custom type renderers ---
+        types: {
+            button: () => "",
+            // Code
+            codeBlock: renderCodeBlock,
+            codesandbox: ({ value }) => {
+                const v = value;
+                const url = v.url ?? "";
+                return url ? `[CodeSandbox](${url})` : "*[CodeSandbox]*";
+            },
+            // Callouts
+            docsCallout: renderDocsCallout,
+            docsCallToAction: ({ value }) => {
+                const title = value.title;
+                return title ? `**${title}**` : "";
+            },
+            // Cards / CTAs
+            docsCardCollection: renderDocsCardCollection,
+            // Skip / minimal rendering
+            docsPaidFeature: () => "",
+            "horizontal-rule": DefaultHorizontalRuleRenderer,
+            // Media — render a placeholder rather than dropping silently
+            image: DefaultImageRenderer,
+            methodHeading: renderMethodHeading,
+            methodTable: renderPropertiesTable, // Same shape
+            muxVideo: () => "*[Video]*",
+            // Tables
+            propertiesTable: renderPropertiesTable,
+            tableBlock: renderTableBlock,
+            youtube: ({ value }) => {
+                const v = value;
+                const url = v.url ?? "";
+                return url ? `[Video](${url})` : "*[Video]*";
+            },
+            youtubePlaylist: () => "*[YouTube Playlist]*",
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Custom type renderers
+// ---------------------------------------------------------------------------
+function nestedToMarkdown(blocks) {
+    if (!blocks || blocks.length === 0) {
+        return "";
+    }
+    return toMarkdown(blocks);
+}
+/**
+ * CodeBlock
+ * Shape: { blocks: [{ code: { code, language }, filename }] }
+ *
+ * May contain multiple tabs (e.g. "Action" / "Mutation").
+ */
+function renderCodeBlock({ value, }) {
+    const blocks = (value.blocks ?? []);
+    return blocks
+        .map((b) => {
+        const code = b.code?.code ?? "";
+        const lang = b.code?.language ?? "";
+        const filename = b.filename ? ` (${b.filename})` : "";
+        return `\`\`\`${lang}${filename}\n${code}\n\`\`\``;
+    })
+        .join("\n\n");
+}
+/**
+ * DocsCallout
+ * Shape: { type: "warning"|"info"|..., title?: string, content: PT[] }
+ */
+function renderDocsCallout({ value, }) {
+    const type = value.type ?? "info";
+    const title = value.title;
+    const inner = nestedToMarkdown(value.content);
+    const label = title ?? type.charAt(0).toUpperCase() + type.slice(1);
+    const lines = inner.split("\n").map((l) => `> ${l}`);
+    return `> **${label}**\n>\n${lines.join("\n")}`;
+}
+/**
+ * DocsCardCollection
+ * Shape (after GROQ reference resolution):
+ *   { cards: [{ title?, description?, resolvedTitle?, resolvedSlug?, url? }] }
+ */
+function renderDocsCardCollection({ value, }) {
+    const cards = (value.cards ?? []);
+    if (cards.length === 0) {
+        return "";
+    }
+    const rendered = cards
+        .map((c) => {
+        // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty strings should fall through to next candidate
+        const title = c.title || c.resolvedTitle || c.description;
+        if (!title) {
+            return null;
+        } // Skip cards with no meaningful content
+        const url = c.resolvedSlug
+            ? `https://sanity.io/docs/${c.resolvedSlug}`
+            : (c.url ?? "");
+        const desc = c.description && c.description !== title ? ` — ${c.description}` : "";
+        return url ? `- [${title}](${url})${desc}` : `- **${title}**${desc}`;
+    })
+        .filter(Boolean);
+    return rendered.join("\n");
+}
+function renderLink({ children, value, }) {
+    const href = value?.url ?? value?.href ?? "";
+    return href ? `[${children}](${href})` : children;
+}
+/**
+ * MethodTable / methodHeading — API method documentation
+ */
+function renderMethodHeading({ value, }) {
+    const name = value.name ?? "";
+    const signature = value.signature ?? "";
+    return signature ? `### \`${name}(${signature})\`` : `### \`${name}\``;
+}
+// ---------------------------------------------------------------------------
+// Link mark renderer
+//
+// Sanity docs use `url` in the content field's link annotations.
+// The library default only handles `href`. This handles `url` as well.
+// ---------------------------------------------------------------------------
+/**
+ * PropertiesTable
+ * Shape: { properties: [{ name, propertyDataType, explanation: PT[], isRequired? }] }
+ */
+function renderPropertiesTable({ value, }) {
+    const properties = (value.properties ?? []);
+    if (properties.length === 0) {
+        return "";
+    }
+    const rows = properties.map((p) => {
+        const name = p.name ?? "";
+        const type = p.propertyDataType ?? "";
+        const required = p.isRequired ? " **(required)**" : "";
+        const explanation = nestedToMarkdown(p.explanation)
+            .replace(/\n/g, " ")
+            .trim();
+        return `| \`${name}\`${required} | \`${type}\` | ${explanation} |`;
+    });
+    return [
+        "| Property | Type | Description |",
+        "|----------|------|-------------|",
+        ...rows,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * TableBlock
+ * Shape: { headerRow: boolean, title?: string, table: { rows: [{ cells: string[] }] } }
+ */
+function renderTableBlock({ value, }) {
+    const title = value.title;
+    const headerRow = value.headerRow;
+    const table = value.table;
+    const rows = table?.rows ?? [];
+    if (rows.length === 0) {
+        return "";
+    }
+    const lines = [];
+    if (title) {
+        lines.push(`**${title}**\n`);
+    }
+    rows.forEach((row, i) => {
+        const cells = (row.cells ?? []).map((c) => c.replace(/\|/g, "\\|"));
+        lines.push(`| ${cells.join(" | ")} |`);
+        if (i === 0 && headerRow) {
+            lines.push(`| ${cells.map(() => "---").join(" | ")} |`);
+        }
+    });
+    // If no header row marker yet, add one after the first row anyway
+    // So the markdown table is valid
+    if (!headerRow && rows.length > 0) {
+        const firstCells = rows[0].cells ?? [];
+        lines.splice(1, 0, `| ${firstCells.map(() => "---").join(" | ")} |`);
+    }
+    return lines.join("\n");
+}