supipowers 1.2.6 → 1.5.0

package/src/review/prompts/review-output-schema.md

@@ -0,0 +1,38 @@
+{
+  "findings": [
+    {
+      "id": "F001",
+      "title": "Missing null check on user input",
+      "severity": "error",
+      "priority": "P1",
+      "confidence": 0.85,
+      "file": "src/auth.ts",
+      "lineStart": 42,
+      "lineEnd": 45,
+      "body": "The code dereferences `userId` without validating that it exists.",
+      "suggestion": "Add a guard that rejects nullish `userId` before use.",
+      "agent": "correctness",
+      "validation": {
+        "verdict": "confirmed",
+        "reasoning": "The null guard is missing at the referenced call site.",
+        "validatedBy": "validator",
+        "validatedAt": "2026-04-11T14:30:22.000Z"
+      }
+    },
+    {
+      "id": "F002",
+      "title": "Location could not be determined confidently",
+      "severity": "warning",
+      "priority": "P3",
+      "confidence": 0.32,
+      "file": null,
+      "lineStart": null,
+      "lineEnd": null,
+      "body": "Use null for unknown location fields instead of guessing.",
+      "suggestion": null,
+      "agent": "correctness"
+    }
+  ],
+  "summary": "Found 2 review findings.",
+  "status": "failed"
+}

package/src/review/prompts/single-review.md

@@ -0,0 +1,53 @@
+You are running a structured code review pass.
+
+Review level: {{level}}
+Scope: {{scope.description}}
+Reviewable files: {{scope.stats.filesChanged}}
+Excluded files: {{scope.stats.excludedFiles}}
+Additions: {{scope.stats.additions}}
+Deletions: {{scope.stats.deletions}}
+{{#if scope.baseBranch}}
+Base branch: {{scope.baseBranch}}
+{{/if}}
+{{#if scope.commit}}
+Commit: {{scope.commit}}
+{{/if}}
+{{#if scope.customInstructions}}
+Custom review focus:
+{{scope.customInstructions}}
+{{/if}}
+
+Files in scope:
+{{#each scope.files}}
+- {{path}} (+{{additions}} -{{deletions}})
+{{/each}}
+
+Review priorities:
+{{#if isQuick}}
+- Focus on the highest-signal correctness, security, and maintainability issues.
+- Prefer fewer, higher-confidence findings over exhaustive commentary.
+{{/if}}
+{{#if isDeep}}
+- Review deeply for correctness, edge cases, security, maintainability, validation, and failure handling.
+- Surface subtle issues that could fail in production.
+{{/if}}
+
+Return JSON only matching this schema:
+```json
+{{outputSchema}}
+```
+
+Rules:
+- Tell the truth. If file, line, or suggestion is unknown, use `null` instead of guessing.
+- Every finding must be actionable and grounded in the diff.
+- `confidence` must be between 0 and 1.
+- Use priority `P0`..`P3`, where `P0` is critical and `P3` is low urgency.
+- Use `status: "failed"` when you found actionable issues.
+- Use `status: "passed"` only when no actionable issues remain.
+- Use `status: "blocked"` only if you cannot complete a truthful review.
+- Do not wrap the JSON in markdown fences.
+
+Unified diff:
+```diff
+{{scope.diff}}
+```

package/src/review/prompts/validation-review.md

@@ -0,0 +1,30 @@
+You are validating prior review findings.
+
+Read the actual code before deciding. Do not trust the previous reviewer blindly.
+Use the available tools to inspect the referenced files and surrounding context.
+
+Validation scope: {{scope.description}}
+Validator name: {{validatorName}}
+Validation timestamp: {{validatedAt}}
+
+Findings to validate:
+```json
+{{findingsJson}}
+```
+
+Return JSON only matching this schema:
+```json
+{{outputSchema}}
+```
+
+Rules:
+- Return the same finding ids. Do not invent new findings.
+- Preserve the original finding fields and add a `validation` object to each finding.
+- Every `validation` must include `verdict`, `reasoning`, `validatedBy`, and `validatedAt`.
+- Set `validatedBy` to `{{validatorName}}`.
+- Set `validatedAt` to `{{validatedAt}}`.
+- Use `confirmed` only when the issue is real in the current code.
+- Use `rejected` when the finding does not hold up.
+- Use `uncertain` when the evidence is inconclusive or the finding lacks enough location detail.
+- Prefer rejecting weak findings over performative agreement.
+- Do not wrap the JSON in markdown fences.

package/src/review/runner.ts

@@ -0,0 +1,128 @@
+import reviewOutputSchema from "./prompts/review-output-schema.md" with { type: "text" };
+import singleReviewPrompt from "./prompts/single-review.md" with { type: "text" };
+import type { GateExecutionContext, ReviewLevel, ReviewOutput, ReviewScope } from "../types.js";
+import { explainReviewOutputFailure, parseReviewOutput, runWithOutputValidation } from "./output.js";
+import { renderReviewTemplate } from "./template.js";
+
+export type SingleReviewLevel = Extract<ReviewLevel, "quick" | "deep">;
+
+export interface SingleReviewRunnerInput {
+  cwd: string;
+  scope: ReviewScope;
+  level: SingleReviewLevel;
+  createAgentSession: GateExecutionContext["createAgentSession"];
+  model?: string;
+  thinkingLevel?: string | null;
+  timeoutMs?: number;
+}
+
+export interface SingleReviewRunResult {
+  output: ReviewOutput;
+  attempts: number;
+  rawOutputs: string[];
+}
+
+function createFallbackFindingId(index: number): string {
+  return `F${String(index + 1).padStart(3, "0")}`;
+}
+
+function normalizeReviewStatus(findingsCount: number, status: ReviewOutput["status"]): ReviewOutput["status"] {
+  if (status === "blocked") {
+    return "blocked";
+  }
+  if (findingsCount > 0) {
+    return "failed";
+  }
+  return "passed";
+}
+
+export function normalizeReviewOutput(output: ReviewOutput): ReviewOutput {
+  const seenIds = new Set<string>();
+  const findings = output.findings.map((finding, index) => {
+    let id = finding.id.trim();
+    if (!id || seenIds.has(id)) {
+      id = createFallbackFindingId(index);
+    }
+    seenIds.add(id);
+
+    const normalizedFile = finding.file?.trim() ? finding.file.trim() : null;
+    const normalizedLineStart = normalizedFile && finding.lineStart !== null ? finding.lineStart : null;
+    const normalizedLineEnd =
+      normalizedLineStart === null
+        ? null
+        : finding.lineEnd ?? normalizedLineStart;
+
+    return {
+      ...finding,
+      id,
+      title: finding.title.trim(),
+      file: normalizedFile,
+      lineStart: normalizedLineStart,
+      lineEnd: normalizedLineEnd,
+    };
+  });
+
+  return {
+    ...output,
+    findings,
+    status: normalizeReviewStatus(findings.length, output.status),
+  };
+}
+
+export function buildSingleReviewPrompt(scope: ReviewScope, level: SingleReviewLevel): string {
+  return renderReviewTemplate(singleReviewPrompt, {
+    level,
+    scope,
+    isQuick: level === "quick",
+    isDeep: level === "deep",
+    outputSchema: reviewOutputSchema.trim(),
+  });
+}
+
+export async function runSingleReview(input: SingleReviewRunnerInput): Promise<SingleReviewRunResult> {
+  const result = await runWithOutputValidation(input.createAgentSession, {
+    cwd: input.cwd,
+    prompt: buildSingleReviewPrompt(input.scope, input.level),
+    schema: reviewOutputSchema.trim(),
+    parse(raw) {
+      const output = parseReviewOutput(raw);
+      return {
+        output,
+        error: output ? null : explainReviewOutputFailure(raw),
+      };
+    },
+    model: input.model,
+    thinkingLevel: input.thinkingLevel ?? null,
+    timeoutMs: input.timeoutMs ?? 120_000,
+  });
+
+  if (result.status === "blocked") {
+    return {
+      output: {
+        findings: [],
+        summary: result.error,
+        status: "blocked",
+      },
+      attempts: result.attempts,
+      rawOutputs: result.rawOutputs,
+    };
+  }
+
+  return {
+    output: normalizeReviewOutput(result.output),
+    attempts: result.attempts,
+    rawOutputs: [result.rawOutput],
+  };
+}
+
+export async function runQuickReview(
+  input: Omit<SingleReviewRunnerInput, "level">,
+): Promise<SingleReviewRunResult> {
+  return runSingleReview({ ...input, level: "quick" });
+}
+
+export async function runDeepReview(
+  input: Omit<SingleReviewRunnerInput, "level">,
+): Promise<SingleReviewRunResult> {
+  return runSingleReview({ ...input, level: "deep" });
+}

package/src/review/scope.ts

@@ -0,0 +1,353 @@
+import type { Platform, PlatformContext } from "../platform/types.js";
+import type { ReviewScope, ReviewScopeFile, ReviewScopeStats } from "../types.js";
+
+interface ExcludedReviewScopeFile {
+  path: string;
+  reason: string;
+  additions: number;
+  deletions: number;
+}
+
+export interface ParsedReviewDiff {
+  files: ReviewScopeFile[];
+  excluded: ExcludedReviewScopeFile[];
+  stats: ReviewScopeStats;
+}
+
+export const EXCLUDED_PATTERNS: Array<{ pattern: RegExp; reason: string }> = [
+  { pattern: /\.lock$/, reason: "lock file" },
+  { pattern: /-lock\.(json|yaml|yml)$/, reason: "lock file" },
+  { pattern: /package-lock\.json$/, reason: "lock file" },
+  { pattern: /yarn\.lock$/, reason: "lock file" },
+  { pattern: /pnpm-lock\.yaml$/, reason: "lock file" },
+  { pattern: /Cargo\.lock$/, reason: "lock file" },
+  { pattern: /Gemfile\.lock$/, reason: "lock file" },
+  { pattern: /poetry\.lock$/, reason: "lock file" },
+  { pattern: /composer\.lock$/, reason: "lock file" },
+  { pattern: /flake\.lock$/, reason: "lock file" },
+  { pattern: /\.min\.(js|css)$/, reason: "minified" },
+  { pattern: /\.generated\./, reason: "generated" },
+  { pattern: /\.snap$/, reason: "snapshot" },
+  { pattern: /\.map$/, reason: "source map" },
+  { pattern: /^dist\//, reason: "build output" },
+  { pattern: /^build\//, reason: "build output" },
+  { pattern: /^out\//, reason: "build output" },
+  { pattern: /node_modules\//, reason: "vendor" },
+  { pattern: /vendor\//, reason: "vendor" },
+  { pattern: /\.(png|jpg|jpeg|gif|ico|webp|avif)$/i, reason: "image" },
+  { pattern: /\.(woff|woff2|ttf|eot|otf)$/i, reason: "font" },
+  { pattern: /\.(pdf|zip|tar|gz|rar|7z)$/i, reason: "binary" },
+];
+
+function getExclusionReason(filePath: string): string | undefined {
+  for (const { pattern, reason } of EXCLUDED_PATTERNS) {
+    if (pattern.test(filePath)) {
+      return reason;
+    }
+  }
+
+  return undefined;
+}
+
+function buildEmptyStats(): ReviewScopeStats {
+  return {
+    filesChanged: 0,
+    excludedFiles: 0,
+    additions: 0,
+    deletions: 0,
+  };
+}
+
+export function parseReviewDiff(diffOutput: string): ParsedReviewDiff {
+  if (!diffOutput.trim()) {
+    return {
+      files: [],
+      excluded: [],
+      stats: buildEmptyStats(),
+    };
+  }
+
+  const files: ReviewScopeFile[] = [];
+  const excluded: ExcludedReviewScopeFile[] = [];
+  let additions = 0;
+  let deletions = 0;
+
+  const chunks = diffOutput.split(/^diff --git /m).filter(Boolean);
+  for (const chunk of chunks) {
+    const headerMatch = chunk.match(/^a\/(.+?) b\/(.+)/);
+    if (!headerMatch) {
+      continue;
+    }
+
+    const filePath = headerMatch[2];
+    let fileAdditions = 0;
+    let fileDeletions = 0;
+
+    for (const line of chunk.split("\n")) {
+      if (line.startsWith("+") && !line.startsWith("+++")) {
+        fileAdditions += 1;
+      } else if (line.startsWith("-") && !line.startsWith("---")) {
+        fileDeletions += 1;
+      }
+    }
+
+    const reason = getExclusionReason(filePath);
+    if (reason) {
+      excluded.push({
+        path: filePath,
+        reason,
+        additions: fileAdditions,
+        deletions: fileDeletions,
+      });
+      continue;
+    }
+
+    files.push({
+      path: filePath,
+      additions: fileAdditions,
+      deletions: fileDeletions,
+      diff: `diff --git ${chunk}`,
+    });
+    additions += fileAdditions;
+    deletions += fileDeletions;
+  }
+
+  return {
+    files,
+    excluded,
+    stats: {
+      filesChanged: files.length,
+      excludedFiles: excluded.length,
+      additions,
+      deletions,
+    },
+  };
+}
+
+function createScope(
+  mode: ReviewScope["mode"],
+  description: string,
+  diff: string,
+  overrides: Partial<ReviewScope> = {},
+): ReviewScope {
+  const parsed = parseReviewDiff(diff);
+  return {
+    mode,
+    description,
+    diff,
+    files: parsed.files,
+    stats: parsed.stats,
+    ...overrides,
+  };
+}
+
+async function execGit(
+  platform: Pick<Platform, "exec">,
+  cwd: string,
+  args: string[],
+  allowedExitCodes: number[] = [0],
+): Promise<string> {
+  let result;
+
+  try {
+    result = await platform.exec("git", args, { cwd });
+  } catch (error) {
+    throw new Error(error instanceof Error ? error.message : `git ${args.join(" ")} failed.`);
+  }
+
+  if (!allowedExitCodes.includes(result.code)) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `git ${args.join(" ")} failed with exit code ${result.code}`;
+    throw new Error(detail);
+  }
+
+  return result.stdout;
+}
+
+async function listUntrackedFiles(platform: Pick<Platform, "exec">, cwd: string): Promise<string[]> {
+  const output = await execGit(platform, cwd, ["ls-files", "--others", "--exclude-standard"]);
+  return output
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
+
+const NULL_DEVICE = process.platform === "win32" ? "NUL" : "/dev/null";
+
+async function buildUntrackedDiff(platform: Pick<Platform, "exec">, cwd: string): Promise<string> {
+  const untracked = await listUntrackedFiles(platform, cwd);
+  if (untracked.length === 0) {
+    return "";
+  }
+
+  const diffs = await Promise.all(
+    untracked.map((filePath) =>
+      execGit(platform, cwd, ["diff", "--no-index", "--", NULL_DEVICE, filePath], [0, 1]).catch(() => ""),
+    ),
+  );
+
+  return diffs.filter((chunk) => chunk.trim().length > 0).join("\n");
+}
+
+function ensureReviewableScope(scope: ReviewScope, message: string): ReviewScope {
+  if (!scope.diff.trim()) {
+    throw new Error("No diff content found for the selected scope.");
+  }
+
+  if (scope.files.length === 0) {
+    throw new Error(message);
+  }
+
+  return scope;
+}
+
+export async function listReviewBaseBranches(platform: Pick<Platform, "exec">, cwd: string): Promise<string[]> {
+  const output = await execGit(platform, cwd, ["branch", "--all", "--format=%(refname:short)"]);
+  return [...new Set(
+    output
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .filter((line) => !line.endsWith("/HEAD")),
+  )].sort();
+}
+
+export async function getCurrentReviewBranch(platform: Pick<Platform, "exec">, cwd: string): Promise<string> {
+  const branch = (await execGit(platform, cwd, ["branch", "--show-current"])).trim();
+  return branch || "HEAD";
+}
+
+export async function listRecentReviewCommits(
+  platform: Pick<Platform, "exec">,
+  cwd: string,
+  count = 20,
+): Promise<string[]> {
+  const output = await execGit(platform, cwd, ["log", "--oneline", `-${count}`]);
+  return output
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
+
+export async function loadPullRequestScope(
+  platform: Pick<Platform, "exec">,
+  cwd: string,
+  baseBranch: string,
+  currentBranch?: string,
+): Promise<ReviewScope> {
+  const branch = currentBranch ?? await getCurrentReviewBranch(platform, cwd);
+  const diff = await execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary", `${baseBranch}...${branch}`]);
+  const scope = createScope(
+    "pull-request",
+    `Reviewing changes between ${baseBranch} and ${branch}`,
+    diff,
+    { baseBranch },
+  );
+  return ensureReviewableScope(scope, "No reviewable files remain after filtering PR-style changes.");
+}
+
+export async function loadUncommittedScope(platform: Pick<Platform, "exec">, cwd: string): Promise<ReviewScope> {
+  const [unstaged, staged, untracked] = await Promise.all([
+    execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary"]),
+    execGit(platform, cwd, ["diff", "--cached", "--no-ext-diff", "--binary"]),
+    buildUntrackedDiff(platform, cwd),
+  ]);
+  const diff = [unstaged, staged, untracked].filter((chunk) => chunk.trim().length > 0).join("\n");
+  const scope = createScope("uncommitted", "Reviewing uncommitted changes", diff);
+  return ensureReviewableScope(scope, "No reviewable files remain after filtering uncommitted changes.");
+}
+
+export async function loadCommitScope(
+  platform: Pick<Platform, "exec">,
+  cwd: string,
+  commit: string,
+): Promise<ReviewScope> {
+  const diff = await execGit(platform, cwd, ["show", "--format=", "--no-ext-diff", "--binary", commit]);
+  const scope = createScope("commit", `Reviewing commit ${commit}`, diff, { commit });
+  return ensureReviewableScope(scope, "No reviewable files remain after filtering commit changes.");
+}
+
+export async function loadCustomReviewScope(
+  platform: Pick<Platform, "exec">,
+  cwd: string,
+  instructions: string,
+): Promise<ReviewScope> {
+  let diff = "";
+
+  try {
+    diff = await execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary", "HEAD"]);
+  } catch {
+    diff = "";
+  }
+
+  return createScope(
+    "custom",
+    `Custom review: ${instructions.slice(0, 60)}`,
+    diff,
+    { customInstructions: instructions },
+  );
+}
+
+export async function selectReviewScope(
+  platform: Pick<Platform, "exec">,
+  ctx: Pick<PlatformContext, "cwd" | "ui">,
+): Promise<ReviewScope | null> {
+  const choice = await ctx.ui.select(
+    "What should /supi:review inspect?",
+    [
+      "PR-style — compare current branch against a base branch",
+      "Uncommitted changes — staged, unstaged, and untracked",
+      "Specific commit — review a recent commit",
+      "Custom instructions — describe the review focus",
+    ],
+    { helpText: "Select the review scope · Esc to cancel" },
+  );
+
+  if (!choice) {
+    return null;
+  }
+
+  if (choice.startsWith("PR-style")) {
+    const branches = await listReviewBaseBranches(platform, ctx.cwd);
+    if (branches.length === 0) {
+      throw new Error("No git branches found.");
+    }
+    const selected = await ctx.ui.select("Base branch", branches, {
+      helpText: "Select the branch to compare against · Esc to cancel",
+    });
+    if (!selected) {
+      return null;
+    }
+    return loadPullRequestScope(platform, ctx.cwd, selected);
+  }
+
+  if (choice.startsWith("Uncommitted changes")) {
+    return loadUncommittedScope(platform, ctx.cwd);
+  }
+
+  if (choice.startsWith("Specific commit")) {
+    const commits = await listRecentReviewCommits(platform, ctx.cwd);
+    if (commits.length === 0) {
+      throw new Error("No commits found.");
+    }
+    const selected = await ctx.ui.select("Commit to review", commits, {
+      helpText: "Select a recent commit · Esc to cancel",
+    });
+    if (!selected) {
+      return null;
+    }
+    const commit = selected.split(" ")[0]?.trim();
+    if (!commit) {
+      throw new Error("Could not determine the selected commit hash.");
+    }
+    return loadCommitScope(platform, ctx.cwd, commit);
+  }
+
+  const instructions = await ctx.ui.input("Custom review focus", {
+    helpText: "Describe what the review should pay special attention to.",
+    placeholder: "Example: focus on auth flows, data races, and unsafe error handling",
+  });
+  if (!instructions?.trim()) {
+    return null;
+  }
+  return loadCustomReviewScope(platform, ctx.cwd, instructions.trim());
+}

package/src/review/template.ts

@@ -0,0 +1,15 @@
+import Handlebars from "handlebars";
+
+const handlebars = Handlebars.create();
+
+handlebars.registerHelper("json", (value: unknown): string => JSON.stringify(value, null, 2));
+handlebars.registerHelper("joinLines", (value: unknown): string => {
+  if (!Array.isArray(value)) {
+    return "";
+  }
+  return value.join("\n");
+});
+
+export function renderReviewTemplate(template: string, context: Record<string, unknown> = {}): string {
+  return handlebars.compile(template, { noEscape: true })(context);
+}