@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.10

package/src/report.ts

@@ -4,7 +4,9 @@
  * renders this document, so no two renderings disagree about which findings exist.
  */
 
-import type { Severity, Sort, TargetKind } from "./config.ts";
+import { SCHEMA_VERSION, SCHEMA_VERSIONS } from "./contract/contract.generated.ts";
+import type * as wire from "./contract/report.generated.ts";
+import type { Sort, TargetKind } from "./config.ts";
 import type { Conformance, DeclaredGap } from "./conformance.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type {
@@ -17,129 +19,8 @@ import type { AppliedConvention } from "./conventions.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. */
-const SCHEMA_VERSION = "8.2.0";
-
-/** Every report schema version this analyzer reads: the one the Contract it implements admits. */
-export const SCHEMA_VERSIONS_ACCEPTED: readonly string[] = [SCHEMA_VERSION];
-
-/** 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";
-
-interface WirePosition {
-  readonly path: string;
-  readonly line: number;
-  readonly column: number;
-  readonly end_line: number;
-}
-
-interface WireDetails {
-  readonly narrower_visibility?: string;
-  readonly implementations?: readonly {
-    readonly ref: string;
-    readonly name: string;
-    readonly position: WirePosition;
-  }[];
-  readonly write_positions?: readonly WirePosition[];
-  /** Set under the name-literal rule, which no finding of this analyzer meets; SARIF still maps it. */
-  readonly name_literal?: WirePosition;
-  readonly dependency_class?: string;
-  readonly mechanism?: string;
-  readonly entry?: {
-    readonly code: string;
-    readonly symbol?: string;
-    readonly path?: string;
-    readonly reason?: string;
-  };
-  readonly overlap?: readonly string[];
-  readonly removes_last_use_of?: readonly 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 members?: readonly {
-      readonly ref: string;
-      readonly name: string;
-      readonly position: WirePosition;
-    }[];
-  };
-  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;
-}
-
-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;
-}
-
-interface WireDeclaredGap {
-  readonly fixture: string;
-  readonly symbol?: string;
-  readonly capability: string;
-  readonly reason: 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;
-  readonly withheld: {
-    readonly certain: number;
-    readonly probable: number;
-    readonly possible: number;
-  };
-}
+import { bytewise } from "./text/compare.ts";
+import { LANGUAGE, PRODUCT } from "./product.ts";
 
 /** One project configuration of the matrix a run analyzed. */
 export interface ReportConfiguration {
@@ -186,49 +67,21 @@ interface UnavailableConsumer {
   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 ReportNotBuilt[];
-  readonly consumers: {
-    readonly declared: number;
-    readonly loaded: readonly {
-      readonly id: string;
-      readonly role: "consumer";
+/** One hint about the run's setup, as the report schema's `notes` spells it. */
+export type ReportNote =
+  | {
+      readonly kind: "unmapped-entry";
+      /** The directory of the manifest the note is about, below the target root. */
       readonly path: string;
-    }[];
-    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 WireDeclaredGap[];
-  readonly excluded_by_cgo: readonly never[];
-  readonly test_file_rules: readonly TestFileRule[];
-  readonly type_error_skips: readonly TypeErrorSkip[];
-  readonly notes: readonly never[];
-  readonly unanswered_questions: readonly UnansweredCount[];
-  readonly conventions_applied: readonly AppliedConvention[];
-  readonly totals: WireTotals;
-}
+      readonly key: "ts.entry_files";
+      readonly message: string;
+    }
+  | {
+      readonly kind: "computed-load" | "unread-command" | "unresolved-specifier";
+      /** The directory of the file that writes the load or the specifier, or of the manifest, below the target root. */
+      readonly path: string;
+      readonly message: string;
+    };
 
 /** What one run answered, from which its report is built. */
 export interface ReportInput {
@@ -247,17 +100,34 @@ export interface ReportInput {
   readonly unanswered: readonly UnansweredCount[];
   /** The convention rows the run applied, in the report's order. */
   readonly conventionsApplied: readonly AppliedConvention[];
+  /** The notes the run states, in any order. */
+  readonly notes?: readonly ReportNote[];
+  /** Whether the run lists each component in full, which `reporters.cascade: full` asks for. */
+  readonly listsComponents?: boolean;
 }
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
+/**
+ * Each component the findings name, once, with the members the first finding naming it
+ * carries, in the order the findings are: `findings` paired with their wire forms and
+ * sorted, then the edge evaluations' findings.
+ */
+function componentsOf(
+  findings: readonly (readonly [wire.Finding, CompletedFinding])[],
+): readonly wire.ComponentsEntry[] {
+  const listed = new Map<string, wire.ComponentsEntry>();
+  for (const [written, finding] of findings) {
+    const { members } = finding.component;
+    if (members !== undefined && !listed.has(written.component.id)) {
+      listed.set(written.component.id, {
+        id: written.component.id,
+        members: members.map(wireSymbol),
+      });
+    }
   }
-  return a < b ? -1 : 1;
+  return [...listed.values()];
 }
 
-function wirePosition(position: FindingPosition): WirePosition {
+function wirePosition(position: FindingPosition): wire.Position {
   return {
     path: position.path,
     line: position.line,
@@ -269,13 +139,13 @@ function wirePosition(position: FindingPosition): WirePosition {
 function wireSymbol(symbol: PositionedSymbol): {
   ref: string;
   name: string;
-  position: WirePosition;
+  position: wire.Position;
 } {
   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 {
+function wireDetails(details: FindingDetails): wire.Details {
   const { entry } = details;
   return {
     ...(details.narrowerVisibility === undefined
@@ -307,7 +177,7 @@ function wireDetails(details: FindingDetails): WireDetails {
 }
 
 /** One finding as the finding schema spells it, member for member in its order. */
-export function wireFinding(finding: CompletedFinding): WireFinding {
+export function wireFinding(finding: CompletedFinding): wire.Finding {
   return {
     code: finding.code,
     kind: finding.kind,
@@ -331,9 +201,6 @@ export function wireFinding(finding: CompletedFinding): WireFinding {
       root: finding.component.root,
       symbol_count: finding.component.symbolCount,
       deletable_lines: finding.component.deletableLines,
-      ...(finding.component.members === undefined
-        ? {}
-        : { members: finding.component.members.map(wireSymbol) }),
     },
     retained_by: finding.retainedBy,
     configurations: finding.configurations,
@@ -345,7 +212,7 @@ export function wireFinding(finding: CompletedFinding): WireFinding {
   };
 }
 
-function wireEvaluation(evaluation: EdgeEvaluation<CompletedFinding>): WireEdgeEvaluation {
+function wireEvaluation(evaluation: EdgeEvaluation<CompletedFinding>): wire.EdgeEvaluationsEntry {
   return {
     edge: evaluation.edge,
     side: evaluation.side,
@@ -355,7 +222,7 @@ function wireEvaluation(evaluation: EdgeEvaluation<CompletedFinding>): WireEdgeE
   };
 }
 
-function wireStale(stale: StaleSuppression): WireStaleSuppression {
+function wireStale(stale: StaleSuppression): wire.StaleSuppressionsEntry {
   return {
     code: stale.code,
     mechanism: stale.mechanism,
@@ -376,29 +243,29 @@ function wireStale(stale: StaleSuppression): WireStaleSuppression {
 }
 
 /** The canonical key over two findings: path, line, column, code, then the symbol reference. */
-function canonical(a: WireFinding, b: WireFinding): number {
+function canonical(a: wire.Finding, b: wire.Finding): number {
   return (
-    compare(a.position.path, b.position.path) ||
+    bytewise(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)
+    bytewise(a.code, b.code) ||
+    bytewise(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 {
+function canonicalStale(a: wire.StaleSuppressionsEntry, b: wire.StaleSuppressionsEntry): number {
   return (
-    compare(a.position.path, b.position.path) ||
+    bytewise(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)
+    bytewise(a.code, b.code) ||
+    bytewise(a.symbol, b.symbol)
   );
 }
 
 /** One declared gap as a report carries it, its members in the schema's order. */
-function wireGap(gap: DeclaredGap): WireDeclaredGap {
+function wireGap(gap: DeclaredGap): wire.DeclaredGapsEntry {
   return {
     fixture: gap.fixture,
     ...(gap.symbol === undefined ? {} : { symbol: gap.symbol }),
@@ -408,11 +275,11 @@ function wireGap(gap: DeclaredGap): WireDeclaredGap {
 }
 
 /** Edge evaluations by edge, then side, then their compact encodings. */
-function byEdge(a: WireEdgeEvaluation, b: WireEdgeEvaluation): number {
+function byEdge(a: wire.EdgeEvaluationsEntry, b: wire.EdgeEvaluationsEntry): number {
   return (
-    compare(a.edge, b.edge) ||
-    compare(a.side, b.side) ||
-    compare(JSON.stringify(a), JSON.stringify(b))
+    bytewise(a.edge, b.edge) ||
+    bytewise(a.side, b.side) ||
+    bytewise(JSON.stringify(a), JSON.stringify(b))
   );
 }
 
@@ -420,7 +287,7 @@ function byEdge(a: WireEdgeEvaluation, b: WireEdgeEvaluation): number {
  * 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 {
+function deletableLines(findings: readonly wire.Finding[]): number {
   const counted = new Map<string, number>();
   for (const finding of findings) {
     if (finding.component.root) {
@@ -435,7 +302,7 @@ function deletableLines(findings: readonly WireFinding[]): number {
 }
 
 /** The totals of one finding set, counted over the whole set. */
-function totalsOf(findings: readonly WireFinding[], result: PassResult): WireTotals {
+function totalsOf(findings: readonly wire.Finding[], result: PassResult): wire.Totals {
   const bySeverity = { allow: 0, warn: 0, deny: 0 };
   for (const finding of findings) {
     bySeverity[finding.severity] += 1;
@@ -458,22 +325,28 @@ function totalsOf(findings: readonly WireFinding[], result: PassResult): WireTot
 }
 
 /** 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);
+export function buildReport(input: ReportInput): wire.Report {
+  const paired = input.result.findings
+    .map((finding) => [wireFinding(finding), finding] as const)
+    .sort(([a], [b]) => canonical(a, b));
+  const findings = paired.map(([wire]) => wire);
+  const evaluated = input.result.edgeEvaluations.flatMap((one) =>
+    one.finding === undefined ? [] : [[wireFinding(one.finding), one.finding] as const],
+  );
   const unavailable = [...new Map(input.unavailable.map((one) => [one.id, one])).values()]
-    .sort((a, b) => compare(a.id, b.id))
+    .sort((a, b) => bytewise(a.id, b.id))
     .map((one) => ({ id: one.id, role: "consumer" as const, reason: one.reason }));
   const loaded = [...input.loaded]
-    .sort((a, b) => compare(a.id, b.id) || compare(a.path, b.path))
+    .sort((a, b) => bytewise(a.id, b.id) || bytewise(a.path, b.path))
     .map((one) => ({ id: one.id, role: "consumer" as const, path: one.path }));
   return {
     schema_version: SCHEMA_VERSION,
     contract_version: input.contractVersion,
     analyzer: {
-      name: ANALYZER_NAME,
+      name: PRODUCT,
       version: input.version,
       languages: [LANGUAGE],
-      schema_versions_accepted: SCHEMA_VERSIONS_ACCEPTED,
+      schema_versions_accepted: SCHEMA_VERSIONS,
       conformance: {
         corpus_version: input.conformance.corpusVersion,
         result: input.conformance.result,
@@ -482,23 +355,26 @@ export function buildReport(input: ReportInput): Report {
     },
     target: { kind: input.target.kind, root: input.target.root, identity: input.target.identity },
     configurations: [...input.configurations]
-      .sort((a, b) => compare(a.id, b.id))
+      .sort((a, b) => bytewise(a.id, b.id))
       .map((one) => ({ id: one.id, project: one.project })),
     configurations_not_built: [...input.notBuilt]
-      .sort((a, b) => compare(a.id, b.id))
+      .sort((a, b) => bytewise(a.id, b.id))
       .map((one) => ({ id: one.id, project: one.project, error: one.error })),
     consumers: { declared: loaded.length + unavailable.length, loaded, unavailable },
     findings,
+    ...(input.listsComponents === true
+      ? { components: componentsOf([...paired, ...evaluated]) }
+      : {}),
     edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
     stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
     // Every gap shares the one component of the canonical key a gap supplies, the analyzer's
     // name, so the compact encodings alone order them.
     declared_gaps: input.declaredGaps
       .map(wireGap)
-      .sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b))),
+      .sort((a, b) => bytewise(JSON.stringify(a), JSON.stringify(b))),
     excluded_by_cgo: [],
     test_file_rules: [...input.testFileRules]
-      .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)
+      .sort((a, b) => bytewise(a.rule, b.rule) || a.matched - b.matched)
       .map((one) => ({ rule: one.rule, matched: one.matched })),
     type_error_skips: [
       ...new Map(
@@ -508,14 +384,18 @@ export function buildReport(input: ReportInput): Report {
         }),
       ),
     ]
-      .sort(([a, x], [b, y]) => compare(x.path, y.path) || x.line - y.line || compare(a, b))
+      .sort(([a, x], [b, y]) => bytewise(x.path, y.path) || x.line - y.line || bytewise(a, b))
       .map(([, skip]) => skip),
-    notes: [],
+    notes: [...new Map((input.notes ?? []).map((one) => [JSON.stringify(one), one])).entries()]
+      .sort(
+        ([a, x], [b, y]) => bytewise(x.kind, y.kind) || bytewise(x.path, y.path) || bytewise(a, b),
+      )
+      .map(([, note]) => note),
     unanswered_questions: [...input.unanswered]
       .sort(
         (a, b) =>
-          compare(a.configuration, b.configuration) ||
-          compare(JSON.stringify(a), JSON.stringify(b)),
+          bytewise(a.configuration, b.configuration) ||
+          bytewise(JSON.stringify(a), JSON.stringify(b)),
       )
       .map((one) => ({
         configuration: one.configuration,
@@ -537,8 +417,8 @@ export function buildReport(input: ReportInput): Report {
  * 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 =>
+export function sortFindings(report: wire.Report, by: Sort): wire.Report {
+  const bySize = (a: wire.Finding, b: wire.Finding): number =>
     b.component.deletable_lines - a.component.deletable_lines ||
     b.symbol.size_lines - a.symbol.size_lines ||
     canonical(a, b);
@@ -546,16 +426,26 @@ export function sortFindings(report: Report, by: Sort): Report {
 }
 
 /**
- * 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.
+ * The report holding the first `most` findings of its order, the rest counted as omitted,
+ * and listing only the components those findings name. Every other total keeps describing
+ * the whole set. Zero keeps every finding.
  */
-export function capFindings(report: Report, most: number): Report {
+export function capFindings(report: wire.Report, most: number): wire.Report {
   if (most <= 0 || report.findings.length <= most) {
     return report;
   }
+  const findings = report.findings.slice(0, most);
+  const named = new Set(
+    [...findings, ...report.edge_evaluations.flatMap((one) => one.finding ?? [])].map(
+      (finding) => finding.component.id,
+    ),
+  );
   return {
     ...report,
-    findings: report.findings.slice(0, most),
+    findings,
+    ...(report.components === undefined
+      ? {}
+      : { components: report.components.filter((listed) => named.has(listed.id)) }),
     totals: { ...report.totals, omitted: report.findings.length - most },
   };
 }

package/src/reporters/annotations.ts

@@ -1,8 +1,7 @@
-import { fails } from "../config.ts";
+import type { Severity } from "../contract/contract.generated.ts";
 import { coalesced } from "../json-chunks.ts";
 import { KINDS } from "../kinds.ts";
-import type { Report } from "../report.ts";
-import type { RenderOptions } from "./reporter.ts";
+import type { Report } from "../contract/report.generated.ts";
 
 /** The escapes a workflow command's message needs, so a line break does not end the command. */
 const DATA_ESCAPES: Readonly<Record<string, string>> = { "%": "%25", "\r": "%0D", "\n": "%0A" };
@@ -27,8 +26,18 @@ function kindName(code: string): string {
   return KINDS.get(code)?.name ?? code;
 }
 
+/** The workflow command a record is written as. */
+type Level = "error" | "warning" | "notice";
+
+/** The command each finding severity is annotated with, whatever the failing severity. */
+const LEVELS: Readonly<Record<Severity, Level>> = {
+  deny: "error",
+  warn: "warning",
+  allow: "notice",
+};
+
 function command(
-  level: "error" | "warning",
+  level: Level,
   at: { readonly path: string; readonly line: number; readonly column: number },
   endLine: number,
   title: string,
@@ -43,18 +52,17 @@ const SKIP_MESSAGE =
   "the analysis did not evaluate the function or statement holding this type error: ";
 
 /**
- * One workflow annotation per finding, then one per stale suppression, each naming its
- * file, line, column and last line, titled by its code and kind, then one warning per
- * type-error skip naming its file and line. A finding at or above the failing severity is
- * an error and one below it a warning; a stale suppression is an error, because its kind
- * is fixed on at the failing severity.
+ * The annotations `contract/grammar/annotations.md` states: one per finding, at the
+ * command its severity names, and one error per stale suppression, each naming its file,
+ * line, column and last line and titled by its code and kind; then one warning per
+ * type-error skip naming its file and line, and one per note naming its directory.
  */
-export function annotations(report: Report, options: RenderOptions): Iterable<string> {
+export function annotations(report: Report): Iterable<string> {
   return coalesced(
     (function* lines(): Generator<string, void, undefined> {
       for (const found of report.findings) {
         yield `${command(
-          fails(found.severity, options.failOn) ? "error" : "warning",
+          LEVELS[found.severity],
           found.position,
           found.position.end_line,
           `${found.code} ${found.kind}`,
@@ -73,6 +81,9 @@ export function annotations(report: Report, options: RenderOptions): Iterable<st
       for (const skip of report.type_error_skips) {
         yield `::warning file=${escapeProperty(skip.path)},line=${String(skip.line)},title=${escapeProperty(SKIP_TITLE)}::${escapeData(SKIP_MESSAGE + skip.message)}\n`;
       }
+      for (const note of report.notes) {
+        yield `::warning file=${escapeProperty(note.path)},title=${escapeProperty(note.kind)}::${escapeData(note.message)}\n`;
+      }
     })(),
   );
 }

package/src/reporters/json.ts

@@ -1,5 +1,5 @@
 import { jsonChunks } from "../json-chunks.ts";
-import type { Report } from "../report.ts";
+import type { Report } from "../contract/report.generated.ts";
 
 /** The indentation of the report document, which with the schema's member order fixes its bytes. */
 const INDENT = 2;

package/src/reporters/reporter.ts

@@ -1,11 +1,9 @@
-import type { Format, Severity } from "../config.ts";
-import type { Report } from "../report.ts";
+import type { Format } from "../contract/contract.generated.ts";
+import type { Report } from "../contract/report.generated.ts";
 import type { Template } from "./template.ts";
 
 /** What a rendering reads beside the report. */
 export interface RenderOptions {
-  /** The lowest severity at which a finding fails the run. */
-  readonly failOn: Severity;
   /** The text of the file at one path below the target root, or a throw naming why not. */
   readonly readSource: (path: string) => string;
   /** The template the template rendering renders, where one was named. */

package/src/reporters/reporters.ts

@@ -1,4 +1,4 @@
-import type { Format } from "../config.ts";
+import type { Format } from "../contract/contract.generated.ts";
 import { annotations } from "./annotations.ts";
 import { json } from "./json.ts";
 import { RenderError, type Rendering, type Renderings } from "./reporter.ts";