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

package/README.md

@@ -73,6 +73,12 @@ 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
 ```
 
 ### generate: 基本的な使用方法
@@ -197,6 +203,38 @@ 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` に書きます。
+
+```bash
+gcloud auth login                         # 初回のみ（ADC を使う場合は gcloud auth application-default login）
+npx --yes sparkle-design-cli@beta auth    # プロジェクトの .npmrc の @goodpatch:registry が対象
+pnpm install
+```
+
+- 対象の registry は `--registry <url>`、無ければプロジェクトの `.npmrc`（親ディレクトリも辿る）の `@goodpatch:registry=` です。プロジェクトの `.npmrc` には registry 行だけを置けばよく、そのままコミットできます
+- トークンの取得は ADC → `gcloud auth print-access-token` の順です。どちらも使えなければ `gcloud auth login` を案内して終了します
+- **トークンは約 60 分で失効します。** `pnpm install` が 401 で落ちたら（npm は `npm adduser` を案内しますが、AR では解決しません）もう一度 `auth` を実行してください
+- 同じ registry の行は置き換えるので、何度実行しても `~/.npmrc` に行は積み上がりません。`always-auth` は書きません
+- トークンは Artifact Registry（`<location>-npm.pkg.dev`）以外には書きません。`cloud-platform` スコープの Google トークンなので、ほかのホストに渡すと資格情報の漏えいになるためです
+- トークンを画面に出さず、refresh token などの長期クレデンシャルもコピーしません（gcloud の管理下に置いたまま）
+
 ### setup: プロジェクトのフルセットアップ
 
 `sparkle-design-cli setup` は、Sparkle Design の導入に必要な作業をまとめて行います：

package/bin/sparkle-design.js

@@ -7,8 +7,19 @@ import { runStopHook } from '../lib/stop-hook.js';
 import { PLUGIN_SPEC_MARKDOWN } from '../lib/plugin-api.js';
 import { loadAntiPatternPlugins } from '../lib/load-plugins.js';
 import { runRules } from '../lib/rules-report.js';
-
-const SUBCOMMANDS = new Set(['generate', 'check', 'rules', 'setup', 'stop-hook', 'plugin-spec']);
+import { runAuth } from '../lib/auth.js';
+import { runMigrate } from '../lib/migrate.js';
+
+const SUBCOMMANDS = new Set([
+  'generate',
+  'check',
+  'rules',
+  'migrate',
+  'setup',
+  'auth',
+  'stop-hook',
+  'plugin-spec',
+]);
 
 function requireOptionValue(args, index, flags) {
   const value = args[index + 1];
@@ -170,6 +181,67 @@ 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, 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.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.
+ */
+function parseAuthOptions(args) {
+  const options = { registry: null, help: false };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--registry') {
+      options.registry = requireOptionValue(args, i, '--registry');
+      i += 1;
+      continue;
+    }
+    throw new Error(`Unknown option for auth: ${arg}`);
+  }
+
+  return options;
+}
+
 function showHelp() {
   console.log(`
 Sparkle Design CLI
@@ -181,7 +253,9 @@ 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 か、
                実行に失敗して未検査のルールがあるときに exit 2 で 1 度だけ停止をブロック / 再発火は自動回避。
                warning / info はブロックせず件数の要約を stderr に出す）
@@ -203,6 +277,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 向け
@@ -211,6 +291,10 @@ Plugin spec:
   sparkle-design-cli plugin-spec           # アンチパターン拡張プラグインの契約仕様を出力
   sparkle-design-cli plugin-spec --list    # 現在のプロジェクトで発見されたプラグインを表示
 
+Auth (beta):
+  sparkle-design-cli auth                  # プロジェクトの .npmrc の @goodpatch:registry を対象に認証
+  sparkle-design-cli auth --registry https://asia-northeast1-npm.pkg.dev/<project>/<repository>/
+
 Setup:
   sparkle-design-cli setup                                        # フルセットアップ（推奨・新規導入時）
   sparkle-design-cli setup --assistant claude                     # Claude 向けガードも同時にセットアップ
@@ -275,6 +359,36 @@ Check options:
                              （warning / info は報告のみで exit code に影響しない）
   --format <text|json>       出力形式 (default: text)
 
+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} に対応）
+
+Migrate の分類:
+  自動変換可     bg- / text- / border- などの用途と variant 接頭辞（hover: 等）から移行先が
+                 一意に決まり、値も変わらないもの。--write のときだけ置換する
+  要判断         移行先候補が複数ある / 対応する新トークンが無いもの。候補を表示するだけで置換しない
+  構造変更あり   トークンの差し替えでは済まない（マークアップ変更を伴う）もの。指摘するだけで置換しない
+  対応表は check の移行ルールと共通（lib/token-migration.js）。check で抑制コメント
+  （sparkle-disable-line <rule-id>）を付けた箇所は migrate でも書き換えない
+
+Auth options:
+  -h, --help                 このヘルプメッセージを表示
+  --registry <url>           対象の registry（default: プロジェクトの .npmrc の @goodpatch:registry）
+
+Auth の動作:
+  1. Google の資格情報（ADC → gcloud auth print-access-token の順）からアクセストークンを取得
+     どちらも無い / 期限切れなら gcloud auth login を案内して終了
+  2. ユーザー単位の ~/.npmrc（NPM_CONFIG_USERCONFIG があればそちら）に、同じ registry の行を
+     置き換えて書く（プロジェクトの .npmrc は registry 行のみのまま、コミットできる状態を保つ）
+  3. 有効期限（約 60 分）を表示する。切れたらもう一度 auth を実行する
+  トークンは Artifact Registry（<location>-npm.pkg.dev）にだけ書き、画面には出しません。
+  refresh token などの長期クレデンシャルは gcloud の管理下に置いたままで、コピーしません。
+
 Setup options:
   -h, --help                 このヘルプメッセージを表示
   --assistant <name>         claude / codex / cursor / generic (default: generic)
@@ -410,6 +524,16 @@ async function main() {
       return;
     }
 
+    if (command === 'auth') {
+      const options = parseAuthOptions(args.slice(1));
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+      await runAuth(options);
+      return;
+    }
+
     if (command === 'stop-hook') {
       // setup で各 agent の hook 設定ファイルから呼ばれる internal subcommand。
       // 以降の引数はすべて lint 対象 path。setup が書き出す hook は 1 つだが、
@@ -440,6 +564,16 @@ 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 });
+      return;
+    }
+
     if (command === 'plugin-spec') {
       await runPluginSpec(args.slice(1));
       return;

package/docs/anti-patterns.md

@@ -55,6 +55,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` で報告し、前後の候補を提示します。