sparkle-design-cli 2.0.8 → 2.2.0

package/README.md

@@ -167,6 +167,112 @@ sparkle-design-cli check --help
 
 AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
+#### アンチパターン検知の拡張（プラグイン）
+
+他のコンポーネントライブラリ（社内拡張など）に固有のアンチパターン検知を、`sparkle-design-cli` 本体に変更を加えず追加できる拡張機構があります。
+
+##### 仕組み
+
+プラグインを提供するパッケージは、自身の `package.json` に検知ルールのエントリを宣言します:
+
+```json
+{
+  "name": "@your-org/your-design-extensions",
+  "sparkleCli": {
+    "antiPatterns": "./anti-patterns/index.js"
+  }
+}
+```
+
+エントリファイルは `defineAntiPatternPlugin` を使ってプラグインを default export します:
+
+```js
+import { defineAntiPatternPlugin } from 'sparkle-design-cli/plugin';
+
+export default defineAntiPatternPlugin({
+  groups: [
+    {
+      id: 'your-org-foocard-nesting',
+      check: {
+        description: 'FooCard を別の FooCard でラップしないでください。',
+        recommendation: '入れ子表示が必要なら FooStack を使ってください。',
+        pattern: /<FooCard[^>]*>[\s\S]*?<FooCard/g,
+      },
+    },
+  ],
+  manualReviewReminders: [
+    {
+      id: 'your-org-foocard-color',
+      message: 'FooCard の color token が brand に揃っているか確認してください。',
+    },
+  ],
+});
+```
+
+##### 複雑な検出（`match` とヘルパー）
+
+単純な正規表現では安全に書けない検出（accessible name の有無、prop の組み合わせ、JSX 式を意識した走査など）には、`check.pattern` の代わりに `check.match` を使います。`match` は `(content, helpers)` で呼ばれ、第 2 引数の `helpers` に JSX パースヘルパーが **CLI から注入** されます。各パッケージがパース処理を再実装して同じ false-positive / negative を踏むのを防ぐ仕組みです。
+
+```js
+// sparkle-design-cli を import しない（plain object を default export）
+export default {
+  groups: [
+    {
+      id: 'your-org-avatar-accessible-name',
+      check: {
+        description: 'Avatar に accessible name がありません。',
+        recommendation: 'aria-label か alt を指定してください。',
+        // helpers = { matchOpeningTags, hasProp, isMultipleTypeProp, findOpeningTagEnd }
+        match: (content, { matchOpeningTags, hasProp }) =>
+          matchOpeningTags(
+            content,
+            'Avatar',
+            (props) =>
+              !hasProp(props, 'src') &&
+              !hasProp(props, 'aria-label') &&
+              !hasProp(props, 'aria-labelledby')
+          ),
+      },
+    },
+  ],
+};
+```
+
+注入されるヘルパー（`check.match` の第 2 引数）:
+
+| ヘルパー                                        | 用途                                                                                 |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `matchOpeningTags(content, tagName, predicate)` | `<Tag ...>` / `<Tag ... />` を走査し predicate が真のものを `{ index, text }` で返す |
+| `hasProp(propsBlock, propName)`                 | prop が指定されているかを厳密判定（`aria-*` / `data-*` を誤検出しない）              |
+| `isMultipleTypeProp(propsBlock)`                | `type` が静的に `"multiple"` か判定（動的式は `false`）                              |
+| `findOpeningTagEnd(content, startIdx)`          | 低レベル: 開きタグの閉じ `>` のオフセット（文字列 / JSX 式を考慮）。無ければ `-1`    |
+
+> 💡 `match` を使うプラグインは（上の `pattern` 例の `defineAntiPatternPlugin` import と違い）`sparkle-design-cli` を **import せず** plain object として default export してください。`helpers` はランタイムで CLI が注入するため import は不要で、生 JS のまま配布され npx 経由で実行される consumer 環境でも確実に解決されます。`pattern` と `match` は排他で、どちらか一方のみ指定します。
+
+##### 自動 discovery
+
+`sparkle-design-cli check` 実行時、CLI は consumer プロジェクトの `package.json` の `dependencies` / `devDependencies` / `peerDependencies` / `optionalDependencies` を走査し、`sparkleCli.antiPatterns` を宣言しているパッケージを発見次第ロードしてビルトインのルールにマージします。
+
+- プラグインパッケージが install されていなければ何も起きません
+- ロードや評価で失敗したプラグインは warn を出してスキップし、残りのルールで check は継続されます
+- ルール ID はビルトイン・他プラグインと名前空間を共有するため、`your-org-` のようなプレフィックスを付けて衝突を避けてください
+
+> ⚠️ **信頼境界**: プラグインのエントリファイルは `import()` で **任意の JavaScript を実行** します。これは Node.js の通常のパッケージ依存と同じ性質ですが、`sparkle-design-cli check` 実行時に走るコードが増えるという点で意識しておく必要があります。プラグインは信頼できる org / 著者のパッケージのみインストールしてください。
+
+##### 契約仕様の確認
+
+最新の契約仕様は CLI から直接出力できます:
+
+```bash
+# 契約 shape のドキュメントを出力
+npx --yes sparkle-design-cli plugin-spec
+
+# 現在のプロジェクトで discover されたプラグインを一覧
+npx --yes sparkle-design-cli plugin-spec --list
+```
+
+完全な型定義は `node_modules/sparkle-design-cli/lib/plugin-api.js` の JSDoc を参照してください。
+
 ### setup: プロジェクトのフルセットアップ
 
 `sparkle-design-cli setup` は、Sparkle Design の導入に必要な作業をまとめて行います：

package/bin/sparkle-design.js

@@ -4,8 +4,10 @@ import { generateCSS } from '../lib/generate-css.js';
 import { checkProject } from '../lib/check.js';
 import { setupAssistant } from '../lib/setup.js';
 import { runStopHook } from '../lib/stop-hook.js';
+import { PLUGIN_SPEC_MARKDOWN } from '../lib/plugin-api.js';
+import { loadAntiPatternPlugins } from '../lib/load-plugins.js';
 
-const SUBCOMMANDS = new Set(['generate', 'check', 'setup', 'stop-hook']);
+const SUBCOMMANDS = new Set(['generate', 'check', 'setup', 'stop-hook', 'plugin-spec']);
 
 function requireOptionValue(args, index, flags) {
   const value = args[index + 1];
@@ -136,10 +138,11 @@ Sparkle Design CLI
   sparkle-design-cli <command> [options]
 
 Commands:
-  generate   sparkle.config.json から CSS を生成
-  check      Sparkle Design のアンチパターンを検査
-  setup      Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
-  stop-hook  AI assistant の Stop hook 用 internal subcommand（findings 検出時に exit 2 で 1 度だけ停止をブロック / 再発火は自動回避）
+  generate     sparkle.config.json から CSS を生成
+  check        Sparkle Design のアンチパターンを検査
+  setup        Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
+  stop-hook    AI assistant の Stop hook 用 internal subcommand（findings 検出時に exit 2 で 1 度だけ停止をブロック / 再発火は自動回避）
+  plugin-spec  アンチパターン拡張プラグインの契約仕様を出力（--list で導入済みプラグインを表示）
 
 Generate:
   sparkle-design-cli generate
@@ -153,6 +156,10 @@ Check:
   sparkle-design-cli check src --format json
   sparkle-design-cli check src/components src/features
 
+Plugin spec:
+  sparkle-design-cli plugin-spec           # アンチパターン拡張プラグインの契約仕様を出力
+  sparkle-design-cli plugin-spec --list    # 現在のプロジェクトで発見されたプラグインを表示
+
 Setup:
   sparkle-design-cli setup                                        # フルセットアップ（推奨・新規導入時）
   sparkle-design-cli setup --assistant claude                     # Claude 向けガードも同時にセットアップ
@@ -250,7 +257,31 @@ generate で生成されるファイル:
 `);
 }
 
-function main() {
+async function runPluginSpec(args) {
+  // `--list` prints the discovered plugins; default prints the contract markdown so authors
+  // can `npx sparkle-design-cli plugin-spec > PLUGIN.md` to seed their docs.
+  // en: With --list, summarize what was discovered in the cwd; otherwise print the spec.
+  if (args.includes('--list')) {
+    const { discovered } = await loadAntiPatternPlugins();
+    if (discovered.length === 0) {
+      console.log('No anti-pattern plugins discovered in the current project.');
+      return;
+    }
+    for (const record of discovered) {
+      const status = record.status === 'loaded' ? 'ok' : `error: ${record.error}`;
+      console.log(`- ${record.packageName} (${status})`);
+      console.log(`    entry: ${record.entry}`);
+      console.log(`    resolved: ${record.resolvedFile}`);
+      if (record.groupIds && record.groupIds.length > 0) {
+        console.log(`    rules: ${record.groupIds.join(', ')}`);
+      }
+    }
+    return;
+  }
+  console.log(PLUGIN_SPEC_MARKDOWN);
+}
+
+async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
@@ -282,7 +313,7 @@ function main() {
         process.exit(0);
       }
 
-      const hasFindings = checkProject(options.targets, {
+      const hasFindings = await checkProject(options.targets, {
         strict: options.strict,
         format: options.format,
       });
@@ -310,10 +341,15 @@ function main() {
       // en: Internal subcommand invoked by agent stop hooks. The single positional
       // arg is the lint target path determined at setup time.
       const target = args[1];
-      const exitCode = runStopHook(target);
+      const exitCode = await runStopHook(target);
       process.exit(exitCode);
     }
 
+    if (command === 'plugin-spec') {
+      await runPluginSpec(args.slice(1));
+      return;
+    }
+
     // 未知のコマンド: エラー終了ではなく note + help 表示にする（typo 時の迷子を防ぐ）
     // en: Unknown command: show a short note + help instead of throwing
     console.warn(

package/lib/anti-pattern-rules.js

@@ -23,7 +23,7 @@ function renderJSDocSection(section) {
   return output.map((line) => (line ? ` * ${line}` : ' *')).join('\n');
 }
 
-const MANUAL_REVIEW_REMINDERS = [
+const BUILTIN_MANUAL_REVIEW_REMINDERS = [
   {
     id: 'badge-tag-semantics',
     message:
@@ -46,7 +46,7 @@ const MANUAL_REVIEW_REMINDERS = [
   },
 ];
 
-const ANTI_PATTERN_GROUPS = [
+const BUILTIN_ANTI_PATTERN_GROUPS = [
   {
     id: 'card-description',
     featureSection: lines([
@@ -1200,51 +1200,62 @@ const ANTI_PATTERN_GROUPS = [
   },
 ];
 
-function getCheckRules() {
-  const order = [
-    'dialog-form',
-    'dialog-button-wrap',
-    'button-icon-only',
-    'material-symbols-direct',
-    'shadcn-token',
-    'tailwind-typography',
-    'card-title-typography',
-    'card-control-non-button',
-    'card-padding-override',
-    'aschild-with-icon-props',
-    'disabled-vs-is-disabled',
-    'button-prefixicon-jsx',
-    'icon-children-text',
-  ];
+// Built-in groups always come before plugin-supplied groups in this priority order.
+// Plugin-supplied IDs that aren't in this list fall to the end (stable insertion order).
+// en: Determines `check` finding emission order so the most-important built-in rules surface first.
+const BUILTIN_CHECK_ORDER = [
+  'dialog-form',
+  'dialog-button-wrap',
+  'button-icon-only',
+  'material-symbols-direct',
+  'shadcn-token',
+  'tailwind-typography',
+  'card-title-typography',
+  'card-control-non-button',
+  'card-padding-override',
+  'aschild-with-icon-props',
+  'disabled-vs-is-disabled',
+  'button-prefixicon-jsx',
+  'icon-children-text',
+];
 
-  return ANTI_PATTERN_GROUPS.filter((group) => group.check)
+function getCheckRules(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
+  return groups
+    .filter((group) => group.check)
     .map((group) => ({
       id: group.id,
       ...group.check,
     }))
     .sort((left, right) => {
-      const leftIndex = order.indexOf(left.id);
-      const rightIndex = order.indexOf(right.id);
+      const leftIndex = BUILTIN_CHECK_ORDER.indexOf(left.id);
+      const rightIndex = BUILTIN_CHECK_ORDER.indexOf(right.id);
       const normalizedLeftIndex = leftIndex === -1 ? Number.MAX_SAFE_INTEGER : leftIndex;
       const normalizedRightIndex = rightIndex === -1 ? Number.MAX_SAFE_INTEGER : rightIndex;
       return normalizedLeftIndex - normalizedRightIndex;
     });
 }
 
-function getAllJSDocTargets() {
-  return ANTI_PATTERN_GROUPS.flatMap((group) => group.jsdocTargets);
+function getAllJSDocTargets(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
+  return groups.flatMap((group) => group.jsdocTargets ?? []);
 }
 
-function renderFeatureSections() {
-  return ANTI_PATTERN_GROUPS.map((group) => group.featureSection).join('\n\n');
+function renderFeatureSections(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
+  return groups
+    .map((group) => group.featureSection)
+    .filter(Boolean)
+    .join('\n\n');
 }
 
-function getManualReviewReminders() {
-  return MANUAL_REVIEW_REMINDERS;
+function getManualReviewReminders(reminders = BUILTIN_MANUAL_REVIEW_REMINDERS) {
+  return reminders;
 }
 
 export {
-  ANTI_PATTERN_GROUPS,
+  BUILTIN_ANTI_PATTERN_GROUPS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS,
+  // Backward-compatible aliases — keep until external callers (sync-anti-pattern-docs, tests) migrate.
+  BUILTIN_ANTI_PATTERN_GROUPS as ANTI_PATTERN_GROUPS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
   COMMON_INTRO,
   getAllJSDocTargets,
   getCheckRules,

package/lib/check.js

@@ -1,14 +1,23 @@
 import fs from 'fs';
 import path from 'path';
 
-import { getCheckRules, getManualReviewReminders } from './anti-pattern-rules.js';
+import {
+  BUILTIN_ANTI_PATTERN_GROUPS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS,
+  getCheckRules,
+  getManualReviewReminders,
+} from './anti-pattern-rules.js';
+import { loadAntiPatternPlugins } from './load-plugins.js';
+import { MATCH_HELPERS } from './plugin-helpers.js';
 import { REGEX, FONT_DOMAINS } from './constants.js';
 
 const DEFAULT_TARGET = 'src';
 const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
 const CSS_EXTENSIONS = new Set(['.css']);
-const RULES = getCheckRules();
-const BASE_MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
+
+// Built-ins resolved at module load so test code that imports { RULES } directly still works.
+// en: Synchronous built-in snapshot for backward-compatible export below.
+const BUILTIN_RULES = getCheckRules(BUILTIN_ANTI_PATTERN_GROUPS);
 
 const SPARKLE_HEAD_JSX_PATTERN = /<SparkleHead\s*\/?\s*>/;
 // CSP key が「実際の設定 key として記述されている」コンテキストに絞る。
@@ -102,7 +111,8 @@ function formatSnippet(text) {
  * out when character-* / Sparkle tokens don't map cleanly (e.g. sub-token
  * font sizes). Same-line or previous-line comment is honored.
  */
-const SUPPRESS_LINE = /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
+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*(?:\*\/\}?|$)/;
 
@@ -130,7 +140,7 @@ function isSuppressed(ruleId, contentLines, lineNumber) {
   return false;
 }
 
-function collectFindings(filePath, content) {
+function collectFindings(filePath, content, rules = BUILTIN_RULES) {
   const findings = [];
   const contentLines = content.split(/\r?\n/);
   const pushFinding = (rule, index, snippet) => {
@@ -146,18 +156,46 @@ function collectFindings(filePath, content) {
     });
   };
 
-  for (const rule of RULES) {
-    if (typeof rule.match === 'function') {
-      // rule.match(content) -> Array<{ index: number, text: string }>
-      // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
-      // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
-      for (const hit of rule.match(content)) {
-        pushFinding(rule, hit.index ?? 0, formatSnippet(hit.text ?? ''));
+  for (const rule of rules) {
+    // rule ごとに try/catch で隔離する。1 つのプラグイン rule の throw / malformed
+    // RegExp で sparkle-design-cli check 全体が落ちるのを防ぐ。loadAntiPatternPlugins の
+    // 「warn して skip」と同じ failure mode に揃える。
+    // en: Isolate each rule. A broken plugin rule (throw / non-global regex / wrong
+    // type) must not crash the whole check pipeline.
+    try {
+      if (typeof rule.match === 'function') {
+        // rule.match(content, helpers) -> Array<{ index: number, text: string }>
+        // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
+        // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
+        // 第 2 引数 helpers (MATCH_HELPERS) で JSX パースヘルパー（matchOpeningTags /
+        // hasProp / findOpeningTagEnd / isMultipleTypeProp）を注入し、各プラグインが
+        // 同じパース実装を再実装して同じ false-positive/negative を踏むのを防ぐ。
+        // 第 2 引数を無視する既存の match(content) も後方互換でそのまま動く。
+        // en: helpers (2nd arg) injects shared JSX parsing utilities so plugins don't
+        // re-derive the regex edge cases. Existing match(content) stays compatible.
+        const hits = rule.match(content, MATCH_HELPERS);
+        if (!Array.isArray(hits)) {
+          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 ?? ''));
+        }
+        continue;
       }
-      continue;
-    }
-    for (const match of content.matchAll(rule.pattern)) {
-      pushFinding(rule, match.index ?? 0, formatMatch(match));
+      if (!(rule.pattern instanceof RegExp)) {
+        throw new TypeError('rule.pattern must be a RegExp (or define rule.match instead)');
+      }
+      if (!rule.pattern.global) {
+        throw new TypeError('rule.pattern must include the global flag (e.g. /foo/g)');
+      }
+      for (const match of content.matchAll(rule.pattern)) {
+        pushFinding(rule, match.index ?? 0, formatMatch(match));
+      }
+    } catch (error) {
+      const message = error?.message ?? String(error);
+      console.warn(
+        `⚠️  sparkle-design-cli: rule "${rule.id ?? '(unknown)'}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
+      );
     }
   }
 
@@ -267,7 +305,9 @@ function collectNextjsCspFindings(cwd) {
   return findings;
 }
 
-function createCheckReport(targets = []) {
+function createCheckReport(targets = [], options = {}) {
+  const rules = options.rules ?? BUILTIN_RULES;
+  const baseReminders = options.baseReminders ?? BUILTIN_MANUAL_REVIEW_REMINDERS;
   const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
   const textFiles = new Set();
   const cssFiles = new Set();
@@ -289,7 +329,7 @@ function createCheckReport(targets = []) {
   }
 
   const findings = [...fileContents.entries()]
-    .flatMap(([filePath, content]) => collectFindings(filePath, content))
+    .flatMap(([filePath, content]) => collectFindings(filePath, content, rules))
     .map((finding) => ({
       ...finding,
       filePath: toRelativeReportPath(finding.filePath),
@@ -308,7 +348,7 @@ function createCheckReport(targets = []) {
     return left.id.localeCompare(right.id);
   });
 
-  const manualReviewReminders = [...BASE_MANUAL_REVIEW_REMINDERS];
+  const manualReviewReminders = [...baseReminders];
   if (!hasSparkleHeadUsage(fileContents)) {
     manualReviewReminders.push({
       id: 'sparkle-head-missing',
@@ -352,15 +392,9 @@ function printTextReport(report, options = {}) {
     // exit code — reminders are judgment calls, not hard failures.
     console.log('');
     console.log('=== Manual review reminders (must acknowledge each ID in your response) ===');
-    console.log(
-      'These are judgment calls the linter cannot detect. For every item below,'
-    );
-    console.log(
-      'explicitly state the reminder ID in your reply together with whether the'
-    );
-    console.log(
-      'current code already satisfies it, or what change is needed. Silence = skipped.'
-    );
+    console.log('These are judgment calls the linter cannot detect. For every item below,');
+    console.log('explicitly state the reminder ID in your reply together with whether the');
+    console.log('current code already satisfies it, or what change is needed. Silence = skipped.');
     console.log('');
     for (const reminder of reminders) {
       console.log(`- [${reminder.id}] ${reminder.message}`);
@@ -413,8 +447,19 @@ function printJsonReport(report, options = {}) {
   );
 }
 
-export function checkProject(targets = [], options = {}) {
-  const report = createCheckReport(targets);
+export async function checkProject(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.
+  const { groups: pluginGroups, reminders: pluginReminders } = await loadAntiPatternPlugins();
+  const mergedGroups = [...BUILTIN_ANTI_PATTERN_GROUPS, ...pluginGroups];
+  const rules = getCheckRules(mergedGroups);
+  const baseReminders = getManualReviewReminders([
+    ...BUILTIN_MANUAL_REVIEW_REMINDERS,
+    ...pluginReminders,
+  ]);
+
+  const report = createCheckReport(targets, { rules, baseReminders });
 
   if (options.format === 'json') {
     printJsonReport(report, options);
@@ -426,8 +471,8 @@ export function checkProject(targets = [], options = {}) {
 }
 
 export {
-  RULES,
+  BUILTIN_RULES as RULES,
   collectFindings,
   createCheckReport,
-  BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
 };

package/lib/load-plugins.js

@@ -0,0 +1,136 @@
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+
+import {
+  PLUGIN_PACKAGE_FIELD,
+  PLUGIN_ANTI_PATTERNS_KEY,
+  validatePluginShape,
+} from './plugin-api.js';
+
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function collectDependencyNames(consumerPkg) {
+  const names = new Set();
+  for (const field of DEP_FIELDS) {
+    const block = consumerPkg[field];
+    if (block && typeof block === 'object') {
+      for (const name of Object.keys(block)) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+}
+
+function resolvePluginPackageJson(depName, cwd) {
+  // cwd を基点に dep の package.json を解決する。tsup / pkg-roll で生成される strict な
+  // `exports` フィールドのみのパッケージは subpath `./package.json` が export されておらず
+  // require.resolve が `ERR_PACKAGE_PATH_NOT_EXPORTED` を投げる。その場合は node_modules
+  // 配下の `package.json` を fs で直接読みに行く fallback を取る（pnpm の symlink は OS 透過）。
+  // en: Primary resolve via Node's resolver; if the plugin package's `exports` does not list
+  // `./package.json`, fall back to a direct fs read so plugins are not silently skipped.
+  const requireFromCwd = createRequire(path.join(cwd, 'package.json'));
+  try {
+    return requireFromCwd.resolve(`${depName}/package.json`);
+  } catch (error) {
+    if (error?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+      const fallback = path.join(cwd, 'node_modules', ...depName.split('/'), 'package.json');
+      if (fs.existsSync(fallback)) {
+        return fallback;
+      }
+    }
+    return null;
+  }
+}
+
+function extractPluginEntry(pkg) {
+  const block = pkg?.[PLUGIN_PACKAGE_FIELD];
+  if (!block || typeof block !== 'object') return null;
+  const entry = block[PLUGIN_ANTI_PATTERNS_KEY];
+  return typeof entry === 'string' && entry.length > 0 ? entry : null;
+}
+
+/**
+ * Discover and load anti-pattern plugins from the consumer's package.json deps.
+ *
+ * Returns an object of the shape:
+ *   {
+ *     groups: AntiPatternGroup[],
+ *     reminders: ManualReviewReminder[],
+ *     discovered: Array<{
+ *       packageName: string,
+ *       entry: string,              // path declared in package.json (relative)
+ *       resolvedFile: string,       // absolute resolved file path
+ *       status: 'loaded' | 'error',
+ *       groupIds?: string[],        // populated when status === 'loaded'
+ *       error?: string,
+ *     }>,
+ *   }
+ *
+ * The function never throws — broken or missing plugins are reported in `discovered`
+ * and surfaced to stderr as warnings so the rest of the check can proceed.
+ */
+export async function loadAntiPatternPlugins({ cwd = process.cwd() } = {}) {
+  const consumerPkgPath = path.join(cwd, 'package.json');
+  const consumerPkg = readJsonSafe(consumerPkgPath);
+  if (!consumerPkg) {
+    return { groups: [], reminders: [], discovered: [] };
+  }
+
+  const depNames = collectDependencyNames(consumerPkg);
+  const discovered = [];
+  const groups = [];
+  const reminders = [];
+
+  for (const depName of depNames) {
+    const depPkgPath = resolvePluginPackageJson(depName, cwd);
+    if (!depPkgPath) continue;
+
+    const depPkg = readJsonSafe(depPkgPath);
+    if (!depPkg) continue;
+
+    const entry = extractPluginEntry(depPkg);
+    if (!entry) continue;
+
+    const resolvedFile = path.resolve(path.dirname(depPkgPath), entry);
+    const record = { packageName: depName, entry, resolvedFile, status: 'loaded' };
+
+    try {
+      if (!fs.existsSync(resolvedFile)) {
+        throw new Error(`plugin entry file not found at ${resolvedFile}`);
+      }
+      const mod = await import(pathToFileURL(resolvedFile).href);
+      const candidate = mod?.default ?? mod;
+      // shape の検証は plugin-api.js と共有する。`defineAntiPatternPlugin` を呼ばずに
+      // plain object を export する plugin にも同じ厳しさを適用したい。
+      // en: Share shape validation with `defineAntiPatternPlugin` so plugins that skip
+      // the helper are still rejected at load time.
+      validatePluginShape(candidate, `${depName} (${entry})`);
+      groups.push(...candidate.groups);
+      record.groupIds = candidate.groups.map((group) => group.id);
+      if (Array.isArray(candidate.manualReviewReminders)) {
+        reminders.push(...candidate.manualReviewReminders);
+      }
+    } catch (error) {
+      record.status = 'error';
+      record.error = error?.message ?? String(error);
+      console.warn(
+        `⚠️  sparkle-design-cli: failed to load anti-pattern plugin from ${depName} (entry: ${entry}, error: ${record.error})`
+      );
+    }
+
+    discovered.push(record);
+  }
+
+  return { groups, reminders, discovered };
+}

package/lib/plugin-api.js

@@ -0,0 +1,308 @@
+/**
+ * sparkle-design-cli anti-pattern plugin contract.
+ *
+ * Plugin packages declare themselves in their own package.json:
+ *
+ *   {
+ *     "name": "@your-org/your-design-extensions",
+ *     "sparkleCli": {
+ *       "antiPatterns": "./anti-patterns/index.js"
+ *     }
+ *   }
+ *
+ * The referenced file must export a plugin object as the default export,
+ * typically produced by `defineAntiPatternPlugin({ ... })`.
+ *
+ * ## Plugin shape
+ *
+ *   defineAntiPatternPlugin({
+ *     groups: AntiPatternGroup[],
+ *     manualReviewReminders?: ManualReviewReminder[],
+ *   })
+ *
+ * ## AntiPatternGroup
+ *
+ *   {
+ *     id: string,                         // unique stable identifier (also used in --disable-line comments)
+ *     featureSection?: string,            // markdown emitted into the published anti-pattern doc (esa)
+ *     jsdocTargets?: JSDocTarget[],       // optional — JSDoc injection targets in the plugin's own source
+ *     check?: {
+ *       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 }>,
+ *                                         // opt-in API for complex matching (2-pass, AST, etc.).
+ *                                         // `helpers` (2nd arg) is injected by the CLI — see ## MatchHelpers.
+ *     },
+ *   }
+ *
+ * ## MatchHelpers
+ *
+ * `check.match` receives a frozen `helpers` object as its second argument. Prefer these over
+ * hand-rolling JSX parsing — they are maintained and tested in the CLI, so plugins stay free of a
+ * `sparkle-design-cli` dependency (plugins ship as plain JS and are loaded by the CLI) and always
+ * run on the same parser as the CLI at runtime (no version skew across plugins).
+ *
+ *   {
+ *     // Iterate `<Tag ...>` / `<Tag ... />` openings; return `{ index, text }` for predicate hits.
+ *     matchOpeningTags(content: string, tagName: string,
+ *                      predicate: (propsBlock: string) => boolean): Array<{ index: number, text: string }>,
+ *     // Strict-equality check for a prop assignment (handles `aria-*` / `data-*` without `\b` bugs).
+ *     hasProp(propsBlock: string, propName: string): boolean,
+ *     // Statically resolve whether the `type` prop is "multiple" (dynamic exprs -> false).
+ *     isMultipleTypeProp(propsBlock: string): boolean,
+ *     // Low-level: offset of an opening tag's closing `>` (string / JSX-expr aware), or -1.
+ *     findOpeningTagEnd(content: string, startIdx: number): number,
+ *   }
+ *
+ * ## JSDocTarget
+ *
+ *   {
+ *     file: string,                       // path relative to the plugin package root
+ *     targetName: string,                 // symbol whose JSDoc block receives the anti-pattern section
+ *     section: {
+ *       bullets: Array<{ ja: string, en: string }>,
+ *       example?: string,                 // tsx snippet
+ *     },
+ *   }
+ *
+ * ## ManualReviewReminder
+ *
+ *   {
+ *     id: string,                         // unique stable identifier echoed by the AI in acknowledgments
+ *     message: string,                    // human-readable instruction
+ *   }
+ *
+ * ## Notes
+ *
+ * - Built-in rules for the public `@goodpatch/sparkle-design` library are bundled with the CLI
+ *   and not exposed as a plugin. Plugins are merged on top of the built-ins.
+ * - Plugins are auto-discovered from the consumer's `package.json` dependencies, so a plugin
+ *   is active only when the consuming project actually installs the plugin package.
+ * - Plugin IDs share a namespace with built-ins. Pick a prefix (e.g. `internal-`) to avoid clashes.
+ */
+
+const PLUGIN_PACKAGE_FIELD = 'sparkleCli';
+const PLUGIN_ANTI_PATTERNS_KEY = 'antiPatterns';
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function validateGroup(group, context) {
+  if (!group || typeof group !== 'object' || Array.isArray(group)) {
+    throw new TypeError(`${context}: group entry must be a non-null object`);
+  }
+  if (!isNonEmptyString(group.id)) {
+    throw new TypeError(`${context}: group.id must be a non-empty string`);
+  }
+
+  if (group.check !== undefined) {
+    const { check } = group;
+    if (!check || typeof check !== 'object') {
+      throw new TypeError(`${context} (group "${group.id}"): check must be an object`);
+    }
+    if (!isNonEmptyString(check.description)) {
+      throw new TypeError(
+        `${context} (group "${group.id}"): check.description must be a non-empty string`
+      );
+    }
+    if (!isNonEmptyString(check.recommendation)) {
+      throw new TypeError(
+        `${context} (group "${group.id}"): check.recommendation must be a non-empty string`
+      );
+    }
+    const hasPattern = check.pattern !== undefined;
+    const hasMatch = check.match !== undefined;
+    if (hasPattern === hasMatch) {
+      throw new TypeError(
+        `${context} (group "${group.id}"): check must define exactly one of \`pattern\` (RegExp) or \`match\` (function)`
+      );
+    }
+    if (hasPattern) {
+      if (!(check.pattern instanceof RegExp)) {
+        throw new TypeError(`${context} (group "${group.id}"): check.pattern must be a RegExp`);
+      }
+      // matchAll は global flag が無い RegExp で TypeError を投げるので、ここで明示的に弾く。
+      // en: Bail early so the check pipeline never reaches `content.matchAll(nonGlobal)`.
+      if (!check.pattern.global) {
+        throw new TypeError(
+          `${context} (group "${group.id}"): check.pattern must include the global flag (e.g. /foo/g)`
+        );
+      }
+    } else if (typeof check.match !== 'function') {
+      throw new TypeError(`${context} (group "${group.id}"): check.match must be a function`);
+    }
+  }
+}
+
+function validateReminders(reminders, context) {
+  if (reminders === undefined) return;
+  if (!Array.isArray(reminders)) {
+    throw new TypeError(`${context}: manualReviewReminders must be an array if present`);
+  }
+  for (const [index, reminder] of reminders.entries()) {
+    if (!reminder || typeof reminder !== 'object') {
+      throw new TypeError(`${context}: manualReviewReminders[${index}] must be a non-null object`);
+    }
+    if (!isNonEmptyString(reminder.id)) {
+      throw new TypeError(
+        `${context}: manualReviewReminders[${index}].id must be a non-empty string`
+      );
+    }
+    if (!isNonEmptyString(reminder.message)) {
+      throw new TypeError(
+        `${context}: manualReviewReminders[${index}].message must be a non-empty string`
+      );
+    }
+  }
+}
+
+/**
+ * Validate that the given object matches the documented plugin shape. Throws TypeError
+ * with an actionable message on the first violation. Exported so the loader can apply
+ * the same checks to plugins that don't go through `defineAntiPatternPlugin`.
+ *
+ * @param {unknown} plugin
+ * @param {string} [context] source identifier shown in error messages (e.g. `@org/pkg (./file.js)`)
+ */
+function validatePluginShape(plugin, context = 'plugin') {
+  if (!plugin || typeof plugin !== 'object' || Array.isArray(plugin)) {
+    throw new TypeError(`${context}: plugin must be a non-null object`);
+  }
+  if (!Array.isArray(plugin.groups)) {
+    throw new TypeError(`${context}: plugin.groups must be an array`);
+  }
+  for (const [index, group] of plugin.groups.entries()) {
+    validateGroup(group, `${context} groups[${index}]`);
+  }
+  validateReminders(plugin.manualReviewReminders, context);
+}
+
+function defineAntiPatternPlugin(plugin) {
+  validatePluginShape(plugin, 'defineAntiPatternPlugin');
+  return plugin;
+}
+
+const PLUGIN_SPEC_MARKDOWN = `# sparkle-design-cli anti-pattern plugin spec
+
+Plugin packages extend \`sparkle-design-cli check\` with additional anti-pattern rules.
+Built-in rules cover the public \`@goodpatch/sparkle-design\` library; plugins are auto-discovered
+from the consuming project's dependencies, so private or org-specific component libraries can ship
+their own detection rules without bundling them into the public CLI.
+
+## Declaring a plugin
+
+In the plugin package's own \`package.json\`:
+
+\`\`\`json
+{
+  "name": "@your-org/your-design-extensions",
+  "sparkleCli": {
+    "antiPatterns": "./anti-patterns/index.js"
+  }
+}
+\`\`\`
+
+The referenced file must default-export a plugin object:
+
+\`\`\`js
+import { defineAntiPatternPlugin } from 'sparkle-design-cli/plugin';
+
+export default defineAntiPatternPlugin({
+  groups: [
+    {
+      id: 'internal-foo-misuse',
+      featureSection: '### FooCard はネスト禁止\\n...',
+      check: {
+        description: 'FooCard を別の FooCard でラップしないでください。',
+        recommendation: '入れ子表示が必要なら FooStack を使ってください。',
+        pattern: /<FooCard[^>]*>[\\s\\S]*?<FooCard/g,
+      },
+    },
+  ],
+  manualReviewReminders: [
+    {
+      id: 'internal-foo-color',
+      message: 'FooCard の color token が brand に揃っているか確認してください。',
+    },
+  ],
+});
+\`\`\`
+
+## Discovery
+
+When \`sparkle-design-cli\` runs in a project, it reads that project's \`package.json\`,
+walks \`dependencies\` / \`devDependencies\` / \`peerDependencies\` / \`optionalDependencies\`,
+and resolves each entry's own \`package.json\`. Packages whose \`package.json\` declares
+\`sparkleCli.antiPatterns\` are loaded and merged into the check rules.
+
+End users do not have to configure anything — installing a plugin package is enough to activate it.
+
+## Shape reference
+
+See the JSDoc in \`lib/plugin-api.js\` for the full type contract:
+
+- \`AntiPatternGroup\`: \`{ id, featureSection?, jsdocTargets?, check? }\`
+- \`AntiPatternGroup.check\`: \`{ description, recommendation, pattern | match }\`
+  - \`pattern\` is a RegExp and **must include the global flag** (\`/foo/g\`); otherwise
+    the rule is rejected at load time.
+  - \`match\` is called as \`match(content, helpers)\`; \`helpers\` (matchOpeningTags / hasProp /
+    isMultipleTypeProp / findOpeningTagEnd) is injected by the CLI, so plugins need no import.
+  - \`pattern\` and \`match\` are mutually exclusive — provide exactly one.
+- \`JSDocTarget\`: \`{ file, targetName, section: { bullets, example? } }\`
+- \`ManualReviewReminder\`: \`{ id, message }\`
+
+## Complex matching with injected helpers
+
+For matches a single regex can't express safely (accessible-name presence, prop combinations,
+JSX-expression-aware scanning), use \`check.match\` instead of \`check.pattern\`. \`match\` receives the
+file \`content\` and a frozen \`helpers\` bundle as its **second argument**, so the plugin never imports
+\`sparkle-design-cli\` — it ships as plain JS and the running CLI injects its own tested parser. This
+keeps plugins dependency-free and guarantees every plugin uses the same parser at runtime.
+
+\`\`\`js
+// No import of sparkle-design-cli — default-export a plain object.
+export default {
+  groups: [
+    {
+      id: 'internal-avatar-without-accessible-name',
+      check: {
+        description: 'Avatar に accessible name がありません。',
+        recommendation: 'aria-label か alt を指定してください。',
+        // helpers = { matchOpeningTags, hasProp, isMultipleTypeProp, findOpeningTagEnd }
+        match: (content, { matchOpeningTags, hasProp }) =>
+          matchOpeningTags(
+            content,
+            'Avatar',
+            (props) =>
+              !hasProp(props, 'src') &&
+              !hasProp(props, 'aria-label') &&
+              !hasProp(props, 'aria-labelledby')
+          ),
+      },
+    },
+  ],
+};
+\`\`\`
+
+## ID namespace
+
+Plugin rule IDs share a namespace with built-in rules and with each other. Choose a stable prefix
+(e.g. \`internal-\`, \`acme-\`) so suppression comments like \`// sparkle-disable-next-line internal-foo-misuse\`
+remain unambiguous.
+
+## Failure mode
+
+Errors loading or evaluating a plugin are logged as warnings; the rest of the check continues with
+the rules that did load. The CLI never fails because a plugin is missing or broken.
+`;
+
+export {
+  PLUGIN_PACKAGE_FIELD,
+  PLUGIN_ANTI_PATTERNS_KEY,
+  PLUGIN_SPEC_MARKDOWN,
+  defineAntiPatternPlugin,
+  validatePluginShape,
+};

package/lib/plugin-helpers.js

@@ -0,0 +1,165 @@
+/**
+ * sparkle-design-cli が anti-pattern プラグインの `check.match` に注入する JSX パース
+ * ヘルパー群。プラグイン側はこれらを import せず、`match(content, helpers)` の第 2 引数
+ * として受け取る。npx 実行された CLI 自身が自分の実装を渡すため、プラグインパッケージは
+ * sparkle-design-cli への依存を一切持たずに済み（生 JS のまま配布できる）、かつ全プラグインが
+ * 常に実行中 CLI と同一のパース実装で動く（バージョンずれによる検出差が原理的に起きない）。
+ *
+ * ここに集約する狙いは、各プラグインが正規表現ベース JSX 解析の罠
+ * （文字列リテラル / JSX 式 `{}` のバランス、escape backslash、`\b` 境界）を再実装して
+ * 同じ false-positive / negative を踏むのを防ぐこと。修正履歴は下の各 JSDoc に残す。
+ *
+ * en: JSX parsing helpers injected into a plugin's `check.match` as the second argument.
+ * Plugins never import these — the running CLI passes its own implementation, so plugins
+ * stay dependency-free and always run on the same parser as the CLI (no version skew).
+ * Centralizing them keeps every plugin on one tested implementation instead of re-deriving
+ * the regex edge cases (string / JSX-expression `{}` balance, escaped backslashes, `\b`).
+ */
+
+/**
+ * 開きタグの「最後の `>` の位置」を返すスキャナ。`[^>]*?` だと JSX prop 値中の
+ * `=>` / `>` / 子 JSX (`<X />`) で早期打ち切りになるため、文字列リテラル
+ * （`'`, `"`, `` ` ``）と JSX expression `{ ... }` の中括弧バランスを
+ * 意識した state machine で `>` を探す。
+ *
+ * 文字列内の closing quote は **直前の連続 backslash の数が偶数のときだけ**
+ * 終端として認める。`<Avatar title="C:\\" />` のように奇数個 backslash で
+ * 終わる場合に「閉じ quote が escape されたまま」と誤判定して全体を skip
+ * する false negative を防ぐ。
+ *
+ * en: Scanner returning the closing `>` of an opening JSX tag. Tracks string
+ * literals and `{}` nesting to avoid early termination on `=>` / `>` inside
+ * prop values or nested JSX. The closing quote is honored only when the count
+ * of preceding consecutive backslashes is even, so attribute values ending in
+ * a literal backslash (`"C:\\"`) don't make the scanner walk past EOF.
+ *
+ * @param {string} content
+ * @param {number} startIdx 走査開始オフセット（`<Tag` の直後を渡す）
+ * @returns {number} 開きタグを閉じる `>` の絶対オフセット。見つからなければ -1。
+ */
+function findOpeningTagEnd(content, startIdx) {
+  let depth = 0;
+  let inStr = null;
+  for (let i = startIdx; i < content.length; i += 1) {
+    const ch = content[i];
+    if (inStr) {
+      if (ch === inStr) {
+        // 直前の連続 backslash 数を数える。偶数（0 含む）なら closing quote。
+        // en: Count preceding consecutive backslashes; even means unescaped.
+        let backslashes = 0;
+        for (let j = i - 1; j >= startIdx && content[j] === '\\'; j -= 1) {
+          backslashes += 1;
+        }
+        if (backslashes % 2 === 0) inStr = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      inStr = ch;
+      continue;
+    }
+    if (ch === '{') depth += 1;
+    else if (ch === '}') depth -= 1;
+    else if (ch === '>' && depth === 0) return i;
+  }
+  return -1;
+}
+
+/**
+ * 与えられた tagName の開きタグ `<Tag ...>` / `<Tag ... />` を全て走査し、
+ * 各 propsBlock で `predicate` が真になったものを CLI の `rule.match` API
+ * 形式 `{ index, text }` で返す。
+ *
+ * anchor は `<Tag` の直後が `\s` / `/` / `>` のいずれかであることを要求するため、
+ * `<Tagged` / `<TagOther` / `<Tag.Image` のような名前の prefix 違いには hit しない。
+ * 一方で JS line comment 中の `// <Avatar />` のような疑似 JSX には素直に hit する
+ * が、ノイズは低く `// sparkle-disable-*` で個別に suppress できるため許容している。
+ *
+ * en: Iterate all `<Tag ...>` / `<Tag ... />` openings of the given tag name
+ * and call `predicate(propsBlock)` for each. Returns `{ index, text }` items
+ * for hits in the shape expected by the CLI's `rule.match` API. The anchor
+ * requires `\s` / `/` / `>` right after `<Tag` so prefix-different names like
+ * `<Tagged` or `<Tag.Image` are not picked up. JS line comments aren't filtered
+ * out — `// sparkle-disable-*` covers that escape hatch.
+ *
+ * @param {string} content
+ * @param {string} tagName 例: `'Avatar'`
+ * @param {(propsBlock: string) => boolean} predicate propsBlock を受け取り hit 判定を返す
+ * @returns {Array<{ index: number, text: string }>}
+ */
+function matchOpeningTags(content, tagName, predicate) {
+  const anchor = new RegExp(`<${tagName}(?=[\\s/>])`, 'g');
+  const hits = [];
+  for (const opener of content.matchAll(anchor)) {
+    const start = opener.index ?? 0;
+    const tagBodyStart = start + opener[0].length;
+    const end = findOpeningTagEnd(content, tagBodyStart);
+    if (end === -1) continue;
+    const propsBlock = content.slice(tagBodyStart, end);
+    if (predicate(propsBlock)) {
+      hits.push({ index: start, text: `<${tagName}${propsBlock}>` });
+    }
+  }
+  return hits;
+}
+
+/**
+ * propsBlock 内に prop 名 `propName` が代入されているかを厳密一致で判定する。
+ *
+ * 旧実装の `\b${propName}\s*=` は `\b` が letter と `-` の境界でも発火するため
+ * - `hasProp(..., 'label')` が `aria-label=` を拾う（label 未指定の見逃し）
+ * - `hasProp(..., 'initials')` が `data-initials=` を拾う（initials なしを HIT）
+ * の両方向の bug を抱えていた。prop 名の直前を `^` か whitespace か `{`
+ * のいずれかでアンカーすることで両方解消する。
+ *
+ * en: Strict-equality check for a prop assignment in `propsBlock`. The previous
+ * `\b${propName}\s*=` was broken in both directions because `\b` fires between
+ * a letter and `-`. Anchoring the prop name at start-of-block or a non-identifier
+ * character (whitespace / `{`) fixes both `aria-label` ↔ `label` and
+ * `data-initials` ↔ `initials` confusions.
+ *
+ * @param {string} propsBlock matchOpeningTags が渡す開きタグ内部のテキスト
+ * @param {string} propName 探す prop 名（`aria-label` など `-` を含んでも可）
+ * @returns {boolean}
+ */
+function hasProp(propsBlock, propName) {
+  const escaped = propName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(?:^|[\\s{])${escaped}\\s*=`).test(propsBlock);
+}
+
+/**
+ * propsBlock の `type` prop が静的に `"multiple"` と判定できるかを返す。
+ *
+ * 静的に "multiple" と判定できる 6 形式に対応（bare 3 + JSX 式中 3。`[`"']` が
+ * backtick / double / single の 3 quote をカバーする）:
+ *   bare:     type="multiple" / type='multiple' / type=`multiple`
+ *   JSX 式中: type={"multiple"} / type={'multiple'} / type={`multiple`}
+ * `type={someExpr}` のような動的指定は判定不能なので安全側に倒して `false`
+ * （= 非 multiple 扱い = rule HIT 候補）を返す。bare backtick は JSX としては不正だが、
+ * 正規表現上はマッチする（実害なく、誤検出は安全側）。
+ *
+ * en: Recognize all statically-resolvable "multiple" forms — bare and
+ * JSX-expression, each across the three quote styles (`/"/'). Dynamic
+ * expressions stay as HIT candidates (returns `false`) so we don't silently
+ * miss bugs.
+ *
+ * @param {string} propsBlock
+ * @returns {boolean}
+ */
+function isMultipleTypeProp(propsBlock) {
+  return /type\s*=\s*(?:[`"']multiple[`"']|\{\s*[`"']multiple[`"']\s*\})/.test(propsBlock);
+}
+
+/**
+ * `check.match(content, helpers)` の第 2 引数としてプラグインに注入されるヘルパー集合。
+ * 凍結して渡すことで、プラグインが誤って実装を差し替えるのを防ぐ。
+ * en: Frozen helper bundle injected as the second argument of `check.match`.
+ */
+const MATCH_HELPERS = Object.freeze({
+  findOpeningTagEnd,
+  matchOpeningTags,
+  hasProp,
+  isMultipleTypeProp,
+});
+
+export { findOpeningTagEnd, matchOpeningTags, hasProp, isMultipleTypeProp, MATCH_HELPERS };

package/lib/stop-hook.js

@@ -19,7 +19,7 @@ import { checkProject } from './check.js';
  * Claude Code sets `stop_hook_active: true` on re-fires so the hook can
  * exit cleanly instead of looping forever (see Claude Code hooks docs).
  */
-export function runStopHook(target) {
+export async function runStopHook(target) {
   const payload = readStdinJsonSafely();
 
   if (payload && payload.stop_hook_active === true) {
@@ -32,7 +32,7 @@ export function runStopHook(target) {
   }
 
   const targets = target ? [target] : [];
-  const hasFindings = checkProject(targets, { strict: true, format: 'text' });
+  const hasFindings = await checkProject(targets, { strict: true, format: 'text' });
 
   if (hasFindings) {
     process.stderr.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.0.8",
+  "version": "2.2.0",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -8,6 +8,11 @@
   },
   "main": "lib/generate-css.js",
   "type": "module",
+  "exports": {
+    ".": "./lib/generate-css.js",
+    "./plugin": "./lib/plugin-api.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "sparkle-design-cli": "./bin/sparkle-design.js"
   },