pruneguard 0.2.1 → 0.3.1

package/review_report_schema.json

@@ -0,0 +1,624 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewReport",
+  "description": "Branch review report for CI/agent branch gating.",
+  "type": "object",
+  "required": [
+    "advisoryFindings",
+    "blockingFindings",
+    "changedFiles",
+    "newFindings",
+    "trust"
+  ],
+  "properties": {
+    "advisoryFindings": {
+      "description": "Findings that are advisory (medium/low confidence, or info severity).",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Finding"
+      }
+    },
+    "baseRef": {
+      "description": "Base ref used for comparison.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "blockingFindings": {
+      "description": "Findings that should block merge (high confidence errors/warnings).",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Finding"
+      }
+    },
+    "changedFiles": {
+      "description": "Files changed on this branch.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "compatibilityWarnings": {
+      "description": "Compatibility warnings from framework detection.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "executionMode": {
+      "description": "Execution mode used for this review.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ExecutionMode"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "latencyMs": {
+      "description": "Wall-clock latency in milliseconds.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "newFindings": {
+      "description": "All new findings introduced on this branch.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Finding"
+      }
+    },
+    "proposedActions": {
+      "description": "Proposed remediation actions for blocking findings.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/RemediationAction"
+      }
+    },
+    "recommendations": {
+      "description": "Concise recommendations for the branch author.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "recommendedActions": {
+      "description": "Machine-readable recommended next actions for agents.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/RecommendedAction"
+      }
+    },
+    "strictTrustApplied": {
+      "description": "Whether strict trust mode was applied.",
+      "default": false,
+      "type": "boolean"
+    },
+    "trust": {
+      "description": "Trust summary for this review.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/ReviewTrust"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "ConfidenceCounts": {
+      "type": "object",
+      "required": [
+        "high",
+        "low",
+        "medium"
+      ],
+      "properties": {
+        "high": {
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "low": {
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "medium": {
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        }
+      }
+    },
+    "Evidence": {
+      "description": "Evidence supporting a finding.",
+      "type": "object",
+      "required": [
+        "description",
+        "kind"
+      ],
+      "properties": {
+        "description": {
+          "description": "Description of this evidence.",
+          "type": "string"
+        },
+        "file": {
+          "description": "File path involved.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "kind": {
+          "description": "Type of evidence.",
+          "type": "string"
+        },
+        "line": {
+          "description": "Line number, if applicable.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 0.0
+        }
+      }
+    },
+    "ExecutionMode": {
+      "description": "Execution mode for daemon/oneshot distinction.",
+      "type": "string",
+      "enum": [
+        "oneshot",
+        "daemon"
+      ]
+    },
+    "Finding": {
+      "description": "A single finding from analysis.",
+      "type": "object",
+      "required": [
+        "category",
+        "code",
+        "confidence",
+        "id",
+        "message",
+        "severity",
+        "subject"
+      ],
+      "properties": {
+        "actionKinds": {
+          "description": "All applicable remediation action kinds.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RemediationActionKind"
+          }
+        },
+        "category": {
+          "description": "Category of the finding.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/FindingCategory"
+            }
+          ]
+        },
+        "code": {
+          "description": "Machine-readable code (e.g. `unused-export`, `cycle`, `boundary-violation`).",
+          "type": "string"
+        },
+        "confidence": {
+          "description": "Confidence level for this finding.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/FindingConfidence"
+            }
+          ]
+        },
+        "evidence": {
+          "description": "Evidence supporting the finding.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Evidence"
+          }
+        },
+        "frameworkContext": {
+          "description": "Framework context relevant to this finding.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "id": {
+          "description": "Stable deterministic ID for this finding.",
+          "type": "string"
+        },
+        "message": {
+          "description": "Human-readable message.",
+          "type": "string"
+        },
+        "package": {
+          "description": "Package this finding belongs to, if applicable.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "primaryActionKind": {
+          "description": "Primary remediation action kind for this finding.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/RemediationActionKind"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "ruleName": {
+          "description": "Name of the rule that produced this finding, if any.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "severity": {
+          "description": "Severity level.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/FindingSeverity"
+            }
+          ]
+        },
+        "subject": {
+          "description": "The subject of the finding (file path, export name, etc.).",
+          "type": "string"
+        },
+        "suggestion": {
+          "description": "Suggested fix.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "trustNotes": {
+          "description": "Trust-related notes for this finding.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "workspace": {
+          "description": "Workspace this finding belongs to, if applicable.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "FindingCategory": {
+      "type": "string",
+      "enum": [
+        "unused-export",
+        "unused-file",
+        "unused-package",
+        "unused-dependency",
+        "cycle",
+        "boundary-violation",
+        "ownership-violation",
+        "impact"
+      ]
+    },
+    "FindingConfidence": {
+      "type": "string",
+      "enum": [
+        "high",
+        "medium",
+        "low"
+      ]
+    },
+    "FindingSeverity": {
+      "type": "string",
+      "enum": [
+        "error",
+        "warn",
+        "info"
+      ]
+    },
+    "RecommendedAction": {
+      "description": "A machine-readable recommended next action for an AI agent or CI system.",
+      "type": "object",
+      "required": [
+        "description",
+        "kind",
+        "priority"
+      ],
+      "properties": {
+        "command": {
+          "description": "The pruneguard command to run, if applicable.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "description": "Human-readable description of what to do.",
+          "type": "string"
+        },
+        "kind": {
+          "description": "Machine-readable action kind.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/RecommendedActionKind"
+            }
+          ]
+        },
+        "priority": {
+          "description": "Priority rank (1 = most important).",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "targets": {
+          "description": "Targets this action applies to.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "RecommendedActionKind": {
+      "description": "Kind of recommended next action.",
+      "oneOf": [
+        {
+          "description": "Run safe-delete on identified targets.",
+          "type": "string",
+          "enum": [
+            "run-safe-delete"
+          ]
+        },
+        {
+          "description": "Run fix-plan for specific findings.",
+          "type": "string",
+          "enum": [
+            "run-fix-plan"
+          ]
+        },
+        {
+          "description": "Resolve blocking findings before merge.",
+          "type": "string",
+          "enum": [
+            "resolve-blocking"
+          ]
+        },
+        {
+          "description": "Investigate unresolved specifier pressure.",
+          "type": "string",
+          "enum": [
+            "fix-resolver-config"
+          ]
+        },
+        {
+          "description": "Review advisory findings.",
+          "type": "string",
+          "enum": [
+            "review-advisory"
+          ]
+        },
+        {
+          "description": "Run a full-scope scan for higher confidence.",
+          "type": "string",
+          "enum": [
+            "run-full-scope"
+          ]
+        },
+        {
+          "description": "Branch is clean; no action required.",
+          "type": "string",
+          "enum": [
+            "none"
+          ]
+        }
+      ]
+    },
+    "RemediationAction": {
+      "description": "A remediation action describing how to fix one or more findings.",
+      "type": "object",
+      "required": [
+        "confidence",
+        "id",
+        "kind",
+        "risk",
+        "targets",
+        "why"
+      ],
+      "properties": {
+        "confidence": {
+          "description": "Confidence in this action's correctness.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/FindingConfidence"
+            }
+          ]
+        },
+        "findingIds": {
+          "description": "IDs of findings this action addresses.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "id": {
+          "description": "Unique identifier for this action.",
+          "type": "string"
+        },
+        "kind": {
+          "description": "The kind of remediation to perform.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/RemediationActionKind"
+            }
+          ]
+        },
+        "phase": {
+          "description": "Phase this action belongs to (dead-code, architecture, governance).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "preconditions": {
+          "description": "Conditions that must be true before this action can be applied.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rank": {
+          "description": "Ranking position within the plan (1-based, lower = do first).",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "risk": {
+          "description": "Risk level of this action.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/RiskLevel"
+            }
+          ]
+        },
+        "steps": {
+          "description": "Ordered steps to execute.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RemediationStep"
+          }
+        },
+        "targets": {
+          "description": "Files or exports this action targets.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "verification": {
+          "description": "Verification commands to run after applying the action.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "why": {
+          "description": "Human-readable rationale explaining why this action is needed.",
+          "type": "string"
+        }
+      }
+    },
+    "RemediationActionKind": {
+      "description": "The kind of remediation action to take.",
+      "type": "string",
+      "enum": [
+        "delete-file",
+        "delete-export",
+        "remove-dependency",
+        "break-cycle",
+        "move-import",
+        "tighten-entrypoint",
+        "update-boundary-rule",
+        "assign-owner",
+        "split-package",
+        "acknowledge-baseline"
+      ]
+    },
+    "RemediationStep": {
+      "description": "A single step in a remediation action.",
+      "type": "object",
+      "required": [
+        "description"
+      ],
+      "properties": {
+        "action": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": "string"
+        },
+        "file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "ReviewTrust": {
+      "description": "Trust summary within a review report.",
+      "type": "object",
+      "required": [
+        "baselineApplied",
+        "confidenceCounts",
+        "fullScope",
+        "unresolvedPressure"
+      ],
+      "properties": {
+        "baselineApplied": {
+          "description": "Whether a baseline was applied.",
+          "type": "boolean"
+        },
+        "confidenceCounts": {
+          "description": "Confidence counts for new findings.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ConfidenceCounts"
+            }
+          ]
+        },
+        "executionMode": {
+          "description": "Execution mode used for this analysis.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ExecutionMode"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "fullScope": {
+          "description": "Whether full-scope analysis was performed.",
+          "type": "boolean"
+        },
+        "unresolvedPressure": {
+          "description": "Unresolved specifier pressure ratio.",
+          "type": "number",
+          "format": "double"
+        }
+      }
+    },
+    "RiskLevel": {
+      "description": "Risk level for a remediation action or fix plan.",
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    }
+  }
+}