efaimo 0.1.2 → 0.2.0

package/dist/reporters/json.js

@@ -1,10 +1,21 @@
 import { VERSION } from "../version.js";
-export function toJsonEnvelope(kind, data) {
+import { RULES_VERSION } from "../rules/version.js";
+export function toJsonEnvelope(kind, data, opts = {}) {
     return JSON.stringify({
         tool: "efaimo",
         version: VERSION,
+        // Which ruleset produced this. The tool version alone does not say it: a
+        // patch release can change what a rule fires on, and every published
+        // grade is only reproducible if the reader can tell which rules were
+        // being run. See src/rules/version.ts.
+        //
+        // Only where rules actually ran. `weigh` counts tokens and `test` runs
+        // trials; neither evaluates a rule, and stamping a ruleset onto their
+        // output would be a report asserting which rules produced it when none
+        // did.
+        ...(kind === "check" || kind === "find" ? { rulesVersion: RULES_VERSION } : {}),
         kind,
-        generatedAt: new Date().toISOString(),
+        ...(opts.timestamp === false ? {} : { generatedAt: new Date().toISOString() }),
         data,
     }, null, 2);
 }

package/dist/reporters/markdown.d.ts

@@ -1,7 +1,8 @@
-import type { CheckReport, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
+import type { CheckReport, Finding, FindResult, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
 import type { CheckSkillResult } from "../check/check.js";
 import type { WeighDiff } from "../weigh/diff.js";
 export declare function renderCheckMarkdown(report: CheckReport): string;
 export declare function renderSkillSetMarkdown(res: CheckSkillResult): string;
 export declare function renderWeighMarkdown(w: ServerWeighResult | SkillSetWeighResult): string;
+export declare function renderFindMarkdown(f: FindResult, findings: Finding[]): string;
 export declare function renderDiffMarkdown(d: WeighDiff): string;

package/dist/reporters/markdown.js

@@ -3,23 +3,57 @@ import { safeText } from "../util/safeText.js";
 const SEV_LABEL = { error: "🔴 error", warn: "🟡 warn", info: "🔵 info" };
 // Everything through here came from the audited target, and
 // docs/INTEGRATIONS.md recommends piping --md into $GITHUB_STEP_SUMMARY, so a
-// hostile tool name or description renders into a page the reader trusts.
-// Two things were missing: control characters (raw ESC bytes were written
-// through literally) and backticks (most call sites wrap the value in a code
-// span, so one backtick closes it and the rest of the name becomes markup).
-// The backtick is neutralised with a zero-width space rather than a backslash,
-// because a backslash is not an escape inside a code span.
-function esc(s) {
+// hostile tool name or description renders into a page the reader trusts. An
+// auditor's verdict must not be rewritable by the thing being audited.
+//
+// Two escapes that were here did not work, both found by adversarial review:
+//
+//   `\|`  was applied without escaping the backslash first. A name containing
+//         backslash-pipe became `\\|`, which GFM reads as an escaped backslash
+//         followed by a LIVE cell delimiter. Extra cells past the header count
+//         are dropped, so a hostile server could push the real verdict column
+//         off the end of the row and supply its own.
+//
+//   `` ` `` was neutralised by putting a zero-width space BEFORE it, which
+//         changes nothing: a code span ends at the next backtick run whatever
+//         precedes it. The rest of the name then rendered as live markup, and a
+//         `[click](url)` in a tool name became a link in the summary. A
+//         backtick cannot be escaped inside a code span at all, so it is
+//         substituted rather than escaped; a tool whose name contains one is
+//         still recognisable and can no longer close the span.
+function escCode(s) {
     return safeText(s)
+        .replace(/[\r\n]+/g, " ")
+        .replace(/\\/g, "\\\\")
         .replace(/\|/g, "\\|")
-        .replace(/`/g, "​`")
-        .replace(/\n/g, " ");
+        .replace(/`/g, "'");
 }
+// For a cell that is NOT wrapped in a code span, where markdown and inline
+// HTML are both live. Every value that reaches one of these should really be
+// in a code span; this is the belt for the places that are not, such as rule
+// messages, which embed a tool name mid-sentence.
+function escText(s) {
+    return escCode(s)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/([[\]*_~])/g, "\\$1");
+}
+/** Backwards-compatible alias for the code-span form, which is what most call sites want. */
+const esc = escCode;
 function findingsTable(lines, findings) {
     lines.push("| severity | rule | finding |");
     lines.push("|---|---|---|");
     for (const f of findings) {
-        lines.push(`| ${SEV_LABEL[f.severity]} | ${f.ruleId} | ${esc(f.message)} |`);
+        // escText, not escCode: a message is prose, not a code span, so markdown
+        // and inline HTML are both live in this cell. The message embeds a tool
+        // name the target chose.
+        //
+        // detail and fixHint were dropped here, so E141's "every word it has also
+        // appears on: ..." and E142's "outranked by: ..." existed in the terminal
+        // and in JSON and silently vanished from the surface the CI docs recommend.
+        const extra = [f.detail, f.fixHint && `fix: ${f.fixHint}`].filter(Boolean).join(" ");
+        lines.push(`| ${SEV_LABEL[f.severity]} | ${f.ruleId} | ${escText(f.message)}${extra ? ` <br>${escText(extra)}` : ""} |`);
     }
 }
 export function renderCheckMarkdown(report) {
@@ -85,7 +119,10 @@ export function renderWeighMarkdown(w) {
         lines.push(`| Claude-style | ${w.totals.claudeStyle.toLocaleString("en-US")} |`);
         lines.push(`| OpenAI tools | ${w.totals.openaiTools.toLocaleString("en-US")} |`);
         if (w.anthropicExactTotal !== undefined) {
-            lines.push(`| anthropic exact (API) | ${w.anthropicExactTotal.toLocaleString("en-US")} |`);
+            // Names the model, like the terminal does. Without it the same figure
+            // was reproducible from --json and from pretty output but not from --md,
+            // which is the surface the CI docs recommend piping into a summary.
+            lines.push(`| anthropic exact (count_tokens, ${escCode(w.anthropicExactModel ?? "model not recorded")}) | ${w.anthropicExactTotal.toLocaleString("en-US")} |`);
         }
         lines.push("");
         if (w.perTool.length) {
@@ -115,6 +152,67 @@ export function renderWeighMarkdown(w) {
         lines.push(`> ${esc(note)}`);
     return lines.join("\n");
 }
+export function renderFindMarkdown(f, findings) {
+    const lines = [];
+    lines.push(`## efaimo find: ${f.distinct.count}/${f.distinct.total} tools own a distinct word`);
+    lines.push("");
+    lines.push(`target: \`${esc(f.label)}\``);
+    lines.push("");
+    lines.push(`**distinct ${f.distinct.count}/${f.distinct.total} (${f.distinct.pct}%)** tools that own a word no other tool has. ` +
+        `Probe ${f.probe.returned}/${f.probe.total} (${f.probe.pct}%) returned by a simulated search for their own description.`);
+    lines.push("");
+    if (f.distinctVacuous) {
+        lines.push(`> **Distinct is vacuous here.** A one-tool catalog has nothing to be distinct from.`);
+        lines.push("");
+    }
+    if (f.windowCoversCatalog) {
+        lines.push(`> **The probe is vacuous here.** ${f.toolCount} tools and a result window of ${f.method.topK}, so no tool can fall outside it.`);
+        lines.push("");
+    }
+    lines.push("| words | tool | vocabulary no other tool has | probe |");
+    lines.push("|---|---|---|---|");
+    const byWorst = [...f.perTool].sort((a, b) => {
+        const ar = a.rank ?? Number.POSITIVE_INFINITY;
+        const br = b.rank ?? Number.POSITIVE_INFINITY;
+        return a.ownTermCount - b.ownTermCount || br - ar || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    });
+    // Capped, like every other table here. Uncapped, a 3,000-tool catalog wrote
+    // 74 KB of rows and a large aggregate would blow GitHub's 1 MiB step-summary
+    // limit, failing the step it was meant to annotate.
+    const MD_ROWS = 50;
+    for (const t of byWorst.slice(0, MD_ROWS)) {
+        const own = t.ownTermCount === 0
+            ? t.sharedWith.length
+                ? `none, every word also on ${t.sharedWith.map((s) => `\`${escCode(s)}\``).join(", ")}`
+                : "none"
+            : `\`${escCode(t.ownTerms.join(", "))}\`` +
+                (t.ownTermCount > t.ownTerms.length ? ` (+${t.ownTermCount - t.ownTerms.length})` : "");
+        // Blank when it has nothing to say, matching the terminal. A column of
+        // "ok" down every row is a value that never varies presented as a
+        // measurement, which is the thing renderFindPretty refuses to do.
+        const probe = t.rank === undefined ? "no description" : t.reachable ? "" : `rank ${t.rank}`;
+        lines.push(`| ${t.ownTermCount} | \`${escCode(t.name)}\` | ${own} | ${probe} |`);
+    }
+    if (byWorst.length > MD_ROWS) {
+        lines.push(`| | *(+${byWorst.length - MD_ROWS} more, see \`--json\`)* | | |`);
+    }
+    lines.push("");
+    lines.push("### findings");
+    lines.push("");
+    if (!findings.length)
+        lines.push("no findability findings.");
+    else
+        findingsTable(lines, findings);
+    lines.push("");
+    // A blank line between blockquotes, or CommonMark lazily continues them into
+    // one paragraph and five separate notes render as one wall of prose.
+    for (const note of f.notes) {
+        lines.push(`> ${escText(note)}`);
+        lines.push("");
+    }
+    lines.push(`<sub>efaimo v${VERSION}</sub>`);
+    return lines.join("\n");
+}
 export function renderDiffMarkdown(d) {
     const sign = d.delta >= 0 ? "+" : "";
     const lines = [];

package/dist/reporters/pretty.d.ts

@@ -1,4 +1,4 @@
-import type { CheckReport, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
+import type { CheckReport, Finding, FindResult, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
 import type { CheckSkillResult } from "../check/check.js";
 import type { Scenario, TestReport } from "../testing/harness.js";
 import type { WeighDiff } from "../weigh/diff.js";
@@ -9,6 +9,17 @@ export declare function renderTestReportPretty(r: TestReport): string;
 export declare function renderSkillSetPretty(res: CheckSkillResult): string;
 export declare function renderServerWeighPretty(w: ServerWeighResult): string;
 export declare function renderSkillWeighPretty(w: SkillSetWeighResult): string;
+/**
+ * `efaimo find`.
+ *
+ * Two numbers, both as fractions with their denominators printed, neither a
+ * letter. The first is a property of the catalog; the second is a simulation
+ * and is labelled as one on the line itself, because a saturated 100% next to
+ * a real measurement reads like a good score unless the page says otherwise.
+ */
+export declare function renderFindPretty(f: FindResult): string;
+/** The findings half of `efaimo find`, printed under the table. */
+export declare function renderFindFindingsPretty(f: FindResult, findings: Finding[]): string;
 export declare function renderDiffPretty(d: WeighDiff, opts: {
     maxTokens?: number;
     allowIncreasePct?: number;

package/dist/reporters/pretty.js

@@ -1,6 +1,7 @@
 import pc from "picocolors";
 import { formatWindowShare } from "../weigh/window.js";
 import { sortFindings } from "../core/grade.js";
+import { minimumDetectableDelta } from "../testing/stats.js";
 import { VERSION } from "../version.js";
 import { safeText } from "../util/safeText.js";
 const DOCS_RULES = "https://github.com/efaimo-ai/efaimo/blob/main/docs/RULES.md";
@@ -32,8 +33,23 @@ function gradeColor(letter, text) {
 function n(x) {
     return x.toLocaleString("en-US");
 }
+/**
+ * A value that has to stay inside one line of a table or one line of a
+ * finding.
+ *
+ * `safeText` strips control characters but deliberately keeps newlines,
+ * because a detail block is meant to be multi-line. That is the wrong default
+ * for a single cell: a tool named
+ * `nl_tool\n      9  forged_row      weather, forecast` renders as a SECOND
+ * row byte-identical in shape to a real one, and under `--no-color`, which is
+ * how CI logs read, there is no tell at all. The audited thing must not be
+ * able to write rows in the auditor's table.
+ */
+function cell(s) {
+    return safeText(s).replace(/[\r\n]+/g, " ");
+}
 function renderFinding(lines, f) {
-    lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${safeText(f.message)}`);
+    lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${cell(f.message)}`);
     if (f.detail) {
         for (const d of safeText(f.detail).split("\n"))
             lines.push(paint(pc.dim, `          ${d}`));
@@ -80,13 +96,23 @@ export function renderCheckPretty(report) {
 export function renderScenarioPlan(s) {
     const calls = s.trials * 2 * 2;
     const firstLine = s.task.split("\n")[0].slice(0, 60);
+    const mde = minimumDetectableDelta(s.trials);
     return [
         paint(pc.dim, `efaimo v${VERSION}`),
         `test (dry run)  ${paint(pc.bold, s.name)}`,
         "",
         `  skill   ${s.skillName}`,
         `  model   ${s.model}`,
+        `  judge   ${s.judgeModel}${s.judgeModel === s.model
+            ? paint(pc.yellow, "   (same model grades its own answers; set judge_model or --judge-model to separate them)")
+            : ""}`,
         `  plan    ${s.trials} trials x 2 arms x (task + judge) = ${paint(pc.bold, String(calls))} API calls`,
+        // What this plan cannot detect, before any tokens are spent. A run that
+        // cannot reach significance produces a green that means nothing, and the
+        // only useful moment to learn that is now.
+        `  power   ${Number.isFinite(mde)
+            ? `the smallest gap this size can call significant is ${paint(mde > 40 ? pc.yellow : pc.dim, `${mde.toFixed(0)} points`)}${mde > 40 ? paint(pc.yellow, "   (raise trials)") : ""}`
+            : paint(pc.red, "no outcome at this size can reach p < 0.05; raise trials")}`,
         `  task    ${paint(pc.dim, firstLine + (s.task.length > 60 ? "..." : ""))}`,
         "",
         paint(pc.yellow, "dry run: no API calls made. add --live to run it (Claude models need ANTHROPIC_API_KEY, GPT models need OPENAI_API_KEY)."),
@@ -98,7 +124,7 @@ export function renderTestReportPretty(r) {
     const lines = [
         paint(pc.dim, `efaimo v${VERSION}`),
         `test  ${paint(pc.bold, r.scenario)}`,
-        `skill ${r.skill}   model ${r.model}`,
+        `skill ${r.skill}   model ${r.model}   judge ${r.judgeModel}${r.judgeModel === r.model ? paint(pc.dim, " (same model)") : ""}`,
         "",
         `  with skill     ${r.withSkill.passes}/${r.withSkill.scored} pass  (${r.withSkill.passRate.toFixed(0)}%)`,
         `  without skill  ${r.withoutSkill.passes}/${r.withoutSkill.scored} pass  (${r.withoutSkill.passRate.toFixed(0)}%)`,
@@ -130,21 +156,21 @@ export function renderSkillSetPretty(res) {
     for (const s of [...res.perSkill].sort((a, b) => a.report.grade.score - b.report.grade.score)) {
         const g = s.report.grade;
         const c = s.report.counts;
-        lines.push(`  ${gradeColor(g.letter, `${g.letter} (${String(g.score).padStart(3)})`)}  ${safeText(s.name).padEnd(nameW)}  ` +
+        lines.push(`  ${gradeColor(g.letter, `${g.letter} (${String(g.score).padStart(3)})`)}  ${cell(s.name).padEnd(nameW)}  ` +
             `${paint(pc.red, String(c.error))}e ${paint(pc.yellow, String(c.warn))}w ${paint(pc.cyan, String(c.info))}i`);
     }
     if (res.setFindings.length) {
         lines.push("");
         lines.push(paint(pc.bold, "across the set"));
         for (const f of sortFindings(res.setFindings)) {
-            lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${safeText(f.message)}`);
+            lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${cell(f.message)}`);
         }
     }
     const flagged = res.perSkill.filter((s) => s.report.findings.length);
     if (flagged.length) {
         lines.push("");
         for (const s of flagged) {
-            lines.push(paint(pc.bold, `${safeText(s.name)}  ${gradeColor(s.report.grade.letter, s.report.grade.letter)}`));
+            lines.push(paint(pc.bold, `${cell(s.name)}  ${gradeColor(s.report.grade.letter, s.report.grade.letter)}`));
             for (const f of s.report.findings) {
                 lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${safeText(f.message)}`);
                 if (f.fixHint)
@@ -170,7 +196,7 @@ export function renderServerWeighPretty(w) {
     if (w.instructionsTokens > 0)
         lines.push(`  server instructions ${n(w.instructionsTokens).padStart(4)}`);
     if (w.anthropicExactTotal !== undefined) {
-        lines.push(`  ${paint(pc.green, "anthropic exact")} ${n(w.anthropicExactTotal).padStart(8)}   (count_tokens API)`);
+        lines.push(`  ${paint(pc.green, "anthropic exact")} ${n(w.anthropicExactTotal).padStart(8)}   (count_tokens, ${safeText(w.anthropicExactModel ?? "model not recorded")})`);
     }
     if (w.perTool.length) {
         lines.push("");
@@ -183,9 +209,9 @@ export function renderServerWeighPretty(w) {
         // column in its own flagship demo. Capped so one pathological name cannot
         // push the numbers off a terminal.
         const shown = w.perTool.slice(0, 8);
-        const toolW = Math.min(38, Math.max(20, ...shown.map((t) => safeText(t.name).length)));
+        const toolW = Math.min(38, Math.max(20, ...shown.map((t) => cell(t.name).length)));
         for (const [i, t] of shown.entries()) {
-            lines.push(`  ${String(i + 1).padStart(2)}. ${safeText(t.name).padEnd(toolW)} ${n(t.tokens.claudeStyle).padStart(7)}   desc ${n(t.descriptionTokens)} | schema ${n(t.schemaTokens)}`);
+            lines.push(`  ${String(i + 1).padStart(2)}. ${cell(t.name).padEnd(toolW)} ${n(t.tokens.claudeStyle).padStart(7)}   desc ${n(t.descriptionTokens)} | schema ${n(t.schemaTokens)}`);
         }
         if (w.perTool.length > 8)
             lines.push(paint(pc.dim, `      (+${w.perTool.length - 8} more)`));
@@ -205,7 +231,7 @@ export function renderSkillWeighPretty(w) {
     lines.push("");
     lines.push(`  ${"skill".padEnd(28)} ${"metadata".padStart(8)} ${"body".padStart(9)} ${"lines".padStart(6)}  refs`);
     for (const s of w.perSkill) {
-        lines.push(`  ${safeText(s.name).padEnd(28)} ${n(s.metadataTokens).padStart(8)} ${n(s.bodyTokens).padStart(9)} ${String(s.bodyLines).padStart(6)}  ${s.refFileCount ? `${s.refFileCount} files ${n(s.refFileTokens)}` : "-"}`);
+        lines.push(`  ${cell(s.name).padEnd(28)} ${n(s.metadataTokens).padStart(8)} ${n(s.bodyTokens).padStart(9)} ${String(s.bodyLines).padStart(6)}  ${s.refFileCount ? `${s.refFileCount} files ${n(s.refFileTokens)}` : "-"}`);
     }
     lines.push("");
     lines.push(`totals: metadata ${paint(pc.bold, n(w.totals.metadata))} (always loaded) | body ${n(w.totals.body)} (on trigger) | referenced ${n(w.totals.refFiles)} (on demand)`);
@@ -214,6 +240,145 @@ export function renderSkillWeighPretty(w) {
         lines.push(paint(pc.dim, `note: ${safeText(note)}`));
     return lines.join("\n");
 }
+/**
+ * `efaimo find`.
+ *
+ * Two numbers, both as fractions with their denominators printed, neither a
+ * letter. The first is a property of the catalog; the second is a simulation
+ * and is labelled as one on the line itself, because a saturated 100% next to
+ * a real measurement reads like a good score unless the page says otherwise.
+ */
+export function renderFindPretty(f) {
+    const lines = [];
+    lines.push(paint(pc.dim, `efaimo v${VERSION}`));
+    lines.push(`find mcp  ${paint(pc.bold, safeText(f.label))}`);
+    lines.push(paint(pc.dim, `tools ${f.toolCount}   result window ${f.method.topK}   BM25 k1=${f.method.bm25.k1} b=${f.method.bm25.b}, ${f.method.queryTerms} query terms`));
+    lines.push("");
+    // Coloured on the rule condition, not on invented cutoffs. An earlier
+    // version banded this at 95 and 80 percent, two numbers that appear in no
+    // rule, no doc and no ADR, inside the one command whose whole design note
+    // says it does not grade. Red means E141 fired; that is a threshold the
+    // ruleset already owns.
+    const dpct = f.distinct.pct;
+    const anyOwnsNothing = f.distinct.count < f.distinct.total;
+    const dcolor = f.distinctVacuous ? pc.dim : anyOwnsNothing ? pc.red : pc.green;
+    const dFrac = `${f.distinct.count}/${f.distinct.total} (${dpct}%)`;
+    const pFrac = `${f.probe.returned}/${f.probe.total} (${f.probe.pct}%)`;
+    // Pad on the plain text, never on the painted string: colour codes are bytes
+    // that padEnd counts and a terminal does not, which is how a coloured column
+    // ends up crooked in exactly the demo everyone screenshots.
+    const fracW = Math.max(dFrac.length, pFrac.length);
+    lines.push(`distinct  ${paint(dcolor, dFrac)}${" ".repeat(fracW - dFrac.length)}` +
+        `   ${paint(pc.dim, "tools that own a word no other tool has")}`);
+    if (f.distinctVacuous) {
+        lines.push(paint(pc.yellow, `          vacuous: a one-tool catalog has nothing to be distinct from, so this is 100% for any tool`));
+    }
+    lines.push(`probe     ${paint(pc.dim, pFrac)}${" ".repeat(fracW - pFrac.length)}` +
+        `   ${paint(pc.dim, "returned by a simulated search for their own description")}`);
+    if (f.windowCoversCatalog) {
+        lines.push(paint(pc.yellow, `          vacuous: ${f.toolCount} tools fit inside a window of ${f.method.topK}, so none can fall outside it`));
+    }
+    lines.push("");
+    // Worst first. A reader scanning the top of the table should be looking at
+    // the tools that cannot be told apart, not at an alphabetical list.
+    const byWorst = [...f.perTool].sort((a, b) => {
+        const ar = a.rank ?? Number.POSITIVE_INFINITY;
+        const br = b.rank ?? Number.POSITIVE_INFINITY;
+        return (a.ownTermCount - b.ownTermCount ||
+            br - ar ||
+            (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    });
+    const shown = byWorst.slice(0, 15);
+    const nameW = Math.min(34, Math.max(12, ...shown.map((t) => cell(t.name).length)));
+    lines.push(paint(pc.dim, `  words  ${"tool".padEnd(nameW)}  vocabulary no other tool has`));
+    for (const t of shown) {
+        const count = t.ownTermCount === 0
+            ? paint(pc.red, "    0")
+            : t.ownTermCount === 1
+                ? paint(pc.yellow, "    1")
+                : paint(pc.green, String(t.ownTermCount).padStart(5));
+        let tail;
+        if (t.ownTermCount === 0) {
+            tail = paint(pc.red, t.sharedWith.length ? `none: every word also on ${cell(t.sharedWith.join(", "))}` : "none");
+        }
+        else {
+            const more = t.ownTermCount - t.ownTerms.length;
+            tail = paint(pc.dim, cell(t.ownTerms.join(", ")) + (more > 0 ? ` (+${more})` : ""));
+        }
+        // The probe only ever appears as a flag on a row it failed. A column of
+        // "1" down the whole table would be a number that never varies presented
+        // as if it were a measurement.
+        const probe = t.rank === undefined
+            ? paint(pc.red, "   [probe: no description]")
+            : t.reachable
+                ? ""
+                : paint(pc.red, `   [probe: rank ${t.rank}]`);
+        lines.push(`  ${count}  ${cell(t.name).padEnd(nameW)}  ${tail}${probe}`);
+    }
+    // Describe the hidden rows from the hidden rows, never from an assumption.
+    // This line used to read "(+N more, each owning at least one word)" without
+    // checking: on a catalog where all 18 tools owned nothing it printed that
+    // three lines under a `0/18` headline saying the opposite.
+    const hiddenRows = byWorst.slice(shown.length);
+    if (hiddenRows.length) {
+        const hiddenAtZero = hiddenRows.filter((t) => t.ownTermCount === 0).length;
+        lines.push(paint(pc.dim, `         (+${hiddenRows.length} more` +
+            (hiddenAtZero ? `, ${hiddenAtZero} of them owning no word` : ", each owning at least one word") +
+            `; --json for all of them)`));
+    }
+    return lines.join("\n");
+}
+/** The findings half of `efaimo find`, printed under the table. */
+export function renderFindFindingsPretty(f, findings) {
+    const lines = [""];
+    if (!findings.length) {
+        lines.push(paint(pc.green, "  no findability findings."));
+    }
+    else {
+        for (const x of sortFindings(findings))
+            renderFinding(lines, x);
+    }
+    lines.push("");
+    for (const note of f.notes) {
+        // The two vacuity notes are already printed inline, in yellow, on the row
+        // the reader is looking at. Repeating them here as prose was the same
+        // warning twice in one screen; the data still carries them for --json and
+        // --md, where there is no inline row to carry it.
+        if (note.startsWith("VACUOUS"))
+            continue;
+        for (const [i, line] of wrapNote(safeText(note)).entries()) {
+            lines.push(paint(pc.dim, i === 0 ? `note: ${line}` : `      ${line}`));
+        }
+    }
+    // What to do next. A clean run used to end on "no findability findings" and
+    // a rules URL, which tells a first-time reader nothing about how to keep it
+    // that way. `distinct` is named because it is the number that can fail at
+    // any catalog size; the probe cannot.
+    if (!f.distinctVacuous) {
+        lines.push(paint(pc.dim, `gate it: efaimo find "<server>" --min-distinct ${Math.floor(f.distinct.pct)}` +
+            (f.distinct.pct < 100 ? "   (raise it as you fix the tools above)" : "")));
+    }
+    lines.push(paint(pc.dim, `rules: ${DOCS_RULES}`));
+    return lines.join("\n");
+}
+/** Soft-wrap a long note at ~92 columns on word boundaries, so terminals do not ragged-wrap mid-number. */
+function wrapNote(s, width = 92) {
+    const out = [];
+    for (const paragraph of s.split("\n")) {
+        let line = "";
+        for (const word of paragraph.split(/\s+/)) {
+            if (line && line.length + 1 + word.length > width) {
+                out.push(line);
+                line = word;
+            }
+            else {
+                line = line ? `${line} ${word}` : word;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
 export function renderDiffPretty(d, opts) {
     const lines = [];
     const sign = d.delta >= 0 ? "+" : "";

package/dist/rules/find/index.d.ts

@@ -0,0 +1,4 @@
+import type { FindRule } from "../../core/types.js";
+export declare const FIND_RULES: FindRule[];
+/** E141-E146 are findability rules: reported by `efaimo find`, never part of a `check` grade. */
+export declare function isFindabilityRuleId(id: string): boolean;