entity.kinds

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

{
  "$defs": {
    "KindEntry": {
      "description": "One kind of the layer, with its address and how many objects it holds.\n\n`example` carries one of the kind's objects so that a catalogue of kinds is somewhere a\nreader can go from rather than a list of words: a kind with a count and no way in is a\ndead row. It is `None` only for a kind the index holds no object of.\n\n```\nuse majordomus_cli::capability::builtin::entity::KindEntry;\n\nlet e: KindEntry = serde_json::from_value(serde_json::json!({\n    \"kind\": \"adr\",\n    \"count\": 52,\n    \"route\": \"/cockpit/objects/adr\",\n}))\n.unwrap();\n\nassert_eq!(e.kind, \"adr\");\n// the route is the kind's, derived — never a per-kind entry in a table of routes\nassert_eq!(e.route, majordomus_cli::entity::kind_route(&e.kind));\nassert!(e.example.is_none());\n```",
      "properties": {
        "count": {
          "description": "How many objects of it the index holds.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "example": {
          "anyOf": [
            {
              "$ref": "#/$defs/ObjectSummary"
            },
            {
              "type": "null"
            }
          ],
          "description": "One of its objects, so a reader has somewhere to go."
        },
        "kind": {
          "description": "The kind.",
          "type": "string"
        },
        "route": {
          "description": "Where its index is served.",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "count",
        "route"
      ],
      "type": "object"
    },
    "ObjectSummary": {
      "description": "One object, summarised for a listing.",
      "properties": {
        "description": {
          "description": "The one-line description, when the kind holds one.",
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "description": "The capability id, `<kind>.<identity>`.",
          "type": "string"
        },
        "identity": {
          "description": "The identity within the kind.",
          "type": "string"
        },
        "kind": {
          "description": "The kind the object was read as.",
          "type": "string"
        },
        "path": {
          "description": "Repository-relative source path.",
          "type": "string"
        },
        "title": {
          "description": "The title, when the kind's title rule found one.",
          "type": [
            "string",
            "null"
          ]
        },
        "uri": {
          "description": "`majordomus://<kind>/<identity>`.",
          "type": "string"
        }
      },
      "required": [
        "uri",
        "id",
        "kind",
        "identity",
        "path"
      ],
      "type": "object"
    },
    "RouteCollision": {
      "description": "Two objects of one kind whose identities reduce to the same route.\n\nCarries both identities and both files, because the reader who has to fix it needs to\nknow which two things collided and where they are written — a count would tell them\nonly that the tree is refused. `correction` is the sentence `collisions` wrote about\nthis particular pair.\n\n```\n# use majordomus_cli::{Object, Provenance};\n# fn object(kind: &str, identity: &str) -> Object {\n#     Object { kind: kind.into(), identity: identity.into(),\n#         uri: format!(\"majordomus://{kind}/{identity}\"), title: None, description: None,\n#         metadata: serde_json::json!({}), body: String::new(), content: String::new(),\n#         media_type: \"text/markdown\",\n#         provenance: Provenance { path: format!(\"{identity}.md\"), directory: \"x\".into(),\n#             source_class: kind.into(), section: None, bytes: 0, member: None } }\n# }\nuse majordomus_cli::entity::{collisions, Collision};\n\n// `a.b` and `a-b` are two identities and one slug\nlet objects = vec![object(\"rule\", \"a.b\"), object(\"rule\", \"a-b\")];\nlet found: Vec<Collision> = collisions(&objects);\n\nassert_eq!(found.len(), 1);\nassert_eq!(found[0].kind, \"rule\");\nassert_eq!(found[0].slug, \"a-b\");\nassert_eq!(found[0].identities, [\"a.b\", \"a-b\"]);\nassert!(!found[0].correction.is_empty());\n```",
      "properties": {
        "correction": {
          "description": "What to do about it.",
          "type": "string"
        },
        "identities": {
          "description": "The identities that collide, in index order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "kind": {
          "description": "The kind they share.",
          "type": "string"
        },
        "paths": {
          "description": "The files that declared them.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "slug": {
          "description": "The slug they both reduce to; empty when an identity reduces to nothing.",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "slug",
        "identities",
        "paths",
        "correction"
      ],
      "type": "object"
    }
  },
  "description": "Every kind of the layer, each with its route, and every route collision there is.\n\nThe two numbers are what `scripts/ci/entity-check` compares: the objects the index holds\nagainst the objects that have an address. They are reported together, in one answer, so\nthat the gate asks one question instead of joining two lists and deciding for itself\nwhat the difference means.\n\n```\nuse majordomus_cli::capability::builtin::entity::KindList;\n\nlet healthy: KindList = serde_json::from_value(serde_json::json!({\n    \"count\": 1,\n    \"kinds\": [{ \"kind\": \"adr\", \"count\": 52, \"route\": \"/cockpit/objects/adr\" }],\n    \"routable\": 52,\n}))\n.unwrap();\n\nlet held: usize = healthy.kinds.iter().map(|k| k.count).sum();\n// every object addressable, and no collision: the only state the gate accepts\nassert_eq!(held, healthy.routable);\nassert!(healthy.collisions.is_empty());\n```",
  "properties": {
    "collisions": {
      "description": "Two objects of one kind whose identities reduce to one route, which is the only way\nan object can fail to be addressable. Empty is the healthy answer and the only one\n`scripts/ci/entity-check` accepts.",
      "items": {
        "$ref": "#/$defs/RouteCollision"
      },
      "type": "array"
    },
    "count": {
      "description": "How many kinds.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "kinds": {
      "description": "The kinds, in the index's order.",
      "items": {
        "$ref": "#/$defs/KindEntry"
      },
      "type": "array"
    },
    "routable": {
      "description": "How many objects have a route. Every object does, unless it is in `collisions`.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "count",
    "kinds",
    "routable"
  ],
  "title": "KindList",
  "type": "object"
}