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

package/lib/migrate.js

@@ -0,0 +1,460 @@
+import fs from 'fs';
+import path from 'path';
+
+import { collectDeclaredCustomProperties, maskBlockComments } from './anti-pattern-rules.js';
+import { DEFAULT_TARGET, collectFiles, isSuppressed } from './check.js';
+import {
+  MIGRATION_CLASS,
+  buildDeprecatedAliasPattern,
+  buildLegacyCssVarPattern,
+  buildLegacyScalePattern,
+  buildLegacyTokenPattern,
+  resolveLegacyCssVar,
+  resolveLegacyUtility,
+} from './token-migration.js';
+
+/**
+ * `migrate` サブコマンド本体（goodpatch/sparkle-design-cli#73）。
+ *
+ * 旧セマンティックトークンを新トークンへ書き換える。対応表は持たず、
+ * `lib/token-migration.js` の検出パターンと resolver をそのまま使う
+ * （`check` の移行ルールと同じ入口なので、check が案内する移行先と
+ * migrate が書き換える移行先が食い違うことがない）。
+ *
+ * 分類ごとの扱い:
+ * - `auto`       … `--write` のときだけ置換する
+ * - `review`     … 候補を列挙して報告するだけ。置換しない
+ * - `structural` … 該当箇所を指摘するだけ。置換しない
+ *
+ * 既定は dry-run（不可逆操作をデフォルトにしない）。
+ * en: The `migrate` subcommand. Reuses token-migration.js patterns/resolvers
+ * (no mapping table of its own). Only `auto` hits are rewritten, and only with
+ * `--write`; `review` / `structural` are reported and never touched.
+ */
+
+/**
+ * 検出パターン × resolver の組。`ruleId` は対応する `check` のルール ID で、
+ * `sparkle-disable-line <ruleId>` の抑制コメントを migrate でも尊重するために使う
+ * （check の誤検出を抑制した箇所を migrate が黙って書き換えると、抑制した意味が無くなる）。
+ * en: Pattern/resolver pairs. `ruleId` is the matching `check` rule so that
+ * suppression comments written for `check` are honoured by `migrate` too.
+ */
+export const MIGRATION_SOURCES = [
+  {
+    ruleId: 'legacy-color-token',
+    pattern: buildLegacyScalePattern(),
+    resolve: resolveLegacyUtility,
+  },
+  {
+    ruleId: 'legacy-color-token',
+    pattern: buildLegacyTokenPattern(),
+    resolve: resolveLegacyUtility,
+  },
+  {
+    ruleId: 'legacy-color-var',
+    pattern: buildLegacyCssVarPattern(),
+    resolve: resolveLegacyCssVar,
+  },
+  {
+    ruleId: 'deprecated-radius-alias',
+    pattern: buildDeprecatedAliasPattern(),
+    resolve: resolveLegacyCssVar,
+  },
+];
+
+const CLASSIFICATION_LABELS = {
+  [MIGRATION_CLASS.AUTO]: '自動変換可',
+  [MIGRATION_CLASS.REVIEW]: '要判断',
+  [MIGRATION_CLASS.STRUCTURAL]: '構造変更あり',
+};
+
+function lineNumberAt(content, index) {
+  return content.slice(0, index).split(/\r?\n/).length;
+}
+
+/**
+ * resolver の戻り値を migrate の分類に正規化する。
+ *
+ * 書き換えてよいのは「`auto` かつ置換先が文字列で得られている」ものだけ。
+ * それ以外（未知の分類・置換先が無い auto・解決できなかった hit）は、黙って
+ * 捨てずに `review` として表に出す。check の migrationMatcher と同じ fail-loud 方針。
+ * en: Only `auto` with a string replacement may be rewritten. Anything else is
+ * surfaced as `review` rather than dropped — same fail-loud policy as `check`.
+ */
+function normalizeResolution(text, resolved) {
+  if (!resolved) {
+    return {
+      classification: MIGRATION_CLASS.REVIEW,
+      reason:
+        '旧トークンとして検出しましたが移行先を解決できませんでした。' +
+        'sparkle-design-cli の検出パターンと対応表がずれている可能性があります（issue 報告をお願いします）。',
+    };
+  }
+  const { classification, replacement, candidates, reason } = resolved;
+  if (classification === MIGRATION_CLASS.AUTO) {
+    if (typeof replacement === 'string' && replacement.length > 0 && replacement !== text) {
+      return { classification, replacement, reason };
+    }
+    return {
+      classification: MIGRATION_CLASS.REVIEW,
+      candidates,
+      reason: reason ?? '自動変換可と判定されましたが置換先が得られませんでした。',
+    };
+  }
+  if (classification === MIGRATION_CLASS.STRUCTURAL) {
+    return { classification, candidates, replacement, reason };
+  }
+  return { classification: MIGRATION_CLASS.REVIEW, candidates, replacement, reason };
+}
+
+/**
+ * マッチ位置がクラス名ではなく、パス・import specifier・`url()` の一部に見えるか。
+ *
+ * 検出パターンはファイル全体への正規表現なので、`url('/img/fill-primary-600.svg')`
+ * や `import './bg-primary-600.js'` のようなクラス以外の文字列にもマッチする。
+ * check では warning として報告するだけなので害は小さいが、migrate の `--write` で
+ * 置換すると資産パスや import が壊れる。書き換えを「クラス名として現れているもの」
+ * に限定するための、migrate だけの安全側ガード（check の検出挙動は変えない）。
+ * 該当したものは黙って捨てず、review として報告に残す。
+ * en: Detection is a whole-file regex, so it also hits paths, import specifiers
+ * and url() contents. Rewriting those with --write would break assets/imports,
+ * so migrate demotes such hits to `review` (check's detection is unchanged).
+ *
+ * @returns {string | null} 該当する場合はその理由
+ */
+function nonClassContext(content, index, end) {
+  const before = content[index - 1] ?? '';
+  const after = content[end] ?? '';
+  const afterNext = content[end + 1] ?? '';
+  if (before === '/' || before === '.' || before === '\\') {
+    return 'パスや識別子の一部に見えます';
+  }
+  if ((after === '.' && /\w/.test(afterNext)) || after === '/' || after === '\\') {
+    return 'ファイルパスや識別子の一部に見えます';
+  }
+
+  const lineStart = content.lastIndexOf('\n', index - 1) + 1;
+  const lineBefore = content.slice(lineStart, index);
+
+  // `url(` が開いたまま閉じていない
+  const urlOpen = lineBefore.toLowerCase().lastIndexOf('url(');
+  if (urlOpen !== -1 && !lineBefore.slice(urlOpen).includes(')')) {
+    return '`url()` の中にあります';
+  }
+
+  // 囲んでいる文字列リテラルが import / require / @import の specifier か
+  let quoteIndex = -1;
+  for (let i = lineBefore.length - 1; i >= 0; i -= 1) {
+    if (lineBefore[i] === "'" || lineBefore[i] === '"' || lineBefore[i] === '`') {
+      quoteIndex = i;
+      break;
+    }
+  }
+  if (quoteIndex !== -1) {
+    const lead = lineBefore.slice(0, quoteIndex);
+    if (/(?:\bfrom|\bimport|@import|\brequire\s*\(|\bimport\s*\()\s*$/.test(lead)) {
+      return 'import / require の specifier の中にあります';
+    }
+  }
+  return null;
+}
+
+/**
+ * マッチに付いた modifier（`/…`）が Tailwind の opacity modifier らしい形か。
+ *
+ * token-migration.js の MODIFIER_BODY は `[A-Za-z0-9._%-]+` を許すため、
+ * `"text-neutral-900/data.json"` や `"bg-primary-600/icon.svg"` のようなパスの
+ * 先頭セグメントでは `/data.json` まで modifier として飲み込み、直後が `"` に
+ * なって nonClassContext のパス判定を抜ける。migrate では数値（`/50` `/12.5`）と
+ * 角括弧（`/[0.6]` `/[var(--x)]`）以外の modifier を review に落とす。
+ * check の検出には影響しない。
+ * en: The shared modifier body also swallows path tails like `/data.json`.
+ * Only numeric or bracketed modifiers are trusted for auto rewrites.
+ *
+ * @returns {string | null} 該当する場合はその理由
+ */
+function nonClassModifier(text) {
+  if (text.startsWith('--')) return null;
+  const bare = text.slice(text.lastIndexOf(':') + 1);
+  const slash = bare.indexOf('/');
+  if (slash === -1) return null;
+  const modifier = bare.slice(slash + 1).replace(/!$/, '');
+  if (/^\d+(?:\.\d+)?$/.test(modifier) || /^\[[^\]\s]*\]$/.test(modifier)) return null;
+  return `\`/${modifier}\` は opacity modifier ではなくパスの一部に見えます`;
+}
+
+/**
+ * 1 ファイル分の移行計画を立てる（ファイルには触らない）。
+ *
+ * - 行頭から始まるブロックコメントの中身は対象外（check と同じ）
+ * - そのファイル自身が宣言している CSS 変数への参照は対象外（生成物の定義側を書き換えない）
+ * - `sparkle-disable-line` / `sparkle-disable-next-line` で抑制された箇所は対象外
+ * - 複数パターンが同じ範囲に重なった場合は先に見つかった方だけを採る
+ * - パス・import specifier・`url()` の中の auto は review に落とす（`nonClassContext`）
+ *
+ * @param {string} content
+ * @param {{ sources?: typeof MIGRATION_SOURCES }} [options]
+ * @returns {Array<{ index: number, end: number, line: number, text: string, ruleId: string,
+ *   classification: string, replacement?: string, candidates?: string[], reason?: string }>}
+ */
+export function planFileMigration(content, options = {}) {
+  const sources = options.sources ?? MIGRATION_SOURCES;
+  const masked = maskBlockComments(content);
+  const declaredHere = collectDeclaredCustomProperties(masked);
+  const contentLines = content.split(/\r?\n/);
+
+  const items = [];
+  for (const source of sources) {
+    for (const match of masked.matchAll(source.pattern)) {
+      const text = match[0];
+      const index = match.index ?? 0;
+      if (text.startsWith('--') && declaredHere.has(text)) continue;
+      const line = lineNumberAt(content, index);
+      if (isSuppressed(source.ruleId, contentLines, line)) continue;
+      const end = index + text.length;
+      let resolution = normalizeResolution(text, source.resolve(text));
+      if (resolution.classification === MIGRATION_CLASS.AUTO) {
+        const context = nonClassModifier(text) ?? nonClassContext(content, index, end);
+        if (context) {
+          resolution = {
+            classification: MIGRATION_CLASS.REVIEW,
+            candidates: [resolution.replacement],
+            reason:
+              `${context}。クラス名ではない可能性があるため自動変換しません。` +
+              'クラス名として使っている箇所なら手で置き換えてください。',
+          };
+        }
+      }
+      items.push({ index, end, line, text, ruleId: source.ruleId, ...resolution });
+    }
+  }
+
+  items.sort((left, right) => left.index - right.index);
+  const accepted = [];
+  for (const item of items) {
+    const previous = accepted[accepted.length - 1];
+    if (previous && item.index < previous.end) continue;
+    accepted.push(item);
+  }
+  return accepted;
+}
+
+/**
+ * 計画のうち `auto` だけを適用した内容を返す。`review` / `structural` は触らない。
+ * 置換先は改行を含まないので、行番号は変わらない。
+ * en: Apply only `auto` items. Replacements never contain newlines, so line
+ * numbers are preserved.
+ */
+export function applyFileMigration(content, items) {
+  let output = content;
+  const autos = items
+    .filter((item) => item.classification === MIGRATION_CLASS.AUTO)
+    .sort((left, right) => right.index - left.index);
+  for (const item of autos) {
+    output = output.slice(0, item.index) + item.replacement + output.slice(item.end);
+  }
+  return output;
+}
+
+/**
+ * `--include` の glob を正規表現に変換する。対応する記法は `**` / `*` / `?` / `{a,b}`。
+ * Node の `path.matchesGlob` はバージョンによって使えないため自前で持つ。
+ * en: Minimal glob support (`**`, `*`, `?`, `{a,b}`) — `path.matchesGlob`
+ * is not available on every supported Node version.
+ */
+export function globToRegExp(glob) {
+  let pattern = '';
+  let braceDepth = 0;
+  const normalized = glob.replace(/\\/g, '/').replace(/^\.\//, '');
+  for (let i = 0; i < normalized.length; i += 1) {
+    const char = normalized[i];
+    if (char === '*') {
+      if (normalized[i + 1] === '*') {
+        const followedBySlash = normalized[i + 2] === '/';
+        pattern += followedBySlash ? '(?:.*/)?' : '.*';
+        i += followedBySlash ? 2 : 1;
+      } else {
+        pattern += '[^/]*';
+      }
+    } else if (char === '?') {
+      pattern += '[^/]';
+    } else if (char === '{') {
+      braceDepth += 1;
+      pattern += '(?:';
+    } else if (char === '}' && braceDepth > 0) {
+      braceDepth -= 1;
+      pattern += ')';
+    } else if (char === ',' && braceDepth > 0) {
+      pattern += '|';
+    } else {
+      pattern += char.replace(/[.+^$()|[\]\\]/g, '\\$&');
+    }
+  }
+  if (braceDepth > 0) {
+    throw new Error(`--include の { が閉じていません: ${glob}`);
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+// cwd の外を指定したときに `../../../..` が延々と並ぶと読めないので、
+// その場合だけ絶対パスで出す。
+// en: Fall back to the absolute path for targets outside cwd.
+function toReportPath(filePath, cwd) {
+  const relative = path.relative(cwd, filePath);
+  const shown = relative.startsWith('..') || path.isAbsolute(relative) ? filePath : relative;
+  return shown.split(path.sep).join('/');
+}
+
+/**
+ * 対象ファイルを集める。探索は `check` と同じ `collectFiles` を使う（既定 `src`、
+ * `node_modules` / `.git` は除外、`.js` `.jsx` `.ts` `.tsx` `.css`）。
+ * `--include` があれば、cwd からの相対パスがどれかの glob にマッチするものだけに絞る。
+ */
+function discoverFiles(targets, includes, cwd) {
+  const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
+  const textFiles = new Set();
+  const cssFiles = new Set();
+  const visited = new Set();
+  for (const target of resolvedTargets) {
+    collectFiles(path.resolve(cwd, target), textFiles, cssFiles, visited, true);
+  }
+  const matchers = includes.map(globToRegExp);
+  const allFiles = [...textFiles, ...cssFiles];
+  const files = allFiles.filter(
+    (filePath) =>
+      matchers.length === 0 || matchers.some((re) => re.test(toReportPath(filePath, cwd)))
+  );
+  if (matchers.length > 0 && allFiles.length > 0 && files.length === 0) {
+    // 探索したファイルが全部 --include で落ちた = 照合の基準を取り違えている可能性が高い
+    // en: Every discovered file was filtered out — most likely a cwd-relative mismatch.
+    console.warn(
+      `⚠️  --include にマッチするファイルがありません（探索したファイル: ${allFiles.length}）。` +
+        '--include は cwd からの相対パスで照合します（例: src/**/*.tsx）。'
+    );
+  }
+  return files.sort((left, right) =>
+    toReportPath(left, cwd).localeCompare(toReportPath(right, cwd))
+  );
+}
+
+/**
+ * 移行レポートを作る。`write: true` のときだけ auto を書き換える。
+ *
+ * @param {{ targets?: string[], includes?: string[], write?: boolean, cwd?: string }} options
+ */
+export function createMigrationReport(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const files = discoverFiles(options.targets ?? [], options.includes ?? [], cwd);
+  const write = options.write === true;
+
+  const results = [];
+  for (const filePath of files) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const items = planFileMigration(content);
+    if (items.length === 0) continue;
+    const migrated = applyFileMigration(content, items);
+    const changed = migrated !== content;
+    if (write && changed) {
+      fs.writeFileSync(filePath, migrated, 'utf8');
+    }
+    results.push({
+      filePath: toReportPath(filePath, cwd),
+      items,
+      diff: changed ? lineDiff(content, migrated) : [],
+      written: write && changed,
+    });
+  }
+
+  const count = (classification) =>
+    results.reduce(
+      (sum, result) =>
+        sum + result.items.filter((item) => item.classification === classification).length,
+      0
+    );
+
+  return {
+    write,
+    scannedFileCount: files.length,
+    results,
+    summary: {
+      auto: count(MIGRATION_CLASS.AUTO),
+      review: count(MIGRATION_CLASS.REVIEW),
+      structural: count(MIGRATION_CLASS.STRUCTURAL),
+      autoFileCount: results.filter((result) => result.diff.length > 0).length,
+      writtenFileCount: results.filter((result) => result.written).length,
+    },
+  };
+}
+
+function lineDiff(before, after) {
+  const beforeLines = before.split(/\r?\n/);
+  const afterLines = after.split(/\r?\n/);
+  const diff = [];
+  for (let i = 0; i < beforeLines.length; i += 1) {
+    if (beforeLines[i] !== afterLines[i]) {
+      diff.push({ line: i + 1, before: beforeLines[i], after: afterLines[i] });
+    }
+  }
+  return diff;
+}
+
+function describeItem(item) {
+  const label = CLASSIFICATION_LABELS[item.classification] ?? item.classification;
+  const parts = [`[${label}] ${item.line}: ${item.text}`];
+  if (item.candidates?.length) {
+    parts.push(`候補: ${item.candidates.join(' / ')}`);
+  } else if (item.replacement) {
+    parts.push(`→ ${item.replacement}`);
+  }
+  const head = parts.join(' ');
+  return item.reason ? `${head}\n      ${item.reason}` : head;
+}
+
+export function printMigrationReport(report, log = console.log) {
+  const mode = report.write ? '--write' : 'dry-run';
+  log(`Sparkle Design migrate（${mode}）`);
+  if (!report.write) {
+    log(
+      'ファイルは変更しません。[自動変換可] の箇所だけを書き換えるには --write を付けて実行してください。'
+    );
+  }
+  log('');
+
+  for (const result of report.results) {
+    log(result.filePath);
+    for (const entry of result.diff) {
+      log(`  @@ ${entry.line}`);
+      log(`  - ${entry.before.trim()}`);
+      log(`  + ${entry.after.trim()}`);
+    }
+    for (const item of result.items) {
+      if (item.classification === MIGRATION_CLASS.AUTO) continue;
+      log(`  ${describeItem(item)}`);
+    }
+    log('');
+  }
+
+  const { summary } = report;
+  log(
+    `検査したファイル: ${report.scannedFileCount} / ` +
+      `自動変換可: ${summary.auto} 件（${summary.autoFileCount} ファイル） / ` +
+      `要判断: ${summary.review} 件 / 構造変更あり: ${summary.structural} 件`
+  );
+  if (report.write) {
+    log(`書き換えたファイル: ${summary.writtenFileCount}`);
+  }
+  if (summary.review + summary.structural > 0) {
+    log(
+      '[要判断] と [構造変更あり] は書き換えていません。候補と Figma の該当箇所を見て手で直してください。'
+    );
+  }
+}
+
+/**
+ * @param {{ targets?: string[], includes?: string[], write?: boolean }} options
+ */
+export function runMigrate(options = {}) {
+  const report = createMigrationReport(options);
+  printMigrationReport(report);
+  return report;
+}

package/lib/token-migration.js

@@ -172,7 +172,9 @@ const SCALE_MAP = {
     },
     info: { 300: 'border-info' },
     success: { 300: 'border-success' },
-    warning: { 300: 'border-warning' },
+    // Figma 2026-10-01 再同期で border/warning は yellow/400 を参照する（旧 300）
+    // en: border/warning points at yellow/400 since the 2026-10-01 Figma resync (was 300)
+    warning: { 400: 'border-warning' },
   },
   object: {
     primary: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.5.0-beta.3",
+  "version": "2.5.0-beta.4",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/templates/sparkle-variables/README.md

@@ -14,7 +14,7 @@ Sparkle Design のトークン定義。`sparkle-design-cli` と `sparkle-design-
 | プリミティブカラー（red / orange / yellow / green / blue / purple / pink、black / white、alpha、`ring`） | `colors.json` | **`gray` はここに置かない**。`ring.normal` は旧 `--color-ring-normal` 用の beta 互換値で、移行先は セマンティックの `border/ring` |
 | グレースケール | `gray.json` | primary ごとに 10 段（0–9）。CLI が `--color-gray-50`〜`900` に展開する |
 | 角丸のプロファイル | `radius.csv` | 行 = プロファイル、列 = セマンティック名 |
-| フォント一覧 | `fontdata.csv` | 消費側は Figma プラグイン `sparkle-design-theme-settings` のみ（CLI は読まない）。**現状 `validate-tokens.mjs` の検査対象外** |
+| フォント一覧 | `fontdata.csv` | 消費側は Figma プラグイン `sparkle-design-theme-settings` のみ（CLI は読まない）。CLI 経由の検証が効かないぶん、`validate-tokens.mjs` が形（列名・`proportion` の値・一意性）を検査する |
 | セマンティックトークン（色 / 角丸 / シャドウ / タイポグラフィ）と CSS 構造 | `sparkle-design.template.css` | |
 | 最大幅（`--container-*`） | `sparkle-design.template.css` | Figma の `Sizing: Primitives` と 1:1。**余白（`Spacing: Primitives`）はここに置かない** — 理由は下記 |
 | 上記すべての一次情報 | **Figma `Sparkle Design`** | 齟齬があれば Figma が正 |
@@ -143,9 +143,13 @@ node scripts/validate-tokens.mjs
 - 同一ブロック内に重複した変数宣言が無いこと（後勝ちでサイレント上書きされるため）
 - `character-*` / `icon-*` クラスが **自分の変数だけを** 参照していること（クラス間の取り違えを検出する）。貼り替え漏れ（未参照の変数 / 未定義の参照）も含む
 - テンプレートの波括弧の釣り合いと、プレースホルダーが CLI の期待どおりの字面であること（大文字小文字のタイポと、`/* {{COLOR_TOKENS}} */` の体裁崩れによる置換 no-op を検出する）
+- `@font-face` 専用の記述子（`src` / `font-display` / `unicode-range` / `*-override` / `size-adjust`）がスタイルルールに書かれていないこと。これらはプロパティではないので、スタイルルールに置くと**パース時に宣言ごと捨てられます**。CSS は無効な宣言を黙って飛ばす仕様のため、ビルドも lint も警告を出しません
+- `fontdata.csv` が消費側（Figma プラグイン `sparkle-design-theme-settings`）の期待する形をしていること。列名・`proportion` の取りうる値（`pro` / `mono` / `both`）・`name` と `variable` の一意性・`variable` が `font-*` のクラス名の形であること
 
 ### 検査設計の前提
 
 **「0 件マッチ = 成功」を作らない。** 集合比較だけの検査は、命名変更などで対象を 1 件も拾えなくなったときに黙って合格します。各検査は「最低これだけの件数を実際に見た」ことを表明してから判定するので、検査が空振りしていること自体が失敗になります。
 
-**検査できないこと。** これは構造の検査であって、値の妥当性は見ていません。たとえば `--color-text-high` の参照先を別のグレーに書き換えてもコントラストが壊れるだけで検査は通ります。色の値そのものの正解は Figma です。`fontdata.csv` も現状は検査対象外です。
+**検査できないこと。** これは構造の検査であって、値の妥当性は見ていません。たとえば `--color-text-high` の参照先を別のグレーに書き換えてもコントラストが壊れるだけで検査は通ります。色の値そのものの正解は Figma です。
+
+`fontdata.csv` についても同じで、見ているのは形だけです。`variable` の値が消費側のプラグインに実在するクラスかどうかは、そのクラスが別リポジトリ（`sparkle-design-theme-settings` の `src/ui/styles/main.css`）にあるため、このリポジトリの CI では確かめられません。