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

package/lib/stop-hook.js

@@ -1,5 +1,7 @@
 import fs from 'fs';
-import { countBySeverity, runCheck } 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 { countBySeverity, runCheck } 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,8 +44,20 @@ export async function runStopHook(target) {
     return 0;
   }
 
-  const targets = target ? [target] : [];
-  const { report, blocked } = await runCheck(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」と「実行に失敗して未検査のルール」の
@@ -84,6 +109,94 @@ export async function runStopHook(target) {
   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.

package/lib/token-migration.js

@@ -606,6 +606,216 @@ export function buildLegacyCssVarPattern() {
   );
 }
 
+// --- Tailwind 既定パレット -> Sparkle セマンティックトークン ------------------
+
+/**
+ * Tailwind 既定パレットのファミリー → Sparkle の意味ファミリー。
+ *
+ * Sparkle のプリミティブは Tailwind の同名変数をそのまま参照している
+ * （`--color-neutral-600: var(--color-gray-600)` / `--color-negative-600:
+ * var(--color-red-600)` など）。そのため `gray` / `red` / `green` / `yellow` /
+ * `blue` の 5 系統は**値が完全に一致する**ので、置き換えても見た目が変わらない。
+ * それ以外（`slate` / `zinc` / `emerald` …）は近いだけで色味が変わるため、
+ * 自動変換可とは扱わず必ず要判断にする。
+ *
+ * - `family`: 対応する旧セマンティックファミリー。`null` は対応する意味が無い
+ * - `exact`: Sparkle のプリミティブが同じ値を指しているか
+ * - `ambiguousWith`: 用途上もう一方の意味も有力な場合（ブランド色かどうかは
+ *   コードからは判断できないため、候補を両方出して人に選ばせる）
+ *
+ * `neutral` は**意図的に載せていない**。Tailwind の既定パレットにも Sparkle の
+ * 旧セマンティック層にも同名のファミリーがあり、`text-neutral-500` は
+ * `legacy-color-token` がすでに検出する。ここにも載せると同じ箇所が 2 回報告される。
+ * en: `neutral` is deliberately absent — it collides with Sparkle's own legacy
+ * family name and is already covered by `legacy-color-token`.
+ *
+ * `gray` を `neutral` ではなく `base` に寄せているのは、`base` が「gray と同値」
+ * かつ surface では Figma 専用の `surface/base/*`（ページ地）が優先されるため。
+ * text / border / object には `base` が無いので `neutral` に自動フォールバックする
+ * （`familyScaleMap` 参照）。
+ */
+export const TAILWIND_PALETTE_FAMILIES = {
+  // 値まで一致する系統
+  gray: { family: 'base', exact: true },
+  red: { family: 'negative', exact: true },
+  green: { family: 'success', exact: true },
+  yellow: { family: 'warning', exact: true },
+  blue: { family: 'info', exact: true, ambiguousWith: 'primary' },
+  // 意味は同じだが色味が変わる系統
+  slate: { family: 'base', exact: false },
+  zinc: { family: 'base', exact: false },
+  stone: { family: 'base', exact: false },
+  rose: { family: 'negative', exact: false },
+  emerald: { family: 'success', exact: false },
+  teal: { family: 'success', exact: false },
+  lime: { family: 'success', exact: false },
+  amber: { family: 'warning', exact: false },
+  orange: { family: 'warning', exact: false },
+  sky: { family: 'info', exact: false, ambiguousWith: 'primary' },
+  cyan: { family: 'info', exact: false, ambiguousWith: 'primary' },
+  indigo: { family: 'info', exact: false, ambiguousWith: 'primary' },
+  // 対応する意味が無い系統
+  violet: { family: null },
+  purple: { family: null },
+  fuchsia: { family: null },
+  pink: { family: null },
+};
+
+/**
+ * Tailwind v4 のパレットは 950 まである。Sparkle の旧セマンティック層は 900 止まり
+ * なので、950 は機械的な対応先が無い（要判断として報告する）。
+ */
+const TAILWIND_ONLY_LEVELS = ['950'];
+const TAILWIND_PALETTE_LEVELS = [...LEGACY_LEVELS, ...TAILWIND_ONLY_LEVELS];
+
+/**
+ * `bg-gray-50` / `hover:text-red-600/50` のような Tailwind 既定パレットの
+ * 色ユーティリティを検出する正規表現。
+ *
+ * `legacy-color-token` の `buildLegacyScalePattern` と同じ境界・variant・modifier
+ * の扱いを共有する（`\b` ではなく `[\w-]` 境界を使う理由は同関数のコメント参照）。
+ */
+export function buildTailwindPalettePattern() {
+  const prefixes = alternation(Object.keys(UTILITY_PREFIX_TO_CATEGORY));
+  const families = alternation(Object.keys(TAILWIND_PALETTE_FAMILIES));
+  const levels = alternation(TAILWIND_PALETTE_LEVELS);
+  return new RegExp(
+    `${NOT_CLASS_CHAR_BEFORE}${VARIANT_CHAIN}${IMPORTANT_PREFIX}(?:${prefixes})-(?:${families})-(?:${levels})${NOT_CLASS_CHAR_AFTER}${MODIFIER_SUFFIX}`,
+    'g'
+  );
+}
+
+/**
+ * Tailwind 既定パレットのユーティリティ 1 個を解析して移行結果を返す。
+ *
+ * 旧セマンティックファミリーに読み替えてから `resolveLegacyUtility` に委譲する。
+ * 対応表・状態の絞り込み・opacity modifier の持ち回りを二重に実装せずに済み、
+ * `legacy-color-token` と同じ移行先を必ず案内できる。
+ *
+ * ただし classification は**そのまま通さない**。
+ * - 値が一致しない系統（`slate` など）は見た目が変わるので必ず `review`
+ * - `info` / `primary` のどちらとも読める系統（`blue` など）は、ブランド色かどうかが
+ *   コードから判断できないので候補を両方出して `review`
+ *
+ * en: Rewrite the Tailwind family to Sparkle's legacy family and delegate, so the
+ * mapping table, state narrowing and modifier handling are never duplicated.
+ * Classification is downgraded to `review` whenever the swap is not value-preserving
+ * or the semantic (info vs primary) cannot be decided from the code.
+ *
+ * @param {string} utility 例 `bg-gray-50` / `hover:text-red-600/50`
+ * @returns {null | { input: string, classification: string, replacement?: string, candidates?: string[], reason?: string }}
+ */
+export function resolveTailwindPaletteUtility(utility) {
+  if (typeof utility !== 'string' || utility.length === 0) return null;
+
+  const lastColon = utility.lastIndexOf(':');
+  const variantPrefix = lastColon === -1 ? '' : utility.slice(0, lastColon + 1);
+  let rawBare = lastColon === -1 ? utility : utility.slice(lastColon + 1);
+
+  const importantPrefix = rawBare.startsWith('!') ? '!' : '';
+  if (importantPrefix) rawBare = rawBare.slice(1);
+
+  const [, bare, modifier] = MODIFIER_SUFFIX_PATTERN.exec(rawBare);
+
+  const dashIndex = bare.indexOf('-');
+  if (dashIndex === -1) return null;
+  const prefix = bare.slice(0, dashIndex);
+  const rest = bare.slice(dashIndex + 1);
+  if (!UTILITY_PREFIX_TO_CATEGORY[prefix]) return null;
+
+  const scaleMatch = /^([a-z]+)-(\d{2,3})$/.exec(rest);
+  if (!scaleMatch) return null;
+  const [, paletteFamily, level] = scaleMatch;
+
+  const mapping = TAILWIND_PALETTE_FAMILIES[paletteFamily];
+  if (!mapping || !TAILWIND_PALETTE_LEVELS.includes(level)) return null;
+
+  const wrap = (result) => ({ input: utility, ...result });
+
+  if (!mapping.family) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      reason:
+        `${paletteFamily} に対応する意味のトークンが Sparkle にありません。` +
+        'Figma の該当箇所を見て用途（surface / text / border / object）から選び直してください。' +
+        '装飾目的の面であれば surface-accent-1 / 2 / 3 が候補になります。',
+    });
+  }
+
+  if (TAILWIND_ONLY_LEVELS.includes(level)) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      reason:
+        `Tailwind の ${level} に対応するレベルが Sparkle にありません（Sparkle は 900 まで）。` +
+        `${paletteFamily}-900 相当で足りるかを Figma で確認してください。`,
+    });
+  }
+
+  const delegate = (family) =>
+    resolveLegacyUtility(
+      `${variantPrefix}${importantPrefix}${prefix}-${family}-${level}${modifier}`
+    );
+
+  const primary = delegate(mapping.family);
+  if (!primary) return null;
+
+  // 用途上どちらの意味とも読める系統は、候補を両方並べて人に選ばせる。
+  // en: Surface both semantics when the code cannot tell brand colour from status.
+  if (mapping.ambiguousWith) {
+    const sides = [
+      { family: mapping.family, result: primary },
+      { family: mapping.ambiguousWith, result: delegate(mapping.ambiguousWith) },
+    ];
+    // 片側に該当トークンが無いことがある（例: surface の info には 600 が無い）。
+    // 候補を並べただけでは「なぜ片方しか出ないのか」が分からず、AI が
+    // 残った候補を唯一の正解と誤解するので、欠けている側を明示する。
+    // en: One side can have no matching token; say so, or the remaining
+    // candidate reads as the single correct answer.
+    const missing = sides.filter((side) => toCandidateList(side.result).length === 0);
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      candidates: sides.flatMap((side) => toCandidateList(side.result)),
+      reason:
+        `${paletteFamily} は「${mapping.family}（状態・意味を表す色）」とも「${mapping.ambiguousWith}（ブランド色）」とも読めます。` +
+        'どちらの用途かはコードから判断できないため、Figma の該当箇所を見て選んでください。' +
+        (missing.length > 0
+          ? `${missing.map((side) => side.family).join(' / ')} 側には対応するトークンがありません。`
+          : '') +
+        (mapping.exact ? '' : `なお ${paletteFamily} と Sparkle の色は完全には一致しません。`),
+    });
+  }
+
+  if (!mapping.exact) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      candidates: toCandidateList(primary),
+      reason:
+        `${paletteFamily} は Sparkle の ${mapping.family} に意味は対応しますが、色が完全には一致しません（置き換えると見た目が変わります）。` +
+        'Figma の該当箇所で意図した色かを確認してください。' +
+        (primary.reason ? ` ${primary.reason}` : ''),
+    });
+  }
+
+  // 値が一致する系統は、旧トークンからの移行と同じ確度で案内できる。
+  // en: Value-identical families keep the delegated classification as-is.
+  return wrap({
+    classification: primary.classification,
+    replacement: primary.replacement,
+    candidates: primary.candidates,
+    reason: primary.reason,
+  });
+}
+
+/**
+ * `resolveLegacyUtility` の戻り値を候補リストに正規化する。
+ * en: Flatten a delegated result into a candidate list.
+ */
+function toCandidateList(result) {
+  if (!result) return [];
+  if (result.replacement) return [result.replacement];
+  return result.candidates ?? [];
+}
+
 /**
  * CSS 変数名 1 個を解析して移行結果を返す。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.5.0-beta.1",
+  "version": "2.5.0-beta.3",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -19,10 +19,10 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "test:watch": "node --test --watch test/*.test.js",
-    "lint": "eslint bin/ lib/ test/",
-    "lint:fix": "eslint bin/ lib/ test/ --fix",
-    "format": "prettier --write bin/ lib/ test/ *.md *.json",
-    "format:check": "prettier --check bin/ lib/ test/ *.md *.json",
+    "lint": "eslint bin/ lib/ scripts/ test/",
+    "lint:fix": "eslint bin/ lib/ scripts/ test/ --fix",
+    "format": "prettier --write bin/ lib/ scripts/ test/ docs/ \"*.md\" \"*.json\"",
+    "format:check": "prettier --check bin/ lib/ scripts/ test/ docs/ \"*.md\" \"*.json\"",
     "sync:anti-pattern-docs": "node scripts/sync-anti-pattern-docs.mjs"
   },
   "keywords": [