plan.delivery

{
  "additionalProperties": false,
  "description": "Which issues, and as of when: the input of `plan.delivery`.\n\nBoth fields are optional, and an unknown one is refused rather than ignored, so a caller\nwho misspells `at` is not silently answered live.\n\n```\nuse majordomus_cli::capability::builtin::plan::PlanDeliveryInput;\n\nlet every: PlanDeliveryInput = serde_json::from_str(\"{}\").unwrap();\nassert!(every.issue.is_none() && every.at.is_none(), \"live, every issue\");\nlet one: PlanDeliveryInput =\n    serde_json::from_value(serde_json::json!({ \"issue\": \"I2740\", \"at\": \"HEAD\" })).unwrap();\nassert_eq!((one.issue.as_deref(), one.at.as_deref()), (Some(\"I2740\"), Some(\"HEAD\")));\nassert!(serde_json::from_str::<PlanDeliveryInput>(r#\"{\"commit\":\"HEAD\"}\"#).is_err());\n```",
  "properties": {
    "at": {
      "description": "Observe as of this commit (`HEAD`, a sha, a ref): its history and the tree's release\nrecords, and nothing live — no branch, forge, deployment or clock. Default: live.",
      "type": [
        "string",
        "null"
      ]
    },
    "issue": {
      "description": "One issue id (`I2740`). Default: every issue of the plan. An id the plan does not\ndeclare is not found, never answered as `none`.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "PlanDeliveryInput",
  "type": "object"
}

{
  "$defs": {
    "DeliveryBranch": {
      "description": "A branch that names the issue.",
      "properties": {
        "head": {
          "description": "The commit it points at.",
          "type": "string"
        },
        "name": {
          "description": "The ref, short: `feature/x`, or `origin/feature/x` for a remote-tracking one.",
          "type": "string"
        },
        "observed_at": {
          "description": "When the refs were read.",
          "type": "string"
        },
        "remote": {
          "description": "True for a remote-tracking ref.",
          "type": "boolean"
        },
        "via": {
          "description": "How the name names the issue: `id` or `slug`.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "head",
        "remote",
        "via",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryDeployment": {
      "description": "The published release pointer that covers the issue's release.",
      "properties": {
        "latest_json": {
          "description": "Where that `latest.json` was read: `<commit>:site/static/releases/latest.json`, the\ncommit the observed Pages deployment published.",
          "type": "string"
        },
        "observed_at": {
          "description": "When the publication was observed.",
          "type": "string"
        },
        "version": {
          "description": "The version `latest.json` names.",
          "type": "string"
        }
      },
      "required": [
        "version",
        "latest_json",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryMerge": {
      "description": "The newest commit in the trunk's history that names the issue: a merge, by its pull\nrequest's title or its branch, or a commit whose subject names it the way this\nrepository's commits do (`type(scope): description (I2740)`).",
      "properties": {
        "branch": {
          "description": "The branch it merged, when its subject names one.",
          "type": [
            "string",
            "null"
          ]
        },
        "commit": {
          "description": "The commit: a merge commit, or a commit whose subject names the issue.",
          "type": "string"
        },
        "merged_at": {
          "description": "When it was committed, RFC 3339.",
          "type": "string"
        },
        "merges": {
          "description": "How many commits in the history name the issue; this one is the newest.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "observed_at": {
          "description": "When the history was read.",
          "type": "string"
        },
        "pull_request": {
          "description": "The pull request it merged, when its subject names one.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "title": {
          "description": "The pull request's title, when the merge carries one, or the commit's subject.",
          "type": [
            "string",
            "null"
          ]
        },
        "via": {
          "description": "How it names the issue: `title_or_branch` or `slug` for a merge, `subject` for a\ncommit, `forge_title` for a merged pull request's title as the forge recorded it.",
          "type": "string"
        }
      },
      "required": [
        "commit",
        "via",
        "merged_at",
        "merges",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryObservation": {
      "description": "Where and when the answer was observed.",
      "properties": {
        "commit": {
          "description": "The commit that history ends at.",
          "type": "string"
        },
        "mode": {
          "description": "`live`, or `at` a named commit.",
          "type": "string"
        },
        "observed_at": {
          "description": "When: the clock in live mode, the commit's committer time at a commit.",
          "type": "string"
        },
        "trunk": {
          "description": "The history read: the trunk ref in live mode, the commit asked for otherwise.",
          "type": "string"
        }
      },
      "required": [
        "mode",
        "trunk",
        "commit",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryPullRequest": {
      "description": "An open pull request that names the issue.",
      "properties": {
        "draft": {
          "description": "True for a draft.",
          "type": "boolean"
        },
        "head_ref": {
          "description": "The branch it asks to merge.",
          "type": "string"
        },
        "number": {
          "description": "The number.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "observed_at": {
          "description": "When the forge was observed.",
          "type": "string"
        },
        "title": {
          "description": "The title.",
          "type": "string"
        },
        "via": {
          "description": "How it names the issue: `title_or_branch` or `slug`.",
          "type": "string"
        }
      },
      "required": [
        "number",
        "title",
        "head_ref",
        "draft",
        "via",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryReading": {
      "description": "Whether one source of the answer was read.",
      "oneOf": [
        {
          "const": "read",
          "description": "It was read; what it holds is in the answer.",
          "type": "string"
        },
        {
          "const": "unread",
          "description": "It was not read, and `reason` says why. Nothing it could have proved is claimed or\ndenied.",
          "type": "string"
        }
      ]
    },
    "DeliveryRelease": {
      "description": "The first release that contains the issue's newest merge.",
      "properties": {
        "commit": {
          "description": "The commit the tag names.",
          "type": "string"
        },
        "observed_at": {
          "description": "When the releases were read.",
          "type": "string"
        },
        "tag": {
          "description": "The tag: `v0.27.0`.",
          "type": "string"
        }
      },
      "required": [
        "tag",
        "commit",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliverySource": {
      "description": "One source the answer is built from, and whether it was read.",
      "properties": {
        "detail": {
          "description": "What was read, or why nothing was: the ref, the file, the command that would record\nit.",
          "type": "string"
        },
        "name": {
          "description": "`branches`, `forge`, `history`, `releases` or `publication`.",
          "type": "string"
        },
        "observed_at": {
          "description": "When what was read was observed, RFC 3339, when it was read.",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "$ref": "#/$defs/DeliveryReading",
          "description": "Read or unread."
        }
      },
      "required": [
        "name",
        "state",
        "detail"
      ],
      "type": "object"
    },
    "DeliveryStage": {
      "description": "How far one issue's work has travelled, in order: each stage implies every one before it\nhas been passed through, so the furthest one proved is the issue's stage.",
      "oneOf": [
        {
          "const": "none",
          "description": "Nothing that was read names the issue.",
          "type": "string"
        },
        {
          "const": "branch",
          "description": "A branch names it.",
          "type": "string"
        },
        {
          "const": "pr_open",
          "description": "An open pull request names it.",
          "type": "string"
        },
        {
          "const": "merged",
          "description": "A merge in the trunk's history names it.",
          "type": "string"
        },
        {
          "const": "released",
          "description": "A `v*` release contains its newest merge.",
          "type": "string"
        },
        {
          "const": "deployed",
          "description": "The published `latest.json` names that release or a later one.",
          "type": "string"
        }
      ]
    },
    "IssueDelivery": {
      "description": "One issue's delivery.",
      "properties": {
        "branch": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryBranch"
            },
            {
              "type": "null"
            }
          ],
          "description": "The branch that names it, local first."
        },
        "deployed": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryDeployment"
            },
            {
              "type": "null"
            }
          ],
          "description": "The publication that covers that release."
        },
        "issue": {
          "description": "The issue id.",
          "type": "string"
        },
        "merged": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryMerge"
            },
            {
              "type": "null"
            }
          ],
          "description": "The newest merge that names it."
        },
        "milestone": {
          "description": "Its milestone.",
          "type": "string"
        },
        "pr_open": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryPullRequest"
            },
            {
              "type": "null"
            }
          ],
          "description": "The open pull request that names it, newest first."
        },
        "released": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryRelease"
            },
            {
              "type": "null"
            }
          ],
          "description": "The first release containing that merge."
        },
        "settled": {
          "description": "True when no unread source could have proved a further stage.",
          "type": "boolean"
        },
        "stage": {
          "$ref": "#/$defs/DeliveryStage",
          "description": "The furthest stage proved."
        },
        "status": {
          "description": "Its declared status, as the plan derives it from the stamps: the other half of the\ncomparison this answer exists for.",
          "type": "string"
        },
        "title": {
          "description": "Its title.",
          "type": "string"
        },
        "unread": {
          "description": "The sources that were not read and could have proved a further stage.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "issue",
        "title",
        "milestone",
        "status",
        "stage",
        "settled",
        "unread"
      ],
      "type": "object"
    }
  },
  "description": "Every issue's delivery, with what it was read from.",
  "properties": {
    "issues": {
      "description": "The issues, in id order.",
      "items": {
        "$ref": "#/$defs/IssueDelivery"
      },
      "type": "array"
    },
    "observed": {
      "$ref": "#/$defs/DeliveryObservation",
      "description": "Where and when."
    },
    "schema": {
      "description": "The version of this shape.",
      "format": "uint32",
      "minimum": 0,
      "type": "integer"
    },
    "sources": {
      "description": "Every source, read or not.",
      "items": {
        "$ref": "#/$defs/DeliverySource"
      },
      "type": "array"
    },
    "stages": {
      "description": "The stage vocabulary, in order.",
      "items": {
        "$ref": "#/$defs/DeliveryStage"
      },
      "type": "array"
    },
    "tallies": {
      "additionalProperties": {
        "format": "uint",
        "minimum": 0,
        "type": "integer"
      },
      "description": "How many issues are at each stage, keyed by every stage of the vocabulary.",
      "type": "object"
    },
    "unsettled": {
      "description": "How many issues an unread source could have moved further.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "schema",
    "observed",
    "stages",
    "sources",
    "tallies",
    "unsettled",
    "issues"
  ],
  "title": "IssueDeliveryReport",
  "type": "object"
}