quality.report

{
  "description": "The input of `quality.report`: which findings to answer with.",
  "properties": {
    "code": {
      "description": "Only findings carrying this code (`RUST_PUBLIC_MISSING_EXAMPLE`). All of them when\nabsent. A code nothing recognises is refused rather than answered with an empty\nlist, so a typo cannot read as a clean report.",
      "type": [
        "string",
        "null"
      ]
    },
    "include_baselined": {
      "default": false,
      "description": "Include the findings the ratchet already accepts, which are left out by default.\n\nThe default is what a gate wants: only what is new. This is what a person paying the\ndebt down wants, and it is what `--write-baseline` must ask for — a baseline written\nfrom a report that had the baseline applied to it would empty the file, accepting\nnothing and failing on everything the next time it ran.",
      "type": "boolean"
    },
    "path": {
      "description": "Only findings whose file path starts with this, repository-relative\n(`apps/majordomus-cli/src/web`). All of them when absent.",
      "type": [
        "string",
        "null"
      ]
    },
    "summary_only": {
      "default": false,
      "description": "Answer with the counts and leave the findings out. For a caller that wants the\nstate of the crate and not the list of what to do about it.",
      "type": "boolean"
    }
  },
  "title": "QualityInput",
  "type": "object"
}

{
  "$defs": {
    "Exemption": {
      "description": "A group of items the example policy does not apply to, with the reason it does not.",
      "properties": {
        "items": {
          "description": "How many items it covers.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "reason": {
          "description": "The reason, as the policy names it.",
          "type": "string"
        }
      },
      "required": [
        "reason",
        "items"
      ],
      "type": "object"
    },
    "ModuleQuality": {
      "description": "What the exported module surface looks like.",
      "properties": {
        "behaviourally_tested": {
          "description": "How many something exercises: an in-file test, or a test that names them.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "documented": {
          "description": "Of those, how many carry a `//!` header.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "exampled": {
          "description": "How many carry an executable example in that header.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "modules": {
          "description": "Modules the crate exports, the crate root included.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "modules",
        "documented",
        "exampled",
        "behaviourally_tested"
      ],
      "type": "object"
    },
    "OperationParity": {
      "description": "What the canonical operations look like against the transports that project them.",
      "properties": {
        "canonical": {
          "description": "Executable capabilities in the registry.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "cli": {
          "description": "Of those, how many declare a command-line projection.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "cli_commands": {
          "description": "Commands of the command line, leaves and runnable parents.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "cli_from_capability": {
          "description": "Of those, how many are the projection of a capability.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "cli_local": {
          "description": "How many are declared to belong to the command line alone, with a reason.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "http": {
          "description": "How many declare an HTTP route.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "mcp": {
          "description": "How many declare an MCP tool.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "openapi": {
          "description": "How many the OpenAPI document describes.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "canonical",
        "cli",
        "http",
        "openapi",
        "mcp",
        "cli_commands",
        "cli_from_capability",
        "cli_local"
      ],
      "type": "object"
    },
    "PublicApiQuality": {
      "description": "What the exported item surface looks like.",
      "properties": {
        "documented": {
          "description": "Of those, how many carry documentation.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "exampled": {
          "description": "Of those, how many have one that counts.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "exempt": {
          "description": "How many are exempt from the example policy for a structural reason, and why, by\nreason, so that the exemptions are visible rather than implied by a subtraction.",
          "items": {
            "$ref": "#/$defs/Exemption"
          },
          "type": "array"
        },
        "items": {
          "description": "Items the crate exports, of every kind.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "owe_example": {
          "description": "How many owe an executable example under the policy.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "items",
        "documented",
        "owe_example",
        "exampled",
        "exempt"
      ],
      "type": "object"
    },
    "QualityReport": {
      "description": "One measurement of one crate, and everything found wrong in it.",
      "properties": {
        "modules": {
          "$ref": "#/$defs/ModuleQuality",
          "description": "The exported module surface."
        },
        "operations": {
          "$ref": "#/$defs/OperationParity",
          "description": "The canonical operations against their transports."
        },
        "public_api": {
          "$ref": "#/$defs/PublicApiQuality",
          "description": "The exported item surface."
        },
        "schema": {
          "default": "",
          "description": "`SCHEMA`.",
          "type": "string"
        },
        "target": {
          "description": "What was measured: the crate directory, repository-relative.",
          "type": "string"
        },
        "violations": {
          "description": "Every finding, errors first, then by file and line.",
          "items": {
            "$ref": "#/$defs/Violation"
          },
          "type": "array"
        }
      },
      "required": [
        "target",
        "public_api",
        "modules",
        "operations",
        "violations"
      ],
      "type": "object"
    },
    "QualitySeverity": {
      "description": "How much a finding matters.\n\nThere are two levels and not five, because the only question a gate can answer is\nwhether the change may land. A warning is a finding the repository has decided not to\nblock on; nothing else is a warning.",
      "oneOf": [
        {
          "const": "error",
          "description": "The gate fails.",
          "type": "string"
        },
        {
          "const": "warning",
          "description": "Reported, and the gate passes.",
          "type": "string"
        }
      ]
    },
    "Violation": {
      "description": "One finding: what, where, why, and what to do.",
      "properties": {
        "code": {
          "$ref": "#/$defs/ViolationCode",
          "description": "The stable code."
        },
        "line": {
          "description": "The line, 1-based; `None` when the finding is not about a line.",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "message": {
          "description": "One sentence, specific to this occurrence.",
          "type": "string"
        },
        "path": {
          "description": "Where it is, repository-relative; empty when the finding is not about a file.",
          "type": "string"
        },
        "remediation": {
          "description": "What to do, from the code.",
          "type": "string"
        },
        "rule": {
          "description": "The canonical id of the rule that requires this.",
          "type": "string"
        },
        "severity": {
          "$ref": "#/$defs/QualitySeverity",
          "description": "How bad it is."
        },
        "symbol": {
          "description": "The item's full path, or the command, or the capability id: what the finding is about.",
          "type": "string"
        },
        "why": {
          "description": "Why it matters, from the code.",
          "type": "string"
        }
      },
      "required": [
        "code",
        "severity",
        "rule",
        "path",
        "symbol",
        "message",
        "why",
        "remediation"
      ],
      "type": "object"
    },
    "ViolationCode": {
      "description": "What is wrong, as a stable machine-readable code.\n\nThe codes are the contract between the validator and everything downstream: CI\nannotations, Cockpit filters, documentation anchors and an agent deciding what to fix.\nA code is never renamed once it has shipped; a rule that stops existing takes its code\nwith it.",
      "oneOf": [
        {
          "const": "RUST_PUBLIC_MISSING_DOCS",
          "description": "An exported item carries no documentation at all.",
          "type": "string"
        },
        {
          "const": "RUST_PUBLIC_THIN_DOCS",
          "description": "An exported item's documentation says nothing its signature had not already said.",
          "type": "string"
        },
        {
          "const": "RUST_PUBLIC_MISSING_EXAMPLE",
          "description": "An exported item that carries behaviour has no executable example.",
          "type": "string"
        },
        {
          "const": "RUST_EXAMPLE_NOT_EXECUTABLE",
          "description": "Every example an item has is `ignore`d or is prose in a fenced box.",
          "type": "string"
        },
        {
          "const": "RUST_EXAMPLE_PLACEHOLDER",
          "description": "An example asserts nothing, or asserts something that is true of any program.",
          "type": "string"
        },
        {
          "const": "RUST_EXAMPLE_DOES_NOT_NAME_SUBJECT",
          "description": "An example never names the item it is documenting.",
          "type": "string"
        },
        {
          "const": "RUST_MODULE_MISSING_DOCS",
          "description": "An exported module carries no module-level documentation.",
          "type": "string"
        },
        {
          "const": "RUST_MODULE_MISSING_EXAMPLE",
          "description": "An exported module has no module-level executable example.",
          "type": "string"
        },
        {
          "const": "RUST_MODULE_MISSING_BEHAVIOURAL_TEST",
          "description": "No test names an exported module, and it declares none of its own.",
          "type": "string"
        },
        {
          "const": "OPERATION_CLI_UNCLASSIFIED",
          "description": "A command of the command line is neither a canonical capability nor classified as\nbelonging to the command line alone.",
          "type": "string"
        },
        {
          "const": "OPERATION_CLASSIFICATION_STALE",
          "description": "A command is classified as belonging to the command line alone, and the command\nline no longer has it.",
          "type": "string"
        },
        {
          "const": "OPERATION_CLASSIFICATION_CONFLICT",
          "description": "A command is classified as local *and* bound to a capability: two answers to one\nquestion.",
          "type": "string"
        },
        {
          "const": "OPERATION_MISSING_OPENAPI",
          "description": "A capability declares an HTTP route and the OpenAPI document does not describe it.",
          "type": "string"
        },
        {
          "const": "OPERATION_PROJECTION_MISSING",
          "description": "A capability declares a projection that the projection itself does not carry.",
          "type": "string"
        },
        {
          "const": "OPERATION_PROJECTION_ORPHAN",
          "description": "A projection carries an entry the registry does not hold.",
          "type": "string"
        }
      ]
    }
  },
  "description": "The answer: the measurement, or the reason there was not one.",
  "properties": {
    "baselined": {
      "description": "The findings the ratchet accepts because they stood when the rule landed. A finding\noutside this count is what fails the gate.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "measured": {
      "description": "Whether a crate was found and measured. `false` is a complete answer, not a failure:\nthe layer installs into repositories that carry no Rust crate, and a doctrine that\ncannot apply is not a violation.",
      "type": "boolean"
    },
    "passes": {
      "description": "Whether the report as filtered leaves nothing blocking. Answered here so that a\ncaller over any transport reads the verdict rather than deriving it, and so that the\ncommand line's exit code and this field can never disagree.",
      "type": "boolean"
    },
    "reason": {
      "description": "Why nothing was measured, when nothing was.",
      "type": [
        "string",
        "null"
      ]
    },
    "report": {
      "$ref": "#/$defs/QualityReport",
      "description": "The measurement. Present and empty-of-findings when `measured` is false, so that a\nconsumer reads one shape either way and `measured` is the only question it must ask."
    }
  },
  "required": [
    "measured",
    "report",
    "passes",
    "baselined"
  ],
  "title": "QualityAnswer",
  "type": "object"
}