@vhite/vhite 0.0.0-stage → 0.6.0

package/src/fix/fixers/debugger-statement.js

@@ -0,0 +1,12 @@
+const debuggerFixer = {
+  rule: "debugger-statement",
+  apply(source, issue) {
+    const lines = source.split("\n");
+    const index = issue.line - 1;
+    if (!/^\s*debugger\s*;?\s*$/.test(lines[index] ?? "")) return null;
+    lines.splice(index, 1);
+    return lines.join("\n");
+  },
+};
+
+export default debuggerFixer;

package/src/fix/fixers/index.js

@@ -0,0 +1,9 @@
+import debuggerFixer from "./debugger-statement.js";
+import unusedImportFixer from "./unused-import.js";
+import commentFixer from "./leftover-todo.js";
+
+export const fixers = {
+  [debuggerFixer.rule]: debuggerFixer,
+  [unusedImportFixer.rule]: unusedImportFixer,
+  [commentFixer.rule]: commentFixer,
+};

package/src/fix/fixers/leftover-todo.js

@@ -0,0 +1,32 @@
+const commentFixer = {
+  rule: "leftover-todo",
+  apply(source, issue) {
+    const { type, value, range } = issue.comment ?? {};
+    if (!range) return null;
+
+    const [start, end] = range;
+    const expected = type === "Line" ? `//${value}` : `/*${value}*/`;
+    if (source.slice(start, end) !== expected) return null;
+
+    const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+    const newlineAfter = source.indexOf("\n", end);
+    const lineEnd = newlineAfter === -1 ? source.length : newlineAfter;
+    const before = source.slice(lineStart, start);
+    const after = source.slice(end, lineEnd);
+
+    if (before.trim() === "" && after.trim() === "") {
+      const removeTo = newlineAfter === -1 ? source.length : newlineAfter + 1;
+      return source.slice(0, lineStart) + source.slice(removeTo);
+    }
+
+    const head = source.slice(0, start).replace(/[ \t]+$/, "");
+    if (after.trim() === "") {
+      return head + source.slice(lineEnd);
+    }
+
+    const rest = source.slice(end).replace(/^[ \t]+/, "");
+    return before.trim() === "" ? head + rest : `${head} ${rest}`;
+  },
+};
+
+export default commentFixer;

package/src/fix/fixers/unused-import.js

@@ -0,0 +1,18 @@
+const unusedImportFixer = {
+  rule: "unused-import",
+  apply(source, issue) {
+    const name = issue.message.match(/"([^"]+)"/)?.[1];
+    if (!name) return null;
+    const escaped = name.replace(/\$/g, "\\$");
+    const lines = source.split("\n");
+    const index = issue.line - 1;
+    const single = new RegExp(
+      `^\\s*import\\s+(?:${escaped}|\\{\\s*${escaped}\\s*\\})\\s+from\\s+["'][^"']+["'];?\\s*$`
+    );
+    if (!single.test(lines[index] ?? "")) return null;
+    lines.splice(index, 1);
+    return lines.join("\n");
+  },
+};
+
+export default unusedImportFixer;

package/src/fix/gitignore.js

@@ -0,0 +1,43 @@
+import {
+  readFile,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+
+export const FIX_DIR = ".vhite-fix";
+
+export async function ensureGitignoreEntry(root) {
+  const path = join(root, ".gitignore");
+  const entry = `${FIX_DIR}/`;
+
+  let text = "";
+
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.trim());
+
+  if (lines.includes(entry) || lines.includes(FIX_DIR)) {
+    return false;
+  }
+
+  const separator =
+    text === "" || text.endsWith("\n")
+      ? ""
+      : "\n";
+
+  await writeFile(
+    path,
+    `${text}${separator}${entry}\n`,
+    "utf8"
+  );
+
+  return true;
+}

package/src/fix/safe-fix.js

@@ -0,0 +1,178 @@
+import {
+  readFile,
+  writeFile,
+} from "node:fs/promises";
+import { runRules } from "../core/engine.js";
+import {
+  fixers as defaultFixers,
+} from "./fixers/index.js";
+import {
+  prepareBackupDir,
+  saveBackup,
+  restoreBackup,
+} from "./backup.js";
+
+function summarize(issues) {
+  const counts = new Map();
+
+  for (const issue of issues) {
+    const key = `${issue.rule}|${issue.message}`;
+
+    counts.set(
+      key,
+      (counts.get(key) ?? 0) + 1
+    );
+  }
+
+  return counts;
+}
+
+function isExpectedAfterFix(before, after, key) {
+  const expected = new Map(before);
+
+  if (!expected.get(key)) {
+    return false;
+  }
+
+  const remaining = expected.get(key) - 1;
+
+  if (remaining === 0) {
+    expected.delete(key);
+  } else {
+    expected.set(key, remaining);
+  }
+
+  if (expected.size !== after.size) {
+    return false;
+  }
+
+  for (const [name, count] of expected) {
+    if (after.get(name) !== count) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export async function proposeFixes(
+  issues,
+  { fixers = defaultFixers } = {}
+) {
+  const proposals = [];
+
+  for (const issue of issues) {
+    const fixer = fixers[issue.rule];
+
+    if (!fixer) {
+      continue;
+    }
+
+    const source = await readFile(issue.file, "utf8");
+
+    if (fixer.apply(source, issue) === null) {
+      continue;
+    }
+
+    const lineText = (
+      source.split("\n")[issue.line - 1] ?? ""
+    ).trim();
+
+    proposals.push({
+      ...issue,
+      lineText,
+    });
+  }
+
+  return proposals;
+}
+
+export async function applyApprovedFixes(
+  root,
+  proposals,
+  {
+    fixers = defaultFixers,
+    disabledRules = new Set(),
+  } = {}
+) {
+  const { changed } = await prepareBackupDir(root);
+  const results = [];
+
+  const ordered = [...proposals].sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      b.line - a.line
+  );
+
+  let attempt = 0;
+
+  for (const proposal of ordered) {
+    attempt += 1;
+
+    const fixer = fixers[proposal.rule];
+
+    if (!fixer) {
+      results.push({
+        proposal,
+        status: "skipped",
+        reason: "No fixer is registered for this rule",
+      });
+
+      continue;
+    }
+
+    const source = await readFile(proposal.file, "utf8");
+    const candidate = fixer.apply(source, proposal);
+
+    if (candidate === null) {
+      results.push({
+        proposal,
+        status: "skipped",
+        reason: "The line no longer matches a safe fix",
+      });
+
+      continue;
+    }
+
+    const before = summarize(
+      await runRules([proposal.file], { disabledRules })
+    );
+
+    const backupPath = await saveBackup(
+      root,
+      proposal.file,
+      attempt
+    );
+
+    await writeFile(proposal.file, candidate, "utf8");
+
+    const after = summarize(
+      await runRules([proposal.file], { disabledRules })
+    );
+
+    const key = `${proposal.rule}|${proposal.message}`;
+
+    if (isExpectedAfterFix(before, after, key)) {
+      results.push({
+        proposal,
+        status: "applied",
+        backupPath,
+      });
+    } else {
+      await restoreBackup(proposal.file, backupPath);
+
+      results.push({
+        proposal,
+        status: "rolled back",
+        backupPath,
+        reason:
+          "The change did not fix the issue cleanly, so the original was restored",
+      });
+    }
+  }
+
+  return {
+    results,
+    gitignoreUpdated: changed,
+  };
+}

package/src/output/explanations-frontend.js

@@ -0,0 +1,22 @@
+export const frontendExplanations = {
+  "react-missing-key": {
+    whatHappened: "Items in a list are created without a key. React uses keys to track items, so without them it can reuse or lose the wrong elements when the list changes.",
+    proposedChange: "Add a key prop with a value that is unique and stable for each item, such as an id from your data. Avoid using the array index when items can be added, removed, or reordered.",
+  },
+  "react-dangerous-html": {
+    whatHappened: "dangerouslySetInnerHTML inserts raw HTML into the page. If that HTML comes from users or an API, it can contain scripts that run in other people's browsers.",
+    proposedChange: "Render the content with normal JSX where possible. If raw HTML is required, sanitize it first with a trusted library such as DOMPurify.",
+  },
+  "a11y-img-alt": {
+    whatHappened: "An image without alt text is silent for people using screen readers, and it shows nothing if the image fails to load.",
+    proposedChange: "Add alt text that describes what the image shows or means. For decorative images, use alt=\"\" so screen readers skip them.",
+  },
+  "a11y-input-label": {
+    whatHappened: "A form input without a label is hard to use with a screen reader, because the user can't tell what to type.",
+    proposedChange: "Connect the input to a label element with a matching htmlFor and id, or add an aria-label that describes the field.",
+  },
+  "a11y-click-div": {
+    whatHappened: "A clickable div or span can be clicked with a mouse, but it can't be reached with a keyboard and screen readers don't announce it as a button.",
+    proposedChange: "Use a button element for actions and an a element for links. If you must use a div, add role, tabIndex, and a key handler for Enter and Space.",
+  },
+};

package/src/output/explanations.js

@@ -0,0 +1,37 @@
+  import { frontendExplanations } from "./explanations-frontend.js";
+export const explanations = {
+   "leftover-todo": {
+    whatHappened: "A comment is still in the code. Comments that mark unfinished work (TODO or FIXME) are easy to forget before release, and other comments can go out of date and mislead the next developer.",
+    proposedChange: "Finish the task and delete the note, or move it to your issue tracker. Delete other comments that no longer explain anything.",
+  },
+  "debugger-statement": {
+    whatHappened: "A debugger statement pauses the program whenever developer tools are open. Left in, it can freeze the app for anyone who has them open.",
+    proposedChange: "Delete the debugger line.",
+  },
+  "console-log": {
+    whatHappened: "A console.log call prints a message to the console. It's often a leftover from debugging, and it can reveal internal details to anyone who opens developer tools.",
+    proposedChange: "Delete the line if it was only for debugging. If the output is needed, keep it but make the message clear, or remove it before release.",
+  },
+  "empty-catch": {
+    whatHappened: "This catch block catches an error and does nothing with it. If something fails, the app keeps going silently and nobody sees the problem.",
+    proposedChange: "Log the error, for example with console.error(error), or show the user a helpful message. If ignoring the error is truly intended, add a comment explaining why.",
+  },
+  "unused-import": {
+    whatHappened: "This file imports something it never uses. It adds clutter and can make the file load slower.",
+    proposedChange: "Delete the unused import line.",
+  },
+  "empty-block": {
+    whatHappened: "An if, else, or loop has a body with no code in it. This often means logic was started and never finished.",
+    proposedChange: "Add the missing logic, or delete the block if it isn't needed. If the empty block is intentional, add a comment saying so.",
+  },
+  "hardcoded-secret": {
+    whatHappened: "A value that looks like a password, API key, or token is written directly in the code. Anyone who can read the code can use it.",
+    proposedChange: "Move the value into an environment variable or a settings file that isn't shared. If it was a real value, replace it at the service that issued it, since it may already be exposed.",
+  },
+  parser: {
+    whatHappened: "vhite couldn't read this file as JavaScript, so it skipped the checks that need to understand the code.",
+    proposedChange: "Open the file at the line shown and fix the syntax error, then scan again.",
+  },
+      ...frontendExplanations,
+};
+

package/src/output/json-output.js

@@ -0,0 +1,47 @@
+import { relative, sep } from "node:path";
+
+function toPosix(path) {
+  return path.split(sep).join("/");
+}
+
+export function formatJson({ root, filesScanned, issues, fixes = [], version }) {
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const issue of issues) {
+    counts[issue.severity] = (counts[issue.severity] ?? 0) + 1;
+  }
+
+  const sorted = [...issues].sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      a.line - b.line ||
+      (a.column ?? 1) - (b.column ?? 1)
+  );
+
+  return JSON.stringify(
+    {
+      version,
+      root: toPosix(root),
+      filesScanned,
+      summary: { total: issues.length, ...counts },
+      issues: sorted.map((issue) => ({
+        rule: issue.rule,
+        severity: issue.severity,
+        file: toPosix(relative(root, issue.file)),
+        line: issue.line,
+        column: issue.column ?? 1,
+        endLine: issue.endLine ?? issue.line,
+        endColumn: issue.endColumn ?? issue.column ?? 1,
+        message: issue.message,
+        snippet: issue.snippet,
+      })),
+      fixes: fixes.map((result) => ({
+        rule: result.proposal.rule,
+        file: toPosix(relative(root, result.proposal.file)),
+        line: result.proposal.line,
+        status: result.status,
+      })),
+    },
+    null,
+    2
+  );
+}

package/src/output/reporter.js

@@ -0,0 +1,52 @@
+import { relative } from "node:path";
+import { explanations } from "./explanations.js";
+
+function caretFor(issue) {
+  const startColumn = issue.column ?? 1;
+  const width =
+    issue.endLine === issue.line && issue.endColumn > startColumn
+      ? issue.endColumn - startColumn
+      : Math.max(1, issue.snippet.length - startColumn + 1);
+  return " ".repeat(startColumn - 1) + "^".repeat(width);
+}
+
+export function formatReport(issues, root) {
+  if (issues.length === 0) return "No issues found.";
+
+  const byFile = new Map();
+  for (const issue of issues) {
+    if (!byFile.has(issue.file)) byFile.set(issue.file, []);
+    byFile.get(issue.file).push(issue);
+  }
+
+  const lines = [];
+  const sortedFiles = [...byFile.keys()].sort((a, b) =>
+    relative(root, a).localeCompare(relative(root, b))
+  );
+  for (const file of sortedFiles) {
+    const fileIssues = byFile.get(file);
+    lines.push(relative(root, file));
+    fileIssues.sort(
+      (a, b) => a.line - b.line || (a.column ?? 1) - (b.column ?? 1)
+    );
+    for (const issue of fileIssues) {
+      lines.push(`  Line ${issue.line}: ${issue.message} [${issue.rule}]`);
+
+      if (issue.snippet !== undefined && issue.endLine !== undefined) {
+        const gutter = String(issue.line);
+        const blank = " ".repeat(gutter.length);
+        lines.push(`    ${gutter} | ${issue.snippet}`);
+        lines.push(`    ${blank} | ${caretFor(issue)}`);
+      }
+
+      const info = explanations[issue.rule];
+      if (info) {
+        lines.push(`    What happened: ${info.whatHappened}`);
+        lines.push(`    Proposed change: ${info.proposedChange}`);
+      }
+      lines.push("");
+    }
+  }
+  lines.push(`${issues.length} issue(s) in ${byFile.size} file(s)`);
+  return lines.join("\n");
+}

package/src/output/run-report.js

@@ -0,0 +1,194 @@
+import {
+  mkdir,
+  writeFile,
+} from "node:fs/promises";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline/promises";
+import {
+  FIX_DIR,
+  ensureGitignoreEntry,
+} from "../fix/gitignore.js";
+
+function escapeMarkdown(value) {
+  return String(value ?? "")
+    .replace(/\|/g, "\\|")
+    .replace(/\r?\n/g, " ");
+}
+
+export function formatMarkdownRunReport({
+  root,
+  target = root,
+  startedAt = new Date(),
+  finishedAt = new Date(),
+  filesScanned = 0,
+  issues = [],
+  proposals = [],
+  fixResults = [],
+  logs = [],
+  backupCleanup = null,
+}) {
+  const applied = fixResults.filter(
+    (item) => item.status === "applied"
+  ).length;
+
+  const skipped = fixResults.filter(
+    (item) => item.status === "skipped"
+  ).length;
+
+  const rolledBack = fixResults.filter(
+    (item) => item.status === "rolled back"
+  ).length;
+
+  const lines = [
+    "# Vhite CLI — Run Report",
+    "",
+    "## Run overview",
+    "",
+    `- **Project:** \`${target}\``,
+    `- **Started:** ${startedAt.toISOString()}`,
+    `- **Finished:** ${finishedAt.toISOString()}`,
+    `- **Files scanned:** ${filesScanned}`,
+    `- **Issues detected:** ${issues.length}`,
+    `- **Fix proposals:** ${proposals.length}`,
+    `- **Fixes applied:** ${applied}`,
+    `- **Fixes skipped:** ${skipped}`,
+    `- **Fixes rolled back:** ${rolledBack}`,
+    "",
+    "## Issues detected",
+    "",
+  ];
+
+  if (issues.length === 0) {
+    lines.push("No issues were detected.", "");
+  } else {
+    lines.push(
+      "| File | Line | Rule | Finding |",
+      "|---|---:|---|---|"
+    );
+
+    for (const issue of issues) {
+      lines.push(
+        `| \`${escapeMarkdown(relative(root, issue.file))}\` | ${issue.line} | \`${escapeMarkdown(issue.rule)}\` | ${escapeMarkdown(issue.message)} |`
+      );
+    }
+
+    lines.push("");
+  }
+
+  lines.push("## Fix results", "");
+
+  if (fixResults.length === 0) {
+    lines.push("No fixes were applied during this run.", "");
+  } else {
+    lines.push(
+      "| Status | File | Line | Rule | Details |",
+      "|---|---|---:|---|---|"
+    );
+
+    for (const result of fixResults) {
+      const proposal = result.proposal ?? {};
+      const file = proposal.file
+        ? relative(root, proposal.file)
+        : "—";
+
+      lines.push(
+        `| ${escapeMarkdown(result.status)} | \`${escapeMarkdown(file)}\` | ${proposal.line ?? "—"} | \`${escapeMarkdown(proposal.rule ?? "—")}\` | ${escapeMarkdown(result.reason ?? "No additional details")} |`
+      );
+    }
+
+    lines.push("");
+  }
+
+  lines.push("## Backup management", "");
+
+  if (backupCleanup) {
+    lines.push(
+      `- **Cleanup requested:** ${backupCleanup.requested ? "Yes" : "No"}`,
+      `- **Backup files deleted:** ${backupCleanup.deleted ?? 0}`,
+      `- **Backups retained:** ${backupCleanup.requested ? "No current-run backups were intentionally retained by cleanup" : "Current-run backups were kept"}`,
+      ""
+    );
+  } else {
+    lines.push("No backup cleanup decision was recorded.", "");
+  }
+
+  lines.push("## Terminal log", "", "```text");
+
+  if (logs.length === 0) {
+    lines.push("No captured terminal log entries.");
+  } else {
+    lines.push(...logs);
+  }
+
+  lines.push(
+    "```",
+    "",
+    "## Final notes",
+    "",
+    "- Review any unresolved findings.",
+    "- A rolled-back fix means the original file was restored after verification failed.",
+    "- Run your project's tests before shipping changes.",
+    ""
+  );
+
+  return lines.join("\n");
+}
+
+export async function writeRunReport(options) {
+  const { root } = options;
+
+  const reportDir = join(root, FIX_DIR, "reports");
+  const gitignoreUpdated = await ensureGitignoreEntry(root);
+
+  await mkdir(reportDir, { recursive: true });
+
+  const timestamp = (options.finishedAt ?? new Date())
+    .toISOString()
+    .replace(/[:.]/g, "-");
+
+  const filename = `vhite-report-${timestamp}.md`;
+  const reportPath = join(reportDir, filename);
+  const content = formatMarkdownRunReport(options);
+
+  await writeFile(reportPath, content, "utf8");
+
+  return {
+    reportPath,
+    content,
+    gitignoreUpdated,
+  };
+}
+
+export async function askYesNo(
+  question,
+  { defaultYes = false } = {}
+) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const suffix = defaultYes ? " (Y/n): " : " (y/N): ";
+    const answer = (
+      await rl.question(question + suffix)
+    ).trim().toLowerCase();
+
+    if (answer === "") {
+      return defaultYes;
+    }
+
+    if (["y", "yes"].includes(answer)) {
+      return true;
+    }
+
+    if (["n", "no"].includes(answer)) {
+      return false;
+    }
+
+    console.log("Please enter y or n. Your answer defaults to No.");
+    return false;
+  } finally {
+    rl.close();
+  }
+}