sparkle-design-cli 2.5.0-beta.4 → 2.5.0-beta.5

package/lib/check-config.js

@@ -0,0 +1,358 @@
+import fs from 'fs';
+import path from 'path';
+
+import { FILE_NAMES } from './constants.js';
+import { globToRegExp } from './path-utils.js';
+
+/**
+ * `check` のパス単位の除外設定（goodpatch/sparkle-design-cli#102）。
+ *
+ * `sparkle.config.json` の `check.ignore` に、除外したいパスの glob と
+ * （任意で）ルール ID を書く。行単位のコメント（`sparkle-disable-line` /
+ * `sparkle-disable-next-line`）だけだと、サイト独自のページのように
+ * 意図的な箇所がまとまっているときにコメントだらけになるため。
+ *
+ * ```json
+ * {
+ *   "check": {
+ *     "ignore": [
+ *       { "files": ["src/app/(marketing)/**"], "rules": ["tailwind-typography"] },
+ *       { "files": ["**\/*.stories.tsx"] }
+ *     ],
+ *     "allowTokens": ["text-muted-foreground"]
+ *   }
+ * }
+ * ```
+ *
+ * - glob は **cwd（`check` を実行したディレクトリ）**からの相対パスで照合する。`check` の
+ *   出力に出るパスと同じ基準で、`-c` で別の場所の設定ファイルを指定しても基準は cwd のまま。
+ *   cwd の外のファイル（出力が `../` や絶対パスになるもの）には効かない
+ * - glob 記号を含まないパスはディレクトリ指定とみなし、その配下も対象にする
+ *   （`src/app/blog` と `src/app/blog/**` は同じ意味）
+ * - `rules` を省略すると、そのパスの全ルールを除外する
+ * - `allowTokens`（#104）は、プロジェクトが自前の CSS で定義して意図して使う shadcn/ui の
+ *   トークンを宣言する。`shadcn-token` の指摘のうち、クラスが宣言と完全一致するものを出さない。
+ *   `{ "tokens": [...], "files": [glob] }` の形でパスを絞れる。宣言したものだけを許可するので、
+ *   意図しない持ち込みは引き続き検出される
+ *
+ * 設定の形が不正なときは `CheckConfigError`（code: `E_CHECK_CONFIG`）を throw する。除外設定の typo を黙って無視すると
+ * 「除外したつもりが効いていない」か、その逆に気付けないため。
+ *
+ * en: Path-level ignore entries read from `sparkle.config.json` → `check.ignore`.
+ * Globs are cwd-relative (same as report paths). A glob-free path is treated as
+ * a directory and covers everything under it. Omitting `rules` ignores all rules.
+ * `allowTokens` (#104) declares shadcn/ui classes the project defines and uses on
+ * purpose; it only hides `shadcn-token` findings that match a declared class.
+ * Malformed config throws rather than being silently skipped.
+ */
+
+const GLOB_CHARS = /[*?{]/;
+const CHECK_KEYS = new Set(['ignore', 'allowTokens']);
+const ENTRY_KEYS = new Set(['files', 'rules']);
+
+/**
+ * 除外設定の誤り。stop-hook はこれを見て「設定を直して」とブロックする
+ * （exit 1 は Claude Code では非ブロッキング扱いで、検査が黙って止まるため）。
+ * en: Tagged so stop-hook can block with a fix-the-config message instead of
+ * exiting 1, which Claude Code treats as a non-blocking hook error.
+ */
+export class CheckConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CheckConfigError';
+    this.code = 'E_CHECK_CONFIG';
+  }
+}
+
+/**
+ * cwd の外を指すレポートパスか。`../` 始まりと絶対パス（Windows のドライブ指定含む）。
+ * en: Report paths outside cwd — `../…` or absolute (including drive letters).
+ */
+function isOutsideCwd(relativePath) {
+  return (
+    relativePath === '..' ||
+    relativePath.startsWith('../') ||
+    relativePath.startsWith('/') ||
+    /^[A-Za-z]:/.test(relativePath)
+  );
+}
+
+function describeEntry(index) {
+  return `check.ignore[${index}]`;
+}
+
+function assertStringArray(value, label) {
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.some((item) => typeof item !== 'string' || !item.trim())
+  ) {
+    throw new CheckConfigError(
+      `${label} は空でない文字列の配列で指定してください: ${JSON.stringify(value)}`
+    );
+  }
+}
+
+/**
+ * glob 1 件を照合用の正規表現（複数）にする。glob 記号を含まないパスは
+ * 「そのパス自身」と「その配下」の両方にマッチさせる。
+ * en: A glob-free path matches itself and everything under it.
+ */
+function compileFileGlob(glob, label) {
+  const trimmed = glob.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  if (
+    trimmed === '' ||
+    trimmed === '.' ||
+    path.isAbsolute(trimmed) ||
+    /^[A-Za-z]:/.test(trimmed) ||
+    glob.trim().startsWith('/') ||
+    trimmed.split('/').includes('..') ||
+    // `src/./app` や `src//app` はどのパスにも一致せず、黙って効かない
+    // en: `src/./app` / `src//app` would never match anything — reject loudly.
+    trimmed
+      .replace(/^\.\//, '')
+      .split('/')
+      .some((segment) => segment === '' || segment === '.')
+  ) {
+    throw new CheckConfigError(
+      `${label} には cwd からの相対パスを指定してください（空・絶対パス・..・途中の . や空のセグメントは使えません）: ${glob}`
+    );
+  }
+  try {
+    if (GLOB_CHARS.test(trimmed)) {
+      return [globToRegExp(trimmed, label)];
+    }
+    return [globToRegExp(trimmed, label), globToRegExp(`${trimmed}/**`, label)];
+  } catch (error) {
+    throw new CheckConfigError(error.message);
+  }
+}
+
+/**
+ * `check.ignore` を検証して照合しやすい形にする。
+ *
+ * @param {unknown} checkSection `sparkle.config.json` の `check` の値
+ * @returns {Array<{ files: string[], matchers: RegExp[], rules: string[] | null }>}
+ */
+export function normalizeCheckIgnore(checkSection) {
+  if (checkSection === undefined) return [];
+  if (checkSection === null || typeof checkSection !== 'object' || Array.isArray(checkSection)) {
+    throw new CheckConfigError('sparkle.config.json の check はオブジェクトで指定してください');
+  }
+  const unknownCheckKeys = Object.keys(checkSection).filter((key) => !CHECK_KEYS.has(key));
+  if (unknownCheckKeys.length > 0) {
+    throw new CheckConfigError(
+      `sparkle.config.json の check に未知のキーがあります: ${unknownCheckKeys.join(', ')}（使えるのは ignore / allowTokens）`
+    );
+  }
+  const { ignore } = checkSection;
+  if (ignore === undefined) return [];
+  if (!Array.isArray(ignore)) {
+    throw new CheckConfigError('sparkle.config.json の check.ignore は配列で指定してください');
+  }
+
+  return ignore.map((entry, index) => {
+    const label = describeEntry(index);
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new CheckConfigError(
+        `${label} は { "files": [...], "rules": [...] } の形で指定してください`
+      );
+    }
+    const unknownKeys = Object.keys(entry).filter((key) => !ENTRY_KEYS.has(key));
+    if (unknownKeys.length > 0) {
+      throw new CheckConfigError(
+        `${label} に未知のキーがあります: ${unknownKeys.join(', ')}（使えるのは files / rules）`
+      );
+    }
+    assertStringArray(entry.files, `${label}.files`);
+    if (entry.rules !== undefined) {
+      assertStringArray(entry.rules, `${label}.rules`);
+    }
+    return {
+      files: entry.files.map((glob) => glob.trim()),
+      matchers: entry.files.flatMap((glob) => compileFileGlob(glob, `${label}.files`)),
+      rules: entry.rules ? entry.rules.map((id) => id.trim()) : null,
+    };
+  });
+}
+
+/**
+ * `check.allowTokens` が効くルール。shadcn/ui のトークンを自前の CSS で定義して使う
+ * プロジェクトのための宣言（#104）なので、`shadcn-token` の指摘にだけ効かせる。
+ * 他ルールまで黙らせる汎用の抜け道にしない（範囲を絞った除外は `check.ignore` で行う）。
+ * en: allowTokens only applies to `shadcn-token` findings — it declares intentional
+ * shadcn/ui tokens, and must not become a generic escape hatch for other rules.
+ */
+export const ALLOW_TOKENS_RULE_ID = 'shadcn-token';
+const ALLOW_ENTRY_KEYS = new Set(['tokens', 'files']);
+
+function assertClassNames(tokens, label) {
+  const invalid = tokens.filter((token) => /\s/.test(token.trim()));
+  if (invalid.length > 0) {
+    throw new CheckConfigError(
+      `${label} にはクラス名を 1 つずつ別の要素で書いてください: ${JSON.stringify(invalid)}`
+    );
+  }
+}
+
+/**
+ * `check.allowTokens` を検証して照合しやすい形にする。要素はクラス名の文字列
+ * （全体で許可）か、`{ "tokens": [...], "files": [glob] }`（そのパスでだけ許可）。
+ * 空配列は「宣言なし」として受け付ける。
+ * en: Entries are class-name strings (allowed everywhere) or
+ * `{ tokens, files }` (allowed only under those paths). `[]` means none.
+ *
+ * @param {unknown} checkSection
+ * @returns {Array<{ tokens: string[], matchers: RegExp[] | null }>}
+ */
+export function normalizeAllowTokens(checkSection) {
+  const allowTokens = checkSection?.allowTokens;
+  if (allowTokens === undefined) return [];
+  if (!Array.isArray(allowTokens)) {
+    throw new CheckConfigError(
+      'check.allowTokens はクラス名か { "tokens": [...], "files": [...] } の配列で指定してください'
+    );
+  }
+  const globalTokens = [];
+  const scoped = [];
+  allowTokens.forEach((entry, index) => {
+    const label = `check.allowTokens[${index}]`;
+    if (typeof entry === 'string') {
+      if (!entry.trim()) {
+        throw new CheckConfigError(`${label} が空文字です`);
+      }
+      assertClassNames([entry], label);
+      globalTokens.push(entry.trim());
+      return;
+    }
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new CheckConfigError(
+        `${label} はクラス名か { "tokens": [...], "files": [...] } で指定してください`
+      );
+    }
+    const unknownKeys = Object.keys(entry).filter((key) => !ALLOW_ENTRY_KEYS.has(key));
+    if (unknownKeys.length > 0) {
+      throw new CheckConfigError(
+        `${label} に未知のキーがあります: ${unknownKeys.join(', ')}（使えるのは tokens / files）`
+      );
+    }
+    assertStringArray(entry.tokens, `${label}.tokens`);
+    assertClassNames(entry.tokens, `${label}.tokens`);
+    assertStringArray(entry.files, `${label}.files`);
+    scoped.push({
+      tokens: entry.tokens.map((token) => token.trim()),
+      matchers: entry.files.flatMap((glob) => compileFileGlob(glob, `${label}.files`)),
+    });
+  });
+  return [
+    ...(globalTokens.length > 0 ? [{ tokens: [...new Set(globalTokens)], matchers: null }] : []),
+    ...scoped,
+  ];
+}
+
+/**
+ * `shadcn-token` の指摘（`relativePath` のファイルで `token` を検出）が
+ * `check.allowTokens` で許可されているか。`check.ignore` と同じく cwd の外には効かない。
+ * en: Whether a shadcn-token finding is allowed; like check.ignore, never
+ * applies outside cwd.
+ */
+export function isTokenAllowed(entries, relativePath, token) {
+  if (entries.length === 0 || isOutsideCwd(relativePath)) return false;
+  return entries.some(
+    (entry) =>
+      entry.tokens.includes(token) &&
+      (entry.matchers === null || entry.matchers.some((matcher) => matcher.test(relativePath)))
+  );
+}
+
+/**
+ * `sparkle.config.json` を読み、`check` セクションの生の値を返す。
+ *
+ * - `configPath` 未指定で既定の `./sparkle.config.json` が無ければ `undefined`（`check` は
+ *   設定ファイルが無いプロジェクトでも動く）
+ * - `configPath` を明示したのに無い、または JSON が壊れているときは throw
+ * en: Read the raw `check` section; missing default file means no config.
+ */
+function readCheckSection(configPath, cwd) {
+  const resolved = path.resolve(cwd, configPath ?? FILE_NAMES.CONFIG);
+  let raw;
+  try {
+    raw = fs.readFileSync(resolved, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT' && !configPath) return undefined;
+    throw new CheckConfigError(
+      `設定ファイルを読み込めませんでした: ${resolved} (${error.code ?? error.message})`
+    );
+  }
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (error) {
+    throw new CheckConfigError(`設定ファイルの JSON が不正です: ${resolved} (${error.message})`);
+  }
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    throw new CheckConfigError(`設定ファイルの中身はオブジェクトである必要があります: ${resolved}`);
+  }
+  return config.check;
+}
+
+/**
+ * `sparkle.config.json` から `check` の設定（`ignore` と `allowTokens`）を読む。
+ * en: Load both `check.ignore` and `check.allowTokens`.
+ *
+ * @param {string | null} [configPath]
+ * @param {string} [cwd]
+ * @returns {{ ignore: ReturnType<typeof normalizeCheckIgnore>,
+ *   allowTokens: ReturnType<typeof normalizeAllowTokens> }}
+ */
+export function loadCheckConfig(configPath = null, cwd = process.cwd()) {
+  const checkSection = readCheckSection(configPath, cwd);
+  return {
+    ignore: normalizeCheckIgnore(checkSection),
+    allowTokens: normalizeAllowTokens(checkSection),
+  };
+}
+
+/**
+ * `check.ignore` だけを読む。`migrate` 用で、使わない `allowTokens` の形は検証しない
+ * （`allowTokens` の書き間違いで移行まで止めないため）。
+ * en: `check.ignore` only — used by migrate, which must not fail on allowTokens.
+ */
+export function loadCheckIgnore(configPath = null, cwd = process.cwd()) {
+  return normalizeCheckIgnore(readCheckSection(configPath, cwd));
+}
+
+/**
+ * 相対パス × ルール ID が除外設定にかかるか。cwd の外のパスにはかけない
+ * （`**\/*.stories.tsx` のような glob が `../other/…` に一致してしまうのを防ぐ）。
+ * en: Whether a cwd-relative path / rule pair is covered by an ignore entry.
+ * Paths outside cwd are never ignored, so `**` globs cannot reach them.
+ *
+ * @param {ReturnType<typeof normalizeCheckIgnore>} entries
+ * @param {string} relativePath `/` 区切りの cwd 相対パス
+ * @param {string} ruleId
+ */
+export function isPathIgnored(entries, relativePath, ruleId) {
+  if (entries.length === 0 || isOutsideCwd(relativePath)) return false;
+  return entries.some(
+    (entry) =>
+      (entry.rules === null || entry.rules.includes(ruleId)) &&
+      entry.matchers.some((matcher) => matcher.test(relativePath))
+  );
+}
+
+/**
+ * 除外設定に書かれたルール ID のうち、`knownRuleIds` に無いものを返す。
+ * typo やプラグイン未導入で「除外したつもりが何も外していない」状態に気付けるようにする。
+ * en: Rule IDs referenced by ignore entries that no active rule has.
+ */
+export function unknownIgnoreRuleIds(entries, knownRuleIds) {
+  const known = new Set(knownRuleIds);
+  const unknown = new Set();
+  for (const entry of entries) {
+    for (const id of entry.rules ?? []) {
+      if (!known.has(id)) unknown.add(id);
+    }
+  }
+  return [...unknown].sort();
+}