trace.report

{
  "additionalProperties": false,
  "description": "How much of the trunk to attribute.",
  "properties": {
    "limit": {
      "description": "How many trunk commits to attribute, newest first. Default: 50. Anything above 2000\nis read as 2000 — a traceability report is a reading, not a history export.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "title": "TraceReportInput",
  "type": "object"
}

{
  "$defs": {
    "Attribution": {
      "description": "What is known about the contract one commit served.",
      "oneOf": [
        {
          "const": "attributed",
          "description": "Exactly one issue's branches contain it.",
          "type": "string"
        },
        {
          "const": "unattributed",
          "description": "No branch naming an issue contains it.",
          "type": "string"
        },
        {
          "const": "ambiguous",
          "description": "Branches naming more than one issue contain it.",
          "type": "string"
        }
      ]
    },
    "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"
    },
    "CommitAttribution": {
      "description": "One commit and the contract it served, or the fact that none can be found.",
      "properties": {
        "attribution": {
          "$ref": "#/$defs/Attribution",
          "description": "What is known."
        },
        "branches": {
          "description": "The branches that contain it, by the names their refs carry.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "commit": {
          "$ref": "#/$defs/CommitRef",
          "description": "The commit."
        },
        "issue": {
          "description": "The issue, when exactly one claims it.",
          "type": [
            "string",
            "null"
          ]
        },
        "issues": {
          "description": "Every issue whose branches contain it: one when attributed, none when unattributed,\nmore than one when ambiguous.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "milestone": {
          "description": "The milestone that issue belongs to, filled by the caller that has the index.",
          "type": [
            "string",
            "null"
          ]
        },
        "reason": {
          "description": "Why the verdict is what it is, in one line a person can act on.",
          "type": "string"
        }
      },
      "required": [
        "commit",
        "attribution",
        "issues",
        "branches",
        "reason"
      ],
      "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"
        }
      ]
    },
    "IssueTrace": {
      "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"
      ],
      "type": "object"
    },
    "TraceTallies": {
      "description": "The counts of one report.",
      "properties": {
        "ambiguous": {
          "description": "Examined trunk commits more than one issue claims.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "attributed": {
          "description": "Examined trunk commits with exactly one issue.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "branch_commits": {
          "description": "Distinct commits those branches claim.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "branches": {
          "description": "Branches naming an issue.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "issues_declared": {
          "description": "Issue ids the project model declares.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "issues_with_branch": {
          "description": "Of those, the ones at least one ref names.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "unattributed": {
          "description": "Examined trunk commits no branch naming an issue contains.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "issues_declared",
        "issues_with_branch",
        "branches",
        "branch_commits",
        "attributed",
        "unattributed",
        "ambiguous"
      ],
      "type": "object"
    }
  },
  "description": "The whole traceability answer: every issue git can say something about, and every commit\nof a stretch of the trunk with the contract it served or the fact that it has none.",
  "properties": {
    "commits": {
      "description": "The examined trunk commits, newest first.",
      "items": {
        "$ref": "#/$defs/CommitAttribution"
      },
      "type": "array"
    },
    "examined": {
      "description": "How many trunk commits were attributed.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "issues": {
      "description": "The issues that at least one branch names, in id order.",
      "items": {
        "$ref": "#/$defs/IssueTrace"
      },
      "type": "array"
    },
    "tallies": {
      "$ref": "#/$defs/TraceTallies",
      "description": "The counts, so a caller need not add them up."
    },
    "trunk": {
      "description": "The trunk every branch and commit was measured against.",
      "type": [
        "string",
        "null"
      ]
    },
    "without_branch": {
      "description": "The issue ids the project model declares that no ref names. Not a fault: an issue\nnobody has started has no branch yet.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "examined",
    "issues",
    "without_branch",
    "commits",
    "tallies"
  ],
  "title": "TraceReport",
  "type": "object"
}