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

package/lib/check.js

@@ -2,8 +2,13 @@ import fs from 'fs';
 import path from 'path';
 
 import {
+  BLOCKING_SEVERITIES,
   BUILTIN_ANTI_PATTERN_GROUPS,
   BUILTIN_MANUAL_REVIEW_REMINDERS,
+  DEFAULT_RULE_TARGETS,
+  DEFAULT_SEVERITY,
+  RULE_TARGET,
+  SEVERITY,
   getCheckRules,
   getManualReviewReminders,
 } from './anti-pattern-rules.js';
@@ -11,7 +16,9 @@ import { loadAntiPatternPlugins } from './load-plugins.js';
 import { MATCH_HELPERS } from './plugin-helpers.js';
 import { REGEX, FONT_DOMAINS } from './constants.js';
 
-const DEFAULT_TARGET = 'src';
+// stop-hook 側も「target 未指定時の既定」を知る必要があるので export する。
+// en: Exported so stop-hook can probe with the same default instead of hardcoding it.
+export const DEFAULT_TARGET = 'src';
 const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
 const CSS_EXTENSIONS = new Set(['.css']);
 
@@ -19,6 +26,56 @@ const CSS_EXTENSIONS = new Set(['.css']);
 // en: Synchronous built-in snapshot for backward-compatible export below.
 const BUILTIN_RULES = getCheckRules(BUILTIN_ANTI_PATTERN_GROUPS);
 
+const SEVERITY_ORDER = [SEVERITY.ERROR, SEVERITY.WARNING, SEVERITY.INFO];
+
+/**
+ * finding の severity を既知の値に丸める。
+ *
+ * `getCheckRules` を通れば正規化済みだが、`collectFindings` / `createCheckReport`
+ * は public export なので rule を直接渡す経路がある。そこを素通しにすると
+ * 「並び順は error 扱いなのに exit code 判定では非 error」という**判定ごとに
+ * 結論が変わる**状態になり、件数の内訳も合わなくなる。読み出し側を 1 つの
+ * 関数に集約して、どの判定でも同じ値を見るようにする。
+ * en: Coerce to a known severity at every read site so ordering, counting and
+ * the exit-code decision can never disagree about the same finding.
+ */
+function coerceSeverity(severity) {
+  return SEVERITY_ORDER.includes(severity) ? severity : DEFAULT_SEVERITY;
+}
+
+function severityRank(severity) {
+  return SEVERITY_ORDER.indexOf(coerceSeverity(severity));
+}
+
+/**
+ * `--strict` / stop-hook が失敗として扱う findings。
+ * `warning` / `info` は報告のみで exit code を変えない（issue #74）。
+ * en: Only blocking-severity findings affect the exit code.
+ */
+function blockingFindings(findings) {
+  return findings.filter((finding) => BLOCKING_SEVERITIES.has(coerceSeverity(finding.severity)));
+}
+
+function countBySeverity(findings) {
+  const counts = Object.fromEntries(SEVERITY_ORDER.map((severity) => [severity, 0]));
+  for (const finding of findings) {
+    counts[coerceSeverity(finding.severity)] += 1;
+  }
+  return counts;
+}
+
+function ruleAppliesTo(rule, fileKind) {
+  return (rule.targets ?? DEFAULT_RULE_TARGETS).includes(fileKind);
+}
+
+// NOTE: トークンを定義している CSS（CLI の生成物など）を使用側と取り違えない
+// ための判定は、ここではなく `anti-pattern-rules.js` の `migrationMatcher` が
+// 内容ベースで行う（同じファイルが宣言している変数への参照は報告しない）。
+// ファイル名で除外していたときは `generate --scope`（`-o` 必須で出力名が任意）
+// の生成物が素通りしていた。
+// en: Definition-vs-usage is decided by content in migrationMatcher, not by
+// filename — `generate --scope` output has an arbitrary name.
+
 const SPARKLE_HEAD_JSX_PATTERN = /<SparkleHead\s*\/?\s*>/;
 // CSP key が「実際の設定 key として記述されている」コンテキストに絞る。
 // 以前は単純に `/content-security-policy|.../i` だったため、コメント行
@@ -46,9 +103,28 @@ function toRelativeReportPath(filePath) {
 /**
  * ディレクトリを1回だけ走査し、テキストファイルと CSS ファイルを同時に収集する
  */
-function collectFiles(targetPath, textFiles, cssFiles, visited) {
+function collectFiles(targetPath, textFiles, cssFiles, visited, isUserTarget = false) {
   if (!fs.existsSync(targetPath)) {
-    throw new Error(`Target path does not exist: ${targetPath}`);
+    // cwd の案内を出してよいのは、ユーザーが渡した target を解決した 1 回目だけ。
+    // 再帰の途中で欠けるのは壊れた symlink や走査中の削除で、パスは既に絶対だから
+    // cwd は無関係。そこで「作業ディレクトリを確認してください」と言うと、
+    // 存在しない原因を追わせることになる。
+    // en: Only the user-supplied target can be a cwd problem. Deeper misses come
+    // from broken symlinks or concurrent deletion and are already absolute, so
+    // blaming cwd there sends the reader after a cause that does not exist.
+    if (!isUserTarget) {
+      throw new Error(
+        `Target path does not exist: ${targetPath}\n` +
+          `   走査中にパスが解決できませんでした（壊れた symlink か、走査中に削除された可能性があります）。` +
+          ` / Could not resolve this path while walking the tree (broken symlink or concurrent deletion).`
+      );
+    }
+    throw new Error(
+      `Target path does not exist: ${targetPath}\n` +
+        `   相対 path は現在の作業ディレクトリ（${process.cwd()}）基準で解決しています。` +
+        `別のディレクトリから実行していないか確認してください。` +
+        ` / Relative targets resolve against the current working directory.`
+    );
   }
 
   const realPath = fs.realpathSync(targetPath);
@@ -140,23 +216,37 @@ function isSuppressed(ruleId, contentLines, lineNumber) {
   return false;
 }
 
-function collectFindings(filePath, content, rules = BUILTIN_RULES) {
+function collectFindings(filePath, content, rules = BUILTIN_RULES, options = {}) {
+  const fileKind = options.fileKind ?? RULE_TARGET.SOURCE;
+  const onRuleError = options.onRuleError;
   const findings = [];
   const contentLines = content.split(/\r?\n/);
-  const pushFinding = (rule, index, snippet) => {
+  const pushFinding = (rule, index, snippet, recommendationOverride) => {
     const line = getLineNumber(content, index ?? 0);
     if (isSuppressed(rule.id, contentLines, line)) return;
     findings.push({
       filePath,
       id: rule.id,
+      // severity は getCheckRules で正規化済み。プラグイン rule が
+      // getCheckRules を経由せず直接渡されるテスト経路のために既定値も持たせる。
+      // en: Normalized in getCheckRules; the fallback covers rules injected
+      // directly in tests without going through it.
+      severity: coerceSeverity(rule.severity),
       description: rule.description,
-      recommendation: rule.recommendation,
+      // 移行ルールのように「マッチ 1 件ごとに移行先が変わる」ものは
+      // rule.match が hit ごとの recommendation を返す。無ければルール既定を使う。
+      // en: Per-occurrence recommendation from rule.match wins over the
+      // rule-level default (migration targets differ per match).
+      recommendation: recommendationOverride ?? rule.recommendation,
       line,
       snippet,
     });
   };
 
   for (const rule of rules) {
+    // ルールごとに対象ファイル種別が違う（既定は source のみ）。
+    if (!ruleAppliesTo(rule, fileKind)) continue;
+
     // rule ごとに try/catch で隔離する。1 つのプラグイン rule の throw / malformed
     // RegExp で sparkle-design-cli check 全体が落ちるのを防ぐ。loadAntiPatternPlugins の
     // 「warn して skip」と同じ failure mode に揃える。
@@ -178,7 +268,7 @@ function collectFindings(filePath, content, rules = BUILTIN_RULES) {
           throw new TypeError(`rule.match must return an array, got ${typeof hits}`);
         }
         for (const hit of hits) {
-          pushFinding(rule, hit?.index ?? 0, formatSnippet(hit?.text ?? ''));
+          pushFinding(rule, hit?.index ?? 0, formatSnippet(hit?.text ?? ''), hit?.recommendation);
         }
         continue;
       }
@@ -193,9 +283,17 @@ function collectFindings(filePath, content, rules = BUILTIN_RULES) {
       }
     } catch (error) {
       const message = error?.message ?? String(error);
-      console.warn(
-        `⚠️  sparkle-design-cli: rule "${rule.id ?? '(unknown)'}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
-      );
+      // ルールが落ちた = そのルールについては「違反ゼロ」ではなく「検査していない」。
+      // 呼び出し側に記録させてレポートに載せる（無ければ従来どおり warn するだけ）。
+      // en: A crashed rule means "not checked", not "clean" — hand it to the
+      // caller so it can surface in the report instead of only on stderr.
+      if (typeof onRuleError === 'function') {
+        onRuleError({ ruleId: rule.id ?? '(unknown)', filePath, message });
+      } else {
+        console.warn(
+          `⚠️  sparkle-design-cli: rule "${rule.id ?? '(unknown)'}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
+        );
+      }
     }
   }
 
@@ -214,6 +312,7 @@ function collectFontImportFindings(cssFiles) {
       findings.push({
         filePath,
         id: 'font-import-in-css',
+        severity: SEVERITY.ERROR,
         description:
           'CSS にフォント @import が残っています。SparkleHead コンポーネントに移行してください。',
         recommendation:
@@ -293,6 +392,7 @@ function collectNextjsCspFindings(cwd) {
       findings.push({
         filePath: configPath,
         id: 'csp-font-block',
+        severity: SEVERITY.ERROR,
         description: `CSP ヘッダーが設定されていますが、${missing} が許可されていない可能性があります。`,
         recommendation: `style-src に ${FONT_DOMAINS.GOOGLEAPIS} を、font-src に ${FONT_DOMAINS.GSTATIC} を追加してください。`,
         line: 1,
@@ -315,10 +415,10 @@ function createCheckReport(targets = [], options = {}) {
 
   // 1回のディレクトリ走査でテキストファイルと CSS ファイルを同時に収集
   for (const target of resolvedTargets) {
-    collectFiles(path.resolve(process.cwd(), target), textFiles, cssFiles, visited);
+    collectFiles(path.resolve(process.cwd(), target), textFiles, cssFiles, visited, true);
   }
 
-  const checkedFiles = [...textFiles]
+  const checkedFiles = [...textFiles, ...cssFiles]
     .map((filePath) => toRelativeReportPath(filePath))
     .sort((left, right) => left.localeCompare(right));
 
@@ -328,20 +428,67 @@ function createCheckReport(targets = [], options = {}) {
     fileContents.set(filePath, fs.readFileSync(filePath, 'utf8'));
   }
 
+  // 落ちたルールは rule ID 単位で 1 回だけ warn する。catch が (rule × file) 単位
+  // なので、素直に warn すると 500 ファイルのリポジトリで同じ行が 500 回出て
+  // 本当の findings がスクロールバックから押し出される。
+  // en: Deduplicate by rule ID — the catch is per (rule, file), so warning on
+  // every file would bury the real findings.
+  const skippedRuleMap = new Map();
+  const onRuleError = ({ ruleId, filePath, message }) => {
+    const existing = skippedRuleMap.get(ruleId);
+    if (existing) {
+      existing.fileCount += 1;
+      return;
+    }
+    skippedRuleMap.set(ruleId, {
+      ruleId,
+      message,
+      firstFile: toRelativeReportPath(filePath),
+      fileCount: 1,
+    });
+    console.warn(
+      `⚠️  sparkle-design-cli: rule "${ruleId}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
+    );
+  };
+
   const findings = [...fileContents.entries()]
-    .flatMap(([filePath, content]) => collectFindings(filePath, content, rules))
+    .flatMap(([filePath, content]) =>
+      collectFindings(filePath, content, rules, { fileKind: RULE_TARGET.SOURCE, onRuleError })
+    )
     .map((finding) => ({
       ...finding,
       filePath: toRelativeReportPath(finding.filePath),
     }));
 
+  // CSS も検査する。`--radius-halfModal` のような CSS 変数の直接参照は `.css` に
+  // こそ自然に書かれ、しかも消えてもビルドエラーにならず見た目だけ壊れる。
+  // 対象は `targets` に css を含むルールだけなので、既存ルールの挙動は変わらない。
+  // en: Scan CSS too — variable references live there and fail silently. Only
+  // rules that opted into `css` run, so existing rules are unaffected.
+  for (const filePath of cssFiles) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    findings.push(
+      ...collectFindings(filePath, content, rules, {
+        fileKind: RULE_TARGET.CSS,
+        onRuleError,
+      }).map((finding) => ({ ...finding, filePath: toRelativeReportPath(finding.filePath) }))
+    );
+  }
+
   const fontFindings = collectFontImportFindings(cssFiles);
   findings.push(...fontFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
 
   const cspFindings = collectNextjsCspFindings(process.cwd());
   findings.push(...cspFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
 
+  // severity の高い順 → ファイル → 行 → ID。移行期は warning が大量に出るため、
+  // ファイル順だけで並べると本当に直すべき error が warning に埋もれる。
+  // 既存ルールはすべて error なので、error 同士の相対順は従来どおり保たれる。
+  // en: Sort by severity first so migration warnings can't bury errors. All
+  // pre-existing rules are errors, so their relative order is unchanged.
   findings.sort((left, right) => {
+    const severityComparison = severityRank(left.severity) - severityRank(right.severity);
+    if (severityComparison !== 0) return severityComparison;
     const fileComparison = left.filePath.localeCompare(right.filePath);
     if (fileComparison !== 0) return fileComparison;
     if (left.line !== right.line) return left.line - right.line;
@@ -361,6 +508,12 @@ function createCheckReport(targets = [], options = {}) {
     targets: resolvedTargets,
     checkedFiles,
     findings,
+    // 「ルールが落ちて検査されなかった」ことをレポートに載せる。stderr の warn
+    // だけだと JSON を読む CI / AI には見えず、findings 0 件・passed true を
+    // 「クリーン」と誤読する。
+    // en: Surface skipped rules in the report — a stderr-only warning is
+    // invisible to JSON consumers, who would read 0 findings as "clean".
+    skippedRules: [...skippedRuleMap.values()],
     manualReviewReminders,
   };
 }
@@ -369,14 +522,29 @@ function printTextReport(report, options = {}) {
   if (report.findings.length === 0) {
     console.log('sparkle-design-cli check: no findings');
   } else {
-    console.log(`sparkle-design-cli check: ${report.findings.length} finding(s)\n`);
+    const counts = countBySeverity(report.findings);
+    const breakdown = SEVERITY_ORDER.filter((severity) => counts[severity] > 0)
+      .map((severity) => `${counts[severity]} ${severity}`)
+      .join(', ');
+    console.log(`sparkle-design-cli check: ${report.findings.length} finding(s) (${breakdown})\n`);
 
     for (const finding of report.findings) {
-      console.log(`${finding.filePath}:${finding.line} [${finding.id}] ${finding.description}`);
+      const severity = coerceSeverity(finding.severity);
+      console.log(
+        `${finding.filePath}:${finding.line} [${severity}] [${finding.id}] ${finding.description}`
+      );
       console.log(`  Recommendation: ${finding.recommendation}`);
       console.log(`  Snippet: ${finding.snippet}`);
       console.log('');
     }
+
+    if (counts[SEVERITY.WARNING] > 0 || counts[SEVERITY.INFO] > 0) {
+      console.log(
+        'Note: warning / info は報告のみで exit code には影響しません（--strict でも失敗しません）。' +
+          ' / warning and info findings are informational and never affect the exit code.'
+      );
+      console.log('');
+    }
   }
 
   const reminders = report.manualReviewReminders ?? [];
@@ -406,14 +574,43 @@ function printTextReport(report, options = {}) {
     console.log('=========================================================================');
   }
 
-  if (options.strict && report.findings.length > 0) {
+  const skipped = report.skippedRules ?? [];
+  if (skipped.length > 0) {
+    console.error('');
+    console.error(
+      `⚠️  ${skipped.length} 件のルールが実行に失敗して検査されていません（違反ゼロではなく「未検査」です）:`
+    );
+    for (const entry of skipped) {
+      console.error(
+        `   - [${entry.ruleId}] ${entry.message}（${entry.firstFile} を含む計 ${entry.fileCount} ファイル）`
+      );
+    }
+    console.error('');
+  }
+
+  if (options.strict && hasBlockingIssues(report)) {
     console.error('sparkle-design-cli check: failed because --strict was specified');
   }
 }
 
+/**
+ * `--strict` / stop-hook を失敗させるべきか。
+ *
+ * blocking severity の findings に加えて、**実行に失敗したルールがある場合も失敗**
+ * とする。ルールが落ちた状態は「違反ゼロ」ではなく「検査していない」であり、
+ * ここを通してしまうと検査が死んでいることに誰も気付けない。
+ * en: Also fail when a rule crashed — that state is "not checked", not "clean".
+ */
+function hasBlockingIssues(report) {
+  return blockingFindings(report.findings).length > 0 || (report.skippedRules ?? []).length > 0;
+}
+
 function printJsonReport(report, options = {}) {
   const strictMode = Boolean(options.strict);
-  const passed = !(strictMode && report.findings.length > 0);
+  const counts = countBySeverity(report.findings);
+  const blockingCount = blockingFindings(report.findings).length;
+  const skippedCount = (report.skippedRules ?? []).length;
+  const passed = !(strictMode && hasBlockingIssues(report));
   const reminders = report.manualReviewReminders ?? [];
 
   console.log(
@@ -423,6 +620,15 @@ function printJsonReport(report, options = {}) {
           targetCount: report.targets.length,
           checkedFileCount: report.checkedFiles.length,
           findingCount: report.findings.length,
+          // severity 別内訳。`blockingFindingCount` だけが exit code に効く。
+          // en: Only blockingFindingCount affects the exit code.
+          severityCounts: counts,
+          blockingFindingCount: blockingCount,
+          // 実行に失敗して検査されなかったルールの数。0 でないなら findings が
+          // 0 件でも「クリーン」とは言えない（--strict は失敗する）。
+          // en: Rules that crashed and therefore did not run. Non-zero means the
+          // report is incomplete, so --strict fails even with zero findings.
+          skippedRuleCount: skippedCount,
           reminderCount: reminders.length,
           // AI 向けの attention フラグ。reminder が 1 件でもあれば true になり、
           // AI は最終 response で各 reminder ID を echo する必要がある。
@@ -447,7 +653,13 @@ function printJsonReport(report, options = {}) {
   );
 }
 
-export async function checkProject(targets = [], options = {}) {
+/**
+ * `check` 本体。レポートを出力し、レポートそのものと「失敗させるべきか」を返す。
+ * stop-hook のように findings の内訳まで見たい呼び出し側のために report を返す。
+ * en: Runs the check, prints the report, and returns both the report and the
+ * blocking decision (stop-hook needs the breakdown, not just the boolean).
+ */
+export async function runCheck(targets = [], options = {}) {
   // Plugins are discovered from the consumer project's package.json deps. Errors are
   // already warn-and-skip inside loadAntiPatternPlugins, so we just consume the result.
   // en: Auto-discover plugins from cwd; loader handles its own failure reporting.
@@ -467,12 +679,26 @@ export async function checkProject(targets = [], options = {}) {
     printTextReport(report, options);
   }
 
-  return report.findings.length > 0;
+  return { report, blocked: hasBlockingIssues(report) };
+}
+
+export async function checkProject(targets = [], options = {}) {
+  const { blocked } = await runCheck(targets, options);
+  // 戻り値は「exit code を 1 にすべきか」。severity 導入前は findings が
+  // 1 件でもあれば true だったが、既存ルールはすべて error なので既存プロジェクト
+  // での挙動は変わらない。beta 中の移行 warning で CI や stop-hook を止めない。
+  // en: Returns "should this fail?" — unchanged for existing projects since all
+  // pre-existing rules are errors; beta migration warnings never block.
+  return blocked;
 }
 
 export {
   BUILTIN_RULES as RULES,
+  blockingFindings,
+  coerceSeverity,
   collectFindings,
+  countBySeverity,
   createCheckReport,
+  hasBlockingIssues,
   BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
 };

package/lib/load-plugins.js

@@ -113,6 +113,12 @@ export async function loadAntiPatternPlugins({ cwd = process.cwd() } = {}) {
       validatePluginShape(candidate, `${packageName} (${entry})`);
       groups.push(...candidate.groups);
       record.groupIds = candidate.groups.map((group) => group.id);
+      // group の**実体**も持たせる。ID だけだと、別プラグインが同じ group ID を
+      // 宣言したときに所有者を復元できない（plugin-api は ID の名前空間が
+      // ビルトインとも他プラグインとも共有されると明記している）。
+      // en: Keep the group objects, not just ids — ids are not unique across
+      // plugins, so ownership can't be reconstructed from them afterwards.
+      record.groups = candidate.groups;
       if (Array.isArray(candidate.manualReviewReminders)) {
         reminders.push(...candidate.manualReviewReminders);
       }

package/lib/path-utils.js

@@ -1,3 +1,4 @@
+import fs from 'fs';
 import path from 'path';
 
 // setup.js 側と共通の「unsafe な shell メタ文字や quote」を弾く pattern。
@@ -64,3 +65,122 @@ export function assertSafeRelativePath(inputPath, label) {
   }
   return normalized;
 }
+
+/**
+ * 相対 target を解決する基準ディレクトリの**候補**を、優先順に列挙する。
+ *
+ * 1. `startDir`（＝通常は cwd）… 従来の挙動。ここで解決できるなら何も変えない
+ * 2. `CLAUDE_PROJECT_DIR` … Claude Code が hook 実行時に渡す絶対 path
+ * 3. `sparkle.config.json` を持つ祖先（近い順）… CLI 自身の設定ファイル
+ * 4. `package.json` を持つ祖先（近い順）… monorepo では workspace → repo root の順
+ *
+ * monorepo で「最も近い package.json」だけを見ると、cwd が `apps/web` のときに
+ * 基準も `apps/web` になり、hook に書かれた `apps/web/app` が二重化するという
+ * issue #85 と同じ壊れ方を再現してしまう。だから 1 つに決め打たず、repo root まで
+ * 含めて候補を並べ、呼び出し側が「target が実在するか」で選べるようにする。
+ *
+ * en: Enumerate candidate base directories in priority order. Picking a single
+ * "project root" is not enough: in a monorepo the nearest package.json is the
+ * workspace package, which reproduces the very bug this is meant to fix.
+ *
+ * @param {string} [startDir]
+ * @param {{ existsSync?: (p: string) => boolean, env?: Record<string, string> }} [deps]
+ * @returns {Array<{ dir: string, source: string }>} 重複を除いた候補（優先順）
+ */
+export function projectRootCandidates(startDir = process.cwd(), deps = {}) {
+  const exists = deps.existsSync ?? fs.existsSync;
+  const env = deps.env ?? process.env;
+  const candidates = [{ dir: path.resolve(startDir), source: 'cwd' }];
+
+  const fromEnv = env.CLAUDE_PROJECT_DIR;
+  if (typeof fromEnv === 'string' && fromEnv.trim() && exists(fromEnv)) {
+    candidates.push({ dir: path.resolve(fromEnv), source: 'CLAUDE_PROJECT_DIR' });
+  }
+
+  for (const marker of PROJECT_ROOT_MARKERS) {
+    for (const dir of ancestorsContaining(path.resolve(startDir), marker, exists)) {
+      candidates.push({ dir, source: marker });
+    }
+  }
+
+  const seen = new Set();
+  return candidates.filter(({ dir }) => {
+    if (seen.has(dir)) return false;
+    seen.add(dir);
+    return true;
+  });
+}
+
+/**
+ * `targets` がすべて実在する最初の候補ディレクトリを選ぶ。
+ *
+ * hook は AI の作業途中に発火するため、実行時の cwd を前提にできない。AI が調査で
+ * `cd apps/web` したまま戻していないと `apps/web/app` が `apps/web/apps/web/app` に
+ * 解決されて落ちる（issue #85）。候補を順に当てて実在するものを採れば、配布済みの
+ * `.claude/settings.json` を書き換えずに直る。
+ *
+ * cwd を最優先に置いているので、**今まで動いていた呼び出しの挙動は一切変わらない**。
+ * どの候補でも解決できないときも cwd を返し、エラーメッセージは呼び出し側
+ * （`check` の "Target path does not exist"）に任せる。
+ *
+ * en: Pick the first candidate base where every target exists. cwd comes first,
+ * so anything that already worked keeps working; the fallback only kicks in for
+ * the broken case this exists to fix.
+ *
+ * @param {string[]} targets 相対 path の配列（空なら cwd を返す）
+ * @param {{ startDir?: string, existsSync?: (p: string) => boolean, env?: Record<string, string> }} [options]
+ * @returns {{ dir: string, source: string, resolved: boolean }}
+ */
+export function resolveTargetBaseDir(targets, options = {}) {
+  const startDir = path.resolve(options.startDir ?? process.cwd());
+  const exists = options.existsSync ?? fs.existsSync;
+  const fallback = { dir: startDir, source: 'cwd', resolved: false };
+
+  if (!Array.isArray(targets) || targets.length === 0) return fallback;
+
+  for (const candidate of projectRootCandidates(startDir, options)) {
+    if (targets.every((target) => exists(path.resolve(candidate.dir, target)))) {
+      return { ...candidate, resolved: true };
+    }
+  }
+
+  return fallback;
+}
+
+const PROJECT_ROOT_MARKERS = ['sparkle.config.json', 'package.json'];
+
+// 探索を止める境界。ここより上は「別のプロジェクト」とみなす。
+//
+// 境界を設けないと、プロジェクトが別の `package.json` を持つディレクトリの下に
+// 置かれている場合（`/workspace/package.json` の下に `/workspace/project/`）、
+// **target 名を打ち間違えたときに外側の同名 path が拾われて、無関係なファイルを
+// 黙って検査する**。「target が無い」と報告されるべき場面で静かに別の場所を見る
+// のは、このルール一式が防ごうとしている silent failure そのもの。
+//
+// git worktree では `.git` がファイル（`gitdir:` を書いた 1 行）になるが、
+// `existsSync` はどちらでも true を返すので同じく境界として機能する。
+// en: Bound the walk at the repository root. Without it, a typo'd target could
+// resolve against an unrelated outer project and be checked silently.
+const REPOSITORY_BOUNDARY = '.git';
+
+/**
+ * `startDir` から root 方向へ辿り、`marker` を含むディレクトリを近い順に返す。
+ * リポジトリ境界（`.git`）を含むディレクトリまで見たら、そこで打ち切る。
+ * en: All ancestors (nearest first) that contain marker, stopping at the repo root.
+ */
+function ancestorsContaining(startDir, marker, exists) {
+  const found = [];
+  let current = startDir;
+  // path.dirname('/') === '/' なので、変化しなくなった時点が終端。
+  // en: dirname stops changing at the filesystem root — that's the loop guard.
+  for (;;) {
+    if (exists(path.join(current, marker))) found.push(current);
+    // 境界ディレクトリ自身は候補に含めてから打ち切る（repo root がまさに
+    // 探している基準であることが多いため）。
+    // en: Include the boundary directory itself, then stop.
+    if (exists(path.join(current, REPOSITORY_BOUNDARY))) return found;
+    const parent = path.dirname(current);
+    if (parent === current) return found;
+    current = parent;
+  }
+}

package/lib/plugin-api.js

@@ -27,13 +27,29 @@
  *     featureSection?: string,            // markdown emitted into the published anti-pattern doc (esa)
  *     jsdocTargets?: JSDocTarget[],       // optional — JSDoc injection targets in the plugin's own source
  *     check?: {
+ *       severity?: 'error' | 'warning' | 'info',
+ *                                         // defaults to 'error'. Only 'error' affects the exit code
+ *                                         // of `check --strict` / the stop hook; 'warning' / 'info'
+ *                                         // are reported but never fail. An unknown value warns and
+ *                                         // falls back to 'error'.
+ *       targets?: Array<'source' | 'css'>,
+ *                                         // which file kinds the rule runs on.
+ *                                         // defaults to ['source'] (.js/.jsx/.ts/.tsx).
+ *                                         // Add 'css' for rules that match CSS variable
+ *                                         // references or @apply utilities. Note: the built-in
+ *                                         // migration rules additionally skip references to
+ *                                         // variables the same file declares (definition side),
+ *                                         // which is how generated stylesheets are excluded —
+ *                                         // by content, not by filename.
  *       description: string,              // shown in `check` findings
  *       recommendation: string,           // shown in `check` findings
  *       pattern?: RegExp,                 // simple regex check. MUST have the global (`g`) flag.
  *                                         // mutually exclusive with `match`.
- *       match?: (content: string, helpers: MatchHelpers) => Array<{ index: number, text: string }>,
+ *       match?: (content: string, helpers: MatchHelpers) => Array<{ index: number, text: string, recommendation?: string }>,
  *                                         // opt-in API for complex matching (2-pass, AST, etc.).
  *                                         // `helpers` (2nd arg) is injected by the CLI — see ## MatchHelpers.
+ *                                         // A per-hit `recommendation` overrides `check.recommendation`,
+ *                                         // for rules whose fix differs per occurrence (e.g. token migration).
  *     },
  *   }
  *