sparkle-design-cli 2.5.0-beta.4 → 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 以外への手動セットアップ                                     |
@@ -163,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）
 

package/bin/sparkle-design.js

@@ -71,6 +71,7 @@ function parseCheckOptions(args) {
     targets: [],
     strict: false,
     format: 'text',
+    configPath: null,
     help: false,
   };
 
@@ -81,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') {
@@ -191,7 +195,14 @@ function parseRulesOptions(args) {
  * with `--write` is contradictory and fails fast.
  */
 function parseMigrateOptions(args) {
-  const options = { targets: [], includes: [], write: false, dryRun: false, help: false };
+  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];
@@ -204,6 +215,9 @@ function parseMigrateOptions(args) {
     } 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 {
@@ -358,6 +372,24 @@ 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                 このヘルプメッセージを表示
@@ -367,14 +399,17 @@ Migrate options:
   --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-line <rule-id>）を付けた箇所は migrate でも書き換えない
+  対応表は check の移行ルールと共通（lib/token-migration.js）。check の除外
+  （抑制コメント・sparkle-disable-file・sparkle.config.json の check.ignore）にかかる
+  箇所は migrate でも書き換えない
 
 Auth options:
   -h, --help                 このヘルプメッセージを表示
@@ -505,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);
@@ -570,7 +606,12 @@ async function main() {
         showHelp();
         process.exit(0);
       }
-      runMigrate({ targets: options.targets, includes: options.includes, write: options.write });
+      runMigrate({
+        targets: options.targets,
+        includes: options.includes,
+        write: options.write,
+        configPath: options.configPath,
+      });
       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 期間中）
 

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

package/lib/anti-pattern-rules.js

@@ -465,9 +465,12 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
   {
     id: 'shadcn-token',
     check: {
-      description: 'shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない',
+      // 検出はファイル全体のクラス名に対して行う（Sparkle コンポーネント内かどうかは
+      // 見ない）ので、説明文もその範囲に合わせる（#104）。
+      // en: Detection is file-wide, not limited to Sparkle components (#104).
+      description: 'shadcn/ui 既定 token を使わず、Sparkle Design の token を使う',
       recommendation:
-        'text-muted-foreground / bg-background / border-border などは Sparkle Design token に置き換えてください。',
+        'text-muted-foreground / bg-background / border-border などは Sparkle Design token に置き換えてください。まず置き換えを検討し、置き換えられない理由がある場合（プロジェクトが自前の CSS でこれらを定義し、Sparkle 以外の UI で意図して使っている等）に限り、sparkle.config.json の `check.allowTokens` で宣言できます。',
       // 新セマンティックトークン（border-border-neutral-* 等）へ前方一致しないよう、
       // 直後にハイフン／単語構成文字が続くケースを除外する
       // en: exclude prefix matches against new semantic tokens (e.g. border-border-neutral-*)
@@ -491,7 +494,7 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
       '</CardDescription>',
       '```',
       '',
-      'shadcn/ui と混在するプロジェクトでも、Sparkle Design のコンポーネント内では `character-*` / `text-text-*` / Sparkle の color token を優先する。',
+      'shadcn/ui と混在するプロジェクトでも、`character-*` / `text-text-*` / Sparkle の color token を優先する（`sparkle-design-cli check` はファイル全体のクラス名を検査する）。',
     ]),
     jsdocTargets: [],
   },
@@ -1106,7 +1109,7 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
     check: {
       description: 'Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない',
       recommendation:
-        'text-xs 〜 text-9xl / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同一行または直前行に `// sparkle-disable-line tailwind-typography` コメントを付けて例外扱いとして残すこともできます。font-medium(500) / font-semibold(600) は character-* に対応する token が無いため、`extend.custom-css` で独自クラスを定義してください（詳細は README の「character-* に無いウェイトを使いたい場合」参照）。',
+        'text-xs 〜 text-9xl / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同じ行に `// sparkle-disable-line tailwind-typography`、または直前の行に `// sparkle-disable-next-line tailwind-typography` を付けて例外扱いとして残すこともできます。font-medium(500) / font-semibold(600) は character-* に対応する token が無いため、`extend.custom-css` で独自クラスを定義してください（詳細は README の「character-* に無いウェイトを使いたい場合」参照）。',
       // text-base は旧カラートークンの text-base-50 〜 text-base-900 へ前方一致するため、
       // shadcn-token と同様に直後のハイフン／単語構成文字を除外する
       // en: exclude prefix matches such as text-base-900 (legacy color token)
@@ -1135,7 +1138,7 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
       '<span className="text-xs">どうしても text-xs で残したいケース</span>',
       '```',
       '',
-      'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。character-1（12px）より小さい指定や、対応 token が無いサイズは Tailwind の arbitrary value (`text-[10px]` 等) で表現するか、`// sparkle-disable-line tailwind-typography` で個別に例外指定する。',
+      'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。character-1（12px）より小さい指定や、対応 token が無いサイズは Tailwind の arbitrary value (`text-[10px]` 等) で表現するか、同じ行の `// sparkle-disable-line tailwind-typography` / 直前の行の `// sparkle-disable-next-line tailwind-typography` で個別に例外指定する。',
       '',
       '`font-medium` / `font-semibold`（500 / 600）は character-* に対応する token が存在しない。`character-N-regular-pro font-semibold` のように Tailwind の font-weight ユーティリティを併用しても、character-* が意図的に Tailwind の後に読み込まれる cascade 設計のため上書きされず効かない。これらのウェイトが必要な場合は `extend.custom-css` で `character-N-semibold-pro` のような独自クラスを定義し、font-family / font-size / letter-spacing / line-height は character-* と同じプリミティブトークンを流用する（詳細は README の「character-* に無いウェイトを使いたい場合」）。',
     ]),