Include Dependencies Reference

See Inspect Include Dependencies for examples and Framework Reference for shared tool behavior.

Command Interface

Mode	Arguments and options
summary	Default mode; no arguments.
tree HEADER	One source identifier; --reverse follows dependents and --max-depth N limits depth to a nonnegative value.
path SOURCE TARGET	Two source identifiers; prints a deterministic shortest internal chain or fails if none exists.
cycles	No arguments; lists strongly connected components containing cycles, including self-includes.
export	--format json|dot defaults to JSON. Optional --output NAME selects a confined report filename.
check [RULE]	Checks all configured rules or one case-sensitive name. --all also lists every affected public header.

Irrelevant options and incorrect argument counts fail before scanning. Source identifiers accept source-relative paths, paths prefixed by src/erbsland/, or unique path-component suffixes. Ambiguous and unknown identifiers fail with option context. Tree output retains directive line numbers and marks cycles, previously visited nodes, and depth limits.

Configuration

The required [Include Dependencies] section contains these settings:

Setting	Contract
Public Header Map	Text; defaults to tool/data/public_headers/header_map.txt. Must identify a valid mapping file.
Git Executable	Text; defaults to git. A trusted executable is required for named exports.
Safe Binary Directories	Required nonempty text list of absolute trusted directory roots.

Executable trust follows GitHub Workflows Reference; Git is launched only for named exports.

At least one Required Dependencies section-list entry is required. Each entry supplies a unique Name containing ASCII letters, digits, underscores, or hyphens; a source-relative Target; and optional Excluded Headers text list. Targets and exclusions must identify inventoried files and cannot contain dot components or backslashes. The checked-in definitions rule requires core/Definitions.hpp and exempts core/Namespaces.hpp. Configuration errors retain the offending value’s location.

Graph and Reports

The inventory contains regular .hpp, .tpp, and .cpp files under src/erbsland; symbolic links are skipped. Core’s C++ tokenizer identifies literal include directives outside comments and literals, including continued directive lines. Conditional branches are all included. Macro-generated include names are ignored; this graph does not run a preprocessor. Quoted includes must resolve to inventoried sources. Angle-bracket includes remain external nodes.

Public membership comes from the canonical-first publication map shared with code cleanup. Forward headers and all.hpp or all_*.hpp umbrellas receive their respective roles and are excluded from regular public-header checks. The map rejects malformed paths, unsorted source records, duplicate pairs, and empty contents while retaining aliases and merged public wrappers.

Forward and reverse adjacency are indexed once. Shortest paths use breadth-first traversal. Iterative strongly connected component analysis supports cycle reports and dependency checks. Checks use reverse reachability from each target, then propagate missing-public-header membership over the component graph to select one public insertion point per terminal affected component, including paths through private nodes.

JSON retains schema version 1: schema, summary, nodes, edges, and cycles. Internal nodes include path, role, public membership, and direct/transitive dependency/dependent counts. External node paths are wrapped in angle brackets. Edges contain source, target, one-based physical line, internal, and system. DOT retains nodes, public-header box styling, external-node dashed styling, and include-line edge labels. Exports have deterministic ordering and stdout contains only the requested serialization.

Named reports are written under temporary_data/include_dependencies. NAME must be a filename; an omitted suffix is added and a supplied suffix must match the selected format. Parent links and escapes are rejected. Before scanning or creating directories, Git must confirm that the path is untracked and ignored. Changed reports use atomic replacement. Source files are never modified by this command.

Verification

Native fixtures cover parsing, graph traversal, public scope, cyclic insertion frontiers, JSON/DOT output, diagnostics, and export safeguards. Compiled fake Git responses exercise tracking and ignore decisions without network access.