sparkle-design-cli 1.3.9 → 1.3.10

package/README.md

@@ -1,6 +1,6 @@
 # Sparkle Design CLI
 
-デザインシステム CSS の生成と、Sparkle Design のアンチパターン検査を行う CLI ツールです。
+Sparkle Design の CSS 生成、導入先プロジェクト向けのアンチパターン検査、AI エージェント向け guard 設定を行う CLI ツールです。
 
 ## インストール
 
@@ -18,6 +18,12 @@ npx sparkle-design-cli generate
 
 # アンチパターンを検査
 npx sparkle-design-cli check src --strict
+
+# AI 向けに JSON で検査結果と手動確認項目を取得
+npx sparkle-design-cli check src --format json
+
+# Claude / Codex / Cursor 向けの guard 設定を差し込む
+npx sparkle-design-cli setup --assistant claude
 ```
 
 ### 後方互換モード
@@ -85,6 +91,9 @@ sparkle-design-cli check
 # 特定ディレクトリを strict モードで検査
 sparkle-design-cli check src/components src/features --strict
 
+# AI 向けに JSON 出力
+sparkle-design-cli check src --format json
+
 # check のヘルプを表示
 sparkle-design-cli check --help
 ```
@@ -93,13 +102,24 @@ sparkle-design-cli check --help
 
 - `-h, --help`: ヘルプメッセージを表示
 - `--strict`: 違反が見つかった場合に exit code 1 で終了
+- `--format <text|json>`: 出力形式。AI 連携では `json` を推奨
 
 #### 現在検出するルール
 
 - フォーム入力に Dialog を使わない
 - DialogCancel/DialogAction を Button で二重ラップしない
+- children なしの Button に prefixIcon / suffixIcon を使わない
+- Material Symbols を className 直書きで使わない
 - shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない
 
+#### Manual Review Reminders
+
+`--format json` では、機械検出できない観点も `manualReviewReminders` として返します。現在は次を含みます。
+
+- Badge と Tag の意味的な使い分け
+- CardDescription の typography / color token 明示
+- Dialog と Modal の UX 上の使い分け
+
 #### 導入先での推奨設定
 
 ```json
@@ -112,6 +132,39 @@ sparkle-design-cli check --help
 
 AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
+### setup: AI ガード設定の差し込み
+
+`sparkle-design-cli setup` は、導入先プロジェクトの `package.json` と AI 向け指示ファイルに Sparkle Design guard を追加します。
+
+```bash
+# Claude Code 向け
+sparkle-design-cli setup --assistant claude
+
+# Codex / AGENTS.md 向け
+sparkle-design-cli setup --assistant codex
+
+# Cursor rules 向け
+sparkle-design-cli setup --assistant cursor
+
+# generic な Markdown を生成
+sparkle-design-cli setup --assistant generic
+```
+
+追加されるもの:
+- `package.json` の `lint:sparkle`
+- `package.json` の `lint:sparkle:json`
+- assistant ごとの指示ファイルへの managed block
+
+`--target` を省略した場合は `src`, `src/components`, `src/features`, `app`, `components` の順で自動検出します。既存の `lint:sparkle*` がすでに Sparkle Design 向け script なら再実行時に更新されます。独自 script は保持され、上書きしたい場合だけ `--force-script-update` を付けます。
+
+利用できる assistant:
+- `claude`: `CLAUDE.md`
+- `codex`: `AGENTS.md`
+- `cursor`: `.cursor/rules/sparkle-design-guard.mdc`
+- `generic`: `SPARKLE-DESIGN-AI.md`
+
+`setup` は通常実行時も JSON サマリーを stdout に表示します。`--dry-run` を付けると、その JSON を表示したままファイル変更だけを抑止します。
+
 ## 設定ファイル (sparkle.config.json)
 
 ### 設定ファイルの作成

package/bin/sparkle-design.js

@@ -2,8 +2,9 @@
 
 import { generateCSS } from '../lib/generate-css.js';
 import { checkProject } from '../lib/check.js';
+import { setupAssistant } from '../lib/setup.js';
 
-const SUBCOMMANDS = new Set(['generate', 'check']);
+const SUBCOMMANDS = new Set(['generate', 'check', 'setup']);
 
 function requireOptionValue(args, index, flags) {
   const value = args[index + 1];
@@ -43,6 +44,7 @@ function parseCheckOptions(args) {
   const options = {
     targets: [],
     strict: false,
+    format: 'text',
     help: false,
   };
 
@@ -53,6 +55,13 @@ function parseCheckOptions(args) {
       options.help = true;
     } else if (arg === '--strict') {
       options.strict = true;
+    } else if (arg === '--format') {
+      const value = requireOptionValue(args, i, '--format');
+      if (value !== 'text' && value !== 'json') {
+        throw new Error(`Unsupported format for check: ${value}`);
+      }
+      options.format = value;
+      i += 1;
     } else if (arg.startsWith('-')) {
       throw new Error(`Unknown option for check: ${arg}`);
     } else {
@@ -63,6 +72,38 @@ function parseCheckOptions(args) {
   return options;
 }
 
+function parseSetupOptions(args) {
+  const options = {
+    assistant: 'generic',
+    target: null,
+    dryRun: false,
+    forceScriptUpdate: 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 === '--assistant') {
+      options.assistant = requireOptionValue(args, i, '--assistant');
+      i += 1;
+    } else if (arg === '--target') {
+      options.target = requireOptionValue(args, i, '--target');
+      i += 1;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--force-script-update') {
+      options.forceScriptUpdate = true;
+    } else {
+      throw new Error(`Unknown option for setup: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
 function showHelp() {
   console.log(`
 Sparkle Design CLI
@@ -73,6 +114,7 @@ Sparkle Design CLI
 Commands:
   generate   sparkle.config.json から CSS を生成
   check      Sparkle Design のアンチパターンを検査
+  setup      AI エージェント向けの guard 設定を導入
 
 後方互換:
   sparkle-design-cli [generate options]
@@ -88,8 +130,15 @@ Generate:
 Check:
   sparkle-design-cli check
   sparkle-design-cli check src --strict
+  sparkle-design-cli check src --format json
   sparkle-design-cli check src/components src/features
 
+Setup:
+  sparkle-design-cli setup --assistant claude
+  sparkle-design-cli setup --assistant codex --target src
+  sparkle-design-cli setup --assistant cursor --dry-run
+  sparkle-design-cli setup --assistant claude --force-script-update
+
 Generate options:
   -h, --help                 このヘルプメッセージを表示
   -c, --config <path>        設定ファイルのパス (default: ./sparkle.config.json)
@@ -98,11 +147,23 @@ Generate options:
 Check options:
   -h, --help                 このヘルプメッセージを表示
   --strict                   違反があれば exit code 1 で終了
+  --format <text|json>       出力形式 (default: text)
+
+Setup options:
+  -h, --help                 このヘルプメッセージを表示
+  --assistant <name>         claude / codex / cursor / generic (default: generic)
+  --target <path>            lint 対象パス (default: auto-detect)
+  --dry-run                  ファイルを変更せず結果だけ表示
+  --force-script-update      既存の lint:sparkle 系 script も上書きする
 
 Check で検出する主なパターン:
   - フォーム入力に Dialog を使っている
   - DialogCancel / DialogAction を <Button> で二重ラップしている
+  - children なしの Button に prefixIcon / suffixIcon を使っている
+  - Material Symbols を className 直書きしている
   - text-muted-foreground / bg-background / border-border を持ち込んでいる
+
+JSON 出力では manualReviewReminders も返すため、AI から実行する場合は --format json を推奨
 `);
 }
 
@@ -148,13 +209,28 @@ function main() {
         process.exit(0);
       }
 
-      const hasFindings = checkProject(options.targets, { strict: options.strict });
+      const hasFindings = checkProject(options.targets, {
+        strict: options.strict,
+        format: options.format,
+      });
       if (hasFindings && options.strict) {
         process.exit(1);
       }
       return;
     }
 
+    if (command === 'setup') {
+      const options = parseSetupOptions(args.slice(1));
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      setupAssistant(options);
+      return;
+    }
+
     if (!SUBCOMMANDS.has(command) && command.startsWith('-')) {
       showGenerateDeprecationNotice();
       const options = parseGenerateOptions(args);

package/lib/anti-pattern-rules.js

@@ -23,6 +23,25 @@ function renderJSDocSection(section) {
   return output.map((line) => (line ? ` * ${line}` : ' *')).join('\n');
 }
 
+
+const MANUAL_REVIEW_REMINDERS = [
+  {
+    id: 'badge-tag-semantics',
+    message:
+      'Badge と Tag の使い分けが意味的に正しいか確認してください。数値情報は Badge、ラベリングやステータス表示は Tag を使います。',
+  },
+  {
+    id: 'card-description-typography',
+    message:
+      'CardDescription に typography / color token が明示されているか確認してください。補足テキストには className で token を指定します。',
+  },
+  {
+    id: 'dialog-modal-ux',
+    message:
+      'Dialog が確認用途、Modal が入力・詳細表示用途になっているか確認してください。文脈判断が必要なケースは機械検出されません。',
+  },
+];
+
 const ANTI_PATTERN_GROUPS = [
   {
     id: 'card-description',
@@ -49,9 +68,43 @@ const ANTI_PATTERN_GROUPS = [
       '</CardHeader>',
       '```',
       '',
-      'CardTitle 内の補足情報や件数は CardDescription を使い、必要な typography / color token は className で明示する。',
+      'CardTitle 内の補足情報や件数は CardDescription を使い、必要な typography / color token は className で明示する。長い説明文は CardContent に配置する。',
     ]),
-    jsdocTargets: [],
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/card/index.tsx',
+        targetName: 'CardDescription',
+        section: {
+          bullets: [
+            {
+              ja: '`CardDescription` は CardTitle 内の短い補足テキスト用です。長い説明文は `CardContent` に配置してください。',
+              en: '`CardDescription` is for short supporting text inside CardTitle. Put long descriptive copy inside `CardContent`.',
+            },
+            {
+              ja: 'Typography や text color は用途に応じて className で明示してください。',
+              en: 'Specify typography and text color explicitly with className based on the use case.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<CardTitle>',
+            '  プロジェクト一覧',
+            '  <CardDescription className="character-3-regular-pro text-text-low">',
+            '    全 12 件',
+            '  </CardDescription>',
+            '</CardTitle>',
+            '',
+            '// ❌ Wrong - 長い説明文を CardTitle 内に入れない',
+            '<CardTitle>',
+            '  プロジェクト一覧',
+            '  <CardDescription>',
+            '    このカードはダッシュボードで重要な進捗と担当者の状態を表示します。',
+            '  </CardDescription>',
+            '</CardTitle>',
+          ]),
+        },
+      },
+    ],
   },
   {
     id: 'size-alignment',
@@ -72,7 +125,7 @@ const ANTI_PATTERN_GROUPS = [
       '</div>',
       '```',
       '',
-      'Input / Select / Textarea のデフォルトサイズは md。横並びの Button も原則 md に合わせる。テーブル内アクションなど独立した Button は sm でよい。',
+      'Input / Select / Textarea のデフォルトサイズは md。横並びの Button も原則 md に合わせる。省スペース UI では Input と Button を揃えて sm にしてよい。テーブル内アクションなど独立した Button は sm でよい。',
     ]),
     jsdocTargets: [
       {
@@ -85,8 +138,12 @@ const ANTI_PATTERN_GROUPS = [
               en: 'Do not manually place an IconButton next to Input. Use `isTrigger` / `triggerIcon` props instead.',
             },
             {
-              ja: 'Input と横並びの Button は原則同じサイズにしてください。デフォルトの Input に対しては `Button size="md"` を使ってください。',
-              en: 'Keep Button size aligned when placing it next to Input. Use `Button size="md"` with the default Input size.',
+              ja: 'Input と横並びの Button は原則同じサイズにしてください。デフォルトの Input には `Button size="md"`、省スペース UI では `Input size="sm"` と `Button size="sm"` を使ってください。',
+              en: 'Keep Button size aligned when placing it next to Input. Use `Button size="md"` with the default Input, or pair `Input size="sm"` with `Button size="sm"` in compact UIs.',
+            },
+            {
+              ja: '無効状態は `isDisabled` を優先して使ってください。HTML 標準の `disabled` も互換のため受け付けますが、Sparkle Design のコードでは `isDisabled` に統一します。',
+              en: 'Prefer `isDisabled` for disabled state. The native `disabled` prop is still supported for compatibility, but Sparkle Design code should standardize on `isDisabled`.',
             },
           ],
           example: lines([
@@ -102,6 +159,11 @@ const ANTI_PATTERN_GROUPS = [
             '    <Input placeholder="検索..." />',
             '    <Button size="md">検索</Button>',
             '  </div>',
+            '  <div className="flex gap-2">',
+            '    <Input size="sm" placeholder="メッセージ" />',
+            '    <Button size="sm">送信</Button>',
+            '  </div>',
+            '  <Input isDisabled placeholder="無効状態" />',
             '</>',
             '',
             '// ❌ Wrong - 手動配置',
@@ -261,13 +323,22 @@ const ANTI_PATTERN_GROUPS = [
       '// ❌ Wrong - Icon を children に入れない（レイアウト崩れ・ローディング時に非表示にならない）',
       '<Button><Icon icon="check" /> 確定</Button>',
       '',
-      '// ❌ Wrong - アイコンのみのボタンは IconButton を使う',
-      '<Button><Icon icon="edit" /></Button>',
+      '// ❌ Wrong - children なしの Button + prefixIcon は IconButton に置き換える',
+      '<Button prefixIcon="close" aria-label="閉じる" />',
+      '',
+      '// ❌ Wrong - asChild では prefixIcon / suffixIcon / isLoading は反映されない',
+      '<Button asChild prefixIcon="add">',
+      '  <Link href="/items/new">新規作成</Link>',
+      '</Button>',
+      '',
       '// ✅ Correct',
       '<IconButton icon="edit" aria-label="編集" />',
+      '<Button asChild>',
+      '  <Link href="/items/new">新規作成</Link>',
+      '</Button>',
       '```',
       '',
-      '> Button は size に応じてアイコンサイズを自動設定する（sm→4, md→5, lg→6）。isLoading 時にアイコンを自動で非表示にする。',
+      '> Button は size に応じてアイコンサイズを自動設定する（sm→4, md→5, lg→6）。isLoading 時にアイコンを自動で非表示にする。`asChild` 使用時はアイコンやローディング表現をスロット先で組み立てる。',
     ]),
     jsdocTargets: [
       {
@@ -283,6 +354,10 @@ const ANTI_PATTERN_GROUPS = [
               ja: 'アイコンのみのボタンには `IconButton` を使用してください。',
               en: 'Use `IconButton` for icon-only buttons.',
             },
+            {
+              ja: '`asChild` 使用時は `prefixIcon` / `suffixIcon` / `isLoading` が反映されません。必要ならスロット先でアイコンやローディング表現を構成してください。',
+              en: 'In `asChild` mode, `prefixIcon`, `suffixIcon`, and `isLoading` are ignored. Render icons and loading states inside the slotted child when needed.',
+            },
           ],
           example: lines([
             '// ✅ Correct',
@@ -291,10 +366,19 @@ const ANTI_PATTERN_GROUPS = [
             '// ❌ Wrong - Icon を children に入れない',
             '<Button><Icon icon="check" /> 確定</Button>',
             '',
-            '// ❌ Wrong - アイコンのみは IconButton を使う',
-            '<Button><Icon icon="edit" /></Button>',
+            '// ❌ Wrong - children なしの Button + prefixIcon は IconButton に置き換える',
+            '<Button prefixIcon="close" aria-label="閉じる" />',
+            '',
+            '// ❌ Wrong - asChild では prefixIcon は反映されない',
+            '<Button asChild prefixIcon="add">',
+            '  <Link href="/items/new">新規作成</Link>',
+            '</Button>',
+            '',
             '// ✅ Correct',
             '<IconButton icon="edit" aria-label="編集" />',
+            '<Button asChild>',
+            '  <Link href="/items/new">新規作成</Link>',
+            '</Button>',
           ]),
         },
       },
@@ -310,7 +394,8 @@ const ANTI_PATTERN_GROUPS = [
       '<CardHeader>',
       '  <CardTitle>タイトル</CardTitle>',
       '  <CardControl>',
-      '    <Button>アクション</Button>',
+      '    <Button theme="neutral" variant="outline">キャンセル</Button>',
+      '    <Button>保存</Button>',
       '  </CardControl>',
       '</CardHeader>',
       '',
@@ -322,6 +407,8 @@ const ANTI_PATTERN_GROUPS = [
       '  </div>',
       '</CardHeader>',
       '```',
+      '',
+      '`CardControl` は既定で `flex items-center gap-2` を持つ。複数アクションでも追加の layout class は不要。',
     ]),
     jsdocTargets: [
       {
@@ -337,6 +424,10 @@ const ANTI_PATTERN_GROUPS = [
               ja: 'CardTitle の補足情報や件数は、`span` などを直書きせず `CardDescription` を使ってください。',
               en: 'For supporting text or counts inside CardTitle, do not inline a `span`; use `CardDescription`.',
             },
+            {
+              ja: '`CardDescription` はタイトルの補足テキスト用です。長い説明文は `CardContent` に配置してください。',
+              en: 'Use `CardDescription` for short supporting text in CardTitle. Put long descriptive copy inside `CardContent`.',
+            },
           ],
           example: lines([
             '// ✅ Correct',
@@ -348,7 +439,8 @@ const ANTI_PATTERN_GROUPS = [
             '    </CardDescription>',
             '  </CardTitle>',
             '  <CardControl>',
-            '    <Button>アクション</Button>',
+            '    <Button theme="neutral" variant="outline">キャンセル</Button>',
+            '    <Button>保存</Button>',
             '  </CardControl>',
             '</CardHeader>',
             '',
@@ -356,7 +448,8 @@ const ANTI_PATTERN_GROUPS = [
             '<CardHeader>',
             '  <div className="flex justify-between">',
             '    <CardTitle>タイトル</CardTitle>',
-            '    <Button>アクション</Button>',
+            '    <Button theme="neutral" variant="outline">キャンセル</Button>',
+            '    <Button>保存</Button>',
             '  </div>',
             '</CardHeader>',
             '',
@@ -370,6 +463,25 @@ const ANTI_PATTERN_GROUPS = [
           ]),
         },
       },
+      {
+        file: 'src/components/ui/card/index.tsx',
+        targetName: 'CardControl',
+        section: {
+          bullets: [
+            {
+              ja: 'CardHeader の右側アクションは `CardControl` に集約してください。複数ボタンでも追加の layout class は不要です。',
+              en: 'Place right-side actions in `CardControl`. No extra layout classes are needed even with multiple buttons.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<CardControl>',
+            '  <Button theme="neutral" variant="outline">キャンセル</Button>',
+            '  <Button>保存</Button>',
+            '</CardControl>',
+          ]),
+        },
+      },
     ],
   },
   {
@@ -428,6 +540,92 @@ const ANTI_PATTERN_GROUPS = [
       },
     ],
   },
+  {
+    id: 'button-icon-only',
+    check: {
+      description: 'children なしの Button に prefixIcon / suffixIcon を使わない',
+      recommendation:
+        'アイコンのみのアクションは IconButton を使ってください。Button に prefixIcon / suffixIcon だけを渡さないでください。',
+      pattern:
+        /<Button\b(?=[^>]*\b(?:prefixIcon|suffixIcon)=)[^>]*\/\s*>|<Button\b(?=[^>]*\b(?:prefixIcon|suffixIcon)=)[^>]*>\s*<\/Button>/g,
+    },
+    featureSection: lines([
+      '### children なしの Button + prefixIcon / suffixIcon を使わない',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<IconButton icon="close" aria-label="閉じる" />',
+      '',
+      '// ❌ Wrong - children なしの Button + prefixIcon',
+      '<Button prefixIcon="close" aria-label="閉じる" />',
+      '```',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'material-symbols-direct',
+    check: {
+      description: 'Material Symbols を className 直書きで使わない',
+      recommendation:
+        'Material Symbols は Icon / IconButton コンポーネント経由で使ってください。`material-symbols-rounded` を直接書かないでください。',
+      pattern:
+        /<[^>]+\bclassName\s*=\s*(?:"[^"]*\bmaterial-symbols-rounded\b[^"]*"|'[^']*\bmaterial-symbols-rounded\b[^']*'|\{[^}]*\bmaterial-symbols-rounded\b[^}]*\})[^>]*>/g,
+    },
+    featureSection: lines([
+      '### Material Symbols を直書きしない',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<Icon icon="content_copy" size={4} />',
+      '<IconButton icon="content_copy" size="xs" aria-label="コピー" />',
+      '',
+      '// ❌ Wrong - material-symbols-rounded を直書きしない',
+      '<span className="material-symbols-rounded text-sm">content_copy</span>',
+      '```',
+      '',
+      'Material Symbols は `Icon` / `IconButton` 経由で使用する。直書きするとフォント読み込みタイミングでアイコン名テキストが見えることがある。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/icon/index.tsx',
+        targetName: 'Icon',
+        section: {
+          bullets: [
+            {
+              ja: '`material-symbols-rounded` を `span` に直書きせず、`Icon` を使ってください。',
+              en: 'Use `Icon` instead of writing `material-symbols-rounded` directly on a span.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<Icon icon="content_copy" size={4} />',
+            '',
+            '// ❌ Wrong - className を直書きしない',
+            '<span className="material-symbols-rounded text-sm">content_copy</span>',
+          ]),
+        },
+      },
+      {
+        file: 'src/components/ui/icon-button/index.tsx',
+        targetName: 'IconButton',
+        section: {
+          bullets: [
+            {
+              ja: 'アイコンだけのアクションでは `Button` + `prefixIcon` ではなく `IconButton` を使ってください。',
+              en: 'Use `IconButton` for icon-only actions instead of `Button` with `prefixIcon`.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<IconButton icon="content_copy" aria-label="コピー" />',
+            '',
+            '// ❌ Wrong - Icon-only action を Button で表現しない',
+            '<Button prefixIcon="content_copy" aria-label="コピー" />',
+          ]),
+        },
+      },
+    ],
+  },
   {
     id: 'dialog-button-wrap',
     check: {
@@ -664,7 +862,7 @@ const ANTI_PATTERN_GROUPS = [
 ];
 
 function getCheckRules() {
-  const order = ['dialog-form', 'dialog-button-wrap', 'shadcn-token'];
+  const order = ['dialog-form', 'dialog-button-wrap', 'button-icon-only', 'material-symbols-direct', 'shadcn-token'];
 
   return ANTI_PATTERN_GROUPS.filter((group) => group.check)
     .map((group) => ({
@@ -688,11 +886,16 @@ function renderFeatureSections() {
   return ANTI_PATTERN_GROUPS.map((group) => group.featureSection).join('\n\n');
 }
 
+function getManualReviewReminders() {
+  return MANUAL_REVIEW_REMINDERS;
+}
+
 export {
   ANTI_PATTERN_GROUPS,
   COMMON_INTRO,
   getAllJSDocTargets,
   getCheckRules,
+  getManualReviewReminders,
   renderFeatureSections,
   renderJSDocSection,
 };

package/lib/check.js

@@ -1,11 +1,16 @@
 import fs from 'fs';
 import path from 'path';
 
-import { getCheckRules } from './anti-pattern-rules.js';
+import { getCheckRules, getManualReviewReminders } from './anti-pattern-rules.js';
 
 const DEFAULT_TARGET = 'src';
 const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
 const RULES = getCheckRules();
+const MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
+
+function toRelativeReportPath(filePath) {
+  return path.relative(process.cwd(), filePath).split(path.sep).join('/');
+}
 
 function collectFiles(targetPath, files, visited) {
   if (!fs.existsSync(targetPath)) {
@@ -68,7 +73,7 @@ function collectFindings(filePath) {
   return findings;
 }
 
-export function checkProject(targets = [], options = {}) {
+function createCheckReport(targets = []) {
   const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
   const files = new Set();
   const visited = new Set();
@@ -77,28 +82,93 @@ export function checkProject(targets = [], options = {}) {
     collectFiles(path.resolve(process.cwd(), target), files, visited);
   }
 
-  const findings = [...files].flatMap(collectFindings);
+  const checkedFiles = [...files]
+    .map((filePath) => toRelativeReportPath(filePath))
+    .sort((left, right) => left.localeCompare(right));
+  const findings = [...files]
+    .flatMap(collectFindings)
+    .map((finding) => ({
+      ...finding,
+      filePath: toRelativeReportPath(finding.filePath),
+    }))
+    .sort((left, right) => {
+      const fileComparison = left.filePath.localeCompare(right.filePath);
+      if (fileComparison !== 0) {
+        return fileComparison;
+      }
+
+      if (left.line !== right.line) {
+        return left.line - right.line;
+      }
+
+      return left.id.localeCompare(right.id);
+    });
+
+  return {
+    targets: resolvedTargets,
+    checkedFiles,
+    findings,
+    manualReviewReminders: MANUAL_REVIEW_REMINDERS,
+  };
+}
 
-  if (findings.length === 0) {
+function printTextReport(report, options = {}) {
+  if (report.findings.length === 0) {
     console.log('sparkle-design-cli check: no findings');
-    return false;
+  } else {
+    console.log(`sparkle-design-cli check: ${report.findings.length} finding(s)\n`);
+
+    for (const finding of report.findings) {
+      console.log(`${finding.filePath}:${finding.line} [${finding.id}] ${finding.description}`);
+      console.log(`  Recommendation: ${finding.recommendation}`);
+      console.log(`  Snippet: ${finding.snippet}`);
+      console.log('');
+    }
   }
 
-  console.log(`sparkle-design-cli check: ${findings.length} finding(s)\n`);
-
-  for (const finding of findings) {
-    const relativePath = path.relative(process.cwd(), finding.filePath);
-    console.log(`${relativePath}:${finding.line} [${finding.id}] ${finding.description}`);
-    console.log(`  Recommendation: ${finding.recommendation}`);
-    console.log(`  Snippet: ${finding.snippet}`);
-    console.log('');
+  console.log('Manual review reminders:');
+  for (const reminder of report.manualReviewReminders) {
+    console.log(`- [${reminder.id}] ${reminder.message}`);
   }
 
-  if (options.strict) {
+  if (options.strict && report.findings.length > 0) {
     console.error('sparkle-design-cli check: failed because --strict was specified');
   }
+}
+
+function printJsonReport(report, options = {}) {
+  const strictMode = Boolean(options.strict);
+  const passed = !(strictMode && report.findings.length > 0);
+
+  console.log(
+    JSON.stringify(
+      {
+        summary: {
+          targetCount: report.targets.length,
+          checkedFileCount: report.checkedFiles.length,
+          findingCount: report.findings.length,
+          strictMode,
+          passed,
+          exitCode: passed ? 0 : 1,
+        },
+        ...report,
+      },
+      null,
+      2
+    )
+  );
+}
+
+export function checkProject(targets = [], options = {}) {
+  const report = createCheckReport(targets);
+
+  if (options.format === 'json') {
+    printJsonReport(report, options);
+  } else {
+    printTextReport(report, options);
+  }
 
-  return true;
+  return report.findings.length > 0;
 }
 
-export { RULES, collectFindings };
+export { RULES, collectFindings, createCheckReport, MANUAL_REVIEW_REMINDERS };

package/lib/setup.js

@@ -0,0 +1,260 @@
+import fs from 'fs';
+import path from 'path';
+
+const ASSISTANT_CONFIG = {
+  claude: {
+    path: 'CLAUDE.md',
+  },
+  codex: {
+    path: 'AGENTS.md',
+  },
+  cursor: {
+    path: '.cursor/rules/sparkle-design-guard.mdc',
+  },
+  generic: {
+    path: 'SPARKLE-DESIGN-AI.md',
+  },
+};
+
+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'];
+const UNSAFE_TARGET_PATTERN = /[\s"'`;$&|<>()[\]{}\\]/;
+
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function normalizeTarget(cwd, target, sourceLabel) {
+  const trimmed = target.trim();
+
+  if (!trimmed) {
+    throw new Error(`Target path is empty (${sourceLabel})`);
+  }
+
+  if (path.isAbsolute(trimmed)) {
+    throw new Error(`Target path must be relative to the project root: ${trimmed}`);
+  }
+
+  if (UNSAFE_TARGET_PATTERN.test(trimmed)) {
+    throw new Error(
+      `Target path contains unsupported characters: ${trimmed}. Use a simple relative path without spaces or shell metacharacters.`
+    );
+  }
+
+  const normalized = path.posix.normalize(trimmed.replace(/\\/g, '/'));
+
+  if (normalized === '.' || normalized === '') {
+    throw new Error(`Target path is empty (${sourceLabel})`);
+  }
+
+  if (normalized.startsWith('../')) {
+    throw new Error(`Target path must stay inside the project root: ${trimmed}`);
+  }
+
+  const absolutePath = path.resolve(cwd, normalized);
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Target path does not exist: ${normalized}`);
+  }
+
+  return normalized;
+}
+
+function detectTarget(cwd) {
+  for (const candidate of TARGET_CANDIDATES) {
+    const absolutePath = path.resolve(cwd, candidate);
+    if (fs.existsSync(absolutePath)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    'Could not auto-detect a lint target. Pass --target with an existing relative path such as src or app.'
+  );
+}
+
+function isManagedSparkleScript(value, mode) {
+  if (!value || typeof value !== 'string') {
+    return false;
+  }
+
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.length < 3) {
+    return false;
+  }
+
+  if (tokens[0] !== 'sparkle-design-cli' || tokens[1] !== 'check') {
+    return false;
+  }
+
+  const hasStrict = tokens.includes('--strict');
+  const formatIndex = tokens.indexOf('--format');
+  const formatValue = formatIndex >= 0 ? tokens[formatIndex + 1] : null;
+
+  if (mode === 'strict') {
+    return hasStrict && formatIndex === -1;
+  }
+
+  if (mode === 'json') {
+    return formatIndex >= 0 && formatValue === 'json' && !hasStrict;
+  }
+
+  return false;
+}
+
+function buildInstructionBlock(target, assistant) {
+  const heading = assistant === 'cursor' ? '# Sparkle Design Guard' : '## Sparkle Design Guard';
+
+  return [
+    BLOCK_START,
+    heading,
+    '',
+    '- Run `lint:sparkle` when Sparkle Design changes are involved.',
+    `- For AI review, prefer \`lint:sparkle:json\` or run \`npx --yes sparkle-design-cli check ${target} --format json\` directly.`,
+    '- Always inspect both `findings` and `manualReviewReminders` from the JSON output.',
+    '- If semantic guidance is still needed, consult Sparkle Design docs and JSDoc examples.',
+    BLOCK_END,
+  ].join('\n');
+}
+
+function updateInstructionFile(filePath, block) {
+  const exists = fs.existsSync(filePath);
+  const current = exists ? fs.readFileSync(filePath, 'utf8') : '';
+
+  if (current.includes(BLOCK_START) && current.includes(BLOCK_END)) {
+    const next = current.replace(new RegExp(`${BLOCK_START}[\\s\\S]*?${BLOCK_END}`), block);
+    return { changed: next !== current, content: next, existed: exists };
+  }
+
+  const separator = current.trim().length > 0 ? '\n\n' : '';
+  return {
+    changed: true,
+    content: `${current}${separator}${block}\n`,
+    existed: exists,
+  };
+}
+
+function resolveScriptUpdate(existingValue, nextValue, mode, force) {
+  if (!existingValue) {
+    return { value: nextValue, changed: true, conflict: false, reason: 'created' };
+  }
+
+  if (existingValue === nextValue) {
+    return { value: existingValue, changed: false, conflict: false, reason: 'unchanged' };
+  }
+
+  if (force || isManagedSparkleScript(existingValue, mode)) {
+    return { value: nextValue, changed: true, conflict: false, reason: force ? 'forced' : 'updated' };
+  }
+
+  return { value: existingValue, changed: false, conflict: true, reason: 'preserved-custom' };
+}
+
+function updatePackageJson(filePath, target, force) {
+  const pkg = readJson(filePath);
+  const scripts = { ...(pkg.scripts ?? {}) };
+
+  const strictResult = resolveScriptUpdate(
+    scripts['lint:sparkle'],
+    `sparkle-design-cli check ${target} --strict`,
+    'strict',
+    force
+  );
+  const jsonResult = resolveScriptUpdate(
+    scripts['lint:sparkle:json'],
+    `sparkle-design-cli check ${target} --format json`,
+    'json',
+    force
+  );
+
+  scripts['lint:sparkle'] = strictResult.value;
+  scripts['lint:sparkle:json'] = jsonResult.value;
+
+  return {
+    changed: strictResult.changed || jsonResult.changed || !pkg.scripts,
+    packageJson: {
+      ...pkg,
+      scripts,
+    },
+    scriptResults: {
+      'lint:sparkle': strictResult,
+      'lint:sparkle:json': jsonResult,
+    },
+  };
+}
+
+export function setupAssistant(options = {}) {
+  const assistant = options.assistant ?? 'generic';
+  const cwd = process.cwd();
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.forceScriptUpdate);
+  const assistantConfig = ASSISTANT_CONFIG[assistant];
+
+  if (!assistantConfig) {
+    throw new Error(`Unsupported assistant: ${assistant}`);
+  }
+
+  const targetSource = options.target ? 'explicit' : 'auto';
+  const target = options.target
+    ? normalizeTarget(cwd, options.target, 'explicit')
+    : normalizeTarget(cwd, detectTarget(cwd), 'auto');
+
+  const packageJsonPath = path.resolve(cwd, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`package.json not found in ${cwd}`);
+  }
+
+  const instructionPath = path.resolve(cwd, assistantConfig.path);
+  const packageResult = updatePackageJson(packageJsonPath, target, force);
+  const instructionBlock = buildInstructionBlock(target, assistant);
+  const instructionResult = updateInstructionFile(instructionPath, instructionBlock);
+
+  if (!dryRun) {
+    if (packageResult.changed) {
+      writeJson(packageJsonPath, packageResult.packageJson);
+    }
+
+    if (instructionResult.changed) {
+      ensureDir(instructionPath);
+      fs.writeFileSync(instructionPath, instructionResult.content, 'utf8');
+    }
+  }
+
+  const summary = {
+    assistant,
+    target,
+    targetSource,
+    dryRun,
+    forceScriptUpdate: force,
+    packageJson: {
+      path: path.relative(cwd, packageJsonPath),
+      changed: packageResult.changed,
+      scripts: {
+        'lint:sparkle': packageResult.packageJson.scripts?.['lint:sparkle'] ?? null,
+        'lint:sparkle:json': packageResult.packageJson.scripts?.['lint:sparkle:json'] ?? null,
+      },
+      results: packageResult.scriptResults,
+    },
+    instructions: {
+      path: path.relative(cwd, instructionPath),
+      changed: instructionResult.changed,
+      existed: instructionResult.existed,
+    },
+  };
+
+  console.log(JSON.stringify(summary, null, 2));
+  return summary;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "1.3.9",
+  "version": "1.3.10",
   "description": "Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール",
   "main": "lib/generate-css.js",
   "type": "module",