sparkle-design-cli 2.1.0 → 2.2.1

package/README.md

@@ -209,6 +209,46 @@ export default defineAntiPatternPlugin({
 });
 ```
 
+##### 複雑な検出（`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` を宣言しているパッケージを発見次第ロードしてビルトインのルールにマージします。

package/bin/sparkle-design.js

@@ -174,7 +174,9 @@ Setup:
 Generate options:
   -h, --help                 このヘルプメッセージを表示
   -c, --config <path>        設定ファイルのパス (default: ./sparkle.config.json)
-  -o, --output <path>        出力ファイルのパス (default: ./src/app/sparkle-design.css)
+  -o, --output <path>        出力ファイルのパス
+                             (default: globals-path 指定時はその entry CSS と同じ
+                              ディレクトリ、未指定時は ./src/app/sparkle-design.css)
   --globals-path <path>      Tailwind エントリポイント CSS のパス (default: 自動検出)
   --strict                   globals.css への @source 注入等が失敗したら exit 1
                              (CI 向け。既定は warn + 継続で後方互換を維持)

package/lib/check.js

@@ -8,6 +8,7 @@ import {
   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';
@@ -163,10 +164,16 @@ function collectFindings(filePath, content, rules = BUILTIN_RULES) {
     // type) must not crash the whole check pipeline.
     try {
       if (typeof rule.match === 'function') {
-        // rule.match(content) -> Array<{ index: number, text: string }>
+        // rule.match(content, helpers) -> Array<{ index: number, text: string }>
         // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
         // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
-        const hits = rule.match(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}`);
         }

package/lib/font-manager.js

@@ -259,9 +259,10 @@ function reconstructGlobalsCss(globalsContent, sparkleImportBlock, tailwindInfo)
  * @param {string} globalsPath globals.cssのパス
  * @param {Array<string>|null} sourcePackages 追加パッケージ名の配列（null の場合は @source を生成しない）
  * @param {string|null} customCssPath custom-css ファイルの相対パス
- * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string }}
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string, globalsPath?: string, sourcePackages?: Array<string>|null }}
  *   skipped: 触る理由がない (fonts/sourcePackages/customCss すべて空)
- *   updated: globals.css を正常に書き換えた
+ *   updated: globals.css を正常に書き換えた（patch した globalsPath と挿入した
+ *            sourcePackages を併せて返す — issue #56 のサマリ表示用）
  *   failed: 書き換え対象だったが失敗した (TAILWIND_IMPORT 欠落、write 失敗等)
  */
 export function updateGlobalsWithFonts(
@@ -342,7 +343,11 @@ export function updateGlobalsWithFonts(
     // 6. 更新したglobals.cssを書き込む
     fs.writeFileSync(globalsPath, reconstructedContent, 'utf8');
     console.log(MESSAGES.GLOBALS_UPDATED(globalsPath));
-    return { status: 'updated' };
+    // `globalsPath` / `sourcePackages` は generate のサマリ出力（issue #56）が
+    // 「どの entry CSS に何の @source を挿入したか」を表示するために返す。
+    // en: Surface which entry CSS was patched and with which @source packages
+    // so the caller can render the generate summary (issue #56).
+    return { status: 'updated', globalsPath, sourcePackages };
   } catch (error) {
     // `E_UNSAFE_RELATIVE_PATH`（custom-css の path traversal 等）や
     // `E_TAILWIND_IMPORT_PREPEND_FAILED`（内部不整合）は silent fallback
@@ -564,7 +569,9 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
  * @param {string|null} customCssPath custom-css ファイルの相対パス
  * @param {string|null} globalsPathOverride 明示的に指定された globals パス
  * @param {{ strict?: boolean }} [options] strict=true のとき失敗を throw する
- * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string }}
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string, globalsPath?: string, sourcePackages?: Array<string>|null }}
+ *   updated のときは patch した entry CSS の globalsPath と挿入した sourcePackages
+ *   を含む（issue #56 の generate サマリ用）。
  */
 export function manageFontImports(
   sparkleDesignPath,

package/lib/generate-css.js

@@ -23,6 +23,7 @@ import {
   updateGlobalsWithFonts,
   isViteProject,
 } from './font-manager.js';
+import { assertSafeRelativePath, toPosixPath } from './path-utils.js';
 
 /**
  * config の extend セクションを解決する
@@ -344,6 +345,7 @@ function writeSparkleHead(content, sparkleDesignCssPath) {
   fs.writeFileSync(outputPath, content, 'utf8');
   console.log(`✅ SparkleHead.tsx を生成しました: ${outputPath}`);
   console.log('   → ルートレイアウトの <head> 内に <SparkleHead /> を追加してください');
+  return outputPath;
 }
 
 const VITE_INDEX_HTML_BLOCK_START = '<!-- sparkle-design-cli:fonts:start -->';
@@ -602,6 +604,73 @@ function detectSourcePackagesFromPackageJson(cwd = process.cwd()) {
   return null;
 }
 
+/**
+ * `--output` 未指定時に、明示された globals-path（CLI `--globals-path` または
+ * `extend.globals-path`）と同じディレクトリを出力先に使えるか判定する。
+ *
+ * 以前は framework に依らず常に `DEFAULT_OUTPUT_DIR = src/app/` に書き出していた
+ * ため、Vite の `src/index.css` 構成で `globals-path: src/index.css` を指定しても
+ * `sparkle-design.css` が `src/app/` に落ち、本来不要な `src/app/` ディレクトリが
+ * 生成されてレビュー / クリーンアップを混乱させていた（issue #56 確定バグ）。
+ *
+ * - globals-path が未指定なら null（従来どおり src/app/ を使う）
+ * - 不正な path（traversal / shell メタ文字 / 絶対パス）は `assertSafeRelativePath`
+ *   が throw（後段 `resolveGlobalsPath` でも同様に弾かれるので早期 fail-loud）
+ * - 解決した path が実在しなければ null。実在しない globals-path は
+ *   `manageFontImports` が `E_EXPLICIT_GLOBALS_PATH_NOT_FOUND` で loud に throw
+ *   するので、ここで typo 由来の誤ディレクトリを掘らないよう存在チェックする
+ * - 実在しても**通常ファイルでない**（ディレクトリ等）なら null。例えば
+ *   `globals-path: src` のようにディレクトリを誤指定すると、存在チェックだけ
+ *   では通過し `path.dirname('.../src')` がプロジェクト root を指して出力先が
+ *   root に誤誘導される。entry CSS は CSS ファイル前提なので `isFile()` で弾く。
+ *
+ * en: When `--output` is omitted, return the directory of an explicit
+ * globals-path so sparkle-design.css lands next to the entry CSS instead of
+ * always under src/app/. Returns null (→ keep src/app/ default) when no
+ * globals-path is given, it doesn't exist yet, or it isn't a regular file
+ * (e.g. a directory was passed by mistake).
+ *
+ * @param {string|null} globalsPathOverride
+ * @returns {string|null} entry CSS が通常ファイルとして実在する場合その絶対ディレクトリ、なければ null
+ */
+function resolveGlobalsDirForOutput(globalsPathOverride) {
+  if (!globalsPathOverride) {
+    return null;
+  }
+  assertSafeRelativePath(globalsPathOverride, 'globals-path');
+  const resolved = path.resolve(process.cwd(), globalsPathOverride);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch {
+    // 実在しない（ENOENT 等）。出力先は src/app/ 既定に委ね、entry CSS の
+    // not-found は manageFontImports が loud に throw する。
+    return null;
+  }
+  if (!stat.isFile()) {
+    return null;
+  }
+  return path.dirname(resolved);
+}
+
+/**
+ * sparkle-design.css の出力先絶対パスを決定する。
+ * 優先順位: `--output` 明示 > globals-path と同じディレクトリ > `src/app/`（既定）
+ * @param {string|null} outputPath `--output` の値
+ * @param {string|null} globalsPathOverride globals-path（CLI > config）
+ * @returns {string} 出力先の絶対パス
+ */
+function resolveOutputPath(outputPath, globalsPathOverride) {
+  if (outputPath) {
+    return path.resolve(outputPath);
+  }
+  const globalsDir = resolveGlobalsDirForOutput(globalsPathOverride);
+  if (globalsDir) {
+    return path.join(globalsDir, 'sparkle-design.css');
+  }
+  return path.resolve(process.cwd(), ...PATHS.DEFAULT_OUTPUT_DIR, 'sparkle-design.css');
+}
+
 function writeCSS(cssContent, outputPath = null) {
   // カスタムパスが指定されていない場合は実行場所からsrc/appディレクトリに出力
   const defaultOutputPath = path.resolve(
@@ -626,6 +695,79 @@ function writeCSS(cssContent, outputPath = null) {
   }
 }
 
+/**
+ * `@source` ブロックに実際に書き出されるパッケージ名一覧を組み立てる。
+ * `createSourceBlock`（font-manager.js）と同じく default の `sparkle-design` を
+ * 先頭に入れ、重複を除いた配列を返す。サマリ表示専用。
+ * en: Mirror createSourceBlock's package list (default sparkle-design first)
+ * for the summary output.
+ * @param {Array<string>|null|undefined} sourcePackages
+ * @returns {Array<string>|null} null は @source 未挿入
+ */
+function describeInsertedSourcePackages(sourcePackages) {
+  if (sourcePackages === null || sourcePackages === undefined) {
+    return null;
+  }
+  const defaultPackage = 'sparkle-design';
+  return [defaultPackage, ...sourcePackages.filter((p) => p !== defaultPackage)];
+}
+
+/**
+ * generate 完了時に「何を・どこに書いたか」を 1 ブロックで要約出力する。
+ * issue #56 の可観測性要求への対応。とくに entry CSS と出力先のディレクトリが
+ * 乖離している場合（Vite で `src/index.css` を patch しつつ出力が `src/app/` に
+ * 落ちる等）に警告を出し、`@source` が想定どおり挿入されたかを目視確認できる
+ * ようにする。
+ * en: Print a one-block summary of what `generate` patched / wrote and warn
+ * when the entry CSS dir and the output dir diverge (issue #56 observability).
+ *
+ * @param {Object} args
+ * @param {string} args.outputPath sparkle-design.css の絶対パス
+ * @param {string} args.sparkleHeadPath SparkleHead.tsx の絶対パス
+ * @param {{ status: string, reason?: string, globalsPath?: string, sourcePackages?: Array<string>|null }} args.globalsResult
+ */
+function printGenerateSummary({ outputPath, sparkleHeadPath, globalsResult }) {
+  const cwd = process.cwd();
+  const rel = (p) => (p ? path.relative(cwd, p) || '.' : null);
+  const lines = ['', '📋 生成サマリ (issue #56):'];
+  lines.push(`   • sparkle-design.css: ${rel(outputPath)}`);
+  lines.push(`   • SparkleHead.tsx:    ${rel(sparkleHeadPath)}`);
+
+  if (globalsResult.status === 'updated' && globalsResult.globalsPath) {
+    const entryPath = globalsResult.globalsPath;
+    lines.push(`   • パッチした entry CSS: ${rel(entryPath)}`);
+
+    const inserted = describeInsertedSourcePackages(globalsResult.sourcePackages);
+    if (inserted && inserted.length > 0) {
+      lines.push(`   • 挿入した @source:    ${inserted.join(', ')}`);
+    } else {
+      lines.push('   • 挿入した @source:    なし（source-packages 未指定）');
+    }
+
+    const entryDir = path.dirname(entryPath);
+    const outputDir = path.dirname(outputPath);
+    if (path.resolve(entryDir) === path.resolve(outputDir)) {
+      lines.push(`   • entry CSS と出力先 dir: 一致 (${rel(entryDir)})`);
+    } else {
+      const suggestedOutput = toPosixPath(path.join(rel(entryDir), 'sparkle-design.css'));
+      lines.push(
+        `   ⚠️  entry CSS dir (${rel(entryDir)}) と出力先 dir (${rel(outputDir)}) が異なります。`
+      );
+      lines.push(
+        `      @import は相対パスで解決されるため動作はしますが、出力先を揃えるには ` +
+          `--output ${suggestedOutput} の指定、または extend.globals-path と同じ ` +
+          `ディレクトリへの出力を検討してください。`
+      );
+    }
+  } else if (globalsResult.status === 'skipped') {
+    lines.push(`   • entry CSS パッチ:    スキップ (${globalsResult.reason ?? 'no-work'})`);
+  } else if (globalsResult.status === 'failed') {
+    lines.push(`   • entry CSS パッチ:    ❌ 失敗 (${globalsResult.reason ?? 'unknown'})`);
+  }
+
+  console.log(lines.join('\n'));
+}
+
 /**
  * メイン処理
  * @param {string|null} configPath カスタム設定ファイルのパス（オプション）
@@ -666,18 +808,21 @@ export function generateCSS(
     colors
   );
 
+  // globals-path（CLI `--globals-path` > `extend.globals-path`）を先に解決する。
+  // 出力先デフォルトの決定とフォント管理（@source 挿入）の両方で同じ値を使う。
+  // en: Resolve globals-path once (CLI over config); both the default output
+  // location and the font-import patcher consume it.
+  const globalsPathOverride = globalsPath || config['globals-path'] || null;
+
   // 6. CSSファイルを書き出し
-  const defaultOutputPath = path.resolve(
-    process.cwd(),
-    ...PATHS.DEFAULT_OUTPUT_DIR,
-    'sparkle-design.css'
-  );
-  const resolvedOutputPath = outputPath ? path.resolve(outputPath) : defaultOutputPath;
-  writeCSS(processedCSS, outputPath);
+  // `--output` 未指定時は globals-path と同じディレクトリ（実在する場合）に出す。
+  // 詳細は resolveOutputPath / resolveGlobalsDirForOutput の comment 参照（#56）。
+  const resolvedOutputPath = resolveOutputPath(outputPath, globalsPathOverride);
+  writeCSS(processedCSS, resolvedOutputPath);
 
   // 7. SparkleHead.tsx を生成（processTemplate で解決済みの resolvedFonts を再利用）
   const sparkleHeadContent = generateSparkleHeadContent(resolvedFonts);
-  writeSparkleHead(sparkleHeadContent, resolvedOutputPath);
+  const sparkleHeadPath = writeSparkleHead(sparkleHeadContent, resolvedOutputPath);
 
   // 7.5 Vite プロジェクトの index.html に Sparkle のフォント <link> タグを upsert
   // する。Vite は <head> が index.html 側にあるため、React コンポーネントの
@@ -740,7 +885,6 @@ export function generateCSS(
       ? [...new Set([...(detectedPackages ?? []), ...(explicitPackages ?? [])])]
       : null;
   const customCssPath = config['custom-css'] || null;
-  const globalsPathOverride = globalsPath || config['globals-path'] || null;
   const globalsResult = manageFontImports(
     resolvedOutputPath,
     sourcePackages,
@@ -749,6 +893,11 @@ export function generateCSS(
     { strict: Boolean(options.strict) }
   );
 
+  // 9. 生成サマリ（可観測性 / issue #56）。何を・どこに書いたか、@source が
+  //    挿入されたか、entry CSS と出力先の dir が乖離していないかを 1 ブロックで
+  //    出力する。設定は正しいのに @source が silent に落ちる事象を即検知できる。
+  printGenerateSummary({ outputPath: resolvedOutputPath, sparkleHeadPath, globalsResult });
+
   console.log(MESSAGES.SUCCESS);
   return { globalsResult };
 }

package/lib/plugin-api.js

@@ -31,11 +31,31 @@
  *       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.)
+ *       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
  *
  *   {
@@ -228,10 +248,45 @@ See the JSDoc in \`lib/plugin-api.js\` for the full type contract:
 - \`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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",