@vhite/vhite 0.0.0-stage → 0.1.0

package/src/approve.js

@@ -0,0 +1,71 @@
+import { createInterface } from "node:readline/promises";
+import { relative } from "node:path";
+
+export async function chooseProposals(root, proposals) {
+  if (proposals.length === 0) {
+    return [];
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log(`\n${proposals.length} safe fix(es) available:\n`);
+
+    proposals.forEach((proposal, index) => {
+      console.log(
+        ` ${index + 1}. ${relative(root, proposal.file)} line ${proposal.line}: ${proposal.message}`
+      );
+
+      console.log(
+        ` Proposed change: delete this line: ${proposal.lineText}`
+      );
+    });
+
+    console.log("");
+
+    const answer = (
+      await rl.question(
+        "Enter fix numbers to apply (for example 1,3), type all, or press Enter to skip: "
+      )
+    ).trim().toLowerCase();
+
+    if (answer === "") {
+      return [];
+    }
+
+    if (answer === "all") {
+      return proposals;
+    }
+
+    const picked = new Set();
+
+    for (const part of answer.split(",")) {
+      const entry = part.trim();
+
+      if (entry === "") {
+        continue;
+      }
+
+      const number = Number(entry);
+
+      if (
+        Number.isInteger(number) &&
+        number >= 1 &&
+        number <= proposals.length
+      ) {
+        picked.add(number - 1);
+      } else {
+        console.log(`Ignored "${entry}": not a fix number`);
+      }
+    }
+
+    return [...picked]
+      .sort((a, b) => a - b)
+      .map((index) => proposals[index]);
+  } finally {
+    rl.close();
+  }
+}

package/src/backup.js

@@ -0,0 +1,73 @@
+import { mkdir, copyFile, rm } from "node:fs/promises";
+import {
+  join,
+  relative,
+  dirname,
+  isAbsolute,
+} from "node:path";
+import {
+  FIX_DIR,
+  ensureGitignoreEntry,
+} from "./gitignore.js";
+
+export async function prepareBackupDir(root) {
+  const changed = await ensureGitignoreEntry(root);
+  const dir = join(root, FIX_DIR, "backup");
+
+  await mkdir(dir, { recursive: true });
+
+  return { dir, changed };
+}
+
+function backupPathFor(root, file, attempt) {
+  const rel = relative(root, file);
+
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(
+      `Refusing to back up a file outside the project: ${file}`
+    );
+  }
+
+  return join(
+    root,
+    FIX_DIR,
+    "backup",
+    `${rel}.${attempt}.bak`
+  );
+}
+
+export async function saveBackup(root, file, attempt) {
+  const dest = backupPathFor(root, file, attempt);
+
+  await mkdir(dirname(dest), { recursive: true });
+  await copyFile(file, dest);
+
+  return dest;
+}
+
+export async function restoreBackup(file, backupPath) {
+  await copyFile(backupPath, file);
+}
+
+/**
+ * Deletes only backups explicitly recorded in the results
+ * for this run. It does not delete older backup files.
+ */
+export async function deleteRunBackups(results) {
+  const paths = [
+    ...new Set(
+      results
+        .map((result) => result.backupPath)
+        .filter((backupPath) => typeof backupPath === "string")
+    ),
+  ];
+
+  let deleted = 0;
+
+  for (const backupPath of paths) {
+    await rm(backupPath, { force: true });
+    deleted += 1;
+  }
+
+  return { deleted, paths };
+}

package/src/config.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { rules } from "../rules/index.js";
+
+const CONFIG_NAME = "vhite.config.json";
+const knownRules = new Set(rules.map((rule) => rule.name));
+
+export async function loadConfig(root) {
+  let text;
+  try {
+    text = await readFile(join(root, CONFIG_NAME), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { disabledRules: new Set(), warnings: [] };
+    throw error;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${CONFIG_NAME} is not valid JSON: ${error.message}`);
+  }
+
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error(`${CONFIG_NAME} must contain a JSON object`);
+  }
+
+  const requested = Array.isArray(data.disabledRules) ? data.disabledRules : [];
+  const disabledRules = new Set();
+  const warnings = [];
+
+  for (const name of requested) {
+    if (knownRules.has(name)) {
+      disabledRules.add(name);
+    } else {
+      warnings.push(`"${name}" is not a rule name, so it was ignored`);
+    }
+  }
+
+  return { disabledRules, warnings };
+}
+

package/src/engine.js

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { parse } from "espree";
+import { rules } from "../rules/index.js";
+
+function parseSource(source, file) {
+  const extension = extname(file).toLowerCase();
+
+  return parse(source, {
+    ecmaVersion: "latest",
+    sourceType: extension === ".cjs" ? "commonjs" : "module",
+    ecmaFeatures: {
+      jsx: true,
+    },
+    loc: true,
+    range: true,
+    comment: true,
+    tokens: true,
+    allowHashBang: true,
+  });
+}
+
+export async function runRules(files, { disabledRules = new Set() } = {}) {
+  const issues = [];
+  const activeRules = rules.filter((rule) => !disabledRules.has(rule.name));
+
+  for (const file of files) {
+    const source = await readFile(file, "utf8");
+    const extension = extname(file).toLowerCase();
+
+    const applicableRules = activeRules.filter((rule) =>
+      rule.extensions?.includes(extension)
+    );
+
+    if (applicableRules.length === 0) {
+      continue;
+    }
+
+    const needsAst = applicableRules.some(
+      (rule) => rule.requiresAst === true
+    );
+
+    let ast;
+
+    if (needsAst) {
+      try {
+        ast = parseSource(source, file);
+      } catch (error) {
+        issues.push({
+          rule: "parser",
+          file,
+          line: error.lineNumber ?? 1,
+          message: `Unable to parse file: ${error.message}`,
+        });
+      }
+    }
+
+    for (const rule of applicableRules) {
+      if (rule.requiresAst === true && !ast) {
+        continue;
+      }
+
+      const found = rule.check({
+        file,
+        source,
+        ...(rule.requiresAst === true ? { ast } : {}),
+      });
+
+      for (const issue of found) {
+        issues.push({
+          rule: rule.name,
+          file,
+          ...issue,
+        });
+      }
+    }
+  }
+
+  return issues;
+}

package/src/explanations.js

@@ -0,0 +1,35 @@
+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.",
+  },
+};
+

package/src/files.js

@@ -0,0 +1,21 @@
+import { readdir } from "node:fs/promises";
+import { join, extname } from "node:path";
+
+const IGNORED = new Set(["node_modules", ".git", "dist", "build"]);
+const EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs", ".html", ".css"]);
+
+export async function findFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (IGNORED.has(entry.name)) continue;
+      files.push(...(await findFiles(join(dir, entry.name))));
+    } else if (EXTENSIONS.has(extname(entry.name))) {
+      files.push(join(dir, entry.name));
+    }
+  }
+
+  return files;
+}

package/src/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/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/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/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/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/reporter.js

@@ -0,0 +1,33 @@
+import { relative } from "node:path";
+import { explanations } from "./explanations.js";
+
+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);
+    for (const issue of fileIssues) {
+      lines.push(`  Line ${issue.line}: ${issue.message} [${issue.rule}]`);
+      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/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 "./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();
+  }
+}