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

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/report.js

@@ -0,0 +1,269 @@
+/**
+ * Everything that happens to a `TargetReport` around the checks themselves:
+ * how one is built when a target could not be read at all, how a finding's
+ * evidence is capped, how the set is summed, and how it prints.
+ *
+ * A module rather than the tail of validate.ts because the rollup and the
+ * renderer have to agree. The `--all` footer and the `--json` summary are the
+ * same `summary()`, and the cap reaches both payloads from one place; a second
+ * copy of either is how a footer starts printing a number its own findings
+ * contradict.
+ */
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { listCodes } from "../../core/explain/lookup.js";
+import { countSeverity, subjectsWith, SEVERITY_MARK, } from "../../core/vocabulary/report.js";
+import { EXPLAIN_FOOTER, plural } from "../policy/format.js";
+import { ADOPTION_AXES, groupedWarnCodes, } from "./fleet/scorecard/adoption.js";
+export function summary(targets) {
+    return {
+        services: targets.filter((t) => t.kind === "service").length,
+        features: targets.filter((t) => t.kind === "feature").length,
+        errors: countSeverity(targets, "error"),
+        warnings: countSeverity(targets, "warn"),
+    };
+}
+/**
+ * How many services this run could not check, for the rollup line and the
+ * `--json` payload.
+ *
+ * Counted off the findings rather than alongside them, so the rollup line
+ * and the per-service findings can never disagree about how many services
+ * this run could not check. The by-SUBJECT rule (a service whose spec.md and
+ * arch.spec.md both name `sources` raises two findings and is one service) is
+ * `subjectsWith`'s, spelled once for every findings-derived rollup — the
+ * fleet scorecard counts through the same function on the same code, so its
+ * number and this one are structurally the same number. The code is a LITERAL
+ * rather than checks/vocabulary.ts's UNVERIFIABLE constant because the
+ * stable-code collector reads counting sites too, and it refuses a slot it
+ * cannot read — the collector is also what convicts a typo here.
+ */
+export function unverifiableSubjects(targets) {
+    return subjectsWith(targets, "sources.unverifiable-from-here");
+}
+/**
+ * How many `details` lines any one finding may print before the rest are
+ * summarised away.
+ *
+ * A finding's details are evidence, not a log: LikeC4 reports one syntax error
+ * as dozens of cascading diagnostics, and a fleet-sized repo multiplies that by
+ * every target that mentions the file. The report is read by a person scrolling
+ * a CI log and by an agent with a context window, and neither of them is helped
+ * by the four-hundredth copy. The cap is applied to the JSON payload too, on
+ * purpose: `--json` is the interface an agent pipes, and an unbounded array is
+ * the same denial-of-attention there, just machine-readable.
+ */
+const DETAIL_LIMIT = 10;
+/** Truncate every finding's details, marking what was dropped so nothing looks complete when it is not. */
+export function capDetails(t) {
+    return {
+        ...t,
+        findings: t.findings.map((f) => {
+            const details = f.details ?? [];
+            if (details.length <= DETAIL_LIMIT)
+                return f;
+            return {
+                ...f,
+                details: [...details.slice(0, DETAIL_LIMIT), `… (+${details.length - DETAIL_LIMIT} more)`],
+            };
+        }),
+    };
+}
+/**
+ * One target's checks, with an IO exception turned into a finding ON that
+ * target instead of aborting the run.
+ *
+ * A fleet gate that dies on the first unreadable file reports nothing about the
+ * other ninety-nine services — one bad permission bit, one file that is a
+ * dangling symlink, and CI's answer to "how is the fleet" becomes a stack
+ * trace. The failure is real and it is an error, so the run still exits 1; what
+ * changes is that everything else is still graded, and the finding names the
+ * service and the path instead of arriving as the `internal` catch-all.
+ */
+export async function guarded(target, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        // A docs repo that vanished mid-run is not one target's problem — it is the
+        // whole run's, and the action's own catch reports it.
+        if (err instanceof DocsRepoUnavailableError)
+            throw err;
+        const path = err.path;
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            kind: target.kind,
+            id: target.id,
+            findings: [
+                {
+                    severity: "error",
+                    code: target.kind === "service" ? "service.unreadable" : "feature.unreadable",
+                    subject: target.id,
+                    message: `${target.id}: ${path === undefined ? "an artifact" : path} could not be read — ` +
+                        `nothing about this ${target.kind} was checked. ${reason}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * `target.ambiguous` — the positional named a service AND a feature. The tie is
+ * still broken the way it always was (the feature wins), because changing which
+ * one is picked would silently re-target every script that relies on it; what
+ * is new is that the run says which reading it took and how to force the other.
+ */
+export function ambiguousTarget(arg, chosen) {
+    const other = chosen === "feature" ? "service" : "feature";
+    return {
+        severity: "warn",
+        code: "target.ambiguous",
+        subject: arg,
+        message: `'${arg}' names both a service and a feature — validated as the ${chosen}. ` +
+            `Pass --${other} ${arg} for the other reading.`,
+    };
+}
+/**
+ * `--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.
+ */
+export function renderText(targets, opts) {
+    const { all, errorsOnly, unverifiable } = 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();
+    for (const t of targets) {
+        const shown = t.findings.filter((f) => !isGrouped(f) && (!errorsOnly || f.severity !== "ok"));
+        if (shown.length === 0)
+            continue;
+        // 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}`);
+            }
+            // The whole report goes to stdout, in document order. 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).
+            const marker = hint.marker === false ? "" : `${SEVERITY_MARK[f.severity]} `;
+            // `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})` : "";
+            console.log(`${" ".repeat(hint.indent ?? 0)}${marker}${f.message}${code}`);
+            for (const d of f.details ?? [])
+                console.log(`    ${hint.detailPrefix ?? ""}${d}`);
+        }
+    }
+    if (!all) {
+        // 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;
+    }
+    const s = summary(targets);
+    console.log(`\n${plural(s.services, "service")}, ${plural(s.features, "feature")} — ` +
+        `${plural(s.errors, "error")}, ${plural(s.warnings, "warning")}`);
+    // 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`);
+        }
+    }
+    if (pointer)
+        console.log(`\n${EXPLAIN_FOOTER}`);
+}
+//# sourceMappingURL=report.js.map

package/dist/commands/validate/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/commands/validate/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Everything that happens to a `TargetReport` around the checks themselves:\n * how one is built when a target could not be read at all, how a finding's\n * evidence is capped, how the set is summed, and how it prints.\n *\n * A module rather than the tail of validate.ts because the rollup and the\n * renderer have to agree. The `--all` footer and the `--json` summary are the\n * same `summary()`, and the cap reaches both payloads from one place; a second\n * copy of either is how a footer starts printing a number its own findings\n * contradict.\n */\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { listCodes } from \"../../core/explain/lookup.js\";\nimport {\n  countSeverity,\n  subjectsWith,\n  SEVERITY_MARK,\n  type Finding,\n  type TargetReport,\n} from \"../../core/vocabulary/report.js\";\nimport { EXPLAIN_FOOTER, plural } from \"../policy/format.js\";\nimport {\n  ADOPTION_AXES,\n  groupedWarnCodes,\n  type Adoption,\n  type AdoptionAxis,\n} from \"./fleet/scorecard/adoption.js\";\n\n/**\n * The rollup `--json` carries and the `--all` footer prints.\n *\n * Four named fields rather than a `Record<string, number>`: the keys ARE the\n * contract, and under an index signature every read of them was an assertion\n * (`s.errors!`) that tsc could not check — rename one and the compiler stayed\n * quiet while the footer printed `undefined errors`.\n */\nexport interface ValidateSummary {\n  services: number;\n  features: number;\n  errors: number;\n  warnings: number;\n}\n\nexport function summary(targets: TargetReport[]): ValidateSummary {\n  return {\n    services: targets.filter((t) => t.kind === \"service\").length,\n    features: targets.filter((t) => t.kind === \"feature\").length,\n    errors: countSeverity(targets, \"error\"),\n    warnings: countSeverity(targets, \"warn\"),\n  };\n}\n\n/**\n * How many services this run could not check, for the rollup line and the\n * `--json` payload.\n *\n * Counted off the findings rather than alongside them, so the rollup line\n * and the per-service findings can never disagree about how many services\n * this run could not check. The by-SUBJECT rule (a service whose spec.md and\n * arch.spec.md both name `sources` raises two findings and is one service) is\n * `subjectsWith`'s, spelled once for every findings-derived rollup — the\n * fleet scorecard counts through the same function on the same code, so its\n * number and this one are structurally the same number. The code is a LITERAL\n * rather than checks/vocabulary.ts's UNVERIFIABLE constant because the\n * stable-code collector reads counting sites too, and it refuses a slot it\n * cannot read — the collector is also what convicts a typo here.\n */\nexport function unverifiableSubjects(targets: TargetReport[]): number {\n  return subjectsWith(targets, \"sources.unverifiable-from-here\");\n}\n\n/**\n * How many `details` lines any one finding may print before the rest are\n * summarised away.\n *\n * A finding's details are evidence, not a log: LikeC4 reports one syntax error\n * as dozens of cascading diagnostics, and a fleet-sized repo multiplies that by\n * every target that mentions the file. The report is read by a person scrolling\n * a CI log and by an agent with a context window, and neither of them is helped\n * by the four-hundredth copy. The cap is applied to the JSON payload too, on\n * purpose: `--json` is the interface an agent pipes, and an unbounded array is\n * the same denial-of-attention there, just machine-readable.\n */\nconst DETAIL_LIMIT = 10;\n\n/** Truncate every finding's details, marking what was dropped so nothing looks complete when it is not. */\nexport function capDetails(t: TargetReport): TargetReport {\n  return {\n    ...t,\n    findings: t.findings.map((f) => {\n      const details = f.details ?? [];\n      if (details.length <= DETAIL_LIMIT) return f;\n      return {\n        ...f,\n        details: [...details.slice(0, DETAIL_LIMIT), `… (+${details.length - DETAIL_LIMIT} more)`],\n      };\n    }),\n  };\n}\n\n/**\n * One target's checks, with an IO exception turned into a finding ON that\n * target instead of aborting the run.\n *\n * A fleet gate that dies on the first unreadable file reports nothing about the\n * other ninety-nine services — one bad permission bit, one file that is a\n * dangling symlink, and CI's answer to \"how is the fleet\" becomes a stack\n * trace. The failure is real and it is an error, so the run still exits 1; what\n * changes is that everything else is still graded, and the finding names the\n * service and the path instead of arriving as the `internal` catch-all.\n */\nexport async function guarded(\n  target: { kind: \"service\" | \"feature\"; id: string },\n  run: () => Promise<TargetReport>,\n): Promise<TargetReport> {\n  try {\n    return await run();\n  } catch (err) {\n    // A docs repo that vanished mid-run is not one target's problem — it is the\n    // whole run's, and the action's own catch reports it.\n    if (err instanceof DocsRepoUnavailableError) throw err;\n    const path = (err as NodeJS.ErrnoException).path;\n    const reason = err instanceof Error ? err.message : String(err);\n    return {\n      kind: target.kind,\n      id: target.id,\n      findings: [\n        {\n          severity: \"error\",\n          code: target.kind === \"service\" ? \"service.unreadable\" : \"feature.unreadable\",\n          subject: target.id,\n          message:\n            `${target.id}: ${path === undefined ? \"an artifact\" : path} could not be read — ` +\n            `nothing about this ${target.kind} was checked. ${reason}`,\n        },\n      ],\n    };\n  }\n}\n\n/**\n * `target.ambiguous` — the positional named a service AND a feature. The tie is\n * still broken the way it always was (the feature wins), because changing which\n * one is picked would silently re-target every script that relies on it; what\n * is new is that the run says which reading it took and how to force the other.\n */\nexport function ambiguousTarget(arg: string, chosen: \"service\" | \"feature\"): Finding {\n  const other = chosen === \"feature\" ? \"service\" : \"feature\";\n  return {\n    severity: \"warn\",\n    code: \"target.ambiguous\",\n    subject: arg,\n    message:\n      `'${arg}' names both a service and a feature — validated as the ${chosen}. ` +\n      `Pass --${other} ${arg} for the other reading.`,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Text renderer                                                       */\n/* ------------------------------------------------------------------ */\n\n/** What `renderText` needs of the run beyond the graded targets themselves. */\nexport interface RenderOptions {\n  all: boolean;\n  errorsOnly: boolean;\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.\n */\nexport function renderText(targets: TargetReport[], opts: RenderOptions): void {\n  const { all, errorsOnly, unverifiable } = 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  for (const t of targets) {\n    const shown = t.findings.filter(\n      (f) => !isGrouped(f) && (!errorsOnly || f.severity !== \"ok\"),\n    );\n    if (shown.length === 0) continue;\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      // The whole report goes to stdout, in document order. 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      const marker = hint.marker === false ? \"\" : `${SEVERITY_MARK[f.severity]} `;\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      console.log(`${\" \".repeat(hint.indent ?? 0)}${marker}${f.message}${code}`);\n      for (const d of f.details ?? []) console.log(`    ${hint.detailPrefix ?? \"\"}${d}`);\n    }\n  }\n\n  if (!all) {\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  const s = summary(targets);\n  console.log(\n    `\\n${plural(s.services, \"service\")}, ${plural(s.features, \"feature\")} — ` +\n      `${plural(s.errors, \"error\")}, ${plural(s.warnings, \"warning\")}`,\n  );\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  if (pointer) console.log(`\\n${EXPLAIN_FOOTER}`);\n}\n"]}