cpp-include-insight is an experimental C/C++ include impact analyzer for refactoring, pull request review, and build-time investigation.

It scans direct #include directives, builds a project include graph, and answers graph questions such as:

• why one file depends on another
• which files are affected by a header change
• whether project-local includes form cycles
• how to render include graphs for reports or Markdown

Install the latest published CLI from crates.io:

cargo install cpp-include-insight --locked

Check the installed binary:

cpp-include-insight --help

Fast mode scans source text without invoking a compiler. It uses the including file directory plus any -I flags you pass:

cpp-include-insight scan . -I include

Compilation database mode reads compile_commands.json and applies each translation unit's -iquote, -I, and project-local -isystem paths:

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cpp-include-insight scan --compile-commands build/compile_commands.json
cpp-include-insight graph --compile-commands build/compile_commands.json --format json

Write graph JSON:

cpp-include-insight graph . -I include --format json

Render a Mermaid graph from a root file:

cpp-include-insight graph src/main.cpp -I include --format mermaid --depth 3 --no-external

Inspect include relationships:

cpp-include-insight tree src/main.cpp -I include
cpp-include-insight rtree include/config.h -I include
cpp-include-insight cycles . -I include
cpp-include-insight why src/main.cpp include/config.h -I include --max-paths 5
cpp-include-insight impact include/config.h -I include

Compare include graph changes between Git revisions and render a Markdown report:

cpp-include-insight diff main...HEAD -I include
cpp-include-insight report --base main --format markdown -I include
cpp-include-insight report --base main --compile-commands build/compile_commands.json --format markdown

diff A...B compares the merge-base of A and B against B. diff A..B compares A directly against B. Git revision diffs read committed content with git archive, so uncommitted worktree changes are not included.

Run include graph checks locally or in CI:

cpp-include-insight diff main...HEAD -I include --fail-on-new-cycle
cpp-include-insight ci --base main

The ci command reads cpp-include-insight.json, .cpp-include-insight.json, or .cpp-include-insight/ci.json from the Git root, and can also load an explicit path with --config:

{
  "include_dirs": ["include"],
  "ci": {
    "fail_on_new_cycle": true,
    "fail_on_missing_include": true,
    "max_impact_delta": 3,
    "max_new_edges": 10,
    "banned_includes": [
      {
        "from": "include/public/**",
        "to": "src/private/**",
        "reason": "public headers must not include private headers"
      }
    ]
  }
}

Run include graph checks on pull requests with the bundled GitHub Action. Use fetch-depth: 0 so Git revision diffs can find the base ref and merge base.

name: Include Insight

on:
  pull_request:

permissions:
  contents: read
  # Required only when `comment: true`, so the action can create or update the
  # stable cpp-include-insight pull request report comment.
  pull-requests: write

jobs:
  include-insight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: Honahec/cpp-include-insight@v1
        with:
          build-command: cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
          compile-commands: build/compile_commands.json
          base: origin/main
          fail-on-new-cycle: true
          comment: true

Inputs:

The action requires compile-commands so pull request reports are based on the same include search paths used by the build. build-command is optional because projects generate compilation databases through different tools such as CMake, Meson, or bear -- make.

The action always writes a Markdown report and exposes it through the report-path and report outputs. When comment: true, the action creates a pull request comment containing <!-- cpp-include-insight-report --> and updates that same marked comment on reruns or force-pushes instead of posting duplicates. Add pull-requests: write only when comment: true; otherwise contents: read is enough. Missing or insufficient token permissions fail the comment step with a message that points back to this permission.

The complete example workflow lives at examples/.github/workflows/include-insight.yml.

The current scanner supports direct includes:

#include "app.h"
#include <vector>
# include "foo/bar.hpp"

It does not expand macro includes or run a full C/C++ preprocessor. Fast mode records direct textual include directives conservatively, including directives inside conditional branches. Compilation database mode stores -D and -U metadata for future conditional analysis and improves include path resolution, but conditional evaluation is still out of scope for the current MVP. Angle includes are treated as external in fast scan mode; in compilation database mode project-local angle includes can resolve through -I or project-local -isystem paths.

Run the CLI from a checkout:

cargo run -q -p cpp-include-insight -- scan . -I include
cargo run -q -p cpp-include-insight -- graph --compile-commands build/compile_commands.json --format json
cargo run -q -p cpp-include-insight -- report --base main --format markdown -I include

Run the local checks before sending changes:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo build --workspace --all-features --locked

Or use:

just check

MIT. See LICENSE.