Consider turning ccccc into a custom clang-tidy check for gathering project metrics

[bartlettroscoe]

Description

This project ccccc is very attractive as a way to get extended metrics from a C++ codebase. However, ccccc lacks several key features including:

• Processing translation units in parallel
• Processing only a subset of files in the project
• Filtering output based on source location
• Line filtering
• etc.

But clang-tidy and run-clang-tidy.py supports all of that.

The idea here is to run ccccc as a specialized clang-tidy check so we can use all of the clang-tidy infrastructure. Here is a ChatGPT 5.5 Pro conversation about this:

• https://chatgpt.com/share/69fdf490-156c-83ea-a7f9-b709b13e0563

Minimally Invasive Proposal

Define a new metrics-ccccc clang-tidy check without any modifications to clang-tidy or run-clang-tidy.py:

• Define a new metrics-ccccc clang-tidy check that prints JSON output (or just writes a JSONL file) of the metrics given in the current ccccc repo in addition to those produced by readability-function-size and readability-function-cognitive-complexity.
• Build the new metrics-ccccc clang-tidy check and run it with clang-tidy as a plug-in.
• Use run-clang-tidy.py with just the metrics-ccccc check plugin and scrap the JSON output (or just let it write the the shared JSONL file)
• Implement your own deduplication of metrics in the JSON/JSONL output (which is what I am already doing in https://github.com/bartlettroscoe/cass-clang-metrics).

Here are the details on the implementation of this:

• https://chatgpt.com/s/t_69fdf53111808191a280979f407d9014

Here is how this would work with clangd to lookup additional information it has so that metrics-ccccc would not have to duplicate that:

• https://chatgpt.com/s/t_69fdf4c1f3ac8191920f37c4136d9a0b

More Invasive proposal

Extend clang-tidy and run-clang-tidy.py as follows:

• Define a structured JSON output system for special clang-tidy checks, as an alternative to text-based human-readable output
• Refactor the existing readability-function-size and readability-function-cognitive-complexity checks to expose code that computes these metrics
• Define a new metrics-ccccc clang-tidy check with JSON output that provides all of the metrics given in the current ccccc repo in addition to those produced by readability-function-size and readability-function-cognitive-complexity.

[bartlettroscoe]

Summary of the workflow to run the metrics-ccccc check with run-clang-tidy.py in parallel and then combine this with clangd information:

• https://chatgpt.com/s/t_69fdf4c1f3ac8191920f37c4136d9a0b

This looks like:

run-clang-tidy.py
  -p build
  -j N
  -checks='-*,metrics-ccccc'
        |
        v
metrics-ccccc clang-tidy check
  per translation unit:
    collect file records
    collect class records
    collect function records
    collect call-edge records
    write .metrics-ccccc/<tu>.json
        |
        v
merge_metrics_ccccc.py
  read all .metrics-ccccc/*.json
  deduplicate records
  compute project-level summaries
  select functions/classes worth enriching
        |
        v
clangd LSP client
  use file + line + column from metrics records
  call symbolInfo / callHierarchy / references / hover / definition
        |
        v
final enriched metrics report

[Jarod42]

Whereas integrating metrics into a LSP as clangd, using clang-tidy seems the wrong way.
clang-tidy would be to report too low/value metrics value.

[Jarod42]

ccccc lacks several key features including:

• Processing only a subset of files in the project
• Filtering output based on source location

For those, you might adjust your command line
There is even --exclude-directory=[path] (not mentioned in readMe.Md :/) to allow to filter-out files (from database).

• Line filtering
  Not sure what you mean here.

• Processing translation units in parallel

Indeed, processing take time. Issue with parallelism is memory limit which can be reached :-/

[bartlettroscoe]

Whereas integrating metrics into a LSP as clangd, using clang-tidy seems the wrong way. clang-tidy would be to report too low/value metrics value.

No, I just mean using clangd to provide the additional information it can already provide on top of what you need to get from the AST with LibTool code, like is provided by ccccc and clang-tidy checks. If you already have a clangd index created for your project sitting around (like if you use VS Code), it is dumb to recompute all of that stuff. We need a tool to get additional metrics not already provided by the clangd index.

Processing translation units in parallel

Indeed, processing take time. Issue with parallelism is memory limit which can be reached :-/

Parallel processing is a huge deal for a large project. For some use cases, it is the difference between being usable to being unusable.

The other big advantage of producing these metrics as a custom clang-tidy check is that existing projects that already have workflows and pipelines that are set up to use clang-tidy could just enable this extra plugin and get all of these additional metrics for "free" (as in not having to inject a new tool into their pipeline/workflows).

And if it was useful enough, we might even be able to get this added to the llvm-project repo proper as an officially supported clang-tidy check.

Update: Let me know if you are interested in this approach or not. Otherwise, I may turn Codex + GPT-5.5 xhigh on this and see what it can produce with little manual work.