delivery.report

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "DeliveryState": {
      "description": "Delivered, or not — and when not, how far development got and which dimensions stand in\nthe way. Two variants of one type rather than a flag beside a stage: a delivered feature\nhas no stage to report, and a stage can never be read as delivery.",
      "oneOf": [
        {
          "description": "Every dimension passes.",
          "properties": {
            "state": {
              "const": "delivered",
              "type": "string"
            }
          },
          "required": [
            "state"
          ],
          "type": "object"
        },
        {
          "description": "At least one dimension does not pass.",
          "properties": {
            "blocking": {
              "description": "The dimensions that do not pass, in the order of the conjunction.",
              "items": {
                "$ref": "#/$defs/DimensionId"
              },
              "type": "array"
            },
            "stage": {
              "$ref": "#/$defs/DevelopmentStage",
              "description": "How far development has carried it."
            },
            "state": {
              "const": "not_delivered",
              "type": "string"
            }
          },
          "required": [
            "state",
            "stage",
            "blocking"
          ],
          "type": "object"
        }
      ]
    },
    "DeliveryTallies": {
      "description": "How many features pass each measured dimension, and how many exist.",
      "properties": {
        "deployed": {
          "description": "Contained in the public identity.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "exists": {
          "description": "Every dimension passes.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "features": {
          "description": "Features examined.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "on_master": {
          "description": "On the trunk.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "publicly_verified": {
          "description": "Publicly verified.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "features",
        "on_master",
        "deployed",
        "publicly_verified",
        "exists"
      ],
      "type": "object"
    },
    "DeliveryVerdict": {
      "description": "One dimension's answer. Three values and never two: a question that could not be asked\nis not a question answered yes, and it is not one answered no either.",
      "oneOf": [
        {
          "const": "pass",
          "description": "The dimension holds, and the reason says what was observed.",
          "type": "string"
        },
        {
          "const": "fail",
          "description": "The dimension was measured and does not hold.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "The dimension could not be measured. Not a pass.",
          "type": "string"
        }
      ]
    },
    "DevelopmentStage": {
      "description": "How far development has carried a feature that does not exist yet. A ladder: a rung is\nreached only when every rung below it passes, so a feature whose tests are unknown is\n`on_master` even when the site already serves it.",
      "oneOf": [
        {
          "const": "unknown",
          "description": "Git could not say where its implementation is.",
          "type": "string"
        },
        {
          "const": "not_implemented",
          "description": "It names no implementation, or nothing ever committed one.",
          "type": "string"
        },
        {
          "const": "implemented_on_branch",
          "description": "Its latest implementation revision is on a branch and not on the trunk.",
          "type": "string"
        },
        {
          "const": "on_master",
          "description": "Its implementation is on the trunk.",
          "type": "string"
        },
        {
          "const": "tested",
          "description": "On the trunk, with every required test current.",
          "type": "string"
        },
        {
          "const": "deployed",
          "description": "Tested, and contained in what the public site serves.",
          "type": "string"
        }
      ]
    },
    "Dimension": {
      "description": "One dimension, decided: the verdict, the sentence that decided it, and what would move it.",
      "properties": {
        "dimension": {
          "$ref": "#/$defs/DimensionId",
          "description": "Which dimension."
        },
        "reason": {
          "description": "What was observed, in one sentence.",
          "type": "string"
        },
        "remediation": {
          "description": "What would change the verdict; absent on a pass.",
          "type": [
            "string",
            "null"
          ]
        },
        "verdict": {
          "$ref": "#/$defs/DeliveryVerdict",
          "description": "Pass, fail or unknown."
        }
      },
      "required": [
        "dimension",
        "verdict",
        "reason"
      ],
      "type": "object"
    },
    "DimensionId": {
      "description": "The six dimensions of the delivery invariant, in the order the conjunction is written.",
      "oneOf": [
        {
          "const": "on_master",
          "description": "The feature's latest implementation revision is reachable from the trunk.",
          "type": "string"
        },
        {
          "const": "deployed",
          "description": "The public site's identity commit contains that revision.",
          "type": "string"
        },
        {
          "const": "publicly_verified",
          "description": "The publication was verified from outside: the site answers with a clean identity,\na second probe agrees, and GitHub's own build of the published branch succeeded.",
          "type": "string"
        },
        {
          "const": "required_tests_current",
          "description": "Every test the feature requires has a current passing execution.",
          "type": "string"
        },
        {
          "const": "test_evidence_published",
          "description": "The evidence of those executions is published.",
          "type": "string"
        },
        {
          "const": "ui_linked",
          "description": "The feature is linked from the user interface.",
          "type": "string"
        }
      ]
    },
    "FeatureDelivery": {
      "description": "One feature against the invariant.",
      "properties": {
        "delivery": {
          "$ref": "#/$defs/DeliveryState",
          "description": "Delivered, or the development stage and what blocks it."
        },
        "dimensions": {
          "description": "Every dimension, in the order of the conjunction.",
          "items": {
            "$ref": "#/$defs/Dimension"
          },
          "type": "array"
        },
        "exists": {
          "description": "The conjunction: true only when every dimension passes.",
          "type": "boolean"
        },
        "id": {
          "description": "The feature's id.",
          "type": "string"
        },
        "implementation": {
          "$ref": "#/$defs/Implementation",
          "description": "What it is implemented by."
        },
        "status": {
          "description": "The status its file declares. Editorial, and not one of the dimensions.",
          "type": "string"
        },
        "title": {
          "description": "Its title.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "title",
        "status",
        "exists",
        "delivery",
        "dimensions",
        "implementation"
      ],
      "type": "object"
    },
    "IdentityRead": {
      "description": "What reading the public identity document gave.",
      "oneOf": [
        {
          "description": "The site answered with an identity naming the commit it was built from.",
          "properties": {
            "commit": {
              "description": "The commit, as the site states it.",
              "type": "string"
            },
            "dirty": {
              "description": "Whether the tree it was built from was dirty, when the identity says.",
              "type": [
                "boolean",
                "null"
              ]
            },
            "state": {
              "const": "served",
              "type": "string"
            }
          },
          "required": [
            "state",
            "commit"
          ],
          "type": "object"
        },
        {
          "description": "The site was asked and gave no identity: no network, no route, not a document.",
          "properties": {
            "reason": {
              "description": "Why, in one clause.",
              "type": "string"
            },
            "state": {
              "const": "unreachable",
              "type": "string"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "type": "object"
        },
        {
          "description": "There was nothing to ask: no site address or no publication model.",
          "properties": {
            "reason": {
              "description": "Why, in one clause.",
              "type": "string"
            },
            "state": {
              "const": "unconfigured",
              "type": "string"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "type": "object"
        }
      ]
    },
    "Implementation": {
      "description": "The paths a feature is implemented by and the revisions that last touched them.",
      "properties": {
        "head_revision": {
          "description": "The latest commit touching them reachable from `HEAD`.",
          "type": [
            "string",
            "null"
          ]
        },
        "master_revision": {
          "description": "The latest commit touching them reachable from the trunk.",
          "type": [
            "string",
            "null"
          ]
        },
        "paths": {
          "description": "Repository-relative paths, derived from what the feature names: the source file of\nevery capability module, `lib/<command>.sh` of every shell command the dispatcher\nsources, and the `implementation` of every claim.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "paths"
      ],
      "type": "object"
    },
    "Publication": {
      "description": "The publication as observed: where the site is, what it serves, and whether that was\nverified.",
      "properties": {
        "identity": {
          "$ref": "#/$defs/IdentityRead",
          "description": "What reading it gave."
        },
        "identity_path": {
          "description": "The identity document's path under it, from the publication model.",
          "type": [
            "string",
            "null"
          ]
        },
        "url": {
          "description": "The site's address, when one was found.",
          "type": [
            "string",
            "null"
          ]
        },
        "verification": {
          "$ref": "#/$defs/SiteVerification",
          "description": "Whether the publication was verified."
        }
      },
      "required": [
        "identity",
        "verification"
      ],
      "type": "object"
    },
    "SiteVerification": {
      "description": "Whether the publication was verified from outside.",
      "oneOf": [
        {
          "description": "Clean identity, a second probe agrees, GitHub's own build succeeded.",
          "properties": {
            "detail": {
              "description": "What was observed.",
              "type": "string"
            },
            "state": {
              "const": "verified",
              "type": "string"
            }
          },
          "required": [
            "state",
            "detail"
          ],
          "type": "object"
        },
        {
          "description": "Measured, and it does not hold.",
          "properties": {
            "reason": {
              "description": "What was observed.",
              "type": "string"
            },
            "state": {
              "const": "refused",
              "type": "string"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "type": "object"
        },
        {
          "description": "Could not be measured.",
          "properties": {
            "reason": {
              "description": "Why.",
              "type": "string"
            },
            "state": {
              "const": "unmeasured",
              "type": "string"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "type": "object"
        }
      ]
    }
  },
  "description": "Every feature of the layer against the delivery invariant.",
  "properties": {
    "features": {
      "description": "Every feature, ordered by id.",
      "items": {
        "$ref": "#/$defs/FeatureDelivery"
      },
      "type": "array"
    },
    "publication": {
      "$ref": "#/$defs/Publication",
      "description": "What the public site was observed to serve, read once for every feature."
    },
    "schema": {
      "description": "`majordomus/delivery/v1`.",
      "type": "string"
    },
    "tallies": {
      "$ref": "#/$defs/DeliveryTallies",
      "description": "The counts."
    },
    "trunk": {
      "description": "The trunk ref every `on_master` verdict was measured against, when one was found.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "schema",
    "publication",
    "tallies",
    "features"
  ],
  "title": "DeliveryReport",
  "type": "object"
}