sparkle-design-cli 2.0.8 → 2.1.0

package/README.md

@@ -167,6 +167,72 @@ 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 に揃っているか確認してください。',
+    },
+  ],
+});
+```
+
+##### 自動 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,22 @@
 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 { 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 +110,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 +139,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 +155,40 @@ 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) -> Array<{ index: number, text: string }>
+        // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
+        // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
+        const hits = rule.match(content);
+        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 +298,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 +322,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 +341,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 +385,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 +440,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 +464,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,253 @@
+/**
+ * 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) => Array<{ index: number, text: string }>,
+ *                                         // opt-in API for complex matching (2-pass, AST, etc.)
+ *     },
+ *   }
+ *
+ * ## 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.
+  - \`pattern\` and \`match\` are mutually exclusive — provide exactly one.
+- \`JSDocTarget\`: \`{ file, targetName, section: { bullets, example? } }\`
+- \`ManualReviewReminder\`: \`{ id, message }\`
+
+## 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/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.1.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"
   },