Skip to content
Shape

Diagnostics and Provenance

Diagnostics are a primary product surface for Shape.

Diagnostic causal trail diagram showing function claim, effect, resource, trait, constraint, provenance, and source evidence.

A useful diagnostic should show the causal path:

function emits effect
effect targets resource
resource has trait
trait derives forbidden effect
component cannot contain function

Example

Section titled “Example”

The hard-delete fixture fails because the function emits an effect that the resource trait forbids:

error: forbidden effect


AuditStore.purgeOldEvents emits:
  HardDelete<AuditEvent>


But:
  AuditEvent has trait AppendOnly
  AppendOnly forbids final HardDelete<AuditEvent>

Provenance

Section titled “Provenance”

Shape keeps the declarations that caused a violation close to the diagnostic. Evidence refs make the final step reviewable:

HardDelete<AuditEvent>
  evidence ts("src/audit/purge.ts:12-16")

The diagnostic should lead the reviewer from the failed function to the source span behind the claim.