delivery.report

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

{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "description": "`majordomus/delivery/v1`."
    },
    "trunk": {
      "type": [
        "string",
        "null"
      ],
      "description": "The trunk ref every `on_master` verdict was measured against, when one was found."
    },
    "publication": {
      "$ref": "#/$defs/Publication",
      "description": "What the public site was observed to serve, read once for every feature."
    },
    "tallies": {
      "$ref": "#/$defs/DeliveryTallies",
      "description": "The counts."
    },
    "features": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FeatureDelivery"
      },
      "description": "Every feature, ordered by id."
    }
  },
  "required": [
    "schema",
    "publication",
    "tallies",
    "features"
  ],
  "description": "Every feature of the layer against the delivery invariant.",
  "title": "DeliveryReport",
  "$defs": {
    "Publication": {
      "type": "object",
      "properties": {
        "url": {
          "type": [
            "string",
            "null"
          ],
          "description": "The site's address, when one was found."
        },
        "identity_path": {
          "type": [
            "string",
            "null"
          ],
          "description": "The identity document's path under it, from the publication model."
        },
        "identity": {
          "$ref": "#/$defs/IdentityRead",
          "description": "What reading it gave."
        },
        "verification": {
          "$ref": "#/$defs/SiteVerification",
          "description": "Whether the publication was verified."
        }
      },
      "required": [
        "identity",
        "verification"
      ],
      "description": "The publication as observed: where the site is, what it serves, and whether that was\nverified."
    },
    "IdentityRead": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "commit": {
              "type": "string",
              "description": "The commit, as the site states it."
            },
            "dirty": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Whether the tree it was built from was dirty, when the identity says."
            },
            "state": {
              "type": "string",
              "const": "served"
            }
          },
          "required": [
            "state",
            "commit"
          ],
          "description": "The site answered with an identity naming the commit it was built from."
        },
        {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Why, in one clause."
            },
            "state": {
              "type": "string",
              "const": "unreachable"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "description": "The site was asked and gave no identity: no network, no route, not a document."
        },
        {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Why, in one clause."
            },
            "state": {
              "type": "string",
              "const": "unconfigured"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "description": "There was nothing to ask: no site address or no publication model."
        }
      ],
      "description": "What reading the public identity document gave."
    },
    "SiteVerification": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "detail": {
              "type": "string",
              "description": "What was observed."
            },
            "state": {
              "type": "string",
              "const": "verified"
            }
          },
          "required": [
            "state",
            "detail"
          ],
          "description": "Clean identity, a second probe agrees, GitHub's own build succeeded."
        },
        {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "What was observed."
            },
            "state": {
              "type": "string",
              "const": "refused"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "description": "Measured, and it does not hold."
        },
        {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Why."
            },
            "state": {
              "type": "string",
              "const": "unmeasured"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "description": "Could not be measured."
        }
      ],
      "description": "Whether the publication was verified from outside."
    },
    "DeliveryTallies": {
      "type": "object",
      "properties": {
        "features": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Features examined."
        },
        "on_master": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "On the trunk."
        },
        "deployed": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Contained in the public identity."
        },
        "publicly_verified": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Publicly verified."
        },
        "exists": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Every dimension passes."
        }
      },
      "required": [
        "features",
        "on_master",
        "deployed",
        "publicly_verified",
        "exists"
      ],
      "description": "How many features pass each measured dimension, and how many exist."
    },
    "FeatureDelivery": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The feature's id."
        },
        "title": {
          "type": "string",
          "description": "Its title."
        },
        "status": {
          "type": "string",
          "description": "The status its file declares. Editorial, and not one of the dimensions."
        },
        "exists": {
          "type": "boolean",
          "description": "The conjunction: true only when every dimension passes."
        },
        "delivery": {
          "$ref": "#/$defs/DeliveryState",
          "description": "Delivered, or the development stage and what blocks it."
        },
        "dimensions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Dimension"
          },
          "description": "Every dimension, in the order of the conjunction."
        },
        "implementation": {
          "$ref": "#/$defs/Implementation",
          "description": "What it is implemented by."
        }
      },
      "required": [
        "id",
        "title",
        "status",
        "exists",
        "delivery",
        "dimensions",
        "implementation"
      ],
      "description": "One feature against the invariant."
    },
    "DeliveryState": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "const": "delivered"
            }
          },
          "required": [
            "state"
          ],
          "description": "Every dimension passes."
        },
        {
          "type": "object",
          "properties": {
            "stage": {
              "$ref": "#/$defs/DevelopmentStage",
              "description": "How far development has carried it."
            },
            "blocking": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/DimensionId"
              },
              "description": "The dimensions that do not pass, in the order of the conjunction."
            },
            "state": {
              "type": "string",
              "const": "not_delivered"
            }
          },
          "required": [
            "state",
            "stage",
            "blocking"
          ],
          "description": "At least one dimension does not pass."
        }
      ],
      "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."
    },
    "DevelopmentStage": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "DimensionId": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "description": "The six dimensions of the delivery invariant, in the order the conjunction is written."
    },
    "Dimension": {
      "type": "object",
      "properties": {
        "dimension": {
          "$ref": "#/$defs/DimensionId",
          "description": "Which dimension."
        },
        "verdict": {
          "$ref": "#/$defs/DeliveryVerdict",
          "description": "Pass, fail or unknown."
        },
        "reason": {
          "type": "string",
          "description": "What was observed, in one sentence."
        },
        "remediation": {
          "type": [
            "string",
            "null"
          ],
          "description": "What would change the verdict; absent on a pass."
        }
      },
      "required": [
        "dimension",
        "verdict",
        "reason"
      ],
      "description": "One dimension, decided: the verdict, the sentence that decided it, and what would move it."
    },
    "DeliveryVerdict": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "Implementation": {
      "type": "object",
      "properties": {
        "paths": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "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."
        },
        "head_revision": {
          "type": [
            "string",
            "null"
          ],
          "description": "The latest commit touching them reachable from `HEAD`."
        },
        "master_revision": {
          "type": [
            "string",
            "null"
          ],
          "description": "The latest commit touching them reachable from the trunk."
        }
      },
      "required": [
        "paths"
      ],
      "description": "The paths a feature is implemented by and the revisions that last touched them."
    }
  }
}