@vhite/vhite 0.1.0 → 0.6.0

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;
+}

package/bin/output/text.js

@@ -0,0 +1,40 @@
+export const USAGE = `Usage:
+  vhite [path]              Scan a folder (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 this 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
+
+Ignoring code:
+  Put  // vhite-disable-next-line rule-name  above a line, or
+       // vhite-disable-line rule-name  at the end of a line,
+  to skip that finding. Leave out the rule name to skip every rule.`;
+
+export const BANNER = `vhite is installed and running
+   loading..
+             ....
+                  ......
+                         ........
+   Done..`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vhite/vhite",
-  "version": "0.1.0",
+  "version": "0.6.0",
   "description": "An AI code cleaner for front-end projects that finds and safely fixes common AI-generated problems",
   "license": "ISC",
   "author": "Victor Edem",
@@ -21,12 +21,39 @@
   "engines": {
     "node": ">=18"
   },
-  "keywords": [
+    "keywords": [
     "ai",
+    "ai-code",
+    "ai-generated-code",
+    "ai-code-cleanup",
+    "ai-code-review",
     "code-cleanup",
+    "code-quality",
+    "code-review",
     "linter",
+    "lint",
+    "static-analysis",
+    "code-analysis",
     "front-end",
-    "javascript"
+    "frontend",
+    "javascript",
+    "jsx",
+    "react",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "security",
+    "hardcoded-secrets",
+    "console-log",
+    "debugger",
+    "unused-imports",
+    "dead-code",
+    "cli",
+    "command-line",
+    "ci",
+    "github-actions",
+    "pre-commit",
+    "vibe-coding"
   ],
   "repository": {
     "type": "git",
@@ -37,10 +64,10 @@
   },
   "homepage": "https://github.com/Wilson-Edem/vhite#readme",
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*/*.test.js"
   },
   "dependencies": {
     "espree": "^10.0.1",
     "eslint-scope": "^8.4.0"
   }
-}
+}

package/rules/a11y/a11y-click-div.js

@@ -0,0 +1,39 @@
+import { childNodes, attributeNamed, hasSpread } from "../shared/jsx-helpers.js";
+
+const CLICKABLE_TAGS = new Set(["div", "span"]);
+
+const a11yClickDiv = {
+  name: "a11y-click-div",
+  description: "Flags clickable div or span elements that have no role",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      if (
+        node.type === "JSXOpeningElement" &&
+        node.name?.type === "JSXIdentifier" &&
+        CLICKABLE_TAGS.has(node.name.name) &&
+        attributeNamed(node, "onClick") &&
+        !attributeNamed(node, "role") &&
+        !hasSpread(node)
+      ) {
+        issues.push({
+          start: node.range?.[0],
+          end: node.range?.[1],
+          message: `Clickable <${node.name.name}> is not reachable by keyboard or announced to screen readers; use a button, or add role and keyboard handling`,
+        });
+      }
+
+      for (const child of childNodes(node)) visit(child);
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default a11yClickDiv;

package/rules/a11y/a11y-img-alt.js

@@ -0,0 +1,36 @@
+import { childNodes, attributeNamed, hasSpread } from "../shared/jsx-helpers.js";
+
+const a11yImgAlt = {
+  name: "a11y-img-alt",
+  description: "Flags images that have no alt attribute",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      if (
+        node.type === "JSXOpeningElement" &&
+        node.name?.type === "JSXIdentifier" &&
+        node.name.name === "img" &&
+        !hasSpread(node) &&
+        !attributeNamed(node, "alt")
+      ) {
+        issues.push({
+          start: node.range?.[0],
+          end: node.range?.[1],
+          message: "Image has no alt attribute; add a description, or alt=\"\" if it is decorative",
+        });
+      }
+
+      for (const child of childNodes(node)) visit(child);
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default a11yImgAlt;

package/rules/a11y/a11y-input-label.js

@@ -0,0 +1,40 @@
+import { childNodes, attributeNamed, hasSpread, literalValue } from "../shared/jsx-helpers.js";
+
+const NO_LABEL_TYPES = new Set(["hidden", "submit", "button", "reset", "image"]);
+const LABEL_ATTRIBUTES = ["aria-label", "aria-labelledby", "id", "title"];
+
+const a11yInputLabel = {
+  name: "a11y-input-label",
+  description: "Flags form inputs with no label or accessible name attribute",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      if (
+        node.type === "JSXOpeningElement" &&
+        node.name?.type === "JSXIdentifier" &&
+        node.name.name === "input" &&
+        !hasSpread(node) &&
+        !NO_LABEL_TYPES.has(literalValue(attributeNamed(node, "type"))) &&
+        !LABEL_ATTRIBUTES.some((name) => attributeNamed(node, name))
+      ) {
+        issues.push({
+          start: node.range?.[0],
+          end: node.range?.[1],
+          message: "Form input has no label; connect it to a label element, or add aria-label",
+        });
+      }
+
+      for (const child of childNodes(node)) visit(child);
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default a11yInputLabel;

package/rules/{console-log.js → core/console-log.js}

@@ -19,7 +19,8 @@ const consoleLog = {
         node.callee.property.name === "log"
       ) {
         issues.push({
-          line: node.loc?.start.line ?? 1,
+                    start: node.range?.[0],
+          end: node.range?.[1],
           message: "Review or remove this console.log call",
         });
       }

package/rules/{debugger-statement.js → core/debugger-statement.js}

@@ -11,7 +11,8 @@ const debuggerStatement = {
 
       if (node.type === "DebuggerStatement") {
         issues.push({
-          line: node.loc?.start.line ?? 1,
+                    start: node.range?.[0],
+          end: node.range?.[1],
           message: "Remove the debugger statement before shipping",
         });
       }

package/rules/{empty-block.js → core/empty-block.js}

@@ -16,7 +16,8 @@ const emptyBlock = {
         key !== "body"
       ) {
         issues.push({
-          line: node.loc?.start.line ?? 1,
+                    start: node.range?.[0],
+          end: node.range?.[1],
           message: "Review this empty block; it may indicate missing logic",
         });
       }

package/rules/{empty-catch.js → core/empty-catch.js}

@@ -15,7 +15,8 @@ const emptyCatch = {
         node.body.body.length === 0
       ) {
         issues.push({
-          line: node.loc?.start.line ?? 1,
+                    start: node.range?.[0],
+          end: node.range?.[1],
           message: "Handle, log, or explicitly document this caught error",
         });
       }

package/rules/{hardcoded-secret.js → core/hardcoded-secret.js}

@@ -17,20 +17,25 @@ const hardcodedSecret = {
     const issues = [];
     const lines = source.split("\n");
 
-    lines.forEach((text, index) => {
+    let lineStart = 0;
+    lines.forEach((text) => {
       for (const item of SECRET_PATTERNS) {
-        if (item.pattern.test(text)) {
+        const match = item.pattern.exec(text);
+        if (match) {
+          const start = lineStart + match.index;
           issues.push({
-            line: index + 1,
+            start,
+            end: start + match[0].length,
             message: `Possible hardcoded secret (${item.label}); move it to a secure environment variable and rotate it if real`,
           });
           break;
         }
       }
+      lineStart += text.length + 1;
     });
 
     return issues;
   },
 };
 
-export default hardcodedSecret;
+export default hardcodedSecret;

package/rules/{leftover-todo.js → core/leftover-todo.js}

@@ -5,12 +5,16 @@ const leftoverTodo = {
   description: "Flags comments left in code, with TODO and FIXME notes called out separately",
   extensions: [".js", ".jsx", ".mjs", ".cjs"],
   requiresAst: true,
-  check({ ast }) {
+  check({ ast, source }) {
     const issues = [];
     for (const comment of ast.comments ?? []) {
+      if (comment.range?.[0] === 0 && source?.startsWith("#!")) continue;
+      if (comment.value.includes("vhite-disable")) continue;
+
       const isTodo = todoPattern.test(comment.value);
       issues.push({
-        line: comment.loc.start.line,
+        start: comment.range?.[0],
+        end: comment.range?.[1],
         message: isTodo ? "Leftover TODO or FIXME note" : "Code comment left in the file",
         comment: {
           type: comment.type,

package/rules/{unused-import.js → core/unused-import.js}

@@ -52,8 +52,10 @@ const unusedImport = {
 
         if (!hasRead && !usedInJsx && !implicitReact) {
           const definition = variable.defs.find((item) => item.type === "ImportBinding");
+                   const target = definition?.name ?? variable.identifiers[0];
           issues.push({
-            line: definition?.name?.loc?.start.line ?? variable.identifiers[0]?.loc?.start.line ?? 1,
+            start: target?.range?.[0],
+            end: target?.range?.[1],
             message: `Imported binding "${variable.name}" is never used`,
           });
         }

package/rules/index.js

@@ -1,10 +1,15 @@
-import leftoverTodo from "./leftover-todo.js";
-import debuggerStatement from "./debugger-statement.js";
-import consoleLog from "./console-log.js";
-import emptyCatch from "./empty-catch.js";
-import unusedImport from "./unused-import.js";
-import emptyBlock from "./empty-block.js";
-import hardcodedSecret from "./hardcoded-secret.js";
+import leftoverTodo from "./core/leftover-todo.js";
+import debuggerStatement from "./core/debugger-statement.js";
+import consoleLog from "./core/console-log.js";
+import emptyCatch from "./core/empty-catch.js";
+import unusedImport from "./core/unused-import.js";
+import emptyBlock from "./core/empty-block.js";
+import hardcodedSecret from "./core/hardcoded-secret.js";
+import reactMissingKey from "./react/react-missing-key.js";
+import reactDangerousHtml from "./react/react-dangerous-html.js";
+import a11yImgAlt from "./a11y/a11y-img-alt.js";
+import a11yInputLabel from "./a11y/a11y-input-label.js";
+import a11yClickDiv from "./a11y/a11y-click-div.js";
 
 export const rules = [
   leftoverTodo,
@@ -14,4 +19,9 @@ export const rules = [
   unusedImport,
   emptyBlock,
   hardcodedSecret,
-];
+  reactMissingKey,
+  reactDangerousHtml,
+  a11yImgAlt,
+  a11yInputLabel,
+  a11yClickDiv,
+];