Claude Code にルールを強制させる Stop Hooks とBiome v2による仕組みづくり

#!/usr/bin/env -S bun run --silent
import { parseArgs } from 'node:util';
import { $ } from 'bun';
import { defineHook, runHook } from 'cc-hooks-ts';
import { hasTypeScriptEdits } from './utils';
 
/**
 * コマンド実行結果を表す型
 */
type CommandResult = {
  /** コマンド名 */
  command: string;
  /** プロセス終了コード (0: 成功, その他: エラー) */
  code: number;
  /** 標準出力の内容 */
  stdout: string;
  /** 標準エラー出力の内容 */
  stderr: string;
};
 
/**
 * コマンドライン引数から -c オプションの値を取得する
 */
function getCommandsFromArgs(): string | undefined {
  const { values } = parseArgs({
    args: Bun.argv.slice(2),
    options: {
      c: { type: 'string' },
    },
    strict: true,
    allowPositionals: false,
  });
  return values.c;
}
 
/**
 * カンマ区切りの文字列をコマンド配列に変換する
 */
function parseCommands(commandsStr: string): string[] {
  return commandsStr
    .split(',')
    .map((cmd) => cmd.trim())
    .filter((cmd) => {
      if (cmd.length === 0) return false;
      // 危険な文字を含むコマンドを拒否
      if (/[\s;|&$`<>()]/.test(cmd)) return false;
      return true;
    });
}
 
/**
 * 指定されたコマンドを実行する
 */
async function runCommand(
  command: string,
  cwd: string,
): Promise<CommandResult> {
  const proc = await $`bun run ${command}`.cwd(cwd).nothrow().quiet();
 
  return {
    command,
    code: proc.exitCode,
    stdout: proc.stdout.toString(),
    stderr: proc.stderr.toString(),
  };
}
 
/**
 * コマンド実行結果からエラーメッセージを生成する
 */
function formatErrorMessage(results: CommandResult[]): string | undefined {
  const failures = results.filter((r) => r.code !== 0);
 
  if (failures.length === 0) {
    return undefined;
  }
 
  const errorMessages = failures
    .map((f) => {
      // stdout と stderr の両方を含めて 型チェック で stderr に出力がある場合でも
      // 個別の結果を返却させるようにする
      const outputs = [f.stdout, f.stderr].filter(Boolean);
      const output =
        outputs.length > 0 ? outputs.join('\n') : 'No output captured';
      return `\x1b[31m❌ Command failed: bun run ${f.command}\x1b[0m\n${output}`;
    })
    .join('\n\n');
 
  return `\x1b[31mSome commands failed. Fix the following errors:\x1b[0m\n\n${errorMessages}`;
}
 
/**
 * コマンド実行結果から成功メッセージを生成する
 */
function formatSuccessMessage(results: CommandResult[]): string {
  const commandList = results.map((r) => r.command).join(', ');
  return `All commands passed: ${commandList}`;
}
 
export const multiCommandCheckHook = defineHook({
  trigger: {
    Stop: true,
  },
 
  run: async (c) => {
    // すでにHookで継続中なら実行しない
    if (c.input.stop_hook_active) {
      return c.success();
    }
    // コマンド引数から -c オプションを取得
    const commandsStr = getCommandsFromArgs();
 
    // 設定されていない場合は誤爆防止で success を返す
    if (!commandsStr) {
      return c.success();
    }
 
    const transcriptPath = c.input.transcript_path;
    const cwd = c.input.cwd;
 
    // TypeScript ファイルの編集がなかった場合はスキップ
    const hasEdits = hasTypeScriptEdits(transcriptPath);
 
    if (!hasEdits) {
      return c.success();
    }
 
    // コマンドをパースして実行
    const commands = parseCommands(commandsStr);
 
    if (commands.length === 0) {
      return c.success();
    }
 
    const results: CommandResult[] = [];
 
    // コマンドを順次実行
    for (const command of commands) {
      const result = await runCommand(command, cwd);
      results.push(result);
    }
 
    // エラーがあればブロッキングエラーを返す
    const errorMessage = formatErrorMessage(results);
 
    if (errorMessage) {
      return c.blockingError(errorMessage);
    }
 
    // 全て成功
    return c.success({
      messageForUser: formatSuccessMessage(results),
    });
  },
});
 
if (process.env.NODE_ENV !== 'test') {
  await runHook(multiCommandCheckHook);
}

/**
 * transcriptを確認して最新ユーザーメッセージ以降でTypeScriptファイルの編集があったかチェックする
 */
export function hasTypeScriptEdits(transcriptPath: string): boolean {
  if (!existsSync(transcriptPath)) {
    return false;
  }
 
  try {
    const content = readFileSync(transcriptPath, 'utf-8');
    const lines = content
      .split('\n')
      .filter((line) => line.trim())
      .reverse();
 
    // 最新のユーザーメッセージのタイムスタンプを見つける
    const lastUserTimestamp = (() => {
      for (const line of lines) {
        try {
          const msg: TranscriptEntry = JSON.parse(line);
          if (
            msg.type === 'user' &&
            !msg.message.content.startsWith('Stop hook feedback:')
          ) {
            return msg.timestamp;
          }
        } catch {
          // JSONパースエラーを無視
        }
      }
    })();
 
    if (!lastUserTimestamp) {
      return false;
    }
 
    // 最新ユーザーメッセージ以降のassistantメッセージでTypeScript編集をチェック
    for (const line of lines.reverse()) {
      try {
        const msg: TranscriptEntry = JSON.parse(line);
        if (msg.type === 'assistant' && msg.timestamp > lastUserTimestamp) {
          for (const content of msg.message.content) {
            if (
              content.type === 'tool_use' &&
              content.name &&
              isTypeScriptEditTool(content.name)
            ) {
              // file_path または relative_path のいずれかをチェック
              const filePath =
                content.input?.file_path || content.input?.relative_path;
              if (
                filePath &&
                isTypeScriptFile(filePath, TYPE_SCRIPT_EXTENSIONS)
              ) {
                return true;
              }
            }
          }
        }
      } catch {
        // JSONパースエラーを無視
      }
    }
 
    return false;
  } catch {
    return false;
  }
}

import type { ToolSchema } from 'cc-hooks-ts';
 
/**
 * transcript JSONLファイル内の1行（1つのメッセージエントリ）を表す型
 */
export type TranscriptEntry = UserEntry | AssistantEntry | SystemEntry;
 
/**
 * ユーザーメッセージ
 */
type UserEntry = {
  /** メッセージタイプ ('user': ユーザーメッセージ) */
  type: 'user';
  /** ISO8601形式のタイムスタンプ (例: "2025-09-28T01:33:41.977Z") */
  timestamp: string;
  /** ユーザーメッセージの内容 */
  message: {
    /** メッセージの役割 */
    role: 'user';
    /** ユーザーの入力内容（文字列） */
    content: string;
  };
};
 
/**
 * アシスタントメッセージ
 */
type AssistantEntry = {
  /** メッセージタイプ ('assistant': AIメッセージ) */
  type: 'assistant';
  /** ISO8601形式のタイムスタンプ (例: "2025-09-28T01:33:41.977Z") */
  timestamp: string;
  /** アシスタントメッセージの内容 */
  message: {
    /** メッセージ内のコンテンツ要素配列（テキスト、ツール使用など） */
    content: ContentElement[];
  };
};
 
/**
 * システムメッセージ
 */
type SystemEntry = {
  /** メッセージタイプ ('system') */
  type: 'system';
  /** ISO8601形式のタイムスタンプ (例: "2025-09-28T01:33:41.977Z") */
  timestamp: string;
  /** システムメッセージの内容 */
  message?: {
    /** システムメッセージのコンテンツ */
    content?: ContentElement[] | string;
  };
};
 
/**
 * メッセージ内の個別コンテンツ要素（テキストやツール使用）を表す型
 */
type ContentElement = {
  /** コンテンツタイプ ('tool_use': ツール使用, 'text': テキスト, その他) */
  type?: 'tool_use' | 'text' | string;
  /** ツール名 ('Edit': ファイル編集, 'MultiEdit': 複数ファイル編集, その他) */
  name?: keyof ToolSchema;
  /** テキストコンテンツ ('text'タイプの場合) */
  text?: string;
  /** ツール実行時の入力パラメータ */
  input?: {
    /** 編集対象ファイルの絶対パス (例: "/path/to/file.ts") */
    file_path?: string;
    /** 編集対象ファイルの相対パス (Serena MCPツール用) */
    relative_path?: string;
  };
};

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun run --silent -i ~/.claude/scripts/typescript/multi-command-check.ts -c format,lint:ai,type-check:ai"
          }
        ]
      }
    ]
  }
}

{
  "scripts": {
    "lint:ai": "set -o pipefail && biome lint . --reporter=github 2>&1 | { grep '^::' || true; }",
    "format": "biome format --write .",
    "type-check:ai": "tsc --noEmit --pretty false",
  },
}