mirror of
https://github.com/ivuorinen/branch-usage-checker.git
synced 2026-02-24 09:52:01 +00:00
Ismo Vuorinen
2a37912685
* chore: remove unused code and dead files
Remove InspireCommand, GitHubApiBranch DTO, PackagistApiStatsPayload DTO,
and GitHubRestApi fetcher. Remove InspireCommand reference from config.
* chore(deps): remove unused composer dependencies
Remove guzzlehttp/guzzle, laravel-zero/phar-updater, and
nunomaduro/termwind. Clean up dead autoload entries and orphaned
allow-plugins configuration.
* feat: improve CheckCommand input handling and error reporting
Add vendor/package slash format support, input validation, HTTP error
handling, and concurrent stats fetching. Replace exit() calls with
return statements. Add 13 new test cases with Http::fake coverage.
* build: rebuild PHAR executable
* chore: add CLAUDE.md project instructions
* docs: add design for PHPCS + CaptainHook integration
* docs: add implementation plan for PHPCS + CaptainHook
* build(deps): add squizlabs/php_codesniffer
* build: add composer lint and format scripts
* build(deps): add captainhook and hook-installer
* build: configure CaptainHook pre-commit hook for PHPCS
* docs: add lint/format commands and hook info to CLAUDE.md
* build: add markdownlint-cli2 configuration
* build: add lint:md, lint:ec, lint:all, and format:md composer scripts
* build: add editorconfig and markdownlint to pre-commit hook
* docs: add new lint and format commands to CLAUDE.md
* chore: add missing gitignore patterns
* refactor: replace Http facade with injected HttpFactory
- Resolve HttpFactory via the container instead of using the Http facade
directly, improving testability and explicitness
- Simplify early-return logic in package metadata error handling
- Reformat long strings and closures for PSR-12 line length compliance
- Extract repeated stats URL prefix into variable in tests
* build: add Claude Code shared settings and skills
Add shared hooks (auto-format PHP on edit, block vendor/lock edits),
shared permissions for common dev commands, and two user-invocable
skills (/build-phar, /release-check).
* refactor: extract test constants to reduce duplication in CheckCommandTest
Replace 6 occurrences of the command string and 4 occurrences of the
stats URL with TEST_COMMAND and TEST_STATS_URL constants. Fixes
SonarCloud S1192 code smells and brings duplicated lines density
below the 3% threshold.
* refactor: extract resolveInput and fetchPackageMetadata from handle()
Reduce handle() from 8 return statements to 3 by extracting input
validation into resolveInput() and HTTP fetching into
fetchPackageMetadata(). Fixes SonarCloud S1142 (too many returns).
* fix: improve CheckCommand error handling, input normalization, and timeouts
- Return exit code 1 from catch block instead of silently succeeding
- Normalize vendor/package inputs to lowercase before validation
- Add 10-second HTTP timeouts to metadata fetch and pool requests
- Return false from outputSuggestions when no suggestions found
* test: stub HTTP in live-request tests and assert exception output
- Add Http::fake() to slash-format and two-argument tests to prevent
real Packagist requests during CI
- Assert exception message in try-block test and expect exit code 1
to match the updated catch behavior
* docs: fix command signature, remove stale Fetchers reference in CLAUDE.md
- Change {package} to {package?} and note vendor/package combined form
- Remove non-existent app/Fetchers/ directory reference
- Update HTTP dependency note to reflect HttpFactory injection
* fix: guard array_combine against mismatched Packagist stats
Add a length check before array_combine() so malformed stats
(different label/value counts) produce a warning and skip the
branch instead of throwing a ValueError.
* refactor: change outputSuggestions return type to void
No caller uses the return value. Replace bool return type with
void and remove the now-unnecessary return statements.
* fix: narrow Throwable catch to Exception, add docblocks, remove unused default
- Catch \Exception instead of \Throwable so programming errors (TypeError,
OutOfMemoryError) propagate instead of being silently displayed
- Add minimal PHPDoc summaries to all CheckCommand methods for coverage
- Remove unused default `= []` on outputSuggestions parameter
- Update test to expect TypeError propagation via ->throws()
* refactor: extract constants, fix dead store, deduplicate test setup
- Add TIMEOUT_SECONDS and PACKAGIST_URL constants in CheckCommand
- Replace inline timeout(10) and URL strings with constant references
- Fix dead store: $deletable[$k] = $values['Total'] → $deletable[] = $k
- Eliminate unused $keys intermediate variable in outputSuggestions()
- Standardize string formatting to use sprintf() consistently
- Add TEST_METADATA_URL constant and fakePackageResponses() helper in tests
- Refactor 6 tests to use shared helper, reducing Http::fake duplication
* docs: fix capitalization and remove stale GitHub reference in CLAUDE.md
* docs: add design for fixing SonarCloud duplication quality gate
* docs: add implementation plan for SonarCloud duplication fix
* refactor(tests): parameterize input-validation tests to fix duplication gate
* feat: add PHPMD linter and fix Codacy markdownlint config
Add PHPMD as a dev dependency with cleancode, codesize, unusedcode, and
naming rulesets. Integrate via composer lint:phpmd script, lint:all, and
CaptainHook pre-commit hook.
Split markdownlint config into .markdownlint.jsonc (rules) and
.markdownlint-cli2.jsonc (ignores only) so Codacy's plain markdownlint
can discover the shared rules file.
* fix: rename markdownlint config to .json and disable MD043
Rename .markdownlint.jsonc to .markdownlint.json so Codacy discovers
it at highest priority, and add required-headings: false to explicitly
disable MD043 which flags docs with varying heading structures.
* fix: guard against ConnectionException in pool responses and catch Throwable
Pool responses can be Throwable (e.g. ConnectionException) instead of
Response objects, causing crashes on ->failed(). Add instanceof guard,
widen catch to Throwable with TypeError re-throw, and extract loop into
collectBranchStats() to stay under cyclomatic complexity threshold.
82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# Branch Usage Checker
|
|
|
|
This file provides guidance to Claude Code
|
|
(claude.ai/code) when working with code in this
|
|
repository.
|
|
|
|
## Project Overview
|
|
|
|
Branch Usage Checker is a Laravel Zero CLI tool
|
|
that cross-references GitHub branches with
|
|
Packagist download statistics to identify branches
|
|
safe to delete. Built as a PHAR-distributable PHP
|
|
application.
|
|
|
|
## Commands
|
|
|
|
- `composer install` — Install dependencies
|
|
- `composer test` — Run tests (Pest v4)
|
|
- `composer build` — Build PHAR executable
|
|
to `builds/branch-usage-checker`
|
|
- `composer lint` — Check code style (PHPCS)
|
|
- `composer lint:phpmd` — Static analysis (PHPMD)
|
|
- `composer lint:md` — Lint markdown files
|
|
- `composer lint:ec` — Check EditorConfig compliance
|
|
- `composer lint:all` — Run all linters
|
|
- `composer format` — Auto-fix code style (PHPCBF)
|
|
- `composer format:md` — Format Markdown tables
|
|
- `composer x` — Run the built PHAR
|
|
- `vendor/bin/pest --filter "test name"` — Run a
|
|
single test
|
|
|
|
## Code Standards
|
|
|
|
- PSR-12 via PHP CodeSniffer (`phpcs.xml`),
|
|
with `PSR12.Operators.OperatorSpacing` excluded
|
|
- PHP 8.4 required
|
|
- Composer normalize runs automatically on
|
|
autoload dump
|
|
- CaptainHook pre-commit hook runs PHPCBF
|
|
then PHPCS on staged PHP files automatically
|
|
|
|
## Architecture
|
|
|
|
This is a Laravel Zero console application.
|
|
Entry point is `./application`, which bootstraps
|
|
via `bootstrap/app.php`.
|
|
|
|
### Core Flow (CheckCommand)
|
|
|
|
`check {vendor} {package?} {months=9}` — the main
|
|
(and only functional) command. The `vendor` argument
|
|
accepts a combined `vendor/package` form, making
|
|
`package` optional in that case:
|
|
|
|
1. Fetches package metadata from
|
|
`packagist.org/packages/{vendor}/{package}.json`
|
|
2. Extracts branches (versions prefixed with
|
|
`dev-`)
|
|
3. For each branch, fetches monthly download
|
|
stats from Packagist over the configured
|
|
lookback window
|
|
4. Displays a statistics table and a suggestions
|
|
table (branches with zero downloads)
|
|
|
|
### Key Directories
|
|
|
|
- `app/Commands/` — CLI commands
|
|
(CheckCommand is the primary one)
|
|
- `app/Dto/` — Spatie DataTransferObject classes
|
|
for Packagist API responses
|
|
- `tests/Feature/Commands/` — Feature tests
|
|
for commands
|
|
- `builds/` — PHAR output directory
|
|
|
|
### Dependencies of Note
|
|
|
|
- HTTP requests use `Illuminate\Http\Client\Factory`
|
|
(Guzzle-backed), injected via the container
|
|
- DTOs use `spatie/data-transfer-object` with
|
|
`MapFrom` attributes for JSON field mapping
|
|
- PHAR building configured in `box.json`
|