gates.policy

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

{
  "$defs": {
    "QuestionDecl": {
      "description": "One question of the policy, as declared.\n\n`source` is carried as the text the file states (`obligation:tests`, `gates`,\n`closing:debt`), never as a structure: the policy file, `gates.policy` and the\nquestions of the completion report then state the same bytes for the same question,\nand a reader compares them by eye. `Self::kind`\nparses it; `CompletionPolicy::parse` has already refused a text nothing answers.\n\n```\nuse majordomus_cli::gates::{QuestionDecl, QuestionSource};\n\nlet decl = QuestionDecl {\n    id: \"pushed\".into(),\n    stage: \"commit\".into(),\n    question: \"Has the commit reached the remote?\".into(),\n    source: \"obligation:push\".into(),\n    remediation: \"git push\".into(),\n};\nassert_eq!(decl.kind(), QuestionSource::Obligation(\"push\".into()));\n// the source is carried as text, and serialises as the text the file stated\nassert_eq!(serde_json::to_value(&decl).unwrap()[\"source\"], \"obligation:push\");\n```",
      "properties": {
        "id": {
          "description": "The question's identity, stable across reports.",
          "type": "string"
        },
        "question": {
          "description": "The question, as a person would ask it.",
          "type": "string"
        },
        "remediation": {
          "description": "What would settle it, as a command.",
          "type": "string"
        },
        "source": {
          "description": "What answers it, as the policy states it.",
          "type": "string"
        },
        "stage": {
          "description": "The stage it belongs to.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "stage",
        "question",
        "source",
        "remediation"
      ],
      "type": "object"
    },
    "StageDecl": {
      "description": "One stage of the lifecycle, in the order the policy states them. A stage carries no\nquestion of its own: the questions name it by `id`, and\n`CompletionPolicy::questions_of` gathers them back, so a stage is a heading over\nwhatever the policy hangs under it.\n\n```\nuse majordomus_cli::gates::StageDecl;\n\nlet stage = StageDecl {\n    id: \"commit\".into(),\n    title: \"Commit and push\".into(),\n    summary: \"The work is in the branch's history.\".into(),\n};\n// the same shape the file carries, so a report and the policy agree byte for byte\nlet json = serde_json::to_value(&stage).unwrap();\nassert_eq!(json[\"id\"], \"commit\");\nassert_eq!(serde_json::from_value::<StageDecl>(json).unwrap(), stage);\n```",
      "properties": {
        "id": {
          "description": "The stage's identity, stable across reports.",
          "type": "string"
        },
        "summary": {
          "description": "What it means for the stage to be complete.",
          "type": "string"
        },
        "title": {
          "description": "The stage as a heading.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "title",
        "summary"
      ],
      "type": "object"
    }
  },
  "description": "The completion policy, as `gates.policy` serves it: the stages, the questions and the\nsource each is answered from, with what the policy resolves to in this repository.\nThe policy is flattened into the report, so a reader sees the keys the file carries\nwith the derived fields beside them.\n\n```\nuse majordomus_cli::capability::builtin::gates::CompletionPolicyReport;\nuse majordomus_cli::gates::CompletionPolicy;\n\nlet policy = CompletionPolicy::parse(\n    \"version: 1\\nstages:\\n  - id: a\\n    title: Alpha\\n    summary: s\\nquestions:\\n  - id: q\\n    stage: a\\n    question: Is it?\\n    source: gate:site-check\\n    remediation: run it\\n\",\n    \"share/completion.yaml\",\n)\n.unwrap();\nlet report = CompletionPolicyReport {\n    outline: policy.outline(),\n    problems: policy.validate(&[]),\n    unanswered_gates: policy.unanswered_gates(&[]),\n    policy,\n};\nassert_eq!(report.outline, \"- Alpha: q\\n\");\nassert_eq!(report.unanswered_gates, [\"q:site-check\"]);\nlet json = serde_json::to_value(&report).unwrap();\nassert_eq!(json[\"stages\"][0][\"id\"], \"a\", \"the policy's own keys, flattened\");\nassert!(json.get(\"problems\").is_none(), \"a coherent distribution writes no problems\");\n```",
  "properties": {
    "outline": {
      "description": "The definition of done in a dozen lines: one per stage that asks anything, its\nquestions after a colon.",
      "type": "string"
    },
    "problems": {
      "description": "What does not resolve against the vocabulary the policy is shipped beside: a token\n`share/obligations.yaml` lacks. Empty in a coherent distribution, and never silently so.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "questions": {
      "description": "Every question, in declaration order.",
      "items": {
        "$ref": "#/$defs/QuestionDecl"
      },
      "type": "array"
    },
    "source": {
      "description": "Where it was read from.",
      "type": "string"
    },
    "stages": {
      "description": "The lifecycle, in order.",
      "items": {
        "$ref": "#/$defs/StageDecl"
      },
      "type": "array"
    },
    "unanswered_gates": {
      "description": "The questions answered by a gate this repository's CI model does not declare, as\n`question:gate`. Not a problem of the policy — the model is the repository's — but a\nquestion this repository never gets a verdict for, listed so that it is seen.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "version": {
      "description": "The format version the file states.",
      "format": "uint32",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "version",
    "source",
    "stages",
    "questions",
    "outline"
  ],
  "title": "CompletionPolicyReport",
  "type": "object"
}