watertight 0.1.0 → 0.2.0

package/README.md

@@ -150,10 +150,31 @@ can reach, rewrites `value` and `fetched_at`, and recomputes derived values:
 - `command` sources — run **only** with the explicit `--allow-commands` flag,
   because refreshing an IR you didn't author must never execute its shell
   commands
+- any other source type can be covered by a **custom fetcher** — a JS module
+  you point at explicitly:
+
+  ```bash
+  watertight refresh . --fetchers ./my-fetchers.mjs
+  ```
+
+  ```js
+  // my-fetchers.mjs — export one function per source type
+  export async function mixpanel(source) {
+    // credentials from the environment, receipt fields from the IR
+    return valueFetchedFrom(source.project, source.bookmark)
+  }
+  ```
+
+  [`examples/fetchers/mixpanel.mjs`](./examples/fetchers/mixpanel.mjs) is a
+  working example. Loading a module runs its code, so only pass files you
+  wrote or trust — the IR itself can never name a fetcher. Built-in csv/json/
+  command adapters always win over a custom one of the same name.
 - everything else (dashboards, vendor reports, hypotheses) is **named as
   skipped** — never silently assumed fresh
 
-`--dry-run` previews changes without writing.
+Derived values follow their inputs: sums are recomputed exactly, percentage
+changes at the precision the author stated. `--dry-run` previews changes
+without writing.
 
 ## For AI-authored reports
 

package/SKILL.md

@@ -89,6 +89,9 @@ inputs: recompute at the source and correct whichever side is wrong.
 sources, updates `fetched_at`, recomputes derived values, and names every
 metric it could *not* refresh. `command` sources run only under
 `--allow-commands`; never pass that flag on an IR you did not author.
+Other source types (vendor APIs, analytics tools) can be refreshed through
+`--fetchers <module.mjs>` — one exported function per source type, with
+credentials from the environment, never from the IR.
 
 ## What stays yours
 

package/dist/cli.js

@@ -3,6 +3,7 @@ import { access, readFile, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { compile } from './compile.js';
 import { refresh } from './refresh.js';
+import { pathToFileURL } from 'node:url';
 const USAGE = `watertight — reports that hold water. Every number carries its receipt;
 an ungrounded claim is a leak, and a report with leaks does not build.
 
@@ -17,6 +18,9 @@ Options
   --out <file>       where to write the output (default: report.html / report.grounded.md)
   --check            verify only, write nothing
   --dry-run          refresh only: show what would change, write nothing
+  --fetchers <file>  refresh only: a JS module of custom source adapters, e.g.
+                     export function mixpanel(source) { ... return value }
+                     Loading a module runs its code — only pass files you wrote or trust.
   --allow-commands   refresh only: let "command" sources run shell (off by default —
                      an IR from someone else's repo must not execute code on your machine)
   --json          machine-readable result on stdout
@@ -33,6 +37,7 @@ function parseArgs(argv) {
     let json = false;
     let dryRun = false;
     let allowCommands = false;
+    let fetchersPath;
     let format = 'html';
     let help = false;
     let version = false;
@@ -46,6 +51,8 @@ function parseArgs(argv) {
             dryRun = true;
         else if (arg === '--allow-commands')
             allowCommands = true;
+        else if (arg === '--fetchers')
+            fetchersPath = args[++i];
         else if (arg === '--format')
             format = args[++i] === 'md' ? 'md' : 'html';
         else if (arg === '--json')
@@ -60,7 +67,7 @@ function parseArgs(argv) {
     const command = positional[0] === 'refresh' ? 'refresh' : 'compile';
     if (command === 'refresh')
         positional.shift();
-    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format };
+    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format, fetchersPath };
 }
 async function exists(path) {
     try {
@@ -90,7 +97,8 @@ async function main() {
         reportPath = join(dir, 'report.md');
         irPath = join(dir, 'metrics.json');
     }
-    for (const path of [reportPath, irPath]) {
+    // refresh works on the IR alone — an IR-only directory is a legitimate workspace
+    for (const path of opts.command === 'refresh' ? [irPath] : [reportPath, irPath]) {
         if (!(await exists(path))) {
             console.error(`Not found: ${path}`);
             console.error('Expected report.md and metrics.json — see --help.');
@@ -98,7 +106,21 @@ async function main() {
         }
     }
     if (opts.command === 'refresh') {
-        const r = await refresh(irPath, { allowCommands: opts.allowCommands, dryRun: opts.dryRun });
+        let fetchers;
+        if (opts.fetchersPath) {
+            const mod = await import(pathToFileURL(resolve(opts.fetchersPath)).href);
+            const exports = (typeof mod.default === 'object' && mod.default !== null ? mod.default : mod);
+            fetchers = Object.fromEntries(Object.entries(exports).filter(([, v]) => typeof v === 'function'));
+            if (Object.keys(fetchers).length === 0) {
+                console.error(`error: ${opts.fetchersPath} exports no functions — nothing to fetch with`);
+                process.exit(2);
+            }
+        }
+        const r = await refresh(irPath, { allowCommands: opts.allowCommands, dryRun: opts.dryRun, fetchers });
+        if (opts.json) {
+            console.log(JSON.stringify(r, null, 2));
+            process.exit(r.errors.length > 0 ? 1 : 0);
+        }
         for (const c of r.changes)
             console.log(`  ${c.key}: ${c.before.toLocaleString()} → ${c.after.toLocaleString()}`);
         for (const s of r.skipped)

package/dist/refresh.js

@@ -91,8 +91,11 @@ export async function refresh(irPath, options) {
                 }
                 value = fetchCommand(m.source, baseDir);
             }
+            else if (options.fetchers?.[m.source.type]) {
+                value = toNumber(await options.fetchers[m.source.type](m.source, { key, metric: m, baseDir }), `fetcher "${m.source.type}" for "${key}"`);
+            }
             else {
-                result.skipped.push({ key, reason: `no built-in adapter for source type "${m.source.type}"` });
+                result.skipped.push({ key, reason: `no adapter for source type "${m.source.type}"` });
                 continue;
             }
             if (value !== m.value)
@@ -104,14 +107,26 @@ export async function refresh(irPath, options) {
             result.errors.push({ key, message: err instanceof Error ? err.message : String(err) });
         }
     }
-    // parts may have moved, so stored sums are recomputed rather than left to go stale
+    // inputs may have moved, so derived values are recomputed rather than left to go stale
     for (const [key, m] of Object.entries(raw.metrics)) {
-        if (m.derived?.op !== 'sum' || Array.isArray(m.value))
+        if (!m.derived || Array.isArray(m.value))
             continue;
-        const computed = m.derived.of.reduce((acc, ref) => {
-            const part = raw.metrics[ref];
-            return acc + (part && typeof part.value === 'number' ? part.value : NaN);
-        }, 0);
+        let computed;
+        if (m.derived.op === 'sum') {
+            computed = m.derived.of.reduce((acc, ref) => {
+                const part = raw.metrics[ref];
+                return acc + (part && typeof part.value === 'number' ? part.value : NaN);
+            }, 0);
+        }
+        else {
+            const before = raw.metrics[m.derived.before]?.value;
+            const after = raw.metrics[m.derived.after]?.value;
+            if (typeof before !== 'number' || typeof after !== 'number' || before === 0)
+                continue;
+            // keep the author's stated precision — refresh must not turn 0.155 into 0.1551724
+            const decimals = (String(m.value).split('.')[1] ?? '').length;
+            computed = Number(((after - before) / before).toFixed(decimals));
+        }
         if (Number.isFinite(computed) && computed !== m.value) {
             result.changes.push({ key, before: m.value, after: computed });
             m.value = computed;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "watertight",
-  "version": "0.1.0",
-  "description": "Reports that hold water \u2014 every number carries its receipt, and ungrounded claims fail the build.",
+  "version": "0.2.0",
+  "description": "Reports that hold water — every number carries its receipt, and ungrounded claims fail the build.",
   "type": "module",
   "bin": {
-    "watertight": "./dist/cli.js"
+    "watertight": "dist/cli.js"
   },
   "files": [
     "dist",