@vhite/vhite 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @vhite/vhite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 without installing it:
+
+    npx @vhite/vhite path/to/your/project
+
+Or on the current folder:
+
+    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
+
+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`.
+
+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 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.
+3. Before each change, it saves a backup in `.vhite-fix/backup/`.
+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`.
+
+For scripts and CI, use `--fix` to apply all safe fixes without asking. `vhite fix` requires an interactive terminal unless `--fix` is given.
+
+## Baselines
+
+Projects that already have problems can start with a baseline:
+
+    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
+
+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 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
+
+ISC

package/bin/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+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;
+  }
+
+  if (options.command === "help") {
+    console.log(USAGE);
+    return EXIT.CLEAN;
+  }
+
+  if (options.command === "version") {
+    console.log(await readVersion());
+    return EXIT.CLEAN;
+  }
+
+  if (options.command === "rules") {
+    return listRules();
+  }
+
+  if (options.command === "explain") {
+    return explainRule(options.ruleName);
+  }
+
+  if (options.command === "baseline") {
+    return runBaseline(options);
+  }
+
+  if (options.command === "hook") {
+    return runHook(options);
+  }
+
+  if (options.watch) {
+    return runWatch(options);
+  }
+
+  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;
+}

package/bin/commands/scan.js

@@ -0,0 +1,206 @@
+import { resolve, join, relative } from "node:path";
+import { existsSync } from "node:fs";
+import { loadConfig } from "../../src/core/config.js";
+import { CONFIG_NAME, canAskQuestions, runFirstTimeSetup } from "../../src/core/setup.js";
+import { proposeFixes, applyApprovedFixes } from "../../src/fix/safe-fix.js";
+import { chooseProposals } from "../../src/fix/approve.js";
+import { deleteRunBackups } from "../../src/fix/backup.js";
+import { FIX_DIR } from "../../src/fix/gitignore.js";
+import { askYesNo, writeRunReport } from "../../src/output/run-report.js";
+import { EXIT, decideExitCode } from "../../src/core/exit-codes.js";
+import { formatJson } from "../../src/output/json-output.js";
+import { formatSarif } from "../../src/output/sarif.js";
+import { formatReport } from "../../src/output/reporter.js";
+import { BASELINE_NAME, loadBaseline } from "../../src/scan/baseline.js";
+import { readVersion } from "../../src/core/version.js";
+import { BANNER } from "../output/text.js";
+import {
+  KNOWN_RULES,
+  selectFiles,
+  collectIssues,
+  disabledSetFor,
+  summaryLine,
+} from "./shared.js";
+
+export async function runScan(options) {
+  const target = resolve(options.path ?? ".");
+  const isText = options.format === "text";
+  const showText = isText && !options.quiet;
+  const interactive = canAskQuestions() && showText && !options.watching && !options.noPrompt;
+  const logs = [];
+  const startedAt = new Date();
+
+  const say = (message = "") => {
+    logs.push(message);
+    if (showText) console.log(message);
+  };
+
+  const unknown = [...options.rules, ...options.disable].filter(
+    (name) => !KNOWN_RULES.has(name)
+  );
+  if (unknown.length > 0) {
+    console.error(`Error: unknown rule name(s): ${unknown.join(", ")}`);
+    return EXIT.ERROR;
+  }
+
+  let issues = [];
+  let files = [];
+  let fixResults = [];
+  let backupCleanup = null;
+
+  try {
+    if (showText && !options.quiet) {
+      console.log(BANNER);
+    }
+
+    if (!existsSync(join(target, CONFIG_NAME)) && interactive) {
+      await runFirstTimeSetup(target);
+    }
+
+    const config = await loadConfig(target);
+
+    for (const warning of config.warnings) {
+      say(`Warning: ${warning}`);
+    }
+
+    const disabled = disabledSetFor(config, options);
+    if (disabled.size > 0 && showText) {
+      say(`Rules turned off: ${[...disabled].join(", ")}`);
+    }
+
+    const baseline = options.useBaseline ? await loadBaseline(target) : null;
+
+    files = await selectFiles(target, options);
+
+    say(
+      `vhite found ${files.length} front-end files in ${relative(process.cwd(), target) || "."}\n`
+    );
+
+    const first = await collectIssues(files, target, disabled, config, baseline);
+    issues = first.issues;
+
+    say(formatReport(issues, target));
+    if (issues.length > 0) say(summaryLine(issues));
+    if (first.hidden > 0) {
+      say(`${first.hidden} known issue(s) hidden by ${BASELINE_NAME}`);
+    }
+    if (first.suppressed > 0) {
+      say(`${first.suppressed} issue(s) skipped by vhite-disable comments`);
+    }
+
+    const proposals = await proposeFixes(issues);
+    let chosen = [];
+
+    if (proposals.length > 0) {
+      if (options.fix) {
+        chosen = proposals;
+      } else if (interactive) {
+        chosen = await chooseProposals(target, proposals);
+      } else if (options.command === "fix") {
+        console.error(
+          "Error: vhite fix needs an interactive terminal. Use --fix to apply all safe fixes."
+        );
+        return EXIT.ERROR;
+      }
+    }
+
+    if (chosen.length > 0) {
+      const result = await applyApprovedFixes(target, chosen, { disabledRules: disabled });
+      fixResults = result.results;
+
+      if (result.gitignoreUpdated) {
+        say(`Added ${FIX_DIR}/ to .gitignore`);
+      }
+
+      for (const item of fixResults) {
+        const where = `${relative(target, item.proposal.file)} line ${item.proposal.line}`;
+        if (item.status === "applied") {
+          say(`Applied: ${where}`);
+        } else {
+          const label = item.status === "skipped" ? "Skipped" : "Rolled back";
+          say(`${label}: ${where}. ${item.reason}`);
+        }
+      }
+
+      const rescan = await collectIssues(files, target, disabled, config, baseline);
+      issues = rescan.issues;
+      say(`Final scan: ${issues.length} issue(s) remaining`);
+    }
+
+    const hasRunBackups = fixResults.some((item) => typeof item.backupPath === "string");
+
+    if (interactive && 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 };
+        say(`Deleted ${result.deleted} backup file(s) created during this run.`);
+      } else {
+        backupCleanup = { requested: false, deleted: 0 };
+        say("Kept the backup files created during this run.");
+      }
+    }
+
+    if (showText) say("\nVhite run completed.");
+
+    if (interactive) {
+      const shouldCreateReport = await askYesNo(
+        "Would you like to create a detailed Markdown report of this run?"
+      );
+
+      if (shouldCreateReport) {
+        const result = await writeRunReport({
+          root: target,
+          target,
+          startedAt,
+          finishedAt: new Date(),
+          filesScanned: files.length,
+          issues,
+          proposals: await proposeFixes(issues),
+          fixResults,
+          logs: [...logs],
+          backupCleanup,
+        });
+
+        if (result.gitignoreUpdated) {
+          say(`Added ${FIX_DIR}/ to .gitignore`);
+        }
+        say(`Report created successfully: ${relative(target, result.reportPath)}`);
+      } else {
+        say("Report generation skipped.");
+      }
+    }
+
+    if (options.format === "sarif") {
+      console.log(formatSarif({ root: target, issues, version: await readVersion() }));
+    }
+
+    if (options.format === "json") {
+      console.log(
+        formatJson({
+          root: target,
+          filesScanned: files.length,
+          issues,
+          fixes: fixResults,
+          version: await readVersion(),
+        })
+      );
+    }
+
+    const failing = issues.filter(
+      (issue) => issue.severity === "error" || issue.severity === "warning"
+    ).length;
+
+    return decideExitCode({
+      rolledBack: fixResults.filter((item) => item.status === "rolled back").length,
+      issues: failing,
+      applied: fixResults.filter((item) => item.status === "applied").length,
+    });
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    return EXIT.ERROR;
+  }
+}

package/bin/commands/shared.js

@@ -0,0 +1,67 @@
+import { resolve, relative } from "node:path";
+import { findFiles } from "../../src/core/files.js";
+import { runRules } from "../../src/core/engine.js";
+import { applySeverity } from "../../src/core/config.js";
+import { isIncluded } from "../../src/core/args.js";
+import { loadIgnorePatterns, isIgnored } from "../../src/scan/ignore.js";
+import { changedFiles } from "../../src/scan/git.js";
+import { applySuppressions } from "../../src/scan/suppress.js";
+import { applyBaseline } from "../../src/scan/baseline.js";
+import { rules } from "../../rules/index.js";
+
+export const KNOWN_RULES = new Set(rules.map((rule) => rule.name));
+
+export function summaryLine(issues) {
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const issue of issues) {
+    counts[issue.severity] = (counts[issue.severity] ?? 0) + 1;
+  }
+  return `Errors: ${counts.error}  Warnings: ${counts.warning}  Info: ${counts.info}`;
+}
+
+export async function selectFiles(target, options) {
+  const patterns = await loadIgnorePatterns(target);
+  const allFiles = await findFiles(target);
+
+  let files = allFiles.filter((file) => {
+    const rel = relative(target, file);
+    return !isIgnored(rel, patterns) && isIncluded(rel, options.include, options.exclude);
+  });
+
+  if (options.changed || options.staged) {
+    const changed = await changedFiles(target, options.staged ? "staged" : "changed");
+    files = files.filter((file) => changed.has(resolve(file)));
+  }
+
+  return files;
+}
+
+export async function collectIssues(files, target, disabled, config, baseline) {
+  const found = applySeverity(
+    await runRules(files, { disabledRules: disabled }),
+    config
+  );
+
+  const suppressed = await applySuppressions(found, target);
+  let issues = suppressed.issues;
+  let hidden = 0;
+
+  if (baseline) {
+    const applied = applyBaseline(issues, baseline, target);
+    issues = applied.issues;
+    hidden = applied.hidden;
+  }
+
+  return { issues, suppressed: suppressed.suppressed, hidden };
+}
+
+export function disabledSetFor(config, options) {
+  const disabled = new Set([...config.disabledRules, ...options.disable]);
+  if (options.rules.length > 0) {
+    const only = new Set(options.rules);
+    for (const rule of rules) {
+      if (!only.has(rule.name)) disabled.add(rule.name);
+    }
+  }
+  return disabled;
+}

package/bin/commands/watch.js

@@ -0,0 +1,44 @@
+import { watch } from "node:fs";
+import { resolve } from "node:path";
+import { runScan } from "./scan.js";
+
+const IGNORED_SEGMENTS = new Set(["node_modules", ".git", ".vhite-fix", "dist", "build", "coverage"]);
+const DEBOUNCE_MS = 300;
+
+function isIgnoredPath(filename) {
+  return filename.split(/[\\/]/).some((part) => IGNORED_SEGMENTS.has(part));
+}
+
+export async function runWatch(options) {
+  const target = resolve(options.path ?? ".");
+  const scanOptions = { ...options, watching: true };
+  let timer = null;
+  let running = false;
+  let pending = false;
+
+  const scanNow = async () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    running = true;
+    do {
+      pending = false;
+      console.log(`\n[${new Date().toLocaleTimeString()}] Scanning...`);
+      await runScan(scanOptions);
+    } while (pending);
+    running = false;
+  };
+
+  watch(target, { recursive: true }, (_event, filename) => {
+    if (!filename || isIgnoredPath(filename.toString())) return;
+    clearTimeout(timer);
+    timer = setTimeout(scanNow, DEBOUNCE_MS);
+  });
+
+  await scanNow();
+  console.log("\nWatching for changes. Press Ctrl+C to stop.");
+
+  await new Promise(() => {});
+  return 0;
+}