karajan-code 4.21.0 → 4.23.0

package/src/steward/phantom-coverage.js

@@ -0,0 +1,137 @@
+/**
+ * Phantom coverage (KJC-TSK-0800, epic KJC-PCS-0081) — a phantom test is
+ * worse than no test: it adds to the count, feels like a net, and covers
+ * nothing. TWO detectors, because one is not enough: the call graph catches
+ * a unit test that only exercises unreachable members, and LITERAL crossing
+ * catches the case the graph cannot see — GREBLA's hierarchy.spec called no
+ * dead method, it looked for an aria-label that only existed inside one.
+ * Both inherit the reachability perimeter: a NOT OBSERVABLE analysis makes
+ * the detector not observable — no test is accused on an unreliable basis.
+ */
+import { parse } from "@babel/parser";
+
+const parseLoose = (source, file) =>
+  parse(source, {
+    sourceType: "unambiguous", allowReturnOutsideFunction: true,
+    plugins: [...(/\.(ts|tsx|mts|cts)$/.test(file) ? ["typescript"] : []), ...(/\.(tsx|jsx)$/.test(file) || !/\.(ts|mts|cts)$/.test(file) ? ["jsx"] : []), "decorators"],
+  });
+
+function walk(node, visit) {
+  if (!node || typeof node.type !== "string") return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    const child = node[key];
+    if (Array.isArray(child)) child.forEach((c) => walk(c, visit));
+    else if (child && typeof child.type === "string") walk(child, visit);
+  }
+}
+
+const notObservable = (sourceAnalysis) => {
+  if (!sourceAnalysis?.observable) return sourceAnalysis?.reason || "the reachability analysis is not observable";
+  const classes = (sourceAnalysis.classes || []).filter((c) => c.observable);
+  if (classes.length === 0) return "no class in the source is observable — the analysis cannot vouch for anything";
+  return null;
+};
+const observableClasses = (a) => (a.classes || []).filter((c) => c.observable);
+const bareName = (slot) => slot.replace(/^static /, "");
+
+/**
+ * Unit detector: of the test's member CALLS that belong to an analyzed class,
+ * do all of them land on unreachable members? One live call absolves.
+ * @returns {{observable: boolean, reason?: string, phantoms: Array<{member: string, className: string}>}}
+ */
+export function detectPhantomUnit({ sourceAnalysis, testSource, file = "<test>" }) {
+  const why = notObservable(sourceAnalysis);
+  if (why) return { observable: false, reason: `not observable: ${why}`, phantoms: [] };
+  let tree;
+  try { tree = parseLoose(testSource, file); } catch (err) {
+    return { observable: false, reason: `the test could not be parsed (${err.message})`, phantoms: [] };
+  }
+  // Calls grouped by RECEIVER (weak binding, reviewer's catch): a receiver is
+  // tied to a class only when EVERY member it calls belongs to that class —
+  // mixing two objects under one name must not get a test accused.
+  const byReceiver = new Map();
+  walk(tree, (n) => {
+    if (n.type !== "CallExpression" || n.callee?.type !== "MemberExpression" || n.callee.computed || n.callee.property?.type !== "Identifier") return;
+    const recv = n.callee.object?.type === "Identifier" ? n.callee.object.name : n.callee.object?.type === "ThisExpression" ? "this" : "(expr)";
+    (byReceiver.get(recv) ?? byReceiver.set(recv, new Set()).get(recv)).add(n.callee.property.name);
+  });
+  const phantoms = [];
+  for (const c of observableClasses(sourceAnalysis)) {
+    const members = new Set(c.memberNames.map(bareName));
+    const dead = new Set(c.unreachable.map((u) => bareName(u.name)));
+    for (const [, names] of byReceiver) {
+      const touched = [...names].filter((n) => members.has(n));
+      // bound to this class, and everything it touches is dead → phantom;
+      // one live call — or a call outside the class — absolves the receiver.
+      if (touched.length > 0 && touched.length === names.size && touched.every((n) => dead.has(n))) {
+        for (const n of touched) phantoms.push({ member: n, className: c.name, file });
+      }
+    }
+  }
+  return { observable: true, phantoms };
+}
+
+const literalsOf = (tree, minLength) => {
+  const out = [];
+  walk(tree, (n) => {
+    if (n.type === "StringLiteral" && n.value.trim().length >= minLength) out.push({ value: n.value, line: n.loc.start.line });
+    if (n.type === "TemplateElement" && n.value.cooked && n.value.cooked.trim().length >= minLength) out.push({ value: n.value.cooked, line: n.loc.start.line });
+  });
+  return out;
+};
+
+/**
+ * E2E detector: literals the test looks for that ONLY exist inside
+ * unreachable spans of the source. A literal also present in reachable code
+ * is never reported — that test does cover something.
+ * @returns {{observable: boolean, reason?: string, phantoms: Array<{literal: string, line: number}>}}
+ */
+export function detectPhantomE2E({ sourceText, sourceAnalysis, testSource, file = "<spec>", minLength = 4 }) {
+  const why = notObservable(sourceAnalysis);
+  if (why) return { observable: false, reason: `not observable: ${why}`, phantoms: [] };
+  let sourceTree, testTree;
+  try {
+    sourceTree = parseLoose(sourceText, sourceAnalysis.file || "<source>");
+    testTree = parseLoose(testSource, file);
+  } catch (err) {
+    return { observable: false, reason: `could not be parsed (${err.message})`, phantoms: [] };
+  }
+  const deadSpans = observableClasses(sourceAnalysis).flatMap((c) => c.unreachable.map((u) => [u.line, u.endLine]));
+  const inDead = (line) => deadSpans.some(([a, b]) => line >= a && line <= b);
+  const onlyInDead = new Map(); // literal → line where it lives
+  for (const lit of literalsOf(sourceTree, minLength)) {
+    if (inDead(lit.line)) { if (!onlyInDead.has(lit.value)) onlyInDead.set(lit.value, lit.line); }
+    else onlyInDead.set(lit.value, -1); // seen reachable — poisoned, never reportable
+  }
+  const wanted = new Set(literalsOf(testTree, minLength).map((l) => l.value));
+  const phantoms = [...wanted]
+    .filter((v) => onlyInDead.get(v) !== undefined && onlyInDead.get(v) !== -1)
+    .map((v) => ({ literal: v, line: onlyInDead.get(v), file }));
+  return { observable: true, phantoms };
+}
+
+/**
+ * The temporal signature — zero static analysis, and it would have been
+ * enough for GREBLA: a bug gets fixed or reverted; a phantom fails the SAME
+ * way indefinitely because it proves something that no longer exists.
+ * kj holds no per-test history, so the source is INJECTED and said:
+ * failures = [{test, reason, at}] from whoever owns the CI history.
+ */
+export function assessTemporalSignature({ failures, thresholdDays = 7 } = {}) {
+  if (!Array.isArray(failures)) {
+    return { observable: false, reason: "no per-test failure history handed in — kj holds none; inject it from the CI that owns it", suspects: [] };
+  }
+  const byTest = new Map();
+  for (const f of failures) (byTest.get(f.test) ?? byTest.set(f.test, []).get(f.test)).push(f);
+  const suspects = [];
+  for (const [test, rows] of byTest) {
+    const reasons = new Set(rows.map((r) => String(r.reason || "").trim().toLowerCase()));
+    if (reasons.size !== 1) continue; // changing reasons look like a bug being worked
+    const times = rows.map((r) => Date.parse(r.at)).filter(Number.isFinite);
+    if (times.length < 2) continue;
+    const days = Math.floor((Math.max(...times) - Math.min(...times)) / 86_400_000);
+    if (days >= thresholdDays) suspects.push({ test, reason: rows[0].reason, days, firstAt: new Date(Math.min(...times)).toISOString(), lastAt: new Date(Math.max(...times)).toISOString() });
+  }
+  return { observable: true, suspects };
+}

package/src/steward/proposed-work.js

@@ -0,0 +1,68 @@
+/**
+ * Proposed work (STW-D, KJC-TSK-0792, epic KJC-PCS-0081) — every broken
+ * invariant becomes a CARD in the channel the Brain already consumes, as a
+ * PROPOSAL: evidence, since-when, and a remedy plan that nothing executes
+ * without review (the user's decision, 22-aug: an unreviewed generated plan
+ * can do more harm than the decay itself). The same break UPDATES its card —
+ * a daily sweep must never flood the board with twins — and a green
+ * invariant resolves it with the green evidence.
+ *
+ * kj only writes the board it owns (hu-board). planning-game and external
+ * boards are never mirrored (KJC-TSK-0684: a half-empty parallel board is
+ * worse than none): there the sweep reports synced:false LOUDLY, and the
+ * Sentinel's inevitable notice (STW-C) pushes the host agent — who does
+ * have the board's MCP — to card them.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { addHu, updateHu, updateHuStatus } from "../plan/plan-hu-ops.js";
+import { savePlan } from "../plan/plan-store.js";
+import { backlogPlan } from "../commands/hu.js";
+
+const mapPath = (projectDir) => path.join(projectDir, ".karajan", "steward", "cards.json");
+const readMap = (projectDir) => { try { return JSON.parse(fs.readFileSync(mapPath(projectDir), "utf8")); } catch { return {}; } };
+
+const cardText = (r, brokenSince) => [
+  `Steward invariant BROKEN since ${brokenSince}.`,
+  `Evidence: ${r.evidence || "(none recorded)"}`,
+  `Proposed remedy plan: ${r.remedy || r.renew || "kj steward sweep"}.`,
+  "This plan is a PROPOSAL — review before executing: nothing in it runs unreviewed.",
+].join("\n");
+
+/**
+ * @returns {Promise<{synced: boolean, reason?: string, created?: number, updated?: number, resolved?: number}>}
+ */
+export async function syncProposedWork({ projectDir, config = {}, results = [], sweptAt }) {
+  const backend = config.state_backend || "hu-board";
+  if (backend !== "hu-board") {
+    return { synced: false, reason: `the board lives in ${backend} — kj never mirrors a board it does not own; card the broken invariants through your agent's board tools` };
+  }
+  const map = readMap(projectDir);
+  const broken = results.filter((r) => r.verdict === "broken");
+  const okAgain = results.filter((r) => r.verdict === "ok" && map[r.id]);
+  if (broken.length === 0 && okAgain.length === 0) return { synced: true, created: 0, updated: 0, resolved: 0 };
+
+  const plan = await backlogPlan(projectDir);
+  let created = 0, updated = 0, resolved = 0;
+  for (const r of broken) {
+    const known = map[r.id];
+    if (known) {
+      updateHu(plan, known.huId, { scope: cardText(r, known.brokenSince) });
+      updated += 1;
+    } else {
+      const hu = addHu(plan, { title: `steward: ${r.id} broken — proposed remedy (review before executing)`, scope: cardText(r, sweptAt), created_by: "steward" });
+      map[r.id] = { huId: hu.id, brokenSince: sweptAt };
+      created += 1;
+    }
+  }
+  for (const r of okAgain) {
+    updateHu(plan, map[r.id].huId, { scope: `Resolved: the invariant is green again (${r.evidence || "no evidence text"}) — validation stays with the user.` });
+    updateHuStatus(plan, map[r.id].huId, "done");
+    delete map[r.id];
+    resolved += 1;
+  }
+  await savePlan(projectDir, plan);
+  fs.mkdirSync(path.dirname(mapPath(projectDir)), { recursive: true });
+  fs.writeFileSync(mapPath(projectDir), `${JSON.stringify(map, null, 2)}\n`);
+  return { synced: true, created, updated, resolved };
+}