watertight 0.5.0 → 0.6.0

package/README.md

@@ -164,12 +164,13 @@ figure shows its receipt.
 
 | check | catches |
 |---|---|
-| `naked-number` | any digit in prose not covered by a reference (dates, headings, code spans and `{{raw:}}` are exempt) |
+| `naked-number` | any digit in prose not covered by a reference — heading text included; dates, URLs, code spans and `{{raw:}}` are exempt |
 | `unknown-ref` | `{{m:...}}` / `{{id:...}}` pointing at nothing |
 | `missing-field` | a measured metric without `source`, `window`, or `fetched_at` |
 | `definition-required` | a `ratio` / `ratio-point` metric with no stated basis — this is how a fill rate of 107% stays honest |
 | `derived-mismatch` | a `sum` that doesn't add up; a `pct_change` that doesn't recompute — to the stored value's own precision, so `0.161` passes as 16.1% but `0.15` for 15.5% fails |
 | `claim-without-evidence` | a `{{claim:}}` with no `evidence:` keys, or keys that don't exist |
+| `malformed-marker` | anything still marker-shaped after every recognised form — a typo'd `{{claim:…\|evidnce:…}}` must fail, not render verbatim |
 | `bad-derived` | derived ops referencing missing or non-numeric inputs |
 | `empty-ir` | a report "grounded" in nothing |
 | `stale-metric` | with `--max-age <days>`: a receipt whose `fetched_at` is older than the budget — numbers age |

package/dist/cli.js

@@ -74,7 +74,12 @@ function parseArgs(argv) {
             help = true;
         else if (arg === '-v' || arg === '--version')
             version = true;
-        else if (!arg.startsWith('-'))
+        else if (arg.startsWith('-')) {
+            // a strictness tool must not silently ignore a typo'd flag — --chekc writing a file is a betrayal
+            console.error(`error: unknown flag "${arg}" — see --help`);
+            process.exit(2);
+        }
+        else
             positional.push(arg);
     }
     const command = positional[0] === 'refresh' ? 'refresh' : positional[0] === 'init' ? 'init' : 'compile';

package/dist/compile.js

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { parseIr } from './ir.js';
 import { render } from './render.js';
 import { renderMarkdown } from './renderMd.js';
-import { scanNakedNumbers, scanRefs } from './scan.js';
+import { scanMarkers, scanNakedNumbers, scanRefs } from './scan.js';
 export async function compile(reportPath, irPath, options = 'html') {
     const opts = typeof options === 'string' ? { format: options } : options;
     const format = opts.format ?? 'html';
@@ -33,6 +33,7 @@ export async function compile(reportPath, irPath, options = 'html') {
         claims: [...report.matchAll(/\{\{claim:/g)].length,
     };
     leaks.push(...scanNakedNumbers(report));
+    leaks.push(...scanMarkers(report));
     if (ir)
         leaks.push(...scanRefs(report, new Set(Object.keys(ir.metrics)), new Set(Object.keys(ir.identifiers))));
     if (leaks.length > 0 || !ir)

package/dist/init.js

@@ -1,4 +1,4 @@
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 /**
@@ -58,6 +58,7 @@ export async function init(dir) {
         if (existsSync(path))
             throw new Error(`refusing to overwrite ${path}`);
     }
+    await mkdir(dir, { recursive: true });
     for (const [path, content] of files)
         await writeFile(path, content);
     return { written: files.map(([p]) => p) };

package/dist/ir.js

@@ -2,9 +2,18 @@
 const DEFINITION_REQUIRED = new Set(['ratio', 'ratio-point']);
 function decimals(n) {
     const s = String(n);
+    const e = s.indexOf('e');
+    if (e !== -1) {
+        // 1e-7 has 7 decimals, 1.5e-7 has 8 — exponential notation must not disarm the precision check
+        const exp = Number(s.slice(e + 1));
+        const mantissa = s.slice(0, e);
+        const dot = mantissa.indexOf('.');
+        return Math.max(0, (dot === -1 ? 0 : mantissa.length - dot - 1) - exp);
+    }
     const dot = s.indexOf('.');
     return dot === -1 ? 0 : s.length - dot - 1;
 }
+const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
 /**
  * A stored derived value must be correctly rounded to its own precision: writing 0.15
  * for a computed 0.155 is a mismatch, writing 0.155 for 0.15517 is fine. This is what
@@ -31,8 +40,10 @@ export function parseIr(raw) {
         return { leaks };
     }
     for (const [key, m] of Object.entries(metrics)) {
-        if (m.value === undefined) {
-            leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" has no value` });
+        const valueOk = isFiniteNumber(m.value) ||
+            (Array.isArray(m.value) && m.value.length === 2 && m.value.every(isFiniteNumber));
+        if (!valueOk) {
+            leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" has no usable numeric value` });
             continue;
         }
         if (typeof m.unit !== 'string' || m.unit.length === 0) {
@@ -63,7 +74,7 @@ export function parseIr(raw) {
                     }
                     computed += part.value;
                 }
-                if (!broken && computed !== m.value) {
+                if (!broken && !roundsTo(m.value, computed)) {
                     leaks.push({
                         severity: 'error',
                         rule: 'derived-mismatch',
@@ -98,6 +109,15 @@ export function parseIr(raw) {
                     });
                 }
             }
+            else {
+                // an op the verifier cannot recompute must never pass as verified
+                leaks.push({
+                    severity: 'error',
+                    rule: 'bad-derived',
+                    message: `metric "${key}" has unknown derived op "${m.derived.op}"`,
+                    detail: 'Supported ops: sum, pct_change. A derivation the compiler cannot recompute cannot hold water.',
+                });
+            }
         }
         else {
             // a measured value must say where it came from and when

package/dist/refresh.js

@@ -74,7 +74,8 @@ export async function refresh(irPath, options) {
     const raw = JSON.parse(await readFile(irPath, 'utf8'));
     const baseDir = dirname(resolve(irPath));
     const result = { changes: [], skipped: [], errors: [], wrote: false };
-    const now = new Date().toISOString();
+    // date-only, matching the style people write by hand — receipts should look uniform
+    const now = new Date().toISOString().slice(0, 10);
     for (const [key, m] of Object.entries(raw.metrics)) {
         if (m.derived || !m.source || Array.isArray(m.value))
             continue;
@@ -107,37 +108,65 @@ export async function refresh(irPath, options) {
             result.errors.push({ key, message: err instanceof Error ? err.message : String(err) });
         }
     }
-    // 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 || Array.isArray(m.value))
-            continue;
-        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 endpoint = (v) => {
-                if (typeof v === 'number')
-                    return v;
-                const ref = raw.metrics[v];
-                return ref && typeof ref.value === 'number' ? ref.value : undefined;
+    // inputs may have moved, so derived values are recomputed rather than left to go stale.
+    // Iterated to a fixpoint so a derived that reads another derived settles too; a derivation
+    // that cannot be recomputed is a named error — silence is impossible here as everywhere.
+    const derivedErrors = new Set();
+    const firstBefore = new Map();
+    for (let pass = 0, moved = true; moved && pass < 10; pass++) {
+        moved = false;
+        for (const [key, m] of Object.entries(raw.metrics)) {
+            if (!m.derived || Array.isArray(m.value))
+                continue;
+            const fail = (message) => {
+                if (!derivedErrors.has(key)) {
+                    derivedErrors.add(key);
+                    result.errors.push({ key, message });
+                }
             };
-            const before = endpoint(m.derived.before);
-            const after = endpoint(m.derived.after);
-            if (before === undefined || after === undefined || before === 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);
+                if (!Number.isFinite(computed)) {
+                    fail('sum references unknown or non-scalar metrics — not recomputed');
+                    continue;
+                }
+            }
+            else if (m.derived.op === 'pct_change') {
+                const endpoint = (v) => {
+                    if (typeof v === 'number')
+                        return v;
+                    const ref = raw.metrics[v];
+                    return ref && typeof ref.value === 'number' ? ref.value : undefined;
+                };
+                const before = endpoint(m.derived.before);
+                const after = endpoint(m.derived.after);
+                if (before === undefined || after === undefined || before === 0) {
+                    fail('pct_change endpoints are unresolvable or zero — not recomputed');
+                    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));
+            }
+            else {
+                fail(`unknown derived op "${m.derived.op}" — not recomputed`);
                 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;
+            }
+            if (computed !== m.value) {
+                if (!firstBefore.has(key))
+                    firstBefore.set(key, m.value);
+                m.value = computed;
+                moved = true;
+            }
         }
     }
+    for (const [key, before] of firstBefore) {
+        result.changes.push({ key, before, after: raw.metrics[key].value });
+    }
     if (!options.dryRun && (result.changes.length > 0 || result.errors.length === 0)) {
         await writeFile(irPath, `${JSON.stringify(raw, null, 2)}\n`);
         result.wrote = true;

package/dist/render.js

@@ -1,13 +1,30 @@
+/**
+ * Code shows syntax, it does not state facts — a fenced example of {{m:…}} must render
+ * verbatim, not substitute. Stash code regions before substitution, restore after.
+ */
+export function protectCode(text) {
+    const stash = [];
+    const protectedText = text.replace(/```[\s\S]*?```|`[^`\n]*`/g, (m) => {
+        stash.push(m);
+        return `\u0000${stash.length - 1}\u0000`;
+    });
+    return { text: protectedText, restore: (s) => s.replace(/\u0000(\d+)\u0000/g, (_, i) => stash[Number(i)]) };
+}
 function escapeHtml(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
 export function formatValue(m) {
     if (Array.isArray(m.value)) {
         const [lo, hi] = m.value;
-        return `${lo.toLocaleString()}~${hi.toLocaleString()}${m.unit === 'ratio' ? '%' : ` ${m.unit}`}`;
+        // a range keeps the same unit conversion as a scalar — [0.3, 0.5] ratio is 30~50%, not 0.3~0.5%
+        if (m.unit === 'ratio' || m.unit === 'ratio-point') {
+            const pct = (v) => (v * 100).toFixed(1);
+            return `${pct(lo)}~${pct(hi)}${m.unit === 'ratio' ? '%' : '%p'}`;
+        }
+        return `${lo.toLocaleString()}~${hi.toLocaleString()} ${m.unit}`.trim();
     }
     if (m.unit === 'ratio')
-        return `${(m.value * 100).toFixed(m.value < 0.01 ? 2 : 1)}%`;
+        return `${(m.value * 100).toFixed(Math.abs(m.value) < 0.01 ? 2 : 1)}%`;
     if (m.unit === 'ratio-point')
         return `${m.value >= 0 ? '+' : ''}${(m.value * 100).toFixed(1)}%p`;
     return `${m.value.toLocaleString()} ${m.unit}`.trim();
@@ -37,7 +54,8 @@ function markdown(src) {
         .replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>');
 }
 export function render(report, ir) {
-    const grounded = escapeHtml(report)
+    const { text: protectedReport, restore } = protectCode(escapeHtml(report));
+    const grounded = restore(protectedReport
         .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
         const m = ir.metrics[key];
         return `<b class="w" title="${escapeHtml(receipt(m))}">${formatValue(m)}<sup>†</sup></b>`;
@@ -50,7 +68,7 @@ export function render(report, ir) {
             .join(' | ');
         return `<span class="c" title="${escapeHtml(receipts)}">${text.trim()}<sup>‡</sup></span>`;
     })
-        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => escapeHtml(text));
+        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => escapeHtml(text)));
     return `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
 <style>
   body{font:15px/1.75 -apple-system,system-ui,sans-serif;max-width:720px;margin:40px auto;padding:0 16px;color:#1a1a1a}

package/dist/renderMd.js

@@ -1,4 +1,4 @@
-import { formatValue, receipt } from './render.js';
+import { formatValue, protectCode, receipt } from './render.js';
 const SUPERSCRIPT = '⁰¹²³⁴⁵⁶⁷⁸⁹';
 const sup = (n) => `⁽${String(n).split('').map((d) => SUPERSCRIPT[Number(d)]).join('')}⁾`;
 /**
@@ -9,7 +9,8 @@ const sup = (n) => `⁽${String(n).split('').map((d) => SUPERSCRIPT[Number(d)]).
  */
 export function renderMarkdown(report, ir) {
     const used = [];
-    const body = report
+    const { text: protectedReport, restore } = protectCode(report);
+    const body = restore(protectedReport
         .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
         if (!used.includes(key))
             used.push(key);
@@ -17,7 +18,14 @@ export function renderMarkdown(report, ir) {
     })
         .replace(/\{\{id:([\w-]+)\}\}/g, (_, key) => `\`${ir.identifiers[key]}\``)
         .replace(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g, (_, text, evidence) => `**${text.trim()}** *(evidence: ${evidence.trim()})*`)
-        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => text);
+        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => text));
+    // evidence-only metrics get receipts too — a claim's reader must be able to check its keys
+    for (const [, , evidence] of protectedReport.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+        for (const key of evidence.split(',').map((k) => k.trim()).filter(Boolean)) {
+            if (ir.metrics[key] && !used.includes(key))
+                used.push(key);
+        }
+    }
     const appendix = used
         .map((key, i) => {
         const m = ir.metrics[key];

package/dist/scan.js

@@ -1,6 +1,8 @@
 /** Same-length whitespace, newlines kept — stripping must not move anything */
 const blank = (s) => s.replace(/[^\n]/g, ' ');
 const lineAt = (text, index) => text.slice(0, index).split('\n').length;
+/** Code shows syntax, it does not state facts — refs and numbers inside it are exempt */
+const blankCode = (report) => report.replace(/```[\s\S]*?```/g, blank).replace(/`[^`\n]*`/g, blank);
 /**
  * Find numbers in the narrative that are not bound to the IR. These are the leaks the
  * tool exists to catch: a typed, transcribed, or hallucinated figure reads exactly like
@@ -18,12 +20,14 @@ export function scanNakedNumbers(report) {
         .replace(/\{\{raw:[^}]*\}\}/g, blank) // explicit, greppable escape hatch
         .replace(/```[\s\S]*?```/g, blank) // fenced code
         .replace(/`[^`\n]*`/g, blank) // inline code
+        .replace(/\]\([^)\s]*\)/g, blank) // markdown link targets — URLs locate, they do not measure
+        .replace(/https?:\/\/\S+/g, blank) // bare URLs, same reason
         .replace(/\d{4}-\d{2}-\d{2}/g, blank) // ISO dates locate, they do not measure
-        .replace(/^#+ .*$/gm, blank) // headings
+        .replace(/^#{1,6}(?= )/gm, blank) // heading markers only — heading TEXT is scanned, people summarise numbers there
         .replace(/^\s*\d+\.\s/gm, blank); // ordered-list markers
     const leaks = [];
     for (const m of stripped.matchAll(/\d[\d,.]*\s*(%p?|[가-힣]{1,2})?/g)) {
-        const token = m[0].trim();
+        const token = m[0].trim().replace(/[.,]+$/, '');
         if (!token)
             continue;
         leaks.push({
@@ -37,8 +41,9 @@ export function scanNakedNumbers(report) {
     return leaks;
 }
 /** Every reference in the narrative must resolve; a dangling one is authoring drift. */
-export function scanRefs(report, metricKeys, idKeys) {
+export function scanRefs(rawReport, metricKeys, idKeys) {
     const leaks = [];
+    const report = blankCode(rawReport);
     for (const m of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
         const [, text, evidence] = m;
         const line = lineAt(report, m.index);
@@ -80,3 +85,25 @@ export function scanRefs(report, metricKeys, idKeys) {
     }
     return leaks;
 }
+/**
+ * Anything still shaped like a marker after every recognised form is removed was a typo —
+ * and a typo'd marker must be a leak, or it renders verbatim and its number sails through.
+ */
+export function scanMarkers(rawReport) {
+    const known = blankCode(rawReport)
+        .replace(/\{\{(m|id):[\w-]+\}\}/g, blank)
+        .replace(/\{\{raw:[^}]*\}\}/g, blank)
+        .replace(/\{\{claim:[^|}]*\|\s*evidence:[^}]*\}\}/g, blank)
+        .replace(/\{\{claim:[^|}]*\}\}/g, blank); // no-pipe form is already claim-without-evidence
+    const leaks = [];
+    for (const m of known.matchAll(/\{\{[^}]*\}\}?/g)) {
+        leaks.push({
+            severity: 'error',
+            rule: 'malformed-marker',
+            line: lineAt(known, m.index),
+            message: `"${m[0]}" is not a recognised marker`,
+            detail: 'Valid forms: {{m:key}}, {{id:key}}, {{raw:…}}, {{claim: text | evidence: keys}}.',
+        });
+    }
+    return leaks;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watertight",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Reports that hold water — every number carries its receipt, and ungrounded claims fail the build.",
   "type": "module",
   "bin": {