@gigzen/populace 0.1.0 → 1.1.0

package/src/selftest.mjs

@@ -9,6 +9,9 @@
 // that the failures are CAUGHT, grouped, and reflected in the verdict.
 
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
 import { World } from "./engine/world.mjs";
 import { Agent } from "./engine/agent.mjs";
@@ -25,6 +28,10 @@ import {
 import { buildReport, renderReport } from "./report.mjs";
 import { canSignInOnly, CONTRACT_METHODS, coverageOf, isStub } from "./contract.mjs";
 import { diagnose } from "./diagnose.mjs";
+import { fill, match } from "./openapi.mjs";
+import { explain, explainReport, verdictLine } from "./explain.mjs";
+import { explainWithAI, isConfigured } from "./ai.mjs";
+import { checksDisabled, compare, latestVersion } from "./update.mjs";
 
 let failed = 0;
 const pending = [];
@@ -1355,10 +1362,326 @@ check("the report renders without throwing", () => {
   });
 }
 
+// --- 9. the OpenAPI adapter generator -------------------------------------
+//
+// The generator is a guess by design, so what has to hold is not "it is always
+// right" but "it never produces something broken that looks finished".
+
+const SPEC = {
+  openapi: "3.0.0",
+  paths: {
+    "/auth/signup": { post: { operationId: "registerUser", summary: "Register a new account" } },
+    "/auth/login": { post: { operationId: "login", summary: "Sign in" } },
+    "/auth/token/refresh": { post: { operationId: "refreshToken", summary: "Refresh the access token" } },
+    "/users/me": {
+      patch: { operationId: "updateProfile", summary: "Update profile" },
+      delete: { operationId: "deleteAccount", summary: "Delete account" },
+    },
+    "/locations": { post: { operationId: "reportPosition", summary: "Report current position" } },
+    "/posts": {
+      get: { operationId: "listFeed", summary: "Recent posts timeline" },
+      post: { operationId: "createPost", summary: "Create a post" },
+    },
+    "/posts/{postId}/likes": { post: { operationId: "likePost", summary: "Like a post" } },
+    "/posts/{postId}/comments": { post: { operationId: "addComment", summary: "Reply to a post" } },
+    "/conversations": { post: { operationId: "startConversation", summary: "Start a direct message thread" } },
+    "/conversations/{id}/messages": { post: { operationId: "sendMessage", summary: "Send a message" } },
+    "/groups": { get: { operationId: "listGroups", summary: "List groups" } },
+    "/groups/{id}/members": { post: { operationId: "joinGroup", summary: "Join a group" } },
+  },
+};
+
+check("the generator matches a conventional REST spec", () => {
+  const { results } = match(SPEC);
+  const expected = {
+    createUser: "POST /auth/signup",
+    refreshSession: "POST /auth/token/refresh",
+    setProfile: "PATCH /users/me",
+    deleteUser: "DELETE /users/me",
+    reportLocation: "POST /locations",
+    post: "POST /posts",
+    recentPostsByOthers: "GET /posts",
+    like: "POST /posts/{postId}/likes",
+    comment: "POST /posts/{postId}/comments",
+    openConversation: "POST /conversations",
+    sendMessage: "POST /conversations/{id}/messages",
+    listGroups: "GET /groups",
+    joinGroup: "POST /groups/{id}/members",
+  };
+  for (const [method, want] of Object.entries(expected)) {
+    const r = results[method];
+    const got = r.op ? `${r.op.verb.toUpperCase()} ${r.op.path}` : "no match";
+    if (got !== want) throw new Error(`${method}: matched ${got}, expected ${want}`);
+  }
+});
+
+check("a summary's own words never exclude the right endpoint", () => {
+  // POST /conversations is described as "start a direct message thread". An
+  // earlier version checked the `avoid` list against the summary as well as the
+  // path, so the word "message" rejected the one correct answer.
+  const { results } = match(SPEC);
+  if (results.openConversation.op?.path !== "/conversations") {
+    throw new Error("openConversation was excluded by a word in its own description");
+  }
+  // And sendMessage lives UNDER conversations, so "conversation" cannot exclude it.
+  if (results.sendMessage.op?.path !== "/conversations/{id}/messages") {
+    throw new Error("sendMessage was excluded by its parent resource's name");
+  }
+});
+
+check("a generated adapter never leaves a literal {param} in a call", () => {
+  // A path written in as a literal string would make the adapter request
+  // "/posts/{postId}/likes" verbatim: broken, and looking finished.
+  const template = fs.readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "adapters", "template-rest.mjs"),
+    "utf8",
+  );
+  const { source } = fill(template, match(SPEC).results);
+  const leftovers = source.match(/call\("[A-Z]+", "[^"]*\{[a-zA-Z_]+\}/g);
+  if (leftovers) throw new Error(`unfilled path parameters: ${leftovers.join(", ")}`);
+  if (!source.includes("`/posts/${postId}/likes`")) {
+    throw new Error("the path parameter was not turned into a template literal");
+  }
+});
+
+check("a spec with nothing recognisable produces no false matches", () => {
+  const { results } = match({ paths: { "/health": { get: { operationId: "health" } } } });
+  const matched = Object.values(results).filter((r) => r.op).length;
+  if (matched > 0) throw new Error(`${matched} method(s) matched a spec containing only /health`);
+});
+
+// --- 10. failure explanation ----------------------------------------------
+//
+// The judgement that matters is the first one: was this the application at all?
+// Getting that wrong in either direction is worse than saying nothing.
+
+check("a transport failure is never blamed on the application", () => {
+  for (const msg of ["TypeError: fetch failed", "socket hang up", "ECONNRESET", "UND_ERR_CONNECT_TIMEOUT"]) {
+    const e = explain(msg);
+    if (e.blame !== "harness") throw new Error(`"${msg}" was blamed on ${e.blame}, not the harness`);
+  }
+});
+
+check("a provider quota is not the app's fault", () => {
+  const e = explain("Invalid login credentials (signup first failed: Request rate limit reached)");
+  if (e.blame !== "environment") throw new Error(`rate limit blamed on ${e.blame}`);
+});
+
+check("permission and constraint failures are the app's", () => {
+  for (const [msg, rule] of [
+    ["permission denied for table profiles", "rls-denied"],
+    ["duplicate key value violates unique constraint \"post_likes_pkey\"", "duplicate-key"],
+    ["insert violates foreign key constraint", "foreign-key"],
+  ]) {
+    const e = explain(msg);
+    if (e.blame !== "app") throw new Error(`"${msg}" blamed on ${e.blame}`);
+    if (e.rule !== rule) throw new Error(`"${msg}" matched ${e.rule}, expected ${rule}`);
+  }
+});
+
+check("the upsert-under-RLS bug gets its own explanation", () => {
+  // The specific mistake behind five of the first defects Populace ever found.
+  // Plain "permission denied" is true but useless; this names the cause.
+  const e = explain("permission denied for table profiles (upsert / ON CONFLICT DO UPDATE)");
+  if (e.rule !== "rls-upsert") throw new Error(`matched ${e.rule}, expected the upsert-specific rule`);
+  if (!/cannot upsert a column you cannot select/i.test(e.fix)) {
+    throw new Error("the fix does not state the actual rule");
+  }
+});
+
+check("an unrecognised failure says so rather than inventing a cause", () => {
+  const e = explain("Xyzzy plugh 42 frobnicated");
+  if (e.rule !== "none") throw new Error(`invented rule ${e.rule}`);
+  if (e.blame !== "unknown") throw new Error(`claimed blame "${e.blame}" for an unknown error`);
+});
+
+check("unclassified failures are never counted as 'not the app'", () => {
+  // The dangerous rounding: reporting "no application failures" when some
+  // failures were simply not understood turns "we cannot tell" into an
+  // all-clear.
+  const line = verdictLine([{ blame: "harness", count: 5 }, { blame: "unknown", count: 3 }]);
+  if (/^No application failures/.test(line)) {
+    throw new Error(`claimed a clean app while 3 failures were unclassified: "${line}"`);
+  }
+  if (!/could not be classified/.test(line)) throw new Error(`unclassified failures not mentioned: "${line}"`);
+});
+
+check("explanations are ordered by how much they happened", () => {
+  const ex = explainReport({
+    api: { methods: [
+      { method: "a", errors: [{ message: "fetch failed", count: 2 }] },
+      { method: "b", errors: [{ message: "fetch failed", count: 90 }] },
+    ] },
+  });
+  if (ex[0].method !== "b") throw new Error("the 90-count failure was not listed first");
+});
+
+// --- 11. the model layer is an enhancement, never a dependency ------------
+//
+// A report is complete and useful without it. Everything here is about the
+// model layer being unable to make things worse.
+
+check("without a key, the model layer returns nothing and says nothing", async () => {
+  const before = process.env.ANTHROPIC_API_KEY;
+  delete process.env.ANTHROPIC_API_KEY;
+  try {
+    if (isConfigured({})) throw new Error("reported configured with no key anywhere");
+    const out = await explainWithAI([{ method: "post", message: "something odd", count: 1 }], { config: {} });
+    if (out.length) throw new Error("returned explanations without a key");
+  } finally {
+    if (before !== undefined) process.env.ANTHROPIC_API_KEY = before;
+  }
+});
+
+check("nothing to explain means no request is made", async () => {
+  // Guards against a run with zero failures still costing an API call.
+  const out = await explainWithAI([], { config: { ai: { apiKey: "sk-ant-would-be-wrong-to-use" } } });
+  if (out.length) throw new Error("returned explanations for an empty list");
+});
+
+check("a key in config is found as well as one in the environment", () => {
+  const before = process.env.ANTHROPIC_API_KEY;
+  delete process.env.ANTHROPIC_API_KEY;
+  try {
+    if (!isConfigured({ ai: { apiKey: "sk-ant-test" } })) {
+      throw new Error("a key in populace.config.mjs was not found");
+    }
+  } finally {
+    if (before !== undefined) process.env.ANTHROPIC_API_KEY = before;
+  }
+});
+
+check("rule explanations are never labelled as coming from the model", () => {
+  // The provenance has to survive, or a reader cannot tell which explanations
+  // were deterministic and which were generated.
+  const e = explain("permission denied for table profiles");
+  if (e.source === "model") throw new Error("a rule explanation claimed to be from the model");
+  if (e.rule === "model") throw new Error("a rule explanation used the model's rule name");
+});
+
+// --- 12. the update check ------------------------------------------------
+
+check("version comparison orders releases correctly", () => {
+  const cases = [
+    ["1.0.0", "1.0.0", 0], ["1.0.1", "1.0.0", 1], ["1.0.0", "1.0.1", -1],
+    ["1.10.0", "1.9.0", 1], ["2.0.0", "1.99.99", 1], ["1.0.0", "0.1.0", 1],
+    ["1.0.0-beta.1", "1.0.0", 0],   // pre-release tags are ignored, not parsed
+  ];
+  for (const [a, b, want] of cases) {
+    const got = compare(a, b);
+    if (got !== want) throw new Error(`compare("${a}","${b}") = ${got}, expected ${want}`);
+  }
+});
+
+check("10.0.0 is newer than 9.0.0, not older", () => {
+  // String comparison would say "10" < "9". Numeric parsing is the whole point.
+  if (compare("10.0.0", "9.0.0") !== 1) throw new Error("compared version parts as strings");
+});
+
+check("CI switches the update check off without being asked", async () => {
+  // A build server should not make an outbound call nobody requested, and its
+  // logs should not carry an upgrade nag.
+  const beforeCI = process.env.CI;
+  process.env.CI = "true";
+  try {
+    if (!checksDisabled()) throw new Error("update checks stayed on under CI");
+    const v = await latestVersion();
+    if (v !== null) throw new Error("a request was made under CI");
+  } finally {
+    if (beforeCI === undefined) delete process.env.CI; else process.env.CI = beforeCI;
+  }
+});
+
+check("POPULACE_NO_UPDATE_CHECK switches it off", () => {
+  const before = process.env.POPULACE_NO_UPDATE_CHECK;
+  const beforeCI = process.env.CI;
+  delete process.env.CI;
+  process.env.POPULACE_NO_UPDATE_CHECK = "1";
+  try {
+    if (!checksDisabled()) throw new Error("the opt-out was ignored");
+  } finally {
+    if (before === undefined) delete process.env.POPULACE_NO_UPDATE_CHECK;
+    else process.env.POPULACE_NO_UPDATE_CHECK = before;
+    if (beforeCI !== undefined) process.env.CI = beforeCI;
+  }
+});
+
 // Async checks must settle before the total is printed. Exiting synchronously
 // would report "all passed" while an async assertion was still in flight — a
 // test suite lying about its own result, in a product whose entire argument is
 // that a report must never claim more than it has earned.
+// --- sign-up pacing and throttling -----------------------------------------
+// A rate limit is the target pacing us; a real error is a finding. Waiting out
+// the first is honest and waiting out the second would hide a defect, so the two
+// must never be treated alike. Added 2026-08-24 after a 250-person run lost 215
+// people to a limit that said nothing about the app under test.
+{
+  const persona = () => ({
+    name: "Test Person",
+    city: { name: "Manila", country: "PH", lat: 14.6, lng: 121 },
+    platform: "grab", rhythm: {}, engagement: 1,
+  });
+  const stub = (fail) => ({
+    createUser: fail,
+    async setProfile() {}, async refreshSession() {}, async reportLocation() {},
+    async post() {}, async recentPostsByOthers() { return []; }, async like() {},
+    async comment() {}, async openConversation() { return { id: "c" }; },
+    async sendMessage() {}, async listGroups() { return []; }, async joinGroup() {},
+    async deleteUser() {},
+  });
+  const throttling = (times) => {
+    let n = 0;
+    return stub(async () => {
+      if (n++ < times) throw new Error("Request rate limit reached");
+      return { id: "u" + n, token: "t" };
+    });
+  };
+  const world = (adapter, options, on = {}) =>
+    new World({ adapter, personas: [persona()], options, on });
+  const pacing = { signupRateLimitBackoffMs: 10, signupRateLimitRetries: 2, signupStaggerMs: 0 };
+
+  const recovered = world(throttling(2), pacing);
+  const attempts = [];
+  recovered.on.joinThrottled = (_p, a) => attempts.push(a);
+  await recovered.populate();
+  check("a sign-up refused for being too fast is retried, not counted as a failure", () => {
+    assert.equal(recovered.agents.length, 1, "the person should end up signed in");
+    assert.equal(recovered.signupFailures.length, 0, "a rate limit is not a finding");
+    assert.deepEqual(attempts, [1, 2], "each wait should be announced, not silent");
+  });
+
+  const exhausted = world(throttling(99), pacing);
+  await exhausted.populate();
+  check("a rate limit that never lets up is recorded with its cause intact", () => {
+    assert.equal(exhausted.agents.length, 0);
+    assert.equal(exhausted.signupFailures[0].throttled, true,
+      "the report must be able to tell throttling from a broken API");
+  });
+
+  let realErrorCalls = 0;
+  const genuine = world(stub(async () => {
+    realErrorCalls += 1;
+    throw new Error("duplicate key violates unique constraint");
+  }), pacing);
+  await genuine.populate();
+  check("a genuine sign-up error is never retried or waited out", () => {
+    assert.equal(realErrorCalls, 1, "retrying a finding would hide it");
+    assert.equal(genuine.signupFailures[0].throttled, false);
+  });
+
+  const paced = new World({
+    adapter: throttling(0), personas: [persona(), persona(), persona()],
+    options: { signupStaggerMs: 120 }, on: {},
+  });
+  const startedAt = Date.now();
+  await paced.populate();
+  const elapsed = Date.now() - startedAt;
+  check("signupStaggerMs actually paces sign-ups", () => {
+    assert.ok(elapsed >= 240,
+      `three people at 120ms apart should take at least 240ms, took ${elapsed}ms`);
+  });
+}
+
 await Promise.all(pending);
 
 console.log(

package/src/update.mjs

@@ -0,0 +1,141 @@
+// Is there a newer Populace than the one running?
+//
+// A version check phones home, and a testing tool that quietly makes network
+// calls you did not ask for has no business asking you to trust it with your
+// staging credentials. So this one is:
+//
+//   · explicit          `populace update` asks; a run mentions it at most once
+//                       a day, after the report, never before
+//   · off with one flag POPULACE_NO_UPDATE_CHECK=1, and the CI environment
+//                       variable turns it off on its own
+//   · silent on failure no registry, no network, a firewall — nothing is said,
+//                       because a version check is never worth an error message
+//   · anonymous         a plain GET to the public registry. No identifiers, no
+//                       telemetry, nothing about your app or your runs
+//
+// Cached in the system temp directory for a day so twenty runs make one request.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PACKAGE_NAME, VERSION } from "./version.mjs";
+
+const REGISTRY = "https://registry.npmjs.org";
+const CACHE = path.join(os.tmpdir(), "populace-update-check.json");
+const DAY = 24 * 60 * 60 * 1000;
+
+/** Off in CI, and off whenever anyone says so. */
+export function checksDisabled() {
+  return Boolean(process.env.POPULACE_NO_UPDATE_CHECK || process.env.CI);
+}
+
+/** -1 a is older, 0 same, 1 a is newer. Plain semver; pre-release tags ignored. */
+export function compare(a, b) {
+  const parts = (v) => String(v).split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < 3; i++) {
+    if ((x[i] || 0) > (y[i] || 0)) return 1;
+    if ((x[i] || 0) < (y[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+function readCache() {
+  try {
+    const c = JSON.parse(fs.readFileSync(CACHE, "utf8"));
+    return Date.now() - c.at < DAY ? c : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(latest) {
+  try {
+    fs.writeFileSync(CACHE, JSON.stringify({ at: Date.now(), latest }));
+  } catch {
+    // A read-only temp directory is not a reason to fail anything.
+  }
+}
+
+/**
+ * The newest published version, or null.
+ *
+ * Never throws and never waits long: this runs after a report a person is
+ * already reading, and a version check that delays it has cost more than it
+ * is worth.
+ */
+export async function latestVersion({ timeoutMs = 3000, useCache = true } = {}) {
+  if (checksDisabled()) return null;
+  if (useCache) {
+    const cached = readCache();
+    if (cached) return cached.latest;
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // No Accept header. The abbreviated-packument type
+    // (application/vnd.npm.install-v1+json) is valid on the full packument and
+    // returns 406 on /latest — which this swallowed as "could not reach the
+    // registry", hiding a bug behind a reassuring message.
+    const res = await fetch(`${REGISTRY}/${PACKAGE_NAME}/latest`, { signal: controller.signal });
+    if (!res.ok) return null;
+    const { version } = await res.json();
+    if (!version) return null;
+    writeCache(version);
+    return version;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** One line for the end of a report, or null when there is nothing to say. */
+export async function updateNotice(options) {
+  const latest = await latestVersion(options);
+  if (!latest || compare(latest, VERSION) !== 1) return null;
+  return `  A newer Populace is out: ${VERSION} → ${latest}   npm i -g ${PACKAGE_NAME}`;
+}
+
+/** `populace update` — the explicit check, which always says something. */
+export async function updateCommand() {
+  if (checksDisabled()) {
+    console.log(`
+  Update checks are switched off${process.env.CI ? " (CI is set)" : " (POPULACE_NO_UPDATE_CHECK is set)"}.
+  Running ${PACKAGE_NAME} ${VERSION}.
+`);
+    return;
+  }
+
+  console.log(`\n  Running ${PACKAGE_NAME} ${VERSION}. Asking the npm registry…`);
+  const latest = await latestVersion({ timeoutMs: 10000, useCache: false });
+
+  if (!latest) {
+    console.log(`
+  Could not reach the registry. That is all this means — nothing is wrong with
+  your install, and Populace never needs the network to run.
+`);
+    return;
+  }
+
+  const d = compare(latest, VERSION);
+  if (d === 1) {
+    console.log(`
+  ${VERSION} → ${latest} is available.
+
+    npm i -g ${PACKAGE_NAME}
+    npx ${PACKAGE_NAME}@latest run
+
+  Turn these checks off with POPULACE_NO_UPDATE_CHECK=1.
+`);
+  } else if (d === 0) {
+    console.log(`\n  Up to date.\n`);
+  } else {
+    // Running ahead of the registry: a local build, or a publish still pending.
+    console.log(`
+  You are running ${VERSION}; the registry has ${latest}. That means this is a
+  local or unpublished build, not that anything is wrong.
+`);
+  }
+}