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

package/lib/rules-report.js

@@ -0,0 +1,216 @@
+/**
+ * `sparkle-design-cli rules` の実装。
+ *
+ * ## なぜコマンドなのか
+ *
+ * ルール一覧はこれまで README / `check --help` / internal の setup-guide /
+ * コンポーネントの JSDoc / スキルの features.md と 6 箇所に写しが散らばっていて、
+ * 実際に `check --help` は組み込み 18 件のうち 16 件しか載せておらず、しかも
+ * `check` のルールではない項目を 2 件含んだまま腐っていた。
+ *
+ * それ以上に本質的なのは、**静的なドキュメントには「有効なルール」を書けない**
+ * ということ。プラグインはコンシューマの package.json から自動発見されるので、
+ * 実際に効いているルールはプロジェクトごとに違う。組み込み 18 件を列挙した
+ * ドキュメントは、プラグインを入れた利用者にとって最初から不正確になる。
+ *
+ * en: The rule list used to be copied into six places and had already rotted.
+ * More fundamentally, static docs cannot state which rules are *active* — plugins
+ * are discovered from the consumer's package.json, so the effective set differs
+ * per project. This command is the only place that can answer that.
+ */
+
+import {
+  BUILTIN_ANTI_PATTERN_GROUPS,
+  RULE_TARGET,
+  SEVERITY,
+  getCheckRules,
+} from './anti-pattern-rules.js';
+import { loadAntiPatternPlugins } from './load-plugins.js';
+
+/** 利用者の手元に `docs/` は無いので、案内は解決できる場所を指す。 */
+const DOCS_URL = 'https://github.com/goodpatch/sparkle-design-cli/blob/main/docs';
+
+/** 表示順。`check` のレポートと同じ「重いものが先」に揃える。 */
+const SEVERITY_ORDER = [SEVERITY.ERROR, SEVERITY.WARNING, SEVERITY.INFO];
+
+const SEVERITY_NOTE = {
+  [SEVERITY.ERROR]: '例外なし。--strict / stop-hook を失敗させる',
+  [SEVERITY.WARNING]: '原則ダメだが理由があれば例外可。exit code は変えない',
+  [SEVERITY.INFO]: '参考。従わなくてもよい選択肢',
+};
+
+/**
+ * 組み込み + プラグインのルールを集める。
+ *
+ * プラグイン由来かどうかを `source` に持たせる。利用者が「なぜこのルールが
+ * 出るのか」を追えるようにするためで、これが分からないと組み込みの不具合と
+ * プラグインの不具合を切り分けられない。
+ */
+export async function collectActiveRules(options = {}) {
+  // cwd を受けるのはテストのためだけではない。プラグインは**そのディレクトリの**
+  // package.json から発見されるので、どこを見たかで結果が変わる。既定は
+  // loadAntiPatternPlugins 側の既定（process.cwd()）に委ねる。
+  // en: The discovered set depends on which directory is inspected.
+  const { groups: pluginGroups, discovered } = await loadAntiPatternPlugins(
+    options.cwd ? { cwd: options.cwd } : undefined
+  );
+
+  // 出所は**結合前**に決める。結合後に ID で引き当てる方式だと、プラグインが
+  // 組み込みと同じ ID を名乗ったときに両方が builtin として表示され、
+  // 「見慣れないルールが出た」ときの切り分けができなくなる。ID の重複は
+  // getCheckRules も check 側も弾かない（両方のルールが実際に動く）ので、
+  // ここで潰さず、出所を正しく付けたうえで衝突として見せる。
+  // en: Derive the origin before merging. Looking it up by id afterwards would
+  // label a plugin rule that reuses a built-in id as `builtin`, defeating the
+  // whole point of the field. Duplicate ids are not rejected anywhere — both
+  // rules really run — so surface the clash instead of hiding it.
+  const shape = (source) => (rule) => ({
+    id: rule.id,
+    severity: rule.severity,
+    description: rule.description,
+    targets: rule.targets,
+    source,
+  });
+
+  const rules = [
+    ...getCheckRules(BUILTIN_ANTI_PATTERN_GROUPS).map(shape('builtin')),
+    ...getCheckRules(pluginGroups).map(shape('plugin')),
+  ];
+
+  // 各プラグインが実際に出した rule は、**そのプラグインの group から直接**求める。
+  // 「全 rule の中に同じ id があるか」で絞ると、`check` を持たない group の id が
+  // 組み込みや別プラグインの rule id と衝突したときに、そのプラグインが所有して
+  // いない ID を並べてしまう（`check` は plugin-api で optional なので実際に起きる）。
+  // en: Derive each plugin's rule ids from its own groups. Matching against the
+  // merged list would attribute a built-in (or another plugin's) rule to a plugin
+  // whose `check`-less group merely reuses that id.
+  // 所有関係はローダーが持つ `record.groups`（group の実体）から取る。
+  // ID で引き直すと、別プラグインが同じ group ID を宣言したときに互いの分まで
+  // 拾ってしまう（実測で両方が 2 件ずつ持つ状態になった）。
+  // en: Ownership comes from the loader's group objects. Re-deriving it from ids
+  // credits each plugin with the other's rules when two declare the same id.
+  const plugins = discovered.map((record) => ({
+    ...record,
+    ruleIds: getCheckRules(record.groups ?? []).map((rule) => rule.id),
+  }));
+
+  return { rules, plugins };
+}
+
+function severityRank(severity) {
+  const index = SEVERITY_ORDER.indexOf(severity);
+  return index === -1 ? SEVERITY_ORDER.length : index;
+}
+
+function sortForDisplay(rules) {
+  return [...rules].sort(
+    (a, b) => severityRank(a.severity) - severityRank(b.severity) || a.id.localeCompare(b.id)
+  );
+}
+
+/** `--format json` の出力。CI や AI から読む前提なので件数の内訳も添える。 */
+export function renderRulesJson({ rules, plugins }) {
+  const counts = Object.fromEntries(
+    SEVERITY_ORDER.map((severity) => [
+      severity,
+      rules.filter((r) => r.severity === severity).length,
+    ])
+  );
+  return JSON.stringify(
+    {
+      summary: {
+        ruleCount: rules.length,
+        duplicateIds: [
+          ...new Set(
+            rules
+              .filter((rule, i) => rules.findIndex((r) => r.id === rule.id) !== i)
+              .map((r) => r.id)
+          ),
+        ],
+        severityCounts: counts,
+        builtinCount: rules.filter((r) => r.source === 'builtin').length,
+        pluginCount: rules.filter((r) => r.source === 'plugin').length,
+      },
+      rules: sortForDisplay(rules),
+      plugins: plugins.map((record) => ({
+        packageName: record.packageName,
+        status: record.status,
+        error: record.error ?? null,
+        // `ruleIds` は collectActiveRules がプラグインごとに算出したもの
+        // （`check` を持つ group だけ）。`groupIds` は宣言した group 全部。
+        // en: `ruleIds` counts only groups that actually define a check.
+        ruleIds: record.ruleIds ?? [],
+        groupIds: record.groupIds ?? [],
+      })),
+    },
+    null,
+    2
+  );
+}
+
+/** 既定のテキスト出力。 */
+export function renderRulesText({ rules, plugins }) {
+  const lines = [];
+  const sorted = sortForDisplay(rules);
+
+  lines.push(`有効なルール: ${sorted.length} 件`);
+
+  for (const severity of SEVERITY_ORDER) {
+    const group = sorted.filter((rule) => rule.severity === severity);
+    if (group.length === 0) continue;
+    lines.push('', `[${severity}] ${group.length} 件 — ${SEVERITY_NOTE[severity]}`);
+    for (const rule of group) {
+      // `.css` も見るルールは既定と違うので明示する。どのファイルが検査対象か
+      // 分からないと「なぜ検出されないのか」を利用者が追えない。
+      const css = rule.targets?.includes(RULE_TARGET.CSS) ? ' (.css も検査)' : '';
+      const from = rule.source === 'plugin' ? ' [plugin]' : '';
+      lines.push(`  ${rule.id}${from}${css}`);
+      lines.push(`    ${rule.description}`);
+    }
+  }
+
+  const clashes = [
+    ...new Set(
+      rules.filter((rule, i) => rules.findIndex((r) => r.id === rule.id) !== i).map((r) => r.id)
+    ),
+  ];
+  if (clashes.length > 0) {
+    // 衝突は「組み込み × プラグイン」だけでなく「プラグイン同士」でも起きる
+    // （plugin-api が名前空間を共有すると明記している）。source を見ずに
+    // 「組み込みと同じ」と決め打つと、後者で嘘の案内になる。
+    // en: Clashes also happen plugin-vs-plugin; don't assume a built-in is involved.
+    lines.push('');
+    for (const id of clashes) {
+      const sources = rules.filter((rule) => rule.id === id).map((rule) => rule.source);
+      const kind = sources.includes('builtin') ? '組み込みと同じ ID' : 'プラグイン同士で同じ ID';
+      lines.push(`⚠️  ${kind}のルールがあります: ${id}（${sources.join(' + ')}）`);
+    }
+    lines.push('    どちらも実行されます。指摘の出所が分からなくなるので ID を変えてください。');
+  }
+
+  lines.push('');
+  if (plugins.length === 0) {
+    lines.push('プラグイン: なし（組み込みルールのみ）');
+  } else {
+    lines.push('プラグイン:');
+    for (const record of plugins) {
+      const status = record.status === 'loaded' ? 'ok' : `error: ${record.error}`;
+      lines.push(`  - ${record.packageName} (${status})`);
+    }
+  }
+  lines.push('');
+  // 利用者の cwd に `docs/` は無い。npm 同梱の実体か GitHub を指す。
+  // en: `docs/` doesn't exist in the consumer's cwd — point at the real locations.
+  lines.push(
+    `個別ルールの背景と対処: ${DOCS_URL}/anti-patterns.md` +
+      '（npm 経由なら node_modules/sparkle-design-cli/docs/anti-patterns.md）'
+  );
+  lines.push('抑制するには `sparkle-disable-next-line <rule-id>` を使います。');
+
+  return lines.join('\n');
+}
+
+export async function runRules(options = {}) {
+  const collected = await collectActiveRules(options);
+  console.log(options.format === 'json' ? renderRulesJson(collected) : renderRulesText(collected));
+}

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,7 @@
 import fs from 'fs';
-import { checkProject } from './check.js';
+
+import { DEFAULT_TARGET, countBySeverity, runCheck } from './check.js';
+import { resolveTargetBaseDir } from './path-utils.js';
 
 /**
  * AI assistant の Stop / stop hook 用エントリポイント。
@@ -14,10 +16,21 @@ import { checkProject } from './check.js';
  * 抜ける。これで「最初の 1 回だけ exit 2 で停止をブロックして findings
  * を通知し、以降はユーザーの判断に委ねる」フローになる。
  *
+ * 相対 path は cwd で解決できなければ**プロジェクトルート基準で解決し直す**。
+ * hook は AI の作業途中に発火するため、AI が調査で `cd` したまま戻していない
+ * ケースが普通に起きる（issue #85）。cwd を最優先で試すので、今まで動いていた
+ * 呼び出しの挙動は変わらない。`check` サブコマンドは人間が直接叩くものなので
+ * 従来どおり cwd 基準のみで、この救済は stop-hook 限定。
+ *
  * en: Run `check --strict` once per session to surface findings, but stop
  * blocking on subsequent invocations within the same Stop hook chain.
  * 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).
+ * Relative targets fall back to the project root when cwd cannot resolve them,
+ * because hooks fire mid-session when the shell may sit in a subdirectory.
+ *
+ * @param {string | string[]} [target] lint 対象 path（複数可）
+ * @returns {Promise<0 | 2>} hook の exit code
  */
 export async function runStopHook(target) {
   const payload = readStdinJsonSafely();
@@ -31,21 +44,159 @@ export async function runStopHook(target) {
     return 0;
   }
 
-  const targets = target ? [target] : [];
-  const hasFindings = await checkProject(targets, { strict: true, format: 'text' });
+  const targets = normalizeTargets(target);
+  const restoreCwd = enterTargetBaseDir(targets);
+
+  let result;
+  try {
+    result = await runCheck(targets, { strict: true, format: 'text' });
+  } finally {
+    // check が throw しても cwd は必ず戻す。runStopHook は bin から呼ばれて
+    // すぐ process.exit する経路が主だが、テストや将来の埋め込み利用で
+    // プロセスが生き続ける場合に cwd を汚したままにしない。
+    // en: Always restore cwd, even when the check throws.
+    restoreCwd();
+  }
+  const { report, blocked } = result;
+
+  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;
 }
 
+/**
+ * hook に渡された lint 対象を配列に正規化する。
+ *
+ * 2.5.0-beta.1 までは `bin/sparkle-design.js` が `args[1]` しか渡しておらず、
+ * 実運用で見られる `stop-hook apps/web/app apps/web/components` の**2つ目以降が
+ * 黙って未検査**になっていた（issue #85 の調査で判明）。無指定なら `runCheck`
+ * 側の既定 target（`src`）に委ねるので、空配列をそのまま返す。
+ *
+ * en: Accept multiple targets. Before this, only the first positional arg was
+ * forwarded, so extra paths in a hook command were silently never checked.
+ */
+function normalizeTargets(target) {
+  const list = Array.isArray(target) ? target : [target];
+  return list
+    .filter((value) => typeof value === 'string' && value.trim())
+    .map((value) => value.trim());
+}
+
+/**
+ * target が実在する基準ディレクトリへ `chdir` し、元に戻す関数を返す。
+ *
+ * target path だけを解決し直すのでは足りない。`check` は cwd に依存する処理を
+ * 他にも持っているので、target だけずらすとそれらが元の cwd を見たままになる。
+ *
+ *   - **アンチパターンプラグインの discovery**（`loadAntiPatternPlugins` が
+ *     `cwd/package.json` の `sparkleCli.antiPatterns` を読む）。ここがずれると
+ *     「target は repo root のファイルを見ているのに、有効なルールは apps/web 基準」
+ *     という、**検査したのに一部のルールが効いていない**状態になる
+ *   - Next.js の CSP 設定検出（`cwd` から `next.config.*` を探す）
+ *   - レポートの相対 path 表示（`path.relative(process.cwd(), ...)`）
+ *
+ * cwd ごと合わせるのが最も整合的。
+ *
+ * `resolveTargetBaseDir` は cwd を最優先で試すので、**今まで通り動いていたケースは
+ * chdir されず挙動が変わらない**。移動したときだけ stderr に 1 行出す。黙って別の
+ * ディレクトリを検査していると、findings の差分を追うときに原因が分からなくなる。
+ *
+ * `process.chdir()` はプロセス全体の状態なので、**1 プロセスにつき 1 回だけ
+ * `runStopHook` を呼ぶ**ことが前提。`bin/sparkle-design.js` は subcommand を 1 つ
+ * 処理して `process.exit` するのでこの前提は満たされている。将来 `runStopHook` を
+ * ライブラリとして並行に呼ぶ用途が出たら、cwd を動かさずに基準ディレクトリを
+ * `runCheck` へ引数で渡す形（`check` 側の cwd 依存を全部剥がす）に作り替えること。
+ *
+ * en: chdir to the base where the targets actually exist, rather than only
+ * rebasing target paths — the check pipeline reads config, CSP settings and
+ * report paths from cwd too. cwd is tried first, so working setups don't move.
+ * chdir is process-global, so this assumes one runStopHook per process — true
+ * for the CLI, which exits right after. Concurrent library use would need the
+ * base directory threaded through runCheck instead.
+ */
+function enterTargetBaseDir(targets) {
+  const originalCwd = process.cwd();
+  // target 未指定なら check 側の既定 target で探る。ここで `src` を決め打ちすると
+  // 既定が変わったときに静かにズレるので、check.js の定数をそのまま使う。
+  // en: Probe with check's own default target instead of hardcoding 'src'.
+  const probe = targets.length > 0 ? targets : [DEFAULT_TARGET];
+  const { dir, source, resolved } = resolveTargetBaseDir(probe, { startDir: originalCwd });
+
+  if (!resolved || dir === originalCwd) return () => {};
+
+  try {
+    process.chdir(dir);
+  } catch (error) {
+    // chdir に失敗しても検査自体は続ける価値がある（従来どおり cwd 基準）。
+    // en: Fall back to cwd-relative behaviour instead of aborting the check.
+    process.stderr.write(
+      `sparkle-design-cli stop-hook: ${dir} へ移動できなかったため cwd 基準で検査します (${error.code ?? error.message})` +
+        ` / Could not chdir to the resolved base dir; falling back to cwd.\n`
+    );
+    return () => {};
+  }
+
+  process.stderr.write(
+    `sparkle-design-cli stop-hook: 実行時の cwd (${originalCwd}) では ${probe.join(' / ')} が見つからないため、` +
+      `${dir} 基準で検査します（${source} から判定）。` +
+      ` / Resolved relative targets against ${dir} instead of cwd.\n`
+  );
+
+  return () => {
+    try {
+      process.chdir(originalCwd);
+    } catch {
+      // 元の cwd が消えている場合まで面倒は見ない。
+      // en: Ignore — the original cwd may no longer exist.
+    }
+  };
+}
+
 function readStdinJsonSafely() {
   // stdin が tty / 空 / 非 JSON の場合は「初回呼び出し」として扱う。
   // en: Treat missing or non-JSON stdin as a first invocation.