@bongos/core 1.19.332 → 1.19.333

package/scripts/gds/fitness-checks-write-validation.js

@@ -0,0 +1,144 @@
+// scripts/gds/fitness-checks-write-validation.js — Check 18 (BV1 R12 / task 1999,
+// ADR 0118): every body-reading write route validates its body.
+//
+// Carved out of scripts/gds/fitness.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring that file under the 1,500-line ratchet. A STRUCTURAL
+// move: the lines below are fitness.js's originals unchanged, and fitness.js
+// imports every name straight back, so the CHECKS registry and the module's
+// public surface (which the tests read heavily) are untouched.
+
+'use strict';
+
+const genApiDocs = require('./gen-api-docs'); // R12 (#1999): reuse the route model (readsBody/validated) that drives the OpenAPI spec
+
+// ============================================================================
+// Check 18 — every write route validates its body (BV1 R12 / task 1999 / ADR 0118)
+// ============================================================================
+//
+// Criterion api-validation: "the build fails on an unvalidated write route." R11
+// (#1998) gave every body-reading write route a strict validateOrRespond schema
+// (code-first, spec-driven — ADR 0118); this LOCKS that in. Reusing the SAME
+// route model that generates the OpenAPI spec (gen-api-docs.extractModel —
+// readsBody + validated), a POST/PUT/PATCH/DELETE that reads req.body must carry
+// a validateOrRespond()/validate(req.body) schema. Hard-zero (no ratchet — the
+// R11 sweep already reached 100%): a NEW write route that reads a body but
+// declares no schema fails the build immediately, so unknown/typo'd fields can
+// never again be silently dropped.
+//
+// EXEMPT — the builder-settings /me/*-prefs routes. Their bodies are DYNAMIC-KEY
+// maps ({ "<skill|sound|event-id>": <value> }, or a single-key toggle) that a
+// FIXED field schema cannot express; they validate via their module lib's
+// validatePatch()/validate() (which already rejects unknown keys with a 422). A
+// fixed strict schema would wrongly reject the valid dynamic keys — so these are
+// validated-by-lib, not by validateOrRespond. Documented per-route below; see
+// learning #133 / ADR 0118. Adding a route here is a deliberate, reviewable act.
+const WRITE_VALIDATION_EXEMPT = new Set([
+  'PATCH /me/skill-prefs',        // { "<skill>": "<model>"|null } — dynamic keys; skillPrefs.validatePatch
+  'PATCH /me/sound-prefs',        // { "<sound>": <bool>|null }    — dynamic keys; soundPrefs.validatePatch
+  'PATCH /me/event-sound-prefs',  // { "<event>": "<variant>"|null } — dynamic keys; eventSoundPrefs.validatePatch
+  'PATCH /me/wandering',          // { wandering: 0..3|null }      — rank-capped; wanderingPrefs.validatePatch
+  'PATCH /me/interaction',        // interaction profile           — interactionPrefs.validatePatch
+  'PATCH /me/model-allocation',   // per-slot tiers                — modelAllocPrefs.validatePatch
+  'PATCH /me/render',             // { widgets: <bool>|null }      — renderPrefs.validatePatch
+  'PATCH /me/display-name',       // { display_name }              — displayName.validate
+]);
+
+// KNOWN GAPS, NOT EXEMPTIONS (task 1002551 / BV1.R109b → tracked by task 1002552).
+//
+// These three are NOT validated-by-lib and do NOT belong in WRITE_VALIDATION_EXEMPT
+// above — they are genuine ADR 0118 gaps that must grow a validateOrRespond schema.
+// They surface here only because R109b taught route discovery to see MULTI-LINE
+// `router.<method>(` declarations: this check reuses gen-api-docs.extractModel(), so
+// the same regex hole that hid them from the rank auditor hid them from Check 18 too.
+// They are pre-existing (never validated), not a regression.
+//
+// They are recorded rather than fixed because modules/*/routes/*.js was being migrated
+// concurrently by BV1.R105, so editing those files would have collided. This is the
+// Check-17 ratchet posture: a NAMED, non-growing baseline. The list may only ever
+// SHRINK — a new unvalidated write route is not on it and still hard-fails the build,
+// and a stale entry (one that HAS been fixed) also fails, so the list cannot rot.
+// Delete this constant when task 1002552 lands and Check 18 returns to hard-zero.
+// EMPTY as of BV1.R109c (task 1002552) — all three original entries now validate.
+// Kept (rather than deleted) as the ratchet itself: an empty named baseline states
+// the invariant is hard-zero, and any future entry has to be added deliberately.
+const WRITE_VALIDATION_BASELINE = new Set([]);
+
+function scanUnvalidatedWriteRoutes(model = genApiDocs.extractModel()) {
+  const unvalidated = [];
+  const baselineSeen = new Set();
+  for (const r of model) {
+    if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(r.method)) continue;
+    // Only routes that actually read a body have an input surface to validate;
+    // a write that ignores req.body has nothing to declare.
+    if (!r.body || !r.body.readsBody || r.body.validated) continue;
+    const key = `${r.method} ${r.route}`;
+    if (WRITE_VALIDATION_EXEMPT.has(key)) continue;
+    if (WRITE_VALIDATION_BASELINE.has(key)) { baselineSeen.add(key); continue; }
+    unvalidated.push(`${key}  [${r.file}]`);
+  }
+  // A baseline entry that no longer reports as unvalidated has been FIXED — it must be
+  // removed, or the list would quietly license a future regression on that same route.
+  for (const key of WRITE_VALIDATION_BASELINE) {
+    if (!baselineSeen.has(key)) {
+      unvalidated.push(`${key}  [STALE BASELINE — this route now validates; remove it from WRITE_VALIDATION_BASELINE in scripts/gds/fitness.js]`);
+    }
+  }
+  return unvalidated;
+}
+
+function checkWriteRoutesValidated() {
+  const unvalidated = scanUnvalidatedWriteRoutes();
+  const violations = [];
+  if (unvalidated.length) {
+    violations.push(
+      `${unvalidated.length} write route(s) read req.body but declare NO validateOrRespond/validate schema (ADR 0118 / R11 requires one so unknown fields are rejected via the ADR-0116 envelope): ${unvalidated.join('; ')}. Add a strict validateOrRespond(req, res, { … }) listing every field the handler reads (see learning #133). A dynamic-key body validated by a module lib belongs in WRITE_VALIDATION_EXEMPT with a one-line reason.`
+    );
+  }
+  return {
+    name: 'every write route validates its body (ADR 0118 / R12)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `body-reading POST/PUT/PATCH/DELETE routes must call validateOrRespond/validate (${WRITE_VALIDATION_EXEMPT.size} dynamic-key prefs routes validate by lib; ${WRITE_VALIDATION_BASELINE.size} known gaps tracked by task 1002552, list may only shrink); ${unvalidated.length} unvalidated.`,
+  };
+}
+
+
+// ── Check 19 — the ADR 0174 vocabulary wall (goal 1000068 R07, task 1003008) ──
+//
+// "Role" means ONE thing in this codebase: a craft — Artist, Ideator, or Builder.
+// The permission system is the GOVERNMENT and the positions in it are RANKS.
+// Before ADR 0174 the same word named both, and goal 1000066 was about to claim
+// it for the crafts while modules/governance/ still used it for the ladder. This
+// check is what stops that collision reforming the first time someone copies an
+// old file.
+//
+// TWO RULES, both scoped to the GOVERNMENT SURFACE — not the whole repo. A repo-
+// wide ban would be wrong: `builders.system_role` is a core column for machine
+// identities, Discord's API owns its own "role" noun, and the crafts are supposed
+// to use the word.
+//
+//   1. no "role" under modules/government/ or on the Government hall page
+//   2. no "governance" there either — the old name of the same surface
+//
+// EXCLUDED BY CONSTRUCTION (not by allowlist):
+//   • modules/government/migrations/governance_*.sql — the already-applied
+//     migrations keep their filenames forever (schema_migrations is stem-keyed;
+//     renaming one re-runs it, and governance_002 is a seed/backfill). Their
+//     bodies necessarily name the pre-rename tables they created.
+//   • docs/adr/, docs/session-logs/, docs/governance/ — the historical record.
+//     An ADR describes a decision at a point in time; rewriting it to match
+//     today's vocabulary would erase the evidence that the words changed.
+//
+// The ALLOWLIST below is deliberately tiny and each entry carries its reason. A
+// rule that passes because everything is suppressed reads as evidence while
+// proving nothing — if this list grows, that is the signal to finish the rename,
+// not to add a line.
+
+module.exports = {
+  WRITE_VALIDATION_BASELINE,
+  WRITE_VALIDATION_EXEMPT,
+  checkWriteRoutesValidated,
+  scanUnvalidatedWriteRoutes,
+};

package/scripts/gds/fitness-lib.js

@@ -0,0 +1,82 @@
+// scripts/gds/fitness-lib.js — the two roots every architecture check walks, and
+// the walkers themselves (ADR 0108 §1: core tree vs instance tree).
+//
+// Carved out of scripts/gds/fitness.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring that file under the 1,500-line ratchet. A STRUCTURAL
+// move: the lines below are fitness.js's originals unchanged, and fitness.js
+// imports every name straight back, so the CHECKS registry and the module's
+// public surface (which the tests read heavily) are untouched.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+
+
+// ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — the guardrail walks TWO trees.
+// CORE code + core-owned docs (src/, server.js, scripts/, the src/bongos + scripts/gds nested docs)
+// live under the core PACKAGE; INSTANCE content (the root CLAUDE.md, the .claude/ methodology
+// surface, instance modules + migrations) lives under the host REPO. Modules ship from BOTH.
+// Today both resolve to the same checkout, so every walk below is byte-identical; once the core
+// installs from node_modules they diverge and each check inspects the CORRECT tree. A NEW
+// hardcoded `path.resolve(__dirname,'..','..')` here reintroduces the bug this check exists to stop.
+const CORE_ROOT = resolveCoreRoot();
+const INSTANCE_ROOT = resolveInstanceRoot();
+// REPO_ROOT retained as an alias to the core root for the many purely-core walks below (src/bongos,
+// KERNEL_FILES, scope map, …) — those keep their exact behavior. Instance-owned reads route
+// through INSTANCE_ROOT explicitly, and module reads through MODULE_ROOTS.
+const REPO_ROOT = CORE_ROOT;
+// Deduped module search roots — a module can ship from the core package OR the instance repo (the
+// loader errors on a cross-root key collision, so a key resolves to exactly one root). Deduped so
+// today's single checkout scans each module ONCE (no double-counting).
+const MODULE_ROOTS = [...new Set([CORE_ROOT, INSTANCE_ROOT])];
+
+// ---- shared fs helpers -----------------------------------------------------
+
+function walkJs(absRoot, out = []) {
+  let st;
+  try { st = fs.statSync(absRoot); } catch { return out; }
+  if (st.isFile()) { if (absRoot.endsWith('.js')) out.push(absRoot); return out; }
+  for (const ent of fs.readdirSync(absRoot, { withFileTypes: true })) {
+    if (ent.name === 'node_modules' || ent.name === '.git') continue;
+    walkJs(path.join(absRoot, ent.name), out);
+  }
+  return out;
+}
+// repo-relative POSIX path for an abs file under EITHER root (core or instance). The classifier
+// regexes throughout this file key on these relative strings, which are identical whichever tree
+// a file lives in — so only the WALK roots change under the split, not the classification.
+const rel = (abs) => {
+  for (const base of [CORE_ROOT, INSTANCE_ROOT]) {
+    const r = path.relative(base, abs);
+    if (r && !r.startsWith('..') && !path.isAbsolute(r)) return r.split(path.sep).join('/');
+  }
+  return path.relative(CORE_ROOT, abs).split(path.sep).join('/');
+};
+// Walk .js under `subpath` (e.g. 'modules') across ALL module roots, deduped by repo-relative
+// path so the same file is never scanned twice when the roots coincide (today).
+function walkJsAllRoots(subpath, roots = MODULE_ROOTS) {
+  const seen = new Set();
+  const out = [];
+  for (const root of roots) {
+    for (const abs of walkJs(path.join(root, subpath))) {
+      const r = rel(abs);
+      if (seen.has(r)) continue;
+      seen.add(r);
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+
+module.exports = {
+  CORE_ROOT,
+  INSTANCE_ROOT,
+  MODULE_ROOTS,
+  REPO_ROOT,
+  rel,
+  walkJs,
+  walkJsAllRoots,
+};