@cplieger/deadset-ts 3.8.0 → 3.9.0

package/src/references.ts

@@ -126,8 +126,6 @@ export interface References {
   /** The compiler configuration the project was opened from. */
   readonly configFile: string;
   readonly references: readonly Reference[];
-  /** The rules that classified files as test files, ordered by rule. */
-  readonly testFileRules: readonly TestFileRule[];
   /**
    * Every file the rules classified as a test file, by its path below the target root,
    * ascending. A declaration such a file holds is a test declaration, by the same
@@ -147,7 +145,7 @@ export interface ReferenceOptions {
   readonly batchCap?: number;
   /**
    * Glob patterns, relative to the target root, naming the files that are test files.
-   * Each pattern is a rule of its own and reports the files it matched.
+   * Each pattern is a rule of its own, which {@link testFileRulesOf} counts.
    */
   readonly testFiles: readonly string[];
 }
@@ -499,6 +497,26 @@ function patternRule(index: number): string {
   return `test-file-pattern-${String(index + 1)}`;
 }
 
+/**
+ * The rules over the test files of several projects at once, ordered by rule: a file two
+ * projects hold is one file, so each rule counts the distinct paths it matches.
+ */
+export function testFileRulesOf(
+  testFiles: readonly string[],
+  paths: readonly string[],
+): readonly TestFileRule[] {
+  const distinct = [...new Set(paths)];
+  return testFiles
+    .map((pattern, index) => {
+      const expression = globExpression(pattern);
+      return {
+        rule: patternRule(index),
+        matched: distinct.filter((path) => expression.test(path)).length,
+      };
+    })
+    .sort((a, b) => compare(a.rule, b.rule));
+}
+
 /** Two strings ordered bytewise, which is the order every set of a run is read in. */
 function compare(a: string, b: string): number {
   if (a === b) {
@@ -509,7 +527,7 @@ function compare(a: string, b: string): number {
 
 /**
  * Every reference one project's own files make to the project's own declarations, in
- * position order, and the test-file rules that classified those files.
+ * position order, and the files the test-file rules classified.
  *
  * `held` is the inventory of the same project, whose declaration map is what a resolved
  * symbol is looked up in; `targetRoot` is the absolute path every position is rendered
@@ -530,7 +548,6 @@ export function references<Brand>(
   const cap = options.batchCap ?? DEFAULT_BATCH_CAP;
   const declarations = held.declarations;
   const patterns = options.testFiles.map(globExpression);
-  const matched = options.testFiles.map(() => 0);
   const found: Reference[] = [];
   const tests: string[] = [];
   const chains = aliasChains(project, held);
@@ -574,13 +591,7 @@ export function references<Brand>(
 
   for (const file of files) {
     const path = renderPosition(file, targetRoot, 0).path;
-    const hits = patterns.map((pattern) => pattern.test(path));
-    hits.forEach((hit, index) => {
-      if (hit) {
-        matched[index] = (matched[index] ?? 0) + 1;
-      }
-    });
-    const test = hits.includes(true);
+    const test = patterns.some((pattern) => pattern.test(path));
     if (test) {
       tests.push(path);
     }
@@ -706,9 +717,6 @@ export function references<Brand>(
   return {
     configFile: project.configFile,
     references: found,
-    testFileRules: options.testFiles
-      .map((_pattern, index) => ({ rule: patternRule(index), matched: matched[index] ?? 0 }))
-      .sort((a, b) => compare(a.rule, b.rule)),
     testFilePaths: tests.sort(compare),
     cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps: chains.steps },
   };

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`;
+};