@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/commands/validate/links/glossary.js

@@ -0,0 +1,75 @@
+/**
+ * `glossary.unlinked` — a defined term that no document outside the glossary
+ * cites.
+ *
+ * The mirror of `permissions.unenforced` and `capability.unrealized`, and it
+ * earns its place for their reason: a vocabulary is worth what cites it. A term
+ * nobody links to is either a word the fleet never adopted or a definition left
+ * behind by a rename — both are drift, and neither is visible from inside the
+ * file. WARN, because the honest answer is often "not written up yet", and
+ * because a glossary must be safe to start: a fleet that defines twenty terms
+ * on a Monday and cites four of them is adopting the axis, not failing it.
+ *
+ * A TERM CITED ONLY BY OTHER TERMS IS STILL UNLINKED, and this is the judgement
+ * that keeps the warning worth anything. A glossary is a network of definitions,
+ * so `order-line` linking to `order` is normal and correct — and it proves
+ * nothing about whether the FLEET uses either word. The same reasoning
+ * `capability.requirement-inert-join` applies one axis over: a join written
+ * inside the tree is not evidence about the world outside it. The intra-glossary
+ * citations are listed in `details` rather than hidden, because they are the
+ * first thing a reader will otherwise go looking for.
+ *
+ * ONE FINDING FOR THE WHOLE GLOSSARY when nothing cites anything, and one per
+ * term otherwise. A fleet that has just created `glossary/` and written its
+ * first eight definitions would otherwise get eight identical warnings saying
+ * the same thing about the same afternoon's work.
+ */
+import { backlinkIndex } from "../../../core/links/backlinks.js";
+import { readGlossary } from "../../../core/glossary/tree.js";
+import { glossaryDir } from "../../../core/repo/authored/paths.js";
+import { repoPath } from "../../../core/envelope/json.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import {} from "../../../core/vocabulary/report.js";
+export async function glossaryFindings(docsDir, fleet) {
+    const root = glossaryDir(docsDir);
+    const glossary = await readGlossary(root);
+    // The directory's existence is the axis's opt-in, exactly as
+    // `architecture/capabilities.yaml` and `capabilities/` are the business
+    // axis's. A fleet without one pays a single `existsSync` and hears nothing —
+    // and the whole fleet-wide link walk below is never built.
+    if (!glossary.present || glossary.terms.length === 0)
+        return [];
+    const index = await backlinkIndex(docsDir, fleet);
+    const inGlossary = (source) => source.startsWith(`${repoPath(docsDir, root)}/`);
+    const unlinked = glossary.terms
+        .map((term) => ({ term, cited: index.linkersOf(term.path) }))
+        .map(({ term, cited }) => ({ term, outside: cited.filter((s) => !inGlossary(s)), within: cited.filter(inGlossary) }))
+        .filter(({ outside }) => outside.length === 0);
+    if (unlinked.length === 0)
+        return [];
+    // The whole vocabulary uncited is one fact about one afternoon, not N facts.
+    if (unlinked.length === glossary.terms.length && glossary.terms.length > 1) {
+        return [
+            {
+                severity: "warn",
+                code: "glossary.unlinked",
+                message: `glossary: none of the ${glossary.terms.length} defined term(s) is linked from any document outside glossary/. ` +
+                    "A term becomes checkable when a requirement, capability or intent cites it — " +
+                    "`[Order](../../glossary/order.md)` — and until then the definitions are a document nothing joins to.",
+                details: unlinked.map(({ term }) => term.id),
+            },
+        ];
+    }
+    return unlinked.map(({ term, within }) => ({
+        severity: "warn",
+        code: "glossary.unlinked",
+        subject: term.id,
+        message: `glossary/${term.id}.md is linked from no document outside glossary/` +
+            (within.length === 0
+                ? " — either a word the fleet has not adopted, or a definition left behind by a rename."
+                : ", only from other terms — which says the glossary is consistent, not that the fleet uses the word.") +
+            ` Cite it as \`[${term.id}](<relative>/glossary/${term.id}.md)\` from the requirement or capability that uses it, or delete the definition.`,
+        ...(within.length === 0 ? {} : { details: within }),
+    }));
+}
+//# sourceMappingURL=glossary.js.map

package/dist/commands/validate/links/glossary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.js","sourceRoot":"","sources":["../../../../src/commands/validate/links/glossary.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `glossary.unlinked` — a defined term that no document outside the glossary\n * cites.\n *\n * The mirror of `permissions.unenforced` and `capability.unrealized`, and it\n * earns its place for their reason: a vocabulary is worth what cites it. A term\n * nobody links to is either a word the fleet never adopted or a definition left\n * behind by a rename — both are drift, and neither is visible from inside the\n * file. WARN, because the honest answer is often \"not written up yet\", and\n * because a glossary must be safe to start: a fleet that defines twenty terms\n * on a Monday and cites four of them is adopting the axis, not failing it.\n *\n * A TERM CITED ONLY BY OTHER TERMS IS STILL UNLINKED, and this is the judgement\n * that keeps the warning worth anything. A glossary is a network of definitions,\n * so `order-line` linking to `order` is normal and correct — and it proves\n * nothing about whether the FLEET uses either word. The same reasoning\n * `capability.requirement-inert-join` applies one axis over: a join written\n * inside the tree is not evidence about the world outside it. The intra-glossary\n * citations are listed in `details` rather than hidden, because they are the\n * first thing a reader will otherwise go looking for.\n *\n * ONE FINDING FOR THE WHOLE GLOSSARY when nothing cites anything, and one per\n * term otherwise. A fleet that has just created `glossary/` and written its\n * first eight definitions would otherwise get eight identical warnings saying\n * the same thing about the same afternoon's work.\n */\nimport { backlinkIndex } from \"../../../core/links/backlinks.js\";\nimport { readGlossary } from \"../../../core/glossary/tree.js\";\nimport { glossaryDir } from \"../../../core/repo/authored/paths.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\nexport async function glossaryFindings(docsDir: DocsDir, fleet: FleetContext): Promise<Finding[]> {\n  const root = glossaryDir(docsDir);\n  const glossary = await readGlossary(root);\n  // The directory's existence is the axis's opt-in, exactly as\n  // `architecture/capabilities.yaml` and `capabilities/` are the business\n  // axis's. A fleet without one pays a single `existsSync` and hears nothing —\n  // and the whole fleet-wide link walk below is never built.\n  if (!glossary.present || glossary.terms.length === 0) return [];\n\n  const index = await backlinkIndex(docsDir, fleet);\n  const inGlossary = (source: string): boolean => source.startsWith(`${repoPath(docsDir, root)}/`);\n  const unlinked = glossary.terms\n    .map((term) => ({ term, cited: index.linkersOf(term.path) }))\n    .map(({ term, cited }) => ({ term, outside: cited.filter((s) => !inGlossary(s)), within: cited.filter(inGlossary) }))\n    .filter(({ outside }) => outside.length === 0);\n  if (unlinked.length === 0) return [];\n\n  // The whole vocabulary uncited is one fact about one afternoon, not N facts.\n  if (unlinked.length === glossary.terms.length && glossary.terms.length > 1) {\n    return [\n      {\n        severity: \"warn\",\n        code: \"glossary.unlinked\",\n        message:\n          `glossary: none of the ${glossary.terms.length} defined term(s) is linked from any document outside glossary/. ` +\n          \"A term becomes checkable when a requirement, capability or intent cites it — \" +\n          \"`[Order](../../glossary/order.md)` — and until then the definitions are a document nothing joins to.\",\n        details: unlinked.map(({ term }) => term.id),\n      },\n    ];\n  }\n  return unlinked.map(({ term, within }) => ({\n    severity: \"warn\" as const,\n    code: \"glossary.unlinked\",\n    subject: term.id,\n    message:\n      `glossary/${term.id}.md is linked from no document outside glossary/` +\n      (within.length === 0\n        ? \" — either a word the fleet has not adopted, or a definition left behind by a rename.\"\n        : \", only from other terms — which says the glossary is consistent, not that the fleet uses the word.\") +\n      ` Cite it as \\`[${term.id}](<relative>/glossary/${term.id}.md)\\` from the requirement or capability that uses it, or delete the definition.`,\n    ...(within.length === 0 ? {} : { details: within }),\n  }));\n}\n"]}

package/dist/commands/validate/render/repeats.js

@@ -0,0 +1,63 @@
+import { plural } from "../../policy/format.js";
+import { cappedNames } from "./rollups.js";
+/**
+ * More than three services: three can be a coincidence of one team's
+ * services, and three lines are still read one by one. Past that the lines
+ * stop being read and start being scrolled.
+ */
+const REPEAT_THRESHOLD = 3;
+/**
+ * The groups over `services`, considering only the findings `shown` would
+ * print. The predicate is the listing's own, so a finding another lever
+ * already took out of the listing (`--errors-only`, an axis banner, a lead) is
+ * neither counted here nor printed twice.
+ */
+export function repeatedFindings(services, shown) {
+    // Per key, the foldable finding of each service that raises the key exactly
+    // once — a Map iterates in insertion order, so the names keep the report's.
+    const byKey = new Map();
+    for (const t of services) {
+        for (const f of t.findings) {
+            if (f.severity === "ok" || !shown(f))
+                continue;
+            const key = `${f.severity} ${f.code}`;
+            const perService = byKey.get(key) ?? new Map();
+            // A second finding from the same service, or one carrying details, makes
+            // that service's entry unfoldable (null): its lines print as themselves.
+            const foldable = !perService.has(t.id) && (f.details ?? []).length === 0;
+            perService.set(t.id, foldable ? f : null);
+            byKey.set(key, perService);
+        }
+    }
+    const groups = [];
+    const collapsed = new Set();
+    for (const perService of byKey.values()) {
+        const folded = [...perService].filter((entry) => entry[1] !== null);
+        const [first] = folded;
+        if (first === undefined || folded.length <= REPEAT_THRESHOLD)
+            continue;
+        groups.push({ example: first[1], findings: folded.length, services: folded.map(([id]) => id) });
+        for (const [, f] of folded)
+            collapsed.add(f);
+    }
+    // A stable sort, so the report order survives inside each severity.
+    groups.sort((a, b) => severityRank(a.example) - severityRank(b.example));
+    return { groups, collapsed };
+}
+function severityRank(f) {
+    return f.severity === "error" ? 0 : 1;
+}
+/**
+ * Each group as its example — through `lineOf`, the listing's own line, so it
+ * keeps the severity marker and the `(code)` suffix exactly as any finding
+ * does — and one indented line saying how far it repeats. No member carries
+ * details (those are never folded), so nothing is left out of either line.
+ */
+export function printRepeats(groups, lineOf) {
+    for (const g of groups) {
+        console.log(lineOf(g.example));
+        console.log(`    same code ×${g.findings} on ${plural(g.services.length, "service")}: ` +
+            `${cappedNames(g.services)} — every finding is in --json`);
+    }
+}
+//# sourceMappingURL=repeats.js.map

package/dist/commands/validate/render/repeats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeats.js","sourceRoot":"","sources":["../../../../src/commands/validate/render/repeats.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Repeat grouping: on a fleet run, a warning or error that MORE THAN\n * `REPEAT_THRESHOLD` services raise prints once, as itself, followed by one\n * counted line naming the services — instead of once per service.\n *\n * A fleet mid-adoption raises the same finding on most of its services: forty\n * services with no `sources:` print forty near-identical warnings, and the one\n * warning that is actually different sits somewhere among them. The reader of\n * a CI log needs the pattern once and the exceptions individually; the per-\n * service copies are what the `--json` payload and a single-service run are\n * for, and both still carry every one.\n *\n * It is the same kind of lever as `--errors-only` and axis grouping\n * (`./text.ts`), and holds the same discipline: the report, the footer's\n * counts, `--json` and `--strict` are computed from the UNFILTERED findings,\n * and nothing is dropped — every finding a group stands for is counted on its\n * line and its service named there (capped, the remainder counted). Each\n * boundary below is chosen so a group cannot hide something a reader needs:\n *\n * - SERVICE targets only. A feature's block is that feature's work list, and\n *   the landscape's findings are each about a different place on the map, so\n *   neither is \"the same finding again\".\n * - Warnings and errors only. An `ok` line confirms a per-service fact (how\n *   many elements, how many requirements), and `--errors-only` already exists\n *   for a reader who wants confirmations gone.\n * - Keyed on severity AND code. `service.no-openapi` is an error or a warning\n *   depending on what already points into the missing file; one key would file\n *   an error under a ⚠.\n * - The threshold counts distinct SERVICES, not findings, and only a service\n *   raising the finding exactly ONCE is folded. One service raising\n *   `covers.unknown` five times is five broken lines in one document, and each\n *   of them has to print — that is not a fleet-wide pattern, it is a worklist —\n *   so its five lines stay in its own listing even when four other services\n *   raise the code once each and are folded.\n * - A finding that carries `details` is never folded. Details are evidence\n *   about one service (which links dangle into the missing file, which ids do\n *   not resolve), and a counted line could only drop them.\n */\nimport type { Finding, TargetReport } from \"../../../core/vocabulary/report.js\";\nimport { plural } from \"../../policy/format.js\";\nimport { cappedNames } from \"./rollups.js\";\n\n/**\n * More than three services: three can be a coincidence of one team's\n * services, and three lines are still read one by one. Past that the lines\n * stop being read and start being scrolled.\n */\nconst REPEAT_THRESHOLD = 3;\n\nexport interface RepeatGroup {\n  /** The group's first finding in report order — printed in full, as itself. */\n  readonly example: Finding;\n  /** How many findings the group stands for, the example included. */\n  readonly findings: number;\n  /** The distinct services raising it, in report order. */\n  readonly services: readonly string[];\n}\n\nexport interface Repeats {\n  /** Errors first, then warnings; within each, the order the report raised them in. */\n  readonly groups: readonly RepeatGroup[];\n  /** Every finding a group stands for — exactly what the per-service listing skips. */\n  readonly collapsed: ReadonlySet<Finding>;\n}\n\n/**\n * The groups over `services`, considering only the findings `shown` would\n * print. The predicate is the listing's own, so a finding another lever\n * already took out of the listing (`--errors-only`, an axis banner, a lead) is\n * neither counted here nor printed twice.\n */\nexport function repeatedFindings(\n  services: readonly TargetReport[],\n  shown: (f: Finding) => boolean,\n): Repeats {\n  // Per key, the foldable finding of each service that raises the key exactly\n  // once — a Map iterates in insertion order, so the names keep the report's.\n  const byKey = new Map<string, Map<string, Finding | null>>();\n  for (const t of services) {\n    for (const f of t.findings) {\n      if (f.severity === \"ok\" || !shown(f)) continue;\n      const key = `${f.severity} ${f.code}`;\n      const perService = byKey.get(key) ?? new Map<string, Finding | null>();\n      // A second finding from the same service, or one carrying details, makes\n      // that service's entry unfoldable (null): its lines print as themselves.\n      const foldable = !perService.has(t.id) && (f.details ?? []).length === 0;\n      perService.set(t.id, foldable ? f : null);\n      byKey.set(key, perService);\n    }\n  }\n  const groups: RepeatGroup[] = [];\n  const collapsed = new Set<Finding>();\n  for (const perService of byKey.values()) {\n    const folded = [...perService].filter((entry): entry is [string, Finding] => entry[1] !== null);\n    const [first] = folded;\n    if (first === undefined || folded.length <= REPEAT_THRESHOLD) continue;\n    groups.push({ example: first[1], findings: folded.length, services: folded.map(([id]) => id) });\n    for (const [, f] of folded) collapsed.add(f);\n  }\n  // A stable sort, so the report order survives inside each severity.\n  groups.sort((a, b) => severityRank(a.example) - severityRank(b.example));\n  return { groups, collapsed };\n}\n\nfunction severityRank(f: Finding): number {\n  return f.severity === \"error\" ? 0 : 1;\n}\n\n/**\n * Each group as its example — through `lineOf`, the listing's own line, so it\n * keeps the severity marker and the `(code)` suffix exactly as any finding\n * does — and one indented line saying how far it repeats. No member carries\n * details (those are never folded), so nothing is left out of either line.\n */\nexport function printRepeats(groups: readonly RepeatGroup[], lineOf: (f: Finding) => string): void {\n  for (const g of groups) {\n    console.log(lineOf(g.example));\n    console.log(\n      `    same code ×${g.findings} on ${plural(g.services.length, \"service\")}: ` +\n        `${cappedNames(g.services)} — every finding is in --json`,\n    );\n  }\n}\n"]}

package/dist/commands/validate/render/rollups.js

@@ -0,0 +1,115 @@
+/**
+ * The lines of a fleet report that describe the WHOLE run rather than one
+ * finding: the summary that opens and closes it, the index of its errors, the
+ * unverifiable-sources line and the not-started axis banners.
+ *
+ * Every one of them is tallied off the UNFILTERED findings — the same walk the
+ * `--json` summary counts — and none of them is a finding, which is why they
+ * all print under `--errors-only` and why no rendering lever (axis grouping,
+ * repeat grouping) can move a number in any of them.
+ */
+import { SEVERITY_MARK } from "../../../core/vocabulary/report.js";
+import { plural } from "../../policy/format.js";
+import { ADOPTION_AXES } from "../fleet/scorecard/adoption.js";
+/**
+ * How many names a counted line spells before the rest become `+N more`.
+ *
+ * A counted line exists to keep a hundred-service fleet's report readable, and
+ * a line that names all hundred is the same wall of text moved sideways. Five
+ * is enough to recognise a pattern — "it is every platform service" — and the
+ * count beside the list says how much was left out, so nothing reads complete
+ * when it is not. `--json` always carries every one.
+ */
+const NAME_LIMIT = 5;
+/** `a, b, c, d, e +3 more` — the one spelling of a capped name list. */
+export function cappedNames(names) {
+    const shown = names.slice(0, NAME_LIMIT).join(", ");
+    return names.length > NAME_LIMIT ? `${shown} +${names.length - NAME_LIMIT} more` : shown;
+}
+/** The counts line, printed above a fleet report and again as its footer. */
+export function summaryLine(s) {
+    return (`${plural(s.services, "service")}, ${plural(s.features, "feature")} — ` +
+        `${plural(s.errors, "error")}, ${plural(s.warnings, "warning")}`);
+}
+/**
+ * Every error the run raised, one line per code, BEFORE the long listing.
+ *
+ * A fleet run that fails prints its errors wherever their targets happen to
+ * sit, and on a large fleet that is hundreds of lines in: a reader who opens
+ * the log at the top saw confirmations and warnings first and had to scroll to
+ * learn that, and why, the run was red. The index answers that in a few lines
+ * — which codes, how many, on what — and does NOT repeat the findings: each
+ * prints further down, under its own target or counted on a repeat group.
+ *
+ * Each error is named by WHERE it prints and, when narrower, what it is
+ * about: `FEAT-112 (order-service)` for a feature's per-service check, bare
+ * `payment-service` for a service's own. The subject alone sent a reader to
+ * the service section for an error printed under a feature; the target alone
+ * hid which service a feature or landscape finding is about. Most frequent
+ * first; ties keep the order the report raised them in, because a stable sort
+ * over the target walk is deterministic across runs and machines. The ×counts
+ * sum to the summary's error count by construction — both walk every error.
+ */
+export function printErrorIndex(targets) {
+    const byCode = new Map();
+    for (const t of targets) {
+        for (const f of t.findings) {
+            if (f.severity !== "error")
+                continue;
+            const entry = byCode.get(f.code) ?? { count: 0, places: new Set() };
+            entry.count += 1;
+            const where = f.subject === undefined || f.subject === t.id ? t.id : `${t.id} (${f.subject})`;
+            entry.places.add(where);
+            byCode.set(f.code, entry);
+        }
+    }
+    if (byCode.size === 0)
+        return;
+    console.log("errors by code:");
+    const rows = [...byCode].sort(([, a], [, b]) => b.count - a.count);
+    for (const [raised, entry] of rows) {
+        console.log(`  ${SEVERITY_MARK.error} ${raised} ×${entry.count}: ${cappedNames([...entry.places])}`);
+    }
+}
+/**
+ * The `--all` footer: the summary, the unverifiable-sources line and the axis
+ * banners. Printed last because CI logs are read from the tail.
+ */
+export function printFooter(targets, footer) {
+    const { unverifiable, card, grouped, isGrouped } = footer;
+    console.log(`\n${summaryLine(footer.summary)}`);
+    // One line for the whole fleet, never one per service: honest about the blind
+    // spot without drowning the report in a hundred copies of it.
+    if (unverifiable > 0) {
+        const whose = unverifiable === 1 ? "1 service's" : `${unverifiable} services'`;
+        console.log(`⚠ sources.unverifiable-from-here: ${whose} sources can only be checked from their own repos`);
+    }
+    // The axis banners — one per not-started axis that actually grouped a
+    // warning, in the axes' fixed order, each naming its dropped codes with
+    // counts. Tallied off the UNFILTERED findings (the same walk the footer
+    // counts), and printed under --errors-only too: like the footer and the
+    // unverifiable line this is a rollup, not a finding.
+    if (card !== null && grouped.size > 0) {
+        const tally = new Map();
+        for (const t of targets) {
+            for (const f of t.findings) {
+                if (isGrouped(f))
+                    tally.set(f.code, (tally.get(f.code) ?? 0) + 1);
+            }
+        }
+        for (const axis of ADOPTION_AXES) {
+            // Insertion order of `grouped` is the table's order, so the pairs render
+            // deterministically across runs and machines.
+            const pairs = [...grouped]
+                .filter(([code, a]) => a === axis && (tally.get(code) ?? 0) > 0)
+                .map(([code]) => [code, tally.get(code) ?? 0]);
+            if (pairs.length === 0)
+                continue;
+            const total = pairs.reduce((n, [, k]) => n + k, 0);
+            console.log(`⚠ ${axis} axis not started fleet-wide (0 of ${plural(card.services, "service")}), ` +
+                `expected during staged adoption — ${total} warning(s) grouped: ` +
+                `${pairs.map(([code, k]) => `${code}×${k}`).join(", ")}; every finding is unchanged in --json`);
+        }
+    }
+}
+//# sourceMappingURL=rollups.js.map

package/dist/commands/validate/render/rollups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollups.js","sourceRoot":"","sources":["../../../../src/commands/validate/render/rollups.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The lines of a fleet report that describe the WHOLE run rather than one\n * finding: the summary that opens and closes it, the index of its errors, the\n * unverifiable-sources line and the not-started axis banners.\n *\n * Every one of them is tallied off the UNFILTERED findings — the same walk the\n * `--json` summary counts — and none of them is a finding, which is why they\n * all print under `--errors-only` and why no rendering lever (axis grouping,\n * repeat grouping) can move a number in any of them.\n */\nimport { SEVERITY_MARK, type Finding, type TargetReport } from \"../../../core/vocabulary/report.js\";\nimport { plural } from \"../../policy/format.js\";\nimport { ADOPTION_AXES, type Adoption, type AdoptionAxis } from \"../fleet/scorecard/adoption.js\";\nimport type { ValidateSummary } from \"../report.js\";\n\n/**\n * How many names a counted line spells before the rest become `+N more`.\n *\n * A counted line exists to keep a hundred-service fleet's report readable, and\n * a line that names all hundred is the same wall of text moved sideways. Five\n * is enough to recognise a pattern — \"it is every platform service\" — and the\n * count beside the list says how much was left out, so nothing reads complete\n * when it is not. `--json` always carries every one.\n */\nconst NAME_LIMIT = 5;\n\n/** `a, b, c, d, e +3 more` — the one spelling of a capped name list. */\nexport function cappedNames(names: readonly string[]): string {\n  const shown = names.slice(0, NAME_LIMIT).join(\", \");\n  return names.length > NAME_LIMIT ? `${shown} +${names.length - NAME_LIMIT} more` : shown;\n}\n\n/** The counts line, printed above a fleet report and again as its footer. */\nexport function summaryLine(s: ValidateSummary): string {\n  return (\n    `${plural(s.services, \"service\")}, ${plural(s.features, \"feature\")} — ` +\n    `${plural(s.errors, \"error\")}, ${plural(s.warnings, \"warning\")}`\n  );\n}\n\n/**\n * Every error the run raised, one line per code, BEFORE the long listing.\n *\n * A fleet run that fails prints its errors wherever their targets happen to\n * sit, and on a large fleet that is hundreds of lines in: a reader who opens\n * the log at the top saw confirmations and warnings first and had to scroll to\n * learn that, and why, the run was red. The index answers that in a few lines\n * — which codes, how many, on what — and does NOT repeat the findings: each\n * prints further down, under its own target or counted on a repeat group.\n *\n * Each error is named by WHERE it prints and, when narrower, what it is\n * about: `FEAT-112 (order-service)` for a feature's per-service check, bare\n * `payment-service` for a service's own. The subject alone sent a reader to\n * the service section for an error printed under a feature; the target alone\n * hid which service a feature or landscape finding is about. Most frequent\n * first; ties keep the order the report raised them in, because a stable sort\n * over the target walk is deterministic across runs and machines. The ×counts\n * sum to the summary's error count by construction — both walk every error.\n */\nexport function printErrorIndex(targets: readonly TargetReport[]): void {\n  const byCode = new Map<string, { count: number; places: Set<string> }>();\n  for (const t of targets) {\n    for (const f of t.findings) {\n      if (f.severity !== \"error\") continue;\n      const entry = byCode.get(f.code) ?? { count: 0, places: new Set<string>() };\n      entry.count += 1;\n      const where = f.subject === undefined || f.subject === t.id ? t.id : `${t.id} (${f.subject})`;\n      entry.places.add(where);\n      byCode.set(f.code, entry);\n    }\n  }\n  if (byCode.size === 0) return;\n  console.log(\"errors by code:\");\n  const rows = [...byCode].sort(([, a], [, b]) => b.count - a.count);\n  for (const [raised, entry] of rows) {\n    console.log(`  ${SEVERITY_MARK.error} ${raised} ×${entry.count}: ${cappedNames([...entry.places])}`);\n  }\n}\n\n/** What the footer needs beyond the targets themselves. */\nexport interface Footer {\n  summary: ValidateSummary;\n  /** The fleet's unverifiable-sources subject count. */\n  unverifiable: number;\n  /** The scorecard facts that licensed axis grouping, or null when nothing was grouped. */\n  card: { readonly adoption: Adoption; readonly services: number } | null;\n  /** The warn codes axis grouping folded, by axis — empty when `card` is null. */\n  grouped: ReadonlyMap<string, AdoptionAxis>;\n  /**\n   * The predicate the listing dropped findings by. Handed in rather than\n   * re-derived from `grouped`, so the banner counts exactly the findings the\n   * listing left out — two spellings of one rule are two rules.\n   */\n  isGrouped: (f: Finding) => boolean;\n}\n\n/**\n * The `--all` footer: the summary, the unverifiable-sources line and the axis\n * banners. Printed last because CI logs are read from the tail.\n */\nexport function printFooter(targets: readonly TargetReport[], footer: Footer): void {\n  const { unverifiable, card, grouped, isGrouped } = footer;\n  console.log(`\\n${summaryLine(footer.summary)}`);\n  // One line for the whole fleet, never one per service: honest about the blind\n  // spot without drowning the report in a hundred copies of it.\n  if (unverifiable > 0) {\n    const whose = unverifiable === 1 ? \"1 service's\" : `${unverifiable} services'`;\n    console.log(\n      `⚠ sources.unverifiable-from-here: ${whose} sources can only be checked from their own repos`,\n    );\n  }\n  // The axis banners — one per not-started axis that actually grouped a\n  // warning, in the axes' fixed order, each naming its dropped codes with\n  // counts. Tallied off the UNFILTERED findings (the same walk the footer\n  // counts), and printed under --errors-only too: like the footer and the\n  // unverifiable line this is a rollup, not a finding.\n  if (card !== null && grouped.size > 0) {\n    const tally = new Map<string, number>();\n    for (const t of targets) {\n      for (const f of t.findings) {\n        if (isGrouped(f)) tally.set(f.code, (tally.get(f.code) ?? 0) + 1);\n      }\n    }\n    for (const axis of ADOPTION_AXES) {\n      // Insertion order of `grouped` is the table's order, so the pairs render\n      // deterministically across runs and machines.\n      const pairs = [...grouped]\n        .filter(([code, a]) => a === axis && (tally.get(code) ?? 0) > 0)\n        .map(([code]) => [code, tally.get(code) ?? 0] as const);\n      if (pairs.length === 0) continue;\n      const total = pairs.reduce((n, [, k]) => n + k, 0);\n      console.log(\n        `⚠ ${axis} axis not started fleet-wide (0 of ${plural(card.services, \"service\")}), ` +\n          `expected during staged adoption — ${total} warning(s) grouped: ` +\n          `${pairs.map(([code, k]) => `${code}×${k}`).join(\", \")}; every finding is unchanged in --json`,\n      );\n    }\n  }\n}\n"]}

package/dist/commands/validate/render/text.js

@@ -0,0 +1,199 @@
+/**
+ * `loam validate`'s human view: how a graded report prints.
+ *
+ * Its own package since the fleet report grew an ORDER — lead findings, the
+ * counts and the error index, every feature, the fleet, the footer — and two
+ * levers that fold lines (axis banners, repeat groups). None of that changes a
+ * finding, a count or an exit code: `--json` and `--strict` read the targets
+ * this module is handed, never what it chose to print.
+ *
+ * The rollup is not recounted here. `RenderOptions.summary` IS the run's
+ * `summary()` (`../report.ts`), the same object `--json` carries, handed in by
+ * validate.ts — a renderer with its own count is how a footer starts printing
+ * a number its own findings contradict.
+ */
+import { listCodes } from "../../../core/explain/lookup.js";
+import { NOT_CHECKED_MARK, SEVERITY_MARK, subjectsWith, } from "../../../core/vocabulary/report.js";
+import { EXPLAIN_FOOTER } from "../../policy/format.js";
+import { groupedWarnCodes } from "../fleet/scorecard/adoption.js";
+import { printRepeats, repeatedFindings } from "./repeats.js";
+import { printErrorIndex, printFooter, summaryLine } from "./rollups.js";
+/**
+ * `--errors-only` is a RENDERING lever, the way `--strict` is an exit-code
+ * lever: neither changes the report, and the `--json` payload is unaffected by
+ * both. On a fleet of a hundred services the clean run prints several hundred
+ * `ok` confirmations, and the two warnings that matter are somewhere inside it;
+ * anyone reading a CI log wants the exceptions, and anyone auditing wants all
+ * of it. Both are available, from the same run, and neither is the default.
+ *
+ * Axis grouping is the same kind of lever, one notch further: warnings whose
+ * SOLE cause is a fleet-wide not-started axis (the mechanical, fail-closed
+ * rule in fleet/scorecard/adoption.ts — warn severity, listed code, axis at
+ * zero) are dropped from the per-target listing and re-stated as one banner
+ * per axis after the footer. The report, the footer's counts, `--json` and
+ * `--strict` are all computed from the UNFILTERED findings, so nothing a
+ * machine or an exit code reads moves by a single bit. Repeat grouping
+ * (`./repeats.ts`) is the third, under the same rule.
+ */
+export function renderText(targets, opts) {
+    const { all, errorsOnly } = opts;
+    // When the fleet-wide "not started" claim is measurable at all — each guard
+    // fails closed to ungrouped rendering. `!all` is structural, not just the
+    // call site's promise: the banners print after the footer that only `--all`
+    // reaches, so grouping outside `--all` would DROP warnings instead of
+    // moving them — the one thing this lever must never do. `services === 0`
+    // is the vacuous fleet: with no services every axis is 0 "fleet-wide", and
+    // a banner over "0 of 0 services" would hide the fleet-level warnings of a
+    // repo that merely has no fleet yet. And an unreadable service proves
+    // nothing about what it started: its all-false participation (contracts.ts)
+    // could MANUFACTURE the very N=0 that licenses suppression — beside an
+    // error saying that service could not be checked — so one
+    // `service.unreadable` subject disables grouping for the whole run.
+    const card = !all ||
+        opts.scorecard === null ||
+        opts.scorecard.services === 0 ||
+        subjectsWith(targets, "service.unreadable") > 0
+        ? null
+        : opts.scorecard;
+    const grouped = card === null ? new Map() : groupedWarnCodes(card.adoption);
+    const isGrouped = (f) => f.severity === "warn" && grouped.has(f.code);
+    // The explain pointer follows any report that printed work — a non-ok
+    // finding, listed or folded under an axis banner. Gated on the UNFILTERED
+    // findings like every other rollup, so `--errors-only` and grouping cannot
+    // print codes the pointer then fails to follow. It is computed HERE rather
+    // than beside the two places it prints because the code column below asks
+    // the same question and must not walk the findings a second time to answer
+    // it differently.
+    const pointer = targets.some((t) => t.findings.some((f) => f.severity !== "ok"));
+    // The lookup key on the line itself.
+    //
+    // Until now a text report printed messages and no codes, so the footer under
+    // it could only say codes were somewhere else — in `--json`, which a reader
+    // would have to re-run the whole command to see. The code is what `loam
+    // explain` takes, what a CI branch tests and what a bug report quotes, and
+    // withholding it from the one surface a person actually reads made the
+    // footer's own offer unreachable.
+    //
+    // Only where a code is genuinely answerable, and that guard is not
+    // decoration: a handful of emitted finding codes still have no fix-table row
+    // (test/explain.test.ts names them), and printing one beside a footer
+    // promising an explanation would send the reader to a refusal. The set is
+    // built ONCE per render, and only when something non-ok will be printed:
+    // `explainSubject` walks the shipped workflow bodies per code (the cost
+    // `fixesFor` measured from the other side, where a handful of lookups is the
+    // cheaper shape), while `listCodes()` walks them once for the whole
+    // vocabulary — and a fleet report has far more finding lines than the fleet
+    // has distinct codes. Measured: 2.7 ms for all 273 codes, once per report.
+    const explainable = pointer ? new Set(listCodes().map((listing) => listing.code)) : new Set();
+    const listed = (f) => !isGrouped(f) && (!errorsOnly || f.severity !== "ok");
+    if (!all) {
+        for (const t of targets)
+            printTarget(t, listed, explainable);
+        // Without the --all footer there would be nothing at all to print for a
+        // clean single target under --errors-only — and silence is the one output
+        // that must never mean "checked, fine".
+        if (errorsOnly && targets.every((t) => t.findings.every((f) => f.severity === "ok"))) {
+            console.log(`${targets.map((t) => t.id).join(", ")}: no errors or warnings`);
+        }
+        if (pointer)
+            console.log(`\n${EXPLAIN_FOOTER}`);
+        return;
+    }
+    printFleet(targets, { listed, explainable, summary: opts.summary });
+    printFooter(targets, { summary: opts.summary, unverifiable: opts.unverifiable, card, grouped, isGrouped });
+    if (pointer)
+        console.log(`\n${EXPLAIN_FOOTER}`);
+}
+/**
+ * The `--all` listing, in the order a reader needs it rather than the order
+ * the targets were graded in.
+ *
+ * Graded order put every service first and the features last, so on a real
+ * fleet the feature blocks — the work somebody is doing right now — and any
+ * error that made the run red sat under hundreds of per-service lines. Now:
+ * the findings that say nothing below can be trusted (`TextHint.lead`); the
+ * counts; the error index; each feature's block; then the fleet — the
+ * landscape, the groups repeat grouping folded, every service. The footer
+ * still closes it, because CI logs are read from the tail. A finding prints at
+ * most once: in full under its target, or — when repeat grouping folded it —
+ * counted on its group's line, the group's first member printed in full.
+ */
+function printFleet(targets, view) {
+    const { listed, explainable } = view;
+    const lead = (f) => f.text?.lead === true;
+    const body = (f) => listed(f) && !lead(f);
+    const services = targets.filter((t) => t.kind === "service");
+    const repeats = repeatedFindings(services, body);
+    const block = (f) => body(f) && !repeats.collapsed.has(f);
+    const features = targets.filter((t) => t.kind === "feature");
+    const featuresPrint = features.some((t) => t.findings.some(block));
+    const fleetPrints = repeats.groups.length > 0 || targets.some((t) => t.kind !== "feature" && t.findings.some(block));
+    // The head prints only above something: on a run whose listing is empty (a
+    // clean fleet under --errors-only) the footer below is the whole report,
+    // and the same counts twice in a row would say nothing new.
+    if (targets.some((t) => t.findings.some(listed))) {
+        const leads = targets.flatMap((t) => t.findings.filter((f) => lead(f) && listed(f)));
+        for (const f of leads)
+            printFinding(f, explainable);
+        console.log(summaryLine(view.summary));
+        printErrorIndex(targets);
+        if (featuresPrint || fleetPrints)
+            console.log("");
+    }
+    for (const t of features)
+        printTarget(t, block, explainable);
+    // One blank line between the features and the fleet, so the last feature's
+    // indented coherence line is not read as the landscape's first.
+    if (featuresPrint && fleetPrints)
+        console.log("");
+    for (const t of targets)
+        if (t.kind === "landscape")
+            printTarget(t, block, explainable);
+    printRepeats(repeats.groups, (f) => findingLine(f, explainable));
+    for (const t of services)
+        printTarget(t, block, explainable);
+}
+/** One target's block: the findings `show` admits, under the target's own header. */
+function printTarget(t, show, explainable) {
+    const shown = t.findings.filter(show);
+    if (shown.length === 0)
+        return;
+    // A feature announces itself; a service's findings already carry its name.
+    if (t.kind === "feature")
+        console.log(t.id);
+    let header;
+    for (const f of shown) {
+        const hint = f.text ?? {};
+        if (hint.header && hint.header !== header) {
+            header = hint.header;
+            console.log(`  ${header}`);
+        }
+        printFinding(f, explainable);
+    }
+}
+/** A finding's line and its evidence. */
+function printFinding(f, explainable) {
+    // The whole report goes to stdout, in the order it prints. Splitting errors
+    // onto stderr meant a piped stdout silently lost them from the middle of
+    // the report and 2>&1 could reorder it; the exit code carries failure,
+    // and stderr stays reserved for refusals (the fail() path).
+    console.log(findingLine(f, explainable));
+    for (const d of f.details ?? [])
+        console.log(`    ${f.text?.detailPrefix ?? ""}${d}`);
+}
+/** The one spelling of a finding's line — the listing's and a repeat group's example's. */
+function findingLine(f, explainable) {
+    const hint = f.text ?? {};
+    // The not-checked glyph replaces ✓ only. A hint can never print a ⚠ or a ✗
+    // as anything but itself: a check that did not run is an `ok` fact, and a
+    // stray hint on a real finding must not make it look like one.
+    const glyph = hint.marker === "not-checked" && f.severity === "ok" ? NOT_CHECKED_MARK : SEVERITY_MARK[f.severity];
+    const marker = hint.marker === false ? "" : `${glyph} `;
+    // `ok` confirmations stay clean, deliberately. A clean fleet run is
+    // several hundred ✓ lines and two warnings, and a code appended to every
+    // one of them would cost exactly the signal the exceptions carry — there
+    // is nothing to look up about a check that passed.
+    const code = f.severity !== "ok" && explainable.has(f.code) ? `  (${f.code})` : "";
+    return `${" ".repeat(hint.indent ?? 0)}${marker}${f.message}${code}`;
+}
+//# sourceMappingURL=text.js.map

package/dist/commands/validate/render/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../../../src/commands/validate/render/text.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam validate`'s human view: how a graded report prints.\n *\n * Its own package since the fleet report grew an ORDER — lead findings, the\n * counts and the error index, every feature, the fleet, the footer — and two\n * levers that fold lines (axis banners, repeat groups). None of that changes a\n * finding, a count or an exit code: `--json` and `--strict` read the targets\n * this module is handed, never what it chose to print.\n *\n * The rollup is not recounted here. `RenderOptions.summary` IS the run's\n * `summary()` (`../report.ts`), the same object `--json` carries, handed in by\n * validate.ts — a renderer with its own count is how a footer starts printing\n * a number its own findings contradict.\n */\nimport { listCodes } from \"../../../core/explain/lookup.js\";\nimport {\n  NOT_CHECKED_MARK,\n  SEVERITY_MARK,\n  subjectsWith,\n  type Finding,\n  type TargetReport,\n} from \"../../../core/vocabulary/report.js\";\nimport { EXPLAIN_FOOTER } from \"../../policy/format.js\";\nimport { groupedWarnCodes, type Adoption, type AdoptionAxis } from \"../fleet/scorecard/adoption.js\";\nimport type { ValidateSummary } from \"../report.js\";\nimport { printRepeats, repeatedFindings } from \"./repeats.js\";\nimport { printErrorIndex, printFooter, summaryLine } from \"./rollups.js\";\n\n/** What `renderText` needs of the run beyond the graded targets themselves. */\nexport interface RenderOptions {\n  all: boolean;\n  errorsOnly: boolean;\n  /** The run's `summary()` — the very object the `--json` payload carries. */\n  summary: ValidateSummary;\n  /** The fleet's unverifiable-sources subject count, for the one-line rollup. */\n  unverifiable: number;\n  /**\n   * The run's scorecard facts the renderer reads — ONE field, not a nullable\n   * adoption beside a defaulted denominator, so \"adoption without its real\n   * denominator\" is not constructible. Null on every single-target run and on\n   * an `--all` run whose card failed closed, and null renders exactly as\n   * before grouping existed: fail-open to today's behaviour, every warning\n   * printed individually.\n   */\n  scorecard: { readonly adoption: Adoption; readonly services: number } | null;\n}\n\n/**\n * `--errors-only` is a RENDERING lever, the way `--strict` is an exit-code\n * lever: neither changes the report, and the `--json` payload is unaffected by\n * both. On a fleet of a hundred services the clean run prints several hundred\n * `ok` confirmations, and the two warnings that matter are somewhere inside it;\n * anyone reading a CI log wants the exceptions, and anyone auditing wants all\n * of it. Both are available, from the same run, and neither is the default.\n *\n * Axis grouping is the same kind of lever, one notch further: warnings whose\n * SOLE cause is a fleet-wide not-started axis (the mechanical, fail-closed\n * rule in fleet/scorecard/adoption.ts — warn severity, listed code, axis at\n * zero) are dropped from the per-target listing and re-stated as one banner\n * per axis after the footer. The report, the footer's counts, `--json` and\n * `--strict` are all computed from the UNFILTERED findings, so nothing a\n * machine or an exit code reads moves by a single bit. Repeat grouping\n * (`./repeats.ts`) is the third, under the same rule.\n */\nexport function renderText(targets: TargetReport[], opts: RenderOptions): void {\n  const { all, errorsOnly } = opts;\n  // When the fleet-wide \"not started\" claim is measurable at all — each guard\n  // fails closed to ungrouped rendering. `!all` is structural, not just the\n  // call site's promise: the banners print after the footer that only `--all`\n  // reaches, so grouping outside `--all` would DROP warnings instead of\n  // moving them — the one thing this lever must never do. `services === 0`\n  // is the vacuous fleet: with no services every axis is 0 \"fleet-wide\", and\n  // a banner over \"0 of 0 services\" would hide the fleet-level warnings of a\n  // repo that merely has no fleet yet. And an unreadable service proves\n  // nothing about what it started: its all-false participation (contracts.ts)\n  // could MANUFACTURE the very N=0 that licenses suppression — beside an\n  // error saying that service could not be checked — so one\n  // `service.unreadable` subject disables grouping for the whole run.\n  const card =\n    !all ||\n    opts.scorecard === null ||\n    opts.scorecard.services === 0 ||\n    subjectsWith(targets, \"service.unreadable\") > 0\n      ? null\n      : opts.scorecard;\n  const grouped = card === null ? new Map<string, AdoptionAxis>() : groupedWarnCodes(card.adoption);\n  const isGrouped = (f: Finding): boolean => f.severity === \"warn\" && grouped.has(f.code);\n\n  // The explain pointer follows any report that printed work — a non-ok\n  // finding, listed or folded under an axis banner. Gated on the UNFILTERED\n  // findings like every other rollup, so `--errors-only` and grouping cannot\n  // print codes the pointer then fails to follow. It is computed HERE rather\n  // than beside the two places it prints because the code column below asks\n  // the same question and must not walk the findings a second time to answer\n  // it differently.\n  const pointer = targets.some((t) => t.findings.some((f) => f.severity !== \"ok\"));\n  // The lookup key on the line itself.\n  //\n  // Until now a text report printed messages and no codes, so the footer under\n  // it could only say codes were somewhere else — in `--json`, which a reader\n  // would have to re-run the whole command to see. The code is what `loam\n  // explain` takes, what a CI branch tests and what a bug report quotes, and\n  // withholding it from the one surface a person actually reads made the\n  // footer's own offer unreachable.\n  //\n  // Only where a code is genuinely answerable, and that guard is not\n  // decoration: a handful of emitted finding codes still have no fix-table row\n  // (test/explain.test.ts names them), and printing one beside a footer\n  // promising an explanation would send the reader to a refusal. The set is\n  // built ONCE per render, and only when something non-ok will be printed:\n  // `explainSubject` walks the shipped workflow bodies per code (the cost\n  // `fixesFor` measured from the other side, where a handful of lookups is the\n  // cheaper shape), while `listCodes()` walks them once for the whole\n  // vocabulary — and a fleet report has far more finding lines than the fleet\n  // has distinct codes. Measured: 2.7 ms for all 273 codes, once per report.\n  const explainable = pointer ? new Set(listCodes().map((listing) => listing.code)) : new Set<string>();\n  const listed = (f: Finding): boolean => !isGrouped(f) && (!errorsOnly || f.severity !== \"ok\");\n\n  if (!all) {\n    for (const t of targets) printTarget(t, listed, explainable);\n    // Without the --all footer there would be nothing at all to print for a\n    // clean single target under --errors-only — and silence is the one output\n    // that must never mean \"checked, fine\".\n    if (errorsOnly && targets.every((t) => t.findings.every((f) => f.severity === \"ok\"))) {\n      console.log(`${targets.map((t) => t.id).join(\", \")}: no errors or warnings`);\n    }\n    if (pointer) console.log(`\\n${EXPLAIN_FOOTER}`);\n    return;\n  }\n  printFleet(targets, { listed, explainable, summary: opts.summary });\n  printFooter(targets, { summary: opts.summary, unverifiable: opts.unverifiable, card, grouped, isGrouped });\n  if (pointer) console.log(`\\n${EXPLAIN_FOOTER}`);\n}\n\n/** What the fleet layout reads of the render already decided above. */\ninterface FleetView {\n  /** Whether a finding prints at all — the `--errors-only` and axis-banner levers already applied. */\n  listed: (f: Finding) => boolean;\n  explainable: ReadonlySet<string>;\n  summary: ValidateSummary;\n}\n\n/**\n * The `--all` listing, in the order a reader needs it rather than the order\n * the targets were graded in.\n *\n * Graded order put every service first and the features last, so on a real\n * fleet the feature blocks — the work somebody is doing right now — and any\n * error that made the run red sat under hundreds of per-service lines. Now:\n * the findings that say nothing below can be trusted (`TextHint.lead`); the\n * counts; the error index; each feature's block; then the fleet — the\n * landscape, the groups repeat grouping folded, every service. The footer\n * still closes it, because CI logs are read from the tail. A finding prints at\n * most once: in full under its target, or — when repeat grouping folded it —\n * counted on its group's line, the group's first member printed in full.\n */\nfunction printFleet(targets: readonly TargetReport[], view: FleetView): void {\n  const { listed, explainable } = view;\n  const lead = (f: Finding): boolean => f.text?.lead === true;\n  const body = (f: Finding): boolean => listed(f) && !lead(f);\n  const services = targets.filter((t) => t.kind === \"service\");\n  const repeats = repeatedFindings(services, body);\n  const block = (f: Finding): boolean => body(f) && !repeats.collapsed.has(f);\n  const features = targets.filter((t) => t.kind === \"feature\");\n  const featuresPrint = features.some((t) => t.findings.some(block));\n  const fleetPrints = repeats.groups.length > 0 || targets.some((t) => t.kind !== \"feature\" && t.findings.some(block));\n\n  // The head prints only above something: on a run whose listing is empty (a\n  // clean fleet under --errors-only) the footer below is the whole report,\n  // and the same counts twice in a row would say nothing new.\n  if (targets.some((t) => t.findings.some(listed))) {\n    const leads = targets.flatMap((t) => t.findings.filter((f) => lead(f) && listed(f)));\n    for (const f of leads) printFinding(f, explainable);\n    console.log(summaryLine(view.summary));\n    printErrorIndex(targets);\n    if (featuresPrint || fleetPrints) console.log(\"\");\n  }\n  for (const t of features) printTarget(t, block, explainable);\n  // One blank line between the features and the fleet, so the last feature's\n  // indented coherence line is not read as the landscape's first.\n  if (featuresPrint && fleetPrints) console.log(\"\");\n  for (const t of targets) if (t.kind === \"landscape\") printTarget(t, block, explainable);\n  printRepeats(repeats.groups, (f) => findingLine(f, explainable));\n  for (const t of services) printTarget(t, block, explainable);\n}\n\n/** One target's block: the findings `show` admits, under the target's own header. */\nfunction printTarget(t: TargetReport, show: (f: Finding) => boolean, explainable: ReadonlySet<string>): void {\n  const shown = t.findings.filter(show);\n  if (shown.length === 0) return;\n  // A feature announces itself; a service's findings already carry its name.\n  if (t.kind === \"feature\") console.log(t.id);\n  let header: string | undefined;\n  for (const f of shown) {\n    const hint = f.text ?? {};\n    if (hint.header && hint.header !== header) {\n      header = hint.header;\n      console.log(`  ${header}`);\n    }\n    printFinding(f, explainable);\n  }\n}\n\n/** A finding's line and its evidence. */\nfunction printFinding(f: Finding, explainable: ReadonlySet<string>): void {\n  // The whole report goes to stdout, in the order it prints. Splitting errors\n  // onto stderr meant a piped stdout silently lost them from the middle of\n  // the report and 2>&1 could reorder it; the exit code carries failure,\n  // and stderr stays reserved for refusals (the fail() path).\n  console.log(findingLine(f, explainable));\n  for (const d of f.details ?? []) console.log(`    ${f.text?.detailPrefix ?? \"\"}${d}`);\n}\n\n/** The one spelling of a finding's line — the listing's and a repeat group's example's. */\nfunction findingLine(f: Finding, explainable: ReadonlySet<string>): string {\n  const hint = f.text ?? {};\n  // The not-checked glyph replaces ✓ only. A hint can never print a ⚠ or a ✗\n  // as anything but itself: a check that did not run is an `ok` fact, and a\n  // stray hint on a real finding must not make it look like one.\n  const glyph = hint.marker === \"not-checked\" && f.severity === \"ok\" ? NOT_CHECKED_MARK : SEVERITY_MARK[f.severity];\n  const marker = hint.marker === false ? \"\" : `${glyph} `;\n  // `ok` confirmations stay clean, deliberately. A clean fleet run is\n  // several hundred ✓ lines and two warnings, and a code appended to every\n  // one of them would cost exactly the signal the exceptions carry — there\n  // is nothing to look up about a check that passed.\n  const code = f.severity !== \"ok\" && explainable.has(f.code) ? `  (${f.code})` : \"\";\n  return `${\" \".repeat(hint.indent ?? 0)}${marker}${f.message}${code}`;\n}\n"]}