sparkle-design-cli 2.5.0-beta.2 → 2.5.0-beta.4

package/lib/anti-pattern-rules.js

@@ -10,6 +10,7 @@ import {
   resolveTailwindPaletteUtility,
 } from './token-migration.js';
 import { buildSpacingUtilityPattern, pxToStep, resolveSpacingStep } from './spacing-scale.js';
+import { findOpeningTagEnd } from './plugin-helpers.js';
 
 const COMMON_INTRO =
   '以下は頻繁に発生する誤用パターンです。コンポーネントが提供する専用 props・サブコンポーネントを使ってください。';
@@ -136,6 +137,93 @@ const BUILTIN_MANUAL_REVIEW_REMINDERS = [
   },
 ];
 
+// --- JSX 開きタグを扱う match 用の小道具 ----------------------------------------
+//
+// フォーム系の a11y ルール（form-control-select-root / handwritten-radio-role /
+// handwritten-form-error）は「どのタグの属性か」「直下の子は何か」を見る必要があり、
+// 1 本の regex では prop 値中の `=>` や `{...}` で打ち切られる。プラグインに注入して
+// いる findOpeningTagEnd を組み込みルールでも使い、同じパース実装に揃える。
+// en: Helpers for the form a11y rules, built on the same findOpeningTagEnd that
+// plugins receive, so built-in and plugin rules share one tag scanner.
+
+// カスタム要素（`<my-radio>`）も拾えるよう `-` を許す
+// en: Allow `-` so custom elements such as `<my-radio>` are scanned too.
+const JSX_OPENING_TAG = /<([A-Za-z][\w.-]*)(?=[\s/>])/g;
+
+function blankOut(text) {
+  return text.replace(/[^\n]/g, ' ');
+}
+
+/**
+ * コメント中の疑似 JSX（`// Radix は <button role="radio"> を描画する` のような説明）を
+ * 検出しないよう、コメントを同じ長さの空白で潰す。index と行番号はずれない。
+ * 行頭からのブロックコメント（maskBlockComments と同じ前提）・JSX コメント
+ * `{/* ... *\/}`・行頭からの `//` コメントが対象。
+ * en: Blank out comments (same length, so offsets stay valid) so explanatory
+ * pseudo-JSX inside comments is not reported.
+ */
+function maskSourceComments(content) {
+  return maskBlockComments(content)
+    .replace(/\{\s*\/\*(?:(?!\*\/)[\s\S])*\*\/\s*\}/g, blankOut)
+    .replace(/^[ \t]*\/\/.*$/gm, blankOut);
+}
+
+/**
+ * `index` から始まる開きタグを読む。読めなければ null。
+ * en: Read the opening tag starting at `index`, or null.
+ */
+function readOpeningTag(content, index, tagName) {
+  const bodyStart = index + 1 + tagName.length;
+  const end = findOpeningTagEnd(content, bodyStart);
+  if (end === -1) return null;
+  const props = content.slice(bodyStart, end);
+  return {
+    index,
+    end,
+    tagName,
+    props,
+    selfClosing: props.trimEnd().endsWith('/'),
+    text: content.slice(index, end + 1),
+  };
+}
+
+/**
+ * `index` の直前にある「閉じていない開きタグ」（＝親要素）を返す。直前が
+ * whitespace を挟んで開きタグの `>` で終わっている場合だけを親とみなす
+ * （テキストや兄弟要素を挟む場合は追わない。ヒューリスティック用途のため）。
+ * en: The opening tag that immediately precedes `index` (only whitespace in
+ * between), i.e. the direct parent in the common `<span><Icon /></span>` shape.
+ */
+function findImmediateParentTag(content, index) {
+  const windowStart = Math.max(0, index - 2000);
+  const before = content.slice(windowStart, index);
+  const trimmed = before.trimEnd();
+  if (!trimmed.endsWith('>') || trimmed.endsWith('/>')) return null;
+  const closeAt = windowStart + trimmed.length - 1;
+  // 走査を closeAt までに切る。content 全体を渡すと、閉じ `>` が遠い候補（TS の
+  // ジェネリクスなど）ごとにファイル末尾まで走査してしまう。
+  // en: Bound the scan at closeAt so each candidate can't walk to EOF.
+  const bounded = content.slice(0, closeAt + 1);
+  let parent = null;
+  for (const opener of before.matchAll(JSX_OPENING_TAG)) {
+    const tag = readOpeningTag(bounded, windowStart + opener.index, opener[1]);
+    if (tag && tag.end === closeAt && !tag.selfClosing) parent = tag;
+  }
+  return parent;
+}
+
+// role="radio" / role="radiogroup"（JSX 式 `role={"radio"}` も）。`aria-role` /
+// `data-role` を拾わないよう、直前を空白か先頭に限る。
+// en: role="radio" / role="radiogroup", excluding aria-role / data-role.
+const RADIO_ROLE_ATTR =
+  /(?:^|\s)role\s*=\s*(?:(["'])(?:radio|radiogroup)\1|\{\s*(["'`])(?:radio|radiogroup)\2\s*\})/;
+
+const ERROR_ICON_ATTR = /(?:^|\s)icon\s*=\s*(?:(["'])error\1|\{\s*(["'`])error\2\s*\})/;
+
+// 旧体系 `text-negative-500` と新体系 `text-text-negative-enabled` の両方
+// en: Both the legacy (`text-negative-*`) and new (`text-text-negative-*`) tokens.
+const NEGATIVE_TEXT_COLOR = /(?<![\w-])text-(?:text-)?negative-[\w-]+/;
+
 const COMPONENT_ANTI_PATTERN_GROUPS = [
   {
     id: 'card-description',
@@ -1302,6 +1390,239 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
     ]),
     jsdocTargets: [],
   },
+  {
+    id: 'form-control-select-root',
+    check: {
+      description: 'FormControl で Select のルートを包まない（ラベルが関連付かない）',
+      recommendation:
+        'FormControl は SelectTrigger を包んでください（<Select><FormControl><SelectTrigger>…</SelectTrigger></FormControl><SelectContent>…</SelectContent></Select>）。FormControl は id / aria-describedby / aria-invalid を直下の子へ渡しますが、Select のルートは DOM を持たないため id がどこにも付かず、FormHeader の <label for> が何も指さなくなります。',
+      // 直下の最初の子要素が <Select> のときだけ。<Select> の中の <FormControl>
+      // （正しい形）や、<FormControl> 直下が <SelectTrigger> のものは拾わない。
+      // en: Only when the first direct child of <FormControl> is <Select>.
+      match: (rawContent) => {
+        const content = maskSourceComments(rawContent);
+        const hits = [];
+        for (const opener of content.matchAll(/<FormControl(?=[\s/>])/g)) {
+          const tag = readOpeningTag(content, opener.index, 'FormControl');
+          if (!tag || tag.selfClosing) continue;
+          const child = /^\s*<([A-Za-z][\w.-]*)(?=[\s/>])/.exec(content.slice(tag.end + 1));
+          if (child?.[1] !== 'Select') continue;
+          hits.push({
+            index: tag.index,
+            text: content.slice(tag.index, tag.end + 1 + child[0].length),
+          });
+        }
+        return hits;
+      },
+    },
+    featureSection: lines([
+      '### Select をフォームで使うときは FormControl で SelectTrigger を包む',
+      '',
+      '```tsx',
+      '// ✅ Correct — FormControl は SelectTrigger を包む',
+      '<FormItem>',
+      '  <FormHeader label="プラン" />',
+      '  <Select value={field.value} onValueChange={field.onChange}>',
+      '    <FormControl>',
+      '      <SelectTrigger>',
+      '        <SelectValue placeholder="選択してください" />',
+      '      </SelectTrigger>',
+      '    </FormControl>',
+      '    <SelectContent>',
+      '      <SelectItem value="free">Free</SelectItem>',
+      '    </SelectContent>',
+      '  </Select>',
+      '</FormItem>',
+      '',
+      '// ❌ Wrong — Select のルートを FormControl で包まない',
+      '<FormControl>',
+      '  <Select value={field.value} onValueChange={field.onChange}>',
+      '    <SelectTrigger>…</SelectTrigger>',
+      '    <SelectContent>…</SelectContent>',
+      '  </Select>',
+      '</FormControl>',
+      '```',
+      '',
+      '`FormControl` は Slot で `id` / `aria-describedby` / `aria-invalid` を直下の子に渡す。`Select` のルートは DOM を持たないので id がどこにも付かず、`FormHeader` の `<label for>` が何も指さない（ラベルを押してもフォーカスせず、読み上げでも関連が伝わらない）。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/form/index.tsx',
+        targetName: 'FormControl',
+        section: {
+          bullets: [
+            {
+              ja: '`Select` と組み合わせるときは `Select` のルートではなく `SelectTrigger` を包んでください。`Select` のルートは DOM を持たないため、渡した `id` が付かずラベルが関連付きません。',
+              en: 'With `Select`, wrap `SelectTrigger` rather than the `Select` root. The root renders no DOM, so the forwarded `id` lands nowhere and the label is not associated.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<Select value={field.value} onValueChange={field.onChange}>',
+            '  <FormControl>',
+            '    <SelectTrigger>',
+            '      <SelectValue placeholder="選択してください" />',
+            '    </SelectTrigger>',
+            '  </FormControl>',
+            '  <SelectContent>...</SelectContent>',
+            '</Select>',
+            '',
+            '// ❌ Wrong - Select のルートを包まない',
+            '<FormControl>',
+            '  <Select>...</Select>',
+            '</FormControl>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'handwritten-radio-role',
+    check: {
+      // 原則ダメだが、Radio / Select / SegmentedControl のどれにも収まらない
+      // 見た目の選択 UI（色見本など）で手組みを選ぶ判断はありうるので warning。
+      // en: warning, not error — a visual picker that none of the components fit
+      // can be a deliberate exception (suppress it with a comment).
+      severity: SEVERITY.WARNING,
+      description: '単一選択を role="radio" / role="radiogroup" で手組みしない',
+      recommendation:
+        '単一選択には Radio（選択肢が少なく常に 1 つ選ばれている）/ Select（選択肢が多い・表示スペースが狭い）/ sparkle-design-internal の SegmentedControl（2〜5 個の切り替え）を使ってください。手組みの role="radio" は矢印キーでの移動・roving tabindex・aria-checked の同期を自前で正しく実装する必要があります。どうしても手組みが必要な場合は `// sparkle-disable-next-line handwritten-radio-role` で理由を添えて残してください。',
+      match: (rawContent) => {
+        if (!/role\s*=\s*\{?\s*["'`]radio/.test(rawContent)) return [];
+        const content = maskSourceComments(rawContent);
+        const hits = [];
+        for (const opener of content.matchAll(JSX_OPENING_TAG)) {
+          // Radio / RadioGroup / SegmentedControl 自身（とその実装の Radix
+          // primitive）は role を持つのが正しいので対象外
+          // en: The components themselves legitimately carry these roles.
+          if (/Radio|SegmentedControl/.test(opener[1])) continue;
+          const tag = readOpeningTag(content, opener.index, opener[1]);
+          if (tag && RADIO_ROLE_ATTR.test(tag.props)) {
+            hits.push({ index: tag.index, text: tag.text });
+          }
+        }
+        return hits;
+      },
+    },
+    featureSection: lines([
+      '### 単一選択を role="radio" で手組みしない',
+      '',
+      '```tsx',
+      '// ✅ Correct — 選択肢が少なく常に 1 つ選ばれている',
+      '<Radio value={value} onValueChange={setValue}>',
+      '  <RadioItem value="sm" label="小" />',
+      '  <RadioItem value="md" label="中" />',
+      '</Radio>',
+      '',
+      '// ✅ Correct — 選択肢が多い・表示スペースが狭い',
+      '<Select value={value} onValueChange={setValue}>…</Select>',
+      '',
+      '// ❌ Wrong — button に role="radio" を付けて手組みしない',
+      '<div role="radiogroup">',
+      '  <button type="button" role="radio" aria-checked={value === "sm"}>小</button>',
+      '  <button type="button" role="radio" aria-checked={value === "md"}>中</button>',
+      '</div>',
+      '```',
+      '',
+      '単一選択は `Radio` / `Select` / sparkle-design-internal の `SegmentedControl`（2〜5 個の切り替え）から選ぶ。手組みの `role="radio"` は矢印キーでの移動や `aria-checked` の同期を自前で実装することになり、漏れやすい。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'handwritten-form-error',
+    check: {
+      // 「error アイコン + negative 系の文字色が並ぶ」というヒューリスティックで、
+      // 入力欄に紐づかないページ全体のエラー表示なども拾いうるので info に留める。
+      // en: Heuristic (error icon next to a negative text color) — it can also hit
+      // page-level errors that aren't tied to a field, so keep it at info.
+      severity: SEVERITY.INFO,
+      description: 'フォームのエラー表示を Icon + negative 色で手組みしない',
+      recommendation:
+        '入力欄のエラーは FormErrorMessage を使ってください。FormErrorMessage は aria-describedby / aria-invalid で入力欄と関連付くため、読み上げでどの欄のエラーかが伝わります（手組みでは伝わりません）。入力欄に紐づかないエラー（ページ全体の失敗など）なら InlineMessage を検討し、意図的な手組みであれば `// sparkle-disable-next-line handwritten-form-error` で残してください。',
+      // `<Icon icon="error">` の (1) 自身 (2) 直上の親 (3) 直後の兄弟 のいずれかに
+      // negative 系の文字色があれば手組みのエラー表示とみなす。親に data-slot が
+      // 付いているもの（FormErrorMessage など Sparkle 本体の実装）は対象外。
+      // en: Flag `<Icon icon="error">` when the icon itself, its immediate parent,
+      // or its next sibling carries a negative text color. Parents with
+      // `data-slot` are Sparkle's own implementation (FormErrorMessage) — skip.
+      match: (rawContent) => {
+        if (!/icon\s*=\s*\{?\s*["'`]error/.test(rawContent)) return [];
+        const content = maskSourceComments(rawContent);
+        const hits = [];
+        for (const opener of content.matchAll(/<Icon(?=[\s/>])/g)) {
+          const icon = readOpeningTag(content, opener.index, 'Icon');
+          if (!icon || !ERROR_ICON_ATTR.test(icon.props)) continue;
+
+          const parent = findImmediateParentTag(content, icon.index);
+          if (
+            parent &&
+            (/(?:^|\s)data-slot\s*=/.test(parent.props) || parent.tagName === 'FormErrorMessage')
+          ) {
+            continue;
+          }
+
+          let sibling = null;
+          if (icon.selfClosing) {
+            const next = /^\s*<([A-Za-z][\w.-]*)(?=[\s/>])/.exec(content.slice(icon.end + 1));
+            if (next) {
+              sibling = readOpeningTag(content, icon.end + 1 + next[0].indexOf('<'), next[1]);
+            }
+          }
+
+          if ([icon, parent, sibling].some((tag) => tag && NEGATIVE_TEXT_COLOR.test(tag.props))) {
+            hits.push({ index: icon.index, text: icon.text });
+          }
+        }
+        return hits;
+      },
+    },
+    featureSection: lines([
+      '### フォームのエラー表示は FormErrorMessage を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct — 入力欄と aria-describedby / aria-invalid で関連付く',
+      '<FormItem>',
+      '  <FormHeader label="招待コード" />',
+      '  <FormControl>',
+      '    <Input {...field} isInvalid={fieldState.invalid} />',
+      '  </FormControl>',
+      '  <FormErrorMessage />',
+      '</FormItem>',
+      '',
+      '// ❌ Wrong — Icon と negative 色でエラー表示を手組みしない',
+      '<span className="flex items-center gap-1 text-text-negative-enabled">',
+      '  <Icon icon="error" size={3} />',
+      '  コードが見つかりません',
+      '</span>',
+      '```',
+      '',
+      '手組みのエラー表示は見た目が同じでも入力欄との関連が無く、スクリーンリーダーではどの欄のエラーかが伝わらない。入力欄に紐づかないエラーは `InlineMessage` を使う。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/form/index.tsx',
+        targetName: 'FormErrorMessage',
+        section: {
+          bullets: [
+            {
+              ja: '`<Icon icon="error" />` と negative 系の文字色でエラー表示を手組みしないでください。`FormErrorMessage` は `aria-describedby` / `aria-invalid` で入力欄と関連付きます。',
+              en: 'Do not hand-roll error text with `<Icon icon="error" />` and a negative text color. `FormErrorMessage` is linked to the field via `aria-describedby` / `aria-invalid`.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<FormErrorMessage />',
+            '',
+            '// ❌ Wrong - 手組みのエラー表示',
+            '<span className="text-text-negative-enabled">',
+            '  <Icon icon="error" size={3} />',
+            '  コードが見つかりません',
+            '</span>',
+          ]),
+        },
+      },
+    ],
+  },
 ];
 
 // Built-in groups always come before plugin-supplied groups in this priority order.
@@ -1351,6 +1672,23 @@ function maskBlockComments(content) {
   return content.replace(/^[ \t]*\/\*[\s\S]*?\*\//gm, (comment) => comment.replace(/[^\n]/g, ' '));
 }
 
+/**
+ * そのファイル自身が宣言している CSS カスタムプロパティ名の集合。
+ *
+ * `check` の移行ルールと `migrate` サブコマンドの両方が「定義側は移行対象の
+ * 使用ではない」という同じ判定を使う。片方だけ直すと、check は黙っているのに
+ * migrate が生成物の定義を書き換える（あるいはその逆）というずれが生まれるため、
+ * 1 箇所にまとめている。
+ * en: Custom properties declared by this file. Shared by `check` and `migrate`
+ * so both agree that definitions are not usages to migrate.
+ *
+ * @param {string} content ブロックコメントをマスク済みの内容
+ * @returns {Set<string>}
+ */
+function collectDeclaredCustomProperties(content) {
+  return new Set([...content.matchAll(/(?:^|[{;])\s*(--[\w-]+)\s*:/gm)].map((m) => m[1]));
+}
+
 function migrationMatcher(pattern, resolve, label) {
   return (rawContent) => {
     const content = maskBlockComments(rawContent);
@@ -1369,9 +1707,7 @@ function migrationMatcher(pattern, resolve, label) {
     // CSS や minify された theme ファイルで**定義側まで「使用」として報告**する。
     // en: Also treat `{`/`;` as declaration starts so single-line/minified CSS
     // doesn't get its own definitions reported as usages.
-    const declaredHere = new Set(
-      [...content.matchAll(/(?:^|[{;])\s*(--[\w-]+)\s*:/gm)].map((m) => m[1])
-    );
+    const declaredHere = collectDeclaredCustomProperties(content);
 
     const hits = [];
     for (const match of content.matchAll(pattern)) {
@@ -1761,6 +2097,9 @@ const BUILTIN_CHECK_ORDER = [
   'disabled-vs-is-disabled',
   'button-prefixicon-jsx',
   'icon-children-text',
+  'form-control-select-root',
+  'handwritten-radio-role',
+  'handwritten-form-error',
   // NOTE: この配列が決めるのは **ルールの評価順** だけで、レポートの表示順では
   // ない（findings は check.js 側で severity 優先にソートされる）。移行ルールを
   // 末尾に置いているのは評価順を安定させるためで、「warning が error を埋もれ
@@ -1814,9 +2153,11 @@ export {
   BUILTIN_ANTI_PATTERN_GROUPS as ANTI_PATTERN_GROUPS,
   BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
   COMMON_INTRO,
+  collectDeclaredCustomProperties,
   getAllJSDocTargets,
   getCheckRules,
   getManualReviewReminders,
+  maskBlockComments,
   renderFeatureSections,
   renderJSDocSection,
 };