@bongos/core 1.19.535 → 1.19.536

package/tests/project_settings_page.mjs

@@ -0,0 +1,337 @@
+// tests/project_settings_page.mjs — the five fundamentals, and the rule that keeps
+// them honest (task 1003280, goal 1000072, criterion legibility-project-settings).
+//
+// Three things are pinned here, and the third matters most.
+//
+// 1. The route works: one read returns all five rows, the timer round-trips through
+//    the shared parser, and the category set can be renamed, reordered and retired.
+//
+// 2. AN ABSENT FUNDAMENTAL IS REPORTED ABSENT. `upmarket_percent` has no knob behind
+//    it anywhere in this codebase, and equity is a settled owner decision that it is
+//    NOT real. Both must render as themselves. A plausible zero on either would be a
+//    fabricated claim about the project's economics on the page its owner trusts most
+//    — a worse failure than the illegibility this goal exists to fix.
+//
+// 3. THE PAGE RE-TYPES NOTHING. No formula, bound, default or file path is duplicated
+//    in the client. That is the whole reason this page can be believed: a settings
+//    surface carrying its own copy of `round(cost × 1.20)` or of "1..365" drifts from
+//    the code that actually decides, which is precisely ADR 0226's failure one release
+//    later. This is asserted against the real file, because a rule that lives only in
+//    a comment comes back.
+//
+// Run:  node --test tests/project_settings_page.mjs
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+// The anti-drift assertions below are about what the code DOES, so they read it with
+// full-line comments removed. Without this they trip on the very prose that explains
+// the rule — this file's own header quotes "1..365" as the thing not to re-type, and
+// the grant migration names the pre-rename table to warn against copying it.
+const stripLineComments = (src, marker) => src
+  .split('\n')
+  .filter((line) => !line.trimStart().startsWith(marker))
+  .join('\n');
+
+const gc = require(path.join(ROOT, 'modules', 'lifecycle', 'goal-category.js'));
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+
+const fakeRes = () => ({
+  code: null, statusCode: 200, payload: null, headers: {},
+  fail(code, status, extra) { this.code = code; this.statusCode = typeof status === 'number' ? status : status?.status ?? 400; this.payload = { error: code, ...(extra || {}) }; return this; },
+  status(c) { this.statusCode = c; return this; },
+  set(k, v) { this.headers[k] = v; return this; },
+  json(p) { this.payload = p; return this; },
+});
+
+// ---- the route, executed for real -----------------------------------------
+//
+// The router is built against the REAL module-api and the REAL goal-category; only
+// the two calls that would reach Postgres are swapped. Stubbing the row builders
+// instead would prove nothing about the shape the page actually receives.
+const WORKING_REWARD = { rewardConfig: () => ({ marginPct: 20, usdPeg: 1, mode: 'cost-plus-only', perTaskCredit: false, ideatorCredit: true }) };
+function buildRouterWithStubs({ timer, categories, reward = WORKING_REWARD }) {
+  const saved = {
+    resolveRotDays: api.resolveRotDays,
+    resolveOptional: api.resolveOptional,
+    list: gc.listCategories,
+    set: api.projectSettings.set,
+  };
+  api.resolveRotDays = async () => timer;
+  // reward: WORKING_REWARD (default) | null (port absent) | 'throws' (rewardConfig raises).
+  const rewardPort = reward === 'throws'
+    ? { rewardConfig: () => { throw new Error('reward boom'); } }
+    : reward;
+  api.resolveOptional = (port) => (port === 'reward' ? rewardPort : null);
+  gc.listCategories = async () => categories;
+  api.projectSettings.set = async () => ({ key: 'attention.rot_days', value: '45' });
+
+  delete require.cache[require.resolve(path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js'))];
+  const router = require(path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js'))();
+  const restore = () => {
+    api.resolveRotDays = saved.resolveRotDays;
+    api.resolveOptional = saved.resolveOptional;
+    gc.listCategories = saved.list;
+    api.projectSettings.set = saved.set;
+  };
+  // The handler is the LAST layer on the matching route (requireBuilder and the
+  // permission gate sit in front); calling it directly is what keeps this a unit test
+  // of the payload rather than of the auth stack, which has its own tests.
+  const handlerFor = (method, routePath) => {
+    const layer = router.stack.find((l) => l.route && l.route.path === routePath && l.route.methods[method]);
+    assert.ok(layer, `no ${method.toUpperCase()} ${routePath}`);
+    const stack = layer.route.stack;
+    return stack[stack.length - 1].handle;
+  };
+  return { handlerFor, restore };
+}
+
+const TIMER_OK = { days: 30, source: 'default', invalid: null };
+const CATS = [
+  { id: 1, slug: 'platform', label: 'Platform', sort_order: 10, active: true },
+  { id: 2, slug: 'retired-thing', label: 'Retired thing', sort_order: 20, active: false },
+];
+
+test('one read returns all five fundamentals, each naming where its value came from', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS });
+  try {
+    const res = fakeRes();
+    await handlerFor('get', '/project-settings')({ query: {} }, res);
+    const rows = res.payload.rows;
+    assert.equal(rows.length, 5, 'the page draws five rows, so the read returns five');
+    assert.deepEqual(rows.map((r) => r.key),
+      ['rot_timer', 'work_categories', 'credit_calculation', 'equity_calculation', 'upmarket_percent']);
+    // Provenance is the point of the page: every row says where its value came from.
+    for (const r of rows) {
+      assert.ok(r.reads && r.reads.file, `${r.key} names no file`);
+      assert.ok(r.sentence && r.sentence.length > 20, `${r.key} has no readable sentence`);
+    }
+    // Exactly two knobs — the criterion's "change the two that are knobs".
+    assert.deepEqual(rows.filter((r) => r.editable).map((r) => r.key), ['rot_timer', 'work_categories']);
+    // A no-store receipt: a cached settings read is wrong the moment a knob turns.
+    assert.equal(res.headers['Cache-Control'], 'no-store');
+  } finally { restore(); }
+});
+
+test('an absent fundamental is reported absent, never as a plausible zero', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS });
+  try {
+    const res = fakeRes();
+    await handlerFor('get', '/project-settings')({ query: {} }, res);
+    const by = Object.fromEntries(res.payload.rows.map((r) => [r.key, r]));
+
+    assert.equal(by.upmarket_percent.state, 'absent');
+    assert.equal(by.upmarket_percent.value, undefined, 'an unconfigured knob must carry NO value');
+    assert.match(by.upmarket_percent.sentence, /no such setting yet/i);
+    assert.doesNotMatch(by.upmarket_percent.sentence, /\b0\s*%/, 'never render the absent knob as 0%');
+
+    assert.equal(by.equity_calculation.state, 'not-yet-real');
+    assert.match(by.equity_calculation.sentence, /no legal equity is issued/i);
+    assert.match(by.equity_calculation.sentence, /no cap table/i);
+  } finally { restore(); }
+});
+
+test('the credit row reports the formula in force, and says the estimate is not paid', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS });
+  try {
+    const res = fakeRes();
+    await handlerFor('get', '/project-settings')({ query: {} }, res);
+    const credit = res.payload.rows.find((r) => r.key === 'credit_calculation');
+    assert.equal(credit.editable, false);
+    assert.match(credit.sentence, /× 1\.20/, 'the multiplier comes from the resolved policy');
+    // cost-plus-only: the per-task estimate is advertised and never paid (ADR 0146).
+    assert.match(credit.sentence, /advertised guide only/i);
+  } finally { restore(); }
+});
+
+test('the credit row degrades named when the economy module is absent', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS, reward: null });
+  try {
+    const res = fakeRes();
+    await handlerFor('get', '/project-settings')({ query: {} }, res);
+    const credit = res.payload.rows.find((r) => r.key === 'credit_calculation');
+    assert.equal(credit.state, 'unavailable');
+    assert.equal(credit.value, undefined, 'no formula to report → no value');
+    assert.match(credit.sentence, /not enabled/i);
+  } finally { restore(); }
+});
+
+test('the credit row degrades named when rewardConfig() throws, rather than 500-ing the page', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS, reward: 'throws' });
+  try {
+    const res = fakeRes();
+    await handlerFor('get', '/project-settings')({ query: {} }, res);
+    // The whole read must still succeed — one bad lens degrades its own row, not the page.
+    assert.equal(res.code, null, 'the GET must not fail');
+    const credit = res.payload.rows.find((r) => r.key === 'credit_calculation');
+    assert.equal(credit.state, 'unavailable');
+    assert.equal(credit.value, undefined);
+    assert.match(credit.sentence, /could not be read/i);
+  } finally { restore(); }
+});
+
+test('the stale-timer row names the OTHER timer, so the page cannot be misread as configuring the sweep', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS });
+  try {
+    const res = fakeRes();
+    await handlerFor('get', '/project-settings')({ query: {} }, res);
+    const rot = res.payload.rows.find((r) => r.key === 'rot_timer');
+    assert.ok(rot.sibling, 'the claim sweep must be named on this row');
+    assert.equal(rot.sibling.reads.file, 'src/stale-timer.js');
+    assert.match(rot.sibling.sentence, /RELEASES it without asking/);
+    // The rot timer only ever ASKS — the reporting half of ADR 0226's asymmetry.
+    assert.match(rot.sentence, /ASKS a person/);
+  } finally { restore(); }
+});
+
+test('a configured-but-unusable timer is reported on screen, not thrown', async () => {
+  const invalid = { days: 30, source: 'default', invalid: { where: "project_settings['attention.rot_days']", raw: 'soon', reason: 'not a number' } };
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: invalid, categories: CATS });
+  try {
+    const res = fakeRes();
+    await handlerFor('get', '/project-settings')({ query: {} }, res);
+    const rot = res.payload.rows.find((r) => r.key === 'rot_timer');
+    assert.equal(rot.invalid.raw, 'soon');
+    assert.equal(rot.value.days, 30, 'the fallback that is actually in force is still reported');
+  } finally { restore(); }
+});
+
+test('the timer write refuses a bad body in two layers, each with its own code', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS });
+  const patch = handlerFor('patch', '/project-settings/rot-days');
+  try {
+    // Layer 1 — the strict ADR 0118 schema settles the TYPE and rejects unknown keys.
+    for (const bad of [{ days: 'soon' }, { days: '' }, { days: null }, {}, { days: 30, sneaky: 1 }]) {
+      const res = fakeRes();
+      await patch({ body: bad, builder: { id: 7 } }, res);
+      assert.equal(res.code, 'validation_failed', `accepted body ${JSON.stringify(bad)}`);
+      assert.equal(res.statusCode, 400);
+    }
+    // Layer 2 — the resolver's OWN parser settles the RANGE, so the form and the reader
+    // of the value can never disagree about what is acceptable.
+    for (const bad of [0, -3, 1.5, 400]) {
+      const res = fakeRes();
+      await patch({ body: { days: bad }, builder: { id: 7 } }, res);
+      assert.equal(res.code, 'bad_rot_days', `accepted ${JSON.stringify(bad)}`);
+      assert.equal(res.statusCode, 400);
+    }
+  } finally { restore(); }
+});
+
+test('a good timer write echoes what the system will now READ, not what was sent', async () => {
+  const { handlerFor, restore } = buildRouterWithStubs({ timer: { days: 45, source: 'project_settings', invalid: null }, categories: CATS });
+  try {
+    const res = fakeRes();
+    await handlerFor('patch', '/project-settings/rot-days')({ body: { days: 45 }, builder: { id: 7 } }, res);
+    assert.equal(res.payload.ok, true);
+    assert.equal(res.payload.rot_days, 45);
+    assert.equal(res.payload.source, 'project_settings');
+    // The receipt carries provenance, never a bare number (ADR 0226).
+    assert.match(res.payload.describe, /45d \(project_settings\)/);
+  } finally { restore(); }
+});
+
+// ---- the category set's shape ----------------------------------------------
+
+test('PATCH refuses a body that changes nothing rather than answering 200', async () => {
+  const handler = gc.categoryUpdateHandler({
+    update: async () => { throw new Error('must not be called'); },
+    validateOrRespond: () => false, LIMITS: { TITLE: 200 },
+    parseId: () => 1, log: null,
+  });
+  const res = fakeRes();
+  await handler({ params: { id: '1' }, body: {} }, res);
+  assert.equal(res.code, 'nothing_to_update');
+});
+
+test('PATCH refuses a fractional sort_order instead of silently rounding it', async () => {
+  const handler = gc.categoryUpdateHandler({
+    update: async () => { throw new Error('must not be called'); },
+    validateOrRespond: () => false, LIMITS: { TITLE: 200 },
+    parseId: () => 1, log: null,
+  });
+  const res = fakeRes();
+  await handler({ params: { id: '1' }, body: { sort_order: 2.5 } }, res);
+  assert.equal(res.code, 'bad_sort_order');
+});
+
+test('retiring a category is a flag, never a delete — the label stays resolvable', async () => {
+  let got = null;
+  const handler = gc.categoryUpdateHandler({
+    update: async (args) => { got = args; return { ...CATS[0], active: false }; },
+    validateOrRespond: () => false, LIMITS: { TITLE: 200 },
+    parseId: () => 1, log: null,
+  });
+  const res = fakeRes();
+  await handler({ params: { id: '1' }, body: { active: false } }, res);
+  assert.equal(res.payload.category.active, false);
+  // Only what was sent travels: a retire must not blank the label by omission.
+  assert.equal(got.label, undefined);
+  assert.equal(got.sortOrder, undefined);
+  assert.equal(got.active, false);
+});
+
+test('a missing category is a 404, and it costs ONE query — no separate pre-read', async () => {
+  // updateCategory returns null for a row that is not there; that IS the 404, so the
+  // handler no longer issues a second read just to produce it (task 1003280 grade).
+  let updateCalls = 0;
+  const handler = gc.categoryUpdateHandler({
+    update: async () => { updateCalls += 1; return null; },
+    validateOrRespond: () => false, LIMITS: { TITLE: 200 },
+    parseId: () => 999, log: null,
+  });
+  const res = fakeRes();
+  await handler({ params: { id: '999' }, body: { label: 'x' } }, res);
+  assert.equal(res.code, 'category_not_found');
+  assert.equal(res.statusCode, 404);
+  assert.equal(updateCalls, 1, 'exactly one PK query — the redundant pre-read is gone');
+});
+
+test('the slug is not patchable — it is the key goal prose refers to', () => {
+  const src = read('modules', 'lifecycle', 'goal-category.js');
+  const fn = src.slice(src.indexOf('async function updateCategory'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.doesNotMatch(body, /\bslug\s*=/, 'updateCategory must never assign slug');
+});
+
+// ---- the anti-drift rule (the one that makes this page believable) ----------
+
+test('the ROUTE re-types no timer bound either — the drift the grade caught, pinned one layer up', () => {
+  // The major finding on this task's first grade: the page's anti-drift rule held on the
+  // CLIENT but the ROUTE re-typed `min: 1, max: 365` and the 400 message re-typed the
+  // range. The bounds live once, in src/bongos/project-settings.js. Assert the route
+  // carries neither literal in executable code.
+  const route = stripLineComments(read('modules', 'lifecycle', 'routes', 'project-settings.js'), '//');
+  assert.doesNotMatch(route, /\b365\b/, 'the route must read MAX_ROT_DAYS, not re-type 365');
+  assert.match(route, /api\.projectSettings\.(MIN|MAX)_ROT_DAYS/, 'the route reads the bounds from the single source');
+});
+
+test('the page re-types no formula, bound, default or file path from the server', () => {
+  const page = stripLineComments(read('modules', 'hall-ui', 'public', 'project-settings.js'), '//');
+  // The credit formula lives in economy and arrives as a sentence.
+  assert.doesNotMatch(page, /1\.2\b|\*\s*1\.20|marginPct\s*[/*]/, 'the client must not compute the reward');
+  // The rot bounds live in src/bongos/project-settings.js and arrive in row.value.
+  assert.doesNotMatch(page, /\b365\b/, 'the client must not re-type the timer ceiling');
+  // Provenance paths are server-supplied strings, never authored in the client.
+  assert.doesNotMatch(page, /src\/stale-timer\.js|core_226|core_231/, 'the client must not author provenance paths');
+});
+
+test('the page is gated, the atom exists, and a grant migration backs it', () => {
+  assert.match(read('tests', 'hall_page_gate_map.mjs'), /'\/builders\/project-settings': 'requireGovernmentPage'/);
+  assert.match(read('modules', 'government', 'catalog.js'), /key: 'project\.settings\.manage'/);
+  const grantSrc = read('modules', 'government', 'migrations', 'government_010_project_settings_manage.sql');
+  const grant = stripLineComments(grantSrc, '--');
+  // One block per rank — the drift guard scans for this literal shape.
+  assert.match(grant, /SELECT 'metic', unnest\(ARRAY\[\s*'project\.settings\.manage'/);
+  assert.match(grant, /SELECT 'archon', unnest\(ARRAY\[\s*'project\.settings\.manage'/);
+  // The renamed table, not the pre-government_001 one.
+  assert.match(grant, /INSERT INTO government_rank_permissions/);
+  assert.doesNotMatch(grant, /governance_role_permissions/);
+});