Skip to content

usage.md

Latest commit

 

History

History
161 lines (110 loc) · 4.54 KB

usage.md

File metadata and controls

161 lines (110 loc) · 4.54 KB

Usage

PR Maven CLI turns Maven test, quality, and selected build log artifacts into focused failure context.

It answers:

What failed, in which Maven module, through which Maven plugin, and how do I reproduce it locally?

Commands

prmaven fails -project .
prmaven fails -project . -format json
prmaven why -project .
prmaven why -project . -format json
prmaven why -project . -module payment-core
prmaven why -project . -format json -output prmaven-report.json
prmaven version

Stage 1 treats fails and why as equivalent analysis commands. The separate names leave room for future UX where fails lists failures and why adds richer causality evidence.

Flags

  • -project: Maven project directory to analyze. Defaults to ..
  • -format: output format. Supported values are text and json. Defaults to text.
  • -module: optional Maven module filter. Matches either a module path, such as payment-core, or a module artifactId. Limits emitted findings to matching modules.
  • -output: optional file path for the generated text or JSON report. When omitted, output is written to stdout.

When -module is set and no module matches, PR Maven CLI emits zero findings for that filtered view.

Exit Codes

  • 0: analysis completed and no findings were found.
  • 1: analysis completed with Maven failure findings, or analysis failed.
  • 2: invalid CLI usage.

The non-zero finding exit code is useful in CI because a failed test suite should remain visible as a failed job while still printing structured context.

Demo: Failure Fixture

From the repository root:

go run ./cmd/prmaven fails -project demo/multi-module-failure

Expected behavior:

  • prints the Maven project root;
  • discovers the aggregator and modules;
  • reads Surefire reports from target/surefire-reports;
  • reads Failsafe reports from target/failsafe-reports;
  • reports two findings;
  • prints minimal reproduction commands.

Example reproduction commands:

mvn -pl payment-core -am -Dtest=PaymentRoundingTest test
mvn -pl payment-api -am -Dit.test=PaymentApiIT verify

JSON output:

go run ./cmd/prmaven why -project demo/multi-module-failure -format json

The JSON contract is designed for CI systems, bots, and coding agents. It includes summary, modules, and findings.

For field-level details and compatibility expectations, read JSON contract.

Provider Integrations

Stage 1 has no native GitHub or GitLab API adapter. The CLI does not need provider tokens and does not call remote PR, check-run, issue, or merge request APIs.

GitHub is the only platform with first-party project automation and a copyable CI example today. For the full integration scope and planned native adapters, read integrations.md.

Demo: No-Failure Fixture

go run ./cmd/prmaven fails -project demo/no-failure

Expected behavior:

  • exits with code 0;
  • reports zero findings;
  • confirms that no supported Maven test or quality failures were found.

Use Against A Real Maven Workspace

First generate test report artifacts with Maven:

mvn -B test

For integration tests that use Failsafe:

mvn -B verify

Then analyze the workspace:

prmaven fails -project /path/to/maven/repo

The CLI scans module-level report folders and deterministic quality artifacts such as:

target/surefire-reports
target/failsafe-reports
target/checkstyle-result.xml
target/spotbugsXml.xml
target/spotbugs.xml
target/maven-enforcer.log
target/jacoco.log
target/maven.log

CI Pattern

This pattern keeps the Maven failure visible while still collecting PR Maven CLI output.

set +e
mvn -B verify
maven_status=$?

prmaven why -project . || true
prmaven why -project . -format json -output prmaven-report.json || true

exit "$maven_status"

When a workflow needs a machine-checked report contract, validate prmaven-report.json with ../schema/prmaven-report.schema.json before uploading or handing it to another tool.

A complete GitHub Actions example is available at ../examples/github-actions/triage-maven-failures.yml.

Library Usage

Use pkg/prmaven when another Go tool needs direct access to the report model.

report, err := prmaven.Analyze(prmaven.Options{ProjectDir: "."})
if err != nil {
    return err
}
for _, finding := range report.Findings {
    fmt.Println(finding.ReproduceCommand)
}

A runnable example is available at ../examples/library.