add pull request command

Author: alerizzo

CLAUDE.md

@@ -33,7 +33,7 @@ codacy-cloud-cli/
 │   │       └── services/        # 28 service classes wrapping API endpoints
 │   ├── commands/                # One file per command (see Command Pattern below)
 │   │   └── CLAUDE.md            # Design decisions for commands
-│   └── utils/                   # Shared utilities (auth, error handling, output formatting)
+│   └── utils/                   # Shared utilities (auth, error handling, output formatting, formatting helpers)
 ├── api-v3/
 │   └── api-swagger.yaml         # OpenAPI 3.0.1 spec (source of truth for client generation)
 ├── dist/                        # Compiled JS output (gitignored)

README.md

@@ -87,6 +87,29 @@ Displays a multi-section dashboard:
 - **Open Pull Requests** -- status, issues, coverage, complexity, duplication deltas
 - **Issues Overview** -- totals by category, severity, and language
 
+#### `pull-request <provider> <organization> <repository> <prNumber>`
+
+Show details, analysis status, issues, and changed files for a specific pull request.
+
+```bash
+codacy-cloud-cli pull-request gh my-org my-repo 42
+codacy-cloud-cli pull-request gh my-org my-repo 42 --output json
+```
+
+| Argument | Description |
+|---|---|
+| `provider` | Git provider: `gh` (GitHub), `gl` (GitLab), or `bb` (Bitbucket) |
+| `organization` | Organization name on the provider |
+| `repository` | Repository name |
+| `prNumber` | Pull request number |
+
+Displays:
+- **About** -- PR title, status, author, branches, head commit
+- **Analysis** -- up-to-standards status, issues, coverage, complexity, duplication with gate pass/fail details
+- **New Issues** -- issues introduced by the PR, sorted by severity, with file path, line content, and detection tool
+- **New Potential Issues** -- potential issues that may need review
+- **Files** -- changed files with metric deltas (issues, coverage, complexity, duplication)
+
 ## Development
 
 ```bash

TODO.md

@@ -92,6 +92,66 @@ Important information to show:
 - [x] 2026-02-18 Implement `repository` command - show details, status, and metrics for a specific repository
 - [x] 2026-02-18 Write tests for `repository` command
 
+### Pull Request Command
+> Show details for a specific pull request.
+> API Endpoints to use: 
+- [getRepositoryPullRequest](https://api.codacy.com/api/api-docs#getrepositorypullrequest)
+- [listPullRequestIssues](https://api.codacy.com/api/api-docs#listpullrequestissues)
+- [listPullRequestFiles](https://api.codacy.com/api/api-docs#listpullrequestfiles)
+
+Important information to show:
+- About the pull request
+  - Provider / Organization / Repository Name / Visibility
+  - Pull Request Number
+  - Title
+  - Created At
+  - Updated At
+  - Last Analysis (Time and Commit SHA)
+  - From Branch to Target Branch
+  - Status (Open, Closed, Merged)
+  - Author
+- About the analysis
+  - Is it currently being analyzed?
+  - Is it up to standards?
+  - Issues (New and Fixed)
+  - Coverage Diff and Delta
+  - Complex Delta
+  - Duplication Delta
+  - General considerations
+    - use again `resultReasons` to color the metrics, and this time, if a metric is not up to the standards, show why (e.g. "Fails <= 2 medium issues")
+    - if in `resultReasons` there is a gate value expected for a metric that still has no data, also show it next to the metric saying for example "To check >= 50% gate"
+- Issues List: show new and new potential issues only (`onlyPotential` false for non potential, true for only potential -- new issues have `deltaType` = 'Added'); sort by severity level, showing the most sever first
+  - File Path, Line Number
+  - Line content
+  - Issue message
+  - Category
+  - Severity (red for critical/error, orange for high, yellow for medium/warning, blue for low/info)
+  - Subcategory (only for security issues)
+  - Detected by (Tool + Pattern title; e.g. "ESLint: no undef vars")
+- Files List: list only files with any metric delta change
+  - File Path
+  - Issues +{New Issues} / -{Fixed Issues}
+  - Coverage Delta +/-{Delta Coverage %}
+  - Complex Delta
+  - Duplication Delta
+
+For the Issues List in particular, showing them in a table will not work. So follow this format:
+```
+--------------------------------
+
+{Severity} | {Category} {Subcategory} | {Detected by}
+{Issue Message}
+
+{File Path}:{Line Number} 
+{Line content}
+
+--------------------------------
+```
+
+- [x] 2026-02-18 Implement `pull-request` command - show details for a specific pull request
+- [x] 2026-02-18 Write tests for `pull-request` command
+
+
 ## Deployment & CI
 
 - [ ] Make the project ready to deploy to npm and be executed as a CLI tool by running `npm install -g`
@@ -109,3 +169,5 @@ Important information to show:
 - 2026-02-17: Utility tests added for `auth` and `providers` (6 tests)
 - 2026-02-17: `src/commands/CLAUDE.md` created with design decisions
 - 2026-02-18: `repository` command implemented with tests (5 tests) — dashboard with about, setup, metrics, PRs, and issues overview
+- 2026-02-18: Extracted shared formatting helpers to `utils/formatting.ts` (reused by repository + pull-request)
+- 2026-02-18: `pull-request` command implemented with tests (9 tests) — about, analysis with gate reasons, issues cards, files list

src/commands/CLAUDE.md

@@ -82,3 +82,41 @@ Instead of a dedicated "Visibility" column (wastes horizontal space), public rep
   - **Issues Overview**: three count tables — by category, severity level, and language — sorted descending by count within each group
 - Shows pagination warning for pull requests if more exist
 - JSON output bundles all three API responses into a single object
+
+## Shared Formatting Utilities (`utils/formatting.ts`)
+
+Several helpers are shared between `repository.ts` and `pull-request.ts` via `utils/formatting.ts`:
+- `printSection(title)` — bold section header
+- `truncate(text, max)` — truncate with "..." suffix
+- `colorMetric(value, threshold, mode)` — threshold-based coloring (max/min)
+- `colorByGate(display, passing)` — green/red based on gate status
+- `formatDelta(value, passing)` — +/- signed value with optional gate coloring
+- `buildGateStatus(pr)` — maps `resultReasons` gate names to metric columns
+- `formatStandards(pr)` — ✓/✗/- from quality + coverage `isUpToStandards`
+- `formatPrCoverage(pr, passing)` — diffCoverage% (+/-deltaCoverage%)
+- `formatPrIssues(pr, passing)` — +newIssues (colored by gate) / -fixedIssues (always gray)
+
+## pull-request command (`pull-request.ts`)
+
+- Takes `<provider>`, `<organization>`, `<repository>`, and `<prNumber>` as required arguments
+- Calls four API endpoints in parallel:
+  - `getRepositoryPullRequest` — PR metadata + analysis summary
+  - `listPullRequestIssues` (status=new, onlyPotential=false) — new confirmed issues
+  - `listPullRequestIssues` (status=new, onlyPotential=true) — new potential issues
+  - `listPullRequestFiles` — files with metric deltas
+- Displays a multi-section view:
+  - **About**: provider/org/repo, PR number + title, status, author, branches (origin → target), updated (friendly date), head commit SHA
+  - **Analysis**: analyzing status, up-to-standards (✓/✗ computed from quality + coverage), issues, coverage, complexity, duplication — all colored by gate status
+    - Gate failure/pass reasons shown inline next to the metric (e.g. "Fails <= 2 warning issues", "Fails <= 0 security issues")
+    - "To check" hints shown inline when a gate is configured but the metric has no data yet (e.g. "To check >= 50% coverage")
+    - Security gates (`securityIssueThreshold`) are handled explicitly — not falling through to generic formatting
+  - **Issues**: single merged list of confirmed + potential issues, card-style format (not a table), sorted by severity (Error > High > Warning > Info)
+    - Each card shows: colored severity | category + subcategory | POTENTIAL (if potential issue)
+    - Message, file:line, line content
+    - Severity colors: Error=red, High=orange (#FF8C00), Warning=yellow, Info=blue
+    - False positive detection: if `falsePositiveProbability >= falsePositiveThreshold`, shows "Potential false positive: {reason}" below line content
+  - **Files**: table showing only files with any metric delta change
+    - File path (truncated at 50), issues (new red, fixed green), coverage delta, complexity delta, duplication delta
+    - Zero values shown in gray without +/- sign; N/A also gray
+- Shows pagination warnings for issues and files
+- JSON output bundles PR data, new issues, potential issues, and files