itworksbut 0.5.0 → 0.6.0

package/README.md

@@ -6,7 +6,19 @@ 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 unless you explicitly ask it to write `todo.md` with `--todo`.
+It mostly reads files and reports findings. It does not send telemetry. The outdated-package check may invoke your local package manager, and the CLI only writes files when you explicitly ask for `todo.md` with `--todo` or `report.md` with `--report`.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Options](#options)
+- [Terminal Experience](#terminal-experience)
+- [GitHub Actions](#github-actions)
+- [Configuration](#configuration)
+- [Example Output](#example-output)
+- [What It Detects](#what-it-detects)
+- [What It Does Not Guarantee](#what-it-does-not-guarantee)
 
 ## Installation
 
@@ -41,6 +53,7 @@ itworksbut scan --fail-on high
 itworksbut scan --json
 itworksbut scan --sarif > itworksbut.sarif
 itworksbut scan --todo
+itworksbut scan --report
 itworksbut scan --config itworksbut.config.json
 itworksbut scan --verbose
 itworksbut --version
@@ -58,6 +71,7 @@ itworksbut scan [options]
 - `--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.
+- `--report`: Write a Markdown `report.md` into the current working directory.
 - `--verbose`: Include scanner warnings and extra metadata in console output.
 - `--quiet`: Print only the summary.
 - `--no-color`: Disable colored output.
@@ -97,6 +111,14 @@ 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.
 
+To create a Markdown scan report:
+
+```sh
+itworksbut scan --report
+```
+
+This writes `report.md` to the current working directory with check statuses, summaries, details, and recommendations.
+
 ## GitHub Actions
 
 ```yaml
@@ -166,38 +188,10 @@ release/**
 ## Example Output
 
 ![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
-- critical: 1
-- high: 1
-- medium: 0
-- low: 0
-- 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.
 
 ## What It Detects
 
-The baseline includes 50 modular checks:
+The baseline includes 51 modular checks:
 
 - `git.gitignore-missing`
 - `git.gitignore-incomplete`
@@ -211,6 +205,7 @@ The baseline includes 50 modular checks:
 - `dependencies.multiple-lockfiles`
 - `dependencies.install-scripts-risk`
 - `dependencies.audit-script-missing`
+- `dependencies.outdated-packages`
 - `package.scripts-missing`
 - `ci.no-ci-config`
 - `ci.npm-install-instead-of-npm-ci`
@@ -257,4 +252,3 @@ 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

@@ -10,6 +10,7 @@ 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';
+import { writeMarkdownReport } from '../src/reporters/markdownReport.js';
 
 async function main() {
     const args = parseArgs(process.argv.slice(2));
@@ -59,6 +60,14 @@ async function main() {
         reportConsole(result, args);
     }
 
+    if (args.report) {
+        const report = await writeMarkdownReport(result);
+        if (!args.json && !args.sarif) {
+            const verb = report.overwritten ? 'Overwrote' : 'Wrote';
+            process.stdout.write(`${verb} scan report: ${report.filePath}\n`);
+        }
+    }
+
     return getExitCode(result.findings, result.config.failOn);
 }
 

package/package.json

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

package/src/checks/dependencies/outdated-packages.js

@@ -0,0 +1,297 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { detectOutdatedPackageManager, getOutdatedCommand } from "../../utils/packageManager.js";
+
+const execFileAsync = promisify(execFile);
+const CHECK_ID = "dependencies.outdated-packages";
+const CHECK_TITLE = "Outdated packages";
+const COMMAND_TIMEOUT_MS = 30_000;
+const COMMAND_MAX_BUFFER = 10 * 1024 * 1024;
+
+export default {
+  id: CHECK_ID,
+  title: CHECK_TITLE,
+  category: "dependencies",
+  severity: "info",
+  tags: ["dependencies", "maintenance"],
+  run: async (context) => {
+    const result = await runOutdatedPackagesCheck(context);
+    return { findings: [], result };
+  }
+};
+
+export async function runOutdatedPackagesCheck(context, options = {}) {
+  const detected = detectOutdatedPackageManager({
+    packageJson: context.packageJson,
+    files: context.allFiles
+  });
+
+  if (detected.status === "skip") {
+    return checkResult({
+      status: "skip",
+      summary: detected.summary,
+      metadata: { reason: "missing-package-json" }
+    });
+  }
+
+  const commandResult = await runOutdatedCommand(detected.manager, context.rootPath, options);
+  if (isMissingCommand(commandResult)) {
+    return checkResult({
+      status: "fail",
+      summary: `${detected.manager} is not installed or could not be found.`,
+      details: [
+        {
+          message: `${detected.manager} is not installed or could not be found.`,
+          command: renderCommand(commandResult),
+          exitCode: commandResult.exitCode
+        }
+      ],
+      metadata: { packageManager: detected.manager }
+    });
+  }
+
+  const parsed = parseOutdatedOutput(detected.manager, commandResult.stdout, context.packageJson);
+  if (!parsed.ok) {
+    if (!hasCommandFailure(commandResult) && isEmptyOutput(commandResult.stdout)) {
+      return checkResult({
+        status: "pass",
+        summary: "all dependencies are up to date",
+        details: [],
+        metadata: { packageManager: detected.manager }
+      });
+    }
+
+    return checkResult({
+      status: "fail",
+      summary: `${detected.manager} outdated returned output that could not be parsed.`,
+      details: [
+        {
+          message: parsed.error,
+          command: renderCommand(commandResult),
+          exitCode: commandResult.exitCode,
+          stderr: trimText(commandResult.stderr)
+        }
+      ],
+      metadata: { packageManager: detected.manager }
+    });
+  }
+
+  if ((hasCommandFailure(commandResult) || hasEmptyExitOneFailure(commandResult)) && parsed.packages.length === 0) {
+    return checkResult({
+      status: "fail",
+      summary: `${detected.manager} outdated failed.`,
+      details: [
+        {
+          message: trimText(commandResult.stderr) || "Command exited with code " + commandResult.exitCode + ".",
+          command: renderCommand(commandResult),
+          exitCode: commandResult.exitCode
+        }
+      ],
+      metadata: { packageManager: detected.manager }
+    });
+  }
+
+  if (parsed.packages.length === 0) {
+    return checkResult({
+      status: "pass",
+      summary: "all dependencies are up to date",
+      details: [],
+      metadata: { packageManager: detected.manager }
+    });
+  }
+
+  return checkResult({
+    status: "warn",
+    summary: `${parsed.packages.length} ${parsed.packages.length === 1 ? "package" : "packages"} outdated`,
+    details: parsed.packages,
+    metadata: { packageManager: detected.manager }
+  });
+}
+
+export async function runOutdatedCommand(manager, rootPath, options = {}) {
+  const runCommand = options.runCommand || execCommand;
+  const { command, args } = getOutdatedCommand(manager);
+  return await runCommand(command, args, { cwd: rootPath });
+}
+
+export function parseOutdatedOutput(manager, stdout, packageJson = {}) {
+  const output = String(stdout || "").trim();
+  if (!output) return { ok: true, packages: [] };
+
+  try {
+    if (manager === "yarn") {
+      return { ok: true, packages: parseYarnOutput(output, packageJson) };
+    }
+
+    const parsed = JSON.parse(output);
+    return { ok: true, packages: normalizeOutdatedData(parsed, packageJson) };
+  } catch (error) {
+    return {
+      ok: false,
+      packages: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+export function normalizeOutdatedData(data, packageJson = {}) {
+  if (!data || typeof data !== "object") return [];
+
+  if (Array.isArray(data)) {
+    return data
+      .map((entry) => normalizePackageEntry(entry.name || entry.package, entry, packageJson))
+      .filter(Boolean);
+  }
+
+  return Object.entries(data)
+    .map(([name, entry]) => normalizePackageEntry(name, entry, packageJson))
+    .filter(Boolean);
+}
+
+async function execCommand(command, args, options) {
+  try {
+    const result = await execFileAsync(command, args, {
+      cwd: options.cwd,
+      timeout: COMMAND_TIMEOUT_MS,
+      maxBuffer: COMMAND_MAX_BUFFER
+    });
+    return {
+      command,
+      args,
+      stdout: result.stdout || "",
+      stderr: result.stderr || "",
+      exitCode: 0
+    };
+  } catch (error) {
+    return {
+      command,
+      args,
+      stdout: error?.stdout || "",
+      stderr: error?.stderr || error?.message || "",
+      exitCode: error?.code ?? null,
+      signal: error?.signal,
+      error
+    };
+  }
+}
+
+function parseYarnOutput(output, packageJson) {
+  const directJson = tryJson(output);
+  if (directJson.ok) {
+    if (directJson.value?.type === "table") return parseYarnTable(directJson.value.data, packageJson);
+    return normalizeOutdatedData(directJson.value, packageJson);
+  }
+
+  const records = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => tryJson(line))
+    .filter((record) => record.ok)
+    .map((record) => record.value);
+
+  const tableRecord = records.find((record) => record?.type === "table" && record.data);
+  if (tableRecord) return parseYarnTable(tableRecord.data, packageJson);
+
+  const packageRecords = records
+    .filter((record) => record?.data && typeof record.data === "object")
+    .map((record) => record.data);
+  if (packageRecords.length > 0) return normalizeOutdatedData(packageRecords, packageJson);
+
+  throw new Error("No parseable Yarn outdated JSON records were found.");
+}
+
+function parseYarnTable(data, packageJson) {
+  const head = Array.isArray(data?.head) ? data.head.map((value) => String(value).toLowerCase()) : [];
+  const body = Array.isArray(data?.body) ? data.body : [];
+
+  return body.map((row) => {
+    const entry = {
+      name: row[indexOf(head, "package", 0)],
+      current: row[indexOf(head, "current", 1)],
+      wanted: row[indexOf(head, "wanted", 2)],
+      latest: row[indexOf(head, "latest", 3)],
+      type: row[indexOf(head, "package type", 4)]
+    };
+    return normalizePackageEntry(entry.name, entry, packageJson);
+  }).filter(Boolean);
+}
+
+function normalizePackageEntry(name, entry, packageJson) {
+  if (!name || !entry || typeof entry !== "object") return null;
+
+  const current = stringValue(entry.current ?? entry.installed ?? entry.version);
+  const wanted = stringValue(entry.wanted ?? entry.latest);
+  const latest = stringValue(entry.latest ?? entry.wanted);
+
+  if (!current && !wanted && !latest) return null;
+
+  return {
+    name: String(name),
+    current: current || "unknown",
+    wanted: wanted || "unknown",
+    latest: latest || "unknown",
+    type: stringValue(entry.type ?? entry.dependencyType ?? entry.packageType) || inferDependencyType(name, packageJson)
+  };
+}
+
+function inferDependencyType(name, packageJson = {}) {
+  if (Object.hasOwn(packageJson.dependencies || {}, name)) return "dependencies";
+  if (Object.hasOwn(packageJson.devDependencies || {}, name)) return "devDependencies";
+  if (Object.hasOwn(packageJson.peerDependencies || {}, name)) return "peerDependencies";
+  if (Object.hasOwn(packageJson.optionalDependencies || {}, name)) return "optionalDependencies";
+  return "dependencies";
+}
+
+function checkResult(result) {
+  return {
+    id: CHECK_ID,
+    title: CHECK_TITLE,
+    category: "dependencies",
+    details: [],
+    ...result
+  };
+}
+
+function hasCommandFailure(result) {
+  return result.exitCode !== 0 && result.exitCode !== 1;
+}
+
+function hasEmptyExitOneFailure(result) {
+  return result.exitCode === 1 && isEmptyOutput(result.stdout) && !isEmptyOutput(result.stderr);
+}
+
+function isMissingCommand(result) {
+  return result.exitCode === "ENOENT" || result.error?.code === "ENOENT";
+}
+
+function isEmptyOutput(value) {
+  return String(value || "").trim() === "";
+}
+
+function renderCommand(result) {
+  return [result.command, ...(result.args || [])].filter(Boolean).join(" ");
+}
+
+function trimText(value) {
+  const normalized = String(value || "").trim();
+  return normalized.length > 1000 ? `${normalized.slice(0, 1000)}...` : normalized;
+}
+
+function tryJson(value) {
+  try {
+    return { ok: true, value: JSON.parse(value) };
+  } catch {
+    return { ok: false, value: null };
+  }
+}
+
+function indexOf(head, name, fallback) {
+  const index = head.indexOf(name);
+  return index === -1 ? fallback : index;
+}
+
+function stringValue(value) {
+  if (value === undefined || value === null || value === "") return "";
+  return String(value);
+}

package/src/checks/index.js

@@ -10,6 +10,7 @@ import lockfileMissing from "./dependencies/lockfile-missing.js";
 import multipleLockfiles from "./dependencies/multiple-lockfiles.js";
 import installScriptsRisk from "./dependencies/install-scripts-risk.js";
 import auditScriptMissing from "./dependencies/audit-script-missing.js";
+import outdatedPackages from "./dependencies/outdated-packages.js";
 import packageScriptsMissing from "./package/scripts-missing.js";
 import noCiConfig from "./ci/no-ci-config.js";
 import npmInstallInsteadOfNpmCi from "./ci/npm-install-instead-of-npm-ci.js";
@@ -62,6 +63,7 @@ export default [
   multipleLockfiles,
   installScriptsRisk,
   auditScriptMissing,
+  outdatedPackages,
   packageScriptsMissing,
   noCiConfig,
   npmInstallInsteadOfNpmCi,

package/src/cli/output.js

@@ -14,6 +14,7 @@ Options:
   --json              Print machine-readable JSON.
   --sarif             Print SARIF for GitHub Code Scanning.
   --todo              Write an AI-ready todo.md to the scanned project.
+  --report            Write a Markdown scan report.md to the current directory.
   --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", "--todo", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
+const BOOLEAN_FLAGS = new Set(["--json", "--sarif", "--todo", "--report", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
 
 export function parseArgs(argv) {
   const args = {
@@ -10,6 +10,7 @@ export function parseArgs(argv) {
     json: false,
     sarif: false,
     todo: false,
+    report: false,
     verbose: false,
     noColor: false,
     noBanner: false,
@@ -48,6 +49,7 @@ export function parseArgs(argv) {
       if (token === "--json") args.json = true;
       if (token === "--sarif") args.sarif = true;
       if (token === "--todo") args.todo = true;
+      if (token === "--report") args.report = true;
       if (token === "--verbose") args.verbose = true;
       if (token === "--no-color") args.noColor = true;
       if (token === "--no-banner") args.noBanner = true;

package/src/core/checkResults.js

@@ -0,0 +1,53 @@
+export const CHECK_STATUSES = ["pass", "warn", "fail", "skip"];
+
+export function normalizeCheckResult(check, value = {}, findings = []) {
+  const status = normalizeStatus(value.status || deriveStatusFromFindings(findings));
+  const details = Array.isArray(value.details) ? value.details : detailsFromFindings(findings);
+
+  return {
+    id: value.id || check.id,
+    title: value.title || check.title,
+    category: value.category || check.category,
+    status,
+    summary: value.summary || defaultSummary(status, findings),
+    details,
+    metadata: value.metadata || undefined
+  };
+}
+
+export function deriveStatusFromFindings(findings = []) {
+  if (!findings.length) return "pass";
+  if (findings.some((finding) => finding.severity === "critical" || finding.severity === "high")) return "fail";
+  return "warn";
+}
+
+export function countByStatus(checks = []) {
+  return Object.fromEntries(
+    CHECK_STATUSES.map((status) => [status, checks.filter((check) => check.status === status).length])
+  );
+}
+
+function normalizeStatus(value) {
+  const normalized = String(value || "pass").toLowerCase();
+  return CHECK_STATUSES.includes(normalized) ? normalized : "fail";
+}
+
+function defaultSummary(status, findings) {
+  if (status === "pass") return "No issues found.";
+  if (status === "skip") return "Skipped.";
+  if (!findings.length) return status === "fail" ? "Check failed." : "Check needs review.";
+
+  const count = findings.length;
+  const noun = count === 1 ? "finding" : "findings";
+  return `${count} ${noun} reported.`;
+}
+
+function detailsFromFindings(findings) {
+  return findings.map((finding) => ({
+    message: finding.message,
+    file: finding.file,
+    line: finding.line,
+    severity: finding.severity,
+    recommendation: finding.recommendation
+  }));
+}

package/src/core/scanner.js

@@ -1,5 +1,6 @@
 import checks from "../checks/index.js";
 import { createContext } from "./context.js";
+import { normalizeCheckResult } from "./checkResults.js";
 import { normalizeFinding, severityRank } from "./findings.js";
 import { packageInfo } from "./packageInfo.js";
 
@@ -7,28 +8,54 @@ export async function scanProject(options = {}) {
   const startedAt = new Date();
   const context = await createContext(options);
   const findings = [];
+  const checkResults = [];
   const warnings = [];
 
   for (const check of checks) {
-    if (context.config.checks[check.id] === false) continue;
+    if (context.config.checks[check.id] === false) {
+      checkResults.push(normalizeCheckResult(check, {
+        status: "skip",
+        summary: "Disabled by configuration."
+      }));
+      continue;
+    }
 
     try {
-      const checkFindings = await check.run(context);
+      const rawResult = await check.run(context);
+      const checkFindings = Array.isArray(rawResult) ? rawResult : rawResult?.findings;
+      const explicitCheckResult = Array.isArray(rawResult) ? null : rawResult?.result || rawResult?.checkResult;
+
       if (!Array.isArray(checkFindings)) {
         warnings.push({
           checkId: check.id,
           message: "Check returned a non-array result and was ignored."
         });
+        checkResults.push(normalizeCheckResult(check, {
+          status: "fail",
+          summary: "Check returned an invalid result.",
+          details: [{ message: "Check returned a non-array result and was ignored." }]
+        }));
         continue;
       }
+
+      const normalizedFindings = [];
       for (const finding of checkFindings) {
-        findings.push(normalizeFinding(check, finding));
+        const normalizedFinding = normalizeFinding(check, finding);
+        normalizedFindings.push(normalizedFinding);
+        findings.push(normalizedFinding);
       }
+      checkResults.push(normalizeCheckResult(check, explicitCheckResult || {}, normalizedFindings));
     } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
       warnings.push({
         checkId: check.id,
-        message: error instanceof Error ? error.message : String(error)
+        message
       });
+      checkResults.push(normalizeCheckResult(check, {
+        status: "fail",
+        summary: message,
+        details: [{ message }]
+      }));
     }
   }
 
@@ -40,12 +67,14 @@ export async function scanProject(options = {}) {
 
   return {
     findings,
+    checks: checkResults,
     warnings,
     config: context.config,
     meta: {
       tool: "ItWorksBut",
       version: packageInfo.version,
       rootPath: context.rootPath,
+      packageName: context.packageJson?.name,
       packageManager: context.packageManager,
       gitAvailable: context.gitAvailable,
       filesScanned: context.allFiles.length,

package/src/reporters/consoleReporter.js

@@ -12,15 +12,17 @@ import {
 
 export function reportConsole(result, options = {}) {
     const { findings, warnings, config, meta } = result;
+    const checks = result.checks || [];
     const counts = countBySeverity(findings);
     const colors = getChalk(options);
     const rich = isFancyOutputEnabled(options);
+    const hasReviewCheck = checks.some(check => check.status === 'warn' || check.status === 'fail');
 
     if (!options.quiet && !rich) {
         process.stdout.write(`${colors.bold('ItWorksBut receipts')}\n\n`);
     }
 
-    if (!options.quiet && findings.length === 0) {
+    if (!options.quiet && findings.length === 0 && !hasReviewCheck) {
         process.stdout.write(
             `${colors.green ? colors.green('Suspiciously clean. No findings.') : 'Suspiciously clean. No findings.'}\n\n`,
         );
@@ -36,6 +38,10 @@ export function reportConsole(result, options = {}) {
         }
     }
 
+    if (!options.quiet) {
+        writeOutdatedPackagesCheck(checks, options);
+    }
+
     if (options.verbose && warnings.length > 0) {
         process.stdout.write('WARNINGS\n');
         for (const warning of warnings) {
@@ -55,6 +61,41 @@ export function reportConsole(result, options = {}) {
     }
 }
 
+function writeOutdatedPackagesCheck(checks, options) {
+    const check = checks.find(candidate => candidate.id === 'dependencies.outdated-packages');
+    if (!check) return;
+
+    const colors = getChalk(options);
+    const title = colors.bold('Outdated packages');
+
+    if (check.status === 'pass') {
+        process.stdout.write(`${colors.green('✓')} ${title}: ${check.summary}\n\n`);
+        return;
+    }
+
+    if (check.status === 'skip') {
+        process.stdout.write(`- ${title}: ${check.summary}\n\n`);
+        return;
+    }
+
+    if (check.status === 'fail') {
+        process.stdout.write(`${colors.red('✖')} ${title}: ${check.summary}\n\n`);
+        return;
+    }
+
+    process.stdout.write(`${colors.yellow('⚠')} ${title}: ${check.summary}\n`);
+    const packages = check.details.filter(detail => detail?.name).slice(0, 10);
+    for (const detail of packages) {
+        process.stdout.write(
+            `  - ${detail.name}: ${detail.current} → ${detail.wanted} wanted, ${detail.latest} latest\n`,
+        );
+    }
+    if (check.details.length > packages.length) {
+        process.stdout.write(`  - and ${check.details.length - packages.length} more\n`);
+    }
+    process.stdout.write('\n');
+}
+
 function writeFinding(finding, options) {
     const colors = getChalk(options);
     const severity = formatSeverity(finding.severity, options);

package/src/reporters/jsonReporter.js

@@ -1,4 +1,5 @@
 import { countBySeverity, getExitCode } from "../core/findings.js";
+import { countByStatus } from "../core/checkResults.js";
 
 export function reportJson(result) {
   return {
@@ -8,9 +9,11 @@ export function reportJson(result) {
     summary: {
       total: result.findings.length,
       bySeverity: countBySeverity(result.findings),
+      byStatus: countByStatus(result.checks || []),
       failOn: result.config.failOn,
       exitCode: getExitCode(result.findings, result.config.failOn)
     },
+    checks: result.checks || [],
     findings: result.findings,
     warnings: result.warnings
   };

package/src/reporters/markdownReport.js

@@ -0,0 +1,203 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { countByStatus } from "../core/checkResults.js";
+
+const ANSI_PATTERN = /\u001B\[[0-?]*[ -/]*[@-~]/g;
+
+export async function writeMarkdownReport(result, options = {}) {
+  const filePath = options.filePath || path.join(options.directoryPath || process.cwd(), "report.md");
+  let overwritten = false;
+
+  try {
+    await fs.access(filePath);
+    overwritten = true;
+  } catch {
+    overwritten = false;
+  }
+
+  await fs.writeFile(filePath, reportMarkdown(result), "utf8");
+  return { filePath, overwritten };
+}
+
+export function reportMarkdown(result) {
+  const checks = result.checks || checksFromFindings(result.findings || []);
+  const counts = countByStatus(checks);
+  const projectName = result.meta?.packageName || path.basename(result.meta?.rootPath || "") || "unknown";
+  const generatedAt = formatTimestamp(result.meta?.completedAt || new Date());
+
+  return stripAnsi(`${[
+    "# ItWorksBut Scan Report",
+    "",
+    `Generated: ${generatedAt}`,
+    "",
+    `Project: ${projectName}`,
+    `Path: ${result.meta?.rootPath || "unknown"}`,
+    "",
+    "## Summary",
+    "",
+    "| Status | Count |",
+    "|---|---:|",
+    `| Pass | ${counts.pass} |`,
+    `| Warn | ${counts.warn} |`,
+    `| Fail | ${counts.fail} |`,
+    `| Skip | ${counts.skip} |`,
+    "",
+    "## Checks",
+    "",
+    renderChecks(checks),
+    renderScannerWarnings(result.warnings || []),
+    renderRecommendations(checks, result.findings || []),
+  ].filter((line) => line !== null && line !== undefined).join("\n")}\n`);
+}
+
+function renderChecks(checks) {
+  if (!checks.length) return "No checks were recorded.\n";
+
+  return checks.map(renderCheck).join("\n");
+}
+
+function renderCheck(check) {
+  return [
+    `### ${check.title || check.id}`,
+    "",
+    `Status: ${check.status || "unknown"}`,
+    "",
+    "Summary:",
+    check.summary || "No summary available.",
+    "",
+    "Details:",
+    renderDetails(check),
+    ""
+  ].join("\n");
+}
+
+function renderDetails(check) {
+  const details = Array.isArray(check.details) ? check.details : [];
+  if (!details.length) return "None.";
+
+  if (isOutdatedPackageCheck(check)) {
+    return renderOutdatedPackageTable(details);
+  }
+
+  return details.map(renderDetailBullet).join("\n");
+}
+
+function renderOutdatedPackageTable(details) {
+  const packageDetails = details.filter((detail) => detail?.name);
+  if (!packageDetails.length) return details.map(renderDetailBullet).join("\n");
+
+  return [
+    "| Package | Current | Wanted | Latest | Type |",
+    "|---|---:|---:|---:|---|",
+    ...packageDetails.map((detail) => (
+      `| ${escapeTable(detail.name)} | ${escapeTable(detail.current)} | ${escapeTable(detail.wanted)} | ${escapeTable(detail.latest)} | ${escapeTable(detail.type)} |`
+    ))
+  ].join("\n");
+}
+
+function renderDetailBullet(detail) {
+  if (typeof detail === "string") return `- ${detail}`;
+  if (!detail || typeof detail !== "object") return `- ${String(detail)}`;
+
+  if (detail.message) return `- ${detail.message}`;
+  return `- ${Object.entries(detail).map(([key, value]) => `${key}: ${String(value)}`).join(", ")}`;
+}
+
+function renderScannerWarnings(warnings) {
+  if (!warnings.length) return "";
+
+  return [
+    "## Scanner Warnings",
+    "",
+    ...warnings.map((warning) => `- ${warning.checkId}: ${warning.message}`),
+    ""
+  ].join("\n");
+}
+
+function renderRecommendations(checks, findings) {
+  const needsReview = checks.some((check) => check.status === "warn" || check.status === "fail");
+  if (!needsReview && findings.length === 0) return "";
+
+  const recommendations = [];
+  if (checks.some((check) => isOutdatedPackageCheck(check) && (check.status === "warn" || check.status === "fail"))) {
+    recommendations.push("Update outdated packages carefully.");
+    recommendations.push("Review major-version upgrades manually.");
+    recommendations.push("Run tests after dependency updates.");
+  }
+
+  for (const finding of findings) {
+    if (finding.recommendation) recommendations.push(finding.recommendation);
+  }
+
+  if (checks.some((check) => check.status === "fail")) {
+    recommendations.push("Review failed checks and scanner warnings before shipping.");
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Review warning and failure details before shipping.");
+  }
+
+  return [
+    "## Recommendations",
+    "",
+    ...unique(recommendations).map((recommendation) => `- ${recommendation}`),
+    ""
+  ].join("\n");
+}
+
+function checksFromFindings(findings) {
+  const byCheck = new Map();
+  for (const finding of findings) {
+    const existing = byCheck.get(finding.checkId) || {
+      id: finding.checkId,
+      title: finding.title,
+      category: finding.category,
+      status: finding.severity === "critical" || finding.severity === "high" ? "fail" : "warn",
+      summary: "Finding reported.",
+      details: []
+    };
+    existing.details.push({
+      message: finding.message,
+      file: finding.file,
+      line: finding.line,
+      severity: finding.severity
+    });
+    byCheck.set(finding.checkId, existing);
+  }
+  return [...byCheck.values()];
+}
+
+function isOutdatedPackageCheck(check) {
+  return check.id === "dependencies.outdated-packages" || check.title === "Outdated packages";
+}
+
+function formatTimestamp(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+
+  const pad = (number) => String(number).padStart(2, "0");
+  return [
+    date.getFullYear(),
+    "-",
+    pad(date.getMonth() + 1),
+    "-",
+    pad(date.getDate()),
+    " ",
+    pad(date.getHours()),
+    ":",
+    pad(date.getMinutes()),
+    ":",
+    pad(date.getSeconds())
+  ].join("");
+}
+
+function escapeTable(value) {
+  return stripAnsi(String(value ?? "unknown")).replace(/\|/g, "\\|");
+}
+
+function stripAnsi(value) {
+  return String(value).replace(ANSI_PATTERN, "");
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}

package/src/utils/packageManager.js

@@ -0,0 +1,28 @@
+export function detectOutdatedPackageManager({ packageJson, files = [] } = {}) {
+  if (!packageJson) {
+    return {
+      status: "skip",
+      manager: null,
+      summary: "skipped, no package.json found"
+    };
+  }
+
+  if (files.includes("pnpm-lock.yaml")) return packageManager("pnpm");
+  if (files.includes("yarn.lock")) return packageManager("yarn");
+  if (files.includes("package-lock.json")) return packageManager("npm");
+  return packageManager("npm");
+}
+
+export function getOutdatedCommand(manager) {
+  if (manager === "pnpm") return { command: "pnpm", args: ["outdated", "--json"] };
+  if (manager === "yarn") return { command: "yarn", args: ["outdated", "--json"] };
+  return { command: "npm", args: ["outdated", "--json"] };
+}
+
+function packageManager(manager) {
+  return {
+    status: "run",
+    manager,
+    ...getOutdatedCommand(manager)
+  };
+}