trace.issue

{
  "additionalProperties": false,
  "description": "One issue of the project model.",
  "properties": {
    "issue": {
      "description": "The issue id, as the project model spells it (`I1305`). An id the model does not\ndeclare is answered with `declared: false` rather than refused, and rather than\nanswered with a bare empty trace: a typo that read as \"nothing realised this issue\"\nis the one answer this capability must never give.",
      "type": "string"
    }
  },
  "required": [
    "issue"
  ],
  "title": "TraceIssueInput",
  "type": "object"
}

{
  "$defs": {
    "BranchTrace": {
      "description": "One branch that names an issue, with the commits it holds.",
      "properties": {
        "commits": {
          "description": "The commits this branch holds and the trunk did not, newest first, merges excluded.",
          "items": {
            "$ref": "#/$defs/CommitRef"
          },
          "type": "array"
        },
        "head": {
          "description": "The commit the ref points at.",
          "type": "string"
        },
        "integration": {
          "$ref": "#/$defs/Integration",
          "description": "How it stands to the trunk."
        },
        "merge_commit": {
          "description": "The merge commit that brought it into the trunk, when one did.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "The ref, short: `feature/I1305-traceability`, or `origin/feature/I1305-traceability`\nwhen only the remote still has it.",
          "type": "string"
        },
        "note": {
          "description": "Why the commit list is what it is, when it is worth a sentence.",
          "type": [
            "string",
            "null"
          ]
        },
        "remote": {
          "description": "True when the ref is a remote-tracking one and no local branch of the same name\nstands for it.",
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "remote",
        "head",
        "integration",
        "commits"
      ],
      "type": "object"
    },
    "CommitRef": {
      "description": "One commit, exactly as git names it. Nothing here is stored anywhere: the whole record\nis re-read from the object database on every call.",
      "properties": {
        "author": {
          "description": "The author, as the commit records them.",
          "type": "string"
        },
        "date": {
          "description": "The author date, ISO 8601 as the commit records it.",
          "type": "string"
        },
        "id": {
          "description": "The full object name.",
          "type": "string"
        },
        "short": {
          "description": "The abbreviated object name, as this repository abbreviates it.",
          "type": "string"
        },
        "subject": {
          "description": "The subject line.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "short",
        "author",
        "date",
        "subject"
      ],
      "type": "object"
    },
    "Integration": {
      "description": "How a branch stands to the trunk, which is what decides which commits are its own.",
      "oneOf": [
        {
          "const": "open",
          "description": "Not reachable from the trunk: its commits are the ones the trunk does not have.",
          "type": "string"
        },
        {
          "const": "merged",
          "description": "Reachable from the trunk through a merge commit, which the trace names: its commits\nare the ones that merge brought in.",
          "type": "string"
        },
        {
          "const": "absorbed",
          "description": "Reachable from the trunk with no merge commit of its own — fast-forwarded, or\nrebased onto it. Its commits cannot be told from the trunk's and none are claimed.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "The trunk is unknown, so there is nothing to measure the branch against.",
          "type": "string"
        }
      ]
    }
  },
  "description": "Everything git knows about one issue's realisation.",
  "properties": {
    "branches": {
      "description": "The branches that name it, local first.",
      "items": {
        "$ref": "#/$defs/BranchTrace"
      },
      "type": "array"
    },
    "commits": {
      "description": "How many distinct commits the branches hold between them.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "complete": {
      "description": "True when every branch's commits could be derived. False when at least one reached\nthe trunk without a merge commit, so part of the work is not distinguishable.",
      "type": "boolean"
    },
    "declared": {
      "description": "True when the project model declares this id. False is not an error and not an\nempty answer: it says the id was looked for and the model does not have it, which a\ncaller must be able to tell apart from \"declared, and nothing has realised it yet\".\nA repository with no project model at all answers `false` for every id rather than\nrefusing, because the branches naming an id are still derivable there.",
      "type": "boolean"
    },
    "issue": {
      "description": "The issue id, as the project model spells it.",
      "type": "string"
    },
    "milestone": {
      "description": "The milestone the canonical issue record names. Git does not hold this edge and\nnothing here derives it: the caller with the index fills it in, and it is `null` in\na repository whose issue record does not name one.",
      "type": [
        "string",
        "null"
      ]
    },
    "trunk": {
      "description": "The trunk every branch was measured against.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "issue",
    "declared",
    "branches",
    "commits",
    "complete"
  ],
  "title": "IssueTrace",
  "type": "object"
}