itworksbut 0.2.0 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ It focuses on common "it works, but..." risks often found in AI-generated or rus
 
 For every finding, ItWorksBut gives you a copy-ready fix prompt you can paste into your coding agent. It does not just say what is wrong; it tells your AI exactly what to inspect, what to change, and what not to leak.
 
-It only reads files and reports findings. It does not call external APIs, does not send telemetry, and does not modify the scanned project.
+It only reads files and reports findings. It does not call external APIs, does not send telemetry, and does not modify the scanned project unless you explicitly ask it to write `todo.md` with `--todo`.
 
 ## Installation
 
@@ -40,6 +40,7 @@ itworksbut scan --path .
 itworksbut scan --fail-on high
 itworksbut scan --json
 itworksbut scan --sarif > itworksbut.sarif
+itworksbut scan --todo
 itworksbut scan --config itworksbut.config.json
 itworksbut scan --verbose
 itworksbut --version
@@ -56,6 +57,7 @@ itworksbut scan [options]
 - `--fail-on <severity>`: Exit with code `1` when a finding at or above the severity exists. Levels: `critical`, `high`, `medium`, `low`, `info`. Default: `low`.
 - `--json`: Print machine-readable JSON only. No banner, colors, spinner, table, or extra text.
 - `--sarif`: Print SARIF JSON for GitHub Code Scanning. No banner, colors, spinner, table, or extra text.
+- `--todo`: Write an AI-ready `todo.md` into the scanned project with prioritized findings, fix prompts, and acceptance criteria.
 - `--verbose`: Include scanner warnings and extra metadata in console output.
 - `--quiet`: Print only the summary.
 - `--no-color`: Disable colored output.
@@ -87,6 +89,14 @@ Console-only flags:
 
 In CI, spinners and banners are automatically disabled. With `--json` and `--sarif`, stdout contains only valid machine-readable output. The edgy tone applies only to the Console Reporter.
 
+To create a fix list for a coding agent:
+
+```sh
+itworksbut scan --todo
+```
+
+This writes `todo.md` to the scanned project. The file is ordered by severity and includes agent rules, exact fix prompts, locations, recommendations, and final verification checkboxes.
+
 ## GitHub Actions
 
 ```yaml
@@ -155,20 +165,21 @@ release/**
 
 ## Example Output
 
-```text
-✖  CRITICAL  It works, but your .env is tracked.
-   ✔ Check: env.env-file-tracked
-   📁 File:  .env
-   🤔 Why:   .env appears to be tracked by git. Secrets may be exposed.
-   🤖 prompt:   You are a senior security engineer working in this repository. Fix the ItWorksBut finding env.env-file-tracked at .env. Treat this as a concrete finding. Problem: .env appears to be tracked by git. Secrets may be exposed. Required change: Remove tracked env files from git, add safe examples such as .env.example, and make sure any exposed credentials are treated as compromised. Do not print, log, or preserve raw secret values; use placeholders only. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
-
-▲  HIGH  It works, but your SQL query is one template string away from pain.
-   ✔ Check: database.raw-sql-interpolation
-   📁 File:  src/db.js:12
-   🤔 Why:   Possible SQL injection risk: raw SQL appears to be built with template string interpolation.
-   🤖 prompt:   You are a senior security engineer working in this repository. Fix the ItWorksBut finding database.raw-sql-interpolation at src/db.js:12. This finding is heuristic, so inspect the code first and only change behavior when the risk is real. Problem: Possible SQL injection risk: raw SQL appears to be built with template string interpolation. Required change: Replace SQL string interpolation or concatenation with parameterized queries, prepared statements, or a safe ORM query builder. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
+![screenshot of an example output](/assets/medium_problems.webp)
+✖ CRITICAL It works, but your .env is tracked.
+✔ Check: env.env-file-tracked
+📁 File: .env
+🤔 Why: .env appears to be tracked by git. Secrets may be exposed.
+🤖 prompt: You are a senior security engineer working in this repository. Fix the ItWorksBut finding env.env-file-tracked at .env. Treat this as a concrete finding. Problem: .env appears to be tracked by git. Secrets may be exposed. Required change: Remove tracked env files from git, add safe examples such as .env.example, and make sure any exposed credentials are treated as compromised. Do not print, log, or preserve raw secret values; use placeholders only. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
+
+▲ HIGH It works, but your SQL query is one template string away from pain.
+✔ Check: database.raw-sql-interpolation
+📁 File: src/db.js:12
+🤔 Why: Possible SQL injection risk: raw SQL appears to be built with template string interpolation.
+🤖 prompt: You are a senior security engineer working in this repository. Fix the ItWorksBut finding database.raw-sql-interpolation at src/db.js:12. This finding is heuristic, so inspect the code first and only change behavior when the risk is real. Problem: Possible SQL injection risk: raw SQL appears to be built with template string interpolation. Required change: Replace SQL string interpolation or concatenation with parameterized queries, prepared statements, or a safe ORM query builder. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
 
 SUMMARY
+
 - ship status: DO NOT SHIP
 - Fix the red stuff before production.
 - total findings: 2
@@ -179,6 +190,7 @@ SUMMARY
 - info: 0
 - fail-on: high
 - exit decision: 1
+
 ```
 
 Secret-like findings never print the full secret value. Findings report the file, line, and secret type where possible.
@@ -225,3 +237,4 @@ Each check is a plain ESM module with an `id`, metadata, and async `run(context)
 ItWorksBut is a static heuristic scanner, not a pentest, SAST replacement, dependency vulnerability database, or runtime security monitor. Findings intentionally use wording such as "possible", "potential", and "appears to" when a check is heuristic.
 
 Use it as a CI guardrail for common project hygiene and security mistakes. For production systems, combine it with code review, tests, dependency scanning, secrets scanning, threat modeling, and focused security assessment.
+```

package/bin/itworksbut.js

@@ -9,6 +9,7 @@ import { getExitCode } from '../src/core/findings.js';
 import { reportConsole } from '../src/reporters/consoleReporter.js';
 import { reportJson } from '../src/reporters/jsonReporter.js';
 import { reportSarif } from '../src/reporters/sarifReporter.js';
+import { writeTodoReport } from '../src/reporters/todoReporter.js';
 
 async function main() {
     const args = parseArgs(process.argv.slice(2));
@@ -51,6 +52,9 @@ async function main() {
         process.stdout.write(`${JSON.stringify(reportSarif(result), null, 2)}\n`);
     } else if (args.json) {
         process.stdout.write(`${JSON.stringify(reportJson(result), null, 2)}\n`);
+    } else if (args.todo) {
+        const filePath = await writeTodoReport(result);
+        if (!args.quiet) process.stdout.write(`Wrote AI todo file: ${filePath}\n`);
     } else {
         reportConsole(result, args);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "itworksbut",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Static CI checks for common security, repo, dependency, build, and deployment risks in JavaScript vibe coding projects.",
     "type": "module",
     "bin": {

package/src/cli/output.js

@@ -14,6 +14,7 @@ Options:
                      Levels: critical, high, medium, low, info. Default: low.
   --json              Print machine-readable JSON.
   --sarif             Print SARIF for GitHub Code Scanning.
+  --todo              Write an AI-ready todo.md to the scanned project.
   --no-color          Disable color styling.
   --no-banner         Disable the intro banner.
   --quiet             Print only the summary.

package/src/cli/parseArgs.js

@@ -1,5 +1,5 @@
 const FLAG_WITH_VALUE = new Set(["--fail-on", "--config", "--path"]);
-const BOOLEAN_FLAGS = new Set(["--json", "--sarif", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
+const BOOLEAN_FLAGS = new Set(["--json", "--sarif", "--todo", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
 
 export function parseArgs(argv) {
   const args = {
@@ -9,6 +9,7 @@ export function parseArgs(argv) {
     failOn: undefined,
     json: false,
     sarif: false,
+    todo: false,
     verbose: false,
     noColor: false,
     noBanner: false,
@@ -46,6 +47,7 @@ export function parseArgs(argv) {
       if (token === "--version" || token === "-v") args.version = true;
       if (token === "--json") args.json = true;
       if (token === "--sarif") args.sarif = true;
+      if (token === "--todo") args.todo = true;
       if (token === "--verbose") args.verbose = true;
       if (token === "--no-color") args.noColor = true;
       if (token === "--no-banner") args.noBanner = true;
@@ -56,8 +58,8 @@ export function parseArgs(argv) {
     throw new Error(`Unknown argument: ${token}`);
   }
 
-  if (args.json && args.sarif) {
-    throw new Error("Use only one output format: --json or --sarif");
+  if ([args.json, args.sarif, args.todo].filter(Boolean).length > 1) {
+    throw new Error("Use only one output format: --json, --sarif, or --todo");
   }
 
   return args;

package/src/cli/terminal.js

@@ -19,11 +19,11 @@ const SPINNER_TEXT = {
 };
 
 export function isFancyOutputEnabled(options = {}, env = process.env, stdout = process.stdout) {
-  return Boolean(stdout.isTTY) && !env.CI && !options.json && !options.sarif && !options.noColor;
+  return Boolean(stdout.isTTY) && !env.CI && !options.json && !options.sarif && !options.todo && !options.noColor;
 }
 
 export function isColorEnabled(options = {}, env = process.env, stdout = process.stdout) {
-  if (options.noColor || options.json || options.sarif) return false;
+  if (options.noColor || options.json || options.sarif || options.todo) return false;
   if (env.FORCE_COLOR && env.FORCE_COLOR !== "0") return true;
   if (env.CI) return false;
   return Boolean(stdout.isTTY);
@@ -40,6 +40,7 @@ export function shouldUseSpinner(options = {}, env = process.env, stdout = proce
     !env.CI &&
     !options.json &&
     !options.sarif &&
+    !options.todo &&
     !options.quiet
   );
 }
@@ -54,7 +55,7 @@ export function createScanSpinner(options = {}) {
 }
 
 export function printIntro(options = {}) {
-  if (options.json || options.sarif || options.noBanner || options.quiet || process.env.CI || !process.stdout.isTTY) {
+  if (options.json || options.sarif || options.todo || options.noBanner || options.quiet || process.env.CI || !process.stdout.isTTY) {
     return;
   }
 

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)}`;
+}