@goodbones/core 0.1.0-beta.1 → 0.1.0-beta.11

package/schema/conformance.schema.json

@@ -0,0 +1,1019 @@
+{
+  "$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
+}