@aria-framework/testkit 0.1.0

package/harness.js

@@ -0,0 +1,79 @@
+/**
+ * createHarness — the ✓/✗ micro test-harness that existed as ~111 hand-rolled copies across the
+ * two apps and this monorepo's own package tests, drifted into three incompatible variants.
+ *
+ * The variant differences were not cosmetic. The one that matters: some copies' `check()` accepted
+ * an async callback and returned before its assertions ran — a WHOLE SUITE silently passing. This
+ * harness makes that structural: `check()` REFUSES a callback that returns a thenable (use
+ * `acheck`), so the failure mode is a loud error at the call site instead of a green lie.
+ *
+ * Deliberately tiny and dependency-free — same discipline as the copies it replaces, minus the
+ * copy-paste. `done()` prints the summary and sets the exit code; keeping process.exit behind it
+ * (instead of sprinkled at file bottoms) lets a suite run inside a larger runner.
+ */
+
+'use strict';
+
+/**
+ * @param {{log?: (line: string) => void, truncate?: number}} [opts]
+ *   truncate: cap failure detail lines (0 = no cap). Some old copies cut to one line and hid the
+ *   assertion diff; the default keeps everything.
+ */
+function createHarness(opts = {}) {
+  const log = opts.log || ((line) => console.log(line));
+  const cap = opts.truncate || 0;
+  let pass = 0;
+  let fail = 0;
+
+  const detail = (e) => {
+    let msg = e && (e.message || String(e));
+    if (cap > 0) msg = String(msg).split('\n').slice(0, cap).join('\n');
+    return msg;
+  };
+
+  const ok = (name) => { pass++; log('  ✓ ' + name); };
+  const bad = (name, e) => { fail++; log('  ✗ ' + name + (e ? '\n      ' + detail(e) : '')); };
+
+  /** Sync check. An async callback is a BUG here — its assertions would be ignored. */
+  const check = (name, fn) => {
+    try {
+      const r = fn();
+      if (r && typeof r.then === 'function') {
+        // DEFUSE the orphaned promise before failing the check: its body may already have
+        // rejected (an assertion inside an async callback), and an unhandled rejection would
+        // crash the whole suite instead of failing this one check.
+        r.catch(() => {});
+        throw new Error('async callback passed to check() — its assertions would be ignored; use acheck()');
+      }
+      ok(name);
+    } catch (e) { bad(name, e); }
+  };
+
+  /** Async-aware check. Await it (or run inside an async IIFE the way the suites already do). */
+  const acheck = async (name, fn) => {
+    try { await fn(); ok(name); } catch (e) { bad(name, e); }
+  };
+
+  /**
+   * Print the summary; set the process exit code. Returns the failure count so a caller composing
+   * suites can decide for itself.
+   * @param {{exit?: boolean}} [o] exit:true (default) calls process.exit — the standalone-script
+   *   behaviour every existing suite has; pass false inside a larger runner.
+   */
+  const done = (o = {}) => {
+    log(`\n${pass} passed, ${fail} failed`);
+    if (o.exit === false) {
+      process.exitCode = fail ? 1 : process.exitCode;
+      return fail;
+    }
+    process.exit(fail ? 1 : 0);
+  };
+
+  return {
+    ok, bad, check, acheck, done,
+    get passed() { return pass; },
+    get failed() { return fail; }
+  };
+}
+
+module.exports = { createHarness };

package/importsInScope.js

@@ -0,0 +1,98 @@
+/**
+ * assertImportsInScope — every consumer of a module has every function it CALLS in scope.
+ *
+ * The failure this guards is silent by construction: a name missing from a destructure is a
+ * ReferenceError at runtime — and when the call sits inside a catch that returns [], it becomes an
+ * empty list that reads exactly like having no data. It shipped that way once (a silently-empty
+ * backup list), which is why this exists. The two apps carried this file byte-identically apart
+ * from the header prose; the module path and matcher are now parameters.
+ *
+ * HONEST LIMITS (read before pointing it at something new): the scope scan is a REGEX HEURISTIC
+ * over CommonJS — destructures, const/let/var declarations, function declarations. It does not
+ * parse; ESM `import` is not understood and produces false negatives, and an exotic declaration
+ * style (deep nesting inside eval'd strings, computed keys) is invisible to it. It is deliberately
+ * over-permissive: it can miss a problem, it should not invent one.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** Names a file has in scope: destructured anywhere, declared, or function-declared. */
+function inScope(src) {
+  const names = new Set();
+  for (const m of src.matchAll(/(?:const|let|var)\s*\{([^}]*)\}\s*=/g)) {
+    for (const part of m[1].split(',')) {
+      const n = part.split(':').pop().trim();
+      if (n) names.add(n);
+    }
+  }
+  for (const m of src.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g)) names.add(m[1]);
+  for (const m of src.matchAll(/function\s+([A-Za-z_$][\w$]*)/g)) names.add(m[1]);
+  return names;
+}
+
+/**
+ * @param {{
+ *   root: string,               app root (absolute)
+ *   modulePath: string,         path (relative to root) of the module whose exports are the vocabulary
+ *   requireMatcher: RegExp,     a file is a CONSUMER when its source matches (e.g. /require\([^)]*backup\/core[^)]*\)/)
+ *   dirs?: string[],            flat-scanned for consumers; default ['routes','lib','scripts']
+ *   minConsumers?: number,      self-check floor (default 2) — zero consumers means the finder drifted
+ *   minCallable?: number        self-check floor (default 3) — a tiny export list means the wrong module
+ * }} opts
+ * @returns {{consumers: number, callable: number}} on success
+ * @throws Error naming every file + missing name
+ */
+function assertImportsInScope(opts = {}) {
+  const { root, modulePath, requireMatcher } = opts;
+  if (!root || !modulePath || !(requireMatcher instanceof RegExp)) {
+    throw new Error('assertImportsInScope({ root, modulePath, requireMatcher }): all three are required');
+  }
+  const dirs = opts.dirs || ['routes', 'lib', 'scripts'];
+  const minConsumers = opts.minConsumers == null ? 2 : opts.minConsumers;
+  const minCallable = opts.minCallable == null ? 3 : opts.minCallable;
+
+  const mod = require(path.join(root, modulePath));
+  const CALLABLE = new Set(Object.keys(mod).filter((k) => typeof mod[k] === 'function'));
+
+  const consumers = [];
+  for (const dir of dirs) {
+    const abs = path.join(root, dir);
+    if (!fs.existsSync(abs)) continue;
+    for (const name of fs.readdirSync(abs)) {
+      if (!name.endsWith('.js')) continue;
+      const src = fs.readFileSync(path.join(abs, name), 'utf8');
+      if (requireMatcher.test(src)) consumers.push({ rel: `${dir}/${name}`, src });
+    }
+  }
+
+  const problems = [];
+  if (consumers.length < minConsumers) {
+    problems.push(`only ${consumers.length} consumer(s) found — if the finder matches nothing, the check passes while checking nothing`);
+  }
+  if (CALLABLE.size < minCallable) {
+    problems.push(`the module exports only ${CALLABLE.size} function(s) — is modulePath pointing at the right file?`);
+  }
+
+  for (const { rel, src } of consumers) {
+    const scope = inScope(src);
+    const missing = new Set();
+    // A call site: an identifier followed by "(", NOT preceded by a dot (`core.foo(` is a
+    // property access, not a bare reference) and not part of a longer identifier.
+    for (const m of src.matchAll(/(^|[^.\w$])([A-Za-z_$][\w$]*)\s*\(/g)) {
+      const name = m[2];
+      if (CALLABLE.has(name) && !scope.has(name)) missing.add(name);
+    }
+    if (missing.size) {
+      problems.push(`${rel} calls ${[...missing].join(', ')} but never brings it into scope — a ` +
+        'ReferenceError at runtime, and inside a catch it reads as an empty result');
+    }
+  }
+
+  if (problems.length) throw new Error('import-scope violations:\n  - ' + problems.join('\n  - '));
+  return { consumers: consumers.length, callable: CALLABLE.size };
+}
+
+module.exports = { assertImportsInScope };

package/index.js

@@ -0,0 +1,21 @@
+/**
+ * @aria-framework/testkit — test infrastructure for the aria apps. A DEV DEPENDENCY: nothing here
+ * belongs in a production install, which is why it is its own package rather than part of kit.
+ *
+ *   createHarness()                     — the ✓/✗ micro-harness (~111 hand-rolled copies replaced);
+ *                                         check() refuses async callbacks, acheck() awaits them,
+ *                                         done() prints the summary and owns process.exit.
+ *   assertImportsInScope({...})         — every consumer of a module has every function it calls
+ *                                         in scope (the silently-empty-list-in-a-catch class).
+ *   assertVersionSingleSource({...})    — package.json vs derived version files vs the lockfile's
+ *                                         two copies.
+ */
+
+'use strict';
+
+module.exports = Object.assign(
+  {},
+  require('./harness'),
+  require('./importsInScope'),
+  require('./versionSync')
+);

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@aria-framework/testkit",
+  "description": "Aria App Framework — test infrastructure. The ✓/✗ micro test-harness (createHarness, with the async-callback guard that stops a suite silently passing), assertImportsInScope (every consumer of a module has every function it calls in scope), and assertVersionSingleSource (package.json vs derived version files vs the lockfile's two copies). Dev-dependency only: nothing here belongs in a production install.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "harness.js",
+    "importsInScope.js",
+    "versionSync.js"
+  ],
+  "scripts": {
+    "test": "node test/smoke.js"
+  }
+}

package/versionSync.js

@@ -0,0 +1,59 @@
+/**
+ * assertVersionSingleSource — every stored copy of the app version agrees.
+ *
+ * The rule, and the history behind it: a second copy of the version that nothing validates WILL
+ * rot. Both apps hand-maintained config/version.js and drifted (27 minors in one, 9 commits in
+ * the other) — fixed by DERIVING it. Then the lockfile did the same thing: version bumps are
+ * applied by editing package.json, which only `npm install` syncs into package-lock.json, so one
+ * app's lock sat six releases behind the tree — in the file `npm ci` reads on every deploy.
+ *
+ * Deriving is not available for the lockfile (npm owns its format), so this is the next best
+ * thing: a check that fails the suite the moment the copies disagree.
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * @param {{
+ *   root: string,               app root (absolute)
+ *   derivedFiles?: string[],    modules exporting { version } that must equal package.json's
+ *                               (default ['config/version.js'])
+ *   lockfile?: boolean          also check package-lock.json root + packages[""] (default true)
+ * }} opts
+ * @returns {{version: string}} on success
+ * @throws Error naming every disagreeing copy
+ */
+function assertVersionSingleSource(opts = {}) {
+  const root = opts.root;
+  if (!root) throw new Error('assertVersionSingleSource({ root }): the app root is required');
+  const derived = opts.derivedFiles || [path.join('config', 'version.js')];
+
+  const pkg = require(path.join(root, 'package.json'));
+  const problems = [];
+
+  for (const rel of derived) {
+    const mod = require(path.join(root, rel));
+    if (mod.version !== pkg.version) {
+      problems.push(`${rel} says ${mod.version}, package.json says ${pkg.version} — it must DERIVE, not be maintained by hand`);
+    }
+  }
+
+  if (opts.lockfile !== false) {
+    const lock = require(path.join(root, 'package-lock.json'));
+    if (lock.version !== pkg.version) {
+      problems.push(`package-lock.json root says ${lock.version} — run \`npm install --package-lock-only\` after bumping`);
+    }
+    const rootPkg = lock.packages && lock.packages[''];
+    if (!rootPkg) problems.push('package-lock.json has no packages[""] entry — expected lockfile v3');
+    else if (rootPkg.version !== pkg.version) {
+      problems.push(`package-lock.json packages[""] says ${rootPkg.version} — the second copy inside the lockfile drifts independently`);
+    }
+  }
+
+  if (problems.length) throw new Error('version copies disagree:\n  - ' + problems.join('\n  - '));
+  return { version: pkg.version };
+}
+
+module.exports = { assertVersionSingleSource };