From a2befb7c37babee373fe97af483797795c4b1e37 Mon Sep 17 00:00:00 2001 From: SmetDenis Date: Sun, 28 Sep 2025 20:34:08 +0400 Subject: [PATCH] docs: Enhance project documentation and add Claude guide - Introduce CLAUDE.md to provide detailed context and instructions for AI assistants like Claude Code. - Revamp README.md for better clarity and comprehensiveness. - Add new sections to README.md, including Features, Advanced Usage, Requirements, Architecture, and Development. - Improve existing sections like Installation and Basic Usage. - Update .gitignore to exclude .claude files. --- .gitignore | 1 + CLAUDE.md | 144 ++++++++++++++++++++++++++++++++++++++++ README.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 321 insertions(+), 16 deletions(-) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index bb6b860..e7bf90c 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ build vendor phpunit.xml *.cache +.claude diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a626a92 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,144 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +JBZoo Composer-Diff is a PHP CLI tool that compares two versions of composer.lock files and shows what packages have changed. It's particularly useful for visualizing dependency changes after running `composer update`, providing detailed output in console, markdown, or JSON formats with links to compare views on package repositories. + +## Core Architecture + +### Command-Line Interface +- Built on **Symfony Console** and **JBZoo CLI** framework +- Single command application with `DiffAction` as the main command (`src/Commands/DiffAction.php`) +- Executable binary: `composer-diff` (defined in composer.json bin section) +- Entry point through the binary file `/composer-diff` + +### Core Classes +- **`Diff`** (`src/Diff.php`) - Main comparison logic with version change detection (New, Removed, Changed, Upgraded, Downgraded) +- **`Comparator`** (`src/Comparator.php`) - Orchestrates the comparison process between composer.lock files +- **`ComposerLock`** (`src/ComposerLock.php`) - Parses and extracts package data from composer.lock files +- **`Package`** (`src/Package.php`) - Represents individual package with version and URL information +- **`Url`** (`src/Url.php`) - Generates comparison URLs for different Git hosting platforms + +### Output Renderers (`src/Renders/`) +- **`Console`** - Default colored table output for terminal +- **`Markdown`** - Generates markdown tables for PRs/documentation +- **`JsonOutput`** - Machine-readable JSON format +- **`AbstractRender`** - Base class for all output formats + +## Common Commands + +### Development Setup +```bash +make build # Install dependencies and build phar +make update # Install/update dependencies and build phar +``` + +### Testing +```bash +make test # Run PHPUnit tests +make test-all # Run all tests and code quality checks +make test-drupal # Test with real Drupal upgrade scenario +make test-manual # Run manual test examples with sample data +``` + +### Code Quality (via JBZoo Toolbox) +```bash +make codestyle # Run all linters and code style checks +``` + +### Build Process +```bash +make build-phar # Build composer-diff.phar executable +make create-symlink # Create symlink vendor/bin/composer-diff → build/composer-diff.phar +``` + +### Usage Examples +```bash +# Basic usage (compares HEAD:composer.lock with ./composer.lock) +php ./vendor/bin/composer-diff + +# Compare specific files +php ./composer-diff --source="old/composer.lock" --target="new/composer.lock" + +# Different output formats +php ./composer-diff --output=markdown +php ./composer-diff --output=json + +# Filter environments +php ./composer-diff --env=require # Production dependencies only +php ./composer-diff --env=require-dev # Development dependencies only +``` + +## Package Detection Logic + +The tool identifies changes by: +1. **Version Comparison**: Uses Composer's semantic versioning via `composer/semver` +2. **Hash Detection**: Recognizes dev packages with commit hashes (40-character strings without dots) +3. **URL Generation**: Creates compare links for GitHub, GitLab, and Bitbucket repositories +4. **Change Classification**: Categorizes as New, Removed, Upgraded, Downgraded, Changed, or Same + +## Testing Strategy + +### Test Structure +- **Unit Tests**: `tests/` directory with comprehensive coverage of all classes +- **Fixture Data**: `tests/fixtures/` contains realistic composer.lock samples for various scenarios +- **Integration Tests**: Real-world examples like Drupal version comparisons +- **Manual Testing**: Built-in examples in Makefile for output verification + +### Test Scenarios Covered +- New package installation +- Package removal +- Version upgrades/downgrades +- Dev branch changes (hash-based versions) +- Complex dependency matrices +- Different environment filtering (require vs require-dev) + +## Build System + +### JBZoo Toolbox Integration +Uses JBZoo's standardized development toolchain: +- Inherits comprehensive Makefile targets from `vendor/jbzoo/codestyle/src/init.Makefile` +- Automated code style, static analysis, and testing via `jbzoo/toolbox-dev` +- Consistent development experience across JBZoo ecosystem + +### PHAR Distribution +- Builds standalone `build/composer-diff.phar` executable +- Supports global installation via `composer global require jbzoo/composer-diff` +- GitHub releases provide downloadable phar files + +## Dependencies + +### Production +- `php: ^8.2` with `ext-json` and `ext-filter` +- `jbzoo/cli: ^7.2.4` - Enhanced Symfony Console wrapper +- `jbzoo/data: ^7.2` - Data manipulation utilities +- `jbzoo/markdown: ^7.0.2` - Markdown generation +- `symfony/console: >=6.4`, `symfony/process: >=6.4` +- `composer/semver: >=1.0` - Version comparison logic + +### Development +- `jbzoo/toolbox-dev: ^7.3` - Complete development toolchain +- `composer/composer: >=2.0` - For testing with real composer.lock files + +## File Structure Patterns + +``` +src/ +├── Commands/DiffAction.php # Main CLI command +├── Renders/ # Output format implementations +├── Diff.php # Core comparison logic +├── Comparator.php # Comparison orchestration +├── ComposerLock.php # Lock file parsing +├── Package.php # Package representation +├── Url.php # URL generation +└── Exception.php # Custom exceptions + +tests/ +├── fixtures/ # Test composer.lock files +│ ├── testComparingComplex/ # Complex change scenarios +│ ├── testDrupal/ # Real Drupal upgrade data +│ └── [scenario-name]/ # Various test cases +└── *Test.php # Unit tests for each class +``` \ No newline at end of file diff --git a/README.md b/README.md index 1dd089b..d5317e4 100644 --- a/README.md +++ b/README.md @@ -12,49 +12,87 @@ [![GitHub License](https://img.shields.io/github/license/jbzoo/composer-diff)](https://github.com/JBZoo/Composer-Diff/blob/master/LICENSE) +A powerful CLI tool for visualizing changes in Composer dependencies after running `composer update`. Compare two `composer.lock` files and see exactly what packages were added, removed, upgraded, or downgraded with beautiful output formatting and direct links to changelogs. + +## Table of Contents + - * [Why?](#why) + * [Features](#features) * [Installation](#installation) - * [Usage](#usage) + * [Via Composer (Recommended)](#via-composer-recommended) + * [Standalone PHAR](#standalone-phar) + * [Basic Usage](#basic-usage) * [Help Description](#help-description) * [Output Examples](#output-examples) * [Default view (--output=console)](#default-view---outputconsole) * [Markdown Output (--output=markdown)](#markdown-output---outputmarkdown) * [JSON Output (--output=json)](#json-output---outputjson) + * [Advanced Usage](#advanced-usage) + * [Compare Specific Files](#compare-specific-files) + * [Environment Filtering](#environment-filtering) + * [Output Formatting](#output-formatting) + * [Real-world Examples](#real-world-examples) + * [Requirements](#requirements) + * [Architecture](#architecture) + * [Change Detection Logic](#change-detection-logic) + * [Supported Git Platforms](#supported-git-platforms) + * [Development](#development) + * [Setup](#setup) + * [Testing](#testing) + * [Building PHAR](#building-phar) * [Roadmap](#roadmap) - * [Unit tests and check code style](#unit-tests-and-check-code-style) * [License](#license) * [See Also](#see-also) -## Why? - -See what packages have been changed after you run `composer update` by comparing `composer.lock` to the `git show HEAD:composer.lock`. +## Features +- **Visual Dependency Tracking**: See exactly what changed after `composer update` with color-coded output +- **Multiple Output Formats**: Console tables, Markdown for PRs, or JSON for automation and CI/CD pipelines +- **Smart Version Detection**: Automatically detects upgrades, downgrades, new, removed, and changed packages +- **Direct Links to Changes**: Generates comparison URLs for GitHub, GitLab, and Bitbucket repositories +- **Environment Filtering**: Compare production (`require`) and development (`require-dev`) dependencies separately or together +- **Git Integration**: Compare current lock file with any git reference (HEAD, branches, tags) +- **Dev Package Support**: Handles dev branches with commit hash detection and comparison +- **CI/CD Friendly**: Perfect for automated workflows, deployment pipelines, and Pull Request automation +- **PHAR Distribution**: Standalone executable or Composer installation options ## Installation -```shell -composer require jbzoo/composer-diff # For specific project -composer global require jbzoo/composer-diff # As global tool +### Via Composer (Recommended) + +```bash +# Install for specific project +composer require jbzoo/composer-diff + +# Install globally +composer global require jbzoo/composer-diff +``` + +### Standalone PHAR -# OR use phar file. +```bash +# Download latest release wget https://github.com/JBZoo/Composer-Diff/releases/latest/download/composer-diff.phar + +# Make it executable +chmod +x composer-diff.phar ``` -## Usage +## Basic Usage ```bash +# Update your dependencies first composer update -# if it's installed via composer -php ./vendor/bin/composer-diff - -# OR (if installed globally) +# Show what changed (compares HEAD:composer.lock with ./composer.lock) composer-diff -# OR (if you downloaded phar file) +# If installed locally in project +php ./vendor/bin/composer-diff + +# If using PHAR file php composer-diff.phar ``` @@ -215,6 +253,128 @@ Rendered in your readme or PR/MR description: ``` +## Advanced Usage + +### Compare Specific Files +```bash +# Compare two specific composer.lock files +composer-diff --source="old/composer.lock" --target="new/composer.lock" + +# Compare Git references +composer-diff --source="HEAD~1:composer.lock" --target="HEAD:composer.lock" + +# Compare with specific branch or tag +composer-diff --source="v1.0.0:composer.lock" --target="./composer.lock" +``` + +### Environment Filtering +```bash +# Production dependencies only +composer-diff --env=require + +# Development dependencies only +composer-diff --env=require-dev + +# Both environments (default) +composer-diff --env=both +``` + +### Output Formatting +```bash +# Markdown output for Pull Requests +composer-diff --output=markdown + +# JSON output for automation +composer-diff --output=json + +# Hide comparison links +composer-diff --no-links + +# Strict mode (exit code 1 if differences found) +composer-diff --strict +``` + +### Real-world Examples +```bash +# Generate PR description after update +composer update +composer-diff --output=markdown >> pr-description.md + +# CI/CD pipeline check +composer-diff --strict --output=json > changes.json + +# Compare major version upgrades +composer-diff --source="tags/v1.0:composer.lock" --target="tags/v2.0:composer.lock" +``` + +## Requirements + +- **PHP**: ^8.2 +- **Extensions**: ext-json, ext-filter +- **Composer**: ^2.0 (for development) + +## Architecture + +The tool is built with a clean, object-oriented architecture: + +- **`DiffAction`**: Main CLI command handler (Symfony Console) +- **`Comparator`**: Orchestrates comparison between composer.lock files +- **`ComposerLock`**: Parses and manages composer.lock data +- **`Package`**: Represents individual packages with version handling +- **`Diff`**: Compares package versions and determines change types +- **`Url`**: Generates comparison URLs for Git hosting platforms +- **Renderers**: Multiple output formats (Console, Markdown, JSON) + +### Change Detection Logic + +The tool intelligently categorizes changes: + +- **New**: Package added to dependencies +- **Removed**: Package removed from dependencies +- **Upgraded**: Semantic version increased (1.0.0 → 2.0.0) +- **Downgraded**: Semantic version decreased (2.0.0 → 1.0.0) +- **Changed**: Dev branches with different commit hashes +- **Same**: No changes (filtered out by default) + +### Supported Git Platforms + +Automatically generates comparison URLs for: + +- **GitHub**: `github.com/user/repo/compare/v1.0.0...v2.0.0` +- **GitLab**: `gitlab.com/user/repo/compare/v1.0.0...v2.0.0` +- **Bitbucket**: `bitbucket.org/user/repo/branches/compare/v1.0.0%0Dv2.0.0` + +## Development + +### Setup +```bash +# Clone and install dependencies +git clone https://github.com/JBZoo/Composer-Diff.git +cd Composer-Diff +make build +``` + +### Testing +```bash +# Run all tests +make test-all + +# Run specific test suites +make test # PHPUnit tests +make test-drupal # Real Drupal upgrade test +make test-manual # Manual output examples +make codestyle # Code quality checks +``` + +### Building PHAR +```bash +# Build standalone PHAR executable +make build-phar + +# Create symlink for local testing +make create-symlink +``` + ## Roadmap * [ ] Supporting Drupal repos. [For example](https://git.drupalcode.org/project/fast_404).