@cplieger/deadset-ts 3.9.1 → 3.11.0

package/src/findings-pass.ts

@@ -5,7 +5,7 @@
  */
 
 import type { AnalysisInputs } from "./analysis.ts";
-import type { Config, Severity } from "./config.ts";
+import { fails, type Config } from "./config.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type { CompletedFinding, Finding } from "./finding.ts";
 import { decidedFindings } from "./findings/emitters.ts";
@@ -44,9 +44,6 @@ export interface PassResult {
 /** The exit code of a report holding at least one pending finding. */
 export const EXIT_PENDING = 4;
 
-/** The severities ranked, the strongest highest. */
-const SEVERITY_RANK: Readonly<Record<Severity, number>> = { allow: 0, warn: 1, deny: 2 };
-
 /** Two strings ordered bytewise. */
 function compare(a: string, b: string): number {
   if (a === b) {
@@ -119,9 +116,10 @@ export function verdictOf(result: PassResult, config: Config): number {
   if (result.totals.staleSuppressions > 0) {
     return EXIT_FINDINGS;
   }
-  const failing = SEVERITY_RANK[config.reporters.failOn];
-  const fails = result.findings.some((finding) => SEVERITY_RANK[finding.severity] >= failing);
-  return fails ? EXIT_FINDINGS : EXIT_CLEAN;
+  const failing = result.findings.some((finding) =>
+    fails(finding.severity, config.reporters.failOn),
+  );
+  return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
 
 /**

package/src/report.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Severity, Sort, TargetKind } from "./config.ts";
-import type { Conformance } from "./conformance.ts";
+import type { Conformance, DeclaredGap } from "./conformance.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type {
   CompletedFinding,
@@ -105,6 +105,13 @@ export interface WireStaleSuppression {
   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 };
@@ -159,7 +166,7 @@ export interface Report {
   readonly findings: readonly WireFinding[];
   readonly edge_evaluations: readonly WireEdgeEvaluation[];
   readonly stale_suppressions: readonly WireStaleSuppression[];
-  readonly declared_gaps: readonly never[];
+  readonly declared_gaps: readonly WireDeclaredGap[];
   readonly excluded_by_cgo: readonly never[];
   readonly test_file_rules: readonly TestFileRule[];
   readonly totals: WireTotals;
@@ -170,6 +177,7 @@ export interface ReportInput {
   readonly contractVersion: string;
   readonly version: string;
   readonly conformance: Conformance;
+  readonly declaredGaps: readonly DeclaredGap[];
   readonly target: { readonly kind: TargetKind; readonly root: string; readonly identity: string };
   readonly configurations: readonly ReportConfiguration[];
   readonly unavailable: readonly UnavailableConsumer[];
@@ -318,6 +326,16 @@ function canonicalStale(a: WireStaleSuppression, b: WireStaleSuppression): numbe
   );
 }
 
+/** One declared gap as a report carries it, its members in the schema's order. */
+function wireGap(gap: DeclaredGap): WireDeclaredGap {
+  return {
+    fixture: gap.fixture,
+    ...(gap.symbol === undefined ? {} : { symbol: gap.symbol }),
+    capability: gap.capability,
+    reason: gap.reason,
+  };
+}
+
 /** Edge evaluations by edge, then side, then their compact encodings. */
 function byEdge(a: WireEdgeEvaluation, b: WireEdgeEvaluation): number {
   return (
@@ -392,7 +410,11 @@ export function buildReport(input: ReportInput): Report {
     findings,
     edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
     stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
-    declared_gaps: [],
+    // 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))),
     excluded_by_cgo: [],
     test_file_rules: [...input.testFileRules]
       .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)

package/src/reporters/annotations.ts

@@ -0,0 +1,67 @@
+import { fails } from "../config.ts";
+import { KINDS } from "../kinds.ts";
+import type { Report } from "../report.ts";
+import type { RenderOptions } from "./reporter.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" };
+
+/** The escapes a property value needs: a message's, and the property list's two separators. */
+const PROPERTY_ESCAPES: Readonly<Record<string, string>> = {
+  ...DATA_ESCAPES,
+  ":": "%3A",
+  ",": "%2C",
+};
+
+function escapeData(value: string): string {
+  return value.replace(/[%\r\n]/gu, (char) => DATA_ESCAPES[char] ?? char);
+}
+
+function escapeProperty(value: string): string {
+  return value.replace(/[%\r\n:,]/gu, (char) => PROPERTY_ESCAPES[char] ?? char);
+}
+
+/** The name of the kind a code names, and the code itself where no live kind carries it. */
+function kindName(code: string): string {
+  return KINDS.get(code)?.name ?? code;
+}
+
+function command(
+  level: "error" | "warning",
+  at: { readonly path: string; readonly line: number; readonly column: number },
+  endLine: number,
+  title: string,
+  message: string,
+): string {
+  return `::${level} file=${escapeProperty(at.path)},line=${String(at.line)},col=${String(at.column)},endLine=${String(endLine)},title=${escapeProperty(title)}::${escapeData(message)}`;
+}
+
+/**
+ * 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. 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.
+ */
+export function annotations(report: Report, options: RenderOptions): string {
+  const lines = report.findings.map((found) =>
+    command(
+      fails(found.severity, options.failOn) ? "error" : "warning",
+      found.position,
+      found.position.end_line,
+      `${found.code} ${found.kind}`,
+      found.message,
+    ),
+  );
+  for (const stale of report.stale_suppressions) {
+    lines.push(
+      command(
+        "error",
+        stale.position,
+        stale.position.line,
+        `${stale.code} ${kindName(stale.code)}`,
+        stale.message,
+      ),
+    );
+  }
+  return lines.map((line) => `${line}\n`).join("");
+}

package/src/reporters/fingerprint.ts

@@ -0,0 +1,69 @@
+import { sha256Hex } from "./sha256.ts";
+
+/** The unit appended after the last unit of a file. */
+const SENTINEL = 0xffffn;
+
+/** The number of significant units one line's hash covers. */
+const WINDOW = 100;
+
+const FACTOR = 37n;
+
+/** Arithmetic is unsigned 64-bit with wraparound. */
+const MASK = (1n << 64n) - 1n;
+
+const SPACE = 0x20;
+const TAB = 0x09;
+const CR = 0x0d;
+const LF = 0x0a;
+
+/**
+ * The units of one file the line fingerprint counts: every UTF-16 code unit but a space or
+ * a tab, a carriage return read as a line feed and the line feed following it dropped, then
+ * the sentinel.
+ */
+function significantUnits(text: string): bigint[] {
+  const kept: bigint[] = [];
+  let afterCR = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const unit = text.charCodeAt(i);
+    if (unit === SPACE || unit === TAB || (afterCR && unit === LF)) {
+      afterCR = false;
+      continue;
+    }
+    afterCR = unit === CR;
+    kept.push(BigInt(afterCR ? LF : unit));
+  }
+  kept.push(SENTINEL);
+  return kept;
+}
+
+/**
+ * The line fingerprint of every line of one file, indexed from zero. The procedure is the one
+ * a code-scanning service computes for a result that carries none, followed exactly, because
+ * a value that differs from the service's opens a second alert for one finding.
+ */
+export function lineHashes(text: string): readonly string[] {
+  const units = significantUnits(text);
+  const starts = [0];
+  for (let i = 0; i < units.length - 1; i += 1) {
+    if (units[i] === BigInt(LF)) {
+      starts.push(i + 1);
+    }
+  }
+  const seen = new Map<string, number>();
+  return starts.map((start) => {
+    let hash = 0n;
+    for (let i = start; i < start + WINDOW; i += 1) {
+      hash = (hash * FACTOR + (units[i] ?? 0n)) & MASK;
+    }
+    const rendered = hash.toString(16);
+    const count = (seen.get(rendered) ?? 0) + 1;
+    seen.set(rendered, count);
+    return `${rendered}:${String(count)}`;
+  });
+}
+
+/** The key a baseline joins on, which a line move leaves unchanged. */
+export function symbolFingerprint(code: string, ref: string): string {
+  return sha256Hex(`${code}\n${ref}`);
+}

package/src/reporters/json.ts

@@ -1,7 +1,7 @@
-import type { Reporter } from "./reporter.ts";
+import type { Report } from "../report.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`;
+export const json = (report: Report): string => `${JSON.stringify(report, null, INDENT)}\n`;

package/src/reporters/reporter.ts

@@ -1,8 +1,19 @@
-import type { Format } from "../config.ts";
+import type { Format, Severity } from "../config.ts";
 import type { Report } from "../report.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. */
+  readonly template: Template | undefined;
+}
 
 /** One rendering of a report, as the text of the file it is written to. */
-export type Reporter = (report: Report) => string;
+type Reporter = (report: Report, options: RenderOptions) => string;
 
 /**
  * One format this analyzer renders: its reporter, and the suffix appended to the report's
@@ -16,3 +27,11 @@ export interface Rendering {
 
 /** Every format this analyzer renders, each by its rendering. */
 export type Renderings = ReadonlyMap<Format, Rendering>;
+
+/** A rendering that cannot be written, which ends the run with the failure code. */
+export class RenderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RenderError";
+  }
+}

package/src/reporters/reporters.ts

@@ -1,6 +1,9 @@
 import type { Format } from "../config.ts";
+import { annotations } from "./annotations.ts";
 import { json } from "./json.ts";
-import type { Rendering, Renderings } from "./reporter.ts";
+import { RenderError, type Rendering, type Renderings } from "./reporter.ts";
+import { sarif } from "./sarif.ts";
+import { renderTemplate } from "./template.ts";
 import { text } from "./text.ts";
 
 /**
@@ -10,4 +13,18 @@ import { text } from "./text.ts";
 export const RENDERINGS: Renderings = new Map<Format, Rendering>([
   ["text", { render: text, suffix: ".txt" }],
   ["json", { render: json, suffix: ".json" }],
+  ["github", { render: annotations, suffix: ".annotations" }],
+  ["sarif", { render: sarif, suffix: ".sarif" }],
+  [
+    "template",
+    {
+      render: (report, options) => {
+        if (options.template === undefined) {
+          throw new RenderError("the template rendering renders a template, and none was named");
+        }
+        return renderTemplate(options.template, report);
+      },
+      suffix: ".tmpl",
+    },
+  ],
 ]);

package/src/reporters/rules.ts

@@ -0,0 +1,195 @@
+/**
+ * The text of every live issue kind this analyzer's language carries, which a SARIF rule
+ * describes the kind with, written out rather than read at run time. A test compares this
+ * table against the Contract release the analyzer is written against.
+ */
+
+/** The text one rule is described with. */
+interface RuleText {
+  /** The kind's rule, whole. */
+  readonly rule: string;
+  /** The condition the kind reports under, where it declares one. */
+  readonly precondition?: string;
+}
+
+/** Every live issue kind whose languages include this analyzer's, by code, in ascending order. */
+export const RULE_TEXTS: ReadonlyMap<string, RuleText> = new Map<string, RuleText>([
+  [
+    "DS1001",
+    {
+      rule: "An exported symbol with no reference in the target and no reference from any loaded consumer. A symbol referenced only from its own declaration site counts as unreferenced.",
+    },
+  ],
+  [
+    "DS1002",
+    {
+      rule: "An unexported symbol with no reference in the target. A symbol referenced only from its own declaration site counts as unreferenced.",
+    },
+  ],
+  [
+    "DS1003",
+    {
+      rule: "A struct field, class member or type member with no reference, a private member included. A member referenced only from its own declaration site counts as unreferenced.",
+    },
+  ],
+  [
+    "DS1004",
+    {
+      rule: "A symbol with zero production references and at least one test reference: an unused-exported or unused-unexported candidate whose test reference count is not zero, reported once under this code. A reference from a consumer's test files is a test reference unless the configuration counts consumer tests as production.",
+    },
+  ],
+  [
+    "DS1005",
+    {
+      rule: "A test symbol whose set of referenced target symbols is non-empty and every member of that set is reported dead. A test that references at least one live target symbol is never reported, no notion of a test's subject and no name matching enters the rule, and the message states the rule. The test joins the dead component of the symbols it references.",
+    },
+  ],
+  [
+    "DS1006",
+    {
+      rule: "A symbol carrying a deprecation marker and no production reference: an unused-exported, unused-unexported or unused-member candidate whose symbol is deprecated, reported once under this code. Go identifies the marker by the convention the standard tools recognize, TypeScript by the documentation tag its tools recognize.",
+    },
+  ],
+  [
+    "DS1101",
+    {
+      rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
+      precondition:
+        "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API.",
+    },
+  ],
+  [
+    "DS1103",
+    {
+      rule: "An unused exported symbol in a package or file no external code can import: an unused-exported candidate whose enclosing package or file is unimportable from outside, reported once under this code at the certain class, because unimportability is a property of the package graph rather than of the consumer set.",
+    },
+  ],
+  [
+    "DS1104",
+    {
+      rule: "An exported declaration used only inside its own file, reported as a candidate for removing the export keyword. The finding names the narrower visibility the references support.",
+      precondition:
+        "Closed world only. Reported in a file that is not an entry file and that either belongs to a project whose consumer set the configuration declares complete or is reached by no manifest export. A declared cross-language edge counts as a reference from outside the file; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
+    },
+  ],
+  [
+    "DS1201",
+    {
+      rule: "An interface no symbol uses as a type, counting uses from every loaded module. The finding names the concrete implementations and their positions, and the interface's members join its dead component rather than being reported as independent unused declarations.",
+    },
+  ],
+  [
+    "DS1203",
+    {
+      rule: "An interface method that no call site invokes or selects through the interface, whatever the number of implementations. The finding names the concrete implementations and their positions.",
+      precondition:
+        "Exempt: every method of an interface that declares an unexported method, the sum-type shape whose method set exists to restrict the implementors; and every marker method, an interface method whose every implementation carries an empty body.",
+    },
+  ],
+  [
+    "DS1301",
+    {
+      rule: "A package-level or module-level variable, struct field, class member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. The finding names each write position, so the deletion set is visible.",
+    },
+  ],
+  [
+    "DS1302",
+    {
+      rule: "An enumerated member that no symbol names, at the reachability class derived for the member and with no confidence ceiling below it. Every member of a type that carries a string, text or binary conversion method, or that a conversion from an integer or a wire value produces, is retained by the enum-group exemption first, so a member reached only by value is never a candidate.",
+    },
+  ],
+  [
+    "DS1303",
+    {
+      rule: "A type parameter of a function or method that no part of the declaration's signature and no part of the declaration's body names, at the certain class. The deletion is local to the declaration and the explicit instantiations the reference set already lists.",
+      precondition:
+        "Function and method type parameters only. A type parameter of a type declaration is never reported, because a phantom type parameter such as `type ID[T any] int` makes two instantiations distinct types while naming the parameter nowhere, so deleting it changes the program.",
+    },
+  ],
+  [
+    "DS1501",
+    {
+      rule: "A source file no configuration in the build matrix builds. On the Go side the finding names the build constraint that excluded the file. A file whose build constraint is the ignore tag is never reported: the toolchain applies no build constraint to a file named on its own command line, so that tag is the toolchain's convention for a file built by hand. A file any other custom tag excludes is reported under a matrix the configuration declares complete, because completeness is the maintainer's assertion that the listed configurations are every one the target builds, and a configuration the maintainer builds by hand belongs in that list.",
+      precondition:
+        'Reported only when the configuration declares the build matrix complete, and never for a file the toolchain ignored solely because it imports "C" under a build with cgo disabled; such a file is recorded as excluded by cgo rather than as never built.',
+    },
+  ],
+  [
+    "DS1502",
+    {
+      rule: "A source file that no import reaches, that no root names, and in which no declared cross-language edge names a declaration. An edge's side names a declaration as a root names one, so a file holding a declaration an edge names is evaluated with the edge rather than reported: whether that declaration is dead is the edge evaluation's to say, and the merge resolves it against the paired side.",
+    },
+  ],
+  [
+    "DS1601",
+    {
+      rule: "A directly declared dependency that no import in the target needs. On the Go side, a direct require whose module provides no package any target package or test variant imports. On the TypeScript side, a manifest dependency, development dependency or peer dependency the project's import closure does not need. A deletion finding whose fix would remove the last use of a dependency names that dependency.",
+      precondition:
+        "On the Go side the rule is the semantics of `go mod tidy -diff` exactly: a requirement marked indirect is never reported, because it exists to pin a transitive version and removing it changes the build list.",
+    },
+  ],
+  [
+    "DS1701",
+    {
+      rule: "A suppression that carries no reason, in any of the three documents: an inline directive, an ignore-file entry or a baseline row. For the ignore file and the baseline, an entry or a row whose reason field is absent, empty or whitespace only is refused and reported rather than matched.",
+    },
+  ],
+  [
+    "DS1702",
+    {
+      rule: "An ignore-file entry or a baseline row that names a symbol and no file path. The entry is reported rather than matched, so a bare name cannot mask a match anywhere else in the project; the inline directive is scoped by its position and cannot be unscoped.",
+    },
+  ],
+  [
+    "DS1703",
+    {
+      rule: "A suppression that matches no current finding, at either mechanism and in the baseline alike. The run exits with the findings code when at least one is reported. The kind is fixed on at deny: no flag, no severity setting and no per-mechanism exception reduces it below a finding, and a configuration naming this code under a severity key is an unimplemented key.",
+    },
+  ],
+  [
+    "DS1704",
+    {
+      rule: "A configured root that matches no symbol, or a configured root pattern that matches no symbol. A root set nobody checks silently changes every result, so a stale one is a finding. The kind is fixed on at deny: no flag, no severity setting and no exception reduces it below a finding, and a configuration naming this code under a severity key is an unimplemented key.",
+    },
+  ],
+  [
+    "DS1705",
+    {
+      rule: "A declared cross-language edge with a side that at least one analyzer evaluated and every evaluation of that side reports absent, so no analyzer that ran enumerates that side's symbol. Emitted by the merge, once per edge, never by an analyzer, so a stale edge is visible rather than silently inert. A dead side paired with an absent side drops its pending finding, and the edge is the reported defect: a misspelled reference must not turn a live pairing into a deletion.",
+    },
+  ],
+  [
+    "DS1801",
+    {
+      rule: "A parameter with no reference inside its function body, on a function whose signature is free to change.",
+      precondition:
+        "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change.",
+    },
+  ],
+  [
+    "DS1803",
+    {
+      rule: "A result value that no call site of the function uses, on a function whose signature is free to change.",
+      precondition:
+        "The same free-signature rule as unused-parameter, plus a closed-world condition: every call site of the function must be in the loaded graph, because an unknown caller may consume the result, so the kind reports only for a function whose callers are all visible.",
+    },
+  ],
+  [
+    "DS1805",
+    {
+      rule: "A statement that control flow cannot reach, at the precision the language's compiler applies to the same construct.",
+    },
+  ],
+  [
+    "DS1807",
+    {
+      rule: "A write to a local variable with no read before the next write to it or the end of its scope, computed on the same read-and-write classification the write-only-symbol kind uses. The finding names the write position.",
+    },
+  ],
+  [
+    "DS1809",
+    {
+      rule: "A switch case whose type or value an earlier case in the same switch already covers.",
+    },
+  ],
+]);