@sanity/ailf 1.0.0 → 2.0.1

package/dist/scripts/webhook-server.js

@@ -0,0 +1,147 @@
+/**
+ * webhook-server.ts
+ *
+ * Local development server for testing the webhook handler.
+ *
+ * Starts an HTTP server that receives Sanity webhook payloads, processes
+ * them through the WebhookHandler, and logs results. Useful for local
+ * development and testing the full event-driven trigger flow.
+ *
+ * Usage:
+ *   pnpm webhook-server                    # start on port 3333
+ *   WEBHOOK_PORT=8080 pnpm webhook-server  # custom port
+ *
+ * Test with curl:
+ *   curl -X POST http://localhost:3333/webhook \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"operation":"update","result":{"_id":"abc","_type":"article","slug":{"current":"groq-introduction"}}}'
+ *
+ * Endpoints:
+ *   POST /webhook    — handle a Sanity webhook payload
+ *   GET  /health     — handler diagnostics (budget, pending, tracked slugs)
+ *   GET  /mappings   — list all tracked document slugs and their areas
+ *
+ * @see docs/design-docs/report-store/visibility-workflows.md
+ */
+import { createServer } from "http";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { allTrackedSlugs, buildReverseMapping, } from "../pipeline/reverse-mapping.js";
+import { WebhookHandler } from "../webhook/handler.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..", "..");
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const PORT = parseInt(process.env.WEBHOOK_PORT ?? "3333", 10);
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? "";
+const DRY_RUN = !GITHUB_TOKEN;
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+const handler = new WebhookHandler({
+    dailyBudget: parseInt(process.env.WEBHOOK_DAILY_BUDGET ?? "20", 10),
+    debounceMs: parseInt(process.env.WEBHOOK_DEBOUNCE_MS ?? "10000", 10), // 10s for local dev
+    githubToken: GITHUB_TOKEN,
+    rootDir: ROOT,
+});
+// ---------------------------------------------------------------------------
+// HTTP Server
+// ---------------------------------------------------------------------------
+const server = createServer((req, res) => {
+    void handleRequest(req, res);
+});
+async function handleRequest(req, res) {
+    const url = new URL(req.url ?? "/", `http://localhost:${PORT}`);
+    // CORS headers for local dev
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    if (req.method === "OPTIONS") {
+        res.writeHead(200);
+        res.end();
+        return;
+    }
+    // Health check
+    if (url.pathname === "/health" && req.method === "GET") {
+        const diagnostics = handler.diagnostics();
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ dryRun: DRY_RUN, ...diagnostics }, null, 2));
+        return;
+    }
+    // Mappings
+    if (url.pathname === "/mappings" && req.method === "GET") {
+        const reverseMapping = buildReverseMapping(ROOT);
+        const slugs = allTrackedSlugs(reverseMapping);
+        const mappings = Object.fromEntries(slugs.map((slug) => [slug, reverseMapping.get(slug)]));
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ mappings, slugCount: slugs.length }, null, 2));
+        return;
+    }
+    // Webhook handler
+    if (url.pathname === "/webhook" && req.method === "POST") {
+        const body = await readBody(req);
+        let payload;
+        try {
+            payload = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid JSON" }));
+            return;
+        }
+        if (DRY_RUN) {
+            console.log("\n  🔶 DRY RUN — would dispatch (no GITHUB_TOKEN set)");
+        }
+        const result = handler.handle(payload);
+        console.log(`  → ${result.status}:`, JSON.stringify(result));
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result, null, 2));
+        return;
+    }
+    // 404
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+        endpoints: ["POST /webhook", "GET /health", "GET /mappings"],
+        error: "Not found",
+    }));
+}
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+server.listen(PORT, () => {
+    const reverseMapping = buildReverseMapping(ROOT);
+    const slugCount = allTrackedSlugs(reverseMapping).length;
+    console.log();
+    console.log("=== AILF Webhook Server ===");
+    console.log();
+    console.log(`  Port:           ${PORT}`);
+    console.log(`  Mode:           ${DRY_RUN ? "DRY RUN (set GITHUB_TOKEN to dispatch)" : "LIVE"}`);
+    console.log(`  Tracked slugs:  ${slugCount}`);
+    console.log(`  Debounce:       ${handler.diagnostics().pendingSlugs}`);
+    console.log();
+    console.log("  Endpoints:");
+    console.log(`    POST http://localhost:${PORT}/webhook   — handle webhook`);
+    console.log(`    GET  http://localhost:${PORT}/health    — diagnostics`);
+    console.log(`    GET  http://localhost:${PORT}/mappings  — slug → area map`);
+    console.log();
+});
+// Graceful shutdown
+process.on("SIGINT", () => {
+    console.log("\n  Shutting down — flushing debounce window...");
+    void handler.shutdown().then(() => {
+        server.close();
+        process.exit(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+        req.on("error", reject);
+    });
+}

package/dist/scripts/weekly-digest.d.ts

@@ -0,0 +1,24 @@
+/**
+ * weekly-digest.ts
+ *
+ * CLI script to generate and deliver a weekly evaluation digest.
+ *
+ * Queries the Sanity Content Lake for all reports within the configured
+ * lookback window, computes trend analysis, and delivers the digest
+ * via configured channels (Slack, stdout, or both).
+ *
+ * Usage:
+ *   pnpm weekly-digest                    # send to configured Slack webhook
+ *   pnpm weekly-digest --dry-run          # print to stdout only
+ *   pnpm weekly-digest --lookback 14      # 14-day lookback window
+ *   pnpm weekly-digest --json             # output raw JSON
+ *
+ * Environment variables:
+ *   SLACK_WEBHOOK_URL     — Slack incoming webhook URL
+ *   SANITY_API_TOKEN      — Sanity read token
+ *   AILF_TRIGGER_TYPE     — set to "scheduled" by the cron workflow
+ *   AILF_SCHEDULE         — the schedule name (e.g., "weekly-digest")
+ *
+ * @see docs/design-docs/report-store/implementation.md — Phase 5
+ */
+export {};

package/dist/scripts/weekly-digest.js

@@ -0,0 +1,144 @@
+/**
+ * weekly-digest.ts
+ *
+ * CLI script to generate and deliver a weekly evaluation digest.
+ *
+ * Queries the Sanity Content Lake for all reports within the configured
+ * lookback window, computes trend analysis, and delivers the digest
+ * via configured channels (Slack, stdout, or both).
+ *
+ * Usage:
+ *   pnpm weekly-digest                    # send to configured Slack webhook
+ *   pnpm weekly-digest --dry-run          # print to stdout only
+ *   pnpm weekly-digest --lookback 14      # 14-day lookback window
+ *   pnpm weekly-digest --json             # output raw JSON
+ *
+ * Environment variables:
+ *   SLACK_WEBHOOK_URL     — Slack incoming webhook URL
+ *   SANITY_API_TOKEN      — Sanity read token
+ *   AILF_TRIGGER_TYPE     — set to "scheduled" by the cron workflow
+ *   AILF_SCHEDULE         — the schedule name (e.g., "weekly-digest")
+ *
+ * @see docs/design-docs/report-store/implementation.md — Phase 5
+ */
+import { config as dotenvConfig } from "dotenv";
+import { existsSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { generateDigest } from "../schedules/digest.js";
+import { getDigestConfig } from "../schedules/loader.js";
+import { formatWeeklyDigest } from "../sinks/slack/format.js";
+// Load root .env (same override behavior as pipeline.ts)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(__dirname, "..", "..", "..", "..", ".env");
+if (existsSync(envPath)) {
+    dotenvConfig({ override: true, path: envPath });
+}
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+function getOption(name) {
+    const idx = args.indexOf(`--${name}`);
+    return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+function hasFlag(name) {
+    return args.includes(`--${name}`);
+}
+const DRY_RUN = hasFlag("dry-run");
+const JSON_OUTPUT = hasFlag("json");
+const lookbackOverride = getOption("lookback");
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    console.log();
+    console.log("=== AI Literacy Weekly Digest ===");
+    console.log();
+    // Load digest config
+    const digestConfig = getDigestConfig();
+    const lookbackDays = lookbackOverride
+        ? parseInt(lookbackOverride, 10)
+        : (digestConfig?.lookbackDays ?? 7);
+    console.log(`  Lookback: ${lookbackDays} days`);
+    console.log(`  Mode: ${DRY_RUN ? "dry run (stdout only)" : "live"}`);
+    console.log();
+    // Generate digest — uses AILF_REPORT_* env vars for report store access,
+    // independent of SANITY_DATASET/SANITY_PROJECT_ID (which control doc evaluation)
+    const digest = await generateDigest({
+        dataset: process.env.AILF_REPORT_DATASET,
+        lookbackDays,
+        projectId: process.env.AILF_REPORT_PROJECT_ID,
+        token: process.env.AILF_REPORT_SANITY_API_TOKEN ?? process.env.SANITY_API_TOKEN,
+    });
+    if (!digest) {
+        console.log("  No reports found in the lookback window. Nothing to send.");
+        process.exit(0);
+    }
+    // Output
+    console.log(`  Reports found: ${digest.reportCount}`);
+    console.log(`  Overall: ${Math.round(digest.overallLatest)} (${digest.overallTrend})`);
+    console.log(`  Improved: ${digest.improved.join(", ") || "none"}`);
+    console.log(`  Regressed: ${digest.regressed.join(", ") || "none"}`);
+    console.log(`  Stable: ${digest.stable.join(", ") || "none"}`);
+    console.log();
+    if (JSON_OUTPUT) {
+        console.log(JSON.stringify(digest, null, 2));
+        return;
+    }
+    // Format for Slack
+    const message = formatWeeklyDigest(digest);
+    if (DRY_RUN) {
+        console.log("  --- Slack Message Preview ---");
+        console.log(`  Text: ${message.text}`);
+        console.log();
+        for (const block of message.blocks) {
+            if (block.text) {
+                console.log(`  [${block.type}] ${block.text.text}`);
+            }
+            if (block.fields) {
+                for (const field of block.fields) {
+                    console.log(`    [field] ${field.text}`);
+                }
+            }
+            if (block.elements) {
+                for (const el of block.elements) {
+                    console.log(`    [element] ${el.text}`);
+                }
+            }
+        }
+        console.log();
+        return;
+    }
+    // Deliver via Slack
+    const webhookUrl = digestConfig?.slackWebhookUrl ?? process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) {
+        console.warn("  ⚠️  No Slack webhook URL configured. Set SLACK_WEBHOOK_URL or configure in schedules.yaml");
+        console.log("  Printing digest to stdout instead:");
+        console.log();
+        console.log(`  ${message.text}`);
+        return;
+    }
+    console.log("  Sending to Slack...");
+    try {
+        const response = await fetch(webhookUrl, {
+            body: JSON.stringify(message),
+            headers: { "Content-Type": "application/json" },
+            method: "POST",
+        });
+        if (response.ok) {
+            console.log("  ✅ Digest sent successfully");
+        }
+        else {
+            const text = await response.text();
+            console.warn(`  ⚠️  Slack delivery failed: ${response.status} ${text}`);
+        }
+    }
+    catch (error) {
+        console.warn(`  ⚠️  Slack delivery error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/sinks/format-slack.d.ts

@@ -0,0 +1,64 @@
+/**
+ * sinks/format-slack.ts
+ *
+ * Formats evaluation report data into Slack Block Kit structures for the
+ * SlackSink. Provides two message formats:
+ *
+ * - `formatRegressionAlert` — detailed regression notification with
+ *   per-area dimension breakdowns
+ * - `formatScoreSummary` — compact score overview for general reporting
+ *
+ * @see docs/design-docs/report-store/sink-architecture.md
+ */
+import type { Report } from "../pipeline/types.js";
+import type { DigestSummary } from "../schedules/digest.js";
+export interface SlackMessage {
+    blocks: SlackBlock[];
+    text: string;
+}
+interface SlackBlock {
+    elements?: Array<{
+        text: string;
+        type: "mrkdwn" | "plain_text";
+    }>;
+    fields?: Array<{
+        text: string;
+        type: "mrkdwn" | "plain_text";
+    }>;
+    text?: {
+        text: string;
+        type: "mrkdwn" | "plain_text";
+    };
+    type: "context" | "divider" | "header" | "section";
+}
+/**
+ * Format a regression alert for areas that have regressed.
+ *
+ * Produces a rich Slack message with:
+ * - Header with overall score change
+ * - Context metadata (mode, source, timestamp, promptfoo link)
+ * - Per-area regression details with dimension breakdowns
+ * - Brief mentions of improved and unchanged areas
+ */
+export declare function formatRegressionAlert(report: Report): SlackMessage;
+/**
+ * Format a general score summary for Slack reporting.
+ *
+ * Produces a compact overview with:
+ * - Overall score with grade emoji
+ * - Per-area score table
+ * - Cost summary (if available)
+ * - Promptfoo link (if available)
+ */
+export declare function formatScoreSummary(report: Report): SlackMessage;
+/**
+ * Format a weekly digest summary for Slack.
+ *
+ * Produces a summary message covering score trends over a time window:
+ * - Header with overall trend direction and score
+ * - Per-area trend table with arrows
+ * - Lists of improved, regressed, and stable areas
+ * - Report count and time window metadata
+ */
+export declare function formatWeeklyDigest(digest: DigestSummary): SlackMessage;
+export {};

package/dist/sinks/format-slack.js

@@ -0,0 +1,306 @@
+/**
+ * sinks/format-slack.ts
+ *
+ * Formats evaluation report data into Slack Block Kit structures for the
+ * SlackSink. Provides two message formats:
+ *
+ * - `formatRegressionAlert` — detailed regression notification with
+ *   per-area dimension breakdowns
+ * - `formatScoreSummary` — compact score overview for general reporting
+ *
+ * @see docs/design-docs/report-store/sink-architecture.md
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Format a regression alert for areas that have regressed.
+ *
+ * Produces a rich Slack message with:
+ * - Header with overall score change
+ * - Context metadata (mode, source, timestamp, promptfoo link)
+ * - Per-area regression details with dimension breakdowns
+ * - Brief mentions of improved and unchanged areas
+ */
+export function formatRegressionAlert(report) {
+    const { comparison, provenance, summary } = report;
+    if (!comparison) {
+        return {
+            blocks: [
+                {
+                    text: { text: "⚠️ No comparison data available", type: "mrkdwn" },
+                    type: "section",
+                },
+            ],
+            text: "No comparison data available",
+        };
+    }
+    const baselineScore = Math.round(comparison.baseline.overall.avgScore);
+    const experimentScore = Math.round(comparison.experiment.overall.avgScore);
+    const delta = Math.round(comparison.deltas.overall);
+    const blocks = [];
+    // Header — emoji + title + overall score change
+    blocks.push({
+        text: {
+            text: `📉 *AI Literacy Score Regression*\n` +
+                `Overall: ${baselineScore} → ${experimentScore} (${formatDelta(delta)})`,
+            type: "mrkdwn",
+        },
+        type: "section",
+    });
+    // Context — mode, source, timestamp, promptfoo link
+    const contextElements = [
+        { text: `*Mode:* ${provenance.mode}`, type: "mrkdwn" },
+        { text: `*Source:* ${provenance.source.name}`, type: "mrkdwn" },
+        { text: `*Date:* ${readableDate(summary.timestamp)}`, type: "mrkdwn" },
+    ];
+    if (provenance.promptfooUrl) {
+        contextElements.push({
+            text: `<${provenance.promptfooUrl}|View in Promptfoo>`,
+            type: "mrkdwn",
+        });
+    }
+    blocks.push({ elements: contextElements, type: "context" });
+    // Divider
+    blocks.push({ type: "divider" });
+    // Regressed areas — detailed fields with dimension breakdowns
+    const regressedAreas = comparison.areas.filter((a) => a.change === "regressed");
+    if (regressedAreas.length > 0) {
+        const fields = regressedAreas.map((area) => ({
+            text: `*${area.area}:* ${Math.round(area.baseline)} → ` +
+                `${Math.round(area.experiment)} (${formatDelta(Math.round(area.delta))})\n` +
+                dimensionBreakdown(area.dimensions),
+            type: "mrkdwn",
+        }));
+        blocks.push({
+            fields,
+            text: {
+                text: `*Regressed Areas (${regressedAreas.length})*`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    // Improved areas — compact mention
+    if (comparison.improved.length > 0) {
+        blocks.push({
+            text: {
+                text: `📈 ${comparison.improved.length} area${comparison.improved.length === 1 ? "" : "s"} improved: ${comparison.improved.join(", ")}`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    // Unchanged areas — brief mention
+    if (comparison.unchanged.length > 0) {
+        blocks.push({
+            text: {
+                text: `➡️ ${comparison.unchanged.length} area${comparison.unchanged.length === 1 ? "" : "s"} unchanged`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    return {
+        blocks,
+        text: `📉 AI Literacy Score Regression: ${baselineScore} → ${experimentScore} (${formatDelta(delta)})`,
+    };
+}
+/**
+ * Format a general score summary for Slack reporting.
+ *
+ * Produces a compact overview with:
+ * - Overall score with grade emoji
+ * - Per-area score table
+ * - Cost summary (if available)
+ * - Promptfoo link (if available)
+ */
+export function formatScoreSummary(report) {
+    const { provenance, summary } = report;
+    const overall = Math.round(summary.overall.avgScore);
+    const blocks = [];
+    // Header — overall score with emoji
+    blocks.push({
+        text: {
+            text: `${gradeEmoji(overall)} *AI Literacy Score: ${overall}*`,
+            type: "mrkdwn",
+        },
+        type: "section",
+    });
+    // Context — mode, source
+    const contextElements = [
+        { text: `*Mode:* ${provenance.mode}`, type: "mrkdwn" },
+        { text: `*Source:* ${provenance.source.name}`, type: "mrkdwn" },
+        { text: `*Date:* ${readableDate(summary.timestamp)}`, type: "mrkdwn" },
+    ];
+    blocks.push({ elements: contextElements, type: "context" });
+    // Divider
+    blocks.push({ type: "divider" });
+    // Per-area score table as markdown
+    const rows = summary.scores
+        .map((s) => {
+        const emoji = gradeEmoji(s.totalScore);
+        return `${emoji} *${s.feature}*: ${Math.round(s.totalScore)}  _(T:${Math.round(s.taskCompletion)} · C:${Math.round(s.codeCorrectness)} · D:${Math.round(s.docCoverage)})_`;
+    })
+        .join("\n");
+    blocks.push({
+        text: { text: rows, type: "mrkdwn" },
+        type: "section",
+    });
+    // Cost summary
+    if (summary.overall.cost) {
+        blocks.push({
+            text: {
+                text: `💰 Total cost: $${summary.overall.cost.total.toFixed(2)} ($${summary.overall.cost.perTest.toFixed(3)}/test)`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    // Promptfoo link
+    if (provenance.promptfooUrl) {
+        blocks.push({
+            text: {
+                text: `🔗 <${provenance.promptfooUrl}|View full results in Promptfoo>`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    return {
+        blocks,
+        text: `${gradeEmoji(overall)} AI Literacy Score: ${overall}`,
+    };
+}
+/**
+ * Format a weekly digest summary for Slack.
+ *
+ * Produces a summary message covering score trends over a time window:
+ * - Header with overall trend direction and score
+ * - Per-area trend table with arrows
+ * - Lists of improved, regressed, and stable areas
+ * - Report count and time window metadata
+ */
+export function formatWeeklyDigest(digest) {
+    const trendEmoji = digest.overallTrend === "improving"
+        ? "📈"
+        : digest.overallTrend === "regressing"
+            ? "📉"
+            : "➡️";
+    const blocks = [];
+    // Header — overall trend
+    blocks.push({
+        text: {
+            text: `${trendEmoji} *Weekly AI Literacy Digest*\n` +
+                `Overall: ${Math.round(digest.overallLatest)} (${formatDelta(Math.round(digest.overallDelta))} this week)`,
+            type: "mrkdwn",
+        },
+        type: "section",
+    });
+    // Context — time window and report count
+    blocks.push({
+        elements: [
+            {
+                text: `*Period:* ${readableDate(digest.lookbackStart)} – ${readableDate(digest.lookbackEnd)}`,
+                type: "mrkdwn",
+            },
+            {
+                text: `*Reports:* ${digest.reportCount}`,
+                type: "mrkdwn",
+            },
+        ],
+        type: "context",
+    });
+    blocks.push({ type: "divider" });
+    // Per-area trend table
+    if (digest.areaTrends.length > 0) {
+        const rows = digest.areaTrends
+            .map((t) => {
+            const arrow = t.trend === "improving" ? "↑" : t.trend === "regressing" ? "↓" : "→";
+            const emoji = gradeEmoji(t.lastScore);
+            return `${emoji} *${t.area}*: ${Math.round(t.lastScore)} ${arrow} (${formatDelta(Math.round(t.scoreDelta))})`;
+        })
+            .join("\n");
+        blocks.push({
+            text: { text: rows, type: "mrkdwn" },
+            type: "section",
+        });
+    }
+    // Summary badges
+    if (digest.improved.length > 0) {
+        blocks.push({
+            text: {
+                text: `📈 *Improved:* ${digest.improved.join(", ")}`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    if (digest.regressed.length > 0) {
+        blocks.push({
+            text: {
+                text: `📉 *Regressed:* ${digest.regressed.join(", ")}`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    if (digest.stable.length > 0) {
+        blocks.push({
+            text: {
+                text: `➡️ *Stable:* ${digest.stable.join(", ")}`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    // Cost summary if available
+    if (digest.totalCost !== undefined) {
+        blocks.push({
+            text: {
+                text: `💰 Total evaluation cost this week: ${digest.totalCost.toFixed(2)}`,
+                type: "mrkdwn",
+            },
+            type: "section",
+        });
+    }
+    return {
+        blocks,
+        text: `${trendEmoji} Weekly AI Literacy Digest: ${Math.round(digest.overallLatest)} (${formatDelta(Math.round(digest.overallDelta))})`,
+    };
+}
+/** Build a dimension breakdown string for an area delta */
+function dimensionBreakdown(dimensions) {
+    return [
+        `Task: ${formatDelta(dimensions.taskCompletion.delta)}`,
+        `Code: ${formatDelta(dimensions.codeCorrectness.delta)}`,
+        `Docs: ${formatDelta(dimensions.docCoverage.delta)}`,
+    ].join(" · ");
+}
+/** Format a numeric delta with explicit sign: "+4", "-2", or "0" */
+function formatDelta(n) {
+    if (n > 0)
+        return `+${n}`;
+    if (n < 0)
+        return `${n}`;
+    return "0";
+}
+/** Score-tier emoji: ✅ (≥80), 🟡 (≥70), 🟠 (≥50), 🔴 (<50) */
+function gradeEmoji(score) {
+    if (score >= 80)
+        return "✅";
+    if (score >= 70)
+        return "🟡";
+    if (score >= 50)
+        return "🟠";
+    return "🔴";
+}
+/** Format an ISO timestamp into a readable date string */
+function readableDate(iso) {
+    const d = new Date(iso);
+    return d.toLocaleDateString("en-US", {
+        day: "numeric",
+        month: "short",
+        year: "numeric",
+    });
+}