@bongos/core 1.19.512 → 1.19.514

package/tests/visible_projects_feed.mjs

@@ -0,0 +1,320 @@
+// tests/visible_projects_feed.mjs — the VISIBLE-PROJECTS FEED (task 1002325, BV1.R06;
+// ADR 0182 D2a / D3).
+//
+// The feed is the in-repo lever the orbs page reads, and this file pins the three
+// things R06 changed about it:
+//
+//   1. WHO IS ON THE MAP. The predicate stops being `featured = true` and becomes
+//      `status = 'active' AND publishable` — the publish gate R16 (task 1002335)
+//      already published as SQL. Dark matter (no name, or no description) is excluded
+//      SERVER-SIDE, so it never reaches a client that could choose to draw it.
+//      `featured` keeps a job — it RANKS among rows already on the map (D3) — and
+//      loses the one it should never have had, gating presence at all.
+//   2. WHAT EACH ORB IS. Every row carries `state` (public|private|stealth) and `orb`
+//      (planet|star|black-hole), derived from ONE mapping so the feed, the Explore
+//      view (R07) and the static orbs site (R09) cannot each invent their own.
+//   3. WHAT A BLACK HOLE MAY SAY. Stealth exposes EXISTENCE, never IDENTITY (D2a), and
+//      the redaction is at the boundary because the orbs page is a static site outside
+//      this repo and could not be trusted to redact even in principle.
+//
+// The stealth assertions are the security spec: they assert ABSENT FIELDS, not absent
+// pixels, which is what R10 (task 1002329) then demonstrates live.
+//
+// DB-free: a recording fake pool for the SQL, and the REAL router driven with a fake
+// req/res for the route composition.
+//
+// Run:  node --test --test-reporter=tap tests/visible_projects_feed.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pi = require('../modules/platform-identity/platform-identity.js');
+const feed = require('../modules/platform-identity/projects-feed.js');
+const projectStats = require('../modules/platform-identity/project-stats.js');
+const projectsRoutes = require('../modules/platform-identity/routes/projects.js');
+
+// A recording fake pool: returns queued responses in order, records every call.
+function mockPool(responses = []) {
+  const calls = [];
+  let i = 0;
+  return {
+    calls,
+    query: async (text, params) => {
+      calls.push({ text: String(text), params: params || [] });
+      return responses[i++] || { rows: [], rowCount: 0 };
+    },
+  };
+}
+
+// ── the mapping: one state, one orb (ADR 0182 D1) ────────────────────────────
+
+test('orbForState maps each stored state to the orb ADR 0182 D1 names for it', () => {
+  // Arrange / Act / Assert — the mapping IS the assertion, and the criterion
+  // (`proj-visibility-states`) locks these three words.
+  assert.equal(feed.orbForState('public'), 'planet');
+  assert.equal(feed.orbForState('private'), 'star');
+  assert.equal(feed.orbForState('stealth'), 'black-hole');
+});
+
+test('the orb mapping is reached through the module surface, so no caller keeps a copy', () => {
+  // R07 (Explore) and R09 (the static orbs site) both render these; a second copy of
+  // the mapping is how two surfaces end up drawing one project two ways.
+  assert.equal(pi.orbForState, feed.orbForState);
+  assert.deepEqual({ ...pi.ORB_BY_STATE }, { public: 'planet', private: 'star', stealth: 'black-hole' });
+  assert.ok(Object.isFrozen(pi.ORB_BY_STATE), 'a caller must not be able to re-map an orb at runtime');
+});
+
+test('an unrecognised state falls back to the ANONYMOUS orb, never the identified one', () => {
+  // Fail-closed, because this mapping is a privacy boundary. A fourth enum value added
+  // later and not mapped here would otherwise ship its project's name as a planet; the
+  // safe degradation is to draw it as a black hole and say nothing about it.
+  assert.equal(feed.orbForState('members-only'), 'black-hole');
+  assert.equal(feed.orbForState(undefined), 'black-hole');
+  assert.equal(feed.orbForState(null), 'black-hole');
+  assert.equal(feed.orbForState(''), 'black-hole');
+});
+
+// ── the wire shape: identified for two states, anonymous for the third ───────
+
+const PUBLIC_ROW = Object.freeze({
+  origin: 'https://mercury.example', name: 'Mercury', tagline: 'A weather sim.',
+  art_url: 'https://mercury.example/art.png', type: 'game', template: 'blob-tint',
+  created_at: '2026-08-01T00:00:00Z', visibility: 'public',
+});
+
+test('feedShapeFor keeps a public project fully identified and marks it a planet', () => {
+  // Arrange
+  const row = { ...PUBLIC_ROW };
+
+  // Act
+  const wire = feed.feedShapeFor(row);
+
+  // Assert
+  assert.equal(wire.state, 'public');
+  assert.equal(wire.orb, 'planet');
+  assert.equal(wire.name, 'Mercury');
+  assert.equal(wire.origin, 'https://mercury.example');
+  assert.equal(wire.tagline, 'A weather sim.');
+  assert.equal(wire.art_url, 'https://mercury.example/art.png');
+  assert.equal(wire.created_at, '2026-08-01T00:00:00Z');
+  assert.ok(!('visibility' in wire), 'the stored column is spent deriving `state`; it never doubles it on the wire');
+});
+
+test('a private project stays IDENTIFIED — a star is visible, only its door is closed', () => {
+  // ADR 0182 D2, inherited unchanged from ADR 0112's private goals: private means
+  // visible-but-closed. Redacting a star would be the bug, not the safe choice.
+  const wire = feed.feedShapeFor({ ...PUBLIC_ROW, visibility: 'private' });
+  assert.equal(wire.state, 'private');
+  assert.equal(wire.orb, 'star');
+  assert.equal(wire.name, 'Mercury');
+  assert.equal(wire.origin, 'https://mercury.example');
+});
+
+test('a stealth project ships NO identifying field — every one of them is null', () => {
+  // Arrange — a fully populated row, so nothing is absent by accident.
+  const row = { ...PUBLIC_ROW, visibility: 'stealth' };
+
+  // Act
+  const wire = feed.feedShapeFor(row);
+
+  // Assert — ADR 0182 D2a names these four explicitly as fields that must not leave
+  // the server. Asserted BY NAME so the ADR's own list is executable.
+  for (const field of ['origin', 'name', 'tagline', 'art_url']) {
+    assert.equal(wire[field], null, `D2a: a stealth project's ${field} must not leave the server`);
+  }
+  // …and the general rule the four are only examples of: existence, never identity.
+  for (const [key, value] of Object.entries(wire)) {
+    if (key === 'state' || key === 'orb') continue;
+    assert.equal(value, null, `a black hole says nothing but that it is there — ${key} leaked`);
+  }
+  assert.equal(wire.state, 'stealth');
+  assert.equal(wire.orb, 'black-hole');
+});
+
+test('the wire never DROPS a key for a stealth row — it nulls it', () => {
+  // The feed's standing contract (the NULL_STATS shape): a value that could not be
+  // answered is null, never absent, because JSON.stringify drops the absent one and a
+  // client reading `p.builders` would then see `undefined` on some rows and null on
+  // others. Redaction must not become the one exception to that.
+  const wire = feed.feedShapeFor({ ...PUBLIC_ROW, visibility: 'stealth' });
+  for (const key of Object.keys(PUBLIC_ROW)) {
+    if (key === 'visibility') continue;
+    assert.ok(key in wire, `${key} must still be a KEY on the wire, carrying null`);
+  }
+});
+
+test('a field the redactor has never seen is anonymous by DEFAULT, not by being listed', () => {
+  // The property that keeps this correct as the feed grows: the stealth shape is an
+  // ALLOW-list of what may be said (state, orb), not a deny-list of what must be
+  // hidden. A column added to the feed next year is redacted without anyone
+  // remembering to add it here — which is the only version of this that stays true.
+  const wire = feed.feedShapeFor({
+    ...PUBLIC_ROW, visibility: 'stealth', owner_avatar: 'https://x/a.png', faces: ['https://x/b.png'],
+    some_field_invented_after_this_test: 'leak',
+  });
+  assert.equal(wire.owner_avatar, null);
+  assert.deepEqual(wire.faces, null);
+  assert.equal(wire.some_field_invented_after_this_test, null);
+  assert.deepEqual(Object.keys(wire).filter((k) => wire[k] !== null).sort(), ['orb', 'state']);
+});
+
+test('a black hole carries no stable key that yesterday\'s feed could be diffed against', () => {
+  // Deliberate: any per-project identifier that survives a state change (a row id, a
+  // slug, a hash of the origin) lets an observer who kept yesterday's public feed name
+  // the project that went stealth today. Black holes are interchangeable on purpose.
+  const a = feed.feedShapeFor({ ...PUBLIC_ROW, id: '7', visibility: 'stealth' });
+  const b = feed.feedShapeFor({ ...PUBLIC_ROW, id: '9', origin: 'https://venus.example', visibility: 'stealth' });
+  assert.deepEqual(a, b, 'two stealth projects must be indistinguishable on the wire');
+  assert.equal(a.id, null);
+});
+
+// ── who is on the map: the predicate (ADR 0182 D3) ───────────────────────────
+
+test('listPublicProjects excludes dark matter using the SHARED publish gate, not a copy', async () => {
+  // Arrange
+  const pool = mockPool([{ rows: [] }]);
+
+  // Act
+  await pi.listPublicProjects({ pool });
+
+  // Assert
+  const sql = pool.calls[0].text;
+  assert.ok(sql.includes(pi.publishableSql()),
+    'the gate rides in the WHERE, from the one SQL definition R16 published for this feed');
+  assert.match(sql, /status = 'active'/, 'a deprovisioned project is off the map too (D3)');
+});
+
+test('featuring no longer GATES presence — it only ranks among projects already on the map', async () => {
+  // ADR 0182 D3, and the behaviour change the whole goal turns on: an owner who sets
+  // their project public used to see nothing happen until an Archon featured them.
+  const pool = mockPool([{ rows: [] }]);
+  await pi.listPublicProjects({ pool });
+  const sql = pool.calls[0].text;
+  const where = (sql.match(/WHERE([\s\S]*?)ORDER BY/i) || [, ''])[1];
+  assert.doesNotMatch(where, /featured/, 'featured must not appear in the predicate at all');
+  assert.match(sql, /ORDER BY featured DESC/, 'it keeps the job D3 leaves it: ranking');
+});
+
+test('the public feed is CAPPED — the swap to self-service removed the human bound on its size', async () => {
+  // Until R06 the listing was bounded by an Archon choosing to feature a project. Making
+  // it `publishable` replaced that bound with self-service, on a route that is public,
+  // CORS-open, unauthenticated AND fans out one outbound stats fetch per row. The cap is
+  // the cheap half of that trade; pagination is its own task.
+  const pool = mockPool([{ rows: [] }]);
+  await pi.listPublicProjects({ pool });
+  assert.match(pool.calls[0].text, new RegExp(`LIMIT ${feed.PUBLIC_FEED_MAX_PROJECTS}\\b`));
+  assert.equal(Number.isInteger(feed.PUBLIC_FEED_MAX_PROJECTS), true,
+    'the cap is interpolated into SQL, so it must be a literal integer and never a caller value');
+  assert.ok(feed.PUBLIC_FEED_MAX_PROJECTS > 0);
+});
+
+test('listPublicProjects projects `visibility`, the column the orb is derived from', async () => {
+  // Without it every row would fall to the anonymous default and the whole map would
+  // go dark — silently, and in the safe direction, which is exactly why it needs a test.
+  const pool = mockPool([{ rows: [] }]);
+  await pi.listPublicProjects({ pool });
+  const sel = (pool.calls[0].text.match(/SELECT([\s\S]*?)FROM/i) || [, ''])[1];
+  assert.match(sel, /\bvisibility\b/);
+});
+
+test('listPublicProjects stays a PUBLIC projection — no owner, no status, no bookkeeping', async () => {
+  // Inherited from the feed this replaced, and re-asserted rather than assumed: the
+  // route is rank:public and CORS-open, so SELECT * must never sneak in behind it.
+  const pool = mockPool([{ rows: [] }]);
+  await pi.listPublicProjects({ pool });
+  const sql = pool.calls[0].text;
+  const sel = (sql.match(/SELECT([\s\S]*?)FROM/i) || [, ''])[1];
+  assert.ok(sel.trim(), 'the projection is an explicit SELECT list');
+  assert.doesNotMatch(sel, /\*/, 'no star projection on a public route');
+  assert.doesNotMatch(sel, /owner_github_id/, 'public projection must not leak owner id');
+  assert.doesNotMatch(sel, /updated_at/, 'curation noise — it may sort, it may never project');
+  assert.doesNotMatch(sel, /\bdescription\b/,
+    'description is the publish BAR, not a card field — it is spent in the predicate');
+  assert.match(sel, /created_at/, 'the LISTED date stays public');
+  assert.match(sel, /\btype\b/, 'the declared type stays public (task 1002772)');
+});
+
+// ── the route: the composition, executed ─────────────────────────────────────
+
+// The real router, driven with a fake req/res. `pi.listPublicProjects` and the stats
+// enrichment are stubbed so the test needs neither Postgres nor the network — what is
+// under test is the ROUTE's composition, not either dependency.
+async function callFeaturedFeed(rows) {
+  const router = projectsRoutes();
+  const layer = router.stack.find((l) => l.route && l.route.path === '/projects/featured'
+    && l.route.methods.get);
+  assert.ok(layer, 'GET /projects/featured must still be a route on this router');
+
+  const askedFor = [];
+  const savedList = pi.listPublicProjects;
+  const savedStats = projectStats.getProjectStats;
+  pi.listPublicProjects = async () => rows;
+  projectStats.getProjectStats = async (origins) => { askedFor.push(...origins); return {}; };
+  try {
+    let body = null;
+    const res = {
+      json: (b) => { body = b; },
+      fail: (code, detail) => { throw new Error(`route failed: ${code} ${JSON.stringify(detail)}`); },
+    };
+    await layer.route.stack[0].handle({}, res, () => {});
+    return { body, askedFor };
+  } finally {
+    pi.listPublicProjects = savedList;
+    projectStats.getProjectStats = savedStats;
+  }
+}
+
+test('the feed renders all three visible states, each with its orb', async () => {
+  // Arrange
+  const rows = [
+    { ...PUBLIC_ROW, visibility: 'public' },
+    { ...PUBLIC_ROW, origin: 'https://venus.example', name: 'Venus', visibility: 'private' },
+    { ...PUBLIC_ROW, origin: 'https://pluto.example', name: 'Pluto', visibility: 'stealth' },
+  ];
+
+  // Act
+  const { body } = await callFeaturedFeed(rows);
+
+  // Assert
+  assert.equal(body.projects.length, 3);
+  assert.deepEqual(body.projects.map((p) => p.state), ['public', 'private', 'stealth']);
+  assert.deepEqual(body.projects.map((p) => p.orb), ['planet', 'star', 'black-hole']);
+  assert.equal(body.projects[0].name, 'Mercury');
+  assert.equal(body.projects[1].name, 'Venus');
+});
+
+test('the stealth row leaves the ROUTE anonymous — redaction survives the enrichment', async () => {
+  // The one that matters: the route spreads stats, planet choices and a scheme-checked
+  // art_url onto each row AFTER the domain read, so a redaction applied any earlier
+  // would be silently undone here.
+  const { body } = await callFeaturedFeed([{ ...PUBLIC_ROW, visibility: 'stealth' }]);
+  const wire = body.projects[0];
+  for (const field of ['origin', 'name', 'tagline', 'art_url']) {
+    assert.equal(wire[field], null, `D2a: ${field} must not leave the server`);
+  }
+  const said = Object.keys(wire).filter((k) => wire[k] !== null);
+  assert.deepEqual(said.sort(), ['orb', 'state']);
+  assert.ok(Object.keys(wire).length > 5, 'and it is a full-width row, not a stub — no key was dropped');
+});
+
+test('a stealth project\'s own API is never asked about its builders', async () => {
+  // The enrichment reads each project's public leaderboard for builder counts, owner
+  // and up to five AVATARS. Handing a stealth origin to it would both leak identity
+  // onto the wire and tell that project it was being enumerated.
+  const { askedFor } = await callFeaturedFeed([
+    { ...PUBLIC_ROW, visibility: 'public' },
+    { ...PUBLIC_ROW, origin: 'https://pluto.example', visibility: 'stealth' },
+  ]);
+  assert.deepEqual(askedFor, ['https://mercury.example']);
+});
+
+test('dark matter never reaches the route at all — the exclusion is in SQL', async () => {
+  // Stated as a structural fact rather than a behaviour, because that IS the decision:
+  // a client-side filter would ship the husk to anyone who opened the network tab.
+  const src = require('node:fs').readFileSync(
+    new URL('../modules/platform-identity/projects-feed.js', import.meta.url), 'utf8');
+  const fn = (src.match(/async function listPublicProjects[\s\S]*?\n\}/) || [''])[0];
+  assert.ok(fn.includes('publishableSql()'), 'the gate is applied in the query, not after it');
+});