Phase 1: JSON contracts foundation #5
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This is a breaking change that establishes the JSON envelope structure and patterns for agent-friendly diagnostic outputs. Changes: - Add reason_codes module with 27 codes across 3 categories (operational, policy, capability) - Update DiagnosticOutput envelope (v2.0.0): - Add tool_version, generated_at, severity, partial fields - Add warnings[] and errors[] arrays with ReasonInfo - Data is now nested under 'data' field (no longer flattened) - Update all diagnostic commands (triage, locks, xid, sequences, indexes) to derive severity and convert skipped checks to warnings - Add 'pgcrate context' command for connection/server/privilege info - Add 'pgcrate capabilities' command for permission-aware feature discovery - Add --include-fixes flag to triage for structured actions - Add JSON schema files for envelope, context, capabilities, action Breaking: JSON output structure changed. Consumers must update to read from nested 'data' field and handle new envelope fields.
- Remove unused actions.rs (NextAction in triage.rs is sufficient) - Remove SkipReason, use ReasonCode directly in triage.rs - Remove unused is_retryable() from ReasonCode - Remove unused _quiet params from print_human functions - Fix SQL injection pattern in capabilities.rs (use parameterized queries) - Simplify classify_error to return ReasonCode directly - Update integration tests for new data wrapper structure
- JsonError now uses envelope structure (schema_id, schema_version, tool_version, generated_at, severity, errors[], data) matching DiagnosticOutput for consistent JSON contracts - Fix SQLSTATE 57014 disambiguation: check message for "statement timeout" before returning QueryCancelled - Gate data_directory behind --no-redact flag (sensitive path info) - Remove --include-fixes flag (was no-op placeholder) - Fix indexes.rs to return Severity::Warning when findings exist - Delete unused DiagnosticError/DiagnosticErrorCode types - Add #[allow(dead_code)] to intentionally kept unused code - Update all JSON schemas to use $ref composition with envelope.schema.json instead of duplicating envelope properties - Update integration tests for new errors[] structure
- Add Diagnostics section to README with new commands - Add context, capabilities, locks, xid, sequences, indexes to Commands table - Update CI/CD section with JSON envelope example - Add Unreleased section to CHANGELOG documenting Phase 1 changes
- Fix needless_borrow warnings (remove & from client references) - Fix unneeded_struct_pattern (Commands::Triage is now unit variant) - Fix manual_strip warning (use strip_suffix instead of ends_with + slice) - Fix vec_init_then_push (use vec![] macro in capabilities.rs) - Run cargo fmt
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR establishes the JSON envelope structure and patterns for agent-friendly diagnostic outputs. It's the foundation for Phase 1 of the pgcrate roadmap.
Breaking Change: JSON output structure changed from flattened to nested
datafield. Consumers must update to read fromdataand handle new envelope fields.Key Changes
tool_version,generated_at,severity,partialfieldswarnings[]anderrors[]arrays with structured ReasonInfodatafield (no longer flattened)pgcrate context- Connection context, server info, extensions, privilegespgcrate capabilities- Permission-aware feature discovery$refcomposition withenvelope.schema.jsonReview Feedback Addressed
data_directorygated behind--no-redactflag--include-fixesflag (was no-op)indexescommand to returnSeverity::Warningwhen findings exist#[allow(dead_code)]annotationsTest plan
cargo test)cargo fmtpassescargo clippycleanpgcrate context --jsonpgcrate capabilities --jsonpgcrate triage --json(verify new envelope structure)