@vhite/vhite 0.0.0-stage → 0.6.0

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/core/files.js

@@ -0,0 +1,21 @@
+import { readdir } from "node:fs/promises";
+import { join, extname } from "node:path";
+
+const IGNORED = new Set(["node_modules", ".git", "dist", "build"]);
+const EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs", ".html", ".css"]);
+
+export async function findFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (IGNORED.has(entry.name)) continue;
+      files.push(...(await findFiles(join(dir, entry.name))));
+    } else if (EXTENSIONS.has(extname(entry.name))) {
+      files.push(join(dir, entry.name));
+    }
+  }
+
+  return files;
+}

package/src/core/setup.js

@@ -0,0 +1,114 @@
+import {
+  writeFile,
+  readFile,
+  appendFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { rules } from "../../rules/index.js";
+
+export const CONFIG_NAME = "vhite.config.json";
+
+export function canAskQuestions() {
+  return Boolean(
+    process.stdin.isTTY &&
+    process.stdout.isTTY &&
+    !process.env.CI
+  );
+}
+
+async function ensureConfigIgnored(root) {
+  const gitignorePath = join(root, ".gitignore");
+  const entry = CONFIG_NAME;
+
+  let contents = "";
+
+  try {
+    contents = await readFile(gitignorePath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+
+  const alreadyIgnored = contents
+    .split(/\r?\n/)
+    .some((line) => line.trim() === entry);
+
+  if (alreadyIgnored) return;
+
+  const prefix =
+    contents.length > 0 && !contents.endsWith("\n")
+      ? "\n"
+      : "";
+
+  await appendFile(
+    gitignorePath,
+    `${prefix}${entry}\n`,
+    "utf8"
+  );
+}
+
+export async function runFirstTimeSetup(root) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log(
+      `No ${CONFIG_NAME} found. Choose which rules to turn off.`
+    );
+
+    rules.forEach((rule, index) => {
+      console.log(
+        `  ${index + 1}. ${rule.name}: ${rule.description}`
+      );
+    });
+
+    console.log("");
+
+    const answer = (
+      await rl.question(
+        "Enter rule numbers separated by commas (for example 1,3), or press Enter to use all rules: "
+      )
+    ).trim();
+
+    const disabled = new Set();
+
+    if (answer !== "") {
+      for (const part of answer.split(",")) {
+        const entry = part.trim();
+        if (entry === "") continue;
+
+        const number = Number(entry);
+
+        if (
+          Number.isInteger(number) &&
+          number >= 1 &&
+          number <= rules.length
+        ) {
+          disabled.add(rules[number - 1].name);
+        } else {
+          console.log(
+            `Ignored "${entry}": not a rule number`
+          );
+        }
+      }
+    }
+
+    const config = {
+      disabledRules: [...disabled],
+    };
+
+    await writeFile(
+      join(root, CONFIG_NAME),
+      JSON.stringify(config, null, 2) + "\n",
+      "utf8"
+    );
+
+    await ensureConfigIgnored(root);
+
+    console.log(`Saved ${CONFIG_NAME}`);
+  } finally {
+    rl.close();
+  }
+}

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/fix/approve.js

@@ -0,0 +1,71 @@
+import { createInterface } from "node:readline/promises";
+import { relative } from "node:path";
+
+export async function chooseProposals(root, proposals) {
+  if (proposals.length === 0) {
+    return [];
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log(`\n${proposals.length} safe fix(es) available:\n`);
+
+    proposals.forEach((proposal, index) => {
+      console.log(
+        ` ${index + 1}. ${relative(root, proposal.file)} line ${proposal.line}: ${proposal.message}`
+      );
+
+      console.log(
+        ` Proposed change: delete this line: ${proposal.lineText}`
+      );
+    });
+
+    console.log("");
+
+    const answer = (
+      await rl.question(
+        "Enter fix numbers to apply (for example 1,3), type all, or press Enter to skip: "
+      )
+    ).trim().toLowerCase();
+
+    if (answer === "") {
+      return [];
+    }
+
+    if (answer === "all") {
+      return proposals;
+    }
+
+    const picked = new Set();
+
+    for (const part of answer.split(",")) {
+      const entry = part.trim();
+
+      if (entry === "") {
+        continue;
+      }
+
+      const number = Number(entry);
+
+      if (
+        Number.isInteger(number) &&
+        number >= 1 &&
+        number <= proposals.length
+      ) {
+        picked.add(number - 1);
+      } else {
+        console.log(`Ignored "${entry}": not a fix number`);
+      }
+    }
+
+    return [...picked]
+      .sort((a, b) => a - b)
+      .map((index) => proposals[index]);
+  } finally {
+    rl.close();
+  }
+}

package/src/fix/backup.js

@@ -0,0 +1,73 @@
+import { mkdir, copyFile, rm } from "node:fs/promises";
+import {
+  join,
+  relative,
+  dirname,
+  isAbsolute,
+} from "node:path";
+import {
+  FIX_DIR,
+  ensureGitignoreEntry,
+} from "./gitignore.js";
+
+export async function prepareBackupDir(root) {
+  const changed = await ensureGitignoreEntry(root);
+  const dir = join(root, FIX_DIR, "backup");
+
+  await mkdir(dir, { recursive: true });
+
+  return { dir, changed };
+}
+
+function backupPathFor(root, file, attempt) {
+  const rel = relative(root, file);
+
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(
+      `Refusing to back up a file outside the project: ${file}`
+    );
+  }
+
+  return join(
+    root,
+    FIX_DIR,
+    "backup",
+    `${rel}.${attempt}.bak`
+  );
+}
+
+export async function saveBackup(root, file, attempt) {
+  const dest = backupPathFor(root, file, attempt);
+
+  await mkdir(dirname(dest), { recursive: true });
+  await copyFile(file, dest);
+
+  return dest;
+}
+
+export async function restoreBackup(file, backupPath) {
+  await copyFile(backupPath, file);
+}
+
+/**
+ * Deletes only backups explicitly recorded in the results
+ * for this run. It does not delete older backup files.
+ */
+export async function deleteRunBackups(results) {
+  const paths = [
+    ...new Set(
+      results
+        .map((result) => result.backupPath)
+        .filter((backupPath) => typeof backupPath === "string")
+    ),
+  ];
+
+  let deleted = 0;
+
+  for (const backupPath of paths) {
+    await rm(backupPath, { force: true });
+    deleted += 1;
+  }
+
+  return { deleted, paths };
+}