itworksbut 0.1.1 → 0.3.0

package/src/reporters/todoReporter.js

@@ -0,0 +1,133 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SEVERITIES } from "../core/config.js";
+import { countBySeverity, getExitCode } from "../core/findings.js";
+import { getConsoleFindingTitle, getFixPrompt } from "./consoleStyle.js";
+
+export async function writeTodoReport(result, options = {}) {
+  const filePath = options.filePath || path.join(result.meta.rootPath, "todo.md");
+  await fs.writeFile(filePath, reportTodo(result), "utf8");
+  return filePath;
+}
+
+export function reportTodo(result) {
+  const counts = countBySeverity(result.findings);
+  const exitCode = getExitCode(result.findings, result.config.failOn);
+  const findingsBySeverity = new Map(
+    SEVERITIES.map((severity) => [severity, result.findings.filter((finding) => finding.severity === severity)])
+  );
+
+  return `${[
+    "# AI Fix Todo",
+    "",
+    "This file was generated by ItWorksBut. It is optimized for coding agents: work top to bottom, keep changes focused, and mark tasks complete only after verification.",
+    "",
+    "## Agent Rules",
+    "",
+    "- Fix critical and high findings before lower-priority cleanup.",
+    "- Inspect the referenced code before editing, especially for heuristic findings.",
+    "- Preserve existing behavior unless the finding explicitly requires changing it.",
+    "- Add or update focused tests when the change has behavioral risk.",
+    "- Do not silence ItWorksBut checks unless the underlying issue is actually fixed.",
+    "- Never print, log, or preserve raw secret values. Use placeholders only.",
+    "",
+    "## Scan Summary",
+    "",
+    `- Tool: ${result.meta.tool || "ItWorksBut"} ${result.meta.version || ""}`.trim(),
+    `- Project: ${result.meta.rootPath || "unknown"}`,
+    `- Completed: ${result.meta.completedAt || "unknown"}`,
+    `- Files scanned: ${result.meta.filesScanned ?? "unknown"}`,
+    `- Text files scanned: ${result.meta.textFilesScanned ?? "unknown"}`,
+    `- Fail-on: ${result.config.failOn}`,
+    `- Exit decision: ${exitCode}`,
+    `- Total findings: ${result.findings.length}`,
+    ...SEVERITIES.map((severity) => `- ${capitalize(severity)}: ${counts[severity]}`),
+    "",
+    renderFindingSections(findingsBySeverity),
+    renderWarnings(result.warnings),
+    "## Final Verification",
+    "",
+    "- [ ] Run the relevant test suite.",
+    "- [ ] Run `itworksbut scan` again.",
+    "- [ ] Confirm there are no remaining findings at or above the configured fail-on severity.",
+    "",
+  ].join("\n")}\n`;
+}
+
+function renderFindingSections(findingsBySeverity) {
+  const sections = [];
+
+  for (const severity of SEVERITIES) {
+    const findings = findingsBySeverity.get(severity) || [];
+    if (findings.length === 0) continue;
+
+    sections.push(`## ${capitalize(severity)} Findings`);
+    sections.push("");
+
+    findings.forEach((finding, index) => {
+      sections.push(renderFinding(finding, index + 1));
+      sections.push("");
+    });
+  }
+
+  if (sections.length === 0) {
+    return [
+      "## Findings",
+      "",
+      "No findings were detected. Keep this file as a record or delete it when no longer useful.",
+      "",
+    ].join("\n");
+  }
+
+  return sections.join("\n");
+}
+
+function renderFinding(finding, number) {
+  const location = finding.file
+    ? `${finding.file}${finding.line ? `:${finding.line}` : ""}${finding.column ? `:${finding.column}` : ""}`
+    : "project-wide";
+  const heuristic = finding.heuristic ? "yes" : "no";
+  const tags = finding.tags?.length ? finding.tags.join(", ") : "none";
+
+  return [
+    `### ${number}. ${getConsoleFindingTitle(finding)}`,
+    "",
+    "- [ ] Fix this finding.",
+    `- Check ID: \`${finding.checkId}\``,
+    `- Severity: \`${finding.severity}\``,
+    `- Category: \`${finding.category || "unknown"}\``,
+    `- Location: \`${location}\``,
+    `- Heuristic: \`${heuristic}\``,
+    `- Tags: ${tags}`,
+    `- Problem: ${finding.message}`,
+    `- Recommendation: ${finding.recommendation || "Fix the underlying issue without suppressing the scanner."}`,
+    "",
+    "#### Agent Prompt",
+    "",
+    "```text",
+    getFixPrompt(finding),
+    "```",
+    "",
+    "#### Acceptance Criteria",
+    "",
+    `- [ ] The issue behind \`${finding.checkId}\` is fixed at the source.`,
+    "- [ ] Existing behavior is preserved or intentional behavior changes are covered by tests.",
+    "- [ ] No raw secrets, tokens, credentials, or private values were added to code, logs, tests, or this todo.",
+    "- [ ] The relevant scanner finding no longer appears after rerunning ItWorksBut.",
+  ].join("\n");
+}
+
+function renderWarnings(warnings = []) {
+  if (!warnings.length) return "";
+
+  return [
+    "## Scanner Warnings",
+    "",
+    ...warnings.map((warning) => `- \`${warning.checkId}\`: ${warning.message}`),
+    "",
+  ].join("\n");
+}
+
+function capitalize(value) {
+  return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}