ivuorinen/branch-usage-checker
1
0
Fork 0
mirror of https://github.com/ivuorinen/branch-usage-checker.git synced 2026-02-23 19:51:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
2a3791268524781c4c6ce64c752ae41c185a6de7
branch-usage-checker/CLAUDE.md
Ismo Vuorinen 2a37912685 chore: cleanup unused deps and dead code (#43) 
* 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.
2026-02-23 09:32:16 +02:00

2.4 KiB
Raw Blame History

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