gdhealth

gdsuite Integration

How gdsuite health uses gdhealth as its backend and what the integration contract covers.

gdhealth is the code-health backend for the gdsuite platform. This page defines the integration contract between the two tools.

What gdsuite health invokes

gdsuite health and the health step of gdsuite check run, from the project root:

gdhealth health

gdhealth health is the canonical backend command. It produces the full report bundle in a single invocation and exposes the right exit-code semantics for CI. gdhealth reads its settings from the [health] section of gdsuite.toml (see Configuration).

To pass other subcommands or flags, put them after --; gdsuite forwards them unchanged:

gdsuite health -- health --fail-on critical
gdsuite health -- graph --format emerge-html --output graph.html

gdsuite setup and gdsuite doctor also probe the installed version and its schema version:

gdhealth --version
gdhealth --schema-version
gdhealth schema-version

What gdsuite consumes

gdsuite reads three artifacts from gdhealth health:

ArtifactUse
Exit codePass/fail signal for the gdsuite health check
reports/code-health/summary.txtHuman-readable display in the gdsuite output
reports/code-health/health.jsonMachine-readable data for aggregation and dashboards

gdsuite does not parse graph.json, metrics.json, or policy.json directly. health.json is the integration surface.

What stays gdhealth-specific

The following features are available directly via gdhealth but are not part of the gdsuite integration contract:

  • gdhealth graph --format emerge-html — interactive browser viewer
  • gdhealth graph --format dot — GraphViz export
  • gdhealth graph --format emerge-json — raw browser payload
  • gdhealth metrics — standalone metrics command
  • gdhealth policy — standalone policy command
  • gdhealth risk <revspec> — standalone commit/range defect-risk scoring (uncalibrated for GDScript)
  • gdhealth validate-defects — standalone diagnostic self-check

These are advanced workflows for users who want to go deeper than the health summary provides.

Stability guarantees for integration

  • The health.json schema is stable at version 1. Breaking changes will increment schema_version.
  • The bundle output path (reports/code-health/) is stable.
  • The summary, top_files, top_functions, cycles, policy_findings, and cross_group_dependencies fields in health.json are all stable.
  • Exit codes 0 and 1 are stable and have the semantics described in CLI Reference.
  • New in health.json: git_available, repo_bus_factor, top_churn_files, top_co_changes (git intelligence), and suggested_fix on policy_findings entries (refactoring suggestions). These are additive and available but not yet part of the stable integration contract — gdsuite does not need to change to keep working, but should not build hard dependencies on their exact shape yet. Same posture entity_scan had when it was introduced.
  • metrics.json's new duplication field is likewise additive/experimental and outside the gdsuite contract (gdsuite doesn't read metrics.json at all, per the "what gdsuite consumes" section above).

Upgrading

When gdhealth releases a new schema version:

  • The old schema version will be documented in this page alongside the new one
  • gdsuite will pin to a minimum compatible gdhealth version
  • The schema_version field at the top of each JSON file allows consumers to detect and handle version differences