@drkmttr/adhere 0.11.0 → 0.13.0

package/src/workflows/format.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_SUFFICIENCY_THRESHOLD, DEFAULT_THRESHOLD } from "#config.ts";
 import { type Kind, tokenize } from "#highlight.ts";
 import { shownId } from "#rules.ts";
 import type { AuditPlan, AuditResult, FileDone, Finding } from "#workflows/audit.ts";
@@ -11,11 +12,15 @@ type Role =
   | "error"
   | "warning"
   | "probability"
+  | "low"
+  | "below"
   | "description"
   | "path"
   | "lineNumber"
   | "underline"
   | "label"
+  | "legend"
+  | "quiet"
   | Kind;
 
 interface Span {
@@ -30,20 +35,28 @@ type Line = ReadonlyArray<Span>;
  * palette (`38;5;N`) or truecolor (`38;2;R;G;B`), bold with a trailing `;1`,
  * and a dim line number. Of the header, only the `×` and the rule are red, or
  * a warning's `⚠` and rule amber, since a whole line of red is hard to read:
- * the probability is an accent, and the description a cool near-white, set
- * here since a theme's own white can be gray. The code's are the terminal's
- * own colors (`3N`), so the user's theme picks shades that read on its
- * background; none is magenta, which would run into the underline.
+ * the description is a cool near-white, set here since a theme's own white
+ * can be gray. A score's three colors are one set, of like lightness, so
+ * they read as a scale, and none is the red of the `×`. Its labels, and the
+ * legend's meanings, are dim. The legend's words are bold in the terminal's
+ * own color, so they do not read as the hint's label. The code's are the
+ * terminal's own colors (`3N`), so the
+ * user's theme picks shades that read on its background; none is magenta,
+ * which would run into the underline.
  */
 const THEME: Readonly<Record<Role, string>> = {
   error: "38;2;164;20;71;1",
   warning: "38;2;214;154;0;1",
-  probability: "38;5;156",
+  probability: "38;2;152;195;121",
+  low: "38;2;229;192;123",
+  below: "38;2;224;108;117",
   description: "38;2;230;230;255",
   path: "38;2;5;125;160;1",
   lineNumber: "2",
   underline: "38;2;255;0;175",
   label: "38;2;242;205;205",
+  legend: "1",
+  quiet: "2",
   comment: "2",
   string: "32",
   constant: "33",
@@ -90,15 +103,60 @@ const displayPath = (file: string, root: string | undefined): string =>
 const counted = (count: number, one: string, many: string): string =>
   `${count} ${count === 1 ? one : many}`;
 
-const header = (finding: Finding): Line => [
-  span("  "),
-  span(finding.level === "warning" ? "⚠" : "×", finding.level),
-  span(" "),
-  span(shownId({ id: finding.rule, preset: finding.preset }), finding.level),
-  span(" ("),
-  span(finding.probability.toFixed(2), "probability"),
-  span("): "),
-  span(finding.description, "description"),
+/** A score as a header shows it, in hundredths, so two compare as they read. */
+const hundredths = (value: number): number => Math.round(value * 100);
+
+/**
+ * Where a confidence stops being far below a threshold and where it starts
+ * being well above it, in hundredths. Between the two it is near the
+ * threshold: within a quarter of the room above it, on either side, so the
+ * band narrows as the threshold rises and leaves room above for scores to be
+ * well clear of it. Scores that gather in the band, reported or not, turn on
+ * where the threshold sits, a sign it may be too low or too high.
+ */
+const bandsOf = (threshold: number): { readonly near: number; readonly clear: number } => {
+  const at = hundredths(threshold);
+  const margin = (100 - at) / 4;
+  return { near: Math.max(0, Math.ceil(at - margin)), clear: Math.ceil(at + margin) };
+};
+
+/**
+ * A score in one of three ranges set by its threshold: amber near it, red
+ * below that, the accent above. A confidence's threshold is its rule's, and
+ * a red one shows only in a run that prints every judgment. A context's is
+ * the sufficiency threshold, and a red one marks the finding to doubt first.
+ */
+const score = (value: number, threshold: number): Span => {
+  const { near, clear } = bandsOf(threshold);
+  const shown = hundredths(value);
+  return span(value.toFixed(2), shown < near ? "below" : shown < clear ? "low" : "probability");
+};
+
+const lacksContext = (finding: Finding, sufficiencyThreshold: number): boolean =>
+  finding.context !== undefined && finding.context < sufficiencyThreshold;
+
+/**
+ * The rule and its description, as `vp lint` heads a diagnostic, then the
+ * scores on a line of their own, where they start in one place whatever the
+ * rule's length. Their labels are dim, so only the numbers carry color.
+ */
+const header = (finding: Finding, sufficiencyThreshold: number): ReadonlyArray<Line> => [
+  [
+    span("  "),
+    span(finding.level === "warning" ? "⚠" : "×", finding.level),
+    span(" "),
+    span(shownId({ id: finding.rule, preset: finding.preset }), finding.level),
+    span(": "),
+    span(finding.description, "description"),
+  ],
+  [
+    span("    "),
+    span("confidence ", "quiet"),
+    score(finding.probability, finding.threshold),
+    ...(finding.context === undefined
+      ? []
+      : [span(" · context ", "quiet"), score(finding.context, sufficiencyThreshold)]),
+  ],
 ];
 
 /**
@@ -151,19 +209,14 @@ const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line
 
 /**
  * The warning on a finding whose file may not show enough to check its rule,
- * with Jev's probability that it does not, and help: how to add what the
- * code relies on as a note Jev reads, in the form the README asks for.
+ * which its context score in the header says how far, and help: how to add
+ * what the code relies on as a note Jev reads, in the form the README asks for.
  */
-const insufficient = (finding: Finding): ReadonlyArray<Line> =>
-  finding.insufficiency === undefined
+const insufficient = (finding: Finding, sufficiencyThreshold: number): ReadonlyArray<Line> =>
+  !lacksContext(finding, sufficiencyThreshold)
     ? []
     : [
-        [
-          span("  warning: ", "warning"),
-          span(
-            `this file may not show enough to check this rule (Jev: ${finding.insufficiency.toFixed(2)} that it does not)`,
-          ),
-        ],
+        [span("  warning: ", "warning"), span("this file may not show enough to check this rule")],
         ...hanging(span("     help: ", "label"), [
           [span("add what the code relies on outside this file as a note Jev reads:")],
           highlighted("// @adhere <the fact>, and how you know it")[0] ?? [],
@@ -183,17 +236,91 @@ const hint = (finding: Finding): ReadonlyArray<Line> => {
 
 /**
  * One diagnostic, in the frame `vp lint` prints on a terminal: a header with
- * the rule in red, the section of the file Jev points at with the lines it
- * names in pink, a warning when the file may not show enough to decide, and
- * the code to write as the hint.
+ * the rule in red and its scores, the description, the section of the file
+ * Jev points at with the lines it names in pink, a warning when the file may
+ * not show enough to decide, and the code to write as the hint.
  */
-const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
-  header(finding),
+const frame = (
+  finding: Finding,
+  root: string | undefined,
+  sufficiencyThreshold: number,
+): ReadonlyArray<Line> => [
+  ...header(finding, sufficiencyThreshold),
   ...excerpt(finding, root),
-  ...insufficient(finding),
+  ...insufficient(finding, sufficiencyThreshold),
   ...hint(finding),
 ];
 
+/** A bound of a range: hundredths as a score shows them, and 0 and 1 without decimals. */
+const bound = (value: number): string =>
+  value === 0 ? "0" : value === 100 ? "1" : (value / 100).toFixed(2);
+
+/** The scores from one number of hundredths through another: `0–0.74`, or `0.85–1`. */
+const range = (from: number, to: number): string => `${bound(from)}–${bound(to)}`;
+
+/**
+ * A legend row's cells for a threshold: the scores far below it, the
+ * threshold, and the scores well above it, as in `0–0.74 < 0.8 < 0.85–1`.
+ * The scores between the two ranges are the ones near the threshold, so it
+ * and each `<` are in their color, and the ranges in theirs. A threshold too low to
+ * have scores far below it has no first range, and no `<` after one.
+ */
+const cellsOf = (threshold: number): ReadonlyArray<Span> => {
+  const { near, clear } = bandsOf(threshold);
+  return [
+    span(near > 0 ? range(0, near - 1) : "", "below"),
+    span(near > 0 ? "<" : "", "low"),
+    span(String(hundredths(threshold) / 100), "low"),
+    span("<", "low"),
+    span(range(clear, 100), "probability"),
+  ];
+};
+
+/**
+ * What the scores under a header mean, once under the findings, as a table:
+ * a row for each score with its ranges around its threshold, then what the
+ * score is, dim. The cells stand in columns, so a color lines up down the
+ * rows. A confidence's threshold is the run's; a rule with a threshold of
+ * its own has its ranges around that. A context's is the sufficiency
+ * threshold.
+ */
+const legend = (
+  result: AuditResult,
+  threshold: number,
+  sufficiencyThreshold: number,
+): ReadonlyArray<Line> => {
+  const rows = [
+    ["confidence", cellsOf(threshold), "Jev's probability that the file breaks the rule"],
+    [
+      "context",
+      cellsOf(sufficiencyThreshold),
+      "its probability that the file shows enough to decide",
+    ],
+  ] as const;
+  const padding = (text: string, width: number): Span => span(" ".repeat(width - text.length));
+  const labels = Math.max(...rows.map(([label]) => label.length));
+  const widthOf = (column: number): number =>
+    Math.max(...rows.map(([, cells]) => cells[column]?.text.length ?? 0));
+  return result.findings.length === 0
+    ? []
+    : [
+        ...rows.map(([label, cells, meaning]) => [
+          span("  "),
+          span(label, "legend"),
+          padding(label, labels),
+          span(" "),
+          ...cells.flatMap((cell, column) => [
+            span(" "),
+            cell,
+            padding(cell.text, widthOf(column)),
+          ]),
+          span("  "),
+          span(meaning, "quiet"),
+        ]),
+        [],
+      ];
+};
+
 /** The findings counted by level: `1 error`, or `2 errors and 1 warning` once there are warnings. */
 const found = (findings: ReadonlyArray<Finding>): string => {
   const warnings = findings.filter((finding) => finding.level === "warning").length;
@@ -239,19 +366,29 @@ export interface RenderOptions {
   /** Color the frame the way `vp lint` does on a terminal, and highlight the code. */
   readonly color?: boolean;
   readonly root?: string;
+  /** The run's threshold, for the legend: lint reports no finding at or below it. Defaults to 0.8. */
+  readonly threshold?: number;
+  /** Below this, a finding's context is low and it carries a warning. Defaults to 0.6. */
+  readonly sufficiencyThreshold?: number;
 }
 
 /**
  * The report, in the default `vp lint` layout: each diagnostic followed by a
- * blank line, then the counts. Color is on when the caller is writing to a
- * terminal.
+ * blank line, then the legend for their scores, then the counts. Color is on
+ * when the caller is writing to a terminal.
  */
-export const render = (result: AuditResult, options: RenderOptions = {}): ReadonlyArray<string> =>
-  [
-    ...result.findings.flatMap((finding) => [...frame(finding, options.root), []]),
+export const render = (result: AuditResult, options: RenderOptions = {}): ReadonlyArray<string> => {
+  const sufficiencyThreshold = options.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD;
+  return [
+    ...result.findings.flatMap((finding) => [
+      ...frame(finding, options.root, sufficiencyThreshold),
+      [],
+    ]),
+    ...legend(result, options.threshold ?? DEFAULT_THRESHOLD, sufficiencyThreshold),
     ...summary(result),
     ...blockedFiles(result, options.root),
   ].map((line) => serialize(line, options.color === true));
+};
 
 /**
  * What a run will do, before it asks: the files and rules found, the checks