quality.rustdoc

{
  "$defs": {
    "RustdocFindingKind": {
      "description": "What is wrong with the tree, as a stable code.",
      "oneOf": [
        {
          "const": "missing-page",
          "description": "An exported item that owns a page has no page at its derived route.",
          "type": "string"
        },
        {
          "const": "orphan-page",
          "description": "An item page no item of the crate derives: a leftover, or a route rule this check\nhas wrong.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "The tree declares it was built from a revision other than the repository's HEAD.",
          "type": "string"
        },
        {
          "const": "undeclared",
          "description": "The tree carries no declaration of what it is or what it was built from.",
          "type": "string"
        },
        {
          "const": "crate-index",
          "description": "The library's index page is absent, or does not say it is the library's.",
          "type": "string"
        },
        {
          "const": "asset",
          "description": "A stylesheet, script, font or search file the library's index page needs is absent.",
          "type": "string"
        },
        {
          "const": "link",
          "description": "A relative link of a page resolves to no file of the tree.",
          "type": "string"
        },
        {
          "const": "machine-path",
          "description": "A file names a path of the machine it was built on.",
          "type": "string"
        },
        {
          "const": "secret",
          "description": "A file carries the shape of a credential.",
          "type": "string"
        }
      ]
    }
  },
  "description": "The input of `quality.rustdoc`: which findings to answer with.\n\nThere is deliberately no field naming the tree. The subject is the `rustdoc` surface's\nartifact as the repository's web topology resolves it, so a caller over HTTP or MCP can\nask about the one tree the repository publishes and about no other directory of the\nmachine; the command line's `--tree` is a local affordance of a person at their own\nterminal, and never reaches this input.",
  "properties": {
    "kind": {
      "anyOf": [
        {
          "$ref": "#/$defs/RustdocFindingKind"
        },
        {
          "type": "null"
        }
      ],
      "description": "Only findings of this kind (`missing-page`, `link`, `stale`). All of them when\nabsent. The verdict and the counts are never narrowed: a filter that changed the\nverdict would be a way of passing a tree with a missing page."
    },
    "summary_only": {
      "default": false,
      "description": "Answer with the verdict, the counts and the module routes, and leave the findings\nout.",
      "type": "boolean"
    }
  },
  "title": "RustdocInput",
  "type": "object"
}

{
  "$defs": {
    "RustdocAcceptedLinks": {
      "description": "The unresolved references of one `RustdocLinkClass`: how many, on how many pages, and\nevery distinct one as the pages write it. Every class is listed, with zeros when the\ntree has none, so that \"none\" is an answer and not an omission.",
      "properties": {
        "class": {
          "$ref": "#/$defs/RustdocLinkClass",
          "description": "The class."
        },
        "links": {
          "description": "References of the class, across every page.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "pages": {
          "description": "Pages carrying at least one.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "written": {
          "description": "Every distinct reference as written, fragment included, in canonical order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "class",
        "links",
        "pages",
        "written"
      ],
      "type": "object"
    },
    "RustdocCounts": {
      "description": "What the check counted, so a reader can see what was joined and not only what failed.",
      "properties": {
        "accepted_links": {
          "description": "The unresolved references that are rustdoc's own, by class; every class is listed.",
          "items": {
            "$ref": "#/$defs/RustdocAcceptedLinks"
          },
          "type": "array"
        },
        "derived_pages": {
          "description": "Pages those items derive; more than the items when a re-export documents one twice.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "exported_items": {
          "description": "Items the library exports, of every kind.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "external_links": {
          "description": "External links, by host.",
          "items": {
            "$ref": "#/$defs/RustdocHostLinks"
          },
          "type": "array"
        },
        "files": {
          "description": "Every file of the tree.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "html_files": {
          "description": "Every HTML file of the tree, whatever it is.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "item_pages": {
          "description": "Item pages found in the tree: every page under a crate directory that is neither a\nredirect stub nor a system file.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "page_owning_items": {
          "description": "Of every documented target, the items that own a page: modules, types, traits, free\nfunctions, constants, statics, aliases, macros.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "redirect_stubs": {
          "description": "Pages that only redirect to where an item is documented.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "relative_links": {
          "description": "Relative links followed, across every page: resolved, broken and accepted alike.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "system_files": {
          "description": "rustdoc's own files: static assets, the search index, source pages, implementor\nlists, the settings and help pages, every crate's all-items page and sidebar.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "exported_items",
        "page_owning_items",
        "derived_pages",
        "item_pages",
        "redirect_stubs",
        "system_files",
        "html_files",
        "files",
        "relative_links",
        "accepted_links",
        "external_links"
      ],
      "type": "object"
    },
    "RustdocFinding": {
      "description": "One finding about the tree.",
      "properties": {
        "file": {
          "description": "The file of the tree it is about, tree-relative; empty when it is about the tree as a\nwhole.",
          "type": "string"
        },
        "kind": {
          "$ref": "#/$defs/RustdocFindingKind",
          "description": "What is wrong."
        },
        "message": {
          "description": "One sentence, specific to this occurrence.",
          "type": "string"
        },
        "remedy": {
          "description": "What to do, from the kind.",
          "type": "string"
        },
        "subject": {
          "description": "What exactly: the item path of a missing page, the target of a broken link, the\npattern that matched.",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "file",
        "subject",
        "message",
        "remedy"
      ],
      "type": "object"
    },
    "RustdocFindingKind": {
      "description": "What is wrong with the tree, as a stable code.",
      "oneOf": [
        {
          "const": "missing-page",
          "description": "An exported item that owns a page has no page at its derived route.",
          "type": "string"
        },
        {
          "const": "orphan-page",
          "description": "An item page no item of the crate derives: a leftover, or a route rule this check\nhas wrong.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "The tree declares it was built from a revision other than the repository's HEAD.",
          "type": "string"
        },
        {
          "const": "undeclared",
          "description": "The tree carries no declaration of what it is or what it was built from.",
          "type": "string"
        },
        {
          "const": "crate-index",
          "description": "The library's index page is absent, or does not say it is the library's.",
          "type": "string"
        },
        {
          "const": "asset",
          "description": "A stylesheet, script, font or search file the library's index page needs is absent.",
          "type": "string"
        },
        {
          "const": "link",
          "description": "A relative link of a page resolves to no file of the tree.",
          "type": "string"
        },
        {
          "const": "machine-path",
          "description": "A file names a path of the machine it was built on.",
          "type": "string"
        },
        {
          "const": "secret",
          "description": "A file carries the shape of a credential.",
          "type": "string"
        }
      ]
    },
    "RustdocHostLinks": {
      "description": "How many external links the tree carries to one host. Counted, never fetched: a check\nthat went to the network would be a check whose verdict depended on it.",
      "properties": {
        "host": {
          "description": "The host: `doc.rust-lang.org`.",
          "type": "string"
        },
        "links": {
          "description": "How many links point at it, across every page.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "host",
        "links"
      ],
      "type": "object"
    },
    "RustdocLinkClass": {
      "description": "A kind of unresolved reference that is rustdoc's and not the crate's: decided by where\nit sits on its page, counted, and never a finding.",
      "oneOf": [
        {
          "const": "inherited-documentation",
          "description": "A relative link inside a docblock that rustdoc copied from another crate: the\ndocumentation of an implementation listed under *Auto Trait Implementations* or\n*Blanket Implementations* of a trait no page of this tree documents (the impl's\nheader links no trait page of the tree). The text is the other crate's, written\nrelative to that crate's own pages — tracing's `dispatcher#setting-the-default-subscriber`\n— so it resolves nowhere under this tree and nothing in this crate can change it.\nThe same link anywhere else, or under an implementation of a trait of this crate,\nis a `link` finding.",
          "type": "string"
        },
        {
          "const": "unwritten-implementors",
          "description": "The implementors script a trait's page loads —\n`trait.impl/<crate>/<path>/trait.<Name>.js`, for the trait the page documents — when\nrustdoc wrote none. rustdoc references it from every trait page and writes it only\nwhen it has implementors to list from the documented crates; the page renders its\nown crate's implementors inline and is complete without it. Any other absent script\nis a `link` finding.",
          "type": "string"
        }
      ]
    },
    "RustdocModuleRoute": {
      "description": "One exported module and the page rustdoc documents it on: the mapping a consumer that\nlinks into the tree reads, rather than deriving a route of its own.",
      "properties": {
        "path": {
          "description": "The module's crate path: `majordomus_cli::quality`.",
          "type": "string"
        },
        "route": {
          "description": "Its page, relative to the tree root: `majordomus_cli/quality/index.html`.",
          "type": "string"
        }
      },
      "required": [
        "path",
        "route"
      ],
      "type": "object"
    },
    "RustdocVerdict": {
      "description": "What the tree was judged to be.",
      "oneOf": [
        {
          "const": "clean",
          "description": "The tree holds every page the crate derives and nothing wrong was found.",
          "type": "string"
        },
        {
          "const": "findings",
          "description": "At least one finding stands.",
          "type": "string"
        },
        {
          "const": "no_tree",
          "description": "Nothing could be judged: the tree, or the crate that documents it, is absent. Never\na pass — the producer has not run, and a check that cannot see its subject says so.",
          "type": "string"
        }
      ]
    }
  },
  "description": "One judgement of one rustdoc tree against the crate it documents.",
  "properties": {
    "built_from": {
      "description": "The revision the tree declares it was built from.",
      "type": [
        "string",
        "null"
      ]
    },
    "counts": {
      "$ref": "#/$defs/RustdocCounts",
      "description": "What was counted."
    },
    "crate": {
      "description": "The library's crate name: the directory of the tree it is documented in. Empty when\nthe repository has no crate.",
      "type": "string"
    },
    "findings": {
      "description": "Every finding, in canonical order.",
      "items": {
        "$ref": "#/$defs/RustdocFinding"
      },
      "type": "array"
    },
    "head": {
      "description": "The repository's HEAD when it was judged.",
      "type": [
        "string",
        "null"
      ]
    },
    "modules": {
      "description": "Every exported module of the library with its page, in canonical order: the one\nmodule-to-route mapping every consumer reads. Derived from the crate, so it is\nanswered even when the tree is absent.",
      "items": {
        "$ref": "#/$defs/RustdocModuleRoute"
      },
      "type": "array"
    },
    "mount": {
      "description": "The mount the tree is published at, from the web topology.",
      "type": [
        "string",
        "null"
      ]
    },
    "reason": {
      "description": "Why nothing was judged, when nothing was.",
      "type": [
        "string",
        "null"
      ]
    },
    "schema": {
      "description": "`SCHEMA`.",
      "type": "string"
    },
    "tree": {
      "description": "The tree judged, repository-relative when it is inside the repository.",
      "type": "string"
    },
    "verdict": {
      "$ref": "#/$defs/RustdocVerdict",
      "description": "The verdict."
    }
  },
  "required": [
    "schema",
    "tree",
    "crate",
    "verdict",
    "counts",
    "modules",
    "findings"
  ],
  "title": "RustdocReport",
  "type": "object"
}