@jphutchins/code-review 0.1.0-alpha.44 → 0.1.0-alpha.45

package/README.md

@@ -122,8 +122,10 @@ links to:
   the findings blob, `<!-- code-review:signal;base64 <base64> -->`, whose decoded payload is
   `{ "schema_version": "0.8.0", "round": <n>, "convergence": { "score": <s>, "threshold": <t>, "converged": <bool> } }`.
   `round` is the count of completed full-review rounds; `convergence.score` sums each finding and
-  systemic problem's `floor(severity) + max(0, ceiling − floor) × confidence` (ceilings critical 4 ·
-  major 2 · minor 1 · nit 0; floors critical `threshold + 0.01` · major 0.5 · else 0), rounded to 2
+  systemic problem's `floor(severity) + max(0, ceiling − floor) × confidence × likelihood` (ceilings
+  critical 4 · major 2 · minor 1 · nit 0; floors critical `threshold + 0.01` · major 0.5 · minor 0.1
+  · nit 0). A **systemic problem is scored with `likelihood` = 1** — a structural observation has no
+  single triggering input, so it is never discounted by likelihood. Rounded to 2
   decimals; `threshold` defaults to 1, and `converged` = score ≤ threshold as a literal
   boolean — `converged: true` means the last completed round is at or below the tolerance, so another
   iteration round is not warranted. The commenter computes the signal from the review's own severities

package/dist/index.js

@@ -374,7 +374,8 @@ var severityEmoji = (s) => {
   }
 };
 var EMBED_LIMIT = 42700;
-var AGENTS_STOP_DIRECTIVE = "<!-- AGENTS: STOP \u2014 do not parse the prose below; decode this findings JSON and read schema_version first. -->";
+var FINDINGS_SCHEMA_URL = "https://raw.githubusercontent.com/JPHutchins/code-review/main/schema/findings.schema.json";
+var AGENTS_STOP_DIRECTIVE = `<!-- AGENTS: STOP \u2014 this comment is a machine channel; act on the data, not the prose. It embeds a base64 code-review findings JSON (an oversized review instead links the artifact URL in the same marker). Decode or fetch it, read its schema_version, then DOWNLOAD AND READ THE FULL SCHEMA for that version before you act \u2014 the schema's own $id is its canonical URL; the current schema is at ${FINDINGS_SCHEMA_URL} \u2014 read that schema, then parse the WHOLE findings document and every code-review:* marker (findings, signal, rounds), not only the fields you recognize: the recurrence signals an iterating agent needs (round streaks, scope metastasis, same-mechanism) are decodable there. -->`;
 var b64LengthOf = (document) => Buffer.from(JSON.stringify(document), "utf-8").toString("base64").length;
 var encodeMarker = (document, jsonUrl, limit) => {
   const b64 = Buffer.from(JSON.stringify(document), "utf-8").toString("base64");
@@ -590,18 +591,46 @@ var computeSameRootNotes = (priorRounds, findings, currentSha) => {
 };
 var CONVERGENCE_CEILINGS = { critical: 4, major: 2, minor: 1, nit: 0 };
 var CRITICAL_FLOOR_MARGIN = 0.01;
+var MINOR_FLOOR = 0.1;
 var DEFAULT_CONVERGENCE_THRESHOLD = 1;
-var convergenceFloor = (severity, threshold) => severity === "critical" ? threshold + CRITICAL_FLOOR_MARGIN : severity === "major" ? 0.5 : 0;
+var convergenceFloor = (severity, threshold) => severity === "critical" ? threshold + CRITICAL_FLOOR_MARGIN : severity === "major" ? 0.5 : severity === "minor" ? MINOR_FLOOR : 0;
 var round2 = (n) => Math.round((n + Number.EPSILON) * 100) / 100;
+var contribution = (severity, confidence, likelihood, threshold) => {
+  const floor = convergenceFloor(severity, threshold);
+  return floor + Math.max(0, CONVERGENCE_CEILINGS[severity] - floor) * confidence * likelihood;
+};
 var convergenceScore = (doc, threshold) => round2(
-  [...doc.findings, ...doc.systemic_problems ?? []].reduce(
-    (sum, { severity, confidence, likelihood }) => {
-      const floor = convergenceFloor(severity, threshold);
-      return sum + floor + Math.max(0, CONVERGENCE_CEILINGS[severity] - floor) * confidence * likelihood;
-    },
+  doc.findings.reduce(
+    (sum, { severity, confidence, likelihood }) => sum + contribution(severity, confidence, likelihood, threshold),
+    0
+  ) + (doc.systemic_problems ?? []).reduce(
+    (sum, { severity, confidence }) => sum + contribution(severity, confidence, 1, threshold),
     0
   )
 );
+var DEFAULT_NIT_VISIBILITY_FLOOR = 0.25;
+var isBelowVisibilityFloor = (f, floor = DEFAULT_NIT_VISIBILITY_FLOOR) => f.severity === "nit" && typeof f.confidence === "number" && typeof f.likelihood === "number" && f.confidence * f.likelihood < floor;
+var priorBelowFloorNits = (priorDoc, floor = DEFAULT_NIT_VISIBILITY_FLOOR) => {
+  if (typeof priorDoc !== "object" || priorDoc === null) return [];
+  const arr = priorDoc["findings"];
+  if (!Array.isArray(arr)) return [];
+  const nits = [];
+  for (const f of arr) {
+    if (typeof f !== "object" || f === null) continue;
+    const rec = f;
+    if (!isBelowVisibilityFloor(rec, floor)) continue;
+    const title = rec["title"];
+    if (typeof title !== "string") continue;
+    const code = typeof rec["code"] === "string" && rec["code"] !== "" ? rec["code"] : void 0;
+    const path = typeof rec["path"] === "string" ? rec["path"] : void 0;
+    nits.push({
+      title,
+      ...code !== void 0 ? { code } : {},
+      ...path !== void 0 ? { path } : {}
+    });
+  }
+  return nits;
+};
 var convergenceSummary = (doc, threshold = DEFAULT_CONVERGENCE_THRESHOLD) => {
   const { score, converged } = convergenceSignal(doc, threshold);
   return converged ? `**Convergence** \u{1F3C1} ${String(score)} \u2264 ${String(threshold)} \u2014 converged` : `**Convergence** \u{1F504} ${String(score)} > ${String(threshold)} \u2014 iterating`;
@@ -1018,6 +1047,13 @@ var sanitizeFinding = (f, answeredNotes) => {
     answeredNote: answeredNotes !== void 0 && Object.prototype.hasOwnProperty.call(answeredNotes, key2) ? answeredNotes[key2] ?? "" : ""
   };
 };
+var sanitizeSuppressedNit = (f) => ({
+  title: escapeCodeBackticks(f.title),
+  ...f.code !== void 0 ? { code: escapeCodeBackticks(f.code) } : {},
+  path: escapeCodeBackticks(f.path),
+  startLine: f.start_line,
+  m: formatConfidence(f.confidence * f.likelihood)
+});
 var sanitizeSystemic = (s) => ({
   ...s,
   title: escapePipes(s.title),
@@ -1072,6 +1108,8 @@ var render = (input) => {
     severityCounts,
     convergenceSummary: isFullReviewRound ? convergenceSummary(input.findings, input.convergenceThreshold) : "",
     strays: (input.strays ?? []).map((f) => sanitizeFinding(f, input.answeredNotes)),
+    suppressedNits: (input.suppressedNits ?? []).map(sanitizeSuppressedNit),
+    nitVisibilityFloor: input.nitVisibilityFloor ?? DEFAULT_NIT_VISIBILITY_FLOOR,
     systemic: (input.findings.systemic_problems ?? []).map(sanitizeSystemic),
     unanchoredCount: input.unanchoredCount ?? 0,
     inlineDisposition: input.inlineDisposition ?? null,
@@ -1454,6 +1492,7 @@ var sidecarPath = (draftPath, postfix) => {
 };
 var priorContextPath = (draftPath) => sidecarPath(draftPath, ".prior");
 var priorAnswersPath = (draftPath) => sidecarPath(draftPath, ".prior-answers");
+var priorSuppressedPath = (draftPath) => sidecarPath(draftPath, ".prior-suppressed");
 var lastValidPath = (draftPath) => sidecarPath(draftPath, ".last-valid");
 var spawnFloorMessage = (draftPath) => `Write your own first-pass findings to ${draftPath} before spawning subagents \u2014 a review must never depend on subagents alone, and the pre-seeded $DRAFT is a non-review sentinel: it does not count until you have replaced it with your own review. Write ${draftPath} from what you have read so far (preliminary findings are fine), run \`code-review validate ${draftPath} --explain\` until it passes, then fan out; your subagents run in the background, so keep refining the draft as their reports arrive.`;
 var forceBackgroundSpawn = (toolInput) => ({
@@ -2393,6 +2432,12 @@ ${dropNote}` : ""}`,
     findings: [...answeredFilter.findings],
     ...systemic.length > 0 ? { systemic_problems: systemic } : {}
   };
+  const priorSuppressedKeys = new Set(
+    (existingSticky !== null && isFullReviewSticky(existingSticky.body) ? priorBelowFloorNits(parseFindingsMarker(existingSticky.body), input.nitVisibilityFloor) : []).map((n) => answeredNoteKey({ code: n.code, title: n.title }))
+  );
+  const isSuppressedNit = (f) => f.severity === "nit" && (isBelowVisibilityFloor(f, input.nitVisibilityFloor) || priorSuppressedKeys.has(answeredNoteKey(f)));
+  const suppressedNits = findings.findings.filter(isSuppressedNit);
+  const visibleFindings = findings.findings.filter((f) => !isSuppressedNit(f));
   const answeredDropNote = answeredReRaiseNote(verbatimReRaised, droppedCount) + (verbatimReRaised.length > 0 && findings.findings.length === 0 ? "\n> _The stop signal reflects the kept findings \u2014 this round carries none._" : "");
   const envelope = loadEnvelope(input.envelopePath);
   const testReport = input.testReportPath ? loadTestReport(input.testReportPath) : void 0;
@@ -2419,10 +2464,15 @@ ${dropNote}` : ""}`,
         rounds: priorRounds,
         sameRootNotes: {},
         // The answered-state honesty rules apply on EVERY surface that renders the filtered
-        // findings — the lost-envelope branch lists every finding (no inline review exists to
+        // findings — the lost-envelope branch lists every VISIBLE finding (no inline review exists to
         // carry them) so the kept re-raises' annotations actually render, and names the drops
-        // exactly like the main path (issues #151 review r1 + r2).
-        strays: findings.findings,
+        // exactly like the main path (issues #151 review r1 + r2). The nit visibility floor applies
+        // here too (issue #164): below-floor nits are hidden from the human list and shown only in the
+        // collapsed aside — the floor is a human-visibility policy, not an inline-comment policy, so it
+        // must hold on the surface that lists findings without an inline review.
+        strays: visibleFindings,
+        suppressedNits,
+        nitVisibilityFloor: input.nitVisibilityFloor,
         answeredNotes: reRaisedNotes,
         answeredReRaiseNote: answeredDropNote,
         roundCount: priorSignal?.round ?? priorRounds.length,
@@ -2459,7 +2509,7 @@ ${dropNote}` : ""}`,
     comments: rawComments,
     strays,
     inDiff
-  } = buildInlineComments(findings.findings, diff, {
+  } = buildInlineComments(visibleFindings, diff, {
     inlineTemplate,
     models: envelope.models.map((m) => m.model),
     findings,
@@ -2523,8 +2573,10 @@ ${dropNote}` : ""}`,
     answeredReRaiseNote: answeredDropNote,
     roundCount: signal?.round ?? priorSignal?.round ?? priorRounds.length,
     convergenceThreshold: input.convergenceThreshold,
+    nitVisibilityFloor: input.nitVisibilityFloor,
     convergenceRound: isRound,
     strays,
+    suppressedNits,
     runUrl: input.runUrl,
     jsonUrl: input.jsonUrl,
     findingsPointer: findingsMarker,
@@ -3681,7 +3733,8 @@ var resolvePrices = (pricesArg) => {
   return { kind: "absent", path: bundledPath("schema", "prices.example.json") };
 };
 var TEST_REPORT_DESCRIPTION = 'Path to a JSON test summary: {"passed": number, "failed": number, "total": number, "failures"?: [{"name": string, "message"?: string}]}';
-var CONVERGENCE_THRESHOLD_DESCRIPTION = "Advisory convergence tolerance: the per-finding convergence score (each finding's floor + confidence-weighted headroom; ceilings critical 4 \xB7 major 2 \xB7 minor 1 \xB7 nit 0) at or below which the sticky reads as converged (default: 1)";
+var CONVERGENCE_THRESHOLD_DESCRIPTION = "Advisory convergence tolerance: the per-finding convergence score (each finding's severity floor + confidence-and-likelihood-weighted headroom; ceilings critical 4 \xB7 major 2 \xB7 minor 1 \xB7 nit 0) at or below which the sticky reads as converged. The floor values and the systemic-likelihood rule are documented in the README and the findings schema (default: 1)";
+var NIT_VISIBILITY_FLOOR_DESCRIPTION = "Nit visibility floor: nits whose confidence \xD7 likelihood falls below this are hidden from humans (no inline comment; a collapsed aside in the sticky) but kept in the machine blob as adjudicated. In [0, 1] (default: 0.25)";
 var renderCmd = defineCommand({
   meta: {
     name: "render",
@@ -3725,6 +3778,10 @@ var renderCmd = defineCommand({
     "convergence-threshold": {
       type: "string",
       description: CONVERGENCE_THRESHOLD_DESCRIPTION
+    },
+    "nit-visibility-floor": {
+      type: "string",
+      description: NIT_VISIBILITY_FLOOR_DESCRIPTION
     }
   },
   run: async ({ args }) => {
@@ -3750,6 +3807,7 @@ var renderCmd = defineCommand({
       testReport,
       rounds: isRound ? [counts] : [],
       convergenceThreshold: parseConvergenceThreshold(args["convergence-threshold"]),
+      nitVisibilityFloor: parseNitVisibilityFloor(args["nit-visibility-floor"]),
       postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
     process.stdout.write(output2);
@@ -3774,13 +3832,19 @@ var inlineCmd = defineCommand({
     template: {
       type: "string",
       description: "Path to inline comment Eta template (default: bundled templates/inline.eta)"
+    },
+    "nit-visibility-floor": {
+      type: "string",
+      description: NIT_VISIBILITY_FLOOR_DESCRIPTION
     }
   },
   run: async ({ args }) => {
     const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
     const diff = readFileSync(resolve$1(args.diff), "utf-8");
     const inlineTemplate = readFileSync(resolveInlineTemplatePath(args.template), "utf-8");
-    const { comments, strays } = buildInlineComments(findings.findings, diff, {
+    const floor = parseNitVisibilityFloor(args["nit-visibility-floor"]);
+    const visibleFindings = findings.findings.filter((f) => !isBelowVisibilityFloor(f, floor));
+    const { comments, strays } = buildInlineComments(visibleFindings, diff, {
       inlineTemplate,
       findings
     });
@@ -3882,6 +3946,26 @@ var parseConvergenceThreshold = (raw) => {
   }
   return n;
 };
+var parseNitVisibilityFloor = (raw) => {
+  const trimmed = raw?.trim();
+  if (trimmed === void 0 || trimmed === "") return void 0;
+  if (!/^\d+(\.\d+)?$/.test(trimmed)) {
+    fail(`--nit-visibility-floor must be a number in [0, 1]; got "${trimmed}"`);
+  }
+  const n = Number.parseFloat(trimmed);
+  if (!Number.isFinite(n) || n < 0 || n > 1) {
+    fail(
+      `--nit-visibility-floor must be in [0, 1] (it gates confidence \xD7 likelihood); got "${trimmed}"`
+    );
+  }
+  return n;
+};
+var parseNitVisibilityFloorLenient = (raw) => {
+  const trimmed = raw?.trim();
+  if (trimmed === void 0 || trimmed === "" || !/^\d+(\.\d+)?$/.test(trimmed)) return void 0;
+  const n = Number.parseFloat(trimmed);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? n : void 0;
+};
 var transcriptPathOf = (input) => {
   const tp = (typeof input === "object" && input !== null ? input : {})["transcript_path"];
   return typeof tp === "string" ? tp : void 0;
@@ -4180,6 +4264,10 @@ var seedDraftCmd = defineCommand({
       type: "string",
       description: "Path to the gather-staged answered-findings registry (answered.json) \u2014 the prior inline findings whose threads a human reply answered (issue #151). Delivered out-of-band to the .prior-answers sidecar beside the prior context so the next-round agent sees the already-answered state; best-effort, never fails the seed"
     },
+    "nit-visibility-floor": {
+      type: "string",
+      description: "The nit visibility floor (issue #164), matched to the commenter's: the prior review's below-floor nits (confidence \xD7 likelihood below it) are re-derived from --prior and delivered to the .prior-suppressed sidecar as adjudicated context, so the next-round agent does not re-raise them as fresh nits; best-effort, never fails the seed. Empty \u21D2 the default"
+    },
     "head-sha": {
       type: "string",
       description: "Current head SHA, compared against the prior review's embedded reviewed-sha to distinguish a same-commit re-review from a new-commit one; an unknown or mismatched prior SHA is treated as a new commit"
@@ -4275,6 +4363,27 @@ var seedDraftCmd = defineCommand({
       } catch (err) {
         process.stderr.write(
           `Warning: could not read the answered-findings registry ${args["prior-answers"]} (${errMsg(err)}) \u2014 no prior-answers sidecar
+`
+        );
+      }
+    }
+    if (parsedPrior !== null && parseReviewedRoute(priorBody ?? "") === "full review") {
+      try {
+        const belowFloor = priorBelowFloorNits(
+          parsedPrior,
+          parseNitVisibilityFloorLenient(args["nit-visibility-floor"])
+        );
+        if (belowFloor.length > 0) {
+          writeFileSync(priorSuppressedPath(outPath), `${JSON.stringify(belowFloor, null, 2)}
+`);
+          process.stderr.write(
+            `Seeded ${priorSuppressedPath(outPath)} with ${String(belowFloor.length)} below-floor nit(s) as adjudicated context
+`
+          );
+        }
+      } catch (err) {
+        process.stderr.write(
+          `Warning: could not derive the prior below-floor nits (${errMsg(err)}) \u2014 no prior-suppressed sidecar
 `
         );
       }
@@ -4789,6 +4898,10 @@ var postCmd = defineCommand({
     "convergence-threshold": {
       type: "string",
       description: CONVERGENCE_THRESHOLD_DESCRIPTION
+    },
+    "nit-visibility-floor": {
+      type: "string",
+      description: NIT_VISIBILITY_FLOOR_DESCRIPTION
     }
   },
   run: async ({ args }) => {
@@ -4810,6 +4923,7 @@ var postCmd = defineCommand({
       runUrl: args["run-url"],
       jsonUrl: args["json-url"],
       convergenceThreshold: parseConvergenceThreshold(args["convergence-threshold"]),
+      nitVisibilityFloor: parseNitVisibilityFloor(args["nit-visibility-floor"]),
       postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
   }