@bongos/core 1.20.25 → 1.20.27

package/tests/provisioning_planet_physics.mjs

@@ -0,0 +1,377 @@
+// tests/provisioning_planet_physics.mjs
+//
+// The seven planet-physics answers, the screening hook, and the soft-limit rule
+// table (BV2.PS02, task 1004416; goal 1000121, spec
+// docs/specs/bongos-v2-project-startup.md decision D6).
+//
+// Done when: a create request can carry the answers, they read back on the project,
+// and a test pins the vocabulary and the stop path. Four layers:
+//   • the vocabulary   — every kind of question, stored canonically, refused loudly
+//   • soft limits      — a reason on every rule, every rule names real answers, and
+//                        nothing claims a limit is enforced
+//   • screening        — the stop path, and the honest projects it must let through
+//   • the routes       — POST /instances carries and reads back the answers; a
+//                        screened description is stopped BEFORE anything is created;
+//                        PATCH …/detail un-answers with null
+//
+// DB-free: the data-access functions the routes need are stubbed on the cached
+// module object, over a loopback listener (the provisioning_module_selection.mjs rig).
+//
+// Run:  node tests/provisioning_planet_physics.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+// ESM named imports off the CJS modules on purpose — knip cannot trace a
+// createRequire() import (the tests/provisioning_module_selection.mjs note).
+import { EU_COUNTRIES, COUNTRY_CODES, REGION_CODES, crossAnswerFault }
+  from '../modules/provisioning/planet-physics.js';
+import { SOFT_LIMIT_RULES, EFFECTS, softLimitsFor } from '../modules/provisioning/soft-limits.js';
+import { SCREENING_RULES, STOP_MESSAGE, screenProject } from '../modules/provisioning/screening.js';
+import { badProjectDetail, screenedOut } from '../modules/provisioning/routes/body-validators.js';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// The Kestrel sample from the canvas, answered in full.
+const KESTREL = Object.freeze({
+  project_state: 'existing', existing_work: ['digital-files', 'code'], main_work: 'code',
+  home_country: 'US', home_region: 'US-NY', builder_geography: 'global',
+  minors_on_board: true, entity: 'for-profit',
+  builders_at_start: 3, builders_expected: 8,
+  reward_intents: ['future-payouts', 'non-monetary'],
+  framing: 'hybrid', services: ['hosting', 'starter-kit', 'guild-access'],
+});
+
+console.log('\nThe vocabulary:');
+
+await t('the seven answers are all questions the detail column knows, beside team_shape', () => {
+  const keys = Object.keys(provisioning.PROJECT_DETAIL_QUESTIONS);
+  for (const key of ['team_shape', ...Object.keys(KESTREL)]) assert.ok(keys.includes(key), `${key} is a question`);
+  assert.deepEqual(provisioning.PROJECT_DETAIL_VOCAB.team_shape, ['solo', 'small-team', 'community'], 'the R15 answer is untouched');
+  // Framing is A–D, in that order.
+  assert.deepEqual(provisioning.PROJECT_DETAIL_VOCAB.framing, ['managed', 'hybrid', 'local', 'open-source']);
+});
+
+await t('every enumerated question has a closed answer list, and every count a range — no defaults anywhere', () => {
+  for (const [key, q] of Object.entries(provisioning.PROJECT_DETAIL_QUESTIONS)) {
+    if (q.kind === 'count') {
+      assert.ok(Number.isInteger(q.min) && q.max > q.min, `${key} has a range`);
+      assert.ok(!(key in provisioning.PROJECT_DETAIL_VOCAB), `${key} has no answer list to offer`);
+    } else {
+      assert.ok(['one', 'many'].includes(q.kind), `${key} is a known kind`);
+      assert.ok(Array.isArray(q.values) && q.values.length, `${key} has a closed list`);
+      assert.equal(provisioning.PROJECT_DETAIL_VOCAB[key], q.values, `${key}'s list is what options serves`);
+    }
+    assert.equal(q.default, undefined, `${key} carries no default`);
+  }
+});
+
+await t('a full set of answers stores canonically and reads back on the project', () => {
+  const stored = provisioning.normalizeProjectDetail(KESTREL);
+  // `many` answers come back in the vocabulary's order, so two spellings store one value.
+  assert.deepEqual(stored.existing_work, ['code', 'digital-files']);
+  assert.deepEqual(stored.reward_intents, ['non-monetary', 'future-payouts']);
+  assert.equal(stored.minors_on_board, true);
+  assert.equal(stored.builders_at_start, 3);
+  const read = provisioning.publicInstance({ id: 1, slug: 'kestrel', detail: stored }).detail;
+  assert.deepEqual(read, stored, 'the read is the stored answers, nothing added or lost');
+  assert.equal(Object.keys(read).length, Object.keys(KESTREL).length);
+});
+
+await t('false and an empty list are real answers, distinct from never answering', () => {
+  const stored = provisioning.normalizeProjectDetail({ minors_on_board: false, reward_intents: [] });
+  assert.deepEqual(stored, { minors_on_board: false, reward_intents: [] });
+  assert.deepEqual(provisioning.normalizeProjectDetail({}), {});
+});
+
+await t('badProjectDetail refuses every kind of wrong answer LOUDLY, naming the question', () => {
+  const cases = [
+    [{ plannet_state: 'new' }, /Unknown detail answer "plannet_state"/],
+    [{ project_state: 'brownfield' }, /"project_state" must be one of: new, existing/],
+    [{ existing_work: 'code' }, /"existing_work" must be a list/],
+    [{ existing_work: ['code', 'sculpture'] }, /"existing_work" must be a list, each item one of/],
+    [{ home_country: 'ZZ' }, /ISO 3166-1 alpha-2/],
+    [{ home_country: 'us' }, /ISO 3166-1 alpha-2/],
+    [{ home_region: 'US-XX' }, /US state or Canadian province/],
+    [{ minors_on_board: 'yes' }, /"minors_on_board" must be one of: false, true/],
+    [{ entity: 'llc' }, /"entity" must be one of/],
+    [{ builders_at_start: 0 }, /whole number from 1/],
+    [{ builders_expected: 2.5 }, /whole number/],
+    [{ builders_expected: '8' }, /whole number/],
+    [{ framing: 'b' }, /"framing" must be one of: managed, hybrid, local, open-source/],
+    [{ services: ['hosting', 'yacht'] }, /"services" must be a list/],
+  ];
+  for (const [detail, re] of cases) {
+    const fault = badProjectDetail(detail);
+    assert.ok(fault, `${JSON.stringify(detail)} is refused`);
+    assert.equal(fault.code, 'bad_detail');
+    assert.match(fault.message, re, JSON.stringify(detail));
+  }
+  assert.equal(badProjectDetail(KESTREL), null, 'the canvas sample is clean');
+});
+
+await t('null un-answers every kind of question — and only null does', () => {
+  const nulls = Object.fromEntries(Object.keys(KESTREL).map((k) => [k, null]));
+  assert.equal(badProjectDetail(nulls), null, 'null is accepted for every question');
+  const { set, clear } = provisioning.projectDetailPatch(nulls);
+  assert.deepEqual(set, {});
+  assert.deepEqual(clear.sort(), Object.keys(KESTREL).sort());
+  assert.ok(badProjectDetail({ existing_work: '' }), 'an empty string is still a typo, not an erase');
+});
+
+await t('answers sent together must agree: main work is one of the existing kinds, the region is in the country', () => {
+  assert.match(badProjectDetail({ existing_work: ['code'], main_work: 'physical-work' }).message, /"main_work" must be one of the kinds/);
+  assert.match(badProjectDetail({ home_country: 'DE', home_region: 'US-CA' }).message, /not in "home_country" DE/);
+  assert.equal(badProjectDetail({ home_country: 'CA', home_region: 'CA-ON' }), null);
+  // Across two writes it is not refused: a merge patch may change one half first.
+  assert.equal(crossAnswerFault({ main_work: 'physical-work' }), null);
+});
+
+await t('the reference lists are what they claim to be', () => {
+  assert.equal(new Set(COUNTRY_CODES).size, COUNTRY_CODES.length, 'no duplicate country');
+  assert.equal(COUNTRY_CODES.length, 249, 'the ISO 3166-1 officially assigned set');
+  assert.equal(EU_COUNTRIES.length, 27);
+  for (const c of EU_COUNTRIES) assert.ok(COUNTRY_CODES.includes(c), `${c} is a country`);
+  for (const r of REGION_CODES) assert.ok(COUNTRY_CODES.includes(r.slice(0, 2)), `${r} is inside a country`);
+});
+
+console.log('\nThe soft-limit table:');
+
+// Is `option` a real question, or a real member of one?
+function optionExists(option) {
+  const [key, member] = option.split(':');
+  const q = provisioning.PROJECT_DETAIL_QUESTIONS[key];
+  if (!q) return false;
+  return member === undefined || (q.values || []).map(String).includes(member);
+}
+
+await t('every rule carries a reason, a known effect, and names only real questions and answers', () => {
+  const ids = new Set();
+  for (const rule of SOFT_LIMIT_RULES) {
+    assert.ok(!ids.has(rule.id), `${rule.id} is unique`); ids.add(rule.id);
+    assert.ok(typeof rule.reason === 'string' && rule.reason.length > 10, `${rule.id} has a reason`);
+    assert.ok(EFFECTS.includes(rule.effect), `${rule.id}'s effect is one of ${EFFECTS}`);
+    assert.ok(rule.options.length, `${rule.id} names an option`);
+    for (const option of rule.options) assert.ok(optionExists(option), `${rule.id}: ${option} exists`);
+    for (const [key, test] of Object.entries(rule.when)) {
+      const q = provisioning.PROJECT_DETAIL_QUESTIONS[key];
+      assert.ok(q, `${rule.id}: ${key} is a question`);
+      const named = test.in || [test.has ?? test.lacks];
+      for (const v of named) assert.ok(q.values.includes(v), `${rule.id}: ${key}=${v} is a real answer`);
+    }
+  }
+});
+
+await t('nothing claims a limit is enforced — not the resolution, not any reason', () => {
+  assert.equal(softLimitsFor(KESTREL).enforced, false);
+  assert.equal(softLimitsFor({}).enforced, false);
+  for (const rule of SOFT_LIMIT_RULES) {
+    assert.doesNotMatch(rule.reason, /enforc|automatic|blocked|prohibit|not permitted|forbidden/i, `${rule.id} words advice as a rule`);
+  }
+});
+
+await t("the spec's three examples fire, each with its why line", () => {
+  const find = (answers, option) => softLimitsFor(answers).limits.filter((l) => l.option === option);
+  const equity = find({ entity: 'intent-solo' }, 'reward_intents:equity');
+  assert.equal(equity.length, 1); assert.equal(equity[0].effect, 'grey');
+  assert.match(equity[0].reason, /until you form a company/);
+  assert.match(find({ builder_geography: 'us-eu' }, 'reward_intents:cash')[0].reason, /EU aren't available yet/);
+  assert.match(find({ minors_on_board: true }, 'reward_intents:cash')[0].reason, /13 to 15 join non-monetary tracks only/);
+  // A formed company is not greyed out of equity.
+  assert.equal(find({ entity: 'for-profit' }, 'reward_intents:equity').length, 0);
+});
+
+await t('a rule never fires on an answer nobody gave — only the platform-wide facts apply to a skipped interview', () => {
+  const skipped = softLimitsFor({});
+  for (const limit of skipped.limits) {
+    const rule = SOFT_LIMIT_RULES.find((r) => r.id === limit.rule);
+    assert.deepEqual(rule.when, {}, `${rule.id} fired with no answers`);
+  }
+  // `lacks` is "said, and not this" — never "never said".
+  assert.ok(!softLimitsFor({}).limits.some((l) => l.rule === 'labor-payment-follows-cash'));
+  assert.ok(softLimitsFor({ reward_intents: ['equity'] }).limits.some((l) => l.rule === 'labor-payment-follows-cash'));
+  assert.ok(!softLimitsFor({ reward_intents: ['cash'] }).limits.some((l) => l.rule === 'labor-payment-follows-cash'));
+});
+
+await t('the table hides whole questions too: a new planet has no existing work, managed has no services to pick', () => {
+  const opts = (answers) => softLimitsFor(answers).limits.filter((l) => l.effect === 'hide').map((l) => l.option);
+  assert.deepEqual(opts({ project_state: 'new' }), ['existing_work', 'main_work']);
+  assert.ok(opts({ framing: 'managed' }).includes('services'));
+  assert.ok(!opts({ framing: 'hybrid' }).includes('services'));
+});
+
+await t('the soft limits read back on every owner read of the project, from the stored answers', () => {
+  const view = provisioning.publicInstance({ id: 1, slug: 'kestrel', detail: provisioning.normalizeProjectDetail({ entity: 'nonprofit' }) });
+  assert.equal(view.soft_limits.enforced, false);
+  assert.ok(view.soft_limits.limits.some((l) => l.rule === 'equity-not-in-a-nonprofit'));
+});
+
+console.log('\nScreening:');
+
+await t('the stop path: each rule stops a description that asks for the thing itself', () => {
+  const stops = [
+    ['A marketplace to sell ransomware to anyone who pays.', 'malware'],
+    ['We want to build a phishing kit that copies bank logins.', 'phishing'],
+    ['A site sharing explicit images of minors.', 'child-sexual-abuse'],
+  ];
+  for (const [description, rule] of stops) assert.deepEqual(screenProject({ description }), { stop: true, rule }, description);
+  assert.deepEqual(SCREENING_RULES.map((r) => r.id).sort(), stops.map(([, r]) => r).sort(), 'every rule has a stop case here');
+});
+
+await t('honest projects pass — including the ones that talk about the same things', () => {
+  for (const description of [
+    'A field guide app where birdwatchers log sightings together and build a shared map.',
+    'We build a ransomware detector for small clinics.',
+    'A phishing awareness course that runs simulated campaigns for our staff.',
+    'A child safety app that helps parents block harmful content.',
+    '', '   ',
+  ]) assert.deepEqual(screenProject({ description }), { stop: false }, description);
+  assert.deepEqual(screenProject({}), { stop: false }, 'no text is never a stop');
+  assert.deepEqual(screenProject({ description: 42 }), { stop: false });
+});
+
+await t('the hook is a seam: a caller can hand it different rules and nothing else changes', () => {
+  const rules = [{ id: 'test-only', match: /\bkestrel\b/i, unless: null }];
+  assert.deepEqual(screenProject({ description: 'Kestrel' }, rules), { stop: true, rule: 'test-only' });
+  assert.deepEqual(screenProject({ description: 'Kestrel' }), { stop: false });
+});
+
+await t('screenedOut answers with the canvas copy and names no rule anywhere in the reply', () => {
+  assert.equal(screenedOut('A birdwatching map.'), null);
+  assert.equal(screenedOut(undefined), null);
+  const out = screenedOut('We will sell ransomware.');
+  assert.equal(out.status, 422);
+  assert.equal(out.message, STOP_MESSAGE);
+  assert.match(out.message, /Nothing has been set up/);
+  assert.deepEqual(out.details, { screened: true }, 'naming the rule would teach a caller how to reword around it');
+  assert.doesNotMatch(JSON.stringify(out), /malware/);
+});
+
+console.log('\nThe routes:');
+
+let lastCreateArgs = null;
+let detailRow = null;
+provisioning.getInstanceBySlug = async () => null;
+provisioning.getInstanceByDomain = async () => null;
+provisioning.getInstanceById = async () => detailRow;
+provisioning.createInstance = async (_db, args) => {
+  lastCreateArgs = args;
+  return { instance: { id: 41, owner_builder_id: 7, slug: args.slug, status: 'requested', hosting_shape: 'byo-host',
+    description: args.description || null, detail: provisioning.normalizeProjectDetail(args.detail) }, created: true };
+};
+provisioning.enqueueIntent = async (_db, id, action) => ({ intent: { id: 9, action, state: 'pending' }, created: true });
+provisioning.getOpenIntent = async () => null;
+provisioning.recordEvent = async () => {};
+// Mirrors the real statement: merge the set answers, drop the un-answered keys.
+provisioning.updateInstanceDetail = async (_db, _id, patch) => {
+  const row = { ...detailRow };
+  if (patch.description !== undefined) row.description = patch.description;
+  if (patch.detail !== undefined) {
+    const { set, clear } = provisioning.projectDetailPatch(patch.detail);
+    row.detail = { ...(detailRow.detail || {}), ...set };
+    for (const key of clear) delete row.detail[key];
+  }
+  detailRow = row;
+  return row;
+};
+
+const api = require('../src/module-api.js');
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
+
+const express = require('express');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, ...(details || (typeof opts === 'object' ? opts : {})) } });
+  };
+  next();
+});
+app.use('/api/bongos', provisioningRoutes());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function send(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method, headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+await t('POST /instances carries all seven answers to storage and reads them back on the project', async () => {
+  lastCreateArgs = null;
+  const res = await send('POST', '/provisioning/instances', {
+    slug: 'kestrel', hosting_shape: 'byo-host', description: 'An inventory tool our team started last year.', detail: KESTREL,
+  });
+  assert.equal(res.status, 201, res.raw);
+  assert.deepEqual(lastCreateArgs.detail, KESTREL, 'the answers reached createInstance');
+  assert.deepEqual(res.body.instance.detail, provisioning.normalizeProjectDetail(KESTREL), 'and read back on the project');
+  assert.equal(res.body.instance.soft_limits.enforced, false, 'with the soft limits beside them');
+});
+
+await t('POST /instances refuses an unknown answer with a 400 and creates nothing', async () => {
+  lastCreateArgs = null;
+  const res = await send('POST', '/provisioning/instances', { slug: 'kestrel', hosting_shape: 'byo-host', detail: { framing: 'e' } });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_detail');
+  assert.equal(lastCreateArgs, null);
+});
+
+await t('POST /instances: a screened description STOPS creation — 422, nothing created, no intent queued', async () => {
+  lastCreateArgs = null;
+  let queued = false;
+  const enqueue = provisioning.enqueueIntent;
+  provisioning.enqueueIntent = async (...a) => { queued = true; return enqueue(...a); };
+  const res = await send('POST', '/provisioning/instances', {
+    slug: 'kestrel', hosting_shape: 'byo-host', description: 'Build ransomware and sell it on forums.', detail: KESTREL,
+  });
+  provisioning.enqueueIntent = enqueue;
+  assert.equal(res.status, 422, res.raw);
+  assert.equal(res.body.error.code, 'screened_out');
+  assert.equal(res.body.error.message, STOP_MESSAGE);
+  assert.deepEqual(res.body.error.details, { screened: true }, 'the reply names no rule');
+  assert.equal(lastCreateArgs, null, 'createInstance never ran');
+  assert.equal(queued, false, 'and no provision intent exists');
+});
+
+await t('PATCH …/detail screens a new description too, so the stop cannot be walked around after creation', async () => {
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'kestrel', status: 'active', description: 'A map.', detail: {} };
+  const res = await send('PATCH', '/provisioning/instances/41/detail', { description: 'We will build a phishing kit.' });
+  assert.equal(res.status, 422, res.raw);
+  assert.equal(res.body.error.code, 'screened_out');
+  assert.equal(detailRow.description, 'A map.', 'nothing was written');
+});
+
+await t('PATCH …/detail answers, re-reads, and un-answers with null — soft limits following the stored answers', async () => {
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'kestrel', status: 'active', detail: {} };
+  const set = await send('PATCH', '/provisioning/instances/41/detail', { detail: { entity: 'intent-solo', reward_intents: ['equity'] } });
+  assert.equal(set.status, 200, set.raw);
+  assert.deepEqual(set.body.detail, { entity: 'intent-solo', reward_intents: ['equity'] });
+  assert.ok(set.body.soft_limits.limits.some((l) => l.rule === 'equity-needs-a-company'));
+  const cleared = await send('PATCH', '/provisioning/instances/41/detail', { detail: { entity: null } });
+  assert.equal(cleared.status, 200, cleared.raw);
+  assert.deepEqual(cleared.body.detail, { reward_intents: ['equity'] }, 'the entity is un-answered, the rest kept');
+  assert.ok(!cleared.body.soft_limits.limits.some((l) => l.rule === 'equity-needs-a-company'), 'and its limit left with it');
+});
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);