@vhite/vhite 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,57 @@
-# 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 common problems left behind by AI code generators, explains each one in plain English, and can safely fix some of them.
+
+## Install and run
+
+Run it on any project folder without installing it:
+
+    npx @vhite/vhite path/to/your/project
+
+Or run it on the current folder:
+
+    npx @vhite/vhite .
+
+## 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.
+
+Supported file types: `.js`, `.jsx`, `.mjs`, `.cjs`, `.html`, and `.css`. Some checks only apply to JavaScript files.
+
+## Safe fixes
+
+Some problems can be fixed automatically: debugger statements, unused imports, and comments. vhite never changes a file without asking first.
+
+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`, so backups and reports stay out of your repository.
+
+Fixes only run in an interactive terminal. In scripts or CI, vhite only reports problems.
+
+## Settings
+
+Create a `vhite.config.json` file in your project to turn off specific checks:
+
+    {
+      "disabledRules": ["console-log", "leftover-todo"]
+    }
+
+Use the rule names shown in the report, in brackets at the end of each line.
+
+## 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.
+
+## License
+
+ISC

package/bin/cli.js

@@ -0,0 +1,216 @@
+#!/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);
+  }
+
+  config = await loadConfig(target);
+
+  for (const warning of config.warnings) {
+    console.log(`Warning: ${warning}`);
+  }
+
+  if (config.disabledRules.size > 0) {
+    console.log(
+           `Rules turned off by ${CONFIG_NAME}: ${[...config.disabledRules].join(", ")}`
+    );
+  }
+
+  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}`
+          );
+        }
+      }
+    }
+  }
+
+  // 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.");
+    }
+  }
+
+  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 (result.gitignoreUpdated) {
+        console.log(`Added ${FIX_DIR}/ to .gitignore`);
+      }
+
+      console.log(
+        `Report created successfully: ${relative(target, result.reportPath)}`
+      );
+    } else {
+      console.log("Report generation skipped.");
+    }
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@vhite/vhite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.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",
+    "code-cleanup",
+    "linter",
+    "front-end",
+    "javascript"
+  ],
+  "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/console-log.js

@@ -0,0 +1,43 @@
+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({
+          line: node.loc?.start.line ?? 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/debugger-statement.js

@@ -0,0 +1,35 @@
+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({
+          line: node.loc?.start.line ?? 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/empty-block.js

@@ -0,0 +1,40 @@
+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({
+          line: node.loc?.start.line ?? 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/empty-catch.js

@@ -0,0 +1,39 @@
+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({
+          line: node.loc?.start.line ?? 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/hardcoded-secret.js

@@ -0,0 +1,36 @@
+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");
+
+    lines.forEach((text, index) => {
+      for (const item of SECRET_PATTERNS) {
+        if (item.pattern.test(text)) {
+          issues.push({
+            line: index + 1,
+            message: `Possible hardcoded secret (${item.label}); move it to a secure environment variable and rotate it if real`,
+          });
+          break;
+        }
+      }
+    });
+
+    return issues;
+  },
+};
+
+export default hardcodedSecret;

package/rules/index.js

@@ -0,0 +1,17 @@
+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";
+
+export const rules = [
+  leftoverTodo,
+  debuggerStatement,
+  consoleLog,
+  emptyCatch,
+  unusedImport,
+  emptyBlock,
+  hardcodedSecret,
+];

package/rules/leftover-todo.js

@@ -0,0 +1,26 @@
+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 }) {
+    const issues = [];
+    for (const comment of ast.comments ?? []) {
+      const isTodo = todoPattern.test(comment.value);
+      issues.push({
+        line: comment.loc.start.line,
+        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/unused-import.js

@@ -0,0 +1,67 @@
+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");
+          issues.push({
+            line: definition?.name?.loc?.start.line ?? variable.identifiers[0]?.loc?.start.line ?? 1,
+            message: `Imported binding "${variable.name}" is never used`,
+          });
+        }
+      }
+    }
+
+    return issues;
+  },
+};
+
+export default unusedImport;