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

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

@@ -220,7 +220,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,

package/package.json

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