testguard-cli 0.5.0 → 0.7.0

package/spec/schemas/claims.schema.json

@@ -1,27 +1,43 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:guard-spec:v1:claims",
-  "title": "Guard spec v1 — claims file",
+  "$id": "urn:claimspec:v1:claims",
+  "title": "claimspec v1 \u2014 claims file",
   "description": "What must be true, and how to try to falsify it. A claim is a statement the project makes; each fault is one concrete way that statement could be false, expressed as a deterministic source change. This file is code: its `replace` strings execute under the test runner. Treat it with the same review discipline as source.",
   "type": "object",
-  "required": ["schemaVersion", "claims"],
+  "required": [
+    "schemaVersion",
+    "claims"
+  ],
   "properties": {
-    "$schema": { "type": "string" },
-    "schemaVersion": { "const": 1 },
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
     "claims": {
       "type": "array",
-      "items": { "$ref": "#/$defs/claim" }
+      "items": {
+        "$ref": "#/$defs/claim"
+      }
     }
   },
   "additionalProperties": false,
   "$defs": {
     "claim": {
       "type": "object",
-      "required": ["id", "statement", "source", "severity", "producedBy", "faults"],
+      "required": [
+        "id",
+        "statement",
+        "source",
+        "severity",
+        "producedBy",
+        "faults"
+      ],
       "properties": {
         "id": {
           "description": "Stable identifier. Renaming it changes every fingerprint derived from it.",
-          "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+          "$ref": "urn:claimspec:v1:common#/$defs/identifier"
         },
         "statement": {
           "description": "The claim in plain language, as the project states it.",
@@ -32,46 +48,82 @@
         "source": {
           "description": "Where the claim comes from. Spec- and ADR-sourced claims are human-governed; annotation- and comment-sourced claims may have been written by the same agent that wrote the tests, and should be ranked accordingly.",
           "type": "object",
-          "required": ["kind"],
+          "required": [
+            "kind"
+          ],
           "properties": {
-            "kind": { "enum": ["spec", "adr", "annotation", "comment", "manual"] },
-            "ref": { "type": "string", "maxLength": 512 }
+            "kind": {
+              "enum": [
+                "spec",
+                "adr",
+                "annotation",
+                "comment",
+                "manual"
+              ]
+            },
+            "ref": {
+              "type": "string",
+              "maxLength": 512
+            }
           },
           "additionalProperties": false
         },
-        "severity": { "$ref": "urn:guard-spec:v1:common#/$defs/severity" },
-        "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" },
+        "severity": {
+          "$ref": "urn:claimspec:v1:common#/$defs/severity"
+        },
+        "producedBy": {
+          "$ref": "urn:claimspec:v1:common#/$defs/provenance"
+        },
         "defendedBy": {
           "description": "Globs (project-relative) for the test files that supposedly defend this claim. Empty or absent means: discover defenders as the test files that import each fault's target file (relative paths and resolved aliases). If nothing resolves, the verdict is `nocover`.",
           "type": "array",
-          "items": { "type": "string", "minLength": 1 },
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
           "uniqueItems": true
         },
         "faults": {
           "type": "array",
           "minItems": 1,
-          "items": { "$ref": "#/$defs/fault" }
+          "items": {
+            "$ref": "#/$defs/fault"
+          }
         },
         "tags": {
           "type": "array",
-          "items": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+          "items": {
+            "$ref": "urn:claimspec:v1:common#/$defs/identifier"
+          },
           "uniqueItems": true
         }
       },
       "additionalProperties": false
     },
     "fault": {
-      "description": "One concrete way the claim could be false. Applied as an exact-string substitution; the schema is producer-agnostic — a human, an operator, an agent, or a derivation may all emit this shape.",
+      "description": "One concrete way the claim could be false, and how a tool would try to make it so. `method` says which; it defaults to `fault-injection`, whose shape is an exact-string substitution and is unchanged. Producer-agnostic: a human, an operator, an agent or a derivation may all emit this shape, and every artifact says which.",
       "type": "object",
-      "required": ["id", "description", "faultClass", "file", "find", "replace", "producedBy"],
+      "required": [
+        "id",
+        "description",
+        "producedBy"
+      ],
       "properties": {
         "id": {
           "description": "Unique within the claim.",
-          "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+          "$ref": "urn:claimspec:v1:common#/$defs/identifier"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000
+        },
+        "faultClass": {
+          "$ref": "urn:claimspec:v1:common#/$defs/faultClass"
+        },
+        "file": {
+          "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
         },
-        "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
-        "faultClass": { "$ref": "urn:guard-spec:v1:common#/$defs/faultClass" },
-        "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
         "find": {
           "description": "Exact text to locate in `file`. Must occur exactly `expectHits` times or the fault is `unverifiable`.",
           "type": "string",
@@ -90,14 +142,59 @@
           "default": 1
         },
         "expectHits": {
-          "description": "How many times `find` must occur in `file`. Any other count means the anchor has rotted or is ambiguous → `unverifiable`, never a silent skip.",
+          "description": "How many times `find` must occur in `file`. Any other count means the anchor has rotted or is ambiguous \u2192 `unverifiable`, never a silent skip.",
           "type": "integer",
           "minimum": 1,
           "default": 1
         },
-        "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" }
+        "producedBy": {
+          "$ref": "urn:claimspec:v1:common#/$defs/provenance"
+        },
+        "method": {
+          "$ref": "urn:claimspec:v1:common#/$defs/method"
+        }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "anyOf": [
+              {
+                "properties": {
+                  "method": {
+                    "const": "fault-injection"
+                  }
+                },
+                "required": [
+                  "method"
+                ]
+              },
+              {
+                "not": {
+                  "required": [
+                    "method"
+                  ]
+                }
+              }
+            ]
+          },
+          "then": {
+            "$comment": "The default method. Absent `method` means fault-injection, so every claims file written before the field existed is held to exactly the same requirements as before. The property stubs are what ajv's strict mode needs to accept `required` here; the real definitions stay above.",
+            "properties": {
+              "faultClass": true,
+              "file": true,
+              "find": true,
+              "replace": true
+            },
+            "required": [
+              "faultClass",
+              "file",
+              "find",
+              "replace"
+            ]
+          }
+        }
+      ]
     }
   }
 }

package/spec/schemas/common.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:guard-spec:v1:common",
-  "title": "Guard spec v1 — shared definitions",
-  "description": "Definitions shared by every Guard-spec format. Referenced as urn:guard-spec:v1:common#/$defs/<name>.",
+  "$id": "urn:claimspec:v1:common",
+  "title": "claimspec v1 \u2014 shared definitions",
+  "description": "Definitions shared by every Guard-spec format. Referenced as urn:claimspec:v1:common#/$defs/<name>.",
   "$defs": {
     "sha256": {
       "type": "string",
@@ -28,7 +28,12 @@
       "pattern": "^(?![/\\\\])(?!\\.\\.(?:[/\\\\]|$))(?!.*[/\\\\]\\.\\.(?:[/\\\\]|$)).*$"
     },
     "severity": {
-      "enum": ["critical", "high", "medium", "low"]
+      "enum": [
+        "critical",
+        "high",
+        "medium",
+        "low"
+      ]
     },
     "verdict": {
       "description": "Closed set. Only `killed` is a pass. Every other verdict gates by default (see GATE-SEMANTICS.md). `unverifiable` covers a fault that could not be applied (anchor missing/ambiguous) and a claim whose defenders failed to load (`defenders-failed-to-load`).",
@@ -43,7 +48,7 @@
       ]
     },
     "faultClass": {
-      "description": "Taxonomy of the injected change. Required on every fault so calibration (fault class → real-bug predictiveness) can be computed later.",
+      "description": "Taxonomy of the injected change. Required on every fault so calibration (fault class \u2192 real-bug predictiveness) can be computed later. `field-dropped` = a field removed from a persisted/transmitted object, allow-list, schema or merge; `argument-swapped` = a call kept with a parameter-derived argument replaced by a trivial value; `element-removed` = a UI element no longer rendered; `handler-dropped` = an event handler no longer wired.",
       "enum": [
         "guard-removed",
         "condition-forced",
@@ -53,69 +58,166 @@
         "call-removed",
         "return-altered",
         "exception-swallowed",
+        "field-dropped",
+        "argument-swapped",
+        "element-removed",
+        "handler-dropped",
         "other"
       ]
     },
     "provenance": {
       "description": "Who or what produced an artifact. `human` = authored by a person; `agent` = proposed by an LLM agent; `operator` = emitted by a mechanical mutation operator; `derived` = computed from another artifact (e.g. a bug log).",
       "type": "object",
-      "required": ["producer"],
+      "required": [
+        "producer"
+      ],
       "properties": {
-        "producer": { "enum": ["human", "agent", "operator", "derived"] },
-        "by": { "type": "string", "maxLength": 256 },
-        "reviewedBy": { "type": "string", "maxLength": 256 },
-        "at": { "$ref": "#/$defs/isoDateTime" }
+        "producer": {
+          "enum": [
+            "human",
+            "agent",
+            "operator",
+            "derived"
+          ]
+        },
+        "by": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "reviewedBy": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "at": {
+          "$ref": "#/$defs/isoDateTime"
+        }
       },
       "additionalProperties": false
     },
     "tool": {
       "type": "object",
-      "required": ["name", "version"],
+      "required": [
+        "name",
+        "version"
+      ],
       "properties": {
-        "name": { "$ref": "#/$defs/identifier" },
-        "version": { "type": "string", "minLength": 1, "maxLength": 64 }
+        "name": {
+          "$ref": "#/$defs/identifier"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        }
       },
       "additionalProperties": false
     },
     "uncoveredFile": {
       "description": "A changed source or test file that no claim covers and no unexpired ignore entry excuses. Shared by the gate and status documents.",
       "type": "object",
-      "required": ["file", "kind", "suggestion"],
+      "required": [
+        "file",
+        "kind",
+        "suggestion"
+      ],
       "properties": {
-        "file": { "$ref": "#/$defs/repoPath" },
-        "kind": { "enum": ["source", "test"] },
+        "file": {
+          "$ref": "#/$defs/repoPath"
+        },
+        "kind": {
+          "enum": [
+            "source",
+            "test"
+          ]
+        },
         "nearestClaimId": {
-          "description": "The claim whose fault files share the longest directory prefix with this file — where to attach, not a verdict.",
+          "description": "The claim whose fault files share the longest directory prefix with this file \u2014 where to attach, not a verdict.",
           "$ref": "#/$defs/identifier"
         },
-        "suggestion": { "type": "string", "minLength": 1, "maxLength": 1024 }
+        "suggestion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        }
       },
       "additionalProperties": false
     },
     "ignoreReliance": {
       "description": "An ignore entry the gate relied on (or would have, had it not expired), with the changed files it matched.",
       "type": "object",
-      "required": ["pattern", "reason", "files"],
+      "required": [
+        "pattern",
+        "reason",
+        "files"
+      ],
       "properties": {
-        "pattern": { "type": "string", "minLength": 1, "maxLength": 512 },
-        "reason": { "type": "string", "minLength": 8, "maxLength": 2000 },
-        "expires": { "$ref": "#/$defs/isoDateTime" },
-        "files": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/repoPath" } }
+        "pattern": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 2000
+        },
+        "expires": {
+          "$ref": "#/$defs/isoDateTime"
+        },
+        "files": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/repoPath"
+          }
+        }
       },
       "additionalProperties": false
     },
     "annotation": {
       "description": "Strictly additive. An annotation never changes, suppresses, or drops a finding; it only attaches context to it.",
       "type": "object",
-      "required": ["kind", "text"],
+      "required": [
+        "kind",
+        "text"
+      ],
       "properties": {
-        "kind": { "enum": ["note", "accepted-risk", "false-positive", "tracked", "wontfix"] },
-        "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
-        "by": { "type": "string", "maxLength": 256 },
-        "at": { "$ref": "#/$defs/isoDateTime" },
-        "ref": { "type": "string", "maxLength": 512 }
+        "kind": {
+          "enum": [
+            "note",
+            "accepted-risk",
+            "false-positive",
+            "tracked",
+            "wontfix"
+          ]
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4000
+        },
+        "by": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "at": {
+          "$ref": "#/$defs/isoDateTime"
+        },
+        "ref": {
+          "type": "string",
+          "maxLength": 512
+        }
       },
       "additionalProperties": false
+    },
+    "method": {
+      "description": "How a tool tries to falsify a claim. `fault-injection` mutates source and runs the claim's defenders; it is the only method fully specified in v1, and the default when the field is absent, so every document written before this field existed stays valid. `assertion` (a claim checked by reading code, as a documentation guard does) and `scan` (a surface checked by a scanner) are RESERVED: their required fields are deliberately not specified here and will be defined by their first real consumer. Inventing them for an absent tool is the mistake that made this discriminator necessary.",
+      "enum": [
+        "fault-injection",
+        "assertion",
+        "scan"
+      ],
+      "default": "fault-injection"
     }
   }
 }