@goodbones/cli 0.1.0-beta.14 → 0.1.0-beta.16

package/src/run.ts

@@ -28,7 +28,10 @@ import {
   renderCampaignRows,
   renderHistory,
   renderNudge,
+  renderSectorView,
   reportSpecsOf,
+  sectorMovesOf,
+  sectorViewOf,
   snapshotCampaignsOf,
   valueOfParts,
   widenedExtensions,
@@ -39,6 +42,7 @@ import {
   breaches,
   CONFORMANCE_MEASURES,
   type ConformanceMeasure,
+  countedFiles,
   type CoverageFamily,
   coverageOf,
   cyclesIn,
@@ -51,12 +55,15 @@ import {
   evaluateSelectedBindings,
   evaluateStructure,
   evaluateSurface,
+  expandAliases,
   exportRulesSelecting,
   findManifestFile,
   fingerprintOf,
   formatManifestYaml,
   formatMessage,
   fractionsOf,
+  globsOf,
+  globToRegExp,
   type Graph,
   hasGraphRules,
   heightOf,
@@ -287,10 +294,18 @@ export type ReportedViolation = Violation & {
   readonly entry?: string;
 };
 
+// Per family: the files it reaches of those the limits count, the floor the
+// manifest's `limits.coverage` states as a fraction, and the ceiling its
+// `limits.unreached` states on the files left over.
 export type CoverageReport = Readonly<
   Record<
     CoverageFamily,
-    { readonly covered: number; readonly total: number; readonly floor?: number }
+    {
+      readonly covered: number;
+      readonly total: number;
+      readonly floor?: number;
+      readonly ceiling?: number;
+    }
   >
 >;
 
@@ -304,6 +319,9 @@ export type ConformanceReport = Readonly<
 export type CheckReport = {
   readonly version: 1;
   readonly files: number;
+  // Walked files under the manifest's `limits.outside`: judged by every
+  // rule, and left out of `coverage` and of the residue.
+  readonly outside: number;
   readonly roots: ReadonlyArray<string>;
   readonly ok: boolean;
   // The file the policy was read from, repo-relative, and a hash of its
@@ -355,6 +373,13 @@ type Measures = {
   readonly concentration: ReturnType<typeof slackOf>["concentration"];
 };
 
+// The patterns the policy's `limits.outside` names, alias-expanded, each a
+// subtree.
+const outsideOf = (policy: LoadedPolicy): ReadonlyArray<RegExp> =>
+  globsOf(policy.config.limits?.outside ?? []).map((glob) =>
+    globToRegExp(expandAliases(glob, policy.config.aliases ?? {})),
+  );
+
 const measuresOf = (
   policy: LoadedPolicy,
   files: ReadonlyArray<string>,
@@ -365,7 +390,9 @@ const measuresOf = (
   // that rather than as lines nobody needs.
   const { concentration, slack } = slackOf(policy.importRules, edges, files);
   return {
-    residue: residueOf(policy, files),
+    // 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,
@@ -423,25 +450,32 @@ const reportOf = (
 
   // 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 found = coverageOf(policy, files);
+  const counted = countedFiles(files, outsideOf(policy));
+  const found = coverageOf(policy, counted);
   const covered = (family: CoverageFamily): number =>
     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 }),
         },
       ];
     }),
   ) as CoverageReport;
   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
@@ -461,12 +495,14 @@ const reportOf = (
   const report: CheckReport = {
     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 &&
       campaignFailuresOf(campaigns).length === 0,
     manifest: {
@@ -505,6 +541,25 @@ const shortfallsOf = (coverage: CoverageReport): ReadonlyArray<Shortfall> =>
       : [{ family, actual, floor }];
   });
 
+// A family leaving more files unreached than the ceiling the policy states
+// for it. A count, so deleting files a rule reached changes nothing here,
+// where it lowers the fraction a floor holds.
+type Overrun = {
+  readonly family: CoverageFamily;
+  readonly unreached: number;
+  readonly ceiling: number;
+};
+
+const overrunsOf = (coverage: CoverageReport): ReadonlyArray<Overrun> =>
+  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 }];
+  });
+
 // A conformance measure over the ceiling the policy states for it.
 type Excess = {
   readonly measure: ConformanceMeasure;
@@ -529,6 +584,7 @@ const failureOf = (
   const [campaignFailure] = campaignFailuresOf(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");
@@ -576,6 +632,7 @@ const renderText = (report: CheckReport): ReadonlyArray<string> => {
   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),
@@ -607,6 +664,18 @@ const renderText = (report: CheckReport): ReadonlyArray<string> => {
           "",
           "  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
       ? []
       : [
@@ -680,6 +749,7 @@ export const snapshotOf = (
     manifest: report_.manifest,
     roots: report_.roots,
     files: report_.files,
+    outside: report_.outside,
     ok: report_.ok,
     coverage: report_.coverage,
     conformance: report_.conformance,
@@ -697,11 +767,23 @@ export const snapshotOf = (
   };
 };
 
+// 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: number, total: number, ceiling: number | undefined): string => {
+  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: number): string =>
+  outside === 0 ? "" : `, ${count(outside, "file")} outside the limits`;
+
 const renderSnapshot = (snapshot: Snapshot): ReadonlyArray<string> => {
   const reportable = snapshot.violations.filter((one) => !one.baselined && !one.ledgered);
   const carried = snapshot.violations.length - reportable.length;
   const row = (family: CoverageFamily): string => {
-    const { covered, floor, total } = snapshot.coverage[family];
+    const { ceiling, covered, floor, total } = snapshot.coverage[family];
     const fraction = total === 0 ? 1 : covered / total;
     const mark =
       floor === undefined
@@ -709,7 +791,7 @@ const renderSnapshot = (snapshot: Snapshot): ReadonlyArray<string> => {
         : fraction >= floor
           ? `  ≥ ${percent(floor)} ✓`
           : `  < ${percent(floor)} ✗`;
-    return `  ${family.padEnd(10)} ${String(covered).padStart(5)}/${String(total)}  ${percent(fraction).padStart(4)}${mark}`;
+    return `  ${family.padEnd(10)} ${String(covered).padStart(5)}/${String(total)}  ${percent(fraction).padStart(4)}${mark}${unreachedMark(covered, total, ceiling)}`;
   };
   const section = (title: string, lines: ReadonlyArray<string>): ReadonlyArray<string> => [
     "",
@@ -730,7 +812,7 @@ const renderSnapshot = (snapshot: Snapshot): ReadonlyArray<string> => {
   };
 
   return [
-    `${String(snapshot.files)} files under ${snapshot.roots.join(", ")}, against ${snapshot.manifest.path}`,
+    `${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` +
@@ -833,10 +915,14 @@ export const coverage = (
   roots: ReadonlyArray<string>,
 ): Effect.Effect<void, CliFailure> =>
   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: keyof typeof fractions, covered: number, note: string): string => {
       const floor = floors[family];
       const mark =
@@ -845,11 +931,11 @@ export const coverage = (
           : 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(
@@ -987,14 +1073,14 @@ export const explain = (
                 ? `${String(parts.of)} of ${String(parts.per)} here`
                 : `${String(valueOfParts(measure, parts))} here`;
             return [
-              `      ${objective.name} — ${firstSentence(objective.why ?? objective.message)} (measure, ${objective.direction}; ${here})`,
+              `      ${objective.name} — ${firstSentence(objective.intent ?? objective.message)} (measure, ${objective.direction}; ${here})`,
             ];
           }
           const table = explainObjective(objective, input);
           if (table.length === 0) return [];
           const fired = table.length > 0 && table.every((line) => line.answer);
           return [
-            `      ${objective.name} — ${firstSentence(objective.why ?? objective.message)} (${objective.holdout}; ${fired ? "fires here" : "no hit"})`,
+            `      ${objective.name} — ${firstSentence(objective.intent ?? objective.message)} (${objective.holdout}; ${fired ? "fires here" : "no hit"})`,
             ...table.map(
               (line) =>
                 `          ${line.answer ? "✓" : "✗"} ${line.term}${line.count === undefined ? "" : ` (${String(line.count)})`}`,
@@ -1156,6 +1242,7 @@ limits:
 #     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 }] }
@@ -1380,7 +1467,8 @@ const campaignFor = (
       : Result.succeed(found);
   }
   const [only] = campaignsOf(policy).campaignRules;
-  if (campaignsOf(policy).campaignRules.length === 1 && only !== undefined) return Result.succeed(only);
+  if (campaignsOf(policy).campaignRules.length === 1 && only !== undefined)
+    return Result.succeed(only);
   return Result.fail(
     `this policy declares ${String(campaignsOf(policy).campaignRules.length)} campaigns; say which with --campaign <id>.`,
   );
@@ -1424,7 +1512,9 @@ export const objectives = (
         const targets =
           parsed.target === null
             ? campaignsOf(policy).campaignRules
-            : campaignsOf(policy).campaignRules.filter((rule) => rule.id === parsed.target?.campaign);
+            : campaignsOf(policy).campaignRules.filter(
+                (rule) => rule.id === parsed.target?.campaign,
+              );
         const by = authorOf(flagOf(argv, "--by")) ?? "unknown";
         const all = evaluations();
         const lines: Array<string> = [];
@@ -1439,6 +1529,9 @@ export const objectives = (
             try: () => clear(policy, evaluation, only, by),
             catch: (cause) => fail(String(cause)),
           });
+          // Where each sector went, read off the ledgers as they stood: a
+          // clear of one objective places no sector, so it says nothing.
+          const moves = only === null ? sectorMovesOf(policy, evaluation) : [];
           for (const outcome of outcomes) {
             const parts = [
               ...(outcome.entered.length > 0
@@ -1471,6 +1564,16 @@ export const objectives = (
                         .join(", ")})`,
                     ]
                   : []),
+                ...(outcome.measure.grown.length > 0
+                  ? [
+                      `${count(outcome.measure.grown.length, "sector")} grown (${outcome.measure.grown
+                        .map(
+                          (one) =>
+                            `${one.sector} ${String(one.from)} → ${String(one.to)}, ${one.phase === null ? "measured, not held" : `as ${one.phase} expects`}`,
+                        )
+                        .join(", ")})`,
+                    ]
+                  : []),
                 ...(outcome.closed > 0 ? [`${count(outcome.closed, "sector")} closed`] : []),
                 ...(outcome.rebaselined.length > 0
                   ? [
@@ -1487,6 +1590,14 @@ export const objectives = (
               `${outcome.campaign}/${outcome.objective}: ${parts.length === 0 ? "nothing to clear" : parts.join(", ")}; ${count(outcome.left, "holdout")} left.`,
             );
           }
+          for (const move of moves) {
+            lines.push(
+              `${move.campaign}: ${move.sector} ${move.back ? "went back" : "moved"} ${move.from ?? "done"} → ${move.to ?? "done"}` +
+                (move.passed.length === 0
+                  ? "."
+                  : `, passing ${move.passed.join(", ")} in the same clear: nothing there was ever counted for it.`),
+            );
+          }
         }
         return yield* report(lines);
       }
@@ -1498,7 +1609,9 @@ export const objectives = (
             ),
           );
         }
-        const rule = campaignsOf(policy).campaignRules.find((one) => one.id === parsed.target?.campaign);
+        const rule = campaignsOf(policy).campaignRules.find(
+          (one) => one.id === parsed.target?.campaign,
+        );
         if (rule === undefined)
           return yield* Effect.fail(fail(`no campaign is named "${parsed.target.campaign}"`));
         const objective = objectiveFor(rule, parsed.target.objective);
@@ -1540,6 +1653,21 @@ export const objectives = (
           },
         );
         if (Result.isFailure(outcome)) return yield* Effect.fail(fail(outcome.failure));
+        // A concession that sends a sector back a phase says so, and names
+        // the attestations it revoked on the way.
+        const sentBack = outcome.success.sentBack.flatMap((one) => [
+          "",
+          `this concession moves ${one.sector} back ${one.from ?? "done"} → ${one.to ?? "done"}.`,
+          ...(one.revoked.length === 0
+            ? []
+            : [
+                `It revokes ${one.sector}'s attestation of ${one.revoked.join(", ")}: what was attested no longer holds. Once it does again, attest it anew:`,
+                ...one.revoked.map(
+                  (phase) =>
+                    `  architecture campaigns attest ${one.sector} ${phase} --reason "…" --campaign ${rule.id}`,
+                ),
+              ]),
+        ]);
         const scalar =
           rule.objectives.find((one) => one.id === objective.success)?.measure !== null;
         if (scalar) {
@@ -1557,6 +1685,7 @@ export const objectives = (
                   "",
                   `${count(outcome.success.left.length, "sector")} left past the record; check still fails on them.`,
                 ]),
+            ...sentBack,
           ]);
         }
         if (outcome.success.conceded.length === 0) {
@@ -1573,6 +1702,7 @@ export const objectives = (
                 "",
                 `${count(outcome.success.left.length, "hit")} left unrecorded; check still fails on them.`,
               ]),
+          ...sentBack,
         ]);
       }
       default:
@@ -1602,16 +1732,63 @@ export const campaigns = (
     const json = argv.includes("--json");
     const retired = parsed.subcommand === undefined ? undefined : RETIRED[parsed.subcommand];
     if (retired !== undefined) return yield* Effect.fail(fail(retired));
+    // A positional that is no path is refused, not walked: most often it is
+    // a sector's name, and `--sector` is what asks about one.
+    for (const root of parsed.roots) {
+      if (existsSync(path.resolve(policy.repoRoot, root))) continue;
+      const named = collectFindings(policy, defaultRoots).campaigns.some((one) =>
+        one.sectors.has(root),
+      );
+      return yield* Effect.fail(
+        fail(
+          `campaigns: ${root} is not a path in the repository, so there is nothing to walk there.` +
+            (named ? ` It names a sector: \`campaigns status --sector ${root}\`.` : ""),
+        ),
+      );
+    }
+    const sector = flagOf(argv, "--sector");
+    if (parsed.subcommand === "status" && sector !== undefined) {
+      const only = argv.includes("--campaign") ? campaignFor(policy, argv) : null;
+      if (only !== null && Result.isFailure(only)) return yield* Effect.fail(fail(only.failure));
+      const views = collectFindings(policy, roots)
+        .campaigns.filter((one) => only === null || one.rule.id === only.success.id)
+        .flatMap((one) => {
+          const view = sectorViewOf(policy, one, sector);
+          return view === null ? [] : [view];
+        });
+      if (views.length === 0) {
+        return yield* Effect.fail(
+          fail(`campaigns: no campaign under ${roots.join(", ")} has a sector named ${sector}.`),
+        );
+      }
+      return yield* report(
+        json
+          ? [JSON.stringify({ version: 1, sectors: views }, null, 2)]
+          : views.flatMap((view, i) => [...(i === 0 ? [] : [""]), ...renderSectorView(view)]),
+      );
+    }
 
-    switch (parsed.subcommand) {
+    // `status` without `--changed` is the overview, in text or JSON: the
+    // nudge alone is scoped to a diff.
+    const subcommand =
+      parsed.subcommand === "status" && !argv.includes("--changed") ? undefined : parsed.subcommand;
+    switch (subcommand) {
       case undefined: {
         const snapshot = snapshotOf(policy, roots, manifestPathOf(policy.repoRoot, configFilename));
+        if (json) {
+          // Each campaign as the conformance snapshot carries it: its
+          // burn-down, its ladder, and a row per sector.
+          return yield* report([
+            JSON.stringify({ version: 1, campaigns: snapshot.campaigns }, null, 2),
+          ]);
+        }
         return yield* report([
           `${count(snapshot.campaigns.length, "campaign")} under ${roots.join(", ")}`,
           "",
           ...renderCampaignRows(snapshot.campaigns),
           "",
           "  architecture campaigns status --changed [--base <ref>] [--json]   # what a diff touches, and what to do",
+          "  architecture campaigns status --sector <sector> [--json]          # where one sector stands, and what holds it",
           "  architecture objectives clear [<campaign>[/<objective>]]        # reconcile the ledgers with the code",
           '  architecture objectives concede <campaign>[/<objective>] --reason "<why>"   # record why a count may rise',
           '  architecture campaigns attest <sector> <phase> --reason "<why>" [--evidence <url>]',
@@ -1620,11 +1797,6 @@ export const campaigns = (
         ]);
       }
       case "status": {
-        if (!argv.includes("--changed")) {
-          return yield* Effect.fail(
-            fail("campaigns status takes --changed: the nudge is scoped to a diff."),
-          );
-        }
         const base = flagOf(argv, "--base") ?? null;
         const diff = yield* Effect.try({
           try: () => readDiff(policy.repoRoot, base),
@@ -1642,6 +1814,19 @@ export const campaigns = (
                 catch: (cause) =>
                   fail(`could not evaluate the base tree at ${base}: ${String(cause)}`),
               });
+        // The ledger mode's "before" for work done ahead of the plan is the
+        // HEAD tree, evaluated once per commit and cached: no ledger counts
+        // the holdouts of a phase a sector has not entered.
+        const headTree =
+          base !== null || !current.some((one) => one.rule.phases.length > 0)
+            ? null
+            : yield* Effect.tryPromise({
+                try: () =>
+                  baseSideAt(policy, "HEAD", roots, (repoRoot) =>
+                    loadPolicyFromFile(repoRoot, configFilename),
+                  ),
+                catch: (cause) => fail(`could not evaluate the tree at HEAD: ${String(cause)}`),
+              });
         const hotfix = flagOf(argv, "--hotfix") ?? null;
         const nudge = nudgeOf(
           policy,
@@ -1650,10 +1835,23 @@ export const campaigns = (
           baseSide,
           hotfix,
           hotfix === null ? null : authorOf(flagOf(argv, "--by")),
+          headTree,
         );
         yield* report(json ? [JSON.stringify(nudge, null, 2)] : renderNudge(nudge, policy.now));
-        if (!nudge.ok)
-          return yield* Effect.fail(fail("the diff sends a sector back under its onTouch"));
+        if (!nudge.ok) {
+          const ahead = nudge.sectors.some((one) => one.verdict === "ahead");
+          const back = nudge.sectors.some(
+            (one) => one.verdict !== "ok" && one.verdict !== "ahead" && one.verdict !== "hotfix",
+          );
+          return yield* Effect.fail(
+            fail(
+              [
+                ...(back ? ["the diff sends a sector back under its onTouch"] : []),
+                ...(ahead ? ["the diff works ahead of a sector's phase under its onAhead"] : []),
+              ].join("; "),
+            ),
+          );
+        }
         return;
       }
       case "attest": {
@@ -1809,7 +2007,9 @@ export const run = (
       yield* Effect.tryPromise({
         try: () =>
           Promise.all(
-            reportSpecsOf(campaignsOf(policy).campaignRules).map((spec) => campaignsOf(policy).reports.read?.(spec)),
+            reportSpecsOf(campaignsOf(policy).campaignRules).map((spec) =>
+              campaignsOf(policy).reports.read?.(spec),
+            ),
           ),
         catch: (cause) => fail(String(cause)),
       });