stilltrue 0.0.1 → 0.1.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,77 @@
 #!/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 { parseArgs } from 'node:util';
+import { findConfigPath, loadConfig } from "./loadConfig.js";
+import { runDrift } from "./runner.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' },
+        },
+    });
+    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}`);
+    }
+    return rotted > 0 ? 1 : 0;
+}
+const [command, ...rest] = process.argv.slice(2);
+try {
+    switch (command) {
+        case 'drift':
+            process.exit(await drift(rest));
+            break;
+        case 'golden':
+        case 'report':
+            console.error(`stilltrue ${command}: 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>]');
+            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/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/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.1.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": {