sparkle-design-cli 2.5.0-beta.3 → 2.5.0-beta.5

package/lib/check.js

@@ -12,6 +12,13 @@ import {
   getCheckRules,
   getManualReviewReminders,
 } from './anti-pattern-rules.js';
+import {
+  ALLOW_TOKENS_RULE_ID,
+  isPathIgnored,
+  isTokenAllowed,
+  loadCheckConfig,
+  unknownIgnoreRuleIds,
+} from './check-config.js';
 import { loadAntiPatternPlugins } from './load-plugins.js';
 import { MATCH_HELPERS } from './plugin-helpers.js';
 import { REGEX, FONT_DOMAINS } from './constants.js';
@@ -28,6 +35,11 @@ const BUILTIN_RULES = getCheckRules(BUILTIN_ANTI_PATTERN_GROUPS);
 
 const SEVERITY_ORDER = [SEVERITY.ERROR, SEVERITY.WARNING, SEVERITY.INFO];
 
+// ルール定義を持たず check.js が直接出す finding の ID。除外設定で指定できる
+// ルール ID の判定に使う。
+// en: Finding IDs emitted directly by check.js rather than by a rule definition.
+const BUILTIN_REPORT_RULE_IDS = ['font-import-in-css', 'csp-font-block'];
+
 /**
  * finding の severity を既知の値に丸める。
  *
@@ -171,27 +183,43 @@ function formatSnippet(text) {
 }
 
 /**
- * ESLint 風の suppression コメントをサポートする。以下のいずれかが findings
- * と同じ行、または直前行にあれば該当 rule の finding は emit しない:
+ * ESLint 風の suppression コメントをサポートする。コメントの種類で効く行が
+ * 決まっており、取り違えると抑制されない（issue #101）:
  *
- *   // sparkle-disable-line <rule-id>
- *   // sparkle-disable-next-line <rule-id>
- *   {/* sparkle-disable-line <rule-id> *\/}   （JSX コメント）
+ *   // sparkle-disable-line <rule-id>        … finding と**同じ行**に置く
+ *   // sparkle-disable-next-line <rule-id>   … finding の**直前の行**に置く
+ *   {/* sparkle-disable-line <rule-id> *\/}   （JSX コメント。効く行は同上）
  *
  * ユーザーがどうしても character-* に移行できない typography（token に
- * 存在しないサイズなど）や、特定 file だけ例外扱いしたい場合の escape
- * hatch として用意する。ルール ID は複数カンマ区切り可（例:
+ * 存在しないサイズなど）を例外扱いしたい場合の escape hatch として用意する。
+ * ファイル単位の除外は `sparkle-disable-file`（`getFileSuppressedRules`）か、
+ * 設定ファイルの `check.ignore` を使う。
+ * ルール ID は複数カンマ区切り可（例:
  * `sparkle-disable-line tailwind-typography, card-padding-override`）。
  *
- * en: ESLint-style suppression comments so specific findings can be opted
- * out when character-* / Sparkle tokens don't map cleanly (e.g. sub-token
- * font sizes). Same-line or previous-line comment is honored.
+ * en: ESLint-style suppression comments. `disable-line` applies to its own
+ * line only; `disable-next-line` applies to the following line only.
  */
 const SUPPRESS_LINE =
   /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
 const SUPPRESS_NEXT_LINE =
   /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-next-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
 
+/**
+ * ファイル単位の suppression（issue #102）。ファイル内のどこに書いても、
+ * そのファイル全体で指定ルールの finding を出さない。行コメントと同じく
+ * ルール ID は必須（ID 無しの全面除外はコメントでは許さず、設定ファイルの
+ * `check.ignore` に寄せる。ファイルを開いても気付きにくい全面除外を散らさないため）。
+ *
+ *   /* sparkle-disable-file shadcn-token *\/
+ *   // sparkle-disable-file shadcn-token, tailwind-typography
+ *
+ * en: File-level suppression. Rule IDs are required, as with line comments;
+ * blanket "all rules" ignores belong in `check.ignore` in sparkle.config.json.
+ */
+const SUPPRESS_FILE =
+  /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-file\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
+
 function extractSuppressedRules(source, regex) {
   if (!source) return null;
   const m = source.match(regex);
@@ -204,6 +232,19 @@ function extractSuppressedRules(source, regex) {
   );
 }
 
+/**
+ * `sparkle-disable-file` で除外されたルール ID の集合を返す（複数書けば和集合）。
+ * en: Union of rule IDs named by every `sparkle-disable-file` comment in the file.
+ */
+function getFileSuppressedRules(content) {
+  const ids = new Set();
+  if (!content || !content.includes('sparkle-disable-file')) return ids;
+  for (const line of content.split(/\r?\n/)) {
+    for (const id of extractSuppressedRules(line, SUPPRESS_FILE) ?? []) ids.add(id);
+  }
+  return ids;
+}
+
 function isSuppressed(ruleId, contentLines, lineNumber) {
   // lineNumber は 1-origin
   // en: 1-based line numbers from getLineNumber.
@@ -219,11 +260,15 @@ function isSuppressed(ruleId, contentLines, lineNumber) {
 function collectFindings(filePath, content, rules = BUILTIN_RULES, options = {}) {
   const fileKind = options.fileKind ?? RULE_TARGET.SOURCE;
   const onRuleError = options.onRuleError;
+  const onSuppress = options.onSuppress;
   const findings = [];
   const contentLines = content.split(/\r?\n/);
   const pushFinding = (rule, index, snippet, recommendationOverride) => {
     const line = getLineNumber(content, index ?? 0);
-    if (isSuppressed(rule.id, contentLines, line)) return;
+    if (isSuppressed(rule.id, contentLines, line)) {
+      onSuppress?.(rule.id);
+      return;
+    }
     findings.push({
       filePath,
       id: rule.id,
@@ -405,9 +450,27 @@ function collectNextjsCspFindings(cwd) {
   return findings;
 }
 
+/**
+ * `allowTokens` に書いたクラスを、`shadcn-token` が検出するか。typo の検出に使う。
+ * `shadcn-token` はクラス単体の正規表現なので、単体の文字列で判定して誤りが無い。
+ * en: Whether shadcn-token detects this class — used to flag allowTokens typos.
+ * The rule is a plain class regex, so probing the bare string is exact.
+ */
+function isDetectedByAllowTokensRule(token, rules) {
+  // プラグインが同じ ID のルールを足すこともあるので、該当するものをすべて使う
+  // en: Plugins may add rules under the same ID, so probe with all of them.
+  const targetRules = rules.filter((candidate) => candidate.id === ALLOW_TOKENS_RULE_ID);
+  if (targetRules.length === 0) return true;
+  return collectFindings('allow-tokens-probe', token, targetRules, {
+    onRuleError: () => {},
+  }).some((finding) => finding.snippet === token);
+}
+
 function createCheckReport(targets = [], options = {}) {
   const rules = options.rules ?? BUILTIN_RULES;
   const baseReminders = options.baseReminders ?? BUILTIN_MANUAL_REVIEW_REMINDERS;
+  const ignoreEntries = options.ignore ?? [];
+  const allowTokenEntries = options.allowTokens ?? [];
   const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
   const textFiles = new Set();
   const cssFiles = new Set();
@@ -428,6 +491,23 @@ function createCheckReport(targets = [], options = {}) {
     fileContents.set(filePath, fs.readFileSync(filePath, 'utf8'));
   }
 
+  // CSS も先に読み、ファイル単位コメントを走査前に集めておく。ルールが落ちたときに
+  // 「そのファイル × ルールは除外済みか」を判定するため。
+  // en: Read CSS up front and gather file-level suppressions before scanning, so
+  // a rule crash on an already-ignored file/rule pair can be disregarded.
+  const cssContents = new Map();
+  for (const filePath of cssFiles) {
+    cssContents.set(filePath, fs.readFileSync(filePath, 'utf8'));
+  }
+  const fileSuppressions = new Map();
+  for (const [filePath, content] of [...fileContents, ...cssContents]) {
+    const ids = getFileSuppressedRules(content);
+    if (ids.size > 0) fileSuppressions.set(toRelativeReportPath(filePath), ids);
+  }
+  const isIgnoredFor = (relativePath, ruleId) =>
+    Boolean(fileSuppressions.get(relativePath)?.has(ruleId)) ||
+    isPathIgnored(ignoreEntries, relativePath, ruleId);
+
   // 落ちたルールは rule ID 単位で 1 回だけ warn する。catch が (rule × file) 単位
   // なので、素直に warn すると 500 ファイルのリポジトリで同じ行が 500 回出て
   // 本当の findings がスクロールバックから押し出される。
@@ -435,6 +515,11 @@ function createCheckReport(targets = [], options = {}) {
   // every file would bury the real findings.
   const skippedRuleMap = new Map();
   const onRuleError = ({ ruleId, filePath, message }) => {
+    // 除外済みのファイル × ルールで落ちても「未検査」にはしない。結果を出さない
+    // 箇所のせいで --strict / stop-hook が失敗するのは利用者の意図に反する。
+    // en: A crash on an ignored file/rule pair is not "unchecked" — its result
+    // would be hidden anyway, so it must not fail --strict / stop-hook.
+    if (isIgnoredFor(toRelativeReportPath(filePath), ruleId)) return;
     const existing = skippedRuleMap.get(ruleId);
     if (existing) {
       existing.fileCount += 1;
@@ -451,9 +536,20 @@ function createCheckReport(targets = [], options = {}) {
     );
   };
 
+  // 除外した件数を仕組みごとに数える。除外しすぎに気付けるよう summary に載せる（#102）。
+  // en: Count suppressed findings per mechanism so over-ignoring stays visible.
+  const ignored = { line: 0, file: 0, config: 0, token: 0 };
+  const onSuppress = () => {
+    ignored.line += 1;
+  };
+
   const findings = [...fileContents.entries()]
     .flatMap(([filePath, content]) =>
-      collectFindings(filePath, content, rules, { fileKind: RULE_TARGET.SOURCE, onRuleError })
+      collectFindings(filePath, content, rules, {
+        fileKind: RULE_TARGET.SOURCE,
+        onRuleError,
+        onSuppress,
+      })
     )
     .map((finding) => ({
       ...finding,
@@ -465,12 +561,12 @@ function createCheckReport(targets = [], options = {}) {
   // 対象は `targets` に css を含むルールだけなので、既存ルールの挙動は変わらない。
   // en: Scan CSS too — variable references live there and fail silently. Only
   // rules that opted into `css` run, so existing rules are unaffected.
-  for (const filePath of cssFiles) {
-    const content = fs.readFileSync(filePath, 'utf8');
+  for (const [filePath, content] of cssContents) {
     findings.push(
       ...collectFindings(filePath, content, rules, {
         fileKind: RULE_TARGET.CSS,
         onRuleError,
+        onSuppress,
       }).map((finding) => ({ ...finding, filePath: toRelativeReportPath(finding.filePath) }))
     );
   }
@@ -479,14 +575,99 @@ function createCheckReport(targets = [], options = {}) {
   findings.push(...fontFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
 
   const cspFindings = collectNextjsCspFindings(process.cwd());
+  // CSP の finding は走査対象外の `next.config.*` に対して出るので、そのファイルの
+  // `sparkle-disable-file` もここで読んでおく。
+  // en: CSP findings point at `next.config.*`, usually outside the scanned
+  // targets, so read its file-level suppressions too.
+  for (const finding of cspFindings) {
+    const relativePath = toRelativeReportPath(finding.filePath);
+    if (fileSuppressions.has(relativePath)) continue;
+    let content;
+    try {
+      content = fs.readFileSync(finding.filePath, 'utf8');
+    } catch {
+      // 直前に CSP 検査で読めたファイル。読めなくなっていたら除外なしとして扱う。
+      // en: Just read by the CSP check; if it vanished, treat as no suppression.
+      continue;
+    }
+    const ids = getFileSuppressedRules(content);
+    if (ids.size > 0) fileSuppressions.set(relativePath, ids);
+  }
   findings.push(...cspFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
 
+  // ファイル単位のコメントと設定ファイルの除外は、組み込み検査（フォント @import /
+  // CSP）の finding も含めてここでまとめてかける。
+  // en: Apply file comments and config ignores to every finding, built-ins included.
+  const visibleFindings = findings.filter((finding) => {
+    if (fileSuppressions.get(finding.filePath)?.has(finding.id)) {
+      ignored.file += 1;
+      return false;
+    }
+    if (isPathIgnored(ignoreEntries, finding.filePath, finding.id)) {
+      ignored.config += 1;
+      return false;
+    }
+    // check.allowTokens（#104）: shadcn-token の指摘のうち、プロジェクトが意図して使うと
+    // 宣言したクラスと完全一致するものは出さない。宣言していないものは従来どおり検出する。
+    // en: Hide shadcn-token findings whose class the project declared intentional;
+    // undeclared ones are still reported.
+    if (
+      finding.id === ALLOW_TOKENS_RULE_ID &&
+      isTokenAllowed(allowTokenEntries, finding.filePath, finding.snippet)
+    ) {
+      ignored.token += 1;
+      return false;
+    }
+    return true;
+  });
+
+  // 存在しないルール ID を除外指定していたら警告する。typo やプラグイン未導入だと
+  // 「除外したつもりが何も外していない」まま気付けない。
+  // en: Warn about ignore rule IDs no active rule has (typos, missing plugins).
+  const knownRuleIds = [...rules.map((rule) => rule.id), ...BUILTIN_REPORT_RULE_IDS];
+  const ignoreWarnings = [
+    ...unknownIgnoreRuleIds(ignoreEntries, knownRuleIds).map((ruleId) => ({
+      source: 'config',
+      ruleId,
+    })),
+  ];
+  const knownSet = new Set(knownRuleIds);
+  for (const [filePath, ids] of [...fileSuppressions].sort(([a], [b]) => a.localeCompare(b))) {
+    for (const ruleId of ids) {
+      if (!knownSet.has(ruleId)) ignoreWarnings.push({ source: 'file', ruleId, filePath });
+    }
+  }
+  // allowTokens に書いたクラスが shadcn-token の検出対象でなければ警告する
+  // （typo や、対象外のクラスを書いて「許可したつもり」になるのを防ぐ）。
+  // en: Warn about allowTokens shadcn-token never detects (typos, other classes).
+  const declaredTokens = [...new Set(allowTokenEntries.flatMap((entry) => entry.tokens))].sort();
+  for (const token of declaredTokens) {
+    if (!isDetectedByAllowTokensRule(token, rules)) {
+      ignoreWarnings.push({ source: 'allowTokens', ruleId: ALLOW_TOKENS_RULE_ID, token });
+    }
+  }
+  for (const warning of ignoreWarnings) {
+    if (warning.source === 'allowTokens') {
+      console.warn(
+        `⚠️  sparkle-design-cli: 設定ファイルの check.allowTokens に指定された "${warning.token}" は ${ALLOW_TOKENS_RULE_ID} の検出対象ではありません（typo か、variant・/50・! を付けたまま書いている可能性があります。クラス名だけで書いてください。allowTokens は ${ALLOW_TOKENS_RULE_ID} の指摘にだけ効きます）`
+      );
+      continue;
+    }
+    const where =
+      warning.source === 'config'
+        ? '設定ファイルの check.ignore'
+        : `${warning.filePath} の sparkle-disable-file`;
+    console.warn(
+      `⚠️  sparkle-design-cli: ${where} に指定されたルール "${warning.ruleId}" は有効なルールにありません（typo か、プラグインが入っていない可能性があります）`
+    );
+  }
+
   // severity の高い順 → ファイル → 行 → ID。移行期は warning が大量に出るため、
   // ファイル順だけで並べると本当に直すべき error が warning に埋もれる。
   // 既存ルールはすべて error なので、error 同士の相対順は従来どおり保たれる。
   // en: Sort by severity first so migration warnings can't bury errors. All
   // pre-existing rules are errors, so their relative order is unchanged.
-  findings.sort((left, right) => {
+  visibleFindings.sort((left, right) => {
     const severityComparison = severityRank(left.severity) - severityRank(right.severity);
     if (severityComparison !== 0) return severityComparison;
     const fileComparison = left.filePath.localeCompare(right.filePath);
@@ -507,7 +688,14 @@ function createCheckReport(targets = [], options = {}) {
   return {
     targets: resolvedTargets,
     checkedFiles,
-    findings,
+    findings: visibleFindings,
+    // 除外（抑制コメント・設定ファイル）で出さなかった件数。除外しすぎの目安（#102）。
+    // en: Findings hidden by suppression comments or config ignores.
+    ignored: {
+      total: ignored.line + ignored.file + ignored.config + ignored.token,
+      ...ignored,
+    },
+    ignoreWarnings,
     // 「ルールが落ちて検査されなかった」ことをレポートに載せる。stderr の warn
     // だけだと JSON を読む CI / AI には見えず、findings 0 件・passed true を
     // 「クリーン」と誤読する。
@@ -518,15 +706,32 @@ function createCheckReport(targets = [], options = {}) {
   };
 }
 
+function describeIgnored(ignored) {
+  if (!ignored || ignored.total === 0) return null;
+  const parts = [
+    ['行コメント', ignored.line],
+    ['sparkle-disable-file', ignored.file],
+    ['check.ignore', ignored.config],
+    ['check.allowTokens', ignored.token],
+  ]
+    .filter(([, count]) => count > 0)
+    .map(([label, count]) => `${label} ${count}`);
+  return `${ignored.total} 件を除外しました（${parts.join(' / ')}）`;
+}
+
 function printTextReport(report, options = {}) {
+  const ignoredLine = describeIgnored(report.ignored);
   if (report.findings.length === 0) {
     console.log('sparkle-design-cli check: no findings');
+    if (ignoredLine) console.log(`  ${ignoredLine}`);
   } else {
     const counts = countBySeverity(report.findings);
     const breakdown = SEVERITY_ORDER.filter((severity) => counts[severity] > 0)
       .map((severity) => `${counts[severity]} ${severity}`)
       .join(', ');
-    console.log(`sparkle-design-cli check: ${report.findings.length} finding(s) (${breakdown})\n`);
+    console.log(`sparkle-design-cli check: ${report.findings.length} finding(s) (${breakdown})`);
+    if (ignoredLine) console.log(`  ${ignoredLine}`);
+    console.log('');
 
     for (const finding of report.findings) {
       const severity = coerceSeverity(finding.severity);
@@ -629,6 +834,9 @@ function printJsonReport(report, options = {}) {
           // en: Rules that crashed and therefore did not run. Non-zero means the
           // report is incomplete, so --strict fails even with zero findings.
           skippedRuleCount: skippedCount,
+          // 抑制コメントや check.ignore で出さなかった件数（内訳はトップレベルの ignored）。
+          // en: Findings hidden by suppression; breakdown in top-level ignored.
+          ignoredFindingCount: report.ignored?.total ?? 0,
           reminderCount: reminders.length,
           // AI 向けの attention フラグ。reminder が 1 件でもあれば true になり、
           // AI は最終 response で各 reminder ID を echo する必要がある。
@@ -671,7 +879,8 @@ export async function runCheck(targets = [], options = {}) {
     ...pluginReminders,
   ]);
 
-  const report = createCheckReport(targets, { rules, baseReminders });
+  const { ignore, allowTokens } = loadCheckConfig(options.configPath ?? null);
+  const report = createCheckReport(targets, { rules, baseReminders, ignore, allowTokens });
 
   if (options.format === 'json') {
     printJsonReport(report, options);
@@ -696,9 +905,12 @@ export {
   BUILTIN_RULES as RULES,
   blockingFindings,
   coerceSeverity,
+  collectFiles,
   collectFindings,
   countBySeverity,
   createCheckReport,
+  getFileSuppressedRules,
   hasBlockingIssues,
+  isSuppressed,
   BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
 };