feat: add AI-optimized lint scripts for better developer experience

[dguido]

Summary

This PR adds intelligent linting scripts specifically optimized for AI coding assistants like Claude Code, Cursor, and GitHub Copilot. These scripts provide structured, deterministic output that AI tools can reliably parse and act upon.

Problem Being Solved

AI coding assistants struggle with traditional linting tools because:

• Output is often interleaved from parallel processes
• Human-readable output is hard to parse programmatically
• Interactive prompts block automation
• Non-deterministic behavior makes automation unreliable

Solution

Created a linting orchestrator that:

• ✅ Provides JSON output format for structured data
• ✅ Runs sequentially for predictable output
• ✅ Automatically discovers components
• ✅ Routes files to correct component linters
• ✅ Never prompts for input
• ✅ Returns clear success/failure signals

Features Added

1. Smart Linting Script (scripts/lint-changed-files.sh)

• Dynamic component discovery: Finds all components with pyproject.toml
• Intelligent file routing: Maps each file to its component
• Multiple output formats:
  • Human-readable colored text (default)
  • Plain text (--plain)
  • Machine-parseable JSON (--format=json)
• Dependency caching: Only runs uv sync when needed
• Comprehensive error handling: Never silently fails

2. Documentation (scripts/README.md)

• Explains why AI tools need special handling
• Documents JSON output structure
• Provides integration examples
• Lists all available options

3. Test Suite (scripts/test-lint-script.sh)

• 10 comprehensive tests
• Validates both text and JSON output
• Tests error conditions
• Ensures reliability for automation

Usage Examples

For Humans

# Check files
scripts/lint-changed-files.sh check src/file.py

# Fix issues
scripts/lint-changed-files.sh fix src/file.py

For AI Tools

# Get structured output
scripts/lint-changed-files.sh --format=json fix src/file.py

# Response:
{
  "status": "success",
  "mode": "fix",
  "total_files": 1,
  "files_processed": 1,
  "files_skipped": 0,
  "components_checked": 1,
  "errors": []
}

Why This Matters

This enables AI coding assistants to:

• Automatically fix linting issues without human intervention
• Understand exactly what happened during linting
• Make intelligent decisions based on results
• Provide better feedback to users

Testing

• ✅ All 10 tests pass
• ✅ Tested with real files from the codebase
• ✅ JSON output validates correctly
• ✅ Works on macOS and Linux

Impact

This significantly improves the developer experience when using AI tools with Buttercup, reducing friction and accelerating development.

Part of the effort to break down #295 into focused, reviewable pieces.

🤖 Generated with Claude Code