@sanity/ailf 4.1.0 → 4.3.0

package/dist/pipeline/preflight/load-preflight-scoring.js

@@ -0,0 +1,17 @@
+/**
+ * load-preflight-scoring — read the W0198 preflight scoring config
+ * (`config/preflight-scoring.ts`) authored via `definePreflightScoring()`.
+ *
+ * Returns `undefined` when the file is absent so callers fall back to
+ * `DEFAULT_PREFLIGHT_CODE_CORRECTNESS_WEIGHT`. The eval package itself
+ * ships a config so the live pipeline always finds one; the optional
+ * return path exists for downstream / external callers that may not
+ * have authored one yet.
+ */
+import { tryLoadConfigFile } from "../compiler/config-loader.js";
+export async function loadPreflightScoring(rootDir) {
+    const result = tryLoadConfigFile("preflight-scoring", rootDir);
+    if (!result)
+        return undefined;
+    return result.data;
+}

package/dist/pipeline/preflight/parse-imports.d.ts

@@ -0,0 +1,62 @@
+/**
+ * parse-imports — pure function that extracts every `import` declaration
+ * from a candidate code block as a flat list of per-binding entries.
+ *
+ * Output shape is intentionally flat: the W0198 preflight checks each
+ * `(source, imported)` pair against the resolved package surface, so a
+ * flat list is the natural input. Multi-binding declarations
+ * (`import { a, b as c } from "pkg"`) produce one entry per binding;
+ * default + named combos (`import def, { a } from "pkg"`) likewise.
+ *
+ * Implementation: delegates to `oxc-parser`'s `staticImports` view, which
+ * already decomposes each import statement into entries with explicit
+ * `importName` / `localName` / `isType` fields. The TS-aware grammar
+ * means dynamic `import(...)`, `import.meta`, and malformed statements
+ * are all handled by the parser itself — we just translate the entries
+ * into our `CandidateImportBinding` shape.
+ *
+ * Recognized grammar (handled by oxc-parser):
+ *   - `import { a, b as c } from "pkg"`
+ *   - `import def from "pkg"`
+ *   - `import * as ns from "pkg"`
+ *   - `import def, { a } from "pkg"` and `import def, * as ns from "pkg"`
+ *   - `import type { ... } from "pkg"` and `import { type a, b } from "pkg"`
+ *   - `import "pkg"` (side-effect; surfaced as a single `side-effect` entry)
+ *   - Multi-line variants of all of the above.
+ *
+ * Out of scope (intentionally — both regex and oxc-parser ignore these):
+ *   - Dynamic `import("pkg")` — runtime, not statically resolvable here.
+ *   - `export { a } from "pkg"` re-exports from candidate code.
+ *   - TypeScript `import = require()` and `import("...").Type` ambient
+ *     references — neither pattern shows up in the App SDK / Studio
+ *     candidate corpus the preflight grades against.
+ */
+export type CandidateImportKind = "named" | "default" | "namespace" | "side-effect";
+export interface CandidateImportBinding {
+    /** Source specifier as written by the candidate (e.g. `"@sanity/sdk-react"`). */
+    source: string;
+    /** Which import-clause shape this binding came from. */
+    kind: CandidateImportKind;
+    /**
+     * Name to look up against the package surface:
+     *   - `kind: "named"` — the imported identifier.
+     *   - `kind: "default"` — the literal string `"default"`.
+     *   - `kind: "namespace"` — the literal string `"*"`.
+     *   - `kind: "side-effect"` — empty string (no binding).
+     */
+    imported: string;
+    /** Local alias used in the candidate's body. Same as `imported` when no alias. */
+    local: string;
+    /**
+     * Whether this binding is type-only — either the whole declaration was
+     * `import type`, or this specifier was prefixed with `type`
+     * (`import { type X, Y } from "pkg"`).
+     */
+    isType: boolean;
+    /**
+     * 1-based line number where the import declaration starts in the
+     * source. Useful for surfacing findings back to a reviewer.
+     */
+    line: number;
+}
+export declare function parseImports(src: string): CandidateImportBinding[];

package/dist/pipeline/preflight/parse-imports.js

@@ -0,0 +1,125 @@
+/**
+ * parse-imports — pure function that extracts every `import` declaration
+ * from a candidate code block as a flat list of per-binding entries.
+ *
+ * Output shape is intentionally flat: the W0198 preflight checks each
+ * `(source, imported)` pair against the resolved package surface, so a
+ * flat list is the natural input. Multi-binding declarations
+ * (`import { a, b as c } from "pkg"`) produce one entry per binding;
+ * default + named combos (`import def, { a } from "pkg"`) likewise.
+ *
+ * Implementation: delegates to `oxc-parser`'s `staticImports` view, which
+ * already decomposes each import statement into entries with explicit
+ * `importName` / `localName` / `isType` fields. The TS-aware grammar
+ * means dynamic `import(...)`, `import.meta`, and malformed statements
+ * are all handled by the parser itself — we just translate the entries
+ * into our `CandidateImportBinding` shape.
+ *
+ * Recognized grammar (handled by oxc-parser):
+ *   - `import { a, b as c } from "pkg"`
+ *   - `import def from "pkg"`
+ *   - `import * as ns from "pkg"`
+ *   - `import def, { a } from "pkg"` and `import def, * as ns from "pkg"`
+ *   - `import type { ... } from "pkg"` and `import { type a, b } from "pkg"`
+ *   - `import "pkg"` (side-effect; surfaced as a single `side-effect` entry)
+ *   - Multi-line variants of all of the above.
+ *
+ * Out of scope (intentionally — both regex and oxc-parser ignore these):
+ *   - Dynamic `import("pkg")` — runtime, not statically resolvable here.
+ *   - `export { a } from "pkg"` re-exports from candidate code.
+ *   - TypeScript `import = require()` and `import("...").Type` ambient
+ *     references — neither pattern shows up in the App SDK / Studio
+ *     candidate corpus the preflight grades against.
+ */
+import { parseSync } from "oxc-parser";
+export function parseImports(src) {
+    // Use the `.tsx` filename hint so the parser tolerates JSX in candidate
+    // code (App SDK literacy tasks frequently include JSX in their answers).
+    const result = parseSync("input.tsx", src, { lang: "tsx" });
+    const lineStarts = computeLineStarts(src);
+    const offsetToLine = (offset) => binarySearchLine(lineStarts, offset) + 1;
+    const out = [];
+    for (const imp of result.module.staticImports) {
+        const source = imp.moduleRequest.value;
+        // The parser recovers from malformed specifiers (e.g. backtick-quoted
+        // module requests) by emitting an empty source; the W0198 preflight
+        // can't do anything useful with that, so drop those entries.
+        if (!source)
+            continue;
+        const line = offsetToLine(imp.start);
+        if (imp.entries.length === 0) {
+            // Side-effect form: `import "pkg"`.
+            out.push({
+                source,
+                kind: "side-effect",
+                imported: "",
+                local: "",
+                isType: false,
+                line,
+            });
+            continue;
+        }
+        for (const entry of imp.entries) {
+            const local = entry.localName.value;
+            const isType = entry.isType;
+            switch (entry.importName.kind) {
+                case "Name":
+                    out.push({
+                        source,
+                        kind: "named",
+                        imported: entry.importName.name ?? local,
+                        local,
+                        isType,
+                        line,
+                    });
+                    break;
+                case "Default":
+                    out.push({
+                        source,
+                        kind: "default",
+                        imported: "default",
+                        local,
+                        isType,
+                        line,
+                    });
+                    break;
+                case "NamespaceObject":
+                    out.push({
+                        source,
+                        kind: "namespace",
+                        imported: "*",
+                        local,
+                        isType,
+                        line,
+                    });
+                    break;
+            }
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Line-number helpers — oxc-parser returns byte offsets; the W0198
+// preflight surfaces 1-based line numbers in findings so reviewers can
+// jump straight to the citing line.
+// ---------------------------------------------------------------------------
+function computeLineStarts(src) {
+    const offsets = [0];
+    for (let i = 0; i < src.length; i++) {
+        if (src[i] === "\n")
+            offsets.push(i + 1);
+    }
+    return offsets;
+}
+function binarySearchLine(offsets, target) {
+    let lo = 0;
+    let hi = offsets.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (offsets[mid] <= target)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}

package/dist/report-store.d.ts

@@ -65,6 +65,10 @@ export declare class ReportStore {
      * matching `evalFingerprint`. Used by the pipeline to skip the expensive
      * eval step when identical inputs have already been evaluated.
      *
+     * Advisory lookup: a `ReportSchemaValidationError` from a corrupt prior
+     * doc is logged + counted, then null is returned so the current eval
+     * proceeds. Use `read(id)` when callers ask for a specific document by id.
+     *
      * @returns The cached report, or null if no match or on error
      * @see docs/design-docs/content-lake-eval-caching.md
      */
@@ -78,6 +82,10 @@ export declare class ReportStore {
      * "Comparable" means: same evaluation mode + same source name.
      * More granular matching (areas, models) can be added as needed.
      *
+     * Advisory lookup: see `findByFingerprint` — a malformed prior baseline
+     * is logged + counted and null is returned so the current run still
+     * publishes its report.
+     *
      * @see docs/design-docs/report-store/architecture.md — Auto-comparison
      */
     findComparableBaseline(query: LineageQuery): Promise<null | Report>;

package/dist/report-store.js

@@ -119,6 +119,10 @@ export class ReportStore {
      * matching `evalFingerprint`. Used by the pipeline to skip the expensive
      * eval step when identical inputs have already been evaluated.
      *
+     * Advisory lookup: a `ReportSchemaValidationError` from a corrupt prior
+     * doc is logged + counted, then null is returned so the current eval
+     * proceeds. Use `read(id)` when callers ask for a specific document by id.
+     *
      * @returns The cached report, or null if no match or on error
      * @see docs/design-docs/content-lake-eval-caching.md
      */
@@ -131,9 +135,19 @@ export class ReportStore {
             return doc ? toReport(doc) : null;
         }
         catch (error) {
-            // W0191: schema-validation errors are bugs, not outages — surface them.
-            if (error instanceof ReportSchemaValidationError)
-                throw error;
+            // Advisory lookup — a single corrupt prior doc must not break the
+            // current eval. Log loudly + emit a counter so ops can alert, and
+            // return null so the caller treats it as "no comparable cache hit".
+            // Direct read(id) keeps the rethrow behavior because the caller asked
+            // for that specific document and silent-null would mask the bug.
+            if (error instanceof ReportSchemaValidationError) {
+                logAdvisoryQuerySchemaFailure({
+                    query: "findByFingerprint",
+                    context: { fingerprint },
+                    error,
+                });
+                return null;
+            }
             console.warn(`  ⚠️  Failed to query cached report by fingerprint: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
@@ -147,6 +161,10 @@ export class ReportStore {
      * "Comparable" means: same evaluation mode + same source name.
      * More granular matching (areas, models) can be added as needed.
      *
+     * Advisory lookup: see `findByFingerprint` — a malformed prior baseline
+     * is logged + counted and null is returned so the current run still
+     * publishes its report.
+     *
      * @see docs/design-docs/report-store/architecture.md — Auto-comparison
      */
     async findComparableBaseline(query) {
@@ -170,9 +188,21 @@ export class ReportStore {
             return doc ? toReport(doc) : null;
         }
         catch (error) {
-            // W0191: schema-validation errors are bugs, not outages — surface them.
-            if (error instanceof ReportSchemaValidationError)
-                throw error;
+            // Advisory lookup — see findByFingerprint for rationale. A malformed
+            // prior baseline returns null + counter so the current run still
+            // publishes; direct read(id) preserves the rethrow.
+            if (error instanceof ReportSchemaValidationError) {
+                logAdvisoryQuerySchemaFailure({
+                    query: "findComparableBaseline",
+                    context: {
+                        mode: query.mode,
+                        sourceName: query.source?.name,
+                        before: query.before,
+                    },
+                    error,
+                });
+                return null;
+            }
             console.warn(`  ⚠️  Failed to query comparable baseline: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
@@ -299,6 +329,25 @@ export class ReportSchemaValidationError extends Error {
         this.name = "ReportSchemaValidationError";
     }
 }
+/**
+ * Stable log marker for log-aggregator counters. Operators alert on the
+ * count of `[report-store.advisory] schema_validation_error` lines per
+ * window; the trailing JSON carries enough context (which advisory query,
+ * what filter values, error message) to find the offending document
+ * without spelunking through GROQ.
+ *
+ * Emitted via console.error rather than console.warn so it surfaces in
+ * the same severity tier as a real failure even though we're swallowing
+ * it for the current run.
+ */
+function logAdvisoryQuerySchemaFailure(input) {
+    const payload = {
+        query: input.query,
+        context: input.context,
+        error: input.error.message,
+    };
+    console.error(`[report-store.advisory] schema_validation_error ${JSON.stringify(payload)}`);
+}
 export function toSanityReportDoc(report) {
     const comparison = report.comparison
         ? stripComparisonBulk(report.comparison)

package/dist/sanity/document-renderers.d.ts

@@ -0,0 +1,106 @@
+/**
+ * document-renderers.ts
+ *
+ * Renderer registry that turns a Sanity document into both:
+ *
+ *   - Markdown content for inclusion in a literacy task's grader/candidate
+ *     context (existing surface, used by the doc fetcher).
+ *   - A symbol-reference index for the W0197 grader-context pathway —
+ *     a flat list of identifiers the doc legitimizes, with provenance.
+ *     The grader prefers this over the rendered markdown when available
+ *     (smaller, deterministic, harder for the grader's prior to override).
+ *
+ * Both surfaces dispatch through the same registry. Articles and
+ * typesReference docs have hand-written renderers; everything else falls
+ * through to the default walker. This keeps "what to do with a document
+ * of type X" a single decision point regardless of whether the doc was
+ * looked up by slug, path, perspective, or id.
+ *
+ * Two tiers of fidelity (rendered output):
+ *
+ *   1. Registered renderers (high fidelity) — `article`, `typesReference`.
+ *      Hand-written for the document shapes we care about most.
+ *   2. Default renderer (best effort) — walks the doc, flattens portable-text
+ *      fields, surfaces top-level scalars, follows references one level deep,
+ *      skips framework-internal fields. Lets pinning a `marketingPage`,
+ *      `glossaryEntry`, etc. work without AILF code changes.
+ *
+ * Adding a new high-fidelity renderer: implement a `DocumentRenderer`
+ * (both `render` and `extractSymbols`) and register it in
+ * `BUILT_IN_RENDERERS` keyed by `_type`.
+ */
+import { type SymbolIndex } from "./symbol-index.js";
+/**
+ * A Sanity document plus any references we've already resolved for it.
+ * The resolver fetches the doc once and may include common deref payloads
+ * (e.g. `latestVersion->{...}` for typesReference) so renderers don't need
+ * to issue additional client.fetch calls themselves.
+ */
+export interface DocumentForRender {
+    _id: string;
+    _type: string;
+    [key: string]: unknown;
+}
+export interface RenderContext {
+    /**
+     * Async URL fetcher for renderers that need to follow `sanity.fileAsset`
+     * URLs (e.g. typedoc JSON for `typesReference` docs). Returns the raw
+     * body text or `null` on failure.
+     */
+    fetchUrl?: (url: string) => Promise<string | null>;
+    /**
+     * Soft cap on rendered content length, in bytes. Renderers should respect
+     * this and append a truncation notice rather than blow up grader context.
+     */
+    maxBytes?: number;
+}
+export interface RenderResult {
+    /** The rendered Markdown. Empty string is permitted but produces a warn. */
+    content: string;
+    /**
+     * The fidelity tier used. Resolvers can log differently based on this:
+     *   - "high"    — a registered renderer ran
+     *   - "default" — fell through to the generic walker (info log)
+     */
+    fidelity: "high" | "default";
+    /**
+     * Stable display slug for this document. Articles use `slug.current`;
+     * other types fall back to a `<_type>:<_id>` form when no slug exists.
+     * Surfaces in `DocContext.slugs` for retrieval-metric attribution.
+     */
+    slug: string;
+}
+export interface DocumentRenderer {
+    /**
+     * Produce rendered Markdown for the doc's content surface (for grader
+     * + candidate context inclusion).
+     */
+    render(doc: DocumentForRender, ctx: RenderContext): Promise<RenderResult> | RenderResult;
+    /**
+     * Produce a symbol-reference index for the doc — a flat list of
+     * identifiers the doc legitimizes plus provenance snippets. Used by
+     * the grader-context pathway (W0197) instead of injecting the full
+     * rendered doc. Returning an empty index signals the caller to fall
+     * back to the rendered markdown.
+     */
+    extractSymbols(doc: DocumentForRender, ctx: RenderContext): Promise<SymbolIndex> | SymbolIndex;
+}
+/**
+ * Render a document using the registered renderer for its `_type`, falling
+ * back to the default walker. The returned `fidelity` flag tells callers
+ * whether to emit the "info: dedicated renderer would help" log.
+ */
+export declare function renderDocument(doc: DocumentForRender, ctx?: RenderContext): Promise<RenderResult>;
+/**
+ * Extract a symbol-reference index for a document using its registered
+ * renderer (or the default walker for unknown types). Used by the
+ * grader-context pathway (W0197) to feed the LLM judge a compact
+ * deterministic recognition reference instead of the full rendered doc.
+ *
+ * Returns an empty `SymbolIndex` (`{ symbols: [] }`) when extraction
+ * yields nothing — callers interpret this as the signal to fall back to
+ * the rendered markdown.
+ */
+export declare function extractSymbolsForDoc(doc: DocumentForRender, ctx?: RenderContext): Promise<SymbolIndex>;
+/** Exported for tests and consumers that want the registered set. */
+export declare const REGISTERED_RENDERER_TYPES: string[];