@yuu1111/comment-check 1.0.0 → 2.0.0

package/README.ja.md

@@ -0,0 +1,49 @@
+[English](README.md)
+
+# @yuu1111/comment-check
+
+baselineを持つ小さなcomment検査 抑制commentとplaceholder commentの増殖を止める
+
+## Install
+
+```bash
+bun add -D @yuu1111/comment-check
+```
+
+## Usage
+
+現在の検出を一度baselineへ記録し、新しく出たものだけを失敗にする
+
+```bash
+comment-check --update-baseline .
+comment-check .
+```
+
+```
+src/queue.ts:18:2 undocumented-directive TypeScript directive needs a description
+Checked 42 files: 1 new, 0 resolved, 3 baselined
+```
+
+## Rules
+
+| Rule | 検出対象 |
+|------|---------|
+| `broad-suppression` | `biome-ignore-all`、`@ts-nocheck`、ruleを書いていない `eslint-disable` |
+| `undocumented-directive` | 説明の無い `@ts-ignore` と `@ts-expect-error` |
+| `placeholder-comment` | `TODO`、`FIXME`、`XXX`、`HACK` |
+| `separator-comment` | 記号だけで作った装飾comment |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--baseline <path>` | 読み書きするbaseline file（既定は `comment-baseline.json`） |
+| `--ignore <path>` | 検査から外すpath 複数指定できる |
+| `--update-baseline` | baselineを現在の検出で置き換える |
+| `--json` | 新規と解消済みの検出をJSONで出力する |
+
+## Notes
+
+生成物のディレクトリなどProjectが持つpathは `--ignore` で検査から外す 例えば `--ignore src/generated`
+
+baselineはrule、file、comment本文をキーにするため、行が動いてもそのcommentを新規とは報告しない Biomeは `biome-ignore` の理由と未使用の抑制を既に扱うため、このcheckerはBiomeが読まないcommentの細部だけを担当する

package/README.md

@@ -1,3 +1,5 @@
+[日本語](README.ja.md)
+
 # @yuu1111/comment-check
 
 Small comment checker with a baseline, used to keep suppressions and placeholder

package/dist/cli.js

@@ -0,0 +1,586 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/scan.ts
+import { readFileSync } from "fs";
+import { relative as relative2 } from "path";
+
+// ../shared/src/files.ts
+import { readdirSync, statSync } from "fs";
+import { extname, join, relative, resolve } from "path";
+var IGNORED_DIRECTORIES = new Set([
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "vendor"
+]);
+function normalizePath(path) {
+  return path.split("\\").join("/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function isIgnored(path, ignores) {
+  return ignores.some((ignore) => path === ignore || path.startsWith(`${ignore}/`));
+}
+function walk(directory, extensions, files) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRECTORIES.has(entry.name)) {
+        walk(path, extensions, files);
+      }
+      continue;
+    }
+    if (entry.isFile() && extensions.has(extname(entry.name))) {
+      files.add(path);
+    }
+  }
+}
+function collectFiles(targets, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const ignores = options.ignores ?? [];
+  const files = new Set;
+  for (const target of targets) {
+    const absolute = resolve(cwd, target);
+    let stats;
+    try {
+      stats = statSync(absolute);
+    } catch {
+      continue;
+    }
+    if (stats.isFile()) {
+      if (options.extensions.has(extname(absolute)) && !isIgnored(normalizePath(target), ignores)) {
+        files.add(absolute);
+      }
+      continue;
+    }
+    walk(absolute, options.extensions, files);
+  }
+  return [...files].filter((file) => !isIgnored(normalizePath(relative(cwd, file)), ignores)).sort();
+}
+
+// ../shared/src/findings.ts
+function compareFindings(left, right) {
+  if (left.file !== right.file) {
+    return left.file < right.file ? -1 : 1;
+  }
+  if (left.line !== right.line) {
+    return left.line - right.line;
+  }
+  return left.column - right.column;
+}
+function formatLocation(finding) {
+  return `${finding.file}:${finding.line}:${finding.column}`;
+}
+
+// src/comments.ts
+var REGEX_PRECEDING_CHARACTERS = new Set("(,=:[!&|?{};".split(""));
+var REGEX_PRECEDING_KEYWORDS = new Set([
+  "await",
+  "case",
+  "delete",
+  "do",
+  "else",
+  "in",
+  "instanceof",
+  "new",
+  "of",
+  "return",
+  "throw",
+  "typeof",
+  "void",
+  "yield"
+]);
+function isIdentifierCharacter(character) {
+  return /[A-Za-z0-9_$]/.test(character);
+}
+function skipString(source, start, quote) {
+  let index = start + 1;
+  while (index < source.length) {
+    const character = source[index] ?? "";
+    if (character === "\\") {
+      index += 2;
+      continue;
+    }
+    if (character === quote) {
+      return index + 1;
+    }
+    if (character === `
+`) {
+      return index;
+    }
+    index += 1;
+  }
+  return index;
+}
+function isRegexStart(source, index) {
+  let previous = index - 1;
+  while (previous >= 0 && /\s/.test(source[previous] ?? "")) {
+    previous -= 1;
+  }
+  if (previous < 0) {
+    return true;
+  }
+  const character = source[previous] ?? "";
+  if (REGEX_PRECEDING_CHARACTERS.has(character)) {
+    return true;
+  }
+  if (!isIdentifierCharacter(character)) {
+    return false;
+  }
+  let wordStart = previous;
+  while (wordStart >= 0 && isIdentifierCharacter(source[wordStart] ?? "")) {
+    wordStart -= 1;
+  }
+  return REGEX_PRECEDING_KEYWORDS.has(source.slice(wordStart + 1, previous + 1));
+}
+function skipRegex(source, start) {
+  let index = start + 1;
+  let inClass = false;
+  while (index < source.length) {
+    const character = source[index] ?? "";
+    if (character === "\\") {
+      index += 2;
+      continue;
+    }
+    if (character === `
+`) {
+      return start;
+    }
+    if (inClass) {
+      inClass = character !== "]";
+      index += 1;
+      continue;
+    }
+    if (character === "[") {
+      inClass = true;
+      index += 1;
+      continue;
+    }
+    if (character === "/") {
+      return index + 1;
+    }
+    index += 1;
+  }
+  return start;
+}
+function currentMode(state) {
+  return state.modes[state.modes.length - 1] ?? "code";
+}
+function stepComment(state, source) {
+  const character = source[state.index] ?? "";
+  const next = source[state.index + 1] ?? "";
+  if (character !== "/" || next !== "/" && next !== "*") {
+    return false;
+  }
+  if (next === "/") {
+    const newline = source.indexOf(`
+`, state.index);
+    const stop2 = newline === -1 ? source.length : newline;
+    state.comments.push({
+      end: stop2,
+      kind: "line",
+      start: state.index,
+      text: source.slice(state.index + 2, stop2)
+    });
+    state.index = stop2;
+    return true;
+  }
+  const close = source.indexOf("*/", state.index + 2);
+  const stop = close === -1 ? source.length : close + 2;
+  state.comments.push({
+    end: stop,
+    kind: "block",
+    start: state.index,
+    text: source.slice(state.index + 2, Math.max(state.index + 2, stop - 2))
+  });
+  state.index = stop;
+  return true;
+}
+function stepString(state, source) {
+  const character = source[state.index] ?? "";
+  if (character !== "'" && character !== '"') {
+    return false;
+  }
+  state.index = skipString(source, state.index, character);
+  return true;
+}
+function stepTemplateStart(state, source) {
+  if (source[state.index] !== "`") {
+    return false;
+  }
+  state.modes.push("template");
+  state.index += 1;
+  return true;
+}
+function stepRegex(state, source) {
+  if (source[state.index] !== "/" || !isRegexStart(source, state.index)) {
+    return false;
+  }
+  const stop = skipRegex(source, state.index);
+  if (stop <= state.index) {
+    return false;
+  }
+  state.index = stop;
+  return true;
+}
+function stepTemplate(state, source) {
+  const character = source[state.index] ?? "";
+  if (character === "\\") {
+    state.index += 2;
+    return;
+  }
+  if (character === "`") {
+    state.modes.pop();
+    state.index += 1;
+    return;
+  }
+  if (character === "$" && source[state.index + 1] === "{") {
+    state.modes.push("expression");
+    state.braces.push(1);
+    state.index += 2;
+    return;
+  }
+  state.index += 1;
+}
+function stepExpression(state, source) {
+  const character = source[state.index] ?? "";
+  const depth = state.braces[state.braces.length - 1] ?? 0;
+  if (character === "{") {
+    state.braces[state.braces.length - 1] = depth + 1;
+  } else if (character === "}") {
+    state.braces[state.braces.length - 1] = depth - 1;
+    if (depth - 1 === 0) {
+      state.modes.pop();
+      state.braces.pop();
+    }
+  }
+  state.index += 1;
+}
+function step(state, source) {
+  if (currentMode(state) === "template") {
+    stepTemplate(state, source);
+    return;
+  }
+  if (stepComment(state, source) || stepString(state, source) || stepTemplateStart(state, source) || stepRegex(state, source)) {
+    return;
+  }
+  stepExpression(state, source);
+}
+function extractComments(source) {
+  const shebang = source.startsWith("#!") ? source.indexOf(`
+`) : 0;
+  const state = {
+    braces: [],
+    comments: [],
+    index: Math.max(0, shebang),
+    modes: ["code"]
+  };
+  while (state.index < source.length) {
+    step(state, source);
+  }
+  return state.comments;
+}
+
+// src/rules.ts
+var PLACEHOLDER_PATTERN = /\b(TODO|FIXME|XXX|HACK)\b/;
+var SEPARATOR_PATTERN = /^[-=*_#~+./\\|]{4,}$/;
+var DIRECTIVE_PATTERN = /^@ts-(?:ignore|expect-error)\b([\s\S]*)$/;
+function normalizeComment(body) {
+  return body.split(`
+`).map((line) => line.replace(/^\s*\*+\s?/, "")).join(" ").replace(/\s+/g, " ").trim();
+}
+function classifyComment(body) {
+  const text = normalizeComment(body);
+  if (text === "") {
+    return null;
+  }
+  if (/^(?:biome-ignore-all|@ts-nocheck)\b/.test(text) || /^eslint-disable(?:-next-line|-line)?\s*$/.test(text)) {
+    return "broad-suppression";
+  }
+  const directive = DIRECTIVE_PATTERN.exec(text);
+  if (directive) {
+    return (directive[1] ?? "").replace(/^[\s:\u2014-]+/, "") === "" ? "undocumented-directive" : null;
+  }
+  if (PLACEHOLDER_PATTERN.test(text)) {
+    return "placeholder-comment";
+  }
+  if (SEPARATOR_PATTERN.test(text)) {
+    return "separator-comment";
+  }
+  return null;
+}
+
+// src/scan.ts
+var SUPPORTED_EXTENSIONS = new Set([
+  ".cjs",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".mts",
+  ".ts",
+  ".tsx"
+]);
+function positionAt(source, offset) {
+  let line = 1;
+  let lineStart = 0;
+  for (let index = 0;index < offset; index += 1) {
+    if (source[index] === `
+`) {
+      line += 1;
+      lineStart = index + 1;
+    }
+  }
+  return { line, column: offset - lineStart + 1 };
+}
+function scanSource(source, file) {
+  const findings = [];
+  for (const comment of extractComments(source)) {
+    const rule = classifyComment(comment.text);
+    if (rule === null) {
+      continue;
+    }
+    const position = positionAt(source, comment.start);
+    findings.push({
+      column: position.column,
+      file,
+      line: position.line,
+      rule,
+      text: normalizeComment(comment.text)
+    });
+  }
+  return findings;
+}
+function scanFile(file, cwd = process.cwd()) {
+  return scanSource(readFileSync(file, "utf8"), normalizePath(relative2(cwd, file)));
+}
+function scanFiles(files, cwd = process.cwd()) {
+  const findings = [];
+  for (const file of files) {
+    findings.push(...scanFile(file, cwd));
+  }
+  return findings.sort(compareFindings);
+}
+
+// ../shared/src/baseline.ts
+import { existsSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+
+// ../shared/src/json.ts
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ../shared/src/baseline.ts
+function entryKey(entry) {
+  return [entry.engine ?? "", entry.rule, entry.file, entry.text].join("\x00");
+}
+function compareEntries(left, right) {
+  const leftKey = entryKey(left);
+  const rightKey = entryKey(right);
+  if (leftKey === rightKey) {
+    return 0;
+  }
+  return leftKey < rightKey ? -1 : 1;
+}
+function toEntry(finding) {
+  const entry = {
+    count: 1,
+    file: finding.file,
+    rule: finding.rule,
+    text: finding.text
+  };
+  if (finding.engine !== undefined) {
+    entry.engine = finding.engine;
+  }
+  return entry;
+}
+function createBaseline(findings) {
+  const entries = new Map;
+  for (const finding of findings) {
+    const key = entryKey(finding);
+    const existing = entries.get(key);
+    if (existing) {
+      existing.count += 1;
+      continue;
+    }
+    entries.set(key, toEntry(finding));
+  }
+  return { entries: [...entries.values()].sort(compareEntries), version: 1 };
+}
+function compareWithBaseline(findings, baseline) {
+  const remaining = new Map;
+  for (const entry of baseline.entries) {
+    const key = entryKey(entry);
+    remaining.set(key, (remaining.get(key) ?? 0) + entry.count);
+  }
+  const added = [];
+  for (const finding of findings) {
+    const key = entryKey(finding);
+    const count = remaining.get(key) ?? 0;
+    if (count > 0) {
+      remaining.set(key, count - 1);
+      continue;
+    }
+    added.push(finding);
+  }
+  const resolved = baseline.entries.filter((entry) => (remaining.get(entryKey(entry)) ?? 0) > 0);
+  return { added, resolved };
+}
+function isBaselineEntry(value) {
+  if (!isJsonObject(value)) {
+    return false;
+  }
+  return (value.engine === undefined || typeof value.engine === "string") && typeof value.file === "string" && typeof value.rule === "string" && typeof value.text === "string" && typeof value.count === "number";
+}
+function readBaseline(path, label) {
+  if (!existsSync(path)) {
+    return { entries: [], version: 1 };
+  }
+  const value = JSON.parse(readFileSync2(path, "utf8"));
+  if (!isJsonObject(value) || !Array.isArray(value.entries) || !value.entries.every(isBaselineEntry)) {
+    throw new Error(`${path} is not a ${label} baseline`);
+  }
+  return { entries: value.entries, version: 1 };
+}
+function writeBaseline(path, baseline) {
+  writeFileSync(path, `${JSON.stringify(baseline, null, "\t")}
+`);
+}
+
+// ../shared/src/cli.ts
+function addValue(values, name, value) {
+  const list = values.get(name);
+  if (list === undefined) {
+    values.set(name, [value]);
+    return;
+  }
+  list.push(value);
+}
+function addTarget(targets, argument) {
+  if (argument.startsWith("-")) {
+    throw new Error(`unknown option: ${argument}`);
+  }
+  targets.push(argument);
+}
+function optionName(argument) {
+  const separator = argument.indexOf("=");
+  return separator === -1 ? argument.slice(2) : argument.slice(2, separator);
+}
+function inlineValue(argument) {
+  const separator = argument.indexOf("=");
+  return separator === -1 ? undefined : argument.slice(separator + 1);
+}
+function consumeValue(values, argv, index, name) {
+  const value = argv[index + 1];
+  if (value === undefined) {
+    return 0;
+  }
+  addValue(values, name, value);
+  return 1;
+}
+function parseArgv(argv, spec) {
+  const flags = new Set;
+  const values = new Map;
+  const valueNames = new Set(spec.values ?? []);
+  const flagNames = new Set(spec.flags ?? []);
+  const targets = [];
+  for (let index = 0;index < argv.length; index += 1) {
+    const argument = argv[index] ?? "";
+    if (!argument.startsWith("--")) {
+      addTarget(targets, argument);
+      continue;
+    }
+    const name = optionName(argument);
+    if (valueNames.has(name)) {
+      const inline = inlineValue(argument);
+      if (inline !== undefined) {
+        addValue(values, name, inline);
+        continue;
+      }
+      index += consumeValue(values, argv, index, name);
+      continue;
+    }
+    if (flagNames.has(name) && argument.indexOf("=") === -1) {
+      flags.add(name);
+      continue;
+    }
+    throw new Error(`unknown option: ${argument}`);
+  }
+  return { flags, targets, values };
+}
+function wantsHelp(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+function runCli(main) {
+  async function execute() {
+    try {
+      process.exit(await main(process.argv.slice(2)));
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(2);
+    }
+  }
+  execute();
+}
+
+// src/cli.ts
+var DEFAULT_BASELINE = "comment-baseline.json";
+var RULE_MESSAGES = {
+  "broad-suppression": "file-wide suppression hides too much",
+  "placeholder-comment": "placeholder comment should be resolved or tracked",
+  "separator-comment": "decorative separator comment adds no information",
+  "undocumented-directive": "TypeScript directive needs a description"
+};
+var USAGE = "Usage: comment-check [--baseline <path>] [--ignore <path>] [--update-baseline] [--json] [path...]";
+function parseArguments(argv) {
+  const parsed = parseArgv(argv, {
+    flags: ["json", "update-baseline"],
+    values: ["baseline", "ignore"]
+  });
+  return {
+    baselinePath: parsed.values.get("baseline")?.at(-1) ?? DEFAULT_BASELINE,
+    ignores: (parsed.values.get("ignore") ?? []).map(normalizePath),
+    json: parsed.flags.has("json"),
+    targets: parsed.targets.length > 0 ? parsed.targets : ["."],
+    update: parsed.flags.has("update-baseline")
+  };
+}
+function describeFinding(finding) {
+  const message = RULE_MESSAGES[finding.rule] ?? "";
+  return `${formatLocation(finding)} ${finding.rule} ${message}`.trimEnd();
+}
+function main(argv) {
+  if (wantsHelp(argv)) {
+    console.log(USAGE);
+    return 0;
+  }
+  const options = parseArguments(argv);
+  const files = collectFiles(options.targets, {
+    cwd: process.cwd(),
+    extensions: SUPPORTED_EXTENSIONS,
+    ignores: options.ignores
+  });
+  const findings = scanFiles(files);
+  if (options.update) {
+    const baseline2 = createBaseline(findings);
+    writeBaseline(options.baselinePath, baseline2);
+    console.log(`Recorded ${baseline2.entries.length} entries in ${options.baselinePath}`);
+    return 0;
+  }
+  const baseline = readBaseline(options.baselinePath, "comment");
+  const comparison = compareWithBaseline(findings, baseline);
+  if (options.json) {
+    console.log(JSON.stringify({ added: comparison.added, resolved: comparison.resolved }, null, "\t"));
+  } else {
+    for (const finding of comparison.added) {
+      console.log(describeFinding(finding));
+    }
+    console.log(`Checked ${files.length} files: ${comparison.added.length} new, ${comparison.resolved.length} resolved, ${baseline.entries.length} baselined`);
+  }
+  return comparison.added.length > 0 ? 1 : 0;
+}
+runCli(main);