Interpreting Reports
What each metric and finding means, and when to act on it.
summary.txt
For concepts, examples, action guidance, and limitations, start with Understanding Code Health. This page is the concise metric reference.
The text summary is the fastest way to get a health overview:
root: C:/Projects/my-game
files: 126
edges: 142
cycles: 1
cross-group dependencies: 79
policy findings: 91
parser warnings: 22
top files:
- player.gd (hotspot: 204, lines: 717, funcs: 36, incoming: 0, outgoing: 1, cycles: 0)
- ai/mob_ai_controller.gd (hotspot: 169, lines: 568, funcs: 33, incoming: 8, outgoing: 0, cycles: 0)
top functions:
- terrain_grid.gd::_cast_light (hotspot: 72, lines: 90, cyclomatic: 19, nesting: 4, params: 0)
cycles:
- net/network_replay_artifact.gd
policy findings:
- [critical] function_lines_threshold: terrain_grid.gd::_cast_light spans 90 lines (warn 40, critical 80)Metrics explained
Fan-in and fan-out
- fan-in (
incoming_dependency_count): how many other files depend on this file. High fan-in = high impact if you change this file. - fan-out (
outgoing_dependency_count): how many files this file depends on. High fan-out = unstable base (the file will break when any of its dependencies change).
Files with both high fan-in and high fan-out are the most costly to refactor.
Hotspot score
The file hotspot score is a composite of function complexity totals, fan-in/fan-out pressure, and cycle membership. It is not a defect count — it is a relative ranking. Files at the top of the hotspot list are your highest-leverage refactor targets.
The function hotspot score is computed as cyclomatic × nesting × params × lines. It identifies specific functions that are simultaneously complex, deeply nested, parameter-heavy, and long.
Functions
gdhealth reads each .gd file with gdsyntax, a port of Godot's own GDScript parser, so code inside strings and comments is never mistaken for code.
A function row is reported for every func, at file level and in inner classes, and for every property accessor with a body (named hp.set or hp.get). Accessors are measured, but function_count, number_of_methods and public_function_count count func declarations only. A lambda is part of the function that contains it.
A function starts on its func line (annotations on lines of their own are not included) and ends on its last line of code: trailing comments and blank lines do not count toward line_count.
Cyclomatic complexity
McCabe's count: one plus one per decision. Decisions are if, elif, while, for, each and/or (&&/||), each ternary a if c else b, each when guard, and each match pattern except a catch-all (_ or a lone var x). else and match itself are not decisions. branch_count is the number of decisions. Higher values mean more test paths and higher cognitive load.
Nesting depth
The deepest level of nested if/elif/else, for, while and match blocks inside a function, one-line blocks such as if x: return included. A lambda adds no level. Deep nesting makes control flow hard to follow and is a leading indicator of code that needs decomposition.
Weighted sum complexity (ws_complexity)
A file-level metric that sums cyclomatic_estimate × (max_nesting_depth + 1) across all functions. Used in the hotspot score calculation.
TF-IDF
Term frequency–inverse document frequency, computed over function names across the codebase. High TF-IDF means the file uses distinctive vocabulary — often utility files that are hard to share or reuse across contexts.
Cycles
A cycle is a set of files that mutually depend on each other in a loop. Cycles make it impossible to load one file independently of the others, which complicates testing and extraction.
In summary.txt, cycles list the files involved:
cycles:
- net/network_replay_artifact.gdIn health.json, cycles are arrays of file paths:
"cycles": [
["net/network_replay_artifact.gd"]
]When to act: Cycles in critical layers (net, server, ai) are reported as warning. Cycles elsewhere are info. Single-file self-cycles (a file preloading itself) can be suppressed via allow_cycles if intentional.
Parser warnings
Parser warnings are emitted when the extractor detects an ambiguous or incomplete situation:
- Duplicate
class_name— the same class name is declared in multiple files. The parser can't resolve which one a reference refers to and uses the first match. This is not an error, but it can cause confusing reference resolution. - Unresolved reference — a dependency reference couldn't be resolved to a known file. This happens for dynamic
load(variable)calls. - Syntax error — the file is not valid GDScript; the warning gives Godot's message for the first error and how many more there are. gdhealth still measures the file: the parser recovers the way Godot's editor does, and only the code it could not read is left out of the file's functions, dependencies and signals. A function whose header cannot be read may be missing from the report, so fix syntax errors before trusting that file's numbers.
Parser warnings do not cause a non-zero exit. They appear in parser_warnings in graph.json and in summary.txt.
When to act: Duplicate class names are worth fixing if they cause confusing behavior. Unresolved references are expected for dynamic loads — no action needed unless you care about completeness. Syntax errors mean Godot cannot load the script either.
Policy findings
Each finding has a rule_id, severity, message, file, and optionally line.
Rule IDs
rule_id | Triggered by |
|---|---|
forbidden_dependency | A dependency edge crosses a boundary defined in [[policy.forbidden_dependencies]] |
file_lines_threshold | A file exceeds file_lines_warn or file_lines_critical |
function_lines_threshold | A function exceeds function_lines_warn or function_lines_critical |
cyclomatic_threshold | A function's cyclomatic estimate exceeds cyclomatic_warn or cyclomatic_critical |
nesting_threshold | A function's max nesting depth exceeds nesting_warn or nesting_critical |
parameters_threshold | A function has ≥ parameters_warn parameters (always warning) |
cycle_detected | A dependency cycle was found and not suppressed by allow_cycles |
When to act vs when to ignore
Act immediately:
forbidden_dependencyatcritical— this is an architecture rule your team explicitly encodedcycle_detectedatwarning— cycles in net/server/ai layers indicate cross-layer coupling
Schedule work:
function_lines_thresholdorcyclomatic_thresholdatcritical— these functions are refactor candidates for the next sprintfile_lines_thresholdatcritical— consider whether the file should be split
Track but don't rush:
warning-severity threshold findings — keep an eye on trend; act if a file keeps climbingparameters_threshold— useful signal but lower urgency than size or cyclomatic
Suppress selectively:
- Use
allow_cyclesfor intentional self-referencing patterns - Lower or raise thresholds in
[thresholds]to match your team's standards
Cross-group dependencies
Cross-group dependencies are dependency edges that cross the group boundaries defined in [groups]. They are informational — only those matched by [[policy.forbidden_dependencies]] rules become policy findings.
Use the cross-group dependency list to spot coupling that surprises you, even if it doesn't yet violate a rule. Consider whether to encode new forbidden rules.