stilltrue 0.0.1 → 0.2.0

package/README.md

@@ -32,11 +32,47 @@ Drift has three outcomes, never two: `pass`, `rot` (facts changed — fail the
 build), and `error` (source unreachable — warn, don't fail). Conflating the
 last two causes alarm fatigue.
 
+## Quick start
+
+```ts
+// stilltrue.config.ts (or .mjs / .js)
+import { defineStilltrue, corpus, json, surname } from 'stilltrue';
+
+export default defineStilltrue({
+  drift: [
+    {
+      name: 'school-board-roster',
+      source: corpus(['https://district.example.org/board']),
+      expect: json('./data/school-board.json', (d) => d.members.map((m) => surname(m.name))),
+      compare: 'contains-all',
+    },
+  ],
+});
+```
+
+```yaml
+# .github/workflows/drift.yml
+on:
+  schedule: [{ cron: '17 14 * * 3' }]  # off-beat minute: GitHub drops :00 crons
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22' }
+      - run: npm ci
+      - run: npx stilltrue drift
+```
+
+`source` is your code (fetch+parse, or LLM extraction — the comparison stays
+deterministic either way). `expect` is your curated file. Rot fails the run
+with one message per vanished fact; unreachable sources only warn.
+
 ## Status
 
-Pre-v0.1. Current state: config seam design (`src/config.ts`) validated
-against two real production checks (`examples/stilltrue.config.ts`). Next:
-the drift runner, then swapping AskGwinnett's bespoke GitHub Actions to it.
+v0.1 — `drift` is real and running in production (AskGwinnett). `golden` and
+`verify` are designed but not yet shipped; see the brief.
 
 ## License
 

package/dist/cli.js

@@ -1,19 +1,110 @@
 #!/usr/bin/env node
 /**
- * npx stilltrue drift   — run drift checks (v0.1 scope)
- * npx stilltrue golden  — regression evals (later)
- * npx stilltrue report  — HTML drift report (later)
+ * npx stilltrue drift [--config <path>] [--only <name,name>] [--json <path>]
+ *
+ * Exit codes: 0 = all pass (errors warn but never fail — a judge/source
+ * outage must not block CI), 1 = rot detected or usage error.
  */
-const [command] = process.argv.slice(2);
-switch (command) {
-    case 'drift':
-        console.error('stilltrue drift: not implemented yet — see docs/BRIEF.md, First session §3');
-        process.exit(1);
-    case undefined:
-        console.log('usage: stilltrue <drift|golden|report>');
-        process.exit(1);
-    default:
-        console.error(`stilltrue: unknown command "${command}"`);
-        process.exit(1);
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { findConfigPath, loadConfig } from "./loadConfig.js";
+import { runDrift } from "./runner.js";
+import { DEFAULT_HISTORY_PATH, loadHistory, recordRun } from "./history.js";
+import { renderReport } from "./report.js";
+const GH = !!process.env.GITHUB_ACTIONS;
+function printResult(r) {
+    const icon = { pass: '✓', rot: '✗', error: '⚠' }[r.outcome];
+    console.log(`${icon} ${r.name} — ${r.outcome} (${r.durationMs}ms)`);
+    for (const w of r.warnings) {
+        console.log(`    warning: ${w}`);
+        if (GH)
+            console.log(`::warning::${r.name}: ${w}`);
+    }
+    for (const m of r.messages) {
+        console.log(`    ${m}`);
+        if (GH)
+            console.log(`::${r.outcome === 'rot' ? 'error' : 'warning'}::${r.name}: ${m}`);
+    }
+}
+async function drift(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            config: { type: 'string' },
+            only: { type: 'string' },
+            json: { type: 'string' },
+            record: { type: 'boolean' },
+            history: { type: 'string' },
+        },
+    });
+    const configPath = findConfigPath(process.cwd(), values.config);
+    const { config, configDir } = await loadConfig(configPath);
+    if (!config.drift?.length) {
+        console.error('no drift checks configured');
+        return 1;
+    }
+    const results = await runDrift(config, {
+        configDir,
+        only: values.only ? values.only.split(',').map((s) => s.trim()) : undefined,
+    });
+    for (const r of results)
+        printResult(r);
+    const rotted = results.filter((r) => r.outcome === 'rot').length;
+    const errored = results.filter((r) => r.outcome === 'error').length;
+    const passed = results.filter((r) => r.outcome === 'pass').length;
+    console.log(`\n${passed} pass, ${rotted} rot, ${errored} error (errors warn, never fail)`);
+    if (values.json) {
+        await writeFile(values.json, JSON.stringify(results, null, 2));
+        console.log(`results written to ${values.json}`);
+    }
+    if (values.record) {
+        const historyPath = resolve(values.history ?? DEFAULT_HISTORY_PATH);
+        await recordRun(results, historyPath);
+        console.log(`run recorded to ${historyPath}`);
+    }
+    return rotted > 0 ? 1 : 0;
+}
+async function report(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            history: { type: 'string' },
+            out: { type: 'string' },
+            title: { type: 'string' },
+        },
+    });
+    const historyPath = resolve(values.history ?? DEFAULT_HISTORY_PATH);
+    const history = await loadHistory(historyPath);
+    if (!history.length) {
+        console.error(`no recorded runs at ${historyPath} — run \`stilltrue drift --record\` first (use --history to point elsewhere)`);
+        return 1;
+    }
+    const out = resolve(values.out ?? 'stilltrue-report.html');
+    await writeFile(out, renderReport(history, values.title));
+    console.log(`report written to ${out} (${history.length} runs)`);
+    return 0;
+}
+const [command, ...rest] = process.argv.slice(2);
+try {
+    switch (command) {
+        case 'drift':
+            process.exit(await drift(rest));
+            break;
+        case 'report':
+            process.exit(await report(rest));
+            break;
+        case 'golden':
+            console.error('stilltrue golden: not implemented yet — drift shipped first (docs/BRIEF.md)');
+            process.exit(1);
+            break;
+        default:
+            console.log('usage: stilltrue drift [--config <path>] [--only <names>] [--json <path>] [--record] [--history <path>]\n' +
+                '       stilltrue report [--history <path>] [--out <path>] [--title <text>]');
+            process.exit(command ? 1 : 0);
+    }
+}
+catch (err) {
+    console.error(`stilltrue: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
 }
-export {};

package/dist/compare.d.ts

@@ -0,0 +1,2 @@
+import type { Compare, CompareFn } from './config.ts';
+export declare function resolveCompare<E, A>(compare: Compare<E, A> | undefined): CompareFn<E, A>;

package/dist/compare.js

@@ -0,0 +1,57 @@
+/**
+ * 'contains-all': expected is a list of marker strings, actual is a text
+ * corpus. Case-insensitive. The drift signal used by the original
+ * school-board check: a curated name/fact vanishing from the live pages.
+ */
+function containsAll(expected, actual) {
+    if (!Array.isArray(expected)) {
+        throw new TypeError(`contains-all: expected must be string[], got ${typeof expected}`);
+    }
+    if (typeof actual !== 'string') {
+        throw new TypeError(`contains-all: actual must be a string corpus, got ${typeof actual}`);
+    }
+    const corpus = actual.toLowerCase();
+    return expected
+        .filter((marker) => !corpus.includes(String(marker).toLowerCase()))
+        .map((marker) => `marker no longer present in source: "${marker}"`);
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Structural deep-equal with pathed mismatch messages. */
+function deepEqual(expected, actual, path = '$') {
+    if (Array.isArray(expected) && Array.isArray(actual)) {
+        const messages = [];
+        if (expected.length !== actual.length) {
+            messages.push(`${path}: length ${expected.length} → ${actual.length}`);
+        }
+        const len = Math.min(expected.length, actual.length);
+        for (let i = 0; i < len; i++) {
+            messages.push(...deepEqual(expected[i], actual[i], `${path}[${i}]`));
+        }
+        return messages;
+    }
+    if (isPlainObject(expected) && isPlainObject(actual)) {
+        const messages = [];
+        for (const key of new Set([...Object.keys(expected), ...Object.keys(actual)])) {
+            if (!(key in actual))
+                messages.push(`${path}.${key}: missing from source`);
+            else if (!(key in expected))
+                messages.push(`${path}.${key}: unexpected new value ${JSON.stringify(actual[key])}`);
+            else
+                messages.push(...deepEqual(expected[key], actual[key], `${path}.${key}`));
+        }
+        return messages;
+    }
+    if (expected !== actual) {
+        return [`${path}: expected ${JSON.stringify(expected)}, source has ${JSON.stringify(actual)}`];
+    }
+    return [];
+}
+export function resolveCompare(compare) {
+    if (compare === undefined || compare === 'deep-equal')
+        return (e, a) => deepEqual(e, a);
+    if (compare === 'contains-all')
+        return (e, a) => containsAll(e, a);
+    return compare;
+}

package/dist/config.d.ts

@@ -1,13 +1,14 @@
 /**
- * The config seam — the entire product is "the package owns the *how*,
- * the consumer's config owns the *what*." (docs/BRIEF.md, First session §2)
- *
- * Designed against two real checks before the runner exists:
- * see examples/stilltrue.config.ts (GCPS board roster + BOC refresh).
+ * The config seam — the package owns the *how*, the consumer's config owns
+ * the *what*. Designed against the real production check it replaces
+ * (bfoster-services scripts/check-school-board-drift.js): fetch pages into a
+ * text corpus, assert curated markers still appear, tolerate partial fetch
+ * failures with warnings, and never conflate "facts changed" with "source
+ * unreachable".
  */
-/** What a drift check found. Three outcomes, never two (BRIEF §First session 4). */
+/** Three outcomes, never two (docs/BRIEF.md, First session §4). */
 export type DriftOutcome = 
-/** Live source still matches the expected file. */
+/** Live source still matches the curated facts. */
 'pass'
 /** Facts no longer match — fail the build. A human fixes. */
  | 'rot'
@@ -16,36 +17,45 @@ export type DriftOutcome =
 export interface DriftResult {
     name: string;
     outcome: DriftOutcome;
-    /** Human-readable detail: the diff for `rot`, the cause for `error`. */
+    /** One issue per entry: the mismatches for `rot`, the cause for `error`. */
     messages: string[];
-    /** Structured diff when outcome is `rot`, for the HTML report. */
-    diff?: {
-        expected: unknown;
-        actual: unknown;
-    };
+    /** Non-fatal notes (e.g. one of several pages unreachable). */
+    warnings: string[];
     checkedAt: string;
+    durationMs: number;
+}
+/** Passed to consumer `source`/`expect` functions. */
+export interface CheckContext {
+    /** Record a non-fatal problem (partial fetch failure, odd markup, …). */
+    warn: (message: string) => void;
+    /** Absolute directory of the loaded config file — resolve data paths from here. */
+    configDir: string;
 }
 /**
- * One curated fact vs its live authoritative source.
+ * Deterministic comparison: returns mismatch messages, [] = pass.
+ * Built-ins: 'contains-all' (expected: string[] markers, actual: corpus
+ * string, case-insensitive) and 'deep-equal'.
+ */
+export type CompareFn<E, A> = (expected: E, actual: A) => string[];
+export type Compare<E, A> = 'contains-all' | 'deep-equal' | CompareFn<E, A>;
+/**
+ * One curated fact-set vs its live authoritative source.
  *
- * `source()` is the consumer's code — it may fetch+parse deterministically
- * or use an LLM to extract structure from a messy page; the package neither
- * knows nor cares. The comparison stays deterministic either way.
+ * `source()` is consumer code — deterministic fetch+parse or LLM extraction,
+ * the package neither knows nor cares; a throw means outcome `error`, never
+ * `rot`. The comparison is always deterministic.
  */
-export interface DriftCheck<T = unknown> {
+export interface DriftCheck<E = unknown, A = unknown> {
     name: string;
-    /** Fetch the live source and return structured data. Throw => `error`, never `rot`. */
-    source: () => Promise<T>;
-    /** Path to the curated expected file (JSON), or the expected value itself. */
-    expect: string | T;
-    /**
-     * How to compare. A named built-in ('deep-equal', 'surnames', ...) or a
-     * custom deterministic function returning mismatch messages ([] = pass).
-     */
-    compare?: string | ((expected: T, actual: T) => string[]);
+    /** Fetch the live source. Throw => `error`. */
+    source: (ctx: CheckContext) => Promise<A>;
+    /** The curated expectation: a value, or a function deriving it (e.g. from a data file). */
+    expect: E | ((ctx: CheckContext) => E | Promise<E>);
+    /** Defaults to 'deep-equal'. */
+    compare?: Compare<E, A>;
 }
 export interface StilltrueConfig {
-    drift?: DriftCheck<any>[];
+    drift?: DriftCheck<any, any>[];
     /** golden and verify are later phases — see docs/BRIEF.md build plan. */
     golden?: unknown;
     verify?: unknown;

package/dist/config.js

@@ -1,9 +1,10 @@
 /**
- * The config seam — the entire product is "the package owns the *how*,
- * the consumer's config owns the *what*." (docs/BRIEF.md, First session §2)
- *
- * Designed against two real checks before the runner exists:
- * see examples/stilltrue.config.ts (GCPS board roster + BOC refresh).
+ * The config seam — the package owns the *how*, the consumer's config owns
+ * the *what*. Designed against the real production check it replaces
+ * (bfoster-services scripts/check-school-board-drift.js): fetch pages into a
+ * text corpus, assert curated markers still appear, tolerate partial fetch
+ * failures with warnings, and never conflate "facts changed" with "source
+ * unreachable".
  */
 /** Identity function for typed configs: `export default defineStilltrue({...})`. */
 export function defineStilltrue(config) {

package/dist/helpers.d.ts

@@ -0,0 +1,28 @@
+import type { CheckContext } from './config.ts';
+export interface CorpusOptions {
+    /** Per-page fetch timeout, ms. Default 20000. */
+    timeoutMs?: number;
+    /** Sent as User-Agent so site operators can identify the check. */
+    userAgent?: string;
+}
+/** Strip a page to comparable text (same normalization as the original check). */
+export declare function htmlToText(html: string): string;
+/**
+ * Source helper: fetch pages and concatenate them into one text corpus.
+ * Individual unreachable pages warn; ALL pages unreachable throws, which the
+ * runner reports as `error` (source down ≠ facts rotted).
+ */
+export declare function corpus(urls: string[], options?: CorpusOptions): (ctx: CheckContext) => Promise<string>;
+/**
+ * Expect helper: read a curated JSON data file (path relative to the config
+ * file) and optionally derive the comparable expectation from it — e.g. the
+ * marker list for 'contains-all'.
+ */
+export declare function json<T = any, E = T>(path: string, derive?: (data: T) => E): (ctx: CheckContext) => Promise<E>;
+/**
+ * Surname as the drift signal — titles and first names vary in page copy
+ * ("Dr. Jane Smith" vs "Superintendent Smith"); the surname is stable.
+ * Leading honorifics and trailing generational suffixes are stripped
+ * ("Jasper Watkins III" → "Watkins").
+ */
+export declare function surname(fullName: string): string;

package/dist/helpers.js

@@ -0,0 +1,69 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** Strip a page to comparable text (same normalization as the original check). */
+export function htmlToText(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/\s+/g, ' ');
+}
+/**
+ * Source helper: fetch pages and concatenate them into one text corpus.
+ * Individual unreachable pages warn; ALL pages unreachable throws, which the
+ * runner reports as `error` (source down ≠ facts rotted).
+ */
+export function corpus(urls, options = {}) {
+    const { timeoutMs = 20_000, userAgent = 'stilltrue drift check (github.com/sg-bfoster/stilltrue)' } = options;
+    return async (ctx) => {
+        let text = '';
+        const unreachable = [];
+        for (const url of urls) {
+            try {
+                const res = await fetch(url, {
+                    signal: AbortSignal.timeout(timeoutMs),
+                    headers: { 'User-Agent': userAgent },
+                });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                text += ` ${htmlToText(await res.text())}`;
+            }
+            catch (err) {
+                unreachable.push(`${url} (${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
+        if (!text.trim()) {
+            throw new Error(`all pages unreachable: ${unreachable.join('; ')}`);
+        }
+        for (const miss of unreachable)
+            ctx.warn(`page unreachable: ${miss}`);
+        return text;
+    };
+}
+/**
+ * Expect helper: read a curated JSON data file (path relative to the config
+ * file) and optionally derive the comparable expectation from it — e.g. the
+ * marker list for 'contains-all'.
+ */
+export function json(path, derive) {
+    return async (ctx) => {
+        const data = JSON.parse(await readFile(resolve(ctx.configDir, path), 'utf8'));
+        return derive ? derive(data) : data;
+    };
+}
+/**
+ * Surname as the drift signal — titles and first names vary in page copy
+ * ("Dr. Jane Smith" vs "Superintendent Smith"); the surname is stable.
+ * Leading honorifics and trailing generational suffixes are stripped
+ * ("Jasper Watkins III" → "Watkins").
+ */
+export function surname(fullName) {
+    const cleaned = String(fullName)
+        .replace(/^(dr|mr|mrs|ms)\.?\s+/i, '')
+        .replace(/,?\s+(jr|sr|ii|iii|iv|v)\.?$/i, '')
+        .trim();
+    const parts = cleaned.split(/\s+/);
+    return parts[parts.length - 1] ?? '';
+}

package/dist/history.d.ts

@@ -0,0 +1,11 @@
+import type { DriftResult } from './config.ts';
+/** One recorded `stilltrue drift` run. */
+export interface RunRecord {
+    at: string;
+    results: DriftResult[];
+}
+export declare const DEFAULT_HISTORY_PATH = ".stilltrue/history.jsonl";
+/** Append a run to the JSONL history file (created on first record). */
+export declare function recordRun(results: DriftResult[], historyPath: string): Promise<RunRecord>;
+/** Load history oldest-first. Missing file → []. Corrupt lines are skipped. */
+export declare function loadHistory(historyPath: string): Promise<RunRecord[]>;

package/dist/history.js

@@ -0,0 +1,37 @@
+import { mkdir, readFile, appendFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export const DEFAULT_HISTORY_PATH = '.stilltrue/history.jsonl';
+/** Append a run to the JSONL history file (created on first record). */
+export async function recordRun(results, historyPath) {
+    const record = { at: new Date().toISOString(), results };
+    await mkdir(dirname(historyPath), { recursive: true });
+    await appendFile(historyPath, JSON.stringify(record) + '\n');
+    return record;
+}
+/** Load history oldest-first. Missing file → []. Corrupt lines are skipped. */
+export async function loadHistory(historyPath) {
+    let raw;
+    try {
+        raw = await readFile(historyPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const records = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed.at === 'string' && Array.isArray(parsed.results)) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            // A truncated line (interrupted CI write) shouldn't sink the report.
+        }
+    }
+    return records;
+}

package/dist/index.d.ts

@@ -1 +1,4 @@
-export { defineStilltrue, type StilltrueConfig, type DriftCheck, type DriftResult, type DriftOutcome, } from './config.js';
+export { defineStilltrue, type StilltrueConfig, type DriftCheck, type DriftResult, type DriftOutcome, type CheckContext, type Compare, type CompareFn, } from './config.ts';
+export { corpus, json, surname, htmlToText, type CorpusOptions } from './helpers.ts';
+export { runDrift, runDriftCheck, type RunDriftOptions } from './runner.ts';
+export { resolveCompare } from './compare.ts';

package/dist/index.js

@@ -1 +1,4 @@
-export { defineStilltrue, } from './config.js';
+export { defineStilltrue, } from "./config.js";
+export { corpus, json, surname, htmlToText } from "./helpers.js";
+export { runDrift, runDriftCheck } from "./runner.js";
+export { resolveCompare } from "./compare.js";

package/dist/loadConfig.d.ts

@@ -0,0 +1,6 @@
+import type { StilltrueConfig } from './config.ts';
+export declare function findConfigPath(cwd: string, explicit?: string): string;
+export declare function loadConfig(configPath: string): Promise<{
+    config: StilltrueConfig;
+    configDir: string;
+}>;

package/dist/loadConfig.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { createJiti } from 'jiti';
+const CANDIDATES = [
+    'stilltrue.config.ts',
+    'stilltrue.config.mts',
+    'stilltrue.config.js',
+    'stilltrue.config.mjs',
+    'stilltrue.config.cjs',
+];
+export function findConfigPath(cwd, explicit) {
+    if (explicit) {
+        const p = isAbsolute(explicit) ? explicit : resolve(cwd, explicit);
+        if (!existsSync(p))
+            throw new Error(`config not found: ${p}`);
+        return p;
+    }
+    for (const name of CANDIDATES) {
+        const p = join(cwd, name);
+        if (existsSync(p))
+            return p;
+    }
+    throw new Error(`no stilltrue.config.{ts,js,mjs,cjs} found in ${cwd}`);
+}
+export async function loadConfig(configPath) {
+    const jiti = createJiti(import.meta.url, { interopDefault: true });
+    const config = (await jiti.import(configPath, { default: true }));
+    if (!config || typeof config !== 'object') {
+        throw new Error(`config at ${configPath} has no default export object`);
+    }
+    return { config, configDir: dirname(configPath) };
+}

package/dist/report.d.ts

@@ -0,0 +1,2 @@
+import type { RunRecord } from './history.ts';
+export declare function renderReport(history: RunRecord[], title?: string): string;

package/dist/report.js

@@ -0,0 +1,120 @@
+const STATUS = {
+    pass: { color: '#0ca30c', glyph: '✓', ink: '#ffffff', label: 'pass' },
+    rot: { color: '#d03b3b', glyph: '✗', ink: '#ffffff', label: 'rot' },
+    error: { color: '#fab219', glyph: '⚠', ink: '#1a1a19', label: 'error' },
+};
+const MAX_COLUMNS = 60;
+const MAX_LOG = 50;
+function esc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+function day(iso) {
+    return iso.slice(5, 10); // MM-DD
+}
+export function renderReport(history, title = 'stilltrue drift report') {
+    const runs = history.slice(-MAX_COLUMNS);
+    const latest = runs[runs.length - 1];
+    // Stable row order: latest run's order first, then any check seen earlier.
+    const names = [];
+    for (const record of [...runs].reverse()) {
+        for (const r of record.results)
+            if (!names.includes(r.name))
+                names.push(r.name);
+    }
+    const counts = { pass: 0, rot: 0, error: 0 };
+    for (const r of latest?.results ?? [])
+        counts[r.outcome]++;
+    const tiles = ['pass', 'rot', 'error']
+        .map((o) => `<div class="tile">
+        <div class="tile-num" style="color:${counts[o] && o !== 'pass' ? STATUS[o].color : 'var(--ink)'}">${counts[o]}</div>
+        <div class="tile-label">${STATUS[o].glyph} ${STATUS[o].label}</div>
+      </div>`)
+        .join('');
+    const headerCells = runs
+        .map((rec, i) => {
+        const sparse = runs.length <= 10 || i % Math.ceil(runs.length / 10) === 0 || i === runs.length - 1;
+        return `<th title="${esc(rec.at)}">${sparse ? day(rec.at) : ''}</th>`;
+    })
+        .join('');
+    const rows = names
+        .map((name) => {
+        const cells = runs
+            .map((rec) => {
+            const r = rec.results.find((x) => x.name === name);
+            if (!r)
+                return '<td><span class="cell none" title="not run"></span></td>';
+            const s = STATUS[r.outcome];
+            const detail = [r.outcome, ...r.messages, ...r.warnings.map((w) => `warning: ${w}`)].join('\n');
+            return `<td><span class="cell" style="background:${s.color};color:${s.ink}" title="${esc(rec.at)}\n${esc(detail)}">${s.glyph}</span></td>`;
+        })
+            .join('');
+        return `<tr><th class="check-name">${esc(name)}</th>${cells}</tr>`;
+    })
+        .join('');
+    const events = [...runs]
+        .reverse()
+        .flatMap((rec) => rec.results
+        .filter((r) => r.outcome !== 'pass' || r.warnings.length)
+        .map((r) => ({ at: rec.at, ...r })))
+        .slice(0, MAX_LOG);
+    const log = events.length
+        ? events
+            .map((e) => {
+            const s = STATUS[e.outcome];
+            const items = [...e.messages, ...e.warnings.map((w) => `warning: ${w}`)]
+                .map((m) => `<li>${esc(m)}</li>`)
+                .join('');
+            return `<details ${e.outcome === 'rot' ? 'open' : ''}>
+            <summary><span class="badge" style="background:${s.color};color:${s.ink}">${s.glyph} ${s.label}</span>
+            <strong>${esc(e.name)}</strong> <span class="muted">${esc(e.at)}</span></summary>
+            <ul>${items}</ul>
+          </details>`;
+        })
+            .join('')
+        : '<p class="muted">Nothing has rotted, errored, or warned in recorded history.</p>';
+    return `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>
+  :root { --bg:#ffffff; --ink:#1a1a19; --ink-2:#5f5e5a; --line:#e4e2dd; --surface:#f6f5f2; }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg:#1a1a19; --ink:#f2f1ee; --ink-2:#a5a39d; --line:#3a3936; --surface:#242422; }
+  }
+  * { box-sizing: border-box; }
+  body { margin:0; padding:2rem 1.5rem; background:var(--bg); color:var(--ink);
+         font:15px/1.5 ui-sans-serif, system-ui, sans-serif; max-width:64rem; margin-inline:auto; }
+  h1 { font-size:1.3rem; margin:0 0 .25rem; }
+  h2 { font-size:1rem; margin:2rem 0 .75rem; }
+  .muted { color:var(--ink-2); font-size:.85rem; }
+  .tiles { display:flex; gap:.75rem; margin:1.25rem 0; flex-wrap:wrap; }
+  .tile { background:var(--surface); border:1px solid var(--line); border-radius:8px;
+          padding:.75rem 1.25rem; min-width:6.5rem; }
+  .tile-num { font-size:1.6rem; font-weight:600; font-variant-numeric:tabular-nums; }
+  .tile-label { color:var(--ink-2); font-size:.85rem; }
+  .grid-wrap { overflow-x:auto; border:1px solid var(--line); border-radius:8px; padding:.75rem; }
+  table { border-collapse:separate; border-spacing:2px; }
+  th { font-weight:500; color:var(--ink-2); font-size:.7rem; text-align:left; white-space:nowrap; }
+  thead th { vertical-align:bottom; padding-bottom:.25rem; }
+  .check-name { font-size:.85rem; color:var(--ink); padding-right:.75rem; position:sticky; left:0; background:var(--bg); }
+  .cell { display:inline-flex; width:20px; height:20px; border-radius:4px;
+          align-items:center; justify-content:center; font-size:12px; }
+  .cell.none { background:var(--surface); border:1px dashed var(--line); }
+  .badge { display:inline-block; border-radius:4px; padding:0 .45rem; font-size:.8rem; margin-right:.5rem; }
+  details { border-left:2px solid var(--line); padding:.35rem .75rem; margin:.4rem 0; }
+  summary { cursor:pointer; }
+  details ul { margin:.4rem 0 .2rem; padding-left:1.2rem; }
+  details li { font-size:.9rem; }
+</style>
+<h1>${esc(title)}</h1>
+<p class="muted">${runs.length} recorded run${runs.length === 1 ? '' : 's'}${latest ? `, latest ${esc(latest.at)}` : ''} — pass / rot (facts changed) / error (source unreachable)</p>
+<div class="tiles">${tiles}</div>
+<h2>Timeline</h2>
+<div class="grid-wrap"><table>
+  <thead><tr><th></th>${headerCells}</tr></thead>
+  <tbody>${rows}</tbody>
+</table></div>
+<h2>Rot, errors &amp; warnings</h2>
+${log}
+`;
+}

package/dist/runner.d.ts

@@ -0,0 +1,9 @@
+import type { DriftCheck, DriftResult, StilltrueConfig } from './config.ts';
+export interface RunDriftOptions {
+    /** Run only checks whose name is in this list. */
+    only?: string[];
+    /** Directory the config file was loaded from (data paths resolve here). */
+    configDir: string;
+}
+export declare function runDriftCheck(check: DriftCheck<any, any>, configDir: string): Promise<DriftResult>;
+export declare function runDrift(config: StilltrueConfig, options: RunDriftOptions): Promise<DriftResult[]>;

package/dist/runner.js

@@ -0,0 +1,45 @@
+import { resolveCompare } from "./compare.js";
+export async function runDriftCheck(check, configDir) {
+    const warnings = [];
+    const ctx = { warn: (m) => warnings.push(m), configDir };
+    const started = Date.now();
+    const done = (outcome, messages) => ({
+        name: check.name,
+        outcome,
+        messages,
+        warnings,
+        checkedAt: new Date(started).toISOString(),
+        durationMs: Date.now() - started,
+    });
+    let expected;
+    try {
+        expected = typeof check.expect === 'function' ? await check.expect(ctx) : check.expect;
+    }
+    catch (err) {
+        // A broken expectation is consumer misconfiguration, not source rot or
+        // source outage — surface it as `error` so CI warns loudly.
+        return done('error', [`expect failed: ${err instanceof Error ? err.message : String(err)}`]);
+    }
+    let actual;
+    try {
+        actual = await check.source(ctx);
+    }
+    catch (err) {
+        return done('error', [`source failed: ${err instanceof Error ? err.message : String(err)}`]);
+    }
+    try {
+        const mismatches = resolveCompare(check.compare)(expected, actual);
+        return mismatches.length ? done('rot', mismatches) : done('pass', []);
+    }
+    catch (err) {
+        return done('error', [`compare failed: ${err instanceof Error ? err.message : String(err)}`]);
+    }
+}
+export async function runDrift(config, options) {
+    const checks = (config.drift ?? []).filter((c) => !options.only || options.only.includes(c.name));
+    const results = [];
+    for (const check of checks) {
+        results.push(await runDriftCheck(check, options.configDir));
+    }
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stilltrue",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Your tests check your code. stilltrue checks your facts. CI checks for AI-in-the-loop apps: drift (curated facts vs live sources), golden (regression evals), verify (judge answers against sources).",
   "keywords": [
     "drift",
@@ -25,9 +25,10 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "node --test --experimental-strip-types test/*.test.ts"
+    "test": "node --test test/*.test.ts"
   },
   "dependencies": {
+    "jiti": "^2.7.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {