sparkle-design-cli 2.1.0 → 2.2.0

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