{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dataquail.github.io/goodbones/schema/conformance.schema.json",
  "title": "Conformance snapshot",
  "description": "How far a repository's tree is from its architecture manifest, as `architecture conformance --json` reports it. See https://dataquail.github.io/goodbones/architecture-rules/enforcement/conformance/.",
  "type": "object",
  "properties": {
    "version": {
      "type": "number",
      "enum": [
        2
      ],
      "description": "The shape of this document."
    },
    "manifest": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "The file the policy was read from — the root file, when split with `include`."
        },
        "sha256": {
          "type": "string",
          "description": "A hash of that file's bytes, so two snapshots can say whether the policy changed between them."
        }
      },
      "required": [
        "path",
        "sha256"
      ],
      "additionalProperties": false,
      "description": "The policy this snapshot was taken against — the repository's own, or the one `--against` named."
    },
    "roots": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Repo-relative, with forward slashes."
      },
      "description": "The directories walked."
    },
    "files": {
      "type": "number",
      "allOf": [
        {
          "description": "Files walked."
        }
      ]
    },
    "ok": {
      "type": "boolean",
      "description": "What `check` would exit with: true when no reportable violation, unresolved import, stale baseline entry or coverage shortfall exists."
    },
    "coverage": {
      "type": "object",
      "properties": {
        "imports": {
          "type": "object",
          "properties": {
            "covered": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files this family reaches."
                }
              ]
            },
            "total": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files walked."
                }
              ]
            },
            "floor": {
              "type": "number",
              "allOf": [
                {
                  "description": "The fraction the manifest's `limits.coverage` states for this family, when it states one."
                }
              ]
            }
          },
          "required": [
            "covered",
            "total"
          ],
          "additionalProperties": false
        },
        "structure": {
          "type": "object",
          "properties": {
            "covered": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files this family reaches."
                }
              ]
            },
            "total": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files walked."
                }
              ]
            },
            "floor": {
              "type": "number",
              "allOf": [
                {
                  "description": "The fraction the manifest's `limits.coverage` states for this family, when it states one."
                }
              ]
            }
          },
          "required": [
            "covered",
            "total"
          ],
          "additionalProperties": false
        },
        "members": {
          "type": "object",
          "properties": {
            "covered": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files this family reaches."
                }
              ]
            },
            "total": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files walked."
                }
              ]
            },
            "floor": {
              "type": "number",
              "allOf": [
                {
                  "description": "The fraction the manifest's `limits.coverage` states for this family, when it states one."
                }
              ]
            }
          },
          "required": [
            "covered",
            "total"
          ],
          "additionalProperties": false
        },
        "surface": {
          "type": "object",
          "properties": {
            "covered": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files this family reaches."
                }
              ]
            },
            "total": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files walked."
                }
              ]
            },
            "floor": {
              "type": "number",
              "allOf": [
                {
                  "description": "The fraction the manifest's `limits.coverage` states for this family, when it states one."
                }
              ]
            }
          },
          "required": [
            "covered",
            "total"
          ],
          "additionalProperties": false
        },
        "graph": {
          "type": "object",
          "properties": {
            "covered": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files this family reaches."
                }
              ]
            },
            "total": {
              "type": "number",
              "allOf": [
                {
                  "description": "Files walked."
                }
              ]
            },
            "floor": {
              "type": "number",
              "allOf": [
                {
                  "description": "The fraction the manifest's `limits.coverage` states for this family, when it states one."
                }
              ]
            }
          },
          "required": [
            "covered",
            "total"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "imports",
        "structure",
        "members",
        "surface",
        "graph"
      ],
      "additionalProperties": false,
      "description": "Per family, how many walked files it reaches. Structure counts enumerated folders only."
    },
    "conformance": {
      "type": "object",
      "properties": {
        "residue": {
          "type": "object",
          "properties": {
            "count": {
              "type": "number",
              "allOf": [
                {
                  "description": "What the measure counts today."
                }
              ]
            },
            "ceiling": {
              "type": "number",
              "allOf": [
                {
                  "description": "The count the manifest's `limits.conformance` states for this measure, when it states one."
                }
              ]
            }
          },
          "required": [
            "count"
          ],
          "additionalProperties": false
        },
        "vacant": {
          "type": "object",
          "properties": {
            "count": {
              "type": "number",
              "allOf": [
                {
                  "description": "What the measure counts today."
                }
              ]
            },
            "ceiling": {
              "type": "number",
              "allOf": [
                {
                  "description": "The count the manifest's `limits.conformance` states for this measure, when it states one."
                }
              ]
            }
          },
          "required": [
            "count"
          ],
          "additionalProperties": false
        },
        "slack": {
          "type": "object",
          "properties": {
            "count": {
              "type": "number",
              "allOf": [
                {
                  "description": "What the measure counts today."
                }
              ]
            },
            "ceiling": {
              "type": "number",
              "allOf": [
                {
                  "description": "The count the manifest's `limits.conformance` states for this measure, when it states one."
                }
              ]
            }
          },
          "required": [
            "count"
          ],
          "additionalProperties": false
        },
        "concentration": {
          "type": "object",
          "properties": {
            "count": {
              "type": "number",
              "allOf": [
                {
                  "description": "What the measure counts today."
                }
              ]
            },
            "ceiling": {
              "type": "number",
              "allOf": [
                {
                  "description": "The count the manifest's `limits.conformance` states for this measure, when it states one."
                }
              ]
            }
          },
          "required": [
            "count"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "residue",
        "vacant",
        "slack",
        "concentration"
      ],
      "additionalProperties": false,
      "description": "Per measure, the count `check` holds to the manifest's `limits.conformance`: residue files, vacant nodes, slack allowances, and fragment entries used at fewer than half the nodes granted them. The lists below name what each counts."
    },
    "residue": {
      "type": "object",
      "properties": {
        "files": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Repo-relative, with forward slashes."
          },
          "description": "Files no family reaches, sorted."
        },
        "folders": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Repo-relative, with forward slashes."
          },
          "description": "Folders every walked file of which is residue, each the topmost such folder."
        }
      },
      "required": [
        "files",
        "folders"
      ],
      "additionalProperties": false,
      "description": "What the policy has nothing to say about. A file in an open folder under no allowlist is claimed, not policed, and counts."
    },
    "vacant": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "node": {
            "type": "string",
            "description": "The manifest node."
          },
          "allowances": {
            "type": "number",
            "allOf": [
              {
                "description": "Distinct entries the node wrote, `allow` and `external` together."
              }
            ]
          }
        },
        "required": [
          "node",
          "allowances"
        ],
        "additionalProperties": false
      },
      "description": "Nodes that state an import allowlist and select no walked file, in manifest order. Every allowance on one is unused by construction, so none is counted as slack; the node is a tier declared ahead of its first file, or a pattern that no longer matches. Residue is files no node reaches; this is nodes no file reaches."
    },
    "violations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fingerprint": {
            "type": "string",
            "description": "kind|rule|file|subject — line-independent, so it survives edits to the file it names; the baseline's key."
          },
          "kind": {
            "type": "string",
            "enum": [
              "import",
              "export",
              "structure",
              "member",
              "surface",
              "graph",
              "campaign"
            ]
          },
          "ruleName": {
            "type": "string",
            "description": "The manifest node path the rule was lowered from."
          },
          "file": {
            "type": "string",
            "description": "Repo-relative, with forward slashes."
          },
          "subject": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The other end of the violated relationship — the resolved target, the restricted symbol, the missing sibling — or null when the file alone is the violation."
          },
          "message": {
            "type": "string"
          },
          "baselined": {
            "type": "boolean",
            "description": "Carried by the baseline, so `check` does not fail on it."
          },
          "ledgered": {
            "type": "boolean",
            "description": "For a campaign hit: carried by the objective's ledger, so `check` does not fail on it."
          },
          "objective": {
            "type": "string",
            "description": "For a campaign hit: the objective that fired."
          },
          "sector": {
            "type": "string",
            "description": "For a campaign hit: the sector the hit falls in."
          },
          "entry": {
            "type": "string",
            "description": "For a campaign hit: its ledger entry, relative to the sector's root."
          }
        },
        "required": [
          "fingerprint",
          "kind",
          "ruleName",
          "file",
          "subject",
          "message",
          "baselined",
          "ledgered"
        ],
        "additionalProperties": false
      },
      "description": "Every finding, baselined ones included, ordered so the ones cheapest to fix come first: by the height of the violated target in the import graph, leaves first."
    },
    "unresolved": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": {
            "type": "string",
            "description": "Repo-relative, with forward slashes."
          },
          "specifier": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        },
        "required": [
          "file",
          "specifier",
          "detail"
        ],
        "additionalProperties": false
      },
      "description": "Imports the resolver could not turn into a file. Every rule about one enforces nothing."
    },
    "stale": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Baseline entries the code no longer produces."
    },
    "baseline": {
      "type": "object",
      "properties": {
        "size": {
          "type": "number",
          "allOf": [
            {
              "description": "Entries in the baseline file."
            }
          ]
        }
      },
      "required": [
        "size"
      ],
      "additionalProperties": false,
      "description": "The debt the policy is carrying. The ratchet: it may only shrink."
    },
    "cycles": {
      "type": "number",
      "allOf": [
        {
          "description": "Strongly connected components of more than one file, or a file importing itself, anywhere in the walked graph — in a cycles rule's scope or not."
        }
      ]
    },
    "slack": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "node": {
            "type": "string",
            "description": "The manifest node that wrote the entry — or, when `fragment` is set, the `defs` fragment it was written in."
          },
          "kind": {
            "type": "string",
            "enum": [
              "allow",
              "external"
            ],
            "description": "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`."
          },
          "entry": {
            "type": "string",
            "description": "The entry as written, after alias expansion."
          },
          "fragment": {
            "type": "string",
            "description": "Present when the entry arrived through `use`. The nodes that referenced the fragment wrote one word, so the entry is reported once, against the fragment, rather than once per node."
          },
          "of": {
            "type": "number",
            "allOf": [
              {
                "description": "With `fragment`: how many non-vacant nodes were granted the entry through it. None of them uses it."
              }
            ]
          }
        },
        "required": [
          "node",
          "kind",
          "entry"
        ],
        "additionalProperties": false
      },
      "description": "Allowances no observed import uses, in manifest order, vacant nodes excluded. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs. An entry that arrived through `use` is reported once, against the fragment, and only when no node granted it uses it."
    },
    "concentration": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fragment": {
            "type": "string",
            "description": "The `defs` fragment the entry was written in."
          },
          "kind": {
            "type": "string",
            "enum": [
              "allow",
              "external"
            ],
            "description": "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`."
          },
          "entry": {
            "type": "string",
            "description": "The entry as written, after alias expansion."
          },
          "usedAt": {
            "type": "number",
            "allOf": [
              {
                "description": "Nodes granted the entry through the fragment that use it."
              }
            ]
          },
          "of": {
            "type": "number",
            "allOf": [
              {
                "description": "Non-vacant nodes granted the entry through the fragment."
              }
            ]
          }
        },
        "required": [
          "fragment",
          "kind",
          "entry",
          "usedAt",
          "of"
        ],
        "additionalProperties": false
      },
      "description": "Fragment entries used at some of the nodes granted them and not the rest. Not slack — the fragment's line is needed somewhere — but a per-file permission written as a many-node allowance, which is what an allowlist widened to make one build green looks like."
    },
    "adoption": {
      "type": "object",
      "properties": {
        "unrestricted": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Nodes that say `unrestricted: true`."
        },
        "partial": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Nodes that say `partial: true`."
        }
      },
      "required": [
        "unrestricted",
        "partial"
      ],
      "additionalProperties": false,
      "description": "The tiers that said \"not tightened yet\", by name; `limits` caps how many may."
    },
    "campaigns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The campaign's id; its ledgers are under `<ledger>/<id>/`."
          },
          "title": {
            "type": "string",
            "description": "The campaign's title, when it states one."
          },
          "owner": {
            "type": "string",
            "description": "Who is running the campaign, as the manifest names them."
          },
          "count": {
            "type": "number",
            "allOf": [
              {
                "description": "Holdouts across every objective and sector."
              }
            ]
          },
          "progress": {
            "type": "number",
            "allOf": [
              {
                "description": "Cleared over everything ever ledgered, across the campaign's objectives."
              }
            ]
          },
          "objectives": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The objective's id; its ledger is `<ledger>/<campaign>/<objective>.json`."
                },
                "phase": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The phase naming the objective, or `null` for one no phase names — in window everywhere."
                },
                "initial": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "Holdouts recorded as each sector entered the window, summed."
                    }
                  ]
                },
                "allowed": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "Holdouts added since by `objectives concede` or a re-baseline, each with a concession."
                    }
                  ]
                },
                "count": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "Holdouts in the ledger now, every sector summed."
                    }
                  ]
                },
                "cleared": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "Holdouts removed by `objectives clear` because they stopped firing."
                    }
                  ]
                },
                "closed": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "Holdouts still firing when a sector left the window — not progress."
                    }
                  ]
                },
                "progress": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "`1 - count / (initial + allowed - closed)`: how much of everything ever ledgered has been paid down."
                    }
                  ]
                },
                "lastCleared": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "When a holdout last left the ledger, ISO 8601 — the stall clock's reading; `null` with no ledger."
                },
                "concessions": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "How many times a count was allowed to go up."
                    }
                  ]
                },
                "complete": {
                  "type": "boolean",
                  "description": "No holdouts remain."
                },
                "ledgered": {
                  "type": "boolean",
                  "description": "Whether a ledger exists. An objective with none has been declared and not yet cleared."
                }
              },
              "required": [
                "id",
                "phase",
                "initial",
                "allowed",
                "count",
                "cleared",
                "closed",
                "progress",
                "lastCleared",
                "concessions",
                "complete",
                "ledgered"
              ],
              "additionalProperties": false
            },
            "description": "Every objective, in manifest order."
          },
          "phases": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The phase's id."
                },
                "defined": {
                  "type": "boolean",
                  "description": "Whether the phase names criteria. An open phase has only an intent, and is last."
                },
                "sectors": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "How many sectors are derived to stand at this phase."
                    }
                  ]
                }
              },
              "required": [
                "id",
                "defined",
                "sectors"
              ],
              "additionalProperties": false
            },
            "description": "The ladder, in order, with how many sectors stand at each phase."
          },
          "sectors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "The sector's identity, as its perimeter names it."
                },
                "phase": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The phase the sector is derived to stand at, or `null` when it is past the last one."
                },
                "reached": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The furthest phase the sector's record says it has reached; `null` before its first `clear`."
                },
                "files": {
                  "type": "number",
                  "allOf": [
                    {
                      "description": "How many files the sector claims."
                    }
                  ]
                },
                "residue": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "number"
                  },
                  "description": "One dimension per objective in window for the sector: its holdouts there, never summed."
                },
                "stalled": {
                  "type": "boolean",
                  "description": "Holdouts remain for the sector and nothing has been cleared, attested or noted within `staleAfter`."
                }
              },
              "required": [
                "name",
                "phase",
                "reached",
                "files",
                "residue",
                "stalled"
              ],
              "additionalProperties": false
            },
            "description": "Every sector the perimeter births, by name."
          },
          "legacy": {
            "type": "object",
            "properties": {
              "files": {
                "type": "number",
                "allOf": [
                  {
                    "description": "Files in the scope no sector claims."
                  }
                ]
              },
              "holdouts": {
                "type": "number",
                "allOf": [
                  {
                    "description": "Holdouts in the legacy, under the first phase's objectives — where a holdout moved out of a sector lands."
                  }
                ]
              }
            },
            "required": [
              "files",
              "holdouts"
            ],
            "additionalProperties": false,
            "description": "The unclaimed remainder of the scope, which stands at the first phase and is not a sink."
          },
          "plan": {
            "type": "object",
            "properties": {
              "refined": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Phases refined since the last `clear`: an open phase that gained criteria, or a new one. Free."
              },
              "changed": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Defined phases whose definition changed since the last `clear` — what a reviewer reads every time."
              },
              "unreceipted": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Changed phases carrying no new concession; `check` fails on them."
              }
            },
            "required": [
              "refined",
              "changed",
              "unreceipted"
            ],
            "additionalProperties": false,
            "description": "What changed in the plan, refinements and changes apart."
          },
          "stalled": {
            "type": "boolean",
            "description": "Holdouts remain and nothing has been cleared, attested or noted within the campaign's `staleAfter`."
          },
          "complete": {
            "type": "boolean",
            "description": "No holdouts remain in any objective."
          },
          "onComplete": {
            "type": "string",
            "enum": [
              "keep",
              "remove"
            ],
            "description": "What the manifest asks once complete: keep the campaign as a guard, or remove it."
          },
          "ledgered": {
            "type": "boolean",
            "description": "Whether every objective has a ledger."
          }
        },
        "required": [
          "id",
          "count",
          "progress",
          "objectives",
          "phases",
          "sectors",
          "legacy",
          "plan",
          "stalled",
          "complete",
          "onComplete",
          "ledgered"
        ],
        "additionalProperties": false
      },
      "description": "Every campaign the manifest declares, in manifest order, with its burn-down. Campaign hits are not counted in `coverage` or `residue`: a campaign is scoped by construction."
    }
  },
  "required": [
    "version",
    "manifest",
    "roots",
    "files",
    "ok",
    "coverage",
    "conformance",
    "residue",
    "vacant",
    "violations",
    "unresolved",
    "stale",
    "baseline",
    "cycles",
    "slack",
    "concentration",
    "adoption",
    "campaigns"
  ],
  "additionalProperties": false
}