itworksbut 0.5.0 → 0.7.0

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,34 +1,64 @@
 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";
 
 export async function scanProject(options = {}) {
   const startedAt = new Date();
   const context = await createContext(options);
+  const includedCategories = normalizeFilter(options.categories);
   const findings = [];
+  const checkResults = [];
   const warnings = [];
 
   for (const check of checks) {
-    if (context.config.checks[check.id] === false) continue;
+    if (includedCategories && !includedCategories.has(check.category)) 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 +70,15 @@ 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,
+      categories: includedCategories ? [...includedCategories] : undefined,
       packageManager: context.packageManager,
       gitAvailable: context.gitAvailable,
       filesScanned: context.allFiles.length,
@@ -55,3 +88,8 @@ export async function scanProject(options = {}) {
     }
   };
 }
+
+function normalizeFilter(values) {
+  if (!Array.isArray(values) || values.length === 0) return null;
+  return new Set(values.map((value) => String(value).trim()).filter(Boolean));
+}

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/reporters/stressMarkdownReport.js

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ANSI_PATTERN = /\u001B\[[0-?]*[ -/]*[@-~]/g;
+
+export async function writeStressMarkdownReport(result, options = {}) {
+  const filePath = options.filePath || path.join(options.directoryPath || process.cwd(), "stress-report.md");
+  let overwritten = false;
+
+  try {
+    await fs.access(filePath);
+    overwritten = true;
+  } catch {
+    overwritten = false;
+  }
+
+  await fs.writeFile(filePath, reportStressMarkdown(result), "utf8");
+  return { filePath, overwritten };
+}
+
+export function reportStressMarkdown(result) {
+  const details = result.details || {};
+  const tested = details.testedEndpoints || [];
+  const skipped = details.skippedEndpoints || [];
+
+  return stripAnsi(`${[
+    "# ItWorksBut Stress Report",
+    "",
+    `Generated: ${formatTimestamp(details.completedAt || new Date())}`,
+    "",
+    `Target: ${details.target || "unknown"}`,
+    `Duration: ${details.duration ?? "unknown"}s`,
+    `Arrival rate: ${details.arrivalRate ?? "unknown"} req/s`,
+    `Max virtual users: ${details.maxVusers ?? "unknown"}`,
+    "",
+    "## Summary",
+    "",
+    "| Metric | Value |",
+    "|---|---:|",
+    `| Endpoints found | ${details.endpointsFound || 0} |`,
+    `| Endpoints tested | ${tested.length} |`,
+    `| Endpoints skipped | ${skipped.length} |`,
+    `| Warnings | ${details.warnings || 0} |`,
+    `| Failed | ${details.failed || 0} |`,
+    "",
+    "## Tested Endpoints",
+    "",
+    renderTestedEndpoints(tested),
+    "",
+    "## Skipped Endpoints",
+    "",
+    renderSkippedEndpoints(skipped),
+    renderArtilleryError(details.artilleryError),
+    renderRecommendations(result),
+  ].filter((line) => line !== null && line !== undefined).join("\n")}\n`);
+}
+
+function renderTestedEndpoints(endpoints) {
+  if (!endpoints.length) return "None.";
+
+  return [
+    "| Method | Path | Status | p95 | p99 | Errors | Error Rate |",
+    "|---|---|---|---:|---:|---:|---:|",
+    ...endpoints.map((endpoint) => (
+      `| ${escapeTable(endpoint.method)} | ${escapeTable(endpoint.path)} | ${escapeTable(endpoint.status)} | ${formatMs(endpoint.p95)} | ${formatMs(endpoint.p99)} | ${endpoint.errors || 0} | ${formatPercent(endpoint.errorRate)} |`
+    ))
+  ].join("\n");
+}
+
+function renderSkippedEndpoints(endpoints) {
+  if (!endpoints.length) return "None.";
+
+  return [
+    "| Method | Path | Reason |",
+    "|---|---|---|",
+    ...endpoints.map((endpoint) => (
+      `| ${escapeTable(endpoint.method)} | ${escapeTable(endpoint.path)} | ${escapeTable(endpoint.reason)} |`
+    ))
+  ].join("\n");
+}
+
+function renderRecommendations(result) {
+  const details = result.details || {};
+  const recommendations = [];
+
+  if ((details.warnings || 0) > 0) {
+    recommendations.push("Review slow endpoints.");
+    recommendations.push("Add caching or pagination where needed.");
+  }
+  if ((details.failed || 0) > 0 || result.status === "fail") {
+    recommendations.push("Investigate failed requests before increasing load.");
+  }
+  if ((details.skippedEndpoints || []).some((endpoint) => endpoint.reason === "unsafe method")) {
+    recommendations.push("Test mutating endpoints manually in a safe staging environment.");
+  }
+  recommendations.push("Add rate limits before public deployment.");
+
+  return [
+    "",
+    "## Recommendations",
+    "",
+    ...unique(recommendations).map((recommendation) => `- ${recommendation}`),
+    ""
+  ].join("\n");
+}
+
+function renderArtilleryError(error) {
+  if (!error) return "";
+
+  return [
+    "",
+    "## Artillery Error",
+    "",
+    error,
+    ""
+  ].join("\n");
+}
+
+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 formatMs(value) {
+  return value === null || value === undefined ? "n/a" : `${Math.round(value)} ms`;
+}
+
+function formatPercent(value) {
+  return `${Number(value || 0).toFixed(Number.isInteger(value) ? 0 : 2).replace(/\.00$/, "")}%`;
+}
+
+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/stress/artilleryRunner.js

@@ -0,0 +1,83 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { fileExists } from "../utils/fs.js";
+
+const execFileAsync = promisify(execFile);
+const TOOL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+export async function runArtillery(config, options = {}) {
+  if (options.execute) return await options.execute(config, options);
+
+  const rootPath = options.rootPath || process.cwd();
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "itworksbut-stress-"));
+  const configPath = path.join(tempDir, "artillery-config.json");
+  const outputPath = path.join(tempDir, "artillery-report.json");
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+
+  const { command, args } = await resolveArtilleryCommand(rootPath, configPath, outputPath);
+  const timeout = Math.max(90_000, ((options.duration || 30) + 60) * 1000);
+
+  try {
+    const result = await execFileAsync(command, args, {
+      cwd: rootPath,
+      timeout,
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return {
+      ok: true,
+      command,
+      args,
+      stdout: result.stdout || "",
+      stderr: result.stderr || "",
+      exitCode: 0,
+      report: await readJsonFile(outputPath)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      command,
+      args,
+      stdout: error?.stdout || "",
+      stderr: error?.stderr || error?.message || "",
+      exitCode: error?.code ?? null,
+      signal: error?.signal,
+      report: await readJsonFile(outputPath)
+    };
+  }
+}
+
+async function resolveArtilleryCommand(rootPath, configPath, outputPath) {
+  const binaryName = process.platform === "win32" ? "artillery.cmd" : "artillery";
+  const toolBin = path.join(TOOL_ROOT, "node_modules", ".bin", binaryName);
+  if (await fileExists(toolBin)) {
+    return {
+      command: toolBin,
+      args: ["run", configPath, "--output", outputPath]
+    };
+  }
+
+  const projectBin = path.join(rootPath, "node_modules", ".bin", binaryName);
+  if (await fileExists(projectBin)) {
+    return {
+      command: projectBin,
+      args: ["run", configPath, "--output", outputPath]
+    };
+  }
+
+  return {
+    command: process.platform === "win32" ? "npm.cmd" : "npm",
+    args: ["exec", "--yes", "artillery", "--", "run", configPath, "--output", outputPath]
+  };
+}
+
+async function readJsonFile(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}