@gigzen/populace 0.1.0 → 1.1.0

package/src/openapi.mjs

@@ -0,0 +1,322 @@
+// Turn an OpenAPI description into a filled-in adapter.
+//
+// Writing the adapter is the wall. Thirteen methods against someone else's API
+// is the half-hour where a new user either gets a run or gives up, and it is
+// the reason a tool that works has no users outside the company that wrote it.
+// Most serious APIs already describe themselves; this reads that description
+// and fills in what it can.
+//
+// It is deliberately a GUESS, and says so. Every match carries a confidence and
+// the evidence behind it, and anything it is unsure of is left as the template's
+// default with a TODO. A generator that quietly guessed wrong would be worse
+// than no generator: the run would fail and the adapter would look finished.
+//
+// JSON only. Populace has no runtime dependencies and a YAML parser would be
+// the first, for a convenience that `npx js-yaml` covers in one command.
+
+import fs from "node:fs";
+
+/**
+ * What each contract method looks like in a REST API, as scoring signals.
+ *
+ * `verb`  the HTTP method it almost certainly is
+ * `path`  words that appear in the URL, best first
+ * `words` words in the operationId, summary or tags
+ * `avoid` path fragments meaning this is a different endpoint in similar clothes.
+ *         Checked against the PATH ONLY. An earlier version also checked the
+ *         summary, which rejected `POST /conversations` because its description
+ *         read "start a direct message thread" — the correct answer, thrown out
+ *         by a word in its own prose.
+ */
+const SIGNALS = {
+  createUser: {
+    verb: "post",
+    path: ["signup", "sign-up", "admin/users", "register/", "auth/users", "users", "accounts"],
+    words: ["signup", "register", "create user", "create account"],
+    avoid: ["login", "signin", "sign-in", "refresh", "verify", "reset"],
+  },
+  refreshSession: {
+    verb: "post",
+    path: ["refresh", "token/refresh", "auth/token", "token"],
+    words: ["refresh", "renew token", "access token"],
+    avoid: ["revoke", "signup", "register"],
+  },
+  setProfile: {
+    verb: "patch",
+    path: ["profile", "me", "users", "account"],
+    words: ["update profile", "profile", "update user", "edit"],
+    avoid: ["password", "avatar", "delete", "settings/notification"],
+  },
+  deleteUser: {
+    verb: "delete",
+    path: ["users", "account", "me", "profile"],
+    words: ["delete account", "delete user", "remove user", "close account"],
+    avoid: ["post", "comment", "message", "group"],
+  },
+  reportLocation: {
+    verb: "post",
+    path: ["location", "locations", "position", "track", "ping", "telemetry", "gps"],
+    words: ["location", "position", "track", "heartbeat", "ping"],
+    avoid: [],
+  },
+  post: {
+    verb: "post",
+    path: ["posts", "feed", "statuses", "tweets", "entries"],
+    words: ["create post", "new post", "publish", "compose"],
+    avoid: ["comment", "like", "reply", "report"],
+  },
+  recentPostsByOthers: {
+    verb: "get",
+    path: ["feed", "posts", "timeline", "statuses", "entries"],
+    words: ["feed", "timeline", "list posts", "recent"],
+    avoid: ["comment", "like", "my", "mine", "draft"],
+  },
+  like: {
+    verb: "post",
+    path: ["like", "likes", "reactions", "favourite", "favorite", "upvote"],
+    words: ["like", "react", "favourite", "favorite", "upvote"],
+    avoid: ["unlike", "dislike", "remove"],
+  },
+  comment: {
+    verb: "post",
+    path: ["comments", "replies", "comment"],
+    words: ["comment", "reply"],
+    avoid: ["delete", "list", "edit"],
+  },
+  openConversation: {
+    verb: "post",
+    // "/dm" not "dm": as a bare substring it matches "admin", which is how
+    // openConversation ended up pointing at Gitea's POST /admin/cron/{task}.
+    path: ["conversations", "threads", "chats", "/dm", "/dms", "rooms"],
+    words: ["conversation", "thread", "start chat", "direct message", "room"],
+    avoid: ["/messages", "/send", "/read", "/typing"],
+  },
+  sendMessage: {
+    verb: "post",
+    path: ["messages", "message", "send"],
+    words: ["send message", "message", "post message"],
+    avoid: ["/read", "/typing", "/receipts"],
+  },
+  listGroups: {
+    verb: "get",
+    path: ["groups", "orgs", "organizations", "communities", "channels", "teams"],
+    words: ["list groups", "groups", "organizations", "communities", "channels"],
+    avoid: ["member", "join", "leave", "create"],
+  },
+  joinGroup: {
+    verb: "post",
+    path: ["join", "members", "membership", "subscribe"],
+    words: ["join group", "join", "add member", "subscribe"],
+    avoid: ["leave", "remove", "kick", "list"],
+  },
+};
+
+export const CONTRACT_METHODS = Object.keys(SIGNALS);
+
+/** Every operation in the document, flattened. */
+function operations(doc) {
+  const out = [];
+  for (const [path, item] of Object.entries(doc.paths || {})) {
+    if (!item || typeof item !== "object") continue;
+    for (const verb of ["get", "post", "put", "patch", "delete"]) {
+      const op = item[verb];
+      if (!op) continue;
+      out.push({
+        verb,
+        path,
+        operationId: op.operationId || "",
+        summary: op.summary || "",
+        description: (op.description || "").slice(0, 200),
+        tags: op.tags || [],
+      });
+    }
+  }
+  return out;
+}
+
+function score(op, sig) {
+  const path = op.path.toLowerCase();
+  const text = `${op.operationId} ${op.summary} ${op.tags.join(" ")}`.toLowerCase();
+  const why = [];
+  let n = 0;
+
+  for (const bad of sig.avoid) {
+    if (path.includes(bad)) return { n: -1, why: [`excluded: path contains "${bad}"`] };
+  }
+
+  // Path is the strongest signal, and earlier entries are better matches.
+  //
+  // Take the BEST match, never the sum. Summing rewarded long paths that happen
+  // to contain several keywords: against Gitea's real spec,
+  // /pulls/{index}/comments/{id}/replies scored both "comments" and "replies"
+  // and beat /issues/{index}/comments, which is the endpoint a person wants.
+  let bestWord = null;
+  sig.path.forEach((word, i) => {
+    if (!path.includes(word)) return;
+    const points = 10 - Math.min(i, 6);
+    if (!bestWord || points > bestWord.points) bestWord = { word, points };
+  });
+  if (bestWord) {
+    n += bestWord.points;
+    why.push(`path contains "${bestWord.word}"`);
+  }
+
+  if (op.verb === sig.verb) { n += 4; why.push(`${op.verb.toUpperCase()} matches`); }
+  // PUT and PATCH are used interchangeably for updates often enough to allow.
+  else if (sig.verb === "patch" && op.verb === "put") { n += 3; why.push("PUT accepted for PATCH"); }
+  else n -= 3;
+
+  for (const word of sig.words) {
+    if (text.includes(word)) { n += 3; why.push(`described as "${word}"`); }
+  }
+
+  // A shallow path is much likelier to be the main resource than a deep one.
+  // At -1 per segment this was too weak to stop a five-segment sub-resource
+  // outscoring the collection it hangs off.
+  n -= 2 * Math.max(0, op.path.split("/").filter(Boolean).length - 3);
+
+  // Did anything about the URL itself suggest this method? A verb alone must
+  // never be enough: with only that, every GET in a document matched
+  // recentPostsByOthers and listGroups, so a spec containing nothing but
+  // /health produced two confident-looking matches.
+  const hadPathSignal = why.some((w) => w.startsWith("path contains"));
+
+  return { n, why, hadPathSignal };
+}
+
+/**
+ * Match each contract method to its best operation.
+ *
+ * Confidence is deliberately coarse. Anything below `low` is reported as no
+ * match at all rather than dressed up, because a wrong path that looks
+ * confident costs more to debug than an obvious blank.
+ */
+export function match(doc) {
+  const ops = operations(doc);
+  const results = {};
+
+  for (const [method, sig] of Object.entries(SIGNALS)) {
+    let best = null;
+    for (const op of ops) {
+      const { n, why, hadPathSignal } = score(op, sig);
+      // A path signal is mandatory, not just helpful.
+      if (!hadPathSignal || n < 7) continue;
+      if (!best || n > best.n) best = { op, n, why };
+    }
+    const confidence = !best ? "none" : best.n >= 12 ? "high" : best.n >= 9 ? "medium" : "low";
+    results[method] = best && confidence !== "none"
+      ? { ...best, confidence }
+      : { op: null, n: 0, why: ["nothing in the spec looked like this"], confidence: "none" };
+  }
+  return { operationCount: ops.length, results };
+}
+
+/** Read a spec from disk, refusing YAML with a sentence rather than a stack trace. */
+export function load(specPath) {
+  const raw = fs.readFileSync(specPath, "utf8");
+  const looksYaml = /\.ya?ml$/i.test(specPath) || /^\s*(openapi|swagger)\s*:/m.test(raw);
+  if (looksYaml && !raw.trimStart().startsWith("{")) {
+    throw new Error(
+      `${specPath} looks like YAML. Populace has no runtime dependencies, so it does not ship a\n` +
+      `  YAML parser. Convert it once and point at the JSON:\n\n` +
+      `    npx js-yaml ${specPath} > openapi.json\n`,
+    );
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${specPath} is not valid JSON: ${error.message}`);
+  }
+  if (!doc.paths || typeof doc.paths !== "object") {
+    throw new Error(`${specPath} has no "paths" object, so it is not an OpenAPI description.`);
+  }
+  return doc;
+}
+
+/**
+ * Rewrite the REST template's call lines with the matched paths.
+ *
+ * The template is deliberately one `call(VERB, PATH, ...)` per method, so this
+ * is a targeted substitution rather than code generation. Everything the
+ * template already gets right — error handling, token plumbing, the refusal to
+ * return quietly on failure — is left exactly as it is.
+ */
+/**
+ * The identifier each method already has in scope, for filling path parameters.
+ *
+ * Without this, a matched path like /posts/{postId}/likes was written into the
+ * adapter as a literal string, and the adapter then requested that URL verbatim.
+ * Broken — but broken in a way that looks finished, which is the worst kind.
+ */
+const PATH_VAR = {
+  like: "postId",
+  comment: "postId",
+  sendMessage: "conversationId",
+  joinGroup: "groupId",
+  openConversation: "otherUserId",
+  setProfile: "user.id",
+  deleteUser: "user.id",
+  refreshSession: "user.id",
+};
+
+/** `/posts/{postId}/likes` → a template literal, or the raw string if we cannot fill it. */
+function pathExpression(rawPath, method) {
+  const params = [...rawPath.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+  if (!params.length) return { code: JSON.stringify(rawPath), unresolved: [] };
+
+  const variable = PATH_VAR[method];
+  if (!variable) return { code: JSON.stringify(rawPath), unresolved: params };
+
+  // One parameter is the common case and safe to fill. Two or more means a
+  // nested resource whose second id this method does not have in scope, so it
+  // is left visible rather than guessed at.
+  if (params.length > 1) return { code: JSON.stringify(rawPath), unresolved: params.slice(1) };
+
+  return { code: "`" + rawPath.replace(/\{[^}]+\}/, "${" + variable + "}") + "`", unresolved: [] };
+}
+
+export function fill(template, matches) {
+  let out = template;
+  const applied = [];
+  const needsHand = [];
+
+  for (const [method, m] of Object.entries(matches)) {
+    if (!m.op) continue;
+    const verb = m.op.verb.toUpperCase();
+    const { code, unresolved } = pathExpression(m.op.path, method);
+    if (unresolved.length) needsHand.push({ method, path: m.op.path, params: unresolved });
+
+    // Match: await call("POST", "/posts", ...) inside `async <method>(`
+    const block = new RegExp(
+      `(async ${method}\\s*\\([^)]*\\)\\s*\\{[\\s\\S]{0,400}?call\\()"[A-Z]+",\\s*"[^"]*"`,
+    );
+    if (!block.test(out)) continue;
+    out = out.replace(block, `$1"${verb}", ${code}`);
+    applied.push({ method, verb, path: m.op.path, confidence: m.confidence, unresolved });
+  }
+
+  // A header that tells the reader exactly how much to trust what follows.
+  const banner = [
+    "/**",
+    " * GENERATED from an OpenAPI description by `populace init --from-openapi`.",
+    " *",
+    " * The paths below are a best guess made by matching endpoint names against",
+    " * the thirteen contract methods. They are a starting point, not a finished",
+    " * adapter: request bodies, field names and response shapes are still the",
+    " * template's defaults and almost certainly need editing.",
+    " *",
+    " * Run `populace smoke` before anything else. It exercises each method once",
+    " * and names the first one that is wrong.",
+    ...(needsHand.length
+      ? ["  *",
+         "  * Paths still containing {braces} need filling by hand - this method has no",
+         "  * variable in scope for them:",
+         ...needsHand.map((h) => `  *   ${h.method}: ${h.path}`)]
+      : []),
+    " */",
+    "",
+  ].join("\n");
+
+  return { source: banner + out, applied, needsHand };
+}

package/src/progress.mjs

@@ -0,0 +1,141 @@
+// A machine-readable view of a run, for anything watching it happen.
+//
+// The engine already knows everything anyone could want each tick - every
+// person's city, platform, distance, activity and position, and the latency of
+// every method. In a terminal it draws all of that as a table. Piped anywhere
+// else it deliberately drops to a heartbeat every fifth of the run, because a
+// full table written into a CI log would bury the report under thousands of
+// screens of scrollback.
+//
+// That is right for CI and wrong for a window. Populace Studio spawns the CLI
+// with its output piped, so it received the CI version: at a one-second tick
+// over fifteen minutes, one update every three minutes. The application looked
+// frozen while a quarter of a million calls went through it.
+//
+// So the data was never missing - only the transport. This is the transport.
+//
+//   populace run --progress json
+//
+// Each line is `@@populace@@` followed by one JSON object. The prefix means a
+// reader can pick these out of ordinary output without ambiguity, and nothing
+// is emitted at all unless asked, so a human's terminal is unchanged.
+//
+// Percentiles are not computed every tick. summarise() sorts every recorded
+// duration, and at a quarter of a million calls that is real work to do once a
+// second for numbers nobody can read that fast.
+
+export const PROGRESS_PREFIX = "@@populace@@";
+
+/**
+ * Cheap per-method counters, straight off the metrics map - no sorting.
+ *
+ * The most common error message travels with them when there is one. A count
+ * of failures tells a watcher that something is wrong; only the message tells
+ * them what, and waiting for the report to find out is a long time to sit in
+ * front of a run that is already broken.
+ */
+function counters(metrics) {
+  return [...metrics.methods.values()].map((e) => {
+    const row = {
+      method: e.method,
+      calls: e.calls,
+      apiFailures: e.apiFailures,
+      transportFailures: e.transportFailures,
+      retries: e.retries,
+    };
+    if (e.failures && e.errors?.size) {
+      let top = null;
+      for (const [message, count] of e.errors) if (!top || count > top.count) top = { message, count };
+      if (top) row.error = { message: top.message.slice(0, 300), count: top.count };
+    }
+    return row;
+  });
+}
+
+/** p50 and p95 per method. Costs a sort per method, so it runs rarely. */
+function latencies(metrics) {
+  const out = {};
+  for (const e of metrics.methods.values()) {
+    if (!e.durations.length) continue;
+    const sorted = [...e.durations].sort((a, b) => a - b);
+    const at = (p) => sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))];
+    out[e.method] = { p50: Math.round(at(50)), p95: Math.round(at(95)) };
+  }
+  return out;
+}
+
+/**
+ * @param {object} options
+ * @param {boolean} options.enabled   emit anything at all
+ * @param {number}  options.everyLatency  ticks between percentile refreshes
+ * @param {(line: string) => void} options.write
+ */
+export function createProgress({ enabled, everyLatency = 5, write = (l) => process.stdout.write(l) } = {}) {
+  if (!enabled) return { start() {}, tick() {}, done() {} };
+
+  const emit = (event) => {
+    try {
+      write(`${PROGRESS_PREFIX}${JSON.stringify(event)}\n`);
+    } catch {
+      // A watcher that has gone away is not a reason to fail a run.
+    }
+  };
+
+  const startedAt = Date.now();
+
+  return {
+    start(config) {
+      emit({
+        type: "start",
+        app: config.app || "populace",
+        environment: config.environment,
+        agents: config.population.agents,
+        cities: config.population.cities,
+        minutes: config.population.minutes,
+        tickSeconds: config.population.tickSeconds,
+        engagement: config.population.engagement ?? 1,
+      });
+    },
+
+    tick(tickNo, totalTicks, world, metrics) {
+      const t = world.totals();
+      emit({
+        type: "tick",
+        tick: tickNo,
+        totalTicks,
+        elapsedMs: Date.now() - startedAt,
+        totals: {
+          km: Number(t.km.toFixed(2)),
+          posts: t.posts || 0,
+          likes: t.likes || 0,
+          comments: t.comments || 0,
+          messages: t.messages || 0,
+          groupJoins: t.groupJoins || 0,
+          errors: t.errors || 0,
+        },
+        // Short keys: this is written once a second with a row per person, and
+        // the field names would otherwise be most of the bytes.
+        people: world.agents.map((a) => ({
+          n: a.persona.name,
+          c: a.persona.city.name,
+          y: a.persona.city.country,
+          p: a.persona.platform,
+          k: Number(a.distanceKm.toFixed(1)),
+          o: a.stats.posts || 0,
+          l: a.stats.likes || 0,
+          m: a.stats.messages || 0,
+          e: a.stats.errors || 0,
+          b: Boolean(a.onBreak),
+          la: Number(a.position.lat.toFixed(3)),
+          lo: Number(a.position.lng.toFixed(3)),
+        })),
+        methods: counters(metrics),
+        latency: tickNo % everyLatency === 0 || tickNo === totalTicks ? latencies(metrics) : undefined,
+      });
+    },
+
+    done(report) {
+      emit({ type: "done", verdict: report?.verdict?.status || "unknown" });
+    },
+  };
+}

package/src/report.mjs

@@ -6,6 +6,7 @@
 // only shows successes is worse than no report — it manufactures confidence.
 
 import fs from "node:fs";
+import { explainReport, verdictLine } from "./explain.mjs";
 import path from "node:path";
 import { summarise } from "./instrument.mjs";
 import { coverageOf } from "./contract.mjs";
@@ -15,6 +16,22 @@ import { VERSION } from "./version.mjs";
 const pct = (n) => `${(n * 100).toFixed(1)}%`;
 const ms = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}s` : `${Math.round(n)}ms`);
 
+/** Break a sentence onto lines of at most `width`, without splitting words. */
+function wrap(text, width) {
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && line.length + 1 + word.length > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
 export function buildReport({ config, adapter, world, metrics, teardown, startedAt }) {
   const api = summarise(metrics);
   const coverage = coverageOf(adapter);
@@ -219,6 +236,26 @@ export function renderReport(report) {
   }
   L.push("");
 
+  // What broke, why, and the fix - the thing a report is actually for. Rules
+  // only; anything unrecognised says so rather than inventing a cause.
+  const explained = explainReport(report);
+  if (explained.length) {
+    L.push(`  WHAT TO DO`);
+    L.push(`    ${verdictLine(explained)}`);
+    L.push("");
+    const BLAME = { app: "YOUR APP", environment: "THE PLATFORM", harness: "THE TEST CLIENT", unknown: "UNKNOWN" };
+    for (const e of explained.slice(0, 4)) {
+      L.push(`    [${BLAME[e.blame]}]  ${e.method} × ${e.count}`);
+      L.push(`      ${e.headline}`);
+      for (const line of wrap(e.why, 72)) L.push(`      ${line}`);
+      if (e.fix) {
+        L.push(`      Fix:`);
+        for (const line of wrap(e.fix, 70)) L.push(`        ${line}`);
+      }
+      L.push("");
+    }
+  }
+
   if (report.coverage.notTested.length) {
     L.push(`  NOT TESTED — adapter implements ${report.coverage.label}`);
     for (const c of report.coverage.notTested) {