cpp_linter/cli.py (1)

400-405: Subcommand wiring — consider minor help UX tweaks.

Add a title/metavar so --help shows a clearer “Subcommands” section.

Apply within this block:

-    sub_parser = cli_parser.add_subparsers(
-        description="Subcommands for special behavior", dest="command"
-    )
+    sub_parser = cli_parser.add_subparsers(
+        description="Subcommands for special behavior",
+        dest="command",
+        title="Subcommands",
+        metavar="command",
+    )

.github/workflows/run-dev-tests.yml (1)

28-29: Matrix updates OK; two quick nits/checks.

• Quote consistency nit:

-        os: ['windows-latest', ubuntu-latest]
+        os: ['windows-latest', 'ubuntu-latest']

• Intent check: Only the clang=20 job runs tests that aren’t marked no_clang (see Lines 98–101). With clang 21 added, do you still want 20 to be the “full” run, or should that switch to 21?

docs/conf.py (4)

292-299: Avoid runtime asserts in non-test code (ruff S101)

Replace asserts with explicit errors for clearer failures in docs builds.

-            assert arg.dest is not None
+            if arg.dest is None:
+                raise ValueError("arg.dest is None; CLI parser misconfigured")
...
-                assert arg.help is not None
+                if arg.help is None:
+                    raise ValueError(f"Missing help for positional argument '{arg.dest}'")

If you prefer keeping asserts, add “# noqa: S101” with justification.

---

284-299: Subparser detection may be brittle; add a robust fallback

Relying on encountering a “command” positional within parser._optionals can miss subparsers depending on how the parser is structured. Add a post-loop fallback that scans all actions for _SubParsersAction.

         for arg in args:
             if arg.option_strings:
                 continue
             if arg.dest is None:
                 raise ValueError("arg.dest is None; CLI parser misconfigured")
             if arg.dest != "command":
                 doc.write(f"\n.. std:option:: {arg.dest.lower()}\n\n")
                 if arg.help is None:
                     raise ValueError(f"Missing help for positional argument '{arg.dest}'")
                 idx = arg.help.find("Defaults to")
                 help_text = arg.help if idx == -1 else arg.help[:idx]
                 doc.write("\n    ".join(help_text.splitlines()))
             else:
                 sub_commands = arg
+
+        # Fallback: ensure we found subparsers even if grouping differs
+        if sub_commands is None:
+            for a in parser._actions:
+                if isinstance(a, argparse._SubParsersAction):
+                    sub_commands = a
+                    break

---

327-338: Make subcommand section resilient and drop redundant assert

• Accessing SUBCOMMAND_VERSIONS with [] will KeyError on new subcommands.
• The assert at Line 328 is redundant due to the guard.
• Description may be None; prefer a safe default.

-        if sub_commands is not None:
-            assert sub_commands is not None
+        if sub_commands is not None:
             choices = cast(Dict[str, argparse.ArgumentParser], sub_commands.choices)
             doc.write("\n\nSubcommands\n")
             doc.write("-----------\n")
             for sub_cmd in choices:
                 doc.write(f"\n.. std:option:: {sub_cmd}\n")
-                version = SUBCOMMAND_VERSIONS[sub_cmd]
+                version = SUBCOMMAND_VERSIONS.get(sub_cmd, release)
                 doc.write(f"\n    :badge-version:`{version}`\n\n    ")
                 sub_cmd_action = choices[sub_cmd]
-                assert sub_cmd_action.description is not None
-                doc.write("\n    ".join(sub_cmd_action.description.splitlines()) + "\n")
+                desc = sub_cmd_action.description or ""
+                doc.write("\n    ".join(desc.splitlines()) + "\n")

---

242-242: Centralize and document SUBCOMMAND_VERSIONS maintenance

Mapping looks good. Consider a brief comment or test that fails if a new subcommand lacks a version entry, to keep docs consistent.

tests/test_cli_args.py (1)

54-59: LGTM: “version” subcommand parsing

Test clearly verifies the new subcommand path. Consider also asserting no unintended args are set.

tests/list_changes/test_get_file_changes.py (3)

8-8: Avoid private import; use the public constant instead.

Importing from a private module (_version) couples the test to build-time artifacts. Prefer the exported USER_AGENT for a stable expectation that tracks production behavior.

Apply:

-from cpp_linter._version import version
+from cpp_linter.rest_api import USER_AGENT

---

118-126: Align expected header with production constant.

Use USER_AGENT to prevent drift if the format changes (e.g., metadata added).

         mock.get(
             endpoint,
             request_headers={
                 "Authorization": "token 123456",
                 "Accept": "application/vnd.github.diff",
-                "User-Agent": f"cpp-linter/{version}",
+                "User-Agent": USER_AGENT,
             },

---

136-146: Same here—match the standardized User-Agent.

                 mock.get(
                     mock_endpoint + ("" if pg == 1 else "?page=2"),
                     request_headers={
                         "Authorization": "token 123456",
                         "Accept": "application/vnd.github.raw+json",
-                        "User-Agent": f"cpp-linter/{version}",
+                        "User-Agent": USER_AGENT,
                     },

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#143
File: noxfile.py:10-10
Timestamp: 2025-05-31T03:53:32.334Z
Learning: In cpp-linter project, dev dependencies including `nox`, `mypy`, `ruff`, `pre-commit`, `rich`, and `types-requests` are properly configured in pyproject.toml under the `[dependency-groups]` dev section. Running `uv sync` installs all necessary dev requirements.

.github/dependabot.yml (2)

11-11: Monthly is fine; consider a faster cadence for Actions due to frequent security fixes.

Optional: switch Actions to weekly or keep monthly but enable/confirm Dependabot security updates so CVE PRs aren’t delayed by the schedule. You can also add time/timezone to batch PRs predictably.

---

19-19: uv updates monthly: OK; add scheduling hygiene if noise becomes an issue.

If you later want tighter control without increasing volume, set schedule.time/timezone and keep grouping. uv is now a supported ecosystem, so this config is valid.

.github/workflows/build-docs.yml (1)

15-15: Good pin on setup-uv to a commit.

LGTM. As a follow-up, consider pinning other third‑party actions (e.g., actions-gh-pages) to SHAs for supply‑chain hardening.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#143
File: .github/dependabot.yml:16-23
Timestamp: 2025-05-31T02:10:01.595Z
Learning: As of March 13, 2025, Dependabot officially supports `uv` as a package-ecosystem in general availability. Prior to this date, `uv` was not supported by Dependabot. The configuration `package-ecosystem: uv` is now valid and will enable automated dependency updates for uv.lock files.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#143
File: .github/dependabot.yml:16-23
Timestamp: 2025-05-31T02:10:01.595Z
Learning: Dependabot now supports `uv` as a package-ecosystem in general availability, though `uv` is still in beta stage (major version 0). This is documented in GitHub issue https://github.com/dependabot/dependabot-core/issues/10478 and related threads tracking uv maturity features.

.github/workflows/docs.yml (2)

24-24: Pin looks good; consider artifact retention to save storage.

Add a short retention for doc artifacts (they’re ephemeral).

       - name: Upload docs build as artifact
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: ${{ github.event.repository.name }}_docs
           path: ${{ github.workspace }}/${{ env.path_to_doc }}
+          retention-days: 7

---

32-32: Pin is solid; ensure GITHUB_TOKEN has write perms for gh-pages push.

If repo defaults are read-only, this step will fail. Recommend explicit permissions.

 jobs:
   build-docs:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write  # required by peaceiris/actions-gh-pages to push to gh-pages
     env:
       path_to_doc: docs/_build/html

Optional: add concurrency to avoid overlapping publishes.

   build-docs:
+    concurrency:
+      group: docs-${{ github.ref }}
+      cancel-in-progress: true

If you prefer least-privilege, split deploy into a second job with permissions: contents: write and keep build as contents: read.

.github/workflows/release.yml (7)

21-25: Be explicit about fetching tags for setuptools_scm.

fetch-depth: 0 usually brings full history, but being explicit about tags avoids edge cases where tags aren’t present and setuptools_scm can't compute a version.

       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 #v5.0.0
         # use fetch --all for setuptools_scm to work
         with:
           fetch-depth: 0
+          fetch-tags: true

---

29-35: Avoid relying on pipx availability on runners.

pipx is not guaranteed across all runners. Prefer python -m build and install tools explicitly for stability.

-      - name: Build distributions
-        run: pipx run build -o dist
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+      - name: Build distributions
+        run: python -m build -o dist

---

31-36: Artifact name is misleading.

You’re uploading both sdists and wheels, but naming the artifact “wheels”. Rename to “dist” for clarity.

-      - name: Upload builds as artifacts
+      - name: Upload distributions as artifacts
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           path: dist
-          name: wheels
+          name: dist

Note: Update the download step accordingly (see next comment).

---

41-46: Keep artifact name consistent with the upload step.

If you rename the artifact to “dist”, update the consumer step.

       - name: Download distributions
         uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
-          name: wheels
+          name: dist
           path: dist

---

51-56: Preflight twine check on tag builds and make re-runs idempotent.

Running twine check for tag refs helps catch metadata issues before publish. Also consider skip-existing: true to allow safe re-runs on the same tag.

       - name: Check distributions
-        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
         run: pipx run twine check dist/*
+      - name: Check distributions (tag)
+        if: startsWith(github.ref, 'refs/tags/')
+        run: pipx run twine check dist/*
       - name: Deploy to PyPI
         if: startsWith(github.ref, 'refs/tags/')
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          skip-existing: true

If you adopt the earlier “no pipx” change, replace the twine check invocations with python -m twine check and add python -m pip install --upgrade twine alongside build tooling.

---

1-2: Header comment is out of sync with triggers.

Comment says “when a release is created,” but the workflow runs on pushes (branches and tags) and manual dispatch. Update to avoid confusion.

-# This workflow will upload a Python Package using Twine when a release is created
+# This workflow builds on every push (main and v* tags); tag pushes publish to PyPI.

---

55-56: Confirm publishing method (OIDC vs token).

If you’re not using PyPI Trusted Publishing, pass the API token instead of OIDC. Otherwise, the earlier permissions change is sufficient.

Option for token-based publishing:

       - name: Deploy to PyPI
         if: startsWith(github.ref, 'refs/tags/')
         uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

Would you like me to open a follow-up PR snippet with either OIDC (preferred) or token wiring based on your PyPI setup?

.github/workflows/tests.yml (3)

28-29: Matrix bump to clang 21: verify toolchain availability across runners.

LLVM 21 may not be present on all GitHub-hosted images yet. Please verify that:

• apt.llvm.org (for Ubuntu 24.04 behind ubuntu-latest) provides clang-format-21/clang-tidy-21
• clang-tools --install 21 succeeds on both Linux and Windows runners

If 21 is still rolling out, consider temporarily allowing it to be “experimental” to avoid blocking PRs.

Proposed tweak (make 21 non-blocking until confirmed stable):

   strategy:
     fail-fast: false
     matrix:
       os: ['windows-latest', ubuntu-latest]
-      version: ['21', '20', '19', '18', '17', '16', '15', '14', '13', '12', '11', '10', '9']
+      version: ['21', '20', '19', '18', '17', '16', '15', '14', '13', '12', '11', '10', '9']
+      experimental: [false]
+      include:
+        - version: '21'
+          experimental: true
+  continue-on-error: ${{ matrix.experimental }}

For consistency, also quote ubuntu-latest:

-        os: ['windows-latest', ubuntu-latest]
+        os: ['windows-latest', 'ubuntu-latest']

---

98-101: Avoid mixing expression interpolation inside Python.

Using ${{ matrix.version }} inside Python produces generated code like “if 21 == 21:” which is brittle. A small bash step is simpler and safer.

Apply:

-      - name: Is clang-only tests?
-        id: clang-dep
-        shell: python
-        run: |-
-          from os import environ
-          with open(environ["GITHUB_OUTPUT"], mode="a") as gh_out:
-            if ${{ matrix.version }} == 21:
-                gh_out.write("args=\n")
-            else:
-                gh_out.write("args=-m \"not no_clang\"\n")
+      - name: Is clang-only tests?
+        id: clang-dep
+        shell: bash
+        run: |
+          if [ "${{ matrix.version }}" = "21" ]; then
+            echo "args=" >> "$GITHUB_OUTPUT"
+          else
+            echo 'args=-m "not no_clang"' >> "$GITHUB_OUTPUT"
+          fi

---

1-3: Optional: lock down default token permissions and job timeouts.

Reduce blast radius and prevent hangs.

Apply near the top:

 name: Build and Test
+
+permissions:
+  contents: read

And per job:

 jobs:
   test:
+    timeout-minutes: 45
   coverage-report:
+    timeout-minutes: 20

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#143
File: .github/dependabot.yml:16-23
Timestamp: 2025-05-31T02:10:01.595Z
Learning: Dependabot now supports `uv` as a package-ecosystem in general availability, though `uv` is still in beta stage (major version 0). This is documented in GitHub issue https://github.com/dependabot/dependabot-core/issues/10478 and related threads tracking uv maturity features.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#143
File: .github/dependabot.yml:16-23
Timestamp: 2025-05-31T02:10:01.595Z
Learning: As of March 13, 2025, Dependabot officially supports `uv` as a package-ecosystem in general availability. Prior to this date, `uv` was not supported by Dependabot. The configuration `package-ecosystem: uv` is now valid and will enable automated dependency updates for uv.lock files.

.github/workflows/tests.yml (1)

37-37: Resolved: checkout pinned in test job.

This addresses the earlier supply‑chain hardening comment. Thanks for pinning.

.github/workflows/tests.yml (3)

28-29: Matrix tweaks look fine; minor consistency nit.

Mixing quoted and unquoted values in the same list is valid YAML but a bit noisy. Consider quoting both OS entries for consistency.

-        os: ['windows-latest', ubuntu-latest]
+        os: ['windows-latest', 'ubuntu-latest']

---

98-101: Prefer shell-based output over Python interpolation for simplicity and robustness.

Embedding ${{ matrix.version }} inside Python is a bit brittle. Bash keeps it simpler and avoids type/quoting surprises while writing to $GITHUB_OUTPUT.

-      - name: Is clang-only tests?
-        id: clang-dep
-        shell: python
-        run: |-
-          from os import environ
-          with open(environ["GITHUB_OUTPUT"], mode="a") as gh_out:
-            if ${{ matrix.version }} == 21:
-                gh_out.write("args=\n")
-            else:
-                gh_out.write("args=-m \"not no_clang\"\n")
+      - name: Is clang-only tests?
+        id: clang-dep
+        shell: bash
+        run: |
+          if [[ "${{ matrix.version }}" == "21" ]]; then
+            echo "args=" >> "$GITHUB_OUTPUT"
+          else
+            echo 'args=-m "not no_clang"' >> "$GITHUB_OUTPUT"
+          fi

---

118-118: Optional: pin Ubuntu runner to an LTS for stability.

ubuntu-latest can shift images and break toolchains unexpectedly. If you value determinism, consider ubuntu-22.04 (or 24.04) here and in the matrix.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#143
File: .github/dependabot.yml:16-23
Timestamp: 2025-05-31T02:10:01.595Z
Learning: Dependabot now supports `uv` as a package-ecosystem in general availability, though `uv` is still in beta stage (major version 0). This is documented in GitHub issue https://github.com/dependabot/dependabot-core/issues/10478 and related threads tracking uv maturity features.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#143
File: .github/dependabot.yml:16-23
Timestamp: 2025-05-31T02:10:01.595Z
Learning: As of March 13, 2025, Dependabot officially supports `uv` as a package-ecosystem in general availability. Prior to this date, `uv` was not supported by Dependabot. The configuration `package-ecosystem: uv` is now valid and will enable automated dependency updates for uv.lock files.

.github/workflows/labeler.yml (1)

9-13: Minor naming nit: job id “draft-release” under “PR Autolabeler” can confuse.

Consider renaming the job to reflect its PR-labeling purpose (e.g., autolabel) for clarity.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#150
File: .github/workflows/release.yml:0-0
Timestamp: 2025-09-04T03:33:27.553Z
Learning: In GitHub workflows, `contents: read` permissions can be controlled via repository settings for `github.token` access rather than explicitly defining it in the workflow permissions block, as preferred by user 2bndy5.

.github/workflows/labeler.yml (2)

10-12: Reduce to least-privilege permissions

Autolabeling needs pull-requests: write; contents: write is unnecessary. Prefer contents: read to limit the GITHUB_TOKEN scope. If the reusable workflow doesn’t require repo writes, this is safer.

Apply:

 permissions:
-  contents: write
+  contents: read
   pull-requests: write

Note: Per your stated preference to manage token scopes via repo settings, you could also drop this block entirely if the repo default grants pull-requests: write to workflows (verify first).

---

9-9: Nit: rename job for clarity

Job id draft-release is misleading in an autolabeler workflow. Consider autolabel or similar.

-jobs:
-  draft-release:
+jobs:
+  autolabel:

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: 2bndy5
PR: cpp-linter/cpp-linter#150
File: .github/workflows/release.yml:0-0
Timestamp: 2025-09-04T03:33:27.553Z
Learning: In GitHub workflows, `contents: read` permissions can be controlled via repository settings for `github.token` access rather than explicitly defining it in the workflow permissions block, as preferred by user 2bndy5.