@vhite/vhite 0.1.0 → 0.6.0

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;

package/rules/shared/jsx-helpers.js

@@ -0,0 +1,30 @@
+export const SKIP_KEYS = new Set(["loc", "range", "tokens", "comments", "parent"]);
+
+export function childNodes(node) {
+  const children = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (SKIP_KEYS.has(key)) continue;
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child.type === "string") children.push(child);
+      }
+    } else if (value && typeof value.type === "string") {
+      children.push(value);
+    }
+  }
+  return children;
+}
+
+export function attributeNamed(element, name) {
+  return element.attributes.find(
+    (attr) => attr.type === "JSXAttribute" && attr.name?.name === name
+  );
+}
+
+export function hasSpread(element) {
+  return element.attributes.some((attr) => attr.type === "JSXSpreadAttribute");
+}
+
+export function literalValue(attribute) {
+  return attribute?.value?.type === "Literal" ? attribute.value.value : null;
+}

package/src/core/args.js

@@ -0,0 +1,134 @@
+export const COMMANDS = ["scan", "fix", "baseline", "hook", "rules", "explain", "version", "help"];
+
+const FORMATS = ["text", "json", "sarif"];
+const VALUE_FLAGS = new Set(["--format", "--rule", "--disable", "--include", "--exclude"]);
+
+export class UsageError extends Error {}
+
+export function parseArgs(argv) {
+  const args = [...argv];
+  const options = {
+    command: "scan",
+    positionals: [],
+    format: "text",
+    quiet: false,
+    fix: false,
+    changed: false,
+    staged: false,
+    useBaseline: true,
+    watch: false,
+    noPrompt: false,
+    force: false,
+    rules: [],
+    disable: [],
+    include: [],
+    exclude: [],
+  };
+
+  if (args.length > 0 && COMMANDS.includes(args[0])) {
+    options.command = args.shift();
+  }
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--help" || arg === "-h") {
+      options.command = "help";
+    } else if (arg === "--version" || arg === "-v") {
+      options.command = "version";
+    } else if (arg === "--quiet" || arg === "-q") {
+      options.quiet = true;
+    } else if (arg === "--fix") {
+      options.fix = true;
+    } else if (arg === "--changed") {
+      options.changed = true;
+    } else if (arg === "--staged") {
+      options.staged = true;
+    } else if (arg === "--no-baseline") {
+      options.useBaseline = false;
+    } else if (arg === "--no-prompt") {
+      options.noPrompt = true;
+    } else if (arg === "--watch") {
+      options.watch = true;
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (VALUE_FLAGS.has(arg)) {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new UsageError(`${arg} needs a value`);
+      }
+      index += 1;
+      applyValue(options, arg, value);
+    } else if (arg.startsWith("-")) {
+      throw new UsageError(`Unknown option: ${arg}`);
+    } else {
+      options.positionals.push(arg);
+    }
+  }
+
+  if (options.changed && options.staged) {
+    throw new UsageError("Use either --changed or --staged, not both");
+  }
+
+  if (options.watch && (options.command !== "scan" || options.format !== "text")) {
+    throw new UsageError("--watch works only with a scan that prints text");
+  }
+
+  if (options.command === "explain") {
+    if (options.positionals.length !== 1) {
+      throw new UsageError("explain needs exactly one rule name, for example: vhite explain console-log");
+    }
+    options.ruleName = options.positionals[0];
+  } else if (options.command === "hook") {
+    const action = options.positionals[0];
+    if (!["install", "remove"].includes(action)) {
+      throw new UsageError("hook needs an action: vhite hook install or vhite hook remove");
+    }
+    if (options.positionals.length > 2) {
+      throw new UsageError("Only one folder can be used with hook");
+    }
+    options.hookAction = action;
+    options.path = options.positionals[1] ?? ".";
+  } else if (["scan", "fix", "baseline"].includes(options.command)) {
+    if (options.positionals.length > 1) {
+      throw new UsageError("Only one folder can be scanned at a time");
+    }
+    options.path = options.positionals[0] ?? ".";
+  }
+
+  return options;
+}
+
+function applyValue(options, flag, value) {
+  if (flag === "--format") {
+    if (!FORMATS.includes(value)) {
+      throw new UsageError(`--format must be text, json, or sarif, not "${value}"`);
+    }
+    options.format = value;
+  } else if (flag === "--rule") {
+    options.rules.push(value);
+  } else if (flag === "--disable") {
+    options.disable.push(value);
+  } else if (flag === "--include") {
+    options.include.push(value);
+  } else if (flag === "--exclude") {
+    options.exclude.push(value);
+  }
+}
+
+export function normalizePath(path) {
+  const cleaned = path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+  return cleaned === "." ? "" : cleaned;
+}
+
+export function isIncluded(relativePath, include, exclude) {
+  const rel = normalizePath(relativePath);
+  const matches = (prefix) => {
+    const clean = normalizePath(prefix);
+    return clean === "" || rel === clean || rel.startsWith(`${clean}/`);
+  };
+
+  if (include.length > 0 && !include.some(matches)) return false;
+  if (exclude.some(matches)) return false;
+  return true;
+}

package/src/core/config.js

@@ -0,0 +1,92 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { rules } from "../../rules/index.js";
+
+const CONFIG_NAME = "vhite.config.json";
+const knownRules = new Set(rules.map((rule) => rule.name));
+const VALID_SEVERITIES = new Set(["error", "warning", "info", "off"]);
+
+const DEFAULT_SEVERITY = {
+  parser: "error",
+  "hardcoded-secret": "error",
+  "debugger-statement": "error",
+  "console-log": "warning",
+  "empty-catch": "warning",
+  "unused-import": "warning",
+  "empty-block": "warning",
+  "leftover-todo": "info",
+};
+
+export function severityOf(name, config) {
+  return config.severities.get(name) ?? DEFAULT_SEVERITY[name] ?? "warning";
+}
+
+export function applySeverity(issues, config) {
+  for (const issue of issues) {
+    issue.severity = severityOf(issue.rule, config);
+  }
+  return issues;
+}
+
+export async function loadConfig(root) {
+  const empty = { disabledRules: new Set(), severities: new Map(), warnings: [] };
+
+  let text;
+  try {
+    text = await readFile(join(root, CONFIG_NAME), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return empty;
+    throw error;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${CONFIG_NAME} is not valid JSON: ${error.message}`);
+  }
+
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error(`${CONFIG_NAME} must contain a JSON object`);
+  }
+
+  const config = { ...empty, disabledRules: new Set(), severities: new Map(), warnings: [] };
+
+  const requested = Array.isArray(data.disabledRules) ? data.disabledRules : [];
+  for (const name of requested) {
+    if (knownRules.has(name)) {
+      config.disabledRules.add(name);
+    } else {
+      config.warnings.push(`"${name}" is not a rule name, so it was ignored`);
+    }
+  }
+
+  if (data.rules !== undefined) {
+    if (typeof data.rules !== "object" || data.rules === null || Array.isArray(data.rules)) {
+      throw new Error(`${CONFIG_NAME} "rules" must be an object`);
+    }
+
+    for (const [name, value] of Object.entries(data.rules)) {
+      if (!knownRules.has(name)) {
+        config.warnings.push(`"${name}" is not a rule name, so it was ignored`);
+        continue;
+      }
+
+      const severity = typeof value === "string" ? value : value?.severity;
+      if (!VALID_SEVERITIES.has(severity)) {
+        config.warnings.push(
+          `"${name}" has an unknown severity "${severity}", so the default was kept`
+        );
+        continue;
+      }
+
+      if (severity === "off") {
+        config.disabledRules.add(name);
+      } else {
+        config.severities.set(name, severity);
+      }
+    }
+  }
+
+  return config;
+}

package/src/core/engine.js

@@ -0,0 +1,144 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { parse } from "espree";
+import { rules } from "../../rules/index.js";
+
+function parseSource(source, file) {
+  const extension = extname(file).toLowerCase();
+
+  return parse(source, {
+    ecmaVersion: "latest",
+    sourceType: extension === ".cjs" ? "commonjs" : "module",
+    ecmaFeatures: {
+      jsx: true,
+    },
+    loc: true,
+    range: true,
+    comment: true,
+    tokens: true,
+    allowHashBang: true,
+  });
+}
+
+function lineStartsOf(source) {
+  const starts = [0];
+  for (let index = 0; index < source.length; index += 1) {
+    if (source[index] === "\n") starts.push(index + 1);
+  }
+  return starts;
+}
+
+function positionAt(starts, offset) {
+  let low = 0;
+  let high = starts.length - 1;
+
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (starts[middle] <= offset) {
+      low = middle;
+    } else {
+      high = middle - 1;
+    }
+  }
+
+  return { line: low + 1, column: offset - starts[low] + 1 };
+}
+
+function withLocation(issue, source, starts) {
+  if (typeof issue.start !== "number") {
+    return {
+      ...issue,
+      line: issue.line ?? 1,
+      column: issue.column ?? 1,
+    };
+  }
+
+  const start = positionAt(starts, issue.start);
+  const end = positionAt(starts, Math.max(issue.end ?? issue.start, issue.start));
+  const lineStart = starts[start.line - 1];
+  const lineEnd = source.indexOf("\n", lineStart);
+  const snippet = source
+    .slice(lineStart, lineEnd === -1 ? source.length : lineEnd)
+    .replace(/\r$/, "");
+
+  return {
+    ...issue,
+    line: start.line,
+    column: start.column,
+    endLine: end.line,
+    endColumn: end.column,
+    snippet,
+  };
+}
+
+export async function runRules(files, { disabledRules = new Set() } = {}) {
+  const issues = [];
+  const activeRules = rules.filter((rule) => !disabledRules.has(rule.name));
+
+  for (const file of files) {
+    const source = await readFile(file, "utf8");
+    const extension = extname(file).toLowerCase();
+    const starts = lineStartsOf(source);
+
+    const applicableRules = activeRules.filter((rule) =>
+      rule.extensions?.includes(extension)
+    );
+
+    if (applicableRules.length === 0) {
+      continue;
+    }
+
+    const needsAst = applicableRules.some(
+      (rule) => rule.requiresAst === true
+    );
+
+    let ast;
+
+    if (needsAst) {
+      try {
+        ast = parseSource(source, file);
+      } catch (error) {
+        issues.push(
+          withLocation(
+            {
+              rule: "parser",
+              file,
+              line: error.lineNumber ?? 1,
+              message: `Unable to parse file: ${error.message}`,
+            },
+            source,
+            starts
+          )
+        );
+      }
+    }
+
+    for (const rule of applicableRules) {
+      if (rule.requiresAst === true && !ast) {
+        continue;
+      }
+
+      const found = rule.check({
+        file,
+        source,
+        ...(rule.requiresAst === true ? { ast } : {}),
+      });
+
+      for (const issue of found) {
+        issues.push(
+          withLocation(
+            {
+              rule: rule.name,
+              file,
+              ...issue,
+            },
+            source,
+            starts
+          )
+        );
+      }
+    }
+  }
+
+  return issues;
+}

package/src/core/exit-codes.js

@@ -0,0 +1,15 @@
+export const EXIT = {
+  CLEAN: 0,
+  ISSUES: 1,
+  ERROR: 2,
+  FIXED: 3,
+  ROLLED_BACK: 4,
+};
+
+export function decideExitCode({ failed = false, rolledBack = 0, issues = 0, applied = 0 }) {
+  if (failed) return EXIT.ERROR;
+  if (rolledBack > 0) return EXIT.ROLLED_BACK;
+  if (issues > 0) return EXIT.ISSUES;
+  if (applied > 0) return EXIT.FIXED;
+  return EXIT.CLEAN;
+}

package/src/{setup.js → core/setup.js}

@@ -5,7 +5,7 @@ import {
 } from "node:fs/promises";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { rules } from "../rules/index.js";
+import { rules } from "../../rules/index.js";
 
 export const CONFIG_NAME = "vhite.config.json";
 

package/src/core/version.js

@@ -0,0 +1,6 @@
+import { readFile } from "node:fs/promises";
+
+export async function readVersion() {
+  const text = await readFile(new URL("../../package.json", import.meta.url), "utf8");
+  return JSON.parse(text).version;
+}

package/src/{safe-fix.js → fix/safe-fix.js}

@@ -2,7 +2,7 @@ import {
   readFile,
   writeFile,
 } from "node:fs/promises";
-import { runRules } from "./engine.js";
+import { runRules } from "../core/engine.js";
 import {
   fixers as defaultFixers,
 } from "./fixers/index.js";

package/src/output/explanations-frontend.js

@@ -0,0 +1,22 @@
+export const frontendExplanations = {
+  "react-missing-key": {
+    whatHappened: "Items in a list are created without a key. React uses keys to track items, so without them it can reuse or lose the wrong elements when the list changes.",
+    proposedChange: "Add a key prop with a value that is unique and stable for each item, such as an id from your data. Avoid using the array index when items can be added, removed, or reordered.",
+  },
+  "react-dangerous-html": {
+    whatHappened: "dangerouslySetInnerHTML inserts raw HTML into the page. If that HTML comes from users or an API, it can contain scripts that run in other people's browsers.",
+    proposedChange: "Render the content with normal JSX where possible. If raw HTML is required, sanitize it first with a trusted library such as DOMPurify.",
+  },
+  "a11y-img-alt": {
+    whatHappened: "An image without alt text is silent for people using screen readers, and it shows nothing if the image fails to load.",
+    proposedChange: "Add alt text that describes what the image shows or means. For decorative images, use alt=\"\" so screen readers skip them.",
+  },
+  "a11y-input-label": {
+    whatHappened: "A form input without a label is hard to use with a screen reader, because the user can't tell what to type.",
+    proposedChange: "Connect the input to a label element with a matching htmlFor and id, or add an aria-label that describes the field.",
+  },
+  "a11y-click-div": {
+    whatHappened: "A clickable div or span can be clicked with a mouse, but it can't be reached with a keyboard and screen readers don't announce it as a button.",
+    proposedChange: "Use a button element for actions and an a element for links. If you must use a div, add role, tabIndex, and a key handler for Enter and Space.",
+  },
+};

package/src/{explanations.js → output/explanations.js}

@@ -1,3 +1,4 @@
+  import { frontendExplanations } from "./explanations-frontend.js";
 export const explanations = {
    "leftover-todo": {
     whatHappened: "A comment is still in the code. Comments that mark unfinished work (TODO or FIXME) are easy to forget before release, and other comments can go out of date and mislead the next developer.",
@@ -31,5 +32,6 @@ export const explanations = {
     whatHappened: "vhite couldn't read this file as JavaScript, so it skipped the checks that need to understand the code.",
     proposedChange: "Open the file at the line shown and fix the syntax error, then scan again.",
   },
+      ...frontendExplanations,
 };
 

package/src/output/json-output.js

@@ -0,0 +1,47 @@
+import { relative, sep } from "node:path";
+
+function toPosix(path) {
+  return path.split(sep).join("/");
+}
+
+export function formatJson({ root, filesScanned, issues, fixes = [], version }) {
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const issue of issues) {
+    counts[issue.severity] = (counts[issue.severity] ?? 0) + 1;
+  }
+
+  const sorted = [...issues].sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      a.line - b.line ||
+      (a.column ?? 1) - (b.column ?? 1)
+  );
+
+  return JSON.stringify(
+    {
+      version,
+      root: toPosix(root),
+      filesScanned,
+      summary: { total: issues.length, ...counts },
+      issues: sorted.map((issue) => ({
+        rule: issue.rule,
+        severity: issue.severity,
+        file: toPosix(relative(root, issue.file)),
+        line: issue.line,
+        column: issue.column ?? 1,
+        endLine: issue.endLine ?? issue.line,
+        endColumn: issue.endColumn ?? issue.column ?? 1,
+        message: issue.message,
+        snippet: issue.snippet,
+      })),
+      fixes: fixes.map((result) => ({
+        rule: result.proposal.rule,
+        file: toPosix(relative(root, result.proposal.file)),
+        line: result.proposal.line,
+        status: result.status,
+      })),
+    },
+    null,
+    2
+  );
+}

package/src/{reporter.js → output/reporter.js}

@@ -1,6 +1,15 @@
 import { relative } from "node:path";
 import { explanations } from "./explanations.js";
 
+function caretFor(issue) {
+  const startColumn = issue.column ?? 1;
+  const width =
+    issue.endLine === issue.line && issue.endColumn > startColumn
+      ? issue.endColumn - startColumn
+      : Math.max(1, issue.snippet.length - startColumn + 1);
+  return " ".repeat(startColumn - 1) + "^".repeat(width);
+}
+
 export function formatReport(issues, root) {
   if (issues.length === 0) return "No issues found.";
 
@@ -17,9 +26,19 @@ export function formatReport(issues, root) {
   for (const file of sortedFiles) {
     const fileIssues = byFile.get(file);
     lines.push(relative(root, file));
-    fileIssues.sort((a, b) => a.line - b.line);
+    fileIssues.sort(
+      (a, b) => a.line - b.line || (a.column ?? 1) - (b.column ?? 1)
+    );
     for (const issue of fileIssues) {
       lines.push(`  Line ${issue.line}: ${issue.message} [${issue.rule}]`);
+
+      if (issue.snippet !== undefined && issue.endLine !== undefined) {
+        const gutter = String(issue.line);
+        const blank = " ".repeat(gutter.length);
+        lines.push(`    ${gutter} | ${issue.snippet}`);
+        lines.push(`    ${blank} | ${caretFor(issue)}`);
+      }
+
       const info = explanations[issue.rule];
       if (info) {
         lines.push(`    What happened: ${info.whatHappened}`);

package/src/{run-report.js → output/run-report.js}

@@ -7,7 +7,7 @@ import { createInterface } from "node:readline/promises";
 import {
   FIX_DIR,
   ensureGitignoreEntry,
-} from "./gitignore.js";
+} from "../fix/gitignore.js";
 
 function escapeMarkdown(value) {
   return String(value ?? "")