@yuu1111/comment-check 2.0.0 → 2.2.0

package/README.ja.md

@@ -24,26 +24,35 @@ src/queue.ts:18:2 undocumented-directive TypeScript directive needs a descriptio
 Checked 42 files: 1 new, 0 resolved, 3 baselined
 ```
 
+日本語の文末の `。` も止めるProjectはopt-inのruleを指定する
+
+```bash
+comment-check --enable japanese-period .
+```
+
+複数行のcommentを直前の行へ続けず空行で区切るProjectは、もう一つのopt-inのruleを指定する
+
+```bash
+comment-check --enable cramped-comment .
+```
+
 ## Rules
 
 | Rule | 検出対象 |
 |------|---------|
 | `broad-suppression` | `biome-ignore-all`、`@ts-nocheck`、ruleを書いていない `eslint-disable` |
+| `cramped-comment` | 直前の行へ空行なしで続く複数行comment（opt-in） |
 | `undocumented-directive` | 説明の無い `@ts-ignore` と `@ts-expect-error` |
 | `placeholder-comment` | `TODO`、`FIXME`、`XXX`、`HACK` |
 | `separator-comment` | 記号だけで作った装飾comment |
+| `japanese-period` | 日本語の文を終える `。` を含むcomment（opt-in） |
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
 | `--baseline <path>` | 読み書きするbaseline file（既定は `comment-baseline.json`） |
+| `--enable <rule>` | opt-in ruleを実行する 複数指定できる 未知の名前は設定error |
 | `--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

@@ -25,30 +25,37 @@ src/queue.ts:18:2 undocumented-directive TypeScript directive needs a descriptio
 Checked 42 files: 1 new, 0 resolved, 3 baselined
 ```
 
+A project that also keeps Japanese sentences free of a trailing `。` names the
+opt-in rule:
+
+```bash
+comment-check --enable japanese-period .
+```
+
+A project that keeps a blank line before every multi-line comment names the
+other opt-in rule:
+
+```bash
+comment-check --enable cramped-comment .
+```
+
 ## Rules
 
 | Rule | Detects |
 |------|---------|
 | `broad-suppression` | `biome-ignore-all`, `@ts-nocheck`, and rule-less `eslint-disable` |
+| `cramped-comment` | a multi-line block comment written directly under the previous line (opt-in) |
 | `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 |
+| `japanese-period` | a Japanese sentence in a comment that ends with `。` (opt-in) |
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
 | `--baseline <path>` | Baseline file to read or write (default `comment-baseline.json`) |
+| `--enable <rule>` | Run an opt-in rule, repeatable; an unknown name is a configuration error |
 | `--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/dist/cli.js

@@ -286,9 +286,44 @@ function extractComments(source) {
 }
 
 // src/rules.ts
+var OPT_IN_RULE_IDS = ["cramped-comment", "japanese-period"];
 var PLACEHOLDER_PATTERN = /\b(TODO|FIXME|XXX|HACK)\b/;
 var SEPARATOR_PATTERN = /^[-=*_#~+./\\|]{4,}$/;
 var DIRECTIVE_PATTERN = /^@ts-(?:ignore|expect-error)\b([\s\S]*)$/;
+var JAPANESE_PERIOD = "\u3002";
+var BLOCK_OPENER = /(?:=>|[{(,[])\s*$/;
+var COMMENT_CONTINUATION = /^(?:\/\/|\*|\/\*)/;
+function parseEnabledRules(values) {
+  const enabled = [];
+  for (const value of values) {
+    if (!OPT_IN_RULE_IDS.includes(value)) {
+      throw new Error(`unknown rule: ${value}`);
+    }
+    const rule = value;
+    if (!enabled.includes(rule)) {
+      enabled.push(rule);
+    }
+  }
+  return enabled;
+}
+function findJapanesePeriod(text) {
+  return text.indexOf(JAPANESE_PERIOD);
+}
+function isCrampedComment(source, start) {
+  const lineStart = source.lastIndexOf(`
+`, start - 1) + 1;
+  if (lineStart === 0 || source.slice(lineStart, start).trim() !== "") {
+    return false;
+  }
+  const previousEnd = lineStart - 1;
+  const previousStart = source.lastIndexOf(`
+`, previousEnd - 1) + 1;
+  const previous = source.slice(previousStart, previousEnd).trim();
+  if (previous === "" || previous.endsWith("*/")) {
+    return false;
+  }
+  return !(COMMENT_CONTINUATION.test(previous) || BLOCK_OPENER.test(previous));
+}
 function normalizeComment(body) {
   return body.split(`
 `).map((line) => line.replace(/^\s*\*+\s?/, "")).join(" ").replace(/\s+/g, " ").trim();
@@ -337,31 +372,57 @@ function positionAt(source, offset) {
   }
   return { line, column: offset - lineStart + 1 };
 }
-function scanSource(source, file) {
+function scanSource(source, file, enabled = []) {
   const findings = [];
   for (const comment of extractComments(source)) {
+    const text = normalizeComment(comment.text);
     const rule = classifyComment(comment.text);
-    if (rule === null) {
+    if (rule !== null) {
+      const position2 = positionAt(source, comment.start);
+      findings.push({
+        column: position2.column,
+        file,
+        line: position2.line,
+        rule,
+        text
+      });
+    }
+    if (enabled.includes("cramped-comment") && comment.kind === "block" && source.slice(comment.start, comment.end).includes(`
+`) && isCrampedComment(source, comment.start)) {
+      const position2 = positionAt(source, comment.start);
+      findings.push({
+        column: position2.column,
+        file,
+        line: position2.line,
+        rule: "cramped-comment",
+        text
+      });
+    }
+    if (!enabled.includes("japanese-period")) {
       continue;
     }
-    const position = positionAt(source, comment.start);
+    const offset = findJapanesePeriod(comment.text);
+    if (offset < 0) {
+      continue;
+    }
+    const position = positionAt(source, comment.start + 2 + offset);
     findings.push({
       column: position.column,
       file,
       line: position.line,
-      rule,
-      text: normalizeComment(comment.text)
+      rule: "japanese-period",
+      text
     });
   }
   return findings;
 }
-function scanFile(file, cwd = process.cwd()) {
-  return scanSource(readFileSync(file, "utf8"), normalizePath(relative2(cwd, file)));
+function scanFile(file, cwd = process.cwd(), enabled = []) {
+  return scanSource(readFileSync(file, "utf8"), normalizePath(relative2(cwd, file)), enabled);
 }
-function scanFiles(files, cwd = process.cwd()) {
+function scanFiles(files, cwd = process.cwd(), enabled = []) {
   const findings = [];
   for (const file of files) {
-    findings.push(...scanFile(file, cwd));
+    findings.push(...scanFile(file, cwd, enabled));
   }
   return findings.sort(compareFindings);
 }
@@ -531,18 +592,21 @@ function runCli(main) {
 var DEFAULT_BASELINE = "comment-baseline.json";
 var RULE_MESSAGES = {
   "broad-suppression": "file-wide suppression hides too much",
+  "cramped-comment": "a multi-line comment needs a blank line before it",
+  "japanese-period": "a Japanese sentence in a comment does not end with a period",
   "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...]";
+var USAGE = "Usage: comment-check [--baseline <path>] [--enable <rule>] [--ignore <path>] [--update-baseline] [--json] [path...]";
 function parseArguments(argv) {
   const parsed = parseArgv(argv, {
     flags: ["json", "update-baseline"],
-    values: ["baseline", "ignore"]
+    values: ["baseline", "enable", "ignore"]
   });
   return {
     baselinePath: parsed.values.get("baseline")?.at(-1) ?? DEFAULT_BASELINE,
+    enabled: parseEnabledRules(parsed.values.get("enable") ?? []),
     ignores: (parsed.values.get("ignore") ?? []).map(normalizePath),
     json: parsed.flags.has("json"),
     targets: parsed.targets.length > 0 ? parsed.targets : ["."],
@@ -564,7 +628,7 @@ function main(argv) {
     extensions: SUPPORTED_EXTENSIONS,
     ignores: options.ignores
   });
-  const findings = scanFiles(files);
+  const findings = scanFiles(files, process.cwd(), options.enabled);
   if (options.update) {
     const baseline2 = createBaseline(findings);
     writeBaseline(options.baselinePath, baseline2);
@@ -583,4 +647,10 @@ function main(argv) {
   }
   return comparison.added.length > 0 ? 1 : 0;
 }
-runCli(main);
+if (import.meta.main) {
+  runCli(main);
+}
+export {
+  parseArguments,
+  main
+};

package/dist/scan.js

@@ -284,9 +284,44 @@ function extractComments(source) {
 }
 
 // src/rules.ts
+var OPT_IN_RULE_IDS = ["cramped-comment", "japanese-period"];
 var PLACEHOLDER_PATTERN = /\b(TODO|FIXME|XXX|HACK)\b/;
 var SEPARATOR_PATTERN = /^[-=*_#~+./\\|]{4,}$/;
 var DIRECTIVE_PATTERN = /^@ts-(?:ignore|expect-error)\b([\s\S]*)$/;
+var JAPANESE_PERIOD = "\u3002";
+var BLOCK_OPENER = /(?:=>|[{(,[])\s*$/;
+var COMMENT_CONTINUATION = /^(?:\/\/|\*|\/\*)/;
+function parseEnabledRules(values) {
+  const enabled = [];
+  for (const value of values) {
+    if (!OPT_IN_RULE_IDS.includes(value)) {
+      throw new Error(`unknown rule: ${value}`);
+    }
+    const rule = value;
+    if (!enabled.includes(rule)) {
+      enabled.push(rule);
+    }
+  }
+  return enabled;
+}
+function findJapanesePeriod(text) {
+  return text.indexOf(JAPANESE_PERIOD);
+}
+function isCrampedComment(source, start) {
+  const lineStart = source.lastIndexOf(`
+`, start - 1) + 1;
+  if (lineStart === 0 || source.slice(lineStart, start).trim() !== "") {
+    return false;
+  }
+  const previousEnd = lineStart - 1;
+  const previousStart = source.lastIndexOf(`
+`, previousEnd - 1) + 1;
+  const previous = source.slice(previousStart, previousEnd).trim();
+  if (previous === "" || previous.endsWith("*/")) {
+    return false;
+  }
+  return !(COMMENT_CONTINUATION.test(previous) || BLOCK_OPENER.test(previous));
+}
 function normalizeComment(body) {
   return body.split(`
 `).map((line) => line.replace(/^\s*\*+\s?/, "")).join(" ").replace(/\s+/g, " ").trim();
@@ -335,31 +370,57 @@ function positionAt(source, offset) {
   }
   return { line, column: offset - lineStart + 1 };
 }
-function scanSource(source, file) {
+function scanSource(source, file, enabled = []) {
   const findings = [];
   for (const comment of extractComments(source)) {
+    const text = normalizeComment(comment.text);
     const rule = classifyComment(comment.text);
-    if (rule === null) {
+    if (rule !== null) {
+      const position2 = positionAt(source, comment.start);
+      findings.push({
+        column: position2.column,
+        file,
+        line: position2.line,
+        rule,
+        text
+      });
+    }
+    if (enabled.includes("cramped-comment") && comment.kind === "block" && source.slice(comment.start, comment.end).includes(`
+`) && isCrampedComment(source, comment.start)) {
+      const position2 = positionAt(source, comment.start);
+      findings.push({
+        column: position2.column,
+        file,
+        line: position2.line,
+        rule: "cramped-comment",
+        text
+      });
+    }
+    if (!enabled.includes("japanese-period")) {
+      continue;
+    }
+    const offset = findJapanesePeriod(comment.text);
+    if (offset < 0) {
       continue;
     }
-    const position = positionAt(source, comment.start);
+    const position = positionAt(source, comment.start + 2 + offset);
     findings.push({
       column: position.column,
       file,
       line: position.line,
-      rule,
-      text: normalizeComment(comment.text)
+      rule: "japanese-period",
+      text
     });
   }
   return findings;
 }
-function scanFile(file, cwd = process.cwd()) {
-  return scanSource(readFileSync(file, "utf8"), normalizePath(relative2(cwd, file)));
+function scanFile(file, cwd = process.cwd(), enabled = []) {
+  return scanSource(readFileSync(file, "utf8"), normalizePath(relative2(cwd, file)), enabled);
 }
-function scanFiles(files, cwd = process.cwd()) {
+function scanFiles(files, cwd = process.cwd(), enabled = []) {
   const findings = [];
   for (const file of files) {
-    findings.push(...scanFile(file, cwd));
+    findings.push(...scanFile(file, cwd, enabled));
   }
   return findings.sort(compareFindings);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yuu1111/comment-check",
-	"version": "2.0.0",
+	"version": "2.2.0",
 	"description": "Shared comment and suppression checker",
 	"repository": {
 		"type": "git",