itworksbut 0.1.1

package/src/core/fileWalker.js

@@ -0,0 +1,44 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isLikelyTextFile } from "../utils/fs.js";
+import { matchesAnyGlob, normalizeRelativePath, relativePath } from "../utils/path.js";
+
+export async function walkProject(rootPath, ignorePatterns) {
+  const allFiles = [];
+  const textFiles = [];
+
+  async function visit(directory) {
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const absolutePath = path.join(directory, entry.name);
+      const relPath = relativePath(rootPath, absolutePath);
+      if (!relPath || matchesAnyGlob(relPath, ignorePatterns)) continue;
+
+      if (entry.isSymbolicLink()) continue;
+
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+      const normalized = normalizeRelativePath(relPath);
+      allFiles.push(normalized);
+      if (await isLikelyTextFile(absolutePath)) {
+        textFiles.push(normalized);
+      }
+    }
+  }
+
+  await visit(rootPath);
+
+  allFiles.sort();
+  textFiles.sort();
+  return { allFiles, textFiles };
+}

package/src/core/findings.js

@@ -0,0 +1,39 @@
+import { SEVERITIES } from "./config.js";
+
+export const severityRank = new Map(SEVERITIES.map((severity, index) => [severity, SEVERITIES.length - index]));
+
+export function normalizeFinding(check, finding) {
+  return {
+    checkId: finding.checkId || check.id,
+    title: finding.title || check.title,
+    category: finding.category || check.category,
+    severity: normalizeFindingSeverity(finding.severity || check.severity),
+    message: finding.message || check.title,
+    file: finding.file,
+    line: finding.line,
+    column: finding.column,
+    recommendation: finding.recommendation,
+    tags: finding.tags || check.tags || [],
+    heuristic: Boolean(finding.heuristic),
+    metadata: finding.metadata || undefined
+  };
+}
+
+export function normalizeFindingSeverity(value) {
+  const normalized = String(value || "info").toLowerCase();
+  return SEVERITIES.includes(normalized) ? normalized : "info";
+}
+
+export function isAtOrAbove(severity, threshold) {
+  return severityRank.get(severity) >= severityRank.get(threshold);
+}
+
+export function getExitCode(findings, failOn) {
+  return findings.some((finding) => isAtOrAbove(finding.severity, failOn)) ? 1 : 0;
+}
+
+export function countBySeverity(findings) {
+  return Object.fromEntries(
+    SEVERITIES.map((severity) => [severity, findings.filter((finding) => finding.severity === severity).length])
+  );
+}

package/src/core/git.js

@@ -0,0 +1,92 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { normalizeRelativePath } from "../utils/path.js";
+
+const execFileAsync = promisify(execFile);
+
+export async function collectGitInfo(rootPath) {
+  const gitAvailable = await isInsideGitWorkTree(rootPath);
+  if (!gitAvailable) {
+    return {
+      available: false,
+      trackedFiles: [],
+      ignoredFiles: [],
+      ignoredTrackedFiles: [],
+      statusShort: []
+    };
+  }
+
+  const [trackedFiles, ignoredFiles, ignoredTrackedFiles, statusShort] = await Promise.all([
+    gitLsFiles(rootPath, []),
+    gitLsFiles(rootPath, ["--others", "-i", "--exclude-standard"]),
+    gitLsFiles(rootPath, ["-ci", "--exclude-standard"]),
+    gitStatusShort(rootPath)
+  ]);
+
+  return {
+    available: true,
+    trackedFiles,
+    ignoredFiles,
+    ignoredTrackedFiles,
+    statusShort
+  };
+}
+
+export async function checkIgnored(rootPath, files) {
+  const ignored = new Set();
+  const candidates = files.filter(Boolean);
+  for (let index = 0; index < candidates.length; index += 100) {
+    const chunk = candidates.slice(index, index + 100);
+    const result = await runGit(rootPath, ["check-ignore", "--no-index", "-z", "--", ...chunk], [0, 1]);
+    if (result.stdout) {
+      for (const file of parseNullSeparated(result.stdout)) ignored.add(file);
+    }
+  }
+  return [...ignored];
+}
+
+async function isInsideGitWorkTree(rootPath) {
+  const result = await runGit(rootPath, ["rev-parse", "--is-inside-work-tree"], [0, 128]);
+  return result.exitCode === 0 && result.stdout.trim() === "true";
+}
+
+async function gitLsFiles(rootPath, args) {
+  const result = await runGit(rootPath, ["ls-files", "-z", ...args], [0]);
+  return parseNullSeparated(result.stdout);
+}
+
+async function gitStatusShort(rootPath) {
+  const result = await runGit(rootPath, ["status", "--short"], [0]);
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+}
+
+async function runGit(rootPath, args, allowedExitCodes) {
+  try {
+    const { stdout, stderr } = await execFileAsync("git", args, {
+      cwd: rootPath,
+      encoding: "buffer",
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return { exitCode: 0, stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8") };
+  } catch (error) {
+    const exitCode = typeof error.code === "number" ? error.code : 1;
+    if (allowedExitCodes.includes(exitCode)) {
+      return {
+        exitCode,
+        stdout: Buffer.isBuffer(error.stdout) ? error.stdout.toString("utf8") : String(error.stdout || ""),
+        stderr: Buffer.isBuffer(error.stderr) ? error.stderr.toString("utf8") : String(error.stderr || "")
+      };
+    }
+    return { exitCode, stdout: "", stderr: error.message };
+  }
+}
+
+function parseNullSeparated(output) {
+  return output
+    .split("\0")
+    .filter(Boolean)
+    .map((file) => normalizeRelativePath(file));
+}

package/src/core/scanner.js

@@ -0,0 +1,56 @@
+import checks from "../checks/index.js";
+import { createContext } from "./context.js";
+import { normalizeFinding, severityRank } from "./findings.js";
+
+export async function scanProject(options = {}) {
+  const startedAt = new Date();
+  const context = await createContext(options);
+  const findings = [];
+  const warnings = [];
+
+  for (const check of checks) {
+    if (context.config.checks[check.id] === false) continue;
+
+    try {
+      const checkFindings = await check.run(context);
+      if (!Array.isArray(checkFindings)) {
+        warnings.push({
+          checkId: check.id,
+          message: "Check returned a non-array result and was ignored."
+        });
+        continue;
+      }
+      for (const finding of checkFindings) {
+        findings.push(normalizeFinding(check, finding));
+      }
+    } catch (error) {
+      warnings.push({
+        checkId: check.id,
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  findings.sort((a, b) => {
+    const bySeverity = severityRank.get(b.severity) - severityRank.get(a.severity);
+    if (bySeverity !== 0) return bySeverity;
+    return `${a.checkId}:${a.file || ""}:${a.line || 0}`.localeCompare(`${b.checkId}:${b.file || ""}:${b.line || 0}`);
+  });
+
+  return {
+    findings,
+    warnings,
+    config: context.config,
+    meta: {
+      tool: "ItWorksBut",
+      version: "0.1.0",
+      rootPath: context.rootPath,
+      packageManager: context.packageManager,
+      gitAvailable: context.gitAvailable,
+      filesScanned: context.allFiles.length,
+      textFilesScanned: context.textFiles.length,
+      startedAt: startedAt.toISOString(),
+      completedAt: new Date().toISOString()
+    }
+  };
+}

package/src/reporters/consoleReporter.js

@@ -0,0 +1,107 @@
+import { SEVERITIES } from "../core/config.js";
+import { countBySeverity, getExitCode } from "../core/findings.js";
+import { isFancyOutputEnabled, getChalk } from "../cli/terminal.js";
+import { formatSeverity, getConsoleFindingTitle, getShipStatus, renderSummaryBox, renderSummaryTable } from "./consoleStyle.js";
+
+export function reportConsole(result, options = {}) {
+  const { findings, warnings, config, meta } = result;
+  const counts = countBySeverity(findings);
+  const colors = getChalk(options);
+  const rich = isFancyOutputEnabled(options);
+
+  if (!options.quiet && !rich) {
+    process.stdout.write(`${colors.bold("ItWorksBut receipts")}\n\n`);
+  }
+
+  if (!options.quiet && findings.length === 0) {
+    process.stdout.write(`${colors.green ? colors.green("Suspiciously clean. No findings.") : "Suspiciously clean. No findings."}\n\n`);
+  } else if (!options.quiet) {
+    for (const severity of SEVERITIES) {
+      const group = findings.filter((finding) => finding.severity === severity);
+      if (group.length === 0) continue;
+
+      for (const finding of group) {
+        writeFinding(finding, options);
+      }
+      process.stdout.write("\n");
+    }
+  }
+
+  if (options.verbose && warnings.length > 0) {
+    process.stdout.write("WARNINGS\n");
+    for (const warning of warnings) {
+      process.stdout.write(`- [${warning.checkId}] ${warning.message}\n`);
+    }
+    process.stdout.write("\n");
+  }
+
+  const exitCode = getExitCode(findings, config.failOn);
+  writeSummary({ counts, total: findings.length, failOn: config.failOn, exitCode }, options);
+
+  if (options.verbose) {
+    process.stdout.write(`- files scanned: ${meta.filesScanned}\n`);
+    process.stdout.write(`- text files scanned: ${meta.textFilesScanned}\n`);
+    process.stdout.write(`- git available: ${meta.gitAvailable}\n`);
+    process.stdout.write(`- warnings: ${warnings.length}\n`);
+  }
+}
+
+function writeFinding(finding, options) {
+  const colors = getChalk(options);
+  const severity = formatSeverity(finding.severity, options);
+  const title = getConsoleFindingTitle(finding);
+  const location = finding.file ? (finding.line ? `${finding.file}:${finding.line}` : finding.file) : "";
+
+  if (options.compact) {
+    const where = location ? `${location} - ` : "";
+    process.stdout.write(`${severity.compactText} ${finding.checkId} ${where}${title}\n`);
+    return;
+  }
+
+  process.stdout.write(`${severity.text}  ${colors.bold(title)}${finding.heuristic ? colors.gray(" (heuristic)") : ""}\n`);
+  process.stdout.write(`   Check: ${finding.checkId}\n`);
+  if (location) process.stdout.write(`   File:  ${location}\n`);
+  process.stdout.write(`   Why:   ${finding.message}\n`);
+  if (finding.recommendation) process.stdout.write(`   Fix:   ${finding.recommendation}\n`);
+
+  if (options.verbose) {
+    process.stdout.write(`   Category: ${finding.category || "unknown"}\n`);
+    if (finding.tags?.length) process.stdout.write(`   Tags:     ${finding.tags.join(", ")}\n`);
+    if (finding.line) process.stdout.write(`   Line:     ${finding.line}\n`);
+    const evidence = safeEvidence(finding);
+    if (evidence) process.stdout.write(`   Evidence: ${evidence}\n`);
+  }
+
+  process.stdout.write("\n");
+}
+
+function writeSummary({ counts, total, failOn, exitCode }, options) {
+  const colors = getChalk(options);
+  const ship = getShipStatus(counts);
+
+  if (isFancyOutputEnabled(options)) {
+    process.stdout.write(`${renderSummaryBox(counts, options)}\n`);
+    process.stdout.write(`${renderSummaryTable(counts, options)}\n`);
+    process.stdout.write(`\nFail-on: ${failOn} | Exit decision: ${exitCode}\n`);
+    return;
+  }
+
+  process.stdout.write("SUMMARY\n");
+  process.stdout.write(`- ship status: ${colors.bold(ship.status)}\n`);
+  process.stdout.write(`- ${ship.tone}\n`);
+  process.stdout.write(`- total findings: ${total}\n`);
+  for (const severity of SEVERITIES) {
+    process.stdout.write(`- ${severity}: ${counts[severity]}\n`);
+  }
+  process.stdout.write(`- fail-on: ${failOn}\n`);
+  process.stdout.write(`- exit decision: ${exitCode}\n`);
+}
+
+function safeEvidence(finding) {
+  const metadata = finding.metadata || {};
+  if (metadata.secretType) return `secret type: ${metadata.secretType}; value redacted`;
+  if (metadata.pattern) return `pattern: ${metadata.pattern}`;
+  if (metadata.routePath) return `route: ${metadata.routePath}`;
+  if (metadata.envName) return `environment variable name: ${metadata.envName}`;
+  return "";
+}

package/src/reporters/consoleStyle.js

@@ -0,0 +1,155 @@
+import boxen from "boxen";
+import Table from "cli-table3";
+import { SEVERITIES } from "../core/config.js";
+import { getChalk, normalizeTheme } from "../cli/terminal.js";
+
+const EDGY_TITLES = {
+  "env.env-file-tracked": "It works, but your .env is tracked.",
+  "env.possible-secret-in-code": "It works, but your repo may be leaking secrets.",
+  "env.frontend-secret-exposure": "It works, but your frontend env variable smells like a backend secret.",
+  "git.gitignore-missing": "It works, but your repo forgot what not to commit.",
+  "git.gitignore-incomplete": "It works, but your .gitignore has holes.",
+  "git.ignored-files-tracked": "It works, but Git is already tracking files you meant to ignore.",
+  "dependencies.lockfile-missing": "It works on your machine, but your dependency tree is not locked.",
+  "dependencies.multiple-lockfiles": "It works, but your package managers are fighting.",
+  "ci.no-ci-config": "It works, but nobody checks it before it ships.",
+  "ci.npm-install-instead-of-npm-ci": "It works, but your CI is installing instead of reproducing.",
+  "ci.no-test-step": "It works, but your CI is basically decorative.",
+  "node.express-json-limit-missing": "It works, but your API accepts oversized bodies.",
+  "node.rate-limit-missing": "It works, but your endpoints have no brakes.",
+  "node.helmet-missing": "It works, but your HTTP headers are underdressed.",
+  "node.cors-wildcard": "It works, but CORS is holding the door open.",
+  "web.dangerous-inner-html": "It works, but your frontend is injecting HTML with sharp edges.",
+  "api.missing-auth-on-routes": "It works, but this API route appears to trust strangers.",
+  "api.idor-risk": "It works, but this ID lookup may belong to someone else.",
+  "database.raw-sql-interpolation": "It works, but your SQL query is one template string away from pain.",
+  "database.no-migrations": "It works, but your database schema has no paper trail.",
+  "electron.node-integration-enabled": "It works, but Electron is holding the Node.js door open.",
+  "electron.context-isolation-disabled": "It works, but your renderer and backend are sharing a room.",
+  "tauri.dangerous-allowlist-or-capabilities": "It works, but your Tauri permissions look too generous."
+};
+
+const SEVERITY_META = {
+  critical: { symbol: "✖", label: "CRITICAL" },
+  high: { symbol: "▲", label: "HIGH" },
+  medium: { symbol: "◆", label: "MEDIUM" },
+  low: { symbol: "•", label: "LOW" },
+  info: { symbol: "i", label: "INFO" }
+};
+
+export function getConsoleFindingTitle(finding) {
+  if (EDGY_TITLES[finding.checkId]) return EDGY_TITLES[finding.checkId];
+  if (finding.heuristic) return `It works, but this pattern may be risky: ${finding.title || finding.checkId}.`;
+  return `It works, but ${lowercaseFirst(finding.title || finding.message || finding.checkId)}.`;
+}
+
+export function formatSeverity(severity, options = {}) {
+  const colors = getChalk(options);
+  const meta = SEVERITY_META[severity] || SEVERITY_META.info;
+  const raw = `${meta.symbol}  ${meta.label}`;
+
+  if (normalizeTheme(options.theme) === "mono") {
+    return {
+      ...meta,
+      text: colors.bold(raw),
+      compactText: colors.bold(`${meta.symbol} ${meta.label}`)
+    };
+  }
+
+  const stylers = {
+    critical: (value) => colors.bgRed.white.bold(value),
+    high: (value) => colors.red.bold(value),
+    medium: (value) => colors.yellow.bold(value),
+    low: (value) => colors.blue(value),
+    info: (value) => colors.gray(value)
+  };
+
+  const style = stylers[severity] || stylers.info;
+  return {
+    ...meta,
+    text: style(raw),
+    compactText: style(`${meta.symbol} ${meta.label}`)
+  };
+}
+
+export function getShipStatus(counts) {
+  if (counts.critical > 0) {
+    return {
+      status: "DO NOT SHIP",
+      tone: "Fix the red stuff before production.",
+      severity: "critical"
+    };
+  }
+  if (counts.high > 0) {
+    return {
+      status: "FIX BEFORE SHIP",
+      tone: "Close the obvious holes before shipping.",
+      severity: "high"
+    };
+  }
+  if (counts.medium > 0) {
+    return {
+      status: "SHIP WITH CAUTION",
+      tone: "You can ship, but future-you will ask questions.",
+      severity: "medium"
+    };
+  }
+  return {
+    status: "SHIP IT, BUT STAY PARANOID",
+    tone: "Suspiciously clean. Ship it, but stay paranoid.",
+    severity: "info"
+  };
+}
+
+export function renderSummaryBox(counts, options = {}) {
+  const colors = getChalk(options);
+  const ship = getShipStatus(counts);
+  const severity = formatSeverity(ship.severity, options);
+  const content = [
+    colors.bold("It works, but..."),
+    "",
+    `Ship status: ${severity.label === "INFO" ? colors.bold(ship.status) : severityColor(ship.status, ship.severity, colors)}`,
+    `Critical: ${counts.critical}`,
+    `High:     ${counts.high}`,
+    `Medium:   ${counts.medium}`,
+    "",
+    ship.tone
+  ].join("\n");
+
+  return boxen(content, {
+    padding: 1,
+    margin: 1,
+    borderStyle: "round",
+    borderColor: ship.severity === "critical" || ship.severity === "high" ? "red" : ship.severity === "medium" ? "yellow" : "green"
+  });
+}
+
+export function renderSummaryTable(counts, options = {}) {
+  const table = new Table({
+    head: ["Severity", "Count"],
+    style: {
+      head: [],
+      border: []
+    }
+  });
+
+  for (const severity of SEVERITIES) {
+    const formatted = formatSeverity(severity, options);
+    table.push([formatted.compactText, counts[severity]]);
+  }
+
+  return table.toString();
+}
+
+function severityColor(value, severity, colors) {
+  if (severity === "critical") return colors.bgRed.white.bold(value);
+  if (severity === "high") return colors.red.bold(value);
+  if (severity === "medium") return colors.yellow.bold(value);
+  return colors.bold(value);
+}
+
+function lowercaseFirst(value) {
+  if (!value) return value;
+  const normalized = String(value).replace(/\.$/, "");
+  return `${normalized.charAt(0).toLowerCase()}${normalized.slice(1)}`;
+}

package/src/reporters/jsonReporter.js

@@ -0,0 +1,17 @@
+import { countBySeverity, getExitCode } from "../core/findings.js";
+
+export function reportJson(result) {
+  return {
+    tool: result.meta.tool,
+    version: result.meta.version,
+    meta: result.meta,
+    summary: {
+      total: result.findings.length,
+      bySeverity: countBySeverity(result.findings),
+      failOn: result.config.failOn,
+      exitCode: getExitCode(result.findings, result.config.failOn)
+    },
+    findings: result.findings,
+    warnings: result.warnings
+  };
+}

package/src/reporters/sarifReporter.js

@@ -0,0 +1,82 @@
+const SARIF_VERSION = "2.1.0";
+
+export function reportSarif(result) {
+  const rules = buildRules(result.findings);
+
+  return {
+    version: SARIF_VERSION,
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "ItWorksBut",
+            informationUri: "https://github.com/itworksbut/itworksbut",
+            rules
+          }
+        },
+        results: result.findings.map(toSarifResult),
+        invocations: [
+          {
+            executionSuccessful: true,
+            toolExecutionNotifications: result.warnings.map((warning) => ({
+              level: "warning",
+              message: { text: `[${warning.checkId}] ${warning.message}` }
+            }))
+          }
+        ]
+      }
+    ]
+  };
+}
+
+function buildRules(findings) {
+  const byId = new Map();
+  for (const finding of findings) {
+    if (byId.has(finding.checkId)) continue;
+    byId.set(finding.checkId, {
+      id: finding.checkId,
+      name: finding.checkId,
+      shortDescription: { text: finding.title },
+      fullDescription: { text: finding.message },
+      help: { text: finding.recommendation || finding.title },
+      properties: {
+        category: finding.category,
+        tags: finding.tags || [],
+        precision: finding.heuristic ? "low" : "medium"
+      }
+    });
+  }
+  return [...byId.values()];
+}
+
+function toSarifResult(finding) {
+  return {
+    ruleId: finding.checkId,
+    level: sarifLevel(finding.severity),
+    message: { text: finding.message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: finding.file || "." },
+          region: {
+            startLine: finding.line || 1,
+            startColumn: finding.column || 1
+          }
+        }
+      }
+    ],
+    properties: {
+      severity: finding.severity,
+      category: finding.category,
+      recommendation: finding.recommendation,
+      heuristic: finding.heuristic
+    }
+  };
+}
+
+function sarifLevel(severity) {
+  if (severity === "critical" || severity === "high") return "error";
+  if (severity === "medium" || severity === "low") return "warning";
+  return "note";
+}

package/src/utils/fs.js

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const MAX_TEXT_FILE_BYTES = 1024 * 1024;
+
+export async function fileExists(absolutePath) {
+  try {
+    await fs.access(absolutePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readFileSafe(absolutePath, maxBytes = MAX_TEXT_FILE_BYTES) {
+  try {
+    const stat = await fs.stat(absolutePath);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    return await fs.readFile(absolutePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export async function readJsonSafe(absolutePath) {
+  const content = await readFileSafe(absolutePath);
+  if (!content) return null;
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export function resolveInside(rootPath, relativePath) {
+  return path.resolve(rootPath, relativePath);
+}
+
+export async function isLikelyTextFile(absolutePath, maxBytes = MAX_TEXT_FILE_BYTES) {
+  try {
+    const stat = await fs.stat(absolutePath);
+    if (!stat.isFile() || stat.size > maxBytes) return false;
+
+    const handle = await fs.open(absolutePath, "r");
+    try {
+      const length = Math.min(8192, stat.size);
+      const buffer = Buffer.alloc(length);
+      await handle.read(buffer, 0, length, 0);
+      if (buffer.includes(0)) return false;
+      return true;
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return false;
+  }
+}

package/src/utils/mask.js

@@ -0,0 +1,14 @@
+export function maskSecret(value) {
+  if (!value) return "";
+  const text = String(value);
+  if (text.length <= 8) return "*".repeat(text.length);
+  const prefixLength = Math.min(8, Math.ceil(text.length / 4));
+  const suffixLength = Math.min(4, Math.ceil(text.length / 5));
+  return `${text.slice(0, prefixLength)}${"*".repeat(Math.max(8, text.length - prefixLength - suffixLength))}${text.slice(-suffixLength)}`;
+}
+
+export function redactLine(line) {
+  return line.replace(/([A-Z0-9_]*(?:SECRET|TOKEN|KEY|PASSWORD|DATABASE_URL)[A-Z0-9_]*\s*[:=]\s*["']?)([^"'\s]+)/gi, (_match, prefix, value) => {
+    return `${prefix}${maskSecret(value)}`;
+  });
+}