@yuu1111/comment-check 1.0.0 → 2.0.0

package/dist/scan.js

@@ -0,0 +1,371 @@
+// @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);
+}
+export {
+  scanSource,
+  scanFiles,
+  scanFile,
+  SUPPORTED_EXTENSIONS
+};

package/package.json

@@ -1,8 +1,7 @@
 {
 	"name": "@yuu1111/comment-check",
-	"version": "1.0.0",
+	"version": "2.0.0",
 	"description": "Shared comment and suppression checker",
-	"license": "MIT",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/yuu1111/configs.git",
@@ -10,17 +9,24 @@
 	},
 	"type": "module",
 	"bin": {
-		"comment-check": "src/cli.ts"
+		"comment-check": "dist/cli.js"
 	},
 	"exports": {
-		".": "./src/scan.ts"
+		".": "./dist/scan.js"
 	},
 	"files": [
-		"src"
+		"README.ja.md",
+		"dist"
 	],
+	"scripts": {
+		"build": "bun build src/cli.ts src/scan.ts --target=bun --outdir=dist"
+	},
 	"keywords": [
 		"comment",
 		"lint",
 		"suppression"
-	]
+	],
+	"devDependencies": {
+		"@yuu1111/shared": "workspace:*"
+	}
 }

package/src/baseline.ts

@@ -1,81 +0,0 @@
-import type { Finding } from "./rules";
-
-export interface BaselineEntry {
-	rule: string;
-	file: string;
-	text: string;
-	count: number;
-}
-
-export interface BaselineFile {
-	version: 1;
-	entries: BaselineEntry[];
-}
-
-export interface BaselineComparison {
-	added: Finding[];
-	resolved: BaselineEntry[];
-}
-
-export function entryKey(entry: {
-	rule: string;
-	file: string;
-	text: string;
-}): string {
-	return [entry.rule, entry.file, entry.text].join("\u0000");
-}
-
-function compareEntries(left: BaselineEntry, right: BaselineEntry): number {
-	const leftKey = entryKey(left);
-	const rightKey = entryKey(right);
-	if (leftKey === rightKey) {
-		return 0;
-	}
-	return leftKey < rightKey ? -1 : 1;
-}
-
-export function createBaseline(findings: Finding[]): BaselineFile {
-	const entries = new Map<string, BaselineEntry>();
-	for (const finding of findings) {
-		const key = entryKey(finding);
-		const existing = entries.get(key);
-		if (existing) {
-			existing.count += 1;
-			continue;
-		}
-		entries.set(key, {
-			rule: finding.rule,
-			file: finding.file,
-			text: finding.text,
-			count: 1,
-		});
-	}
-	return { version: 1, entries: [...entries.values()].sort(compareEntries) };
-}
-
-export function compareWithBaseline(
-	findings: Finding[],
-	baseline: BaselineFile,
-): BaselineComparison {
-	const remaining = new Map<string, number>();
-	for (const entry of baseline.entries) {
-		const key = entryKey(entry);
-		remaining.set(key, (remaining.get(key) ?? 0) + entry.count);
-	}
-
-	const added: Finding[] = [];
-	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 };
-}

package/src/cli.ts

@@ -1,184 +0,0 @@
-#!/usr/bin/env bun
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import {
-	type BaselineEntry,
-	type BaselineFile,
-	compareWithBaseline,
-	createBaseline,
-} from "./baseline";
-import type { Finding } from "./rules";
-import { collectFiles, normalizePath, scanFiles } from "./scan";
-
-const DEFAULT_BASELINE = "comment-baseline.json";
-
-const RULE_MESSAGES: Record<string, string> = {
-	"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",
-};
-
-interface Options {
-	baselinePath: string;
-	ignores: string[];
-	json: boolean;
-	targets: string[];
-	update: boolean;
-}
-
-type JsonObject = Record<string, unknown>;
-
-function isJsonObject(value: unknown): value is JsonObject {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isBaselineEntry(value: unknown): value is BaselineEntry {
-	if (!isJsonObject(value)) {
-		return false;
-	}
-	return (
-		typeof value.rule === "string" &&
-		typeof value.file === "string" &&
-		typeof value.text === "string" &&
-		typeof value.count === "number"
-	);
-}
-
-function applyFlagOption(options: Options, argument: string): boolean {
-	if (argument === "--update-baseline") {
-		options.update = true;
-		return true;
-	}
-	if (argument === "--json") {
-		options.json = true;
-		return true;
-	}
-	return false;
-}
-
-function applyValueOption(
-	options: Options,
-	argument: string,
-	argv: string[],
-	index: number,
-): number | null {
-	if (argument === "--baseline") {
-		options.baselinePath = argv[index + 1] ?? DEFAULT_BASELINE;
-		return 1;
-	}
-	if (argument.startsWith("--baseline=")) {
-		options.baselinePath = argument.slice("--baseline=".length);
-		return 0;
-	}
-	if (argument === "--ignore") {
-		const value = argv[index + 1];
-		if (value !== undefined) {
-			options.ignores.push(normalizePath(value));
-		}
-		return 1;
-	}
-	if (argument.startsWith("--ignore=")) {
-		options.ignores.push(normalizePath(argument.slice("--ignore=".length)));
-		return 0;
-	}
-	return null;
-}
-
-function parseArguments(argv: string[]): Options {
-	const options: Options = {
-		baselinePath: DEFAULT_BASELINE,
-		ignores: [],
-		json: false,
-		targets: [],
-		update: false,
-	};
-	for (let index = 0; index < argv.length; index += 1) {
-		const argument = argv[index] ?? "";
-		const consumed = applyValueOption(options, argument, argv, index);
-		if (consumed !== null) {
-			index += consumed;
-			continue;
-		}
-		if (applyFlagOption(options, argument)) {
-			continue;
-		}
-		if (argument.startsWith("-")) {
-			throw new Error(`unknown option: ${argument}`);
-		}
-		options.targets.push(argument);
-	}
-	if (options.targets.length === 0) {
-		options.targets.push(".");
-	}
-	return options;
-}
-
-function readBaseline(path: string): BaselineFile {
-	if (!existsSync(path)) {
-		return { entries: [], version: 1 };
-	}
-	const value: unknown = JSON.parse(readFileSync(path, "utf8"));
-	if (
-		!isJsonObject(value) ||
-		!Array.isArray(value.entries) ||
-		!value.entries.every(isBaselineEntry)
-	) {
-		throw new Error(`${path} is not a comment baseline`);
-	}
-	return { entries: value.entries, version: 1 };
-}
-
-function describeFinding(finding: Finding): string {
-	return `${finding.file}:${finding.line}:${finding.column} ${finding.rule} ${RULE_MESSAGES[finding.rule] ?? ""}`.trimEnd();
-}
-
-function main(argv: string[]): number {
-	if (argv.includes("--help")) {
-		console.log(
-			"Usage: comment-check [--baseline <path>] [--ignore <path>] [--update-baseline] [--json] [path...]",
-		);
-		return 0;
-	}
-	const options = parseArguments(argv);
-	const files = collectFiles(options.targets, process.cwd(), options.ignores);
-	const findings = scanFiles(files);
-
-	if (options.update) {
-		const baseline = createBaseline(findings);
-		writeFileSync(
-			options.baselinePath,
-			`${JSON.stringify(baseline, null, "\t")}\n`,
-		);
-		console.log(
-			`Recorded ${baseline.entries.length} entries in ${options.baselinePath}`,
-		);
-		return 0;
-	}
-
-	const baseline = readBaseline(options.baselinePath);
-	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;
-}
-
-try {
-	process.exit(main(process.argv.slice(2)));
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(2);
-}