supipowers 1.2.6 → 1.5.0

package/src/quality/gates/ai-review.ts

@@ -0,0 +1,129 @@
+import { stripMarkdownCodeFence } from "../../text.js";
+import { runStructuredAgentSession } from "../ai-session.js";
+import type {
+  GateExecutionContext,
+  GateIssue,
+  GateStatus,
+} from "../../types.js";
+
+export type AiReviewDepth = "quick" | "deep";
+
+export interface AiReviewResult {
+  status: Extract<GateStatus, "passed" | "failed" | "blocked">;
+  summary: string;
+  issues: GateIssue[];
+  metadata?: Record<string, unknown>;
+}
+
+interface AiReviewPayload {
+  summary: string;
+  issues: GateIssue[];
+  recommendedStatus: AiReviewResult["status"];
+}
+
+export function buildAiReviewPrompt(
+  scopeFiles: string[],
+  fileScope: "changed-files" | "all-files",
+  depth: AiReviewDepth,
+): string {
+  const scopeLabel = fileScope === "changed-files" ? "changed files" : "repository files";
+  const files = scopeFiles.length > 0 ? scopeFiles.map((file) => `- ${file}`).join("\n") : "- (no files reported)";
+  const depthInstructions =
+    depth === "quick"
+      ? "Focus on obvious correctness, security, and maintainability issues."
+      : "Review deeply for correctness, edge cases, security, maintainability, and missing validation.";
+
+  return [
+    "You are running a structured code review pass.",
+    `Scope: ${scopeLabel}.`,
+    `Depth: ${depth}.`,
+    depthInstructions,
+    "",
+    "Files in scope:",
+    files,
+    "",
+    "Return JSON only with this exact shape:",
+    '{"summary":"string","issues":[{"severity":"error|warning|info","message":"string","file":"optional string","line":"optional number","detail":"optional string"}],"recommendedStatus":"passed|failed|blocked"}',
+    "",
+    "Rules:",
+    "- recommendedStatus must be 'failed' when you found actionable issues.",
+    "- recommendedStatus may be 'blocked' only if review could not be completed truthfully.",
+    "- Do not wrap the JSON in markdown fences.",
+  ].join("\n");
+}
+
+function isGateIssue(value: unknown): value is GateIssue {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as GateIssue).severity !== undefined &&
+    ["error", "warning", "info"].includes((value as GateIssue).severity) &&
+    typeof (value as GateIssue).message === "string" &&
+    ((value as GateIssue).file === undefined || typeof (value as GateIssue).file === "string") &&
+    ((value as GateIssue).line === undefined || typeof (value as GateIssue).line === "number") &&
+    ((value as GateIssue).detail === undefined || typeof (value as GateIssue).detail === "string")
+  );
+}
+
+function parseAiReviewPayload(raw: string): AiReviewPayload | null {
+  try {
+    const parsed = JSON.parse(stripMarkdownCodeFence(raw)) as Record<string, unknown>;
+
+    if (
+      typeof parsed.summary !== "string" ||
+      !Array.isArray(parsed.issues) ||
+      !parsed.issues.every(isGateIssue) ||
+      !["passed", "failed", "blocked"].includes(String(parsed.recommendedStatus))
+    ) {
+      return null;
+    }
+
+    return {
+      summary: parsed.summary,
+      issues: parsed.issues,
+      recommendedStatus: parsed.recommendedStatus as AiReviewPayload["recommendedStatus"],
+    };
+  } catch {
+    return null;
+  }
+}
+
+function buildBlockedResult(summary: string, metadata?: Record<string, unknown>): AiReviewResult {
+  return {
+    status: "blocked",
+    summary,
+    issues: [],
+    ...(metadata ? { metadata } : {}),
+  };
+}
+
+export async function runAiReview(
+  context: Pick<GateExecutionContext, "cwd" | "scopeFiles" | "fileScope" | "createAgentSession" | "reviewModel">,
+  depth: AiReviewDepth,
+): Promise<AiReviewResult> {
+  const sessionResult = await runStructuredAgentSession(context.createAgentSession, {
+    cwd: context.cwd,
+    prompt: buildAiReviewPrompt(context.scopeFiles, context.fileScope, depth),
+    model: context.reviewModel?.model,
+    thinkingLevel: context.reviewModel?.thinkingLevel ?? null,
+    timeoutMs: 120_000,
+  });
+
+  if (sessionResult.status !== "ok") {
+    return buildBlockedResult(sessionResult.error);
+  }
+
+  const parsed = parseAiReviewPayload(sessionResult.finalText);
+  if (!parsed) {
+    return buildBlockedResult("AI review returned invalid JSON.", {
+      rawOutput: sessionResult.finalText,
+    });
+  }
+
+  return {
+    status: parsed.recommendedStatus,
+    summary: parsed.summary,
+    issues: parsed.issues,
+    metadata: { depth },
+  };
+}

package/src/quality/gates/build.ts

@@ -0,0 +1,8 @@
+import { createCommandGate } from "./command.js";
+
+export const buildGate = createCommandGate({
+  id: "build",
+  label: "Build",
+  description: "Runs the project's configured build command.",
+  scriptNames: ["build", "build:check"],
+});

package/src/quality/gates/command.ts

@@ -0,0 +1,150 @@
+import type {
+  CommandGateConfig,
+  CommandGateId,
+  GateDefinition,
+  GateIssue,
+  ProjectFacts,
+} from "../../types.js";
+import { GATE_CONFIG_SCHEMAS } from "../registry.js";
+
+interface DetectedCommand {
+  command: string;
+  confidence: "high" | "medium";
+  reason: string;
+}
+
+interface CommandGateOptions<TGateId extends CommandGateId> {
+  id: TGateId;
+  label: string;
+  description: string;
+  scriptNames: string[];
+  matchScript?: (name: string, command: string) => boolean;
+}
+
+function normalizeCommand(command: string | undefined): string | null {
+  const trimmed = command?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function detectScriptByName(
+  projectFacts: ProjectFacts,
+  options: CommandGateOptions<CommandGateId>,
+): DetectedCommand | null {
+  for (const scriptName of options.scriptNames) {
+    const command = normalizeCommand(projectFacts.packageScripts[scriptName]);
+    if (!command) {
+      continue;
+    }
+
+    // When a safety filter is defined, apply it even for exact name matches.
+    // A repo with `"lint": "eslint . --fix"` must not be auto-configured.
+    if (options.matchScript && !options.matchScript(scriptName, command)) {
+      continue;
+    }
+
+    return {
+      command,
+      confidence: "high",
+      reason: `Detected package.json ${scriptName} script.`,
+    };
+  }
+
+  return null;
+}
+
+function detectScriptByHeuristic(
+  projectFacts: ProjectFacts,
+  options: CommandGateOptions<CommandGateId>,
+): DetectedCommand | null {
+  if (!options.matchScript) {
+    return null;
+  }
+
+  for (const [scriptName, rawCommand] of Object.entries(projectFacts.packageScripts)) {
+    const command = normalizeCommand(rawCommand);
+    if (!command || !options.matchScript(scriptName, command)) {
+      continue;
+    }
+
+    return {
+      command,
+      confidence: "medium",
+      reason: `Detected package.json ${scriptName} script by command heuristic.`,
+    };
+  }
+
+  return null;
+}
+
+function createFailureDetail(label: string, exitCode: number, stdout: string, stderr: string): string {
+  return stderr.trim() || stdout.trim() || `${label} command exited with code ${exitCode}.`;
+}
+
+function createFailureIssue(label: string, detail: string): GateIssue {
+  return {
+    severity: "error",
+    message: `${label} command failed.`,
+    detail,
+  };
+}
+
+export function createCommandGate<TGateId extends CommandGateId>(
+  options: CommandGateOptions<TGateId>,
+): GateDefinition<CommandGateConfig> {
+  return {
+    id: options.id,
+    description: options.description,
+    configSchema: GATE_CONFIG_SCHEMAS[options.id],
+    detect(projectFacts) {
+      const detected =
+        detectScriptByName(projectFacts, options) ?? detectScriptByHeuristic(projectFacts, options);
+      if (!detected) {
+        return null;
+      }
+
+      return {
+        suggestedConfig: {
+          enabled: true,
+          command: detected.command,
+        },
+        confidence: detected.confidence,
+        reason: detected.reason,
+      };
+    },
+    async run(context, config) {
+      if (config.enabled !== true || typeof config.command !== "string") {
+        throw new Error(`${options.id} gate requires an enabled config with a command.`);
+      }
+
+      const result = await context.execShell(config.command, {
+        cwd: context.cwd,
+        timeout: 120_000,
+      });
+
+      if (result.code === 0) {
+        return {
+          gate: options.id,
+          status: "passed",
+          summary: `${options.label} passed.`,
+          issues: [],
+          metadata: {
+            command: config.command,
+            exitCode: result.code,
+          },
+        };
+      }
+
+      const detail = createFailureDetail(options.label, result.code, result.stdout, result.stderr);
+      return {
+        gate: options.id,
+        status: "failed",
+        summary: `${options.label} failed.`,
+        issues: [createFailureIssue(options.label, detail)],
+        metadata: {
+          command: config.command,
+          exitCode: result.code,
+        },
+      };
+    },
+  };
+}

package/src/quality/gates/format.ts

@@ -0,0 +1,28 @@
+import { createCommandGate } from "./command.js";
+
+function isSafeFormatCheckCommand(name: string, command: string): boolean {
+  const normalizedName = name.toLowerCase();
+  const normalized = command.toLowerCase();
+  const isSingleCommand = !normalized.includes("&&") && !normalized.includes("||");
+  const hasCheckSignal =
+    normalized.includes("--check") ||
+    normalized.includes("--list-different") ||
+    normalized.includes("prettier -c") ||
+    normalized.includes("dprint check") ||
+    normalized.includes("biome check");
+  const isMutating = normalized.includes("--write") || normalized.includes("eslint --fix");
+
+  if (!isSingleCommand || isMutating || !hasCheckSignal) {
+    return false;
+  }
+
+  return normalizedName === "format" || normalizedName.includes("format");
+}
+
+export const formatGate = createCommandGate({
+  id: "format",
+  label: "Format check",
+  description: "Runs the project's configured formatting check command.",
+  scriptNames: ["format:check", "check-format", "check:format", "fmt:check"],
+  matchScript: isSafeFormatCheckCommand,
+});

package/src/quality/gates/lint.ts

@@ -0,0 +1,22 @@
+import { createCommandGate } from "./command.js";
+
+function isSafeLintCommand(name: string, command: string): boolean {
+  const normalizedName = name.toLowerCase();
+  const normalized = command.toLowerCase();
+  const isSingleCommand = !normalized.includes("&&") && !normalized.includes("||");
+
+  return (
+    isSingleCommand &&
+    normalizedName.includes("lint") &&
+    (normalized.includes("eslint") || normalized.includes("oxlint") || normalized.includes("biome lint")) &&
+    !normalized.includes("--fix")
+  );
+}
+
+export const lintGate = createCommandGate({
+  id: "lint",
+  label: "Lint",
+  description: "Runs the project's configured lint command.",
+  scriptNames: ["lint", "lint:check", "lint:ci"],
+  matchScript: isSafeLintCommand,
+});

package/src/quality/gates/lsp-diagnostics.ts

@@ -0,0 +1,84 @@
+import { GATE_CONFIG_SCHEMAS } from "../registry.js";
+import type {
+  GateDefinition,
+  GateExecutionContext,
+  GateIssue,
+  GateResult,
+  LspDiagnosticsGateConfig,
+  ProjectFacts,
+} from "../../types.js";
+
+function hasActiveLspTool(activeTools: string[]): boolean {
+  return activeTools.some((tool) => tool.toLowerCase().split(":").includes("lsp"));
+}
+
+function summarizeDiagnostics(issues: GateIssue[]): string {
+  const errorCount = issues.filter((issue) => issue.severity === "error").length;
+  const warningCount = issues.filter((issue) => issue.severity === "warning").length;
+
+  if (errorCount > 0) {
+    return `LSP diagnostics found ${errorCount} error(s) and ${warningCount} warning(s).`;
+  }
+
+  if (warningCount > 0) {
+    return `LSP diagnostics passed with ${warningCount} warning(s) and no errors.`;
+  }
+
+  return "LSP diagnostics passed with no issues.";
+}
+
+function detectLspDiagnosticsGate(projectFacts: ProjectFacts) {
+  if (!hasActiveLspTool(projectFacts.activeTools)) {
+    return null;
+  }
+
+  return {
+    suggestedConfig: { enabled: true },
+    confidence: "high" as const,
+    reason: "Active tools include LSP support.",
+  };
+}
+
+async function runLspDiagnosticsGate(
+  context: GateExecutionContext,
+  _config: LspDiagnosticsGateConfig,
+): Promise<GateResult> {
+  if (!hasActiveLspTool(context.activeTools)) {
+    return {
+      gate: "lsp-diagnostics",
+      status: "blocked",
+      summary: "LSP diagnostics gate blocked: no active LSP tool is available.",
+      issues: [],
+    };
+  }
+
+  try {
+    const issues = await context.getLspDiagnostics(context.scopeFiles, context.fileScope);
+    const hasErrors = issues.some((issue) => issue.severity === "error");
+
+    return {
+      gate: "lsp-diagnostics",
+      status: hasErrors ? "failed" : "passed",
+      summary: summarizeDiagnostics(issues),
+      issues,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown diagnostics error";
+
+    return {
+      gate: "lsp-diagnostics",
+      status: "blocked",
+      summary: `LSP diagnostics gate blocked: ${message}`,
+      issues: [],
+      metadata: { error: message },
+    };
+  }
+}
+
+export const lspDiagnosticsGate: GateDefinition<LspDiagnosticsGateConfig> = {
+  id: "lsp-diagnostics",
+  description: "Runs LSP diagnostics across the current review scope.",
+  configSchema: GATE_CONFIG_SCHEMAS["lsp-diagnostics"],
+  detect: detectLspDiagnosticsGate,
+  run: runLspDiagnosticsGate,
+};

package/src/quality/gates/test-suite.ts

@@ -0,0 +1,8 @@
+import { createCommandGate } from "./command.js";
+
+export const testSuiteGate = createCommandGate({
+  id: "test-suite",
+  label: "Test suite",
+  description: "Runs the project's configured test suite command.",
+  scriptNames: ["test"],
+});

package/src/quality/gates/typecheck.ts

@@ -0,0 +1,22 @@
+import { createCommandGate } from "./command.js";
+
+function isTypecheckCommand(name: string, command: string): boolean {
+  const normalizedName = name.toLowerCase();
+  const normalized = command.toLowerCase();
+  const isSingleCommand = !normalized.includes("&&") && !normalized.includes("||");
+
+  return (
+    isSingleCommand &&
+    (normalizedName.includes("type") || normalizedName.includes("tsc")) &&
+    normalized.includes("tsc") &&
+    normalized.includes("--noemit")
+  );
+}
+
+export const typecheckGate = createCommandGate({
+  id: "typecheck",
+  label: "Typecheck",
+  description: "Runs the project's configured type-check command.",
+  scriptNames: ["typecheck", "type-check", "check-types", "check:types", "types", "tsc"],
+  matchScript: isTypecheckCommand,
+});

package/src/quality/registry.ts

@@ -0,0 +1,25 @@
+// src/quality/registry.ts
+import type { GateDefinition, GateId } from "../types.js";
+import { GATE_CONFIG_SCHEMAS } from "./schemas.js";
+
+export type GateRegistry = Partial<Record<GateId, GateDefinition<any>>>;
+
+export const GATE_DISPLAY_NAMES: Record<GateId, string> = {
+  "lsp-diagnostics": "LSP diagnostics",
+  lint: "Lint",
+  typecheck: "Typecheck",
+  format: "Format check",
+  "test-suite": "Test suite",
+  build: "Build",
+};
+
+export const CANONICAL_GATE_ORDER: GateId[] = [
+  "lsp-diagnostics",
+  "lint",
+  "typecheck",
+  "format",
+  "test-suite",
+  "build",
+];
+
+export { GATE_CONFIG_SCHEMAS };

package/src/quality/review-gates.ts

@@ -0,0 +1,33 @@
+import type { QualityGatesConfig, ProjectFacts } from "../types.js";
+import { CANONICAL_GATE_ORDER, type GateRegistry } from "./registry.js";
+import { lspDiagnosticsGate } from "./gates/lsp-diagnostics.js";
+import { lintGate } from "./gates/lint.js";
+import { typecheckGate } from "./gates/typecheck.js";
+import { formatGate } from "./gates/format.js";
+import { testSuiteGate } from "./gates/test-suite.js";
+import { buildGate } from "./gates/build.js";
+
+export const REVIEW_GATE_REGISTRY: GateRegistry = {
+  "lsp-diagnostics": lspDiagnosticsGate,
+  lint: lintGate,
+  typecheck: typecheckGate,
+  format: formatGate,
+  "test-suite": testSuiteGate,
+  build: buildGate,
+};
+
+export function detectReviewGates(projectFacts: ProjectFacts): QualityGatesConfig {
+  const gates: QualityGatesConfig = {};
+
+  for (const gateId of CANONICAL_GATE_ORDER) {
+    const definition = REVIEW_GATE_REGISTRY[gateId];
+    const detection = definition?.detect(projectFacts);
+    if (!detection?.suggestedConfig) {
+      continue;
+    }
+
+    gates[gateId] = detection.suggestedConfig as never;
+  }
+
+  return gates;
+}