issues and findings commands

Author: alerizzo

README.md

@@ -96,6 +96,72 @@ Displays a multi-section dashboard:
 - **Open Pull Requests** -- status, issues, coverage, complexity, duplication deltas
 - **Issues Overview** -- totals by category, severity, and language
 
+#### `issues <provider> <organization> <repository>`
+
+Search for issues in a repository with optional filters.
+
+```bash
+codacy issues gh my-org my-repo
+codacy issues gh my-org my-repo --branch main --severities Critical,High
+codacy issues gh my-org my-repo --categories Security --overview
+codacy issues gh my-org my-repo --output json
+```
+
+| Argument | Description |
+|---|---|
+| `provider` | Git provider: `gh` (GitHub), `gl` (GitLab), or `bb` (Bitbucket) |
+| `organization` | Organization name on the provider |
+| `repository` | Repository name |
+
+| Option | Description |
+|---|---|
+| `--branch <branch>` | Branch name (defaults to the main branch) |
+| `--patterns <patterns>` | Comma-separated list of pattern IDs |
+| `--severities <severities>` | Comma-separated list of severity levels: `Critical`, `High`, `Medium`, `Minor` |
+| `--categories <categories>` | Comma-separated list of category names |
+| `--languages <languages>` | Comma-separated list of language names |
+| `--tags <tags>` | Comma-separated list of tag names |
+| `--authors <authors>` | Comma-separated list of author emails |
+| `--overview` | Show issue count totals instead of the issues list |
+
+Without `--overview`, displays issues as cards sorted by severity (Error first), with file path, line content, and false-positive warnings where applicable.
+
+With `--overview`, displays issue count totals grouped by: category, severity, language, tag, and author.
+
+#### `findings <provider> <organization> [repository]`
+
+Show security findings for a repository or an entire organization.
+
+```bash
+codacy-cloud-cli findings gh my-org my-repo
+codacy-cloud-cli findings gh my-org
+codacy-cloud-cli findings gh my-org --severities Critical,High
+codacy-cloud-cli findings gh my-org my-repo --statuses Overdue,DueSoon
+codacy-cloud-cli findings gh my-org my-repo --output json
+```
+
+| Argument | Description |
+|---|---|
+| `provider` | Git provider: `gh` (GitHub), `gl` (GitLab), or `bb` (Bitbucket) |
+| `organization` | Organization name on the provider |
+| `repository` | Repository name (optional — omit to show org-wide findings) |
+
+| Option | Description |
+|---|---|
+| `-q, --search <text>` | Search term to filter findings |
+| `-s, --severities <severities>` | Comma-separated priority levels: `Critical`, `High`, `Medium`, `Low` |
+| `-S, --statuses <statuses>` | Comma-separated statuses: `Overdue`, `OnTrack`, `DueSoon`, `ClosedOnTime`, `ClosedLate`, `Ignored` |
+| `-c, --categories <categories>` | Comma-separated security category names |
+| `-T, --scan-types <types>` | Comma-separated scan types |
+| `-d, --dast-targets <urls>` | Comma-separated DAST target URLs |
+
+Displays findings as cards sorted by priority (Critical first). Each card shows:
+- Priority, security category, scan type, and (for pen test findings) likelihood and effort to fix
+- Finding title
+- Status, due date, CVE/CWE identifiers, affected/fixed versions, application, and affected targets
+
+When browsing org-wide (no repository argument), the repository name is shown on each card.
+
 #### `pull-request <provider> <organization> <repository> <prNumber>`
 
 Show details, analysis status, issues, and changed files for a specific pull request.

TODO.md

@@ -152,6 +152,64 @@ For the Issues List in particular, showing them in a table will not work. So fol
 - [x] 2026-02-18 Write tests for `pull-request` command
 
 
+### Issues Command
+> Search for issues in a repository.
+> API Endpoints to use: 
+- [searchRepositoryIssues](https://api.codacy.com/api/api-docs#searchrepositoryissues)
+- [issuesOverview](https://api.codacy.com/api/api-docs#issuesoverview)
+
+Allow these parameters to filter the issues:
+- branch: branch name
+- patterns: comma separated list of pattern IDs
+- severity: comma separated list of severity levels
+- category: comma separated list of category names
+- language: comma separated list of language names
+- tags: comma separated list of tag names
+- author: comma separated list of author emails
+- overview: boolean to show the overview of the issues instead of the list
+
+Use the same formatting as the `pull-request` command for the issues list. 
+
+If `overview` parameter is provided, show the totals by language, category, severity, tag, and author.
+
+Both endpoints accept the same body parameters for filtering (`SearchRepositoryIssuesBody`).
+
+- [x] 2026-02-19 Implement `issues` command - search for issues in a repository
+- [x] 2026-02-19 Write tests for `issues` command
+
+
+### Security Findings Command
+> Show security findings for a repository or an organization.
+> API Endpoints to use: 
+- [searchSecurityItems](https://api.codacy.com/api/api-docs#searchsecurityitems)
+
+For this command the repository part is optional.
+- codacy findings gh my-org my-repo // list findings for a repository
+- codacy findings gh my-org // list findings for the organization
+
+Allow these parameters to filter the findings:
+- search: search term to filter the findings
+- severities: comma separated list of severity (called priority in the API) names
+- statuses: comma separated list of status names
+- categories: comma separated list of category names
+- scan-types: comma separated list of scan types
+- dast-targets: comma separated list of DAST target URLs
+
+Use a similar formatting as the `issues` command, with the same rules (totals, pagination limits, etc.). This is the format:
+```
+--------------------------------
+
+{Severity/Priority} | {SecurityCategory} {ScanType} | {Optional: Likelihood} {Optional: EffortToFix} | {Optional: Repository Name when seeing organization findings}
+{Finding Title}
+
+{Status} {DueAt} | {Optional: CVE or CWE} {Optional: AffectedVersion -> FixedVersion} {Optional: Application} {Optional: AffectedTargets}  
+
+--------------------------------
+```
+
+- [x] 2026-02-20 Implement `findings` command - show security findings for a repository or an organization
+- [x] 2026-02-20 Write tests for `findings` command
+
 ## Deployment & CI
 
 - [x] 2026-02-18 Make the project ready to deploy to npm and be executed as a CLI tool by running `npm install -g`
@@ -175,3 +233,5 @@ For the Issues List in particular, showing them in a table will not work. So fol
 - 2026-02-18: npm package ready — bin, files, prepublishOnly, tsconfig.build.json, engines
 - 2026-02-18: CI pipelines — build+test on push/PR (Node 18/20/22), publish to npm on release
 - 2026-02-18: CLI help examples added to all commands
+- 2026-02-19: `issues` command implemented with tests (11 tests) — card-style list with filters, `--overview` mode with count tables by category/severity/language/tag/author
+- 2026-02-20: `findings` command implemented with tests (13 tests) — card-style list for repo or org-wide, filters by severity/status/category/scan-type/DAST targets, CVE/CWE/version display

package-lock.json

@@ -34,13 +34,17 @@
     "ansis": "4.0.0",
     "cli-table3": "^0.6.3",
     "commander": "14.0.0",
-    "dayjs": "^1.11.10",
-    "ora": "7.0.1"
+    "date-fns": "4.1.0",
+    "numeral": "2.0.6",
+    "ora": "7.0.1",
+    "pluralize": "8.0.0"
   },
   "devDependencies": {
     "@codacy/openapi-typescript-codegen": "0.0.8",
     "@types/commander": "2.12.0",
     "@types/node": "22.15.21",
+    "@types/numeral": "2.0.5",
+    "@types/pluralize": "0.0.33",
     "typescript": "5.8.3",
     "vitest": "4.0.18"
   }

package.json

@@ -4,6 +4,30 @@
 
 Each command is a single file that exports a `register<Name>Command(program: Command)` function. Commands are registered in `src/index.ts`.
 
+## Command Aliases
+
+Every command must declare a short alias via `.alias()`. Keep aliases short (2–4 characters) and intuitive:
+- `repositories` → `repos`
+- `repository` → `repo`
+- `pull-request` → `pr`
+- `issues` → `is`
+
+## Option Short Flags
+
+Every command option must have both a short flag and a long flag: `-X, --long-name <value>`. Pick single letters that are intuitive and don't conflict with Commander's built-in flags (`-V/--version`, `-h/--help`) or the global `-o/--output` option. When the natural letter is already taken, use uppercase (e.g. `-O, --overview` instead of `-o`).
+
+## Option Naming: Singular vs Plural
+
+Use a **singular** option name when the parameter accepts a single value, and a **plural** name when it accepts a comma-separated list:
+
+- `--branch main` → singular (one branch)
+- `--severities Critical,High` → plural (list of severity levels)
+- `--categories Security,CodeStyle` → plural (list of categories)
+- `--languages TypeScript,Python` → plural (list of languages)
+- `--authors dev@example.com,other@example.com` → plural (list of emails)
+
+This applies to both the long flag name and the metavar: `--severities <severities>`, not `--severities <severity>`.
+
 ## Output Format
 
 All commands support `--output json` via the global `-o, --output` option. Commands use `getOutputFormat(this)` (from `utils/output.ts`) to check the format and either: