@goodbones/cli 0.1.0-beta.2 → 0.1.0-beta.20

package/build/esm/run.js

@@ -1,34 +1,54 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
-import { baselineOf, coverageOf, coverageShortfalls, decodeBaseline, decodeManifest, EMPTY_BASELINE, evaluateGraph, evaluateMemberSite, evaluateSelectedBindings, evaluateSelectedEdge, evaluateStructure, evaluateSurface, exportRulesSelecting, findManifestFile, fingerprintOf, formatManifestYaml, formatMessage, fractionsOf, hasGraphRules, listSourceFiles, MANIFEST_FILENAMES, MANIFEST_SCHEMA_ID, memberRulesSelecting, readManifestFile, requiredSiblingsOf, rulesSelecting, serializeBaseline, staleEntriesOf, surfaceRulesSelecting, unbaselined, } from "@goodbones/core";
+import { baselineOf, breaches, CONFORMANCE_MEASURES, countedFiles, coverageOf, cyclesIn, decodeBaseline, decodeManifest, EMPTY_BASELINE, evaluateGraph, evaluateMemberSite, evaluateResolvedEdge, evaluateSelectedBindings, evaluateStructure, evaluateSurface, expandAliases, exportRulesSelecting, findManifestFile, fingerprintOf, formatManifestYaml, formatMessage, fractionsOf, globsOf, globToRegExp, hasGraphRules, heightOf, listSourceFiles, makeBaselineFilter, MANIFEST_FILENAMES, MANIFEST_SCHEMA_ID, memberRulesSelecting, readManifestFile, requiredSiblingsOf, residueOf, rulesSelecting, serializeBaseline, slackOf, SNAPSHOT_VERSION, staleEntriesOf, surfaceRulesSelecting, vacancyOf, } from "@goodbones/core";
 import * as Effect from "effect/Effect";
 import * as Result from "effect/Result";
-import { loadPolicyFromFile } from "./config-loader.js";
+import { loadPolicyFromFile, manifestPathOf } from "./config-loader.js";
 import { buildGraph } from "./graph.js";
+import { infer } from "./infer.js";
+import { count, fail, report } from "./output.js";
 import { sourceFactsOf } from "./source-facts.js";
-const fail = (message) => ({ _tag: "CliFailure", message });
-export const collectFindings = (policy, roots) => {
-    const files = listSourceFiles(policy.repoRoot, roots, policy.languages);
+export const collectFindings = (policy, roots, options = {}) => {
+    // A campaign may widen the walk past the packs' extensions; a file only a
+    // campaign asked for is seen by the campaigns and by no other family.
+    const walked = listSourceFiles(policy.repoRoot, roots, policy.languages, policy.campaigns.widenedExtensions(policy));
+    const known = new Set(policy.languages.flatMap((one) => one.extensions));
+    const files = walked.filter((file) => known.has(path.extname(file)));
     const violations = [];
     const unresolved = [];
-    // Each file is parsed at most once, whether the per-file families or the
-    // graph pass asks first.
+    const edges = [];
+    // Each file is read and parsed at most once, whether the per-file
+    // families, the graph pass or a campaign asks first.
+    const texts = new Map();
+    const textOf = (file) => {
+        const cached = texts.get(file);
+        if (cached !== undefined)
+            return cached;
+        const text = readFileSync(path.join(policy.repoRoot, file), "utf8");
+        texts.set(file, text);
+        return text;
+    };
     const parsed = new Map();
     const factsOf = (file) => {
         const cached = parsed.get(file);
         if (cached !== undefined)
             return cached;
-        const facts = sourceFactsOf(policy.repoRoot, file, policy.extractor);
+        const facts = policy.extractor.factsOf(file, textOf(file));
         parsed.set(file, facts);
         return facts;
     };
     // The graph is the whole repository resolved at once — the one question no
     // per-file adapter can ask — and is built only when a rule needs it.
-    if (hasGraphRules(policy.graph)) {
-        for (const violation of evaluateGraph(policy.graph, buildGraph(files, policy.resolver, factsOf))) {
+    const graph = options.graph === true || hasGraphRules(policy.graph)
+        ? buildGraph(files, policy.resolver, factsOf)
+        : null;
+    if (graph !== null && hasGraphRules(policy.graph)) {
+        for (const violation of evaluateGraph(policy.graph, graph))
             violations.push(violation);
-        }
     }
+    // The campaigns, over every walked file, through the same caches.
+    const campaigns = policy.campaigns.evaluate(policy, roots, walked, { textOf, factsOf });
     for (const file of files) {
         for (const violation of evaluateStructure(policy.structure, policy.fileSystem, file)) {
             violations.push(violation);
@@ -54,17 +74,23 @@ export const collectFindings = (policy, roots) => {
         }
         for (const specifier of facts.specifiers) {
             const edge = { importer: file, specifier };
-            const imported = evaluateSelectedEdge(selectedImports, policy.resolver, edge);
-            if (Result.isFailure(imported)) {
-                if (policy.config.resolve.unresolved === "off")
-                    continue;
-                if (policy.ignoreUnresolved.some((pattern) => pattern.test(specifier)))
+            // A file no import rule selects never needs its imports resolved, which
+            // is what keeps resolution off the hot path for the bulk of the repo.
+            if (selectedImports.length > 0) {
+                const resolved = policy.resolver.resolve(file, specifier);
+                if (Result.isFailure(resolved)) {
+                    if (policy.config.resolve.unresolved === "off")
+                        continue;
+                    if (policy.ignoreUnresolved.some((pattern) => pattern.test(specifier)))
+                        continue;
+                    unresolved.push({ file, specifier, detail: resolved.failure.detail });
                     continue;
-                unresolved.push(`${file} → ${specifier} (${imported.failure.detail})`);
-                continue;
+                }
+                edges.push({ importer: file, target: resolved.success });
+                for (const violation of evaluateResolvedEdge(selectedImports, file, resolved.success)) {
+                    violations.push(violation);
+                }
             }
-            for (const violation of imported.success)
-                violations.push(violation);
             const bound = facts.bindings.get(specifier) ?? [];
             const exported = evaluateSelectedBindings(selectedExports, policy.resolver, {
                 ...edge,
@@ -76,7 +102,7 @@ export const collectFindings = (policy, roots) => {
             }
         }
     }
-    return { violations, unresolved, files: files.length };
+    return { violations, campaigns, unresolved, files: files.length, edges, graph };
 };
 const baselinePathOf = (policy) => policy.config.baseline === undefined
     ? null
@@ -92,65 +118,422 @@ const readBaseline = (policy) => {
         return EMPTY_BASELINE;
     }
 };
-const report = (lines) => Effect.sync(() => {
-    for (const line of lines)
-        process.stdout.write(`${line}\n`);
-});
 const describe = (violation) => `  ${violation.file}\n      ${formatMessage(violation)}`;
-export const check = (policy, roots) => Effect.gen(function* () {
-    const findings = collectFindings(policy, roots);
+const COVERAGE_FAMILIES = [
+    "imports",
+    "structure",
+    "members",
+    "surface",
+    "graph",
+];
+const sha256Of = (file) => {
+    try {
+        return createHash("sha256").update(readFileSync(file)).digest("hex");
+    }
+    catch {
+        return "";
+    }
+};
+export const checkReport = (policy, roots, manifestPath) => reportOf(policy, roots, manifestPath, collectFindings(policy, roots)).report;
+// The patterns the policy's `limits.outside` names, alias-expanded, each a
+// subtree.
+const outsideOf = (policy) => globsOf(policy.config.limits?.outside ?? []).map((glob) => globToRegExp(expandAliases(glob, policy.config.aliases ?? {})));
+const measuresOf = (policy, files, edges) => {
+    // Slack is measured over the walked files as well as the edges: an
+    // allowlist that selects no file is vacant, and its entries are reported as
+    // that rather than as lines nobody needs.
+    const { concentration, slack } = slackOf(policy.importRules, edges, files);
+    return {
+        // Residue is a count of files, and counts the ones the limits count. A
+        // node is live or vacant by every file under it, counted or not.
+        residue: residueOf(policy, countedFiles(files, outsideOf(policy))),
+        vacant: vacancyOf(policy.importRules, files),
+        slack,
+        concentration,
+    };
+};
+// A fragment entry is concentrated when it is used at fewer than half the
+// nodes granted it — the text report's threshold, and the ceiling's.
+const isConcentrated = (one) => one.usedAt * 2 < one.of;
+const countsOf = (measures) => ({
+    residue: measures.residue.files.length,
+    vacant: measures.vacant.length,
+    slack: measures.slack.length,
+    concentration: measures.concentration.filter(isConcentrated).length,
+});
+const reportOf = (policy, roots, manifestPath, findings) => {
     const baseline = readBaseline(policy);
-    const reportable = unbaselined(baseline, findings.violations);
     const stale = staleEntriesOf(baseline, findings.violations);
-    yield* report(reportable.map(describe));
-    yield* report(findings.unresolved.map((one) => `  unresolved: ${one}`));
-    const carried = findings.violations.length - reportable.length;
-    yield* report([
+    const { isBaselined } = makeBaselineFilter(baseline);
+    const violations = [
+        ...findings.violations.map((violation) => ({
+            ...violation,
+            fingerprint: fingerprintOf(violation),
+            baselined: isBaselined(violation),
+            ledgered: false,
+        })),
+        // The hits that count: those whose objective is in window for the
+        // sector they fall in.
+        ...policy.campaigns.hitsOf(policy, findings.campaigns).map((hit) => ({
+            ...hit.violation,
+            fingerprint: fingerprintOf(hit.violation),
+            baselined: false,
+            ledgered: hit.ledgered,
+            objective: hit.objective,
+            sector: hit.sector,
+            entry: hit.entry,
+        })),
+    ];
+    const campaigns = policy.campaigns.reportsOf(policy, findings.campaigns);
+    // The floors. A policy states how much of the tree it reaches, per
+    // family; falling under is a policy that quietly stopped covering files.
+    // Both are held over the files the limits count: what `limits.outside`
+    // names is judged by every rule and left out of these numbers.
+    const floors = policy.config.limits?.coverage ?? {};
+    const unreached = policy.config.limits?.unreached ?? {};
+    const files = listSourceFiles(policy.repoRoot, roots, policy.languages);
+    const counted = countedFiles(files, outsideOf(policy));
+    const found = coverageOf(policy, counted);
+    const covered = (family) => family === "structure" ? found.structure.enumerated : found[family].covered;
+    const coverage = Object.fromEntries(COVERAGE_FAMILIES.map((family) => {
+        const floor = floors[family];
+        const ceiling = unreached[family];
+        return [
+            family,
+            {
+                covered: covered(family),
+                total: found.files,
+                ...(floor === undefined ? {} : { floor }),
+                ...(ceiling === undefined ? {} : { ceiling }),
+            },
+        ];
+    }));
+    const shortfalls = shortfallsOf(coverage);
+    const overruns = overrunsOf(coverage);
+    // The ceilings. What no family reaches, what no file is under and what
+    // nothing imports through are each a count the policy may hold itself
+    // to; rising over one is a manifest that quietly widened.
+    const ceilings = policy.config.limits?.conformance ?? {};
+    const measures = measuresOf(policy, files, findings.edges);
+    const counts = countsOf(measures);
+    const conformance = Object.fromEntries(CONFORMANCE_MEASURES.map((measure) => {
+        const ceiling = ceilings[measure];
+        return [measure, { count: counts[measure], ...(ceiling === undefined ? {} : { ceiling }) }];
+    }));
+    const excesses = excessesOf(conformance);
+    const reportable = violations.filter((one) => !one.baselined && !one.ledgered).length;
+    const report = {
+        version: 1,
+        files: findings.files,
+        outside: files.length - counted.length,
+        roots,
+        ok: reportable === 0 &&
+            findings.unresolved.length === 0 &&
+            stale.length === 0 &&
+            shortfalls.length === 0 &&
+            overruns.length === 0 &&
+            excesses.length === 0 &&
+            policy.campaigns.failuresOf(campaigns).length === 0,
+        manifest: {
+            path: path.relative(policy.repoRoot, manifestPath).replaceAll(path.sep, "/"),
+            sha256: sha256Of(manifestPath),
+        },
+        violations,
+        unresolved: findings.unresolved,
+        stale,
+        coverage,
+        conformance,
+        adoption: {
+            unrestricted: policy.adoption.unrestricted,
+            partial: policy.adoption.partial,
+        },
+        campaigns,
+    };
+    return { report, measures, files };
+};
+const shortfallsOf = (coverage) => COVERAGE_FAMILIES.flatMap((family) => {
+    const { covered, floor, total } = coverage[family];
+    const actual = total === 0 ? 1 : covered / total;
+    return floor === undefined || !breaches({ direction: "up", limit: floor, tolerance: 0 }, actual)
+        ? []
+        : [{ family, actual, floor }];
+});
+const overrunsOf = (coverage) => COVERAGE_FAMILIES.flatMap((family) => {
+    const { ceiling, covered, total } = coverage[family];
+    const unreached = total - covered;
+    return ceiling === undefined ||
+        !breaches({ direction: "down", limit: ceiling, tolerance: 0 }, unreached)
+        ? []
+        : [{ family, unreached, ceiling }];
+});
+const excessesOf = (conformance) => CONFORMANCE_MEASURES.flatMap((measure) => {
+    const { ceiling, count } = conformance[measure];
+    return ceiling === undefined ||
+        !breaches({ direction: "down", limit: ceiling, tolerance: 0 }, count)
+        ? []
+        : [{ measure, count, ceiling }];
+});
+const failureOf = (policy, report, shortfalls) => {
+    if (report.stale.length > 0)
+        return fail("stale baseline entries");
+    const [campaignFailure] = policy.campaigns.failuresOf(report.campaigns);
+    if (campaignFailure !== undefined)
+        return fail(campaignFailure);
+    if (shortfalls.length > 0)
+        return fail("coverage below floor");
+    if (overrunsOf(report.coverage).length > 0)
+        return fail("unreached above ceiling");
+    if (excessesOf(report.conformance).length > 0)
+        return fail("conformance above ceiling");
+    if (report.ok)
+        return null;
+    return fail("architecture violations");
+};
+// What each measure counts, as the failure names it.
+const MEASURE_NOUNS = {
+    residue: ["file no family reaches", "files no family reaches"],
+    vacant: ["node no file is under", "nodes no file is under"],
+    slack: ["allowance nothing imports through", "allowances nothing imports through"],
+    concentration: [
+        "allowance used at fewer than half the nodes granted",
+        "allowances used at fewer than half the nodes granted",
+    ],
+};
+const describeExcess = (one) => {
+    const [singular, plural] = MEASURE_NOUNS[one.measure];
+    return `  ${one.measure}: ${count(one.count, singular, plural)}, ceiling ${String(one.ceiling)}`;
+};
+const renderCampaigns = (policy, report) => policy.campaigns.renderReports(report.campaigns, report.violations.flatMap((one) => one.kind === "campaign" &&
+    one.objective !== undefined &&
+    one.sector !== undefined &&
+    one.entry !== undefined
+    ? [
+        {
+            violation: one,
+            objective: one.objective,
+            sector: one.sector,
+            entry: one.entry,
+            ledgered: one.ledgered,
+        },
+    ]
+    : []));
+const renderText = (policy, report) => {
+    const reportable = report.violations.filter((one) => one.kind !== "campaign" && !one.baselined);
+    const carried = report.violations.filter((one) => one.kind !== "campaign").length - reportable.length;
+    const shortfalls = shortfallsOf(report.coverage);
+    const overruns = overrunsOf(report.coverage);
+    const excesses = excessesOf(report.conformance);
+    return [
+        ...reportable.map(describe),
+        ...report.unresolved.map((one) => `  unresolved: ${one.file} → ${one.specifier} (${one.detail})`),
         "",
-        `${String(findings.files)} files, ${String(reportable.length)} violations` +
+        `${String(report.files)} files, ${String(reportable.length)} violations` +
             (carried > 0 ? `, ${String(carried)} carried by the baseline` : ""),
-    ]);
-    if (stale.length > 0) {
         // The ratchet: a fixed violation must leave the baseline, or the floor
         // never rises and the file stops describing anything real.
-        yield* report([
-            "",
-            `${String(stale.length)} baseline entries no longer fire. The code was fixed; prune them:`,
-            ...stale.map((entry) => `  ${entry}`),
-            "",
-            "  architecture baseline    # rewrites the file from what still fires",
-        ]);
-        return yield* Effect.fail(fail("stale baseline entries"));
-    }
-    // The floors. A policy states how much of the tree it reaches, per
-    // family; falling under is a policy that quietly stopped covering files.
-    const floors = policy.config.limits?.coverage;
-    const shortfalls = floors === undefined
-        ? []
-        : coverageShortfalls(coverageOf(policy, listSourceFiles(policy.repoRoot, roots, policy.languages)), floors);
-    if (shortfalls.length > 0) {
-        yield* report([
-            "",
-            "coverage is below the floor the policy states for itself:",
-            ...shortfalls.map((one) => `  ${one.family}: ${percent(one.actual)} covered, floor ${percent(one.floor)}`),
-            "",
-            "  architecture coverage    # which files no rule reaches",
-        ]);
-        return yield* Effect.fail(fail("coverage below floor"));
-    }
-    if (reportable.length > 0 || findings.unresolved.length > 0) {
-        return yield* Effect.fail(fail("architecture violations"));
-    }
+        ...(report.stale.length === 0
+            ? []
+            : [
+                "",
+                `${String(report.stale.length)} baseline entries no longer fire. The code was fixed; prune them:`,
+                ...report.stale.map((entry) => `  ${entry}`),
+                "",
+                "  architecture baseline    # rewrites the file from what still fires",
+            ]),
+        ...(shortfalls.length === 0
+            ? []
+            : [
+                "",
+                "coverage is below the floor the policy states for itself:",
+                ...shortfalls.map((one) => `  ${one.family}: ${percent(one.actual)} covered, floor ${percent(one.floor)}`),
+                "",
+                "  architecture coverage    # which files no rule reaches",
+            ]),
+        ...(overruns.length === 0
+            ? []
+            : [
+                "",
+                "more files are unreached than the ceiling the policy states for itself:",
+                ...overruns.map((one) => `  ${one.family}: ${count(one.unreached, "file")} unreached, ceiling ${String(one.ceiling)}`),
+                "",
+                "  architecture coverage    # which files no rule reaches",
+            ]),
+        ...(excesses.length === 0
+            ? []
+            : [
+                "",
+                "conformance is above the ceiling the policy states for itself:",
+                ...excesses.map(describeExcess),
+                "",
+                "  architecture conformance    # which files, nodes and allowances",
+            ]),
+        ...renderCampaigns(policy, report),
+    ];
+};
+export const check = (policy, roots, options) => Effect.gen(function* () {
+    const report_ = checkReport(policy, roots, options.manifestPath);
+    // JSON is one object on stdout and nothing else there; the failure, when
+    // there is one, is a sentence on stderr and the exit code, as in text.
+    yield* report(options.format === "json" ? [JSON.stringify(report_, null, 2)] : renderText(policy, report_));
+    const failure = failureOf(policy, report_, shortfallsOf(report_.coverage));
+    if (failure !== null)
+        return yield* Effect.fail(failure);
 });
 const percent = (fraction) => `${String(Math.floor(fraction * 100))}%`;
+// The conformance snapshot: `check`'s report grown with what no family
+// reaches, what the allowlists permit and nothing uses, the cycle count and
+// the size of the debt — the whole distance between the tree and the
+// manifest, as one document another run can be compared against. Its shape
+// is the core's `Snapshot`, and the schema published beside the manifest's.
+export const snapshotOf = (policy, roots, manifestPath) => {
+    const findings = collectFindings(policy, roots, { graph: true });
+    const { files, measures, report: report_ } = reportOf(policy, roots, manifestPath, findings);
+    const graph = findings.graph ?? { files, edges: new Map() };
+    const heights = heightOf(graph);
+    // Leaf edges first. A violation names a target when it is about an edge;
+    // the cost of fixing it is roughly how much of the graph stands beneath
+    // that target, so the ones nearest the ground come first and a reader
+    // starting at the top of the list is starting where a fix stays local.
+    // Ties keep the fingerprint order, so the list is the same on every run.
+    const heightOfViolation = (one) => heights.get(one.subject ?? "") ?? heights.get(one.file) ?? 0;
+    const violations = [...report_.violations].sort((left, right) => {
+        const byHeight = heightOfViolation(left) - heightOfViolation(right);
+        return byHeight !== 0 ? byHeight : left.fingerprint.localeCompare(right.fingerprint);
+    });
+    const campaigns = policy.campaigns.snapshotOf(policy, findings.campaigns);
+    return {
+        version: SNAPSHOT_VERSION,
+        manifest: report_.manifest,
+        roots: report_.roots,
+        files: report_.files,
+        outside: report_.outside,
+        ok: report_.ok,
+        coverage: report_.coverage,
+        conformance: report_.conformance,
+        residue: measures.residue,
+        vacant: measures.vacant,
+        violations,
+        unresolved: report_.unresolved,
+        stale: report_.stale,
+        baseline: { size: readBaseline(policy).entries.length },
+        cycles: cyclesIn(graph).length,
+        slack: measures.slack,
+        concentration: measures.concentration,
+        adoption: report_.adoption,
+        campaigns,
+    };
+};
+// The unreached ceiling beside a family's row, and the ratchet's nudge when
+// the count has fallen under it: a ceiling is lowered by hand.
+const unreachedMark = (covered, total, ceiling) => {
+    if (ceiling === undefined)
+        return "";
+    const left = total - covered;
+    if (left > ceiling)
+        return `  ${String(left)} unreached > ${String(ceiling)} ✗`;
+    return `  ${String(left)} unreached ≤ ${String(ceiling)} ✓${left < ceiling ? `, lower it to ${String(left)}` : ""}`;
+};
+const outsideNote = (outside) => outside === 0 ? "" : `, ${count(outside, "file")} outside the limits`;
+const renderSnapshot = (policy, snapshot) => {
+    const reportable = snapshot.violations.filter((one) => !one.baselined && !one.ledgered);
+    const carried = snapshot.violations.length - reportable.length;
+    const row = (family) => {
+        const { ceiling, covered, floor, total } = snapshot.coverage[family];
+        const fraction = total === 0 ? 1 : covered / total;
+        const mark = floor === undefined
+            ? ""
+            : fraction >= floor
+                ? `  ≥ ${percent(floor)} ✓`
+                : `  < ${percent(floor)} ✗`;
+        return `  ${family.padEnd(10)} ${String(covered).padStart(5)}/${String(total)}  ${percent(fraction).padStart(4)}${mark}${unreachedMark(covered, total, ceiling)}`;
+    };
+    const section = (title, lines) => [
+        "",
+        title,
+        ...lines,
+    ];
+    const vacantWidth = Math.max(0, ...snapshot.vacant.map((one) => one.node.length));
+    // The document carries every partly-used fragment entry; the text shows
+    // the ones concentrated enough to read as a per-file rule written wide.
+    const concentrated = snapshot.concentration.filter(isConcentrated);
+    // The ceiling beside each measure that has one, and the ratchet's nudge
+    // when the count has fallen under it: a ceiling is lowered by hand.
+    const ceilingMark = (measure) => {
+        const { ceiling, count: actual } = snapshot.conformance[measure];
+        if (ceiling === undefined)
+            return "";
+        if (actual > ceiling)
+            return `  > ${String(ceiling)} ✗`;
+        return `  ≤ ${String(ceiling)} ✓${actual < ceiling ? `, lower it to ${String(actual)}` : ""}`;
+    };
+    return [
+        `${String(snapshot.files)} files under ${snapshot.roots.join(", ")}, against ${snapshot.manifest.path}${outsideNote(snapshot.outside)}`,
+        ...section("coverage", COVERAGE_FAMILIES.map(row)),
+        ...section(`residue: ${count(snapshot.residue.files.length, "file")} no family reaches` +
+            (snapshot.residue.folders.length === 0
+                ? ""
+                : `, ${count(snapshot.residue.folders.length, "folder")} wholly`) +
+            ceilingMark("residue"), [
+            ...snapshot.residue.folders.map((folder) => `  ${folder}/`),
+            ...snapshot.residue.files
+                .filter((file) => !snapshot.residue.folders.some((folder) => file.startsWith(`${folder}/`)))
+                .map((file) => `  ${file}`),
+        ]),
+        ...section(`vacant: ${count(snapshot.vacant.length, "node")} ${snapshot.vacant.length === 1 ? "selects" : "select"} no file` +
+            ceilingMark("vacant"), snapshot.vacant.map((one) => `  ${one.node.padEnd(vacantWidth)}  ${count(one.allowances, "allowance")}`)),
+        ...section(`violations: ${count(reportable.length, "reportable")}` +
+            (carried > 0 ? `, ${String(carried)} carried by the baseline or a ledger` : "") +
+            (snapshot.stale.length > 0
+                ? `, ${count(snapshot.stale.length, "stale entry", "stale entries")}`
+                : "") +
+            (reportable.length > 0 ? " — nearest the ground first" : ""), reportable.map(describe)),
+        ...(snapshot.unresolved.length === 0
+            ? []
+            : section(`unresolved: ${count(snapshot.unresolved.length, "import")} no rule can police`, snapshot.unresolved.map((one) => `  ${one.file} → ${one.specifier} (${one.detail})`))),
+        ...section(`slack: ${count(snapshot.slack.length, "allowance")} nothing imports through` +
+            ceilingMark("slack"), snapshot.slack.map((one) => `  ${one.node}: ${one.kind} ${JSON.stringify(one.entry)}` +
+            (one.of === undefined ? "" : `  (via use, at ${count(one.of, "node")})`))),
+        ...(concentrated.length === 0 && snapshot.conformance.concentration.ceiling === undefined
+            ? []
+            : section(`concentrated: ${count(concentrated.length, "allowance")} used at fewer than half the nodes granted` +
+                ceilingMark("concentration"), concentrated.map((one) => `  ${one.fragment}: ${one.kind} ${JSON.stringify(one.entry)}  used at ${String(one.usedAt)} of ${count(one.of, "node")}`))),
+        ...(snapshot.campaigns.length === 0
+            ? []
+            : section(`campaigns: ${count(snapshot.campaigns.length, "campaign")}` +
+                (snapshot.campaigns.some((one) => one.stalled)
+                    ? `, ${count(snapshot.campaigns.filter((one) => one.stalled).length, "stalled", "stalled")}`
+                    : "") +
+                (snapshot.campaigns.some((one) => one.complete && one.ledgered)
+                    ? `, ${count(snapshot.campaigns.filter((one) => one.complete && one.ledgered).length, "complete", "complete")}`
+                    : ""), policy.campaigns.renderRows(snapshot.campaigns))),
+        "",
+        `cycles: ${String(snapshot.cycles)}`,
+        `baseline: ${count(snapshot.baseline.size, "entry", "entries")}`,
+        `adoption: ${count(snapshot.adoption.unrestricted.length, "unrestricted tier")}, ${count(snapshot.adoption.partial.length, "partial tier")}`,
+    ];
+};
+// The report of the tree against the manifest. Unlike `check`, it never
+// fails: it is a measurement, and the manifest it measures against may be one
+// the tree was never expected to satisfy yet — `--against` names a target.
+// `ok` in the document says what `check` would have done.
+export const conformance = (policy, roots, options) => Effect.gen(function* () {
+    const snapshot = snapshotOf(policy, roots, options.manifestPath);
+    yield* report(options.format === "json"
+        ? [JSON.stringify(snapshot, null, 2)]
+        : renderSnapshot(policy, snapshot));
+});
 // How much of the tree the policy reaches. A probe proves a rule can fire;
 // this is whether the files are there to fire on. Reported per family, with the
 // adoption backlog — the tiers that said "not tightened yet" — beneath it.
 export const coverage = (policy, roots) => Effect.gen(function* () {
-    const files = listSourceFiles(policy.repoRoot, roots, policy.languages);
+    // The limits are held over the files they count, so that is what the
+    // rows are over: what `limits.outside` names is said, and left out.
+    const walked = listSourceFiles(policy.repoRoot, roots, policy.languages);
+    const files = countedFiles(walked, outsideOf(policy));
     const found = coverageOf(policy, files);
     const fractions = fractionsOf(found);
     const floors = policy.config.limits?.coverage ?? {};
+    const ceilings = policy.config.limits?.unreached ?? {};
     const row = (family, covered, note) => {
         const floor = floors[family];
         const mark = floor === undefined
@@ -158,10 +541,10 @@ export const coverage = (policy, roots) => Effect.gen(function* () {
             : fractions[family] >= floor
                 ? `  ≥ ${percent(floor)} ✓`
                 : `  < ${percent(floor)} ✗`;
-        return `  ${family.padEnd(10)} ${String(covered).padStart(5)}/${String(found.files)}  ${percent(fractions[family]).padStart(4)}  ${note}${mark}`;
+        return `  ${family.padEnd(10)} ${String(covered).padStart(5)}/${String(found.files)}  ${percent(fractions[family]).padStart(4)}  ${note}${mark}${unreachedMark(covered, found.files, ceilings[family])}`;
     };
     yield* report([
-        `${String(found.files)} files under ${roots.join(", ")}`,
+        `${String(walked.length)} files under ${roots.join(", ")}${outsideNote(walked.length - files.length)}`,
         "",
         row("imports", found.imports.covered, "under an import allowlist"),
         row("structure", found.structure.enumerated, `in an enumerated folder (${String(found.structure.open)} in an open one, ${String(found.structure.total - found.structure.enumerated - found.structure.open)} in none)`),
@@ -190,7 +573,7 @@ export const writeBaseline = (policy, roots) => Effect.gen(function* () {
 });
 // The question a tree config makes harder to answer than a flat one: given a
 // file, what governs it? A flat config you grep; a tree you have to walk.
-export const explain = (policy, file) => Effect.gen(function* () {
+export const explain = (policy, file, roots = ["packages"]) => Effect.gen(function* () {
     const relative = path.relative(policy.repoRoot, path.resolve(policy.repoRoot, file));
     const selected = rulesSelecting(policy.importRules, relative);
     // An allowlist rule names no `to` — it fires when the target matches none of
@@ -204,7 +587,7 @@ export const explain = (policy, file) => Effect.gen(function* () {
     const governing = policy.structure.folders.filter((rule) => rule.folder.some((pattern) => pattern.test(path.dirname(relative))));
     const naming = policy.structure.naming.filter((rule) => rule.file.some((pattern) => pattern.test(relative)) &&
         !rule.fileNot.some((pattern) => pattern.test(relative)));
-    const firstSentence = (message) => `${message.split(". ")[0] ?? message}.`;
+    const firstSentence = (message) => `${(message.split(". ")[0] ?? message).replace(/\.$/, "")}.`;
     const named = (rule) => `    ${rule.name} — ${firstSentence(rule.message)}`;
     // The families beyond imports and structure: which rules of each speak to
     // this file at all. What they are evaluated against is `facts`' answer.
@@ -222,6 +605,9 @@ export const explain = (policy, file) => Effect.gen(function* () {
             .map((rule) => `${named(rule)} (reach)`),
     ];
     const section = (title, lines) => lines.length === 0 ? [] : ["", title, ...lines];
+    // The campaigns selecting the file, evaluated over their files only
+    // when one does: a sector's phase is derived from all of them.
+    const campaignLines = policy.campaigns.explainLines(policy, relative, () => collectFindings(policy, roots).campaigns);
     yield* report([
         relative,
         "",
@@ -251,6 +637,7 @@ export const explain = (policy, file) => Effect.gen(function* () {
         ...section("  vocabulary (members):", vocabulary.map(named)),
         ...section("  may export (surface):", surface.map(named)),
         ...section("  graph:", graph),
+        ...section("  campaigns:", campaignLines),
     ]);
 });
 // The other half of `explain`. `explain` says which rules select a file; this
@@ -329,12 +716,35 @@ resolve:
 baseline: .architecture-baseline.json
 
 # Ceilings on how many tiers may say "not tightened yet". At zero, raising one
-# is a line in this file a reviewer sees.
+# is a line in this file a reviewer sees. The same block takes coverage floors
+# and ceilings on what \`architecture conformance\` measures, once there are
+# numbers to write.
 # https://dataquail.github.io/goodbones/architecture-rules/enforcement/adoption/
 limits:
   unrestricted: 0
   partial: 0
 
+# Refactors the repository is running, each an object: objectives (a
+# detector with a ledger under \`.architecture-campaigns/\` of every place the
+# pattern still occurs), over sectors the code births through a perimeter,
+# through phases toward an end. Fill one in, then
+# \`architecture objectives clear <id>\` to write its ledgers.
+# https://dataquail.github.io/goodbones/architecture-rules/manifest/campaigns/
+# campaigns:
+#   js-to-ts:
+#     why: The strict tsconfig cannot land while any src file is JavaScript.
+#     how: Rename to .ts, add types at the module boundary, leave the body alone.
+#     scope: { path: "src/**", extensions: [.js, .jsx] }
+#     perimeter: file
+#     objectives:
+#       is-ts:
+#         intent: A JavaScript file is one the strict compiler never checks.
+#         holdout: file
+#         match: { path: { file: "\\\\.(js|jsx)$" } }
+#         probes: { fires: [{ path: src/legacy/util.js }], ignores: [{ path: src/util.ts }] }
+#     staleAfter: 14d
+#     onComplete: remove
+
 # The repository. One open root, reaching itself and the runtime; run
 # \`architecture check\` to see what else it reaches, and write that down here.
 # https://dataquail.github.io/goodbones/architecture-rules/manifest/imports/
@@ -403,45 +813,112 @@ export const migrate = (repoRoot, configFilename) => Effect.gen(function* () {
         `Then delete ${path.basename(from)}: a repository with two manifests is refused.`,
     ]);
 });
+// The campaign commands, answered by the family the host was composed with:
+// `campaigns` alone is the status table, `status --changed` the nudge,
+// `attest` and `note` write a sector's record, `history` replays the ledgers;
+// `objectives clear` and `objectives concede` write the ledgers. Without
+// `@goodbones/campaigns` installed, each says what to install.
+const verbContext = (policy, defaultRoots, argv, configFilename) => ({
+    policy,
+    defaultRoots,
+    argv,
+    evaluate: (roots) => collectFindings(policy, roots).campaigns,
+    reload: (repoRoot) => loadPolicyFromFile(repoRoot, configFilename),
+    manifestPath: manifestPathOf(policy.repoRoot, configFilename),
+});
+export const objectives = (policy, defaultRoots, argv) => policy.campaigns.objectives(verbContext(policy, defaultRoots, argv));
+export const campaigns = (policy, defaultRoots, argv, configFilename) => policy.campaigns.campaigns(verbContext(policy, defaultRoots, argv, configFilename));
+// The commands that judge a campaign, and so ask its report source.
+const READS_REPORTS = new Set([
+    "check",
+    "conformance",
+    "baseline",
+    "campaigns",
+    "objectives",
+    "explain",
+]);
 export const run = (repoRoot, argv, 
 // From ARCHITECTURE_CONFIG. Absent, the manifest is discovered by name.
 configFilename) => Effect.gen(function* () {
     const [command = "check", ...rest] = argv;
-    // The two commands that write a manifest rather than read one.
+    // The three commands that write a manifest rather than read one.
     if (command === "init")
         return yield* init(repoRoot);
     if (command === "migrate")
         return yield* migrate(repoRoot, configFilename);
+    if (command === "infer") {
+        yield* infer(repoRoot, rest, configFilename);
+        return;
+    }
+    // `--against <file>` measures the tree against a manifest other than the
+    // repository's own — the target the team is moving toward. Only
+    // `conformance` takes it: a `check` against a manifest nobody is held to
+    // yet would fail for no one's benefit.
+    const againstAt = rest.indexOf("--against");
+    const against = againstAt === -1 ? undefined : rest[againstAt + 1];
+    if (againstAt !== -1 && (against === undefined || against.startsWith("--"))) {
+        return yield* Effect.fail(fail("--against needs a manifest path"));
+    }
+    if (against !== undefined && command !== "conformance") {
+        return yield* Effect.fail(fail(`--against is a \`conformance\` flag; ${command} does not take it`));
+    }
+    const manifestFilename = against ?? configFilename;
     const policy = yield* Effect.tryPromise({
-        try: () => loadPolicyFromFile(repoRoot, configFilename),
+        try: () => loadPolicyFromFile(repoRoot, manifestFilename),
         catch: (cause) => fail(String(cause)),
     });
     yield* Effect.sync(() => {
         for (const notice of policy.notices)
             process.stderr.write(`deprecated: ${notice}\n`);
     });
-    const roots = rest.length > 0 ? rest : ["packages"];
+    // Every `report` a campaign names is read now, before any file asks:
+    // a term's several commands run at once rather than one after another
+    // the first time a campaign selects a file. What cannot be read is kept
+    // for the campaign to report; a report that does not parse is refused.
+    if (READS_REPORTS.has(command)) {
+        yield* Effect.tryPromise({
+            try: () => policy.campaigns.readReports(policy),
+            catch: (cause) => fail(String(cause)),
+        });
+    }
+    const json = rest.includes("--json");
+    const positional = rest.filter((argument, index) => argument !== "--json" &&
+        argument !== "--against" &&
+        (againstAt === -1 || index !== againstAt + 1));
+    const roots = positional.length > 0 ? positional : ["packages"];
     switch (command) {
+        case "campaigns":
+            return yield* campaigns(policy, ["packages"], rest, configFilename);
+        case "objectives":
+            return yield* objectives(policy, ["packages"], rest);
         case "check":
-            return yield* check(policy, roots);
+            return yield* check(policy, roots, {
+                format: json ? "json" : "text",
+                manifestPath: manifestPathOf(repoRoot, configFilename),
+            });
+        case "conformance":
+            return yield* conformance(policy, roots, {
+                format: json ? "json" : "text",
+                manifestPath: manifestPathOf(repoRoot, manifestFilename),
+            });
         case "baseline":
             return yield* writeBaseline(policy, roots);
         case "explain": {
-            const [file] = rest;
+            const [file, ...explainRoots] = positional;
             if (file === undefined)
                 return yield* Effect.fail(fail("explain needs a file path"));
-            return yield* explain(policy, file);
+            return yield* explain(policy, file, explainRoots.length > 0 ? explainRoots : ["packages"]);
         }
         case "coverage":
             return yield* coverage(policy, roots);
         case "facts": {
-            const [file] = rest.filter((argument) => argument !== "--json");
+            const [file] = positional;
             if (file === undefined)
                 return yield* Effect.fail(fail("facts needs a file path"));
-            return yield* facts(policy, file, rest.includes("--json") ? "json" : "text");
+            return yield* facts(policy, file, json ? "json" : "text");
         }
         default:
-            return yield* Effect.fail(fail(`unknown command "${command}". Try: check | baseline | coverage | explain <file> | facts <file> [--json] | init | migrate`));
+            return yield* Effect.fail(fail(`unknown command "${command}". Try: check [--json] | conformance [--json] [--against <manifest>] | baseline | campaigns [status --changed | attest | note | history] | objectives [clear | concede] | coverage | explain <file> | facts <file> [--json] | init | infer | migrate`));
     }
 });
 export const fingerprint = fingerprintOf;