mandrel-platform 0.17.2 → 0.19.0

package/scripts/check-coverage-threshold.mjs

@@ -54,10 +54,23 @@ import { join, resolve } from "node:path";
 
 export const VALID_METRICS = ["lines", "statements", "functions", "branches"];
 
+/**
+ * Assert that a value-taking flag at index `i` is actually followed by a
+ * value token. Throws otherwise so a trailing/valueless flag fails loudly
+ * instead of falling through to a silent default (e.g. a bare `--threshold`
+ * must not leave the gate disabled at threshold 0).
+ */
+export function requireValue(flag, argv, i) {
+  if (argv[i + 1] === undefined) {
+    throw new Error(`flag "${flag}" requires a value`);
+  }
+}
+
 /**
  * Parse the CLI argv (array AFTER `node script.mjs`) into an options object.
- * Throws on a malformed numeric threshold or an unknown metric so the gate
- * fails loudly rather than silently mis-reading its own configuration.
+ * Throws on a malformed numeric threshold, an unknown metric, an unknown
+ * flag, or a valueless value-taking flag so the gate fails loudly rather
+ * than silently mis-reading its own configuration.
  */
 export function parseArgs(argv) {
   const opts = {
@@ -66,11 +79,25 @@ export function parseArgs(argv) {
     coverageDirs: [],
     cwd: process.cwd(),
   };
+  // Value-taking flags. Each MUST be followed by a value token; a trailing
+  // (valueless) occurrence is a hard error rather than a silent skip — a
+  // valueless `--threshold` must never leave the gate at its disabled default.
+  const VALUE_FLAGS = new Set([
+    "--threshold",
+    "-t",
+    "--metric",
+    "-m",
+    "--coverage-dir",
+    "--cwd",
+  ]);
+
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if ((arg === "--threshold" || arg === "-t") && argv[i + 1] !== undefined) {
+    if (arg === "--threshold" || arg === "-t") {
+      requireValue(arg, argv, i);
       opts.threshold = parseThreshold(argv[++i]);
-    } else if ((arg === "--metric" || arg === "-m") && argv[i + 1] !== undefined) {
+    } else if (arg === "--metric" || arg === "-m") {
+      requireValue(arg, argv, i);
       const metric = String(argv[++i]).trim().toLowerCase();
       if (!VALID_METRICS.includes(metric)) {
         throw new Error(
@@ -78,10 +105,21 @@ export function parseArgs(argv) {
         );
       }
       opts.metric = metric;
-    } else if (arg === "--coverage-dir" && argv[i + 1] !== undefined) {
+    } else if (arg === "--coverage-dir") {
+      requireValue(arg, argv, i);
       opts.coverageDirs.push(String(argv[++i]));
-    } else if (arg === "--cwd" && argv[i + 1] !== undefined) {
+    } else if (arg === "--cwd") {
+      requireValue(arg, argv, i);
       opts.cwd = String(argv[++i]);
+    } else if (arg.startsWith("-")) {
+      // An unknown flag (e.g. a typo'd `--threshhold`) MUST fail loudly. Left
+      // unhandled it would be silently ignored, leaving `--threshold` at its
+      // 0 default and disabling the gate — the exact fail-open we forbid.
+      throw new Error(
+        `unknown flag "${arg}" (expected one of: ${[...VALUE_FLAGS].join(", ")})`
+      );
+    } else {
+      throw new Error(`unexpected positional argument "${arg}"`);
     }
   }
   return opts;

package/scripts/check-coverage-threshold.test.mjs

@@ -121,6 +121,49 @@ test("parseArgs rejects an unknown --metric", () => {
   assert.throws(() => parseArgs(["--metric", "nonsense"]), /unknown --metric/);
 });
 
+test("parseArgs rejects a valueless --threshold (must not silently disable the gate)", () => {
+  // A bare trailing `--threshold` previously fell through and left the
+  // threshold at its 0 default — silently turning the gate OFF. It MUST now
+  // throw instead.
+  assert.throws(() => parseArgs(["--threshold"]), /requires a value/);
+  assert.throws(() => parseArgs(["-t"]), /requires a value/);
+  // Same for the other value-taking flags.
+  assert.throws(() => parseArgs(["--metric"]), /requires a value/);
+  assert.throws(() => parseArgs(["--coverage-dir"]), /requires a value/);
+  assert.throws(() => parseArgs(["--cwd"]), /requires a value/);
+});
+
+test("parseArgs rejects a mistyped/unknown flag rather than ignoring it", () => {
+  // A typo like `--threshhold 80` used to be silently dropped, disabling the
+  // gate. It MUST now fail loudly.
+  assert.throws(() => parseArgs(["--threshhold", "80"]), /unknown flag/);
+  assert.throws(() => parseArgs(["--nope"]), /unknown flag/);
+});
+
+test("parseArgs rejects unexpected positional arguments", () => {
+  assert.throws(() => parseArgs(["80"]), /unexpected positional argument/);
+});
+
+test("runCli: a mistyped threshold flag exits non-zero instead of passing silently", () => {
+  const out = [];
+  const code = runCli(["--threshhold", "80"], {
+    log: (m) => out.push(m),
+    err: (m) => out.push(m),
+  });
+  assert.equal(code, 1);
+  assert.ok(out.some((l) => /unknown flag/.test(l)));
+});
+
+test("runCli: a valueless threshold flag exits non-zero instead of passing silently", () => {
+  const out = [];
+  const code = runCli(["--threshold"], {
+    log: (m) => out.push(m),
+    err: (m) => out.push(m),
+  });
+  assert.equal(code, 1);
+  assert.ok(out.some((l) => /requires a value/.test(l)));
+});
+
 test("VALID_METRICS covers the four Istanbul totals", () => {
   assert.deepEqual(VALID_METRICS, [
     "lines",

package/scripts/check-docs-staleness.mjs

@@ -23,43 +23,9 @@
  */
 
 import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative, extname } from 'node:path';
+import { join, relative, extname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
-// ---------------------------------------------------------------------------
-// CLI argument parsing
-// ---------------------------------------------------------------------------
-
-const { values: argv } = parseArgs({
-  options: {
-    dir: { type: 'string', default: 'docs' },
-    'warn-only': { type: 'boolean', default: false },
-    quiet: { type: 'boolean', default: false },
-    help: { type: 'boolean', default: false },
-  },
-  strict: false,
-});
-
-if (argv.help) {
-  console.log(`
-check-docs-staleness.mjs — docs staleness lint for mandrel-platform consumers
-
-Usage:
-  node scripts/check-docs-staleness.mjs [options]
-
-Options:
-  --dir <path>      Directory to scan (default: docs/)
-  --warn-only       Exit 0 even when issues are found
-  --quiet           Suppress per-file output; only print summary
-  --help            Print this help and exit
-`);
-  process.exit(0);
-}
-
-const SCAN_DIR = argv.dir ?? 'docs';
-const WARN_ONLY = argv['warn-only'] ?? false;
-const QUIET = argv.quiet ?? false;
-
 // ---------------------------------------------------------------------------
 // Staleness patterns
 //
@@ -74,7 +40,7 @@ const QUIET = argv.quiet ?? false;
 // flagged text to suppress a specific rule for that occurrence.
 // ---------------------------------------------------------------------------
 
-const RULES = [
+export const RULES = [
   {
     id: 'pages-deploy-command',
     description: 'References `wrangler pages deploy` — may be stale if the project has migrated web to a Worker',
@@ -130,12 +96,50 @@ const RULES = [
   {
     id: 'expired-placeholder',
     description: 'Placeholder date that has passed (YYYY-MM-DD pattern in an expiry/todo context)',
-    // Matches explicit expiry dates like "expires: 2025-01-01" that are in the past
-    pattern: /expires[:\s]+202[0-4]-\d{2}-\d{2}/gi,
+    // Matches explicit expiry dates like "expires: 2025-01-01" for ANY 20xx
+    // year. The hardcoded 2020–2024 window meant an expiry that lapsed in
+    // 2025/2026 (or any later year) sailed through the gate. We now match any
+    // 4-digit 20xx year and defer the "is it actually in the past?" decision
+    // to `matchFilter`, so the rule stays correct as the calendar advances and
+    // never flags a still-valid FUTURE expiry.
+    pattern: /expires[:\s]+(20\d{2}-\d{2}-\d{2})/gi,
     severity: 'error',
+    // Only flag when the captured date is strictly before today (UTC). Future
+    // expiries are still valid and must not be reported.
+    matchFilter: (match, { now = new Date() } = {}) => isExpiredDate(match, now),
   },
 ];
 
+// ---------------------------------------------------------------------------
+// Date helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a full regex match like "expires: 2025-03-01", extract the YYYY-MM-DD
+ * date and return true when it is strictly before `now` (i.e. it has expired).
+ * Malformed / unparseable dates return false (nothing to flag).
+ *
+ * @param {string} matchText  The full matched substring (e.g. "expires: 2025-03-01").
+ * @param {Date}   now        Reference "today" (defaults to the current date).
+ * @returns {boolean}
+ */
+export function isExpiredDate(matchText, now = new Date()) {
+  const m = /(\d{4})-(\d{2})-(\d{2})/.exec(String(matchText));
+  if (!m) return false;
+  const [, y, mo, d] = m;
+  // Parse as a UTC calendar date to avoid local-timezone drift.
+  const dateMs = Date.UTC(Number(y), Number(mo) - 1, Number(d));
+  if (Number.isNaN(dateMs)) return false;
+  // Compare against today's UTC calendar date (midnight), so an expiry dated
+  // strictly earlier than today counts as expired regardless of clock time.
+  const todayMs = Date.UTC(
+    now.getUTCFullYear(),
+    now.getUTCMonth(),
+    now.getUTCDate(),
+  );
+  return dateMs < todayMs;
+}
+
 // ---------------------------------------------------------------------------
 // File walker
 // ---------------------------------------------------------------------------
@@ -145,7 +149,7 @@ const RULES = [
  * @param {string} dir
  * @returns {string[]}
  */
-function walkDir(dir) {
+export function walkDir(dir) {
   const results = [];
   let entries;
   try {
@@ -179,7 +183,7 @@ function walkDir(dir) {
  * @param {string} filePath
  * @returns {Finding[]}
  */
-function lintFile(filePath) {
+export function lintFile(filePath) {
   const findings = [];
   let content;
   try {
@@ -205,6 +209,12 @@ function lintFile(filePath) {
       rule.pattern.lastIndex = 0;
       let match;
       while ((match = rule.pattern.exec(line)) !== null) {
+        // A rule may declare a `matchFilter` predicate to decide, per match,
+        // whether the hit is actually a finding (e.g. the expired-placeholder
+        // rule only fires when the captured date is in the past).
+        if (typeof rule.matchFilter === 'function' && !rule.matchFilter(match[0])) {
+          continue;
+        }
         findings.push({
           file: filePath,
           line: i + 1,
@@ -219,59 +229,98 @@ function lintFile(filePath) {
 }
 
 // ---------------------------------------------------------------------------
-// Main
+// CLI entrypoint (guarded so `node --test` imports don't run the scan)
 // ---------------------------------------------------------------------------
 
-const files = walkDir(SCAN_DIR);
+function main() {
+  const { values: argv } = parseArgs({
+    options: {
+      dir: { type: 'string', default: 'docs' },
+      'warn-only': { type: 'boolean', default: false },
+      quiet: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+
+  if (argv.help) {
+    console.log(`
+check-docs-staleness.mjs — docs staleness lint for mandrel-platform consumers
 
-if (files.length === 0) {
-  console.log(`[docs-staleness] No files found under '${SCAN_DIR}' — nothing to check.`);
-  process.exit(0);
-}
+Usage:
+  node scripts/check-docs-staleness.mjs [options]
 
-/** @type {Finding[]} */
-const allFindings = [];
+Options:
+  --dir <path>      Directory to scan (default: docs/)
+  --warn-only       Exit 0 even when issues are found
+  --quiet           Suppress per-file output; only print summary
+  --help            Print this help and exit
+`);
+    return 0;
+  }
 
-for (const file of files) {
-  const findings = lintFile(file);
-  allFindings.push(...findings);
-}
+  const SCAN_DIR = argv.dir ?? 'docs';
+  const WARN_ONLY = argv['warn-only'] ?? false;
+  const QUIET = argv.quiet ?? false;
 
-// Group findings by file for readable output
-const byFile = new Map();
-for (const finding of allFindings) {
-  const key = finding.file;
-  if (!byFile.has(key)) byFile.set(key, []);
-  byFile.get(key).push(finding);
-}
+  const files = walkDir(SCAN_DIR);
 
-const errors = allFindings.filter((f) => f.rule.severity === 'error');
-const warnings = allFindings.filter((f) => f.rule.severity === 'warning');
+  if (files.length === 0) {
+    console.log(`[docs-staleness] No files found under '${SCAN_DIR}' — nothing to check.`);
+    return 0;
+  }
 
-if (!QUIET) {
-  for (const [file, findings] of byFile.entries()) {
-    const relPath = relative(process.cwd(), file);
-    for (const f of findings) {
-      const sev = f.rule.severity === 'error' ? 'ERR ' : 'WARN';
-      console.log(`[${sev}] ${relPath}:${f.line} — ${f.rule.id}: ${f.rule.description}`);
-      console.log(`       matched: ${JSON.stringify(f.match)}`);
+  /** @type {Finding[]} */
+  const allFindings = [];
+
+  for (const file of files) {
+    const findings = lintFile(file);
+    allFindings.push(...findings);
+  }
+
+  // Group findings by file for readable output
+  const byFile = new Map();
+  for (const finding of allFindings) {
+    const key = finding.file;
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(finding);
+  }
+
+  const errors = allFindings.filter((f) => f.rule.severity === 'error');
+  const warnings = allFindings.filter((f) => f.rule.severity === 'warning');
+
+  if (!QUIET) {
+    for (const [file, findings] of byFile.entries()) {
+      const relPath = relative(process.cwd(), file);
+      for (const f of findings) {
+        const sev = f.rule.severity === 'error' ? 'ERR ' : 'WARN';
+        console.log(`[${sev}] ${relPath}:${f.line} — ${f.rule.id}: ${f.rule.description}`);
+        console.log(`       matched: ${JSON.stringify(f.match)}`);
+      }
     }
   }
-}
 
-console.log(
-  `\n[docs-staleness] Scanned ${files.length} file(s). ` +
-  `Found ${errors.length} error(s), ${warnings.length} warning(s).`,
-);
+  console.log(
+    `\n[docs-staleness] Scanned ${files.length} file(s). ` +
+    `Found ${errors.length} error(s), ${warnings.length} warning(s).`,
+  );
 
-if (allFindings.length > 0) {
-  console.log(`\nTo suppress a specific rule occurrence, add this comment on the line above:`);
-  console.log(`  <!-- staleness-ignore: <rule-id> -->`);
-  console.log(`\nAvailable rule IDs: ${RULES.map((r) => r.id).join(', ')}`);
-}
+  if (allFindings.length > 0) {
+    console.log(`\nTo suppress a specific rule occurrence, add this comment on the line above:`);
+    console.log(`  <!-- staleness-ignore: <rule-id> -->`);
+    console.log(`\nAvailable rule IDs: ${RULES.map((r) => r.id).join(', ')}`);
+  }
 
-if (errors.length > 0 && !WARN_ONLY) {
-  process.exit(1);
+  if (errors.length > 0 && !WARN_ONLY) {
+    return 1;
+  }
+
+  return 0;
 }
 
-process.exit(0);
+// Only run when executed directly, not when imported by the test suite.
+const invokedDirectly =
+  process.argv[1] && resolve(process.argv[1]).endsWith('check-docs-staleness.mjs');
+if (invokedDirectly) {
+  process.exit(main());
+}

package/scripts/check-docs-staleness.test.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * check-docs-staleness.test.mjs — node:test suite for the docs-staleness lint
+ * (Story #197).
+ *
+ * Focus: the `expired-placeholder` rule. The rule previously hardcoded the
+ * years 2020–2024 (`/expires[:\s]+202[0-4]-\d{2}-\d{2}/i`), so an expiry that
+ * lapsed in 2025, 2026, or any later year sailed through the gate — a
+ * fail-open. The fix broadens the pattern to any 20xx year and defers the
+ * "is it actually in the past?" decision to `isExpiredDate`, so the rule stays
+ * correct as the calendar advances and never flags a still-valid future date.
+ *
+ * These tests exercise the year fix directly (`isExpiredDate`) and end-to-end
+ * (`lintFile` against a real fixture file), pinning "today" via a fixed clock
+ * so they are deterministic.
+ *
+ * Run: node --test scripts/check-docs-staleness.test.mjs
+ */
+
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+
+import { RULES, lintFile, isExpiredDate } from './check-docs-staleness.mjs';
+
+// ---------------------------------------------------------------------------
+// isExpiredDate — the year fix, tested directly with a pinned clock.
+// ---------------------------------------------------------------------------
+
+// A fixed reference "today" so the tests never depend on the wall clock.
+const NOW = new Date('2026-07-02T12:00:00Z');
+
+test('isExpiredDate flags an expiry in the previously-hardcoded window (2020–2024)', () => {
+  assert.equal(isExpiredDate('expires: 2020-01-01', NOW), true);
+  assert.equal(isExpiredDate('expires: 2024-12-31', NOW), true);
+});
+
+test('isExpiredDate flags an expiry in a recent year OUTSIDE the old window (2025, 2026)', () => {
+  // These are the exact dates the old 202[0-4] regex missed.
+  assert.equal(isExpiredDate('expires: 2025-01-01', NOW), true);
+  assert.equal(isExpiredDate('expires: 2025-12-31', NOW), true);
+  assert.equal(isExpiredDate('expires: 2026-01-01', NOW), true);
+  assert.equal(isExpiredDate('expires: 2026-07-01', NOW), true); // yesterday
+});
+
+test('isExpiredDate does NOT flag today or a future expiry', () => {
+  assert.equal(isExpiredDate('expires: 2026-07-02', NOW), false); // today
+  assert.equal(isExpiredDate('expires: 2026-07-03', NOW), false); // tomorrow
+  assert.equal(isExpiredDate('expires: 2027-01-01', NOW), false);
+  assert.equal(isExpiredDate('expires: 2099-01-01', NOW), false);
+});
+
+test('isExpiredDate returns false for malformed / dateless input', () => {
+  assert.equal(isExpiredDate('expires: soon', NOW), false);
+  assert.equal(isExpiredDate('', NOW), false);
+});
+
+// ---------------------------------------------------------------------------
+// RULES wiring — the expired-placeholder pattern now matches any 20xx year.
+// ---------------------------------------------------------------------------
+
+test('expired-placeholder pattern matches any 20xx year (not just 2020–2024)', () => {
+  const rule = RULES.find((r) => r.id === 'expired-placeholder');
+  assert.ok(rule, 'expired-placeholder rule must exist');
+  for (const line of [
+    'expires: 2024-01-01',
+    'expires: 2025-06-15',
+    'expires: 2026-01-01',
+    'expires: 2031-01-01',
+  ]) {
+    rule.pattern.lastIndex = 0;
+    assert.ok(
+      rule.pattern.test(line),
+      `pattern should match "${line}"`,
+    );
+  }
+  // A carve-out the fix must preserve: the rule is scoped to 20xx expiry dates.
+  rule.pattern.lastIndex = 0;
+  assert.equal(rule.pattern.test('expires: 1999-01-01'), false);
+});
+
+// ---------------------------------------------------------------------------
+// lintFile — end-to-end against a real fixture file.
+//
+// lintFile's matchFilter uses the real `new Date()` clock, so the fixtures use
+// a clearly-past year (2025) and a clearly-future year to stay deterministic
+// for any run date at or after mid-2026 (this suite ships in 2026+).
+// ---------------------------------------------------------------------------
+
+function withTempDoc(contents, fn) {
+  const root = mkdtempSync(join(tmpdir(), 'docs-staleness-'));
+  try {
+    mkdirSync(join(root, 'docs'), { recursive: true });
+    const file = join(root, 'docs', 'note.md');
+    writeFileSync(file, contents);
+    return fn(file);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test('lintFile flags an expired 2025 placeholder (missed by the old 2020–2024 rule)', () => {
+  withTempDoc('Token rotation.\nexpires: 2025-01-01\nEnd.\n', (file) => {
+    const findings = lintFile(file);
+    const expired = findings.filter((f) => f.rule.id === 'expired-placeholder');
+    assert.equal(expired.length, 1);
+    assert.match(expired[0].match, /2025-01-01/);
+  });
+});
+
+test('lintFile does NOT flag a far-future placeholder', () => {
+  withTempDoc('Long-lived.\nexpires: 2099-12-31\nDone.\n', (file) => {
+    const findings = lintFile(file);
+    const expired = findings.filter((f) => f.rule.id === 'expired-placeholder');
+    assert.equal(expired.length, 0);
+  });
+});
+
+test('lintFile honours the staleness-ignore suppression comment for the year rule', () => {
+  withTempDoc(
+    '<!-- staleness-ignore: expired-placeholder -->\nexpires: 2025-01-01\n',
+    (file) => {
+      const findings = lintFile(file);
+      const expired = findings.filter((f) => f.rule.id === 'expired-placeholder');
+      assert.equal(expired.length, 0);
+    },
+  );
+});