gdhealth

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

FieldTypeDescription
idstringUnique identifier (same as path)
pathstringProject-relative file path
groupstring | nullGroup name from config, or null if ungrouped
line_countnumberTotal lines in file

DependencyEdge

FieldTypeDescription
fromstringSource file path
tostringTarget file path
kindstringExtends, Preload, Load, ConstPreload, UnknownScriptReference
linenumberLine 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)

FieldTypeDescription
availablebooleanfalse if duplication detection was disabled or failed
unavailable_reasonstring | nullWhy, when available is false
clonesClonePair[]Token-kind clone matches (renamed identifiers still match)

ClonePair

FieldTypeDescription
file_a / file_bstringThe two files involved
start_line_a / start_line_bnumberStart line of the matching block in each file
token_countnumberSize of the matching token window ([duplication].min_token_window)

FileMetric

FieldTypeDescription
filestringProject-relative file path
line_countnumberTotal lines
function_countnumberTotal functions/methods
number_of_methodsnumberAlias for function_count (method context)
signal_countnumberNumber of signal declarations
signal_emit_countnumberFile-local emits resolved to a declared signal
signal_connection_countnumberFile-local connections resolved to a declared signal
unresolved_signal_reference_countnumberSignal interactions whose ownership cannot be proven in this file
public_function_countnumberFunctions without leading _
outgoing_dependency_countnumberFan-out: files this file depends on
incoming_dependency_countnumberFan-in: files that depend on this file
cycle_countnumberNumber of cycles this file participates in
ws_complexitynumberWeighted sum complexity across all functions
tfidfnumberTF-IDF score (vocabulary uniqueness)
louvain_modularitynumberCommunity cluster ID (Louvain algorithm)
file_hotspot_scorenumberComposite 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

FieldTypeDescription
filestringFile containing this function
function_namestringFunction name; <property>.set / <property>.get for a property accessor
start_linenumberLine of the func keyword (or of set/get)
end_linenumberLast line of code in the function
line_countnumberend_line - start_line + 1
branch_countnumberDecisions: if, elif, while, for, and/or, ternaries, when guards, non-catch-all match patterns
cyclomatic_estimatenumber1 + branch_count
max_nesting_depthnumberDeepest nesting of if/for/while/match blocks
parameter_countnumberNumber of parameters
hotspot_scorenumbercyclomatic × 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

FieldTypeDescription
rule_idstringSee rule IDs in Interpreting Reports
severitystringinfo, warning, or critical
messagestringHuman-readable description of the finding
filestring | nullPrimary file involved, if applicable
linenumber | nullLine number in the file, if applicable
related_filesstring[]All files involved (e.g. both ends of a forbidden dependency)
suggested_fixRefactorSuggestion | absentPresent 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

FieldTypeDescription
file_countnumberTotal files discovered
edge_countnumberTotal dependency edges
policy_finding_countnumberTotal findings (all severities)
signal_declaration_countnumberTotal local signal declarations
signal_emit_countnumberTotal resolved local signal emits
signal_connection_countnumberTotal resolved local signal connections
unresolved_signal_reference_countnumberTotal unresolved signal interactions

GitFileStats (experimental — see Stability guarantees)

FieldTypeDescription
filestringProject-relative file path
commit_count_total / commit_count_90d / commit_count_30dnumberCommit counts touching this file
lines_added_90d / lines_deleted_90dnumberChurn in the last 90 days
temporal_hotspot_scorenumberRecency-decayed churn score
change_entropynumberHassan's HCM — how scattered the file's co-commits are
prior_defect_countnumberFix-shaped commits touching this file within the configured window
ownership{author_email, share}[]Blame-derived line-share per author, sorted descending
churn_percentilenumber0-1, this file's rank among all scored files
is_churn_hotspotbooleanTop 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.