commit.history

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "range": {
      "type": "string",
      "description": "Anything `git log` accepts: `origin/master..HEAD`, `v0.6.0..`, a bare `HEAD`.\nDefault `HEAD`, which is the whole history reachable from here.",
      "default": "HEAD"
    }
  },
  "description": "Which range of history to judge.\n```\nuse majordomus_cli::capability::builtin::commit::HistoryInput;\nlet h: HistoryInput = serde_json::from_str(\"{}\").expect(\"an empty input\");\nassert_eq!(h.range, \"HEAD\", \"the whole history reachable from here\");\n```",
  "title": "HistoryInput"
}

{
  "type": "object",
  "properties": {
    "range": {
      "type": "string",
      "description": "The range as asked for."
    },
    "total": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many commits were read."
    },
    "exempt": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many were exempt because git composed their subject."
    },
    "failing": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many carry a finding of error severity."
    },
    "commits": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/JudgedCommit"
      },
      "description": "Every commit that carries a finding, newest first. A commit with nothing to say is\ncounted and not listed: a report that printed a thousand passing commits would be a\nreport nobody reads."
    }
  },
  "required": [
    "range",
    "total",
    "exempt",
    "failing",
    "commits"
  ],
  "description": "A range of history, judged.\nA range of history, judged in one pass.\n\n```\nuse majordomus_cli::commit::verdict::HistoryReport;\nlet r = HistoryReport {\n    range: \"HEAD\".into(),\n    total: 1755,\n    exempt: 561,\n    failing: 54,\n    commits: Vec::new(),\n};\n// a commit with nothing to say is counted and not listed: a report of a thousand\n// passing commits is a report nobody reads\nassert!(r.commits.is_empty());\nassert_eq!(r.total - r.exempt, 1194);\n```",
  "title": "HistoryReport",
  "$defs": {
    "JudgedCommit": {
      "type": "object",
      "properties": {
        "commit": {
          "type": "string",
          "description": "The commit name, as git gave it."
        },
        "subject": {
          "type": "string",
          "description": "Its subject line."
        },
        "passed": {
          "type": "boolean",
          "description": "Whether it passed."
        },
        "exempt": {
          "anyOf": [
            {
              "$ref": "#/$defs/CommitExemption"
            },
            {
              "type": "null"
            }
          ],
          "description": "Why it was not judged, when it was not."
        },
        "findings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Diagnostic"
          },
          "description": "Every finding."
        }
      },
      "required": [
        "commit",
        "subject",
        "passed",
        "findings"
      ],
      "description": "One commit of the history, judged.\n```\nuse majordomus_cli::commit::verdict::JudgedCommit;\n// what a history report lists: only the commits that have something to say\nlet row = JudgedCommit {\n    commit: \"a1b2c3d4e\".into(),\n    subject: \"update stuff\".into(),\n    passed: false,\n    exempt: None,\n    findings: Vec::new(),\n};\nassert!(!row.passed);\n```"
    },
    "CommitExemption": {
      "oneOf": [
        {
          "type": "string",
          "const": "git_authored",
          "description": "git composed the subject: a merge, a revert, a fixup."
        }
      ],
      "description": "Why a commit was not judged.\n```\nuse majordomus_cli::commit::{judge, CommitExemption, CommitPolicy, CommitSubject};\nlet v = judge(&CommitSubject::of(\"Merge pull request #1 from a/b\"), &CommitPolicy::default());\nassert_eq!(v.exempt, Some(CommitExemption::GitAuthored));\n```"
    },
    "Diagnostic": {
      "type": "object",
      "properties": {
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How bad."
        },
        "code": {
          "type": "string",
          "description": "A stable machine-readable code, e.g. `unknown_key`, `duplicate_identity`."
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Repository-relative path of the file concerned, when there is one."
        },
        "message": {
          "type": "string",
          "description": "What is wrong, for a person; the code is for a program."
        }
      },
      "required": [
        "severity",
        "code",
        "message"
      ],
      "description": "One finding about the declarative state, named by a stable code, tied to a path where\nthere is one, and carrying the command that reproduces it where there is one."
    },
    "Severity": {
      "oneOf": [
        {
          "type": "string",
          "const": "info",
          "description": "Worth knowing; changes nothing."
        },
        {
          "type": "string",
          "const": "warning",
          "description": "Something to look at; the object is still served."
        },
        {
          "type": "string",
          "const": "error",
          "description": "The file is excluded and the index is degraded."
        }
      ],
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither."
    }
  }
}