sparkle-design-cli 2.5.0-beta.1 → 2.5.0-beta.3

package/lib/auth.js

@@ -0,0 +1,302 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { URL, URLSearchParams } from 'url';
+
+/**
+ * `sparkle-design-cli auth` — Google Artifact Registry（AR）の npm registry 用に、
+ * 利用者の Google 資格情報からアクセストークンを取り、ユーザー単位の `~/.npmrc` に書く。
+ *
+ * AR のトークンは約 60 分で失効するので、「翌日 `pnpm install` が 401 で落ちる」を
+ * 1 コマンドで復帰できるようにするのが目的（goodpatch/sparkle-design-cli#94 の Phase 1）。
+ *
+ * 失効を弱めないための制約（#94 の追加仕様）:
+ * - 書き込むのはアクセストークン（60 分以内に失効）だけ。refresh token は gcloud / ADC の
+ *   管理下に置いたまま読むだけで、コピー・キャッシュしない
+ * - トークンを標準出力・エラー出力に出さない
+ * en: Writes a short-lived Google access token for an Artifact Registry npm registry into the
+ *     user-level ~/.npmrc. Never persists or prints long-lived credentials or the token itself.
+ */
+
+const SCOPE = '@goodpatch';
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const GOOGLE_TOKENINFO_URL = 'https://oauth2.googleapis.com/tokeninfo';
+/** アクセストークンとして受け付ける文字。改行などで .npmrc に別の行を差し込ませない */
+const TOKEN_PATTERN = /^[A-Za-z0-9._\-~+/=]+$/;
+
+export class AuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+/**
+ * registry URL を検証して、末尾スラッシュ付きの正規形にする。
+ *
+ * トークンは `cloud-platform` スコープの利用者アクセストークンで、60 分間は GCP 全体を
+ * その人として操作できる。AR 以外のホストに渡すと資格情報の漏えいになるので、
+ * https かつ AR の npm ホスト（`<location>-npm.pkg.dev`）に限る。
+ * en: Only https Artifact Registry npm hosts are accepted, to avoid leaking a broad Google token.
+ */
+export function normalizeRegistry(raw) {
+  let url;
+  try {
+    url = new URL(String(raw).trim());
+  } catch {
+    throw new AuthError(`registry の URL として解釈できません: ${raw}`);
+  }
+  if (url.protocol !== 'https:') {
+    throw new AuthError(`registry は https である必要があります: ${url.href}`);
+  }
+  if (!/^[a-z0-9-]+-npm\.pkg\.dev$/.test(url.hostname)) {
+    throw new AuthError(
+      `Artifact Registry の npm registry（<location>-npm.pkg.dev）ではありません: ${url.host}\n` +
+        '   このコマンドは Google のアクセストークンを書き込むため、Artifact Registry 以外には使えません。'
+    );
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new AuthError(`registry の URL に余分な要素が含まれています: ${raw}`);
+  }
+  const pathname = url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`;
+  return `https://${url.host}${pathname}`;
+}
+
+/** `~/.npmrc` に書くキー（`//host/path/:_authToken`） */
+export function registryAuthKey(registry) {
+  return `${registry.replace(/^https:/, '')}:_authToken`;
+}
+
+/** `.npmrc` のテキストから `@goodpatch:registry=` の値を取り出す。無ければ null */
+export function readScopeRegistry(npmrcText, scope = SCOPE) {
+  for (const rawLine of npmrcText.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith('#') || line.startsWith(';')) continue;
+    const match = /^([^=]+?)\s*=\s*(.+)$/.exec(line);
+    if (match && match[1] === `${scope}:registry`) {
+      return match[2].trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * プロジェクトの `.npmrc` を cwd から親へ辿って探し、`@goodpatch:registry=` を返す。
+ * monorepo でサブディレクトリから実行しても、ルートの `.npmrc` を見つけられるようにする。
+ */
+export function findProjectRegistry(cwd, readFile = (p) => fs.readFileSync(p, 'utf8')) {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    const candidate = path.join(dir, '.npmrc');
+    let text = null;
+    try {
+      text = readFile(candidate);
+    } catch {
+      // 無ければ親へ
+    }
+    if (text !== null) {
+      const registry = readScopeRegistry(text);
+      if (registry) return { registry, source: candidate };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * `.npmrc` のテキスト中の、同じ registry のトークン行を置き換える（無ければ末尾に足す）。
+ * `google-artifactregistry-auth` は追記するだけで、実行のたびに行が積み上がるため。
+ * 末尾スラッシュの有無が違う同じ registry の行もまとめて取り除く。
+ */
+export function upsertAuthToken(npmrcText, registry, token) {
+  const key = registryAuthKey(registry);
+  const variants = new Set([key, key.replace(/\/:_authToken$/, ':_authToken')]);
+  const lines = npmrcText === '' ? [] : npmrcText.split(/\r?\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  const kept = lines.filter((line) => {
+    const match = /^\s*([^=\s]+)\s*=/.exec(line);
+    return !(match && variants.has(match[1]));
+  });
+  kept.push(`${key}=${token}`);
+  return `${kept.join('\n')}\n`;
+}
+
+/** npm が読むユーザー単位の設定ファイル */
+export function resolveUserConfigPath(env = process.env, homedir = os.homedir()) {
+  return env.NPM_CONFIG_USERCONFIG || env.npm_config_userconfig || path.join(homedir, '.npmrc');
+}
+
+/** ADC ファイルの場所（gcloud と同じ探し方） */
+export function resolveAdcPath(env = process.env, homedir = os.homedir()) {
+  if (env.GOOGLE_APPLICATION_CREDENTIALS) return env.GOOGLE_APPLICATION_CREDENTIALS;
+  const configDir =
+    env.CLOUDSDK_CONFIG ||
+    (process.platform === 'win32' && env.APPDATA
+      ? path.join(env.APPDATA, 'gcloud')
+      : path.join(homedir, '.config', 'gcloud'));
+  return path.join(configDir, 'application_default_credentials.json');
+}
+
+/** 失効時刻の表示（例: 15:52（あと 59 分）） */
+export function formatExpiry(expiresInSeconds, now = new Date()) {
+  const expiresAt = new Date(now.getTime() + expiresInSeconds * 1000);
+  const hh = String(expiresAt.getHours()).padStart(2, '0');
+  const mm = String(expiresAt.getMinutes()).padStart(2, '0');
+  return `${hh}:${mm}（あと ${Math.floor(expiresInSeconds / 60)} 分）`;
+}
+
+// ---- トークンの取得（テストでは差し替える） ----
+
+/**
+ * ADC（`gcloud auth application-default login` で作られる authorized_user）の
+ * refresh token でアクセストークンを取り直す。refresh token は読むだけで保存しない。
+ * 使えなければ null（呼び出し側で gcloud にフォールバックする）。
+ */
+async function tokenFromAdc({ env, homedir, fetchImpl }) {
+  let adc;
+  try {
+    adc = JSON.parse(fs.readFileSync(resolveAdcPath(env, homedir), 'utf8'));
+  } catch {
+    return null;
+  }
+  // サービスアカウントキー等は対象外（組織ポリシーでキー発行自体が禁止されている）
+  if (adc?.type !== 'authorized_user' || !adc.refresh_token || !adc.client_id) {
+    return null;
+  }
+  try {
+    const res = await fetchImpl(GOOGLE_TOKEN_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: adc.refresh_token,
+        client_id: adc.client_id,
+        client_secret: adc.client_secret ?? '',
+      }).toString(),
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    if (typeof json.access_token !== 'string') return null;
+    return { token: json.access_token, expiresIn: Number(json.expires_in) || null, via: 'ADC' };
+  } catch {
+    return null;
+  }
+}
+
+/** `gcloud auth print-access-token`。未導入・未ログインなら null */
+function tokenFromGcloud({ spawn }) {
+  const result = spawn('gcloud', ['auth', 'print-access-token'], {
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error || result.status !== 0) return null;
+  const token = String(result.stdout ?? '').trim();
+  return token ? { token, expiresIn: null, via: 'gcloud' } : null;
+}
+
+/** 失効までの秒数を tokeninfo で調べる（取れなくても認証自体は成功扱い） */
+async function lookupExpiresIn(token, fetchImpl) {
+  try {
+    const res = await fetchImpl(GOOGLE_TOKENINFO_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ access_token: token }).toString(),
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return Number(json.expires_in) || null;
+  } catch {
+    return null;
+  }
+}
+
+export const defaultDeps = {
+  env: process.env,
+  homedir: os.homedir(),
+  cwd: () => process.cwd(),
+  fetchImpl: (...args) => globalThis.fetch(...args),
+  spawn: spawnSync,
+  now: () => new Date(),
+  log: (...args) => console.log(...args),
+};
+
+/**
+ * `auth` 本体。成功したら書き込み先と失効時刻を返す。
+ * 失敗は AuthError（メッセージにトークンは含めない）。
+ */
+export async function runAuth(options = {}, deps = {}) {
+  const d = { ...defaultDeps, ...deps };
+
+  let registrySource;
+  let rawRegistry;
+  if (options.registry) {
+    rawRegistry = options.registry;
+    registrySource = '--registry';
+  } else {
+    const found = findProjectRegistry(d.cwd());
+    if (!found) {
+      throw new AuthError(
+        `対象の registry が決められません。次のどちらかを行ってください:\n` +
+          `   - プロジェクトの .npmrc に ${SCOPE}:registry=https://<location>-npm.pkg.dev/<project>/<repository>/ を書く\n` +
+          `   - --registry <url> を指定する`
+      );
+    }
+    rawRegistry = found.registry;
+    registrySource = found.source;
+  }
+  const registry = normalizeRegistry(rawRegistry);
+
+  const acquired = (await tokenFromAdc(d)) ?? tokenFromGcloud(d);
+  if (!acquired) {
+    throw new AuthError(
+      'Google の認証情報が見つからないか、期限切れです。次を実行してから、もう一度 auth を実行してください:\n' +
+        '   gcloud auth login\n' +
+        '   （ADC を使う場合は gcloud auth application-default login）'
+    );
+  }
+  if (!TOKEN_PATTERN.test(acquired.token)) {
+    throw new AuthError(
+      '取得したアクセストークンの形式が想定と異なるため、書き込みを中止しました。'
+    );
+  }
+  const expiresIn = acquired.expiresIn ?? (await lookupExpiresIn(acquired.token, d.fetchImpl));
+
+  const userConfigPath = resolveUserConfigPath(d.env, d.homedir);
+  let current = '';
+  let exists = false;
+  try {
+    current = fs.readFileSync(userConfigPath, 'utf8');
+    exists = true;
+  } catch {
+    // 無ければ新規作成
+  }
+  const next = upsertAuthToken(current, registry, acquired.token);
+  // 本人だけが読めるようにする。既存の ~/.npmrc は既定の 0644（他ユーザーも読める）のことが
+  // 多く、そのまま書くと共有マシンで他のアカウントにトークンを読まれうるので、
+  // 書き込む前に 0600 へ絞る（Windows は POSIX の権限が無いので対象外）
+  let tightened = false;
+  if (exists && process.platform !== 'win32') {
+    const mode = fs.statSync(userConfigPath).mode & 0o777;
+    if (mode !== 0o600) {
+      fs.chmodSync(userConfigPath, 0o600);
+      tightened = true;
+    }
+  }
+  fs.writeFileSync(userConfigPath, next, exists ? undefined : { mode: 0o600 });
+
+  d.log(`✅ Artifact Registry の認証情報を書き込みました（${acquired.via} の資格情報を使用）`);
+  d.log(`   registry: ${registry}（${registrySource}）`);
+  d.log(
+    `   書き込み先: ${userConfigPath}${tightened ? '（他ユーザーから読めない権限 0600 に変更しました）' : ''}`
+  );
+  d.log(
+    expiresIn
+      ? `   有効期限: ${formatExpiry(expiresIn, d.now())}。切れたらもう一度 auth を実行してください`
+      : '   有効期限: 約 60 分。切れたらもう一度 auth を実行してください'
+  );
+
+  return { registry, userConfigPath, expiresIn, via: acquired.via };
+}

package/lib/check.js

@@ -16,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']);
 
@@ -101,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);
@@ -394,7 +415,7 @@ 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, ...cssFiles]

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/rules-report.js

@@ -27,6 +27,9 @@ import {
 } from './anti-pattern-rules.js';
 import { loadAntiPatternPlugins } from './load-plugins.js';
 
+/** 利用者の手元に `docs/` は無いので、案内は解決できる場所を指す。 */
+const DOCS_URL = 'https://github.com/goodpatch/sparkle-design-cli/blob/main/docs';
+
 /** 表示順。`check` のレポートと同じ「重いものが先」に揃える。 */
 const SEVERITY_ORDER = [SEVERITY.ERROR, SEVERITY.WARNING, SEVERITY.INFO];
 
@@ -74,7 +77,24 @@ export async function collectActiveRules(options = {}) {
     ...getCheckRules(pluginGroups).map(shape('plugin')),
   ];
 
-  return { rules, plugins: discovered };
+  // 各プラグインが実際に出した rule は、**そのプラグインの group から直接**求める。
+  // 「全 rule の中に同じ id があるか」で絞ると、`check` を持たない group の id が
+  // 組み込みや別プラグインの rule id と衝突したときに、そのプラグインが所有して
+  // いない ID を並べてしまう（`check` は plugin-api で optional なので実際に起きる）。
+  // en: Derive each plugin's rule ids from its own groups. Matching against the
+  // merged list would attribute a built-in (or another plugin's) rule to a plugin
+  // whose `check`-less group merely reuses that id.
+  // 所有関係はローダーが持つ `record.groups`（group の実体）から取る。
+  // ID で引き直すと、別プラグインが同じ group ID を宣言したときに互いの分まで
+  // 拾ってしまう（実測で両方が 2 件ずつ持つ状態になった）。
+  // en: Ownership comes from the loader's group objects. Re-deriving it from ids
+  // credits each plugin with the other's rules when two declare the same id.
+  const plugins = discovered.map((record) => ({
+    ...record,
+    ruleIds: getCheckRules(record.groups ?? []).map((rule) => rule.id),
+  }));
+
+  return { rules, plugins };
 }
 
 function severityRank(severity) {
@@ -116,7 +136,11 @@ export function renderRulesJson({ rules, plugins }) {
         packageName: record.packageName,
         status: record.status,
         error: record.error ?? null,
-        ruleIds: record.groupIds ?? [],
+        // `ruleIds` は collectActiveRules がプラグインごとに算出したもの
+        // （`check` を持つ group だけ）。`groupIds` は宣言した group 全部。
+        // en: `ruleIds` counts only groups that actually define a check.
+        ruleIds: record.ruleIds ?? [],
+        groupIds: record.groupIds ?? [],
       })),
     },
     null,
@@ -151,11 +175,17 @@ export function renderRulesText({ rules, plugins }) {
     ),
   ];
   if (clashes.length > 0) {
+    // 衝突は「組み込み × プラグイン」だけでなく「プラグイン同士」でも起きる
+    // （plugin-api が名前空間を共有すると明記している）。source を見ずに
+    // 「組み込みと同じ」と決め打つと、後者で嘘の案内になる。
+    // en: Clashes also happen plugin-vs-plugin; don't assume a built-in is involved.
     lines.push('');
-    lines.push(`⚠️  組み込みと同じ ID を名乗るプラグインルールがあります: ${clashes.join(', ')}`);
-    lines.push(
-      '    どちらも実行されます。指摘の出所が分からなくなるので、プラグイン側の ID を変えてください。'
-    );
+    for (const id of clashes) {
+      const sources = rules.filter((rule) => rule.id === id).map((rule) => rule.source);
+      const kind = sources.includes('builtin') ? '組み込みと同じ ID' : 'プラグイン同士で同じ ID';
+      lines.push(`⚠️  ${kind}のルールがあります: ${id}（${sources.join(' + ')}）`);
+    }
+    lines.push('    どちらも実行されます。指摘の出所が分からなくなるので ID を変えてください。');
   }
 
   lines.push('');
@@ -169,7 +199,12 @@ export function renderRulesText({ rules, plugins }) {
     }
   }
   lines.push('');
-  lines.push('個別ルールの背景と対処は docs/anti-patterns.md を参照してください。');
+  // 利用者の cwd に `docs/` は無い。npm 同梱の実体か GitHub を指す。
+  // en: `docs/` doesn't exist in the consumer's cwd — point at the real locations.
+  lines.push(
+    `個別ルールの背景と対処: ${DOCS_URL}/anti-patterns.md` +
+      '（npm 経由なら node_modules/sparkle-design-cli/docs/anti-patterns.md）'
+  );
   lines.push('抑制するには `sparkle-disable-next-line <rule-id>` を使います。');
 
   return lines.join('\n');