feat: add ls and directories commands for browsing repo trees (#26)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alerizzo

.changeset/ls-and-directories-commands.md

@@ -0,0 +1,15 @@
+---
+"@codacy/codacy-cloud-cli": minor
+---
+
+Add `ls` and `directories` commands to browse a repository's tree with quality
+metrics. `ls` lists the directories and files at a path — showing Grade, Issues,
+Complexity, Duplication, and Coverage per row — and `directories` (alias `dirs`)
+lists folders only, with `--plus-children` to also show one level of
+sub-directories as a `└─` tree. Both auto-detect the provider/organization/repository
+from the git remote and the path from your current directory (relative to the
+repo root); override with positional args, `--path`, and `--branch`. Sort with
+`--sort <field>` (`name`, `issues`, `grade`, `duplication`, `complexity`,
+`coverage`) and `--direction asc|desc`. `codacy ls --search <term>` finds files
+at any depth under the path. Folders and files are marked with `▸` and `·` (no
+emojis). Both commands fetch every page of results, so nothing is truncated.

.gemini/styleguide.md

@@ -5,11 +5,15 @@ Commander.js CLI). Please weigh these before flagging style or correctness
 concerns.
 
 ## Testing
-- Tests mutate `process.env` directly: assign the variable in the test and
-  `delete` it in `beforeEach`/`afterEach` for isolation. This is the repo-wide
-  convention (see `src/utils/auth.test.ts` and ~10 other test files). Do **not**
-  suggest `vi.stubEnv` / `vi.unstubAllEnvs` — the codebase deliberately does not
-  use them, and consistency across the suite is preferred.
+- Tests mutate `process.env` directly: set the variable in `beforeEach` (which
+  re-assigns it before every test, so leakage between tests is a non-issue) and,
+  when a specific test needs it unset, `delete` it inside that test. An
+  `afterEach` cleanup block is **not** required and is **not** the convention —
+  ~13 of the 14 test files (`repositories.test.ts`, `issue.test.ts`,
+  `findings.test.ts`, …) use `beforeEach` only. Do **not** suggest adding
+  `afterEach`, and do **not** suggest `vi.stubEnv` / `vi.unstubAllEnvs` — the
+  codebase deliberately does not use them, and consistency across the suite is
+  preferred.
 - API service calls are mocked with `vi.mock(...)`; tests are co-located as
   `<module>.test.ts` next to the source.
 

README.md

@@ -78,6 +78,8 @@ Supported providers: GitHub (`gh`), GitLab (`gl`), Bitbucket (`bb`).
 | `info` | Show authenticated user info and their organizations |
 | `repositories <provider> <org>` | List repositories for an organization |
 | `repository [provider] [org] [repo]` | Show metrics for a repository, or add/remove/follow/unfollow/reanalyze it (optionally waiting for results) |
+| `ls [provider] [org] [repo]` | List (or search) directories and files at a path in a repository, with quality metrics and sorting |
+| `directories [provider] [org] [repo]` | List directories at a path in a repository (optionally one level of sub-directories), with quality metrics |
 | `issues [provider] [org] [repo]` | Search issues in a repository with filters |
 | `issue [provider] [org] [repo] <id>` | Show details for a single issue, or ignore/unignore it |
 | `findings [provider] [org] [repo]` | Show security findings for a repository or organization |

SPECS/README.md

@@ -15,6 +15,8 @@ _No pending tasks._ All commands implemented.
 | `info` | `inf` | ✅ Done | [info.md](commands/info.md) |
 | `repositories` | `repos` | ✅ Done | [repositories.md](commands/repositories.md) |
 | `repository` | `repo` | ✅ Done (actions added) | [repository.md](commands/repository.md) |
+| `ls` | N/A | ✅ Done | [ls.md](commands/ls.md) |
+| `directories` | `dirs` | ✅ Done | [directories.md](commands/directories.md) |
 | `pull-request` | `pr` | ✅ Done (--diff + Diff Coverage Summary added) | [pull-request.md](commands/pull-request.md) |
 | `issues` | `is` | ✅ Done | [issues.md](commands/issues.md) |
 | `issue` | `iss` | ✅ Done | [issue.md](commands/issue.md) |
@@ -71,3 +73,4 @@ _No pending tasks._ All commands implemented.
 | 2026-06-18 | `repo --output json` now includes `repository.fileCount`, plucked from `coverage.numberTotalFiles` on the existing `getRepositoryWithAnalysis` response (present even without coverage data — no extra API call). Unlocks repo-size visibility for downstream consumers like the `configure-codacy-cloud` skill (1 new test, 373 total) |
 | 2026-06-24 | `findings` and `finding` now surface the vulnerable dependency's import chain from the new `dependencyChains` field: Direct (`Update <pkg> to <fixed>`) vs Transitive (`<chain> (Fixed in <fixed>)`), with the middle collapsed to `... N more ...` for 4+ packages. List shows the first chain + `... and X more`; detail shows all chains aligned under a single label. New helpers in `utils/formatting.ts` (`formatDependencyChain`, `formatDependencyChainsLine`, `formatDependencyChainsBlock`); `dependencyChains` added to both JSON projections (17 new tests, 390 total) |
 | 2026-06-30 | npm-style "update available" notice via `update-notifier@5`: one-time stderr hint when a newer version is published, gated to `--output table` (suppressed for `json`, when piped, in CI, under `npx`). Non-blocking daily background check; never auto-updates. New `src/version.ts` (single source of name/version) + `src/utils/update-check.ts` (`maybeNotifyUpdate`); `preAction` hook + `--no-update-notifier` flag wired in `index.ts`. Opt-outs: `CODACY_DISABLE_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`, `--no-update-notifier`. `package.json` `overrides` pin transitive `got@^11.8.6`/`package-json@^7` (CVE-2022-33987) (7 new tests, 409 total) |
+| 2026-07-07 | `ls` and `directories` commands: browse a repository's folders/files with quality metrics (Grade/Issues/Complexity/Duplication/Coverage). Auto-detect provider/org/repo and the cwd-relative path; `--path`/`--branch` options; `directories --plus-children` shows one extra level as a `└─` tree (header adds `, M subdirectories`). `--sort`/`--direction` (server-side; in `ls`, directories and files sorted independently), and `ls --search <term>` (files only; folds the path into the search as `<path>/%<term>` and shows full paths). Duplication uses `numberOfClones`; Complexity uses `complexity` (hotspots). Both fetch **all** pages (no pagination warning) via new `src/utils/repo-tree.ts` (path resolution + `resolveSort`/`resolveDirection` + `fetchAllDirectories`/`fetchAllFiles`). Row markers `▸` folder / dim `·` file (no emojis). Promoted `formatGrade` to `utils/formatting.ts` (now also colors E red) and added `formatCountCell`/`formatCoverageCell` (48 new tests, 457 total) |

SPECS/commands/directories.md

@@ -0,0 +1,57 @@
+# `directories` Command Spec
+
+**Status:** ✅ Done (2026-07-07)
+
+## Purpose
+
+List the immediate directories at a path in a repository, each with quality metrics — like `ls` but folders only. With `--plus-children`, also lists each directory's immediate sub-directories (one extra level) so you can see a bigger picture of the folder structure and its metrics.
+
+## Usage
+
+```
+codacy directories                             # current directory's folders (auto-detected)
+codacy directories --plus-children             # also one more level of sub-folders
+codacy directories --path src/website
+codacy directories --sort issues --direction desc
+codacy directories gh my-org my-repo --plus-children
+codacy dirs --output json
+```
+
+## API Endpoints
+
+- [`listDirectories`](https://api.codacy.com/api/api-docs#listdirectories) — `RepositoryService.listDirectories(provider, org, repo, branch, path, sort, direction, cursor, limit)`
+
+Cursor-paginated; **all pages are fetched** (`fetchAllDirectories` in `utils/repo-tree.ts`) with no pagination warning. `--plus-children` issues one additional (fully paginated) `listDirectories` call per directory, concurrently, listing that directory's `path`.
+
+## Options
+
+| Option | Short | Description |
+|---|---|---|
+| `--path <path>` | `-p` | Repository-relative folder to list (defaults to the cwd relative to the repo root) |
+| `--branch <branch>` | `-b` | Branch name (defaults to the main branch) |
+| `--plus-children` | `-c` | Also list each directory's immediate sub-directories |
+| `--sort <field>` | `-S` | Sort by `name`, `issues`, `grade`, `duplication`, `complexity`, or `coverage` |
+| `--direction <direction>` | `-d` | `asc`/`ascending` or `desc`/`descending` |
+
+`--sort`/`--direction`, when given, are applied server-side to both the top-level listing and each `--plus-children` listing; otherwise directories are ordered by name.
+
+## Output
+
+Bold header `/<repo>/<path> — N directories` (with `--plus-children`, also `, M subdirectories` — the total children across all directories), then a columnar table (same columns as `ls`). Parent rows are prefixed `▸ <name>`; with `--plus-children`, each child is rendered on its own indented row `    └─ <name>` under its parent.
+
+| Column | Source | Notes |
+|---|---|---|
+| Name | `▸ <name>` / `    └─ <name>` | `▸` parent folder, `└─` child connector |
+| Grade | `gradeLetter` | A/B green, C yellow, D/E/F red |
+| Issues | `totalIssues` | Abbreviated (`formatCount`) |
+| Complexity | `complexity` | Highest file complexity under the path (hotspots) |
+| Duplication | `numberOfClones` | Number of cloned code blocks (matches Codacy's UI) |
+| Coverage | `coverageWithDecimals` | e.g. `76.3%` |
+
+Missing metrics render as a dim `-`. Only the Grade letter is colored. No pagination warning. Empty result prints "No directories found at …".
+
+JSON output: `{ path, directories: [ { …, children?: [...] } ] }`, each item projected via `pickDeep`; `children` present only with `--plus-children`.
+
+## Tests
+
+File: `src/commands/directories.test.ts` — 8 tests. Shared helpers covered in `src/utils/repo-tree.test.ts`.

SPECS/commands/ls.md

@@ -0,0 +1,61 @@
+# `ls` Command Spec
+
+**Status:** ✅ Done (2026-07-07)
+
+## Purpose
+
+List the immediate directories **and** files at a path in a repository (like Unix `ls`), each with quality metrics. Repository is auto-detected from the git remote; the path is auto-detected from the current working directory relative to the repo root, or given via `--path`, or defaults to the repo root.
+
+## Usage
+
+```
+codacy ls                                      # current directory (auto-detected)
+codacy ls --path src/website                   # a specific folder
+codacy ls gh my-org my-repo                    # root of an explicit repository
+codacy ls gh my-org my-repo --path src/website
+codacy ls --sort issues --direction desc       # worst files/folders first
+codacy ls --path app/client --search config    # search files under a path
+codacy ls --output json
+```
+
+## API Endpoints
+
+- [`listDirectories`](https://api.codacy.com/api/api-docs#listdirectories) — `RepositoryService.listDirectories(provider, org, repo, branch, path, sort, direction, cursor, limit)`
+- [`listFiles`](https://api.codacy.com/api/api-docs#listfiles) — `RepositoryService.listFiles(provider, org, repo, branch, path, search, sort, direction, cursor, limit)`
+
+Both endpoints are cursor-paginated. This command **fetches every page** (via `fetchAllDirectories` / `fetchAllFiles` in `utils/repo-tree.ts`) — it does **not** show a pagination warning. The `path` argument is always passed as an explicit string (`""` = repo root, non-recursive); it is never `undefined`, which would make `listFiles` recursive.
+
+## Options
+
+| Option | Short | Description |
+|---|---|---|
+| `--path <path>` | `-p` | Repository-relative folder to list (defaults to the cwd relative to the repo root) |
+| `--branch <branch>` | `-b` | Branch name (defaults to the main branch) |
+| `--search <term>` | `-s` | Search files (any depth) under the path instead of listing immediate children |
+| `--sort <field>` | `-S` | Sort by `name`, `issues`, `grade`, `duplication`, `complexity`, or `coverage` |
+| `--direction <direction>` | `-d` | `asc`/`ascending` or `desc`/`descending` |
+
+**Sorting.** With no `--sort`/`--direction`, results are ordered by name client-side. When either is given, ordering is delegated to the API (`sort`/`direction` params) — directories and files are sorted **independently** (each fully paginated, then concatenated), never merged. The CLI `name` field maps to the API's `filename` for files.
+
+**Search.** `--search` lists **files only** (the directories endpoint has no search). The folder scope is folded into the search term (`<path>/%<term>`, or just `<term>` at the root) and `path` is **not** sent, so matches are found at any depth under the path. Results show each file's full repository-relative path.
+
+## Output
+
+Bold header `/<repo>/<path> — N directories, M files`, then a columnar table with directories first (each sorted by name), then files.
+
+| Column | Source (directory / file) | Notes |
+|---|---|---|
+| Name | `▸ <dir.name>` / `· <basename(file.path)>` | `▸` folder, dim `·` file (no emojis); in search mode the file's full path is shown |
+| Grade | `gradeLetter` | A/B green, C yellow, D/E/F red |
+| Issues | `totalIssues` | Abbreviated (`formatCount`, e.g. `1.2k`) |
+| Complexity | `complexity` | Highest file complexity under the path (hotspots); files show the file value |
+| Duplication | `numberOfClones` | Number of cloned code blocks (matches Codacy's UI, not duplicated lines) |
+| Coverage | `coverageWithDecimals` | e.g. `76.3%` |
+
+Missing metrics render as a dim `-`. Only the Grade letter is colored (directory/file items carry no goal thresholds). No pagination warning (all pages fetched). Empty result prints "Nothing found at …".
+
+JSON output: `{ path, directories: [...], files: [...] }`, each item projected via `pickDeep`.
+
+## Tests
+
+File: `src/commands/ls.test.ts` — 14 tests. Shared helpers (path/sort/direction resolution, fetch-all) covered in `src/utils/repo-tree.test.ts`.

package.json

@@ -26,7 +26,7 @@
     "prepublishOnly": "npm run update-api && npm run build",
     "start": "npx ts-node src/index.ts",
     "start:dist": "node dist/index.js",
-    "fetch-api": "curl https://artifacts.codacy.com/api/codacy-api/56.1.1/apiv3-bundled.yaml -o ./api-v3/api-swagger.yaml --create-dirs",
+    "fetch-api": "curl https://artifacts.codacy.com/api/codacy-api/56.2.9/apiv3-bundled.yaml -o ./api-v3/api-swagger.yaml --create-dirs",
     "generate-api": "rm -rf ./src/api/client && openapi --input ./api-v3/api-swagger.yaml --output ./src/api/client --useUnionTypes --indent 2 --client fetch",
     "update-api": "npm run fetch-api && npm run generate-api",
     "check-types": "tsc --noEmit"

src/commands/AGENTS.md

@@ -109,6 +109,65 @@ Instead of a dedicated "Visibility" column (wastes horizontal space), public rep
 - **`--reanalyze` mode** (`-R`): fetches HEAD commit SHA, calls `RepositoryService.reanalyzeCommitById`; early return
 - **`--reanalyze-and-wait` mode** (`-w`): blocking variant — see "Reanalyze and wait" below. Baseline comes from `issuesOverview`; polling reads the repo's first commit via `listRepositoryCommits(limit=1)` analysis timestamps
 
+## ls command (`ls.ts`) and directories command (`directories.ts`)
+
+Repository-level "file browser" commands built on `RepositoryService.listFiles`
+and `listDirectories`. `ls` lists directories **and** files at a path;
+`directories` (alias `dirs`) lists folders only, with `-c, --plus-children` to
+also pull each folder's immediate sub-folders (one extra level).
+
+- **Repo + path resolution**: optional `[provider] [organization] [repository]`
+  positionals via `resolveRepoArgs(..., 0, ...)` (auto-detected from the git
+  remote when omitted). The listed path comes from `resolveListingPath(options.path, autoDetected)`
+  in `utils/repo-tree.ts`: an explicit `--path` wins; otherwise, when the repo
+  was auto-detected, the current working directory relative to the git root
+  (`getCwdRepoRelativePath` → `git rev-parse --show-toplevel` + `path.relative`);
+  otherwise the repo root. `autoDetected = !(provider && organization && repository)`.
+- **Fetch-all, no pagination warning (deliberate deviation)**: unlike every other
+  paginated command, these two fetch *all* pages (`fetchAllDirectories` /
+  `fetchAllFiles` loop over `pagination.cursor`) and do **not** call
+  `printPaginationWarning` — the whole listing must be shown. Do not "fix" this
+  by adding a warning.
+- **Explicit empty-string path**: the repo root is listed by passing `path = ""`
+  (not `undefined`). The generated client serializes `""` as `path=`, which the
+  API treats as "root, non-recursive"; `undefined` would omit the param and make
+  `listFiles` recursive across the whole repo. `fetchAll*` always take a `string`.
+- **Row markers (no emojis)**: `▸` (U+25B8) for folders, dim `·` for files.
+  `directories --plus-children` renders each child on its own indented row with a
+  `└─` connector under its parent (`DirectoryNode.children`).
+- **Metric columns**: Name, Grade, Issues, Complexity, Duplication, Coverage.
+  Grade via `formatGrade` (A/B green, C yellow, D/E/F red — Codacy folder/file
+  grades can be E). Issues/Complexity/Duplication via `formatCountCell`
+  (abbreviated, dim `-` when absent). Complexity is `complexity` (for a folder,
+  the *highest* file complexity under it — surfaces hotspots — not the
+  `complexitySum` total). Duplication is `numberOfClones` (number of cloned
+  code blocks, matching Codacy's UI — not `duplication`, which is duplicated
+  *lines*). Coverage via `formatCoverageCell` (`coverageWithDecimals`). Only the
+  Grade is colored — directory/file items carry no `goals` thresholds, so
+  metrics are not threshold-colored.
+- **Ordering / `--sort` + `--direction`**: with no sort flags, results are
+  sorted client-side by name (directories) / basename (files), ascending. When
+  `--sort` or `--direction` is given, ordering is delegated to the API (`sort`/
+  `direction` params, order preserved across pages) and the client sort is
+  skipped. `resolveSort`/`resolveDirection` (in `repo-tree.ts`) validate the
+  values and map them: CLI `name` → API `filename` for the files endpoint;
+  `ascending`/`descending` (and `asc`/`desc`) → `asc`/`desc`. In `ls`,
+  directories and files are always sorted **independently** and never merged
+  (dirs fully paginated + sorted, then files) so the type grouping holds. In
+  `directories`, the same sort is applied to the top-level and each
+  `--plus-children` listing.
+- **`ls --search <term>` (files only)**: `listDirectories` has no `search`, so
+  search mode lists files only (directories skipped). The folder scope is folded
+  into the search string as `<path>/%<term>` (just `<term>` at the repo root) and
+  `path` is **not** sent — otherwise the API would restrict to immediate
+  children. Results show each file's full repository-relative path (not just the
+  basename), since matches span folders.
+- **`directories --plus-children` header**: appends `, M subdirectories` where M
+  is the summed count of children across all listed directories.
+- **Aliases**: `directories` → `dirs`; `ls` has no alias (already the minimal
+  form).
+- JSON: `ls` → `{ path, directories, files }`; `directories` → `{ path, directories: [{…, children?}] }`, each item projected via `pickDeep`.
+
 ## Shared Formatting Utilities (`utils/formatting.ts`)
 
 Several helpers are shared between `repository.ts` and `pull-request.ts` via `utils/formatting.ts`: