@goodbones/core 0.1.0-beta.4 → 0.1.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodbones/core",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.5",
   "type": "module",
   "license": "MIT",
   "description": "Architecture policy as one manifest of your repository, language-agnostic: the manifest schema, the evaluators for imports, exports, members, surface, structure and the import graph, the ports a language pack implements, and the loader that turns a manifest into a policy every rule of which has proven it can fire.",
@@ -34,6 +34,8 @@
       "default": "./build/esm/testing.js"
     },
     "./schema/architecture.schema.json": "./schema/architecture.schema.json",
+    "./schema/architecture-node.schema.json": "./schema/architecture-node.schema.json",
+    "./schema/conformance.schema.json": "./schema/conformance.schema.json",
     "./package.json": "./package.json"
   },
   "types": "./build/dts/index.d.ts",

package/schema/conformance.schema.json

@@ -0,0 +1,457 @@
+{
+  "$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."
+    },
+    "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."
+    },
+    "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"
+            ]
+          },
+          "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."
+          }
+        },
+        "required": [
+          "fingerprint",
+          "kind",
+          "ruleName",
+          "file",
+          "subject",
+          "message",
+          "baselined"
+        ],
+        "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."
+          },
+          "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."
+          }
+        },
+        "required": [
+          "node",
+          "kind",
+          "entry"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Allowances no observed import uses, in manifest order. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs."
+    },
+    "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."
+    }
+  },
+  "required": [
+    "version",
+    "manifest",
+    "roots",
+    "files",
+    "ok",
+    "coverage",
+    "residue",
+    "violations",
+    "unresolved",
+    "stale",
+    "baseline",
+    "cycles",
+    "slack",
+    "adoption"
+  ],
+  "additionalProperties": false
+}

package/src/core/coverage.ts

@@ -59,52 +59,129 @@ const selects = (
   file: string,
 ) => firstFromMatch(rule, file) !== null;
 
-export const coverageOf = (policy: CoverageInputs, files: ReadonlyArray<string>): Coverage => {
-  const allowlists = policy.importRules.filter(isAllowlist);
-  let imports = 0;
-  let enumerated = 0;
-  let open = 0;
-  let members = 0;
-  let surface = 0;
-  let graph = 0;
-
-  for (const file of files) {
-    if (allowlists.some((rule) => selects(rule, file))) imports += 1;
+// Which families reach one file. The one loop both `coverageOf` and
+// `residueOf` run: the first counts, the second keeps the names.
+export type Reach = {
+  readonly file: string;
+  readonly imports: boolean;
+  // Enumerated and open are told apart, as `coverageOf` counts them.
+  readonly structure: "enumerated" | "open" | null;
+  readonly members: boolean;
+  readonly surface: boolean;
+  readonly graph: boolean;
+};
 
+export const reachOf = (
+  policy: CoverageInputs,
+  files: ReadonlyArray<string>,
+): ReadonlyArray<Reach> => {
+  const allowlists = policy.importRules.filter(isAllowlist);
+  return files.map((file) => {
     const folder = dirnameOf(file);
     const governing = policy.structure.folders.filter((rule) =>
       rule.folder.some((pattern) => pattern.test(folder)),
     );
-    if (governing.length > 0) {
-      if (governing.every((rule) => rule.files.some((pattern) => pattern.source === OPEN_LAYOUT))) {
-        open += 1;
-      } else {
-        enumerated += 1;
-      }
-    }
-
-    if (policy.memberRules.some((rule) => selects(rule, file))) members += 1;
-    if (policy.surfaceRules.some((rule) => selects(rule, file))) surface += 1;
-
-    const scoped = [...policy.graph.cycles, ...policy.graph.orphans].some(
-      (rule) =>
-        rule.within.some((pattern) => pattern.test(file)) &&
-        !rule.withinNot.some((pattern) => pattern.test(file)),
-    );
-    if (scoped) graph += 1;
-  }
+    const structure =
+      governing.length === 0
+        ? null
+        : governing.every((rule) => rule.files.some((pattern) => pattern.source === OPEN_LAYOUT))
+          ? "open"
+          : "enumerated";
+    return {
+      file,
+      imports: allowlists.some((rule) => selects(rule, file)),
+      structure,
+      members: policy.memberRules.some((rule) => selects(rule, file)),
+      surface: policy.surfaceRules.some((rule) => selects(rule, file)),
+      graph: [...policy.graph.cycles, ...policy.graph.orphans].some(
+        (rule) =>
+          rule.within.some((pattern) => pattern.test(file)) &&
+          !rule.withinNot.some((pattern) => pattern.test(file)),
+      ),
+    };
+  });
+};
 
+export const coverageOf = (policy: CoverageInputs, files: ReadonlyArray<string>): Coverage => {
+  const reach = reachOf(policy, files);
+  const count = (is: (one: Reach) => boolean): number => reach.filter(is).length;
   const total = files.length;
   return {
     files: total,
-    imports: { covered: imports, total },
-    structure: { enumerated, open, total },
-    members: { covered: members, total },
-    surface: { covered: surface, total },
-    graph: { covered: graph, total },
+    imports: { covered: count((one) => one.imports), total },
+    structure: {
+      enumerated: count((one) => one.structure === "enumerated"),
+      open: count((one) => one.structure === "open"),
+      total,
+    },
+    members: { covered: count((one) => one.members), total },
+    surface: { covered: count((one) => one.surface), total },
+    graph: { covered: count((one) => one.graph), total },
   };
 };
 
+// The files no family reaches — counted by no family's coverage, so a file in
+// an open folder under no allowlist is residue: claimed, not policed — and
+// the folders wholly made of them, each the topmost such folder. A policy
+// that is 40% silence looks exactly like one that is 100% enforced, until
+// counted; this is what the silence is made of.
+export type Residue = {
+  readonly files: ReadonlyArray<string>;
+  readonly folders: ReadonlyArray<string>;
+};
+
+export const residueOf = (policy: CoverageInputs, files: ReadonlyArray<string>): Residue => {
+  const unreached = reachOf(policy, files)
+    .filter(
+      (one) =>
+        !one.imports &&
+        one.structure !== "enumerated" &&
+        !one.members &&
+        !one.surface &&
+        !one.graph,
+    )
+    .map((one) => one.file)
+    .sort();
+  return { files: unreached, folders: foldersWhollyIn(unreached, files) };
+};
+
+// Every ancestor folder of a file, nearest first, the root (`""`) excluded.
+const ancestorsOf = (file: string): ReadonlyArray<string> => {
+  const folders: Array<string> = [];
+  let folder = dirnameOf(file);
+  while (folder !== "") {
+    folders.push(folder);
+    folder = dirnameOf(folder);
+  }
+  return folders;
+};
+
+// The topmost folders every walked file of which is in `subset`. Each is
+// reported once, with none of its subfolders, and a lone file's folder counts
+// — a folder with one file the policy ignores is a folder the policy ignores.
+const foldersWhollyIn = (
+  subset: ReadonlyArray<string>,
+  files: ReadonlyArray<string>,
+): ReadonlyArray<string> => {
+  const walked = new Map<string, number>();
+  for (const file of files) {
+    for (const folder of ancestorsOf(file)) walked.set(folder, (walked.get(folder) ?? 0) + 1);
+  }
+  const inSubset = new Map<string, number>();
+  for (const file of subset) {
+    for (const folder of ancestorsOf(file)) {
+      inSubset.set(folder, (inSubset.get(folder) ?? 0) + 1);
+    }
+  }
+  const whole = [...inSubset.entries()]
+    .filter(([folder, count]) => walked.get(folder) === count)
+    .map(([folder]) => folder)
+    .sort();
+  return whole.filter(
+    (folder) => !whole.some((other) => other !== folder && folder.startsWith(`${other}/`)),
+  );
+};
+
 // A floor the policy states for itself, per family, as a fraction. Structure
 // counts enumerated folders only: an open one is claimed, not policed by name.
 export type CoverageFloors = {

package/src/core/graph.ts

@@ -227,6 +227,42 @@ export const cyclesIn = (graph: Graph): ReadonlyArray<ReadonlyArray<string>> =>
     );
   });
 
+// How far each file stands above a leaf: 0 for a file importing nothing the
+// walk saw, else one more than the tallest thing it imports. A violation on a
+// short target is local to fix; one on a tall target drags the tower with it —
+// so a report lists the short ones first. Measured over the strongly
+// connected components, so the members of a cycle share one height and the
+// answer is finite: a cycle is one thing to fix, not a ladder.
+export const heightOf = (graph: Graph): ReadonlyMap<string, number> => {
+  const components = stronglyConnected(graph.files, graph);
+  const componentOf = new Map<string, number>();
+  components.forEach((component, index) => {
+    for (const file of component) componentOf.set(file, index);
+  });
+
+  const heights = new Map<number, number>();
+  const measure = (index: number): number => {
+    const known = heights.get(index);
+    if (known !== undefined) return known;
+    let tallest = -1;
+    for (const file of components[index] ?? []) {
+      for (const target of neighboursOf(graph, file)) {
+        const other = componentOf.get(target);
+        if (other !== undefined && other !== index) tallest = Math.max(tallest, measure(other));
+      }
+    }
+    heights.set(index, tallest + 1);
+    return tallest + 1;
+  };
+
+  const byFile = new Map<string, number>();
+  for (const file of [...graph.files].sort()) {
+    const index = componentOf.get(file);
+    if (index !== undefined) byFile.set(file, measure(index));
+  }
+  return byFile;
+};
+
 const evaluateCycles = (rule: CompiledGraphCycleRule, graph: Graph): ReadonlyArray<Violation> => {
   const nodes = graph.files.filter((file) => inScope(rule, file));
   const violations: Array<Violation> = [];