@cplieger/deadset-ts 3.9.1 → 3.11.0

package/src/reporters/text.ts

@@ -1,5 +1,4 @@
-import type { WireTotals } from "../report.ts";
-import type { Reporter } from "./reporter.ts";
+import type { Report, WireTotals } from "../report.ts";
 
 /** The kind token and the confidence a stale suppression is rendered with, both fixed. */
 const STALE_KIND = "suppression";
@@ -30,7 +29,7 @@ function summary(totals: WireTotals): string {
  * summary is deliberately not in that shape, so a filter for finding lines yields exactly
  * them. Nothing else is written: no timestamp, duration or host detail.
  */
-export const text: Reporter = (report) => {
+export const text = (report: Report): string => {
   const lines = report.findings.map(
     (found) =>
       `${found.position.path}:${String(found.position.line)}:${String(found.position.column)}: ${found.symbol.kind} ${found.symbol.name}: ${found.message} [${found.confidence}] (${found.code})`,

package/src/run.ts

@@ -11,6 +11,7 @@ import { printRetainedVerb } from "./verbs/print-retained.ts";
 import { printRootsVerb } from "./verbs/print-roots.ts";
 import { ANALYZE_OPTIONS, analyzeVerb } from "./verbs/analyze.ts";
 import { describeVerb } from "./verbs/describe.ts";
+import { EXPLAIN_OPTIONS, explainVerb } from "./verbs/explain.ts";
 import { EXIT_FAILURE, EXIT_USAGE, type Verb, type VerbOptions } from "./verbs/verb.ts";
 import { versionVerb } from "./verbs/version.ts";
 
@@ -19,17 +20,14 @@ export interface Writer {
   write(text: string): void;
 }
 
-/**
- * Every verb this command answers, in the order the usage text lists them. A verb
- * with no `run` is listed, and invoking it is a usage error.
- */
+/** Every verb this command answers, in the order the usage text lists them. */
 const VERBS: readonly {
   readonly name: string;
-  readonly run?: Verb;
+  readonly run: Verb;
   readonly options?: VerbOptions;
 }[] = [
   { name: "analyze", run: analyzeVerb, options: ANALYZE_OPTIONS },
-  { name: "explain" },
+  { name: "explain", run: explainVerb, options: EXPLAIN_OPTIONS },
   { name: "print-config", run: printConfigVerb },
   { name: "print-projects", run: printProjectsVerb },
   { name: "print-roots", run: printRootsVerb },
@@ -219,7 +217,7 @@ export function run(
 
   const name = args[0];
   const verb = VERBS.find((listed) => listed.name === name);
-  if (verb?.run !== undefined) {
+  if (verb !== undefined) {
     return invoke(
       verb.run,
       verb.options ?? NO_OPTIONS,
@@ -228,10 +226,6 @@ export function run(
       openClient,
     );
   }
-  if (verb !== undefined) {
-    err.write(`deadset-ts: ${verb.name} is not implemented\n`);
-    return EXIT_USAGE;
-  }
   if (name !== undefined) {
     err.write(`deadset-ts: unknown verb ${JSON.stringify(name)}\n`);
   }

package/src/verbs/analyze.ts

@@ -1,9 +1,9 @@
 import { runAnalysis, type RunProject } from "../analysis.ts";
 import { ConfigError, type Format } from "../config.ts";
-import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.ts";
+import { CONFORMANCE, DECLARED_GAPS } from "../conformance.ts";
 import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.ts";
 import { packageScope } from "../inventory.ts";
-import { normalizePath, relativePath, resolvePath } from "../paths.ts";
+import { joinPath, normalizePath, relativePath, resolvePath } from "../paths.ts";
 import type { Host } from "../host.ts";
 import {
   buildReport,
@@ -14,6 +14,7 @@ import {
 } from "../report.ts";
 import { json } from "../reporters/json.ts";
 import { RENDERINGS } from "../reporters/reporters.ts";
+import { parseTemplate, TemplateError, type Template } from "../reporters/template.ts";
 import { resolve } from "../resolve.ts";
 import type { Module } from "../scope.ts";
 import { writeBaseline, type Recorded } from "../suppress-file.ts";
@@ -22,7 +23,7 @@ import { EXIT_CLEAN, EXIT_FAILURE, type Verb, type VerbOptions } from "./verb.ts
 
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS: VerbOptions = {
-  plain: ["report", "baseline-write", "exit-code"],
+  plain: ["report", "baseline-write", "exit-code", "template"],
   repeatable: ["format"],
 };
 
@@ -110,6 +111,47 @@ function counted(n: number, noun: string): string {
   return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
 }
 
+/**
+ * The template `--template` names, read and parsed before any analysis, so a template that
+ * cannot be read or does not parse refuses the invocation. The template format with no
+ * template named is refused the same way.
+ */
+function templateOf(
+  host: Host,
+  invoked: string,
+  named: string | undefined,
+  formats: readonly Format[],
+): Template | undefined {
+  if (named === undefined || named === "") {
+    if (formats.includes("template")) {
+      throw new ConfigError(
+        "malformed",
+        "",
+        "the template format renders the template --template names, and none was named",
+      );
+    }
+    return undefined;
+  }
+  let source: string;
+  try {
+    source = host.readFile(resolvePath(invoked, named));
+  } catch (error: unknown) {
+    throw new ConfigError(
+      "malformed",
+      "",
+      `--template=${named}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  try {
+    return parseTemplate(source);
+  } catch (error: unknown) {
+    if (!(error instanceof TemplateError)) {
+      throw error;
+    }
+    throw new ConfigError("malformed", "", `--template=${named}: ${error.message}`);
+  }
+}
+
 /** Every document one invocation asked for: the report, each rendering beside it, a baseline. */
 interface Documents {
   readonly report: string;
@@ -121,8 +163,9 @@ interface Documents {
  * Analyzes the scope under the configuration and writes the JSON report to the path
  * `--report` names, each rendering `--format` names beside it at the report's path with the
  * format's suffix appended, and a baseline of every finding where `--baseline-write` names a
- * path. Nothing is written to the output stream; diagnostics go to the error stream and the
- * verdict is the exit code, or 0 under `--exit-code=off`.
+ * path. The template format renders the template `--template` names. Nothing is written to
+ * the output stream; diagnostics go to the error stream and the verdict is the exit code, or 0
+ * under `--exit-code=off`, and a rendering that cannot be written ends the run with 3.
  */
 export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option, repeated }) => {
   const reportPath = option("report");
@@ -153,6 +196,7 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
     formats: formatsOf(repeated("format"), config.reporters.formats),
     baseline: baseline === undefined ? undefined : resolvePath(invoked, baseline),
   };
+  const template = templateOf(host, invoked, option("template"), documents.formats);
   const scoped = scope();
   const targetRoot = scoped.target.path;
 
@@ -175,7 +219,8 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
     const built = buildReport({
       contractVersion: CONTRACT_VERSION,
       version,
-      conformance: reportedConformance(RECORDED_CONFORMANCE),
+      conformance: CONFORMANCE,
+      declaredGaps: DECLARED_GAPS,
       target: { kind, root, identity: identityOf(scoped.target, host) },
       configurations: configurationsOf(run.projects, targetRoot),
       unavailable: scoped.consumers.map((consumer) => ({
@@ -200,10 +245,15 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
 
   try {
     host.writeFile(documents.report, json(report));
+    const options = {
+      failOn: config.reporters.failOn,
+      readSource: (path: string) => host.readFile(joinPath(targetRoot, path)),
+      template,
+    };
     for (const format of documents.formats) {
       const rendering = RENDERINGS.get(format);
       if (rendering !== undefined) {
-        host.writeFile(documents.report + rendering.suffix, rendering.render(report));
+        host.writeFile(documents.report + rendering.suffix, rendering.render(report, options));
       }
     }
     if (documents.baseline !== undefined) {

package/src/verbs/describe.ts

@@ -1,4 +1,4 @@
-import { RECORDED_CONFORMANCE, type Conformance } from "../conformance.ts";
+import { CONFORMANCE, type Conformance } from "../conformance.ts";
 import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.ts";
 import { CONTRACT_VERSION } from "../version.ts";
 import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
@@ -6,24 +6,20 @@ import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
  * report schema versions it reads, the languages it claims, and its recorded result over
- * the conformance corpus, absent where it records none.
+ * the conformance corpus.
  */
-export function describeDocument(version: string, recorded: Conformance | undefined): string {
+export function describeDocument(version: string, recorded: Conformance): string {
   const document = {
     name: ANALYZER_NAME,
     version,
     contract_version: CONTRACT_VERSION,
     schema_versions_accepted: [SCHEMA_VERSION],
     languages: [LANGUAGE],
-    ...(recorded === undefined
-      ? {}
-      : {
-          conformance: {
-            corpus_version: recorded.corpusVersion,
-            result: recorded.result,
-            digest: recorded.digest,
-          },
-        }),
+    conformance: {
+      corpus_version: recorded.corpusVersion,
+      result: recorded.result,
+      digest: recorded.digest,
+    },
   };
   return `${JSON.stringify(document, null, 2)}\n`;
 }
@@ -41,6 +37,6 @@ export const describeVerb: Verb = ({ out, err, host, args }) => {
     err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
     return EXIT_FAILURE;
   }
-  out.write(describeDocument(version, RECORDED_CONFORMANCE));
+  out.write(describeDocument(version, CONFORMANCE));
   return EXIT_CLEAN;
 };

package/src/verbs/explain.ts

@@ -0,0 +1,363 @@
+import { runAnalysis, type RunAnalysis } from "../analysis.ts";
+import { listing } from "../components.ts";
+import type { Cascade } from "../config.ts";
+import { ConfigError } from "../config.ts";
+import type { CompletedFinding } from "../finding.ts";
+import { OUTSIDE, swept as judged } from "../graph.ts";
+import type { InventorySymbol } from "../inventory.ts";
+import type { Configured } from "../matrix.ts";
+import { positionKey } from "../position.ts";
+import type { Reference } from "../references.ts";
+import { resolve } from "../resolve.ts";
+import type { Root } from "../roots.ts";
+import { EXIT_CLEAN, EXIT_USAGE, type Verb, type VerbOptions } from "./verb.ts";
+
+/**
+ * The three spellings of an explanation request, each naming the symbol to explain. They are
+ * one request, because exactly one state holds for a symbol and the answer is that state.
+ */
+const WHY_OPTIONS = ["why", "why-live", "why-not"] as const;
+
+/** The options `explain` takes beside the ones every verb takes. */
+export const EXPLAIN_OPTIONS: VerbOptions = { plain: [...WHY_OPTIONS], repeatable: [] };
+
+/** The most partial matches a refused request prints. */
+const MAX_PARTIAL_MATCHES = 20;
+
+/** A count with its noun, so a line reads for one as well as for several. */
+function counted(n: number, noun: string): string {
+  return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
+}
+
+/** A list for a line a maintainer reads, which says none rather than leaving the field blank. */
+function listed(items: readonly string[]): string {
+  return items.length === 0 ? "none" : items.join(" ");
+}
+
+/** The one symbol a request names, from whichever of the three options names it. */
+function namedSymbol(option: (name: string) => string | undefined): string {
+  const named = WHY_OPTIONS.flatMap((name) => {
+    const value = option(name);
+    return value === undefined || value === "" ? [] : [{ name, value }];
+  });
+  const [only, ...more] = named;
+  if (only === undefined) {
+    throw new ConfigError(
+      "malformed",
+      "",
+      "explain explains the symbol --why, --why-live or --why-not names, and none was named",
+    );
+  }
+  if (more.length > 0) {
+    throw new ConfigError(
+      "malformed",
+      "",
+      `explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`,
+    );
+  }
+  return only.value;
+}
+
+/** The part of a reference after its separator: the `Type.member` or bare name a maintainer types. */
+function fragmentOf(symbol: InventorySymbol): string {
+  const at = symbol.ref.indexOf("#");
+  return at < 0 ? "" : symbol.ref.slice(at + 1);
+}
+
+function described(symbol: InventorySymbol): string {
+  return `${symbol.ref}\t${positionKey(symbol.position)}`;
+}
+
+/**
+ * The one declaration a request names, or the candidates where it names none or several.
+ * The reference, the fragment of it a maintainer types and the display name are tried in
+ * order, each an exact match; a key several declarations answer is no answer.
+ */
+function subjectOf(
+  symbols: readonly InventorySymbol[],
+  named: string,
+): { readonly subject?: InventorySymbol; readonly candidates: readonly string[] } {
+  const keys: ((symbol: InventorySymbol) => string)[] = [
+    (symbol) => symbol.ref,
+    fragmentOf,
+    (symbol) => symbol.name,
+  ];
+  for (const key of keys) {
+    const matched = symbols.filter((symbol) => key(symbol) === named);
+    const [only] = matched;
+    if (only !== undefined && matched.length === 1) {
+      return { subject: only, candidates: [] };
+    }
+    if (matched.length > 1) {
+      return { candidates: matched.map(described) };
+    }
+  }
+  const folded = named.toLowerCase();
+  const partial = symbols
+    .filter(
+      (symbol) =>
+        symbol.ref.toLowerCase().includes(folded) || symbol.name.toLowerCase().includes(folded),
+    )
+    .map(described)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return { candidates: partial.slice(0, MAX_PARTIAL_MATCHES) };
+}
+
+/** Every reference of the run once, a reference several configurations make counted once. */
+function referencesOf(configured: readonly Configured[]): readonly Reference[] {
+  const seen = new Set<string>();
+  const held: Reference[] = [];
+  for (const reference of configured.flatMap((one) => one.references)) {
+    const key = [reference.from, reference.to, positionKey(reference.position), reference.use].join(
+      "\u0000",
+    );
+    if (!seen.has(key)) {
+      seen.add(key);
+      held.push(reference);
+    }
+  }
+  return held;
+}
+
+/** Every root of the run once per reason, in the order the projects name them. */
+function rootsOf(configured: readonly Configured[]): readonly Root[] {
+  const seen = new Set<string>();
+  return configured
+    .flatMap((one) => one.roots)
+    .filter((root) => {
+      const key = [root.id, root.kind, root.source].join("\u0000");
+      if (seen.has(key)) {
+        return false;
+      }
+      seen.add(key);
+      return true;
+    });
+}
+
+/**
+ * One step of a path: a reference, or a reference that reads a module and so reaches a
+ * declaration the module exports.
+ */
+type Hop =
+  | { readonly k: "reference"; readonly reference: Reference }
+  | { readonly k: "export"; readonly reference: Reference; readonly to: string };
+
+/**
+ * The shortest path from a root to one declaration, walked breadth first from every root at
+ * once in the order the run names them, following the references the sweep follows: a
+ * reference that reads a module reaches what the module exports, and an evaluation or a root
+ * reaches the module alone. Under `production` no reference a test file made is followed,
+ * which is the set the report's sweep counts.
+ */
+function shortestPath(
+  analysis: RunAnalysis,
+  to: string,
+  production: boolean,
+): { readonly root: Root; readonly path: readonly Hop[] } | undefined {
+  const graph = analysis.swept.matrix.union;
+  const out = new Map<string, Reference[]>();
+  for (const reference of referencesOf(analysis.configured)) {
+    if (production && reference.test) {
+      continue;
+    }
+    const held = out.get(reference.from);
+    if (held === undefined) {
+      out.set(reference.from, [reference]);
+    } else {
+      held.push(reference);
+    }
+  }
+  interface Step {
+    readonly at: string;
+    readonly hop: Hop | undefined;
+    readonly previous: number;
+    readonly root: Root;
+  }
+  const steps: Step[] = [];
+  const seen = new Set<string>();
+  const expanded = new Set<string>();
+  const enter = (step: Step): void => {
+    if (!seen.has(step.at)) {
+      seen.add(step.at);
+      steps.push(step);
+    }
+  };
+  for (const root of rootsOf(analysis.configured)) {
+    enter({ at: root.id, hop: undefined, previous: -1, root });
+  }
+  for (let head = 0; head < steps.length; head += 1) {
+    const step = steps[head];
+    if (step === undefined) {
+      break;
+    }
+    if (step.at === to) {
+      const path: Hop[] = [];
+      for (let at: Step | undefined = step; at?.hop !== undefined; at = steps[at.previous]) {
+        path.unshift(at.hop);
+      }
+      return { root: step.root, path };
+    }
+    for (const reference of out.get(step.at) ?? []) {
+      enter({
+        at: reference.to,
+        hop: { k: "reference", reference },
+        previous: head,
+        root: step.root,
+      });
+      const target = graph.at(reference.to);
+      if (reference.use === "evaluation" || target === OUTSIDE || expanded.has(reference.to)) {
+        continue;
+      }
+      expanded.add(reference.to);
+      for (const exported of graph.exportsOf[target] ?? []) {
+        const id = graph.symbols[exported]?.id;
+        if (id !== undefined) {
+          enter({
+            at: id,
+            hop: { k: "export", reference, to: id },
+            previous: head,
+            root: step.root,
+          });
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+function referenceLine(reference: Reference, tail: string): string {
+  return `  reference: ${positionKey(reference.position)}\t${reference.use}\t${tail}${reference.test ? "\tfrom a test file" : ""}\n`;
+}
+
+/** Why a declaration no finding names and no exemption held back is live, or how it fell. */
+function liveness(analysis: RunAnalysis, subject: InventorySymbol, cascade: Cascade): string {
+  const { sweep } = analysis.swept;
+  const candidate = sweep.candidates.find((one) => one.id === subject.id);
+  if (candidate === undefined && !judged(subject.kind)) {
+    return `answer: unjudged\n  unjudged: neither liveness relation judges a ${subject.kind}\n`;
+  }
+  let text = `answer: ${candidate === undefined ? "live" : "dead"}\n`;
+  text += `  live under: ${listed(sweep.liveUnder.get(subject.id) ?? [])}\n`;
+  for (const root of rootsOf(analysis.configured).filter((one) => one.id === subject.id)) {
+    text += `  root: ${root.kind}${root.source === "" ? "" : `\tnamed by ${root.source}`}\n`;
+  }
+  const found =
+    shortestPath(analysis, subject.id, true) ?? shortestPath(analysis, subject.id, false);
+  if (found !== undefined && found.path.length > 0) {
+    text += `  reached from: root ${found.root.kind} ${found.root.id}\n`;
+    for (const hop of found.path) {
+      text += referenceLine(hop.reference, `${hop.reference.from} -> ${hop.reference.to}`);
+      if (hop.k === "export") {
+        text += `  export: ${hop.reference.to} -> ${hop.to}\n`;
+      }
+    }
+  } else if (found === undefined) {
+    const references = referencesOf(analysis.configured).filter((one) => one.to === subject.id);
+    text += "  unreachable: no path of references reaches it from a root\n";
+    text += `  references: ${String(references.length)}\n`;
+    for (const reference of references) {
+      text += referenceLine(reference, `from ${reference.from}`);
+    }
+  }
+  if (candidate !== undefined) {
+    const component = sweep.components.find((one) => one.members.includes(subject.id));
+    if (component !== undefined) {
+      const listed = listing(component, cascade);
+      text += `  component: ${component.id}, ${counted(listed.symbolCount, "symbol")} and ${counted(listed.deletableLines, "deletable line")} fall with it, listed at cascade ${cascade}\n`;
+      for (const root of listed.roots) {
+        text += `  component root: ${root}\n`;
+      }
+      for (const member of listed.members) {
+        text += `  component member: ${member}\n`;
+      }
+    }
+    text += `  candidate: dead under ${candidate.relation}, with ${String(candidate.productionRefs)} production and ${String(candidate.testRefs)} test references\n`;
+  }
+  return text;
+}
+
+function reported(found: CompletedFinding): string {
+  return [
+    `answer: reported`,
+    `  code: ${found.code} ${found.kind}`,
+    `  message: ${found.message}`,
+    `  class: ${found.reachabilityClass}`,
+    `  confidence: ${found.confidence}`,
+    ...(found.livenessRelation === undefined
+      ? []
+      : [`  liveness relation: ${found.livenessRelation}`]),
+    `  configurations: ${listed(found.configurations)}`,
+    `  loaded consumers: ${listed(found.consumersLoaded)}`,
+    ...found.retainedBy.map((one) => `  retained by: ${one}`),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Every finding of the run that names the declaration by its reference and reports at
+ * another position: a part of it, or a suppression record naming it. Each is published under
+ * the reference asked about, so an explanation leaving it out would disagree with the report.
+ */
+function namedElsewhere(findings: readonly CompletedFinding[], subject: InventorySymbol): string {
+  return findings
+    .filter(
+      (found) => found.symbol.ref === subject.ref && positionKey(found.position) !== subject.id,
+    )
+    .map(
+      (found) =>
+        `also reported: ${found.code} ${found.kind}\t${positionKey(found.position)}\t${found.symbol.kind} ${found.symbol.name}\n`,
+    )
+    .join("");
+}
+
+/** The one explanation that applies to a declaration, built whole before it is written. */
+function explanation(analysis: RunAnalysis, subject: InventorySymbol, cascade: Cascade): string {
+  const graph = analysis.swept.matrix.union;
+  const at = graph.at(subject.id);
+  let text = `symbol: ${subject.ref}\n`;
+  text += `declaration: ${subject.kind} ${subject.name}\n`;
+  text += `position: ${subject.id}\n`;
+  text += `configurations: ${listed(analysis.swept.matrix.heldIn[at] ?? [])}\n`;
+  const found = analysis.result.findings.find((one) => positionKey(one.position) === subject.id);
+  const retained = analysis.swept.retained.filter((one) => one.id === subject.id);
+  if (found !== undefined) {
+    text += reported(found);
+  } else if (retained.length > 0) {
+    text += `answer: retained\n  held back by: ${counted(retained.length, "exemption class")}\n`;
+    for (const one of retained) {
+      text += `  class: ${one.class}\t${positionKey(one.site)}\t${one.detail}\n`;
+    }
+  } else {
+    text += liveness(analysis, subject, cascade);
+  }
+  return text + namedElsewhere(analysis.result.findings, subject);
+}
+
+/**
+ * Explains one symbol from the analysis the report is built from, so an explanation cannot
+ * disagree with a finding: why a reported symbol is reported, which exemption classes held a
+ * retained one back, and for any other declaration the relations that hold it live and the
+ * shortest path of references from a root, or the references it has where no path reaches it.
+ * A request naming no one declaration exits with the usage code and names what partially
+ * matches it.
+ */
+export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, option }) => {
+  const named = namedSymbol(option);
+  const { config, provenance } = resolve(inputs());
+  const analysis = runAnalysis(openClient(false), host, scope(), config, provenance, {
+    production: true,
+  });
+  const { subject, candidates } = subjectOf(analysis.swept.matrix.union.symbols, named);
+  if (subject === undefined) {
+    err.write(`deadset-ts: ${JSON.stringify(named)} names no one symbol of the target\n`);
+    for (const candidate of candidates) {
+      err.write(`  ${candidate}\n`);
+    }
+    if (candidates.length === 0) {
+      err.write("  no symbol of the target partially matches it either\n");
+    }
+    return EXIT_USAGE;
+  }
+  out.write(explanation(analysis, subject, config.reporters.cascade));
+  return EXIT_CLEAN;
+};