sparkle-design-cli 2.4.2 → 2.5.0-beta.1

package/lib/spacing-scale.js

@@ -0,0 +1,228 @@
+/**
+ * Figma の `Spacing: Primitives` を「使ってよいステップ」として検査するためのデータ。
+ *
+ * ## なぜ CSS 変数ではなく check ルールなのか
+ *
+ * Tailwind v4 の `p-N` / `m-N` / `gap-N` は `calc(var(--spacing) * N)` に
+ * コンパイルされる。ここに `--spacing-<N>` という**名前付きキー**を定義すると、
+ * その N だけ名前付きの値が優先される。つまり Figma の値をそのまま CSS 変数に
+ * すると、既存 consumer の余白がビルドも警告も通ったまま静かに変わる。
+ *
+ * しかも数字の意味がずれている。Figma の `padding/16` は 16px だが、
+ * Tailwind の `p-16` は 64px（16 × 4px）で、同じ数字が 4 倍違う。
+ *
+ * そのため sparkle-variables はトークンを出さず（`--spacing-*` を定義しないことを
+ * validate-tokens.mjs が検査している）、代わりにここで「Figma のスケールに乗って
+ * いる値だけを使う」制約として検査する。
+ *
+ * en: Figma's spacing scale is enforced as a lint, not emitted as CSS variables.
+ * Defining `--spacing-<N>` would override Tailwind's dynamic spacing and silently
+ * rescale every existing consumer's padding — and Figma's `padding/16` (16px) is
+ * 4× smaller than Tailwind's `p-16` (64px), so the numbers don't even line up.
+ */
+
+/**
+ * Figma `Spacing: Primitives` の 17 段（px）。
+ * これが唯一の正解データで、以下はすべてここから導出する。
+ */
+export const FIGMA_SPACING_PX = [0, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 56, 72, 88, 104, 120];
+
+/** Tailwind の 1 ステップは 0.25rem = 4px。`p-4` は 4 × 4px = 16px。 */
+export const TAILWIND_STEP_PX = 4;
+
+/**
+ * px を Tailwind のステップに直した**数値**の集合（`0.5` / `1.5` など小数を含む）。
+ *
+ * 文字列ではなく数値で持つのは、`p-4` と `p-4.0` のような表記ゆれを別物として
+ * 扱わないため。判定側は書かれた字面を `Number.parseFloat` で数値化してから
+ * この集合と突き合わせる。
+ */
+export const FIGMA_SPACING_STEPS = new Set(FIGMA_SPACING_PX.map((px) => px / TAILWIND_STEP_PX));
+
+/**
+ * 数値ステップを取るユーティリティ接頭辞。
+ *
+ * Figma のコレクション名は `padding/*` だが、検査対象は padding だけにしない。
+ * `gap-7`（28px）のように Figma のスケールに無い値は、padding でなくても
+ * 同じだけレイアウトを崩すため。逆に言うと **これは「Figma がそう定義している」
+ * のではなく「同じスケールに乗せる」という運用上の判断**で、severity を `info` に
+ * しているのはそのため。
+ * en: Figma only names the collection `padding/*`; applying it to margin/gap/space
+ * is our operational call, which is why this ships at `info` severity.
+ */
+export const SPACING_UTILITY_PREFIXES = [
+  'p',
+  'px',
+  'py',
+  'pt',
+  'pr',
+  'pb',
+  'pl',
+  'ps',
+  'pe',
+  'm',
+  'mx',
+  'my',
+  'mt',
+  'mr',
+  'mb',
+  'ml',
+  'ms',
+  'me',
+  'gap',
+  'gap-x',
+  'gap-y',
+  'space-x',
+  'space-y',
+];
+
+/**
+ * 長い接頭辞を先に並べる。
+ *
+ * 正規表現の選択肢は先勝ちだが、この形（後続に `-<数字>` を要求する）なら
+ * 短い側が先に来てもバックトラックで長い側に到達するため、**並び順を変えても
+ * 検出結果は変わらない**。それでも並べ替えるのは、正しさをバックトラックの
+ * 挙動に依存させないため。
+ * en: Longest-first. With the trailing `-<digits>` requirement, backtracking
+ * would reach the longer alternative anyway — this just avoids depending on it.
+ */
+function alternation(values) {
+  if (values.length === 0) {
+    throw new Error('接頭辞が空です（検査が何にもマッチしなくなります）');
+  }
+  return [...values]
+    .sort((a, b) => b.length - a.length || a.localeCompare(b))
+    .map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|');
+}
+
+/**
+ * arbitrary variant の角括弧。**1 段だけ入れ子を許す**。
+ *
+ * `[^\]\s]*` だと最初の `]` で閉じてしまい、`[&:has([data-x])]:` や
+ * `[&_[data-slot=icon]]:` のような shadcn 系で頻出する形で variant を取りこぼす。
+ * 正規表現で任意段の入れ子は扱えないので 1 段で打ち切る（2 段以上は既知の制約）。
+ * en: Allows one level of nesting — `[&_[data-slot=icon]]:` is common in
+ * shadcn-style code. Arbitrary depth isn't expressible here; two levels or more
+ * is a known limitation.
+ */
+const VARIANT_BRACKET_BODY = '\\[(?:[^\\[\\]\\s]|\\[[^\\[\\]\\s]*\\])*\\]';
+
+/**
+ * variant の名前部分。`hover` / `md` / `data-[state=open]` に加えて、
+ * container query バリアントの `@sm` / `@2xl` のように `@` で始まる形も取る。
+ */
+const VARIANT_NAME = `@?[a-z0-9][a-z0-9-]*(?:${VARIANT_BRACKET_BODY})?`;
+
+/**
+ * 角括弧だけの arbitrary variant（`[&>*]` / `[@supports(display:grid)]`）と、
+ * 角括弧で幅を直接書く container query バリアント（`@[400px]`）。
+ * `@` を許さないと `@[400px]:p-7` の `@` だけが外れ、**存在しないクラス**
+ * `[400px]:p-6` を代替として提示してしまう。
+ */
+const VARIANT_BRACKET = `@?${VARIANT_BRACKET_BODY}`;
+
+/**
+ * 直下の子 `*:` と全子孫 `**:`。どちらも実在する Tailwind の variant。
+ *
+ * ここを落とすと `*:p-7` が `p-7` としてマッチし、「**子要素の余白**を
+ * **自分自身の余白**に書き換えろ」という案内になる。名前でも角括弧でもないので
+ * 独立した選択肢として持つ必要がある。
+ * en: Child (`*:`) and descendant (`**:`) variants. Missing them turns
+ * "change the children's padding" into "change your own padding".
+ */
+const VARIANT_STAR = '\\*\\*?';
+
+/**
+ * 名前付き group / peer / container の `/edit` 部分
+ * （`group-hover/edit:` / `peer-focus/email:` / `@2xl/main:`）。
+ *
+ * 名前はユーザーが決めるので大文字・アンダースコアも入る（`group/menuItem`）。
+ * 小文字だけに絞ると、その variant を丸ごと取りこぼした案内になる。
+ */
+const VARIANT_MODIFIER = `(?:\\/(?:[A-Za-z0-9_-]+|${VARIANT_BRACKET_BODY}))?`;
+
+/**
+ * variant 1 段。
+ *
+ * ここを狭く取ると、**variant を取りこぼしたうえで残りにマッチする**という
+ * 一番たちの悪い失敗をする。たとえば `/edit` を知らないと
+ * `group-hover/edit:p-7` が `edit:p-7` としてマッチし、代替候補が
+ * `edit:p-6` という存在しないクラスになる。
+ *
+ * 各段は必ず `:` を消費し、角括弧の中身も `[` と非 `[` の排他な選択肢で
+ * 組んであるため、`*` の中に置いても曖昧なバックトラックにならない。
+ * en: Too narrow a segment doesn't just miss the variant — it matches the
+ * leftover (`group-hover/edit:p-7` → `edit:p-7`) and suggests a class that
+ * doesn't exist. Every repetition must consume a `:` and the bracket body is
+ * built from mutually exclusive alternatives, so the outer `*` stays unambiguous.
+ */
+const VARIANT_SEGMENT = `(?:${VARIANT_STAR}|${VARIANT_NAME}|${VARIANT_BRACKET})${VARIANT_MODIFIER}`;
+
+/** `hover:md:` のような variant 連鎖。 */
+const VARIANT_CHAIN = `(?:${VARIANT_SEGMENT}:)*`;
+
+/**
+ * spacing ユーティリティにマッチする正規表現を作る。
+ *
+ * - 先頭の `-` は負のマージン（`-mt-4`）
+ * - 先頭・末尾の `!` は important（`!p-4` / `p-4!`）
+ * - 前後の `(?<![\w\-/])` / `(?![\w-])` は、`top-7` の `p-7` や `p-4x` のような
+ *   部分一致を弾くための境界。
+ *   - **`-` を含めるのが重要**。これが無いと `custom-mt-4` の末尾に紛れた
+ *     `mt-4` を誤検出する。
+ *   - **`/` を含めるのはパス対策**。`https://example.com/v1/p-7` や
+ *     `import x from './gap-7'` を拾ってしまうため。クラス名の直前に `/` が
+ *     来ることは実際には無い（`group-hover/edit:` の `/` は variant の内側で
+ *     消費されるので、マッチ開始位置の直前には現れない）。
+ *
+ * 名前つきキャプチャ:
+ * - `lead` … 数値の直前までの字面（`hover:-mt-`）。代替候補はこれに数字を
+ *   付け直して作るので、variant も `-` も `!` も自動的に保たれる
+ * - `sign` … ユーティリティ直前の `!` / `-`（important と負値）
+ * - `step` … ステップ値
+ * - `important` … 末尾の `!`
+ *
+ * `sign` を**正規表現で切り出す**のが重要。`lead` 全体を `/-/` で調べる方式だと、
+ * `[&:-moz-any-link]:mt-7` のように variant の内側に `-` を含む形で
+ * 「負値である」と誤判定し、正の 28px を -28px と案内してしまう。
+ * en: Named captures. `sign` must come from the pattern itself — scanning the
+ * whole `lead` for a hyphen misreads variants like `[&:-moz-any-link]:mt-7`
+ * as negative and reports +28px as −28px.
+ */
+export function buildSpacingUtilityPattern() {
+  return new RegExp(
+    `(?<![\\w\\-/])(?<lead>${VARIANT_CHAIN}(?<sign>!?-?)(?:${alternation(SPACING_UTILITY_PREFIXES)})-)(?<step>\\d+(?:\\.\\d+)?)(?<important>!?)(?![\\w-])`,
+    'g'
+  );
+}
+
+/**
+ * ステップ値が Figma のスケールに乗っているかを判定する。
+ *
+ * @param {string} step 字面のステップ（`"4"` / `"0.5"` / `"20"`）
+ * @returns {null | { px: number, lower: number | null, upper: number | null }}
+ *   スケール内なら null。スケール外なら px 換算値と、前後の許容値を返す。
+ *   数値として読めない入力も null（＝報告しない）を返す。検出パターンが
+ *   `\d+(?:\.\d+)?` しか渡さないので実際には到達しないが、この関数を単体で
+ *   使うときは「null = 違反ではない」であって「null = 妥当な値」ではない。
+ */
+export function resolveSpacingStep(step) {
+  const value = Number.parseFloat(step);
+  if (!Number.isFinite(value)) return null;
+  if (FIGMA_SPACING_STEPS.has(value)) return null;
+
+  const px = value * TAILWIND_STEP_PX;
+  const below = FIGMA_SPACING_PX.filter((p) => p < px);
+  const above = FIGMA_SPACING_PX.filter((p) => p > px);
+  return {
+    px,
+    lower: below.length ? Math.max(...below) : null,
+    upper: above.length ? Math.min(...above) : null,
+  };
+}
+
+/** px を Tailwind のステップ表記に戻す（`16` → `"4"`, `2` → `"0.5"`）。 */
+export function pxToStep(px) {
+  return String(px / TAILWIND_STEP_PX);
+}

package/lib/stop-hook.js

@@ -1,5 +1,5 @@
 import fs from 'fs';
-import { checkProject } from './check.js';
+import { countBySeverity, runCheck } from './check.js';
 
 /**
  * AI assistant の Stop / stop hook 用エントリポイント。
@@ -32,17 +32,55 @@ export async function runStopHook(target) {
   }
 
   const targets = target ? [target] : [];
-  const hasFindings = await checkProject(targets, { strict: true, format: 'text' });
+  const { report, blocked } = await runCheck(targets, { strict: true, format: 'text' });
+
+  if (blocked) {
+    // ブロック理由は「error の findings」と「実行に失敗して未検査のルール」の
+    // 2 系統ある。後者のとき「findings を修正してください」とだけ書くと、
+    // 存在しない findings を AI が探し始めるので理由を書き分ける。
+    // en: Blocking has two causes — error findings and rules that failed to run.
+    // Say which, or the AI hunts for findings that don't exist.
+    const skipped = report.skippedRules ?? [];
+    const errorCount = countBySeverity(report.findings).error;
+    const reasons = [];
+    if (errorCount > 0) reasons.push(`severity=error の findings ${errorCount} 件`);
+    if (skipped.length > 0) {
+      reasons.push(
+        `実行に失敗して未検査のルール ${skipped.length} 件（${skipped.map((s) => s.ruleId).join(', ')}）`
+      );
+    }
 
-  if (hasFindings) {
     process.stderr.write(
-      '\nsparkle-design-cli stop-hook: findings を検出したため応答終了を 1 度だけブロックしました。' +
-        '上記の findings を修正するか、対応しない判断であればユーザーに確認してから再度応答を完了してください。' +
-        ' / Blocked once because findings were detected. Fix them or confirm with the user before completing the response again.\n'
+      `\nsparkle-design-cli stop-hook: ${reasons.join(' と ')} を検出したため応答終了を 1 度だけブロックしました。` +
+        (errorCount > 0
+          ? '上記の findings を修正するか、対応しない判断であればユーザーに確認してください。'
+          : '') +
+        (skipped.length > 0
+          ? 'ルールの実行失敗は検査自体が行われていないことを意味します。プラグインの不具合の可能性があるためユーザーに報告してください（findings を探す必要はありません）。'
+          : '') +
+        ` / Blocked once: ${reasons.join(' and ')}.\n`
     );
     return 2;
   }
 
+  // exit 0 の hook の stdout は AI に渡らない（Claude Code がフィードバックとして
+  // 読むのは exit 2 の stderr のみ）。warning / info は設計上ブロックしないので、
+  // このままだと printTextReport が出した移行ガイドが誰にも読まれずに消える。
+  // ブロックはせず、要約だけ stderr に出して人間の目に留まるようにする。
+  // 詳細は `sparkle-design-cli check --format json` で取得できる。
+  // en: A hook exiting 0 has its stdout dropped, so non-blocking findings would
+  // vanish. Emit a short summary on stderr instead of escalating to exit 2.
+  const counts = countBySeverity(report.findings);
+  const nonBlocking = counts.warning + counts.info;
+  if (nonBlocking > 0) {
+    process.stderr.write(
+      `\nsparkle-design-cli stop-hook: ブロックしない findings が ${nonBlocking} 件あります` +
+        `（warning ${counts.warning} / info ${counts.info}）。` +
+        '詳細は `npx --yes sparkle-design-cli check src --format json` で確認できます。' +
+        ` / ${nonBlocking} non-blocking finding(s); run check --format json for details.\n`
+    );
+  }
+
   return 0;
 }