clud-bug 0.7.0-rc.2 → 0.7.0-rc.21

package/src/core/diff-findings.ts

@@ -0,0 +1,323 @@
+// SPEC §1.8.1 multi-pass diff: prior `docs/reviews/PR-<n>.md` vs current
+// review findings. Produces the `**Resolved this round:**` /
+// `**Still open:**` lists that `renderReviewFile` consumes.
+//
+// Identity model
+// --------------
+// Each finding's identity is a stable hash of:
+//
+//   `${file}:${line}:${severity}:${skillName}:${summary.slice(0, 100)}`
+//
+// A 100-character truncation on `summary` is enough to discriminate
+// distinct findings without being so long that whitespace/punctuation
+// drift between passes breaks identity. A severity-bucket change (e.g.
+// the same skill flags the same line as 🔴 then 🟡 the next round)
+// produces a DIFFERENT identity — by design — so a severity downgrade
+// counts as one resolved finding + one new finding (the user gets
+// credit for the fix AND can see the bot still has a concern, just at
+// a lower severity).
+//
+// The same identity shape is what auto-fix / auto-resolve in
+// clud-bug-app uses for thread anchoring; keeping it identical means a
+// future per-finding cross-reference between the doc-file diff and the
+// inline-thread surface is trivial.
+
+import {
+  flattenFindings,
+  type Finding,
+  type Review,
+} from './review-schema-zod.js';
+
+import { SEVERITY_EMOJI } from './review-writeback.js';
+
+/** One parsed finding from a prior `docs/reviews/PR-<n>.md`. */
+export type ParsedFinding = {
+  /** Relative path. Falls back to '(unknown file)' when the prior file
+   *  itself rendered the unknown-file marker; we keep it intact for
+   *  identity stability. */
+  file: string;
+  /**
+   * 1-indexed line number. Zero when the prior file had no `:N` suffix
+   * (cross-cutting findings). Zero participates in identity as-is.
+   */
+  line: number;
+  severity: 'critical' | 'minor' | 'preexisting';
+  skillName: string;
+  summary: string;
+};
+
+export type ParsedReview = { findings: ParsedFinding[] };
+
+/**
+ * Parse a `docs/reviews/PR-<n>.md` markdown back into structured findings.
+ *
+ * Robust to:
+ *   - `null` / `undefined` input            → returns `null`
+ *   - empty / whitespace-only markdown      → returns `null`
+ *   - missing severity sections             → those sections contribute 0
+ *   - lines that don't match the SPEC bullet shape → silently dropped
+ *   - mixed unknown-file markers (`(unknown file)` vs absent)
+ *
+ * Parsing strategy: walk top-down, switch active severity on each
+ * `### <emoji> <Label>` header (one of the three SPEC §1.8.1 buckets),
+ * then collect every line starting with `- **` until the next header
+ * (or `---` end marker). Each `- **<file>:<line>** — <skill>: <summary>`
+ * line is split into its 4 fields; `:<line>` is optional (cross-cutting).
+ *
+ * `(unknown file)` files are preserved verbatim — they participate in
+ * identity, so the same cross-cutting finding can still be diffed across
+ * rounds even when neither pass has a line anchor.
+ */
+export function parsePriorReviewFile(
+  markdown: string | null | undefined,
+): ParsedReview | null {
+  if (markdown == null) return null;
+  if (markdown.trim() === '') return null;
+
+  const lines = markdown.split('\n');
+  const out: ParsedFinding[] = [];
+  let current: ParsedFinding['severity'] | null = null;
+
+  for (const raw of lines) {
+    // Strip trailing whitespace; leading indent is meaningful for
+    // sub-lines (Reasoning, attribution) which we deliberately ignore.
+    const line = raw.replace(/\s+$/, '');
+
+    // The SPEC §1.8.1 trailing `---` separator ends the findings region.
+    // Anything after it (the [Link to PR] line) is metadata and parsed
+    // by short-circuit so we don't mistake the literal `---` for a
+    // missing header.
+    if (line === '---') {
+      current = null;
+      continue;
+    }
+
+    // Switch active severity on every `### <emoji> <Label>` heading.
+    // We pattern-match on the emoji codepoint (not the label text) so a
+    // future SPEC tweak to "Critical" → "Blocking" doesn't break us.
+    if (line.startsWith('### ')) {
+      if (line.includes(SEVERITY_EMOJI.critical)) {
+        current = 'critical';
+      } else if (line.includes(SEVERITY_EMOJI.minor)) {
+        current = 'minor';
+      } else if (line.includes(SEVERITY_EMOJI.preexisting)) {
+        current = 'preexisting';
+      } else {
+        current = null;
+      }
+      continue;
+    }
+
+    // Resolved / Still-open blocks under SPEC §1.8.1 — these list
+    // findings from PRIOR rounds, NOT this-round findings. Skip them
+    // so a multi-round PR doesn't double-count its own history.
+    // (`**Resolved this round:**` / `**Still open:**` headings.)
+    if (line.startsWith('**Resolved this round:') || line.startsWith('**Still open:')) {
+      current = null;
+      continue;
+    }
+
+    if (current == null) continue;
+
+    // SPEC §1.8.1 bullet: `- **<file>:<line>** — <skill>: <summary>`
+    //                  OR `- **<file>** — <skill>: <summary>`
+    //                  OR `- **(unknown file)** — <skill>: <summary>`
+    //
+    // The multi-pass renderer prepends `[Pass N — Role · model]` to the
+    // bullet; we accept that prefix and discard it for parsing.
+    const parsed = parseFindingBullet(line);
+    if (parsed) {
+      out.push({ ...parsed, severity: current });
+    }
+  }
+
+  if (out.length === 0) return null;
+  return { findings: out };
+}
+
+/**
+ * Diff prior vs current.
+ *
+ * `resolvedFindings`: findings that appeared in `prior` but NOT in
+ * `current`. The PR author (or auto-fix) addressed them.
+ *
+ * `stillOpenFindings`: findings that appeared in BOTH `prior` and
+ * `current`. These are persistent — the PR author hasn't fixed them
+ * (or the bot still considers them findings post-fix-push).
+ *
+ * Findings unique to `current` (newly raised this round) appear in
+ * neither list — those are surfaced directly by the renderer's normal
+ * severity-bucket emission.
+ *
+ * Order is preserved from `prior` for stability across rounds.
+ */
+export function diffFindings(
+  prior: ParsedReview | null,
+  current: {
+    critical_findings?: Array<{
+      skill: string;
+      file?: string;
+      line?: number;
+      summary: string;
+    }>;
+    minor_findings?: Array<{
+      skill: string;
+      file?: string;
+      line?: number;
+      summary: string;
+    }>;
+    preexisting_findings?: Array<{
+      skill: string;
+      file?: string;
+      line?: number;
+      summary: string;
+    }>;
+  },
+): {
+  resolvedFindings: ParsedFinding[];
+  stillOpenFindings: ParsedFinding[];
+} {
+  if (prior === null || prior.findings.length === 0) {
+    return { resolvedFindings: [], stillOpenFindings: [] };
+  }
+
+  // Build identity set for the current round. We do not need the
+  // current-round ParsedFinding objects — we only need to know which
+  // identities are still present.
+  //
+  // Cast through `Review` shape — the schema's three arrays mirror our
+  // input slice exactly (skill / file / line / summary), so we can lean
+  // on `flattenFindings` to produce a tagged list.
+  const currentReview: Review = {
+    status_header: 'clean',
+    summary_counts: {
+      critical: 0,
+      minor: 0,
+      preexisting: 0,
+      resolved_from_prior: 0,
+      still_open: 0,
+    },
+    per_skill_scan: [],
+    critical_findings: current.critical_findings ?? [],
+    minor_findings: current.minor_findings ?? [],
+    preexisting_findings: current.preexisting_findings ?? [],
+    skills_referenced: [],
+    last_reviewed_sha: '',
+  };
+  const currentFlat: Finding[] = flattenFindings(currentReview);
+  const currentIds = new Set<string>(currentFlat.map((f) => findingIdentity({
+    file: f.file ?? '(unknown file)',
+    line: f.line ?? 0,
+    severity: f.severity,
+    skillName: f.skill,
+    summary: f.summary,
+  })));
+
+  const resolved: ParsedFinding[] = [];
+  const stillOpen: ParsedFinding[] = [];
+  for (const f of prior.findings) {
+    const id = findingIdentity(f);
+    if (currentIds.has(id)) {
+      stillOpen.push(f);
+    } else {
+      resolved.push(f);
+    }
+  }
+  return { resolvedFindings: resolved, stillOpenFindings: stillOpen };
+}
+
+/**
+ * Stable identity for a finding. Used for diffing prior vs current
+ * across review rounds AND (by intention) shareable with the
+ * clud-bug-app inline-thread anchor hash so future cross-feature
+ * surfaces (e.g. "the auto-fix that resolved this thread also resolves
+ * this doc-file finding") align without re-computing.
+ *
+ * Exposed for tests + downstream callers that want to align their own
+ * finding storage on the same scheme.
+ */
+export function findingIdentity(f: {
+  file: string;
+  line: number;
+  severity: 'critical' | 'minor' | 'preexisting';
+  skillName: string;
+  summary: string;
+}): string {
+  // Truncate summary to 100 chars to absorb whitespace/punctuation
+  // drift between rounds without losing discrimination between
+  // genuinely-distinct findings (the SPEC §1.8.1 summary line is
+  // user-visible so it tends to be stable; 100 chars is enough for any
+  // realistic distinct summary while tolerating "fix the X" → "fix X"
+  // drift).
+  const summaryPart = f.summary.slice(0, 100);
+  return `${f.file}:${f.line}:${f.severity}:${f.skillName}:${summaryPart}`;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing internals
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse one SPEC §1.8.1 bullet line into a {file, line, skill, summary}
+ * tuple. Returns null for any line that doesn't match the SPEC shape.
+ *
+ * Accepts both shapes:
+ *   `- **<file>:<line>** — <skill>: <summary>`
+ *   `- **<file>** — <skill>: <summary>`
+ *
+ * Also tolerates the multi-pass attribution prefix (D.2.5):
+ *   `- [Pass 1 — Role · model] **<file>:<line>** — <skill>: <summary>`
+ *
+ * Em-dash recognition: the SPEC pins U+2014 EM DASH between location
+ * and skill. Some downstream tools have been observed using `--` or
+ * regular hyphens; we accept both for resilience.
+ */
+function parseFindingBullet(line: string): Omit<ParsedFinding, 'severity'> | null {
+  // Strip the leading `- ` bullet marker.
+  if (!line.startsWith('- ')) return null;
+  let rest = line.slice(2);
+
+  // Strip optional `[Pass N — ...] ` attribution prefix (D.2.5).
+  if (rest.startsWith('[')) {
+    const closeIdx = rest.indexOf('] ');
+    if (closeIdx === -1) return null;
+    rest = rest.slice(closeIdx + 2);
+  }
+
+  // Expect `**<location>** ` next.
+  if (!rest.startsWith('**')) return null;
+  const locEnd = rest.indexOf('**', 2);
+  if (locEnd === -1) return null;
+  const location = rest.slice(2, locEnd);
+  rest = rest.slice(locEnd + 2);
+
+  // Strip the location separator. SPEC pins ` — ` (U+2014 surrounded by
+  // spaces). We accept hyphen-minus variants as a courtesy.
+  // The separator may be ` — `, ` -- `, or ` - `.
+  const sepMatch = rest.match(/^\s+(?:—|--|-)\s+/);
+  if (!sepMatch) return null;
+  rest = rest.slice(sepMatch[0].length);
+
+  // `<skill>: <summary>` — split on the first `: `.
+  const sepIdx = rest.indexOf(': ');
+  if (sepIdx === -1) return null;
+  const skillName = rest.slice(0, sepIdx).trim();
+  const summary = rest.slice(sepIdx + 2).trim();
+  if (skillName === '' || summary === '') return null;
+
+  // Split location into file + optional line. Walk RIGHTWARD from the
+  // last `:` so file names containing colons (Windows-style, rare) on
+  // the LHS don't confuse us.
+  const colonIdx = location.lastIndexOf(':');
+  let file = location;
+  let lineNum = 0;
+  if (colonIdx !== -1) {
+    const tail = location.slice(colonIdx + 1);
+    if (/^\d+$/.test(tail)) {
+      file = location.slice(0, colonIdx);
+      lineNum = Number(tail);
+    }
+  }
+
+  return { file, line: lineNum, skillName, summary };
+}

package/src/core/formal-review.ts

@@ -0,0 +1,168 @@
+// SPEC §7.2.1 formal-review event selector.
+//
+// This is the PURE half of clud-bug-app's `lib/formal-review.ts` (the
+// Octokit-side `postFormalReview` IO wrapper stays App-side — it depends
+// on `getInstallationOctokit` + `@octokit/rest` which we don't want to
+// pull into core). The pure rule-table lives here so:
+//
+//   1. The npm workflow template's new post-step (added in v0.7.0-rc.3)
+//      can `import { selectReviewEvent } from 'clud-bug/core'` and post
+//      formal `pulls.createReview` calls under the workflow path — until
+//      this PR shipped, the workflow path NEVER satisfied the canonical
+//      ruleset's `required_approving_review_count: 1` floor because no
+//      APPROVE review was ever posted.
+//
+//   2. clud-bug-app (Phase 7 PR B) deletes its local copy and imports
+//      this version, gaining the §7.2.1 author_association extension
+//      (clud-bug-app's PR #40 shipped APPROVE without it, so the App
+//      currently auto-approves drive-by external-contributor PRs — a
+//      security bug closed by Phase 7 PR B's dep bump).
+//
+// Ported from clud-bug-app/lib/formal-review.ts (PR #40, MERGED 2026-06-10)
+// with the §7.2.1 `authorAssociation` extension new in Phase 7 PR A.
+
+/** GitHub's `pulls.createReview` `event` enum, narrowed to the three we use. */
+export type FormalReviewEvent = 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT';
+
+/**
+ * GitHub `author_association` on a PR. Verbatim union from the REST API
+ * (per https://docs.github.com/en/rest/pulls/pulls — `author_association`).
+ *
+ * The "external" tier for §7.2.1 auto-approve gating is:
+ *
+ *   { 'NONE', 'FIRST_TIME_CONTRIBUTOR', 'FIRST_TIMER', 'MANNEQUIN' }
+ *
+ * Everything else (OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR) is the
+ * "org-trusted" tier and eligible for auto-approve on a clean review.
+ *
+ * `FIRST_TIMER` is the legacy spelling (October 2018 era); GitHub
+ * currently emits `FIRST_TIME_CONTRIBUTOR` but some PR fixtures in
+ * downstream tests still carry the old token. We keep both so the
+ * external-contributor gate doesn't silently regress on the next
+ * REST-API rename.
+ */
+export type AuthorAssociation =
+  | 'OWNER'
+  | 'MEMBER'
+  | 'COLLABORATOR'
+  | 'CONTRIBUTOR'
+  | 'FIRST_TIME_CONTRIBUTOR'
+  | 'FIRST_TIMER'
+  | 'NONE'
+  | 'MANNEQUIN';
+
+/**
+ * Author-association values that route a clean-review APPROVE *down* to
+ * COMMENT per SPEC §7.2.1 precondition #3 ("PR author is an org member —
+ * NOT a first-time external contributor"). These authors still get a
+ * COMMENT review (so they SEE the bot's verdict) but the formal APPROVE
+ * vote stays withheld — a human reviewer must click Approve before the
+ * PR can merge under the canonical ruleset.
+ *
+ * Drive-by exploitation prevention: a malicious external contributor
+ * who opens a clean-looking PR cannot leverage clud-bug[bot]'s APPROVE
+ * vote to auto-merge.
+ */
+const EXTERNAL_ASSOCIATIONS: ReadonlySet<AuthorAssociation> = new Set<
+  AuthorAssociation
+>(['NONE', 'FIRST_TIME_CONTRIBUTOR', 'FIRST_TIMER', 'MANNEQUIN']);
+
+/**
+ * SPEC §7.2.1 + §7.2 rule table.
+ *
+ * Order matters — earlier rows short-circuit later ones:
+ *
+ * | Priority | Condition                                              | Event           |
+ * |----------|--------------------------------------------------------|-----------------|
+ * | 1        | PR author === clud-bug[bot]                            | 'skip'          |
+ * | 2        | authorAssociation ∈ EXTERNAL                           | 'COMMENT'       |
+ * | 3        | criticalCount > 0 AND strictMode=true                  | REQUEST_CHANGES |
+ * | 4        | criticalCount > 0 AND strictMode=false                 | COMMENT         |
+ * | 5        | minorCount > 0  (no critical)                          | COMMENT         |
+ * | 6        | 0 critical + 0 minor                                   | APPROVE         |
+ *
+ * The external-contributor row (Priority 2) sits BETWEEN self-PR-skip
+ * and the severity-driven rules: external contributors who open a
+ * critical-finding PR still get COMMENT (NOT REQUEST_CHANGES — we don't
+ * block their PR on a bot review; that's a human reviewer's call to
+ * make). External contributors who open a clean PR also get COMMENT
+ * (NOT APPROVE — the §7.2.1 precondition #3 gate).
+ *
+ * The 'skip' verdict tells the caller NOT to invoke `pulls.createReview`
+ * — GitHub returns 422 when a user reviews their own PR, so we
+ * short-circuit before the network round-trip. Self-PRs land during D.7
+ * migration fan-out (the App opens cross-repo update PRs under its own
+ * identity).
+ */
+export interface SelectReviewEventInput {
+  /** Count of `severity: critical` findings on the review. */
+  criticalCount: number;
+  /** Count of `severity: minor` findings on the review. */
+  minorCount: number;
+  /**
+   * `strictMode` flag read from `.clud-bug.json` at the PR's BASE ref.
+   * Older manifests may not carry this field — callers MUST pass
+   * `undefined` in that case so this function applies the safe default
+   * (false) rather than surprising users with REQUEST_CHANGES.
+   */
+  strictMode?: boolean;
+  /**
+   * GitHub login of the PR author. When it equals 'clud-bug[bot]' we
+   * skip the formal review entirely (GitHub disallows self-review with
+   * 422). This is the structural guard for D.7 migration fan-out PRs.
+   */
+  prAuthorLogin: string;
+  /**
+   * GitHub `author_association` on the PR. NEW in v0.7.0-rc.3 / SPEC
+   * §7.2.1: when this is in EXTERNAL_ASSOCIATIONS, a clean review gets
+   * COMMENT (not APPROVE) so external-contributor PRs require a human
+   * reviewer to satisfy the `required_approving_review_count: 1` floor.
+   *
+   * Callers that don't have this metadata (older webhook payloads,
+   * tests, etc.) should pass `'CONTRIBUTOR'` as the safe default — that
+   * tier is org-trusted and preserves pre-§7.2.1 behaviour.
+   */
+  authorAssociation: AuthorAssociation;
+}
+
+export function selectReviewEvent(
+  input: SelectReviewEventInput,
+): FormalReviewEvent | 'skip' {
+  // Priority 1: self-PR guard. GitHub returns 422 on a self-review;
+  // we short-circuit before the network round-trip. Self-PRs land
+  // during D.7 migration fan-out (the App opens cross-repo update PRs
+  // under its own identity).
+  if (input.prAuthorLogin === 'clud-bug[bot]') {
+    return 'skip';
+  }
+
+  // Priority 2: external-contributor gate (SPEC §7.2.1 precondition #3).
+  // External contributors NEVER get APPROVE (no auto-merge bypass via
+  // drive-by) and NEVER get REQUEST_CHANGES (we don't block their PR on
+  // a bot review — that escalation is a human reviewer's call). They
+  // always get an advisory COMMENT so they see the bot's verdict.
+  if (EXTERNAL_ASSOCIATIONS.has(input.authorAssociation)) {
+    return 'COMMENT';
+  }
+
+  // Priority 6 (note: priorities 3-5 fall through to here when there
+  // are no findings): clean review on an org-trusted author → APPROVE.
+  // APPROVE flips the `required_approving_review_count: 1` ruleset and
+  // lets auto-merge fire under the canonical SPEC §7.2 ruleset.
+  if (input.criticalCount === 0 && input.minorCount === 0) {
+    return 'APPROVE';
+  }
+
+  // Priority 3 + 4: critical finding → gate on strictMode. Default
+  // `strictMode === undefined` → false (advisory-only). REQUEST_CHANGES
+  // blocks the PR until the author dismisses or fixes; we only honor
+  // it when the repo opted in.
+  if (input.criticalCount > 0) {
+    return input.strictMode === true ? 'REQUEST_CHANGES' : 'COMMENT';
+  }
+
+  // Priority 5: minor-only or preexisting-only finding → advisory
+  // COMMENT. We never REQUEST_CHANGES on a minor — those are noted,
+  // not blocking.
+  return 'COMMENT';
+}