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 healthgdhealth 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.htmlgdsuite setup and gdsuite doctor also probe the installed version and its schema version:
gdhealth --version
gdhealth --schema-version
gdhealth schema-versionWhat gdsuite consumes
gdsuite reads three artifacts from gdhealth health:
| Artifact | Use |
|---|---|
| Exit code | Pass/fail signal for the gdsuite health check |
reports/code-health/summary.txt | Human-readable display in the gdsuite output |
reports/code-health/health.json | Machine-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 viewergdhealth graph --format dot— GraphViz exportgdhealth graph --format emerge-json— raw browser payloadgdhealth metrics— standalone metrics commandgdhealth policy— standalone policy commandgdhealth 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.jsonschema is stable at version 1. Breaking changes will incrementschema_version. - The bundle output path (
reports/code-health/) is stable. - The
summary,top_files,top_functions,cycles,policy_findings, andcross_group_dependenciesfields inhealth.jsonare 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), andsuggested_fixonpolicy_findingsentries (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 postureentity_scanhad when it was introduced. metrics.json's newduplicationfield is likewise additive/experimental and outside the gdsuite contract (gdsuite doesn't readmetrics.jsonat 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_versionfield at the top of each JSON file allows consumers to detect and handle version differences