sparkle-design-cli 2.4.1 → 2.5.0-beta.1

package/lib/check.js

@@ -2,8 +2,13 @@ import fs from 'fs';
 import path from 'path';
 
 import {
+  BLOCKING_SEVERITIES,
   BUILTIN_ANTI_PATTERN_GROUPS,
   BUILTIN_MANUAL_REVIEW_REMINDERS,
+  DEFAULT_RULE_TARGETS,
+  DEFAULT_SEVERITY,
+  RULE_TARGET,
+  SEVERITY,
   getCheckRules,
   getManualReviewReminders,
 } from './anti-pattern-rules.js';
@@ -19,6 +24,56 @@ const CSS_EXTENSIONS = new Set(['.css']);
 // en: Synchronous built-in snapshot for backward-compatible export below.
 const BUILTIN_RULES = getCheckRules(BUILTIN_ANTI_PATTERN_GROUPS);
 
+const SEVERITY_ORDER = [SEVERITY.ERROR, SEVERITY.WARNING, SEVERITY.INFO];
+
+/**
+ * finding の severity を既知の値に丸める。
+ *
+ * `getCheckRules` を通れば正規化済みだが、`collectFindings` / `createCheckReport`
+ * は public export なので rule を直接渡す経路がある。そこを素通しにすると
+ * 「並び順は error 扱いなのに exit code 判定では非 error」という**判定ごとに
+ * 結論が変わる**状態になり、件数の内訳も合わなくなる。読み出し側を 1 つの
+ * 関数に集約して、どの判定でも同じ値を見るようにする。
+ * en: Coerce to a known severity at every read site so ordering, counting and
+ * the exit-code decision can never disagree about the same finding.
+ */
+function coerceSeverity(severity) {
+  return SEVERITY_ORDER.includes(severity) ? severity : DEFAULT_SEVERITY;
+}
+
+function severityRank(severity) {
+  return SEVERITY_ORDER.indexOf(coerceSeverity(severity));
+}
+
+/**
+ * `--strict` / stop-hook が失敗として扱う findings。
+ * `warning` / `info` は報告のみで exit code を変えない（issue #74）。
+ * en: Only blocking-severity findings affect the exit code.
+ */
+function blockingFindings(findings) {
+  return findings.filter((finding) => BLOCKING_SEVERITIES.has(coerceSeverity(finding.severity)));
+}
+
+function countBySeverity(findings) {
+  const counts = Object.fromEntries(SEVERITY_ORDER.map((severity) => [severity, 0]));
+  for (const finding of findings) {
+    counts[coerceSeverity(finding.severity)] += 1;
+  }
+  return counts;
+}
+
+function ruleAppliesTo(rule, fileKind) {
+  return (rule.targets ?? DEFAULT_RULE_TARGETS).includes(fileKind);
+}
+
+// NOTE: トークンを定義している CSS（CLI の生成物など）を使用側と取り違えない
+// ための判定は、ここではなく `anti-pattern-rules.js` の `migrationMatcher` が
+// 内容ベースで行う（同じファイルが宣言している変数への参照は報告しない）。
+// ファイル名で除外していたときは `generate --scope`（`-o` 必須で出力名が任意）
+// の生成物が素通りしていた。
+// en: Definition-vs-usage is decided by content in migrationMatcher, not by
+// filename — `generate --scope` output has an arbitrary name.
+
 const SPARKLE_HEAD_JSX_PATTERN = /<SparkleHead\s*\/?\s*>/;
 // CSP key が「実際の設定 key として記述されている」コンテキストに絞る。
 // 以前は単純に `/content-security-policy|.../i` だったため、コメント行
@@ -140,23 +195,37 @@ function isSuppressed(ruleId, contentLines, lineNumber) {
   return false;
 }
 
-function collectFindings(filePath, content, rules = BUILTIN_RULES) {
+function collectFindings(filePath, content, rules = BUILTIN_RULES, options = {}) {
+  const fileKind = options.fileKind ?? RULE_TARGET.SOURCE;
+  const onRuleError = options.onRuleError;
   const findings = [];
   const contentLines = content.split(/\r?\n/);
-  const pushFinding = (rule, index, snippet) => {
+  const pushFinding = (rule, index, snippet, recommendationOverride) => {
     const line = getLineNumber(content, index ?? 0);
     if (isSuppressed(rule.id, contentLines, line)) return;
     findings.push({
       filePath,
       id: rule.id,
+      // severity は getCheckRules で正規化済み。プラグイン rule が
+      // getCheckRules を経由せず直接渡されるテスト経路のために既定値も持たせる。
+      // en: Normalized in getCheckRules; the fallback covers rules injected
+      // directly in tests without going through it.
+      severity: coerceSeverity(rule.severity),
       description: rule.description,
-      recommendation: rule.recommendation,
+      // 移行ルールのように「マッチ 1 件ごとに移行先が変わる」ものは
+      // rule.match が hit ごとの recommendation を返す。無ければルール既定を使う。
+      // en: Per-occurrence recommendation from rule.match wins over the
+      // rule-level default (migration targets differ per match).
+      recommendation: recommendationOverride ?? rule.recommendation,
       line,
       snippet,
     });
   };
 
   for (const rule of rules) {
+    // ルールごとに対象ファイル種別が違う（既定は source のみ）。
+    if (!ruleAppliesTo(rule, fileKind)) continue;
+
     // rule ごとに try/catch で隔離する。1 つのプラグイン rule の throw / malformed
     // RegExp で sparkle-design-cli check 全体が落ちるのを防ぐ。loadAntiPatternPlugins の
     // 「warn して skip」と同じ failure mode に揃える。
@@ -178,7 +247,7 @@ function collectFindings(filePath, content, rules = BUILTIN_RULES) {
           throw new TypeError(`rule.match must return an array, got ${typeof hits}`);
         }
         for (const hit of hits) {
-          pushFinding(rule, hit?.index ?? 0, formatSnippet(hit?.text ?? ''));
+          pushFinding(rule, hit?.index ?? 0, formatSnippet(hit?.text ?? ''), hit?.recommendation);
         }
         continue;
       }
@@ -193,9 +262,17 @@ function collectFindings(filePath, content, rules = BUILTIN_RULES) {
       }
     } catch (error) {
       const message = error?.message ?? String(error);
-      console.warn(
-        `⚠️  sparkle-design-cli: rule "${rule.id ?? '(unknown)'}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
-      );
+      // ルールが落ちた = そのルールについては「違反ゼロ」ではなく「検査していない」。
+      // 呼び出し側に記録させてレポートに載せる（無ければ従来どおり warn するだけ）。
+      // en: A crashed rule means "not checked", not "clean" — hand it to the
+      // caller so it can surface in the report instead of only on stderr.
+      if (typeof onRuleError === 'function') {
+        onRuleError({ ruleId: rule.id ?? '(unknown)', filePath, message });
+      } else {
+        console.warn(
+          `⚠️  sparkle-design-cli: rule "${rule.id ?? '(unknown)'}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
+        );
+      }
     }
   }
 
@@ -214,6 +291,7 @@ function collectFontImportFindings(cssFiles) {
       findings.push({
         filePath,
         id: 'font-import-in-css',
+        severity: SEVERITY.ERROR,
         description:
           'CSS にフォント @import が残っています。SparkleHead コンポーネントに移行してください。',
         recommendation:
@@ -293,6 +371,7 @@ function collectNextjsCspFindings(cwd) {
       findings.push({
         filePath: configPath,
         id: 'csp-font-block',
+        severity: SEVERITY.ERROR,
         description: `CSP ヘッダーが設定されていますが、${missing} が許可されていない可能性があります。`,
         recommendation: `style-src に ${FONT_DOMAINS.GOOGLEAPIS} を、font-src に ${FONT_DOMAINS.GSTATIC} を追加してください。`,
         line: 1,
@@ -318,7 +397,7 @@ function createCheckReport(targets = [], options = {}) {
     collectFiles(path.resolve(process.cwd(), target), textFiles, cssFiles, visited);
   }
 
-  const checkedFiles = [...textFiles]
+  const checkedFiles = [...textFiles, ...cssFiles]
     .map((filePath) => toRelativeReportPath(filePath))
     .sort((left, right) => left.localeCompare(right));
 
@@ -328,20 +407,67 @@ function createCheckReport(targets = [], options = {}) {
     fileContents.set(filePath, fs.readFileSync(filePath, 'utf8'));
   }
 
+  // 落ちたルールは rule ID 単位で 1 回だけ warn する。catch が (rule × file) 単位
+  // なので、素直に warn すると 500 ファイルのリポジトリで同じ行が 500 回出て
+  // 本当の findings がスクロールバックから押し出される。
+  // en: Deduplicate by rule ID — the catch is per (rule, file), so warning on
+  // every file would bury the real findings.
+  const skippedRuleMap = new Map();
+  const onRuleError = ({ ruleId, filePath, message }) => {
+    const existing = skippedRuleMap.get(ruleId);
+    if (existing) {
+      existing.fileCount += 1;
+      return;
+    }
+    skippedRuleMap.set(ruleId, {
+      ruleId,
+      message,
+      firstFile: toRelativeReportPath(filePath),
+      fileCount: 1,
+    });
+    console.warn(
+      `⚠️  sparkle-design-cli: rule "${ruleId}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
+    );
+  };
+
   const findings = [...fileContents.entries()]
-    .flatMap(([filePath, content]) => collectFindings(filePath, content, rules))
+    .flatMap(([filePath, content]) =>
+      collectFindings(filePath, content, rules, { fileKind: RULE_TARGET.SOURCE, onRuleError })
+    )
     .map((finding) => ({
       ...finding,
       filePath: toRelativeReportPath(finding.filePath),
     }));
 
+  // CSS も検査する。`--radius-halfModal` のような CSS 変数の直接参照は `.css` に
+  // こそ自然に書かれ、しかも消えてもビルドエラーにならず見た目だけ壊れる。
+  // 対象は `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');
+    findings.push(
+      ...collectFindings(filePath, content, rules, {
+        fileKind: RULE_TARGET.CSS,
+        onRuleError,
+      }).map((finding) => ({ ...finding, filePath: toRelativeReportPath(finding.filePath) }))
+    );
+  }
+
   const fontFindings = collectFontImportFindings(cssFiles);
   findings.push(...fontFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
 
   const cspFindings = collectNextjsCspFindings(process.cwd());
   findings.push(...cspFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
 
+  // 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) => {
+    const severityComparison = severityRank(left.severity) - severityRank(right.severity);
+    if (severityComparison !== 0) return severityComparison;
     const fileComparison = left.filePath.localeCompare(right.filePath);
     if (fileComparison !== 0) return fileComparison;
     if (left.line !== right.line) return left.line - right.line;
@@ -361,6 +487,12 @@ function createCheckReport(targets = [], options = {}) {
     targets: resolvedTargets,
     checkedFiles,
     findings,
+    // 「ルールが落ちて検査されなかった」ことをレポートに載せる。stderr の warn
+    // だけだと JSON を読む CI / AI には見えず、findings 0 件・passed true を
+    // 「クリーン」と誤読する。
+    // en: Surface skipped rules in the report — a stderr-only warning is
+    // invisible to JSON consumers, who would read 0 findings as "clean".
+    skippedRules: [...skippedRuleMap.values()],
     manualReviewReminders,
   };
 }
@@ -369,14 +501,29 @@ function printTextReport(report, options = {}) {
   if (report.findings.length === 0) {
     console.log('sparkle-design-cli check: no findings');
   } else {
-    console.log(`sparkle-design-cli check: ${report.findings.length} finding(s)\n`);
+    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`);
 
     for (const finding of report.findings) {
-      console.log(`${finding.filePath}:${finding.line} [${finding.id}] ${finding.description}`);
+      const severity = coerceSeverity(finding.severity);
+      console.log(
+        `${finding.filePath}:${finding.line} [${severity}] [${finding.id}] ${finding.description}`
+      );
       console.log(`  Recommendation: ${finding.recommendation}`);
       console.log(`  Snippet: ${finding.snippet}`);
       console.log('');
     }
+
+    if (counts[SEVERITY.WARNING] > 0 || counts[SEVERITY.INFO] > 0) {
+      console.log(
+        'Note: warning / info は報告のみで exit code には影響しません（--strict でも失敗しません）。' +
+          ' / warning and info findings are informational and never affect the exit code.'
+      );
+      console.log('');
+    }
   }
 
   const reminders = report.manualReviewReminders ?? [];
@@ -406,14 +553,43 @@ function printTextReport(report, options = {}) {
     console.log('=========================================================================');
   }
 
-  if (options.strict && report.findings.length > 0) {
+  const skipped = report.skippedRules ?? [];
+  if (skipped.length > 0) {
+    console.error('');
+    console.error(
+      `⚠️  ${skipped.length} 件のルールが実行に失敗して検査されていません（違反ゼロではなく「未検査」です）:`
+    );
+    for (const entry of skipped) {
+      console.error(
+        `   - [${entry.ruleId}] ${entry.message}（${entry.firstFile} を含む計 ${entry.fileCount} ファイル）`
+      );
+    }
+    console.error('');
+  }
+
+  if (options.strict && hasBlockingIssues(report)) {
     console.error('sparkle-design-cli check: failed because --strict was specified');
   }
 }
 
+/**
+ * `--strict` / stop-hook を失敗させるべきか。
+ *
+ * blocking severity の findings に加えて、**実行に失敗したルールがある場合も失敗**
+ * とする。ルールが落ちた状態は「違反ゼロ」ではなく「検査していない」であり、
+ * ここを通してしまうと検査が死んでいることに誰も気付けない。
+ * en: Also fail when a rule crashed — that state is "not checked", not "clean".
+ */
+function hasBlockingIssues(report) {
+  return blockingFindings(report.findings).length > 0 || (report.skippedRules ?? []).length > 0;
+}
+
 function printJsonReport(report, options = {}) {
   const strictMode = Boolean(options.strict);
-  const passed = !(strictMode && report.findings.length > 0);
+  const counts = countBySeverity(report.findings);
+  const blockingCount = blockingFindings(report.findings).length;
+  const skippedCount = (report.skippedRules ?? []).length;
+  const passed = !(strictMode && hasBlockingIssues(report));
   const reminders = report.manualReviewReminders ?? [];
 
   console.log(
@@ -423,6 +599,15 @@ function printJsonReport(report, options = {}) {
           targetCount: report.targets.length,
           checkedFileCount: report.checkedFiles.length,
           findingCount: report.findings.length,
+          // severity 別内訳。`blockingFindingCount` だけが exit code に効く。
+          // en: Only blockingFindingCount affects the exit code.
+          severityCounts: counts,
+          blockingFindingCount: blockingCount,
+          // 実行に失敗して検査されなかったルールの数。0 でないなら findings が
+          // 0 件でも「クリーン」とは言えない（--strict は失敗する）。
+          // 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,
           reminderCount: reminders.length,
           // AI 向けの attention フラグ。reminder が 1 件でもあれば true になり、
           // AI は最終 response で各 reminder ID を echo する必要がある。
@@ -447,7 +632,13 @@ function printJsonReport(report, options = {}) {
   );
 }
 
-export async function checkProject(targets = [], options = {}) {
+/**
+ * `check` 本体。レポートを出力し、レポートそのものと「失敗させるべきか」を返す。
+ * stop-hook のように findings の内訳まで見たい呼び出し側のために report を返す。
+ * en: Runs the check, prints the report, and returns both the report and the
+ * blocking decision (stop-hook needs the breakdown, not just the boolean).
+ */
+export async function runCheck(targets = [], options = {}) {
   // Plugins are discovered from the consumer project's package.json deps. Errors are
   // already warn-and-skip inside loadAntiPatternPlugins, so we just consume the result.
   // en: Auto-discover plugins from cwd; loader handles its own failure reporting.
@@ -467,12 +658,26 @@ export async function checkProject(targets = [], options = {}) {
     printTextReport(report, options);
   }
 
-  return report.findings.length > 0;
+  return { report, blocked: hasBlockingIssues(report) };
+}
+
+export async function checkProject(targets = [], options = {}) {
+  const { blocked } = await runCheck(targets, options);
+  // 戻り値は「exit code を 1 にすべきか」。severity 導入前は findings が
+  // 1 件でもあれば true だったが、既存ルールはすべて error なので既存プロジェクト
+  // での挙動は変わらない。beta 中の移行 warning で CI や stop-hook を止めない。
+  // en: Returns "should this fail?" — unchanged for existing projects since all
+  // pre-existing rules are errors; beta migration warnings never block.
+  return blocked;
 }
 
 export {
   BUILTIN_RULES as RULES,
+  blockingFindings,
+  coerceSeverity,
   collectFindings,
+  countBySeverity,
   createCheckReport,
+  hasBlockingIssues,
   BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
 };

package/lib/plugin-api.js

@@ -27,13 +27,29 @@
  *     featureSection?: string,            // markdown emitted into the published anti-pattern doc (esa)
  *     jsdocTargets?: JSDocTarget[],       // optional — JSDoc injection targets in the plugin's own source
  *     check?: {
+ *       severity?: 'error' | 'warning' | 'info',
+ *                                         // defaults to 'error'. Only 'error' affects the exit code
+ *                                         // of `check --strict` / the stop hook; 'warning' / 'info'
+ *                                         // are reported but never fail. An unknown value warns and
+ *                                         // falls back to 'error'.
+ *       targets?: Array<'source' | 'css'>,
+ *                                         // which file kinds the rule runs on.
+ *                                         // defaults to ['source'] (.js/.jsx/.ts/.tsx).
+ *                                         // Add 'css' for rules that match CSS variable
+ *                                         // references or @apply utilities. Note: the built-in
+ *                                         // migration rules additionally skip references to
+ *                                         // variables the same file declares (definition side),
+ *                                         // which is how generated stylesheets are excluded —
+ *                                         // by content, not by filename.
  *       description: string,              // shown in `check` findings
  *       recommendation: string,           // shown in `check` findings
  *       pattern?: RegExp,                 // simple regex check. MUST have the global (`g`) flag.
  *                                         // mutually exclusive with `match`.
- *       match?: (content: string, helpers: MatchHelpers) => Array<{ index: number, text: string }>,
+ *       match?: (content: string, helpers: MatchHelpers) => Array<{ index: number, text: string, recommendation?: string }>,
  *                                         // opt-in API for complex matching (2-pass, AST, etc.).
  *                                         // `helpers` (2nd arg) is injected by the CLI — see ## MatchHelpers.
+ *                                         // A per-hit `recommendation` overrides `check.recommendation`,
+ *                                         // for rules whose fix differs per occurrence (e.g. token migration).
  *     },
  *   }
  *

package/lib/rules-report.js

@@ -0,0 +1,181 @@
+/**
+ * `sparkle-design-cli rules` の実装。
+ *
+ * ## なぜコマンドなのか
+ *
+ * ルール一覧はこれまで README / `check --help` / internal の setup-guide /
+ * コンポーネントの JSDoc / スキルの features.md と 6 箇所に写しが散らばっていて、
+ * 実際に `check --help` は組み込み 18 件のうち 16 件しか載せておらず、しかも
+ * `check` のルールではない項目を 2 件含んだまま腐っていた。
+ *
+ * それ以上に本質的なのは、**静的なドキュメントには「有効なルール」を書けない**
+ * ということ。プラグインはコンシューマの package.json から自動発見されるので、
+ * 実際に効いているルールはプロジェクトごとに違う。組み込み 18 件を列挙した
+ * ドキュメントは、プラグインを入れた利用者にとって最初から不正確になる。
+ *
+ * en: The rule list used to be copied into six places and had already rotted.
+ * More fundamentally, static docs cannot state which rules are *active* — plugins
+ * are discovered from the consumer's package.json, so the effective set differs
+ * per project. This command is the only place that can answer that.
+ */
+
+import {
+  BUILTIN_ANTI_PATTERN_GROUPS,
+  RULE_TARGET,
+  SEVERITY,
+  getCheckRules,
+} from './anti-pattern-rules.js';
+import { loadAntiPatternPlugins } from './load-plugins.js';
+
+/** 表示順。`check` のレポートと同じ「重いものが先」に揃える。 */
+const SEVERITY_ORDER = [SEVERITY.ERROR, SEVERITY.WARNING, SEVERITY.INFO];
+
+const SEVERITY_NOTE = {
+  [SEVERITY.ERROR]: '例外なし。--strict / stop-hook を失敗させる',
+  [SEVERITY.WARNING]: '原則ダメだが理由があれば例外可。exit code は変えない',
+  [SEVERITY.INFO]: '参考。従わなくてもよい選択肢',
+};
+
+/**
+ * 組み込み + プラグインのルールを集める。
+ *
+ * プラグイン由来かどうかを `source` に持たせる。利用者が「なぜこのルールが
+ * 出るのか」を追えるようにするためで、これが分からないと組み込みの不具合と
+ * プラグインの不具合を切り分けられない。
+ */
+export async function collectActiveRules(options = {}) {
+  // cwd を受けるのはテストのためだけではない。プラグインは**そのディレクトリの**
+  // package.json から発見されるので、どこを見たかで結果が変わる。既定は
+  // loadAntiPatternPlugins 側の既定（process.cwd()）に委ねる。
+  // en: The discovered set depends on which directory is inspected.
+  const { groups: pluginGroups, discovered } = await loadAntiPatternPlugins(
+    options.cwd ? { cwd: options.cwd } : undefined
+  );
+
+  // 出所は**結合前**に決める。結合後に ID で引き当てる方式だと、プラグインが
+  // 組み込みと同じ ID を名乗ったときに両方が builtin として表示され、
+  // 「見慣れないルールが出た」ときの切り分けができなくなる。ID の重複は
+  // getCheckRules も check 側も弾かない（両方のルールが実際に動く）ので、
+  // ここで潰さず、出所を正しく付けたうえで衝突として見せる。
+  // en: Derive the origin before merging. Looking it up by id afterwards would
+  // label a plugin rule that reuses a built-in id as `builtin`, defeating the
+  // whole point of the field. Duplicate ids are not rejected anywhere — both
+  // rules really run — so surface the clash instead of hiding it.
+  const shape = (source) => (rule) => ({
+    id: rule.id,
+    severity: rule.severity,
+    description: rule.description,
+    targets: rule.targets,
+    source,
+  });
+
+  const rules = [
+    ...getCheckRules(BUILTIN_ANTI_PATTERN_GROUPS).map(shape('builtin')),
+    ...getCheckRules(pluginGroups).map(shape('plugin')),
+  ];
+
+  return { rules, plugins: discovered };
+}
+
+function severityRank(severity) {
+  const index = SEVERITY_ORDER.indexOf(severity);
+  return index === -1 ? SEVERITY_ORDER.length : index;
+}
+
+function sortForDisplay(rules) {
+  return [...rules].sort(
+    (a, b) => severityRank(a.severity) - severityRank(b.severity) || a.id.localeCompare(b.id)
+  );
+}
+
+/** `--format json` の出力。CI や AI から読む前提なので件数の内訳も添える。 */
+export function renderRulesJson({ rules, plugins }) {
+  const counts = Object.fromEntries(
+    SEVERITY_ORDER.map((severity) => [
+      severity,
+      rules.filter((r) => r.severity === severity).length,
+    ])
+  );
+  return JSON.stringify(
+    {
+      summary: {
+        ruleCount: rules.length,
+        duplicateIds: [
+          ...new Set(
+            rules
+              .filter((rule, i) => rules.findIndex((r) => r.id === rule.id) !== i)
+              .map((r) => r.id)
+          ),
+        ],
+        severityCounts: counts,
+        builtinCount: rules.filter((r) => r.source === 'builtin').length,
+        pluginCount: rules.filter((r) => r.source === 'plugin').length,
+      },
+      rules: sortForDisplay(rules),
+      plugins: plugins.map((record) => ({
+        packageName: record.packageName,
+        status: record.status,
+        error: record.error ?? null,
+        ruleIds: record.groupIds ?? [],
+      })),
+    },
+    null,
+    2
+  );
+}
+
+/** 既定のテキスト出力。 */
+export function renderRulesText({ rules, plugins }) {
+  const lines = [];
+  const sorted = sortForDisplay(rules);
+
+  lines.push(`有効なルール: ${sorted.length} 件`);
+
+  for (const severity of SEVERITY_ORDER) {
+    const group = sorted.filter((rule) => rule.severity === severity);
+    if (group.length === 0) continue;
+    lines.push('', `[${severity}] ${group.length} 件 — ${SEVERITY_NOTE[severity]}`);
+    for (const rule of group) {
+      // `.css` も見るルールは既定と違うので明示する。どのファイルが検査対象か
+      // 分からないと「なぜ検出されないのか」を利用者が追えない。
+      const css = rule.targets?.includes(RULE_TARGET.CSS) ? ' (.css も検査)' : '';
+      const from = rule.source === 'plugin' ? ' [plugin]' : '';
+      lines.push(`  ${rule.id}${from}${css}`);
+      lines.push(`    ${rule.description}`);
+    }
+  }
+
+  const clashes = [
+    ...new Set(
+      rules.filter((rule, i) => rules.findIndex((r) => r.id === rule.id) !== i).map((r) => r.id)
+    ),
+  ];
+  if (clashes.length > 0) {
+    lines.push('');
+    lines.push(`⚠️  組み込みと同じ ID を名乗るプラグインルールがあります: ${clashes.join(', ')}`);
+    lines.push(
+      '    どちらも実行されます。指摘の出所が分からなくなるので、プラグイン側の ID を変えてください。'
+    );
+  }
+
+  lines.push('');
+  if (plugins.length === 0) {
+    lines.push('プラグイン: なし（組み込みルールのみ）');
+  } else {
+    lines.push('プラグイン:');
+    for (const record of plugins) {
+      const status = record.status === 'loaded' ? 'ok' : `error: ${record.error}`;
+      lines.push(`  - ${record.packageName} (${status})`);
+    }
+  }
+  lines.push('');
+  lines.push('個別ルールの背景と対処は docs/anti-patterns.md を参照してください。');
+  lines.push('抑制するには `sparkle-disable-next-line <rule-id>` を使います。');
+
+  return lines.join('\n');
+}
+
+export async function runRules(options = {}) {
+  const collected = await collectActiveRules(options);
+  console.log(options.format === 'json' ? renderRulesJson(collected) : renderRulesText(collected));
+}