artifacts.list

{
  "$defs": {
    "ArtifactFormat": {
      "description": "The encoding one generated artifact is written in.",
      "oneOf": [
        {
          "const": "json",
          "description": "A JSON document: pretty-printed, one trailing newline, provenance as members.",
          "type": "string"
        },
        {
          "const": "yaml",
          "description": "The same document in the layer's YAML, provenance as a comment banner.",
          "type": "string"
        },
        {
          "const": "markdown",
          "description": "Markdown for a reader, provenance as an HTML comment.",
          "type": "string"
        },
        {
          "const": "text",
          "description": "Line-oriented text another program reads: the shell tool's allow-lists,\nprovenance as `#` comments.",
          "type": "string"
        }
      ]
    }
  },
  "additionalProperties": false,
  "description": "The input of `artifacts.list`: the whole manifest, or one slice of it.",
  "properties": {
    "document": {
      "description": "Only the artifacts of this document (`registry`, `cli`, `openapi`, ...).",
      "type": [
        "string",
        "null"
      ]
    },
    "format": {
      "anyOf": [
        {
          "$ref": "#/$defs/ArtifactFormat"
        },
        {
          "type": "null"
        }
      ],
      "description": "Only the artifacts written in this encoding."
    }
  },
  "title": "ArtifactsInput",
  "type": "object"
}

{
  "$defs": {
    "ArtifactFormat": {
      "description": "The encoding one generated artifact is written in.",
      "oneOf": [
        {
          "const": "json",
          "description": "A JSON document: pretty-printed, one trailing newline, provenance as members.",
          "type": "string"
        },
        {
          "const": "yaml",
          "description": "The same document in the layer's YAML, provenance as a comment banner.",
          "type": "string"
        },
        {
          "const": "markdown",
          "description": "Markdown for a reader, provenance as an HTML comment.",
          "type": "string"
        },
        {
          "const": "text",
          "description": "Line-oriented text another program reads: the shell tool's allow-lists,\nprovenance as `#` comments.",
          "type": "string"
        }
      ]
    },
    "ArtifactState": {
      "description": "Where one generated file stands against the tree it is committed in.",
      "oneOf": [
        {
          "const": "current",
          "description": "The file is there and its bytes hash to what the manifest recorded.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "The file is there and its bytes differ: it was edited, or the generator moved on.",
          "type": "string"
        },
        {
          "const": "missing",
          "description": "The manifest names it and the tree does not have it.",
          "type": "string"
        },
        {
          "const": "present",
          "description": "The file is there and the manifest records no hash for it: the manifest's own\nencodings, which cannot hash themselves. `generate --check` compares them.",
          "type": "string"
        }
      ]
    },
    "ArtifactTallies": {
      "description": "How many of each, so a caller needs no arithmetic of its own.",
      "properties": {
        "artifacts": {
          "description": "Files in the manifest, after any filter.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "current": {
          "description": "Hashes that match.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "documents": {
          "description": "Documents in the manifest.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "missing": {
          "description": "Files the manifest names and the tree lacks.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "present": {
          "description": "Files the manifest records no hash for.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "stale": {
          "description": "Hashes that do not.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "documents",
        "artifacts",
        "current",
        "stale",
        "missing",
        "present"
      ],
      "type": "object"
    },
    "ArtifactVerdict": {
      "description": "Where the generated tree stands as a whole: the one verdict every surface renders,\ndecided here so that no page decides it again from a subset of the tallies.\n\n```\nuse majordomus_cli::capability::builtin::artifacts::ArtifactVerdict;\nlet v: ArtifactVerdict = serde_json::from_str(\"\\\"unverified\\\"\").unwrap();\nassert_eq!(v, ArtifactVerdict::Unverified);\nassert!(ArtifactVerdict::Current < ArtifactVerdict::Unverified);\n```",
      "oneOf": [
        {
          "const": "current",
          "description": "Every file is there and hashes to what the manifest recorded.",
          "type": "string"
        },
        {
          "const": "unverified",
          "description": "Every file is there, none is stale, and some carry no recorded hash: their bytes\nwere not compared here, so the tree is not known to be current.\n`majordomus generate --check` is what decides them.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "A file differs from what the manifest recorded.",
          "type": "string"
        },
        {
          "const": "missing",
          "description": "A file the manifest names is not in the tree.",
          "type": "string"
        },
        {
          "const": "not_generated",
          "description": "No manifest is committed: the repository has never run `majordomus generate`.",
          "type": "string"
        }
      ]
    },
    "ArtifactView": {
      "description": "One generated file, as the manifest declares it and as the tree has it.",
      "properties": {
        "bytes": {
          "description": "The size the manifest recorded.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "document": {
          "description": "The document it projects.",
          "type": "string"
        },
        "format": {
          "$ref": "#/$defs/ArtifactFormat",
          "description": "The encoding."
        },
        "path": {
          "description": "Repository-relative path.",
          "type": "string"
        },
        "schema": {
          "description": "The JSON Schema its content satisfies, when it declares one.",
          "type": [
            "string",
            "null"
          ]
        },
        "sha256": {
          "description": "The hash the manifest recorded.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "One line: what it was derived from.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/ArtifactState",
          "description": "Where the file stands against it."
        }
      },
      "required": [
        "path",
        "document",
        "format",
        "source",
        "state"
      ],
      "type": "object"
    },
    "DocumentView": {
      "description": "One document, and the encodings it is committed in.",
      "properties": {
        "formats": {
          "description": "The encodings, in the manifest's order.",
          "items": {
            "$ref": "#/$defs/ArtifactFormat"
          },
          "type": "array"
        },
        "id": {
          "description": "The document id, shared by every encoding of it.",
          "type": "string"
        },
        "schema": {
          "description": "The schema id its structured encodings carry.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "One line: what it was derived from.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "source",
        "formats"
      ],
      "type": "object"
    }
  },
  "description": "The answer of `artifacts.list`.",
  "properties": {
    "artifacts": {
      "description": "The files, in the manifest's order, after any filter.",
      "items": {
        "$ref": "#/$defs/ArtifactView"
      },
      "type": "array"
    },
    "documents": {
      "description": "The documents, in the manifest's order.",
      "items": {
        "$ref": "#/$defs/DocumentView"
      },
      "type": "array"
    },
    "manifest": {
      "description": "The manifest this was read from, repository-relative.",
      "type": "string"
    },
    "present": {
      "description": "Whether the manifest is committed in this repository at all. A repository that has\nnever run `majordomus generate` has no generated tree, which is a fact about it and\nnot a failure of this call: every list below is then empty and every tally zero.",
      "type": "boolean"
    },
    "regenerate": {
      "description": "The command that rewrites every one of them.",
      "type": "string"
    },
    "schema": {
      "description": "The schema the manifest carries, empty when there is none to read.",
      "type": "string"
    },
    "tallies": {
      "$ref": "#/$defs/ArtifactTallies",
      "description": "The counts."
    },
    "verdict": {
      "$ref": "#/$defs/ArtifactVerdict",
      "description": "Where the tree stands as a whole, decided from every tally."
    },
    "verify": {
      "description": "The command that decides staleness byte for byte, which is stronger than the hash.",
      "type": "string"
    }
  },
  "required": [
    "manifest",
    "present",
    "schema",
    "documents",
    "artifacts",
    "tallies",
    "verdict",
    "regenerate",
    "verify"
  ],
  "title": "ArtifactReport",
  "type": "object"
}