Skip to content

README.md

Latest commit

 

History

History
158 lines (111 loc) · 5.88 KB

README.md

File metadata and controls

158 lines (111 loc) · 5.88 KB

PR Composer CLI

Composer-aware PR and CI triage for PHP teams.

PR Composer CLI is planned as a local-first CLI and PHP library that turns Composer install, dependency resolution, test, static analysis, style, and build failures into actionable pull request context.

It will focus on evidence already present in a local workspace or CI artifact directory: composer.json, composer.lock, Composer scripts, PHPUnit or Pest reports, static analysis output, coding standard diagnostics, and build logs.

It should answer the first production question after a PHP PR fails:

Which package, dependency, script, test, or quality gate failed, what evidence proves it, and how do I reproduce it locally?

Status

Project seed.

This repository is public so the project direction can be shaped openly, but no CLI package has been published yet and no production release is available.

The first implementation should stay small, deterministic, and usable without GitHub tokens, CI API access, AI providers, telemetry, or external services.

Why This Exists

Generic PR tools can show that CI failed. Generic agents can inspect logs when prompted. Larger observability platforms can collect broad build telemetry.

PR Composer CLI will focus on a narrower production workflow:

Turn Composer and PHP CI failures into deterministic PR context.

This is useful for:

  • PHP teams maintaining libraries, frameworks, applications, or monorepos.
  • OSS maintainers triaging failing pull requests.
  • Package maintainers validating Packagist publishing readiness.
  • Engineering platform teams standardizing PHP CI failure summaries.
  • Regulated teams that cannot send logs to external services.
  • Internal agent platforms that need structured local evidence.

Composer And PHP Ecosystem Focus

The initial direction is Composer-first and Packagist-aware.

Expected inputs:

  • composer.json.
  • composer.lock.
  • Composer scripts.
  • Composer install, update, validate, and platform requirement logs.
  • dependency resolution errors and package conflicts.
  • vendor/composer/installed.json when present.
  • PHPUnit JUnit XML reports.
  • Pest reports when exported in machine-readable formats.
  • PHPStan or Psalm diagnostics.
  • PHP_CodeSniffer or PHP CS Fixer diagnostics.
  • Rector output when used as a quality gate.
  • coverage reports such as Clover or Cobertura XML.
  • framework-specific CI logs from Laravel, Symfony, Drupal, WordPress, Magento, or similar PHP projects when available as local artifacts.

Expected output:

  • human-readable text for maintainers and contributors;
  • stable JSON for CI systems and coding agents;
  • package, namespace, script, or test-suite mapping;
  • failing dependency, test, analyzer, style, or build context;
  • report path or log artifact references;
  • minimal reproduction commands such as composer install, composer test, vendor/bin/phpunit, or composer analyse when enough evidence exists.

Planned MVP

The first useful version should prioritize:

  • discovery of Composer project metadata from composer.json;
  • detection of Composer scripts and package metadata;
  • parsing of Composer install and dependency resolution failures from captured logs;
  • parsing of PHPUnit JUnit XML reports;
  • parsing of PHPStan or Psalm diagnostics from captured logs or exported reports;
  • parsing of PHP_CodeSniffer diagnostics from machine-readable output or captured logs;
  • mapping findings back to packages, namespaces, files, or test cases;
  • deterministic text output;
  • deterministic JSON output;
  • demo fixtures for failing and passing PHP projects;
  • end-to-end CLI tests;
  • GitHub Actions examples without requiring GitHub API access at runtime.

Non-Goals For The First MVP

  • Replacing Composer, Packagist, PHPUnit, Pest, PHPStan, Psalm, or framework CLIs.
  • Executing arbitrary project commands as part of analysis.
  • Requiring hosted CI provider APIs.
  • Uploading logs to external services.
  • Providing AI-generated explanations as a required runtime feature.
  • Supporting every PHP framework on day one.
  • Publishing a native GitHub or GitLab API adapter before the local evidence model is stable.

Planned Usage

The exact commands are still subject to design, but the intended shape is:

prcomposer fails --project .
prcomposer fails --project . --format json
prcomposer why --project . --file src/Service/CheckoutService.php

The CLI should inspect existing reports and logs. It should not need network access to answer local failure-context questions.

Package Manager Scope

Composer and Packagist are the initial baseline because they are the center of modern PHP dependency management and package distribution.

Future support can add explicit handling for:

  • Composer path repositories;
  • private Composer repositories;
  • plugin-related install failures;
  • platform configuration and PHP extension constraints;
  • monorepo package layouts;
  • framework-specific test and quality report conventions.

The tool should respect the project's chosen Composer configuration instead of forcing every PHP repository into one application layout.

Relationship To PR Maven CLI

PR Composer CLI follows the same product family idea as PR Maven CLI:

  • local-first analysis;
  • deterministic evidence;
  • text and JSON output;
  • CI and agent-friendly summaries;
  • no runtime dependency on provider tokens for core analysis.

The implementation and terminology should be native to the PHP and Composer ecosystem, not a Java/Maven model copied into PHP projects.

Contributing

This project is intentionally early.

Good first contribution areas will likely include:

  • Composer dependency failure fixtures;
  • PHPUnit report fixtures;
  • Pest report fixtures;
  • PHPStan or Psalm diagnostic fixtures;
  • PHP_CodeSniffer diagnostic fixtures;
  • JSON output contracts;
  • CLI ergonomics;
  • documentation for CI examples.

Founder

PR Composer CLI was founded by Will-thom.

License

License to be added before the first release.