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

package/CONTRIBUTING.md

@@ -39,11 +39,37 @@ npm run sync:anti-pattern-docs  # ルールの解説を隣接リポジトリの
 
 ## リリース手順（メンテナ向け）
 
-publish は GitHub Actions の **Publish to npm** workflow 経由。ローカル `npm publish` は禁止。
+publish は GitHub Actions 経由。ローカル `npm publish` は禁止。npm は 2027 年 1 月に granular access token での直接 publish を廃止するため、**trusted publishing（OIDC）で stage → メンテナーが 2FA で承認**する形にしている。
 
 1. `package.json` の `version` を更新（安定版: `X.Y.Z` / RC: `X.Y.Z-rc.N` / Beta: `X.Y.Z-beta.N`）
 2. `CHANGELOG.md` に該当セクションを追加
-3. PR をマージ後、**Publish to npm** workflow を `channel: auto` で実行
+3. PR をマージ後、**Publish to npm** workflow を main から実行する（`gh workflow run --ref` はブランチ名かタグ名のみで SHA は渡せない。main 以外からの実行は拒否される）。CI は `npm stage publish` するだけで、まだ公開されない。Summary に stage ID と commit が出る
+   ```bash
+   gh workflow run "Publish to npm" --repo goodpatch/sparkle-design-cli --ref main -f channel=auto
+   ```
+4. メンテナーが 2FA 付きで承認する（不要なら `stage reject`）。手元で `npm login --registry=https://registry.npmjs.org` 済みであること（社内 proxy が既定 registry の環境があるので `--registry` を必ず付ける）
+   ```bash
+   npx -y npm@11.21.0 stage download <stage-id> --registry=https://registry.npmjs.org   # 任意: 中身を確認
+   npx -y npm@11.21.0 stage approve <stage-id> --otp=<code> --registry=https://registry.npmjs.org
+   ```
+5. 公開を確認したら、Summary に出た commit で tag と GitHub Release を作る（npm で公開済みか・`gitHead` が一致するかを確かめてから動く）
+   ```bash
+   gh workflow run "Publish GitHub Release" --repo goodpatch/sparkle-design-cli -f ref=<Summary の commit>
+   ```
+
+dist-tag は stage 時に決まり、承認時には変えられない。
+
+### trusted publisher（OIDC）の設定
+
+トークンの発行・更新は不要。npm 側でパッケージとワークフローを一度だけ結び付ける（npm の 2FA が要るのでメンテナーが実行する）:
+
+```bash
+npx -y npm@11.21.0 trust github sparkle-design-cli \
+  --repository goodpatch/sparkle-design-cli --file publish.yml --allow-stage-publish --registry=https://registry.npmjs.org
+npx -y npm@11.21.0 trust list sparkle-design-cli --registry=https://registry.npmjs.org
+```
+
+`--allow-publish` は付けない（CI から直接公開できないようにし、公開の確定を人の 2FA に限る）。OIDC で stage できることを確認したら `NPM_TOKEN` secret は削除する。private リポジトリなので provenance は付かない。
 
 `channel: auto` は `package.json` の version 形式から dist-tag を自動判定します（`-beta.N` → `beta` / `-rc.N` → `next` / それ以外 → `latest`）。既存 RC / Beta を latest に昇格させる場合は、新しい `X.Y.Z` として改めて publish します（`npm dist-tag add` での手動付け替えも可能ですが、version 管理が明確になる前者を推奨）。
 

package/README.md

@@ -6,7 +6,7 @@ Sparkle Design のプロジェクト初期セットアップ、CSS 生成、導
 
 | ドキュメント                                   | 内容                                                                        |
 | ---------------------------------------------- | --------------------------------------------------------------------------- |
-| [docs/anti-patterns.md](docs/anti-patterns.md) | `check` の抑制方法、新セマンティックトークンへの移行、余白スケール          |
+| [docs/anti-patterns.md](docs/anti-patterns.md) | `check` の抑制・除外方法、新セマンティックトークンへの移行、余白スケール    |
 | [docs/config.md](docs/config.md)               | `sparkle.config.json` の `extend`（フォント追加・カスタムカラー・任意 CSS） |
 | [docs/theming.md](docs/theming.md)             | 複数のテーマ配色を 1 デプロイでサポートする（`generate --scope`）           |
 | [docs/manual-setup.md](docs/manual-setup.md)   | Next.js / Vite 以外への手動セットアップ                                     |
@@ -74,6 +74,9 @@ npx sparkle-design-cli check src --format json
 # 現在有効なアンチパターンルールを一覧表示（プラグイン由来のものも含む）
 npx sparkle-design-cli rules
 
+# 旧セマンティックトークンを新トークンへ移行（既定は dry-run。--write で書き換え）
+npx --yes sparkle-design-cli migrate
+
 # Artifact Registry の npm registry 用トークンを ~/.npmrc に書く（beta）
 npx --yes sparkle-design-cli@beta auth
 ```
@@ -160,6 +163,9 @@ sparkle-design-cli check --help
 - `-h, --help`: ヘルプメッセージを表示
 - `--strict`: **`error` の違反があるか、実行に失敗して未検査のルールがある**場合に exit code 1 で終了（`warning` / `info` は exit code に影響しません）
 - `--format <text|json>`: 出力形式。AI 連携では `json` を推奨
+- `-c, --config <path>`: 除外設定（`check.ignore` / `check.allowTokens`）を読む設定ファイル（既定: `./sparkle.config.json`。無ければ除外なし）
+
+意図的な箇所を検査から外すには、行単位（`sparkle-disable-line` / `sparkle-disable-next-line`）、ファイル単位（`sparkle-disable-file`）、パス単位（`sparkle.config.json` の `check.ignore`）の 3 つの方法があります。自前の CSS で定義して意図して使う shadcn/ui のトークンは、`check.allowTokens` でクラス単位に宣言できます（`shadcn-token` の指摘にだけ効きます）。詳しくは [docs/anti-patterns.md の「抑制する」](docs/anti-patterns.md#抑制する) を参照してください。
 
 #### ルールの強さ（severity）
 
@@ -200,6 +206,21 @@ npx sparkle-design-cli rules --format json
 
 AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
+### migrate: 新セマンティックトークンへの移行
+
+`check` が警告する旧セマンティックトークン（`bg-primary-600` / `var(--radius-halfModal)` など）を新トークンへ書き換えます。
+
+```bash
+npx --yes sparkle-design-cli migrate                       # src を dry-run（変更内容を diff 形式で表示するだけ）
+npx --yes sparkle-design-cli migrate --write               # [自動変換可] の箇所だけ書き換える
+npx --yes sparkle-design-cli migrate --include 'src/components/**/*.tsx'
+```
+
+- **既定は dry-run** で、`--write` を付けたときだけファイルを書き換えます。探索範囲は `check` と同じです（既定 `src`、パスを並べて指定可）
+- 書き換えるのは移行先が一意に決まり値も変わらない `[自動変換可]` だけです。`[要判断]`（候補が複数ある等）と `[構造変更あり]` は報告するだけで置換しません
+
+分類の考え方は [docs/anti-patterns.md](docs/anti-patterns.md#新セマンティックトークンへの移行beta-期間中) を参照してください。
+
 ### auth: Artifact Registry の認証（beta）
 
 社内パッケージの配信先を Google Artifact Registry（AR）に移行するための準備です（goodpatch/sparkle-design-internal#261）。Google の資格情報から AR 用のアクセストークンを取得し、ユーザー単位の `~/.npmrc` に書きます。

package/bin/sparkle-design.js

@@ -8,11 +8,13 @@ import { PLUGIN_SPEC_MARKDOWN } from '../lib/plugin-api.js';
 import { loadAntiPatternPlugins } from '../lib/load-plugins.js';
 import { runRules } from '../lib/rules-report.js';
 import { runAuth } from '../lib/auth.js';
+import { runMigrate } from '../lib/migrate.js';
 
 const SUBCOMMANDS = new Set([
   'generate',
   'check',
   'rules',
+  'migrate',
   'setup',
   'auth',
   'stop-hook',
@@ -69,6 +71,7 @@ function parseCheckOptions(args) {
     targets: [],
     strict: false,
     format: 'text',
+    configPath: null,
     help: false,
   };
 
@@ -79,6 +82,9 @@ function parseCheckOptions(args) {
       options.help = true;
     } else if (arg === '--strict') {
       options.strict = true;
+    } else if (arg === '-c' || arg === '--config') {
+      options.configPath = requireOptionValue(args, i, '-c/--config');
+      i += 1;
     } else if (arg === '--format') {
       const value = requireOptionValue(args, i, '--format');
       if (value !== 'text' && value !== 'json') {
@@ -179,6 +185,53 @@ function parseRulesOptions(args) {
   return options;
 }
 
+/**
+ * `migrate` のオプション。
+ *
+ * 既定は dry-run。`--write` を付けたときだけファイルを書き換える（不可逆操作を
+ * デフォルトにしない）。`--dry-run` は既定と同じだが、明示したい人のために受け付ける。
+ * 両方指定は意図が矛盾するのでその場で失敗させる。
+ * en: Dry-run by default; only `--write` rewrites files. `--dry-run` together
+ * with `--write` is contradictory and fails fast.
+ */
+function parseMigrateOptions(args) {
+  const options = {
+    targets: [],
+    includes: [],
+    write: false,
+    dryRun: false,
+    configPath: null,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--write') {
+      options.write = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--include') {
+      options.includes.push(requireOptionValue(args, i, '--include'));
+      i += 1;
+    } else if (arg === '-c' || arg === '--config') {
+      options.configPath = requireOptionValue(args, i, '-c/--config');
+      i += 1;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option for migrate: ${arg}`);
+    } else {
+      options.targets.push(arg);
+    }
+  }
+
+  if (options.write && options.dryRun) {
+    throw new Error('--write と --dry-run は同時に指定できません');
+  }
+
+  return options;
+}
+
 /**
  * `auth` のオプション。未知のフラグはその場で失敗させる（他のサブコマンドと同じ）。
  * en: Unknown flags fail fast, same as the other subcommands.
@@ -214,6 +267,7 @@ Commands:
   generate     sparkle.config.json から CSS を生成
   check        Sparkle Design のアンチパターンを検査
   rules        現在有効なアンチパターンルールを一覧表示（プラグイン由来のものも含む）
+  migrate      旧セマンティックトークンを新トークンへ移行（既定は dry-run。--write で書き換え）
   setup        Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
   auth         Artifact Registry の npm registry 用アクセストークンを ~/.npmrc に書く（beta）
   stop-hook    AI assistant の Stop hook 用 internal subcommand（severity=error の findings か、
@@ -237,6 +291,12 @@ Check:
   sparkle-design-cli check src --format json
   sparkle-design-cli check src/components src/features
 
+Migrate:
+  sparkle-design-cli migrate                                   # src を dry-run（変更内容を表示するだけ）
+  sparkle-design-cli migrate --include 'src/components/**/*.tsx'
+  sparkle-design-cli migrate --write                           # [自動変換可] の箇所だけ書き換える
+  sparkle-design-cli migrate src/app src/features --write
+
 Rules:
   sparkle-design-cli rules                 # 有効なルールを severity 別に一覧表示
   sparkle-design-cli rules --format json   # CI / AI 向け
@@ -312,6 +372,44 @@ Check options:
   --strict                   severity=error の違反があれば exit code 1 で終了
                              （warning / info は報告のみで exit code に影響しない）
   --format <text|json>       出力形式 (default: text)
+  -c, --config <path>        除外設定（check.ignore / check.allowTokens）を読む設定ファイル
+                             (default: ./sparkle.config.json。無ければ除外なし)
+
+Check の除外:
+  同じ行に置く     // sparkle-disable-line <rule-id>
+  直前の行に置く   // sparkle-disable-next-line <rule-id>
+  ファイル内に置く /* sparkle-disable-file <rule-id> */（ファイル全体に効く。場所は問わない）
+  パス単位         sparkle.config.json の check.ignore に glob とルール ID を書く
+                   { "check": { "ignore": [{ "files": ["src/app/(marketing)/**"], "rules": ["tailwind-typography"] }] } }
+                   （rules を省略すると全ルール。glob は cwd からの相対パスで、cwd の外には効かない）
+  トークン単位     自前の CSS で定義して意図して使う shadcn/ui のトークンを check.allowTokens で宣言する
+                   { "check": { "allowTokens": ["text-muted-foreground",
+                     { "tokens": ["bg-background"], "files": ["src/app/docs/**"] }] } }
+                   （shadcn-token の指摘にだけ効く。指摘されたクラス名（variant・/50・! を除いた部分）が
+                    宣言と完全一致するものだけを許可。cwd の外には効かない）
+  行コメントは font-import-in-css / csp-font-block には効かない（ファイル単位かパス単位で外す）。
+  除外した件数は出力と JSON の summary.ignoredFindingCount に出る。
+  詳細は docs/anti-patterns.md
+
+Migrate options:
+  -h, --help                 このヘルプメッセージを表示
+  [path ...]                 探索するパス（default: src。check と同じ探索範囲。
+                             .js / .jsx / .ts / .tsx / .css、node_modules と .git は除外）
+  --dry-run                  ファイルを変更せず、変更内容を diff 形式で表示する（既定）
+  --write                    [自動変換可] の箇所だけを書き換える
+  --include <glob>           対象を cwd からの相対パス（cwd の外は絶対パス）が glob に
+                             マッチするファイルに絞る（複数指定可。** / * / ? / {a,b} に対応）
+  -c, --config <path>        check.ignore を読む設定ファイル（check と同じ。
+                             default: ./sparkle.config.json。無ければ除外なし）
+
+Migrate の分類:
+  自動変換可     bg- / text- / border- などの用途と variant 接頭辞（hover: 等）から移行先が
+                 一意に決まり、値も変わらないもの。--write のときだけ置換する
+  要判断         移行先候補が複数ある / 対応する新トークンが無いもの。候補を表示するだけで置換しない
+  構造変更あり   トークンの差し替えでは済まない（マークアップ変更を伴う）もの。指摘するだけで置換しない
+  対応表は check の移行ルールと共通（lib/token-migration.js）。check の除外
+  （抑制コメント・sparkle-disable-file・sparkle.config.json の check.ignore）にかかる
+  箇所は migrate でも書き換えない
 
 Auth options:
   -h, --help                 このヘルプメッセージを表示
@@ -442,6 +540,7 @@ async function main() {
       const hasBlockingIssues = await checkProject(options.targets, {
         strict: options.strict,
         format: options.format,
+        configPath: options.configPath,
       });
       if (hasBlockingIssues && options.strict) {
         process.exit(1);
@@ -501,6 +600,21 @@ async function main() {
       return;
     }
 
+    if (command === 'migrate') {
+      const options = parseMigrateOptions(args.slice(1));
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+      runMigrate({
+        targets: options.targets,
+        includes: options.includes,
+        write: options.write,
+        configPath: options.configPath,
+      });
+      return;
+    }
+
     if (command === 'plugin-spec') {
       await runPluginSpec(args.slice(1));
       return;

package/docs/anti-patterns.md

@@ -6,7 +6,18 @@
 
 ## 抑制する
 
-特定の箇所だけ検査から外すには、ESLint と同じ形のコメントを使います。
+検査から外す方法は、範囲の狭い順に 3 つあります。どれもルール ID を指定でき、ID は `rules` コマンドの出力と `check` の指摘に出ているものです。複数指定するときは、コメントではカンマ区切り（`tailwind-typography, use-figma-spacing-scale`）、設定ファイルでは配列の要素を分けます（`["tailwind-typography", "use-figma-spacing-scale"]`。1 つの文字列にカンマで並べると 1 つの未知 ID として扱われ、何も外れません）。
+
+このほか、自前の CSS で定義した shadcn/ui のトークンを意図して使う場合は、ルールごとではなくクラス単位で宣言する [`check.allowTokens`](#トークン単位checkallowtokens) があります。
+
+### 行単位
+
+ESLint と同じ形のコメントです。**コメントの種類で置く場所が決まっています**。直前の行に `sparkle-disable-line` を置いても抑制されません。
+
+| コメント                              | 置く場所               |
+| ------------------------------------- | ---------------------- |
+| `sparkle-disable-line <rule-id>`      | 指摘される行と同じ行   |
+| `sparkle-disable-next-line <rule-id>` | 指摘される行の直前の行 |
 
 ```tsx
 {/* sparkle-disable-next-line legacy-color-token */}
@@ -15,7 +26,71 @@
 <div className="bg-primary-600" /> {/* sparkle-disable-line legacy-color-token */}
 ```
 
-ルール ID はカンマ区切りで複数指定できます。ID は `rules` コマンドの出力と `check` の指摘に出ているものです。
+行コメントはルール定義から出る指摘に効きます。`check` 本体が直接行う `font-import-in-css` と `csp-font-block` には効かないので、下のファイル単位かパス単位で外してください。
+
+### ファイル単位
+
+`sparkle-disable-file` をファイル内のどこかに書くと、そのファイル全体で指定ルールを外します。行コメントと同じく**ルール ID は必須**です（ID を省略したコメントは何も外しません）。
+
+```tsx
+/* sparkle-disable-file tailwind-typography, use-figma-spacing-scale */
+```
+
+効くのは `check` が走査したファイルと、`csp-font-block` の指摘元になった `next.config.*` です。
+
+### パス単位（`sparkle.config.json`）
+
+デザイナーとの調整待ちの公開ページのように、意図して残す箇所がディレクトリ単位でまとまっているときは、`sparkle.config.json` の `check.ignore` に書きます。コメントを足して回らずに済み、何を外しているかが 1 か所で分かります。
+
+```json
+{
+  "primary": "blue",
+  "check": {
+    "ignore": [
+      { "files": ["src/app/(marketing)/**", "src/app/blog"], "rules": ["tailwind-typography"] },
+      { "files": ["**/*.stories.tsx"] }
+    ]
+  }
+}
+```
+
+- `files` は **cwd（`check` を実行するディレクトリ）からの相対パス**の glob です。`check` の出力に出るパスと同じ基準で照合します。`**` / `*` / `?` / `{a,b}` が使えます。`-c` で別の場所の設定ファイルを指定しても、基準は cwd のままです
+- glob 記号を含まないパス（上の `src/app/blog`）はディレクトリ指定とみなし、配下のファイルすべてに効きます
+- cwd の外のファイル（出力が `../` で始まるもの）には効きません
+- `rules` を省略すると、そのパスの**全ルール**を外します。関係ないルールまで外れないよう、できるだけ `rules` を指定してください
+- 別の設定ファイルを使うときは `check -c <path>`（`migrate -c <path>` も同じ）で指定します。既定の `./sparkle.config.json` が無ければ除外なしで動きます
+- 形が不正な設定（`check` / `ignore` / `allowTokens` が想定の型でない、`files` が空、未知のキー、空・絶対パス・`..` を含むパスなど）は exit 1 で止まります（`migrate` も同じ。ただし `migrate` は `allowTokens` を使わないので、その形は検証しません）。除外の typo に気付かないまま検査が素通りするのを防ぐためです。stop-hook では exit 2 で応答終了を 1 度ブロックし、設定を直すよう伝えます
+
+除外するのは「Sparkle のトークンに置き換えられない・置き換えない理由がある」箇所だけにしてください。検出されたからといって外すのではなく、まず Sparkle のトークンへ置き換えられないかを確認します（例: `shadcn-token` の指摘は、多くの場合 `text-text-neutral-low` などへ置き換えるのが正解です）。
+
+### トークン単位（`check.allowTokens`）
+
+プロジェクトが shadcn/ui のトークン（`text-muted-foreground` など）を自前の CSS で定義し、Sparkle 以外の UI で意図して使っている場合は、`check.allowTokens` で宣言します。**まず Sparkle のトークンへ置き換えられないかを確認し、置き換えない理由がある場合だけ**使ってください。
+
+```json
+{
+  "primary": "blue",
+  "check": {
+    "allowTokens": [
+      "text-muted-foreground",
+      { "tokens": ["bg-background", "border-border"], "files": ["src/app/docs/**"] }
+    ]
+  }
+}
+```
+
+- **`shadcn-token` の指摘にだけ効きます**。他のルールの指摘は外れません（他ルールを外したいときは、上のファイル単位・パス単位を使います）
+- 指摘されたクラスが宣言と**完全一致する**ときだけ、その指摘を出しません。宣言していないクラスは引き続き検出されるので、意図しない持ち込みは見逃しません。`hover:bg-background` / `bg-background/50` / `!bg-background` のような variant・opacity・important 付きも、指摘されるクラス名（`bg-background`）で照合します。宣言にも variant などを付けずにクラス名だけを書いてください
+- 文字列で書いたクラスは全体（cwd の外のファイルを除く）で許可します。`{ "tokens": [...], "files": [glob] }` で書くと、そのパスでだけ許可します（glob の書き方はパス単位と同じ）
+- `shadcn-token` の検出対象ではないクラスを書くと、stderr に警告が出て JSON の `ignoreWarnings` にも載ります（`{ "source": "allowTokens", "ruleId": "shadcn-token", "token": "..." }`。typo に気付けるように）
+
+### 除外しすぎに気付くために
+
+- 除外した件数は出力に `N 件を除外しました（行コメント a / sparkle-disable-file b / check.ignore c / check.allowTokens d）` の形で出ます（0 件の内訳は省略）。1 件の指摘が複数の方法にかかる場合は、行コメント → ファイル単位 → パス単位 → トークン単位の順で最初に当たったものとして数えます
+- JSON 出力では `summary.ignoredFindingCount` に合計、トップレベルの `ignored` に仕組みごとの内訳が入ります
+- `check.ignore` や `sparkle-disable-file` に**有効なルールに無い ID**を書くと、stderr に警告が出て JSON の `ignoreWarnings` にも載ります（typo や、プラグインを入れていない環境での指定に気付けるように）
+- 除外したファイル × ルールでルールの実行が失敗しても、「未検査」（`skippedRules`）には数えません
+- 除外した箇所は `migrate` でも書き換えません
 
 ## 新セマンティックトークンへの移行（beta 期間中）
 
@@ -55,6 +130,27 @@ src/Card.tsx:8 [warning] [legacy-color-token] 旧セマンティックカラー
 >
 > 旧→新の対応表は `lib/token-migration.js` に一元化してあり、`test/token-migration.test.js` が**実際に生成した CSS を読んで**「表に書いた移行先が実在し、旧トークンと同じ実値に解決される」ことを検証しています。表とトークン定義が食い違ったらテストが落ちるので、案内が嘘になりません。検出パターンがマッチする文字列は必ず対応表で解決できることも全数検証しています（片方だけ更新すると「検出したのに黙って捨てる」穴になるため）。
 
+### `migrate` で書き換える
+
+`check` が提示する移行先のうち `[自動変換可]` のものは、`migrate` サブコマンドでまとめて書き換えられます。対応表は `check` と同じ `lib/token-migration.js` を使うので、`check` の案内と `migrate` の書き換え先が食い違うことはありません。
+
+```bash
+npx --yes sparkle-design-cli migrate          # dry-run。変更内容を diff 形式で表示するだけ
+npx --yes sparkle-design-cli migrate --write  # [自動変換可] の箇所だけ書き換える
+```
+
+| 分類         | `migrate` の挙動                                                                                                             |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| 自動変換可   | 用途（`bg-` / `text-` / `border-` …）と variant 接頭辞から移行先が一意に決まり、値も変わらない。`--write` のときだけ置換する |
+| 要判断       | 移行先候補が複数ある / 対応する新トークンが無い。候補を列挙するだけで置換しない                                              |
+| 構造変更あり | トークンの差し替えでは済まない（マークアップ変更を伴う）。該当箇所を指摘するだけ                                             |
+
+- variant 接頭辞（`hover:` / `group-hover:` / `dark:` …）、opacity modifier（`/50`）、important（`!`）は置換後もそのまま残ります
+- `check` で報告しないもの（そのファイル自身が宣言している変数・行頭から始まるブロックコメント）は `migrate` も書き換えません。`sparkle-disable-line legacy-color-token` などの抑制コメントを付けた箇所も書き換えません（誤検出を抑制した箇所を黙って書き換えないため）
+- 書き換えた後に 2 回目を実行しても、`migrate` の `[自動変換可]` は 0 件になります（新トークンは検出パターンにマッチしない）
+- **`check` が `[自動変換可]` と案内しても、`migrate` が `[要判断]` として書き換えずに残す箇所があります。** 検出はファイル全体への正規表現なので、パス（`'/img/fill-primary-600.svg'` / `"bg-primary-600/hero.png"`）、import / require の specifier、`url()` の中のようなクラス名でない文字列にもマッチします。`check` は報告するだけなので案内を変えていませんが、`migrate` は資産パスや import を壊さないよう、これらと数値・角括弧以外の modifier（`/data.json` など）付きのものを書き換えません。クラス名として使っている箇所なら手で置き換えてください
+- `--include <glob>` で対象を cwd からの相対パスで絞れます（`**` / `*` / `?` / `{a,b}`）
+
 ## 余白のスケール（`use-figma-spacing-scale`）
 
 Figma の余白は 17 段（0 / 2 / 4 / 6 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48 / 56 / 72 / 88 / 104 / 120 px）です。Tailwind の 1 ステップは 4px なので、`p-4` = 16px、`p-6` = 24px が対応します。このスケールから外れた値を `info` で報告し、前後の候補を提示します。

package/docs/config.md

@@ -1,5 +1,7 @@
 # 設定ファイルの拡張（`extend`）
 
+> `check` の除外設定（`check.ignore` / `check.allowTokens`）も `sparkle.config.json` に書きます。書き方は [anti-patterns.md の「抑制する」](anti-patterns.md#パス単位sparkleconfigjson) を参照してください。
+
 Figma プラグインが出力する基本4項目に加えて、プロジェクト固有の拡張を `extend` セクションにまとめます。`extend` はオブジェクト直書き（推奨）またはファイルパスを指定できます。
 
 ```json