apidiff-action/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a GitHub Action written in Node.js that detects breaking API changes in Go code using the official golang.org/x/exp/cmd/apidiff tool. It analyzes Go API compatibility between commits and can comment on pull requests with detailed change reports.

Common Commands

Development

Important: Use Node.js v20 to match GitHub Actions runtime.

# Install dependencies
npm ci

# Run tests
npm test

# Run linting
npm run lint

# Run formatter
npm run format

# Build the action (compiles to dist/)
npm run build

# Run pre-commit hooks manually
pre-commit run --all-files

Testing the Action Locally

The action supports testing with environment variables:

# Test with directories
INPUT_OLD=testdata/break/old INPUT_NEW=testdata/break/new node index.js

# Test with git refs
INPUT_OLD=HEAD~1 INPUT_NEW=HEAD node index.js

Architecture

Core Components

1. index.js - Main entry point that:

   • Reads GitHub Action inputs
   • Determines which commits/directories to compare
   • Orchestrates the apidiff run, parsing, and PR commenting
   • Sets action outputs

2. lib/apidiff.js - Handles running the official apidiff tool:

   • Installs golang.org/x/exp/cmd/apidiff if not present
   • Supports both git refs and directory comparisons
   • For directories: creates export files first, then compares them
   • For git refs: runs apidiff directly on the commits

3. lib/parser.js - Parses apidiff text output:

   • Extracts breaking and compatible changes by package
   • Converts to structured format
   • Generates markdown reports for PR comments

4. lib/commenter.js - Manages PR comments:

   • Creates or updates existing comments (identified by hidden tag)
   • Requires pull-requests: write permission
   • Uses GitHub Actions toolkit for API access

Testing Structure

The testdata/ directory contains test cases:

• clean/ - No API changes
• safe/ - Only compatible changes (additions)
• break/ - Contains breaking changes

Each test case has old/ and new/ subdirectories with Go code.

Build Process

The action uses @vercel/ncc to compile all dependencies into a single dist/index.js file. This is required for GitHub Actions and must be committed to the repository. The dist/ folder is intentionally NOT in .gitignore.

Important: The dist must be built with Node.js v20 to match GitHub Actions runtime.

There are two ways to update dist/:

1. Automatic (recommended): Push changes to main branch and the build-dist workflow will automatically rebuild with Node 20
2. Manual: If you have Node 20 installed locally:

   node --version  # Must show v20.x.x
   npm run build
   git add dist/index.js
   

Pre-commit Hooks

Configured with husky to run:

• ESLint and Prettier on JS files
• Pretty-format-json on JSON files (excluding package-lock.json)
• Builds dist/ and verifies it's up to date

Key Design Decisions

1. Node.js wrapper around Go tool: Rather than reimplementing apidiff, this action wraps the official tool
2. Support for both directories and git refs: Allows testing without git commits
3. Structured parsing: Converts free-text apidiff output into structured data for better formatting
4. Comment management: Updates existing comments rather than creating duplicates

Workflow Guidance

• When you open a PR, enable auto-merge, and watch CI checks until they complete and the PR merges. If CI fails, use the gh CLI to diagnose the error