@cplieger/deadset-ts 3.7.0 → 3.9.0

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/roots.ts

@@ -11,9 +11,7 @@
 
 import type { SourceFile } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.ts";
-import { REPOSITORY_DOCUMENT } from "./config.ts";
 import { entryPoints, type EntryRule } from "./entry-points.ts";
-import type { Finding } from "./finding.ts";
 import { globExpression } from "./glob.ts";
 import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
 import type { Manifest, ManifestEntry } from "./manifest.ts";
@@ -89,15 +87,6 @@ export interface RootOptions {
   readonly publishedAPI: boolean;
 }
 
-/** The code the Contract gives a configured root that matches nothing. */
-const UNMATCHED_ROOT_CODE = "DS1704";
-
-/** The subject kind a finding under that code carries, from the Contract's vocabulary. */
-const UNMATCHED_ROOT_SUBJECT = "root";
-
-/** The fixed position of a finding about a document rather than about a line of one. */
-const DOCUMENT_POSITION = 1;
-
 /** Whether a configured string carries either special character. */
 function isPattern(text: string): boolean {
   return text.includes("*") || text.includes("?");
@@ -406,31 +395,3 @@ export function unmatchedEverywhere(
     perProject.every((project) => project.unmatched.includes(pattern)),
   );
 }
-
-/**
- * The findings a run reports for the configured strings that named nothing.
- *
- * `document` is the path of the document that declared the roots, below the target
- * root; where the run read them from no document of the target it is empty and the
- * finding names the conventional repository configuration, which is the document a
- * maintainer writes a configured root in. Every finding of one run sits at that
- * document's first position: the roots are written as an array whose members carry
- * no line of their own, so the string each finding names is what tells one from
- * another.
- */
-export function unmatchedRoots(sources: readonly string[], document: string): readonly Finding[] {
-  const position = {
-    path: document === "" ? REPOSITORY_DOCUMENT : document,
-    line: DOCUMENT_POSITION,
-    column: DOCUMENT_POSITION,
-    endLine: DOCUMENT_POSITION,
-  };
-  return sources.map((source) => ({
-    code: UNMATCHED_ROOT_CODE,
-    position,
-    symbol: { ref: source, kind: UNMATCHED_ROOT_SUBJECT, name: source, sizeLines: 1 },
-    message: isPattern(source)
-      ? "configured root pattern matches no symbol of the inventory"
-      : "configured root matches no symbol of the inventory",
-  }));
-}