@cplieger/deadset-ts 3.8.0 → 3.9.1

package/src/report.ts

@@ -0,0 +1,430 @@
+/**
+ * The report one analysis writes: the Contract's report document, member for member and
+ * in the order its schema lists them, built from what one run answered. Every reporter
+ * renders this document, so no two renderings disagree about which findings exist.
+ */
+
+import type { Severity, Sort, TargetKind } from "./config.ts";
+import type { Conformance } from "./conformance.ts";
+import type { EdgeEvaluation } from "./edges.ts";
+import type {
+  CompletedFinding,
+  FindingDetails,
+  FindingPosition,
+  PositionedSymbol,
+} from "./finding.ts";
+import type { PassResult } from "./findings-pass.ts";
+import type { StaleSuppression } from "./findings/self-check.ts";
+import type { TestFileRule } from "./references.ts";
+
+/** The version of the report schema this analyzer writes a report to. */
+export const SCHEMA_VERSION = "6.0.0";
+
+/** The name this analyzer writes every document under and mints every identifier with. */
+export const ANALYZER_NAME = "deadset-ts";
+
+/** The language this analyzer claims. */
+export const LANGUAGE = "ts";
+
+export interface WirePosition {
+  readonly path: string;
+  readonly line: number;
+  readonly column: number;
+  readonly end_line: number;
+}
+
+export interface WireDetails {
+  readonly narrower_visibility?: string;
+  readonly implementations?: readonly {
+    readonly ref: string;
+    readonly name: string;
+    readonly position: WirePosition;
+  }[];
+  readonly write_positions?: readonly WirePosition[];
+  readonly dependency_class?: string;
+  readonly mechanism?: string;
+  readonly entry?: {
+    readonly code: string;
+    readonly symbol?: string;
+    readonly path?: string;
+    readonly reason?: string;
+  };
+}
+
+/** One finding as the finding schema spells it. */
+export interface WireFinding {
+  readonly code: string;
+  readonly kind: string;
+  readonly language: string;
+  readonly position: WirePosition;
+  readonly symbol: {
+    readonly ref: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly size_lines: number;
+  };
+  readonly reachability_class: string;
+  readonly confidence: string;
+  readonly liveness_relation?: string;
+  readonly test_only: boolean;
+  readonly generated: boolean;
+  readonly component: {
+    readonly id: string;
+    readonly root: boolean;
+    readonly symbol_count: number;
+    readonly deletable_lines: number;
+  };
+  readonly retained_by: readonly string[];
+  readonly configurations: readonly string[];
+  readonly consumers_loaded: readonly string[];
+  readonly fixability: string;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly details: WireDetails;
+}
+
+export interface WireEdgeEvaluation {
+  readonly edge: string;
+  readonly side: string;
+  readonly symbol: string;
+  readonly state: string;
+  readonly finding?: WireFinding;
+}
+
+export interface WireStaleSuppression {
+  readonly code: string;
+  readonly mechanism: string;
+  readonly entry: {
+    readonly code: string;
+    readonly symbol?: string;
+    readonly path: string;
+    readonly reason: string;
+  };
+  readonly position: { readonly path: string; readonly line: number; readonly column: number };
+  readonly symbol: string;
+  readonly message: string;
+}
+
+export interface WireTotals {
+  readonly findings: number;
+  readonly by_severity: { readonly allow: number; readonly warn: number; readonly deny: number };
+  readonly deletable_lines: number;
+  readonly suppressions_in_effect: number;
+  readonly reasons_recorded: number;
+  readonly stale_suppressions: number;
+  readonly pending: number;
+  readonly omitted: number;
+}
+
+/** One project configuration of the matrix a run analyzed. */
+export interface ReportConfiguration {
+  readonly id: string;
+  /** The compiler configuration file below the target root. */
+  readonly project: string;
+}
+
+/** One consumer the scope declared and the run did not load, with why. */
+export interface UnavailableConsumer {
+  readonly id: string;
+  readonly reason: string;
+}
+
+/** The report document. */
+export interface Report {
+  readonly schema_version: string;
+  readonly contract_version: string;
+  readonly analyzer: {
+    readonly name: string;
+    readonly version: string;
+    readonly languages: readonly string[];
+    readonly schema_versions_accepted: readonly string[];
+    readonly conformance: {
+      readonly corpus_version: string;
+      readonly result: string;
+      readonly digest: string;
+    };
+  };
+  readonly target: { readonly kind: TargetKind; readonly root: string; readonly identity: string };
+  readonly configurations: readonly ReportConfiguration[];
+  readonly configurations_not_built: readonly never[];
+  readonly consumers: {
+    readonly declared: number;
+    readonly loaded: readonly never[];
+    readonly unavailable: readonly {
+      readonly id: string;
+      readonly role: "consumer";
+      readonly reason: string;
+    }[];
+  };
+  readonly findings: readonly WireFinding[];
+  readonly edge_evaluations: readonly WireEdgeEvaluation[];
+  readonly stale_suppressions: readonly WireStaleSuppression[];
+  readonly declared_gaps: readonly never[];
+  readonly excluded_by_cgo: readonly never[];
+  readonly test_file_rules: readonly TestFileRule[];
+  readonly totals: WireTotals;
+}
+
+/** What one run answered, from which its report is built. */
+export interface ReportInput {
+  readonly contractVersion: string;
+  readonly version: string;
+  readonly conformance: Conformance;
+  readonly target: { readonly kind: TargetKind; readonly root: string; readonly identity: string };
+  readonly configurations: readonly ReportConfiguration[];
+  readonly unavailable: readonly UnavailableConsumer[];
+  readonly result: PassResult;
+  readonly testFileRules: readonly TestFileRule[];
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+function wirePosition(position: FindingPosition): WirePosition {
+  return {
+    path: position.path,
+    line: position.line,
+    column: position.column,
+    end_line: position.endLine,
+  };
+}
+
+function wireSymbol(symbol: PositionedSymbol): {
+  ref: string;
+  name: string;
+  position: WirePosition;
+} {
+  return { ref: symbol.ref, name: symbol.name, position: wirePosition(symbol.position) };
+}
+
+/** The details one code carries, in the order the finding schema lists them. */
+function wireDetails(details: FindingDetails): WireDetails {
+  const { entry } = details;
+  return {
+    ...(details.narrowerVisibility === undefined
+      ? {}
+      : { narrower_visibility: details.narrowerVisibility }),
+    ...(details.implementations === undefined
+      ? {}
+      : { implementations: details.implementations.map(wireSymbol) }),
+    ...(details.writePositions === undefined
+      ? {}
+      : { write_positions: details.writePositions.map(wirePosition) }),
+    ...(details.dependencyClass === undefined ? {} : { dependency_class: details.dependencyClass }),
+    ...(details.mechanism === undefined ? {} : { mechanism: details.mechanism }),
+    ...(entry === undefined
+      ? {}
+      : {
+          entry: {
+            code: entry.code,
+            ...(entry.symbol === undefined ? {} : { symbol: entry.symbol }),
+            ...(entry.path === undefined ? {} : { path: entry.path }),
+            ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+          },
+        }),
+  };
+}
+
+/** One finding as the finding schema spells it, member for member in its order. */
+export function wireFinding(finding: CompletedFinding): WireFinding {
+  return {
+    code: finding.code,
+    kind: finding.kind,
+    language: finding.language,
+    position: wirePosition(finding.position),
+    symbol: {
+      ref: finding.symbol.ref,
+      kind: finding.symbol.kind,
+      name: finding.symbol.name,
+      size_lines: finding.symbol.sizeLines,
+    },
+    reachability_class: finding.reachabilityClass,
+    confidence: finding.confidence,
+    ...(finding.livenessRelation === undefined
+      ? {}
+      : { liveness_relation: finding.livenessRelation }),
+    test_only: finding.testOnly,
+    generated: finding.generated,
+    component: {
+      id: finding.component.id,
+      root: finding.component.root,
+      symbol_count: finding.component.symbolCount,
+      deletable_lines: finding.component.deletableLines,
+    },
+    retained_by: finding.retainedBy,
+    configurations: finding.configurations,
+    consumers_loaded: finding.consumersLoaded,
+    fixability: finding.fixability,
+    severity: finding.severity,
+    message: finding.message,
+    details: wireDetails(finding.details),
+  };
+}
+
+function wireEvaluation(evaluation: EdgeEvaluation<CompletedFinding>): WireEdgeEvaluation {
+  return {
+    edge: evaluation.edge,
+    side: evaluation.side,
+    symbol: evaluation.symbol,
+    state: evaluation.state,
+    ...(evaluation.finding === undefined ? {} : { finding: wireFinding(evaluation.finding) }),
+  };
+}
+
+function wireStale(stale: StaleSuppression): WireStaleSuppression {
+  return {
+    code: stale.code,
+    mechanism: stale.mechanism,
+    entry: {
+      code: stale.entry.code,
+      ...(stale.entry.symbol === undefined ? {} : { symbol: stale.entry.symbol }),
+      path: stale.entry.path,
+      reason: stale.entry.reason,
+    },
+    position: {
+      path: stale.position.path,
+      line: stale.position.line,
+      column: stale.position.column,
+    },
+    symbol: stale.symbol,
+    message: stale.message,
+  };
+}
+
+/** The canonical key over two findings: path, line, column, code, then the symbol reference. */
+function canonical(a: WireFinding, b: WireFinding): number {
+  return (
+    compare(a.position.path, b.position.path) ||
+    a.position.line - b.position.line ||
+    a.position.column - b.position.column ||
+    compare(a.code, b.code) ||
+    compare(a.symbol.ref, b.symbol.ref)
+  );
+}
+
+/** The canonical key over two stale suppressions, each component from the record's own member. */
+function canonicalStale(a: WireStaleSuppression, b: WireStaleSuppression): number {
+  return (
+    compare(a.position.path, b.position.path) ||
+    a.position.line - b.position.line ||
+    a.position.column - b.position.column ||
+    compare(a.code, b.code) ||
+    compare(a.symbol, b.symbol)
+  );
+}
+
+/** Edge evaluations by edge, then side, then their compact encodings. */
+function byEdge(a: WireEdgeEvaluation, b: WireEdgeEvaluation): number {
+  return (
+    compare(a.edge, b.edge) ||
+    compare(a.side, b.side) ||
+    compare(JSON.stringify(a), JSON.stringify(b))
+  );
+}
+
+/**
+ * The lines a reader deletes by acting on every finding: each distinct component a root
+ * finding names, counted once however many of its roots the findings hold.
+ */
+function deletableLines(findings: readonly WireFinding[]): number {
+  const counted = new Map<string, number>();
+  for (const finding of findings) {
+    if (finding.component.root) {
+      counted.set(finding.component.id, finding.component.deletable_lines);
+    }
+  }
+  let total = 0;
+  for (const lines of counted.values()) {
+    total += lines;
+  }
+  return total;
+}
+
+/** The totals of one finding set, counted over the whole set. */
+function totalsOf(findings: readonly WireFinding[], result: PassResult): WireTotals {
+  const bySeverity = { allow: 0, warn: 0, deny: 0 };
+  for (const finding of findings) {
+    bySeverity[finding.severity] += 1;
+  }
+  return {
+    findings: findings.length,
+    by_severity: bySeverity,
+    deletable_lines: deletableLines(findings),
+    suppressions_in_effect: result.totals.suppressionsInEffect,
+    reasons_recorded: result.totals.reasonsRecorded,
+    stale_suppressions: result.staleSuppressions.length,
+    pending: result.totals.pending,
+    omitted: 0,
+  };
+}
+
+/** Builds the report of one run, every array in the order the Contract fixes for it. */
+export function buildReport(input: ReportInput): Report {
+  const findings = input.result.findings.map(wireFinding).sort(canonical);
+  const unavailable = [...new Map(input.unavailable.map((one) => [one.id, one])).values()]
+    .sort((a, b) => compare(a.id, b.id))
+    .map((one) => ({ id: one.id, role: "consumer" as const, reason: one.reason }));
+  return {
+    schema_version: SCHEMA_VERSION,
+    contract_version: input.contractVersion,
+    analyzer: {
+      name: ANALYZER_NAME,
+      version: input.version,
+      languages: [LANGUAGE],
+      schema_versions_accepted: [SCHEMA_VERSION],
+      conformance: {
+        corpus_version: input.conformance.corpusVersion,
+        result: input.conformance.result,
+        digest: input.conformance.digest,
+      },
+    },
+    target: { kind: input.target.kind, root: input.target.root, identity: input.target.identity },
+    configurations: [...input.configurations]
+      .sort((a, b) => compare(a.id, b.id))
+      .map((one) => ({ id: one.id, project: one.project })),
+    configurations_not_built: [],
+    consumers: { declared: unavailable.length, loaded: [], unavailable },
+    findings,
+    edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
+    stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
+    declared_gaps: [],
+    excluded_by_cgo: [],
+    test_file_rules: [...input.testFileRules]
+      .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)
+      .map((one) => ({ rule: one.rule, matched: one.matched })),
+    totals: totalsOf(findings, input.result),
+  };
+}
+
+/**
+ * The report with its findings in the order a configuration asks for. By size, a finding
+ * whose component a deletion shrinks more comes first, then one whose subject is larger,
+ * then the canonical key, so the order stays total; by position it is the canonical key.
+ */
+export function sortFindings(report: Report, by: Sort): Report {
+  const bySize = (a: WireFinding, b: WireFinding): number =>
+    b.component.deletable_lines - a.component.deletable_lines ||
+    b.symbol.size_lines - a.symbol.size_lines ||
+    canonical(a, b);
+  return { ...report, findings: [...report.findings].sort(by === "size" ? bySize : canonical) };
+}
+
+/**
+ * The report holding the first `most` findings of its order, the rest counted as omitted.
+ * Every other total keeps describing the whole set. Zero keeps every finding.
+ */
+export function capFindings(report: Report, most: number): Report {
+  if (most <= 0 || report.findings.length <= most) {
+    return report;
+  }
+  return {
+    ...report,
+    findings: report.findings.slice(0, most),
+    totals: { ...report.totals, omitted: report.findings.length - most },
+  };
+}

package/src/reporters/json.ts

@@ -0,0 +1,7 @@
+import type { Reporter } from "./reporter.ts";
+
+/** The indentation of the report document, which with the schema's member order fixes its bytes. */
+const INDENT = 2;
+
+/** The report document itself: the report, indented, with a closing newline. */
+export const json: Reporter = (report) => `${JSON.stringify(report, null, INDENT)}\n`;

package/src/reporters/reporter.ts

@@ -0,0 +1,18 @@
+import type { Format } from "../config.ts";
+import type { Report } from "../report.ts";
+
+/** One rendering of a report, as the text of the file it is written to. */
+export type Reporter = (report: Report) => string;
+
+/**
+ * One format this analyzer renders: its reporter, and the suffix appended to the report's
+ * path to name the file the rendering is written to, so no rendering lands on the report or
+ * on another rendering whatever extension the report's path carries.
+ */
+export interface Rendering {
+  readonly render: Reporter;
+  readonly suffix: string;
+}
+
+/** Every format this analyzer renders, each by its rendering. */
+export type Renderings = ReadonlyMap<Format, Rendering>;

package/src/reporters/reporters.ts

@@ -0,0 +1,13 @@
+import type { Format } from "../config.ts";
+import { json } from "./json.ts";
+import type { Rendering, Renderings } from "./reporter.ts";
+import { text } from "./text.ts";
+
+/**
+ * Every format this analyzer renders, each by its reporter and its file suffix. A format
+ * absent from the table is refused rather than silently not written.
+ */
+export const RENDERINGS: Renderings = new Map<Format, Rendering>([
+  ["text", { render: text, suffix: ".txt" }],
+  ["json", { render: json, suffix: ".json" }],
+]);

package/src/reporters/text.ts

@@ -0,0 +1,45 @@
+import type { WireTotals } from "../report.ts";
+import type { Reporter } from "./reporter.ts";
+
+/** The kind token and the confidence a stale suppression is rendered with, both fixed. */
+const STALE_KIND = "suppression";
+const STALE_CONFIDENCE = "certain";
+
+/** A count with the word for it, so the summary reads as a sentence. */
+function counted(n: number, one: string, many: string): string {
+  return `${String(n)} ${n === 1 ? one : many}`;
+}
+
+/** The report's totals in one line, in the order the report declares them. */
+function summary(totals: WireTotals): string {
+  const { allow, warn, deny } = totals.by_severity;
+  return [
+    `summary: ${counted(totals.findings, "finding", "findings")} (${String(allow)} allow, ${String(warn)} warn, ${String(deny)} deny)`,
+    counted(totals.deletable_lines, "deletable line", "deletable lines"),
+    counted(totals.suppressions_in_effect, "suppression in effect", "suppressions in effect"),
+    counted(totals.reasons_recorded, "reason recorded", "reasons recorded"),
+    counted(totals.stale_suppressions, "stale suppression", "stale suppressions"),
+    `${String(totals.pending)} pending`,
+    `${String(totals.omitted)} omitted`,
+  ].join(", ");
+}
+
+/**
+ * One line per finding in the report's order, then one per stale suppression, then the
+ * summary. A finding line is `path:line:col: kind name: message [confidence] (CODE)`; the
+ * 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) => {
+  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})`,
+  );
+  for (const stale of report.stale_suppressions) {
+    lines.push(
+      `${stale.position.path}:${String(stale.position.line)}:${String(stale.position.column)}: ${STALE_KIND} ${stale.symbol}: ${stale.message} [${STALE_CONFIDENCE}] (${stale.code})`,
+    );
+  }
+  lines.push(summary(report.totals));
+  return `${lines.join("\n")}\n`;
+};

package/src/run.ts

@@ -9,7 +9,9 @@ import { printConfigVerb } from "./verbs/print-config.ts";
 import { printProjectsVerb } from "./verbs/print-projects.ts";
 import { printRetainedVerb } from "./verbs/print-retained.ts";
 import { printRootsVerb } from "./verbs/print-roots.ts";
-import { EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verbs/verb.ts";
+import { ANALYZE_OPTIONS, analyzeVerb } from "./verbs/analyze.ts";
+import { describeVerb } from "./verbs/describe.ts";
+import { EXIT_FAILURE, EXIT_USAGE, type Verb, type VerbOptions } from "./verbs/verb.ts";
 import { versionVerb } from "./verbs/version.ts";
 
 /** One output stream of the command line. `process.stdout` and `process.stderr` satisfy it. */
@@ -21,14 +23,18 @@ export interface Writer {
  * 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.
  */
-const VERBS: readonly { readonly name: string; readonly run?: Verb }[] = [
-  { name: "analyze" },
+const VERBS: readonly {
+  readonly name: string;
+  readonly run?: Verb;
+  readonly options?: VerbOptions;
+}[] = [
+  { name: "analyze", run: analyzeVerb, options: ANALYZE_OPTIONS },
   { name: "explain" },
   { name: "print-config", run: printConfigVerb },
   { name: "print-projects", run: printProjectsVerb },
   { name: "print-roots", run: printRootsVerb },
   { name: "print-retained", run: printRetainedVerb },
-  { name: "describe" },
+  { name: "describe", run: describeVerb },
   { name: "version", run: versionVerb },
 ];
 
@@ -69,11 +75,15 @@ const INTEGER_OPTIONS: ReadonlySet<string> = new Set(["max-findings"]);
 /** An integer as an option writes it: an optional minus sign and digits alone. */
 const INTEGER_TEXT = /^-?[0-9]+$/u;
 
-/** One invocation's options, by name, with the verb's remaining arguments. */
+/** One invocation's options, by name: the last value of each, and every value of a repeatable one. */
 interface Options {
   readonly named: ReadonlyMap<string, string>;
+  readonly repeated: ReadonlyMap<string, readonly string[]>;
 }
 
+/** No option beyond the ones every verb takes. */
+const NO_OPTIONS: VerbOptions = { plain: [], repeatable: [] };
+
 /**
  * The first option whose name carries a source-edit token, because every verb
  * reports and never edits. The match is on the name alone, so an option whose
@@ -93,16 +103,22 @@ function sourceEditOption(args: readonly string[]): string | undefined {
   return undefined;
 }
 
-/** Reads one verb's options, refusing a name this command does not offer. */
-function readOptions(args: readonly string[]): Options {
+/** Reads one verb's options, refusing a name neither this command nor the verb offers. */
+function readOptions(args: readonly string[], own: VerbOptions): Options {
   const named = new Map<string, string>();
+  const repeated = new Map<string, string[]>();
   for (const arg of args) {
     if (!arg.startsWith("-")) {
       throw new ConfigError("malformed", "", `unexpected argument ${JSON.stringify(arg)}`);
     }
     const [spelled, ...rest] = arg.split("=");
     const name = (spelled ?? "").replace(/^-+/u, "");
-    if (!PLAIN_OPTIONS.has(name) && !SETTING_OPTIONS.has(name)) {
+    if (
+      !PLAIN_OPTIONS.has(name) &&
+      !SETTING_OPTIONS.has(name) &&
+      !own.plain.includes(name) &&
+      !own.repeatable.includes(name)
+    ) {
       throw new ConfigError("malformed", "", `unknown option ${JSON.stringify(spelled ?? arg)}`);
     }
     if (rest.length === 0) {
@@ -112,9 +128,11 @@ function readOptions(args: readonly string[]): Options {
         `option ${JSON.stringify(spelled ?? arg)} takes a value`,
       );
     }
-    named.set(name, rest.join("="));
+    const value = rest.join("=");
+    named.set(name, value);
+    repeated.set(name, [...(repeated.get(name) ?? []), value]);
   }
-  return { named };
+  return { named, repeated };
 }
 
 function readFileOr(host: Host, path: string, orUndefined: boolean): string | undefined {
@@ -202,7 +220,13 @@ export function run(
   const name = args[0];
   const verb = VERBS.find((listed) => listed.name === name);
   if (verb?.run !== undefined) {
-    return invoke(verb.run, args.slice(1), { out, err, host }, openClient);
+    return invoke(
+      verb.run,
+      verb.options ?? NO_OPTIONS,
+      args.slice(1),
+      { out, err, host },
+      openClient,
+    );
   }
   if (verb !== undefined) {
     err.write(`deadset-ts: ${verb.name} is not implemented\n`);
@@ -222,18 +246,22 @@ export function run(
  */
 function invoke(
   verb: Verb,
+  own: VerbOptions,
   args: readonly string[],
   streams: { readonly out: Writer; readonly err: Writer; readonly host: Host },
   openClient: (collectTiming: boolean) => Engine,
 ): number {
   let options: Options | undefined;
-  const read = (): Options => (options ??= readOptions(args));
+  const read = (): Options => (options ??= readOptions(args, own));
   let opened: Engine | undefined;
   try {
     return verb({
       ...streams,
+      args,
       inputs: () => inputsOf(streams.host, read()),
       scope: () => scopeOf(streams.host, read()),
+      option: (name) => read().named.get(name),
+      repeated: (name) => read().repeated.get(name) ?? [],
       openClient: (collectTiming) => {
         opened = openClient(collectTiming);
         return opened;