clud-bug 0.6.34 → 0.7.0-rc.11

package/{lib/render-review.js → src/core/render-review.ts}

@@ -15,21 +15,52 @@
 // rendered shape is wrong). Centralising the markdown shape here means a
 // future format tweak edits one function rather than the prompt.
 
-const SEVERITY_EMOJI = { critical: '🔴', minor: '🟡', preexisting: '🟣' };
-const SEVERITY_LABEL = {
+import type {
+  DedicatedSection,
+  FindingSeverity,
+  PerSkillScanItem,
+  ReviewData,
+  ReviewFinding,
+  ReviewSummaryCounts,
+} from './review-schema.js';
+
+// Emoji constants: use explicit Unicode escape literals (`\u{HHHHH}`) so
+// every step of the TS→JS toolchain — tsc, vitest's transformer, the
+// publisher's tarball — emits the same byte sequence regardless of
+// editor encoding settings. Per SPEC §6 byte-identical contract:
+//   \u{1F534} = 🔴 (red circle, critical / "important")
+//   \u{1F7E1} = 🟡 (yellow circle, minor / "nit")
+//   \u{1F7E3} = 🟣 (purple circle, pre-existing)
+//   \u{1F41B} = 🐛 (bug, H2 anchor for `## 🐛 Clud Bug review`)
+const SEVERITY_EMOJI: Record<FindingSeverity, string> = {
+  critical: '\u{1F534}',
+  minor: '\u{1F7E1}',
+  preexisting: '\u{1F7E3}',
+};
+const SEVERITY_LABEL: Record<FindingSeverity, string> = {
   critical: 'important',
   minor: 'nit',
   preexisting: 'pre-existing',
 };
+// SEVERITY_LABEL is retained for callers that import the constant table
+// (the JS version exported it implicitly via module scope; keep the
+// export so future renderer extensions can reuse it).
+export { SEVERITY_LABEL };
+
+// Renderer input type — schema-aligned but defensively typed. The renderer
+// is the last line of defense against malformed JSON, so it accepts an
+// "unknown-ish" shape and degrades gracefully rather than throwing on
+// missing fields.
+type RenderReviewInput = Partial<ReviewData> & Record<string, unknown>;
 
 // Render the full summary comment markdown. `data` is the parsed JSON
-// matching the schema (see schema.js). Returns a string suitable for
-// `gh pr comment --body`.
-export function renderReview(data) {
+// matching the schema (see review-schema.ts). Returns a string suitable
+// for `gh pr comment --body`.
+export function renderReview(data: RenderReviewInput | null | undefined): string {
   if (!data || typeof data !== 'object') {
     throw new TypeError('renderReview: data must be an object');
   }
-  const out = [];
+  const out: string[] = [];
   out.push(renderHeader(data));
   out.push('');
   out.push(renderStatusLine(data.summary_counts));
@@ -77,9 +108,9 @@ export function renderReview(data) {
   return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '') + '\n';
 }
 
-function renderHeader(data) {
+function renderHeader(data: RenderReviewInput): string {
   const verdict = data.status_header;
-  const base = '## 🐛 Clud Bug review';
+  const base = '## \u{1F41B} Clud Bug review';
   if (verdict === 'critical findings') return `${base} — critical findings`;
   if (verdict === 'clean') return `${base} — clean`;
   // 'bare' (non-strict-mode default) OR an unexpected verdict — render
@@ -87,7 +118,7 @@ function renderHeader(data) {
   return base;
 }
 
-function renderStatusLine(counts) {
+function renderStatusLine(counts: ReviewSummaryCounts | undefined): string {
   const c = sanitizeCounts(counts);
   return `**This round:** ${c.critical} critical · ${c.minor} minor · ${c.resolved_from_prior} resolved from prior · ${c.still_open} still open`;
 }
@@ -95,13 +126,13 @@ function renderStatusLine(counts) {
 // Severity-emoji stats header. Counts pre-existing in 🟣 even though
 // it's not in summary_counts (the prompt counts pre-existing separately
 // in preexisting_findings.length).
-function renderStatsHeader(counts) {
+function renderStatsHeader(counts: ReviewSummaryCounts | undefined): string {
   const c = sanitizeCounts(counts);
-  return `Found: ${c.critical} 🔴 / ${c.minor} 🟡 / ${c.preexisting} 🟣`;
+  return `Found: ${c.critical} \u{1F534} / ${c.minor} \u{1F7E1} / ${c.preexisting} \u{1F7E3}`;
 }
 
-function renderPerSkillScan(scan) {
-  const out = ['### Per-skill scan'];
+function renderPerSkillScan(scan: PerSkillScanItem[] | undefined): string[] {
+  const out: string[] = ['### Per-skill scan'];
   if (!Array.isArray(scan) || scan.length === 0) {
     out.push('- (no skills loaded — review proceeded against the baseline.)');
     return out;
@@ -116,14 +147,14 @@ function renderPerSkillScan(scan) {
   return out;
 }
 
-function renderDedicatedSection(section) {
+function renderDedicatedSection(section: DedicatedSection | undefined): string[] {
   if (!section || typeof section !== 'object') return [];
   const name = String(section.section_name || '').trim();
   const skill = String(section.skill || '').trim();
   const header = skill && name
     ? `### ${name} [${skill}]`
     : `### ${name || skill || 'Dedicated section'}`;
-  const out = [header, ''];
+  const out: string[] = [header, ''];
   if (Array.isArray(section.findings) && section.findings.length > 0) {
     // Dedicated-section findings use the same emoji-prefix block.
     // Default severity for dedicated sections is "critical" — they're
@@ -135,9 +166,10 @@ function renderDedicatedSection(section) {
   return out;
 }
 
-function renderFindings(findings, severity) {
-  const emoji = SEVERITY_EMOJI[severity] || '🔴';
-  const out = [];
+function renderFindings(findings: ReviewFinding[] | undefined, severity: FindingSeverity): string[] {
+  const emoji = SEVERITY_EMOJI[severity] || SEVERITY_EMOJI.critical;
+  const out: string[] = [];
+  if (!Array.isArray(findings)) return out;
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue;
     const skill = String(f.skill || '').trim();
@@ -163,7 +195,7 @@ function renderFindings(findings, severity) {
   return out;
 }
 
-function renderSkillsReferenced(skills) {
+function renderSkillsReferenced(skills: string[] | undefined): string {
   if (!Array.isArray(skills) || skills.length === 0) {
     return 'Skills referenced: [none] — no installed skill applied to this diff.';
   }
@@ -172,12 +204,12 @@ function renderSkillsReferenced(skills) {
 
 // --- helpers ---
 
-function nonEmpty(arr) {
+function nonEmpty<T>(arr: T[] | undefined): arr is T[] {
   return Array.isArray(arr) && arr.length > 0;
 }
 
-function sanitizeCounts(counts) {
-  const c = counts && typeof counts === 'object' ? counts : {};
+function sanitizeCounts(counts: ReviewSummaryCounts | undefined): ReviewSummaryCounts {
+  const c = counts && typeof counts === 'object' ? counts : ({} as Partial<ReviewSummaryCounts>);
   return {
     critical: numOrZero(c.critical),
     minor: numOrZero(c.minor),
@@ -187,18 +219,18 @@ function sanitizeCounts(counts) {
   };
 }
 
-function numOrZero(v) {
+function numOrZero(v: unknown): number {
   const n = Number(v);
   return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
 }
 
-function locationAnchor(f) {
+function locationAnchor(f: ReviewFinding): string | null {
   const file = String(f.file || '').trim();
   if (!file) return null;
   const line = Number(f.line);
   return Number.isFinite(line) && line > 0 ? `${file}:${line}` : file;
 }
 
-function stripTrailingPunctuation(s) {
+function stripTrailingPunctuation(s: string): string {
   return s.replace(/[.!?]+$/, '');
 }

package/{lib/render.js → src/core/render.ts}

@@ -1,21 +1,32 @@
 import { readFile } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
 import { serializedReviewSchema } from './review-schema.js';
+import { PKG_VERSION } from './version.js';
 
 const PLACEHOLDER_RE = /\{\{([A-Z_]+)\}\}/g;
 
-// CLUD_BUG_VERSION (0.0.O / v0.6.22) — read from this package's
-// package.json at module-load time. The rendered workflow uses
+// CLUD_BUG_VERSION is baked at build time by scripts/gen-version.mjs into
+// src/core/version.ts (a git-ignored file, regenerated on every `npm run
+// build` via the "prebuild" hook). The rendered workflow uses
 // `npx --yes clud-bug@<CLUD_BUG_VERSION>` in the post-step that renders
 // structured output to markdown. Pinning to the version that ran
 // `clud-bug init` guarantees the renderer's output shape matches the
 // prompt's expectations.
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const PKG_VERSION = JSON.parse(
-  readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
-).version;
+//
+// History (v0.7.0-rc.5): previously this module did
+// `readFileSync(package.json)` at module-load. Under Next.js bundling in
+// clud-bug-app, `import.meta.url` resolved to `.next/server/...` not the
+// node_modules layout, so the fs call threw ENOENT (Phase 5.1 hotfix in
+// clud-bug-app PR #50 worked around with `serverExternalPackages`).
+// Codegen eliminates the runtime fs lookup entirely.
+
+// Public shape of the DEFAULTS map. Tests assert presence of CCA_VERSION
+// and CLUD_BUG_VERSION; REVIEW_SCHEMA is the serialized schema string the
+// templates inject via the {{REVIEW_SCHEMA}} placeholder.
+export interface RenderDefaults {
+  CCA_VERSION: string;
+  CLUD_BUG_VERSION: string;
+  REVIEW_SCHEMA: string;
+}
 
 // Default values for substitution tokens that every template uses.
 // Callers can override per-render by passing the same key in `vars`.
@@ -26,19 +37,26 @@ const PKG_VERSION = JSON.parse(
 // workflows mid-cycle. Bumping the pin requires a clud-bug release, which
 // makes the upgrade visible + lets users opt out by pinning a different
 // version in their own forked workflow.
-export const DEFAULTS = {
+export const DEFAULTS: RenderDefaults = {
   CCA_VERSION: 'v1.0.133',
   CLUD_BUG_VERSION: PKG_VERSION,
   REVIEW_SCHEMA: serializedReviewSchema(),
 };
 
+// Caller-supplied substitution vars: any extra placeholders the template
+// uses (REVIEW_PROMPT, PROJECT_DESCRIPTION, etc.). Values may be strings,
+// numbers, or anything String()-coercible. We accept a wider unknown type
+// because the JS callers freely pass numbers, arrays, etc., and the
+// String(value) coercion below handles them uniformly.
+export type RenderVars = Partial<RenderDefaults> & Record<string, unknown>;
+
 // Multi-line value substitution preserves YAML/Markdown indentation by
 // applying the placeholder line's leading whitespace to every
 // continuation line. Single-line values pass through unchanged so
 // existing tokens (CCA_VERSION, PROJECT_DESCRIPTION) keep current behavior.
-export function render(template, vars) {
-  const merged = { ...DEFAULTS, ...vars };
-  return template.replace(PLACEHOLDER_RE, (match, key, offset) => {
+export function render(template: string, vars: RenderVars): string {
+  const merged: Record<string, unknown> = { ...DEFAULTS, ...vars };
+  return template.replace(PLACEHOLDER_RE, (_match, key: string, offset: number) => {
     if (!(key in merged)) {
       throw new Error(`Missing template variable: ${key}`);
     }
@@ -48,7 +66,7 @@ export function render(template, vars) {
     }
     const lineStart = template.lastIndexOf('\n', offset - 1) + 1;
     const leadingWhitespaceMatch = template.slice(lineStart, offset).match(/^(\s*)/);
-    const indent = leadingWhitespaceMatch ? leadingWhitespaceMatch[1] : '';
+    const indent = leadingWhitespaceMatch ? (leadingWhitespaceMatch[1] ?? '') : '';
     return value
       .split('\n')
       .map((line, i) => (i === 0 || line === '' ? line : indent + line))
@@ -56,12 +74,12 @@ export function render(template, vars) {
   });
 }
 
-export async function renderFile(path, vars) {
+export async function renderFile(path: string, vars: RenderVars): Promise<string> {
   const tmpl = await readFile(path, 'utf8');
   return render(tmpl, vars);
 }
 
-export function pickTemplate(languages) {
+export function pickTemplate(languages: string[]): string {
   if (languages.includes('typescript') || languages.includes('javascript')) {
     return 'workflow-ts.yml.tmpl';
   }
@@ -74,7 +92,9 @@ export function pickTemplate(languages) {
 // Map a pickTemplate() filename to the language key that `reviewPrompt`
 // accepts. Keeps the mapping in one place so callers don't repeat the
 // switch when computing the REVIEW_PROMPT token.
-export function templateLanguage(tmplName) {
+export type TemplateLanguage = 'ts' | 'py' | 'generic';
+
+export function templateLanguage(tmplName: string): TemplateLanguage {
   if (tmplName === 'workflow-ts.yml.tmpl') return 'ts';
   if (tmplName === 'workflow-py.yml.tmpl') return 'py';
   return 'generic';

package/src/core/resolve-verifier.ts

@@ -0,0 +1,228 @@
+// Wave 5b — D.2.6 per-thread fix-verifier prompt + response parser.
+//
+// On every fix-push, the CLI verb asks Claude DIRECTLY for each prior
+// thread: "the prior reviewer said X. Here is the BEFORE / AFTER /
+// DIFF. Did the new commit address the original finding?" Verdicts:
+//
+//   ADDRESSED      — fix unambiguously resolves the original concern
+//   NOT_ADDRESSED  — original concern still applies
+//   UNCERTAIN      — can't tell; routes through human review
+//
+// This module is PURE — prompt builder + response parser. The actual
+// Anthropic Messages API call lives in `src/cli/main.ts::runResolveThreads`
+// (raw `fetch()` — no `@anthropic-ai/sdk` dep so the npm package stays
+// dep-light). Tests inject mocked verifier outcomes via the
+// `runAutoResolve` `verifier` callback in `./auto-resolve`.
+//
+// Ported from `clud-bug-app/lib/resolve-verifier.ts:162-260`. Differences:
+//   - No `@ai-sdk/anthropic` / `zod` dependency. Response parsing is
+//     hand-rolled JSON extraction with manual validation.
+//   - DROP `verifySingleFinding` (App-side IO entry point). The CLI
+//     verb owns the API call directly.
+//   - DROP `aggregateMultiPassVerdicts` — OSS is single-pass.
+
+import type { PriorFinding, VerifyOutcome } from './auto-resolve.js';
+
+// ---------------------------------------------------------------------------
+// System prompt — hard-coded, NOT derived from user content (anti-injection)
+// ---------------------------------------------------------------------------
+
+export const VERIFIER_SYSTEM = [
+  'You are a code-review fix verifier. Your only job is to decide whether a',
+  'specific code change addressed a specific prior reviewer concern.',
+  '',
+  'You are NOT writing a new code review. You are NOT looking for new issues.',
+  'You are NOT judging style. You are answering one question: did the change',
+  'between BEFORE and AFTER resolve the concern raised in the prior finding?',
+  '',
+  'Your verdict MUST be exactly one of: ADDRESSED, NOT_ADDRESSED, UNCERTAIN.',
+  '',
+  'Rules:',
+  '- ADDRESSED: the AFTER code unambiguously resolves the original concern.',
+  '  Partial fixes that leave the core problem unsolved are NOT ADDRESSED.',
+  '- NOT_ADDRESSED: the AFTER code still has the original problem, OR the',
+  '  change is unrelated to the concern, OR the change made the problem worse.',
+  '- UNCERTAIN: you cannot tell from the BEFORE / AFTER alone. Use this when',
+  '  the context is too narrow, the change is subtle and could go either way,',
+  '  or the concern depends on code you cannot see. Never guess — say',
+  '  UNCERTAIN when you would be guessing.',
+  '',
+  'Treat the prior finding as a black box: it might be wrong, but you are not',
+  'judging the finding. You are judging whether the new code resolves what it',
+  'said. If the finding asked for X and the change does X, mark ADDRESSED even',
+  'if X is unnecessary.',
+  '',
+  'Reply with a JSON object on a single line, no markdown fence, no surrounding',
+  'prose. Shape:',
+  '  {"verdict":"ADDRESSED"|"NOT_ADDRESSED"|"UNCERTAIN","rationale":"<one sentence>"}',
+  'Rationale MUST be one sentence, max 500 characters.',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Input shape
+// ---------------------------------------------------------------------------
+
+export interface VerifySingleFindingInput {
+  finding: PriorFinding;
+  /** Code at the finding's anchor BEFORE the fix-push. Empty when deleted. */
+  codeBefore: string;
+  /** Code at the finding's anchor AFTER the fix-push. Empty when deleted. */
+  codeAfter: string;
+  /** Optional: unified-diff hunk at the anchor. */
+  diffAtAnchor?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder — pure (no env, no Date.now, no timestamps)
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the user-facing prompt body.
+ *
+ * Prompt-injection defense:
+ *   - System prompt is module-scope, NOT derived from user content.
+ *   - User content (finding body, code, diff) is wrapped in fence-
+ *     delimited blocks with clear labels. The model knows the
+ *     boundaries.
+ *   - Output is parsed with `parseVerifierResponse` which validates
+ *     the verdict against a fixed enum + caps rationale at 500 chars.
+ *     A model coerced to emit "ADDRESSED!" outside the JSON shape
+ *     gets routed to UNCERTAIN+api-error (fail-closed).
+ */
+export function buildVerifierPrompt(input: VerifySingleFindingInput): string {
+  const f = input.finding;
+  const anchor = f.line !== undefined ? `${f.file}:${f.line}` : f.file;
+  const sev = f.severity === 'critical' ? '🔴 critical' : '🟡 minor';
+
+  const parts: string[] = [];
+  parts.push(
+    `A prior code review (skill: \`${f.skill}\`, severity: ${sev}) flagged \`${anchor}\` with this finding:`,
+  );
+  parts.push('');
+  parts.push('```');
+  parts.push('PRIOR FINDING:');
+  parts.push(f.body);
+  parts.push('```');
+  parts.push('');
+  parts.push(
+    'The PR author has since pushed a new commit. Here is the code BEFORE and AFTER:',
+  );
+  parts.push('');
+  parts.push('```');
+  parts.push('BEFORE:');
+  parts.push(input.codeBefore || '(empty — file did not exist or was empty)');
+  parts.push('```');
+  parts.push('');
+  parts.push('```');
+  parts.push('AFTER:');
+  parts.push(input.codeAfter || '(empty — file was deleted or emptied)');
+  parts.push('```');
+
+  if (input.diffAtAnchor) {
+    parts.push('');
+    parts.push('```');
+    parts.push('DIFF AT ANCHOR:');
+    parts.push(input.diffAtAnchor);
+    parts.push('```');
+  }
+
+  parts.push('');
+  parts.push('Did this change ADDRESS the original finding?');
+  parts.push(
+    'Reply with the JSON object only — single line, no markdown fence, no prose.',
+  );
+
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Response parser — extracts `{verdict, rationale}` from the model text
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses the model's text response into a `VerifyOutcome`. Fail-closed:
+ * any malformed input → UNCERTAIN+api-error with the failure mode in
+ * the rationale, so the caller's auto-resolve rules route through
+ * human review (never silently ADDRESSED).
+ *
+ * Tolerates:
+ *   - Leading/trailing whitespace
+ *   - The model wrapping the JSON in ```json fences (strips them)
+ *   - Extra fields (ignored)
+ *
+ * Rejects:
+ *   - Empty / non-string input
+ *   - Non-JSON / malformed JSON
+ *   - Missing or non-string `verdict`
+ *   - `verdict` not in the allowed enum
+ *   - Missing or empty `rationale`
+ *   - `rationale` longer than 500 chars (caps at 500 in the outcome)
+ */
+export function parseVerifierResponse(text: unknown): VerifyOutcome {
+  if (typeof text !== 'string' || !text.trim()) {
+    return {
+      verdict: 'UNCERTAIN',
+      source: 'api-error',
+      rationale: 'verifier returned empty or non-string response',
+    };
+  }
+
+  // Strip optional ```json … ``` or ``` … ``` fence.
+  let body = text.trim();
+  const fenced = body.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+  if (fenced) body = fenced[1]!.trim();
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (err) {
+    return {
+      verdict: 'UNCERTAIN',
+      source: 'api-error',
+      rationale: `verifier response was not valid JSON: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      verdict: 'UNCERTAIN',
+      source: 'api-error',
+      rationale: 'verifier response was not a JSON object',
+    };
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const verdict = obj.verdict;
+  const rationale = obj.rationale;
+
+  if (
+    verdict !== 'ADDRESSED' &&
+    verdict !== 'NOT_ADDRESSED' &&
+    verdict !== 'UNCERTAIN'
+  ) {
+    return {
+      verdict: 'UNCERTAIN',
+      source: 'api-error',
+      rationale: `verifier emitted unknown verdict: ${JSON.stringify(verdict)}`,
+    };
+  }
+
+  if (typeof rationale !== 'string' || !rationale.trim()) {
+    return {
+      verdict: 'UNCERTAIN',
+      source: 'api-error',
+      rationale: 'verifier response missing rationale',
+    };
+  }
+
+  // Cap rationale at 500 chars per the system prompt's contract.
+  const trimmed = rationale.trim().slice(0, 500);
+
+  return {
+    verdict,
+    rationale: trimmed,
+    source: 'model',
+  };
+}