rules.proves

{
  "additionalProperties": false,
  "description": "One test, by the path a rule names it with or by its canonical identity.\n# Example\n\n```\nuse majordomus_cli::capability::builtin::rules::RuleTestInput;\nlet i = RuleTestInput { test: \"test/cases/125_rule_proof.sh\".into() };\nassert!(i.test.starts_with(\"test/cases/\"));\n```",
  "properties": {
    "test": {
      "description": "`test/cases/07_scope.sh`, or `suite:07_scope`, or `crate:product`.",
      "type": "string"
    }
  },
  "required": [
    "test"
  ],
  "title": "RuleTestInput",
  "type": "object"
}

{
  "$defs": {
    "RuleClass": {
      "description": "What a rule declares about how strongly it binds.\n\nThe repository has exactly two, and they are not severities on a scale: `blocking` means\na gate refuses the work, `advisory` means a reader is expected to have read it. A rule\nwhose front matter says neither is reported as `Class::Unknown` rather than defaulted,\nbecause guessing here is how a blocking rule quietly becomes advice.\n# Example\n\n```\nuse majordomus_cli::rules::Class;\nassert_eq!(Class::Blocking.label(), \"blocking\");\nassert_eq!(Class::parse(\"advisory\"), Class::Advisory);\n```",
      "oneOf": [
        {
          "const": "blocking",
          "description": "A gate refuses work that violates it.",
          "type": "string"
        },
        {
          "const": "advisory",
          "description": "Normative for whoever reads it; nothing refuses a violation.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "The front matter declared no class, or one this repository does not know.",
          "type": "string"
        }
      ]
    },
    "RuleState": {
      "description": "What the repository can say about one rule's proof, as a whole.\n\nOrdered strongest to weakest so that a summary sorted by this reads as a ranking. A rule's\nstate is made from its parts' by `crate::evidence::freshness::aggregate`: a failing part\nmakes it failing, and otherwise the weakest part that can carry proof decides.\n# Example\n\n```\nuse majordomus_cli::rules::RuleState;\nassert!(RuleState::Proven < RuleState::Stale);\nassert!(RuleState::Stale.passing());\nassert!(!RuleState::Dangling.passing());\n```",
      "oneOf": [
        {
          "const": "proven",
          "description": "Every artifact it names is present, and every test it names has a passing run that\nnothing has invalidated.",
          "type": "string"
        },
        {
          "const": "inputs_unchanged",
          "description": "Every artifact is present and every test passed, but at least one run is only\nun-invalidated rather than measured against this tree.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "A passing run exists, but something it is about has changed since.",
          "type": "string"
        },
        {
          "const": "gated",
          "description": "An executable gate runs what this rule names, on every CI run that selects it. The\nmechanism is in the tree and wired; no verdict for it is recorded here.",
          "type": "string"
        },
        {
          "const": "failing",
          "description": "The latest run of a test this rule names did not pass.",
          "type": "string"
        },
        {
          "const": "not_run",
          "description": "Every artifact is present, and no run of at least one named test was ever recorded.",
          "type": "string"
        },
        {
          "const": "reviewed",
          "description": "The rule declares, with a stated reason, that nothing executable can express it. An\nhonest exemption: counted apart from every proven rule, never counted as one.",
          "type": "string"
        },
        {
          "const": "unrunnable",
          "description": "The rule names a path no runner in this repository drives.",
          "type": "string"
        },
        {
          "const": "dangling",
          "description": "The rule names a path that is not in the tree. A proof that does not exist is worse\nthan no proof, because the rule reads as proven.",
          "type": "string"
        },
        {
          "const": "unproven",
          "description": "The rule names neither a validator nor a test. Correct for a rule nothing executable\ncan express; a defect for a blocking one.",
          "type": "string"
        }
      ]
    },
    "RuleSummary": {
      "description": "A rule named from somewhere else, with just enough to decide whether to follow it.\n# Example\n\n```\nuse majordomus_cli::capability::builtin::rules::RuleSummary;\nuse majordomus_cli::rules::{Class, RuleState};\nlet s = RuleSummary {\n    id: \"project.x\".into(),\n    title: \"X\".into(),\n    class: Class::Advisory,\n    state: RuleState::Reviewed,\n};\nassert_eq!(s.state, RuleState::Reviewed);\n```",
      "properties": {
        "class": {
          "$ref": "#/$defs/RuleClass",
          "description": "How strongly it binds."
        },
        "id": {
          "description": "The rule id.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/RuleState",
          "description": "What the repository can say about its proof."
        },
        "title": {
          "description": "The title.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "title",
        "class",
        "state"
      ],
      "type": "object"
    }
  },
  "description": "What one test proves: the reverse of `RuleDetail`.\n# Example\n\nThe reverse of `rules show`: what a test proves, and which rules would be left with no\nproof at all if it were deleted.\n\n```\nuse majordomus_cli::capability::builtin::rules::TestSubjects;\nlet t = TestSubjects {\n    test: Some(\"suite:07_scope\".into()),\n    path: \"test/cases/07_scope.sh\".into(),\n    present: true,\n    reproduce: Some(\"bash test/run.sh 07_scope\".into()),\n    proves: vec![],\n    sole_proof_of: vec![],\n};\nassert!(t.present);\n```",
  "properties": {
    "path": {
      "description": "The path as given.",
      "type": "string"
    },
    "present": {
      "description": "Whether that path is in the tree.",
      "type": "boolean"
    },
    "proves": {
      "description": "Every rule that names this test, with the state it is in.",
      "items": {
        "$ref": "#/$defs/RuleSummary"
      },
      "type": "array"
    },
    "reproduce": {
      "description": "The command that runs it again.",
      "type": [
        "string",
        "null"
      ]
    },
    "sole_proof_of": {
      "description": "Every rule that would lose its only proof if this test were deleted. This is the\nquestion the one-way relation could never answer.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "test": {
      "description": "The canonical test identity, when a runner owns the path.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "path",
    "present",
    "proves",
    "sole_proof_of"
  ],
  "title": "TestSubjects",
  "type": "object"
}