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

package/schema/conformance.schema.json

@@ -0,0 +1,775 @@
+{
+  "$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": [
+        1
+      ],
+      "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 campaign's ledger, so `check` does not fail on it."
+          }
+        },
+        "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 ledger is `<ledger>/<id>.json`."
+          },
+          "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."
+          },
+          "initial": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "Entries the day the ledger was written."
+              }
+            ]
+          },
+          "allowed": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "Entries added since by `campaigns allow`, each with a regression record."
+              }
+            ]
+          },
+          "count": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "Entries in the ledger now."
+              }
+            ]
+          },
+          "fixed": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "Entries removed by `campaigns prune` since the ledger was written."
+              }
+            ]
+          },
+          "progress": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "`1 - count / (initial + allowed)`: how much of everything ever ledgered has been paid down."
+              }
+            ]
+          },
+          "lastProgress": {
+            "type": "string",
+            "description": "When an entry last left the ledger, ISO 8601 — the stall clock's reading."
+          },
+          "regressions": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "How many times the count was allowed to go up."
+              }
+            ]
+          },
+          "stalled": {
+            "type": "boolean",
+            "description": "Entries remain and `lastProgress` is older than the campaign's `staleAfter`."
+          },
+          "complete": {
+            "type": "boolean",
+            "description": "No entries remain."
+          },
+          "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 a ledger exists. A campaign with none has been declared and not yet initialised."
+          }
+        },
+        "required": [
+          "id",
+          "initial",
+          "allowed",
+          "count",
+          "fixed",
+          "progress",
+          "lastProgress",
+          "regressions",
+          "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
+}