sparkle-design-cli 2.0.7-rc.2 → 2.0.7-rc.4

package/README.md

@@ -24,11 +24,11 @@ npm install -g sparkle-design-cli
 
 npm の dist-tag でチャネルを分けています。通常は `latest` を使い、RC や beta は先行試用時のみ指定してください。
 
-| チャネル | dist-tag | バージョン形式 | 用途 |
-| --- | --- | --- | --- |
-| 安定版 | `latest` | `X.Y.Z` | 本番運用向け（デフォルト） |
-| Release Candidate | `next` | `X.Y.Z-rc.N` | GA 直前の検証、チーム展開前 |
-| Beta | `beta` | `X.Y.Z-beta.N` | 品質保証中の検証用 |
+| チャネル          | dist-tag | バージョン形式 | 用途                        |
+| ----------------- | -------- | -------------- | --------------------------- |
+| 安定版            | `latest` | `X.Y.Z`        | 本番運用向け（デフォルト）  |
+| Release Candidate | `next`   | `X.Y.Z-rc.N`   | GA 直前の検証、チーム展開前 |
+| Beta              | `beta`   | `X.Y.Z-beta.N` | 品質保証中の検証用          |
 
 ```bash
 # latest を使う（デフォルト）
@@ -203,7 +203,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 
 - `claude`: `CLAUDE.md`
 - `codex`: `AGENTS.md`
-- `cursor`: `.cursor/rules/sparkle-design-guard.mdc`
+- `cursor`: `AGENTS.md`（rc.4 から `.cursor/rules/*.mdc` を廃止。Cursor は AGENTS.md を always-load するため、条件付き読み込みで Guard が silent に skip される問題を解消）
 - `generic`: `SPARKLE-DESIGN-AI.md`
 
 #### setup オプション一覧
@@ -291,10 +291,19 @@ Next.js / Vite 以外ではアプリケーションフレームワークごと
 ```html
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,wght@0..1,500&display=block" />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,wght@0..1,500&display=block"
+/>
 <!-- sparkle.config.json の font-pro / font-mono に合わせた Google Fonts URL -->
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap" />
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap" />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap"
+/>
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap"
+/>
 ```
 
 **7. アンチパターン検査を package.json に追加（任意）**
@@ -310,7 +319,7 @@ Next.js / Vite 以外ではアプリケーションフレームワークごと
 
 **8. AI エージェントを使うなら Guard ブロックと hook を手動で配置**
 
-AI ガード（`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/*.mdc`）と hook 設定（`.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`）は `setup` に任せるのが最も楽です。
+AI ガード（`CLAUDE.md` / `AGENTS.md`）と hook 設定（`.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`）は `setup` に任せるのが最も楽です。Cursor 用 Guard は rc.4 から AGENTS.md に統一しました（`.cursor/rules/*.mdc` は条件付き読み込みのため）。
 
 ```bash
 # ガード追加・hook 設定のみ（パッケージインストールや scaffold はスキップ）

package/lib/anti-pattern-rules.js

@@ -925,7 +925,7 @@ const ANTI_PATTERN_GROUPS = [
     check: {
       description: 'Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない',
       recommendation:
-        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。',
+        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同一行または直前行に `// sparkle-disable-line tailwind-typography` コメントを付けて例外扱いとして残すこともできます。',
       pattern: /\b(text-(?:xs|sm|base|lg|xl|2xl)|font-(?:medium|semibold|bold|normal|light))\b/g,
     },
     featureSection: lines([
@@ -937,9 +937,15 @@ const ANTI_PATTERN_GROUPS = [
       '',
       '// ❌ Wrong — Tailwind デフォルトの typography を使わない',
       '<span className="text-sm font-medium">テキスト</span>',
+      '',
+      '// 例外 — character-* に対応するサイズが無い場合は arbitrary value を使うか',
+      '// suppress コメントを付けて残す',
+      '<span className="text-[10px] text-text-low">12px 未満の極小メタ情報</span>',
+      '{/* sparkle-disable-next-line tailwind-typography */}',
+      '<span className="text-xs">どうしても text-xs で残したいケース</span>',
       '```',
       '',
-      'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。Tailwind の `text-sm` / `font-medium` 等は使わない。',
+      'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。character-1（12px）より小さい指定や、対応 token が無いサイズは Tailwind の arbitrary value (`text-[10px]` 等) で表現するか、`// sparkle-disable-line tailwind-typography` で個別に例外指定する。',
     ]),
     jsdocTargets: [],
   },

package/lib/check.js

@@ -85,8 +85,66 @@ function formatSnippet(text) {
   return text.replace(/\s+/g, ' ').trim().slice(0, 120);
 }
 
+/**
+ * ESLint 風の suppression コメントをサポートする。以下のいずれかが findings
+ * と同じ行、または直前行にあれば該当 rule の finding は emit しない:
+ *
+ *   // sparkle-disable-line <rule-id>
+ *   // sparkle-disable-next-line <rule-id>
+ *   {/* sparkle-disable-line <rule-id> *\/}   （JSX コメント）
+ *
+ * ユーザーがどうしても character-* に移行できない typography（token に
+ * 存在しないサイズなど）や、特定 file だけ例外扱いしたい場合の escape
+ * hatch として用意する。ルール ID は複数カンマ区切り可（例:
+ * `sparkle-disable-line tailwind-typography, card-padding-override`）。
+ *
+ * en: ESLint-style suppression comments so specific findings can be opted
+ * out when character-* / Sparkle tokens don't map cleanly (e.g. sub-token
+ * font sizes). Same-line or previous-line comment is honored.
+ */
+const SUPPRESS_LINE = /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
+const SUPPRESS_NEXT_LINE =
+  /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-next-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
+
+function extractSuppressedRules(source, regex) {
+  if (!source) return null;
+  const m = source.match(regex);
+  if (!m) return null;
+  return new Set(
+    m[1]
+      .split(',')
+      .map((id) => id.trim())
+      .filter(Boolean)
+  );
+}
+
+function isSuppressed(ruleId, contentLines, lineNumber) {
+  // lineNumber は 1-origin
+  // en: 1-based line numbers from getLineNumber.
+  const current = contentLines[lineNumber - 1] ?? '';
+  const previous = contentLines[lineNumber - 2] ?? '';
+  const sameLine = extractSuppressedRules(current, SUPPRESS_LINE);
+  if (sameLine && sameLine.has(ruleId)) return true;
+  const prevLine = extractSuppressedRules(previous, SUPPRESS_NEXT_LINE);
+  if (prevLine && prevLine.has(ruleId)) return true;
+  return false;
+}
+
 function collectFindings(filePath, content) {
   const findings = [];
+  const contentLines = content.split(/\r?\n/);
+  const pushFinding = (rule, index, snippet) => {
+    const line = getLineNumber(content, index ?? 0);
+    if (isSuppressed(rule.id, contentLines, line)) return;
+    findings.push({
+      filePath,
+      id: rule.id,
+      description: rule.description,
+      recommendation: rule.recommendation,
+      line,
+      snippet,
+    });
+  };
 
   for (const rule of RULES) {
     if (typeof rule.match === 'function') {
@@ -94,26 +152,12 @@ function collectFindings(filePath, content) {
       // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
       // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
       for (const hit of rule.match(content)) {
-        findings.push({
-          filePath,
-          id: rule.id,
-          description: rule.description,
-          recommendation: rule.recommendation,
-          line: getLineNumber(content, hit.index ?? 0),
-          snippet: formatSnippet(hit.text ?? ''),
-        });
+        pushFinding(rule, hit.index ?? 0, formatSnippet(hit.text ?? ''));
       }
       continue;
     }
     for (const match of content.matchAll(rule.pattern)) {
-      findings.push({
-        filePath,
-        id: rule.id,
-        description: rule.description,
-        recommendation: rule.recommendation,
-        line: getLineNumber(content, match.index ?? 0),
-        snippet: formatMatch(match),
-      });
+      pushFinding(rule, match.index ?? 0, formatMatch(match));
     }
   }
 

package/lib/setup.js

@@ -56,6 +56,15 @@ const config = {
 export default config;
 `;
 
+// Guard ブロックは「常に読まれる」ファイルだけに置く。Cursor は 2025 年後半
+// 以降 AGENTS.md を公式サポートしている（https://agents.md）ので、
+// `.cursor/rules/*.mdc`（frontmatter で `alwaysApply: true` を付けない限り
+// 条件付き読み込み）は使わない。条件付き読み込みは Guard が読まれない
+// セッションで silent に lint:sparkle 実行漏れを起こす。
+// en: Keep Guard on always-loaded files. `.cursor/rules/*.mdc` is loaded
+// conditionally unless `alwaysApply: true` is set in frontmatter, which
+// silently skips the Guard in some sessions. Cursor (Codex / Aider / Zed
+// / Gemini CLI etc.) all read AGENTS.md, so route Cursor through it.
 const ASSISTANT_CONFIG = {
   claude: {
     path: 'CLAUDE.md',
@@ -64,13 +73,20 @@ const ASSISTANT_CONFIG = {
     path: 'AGENTS.md',
   },
   cursor: {
-    path: '.cursor/rules/sparkle-design-guard.mdc',
+    path: 'AGENTS.md',
   },
   generic: {
     path: 'SPARKLE-DESIGN-AI.md',
   },
 };
 
+// 旧版（rc.3 以前）が cursor 用に書いていた `.mdc` パス。残骸を検出して
+// AGENTS.md への移行を促す warn に使う。silent 削除はしない（ユーザーが
+// frontmatter を付けて意図的に保持しているケースもあるため）。
+// en: Path used by rc.3 and earlier for cursor assistant. We keep it as a
+// constant so the migration warn can detect leftovers without re-typing.
+const LEGACY_CURSOR_GUARD_PATH = '.cursor/rules/sparkle-design-guard.mdc';
+
 const BLOCK_START = '<!-- sparkle-design-cli:setup:start -->';
 const BLOCK_END = '<!-- sparkle-design-cli:setup:end -->';
 const TARGET_CANDIDATES = ['src', 'src/components', 'src/features', 'app', 'components'];
@@ -206,8 +222,14 @@ function isManagedSparkleScript(value, mode) {
   return false;
 }
 
-function buildInstructionBlock(target, assistant) {
-  const heading = assistant === 'cursor' ? '# Sparkle Design Guard' : '## Sparkle Design Guard';
+function buildInstructionBlock(target, _assistant) {
+  // Guard ブロックは常に h2 で出す。rc.3 以前は cursor 用に独立 .mdc ファイル
+  // へ書いていたため h1 にしていたが、rc.4 で AGENTS.md に統一したため、
+  // 親ファイルの heading 階層に揃えて h2 が常に正しい。
+  // en: Always emit Guard as h2. rc.3 used h1 for the standalone cursor
+  // .mdc file, but rc.4 routes cursor through AGENTS.md so h2 fits the
+  // surrounding section hierarchy.
+  const heading = '## Sparkle Design Guard';
 
   return [
     BLOCK_START,
@@ -220,7 +242,7 @@ function buildInstructionBlock(target, assistant) {
     '  - Sparkle fonts (Google Fonts preconnect + Material Symbols + the configured pro/mono fonts) must be present in the document `<head>`: React layouts via `<SparkleHead />` placed inside `<head>` in the root layout, Vite projects via the managed `<!-- sparkle-design-cli:fonts:start -->` … `end` block in `index.html`.',
     '  - Do **not** hand-define `--color-primary-*` or other Sparkle tokens as fallbacks when they look missing. Those come from `sparkle-design.css`; missing values mean the `@import` path is wrong (e.g. `./sparkle-design.css` used when the file lives under `./app/`). Fix the import path, do not duplicate the tokens.',
     '  - If you detect any of the above drifted, re-run `npx --yes sparkle-design-cli generate` before hand-editing. The CLI restores the canonical state (correct relative paths, `@source` placement, `index.html` injection).',
-    '- **Required**: After creating or modifying any UI component, run `lint:sparkle` before finishing. This catches Sparkle Design anti-patterns.',
+    '- **Required**: After creating or modifying any UI component, run `lint:sparkle` before finishing. This catches Sparkle Design anti-patterns. To opt out a specific line from a rule when the Sparkle token does not map cleanly (e.g. sub-12px font sizes for `tailwind-typography`), add `// sparkle-disable-line <rule-id>` on the same line or `// sparkle-disable-next-line <rule-id>` on the line above — but use it sparingly and only when the migration would actually break the design.',
     `- For AI review, prefer \`lint:sparkle:json\` or run \`npx --yes sparkle-design-cli check ${target} --format json\` directly.`,
     '- You must inspect every entry in both `findings` and `manualReviewReminders`. For each entry in `manualReviewReminders`, **echo the reminder ID in your final reply together with a short review note** (e.g. `[badge-tag-semantics] reviewed — Badge is used only for counts, so the usage is fine.`). Silence on a reminder means it was skipped; always state at least a one-line judgment per ID. This is not blocked by the Stop hook (reminders are judgment calls), but reviewers / humans rely on the explicit acknowledgment to trust that each item was actually considered.',
     BLOCK_END,
@@ -243,10 +265,7 @@ function updateInstructionFile(filePath, block) {
         `⚠️  ${filePath} に Sparkle Design Guard ブロックが ${markerCount} 個見つかりました。すべて最新版で置き換えます（手動でコピーした古い block が残っている可能性があります）。`
       );
     }
-    const next = current.replace(
-      new RegExp(`${BLOCK_START}[\\s\\S]*?${BLOCK_END}`, 'g'),
-      block
-    );
+    const next = current.replace(new RegExp(`${BLOCK_START}[\\s\\S]*?${BLOCK_END}`, 'g'), block);
     return { changed: next !== current, content: next, existed: exists };
   }
 
@@ -510,6 +529,42 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
     }
   }
 
+  // rc.4 で Cursor の Guard 出力先を `.cursor/rules/sparkle-design-guard.mdc`
+  // から AGENTS.md に移したため、再 setup 時に旧 .mdc が残っているとガードが
+  // 二重定義になる（しかも .mdc は frontmatter 次第で読まれない場合がある）。
+  // silent 削除はせず、警告だけ出して移行判断はユーザーに委ねる。Cursor 以外
+  // のアシスタントでも、過去に cursor → 別 assistant に切り替えたユーザーが
+  // いるので assistant 値に関係なくチェックする。
+  // en: rc.4 moved Cursor Guard from `.cursor/rules/*.mdc` to AGENTS.md.
+  // Detect leftovers and warn the user instead of deleting silently — the
+  // .mdc may still be intentionally retained with `alwaysApply: true`.
+  let legacyCursorGuard = null;
+  if (!options.instructionsPath) {
+    const legacyPath = path.resolve(cwd, LEGACY_CURSOR_GUARD_PATH);
+    if (fs.existsSync(legacyPath)) {
+      try {
+        const content = fs.readFileSync(legacyPath, 'utf8');
+        // BLOCK_START だけでなく BLOCK_END も含み、かつ START が END より
+        // 前にある完全な block の場合のみ legacy 判定する。途中で削れた断片や
+        // ユーザーが手動でコピーした start マーカーだけ残っているケースを
+        // legacy 警告対象から外す（false positive 防止）。
+        // en: Require both markers in the correct order so partial fragments
+        // don't trigger the migration warn.
+        const startIndex = content.indexOf(BLOCK_START);
+        const endIndex = content.indexOf(BLOCK_END);
+        if (startIndex !== -1 && endIndex !== -1 && startIndex < endIndex) {
+          legacyCursorGuard = { path: legacyPath };
+        }
+      } catch (error) {
+        // 読み込み失敗（権限等）は legacy 検知だけスキップ。setup 本体は続行。
+        // en: Skip legacy detection on read failure; do not block setup.
+        console.warn(
+          `⚠️  ${LEGACY_CURSOR_GUARD_PATH} の読み込みに失敗したため legacy ガード検出をスキップします (${error.code ?? error.message})`
+        );
+      }
+    }
+  }
+
   if (!options.dryRun) {
     if (packageResult.changed) writeJson(packageJsonPath, packageResult.packageJson);
     if (instructionResult.changed) {
@@ -530,6 +585,7 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
     instructionResult,
     agentsInstructionPath,
     agentsInstructionResult,
+    legacyCursorGuard,
   };
 }
 
@@ -624,12 +680,9 @@ function runClaudeHook(cwd, target, dryRun) {
   const managedCommand = buildManagedHookCommand(target);
   const { existed, config } = loadHookJson(settingsPath, '.claude/settings.json');
 
-  const nextSettings =
-    typeof config === 'object' && config ? { ...config } : {};
+  const nextSettings = typeof config === 'object' && config ? { ...config } : {};
   const hooks =
-    typeof nextSettings.hooks === 'object' && nextSettings.hooks
-      ? { ...nextSettings.hooks }
-      : {};
+    typeof nextSettings.hooks === 'object' && nextSettings.hooks ? { ...nextSettings.hooks } : {};
   const stopGroups = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
 
   const alreadyPresent = stopGroups.some(
@@ -908,6 +961,11 @@ export function setupAssistant(options = {}) {
           existed: guard.agentsInstructionResult?.existed ?? false,
         }
       : null,
+    legacyCursorGuard: guard.legacyCursorGuard
+      ? {
+          path: path.relative(cwd, guard.legacyCursorGuard.path),
+        }
+      : null,
     hook: hook
       ? {
           assistant: hook.assistant,
@@ -924,8 +982,7 @@ export function setupAssistant(options = {}) {
           sessionRootMismatch: hook.sessionRootMismatch
             ? {
                 detected: true,
-                sessionDir: path.relative(cwd, hook.sessionRootMismatch.sessionDir) ||
-                  '.',
+                sessionDir: path.relative(cwd, hook.sessionRootMismatch.sessionDir) || '.',
               }
             : null,
         }
@@ -937,7 +994,10 @@ export function setupAssistant(options = {}) {
   // セットアップ後のリマインダー。AI の会話履歴にも残るよう stderr に出す。
   // en: Post-setup reminder. Written to stderr so it stays in the AI transcript
   // without polluting the JSON stdout payload that tooling parses.
-  printPostSetupReminder(guard.target, packageManager, { hook });
+  printPostSetupReminder(guard.target, packageManager, {
+    hook,
+    legacyCursorGuard: guard.legacyCursorGuard,
+  });
 
   return summary;
 }
@@ -965,7 +1025,7 @@ const HOOK_LABELS = {
   codex: { name: 'Codex', file: '.codex/hooks.json', event: 'Stop' },
 };
 
-function printPostSetupReminder(target, packageManager, { hook } = {}) {
+function printPostSetupReminder(target, packageManager, { hook, legacyCursorGuard } = {}) {
   const lintTarget = target || 'src';
   const lintCmd = buildLintCommand(packageManager);
   const lines = [
@@ -1001,6 +1061,12 @@ function printPostSetupReminder(target, packageManager, { hook } = {}) {
       );
     }
   }
+  if (legacyCursorGuard) {
+    lines.push(
+      `  ⚠️  ${legacyCursorGuard.path} に旧バージョンの Sparkle Design Guard ブロックが残っています。rc.4 で Cursor のガードは AGENTS.md に統一されました（Cursor の \`.cursor/rules/*.mdc\` は frontmatter で \`alwaysApply: true\` を付けないと条件付き読み込みになり、ガードが silent に skip される問題があるため）。重複防止のため旧 .mdc を削除するか、\`alwaysApply: true\` の frontmatter を付けて意図的に残す運用に切り替えてください。`,
+      `  ⚠️  Found leftover Sparkle Design Guard in ${legacyCursorGuard.path}. rc.4 routes Cursor Guard through AGENTS.md (\`.cursor/rules/*.mdc\` is conditionally loaded unless \`alwaysApply: true\` is set). Either delete the legacy .mdc or add \`alwaysApply: true\` frontmatter to keep it deliberately.`
+    );
+  }
   lines.push('');
   for (const line of lines) {
     console.error(line);

package/package.json

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