Schema Reference
JSON output schemas for graph, metrics, policy, and health reports.
All JSON outputs share a common metadata header and are treated as a stable public API. The schema_version field is 1 and will increment on breaking changes.
{
"tool_name": "gdhealth",
"tool_version": "0.3.6",
"schema_version": 1,
...
}graph.json
Produced by gdhealth graph --format json and gdhealth health (bundle).
{
tool_name: string
tool_version: string
schema_version: 1
root: string
file_count: number
files: ProjectFile[]
edges: DependencyEdge[]
cycles: string[][] // each inner array is one cycle (list of file paths)
parser_warnings: string[]
file_communities: GraphCommunity[]
file_graph_metrics: GraphAggregateMetrics | null
entity_scan: EntityScanReport | null
}ProjectFile
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (same as path) |
path | string | Project-relative file path |
group | string | null | Group name from config, or null if ungrouped |
line_count | number | Total lines in file |
DependencyEdge
| Field | Type | Description |
|---|---|---|
from | string | Source file path |
to | string | Target file path |
kind | string | Extends, Preload, Load, ConstPreload, UnknownScriptReference |
line | number | Line number in source file |
metrics.json
Produced by gdhealth metrics --format json and gdhealth health (bundle).
{
tool_name: string
tool_version: string
schema_version: 1
root: string
files: FileMetric[]
functions: FunctionMetric[]
entities: EntityMetric[]
signal_flow: SignalFlowReport
duplication: DuplicationReport // experimental, see below
}DuplicationReport (experimental — see Stability guarantees)
| Field | Type | Description |
|---|---|---|
available | boolean | false if duplication detection was disabled or failed |
unavailable_reason | string | null | Why, when available is false |
clones | ClonePair[] | Token-kind clone matches (renamed identifiers still match) |
ClonePair
| Field | Type | Description |
|---|---|---|
file_a / file_b | string | The two files involved |
start_line_a / start_line_b | number | Start line of the matching block in each file |
token_count | number | Size of the matching token window ([duplication].min_token_window) |
FileMetric
| Field | Type | Description |
|---|---|---|
file | string | Project-relative file path |
line_count | number | Total lines |
function_count | number | Total functions/methods |
number_of_methods | number | Alias for function_count (method context) |
signal_count | number | Number of signal declarations |
signal_emit_count | number | File-local emits resolved to a declared signal |
signal_connection_count | number | File-local connections resolved to a declared signal |
unresolved_signal_reference_count | number | Signal interactions whose ownership cannot be proven in this file |
public_function_count | number | Functions without leading _ |
outgoing_dependency_count | number | Fan-out: files this file depends on |
incoming_dependency_count | number | Fan-in: files that depend on this file |
cycle_count | number | Number of cycles this file participates in |
ws_complexity | number | Weighted sum complexity across all functions |
tfidf | number | TF-IDF score (vocabulary uniqueness) |
louvain_modularity | number | Community cluster ID (Louvain algorithm) |
file_hotspot_score | number | Composite hotspot ranking score |
SignalFlowReport is contextual data only and does not affect hotspot scores or policy findings. It contains available, path-sorted files, and path/line/operation-sorted unresolved_references. Each file entry provides its declarations plus emit, connection, and unresolved counts. An unresolved reference includes file, line, operation (emit or connect), and optional signal and receiver text.
FunctionMetric
| Field | Type | Description |
|---|---|---|
file | string | File containing this function |
function_name | string | Function name; <property>.set / <property>.get for a property accessor |
start_line | number | Line of the func keyword (or of set/get) |
end_line | number | Last line of code in the function |
line_count | number | end_line - start_line + 1 |
branch_count | number | Decisions: if, elif, while, for, and/or, ternaries, when guards, non-catch-all match patterns |
cyclomatic_estimate | number | 1 + branch_count |
max_nesting_depth | number | Deepest nesting of if/for/while/match blocks |
parameter_count | number | Number of parameters |
hotspot_score | number | cyclomatic × nesting × params × lines |
policy.json
Produced by gdhealth policy --format json and gdhealth health (bundle).
{
tool_name: string
tool_version: string
schema_version: 1
root: string
findings: PolicyFinding[]
}PolicyFinding
| Field | Type | Description |
|---|---|---|
rule_id | string | See rule IDs in Interpreting Reports |
severity | string | info, warning, or critical |
message | string | Human-readable description of the finding |
file | string | null | Primary file involved, if applicable |
line | number | null | Line number in the file, if applicable |
related_files | string[] | All files involved (e.g. both ends of a forbidden dependency) |
suggested_fix | RefactorSuggestion | absent | Present only on cycle_detected and split-file-candidate findings gated to a concrete fix. Experimental. |
Findings are sorted: critical first, then by file path, then by line.
RefactorSuggestion (experimental — see Stability guarantees)
Tagged union on a kind field:
{ kind: "BreakCycle", cut_edges: [string, string][] }
{ kind: "SplitFile", proposed_groups: string[][], modularity: number }health.json
Produced by gdhealth health. The primary integration surface for gdsuite and automation.
{
tool_name: string
tool_version: string
schema_version: 1
summary: HealthSummary
top_files: FileMetric[] // top 10 by hotspot score
top_functions: FunctionMetric[] // top 10 by hotspot score
cycles: string[][]
policy_findings: PolicyFinding[]
cross_group_dependencies: string[] // human-readable edge descriptions
git_available: boolean
git_unavailable_reason: string | null
git_shallow_repository: boolean
repo_bus_factor: number
top_churn_files: GitFileStats[] // top 10 by temporal hotspot score, experimental
top_co_changes: CoChangePair[] // top 10 by weight, experimental
}HealthSummary
| Field | Type | Description |
|---|---|---|
file_count | number | Total files discovered |
edge_count | number | Total dependency edges |
policy_finding_count | number | Total findings (all severities) |
signal_declaration_count | number | Total local signal declarations |
signal_emit_count | number | Total resolved local signal emits |
signal_connection_count | number | Total resolved local signal connections |
unresolved_signal_reference_count | number | Total unresolved signal interactions |
GitFileStats (experimental — see Stability guarantees)
| Field | Type | Description |
|---|---|---|
file | string | Project-relative file path |
commit_count_total / commit_count_90d / commit_count_30d | number | Commit counts touching this file |
lines_added_90d / lines_deleted_90d | number | Churn in the last 90 days |
temporal_hotspot_score | number | Recency-decayed churn score |
change_entropy | number | Hassan's HCM — how scattered the file's co-commits are |
prior_defect_count | number | Fix-shaped commits touching this file within the configured window |
ownership | {author_email, share}[] | Blame-derived line-share per author, sorted descending |
churn_percentile | number | 0-1, this file's rank among all scored files |
is_churn_hotspot | boolean | Top quartile by churn and meets an absolute activity floor |
CoChangePair: { file_a, file_b, weight } — two files that tend to change together, weight decayed by commit age.
gdhealth risk output
Not part of the health bundle — a standalone command, see CLI Reference.
{
score: number // 0-10
level: string // "low" | "moderate" | "high"
factors: RiskFactor[]
ref_label: string
reference_commit_count: number
method_note: string
}RiskFactor: { feature, value: number | null, percentile: number | null, contribution, label }.
percentile is the feature's rank within the recent repository history; value and percentile are
null when a feature (currently only author experience) is unavailable for the change.
gdhealth validate-defects output
Also standalone, not part of the health bundle.
{
available: boolean
reason: string | null // set when available is false
scored_file_count: number
defect_file_count: number
bottom_k: number
hits: number
precision: number
base_rate: number
lift: number
}Stability guarantees
All fields listed above are stable as of schema version 1. They will not be removed or renamed without a schema version bump.
Fields inside entity_scan and file_graph_metrics in graph.json, duplication in metrics.json,
suggested_fix/RefactorSuggestion on policy findings, and top_churn_files/top_co_changes/GitFileStats/CoChangePair
in health.json are available but not yet committed to as a stable API surface — treat them as
internal/experimental. gdhealth risk and gdhealth validate-defects are standalone diagnostic
commands (not part of health.json) and are likewise still settling.
To detect schema changes in your automation, check schema_version at the top of each JSON file.