@yuu1111/comment-check 0.0.0

package/README.md

@@ -0,0 +1,52 @@
+# @yuu1111/comment-check
+
+Small comment checker with a baseline, used to keep suppressions and placeholder
+comments from spreading.
+
+## Install
+
+```bash
+bun add -D @yuu1111/comment-check
+```
+
+## Usage
+
+Record the current findings once, then fail only when a new one appears:
+
+```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 | Detects |
+|------|---------|
+| `broad-suppression` | `biome-ignore-all`, `@ts-nocheck`, and rule-less `eslint-disable` |
+| `undocumented-directive` | `@ts-ignore` or `@ts-expect-error` without a description |
+| `placeholder-comment` | `TODO`, `FIXME`, `XXX`, `HACK` |
+| `separator-comment` | decorative comments made only of punctuation |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--baseline <path>` | Baseline file to read or write (default `comment-baseline.json`) |
+| `--ignore <path>` | Path to leave out, repeatable |
+| `--update-baseline` | Replace the baseline with the current findings |
+| `--json` | Print new and resolved findings as JSON |
+
+## Notes
+
+Generated directories and other paths that the project owns stay out of the
+check through `--ignore`, for example `--ignore src/generated`.
+
+The baseline keys on the rule, the file, and the comment text, so moving a line
+does not report the comment as new. Biome already requires a reason on
+`biome-ignore` and reports unused suppressions, so this checker only covers the
+comment trivia that Biome does not read.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@yuu1111/comment-check",
+  "version": "0.0.0",
+  "description": "Shared comment and suppression checker",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuu1111/configs.git",
+    "directory": "packages/comment-check"
+  },
+  "type": "module",
+  "bin": {
+    "comment-check": "src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/scan.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "comment",
+    "lint",
+    "suppression"
+  ]
+}

package/src/baseline.ts

@@ -0,0 +1,81 @@
+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

@@ -0,0 +1,184 @@
+#!/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);
+}

package/src/comments.ts

@@ -0,0 +1,241 @@
+export type CommentKind = "line" | "block";
+
+export interface CommentPiece {
+	kind: CommentKind;
+	text: string;
+	start: number;
+	end: number;
+}
+
+type Mode = "code" | "template" | "expression";
+
+interface ScanState {
+	braces: number[];
+	comments: CommentPiece[];
+	index: number;
+	modes: Mode[];
+}
+
+const REGEX_PRECEDING_CHARACTERS = new Set("(,=:[!&|?{};".split(""));
+const REGEX_PRECEDING_KEYWORDS = new Set([
+	"await",
+	"case",
+	"delete",
+	"do",
+	"else",
+	"in",
+	"instanceof",
+	"new",
+	"of",
+	"return",
+	"throw",
+	"typeof",
+	"void",
+	"yield",
+]);
+
+function isIdentifierCharacter(character: string): boolean {
+	return /[A-Za-z0-9_$]/.test(character);
+}
+
+function skipString(source: string, start: number, quote: string): number {
+	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 === "\n") {
+			return index;
+		}
+		index += 1;
+	}
+	return index;
+}
+
+function isRegexStart(source: string, index: number): boolean {
+	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: string, start: number): number {
+	let index = start + 1;
+	let inClass = false;
+	while (index < source.length) {
+		const character = source[index] ?? "";
+		if (character === "\\") {
+			index += 2;
+			continue;
+		}
+		if (character === "\n") {
+			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: ScanState): Mode {
+	return state.modes[state.modes.length - 1] ?? "code";
+}
+
+function stepComment(state: ScanState, source: string): boolean {
+	const character = source[state.index] ?? "";
+	const next = source[state.index + 1] ?? "";
+	if (character !== "/" || (next !== "/" && next !== "*")) {
+		return false;
+	}
+	if (next === "/") {
+		const newline = source.indexOf("\n", state.index);
+		const stop = newline === -1 ? source.length : newline;
+		state.comments.push({
+			end: stop,
+			kind: "line",
+			start: state.index,
+			text: source.slice(state.index + 2, stop),
+		});
+		state.index = stop;
+		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: ScanState, source: string): boolean {
+	const character = source[state.index] ?? "";
+	if (character !== "'" && character !== '"') {
+		return false;
+	}
+	state.index = skipString(source, state.index, character);
+	return true;
+}
+
+function stepTemplateStart(state: ScanState, source: string): boolean {
+	if (source[state.index] !== "`") {
+		return false;
+	}
+	state.modes.push("template");
+	state.index += 1;
+	return true;
+}
+
+function stepRegex(state: ScanState, source: string): boolean {
+	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: ScanState, source: string): void {
+	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: ScanState, source: string): void {
+	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: ScanState, source: string): void {
+	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);
+}
+
+export function extractComments(source: string): CommentPiece[] {
+	const shebang = source.startsWith("#!") ? source.indexOf("\n") : 0;
+	const state: ScanState = {
+		braces: [],
+		comments: [],
+		index: Math.max(0, shebang),
+		modes: ["code"],
+	};
+	while (state.index < source.length) {
+		step(state, source);
+	}
+	return state.comments;
+}

package/src/rules.ts

@@ -0,0 +1,55 @@
+export const RULE_IDS = [
+	"broad-suppression",
+	"undocumented-directive",
+	"placeholder-comment",
+	"separator-comment",
+] as const;
+
+export type RuleId = (typeof RULE_IDS)[number];
+
+export interface Finding {
+	rule: RuleId;
+	file: string;
+	line: number;
+	column: number;
+	text: string;
+}
+
+const PLACEHOLDER_PATTERN = /\b(TODO|FIXME|XXX|HACK)\b/;
+const SEPARATOR_PATTERN = /^[-=*_#~+./\\|]{4,}$/;
+const DIRECTIVE_PATTERN = /^@ts-(?:ignore|expect-error)\b([\s\S]*)$/;
+
+export function normalizeComment(body: string): string {
+	return body
+		.split("\n")
+		.map((line) => line.replace(/^\s*\*+\s?/, ""))
+		.join(" ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export function classifyComment(body: string): RuleId | null {
+	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:—-]+/, "") === ""
+			? "undocumented-directive"
+			: null;
+	}
+	if (PLACEHOLDER_PATTERN.test(text)) {
+		return "placeholder-comment";
+	}
+	if (SEPARATOR_PATTERN.test(text)) {
+		return "separator-comment";
+	}
+	return null;
+}

package/src/scan.ts

@@ -0,0 +1,140 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative, resolve } from "node:path";
+import { extractComments } from "./comments";
+import { classifyComment, type Finding, normalizeComment } from "./rules";
+
+const SUPPORTED_EXTENSIONS = new Set([
+	".cjs",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".mts",
+	".ts",
+	".tsx",
+]);
+const IGNORED_DIRECTORIES = new Set([
+	"build",
+	"coverage",
+	"dist",
+	"node_modules",
+	"out",
+	"vendor",
+]);
+
+export function normalizePath(path: string): string {
+	return path.split("\\").join("/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+
+function isIgnored(path: string, ignores: string[]): boolean {
+	return ignores.some(
+		(ignore) => path === ignore || path.startsWith(`${ignore}/`),
+	);
+}
+
+function positionAt(
+	source: string,
+	offset: number,
+): { line: number; column: number } {
+	let line = 1;
+	let lineStart = 0;
+	for (let index = 0; index < offset; index += 1) {
+		if (source[index] === "\n") {
+			line += 1;
+			lineStart = index + 1;
+		}
+	}
+	return { line, column: offset - lineStart + 1 };
+}
+
+function compareFindings(left: Finding, right: Finding): number {
+	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 walk(directory: string, files: Set<string>): void {
+	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, files);
+			}
+			continue;
+		}
+		if (entry.isFile() && SUPPORTED_EXTENSIONS.has(extname(entry.name))) {
+			files.add(path);
+		}
+	}
+}
+
+export function collectFiles(
+	targets: string[],
+	cwd = process.cwd(),
+	ignores: string[] = [],
+): string[] {
+	const files = new Set<string>();
+	for (const target of targets) {
+		const absolute = resolve(cwd, target);
+		let stats: ReturnType<typeof statSync>;
+		try {
+			stats = statSync(absolute);
+		} catch {
+			continue;
+		}
+		if (stats.isFile()) {
+			if (
+				SUPPORTED_EXTENSIONS.has(extname(absolute)) &&
+				!isIgnored(normalizePath(target), ignores)
+			) {
+				files.add(absolute);
+			}
+			continue;
+		}
+		walk(absolute, files);
+	}
+	return [...files]
+		.filter((file) => !isIgnored(normalizePath(relative(cwd, file)), ignores))
+		.sort();
+}
+
+export function scanSource(source: string, file: string): Finding[] {
+	const findings: Finding[] = [];
+	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;
+}
+
+export function scanFile(file: string, cwd = process.cwd()): Finding[] {
+	return scanSource(
+		readFileSync(file, "utf8"),
+		normalizePath(relative(cwd, file)),
+	);
+}
+
+export function scanFiles(files: string[], cwd = process.cwd()): Finding[] {
+	const findings: Finding[] = [];
+	for (const file of files) {
+		findings.push(...scanFile(file, cwd));
+	}
+	return findings.sort(compareFindings);
+}