@vhite/vhite 0.0.0-stage → 0.6.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,73 @@
 {
   "name": "@vhite/vhite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "type": "module",
+  "main": "bin/cli.js",
+  "bin": {
+    "vhite": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "rules",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+    "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",
+    "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",
+    "url": "https://github.com/Wilson-Edem/vhite"
+  },
+  "bugs": {
+    "url": "https://github.com/Wilson-Edem/vhite/issues"
+  },
+  "homepage": "https://github.com/Wilson-Edem/vhite#readme",
+  "scripts": {
+    "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/core/console-log.js

@@ -0,0 +1,44 @@
+const consoleLog = {
+  name: "console-log",
+  description: "Flags console.log calls that may have been left during debugging",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      if (
+        node.type === "CallExpression" &&
+        node.callee?.type === "MemberExpression" &&
+        !node.callee.computed &&
+        node.callee.object?.type === "Identifier" &&
+        node.callee.object.name === "console" &&
+        node.callee.property?.type === "Identifier" &&
+        node.callee.property.name === "log"
+      ) {
+        issues.push({
+                    start: node.range?.[0],
+          end: node.range?.[1],
+          message: "Review or remove this console.log call",
+        });
+      }
+
+      for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            if (child && typeof child.type === "string") visit(child);
+          }
+        } else if (value && typeof value.type === "string") {
+          visit(value);
+        }
+      }
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default consoleLog;

package/rules/core/debugger-statement.js

@@ -0,0 +1,36 @@
+const debuggerStatement = {
+  name: "debugger-statement",
+  description: "Flags debugger statements left in source code",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      if (node.type === "DebuggerStatement") {
+        issues.push({
+                    start: node.range?.[0],
+          end: node.range?.[1],
+          message: "Remove the debugger statement before shipping",
+        });
+      }
+
+      for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            if (child && typeof child.type === "string") visit(child);
+          }
+        } else if (value && typeof value.type === "string") {
+          visit(value);
+        }
+      }
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default debuggerStatement;

package/rules/core/empty-block.js

@@ -0,0 +1,41 @@
+const emptyBlock = {
+  name: "empty-block",
+  description: "Flags empty control-flow blocks that may hide unfinished logic",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node, parent = null, key = null) {
+      if (!node || typeof node !== "object") return;
+
+      if (
+        node.type === "BlockStatement" &&
+        node.body.length === 0 &&
+        parent?.type !== "CatchClause" &&
+        key !== "body"
+      ) {
+        issues.push({
+                    start: node.range?.[0],
+          end: node.range?.[1],
+          message: "Review this empty block; it may indicate missing logic",
+        });
+      }
+
+      for (const [childKey, value] of Object.entries(node)) {
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            if (child && typeof child.type === "string") visit(child, node, childKey);
+          }
+        } else if (value && typeof value.type === "string") {
+          visit(value, node, childKey);
+        }
+      }
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default emptyBlock;

package/rules/core/empty-catch.js

@@ -0,0 +1,40 @@
+const emptyCatch = {
+  name: "empty-catch",
+  description: "Flags catch clauses that silently ignore errors",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      if (
+        node.type === "CatchClause" &&
+        node.body?.type === "BlockStatement" &&
+        node.body.body.length === 0
+      ) {
+        issues.push({
+                    start: node.range?.[0],
+          end: node.range?.[1],
+          message: "Handle, log, or explicitly document this caught error",
+        });
+      }
+
+      for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            if (child && typeof child.type === "string") visit(child);
+          }
+        } else if (value && typeof value.type === "string") {
+          visit(value);
+        }
+      }
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default emptyCatch;

package/rules/core/hardcoded-secret.js

@@ -0,0 +1,41 @@
+const SECRET_PATTERNS = [
+  {
+    pattern: /\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|secret[_-]?key|password)\b\s*[:=]\s*["'`][^"'`\s]{8,}["'`]/i,
+    label: "credential-like value",
+  },
+  {
+    pattern: /\b(?:sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16})\b/,
+    label: "token-like value",
+  },
+];
+
+const hardcodedSecret = {
+  name: "hardcoded-secret",
+  description: "Heuristically flags possible hardcoded credentials or API tokens",
+  extensions: [".js", ".jsx", ".mjs", ".cjs", ".html", ".css"],
+  check({ source }) {
+    const issues = [];
+    const lines = source.split("\n");
+
+    let lineStart = 0;
+    lines.forEach((text) => {
+      for (const item of SECRET_PATTERNS) {
+        const match = item.pattern.exec(text);
+        if (match) {
+          const start = lineStart + match.index;
+          issues.push({
+            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;

package/rules/core/leftover-todo.js

@@ -0,0 +1,30 @@
+const todoPattern = /\b(TODO|FIXME)\b/;
+
+const leftoverTodo = {
+  name: "leftover-todo",
+  description: "Flags comments left in code, with TODO and FIXME notes called out separately",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  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({
+        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,
+          value: comment.value,
+          range: comment.range,
+        },
+      });
+    }
+    return issues;
+  },
+};
+
+export default leftoverTodo;

package/rules/core/unused-import.js

@@ -0,0 +1,69 @@
+import { analyze } from "eslint-scope";
+
+const unusedImport = {
+  name: "unused-import",
+  description: "Flags imported bindings that are never read",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+    const jsxNames = new Set();
+    let hasJsx = false;
+
+    function collectJsx(node) {
+      if (!node || typeof node !== "object") return;
+      if (node.type === "JSXIdentifier") jsxNames.add(node.name);
+      if (node.type === "JSXOpeningElement" || node.type === "JSXFragment") hasJsx = true;
+
+      for (const [key, value] of Object.entries(node)) {
+        if (["loc", "range", "tokens", "comments"].includes(key)) continue;
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            if (child && typeof child.type === "string") collectJsx(child);
+          }
+        } else if (value && typeof value.type === "string") {
+          collectJsx(value);
+        }
+      }
+    }
+
+    collectJsx(ast);
+
+    let scopeManager;
+    try {
+      scopeManager = analyze(ast, {
+        ecmaVersion: 2022,
+        sourceType: "module",
+        optimistic: true,
+        ignoreEval: true,
+      });
+    } catch {
+      return issues;
+    }
+
+    for (const scope of scopeManager.scopes) {
+      for (const variable of scope.variables) {
+        const isImport = variable.defs?.some((definition) => definition.type === "ImportBinding");
+        if (!isImport) continue;
+
+        const hasRead = variable.references.some((reference) => reference.isRead());
+        const usedInJsx = jsxNames.has(variable.name);
+        const implicitReact = variable.name === "React" && hasJsx;
+
+        if (!hasRead && !usedInJsx && !implicitReact) {
+          const definition = variable.defs.find((item) => item.type === "ImportBinding");
+                   const target = definition?.name ?? variable.identifiers[0];
+          issues.push({
+            start: target?.range?.[0],
+            end: target?.range?.[1],
+            message: `Imported binding "${variable.name}" is never used`,
+          });
+        }
+      }
+    }
+
+    return issues;
+  },
+};
+
+export default unusedImport;

package/rules/index.js

@@ -0,0 +1,27 @@
+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,
+  debuggerStatement,
+  consoleLog,
+  emptyCatch,
+  unusedImport,
+  emptyBlock,
+  hardcodedSecret,
+  reactMissingKey,
+  reactDangerousHtml,
+  a11yImgAlt,
+  a11yInputLabel,
+  a11yClickDiv,
+];

package/rules/react/react-dangerous-html.js

@@ -0,0 +1,30 @@
+import { childNodes } from "../shared/jsx-helpers.js";
+
+const reactDangerousHtml = {
+  name: "react-dangerous-html",
+  description: "Flags uses of dangerouslySetInnerHTML, which can allow script injection",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      if (node.type === "JSXAttribute" && node.name?.name === "dangerouslySetInnerHTML") {
+        issues.push({
+          start: node.range?.[0],
+          end: node.range?.[1],
+          message: "dangerouslySetInnerHTML can run injected scripts; render normal JSX or sanitize the HTML first",
+        });
+      }
+
+      for (const child of childNodes(node)) visit(child);
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default reactDangerousHtml;

package/rules/react/react-missing-key.js

@@ -0,0 +1,56 @@
+import { childNodes, attributeNamed, hasSpread } from "../shared/jsx-helpers.js";
+
+function returnedJsx(fn) {
+  if (fn.body.type === "JSXElement") return fn.body;
+  if (fn.body.type !== "BlockStatement") return null;
+
+  for (const statement of fn.body.body) {
+    if (statement.type === "ReturnStatement" && statement.argument?.type === "JSXElement") {
+      return statement.argument;
+    }
+  }
+  return null;
+}
+
+const reactMissingKey = {
+  name: "react-missing-key",
+  description: "Flags list items created inside a .map() call without a key prop",
+  extensions: [".js", ".jsx", ".mjs", ".cjs"],
+  requiresAst: true,
+  check({ ast }) {
+    const issues = [];
+
+    function visit(node) {
+      if (!node || typeof node !== "object") return;
+
+      const callback = node.arguments?.[0];
+      if (
+        node.type === "CallExpression" &&
+        node.callee?.type === "MemberExpression" &&
+        node.callee.property?.name === "map" &&
+        callback &&
+        ["ArrowFunctionExpression", "FunctionExpression"].includes(callback.type)
+      ) {
+        const element = returnedJsx(callback);
+        if (
+          element &&
+          !hasSpread(element.openingElement) &&
+          !attributeNamed(element.openingElement, "key")
+        ) {
+          issues.push({
+            start: element.range?.[0],
+            end: element.range?.[1],
+            message: "List item needs a unique key prop so React can track it",
+          });
+        }
+      }
+
+      for (const child of childNodes(node)) visit(child);
+    }
+
+    visit(ast);
+    return issues;
+  },
+};
+
+export default reactMissingKey;