atdd 0.1.0__py3-none-any.whl

atdd/tester/schemas/contract.schema.json

@@ -0,0 +1,591 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://wagons.dev/schemas/tester/contract.schema.json",
+  "title": "Contract Schema Meta-Schema",
+  "description": "Meta-schema that validates the common structure of all contract schemas. Enforces required fields and x-artifact-metadata structure, but allows flexible content (properties vs patternProperties).",
+  "type": "object",
+  "required": [
+    "$schema",
+    "$id",
+    "title",
+    "description",
+    "type",
+    "version",
+    "x-artifact-metadata"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "http://json-schema.org/draft-07/schema#",
+      "description": "Must use JSON Schema Draft-07"
+    },
+    "$id": {
+      "type": "string",
+      "pattern": "^([a-z][a-z0-9\\-]*:)+[a-z][a-z0-9\\-.]*$",
+      "description": "Contract ID pattern: {theme}(:{path})*:{resource} - hierarchical with colons, dots allowed temporarily during migration, NO 'contract:' prefix, NO version (e.g., commons:ux:foundations:color)"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable title (PascalCase recommended)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Contract purpose description"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (REQUIRED): 0.x.x for draft, 1.x.x+ for stable. Major=breaking, Minor=additive, Patch=docs/metadata"
+    },
+    "type": {
+      "type": "string",
+      "const": "object",
+      "description": "Contracts must be objects"
+    },
+    "x-artifact-metadata": {
+      "type": "object",
+      "required": [
+        "domain",
+        "resource",
+        "api",
+        "producer",
+        "consumers",
+        "dependencies",
+        "traceability",
+        "governance"
+      ],
+      "properties": {
+        "domain": {
+          "type": "string",
+          "pattern": "^[a-z_]+$",
+          "description": "Domain from artifact name (before colon)"
+        },
+        "resource": {
+          "type": "string",
+          "pattern": "^[a-z_]+(\\.[a-z_]+)?$",
+          "description": "Resource from artifact name (after colon)"
+        },
+        "collection": {
+          "type": "boolean",
+          "description": "True if this schema is part of a collection (multiple schemas for single artifact)"
+        },
+        "member": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9\\-_]*$",
+          "description": "For collection pattern: identifies specific schema within collection (e.g., 'color', 'system-persona' for ux:foundations collection)"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Contract version (semver)"
+        },
+        "hash": {
+          "type": "string",
+          "description": "SHA-256 content hash"
+        },
+        "producer": {
+          "type": "string",
+          "pattern": "^wagon:[a-z\\-]+$",
+          "description": "Producing wagon"
+        },
+        "consumers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(wagon|external):[a-z\\-]+$"
+          },
+          "description": "Consuming wagons or external services"
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^contract:([a-z][a-z0-9\\-]*:)+[a-z][a-z0-9\\-]*$"
+          },
+          "description": "Other contracts this depends on"
+        },
+        "api": {
+          "type": "object",
+          "required": [
+            "operations"
+          ],
+          "properties": {
+            "version": {
+              "type": "string",
+              "pattern": "^v\\d+$",
+              "description": "API version (e.g., v1, v2)"
+            },
+            "operations": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "required": [
+                  "method",
+                  "path",
+                  "responses"
+                ],
+                "properties": {
+                  "method": {
+                    "type": "string",
+                    "enum": [
+                      "GET",
+                      "POST",
+                      "PUT",
+                      "DELETE",
+                      "PATCH"
+                    ]
+                  },
+                  "path": {
+                    "type": "string",
+                    "pattern": "^/",
+                    "description": "REST endpoint path"
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Operation description"
+                  },
+                  "requestBody": {
+                    "type": "object",
+                    "properties": {
+                      "schema": {
+                        "type": "string",
+                        "description": "JSON Schema reference"
+                      },
+                      "required": {
+                        "type": "boolean",
+                        "default": true
+                      },
+                      "contentType": {
+                        "type": "string",
+                        "default": "application/json"
+                      }
+                    }
+                  },
+                  "responses": {
+                    "type": "object",
+                    "patternProperties": {
+                      "^[1-5][0-9]{2}$": {
+                        "type": "object",
+                        "required": [
+                          "description"
+                        ],
+                        "properties": {
+                          "description": {
+                            "type": "string"
+                          },
+                          "schema": {
+                            "type": "string",
+                            "description": "Response schema reference"
+                          },
+                          "headers": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "required": [
+                                "name"
+                              ],
+                              "properties": {
+                                "name": {
+                                  "type": "string"
+                                },
+                                "type": {
+                                  "type": "string"
+                                },
+                                "description": {
+                                  "type": "string"
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    },
+                    "additionalProperties": false
+                  },
+                  "headers": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "name"
+                      ],
+                      "properties": {
+                        "name": {
+                          "type": "string"
+                        },
+                        "value": {
+                          "type": "string"
+                        },
+                        "description": {
+                          "type": "string"
+                        },
+                        "required": {
+                          "type": "boolean",
+                          "default": false
+                        }
+                      }
+                    }
+                  },
+                  "security": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "type"
+                      ],
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "oauth2",
+                            "jwt",
+                            "apiKey",
+                            "basic"
+                          ]
+                        },
+                        "scheme": {
+                          "type": "string",
+                          "description": "Auth scheme (e.g., bearer)"
+                        },
+                        "scopes": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          },
+                          "description": "OAuth2 scopes"
+                        },
+                        "name": {
+                          "type": "string",
+                          "description": "API key name"
+                        },
+                        "in": {
+                          "type": "string",
+                          "enum": [
+                            "header",
+                            "query",
+                            "cookie"
+                          ],
+                          "description": "API key location"
+                        }
+                      }
+                    }
+                  },
+                  "parameters": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "name",
+                        "in"
+                      ],
+                      "properties": {
+                        "name": {
+                          "type": "string"
+                        },
+                        "in": {
+                          "type": "string",
+                          "enum": [
+                            "query",
+                            "path",
+                            "header"
+                          ]
+                        },
+                        "type": {
+                          "type": "string"
+                        },
+                        "description": {
+                          "type": "string"
+                        },
+                        "required": {
+                          "type": "boolean",
+                          "default": false
+                        },
+                        "default": {},
+                        "enum": {
+                          "type": "array"
+                        }
+                      }
+                    }
+                  },
+                  "idempotent": {
+                    "type": "boolean",
+                    "description": "Whether operation is retry-safe"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "traceability": {
+          "type": "object",
+          "required": [
+            "wagon_ref",
+            "feature_refs"
+          ],
+          "properties": {
+            "wagon_ref": {
+              "type": "string",
+              "pattern": "^plan/[a-z_\\-]+/_[a-z_\\-]+\\.yaml$",
+              "description": "Path to wagon manifest that produces this contract"
+            },
+            "feature_refs": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "pattern": "^feature:[a-z\\-]+:[a-z\\-]+$"
+              },
+              "description": "Feature URNs that produce this contract (at least one required)"
+            },
+            "acceptance_refs": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^acc:[a-z][a-z0-9_-]*:([DLPCEMYRK][0-9]{3}-(UNIT|HTTP|EVENT|WS|E2E|A11Y|VIS|METRIC|JOB|DB|SEC|LOAD|SCRIPT|WIDGET|GOLDEN|BLOC|INTEGRATION|RLS|EDGE|REALTIME|STORAGE)-[0-9]{3}(?:-[a-z0-9-]+)?|[A-Z][0-9]{3})$"
+              },
+              "description": "Acceptance URNs that validate this contract (optional)"
+            }
+          }
+        },
+        "testing": {
+          "type": "object",
+          "properties": {
+            "directory": {
+              "type": "string",
+              "pattern": "^contracts/[a-z_]+/[a-z_]+/tests/$",
+              "description": "Optional legacy path to co-located tests"
+            },
+            "schema_tests": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional test file names for documentation"
+            }
+          }
+        },
+        "telemetry_refs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^telemetry:(event|metric|trace|log):([a-z][a-z0-9_-]*:)+[a-z][a-z0-9_-]*$"
+          }
+        },
+        "governance": {
+          "type": "object",
+          "required": ["status"],
+          "properties": {
+            "status": {
+              "type": "string",
+              "enum": [
+                "draft",
+                "active",
+                "deprecated",
+                "retired"
+              ],
+              "description": "Contract lifecycle status. draft=0.x.x (iterating), active=1.x.x+ (stable), deprecated=sunset warning, retired=no longer used"
+            },
+            "stability": {
+              "type": "string",
+              "enum": [
+                "experimental",
+                "stable",
+                "frozen"
+              ],
+              "description": "API stability level. experimental=may change, stable=backward compat maintained, frozen=no more changes"
+            }
+          }
+        },
+        "persistence": {
+          "type": "object",
+          "description": "Database persistence configuration (only for persistent entities)",
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "enum": ["none", "jsonb", "relational"],
+              "description": "Persistence strategy: none (ephemeral), jsonb (document store), relational (normalized tables)"
+            },
+            "table": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9_]*$",
+              "description": "Database table name (required if strategy != none)"
+            },
+            "migration": {
+              "type": "string",
+              "pattern": "^supabase/migrations/[0-9]{14}_[a-z0-9_]+\\.sql$",
+              "description": "Path to migration file that created this table"
+            },
+            "indexes": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["name", "fields"],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Index name"
+                  },
+                  "type": {
+                    "type": "string",
+                    "enum": ["btree", "gin", "gist", "hash"],
+                    "default": "btree"
+                  },
+                  "fields": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Indexed fields (for JSONB: use -> notation like 'data->>id')"
+                  }
+                }
+              },
+              "description": "Database indexes for this table"
+            }
+          },
+          "required": ["strategy"]
+        },
+        "extensions": {
+          "type": "object",
+          "description": "Domain-specific extensions"
+        }
+      },
+      "additionalProperties": false
+    },
+    "properties": {
+      "type": "object",
+      "description": "Contract-specific properties (for fixed-schema contracts)"
+    },
+    "patternProperties": {
+      "type": "object",
+      "description": "Pattern-based properties (for catalog/token contracts)"
+    },
+    "required": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Required property names"
+    },
+    "$defs": {
+      "type": "object",
+      "description": "Reusable schema definitions"
+    },
+    "examples": {
+      "type": "array",
+      "description": "Example instances"
+    },
+    "additionalProperties": {
+      "type": "boolean",
+      "description": "Whether additional properties are allowed"
+    }
+  },
+  "additionalProperties": true,
+  "examples": [
+    {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "$id": "mechanic:timebank:exhausted",
+      "title": "DecisionChoice",
+      "description": "Player decision choice",
+      "version": "1.0.0",
+      "type": "object",
+      "properties": {
+        "playerId": {
+          "type": "string"
+        },
+        "choice": {
+          "type": "string"
+        }
+      },
+      "x-artifact-metadata": {
+        "domain": "decision",
+        "resource": "choice",
+        "version": "1.0.0",
+        "api": {
+          "version": "v1",
+          "operations": [
+            {
+              "method": "POST",
+              "path": "/decisions",
+              "description": "Create a new decision choice",
+              "requestBody": {
+                "schema": "$ref: #/definitions/DecisionChoice",
+                "required": true
+              },
+              "responses": {
+                "201": {
+                  "description": "Choice created successfully",
+                  "schema": "$ref: #/definitions/DecisionChoice"
+                },
+                "400": {
+                  "description": "Invalid input",
+                  "schema": "$ref: #/definitions/ErrorResponse"
+                }
+              },
+              "headers": [
+                {
+                  "name": "Content-Type",
+                  "value": "application/json",
+                  "required": true
+                },
+                {
+                  "name": "Authorization",
+                  "description": "Bearer token",
+                  "required": true
+                }
+              ],
+              "security": [
+                {
+                  "type": "jwt",
+                  "scheme": "bearer"
+                }
+              ],
+              "idempotent": false
+            },
+            {
+              "method": "GET",
+              "path": "/decisions/{id}",
+              "description": "Retrieve a decision choice",
+              "responses": {
+                "200": {
+                  "description": "Choice found",
+                  "schema": "$ref: #/definitions/DecisionChoice"
+                },
+                "404": {
+                  "description": "Choice not found",
+                  "schema": "$ref: #/definitions/ErrorResponse"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "id",
+                  "in": "path",
+                  "type": "string",
+                  "required": true
+                }
+              ],
+              "idempotent": true
+            }
+          ]
+        },
+        "producer": "wagon:resolve-dilemmas",
+        "consumers": [
+          "wagon:pace-dilemmas"
+        ],
+        "dependencies": [],
+        "traceability": {
+          "wagon_ref": "plan/resolve_dilemmas/_resolve_dilemmas.yaml",
+          "feature_refs": [
+            "feature:resolve-dilemmas:choose-option"
+          ]
+        },
+        "testing": {
+          "directory": "contracts/decision/tests/",
+          "schema_tests": [
+            "choice_schema_test.json"
+          ]
+        }
+      }
+    }
+  ]
+}

atdd/tester/schemas/contract.tmpl.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "{theme}:{resource}[.{facet}]",
+  "title": "{PascalCaseTitle}",
+  "description": "{Concise description of contract purpose}",
+  "version": "1.0.0",
+  "type": "object",
+
+  "required": ["version"],
+  "additionalProperties": false,
+
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Contract version (semver)"
+    }
+  },
+
+  "$defs": {
+  },
+
+  "examples": [
+    {
+    }
+  ],
+
+  "x-artifact-metadata": {
+    "domain": "{domain}",
+    "resource": "{resource}",
+    "version": "1.0.0",
+    "hash": "<sha256-content-hash>",
+
+    "producer": "wagon:{wagon-name}",
+    "consumers": [
+      "wagon:{consumer-wagon}",
+      "external:{external-service}"
+    ],
+
+    "dependencies": [
+      "contract:{domain}:{resource}.{facet}"
+    ],
+
+    "api": {
+      "method": "GET|POST|PUT|DELETE",
+      "path": "/{domain}s/{id}/{resource}",
+      "auth": "required|optional|none"
+    },
+
+    "traceability": {
+      "wagon_ref": "plan/{wagon}/_<wagon>.yaml",
+      "feature_refs": [
+        "feature:{wagon}:{feature-slug}"
+      ],
+      "acceptance_refs": [
+        "acc:{wagon}:{epic-id}.{AC-ID}"
+      ]
+    },
+
+    "testing": {
+      "directory": "contracts/{domain}/tests/",
+      "schema_tests": [
+        "{schema_name}_schema_test.json",
+        "{schema_name}_validation_test.ts"
+      ]
+    },
+
+    "telemetry_refs": [
+      "telemetry:event:{domain}:{resource}:{signal}",
+      "telemetry:metric:{domain}:latency:{measure}"
+    ],
+
+    "governance": {
+      "status": "draft|active|deprecated",
+      "stability": "experimental|stable|frozen"
+    },
+
+    "persistence": {
+      "strategy": "jsonb",
+      "table": "{theme}_{domain}_{aspect}",
+      "migration": "supabase/migrations/{timestamp}_{table_name}.sql",
+      "indexes": [
+        {
+          "name": "idx_{table}_data",
+          "type": "gin",
+          "fields": ["data"]
+        }
+      ],
+      "_comment": "Only for persistent entities. Options: 'none' (events/DTOs), 'jsonb' (recommended for document storage), 'relational' (normalized tables). Remove this entire field if not persisted."
+    },
+
+    "extensions": {
+    }
+  }
+}