Crate diagprint 

diagprint

diagprint is a Rust diagnostics lifecycle framework for carrying structured diagnostics through creation, enrichment, rendering, editor and CI integration, guarded remediation, verification, export, and telemetry.

The crate deliberately separates diagnostic data from presentation and mutation:

• Diagnostic describes what happened.
• CapturedDiagnostic pairs a diagnostic with its immutable source snapshot.
• Suggestion describes a possible resolution.
• Fixer validates and applies guarded structured edits.
• FixPlan coordinates transactional multi-file remediation.
• InteropDiagnostic is the dependency-free interoperability boundary.
• SourceCache supplies virtual and cached source text to renderers.
• DocumentationResolver resolves documentation without guessing package versions.
• DiagnosticMetadata lets typed errors supply semantic metadata.
• CompilerImporter consumes structured rustc diagnostics.
• CargoWorkspace models Cargo package/dependency metadata.
• CargoStreamImporter consumes Cargo build-message streams.

Calling a renderer never modifies source files.

Canonical identity

diagprint.canonical/v1 defines stable, schema-versioned identity for diagnostics and reports without depending on JSON field ordering or volatile runtime metadata. DiagnosticFingerprint identifies a logical diagnostic, DiagnosticDigest identifies meaningful diagnostic content, and ReportDigest identifies report content independently of insertion order. DiagnosticDelta uses those identities to classify diagnostics across reports as new, resolved, persisting, or changed while preserving duplicate diagnostic instances. DeltaPolicy evaluates those semantic differences for baseline-aware CI without making existing diagnostic debt appear newly introduced.

Canonical v1 is immutable: incompatible identity changes require a new canonicalization version rather than silently changing existing digests.

Diagnostic forensics

DiagnosticCaseFile turns a verified DiagnosticHistory into a privacy-light forensic explanation for one logical diagnostic fingerprint.

Case-file v1 reports first/last observation, current lifecycle state, contiguous active episodes, reappearances, canonical-content changes, severity increases, supporting run/report/digest evidence, and the current history-chain head.

The forensic layer is deliberately evidence-based. It does not guess root cause, source-control blame, or authorship.

DiagnosticHistory::case_file requires an exact canonical fingerprint. The diagprint why CLI additionally accepts a unique fingerprint prefix.

Git provenance

GitProvenanceRecord can bind one immutable diagnostic-history run to an exact Git commit and tree without changing history-v2 semantics.

GitProvenanceBinding::CapturedClean means diagprint observed a clean worktree around the scan. GitProvenanceBinding::UserAsserted is an explicit after-the-fact association and therefore carries weaker evidence.

Git provenance establishes repository context and temporal association. It does not establish that a commit caused a diagnostic transition.

Diagnostic intelligence

Structured suggestions can carry explanations, documentation links, structured edits, advisory follow-up commands, and an Applicability classification.

Automatic editing requires Applicability::MachineApplicable, valid non-overlapping UTF-8 edit ranges, and verification of expected source contents.

Suggested shell commands are informational only and are never executed by Fixer or FixPlan.

Transactional remediation

FixPlan supports deterministic preconditions, multi-file preparation, rollback-on-error writes, post-apply verification, verification rollback, and optional backups.

Verification is declarative and does not execute shell commands.

Virtual and cached source text

SourceCache stores named source text independently from diagnostics. SourceProvider lets parsers, bridges, and other integrations populate that cache without coupling the renderer to a specific ecosystem. SourceSnapshot captures an immutable point-in-time source view so old diagnostics can render against the exact text they were created from. SourceRevision identifies successive versions of one named source and allows snapshots to detect whether a diagnostic-time buffer is still current. Terminal rendering can prefer cached source and fall back to filesystem reads when no cached source exists.

This supports editor buffers, generated files, parser inputs, compiler virtual files, and other source text which may never exist on disk.

Source contents are not serialized into Diagnostic JSON output.

Generic interoperability

InteropDiagnostic is a dependency-free, owned diagnostic protocol for compilers, linters, parsers, language tools, and third-party adapters.

It preserves:

• severity;
• diagnostic code;
• message and help;
• notes;
• primary and secondary source labels;
• cause chains;
• documentation links;
• related diagnostics.

Custom producers can implement InteropDiagnosticSource and gain direct conversion through InteropDiagnosticSourceExt.

Automatic edits and executable commands are deliberately excluded from the generic protocol. Remediation requires stronger ecosystem-specific safety guarantees.

Cargo intelligence

CargoWorkspace consumes cargo metadata --format-version=1 output and preserves package identity, versions, workspace membership, targets, features, and resolved dependency context.

CargoStreamImporter consumes Cargo --message-format=json output and recognizes compiler diagnostics, compiler artifacts, build-script results, and build completion.

Unknown future Cargo message kinds are retained as CargoMessage::Unknown rather than rejected.

Documentation intelligence

DocumentationResolver can build package/version catalogs from Cargo.lock or CargoWorkspace.

Ambiguous package versions remain ambiguous rather than being guessed.

Ecosystem interoperability

The miette feature consumes miette’s structured diagnostic protocol, including source labels, causes, and related diagnostics.

The codespan-reporting feature resolves codespan’s file IDs and byte ranges into InteropDiagnostic before conversion to diagprint.

The ariadne feature provides a structured bridge which can emit both an Ariadne report and a diagprint InteropDiagnostic from the same source metadata without parsing rendered terminal output.

The annotate-snippets feature provides the same dual-output model for annotate-snippets reports while validating its byte-oriented source spans.

The anyhow feature preserves Anyhow context/source chains.

The tracing feature turns significant tracing events into structured diagnostics.

External adapters never need to parse another library’s pretty terminal rendering.

Compiler diagnostics

CompilerImporter consumes structured rustc JSON diagnostics directly. It preserves compiler severity, Rust error codes, source spans, notes, help, structured replacements, and applicability.

Filesystem hydration is disabled by default.

Typed errors

Application error enums and structs can implement DiagnosticMetadata to provide stable diagnostic codes, severity, help, notes, and structured suggestions.

Terminal documentation

The optional terminal-docs feature can fetch documentation and display it directly in a terminal with sanitized remote content and syntax-highlighted examples.

Themes

Theme, Style, and SeverityTheme control terminal presentation.

The optional cybercore feature maps the Cybercore semantic palette into diagprint rather than copying Cybercore color values.

Feature flags

• artifact-store — append-only artifact generations with filesystem locking.
• derive — derive DiagnosticMetadata from typed errors.
• anyhow — Anyhow context-chain integration.
• ariadne — structured Ariadne/diagprint bridge.
• annotate-snippets — structured annotate-snippets/diagprint bridge.
• miette — miette diagnostic-protocol integration.
• codespan-reporting — codespan-reporting diagnostic integration.
• tracing — structured tracing-event integration.
• compression — gzip and Zstandard report compression.
• html — HTML diagnostic and report rendering.
• cybercore — Cybercore theme-schema integration.
• terminal-docs — terminal documentation retrieval and syntax highlighting.

Generic interoperability, typed errors, compiler/Cargo ingestion, documentation resolution, and FixPlan are core features.

All optional features are disabled by default.

Re-exports

pub use interop::DiagnosticTree;

pub use interop::InteropDiagnostic;

pub use interop::InteropDiagnosticSource;

pub use interop::InteropDiagnosticSourceExt;

pub use interop::InteropLabel;

pub use render::GithubActionsDeltaRenderer;

pub use render::ReportRenderer;

pub use render::SeverityTheme;

pub use render::Style;

pub use render::Theme;

Modules

interop

Dependency-free diagnostic interoperability protocol.

project_scan

render

Structs

ArtifactDigest

SHA-256 identity of exact exported artifact bytes.

ArtifactWriter

Persists verified artifacts as create-only transactional directories.

CapsuleManifestEntry

One exact payload recorded by the capsule manifest.

CapsulePolicyDescriptor

Privacy-safe capsule-policy description stored in the manifest.

CapsuleProvenance

Deterministic producer/project provenance.

CapsuleSourceEntry

One exported source in a capsule source index.

CapsuleSourceIndex

Index describing an explicitly exported source snapshot.

CapturedDiagnostic

A diagnostic paired with the immutable source snapshot it was produced against.

CargoArtifact

CargoBuildFinished

CargoBuildScript

CargoBuildSummary

Aggregate intelligence for one Cargo build stream.

CargoCompilerDiagnostic

CargoDependency

CargoDependencyKind

CargoPackage

CargoPackageIdentity

CargoProfile

CargoStreamImporter

CargoTarget

CargoUnknownMessage

CargoWorkspace

Cause

CompilerImporter

DeltaArtifact

Portable, privacy-aware representation of a semantic diagnostic delta.

DeltaArtifactCounts

Serializable delta summary.

DeltaArtifactEntry

One portable semantic delta entry.

DeltaArtifactEvaluation

Portable CI policy and evaluation result attached to a delta artifact.

DeltaArtifactFingerprintPolicy

Serializable fingerprint policy recorded in a delta artifact.

DeltaArtifactPolicy

Serializable form of DeltaPolicy.

DeltaArtifactViolation

One machine-readable failed CI rule.

DeltaCounts

Counts diagnostic instances by delta classification.

DeltaEvaluation

Result of evaluating a DiagnosticDelta against a DeltaPolicy.

DeltaPolicy

Baseline-aware policy for evaluating a DiagnosticDelta.

DeltaViolation

One failed DeltaRule and the number of matching diagnostic instances.

Diagnostic

DiagnosticAttribute

Named structured value attached to a diagnostic.

DiagnosticCapsule

In-memory diagnostic capsule.

DiagnosticCapsuleManifest

Manifest for one diagnostic capsule.

DiagnosticCapsulePolicy

Controls privacy-sensitive capsule contents.

DiagnosticCapsuleVerification

Successful capsule verification.

DiagnosticCaseFile

Privacy-light forensic summary for one logical diagnostic fingerprint.

DiagnosticCaseRun

Evidence for one history run in which the diagnostic was actually present.

DiagnosticCleanWindow

One contiguous history interval where the fingerprint is absent.

DiagnosticDelta

Semantic comparison between a baseline and candidate diagnostic report.

DiagnosticDigest

Deterministic digest of one diagnostic’s meaningful content under diagprint.canonical/v1.

DiagnosticEpisode

One contiguous period during which a logical diagnostic was present.

DiagnosticFingerprint

Stable semantic identity for one logical diagnostic under diagprint.canonical/v1.

DiagnosticHistory

Append-only tamper-evident diagnostic history.

DiagnosticHistoryRun

One immutable persisted diagnostic state.

DiagnosticHistoryTransition

Semantic transition between two persisted history runs.

DiagnosticLineage

Cross-run history for one logical diagnostic fingerprint.

DiagnosticLineageStep

One transition in the history of a single logical diagnostic fingerprint.

DiagnosticRelationship

DiagnosticRelationshipGraph

DiagnosticRelationshipGraphBuilder

DiagnosticRelationshipNode

DiagnosticRelationshipSnapshot

DiagnosticRemediationAssessment

DiagnosticRemediationReplay

DiagnosticRemediationReplayStep

DiagnosticReport

An owned collection of structured diagnostics.

DiagnosticTimeline

Complete run-by-run forensic lifecycle for one logical fingerprint.

DiagnosticTimelineRun

One complete run in a diagnostic forensic timeline.

DocumentationLink

DocumentationResolver

Resolves documentation without silently guessing package versions.

ExportDiagnostic

External, privacy-conscious representation of a diagnostic.

ExportDocumentationLink

Sanitized documentation link.

ExportLabel

Privacy-conscious source label.

ExportPolicy

Shared privacy policy for external diagnostic serialization.

ExportPolicyDescriptor

Privacy-safe description of the export boundary.

ExportReceipt

Receipt for one exact exported artifact.

ExportSourceLocation

Privacy-conscious source location.

ExportSuggestion

Metadata-only representation of a remediation suggestion.

ExportedArtifact

Exact artifact payload plus its export receipt.

FileCheckFailure

FingerprintPolicy

Controls which stable semantic fields participate in a diagnostic fingerprint.

FixCheck

FixPlan

A transactional remediation plan composed of explicit filesystem edits, preconditions, and deterministic post-apply verification checks.

FixPlanCheck

FixPlanDescriptor

Deterministic, serializable description of one FixPlan.

FixPlanPreview

FixPlanReport

FixPreview

FixReport

Fixer

GitProvenanceRecord

Immutable Git provenance for exactly one diagnostic-history run.

HistoryDeltaCounts

Counts semantic diagnostic transitions between two history runs.

HistoryObservation

One privacy-light canonical observation of a diagnostic.

HistorySeverityCounts

Severity counts retained for one historical run.

JsonLinesSink

Newline-delimited JSON sink suitable for logs and stream processing.

Label

PersistedArtifact

Result of one committed artifact transaction.

PersistedDiagnosticCapsule

Result of one committed capsule transaction.

ReceiptEvaluation

Lightweight CI result retained in an export receipt.

RemediationEffect

Semantic diagnostic effect observed after remediation and rescanning.

RemediationEvidenceEffect

RemediationEvidenceRecord

Privacy-light evidence binding one exact successful remediation receipt to one exact adjacent transition in a verified diagnostic history.

RemediationOutcome

Result of the successful filesystem remediation transaction.

RemediationPlanReceipt

Privacy-safe identity and summary of the exact fix plan used.

RemediationReceipt

Evidence tying one exact remediation plan to before/after diagnostic state.

ReportDigest

Order-independent deterministic digest of a diagnostic report under diagprint.canonical/v1.

Reporter

ReporterBuilder

RollbackFailure

RotationPolicy

RotationState

Sensitive

A value which must be explicitly exposed before its contents are rendered.

SeverityCounts

Counts diagnostics by severity.

SinkError

SourceCache

Thread-safe shared cache of named source texts.

SourceEntry

One immutable source revision.

SourceLocation

SourceRevision

Monotonic revision of one named source.

SourceSnapshot

Immutable point-in-time view of a SourceCache.

SuggestedCommand

Suggestion

TextRange

WriterSink

Sink which renders diagnostics into an arbitrary synchronous writer.

Enums

Applicability

ArtifactEncoding

External encoding used to produce an exact artifact byte stream.

ArtifactVerificationError

Failure while checking artifact bytes against an export receipt.

ArtifactWriteError

Failure while transactionally persisting an exported artifact.

CanonicalizationError

Failure while projecting diagnostic data into a portable canonical form.

CanonicalizationVersion

Version of diagprint’s canonical identity encoding.

CapsuleEntryKind

Logical role of one capsule payload.

CargoImportError

CargoMessage

CompilerImportError

Compression

DeltaKind

Classification of one diagnostic instance between a baseline and candidate report.

DeltaRule

One CI/evaluation rule applied to a DiagnosticDelta.

DiagnosticCapsuleError

Capsule construction, persistence, or verification failure.

DiagnosticCaseStatus

Current lifecycle state of one logical diagnostic.

DiagnosticChange

One classified diagnostic instance in a DiagnosticDelta.

DiagnosticCleanWindowKind

Classification for one contiguous run window where the diagnostic is absent.

DiagnosticHistoryError

Diagnostic-history persistence or integrity failure.

DiagnosticRelationshipDirection

Direction used when traversing a diagnostic relationship graph.

DiagnosticRelationshipError

DiagnosticRelationshipEvidence

DiagnosticRelationshipEvidenceFilter

Controls whether inferred-correlation edges participate in graph traversal.

DiagnosticRelationshipKind

DiagnosticRemediationState

DiagnosticTimelineEvent

Notable lifecycle event occurring at one timeline run.

DiagnosticTimelinePhase

Presence state of one logical diagnostic in one retained history run.

DiagnosticValue

Typed value attached to a structured diagnostic attribute.

DigestAlgorithm

Hash algorithm used by canonical v1 identity values.

DocumentationError

Edit

ExportAttributes

Policy for arbitrary structured diagnostic attributes.

ExportPath

Policy for source paths in an external diagnostic export.

ExportRemediation

Policy for remediation information in an external diagnostic export.

ExportText

Policy for free-form text in an external diagnostic export.

ExportUrl

Policy for documentation URLs in an external diagnostic export.

FileCheck

A deterministic filesystem condition used as either a precondition or a post-apply verification step.

FingerprintSource

Source identity included in derived diagnostic fingerprints.

FixError

FixPlanError

GitProvenanceBinding

Evidence strength for a Git/history binding.

GitProvenanceError

LabelKind

RedactionPolicy

Explicit policy for presenting a Sensitive value.

RemediationEvidenceError

RemediationReceiptError

Failure while constructing a remediation receipt.

RemediationReplayError

RemediationStatus

Successful remediation state.

ReportStatus

Result of evaluating a diagnostic report against a failure threshold.

RotationCadence

Severity

SinkErrorKind

Constants

CANONICAL_V1_NAMESPACE

Stable canonicalization namespace used by diagprint’s first identity schema.

CAPSULE_PROVENANCE_V1_SCHEMA

Stable schema for capsule provenance metadata.

CAPSULE_SOURCE_INDEX_V1_SCHEMA

Stable schema for an exported source snapshot index.

DELTA_V1_MEDIA_TYPE

Media type used by diagprint.delta/v1 JSON artifacts.

DELTA_V1_SCHEMA

Stable schema identifier for portable diagnostic delta artifacts.

DIAGNOSTIC_CAPSULE_V1_SCHEMA

Stable schema identifier for a diagnostic capsule manifest.

DIAGNOSTIC_CASE_FILE_V1_SCHEMA

Stable schema for privacy-light diagnostic forensic case files.

DIAGNOSTIC_HISTORY_HEAD_V1_SCHEMA

Mutable head record for one append-only history directory.

DIAGNOSTIC_HISTORY_RUN_V1_SCHEMA

Original unchained diagnostic-history schema.

DIAGNOSTIC_HISTORY_RUN_V2_SCHEMA

Tamper-evident hash-chained diagnostic-history schema.

DIAGNOSTIC_LINEAGE_V1_SCHEMA

Stable schema for exported diagnostic-lineage summaries.

DIAGNOSTIC_RELATIONSHIP_GRAPH_V1_SCHEMA

DIAGNOSTIC_RELATIONSHIP_SNAPSHOT_V1_SCHEMA

DIAGNOSTIC_REMEDIATION_REPLAY_V1_SCHEMA

DIAGNOSTIC_TIMELINE_V1_SCHEMA

Stable schema for run-by-run diagnostic forensic timelines.

FIX_PLAN_DESCRIPTOR_V1_SCHEMA

Stable schema identifier for deterministic fix-plan descriptors.

GIT_PROVENANCE_V1_SCHEMA

Stable schema for Git provenance bound to one immutable diagnostic-history run.

IDENTITY_ATTRIBUTE

Reserved structured attribute understood by canonical fingerprinting.

RECEIPT_V1_SCHEMA

Stable schema identifier for export receipts.

REDACTED

Default representation for protected values.

REMEDIATION_EVIDENCE_V1_SCHEMA

REMEDIATION_RECEIPT_V1_SCHEMA

Stable schema identifier for remediation receipts.

Traits

DiagnosticErrorExt

Convenience conversion methods for typed errors carrying DiagnosticMetadata.

DiagnosticMetadata

Optional diagnostic metadata implemented by typed application errors.

DiagnosticSink

Synchronous destination for structured diagnostics.

ResultDiagnosticExt

Converts typed Result errors into native diagprint diagnostics.

SourceProvider

A type which can supply named source text to a SourceCache.

Functions

is_sensitive_key

Returns whether an attribute/key name commonly represents sensitive data.

sanitize_path

Reduces a filesystem path or source name to its final component.

sanitize_url

Removes URL user information, query parameters, and fragments.

Type Aliases

CapturedDiagnosticResult

Result type whose error is a boxed captured diagnostic.

DiagnosticResult

Result type whose error is a boxed structured diagnostic.

Result

SinkResult