@vhite/vhite 0.1.0 → 0.6.0

package/README.md

@@ -1,32 +1,101 @@
 # @vhite/vhite
 
-vhite scans front-end code for common problems left behind by AI code generators, explains each one in plain English, and can safely fix some of them.
+vhite scans front-end code for problems commonly left behind by AI code generators. It explains each finding in plain English, and it can safely fix some of them.
 
 ## Install and run
 
-Run it on any project folder without installing it:
+Run it on any project without installing it:
 
     npx @vhite/vhite path/to/your/project
 
-Or run it on the current folder:
+Or on the current folder:
 
-    npx @vhite/vhite .
+    npx @vhite/vhite
+
+To install it once and use a short command:
+
+    npm install -g @vhite/vhite
+    vhite path/to/your/project
+
+## Commands
+
+    vhite [path]              Scan a folder (the default command)
+    vhite scan [path]         Scan and report
+    vhite fix [path]          Scan, then choose which fixes to apply
+    vhite baseline [path]     Save current problems so only new ones are reported
+    vhite rules               List all rules
+    vhite explain <rule>      Explain one rule
+    vhite version             Show the version
+
+## Options
+
+    --format text|json        Output format (default: text)
+    --quiet, -q               Print only errors; the exit code still applies
+    --fix                     Apply all safe fixes without asking, then rescan
+    --changed                 Scan only files changed since the last commit (Git)
+    --staged                  Scan only files staged for commit (Git)
+    --no-baseline             Ignore vhite.baseline.json for this run
+    --rule <name>             Run only this rule (repeatable)
+    --disable <name>          Turn off a rule (repeatable)
+    --include <path>          Scan only files under this path (repeatable)
+    --exclude <path>          Skip files under this path (repeatable)
+    --help, -h                Show help
+
+## Exit codes
+
+    0  no problems
+    1  problems found (errors or warnings; info notes do not count)
+    2  configuration or runtime error
+    3  fixes applied and no problems remain
+    4  fixes were rolled back
+
+Use these in CI. For example, a build fails when the exit code is 1 or higher.
 
 ## What it checks
 
-- **Debugger statements:** `debugger` lines that pause the app when developer tools are open.
-- **console.log calls:** logging left over from debugging.
-- **Empty catch blocks:** errors that are caught and silently ignored.
-- **Unused imports:** imports the file never uses.
-- **Empty blocks:** `if`, `else`, and loop bodies with no code.
-- **Hardcoded secrets:** passwords, API keys, and tokens written directly in the code.
-- **Comments:** every comment is flagged. TODO and FIXME notes get their own message.
+JavaScript and JSX files (`.js`, `.jsx`, `.mjs`, `.cjs`):
+
+- **debugger-statement:** `debugger` lines that pause the app when developer tools are open.
+- **console-log:** `console.log` calls left over from debugging.
+- **empty-catch:** errors that are caught and silently ignored.
+- **unused-import:** imports the file never uses.
+- **empty-block:** `if`, `else`, and loop bodies with no code.
+- **hardcoded-secret:** passwords, API keys, and tokens written directly in the code.
+- **leftover-todo:** comments. TODO and FIXME notes are reported separately from other comments.
+- **react-missing-key:** list items created with `.map()` that have no `key`.
+- **react-dangerous-html:** uses of `dangerouslySetInnerHTML`.
+- **a11y-img-alt:** images with no `alt` attribute.
+- **a11y-input-label:** form inputs with no label or accessible name.
+- **a11y-click-div:** clickable `div` or `span` elements with no `role`.
 
-Supported file types: `.js`, `.jsx`, `.mjs`, `.cjs`, `.html`, and `.css`. Some checks only apply to JavaScript files.
+HTML and CSS files (`.html`, `.css`) are checked for hardcoded secrets only.
+
+Run `vhite rules` for the full list, with each rule's default severity and whether it has an automatic fix.
+
+## Severity
+
+Each rule has a severity: `error`, `warning`, or `info`. Errors and warnings count toward the exit code. Info notes are shown but don't fail a run.
+
+Change a rule's severity in `vhite.config.json`:
+
+    {
+      "rules": {
+        "console-log": "error",
+        "leftover-todo": "off"
+      }
+    }
+
+Use `"off"` to turn a rule off. You can also turn rules off with a list:
+
+    {
+      "disabledRules": ["console-log"]
+    }
+
+Unknown rule names are reported as warnings, and the rest of the config still applies.
 
 ## Safe fixes
 
-Some problems can be fixed automatically: debugger statements, unused imports, and comments. vhite never changes a file without asking first.
+Some problems can be fixed automatically: debugger statements, unused imports, and comments. vhite never changes a file without your approval.
 
 1. It scans the project and lists the problems it found.
 2. It lists the fixes it can make and asks which ones to apply. Enter numbers such as `1,3`, type `all`, or press Enter to skip.
@@ -34,23 +103,49 @@ Some problems can be fixed automatically: debugger statements, unused imports, a
 4. After each change, it scans the file again. If the change created a new problem or didn't fix the issue, the original is restored automatically.
 5. At the end, it can ask whether to delete the backups from this run and whether to create a Markdown report in `.vhite-fix/reports/`.
 
-The first time a fix is applied, vhite adds `.vhite-fix/` to your `.gitignore`, so backups and reports stay out of your repository.
+The first time a fix is applied, vhite adds `.vhite-fix/` to your `.gitignore`.
 
-Fixes only run in an interactive terminal. In scripts or CI, vhite only reports problems.
+For scripts and CI, use `--fix` to apply all safe fixes without asking. `vhite fix` requires an interactive terminal unless `--fix` is given.
 
-## Settings
+## Baselines
 
-Create a `vhite.config.json` file in your project to turn off specific checks:
+Projects that already have problems can start with a baseline:
 
-    {
-      "disabledRules": ["console-log", "leftover-todo"]
-    }
+    vhite baseline
+
+This saves the current findings to `vhite.baseline.json`. Later scans hide those known findings and report only new ones. A finding stays hidden even if its line number moves. Commit this file so your whole team shares the same baseline, and use `--no-baseline` to see everything.
+
+## Ignoring a finding
+
+Add a comment to skip a finding you've reviewed:
+
+    // vhite-disable-next-line console-log
+    console.log("kept on purpose");
+
+    console.log("kept on purpose"); // vhite-disable-line console-log
+
+Leave out the rule name to skip every rule on that line.
+
+## Scanning only changed files
+
+    vhite --changed    # files changed since the last commit
+    vhite --staged     # files staged for commit
+
+Both need the project to be a Git repository.
+
+## Settings file
+
+Ignore patterns come from your `.gitignore`. vhite also skips `node_modules`, `dist`, `build`, and `.git` by default.
+
+## Reports
+
+    --format json      Prints results as JSON for scripts and other tools
 
-Use the rule names shown in the report, in brackets at the end of each line.
+The JSON output includes each finding's rule, severity, file, line, column, and message, plus a summary and any fixes that were applied.
 
 ## Limits
 
-vhite finds common patterns. It does not understand your whole app, so review each fix before you commit it. Removing an unused import also stops that module from loading, which is usually what you want, but check modules that only run for their side effects.
+vhite finds common patterns. It can't understand your whole app, so review each fix before you commit it. Removing an unused import also stops that module from loading, which is usually what you want, but check modules that only run for their side effects. The accessibility and React rules are heuristics and may report some false positives.
 
 ## License
 

package/bin/cli.js

@@ -1,216 +1,59 @@
 #!/usr/bin/env node
 
-import { resolve, join, relative } from "node:path";
-import { existsSync } from "node:fs";
-
-import { findFiles } from "../src/files.js";
-import { runRules } from "../src/engine.js";
-import { formatReport } from "../src/reporter.js";
-import { loadConfig } from "../src/config.js";
-
-import {
-  CONFIG_NAME,
-  canAskQuestions,
-  runFirstTimeSetup,
-} from "../src/setup.js";
-
-import {
-  proposeFixes,
-  applyApprovedFixes,
-} from "../src/safe-fix.js";
-
-import { chooseProposals } from "../src/approve.js";
-import { deleteRunBackups } from "../src/backup.js";
-import { FIX_DIR } from "../src/gitignore.js";
-
-import {
-  askYesNo,
-  writeRunReport,
-} from "../src/run-report.js";
-
-// Capture terminal messages so the report can include them.
-const logs = [];
-
-const originalLog = console.log;
-const originalWarn = console.warn;
-const originalError = console.error;
-
-function capture(method, label = "") {
-  return (...args) => {
-    const message = args
-      .map((arg) => {
-        if (typeof arg === "string") {
-          return arg;
-        }
-
-        try {
-          return JSON.stringify(arg) ?? String(arg);
-        } catch {
-          return String(arg);
-        }
-      })
-      .join(" ");
-
-    logs.push(label ? `${label}: ${message}` : message);
-    method(...args);
-  };
-}
-
-console.log = capture(originalLog);
-console.warn = capture(originalWarn, "WARN");
-console.error = capture(originalError, "ERROR");
-
-const startedAt = new Date();
-const target = resolve(process.argv[2] ?? ".");
-
-let files = [];
-let issues = [];
-let proposals = [];
-let fixResults = [];
-let backupCleanup = null;
-let config = null;
-
-console.log(
-  `vhite is installed and running
-   loading..
-             ....  
-                  ...... 
-                         ........
-   Done..`
-);
-
-try {
-  if (
-    !existsSync(join(target, CONFIG_NAME)) &&
-    canAskQuestions()
-  ) {
-    await runFirstTimeSetup(target);
+import { parseArgs, UsageError } from "../src/core/args.js";
+import { EXIT } from "../src/core/exit-codes.js";
+import { readVersion } from "../src/core/version.js";
+import { USAGE } from "./output/text.js";
+import { listRules, explainRule } from "./commands/info.js";
+import { runBaseline } from "./commands/baseline.js";
+import { runScan } from "./commands/scan.js";
+import { runHook } from "./commands/hook.js";
+import { runWatch } from "./commands/watch.js";
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    if (error instanceof UsageError) {
+      console.error(`Error: ${error.message}\n`);
+      console.error(USAGE);
+      return EXIT.ERROR;
+    }
+    throw error;
   }
 
-  config = await loadConfig(target);
-
-  for (const warning of config.warnings) {
-    console.log(`Warning: ${warning}`);
+  if (options.command === "help") {
+    console.log(USAGE);
+    return EXIT.CLEAN;
   }
 
-  if (config.disabledRules.size > 0) {
-    console.log(
-           `Rules turned off by ${CONFIG_NAME}: ${[...config.disabledRules].join(", ")}`
-    );
+  if (options.command === "version") {
+    console.log(await readVersion());
+    return EXIT.CLEAN;
   }
 
-  files = await findFiles(target);
-
-  console.log(
-    `vhite found ${files.length} front-end files in ${relative(process.cwd(), target) || "."}\n`
-  );
-
-  issues = await runRules(files, {
-    disabledRules: config.disabledRules,
-  });
-
-  console.log(formatReport(issues, target));
-  proposals = await proposeFixes(issues);
-
-  if (proposals.length > 0 && canAskQuestions()) {
-    const chosen = await chooseProposals(target, proposals);
-
-    if (chosen.length > 0) {
-      const result = await applyApprovedFixes(
-        target,
-        chosen,
-        { disabledRules: config.disabledRules }
-      );
-
-      fixResults = result.results;
-
-      if (result.gitignoreUpdated) {
-        console.log(`Added ${FIX_DIR}/ to .gitignore`);
-      }
-
-      for (const item of fixResults) {
-        if (item.status === "applied") {
-          console.log(
-            `Applied: ${relative(target, item.proposal.file)} line ${item.proposal.line}`
-          );
-        } else {
-          const label = item.status === "skipped" ? "Skipped" : "Rolled back";
-          console.log(
-            `${label}: ${relative(target, item.proposal.file)} line ${item.proposal.line}. ${item.reason}`
-          );
-        }
-      }
-    }
+  if (options.command === "rules") {
+    return listRules();
   }
 
-  // Feature 1: Ask whether to remove current-run backups.
-  const hasRunBackups = fixResults.some(
-    (item) => typeof item.backupPath === "string"
-  );
-
-  if (canAskQuestions() && hasRunBackups) {
-    const shouldDelete = await askYesNo(
-      "Do you want to delete the backup files created during this run?"
-    );
-
-    if (shouldDelete) {
-      const result = await deleteRunBackups(fixResults);
-      backupCleanup = {
-        requested: true,
-        deleted: result.deleted,
-      };
-
-      console.log(
-        `Deleted ${result.deleted} backup file(s) created during this run.`
-      );
-    } else {
-      backupCleanup = {
-        requested: false,
-        deleted: 0,
-      };
-
-      console.log("Kept the backup files created during this run.");
-    }
+  if (options.command === "explain") {
+    return explainRule(options.ruleName);
   }
 
-  console.log("\nVhite run completed.");
-
-  // Feature 2: Offer a detailed Markdown report.
-  if (canAskQuestions()) {
-    const shouldCreateReport = await askYesNo(
-      "Would you like to create a detailed Markdown report of this run?"
-    );
-
-    if (shouldCreateReport) {
-      // Include the log messages generated before report creation.
-      const reportLogs = [...logs];
-      const finishedAt = new Date();
-
-      const result = await writeRunReport({
-        root: target,
-        target,
-        startedAt,
-        finishedAt,
-        filesScanned: files.length,
-        issues,
-        proposals,
-        fixResults,
-        logs: reportLogs,
-        backupCleanup,
-      });
+  if (options.command === "baseline") {
+    return runBaseline(options);
+  }
 
-      if (result.gitignoreUpdated) {
-        console.log(`Added ${FIX_DIR}/ to .gitignore`);
-      }
+  if (options.command === "hook") {
+    return runHook(options);
+  }
 
-      console.log(
-        `Report created successfully: ${relative(target, result.reportPath)}`
-      );
-    } else {
-      console.log("Report generation skipped.");
-    }
+  if (options.watch) {
+    return runWatch(options);
   }
-} catch (error) {
-  console.error(`Error: ${error.message}`);
-  process.exitCode = 1;
+
+  return runScan(options);
 }
+
+process.exitCode = await main();

package/bin/commands/baseline.js

@@ -0,0 +1,27 @@
+import { resolve, relative } from "node:path";
+import { loadConfig } from "../../src/core/config.js";
+import { EXIT } from "../../src/core/exit-codes.js";
+import { BASELINE_NAME, buildBaseline, saveBaseline } from "../../src/scan/baseline.js";
+import { selectFiles, collectIssues, disabledSetFor } from "./shared.js";
+
+export async function runBaseline(options) {
+  const target = resolve(options.path ?? ".");
+
+  try {
+    const config = await loadConfig(target);
+    const disabled = disabledSetFor(config, options);
+    const files = await selectFiles(target, options);
+    const { issues } = await collectIssues(files, target, disabled, config, null);
+
+    const baseline = buildBaseline(issues, target);
+    const path = await saveBaseline(target, baseline);
+    const count = issues.length;
+
+    console.log(`Saved ${count} current issue(s) to ${relative(process.cwd(), path) || BASELINE_NAME}`);
+    console.log("Only new issues will be reported from now on.");
+    return EXIT.CLEAN;
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    return EXIT.ERROR;
+  }
+}

package/bin/commands/hook.js

@@ -0,0 +1,58 @@
+import { readFile, writeFile, rm, mkdir, chmod, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { EXIT } from "../../src/core/exit-codes.js";
+
+const MARKER = "# vhite-pre-commit-hook";
+const HOOK_SCRIPT = `#!/bin/sh
+${MARKER}
+# Scans staged files before each commit. Remove with: vhite hook remove
+npx --yes @vhite/vhite --staged --no-prompt
+`;
+
+async function gitDirFor(root) {
+  try {
+    const info = await stat(join(root, ".git"));
+    return info.isDirectory() ? join(root, ".git") : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function runHook(options) {
+  const root = resolve(options.path ?? ".");
+  const gitDir = await gitDirFor(root);
+
+  if (!gitDir) {
+    console.error("Error: this folder is not a Git repository (no .git folder found)");
+    return EXIT.ERROR;
+  }
+
+  const hookPath = join(gitDir, "hooks", "pre-commit");
+  const existing = await readFile(hookPath, "utf8").catch(() => null);
+  const isOurs = existing !== null && existing.includes(MARKER);
+
+  if (options.hookAction === "install") {
+    if (existing !== null && !isOurs && !options.force) {
+      console.error("Error: a pre-commit hook already exists. Use --force to replace it.");
+      return EXIT.ERROR;
+    }
+    await mkdir(join(gitDir, "hooks"), { recursive: true });
+    await writeFile(hookPath, HOOK_SCRIPT, "utf8");
+    await chmod(hookPath, 0o755).catch(() => {});
+    console.log(`Installed pre-commit hook at ${hookPath}`);
+    return EXIT.CLEAN;
+  }
+
+  if (existing === null) {
+    console.log("No pre-commit hook to remove.");
+    return EXIT.CLEAN;
+  }
+  if (!isOurs) {
+    console.error("Error: the existing pre-commit hook was not installed by vhite, so it was left alone.");
+    return EXIT.ERROR;
+  }
+
+  await rm(hookPath);
+  console.log("Removed the vhite pre-commit hook.");
+  return EXIT.CLEAN;
+}

package/bin/commands/info.js

@@ -0,0 +1,39 @@
+import { severityOf } from "../../src/core/config.js";
+import { EXIT } from "../../src/core/exit-codes.js";
+import { fixers } from "../../src/fix/fixers/index.js";
+import { explanations } from "../../src/output/explanations.js";
+import { rules } from "../../rules/index.js";
+import { KNOWN_RULES } from "./shared.js";
+
+export function listRules() {
+  console.log("Rule                  Severity  Fix   Description");
+  for (const rule of rules) {
+    const severity = severityOf(rule.name, { severities: new Map() });
+    const fixable = fixers[rule.name] ? "yes" : "no";
+    console.log(
+      `${rule.name.padEnd(22)}${severity.padEnd(10)}${fixable.padEnd(6)}${rule.description}`
+    );
+  }
+  return EXIT.CLEAN;
+}
+
+export function explainRule(name) {
+  if (!KNOWN_RULES.has(name)) {
+    console.error(`Error: unknown rule "${name}"`);
+    console.error(`Known rules: ${[...KNOWN_RULES].join(", ")}`);
+    return EXIT.ERROR;
+  }
+
+  const rule = rules.find((item) => item.name === name);
+  const info = explanations[name];
+
+  console.log(name);
+  console.log(`  ${rule.description}`);
+  if (info) {
+    console.log(`  What happened: ${info.whatHappened}`);
+    console.log(`  Proposed change: ${info.proposedChange}`);
+  }
+  console.log(`  Default severity: ${severityOf(name, { severities: new Map() })}`);
+  console.log(`  Automatic fix: ${fixers[name] ? "yes" : "no"}`);
+  return EXIT.CLEAN;
+}