stilltrue 0.5.0 → 0.5.1

package/README.md

@@ -36,8 +36,8 @@ project folder with your facts saved in a JSON file.
 npm install --save-dev stilltrue
 ```
 
-**2. Scaffold a check** — this creates a ready-to-edit config file and an
-example facts file (it never overwrites anything you already have):
+**2. Scaffold a check** — this creates a ready-to-edit config file (it
+never overwrites anything you already have):
 
 ```bash
 npx stilltrue init
@@ -45,35 +45,52 @@ npx stilltrue init
 
 Open the generated `stilltrue.config.mjs`. Each check answers three
 questions: *where do I fetch the truth from* (`source`), *what do I
-believe* (`expect`), and *how do I compare the two* (`compare`):
+believe* (`expect`), and *how do I compare the two* (`compare`) — and in
+its simplest form, **the only editing needed is replacing strings**:
 
 ```js
-import { defineStilltrue, corpus, json, surname } from 'stilltrue';
+import { defineStilltrue, corpus } from 'stilltrue';
 
 export default defineStilltrue({
   drift: [
     {
-      name: 'school-board-roster',
-      // Where the truth lives: the district's own pages.
-      source: corpus(['https://www.myschooldistrict.org/board']),
-      // What you believe: read your saved file, keep just the last names.
-      expect: json('./data/school-board.json', (data) =>
-        data.members.map((m) => surname(m.name))
-      ),
-      // How to compare: every name must still appear on those pages.
+      name: 'my-first-check',
+      // Where the truth lives: the official page(s) your facts came from.
+      source: corpus(['https://example.org/about']),
+      // What you believe: your facts, as short strings ("markers").
+      expect: ['Jane Smith', 'Main Street Office', '12 locations'],
+      // How to compare: every marker must still appear on those pages.
       compare: 'contains-all',
     },
   ],
 });
 ```
 
-This example says: *fetch the board page, and make sure every last name in
-my `school-board.json` file still appears somewhere on it.*
+This says: *fetch that page, and make sure "Jane Smith", "Main Street
+Office", and "12 locations" all still appear on it.* Swap in your own URL
+and your own facts — that's a working check, no programming required.
 
 Choosing what to assert is the judgment call — surnames beat full names,
 "143 schools" beats a bare "143". The short guide:
 [docs/MARKERS.md](docs/MARKERS.md).
 
+**Leveling up (optional):** you don't have to keep the facts in the config.
+If `./data/markers.json` is just a list of strings, point at it with
+`expect: json('./data/markers.json')` — still no code. And if your app
+already keeps structured data, derive the markers from it so your data file
+stays the single source of truth:
+
+```js
+// ./data/school-board.json: { "members": [{ "name": "Dr. Jane Smith" }, ...] }
+expect: json('./data/school-board.json', (data) =>
+  data.members.map((m) => surname(m.name))   // keeps just "Smith" — titles
+),                                           // and first names vary on pages
+```
+
+The function receives *your* file's contents, whatever shape they are, and
+returns the list of markers — stilltrue never needs to understand your data
+structure. Update the data file and the markers update themselves.
+
 **3. Run it:**
 
 ```bash

package/dist/cli.js

@@ -103,9 +103,9 @@ try {
                 console.log(`kept existing ${f} (never overwritten)`);
             if (created.length) {
                 console.log('\nNext steps:\n' +
-                    '  1. Edit stilltrue.config.mjs — point source at the real page(s) your facts came from\n' +
-                    '  2. Edit data/example-facts.json — or point the config at a facts file you already have\n' +
-                    '  3. Run: npx stilltrue drift\n' +
+                    '  1. Edit stilltrue.config.mjs — point source at the real page(s) your facts came from,\n' +
+                    '     and replace the example markers with your own facts (plain strings)\n' +
+                    '  2. Run: npx stilltrue drift\n' +
                     'Picking good markers: docs/MARKERS.md in the stilltrue repo');
             }
             process.exit(0);

package/dist/init.d.ts

@@ -2,5 +2,5 @@ export interface InitResult {
     created: string[];
     skipped: string[];
 }
-/** Write starter config + example data file. Never overwrites. */
+/** Write the starter config. Never overwrites an existing one. */
 export declare function init(dir: string): Promise<InitResult>;

package/dist/init.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 const CONFIG_TEMPLATE = `// stilltrue configuration — one entry per fact-set you want watched.
@@ -10,47 +10,53 @@ export default defineStilltrue({
   drift: [
     {
       // A short id for this check — shows up in output and reports.
-      name: 'example-board-roster',
+      name: 'my-first-check',
 
       // WHERE THE TRUTH LIVES: the official page(s) your facts came from.
       // corpus() fetches each page and strips it down to readable text.
-      // If one page is unreachable it warns; only if ALL are down does the
-      // check report an error (which never fails your build).
       source: corpus([
-        'https://example.org/board',
-        // 'https://example.org/about',   // add more pages if facts span several
+        'https://example.org/about',
+        // 'https://example.org/board',   // add more pages if facts span several
       ]),
 
-      // WHAT YOU BELIEVE: read your saved facts file and pick out the
-      // "markers" — short, stable strings that must still appear on the
-      // page(s) above. Here: each member's last name, plus one number.
-      expect: json('./data/example-facts.json', (data) => [
-        ...data.members.map((m) => surname(m.name)),
-        \`\${data.totalSchools} schools\`,
-      ]),
+      // WHAT YOU BELIEVE: list the facts as short strings ("markers").
+      // Every one of these must still appear somewhere on the page(s)
+      // above, or the check fails and names the missing one.
+      expect: [
+        'Jane Smith',
+        'Main Street Office',
+        '12 locations',
+      ],
 
       // HOW TO COMPARE: 'contains-all' = every marker must appear in the
-      // fetched text (case-insensitive). Any missing marker = rot = the
-      // build fails and tells you which fact went stale.
+      // fetched page text (case-insensitive).
       compare: 'contains-all',
     },
+
+    // ── Leveling up (optional) ──────────────────────────────────────────
+    //
+    // Instead of listing markers inline, you can keep them in a file.
+    // If ./data/markers.json contains just a list of strings —
+    //   ["Jane Smith", "Main Street Office", "12 locations"]
+    // — then this works with no code at all:
+    //
+    //   expect: json('./data/markers.json'),
+    //
+    // And if your app already keeps structured data — say
+    // ./data/board.json looks like
+    //   { "members": [ { "name": "Dr. Jane Smith" }, { "name": "Bob Jones Jr." } ] }
+    // — you can derive the markers from it, so your data file stays the
+    // single source of truth (surname() keeps just "Smith" / "Jones",
+    // because pages change titles and first names more than surnames):
+    //
+    //   expect: json('./data/board.json', (data) =>
+    //     data.members.map((m) => surname(m.name))
+    //   ),
   ],
 });
 `;
-const DATA_TEMPLATE = `{
-  "_comment": "Example facts file - replace with your own data, or point the config at a file you already have.",
-  "members": [
-    { "name": "Dr. Jane Smith" },
-    { "name": "Robert Jones Jr." }
-  ],
-  "totalSchools": 12
-}
-`;
-/** Write starter config + example data file. Never overwrites. */
+/** Write the starter config. Never overwrites an existing one. */
 export async function init(dir) {
-    const created = [];
-    const skipped = [];
-    const configPath = join(dir, 'stilltrue.config.mjs');
     const existingConfig = [
         'stilltrue.config.mjs',
         'stilltrue.config.ts',
@@ -59,20 +65,8 @@ export async function init(dir) {
         'stilltrue.config.cjs',
     ].find((name) => existsSync(join(dir, name)));
     if (existingConfig) {
-        skipped.push(existingConfig);
-    }
-    else {
-        await writeFile(configPath, CONFIG_TEMPLATE);
-        created.push('stilltrue.config.mjs');
-    }
-    const dataPath = join(dir, 'data', 'example-facts.json');
-    if (existsSync(dataPath)) {
-        skipped.push('data/example-facts.json');
-    }
-    else {
-        await mkdir(join(dir, 'data'), { recursive: true });
-        await writeFile(dataPath, DATA_TEMPLATE);
-        created.push('data/example-facts.json');
+        return { created: [], skipped: [existingConfig] };
     }
-    return { created, skipped };
+    await writeFile(join(dir, 'stilltrue.config.mjs'), CONFIG_TEMPLATE);
+    return { created: ['stilltrue.config.mjs'], skipped: [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stilltrue",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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",