Diagnostics

Diagnostics help an API author improve the contract before poor names, ambiguous behavior, unsafe operations, or invalid schemas become permanent public interfaces.

Typeship analyzes the complete Definition with deterministic rules. It does not use a hosted model to invent descriptions, examples, API behavior, or opaque scores. Each Diagnostic has a stable semantic rule ID, severity, category, affected surfaces, exact source coordinates, evidence, and a grounded authoring brief.

Findings are grouped by rule rather than exploding one repeated issue into dozens of cards. OpenAPI and GraphQL use native coordinates and source-edit guidance. In a multi-document Definition, every location names the actual source document in addition to its resolved pointer.

Remediation

When an exact OpenAPI edit can be proved from the contract, Typeship offers a reviewable patch. Repository sources can open a source pull request that edits the affected source documents; URL sources can keep the correction as a Definition overlay. Changes that require product intent remain source-edit guidance and explicitly tell an agent when to ask the API owner.

GraphQL remediation stays source-native. Typeship will not round-trip SDL through a lossy formatter or pretend OpenAPI patches apply to GraphQL.

Policy and GitHub

The default policy blocks only new correctness errors. Teams can change the threshold, evaluate the complete current Definition instead of only new findings, or record reasoned rule/location exceptions.

Diagnostics are folded into Typeship – API change review on source pull requests. Typeship does not create a redundant status. The comment separates compatibility from Diagnostics so reviewers can distinguish an intentional breaking change from an invalid or underspecified contract.

Free projects get Diagnostics across the complete Definition even though each generated Target contains only the first 25 operations.