@cplieger/deadset-ts 3.7.0 → 3.9.0

package/src/analysis.ts

@@ -14,6 +14,7 @@ import { decorator } from "./decorator.ts";
 import { dependenciesOf, projectNeeds } from "./dependencies.ts";
 import { deprecatedDeclarations } from "./deprecation.ts";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
+import { readEdgeSides } from "./edges.ts";
 import { enumGroup } from "./enum-group.ts";
 import {
   computeExemptions,
@@ -26,7 +27,13 @@ import {
 import type { TSExemptionClass } from "./exempt-classes.ts";
 import { heldByInclusion, sourceTree } from "./file-facts.ts";
 import type { Finding } from "./finding.ts";
+import { findingsPass, type PassResult } from "./findings-pass.ts";
 import type { EmitterInput } from "./findings/emitter.ts";
+import {
+  NO_SELF_CHECK,
+  unmatchedRootFindings,
+  type SelfCheckFacts,
+} from "./findings/self-check.ts";
 import { frameworkLifecycle } from "./framework-lifecycle.ts";
 import type { Host } from "./host.ts";
 import { implementations, mergeImplementations } from "./implementations.ts";
@@ -38,13 +45,16 @@ import { matrixOf, sweepMatrix, type Configured, type Matrix, type SweepResult }
 import { relativePath, resolvePath } from "./paths.ts";
 import { byPosition, type Position } from "./position.ts";
 import { reflectiveLookup } from "./reflective-lookup.ts";
-import { references } from "./references.ts";
-import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind, type Roots } from "./roots.ts";
+import { references, testFileRulesOf, type TestFileRule } from "./references.ts";
+import { roots, unmatchedEverywhere, type RootKind, type Roots } from "./roots.ts";
 import type { Scope } from "./scope.ts";
 import { serializationContract } from "./serialization-contract.ts";
 import { diagnosticsOf, runSession, type Engine, type ProjectView } from "./session.ts";
 import { accessorsOf, storesOf } from "./stores.ts";
-import type { Exemption, SweepInput } from "./sweep.ts";
+import type { Suppressions } from "./suppress.ts";
+import { readBaseline, readIgnoreFile } from "./suppress-file.ts";
+import { inlineDirectives, inlineSuppressions, type InlineDirective } from "./suppress-inline.ts";
+import type { Exemption, Mode, SweepInput } from "./sweep.ts";
 import { readTemplates, templateField } from "./template-field.ts";
 
 /** The setting whose source decides where a finding about a configured root sits. */
@@ -109,6 +119,8 @@ function compare(a: string, b: string): number {
 /** What every stage after the root set reads of one project. */
 interface ProjectRead {
   readonly configuration: string;
+  /** The compiler configuration file the project was opened from, absolute. */
+  readonly configFile: string;
   readonly held: Inventory;
   readonly rooted: Roots;
 }
@@ -146,7 +158,7 @@ function readProjects<Answer>(
     const held = inventory(project, host, targetRoot);
     const rooted = roots(project, held, targetRoot, options);
     const configuration = ids.get(project.configFile) ?? project.configFile;
-    return stage(project, { configuration, held, rooted });
+    return stage(project, { configuration, configFile: project.configFile, held, rooted });
   });
   if (failures.length > 0) {
     throw new DiscoveryError(
@@ -211,7 +223,10 @@ export function runRoots(
   return {
     configurations,
     roots: ordered,
-    findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
+    findings: unmatchedRootFindings(
+      unmatched,
+      documentOf(host, provenance, ROOTS_SETTING, targetRoot),
+    ),
   };
 }
 
@@ -240,31 +255,33 @@ const DETECTORS: Detectors = new Map<TSExemptionClass, Detector>([
 
 /** What the sweep of one run reads of each project, beside what a caller's stage adds. */
 interface SweptProject<Extra> {
+  readonly configFile: string;
   readonly configured: Configured;
   readonly exempt: readonly Exemption[];
   readonly extra: Extra;
 }
 
-/** The run's sweep, the exemption records it was swept with, and each project's extra answer. */
-interface SweptRun<Extra> {
-  readonly swept: RunSweep;
+/** What a run read of its projects before any sweep: the matrix, its exemptions, and each project's answers. */
+interface ReadRun<Extra> {
+  readonly matrix: Matrix;
   readonly exempt: readonly Exemption[];
   readonly projects: readonly SweptProject<Extra>[];
 }
 
 /**
- * Sweeps the run, reading each project's references and exemptions, and `extra`'s
- * answer, while the project's view is open.
+ * Reads every project of the run, its references and exemptions, and `extra`'s answer,
+ * while the project's view is open, and merges the projects into one matrix in the run's
+ * order.
  */
-function sweepRun<Extra>(
+function readRun<Extra>(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
-  input: Pick<SweepInput, "marked" | "mode">,
+  mode: Mode,
   detectors: Detectors,
   extra: <Brand>(project: ProjectView<Brand>, read: ProjectRead) => Extra,
-): SweptRun<Extra> {
+): ReadRun<Extra> {
   const targetRoot = scope.target.path;
   const disabled = disabledClasses(config);
   const templates = disabled.has("template-field")
@@ -287,22 +304,37 @@ function sweepRun<Extra>(
       detectors,
       {
         disabled,
-        mode: input.mode,
+        mode,
         testFiles: new Set(resolved.testFilePaths),
       },
     );
-    return { configured, exempt, extra: extra(project, projectRead) };
+    return {
+      configFile: projectRead.configFile,
+      configured,
+      exempt,
+      extra: extra(project, projectRead),
+    };
   });
-  const matrix = matrixOf(projects.map((one) => one.configured));
-  const exempt = exemptionsOf(projects.flatMap((one) => one.exempt));
-  const swept: SweepInput = { ...input, exempt };
   return {
-    swept: { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) },
-    exempt,
+    matrix: matrixOf(projects.map((one) => one.configured)),
+    exempt: exemptionsOf(projects.flatMap((one) => one.exempt)),
     projects,
   };
 }
 
+/** The sweep of a run read once, under one set of marks. */
+function sweptOf<Extra>(
+  read: ReadRun<Extra>,
+  input: Pick<SweepInput, "marked" | "mode">,
+): RunSweep {
+  const swept: SweepInput = { ...input, exempt: read.exempt };
+  return {
+    matrix: read.matrix,
+    sweep: sweepMatrix(read.matrix, swept),
+    retained: retainedIn(read.matrix, swept),
+  };
+}
+
 /**
  * Sweeps the run the scope and the configuration describe. Each project's references
  * and exemptions are read against its own inventory while its view is open; the
@@ -321,32 +353,59 @@ export function runSweep(
   input: Pick<SweepInput, "marked" | "mode">,
   detectors: Detectors = DETECTORS,
 ): RunSweep {
-  return sweepRun(engine, host, scope, config, input, detectors, () => undefined).swept;
+  return sweptOf(
+    readRun(engine, host, scope, config, input.mode, detectors, () => undefined),
+    input,
+  );
 }
 
-/**
- * What every emitter reads of the run the scope and the configuration describe: the
- * run's sweep, and the facts beside it each kind family reads, every per-project one
- * read in the same session as the sweep. The run loads no consumer and reads no
- * declared cross-language edge, so its boundary names neither.
- */
-export function runEmitterInput(
+/** What each project contributes to the facts every emitter reads beside the sweep. */
+interface EmitterExtra {
+  readonly deprecated: readonly string[];
+  readonly accessors: ReturnType<typeof accessorsOf>;
+  readonly needs: ReturnType<typeof projectNeeds>;
+  readonly implementations: ReturnType<typeof implementations>;
+  readonly heldByInclusion: readonly string[];
+  readonly rooted: Roots;
+  readonly directives: readonly InlineDirective[];
+}
+
+/** Reads a run's projects with every per-project fact an emitter reads. */
+function readEmitterRun(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
-  input: Pick<SweepInput, "marked" | "mode">,
-  detectors: Detectors = DETECTORS,
-): EmitterInput {
+  mode: Mode,
+  detectors: Detectors,
+): ReadRun<EmitterExtra> {
   const targetRoot = scope.target.path;
-  const run = sweepRun(engine, host, scope, config, input, detectors, (project, read) => ({
+  return readRun(engine, host, scope, config, mode, detectors, (project, read) => ({
     deprecated: deprecatedDeclarations(project, read.held),
     accessors: accessorsOf(project, read.held),
     needs: projectNeeds(project, read.held, host),
     implementations: implementations(project, read.held),
     heldByInclusion: heldByInclusion(project, targetRoot),
+    rooted: read.rooted,
+    directives: inlineDirectives(project, read.held, targetRoot),
   }));
-  const { swept, projects } = run;
+}
+
+/**
+ * The input every emitter reads over one sweep of a read run: the facts beside the sweep
+ * each kind family reads, every per-project one read in the same session as the sweep.
+ */
+function emitterInputOver(
+  host: Host,
+  scope: Scope,
+  config: Config,
+  read: ReadRun<EmitterExtra>,
+  input: Pick<SweepInput, "marked" | "mode">,
+  selfCheck: SelfCheckFacts,
+): EmitterInput {
+  const targetRoot = scope.target.path;
+  const swept = sweptOf(read, input);
+  const { projects } = read;
   return {
     config,
     swept,
@@ -356,7 +415,7 @@ export function runEmitterInput(
         references: one.configured.references,
         accessors: one.extra.accessors,
       })),
-      run.exempt,
+      read.exempt,
       input.mode,
     ),
     dependencies: dependenciesOf(
@@ -373,7 +432,143 @@ export function runEmitterInput(
     boundary: {
       consumers: { declared: scope.consumers.map((consumer) => consumer.id), loaded: [] },
       encapsulated: readManifest(host, targetRoot).declaresExports,
-      edges: [],
+      edges: readEdgeSides(host, targetRoot),
+    },
+    selfCheck,
+  };
+}
+
+/**
+ * What every emitter reads of the run the scope and the configuration describe, swept
+ * under the caller's marks: the run's sweep, the facts beside it each kind family reads,
+ * and the sides of the target's declared cross-language edges that name a symbol of this
+ * language. The run loads no consumer, and it reads no suppression document, so the
+ * self-check family has nothing to report.
+ */
+export function runEmitterInput(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  input: Pick<SweepInput, "marked" | "mode">,
+  detectors: Detectors = DETECTORS,
+): EmitterInput {
+  const read = readEmitterRun(engine, host, scope, config, input.mode, detectors);
+  return emitterInputOver(host, scope, config, read, input, NO_SELF_CHECK);
+}
+
+/** One run read for its findings: the input swept with and without its suppressions' marks. */
+export interface AnalysisInputs {
+  /** The run swept under the marks of every bound suppression record. */
+  readonly marked: EmitterInput;
+  /** The same run swept with no mark, which is what a record would have withheld. */
+  readonly unmarked: EmitterInput;
+  /** The run's suppression records and refusals, in reading order. */
+  readonly suppressions: Suppressions;
+}
+
+/**
+ * Reads the run the scope and the configuration describe for its findings. The inline
+ * directives, the ignore file's entries and the baseline's rows are read and bound before
+ * any sweep, and the run is swept once under every bound record's mark and once under
+ * none, so a record is decided against the finding its code would have produced. The
+ * self-check family reports the refused suppressions and the roots that named nothing.
+ * Beside the inputs it answers the projects and test-file rules a report names.
+ */
+function runAnalysisInputs(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  provenance: Provenance,
+  mode: Mode,
+  detectors: Detectors,
+): { readonly inputs: AnalysisInputs; readonly run: RunFacts } {
+  const targetRoot = scope.target.path;
+  const read = readEmitterRun(engine, host, scope, config, mode, detectors);
+  const symbols = read.matrix.union.symbols;
+  const documents = [
+    inlineSuppressions(read.projects.map((one) => one.extra.directives)),
+    readIgnoreFile(host, targetRoot, symbols),
+    readBaseline(host, targetRoot, symbols),
+  ];
+  const suppressions: Suppressions = {
+    records: documents.flatMap((one) => one.records),
+    refusals: documents.flatMap((one) => one.refusals),
+  };
+  const facts: SelfCheckFacts = {
+    refusals: suppressions.refusals,
+    unmatchedRoots: unmatchedEverywhere(
+      config.rootPatterns,
+      read.projects.map((one) => one.extra.rooted),
+    ),
+    rootsDocument: documentOf(host, provenance, ROOTS_SETTING, targetRoot),
+  };
+  const marked = [...new Set(suppressions.records.map((record) => record.bound))].filter(
+    (id) => id !== "",
+  );
+  return {
+    inputs: {
+      marked: emitterInputOver(host, scope, config, read, { marked, mode }, facts),
+      unmarked: emitterInputOver(host, scope, config, read, { marked: [], mode }, facts),
+      suppressions,
+    },
+    run: {
+      projects: read.projects.map((one) => ({
+        id: one.configured.configuration,
+        configFile: one.configFile,
+      })),
+      testFileRules: testFileRulesOf(
+        config.ts.testFiles,
+        read.projects.flatMap((one) => one.configured.testFiles),
+      ),
     },
   };
 }
+
+/** One project of a run: the name the run gives it and the file it was opened from. */
+export interface RunProject {
+  readonly id: string;
+  /** The compiler configuration file, absolute. */
+  readonly configFile: string;
+}
+
+/** What a report states about the run beside its findings. */
+export interface RunFacts {
+  /** The projects the run analyzed, in the run's order. */
+  readonly projects: readonly RunProject[];
+  /** The rules that classified files as test files, each counted over every project at once. */
+  readonly testFileRules: readonly TestFileRule[];
+}
+
+/** The findings of one run, beside what a report states about the run itself. */
+export interface RunAnalysis {
+  readonly result: PassResult;
+  readonly run: RunFacts;
+}
+
+/**
+ * The analysis of the run the scope and the configuration describe: the run read with its
+ * suppressions bound, every family's findings with the suppressions applied and the
+ * declared edges evaluated, and the projects and test-file rules the report names.
+ */
+export function runAnalysis(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  provenance: Provenance,
+  mode: Mode,
+  detectors: Detectors = DETECTORS,
+): RunAnalysis {
+  const { inputs, run } = runAnalysisInputs(
+    engine,
+    host,
+    scope,
+    config,
+    provenance,
+    mode,
+    detectors,
+  );
+  return { result: findingsPass(inputs), run };
+}

package/src/conformance.ts

@@ -0,0 +1,34 @@
+/**
+ * What this analyzer states about its own conformance: the corpus version it is written
+ * against and its recorded result over that corpus, which `describe` and every report name.
+ */
+
+/** The result one product reached over the conformance corpus. */
+export interface Conformance {
+  readonly corpusVersion: string;
+  readonly result: "pass" | "fail";
+  /** `sha256:` and the lowercase hexadecimal SHA-256 of the results document the runner wrote. */
+  readonly digest: string;
+}
+
+/** The version of the conformance corpus this analyzer is written against. */
+const CORPUS_VERSION = "1.9.0";
+
+/** The SHA-256 of zero bytes, which is the digest of a results document no run wrote. */
+const EMPTY_DIGEST = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+/**
+ * The conformance run this analyzer records, or undefined where it records none. A
+ * description states exactly this, so a reader that requires a pass refuses an analyzer
+ * that has not answered the corpus.
+ */
+export const RECORDED_CONFORMANCE: Conformance | undefined = undefined;
+
+/**
+ * The conformance a report states. A report requires the block, so an analyzer that
+ * records no run states a failed one over the results document no run wrote, which a merge
+ * refuses as it refuses any result other than a pass.
+ */
+export function reportedConformance(recorded: Conformance | undefined): Conformance {
+  return recorded ?? { corpusVersion: CORPUS_VERSION, result: "fail", digest: EMPTY_DIGEST };
+}

package/src/edges.ts

@@ -0,0 +1,241 @@
+/**
+ * Declared cross-language edges: the sides of the target's edges document that name a
+ * symbol of this language, and the evaluation the report publishes for each. This analyzer
+ * never resolves the paired symbol: the other language's analyzer decides whether the
+ * pairing is a use, and the merge reads the two evaluations together.
+ */
+
+import { ConfigError } from "./config.ts";
+import type { Finding } from "./finding.ts";
+import type { EdgeSide, EdgeSideName } from "./findings/boundary.ts";
+import type { Host } from "./host.ts";
+import type { InventorySymbol } from "./inventory.ts";
+import { positionAt, walkDocument } from "./json-document.ts";
+import { joinPath } from "./paths.ts";
+import { positionKey } from "./position.ts";
+
+/** The name and the location the Contract fixes for the edges document. */
+export const EDGES_FILE = "deadset-edges.json";
+
+/** The language prefix of every reference this analyzer evaluates. */
+const OWN_PREFIX = "ts://";
+
+/** The closed key list of the document and of one edge. */
+const DOCUMENT_KEYS: ReadonlySet<string> = new Set(["description", "edges"]);
+const EDGE_KEYS: ReadonlySet<string> = new Set(["id", "because", "provides", "used_by"]);
+
+/** An edge identifier: solidus-separated segments of ASCII letters, digits, `_`, `.` and `-`. */
+const ID_FORM = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/u;
+
+/** A reference naming one symbol of some language: `<language>://<scope>#<fragment>`. */
+const REFERENCE_FORM = /^[a-z][a-z0-9]*:\/\/[^ \t\r\n#]+#[^ \t\r\n]*$/u;
+
+const DOCUMENT_WANT = "an object carrying the edges array, and an optional description";
+const EDGE_WANT = "an edge naming id, provides and used_by, each a string, and an optional because";
+const ID_WANT =
+  "one or more solidus-separated segments of ASCII letters, digits, underscore, full stop and hyphen";
+const REFERENCE_WANT =
+  "a stable symbol reference naming one symbol exactly, <language>://<scope>#<fragment>";
+
+/** An edges document the Contract refuses: a malformed input, answered with the usage code. */
+export class EdgesError extends ConfigError {
+  constructor(at: string, text: string, want: string) {
+    super("malformed", EDGES_FILE, `${at}: ${text}: want ${want}`);
+    this.name = "EdgesError";
+  }
+}
+
+/**
+ * Whether a reference carries a wildcard outside a quoted or a computed component, which
+ * would name a set of symbols rather than one.
+ */
+function carriesWildcard(ref: string): boolean {
+  let quoted = false;
+  let computed = false;
+  let escaped = false;
+  for (const char of ref) {
+    if (escaped) {
+      escaped = false;
+    } else if (quoted && char === "\\") {
+      escaped = true;
+    } else if (quoted) {
+      quoted = char !== "'";
+    } else if (computed) {
+      computed = char !== "]";
+    } else if (char === "'") {
+      quoted = true;
+    } else if (char === "[") {
+      computed = true;
+    } else if (char === "*") {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** One edge, checked: the closed key list, the value types and the value forms. */
+function readEdge(value: unknown, at: string): { id: string; provides: string; usedBy: string } {
+  const refuse = (text: string, want: string): never => {
+    throw new EdgesError(at, text, want);
+  };
+  if (!isObject(value)) {
+    return refuse(JSON.stringify(value), EDGE_WANT);
+  }
+  for (const [key, held] of Object.entries(value)) {
+    if (!EDGE_KEYS.has(key) || typeof held !== "string") {
+      refuse(`the member ${JSON.stringify(key)} holding ${JSON.stringify(held)}`, EDGE_WANT);
+    }
+  }
+  const edge = value as Readonly<Record<string, string | undefined>>;
+  const id = edge["id"] ?? refuse("an edge naming no id", EDGE_WANT);
+  const provides = edge["provides"] ?? refuse("an edge naming no provides side", EDGE_WANT);
+  const usedBy = edge["used_by"] ?? refuse("an edge naming no used_by side", EDGE_WANT);
+  if (!ID_FORM.test(id)) {
+    refuse(JSON.stringify(id), ID_WANT);
+  }
+  for (const ref of [provides, usedBy]) {
+    if (!REFERENCE_FORM.test(ref) || carriesWildcard(ref)) {
+      refuse(JSON.stringify(ref), REFERENCE_WANT);
+    }
+  }
+  return { id, provides, usedBy };
+}
+
+/**
+ * Every side of a declared edge that names a symbol of this language, in document order,
+ * `provides` before `used_by` within an edge. An absent document declares no edge. The
+ * document is strict JSON with a closed key list at both levels, and a defect in it is an
+ * {@link EdgesError}.
+ */
+export function readEdgeSides(host: Host, targetRoot: string): readonly EdgeSide[] {
+  const file = joinPath(targetRoot, EDGES_FILE);
+  if (host.kindOf(file) === "absent") {
+    return [];
+  }
+  const text = host.readFile(file);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error: unknown) {
+    throw new EdgesError(
+      EDGES_FILE,
+      error instanceof Error ? error.message : String(error),
+      DOCUMENT_WANT,
+    );
+  }
+  if (!isObject(parsed)) {
+    throw new EdgesError(EDGES_FILE, JSON.stringify(parsed), DOCUMENT_WANT);
+  }
+  const walk = walkDocument(text, "edges");
+  if (walk.twice !== undefined) {
+    throw new EdgesError(
+      positionKey(positionAt(text, EDGES_FILE, walk.twice.offset)),
+      `the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`,
+      DOCUMENT_WANT,
+    );
+  }
+  const unknown = Object.keys(parsed).find((key) => !DOCUMENT_KEYS.has(key));
+  const description = parsed["description"];
+  const edges = parsed["edges"];
+  if (
+    unknown !== undefined ||
+    (description !== undefined && typeof description !== "string") ||
+    !Array.isArray(edges)
+  ) {
+    throw new EdgesError(
+      EDGES_FILE,
+      unknown === undefined ? EDGES_FILE : `the member ${JSON.stringify(unknown)}`,
+      DOCUMENT_WANT,
+    );
+  }
+
+  const sides: EdgeSide[] = [];
+  (edges as readonly unknown[]).forEach((value, index) => {
+    const offset = walk.opened[index];
+    const at =
+      offset === undefined ? EDGES_FILE : positionKey(positionAt(text, EDGES_FILE, offset));
+    const edge = readEdge(value, at);
+    const named: readonly [EdgeSideName, string][] = [
+      ["provides", edge.provides],
+      ["used_by", edge.usedBy],
+    ];
+    for (const [side, symbol] of named) {
+      if (symbol.startsWith(OWN_PREFIX)) {
+        sides.push({ edge: edge.id, side, symbol });
+      }
+    }
+  });
+  return sides;
+}
+
+/** One side's verdict, as an evaluation names it. */
+export type EdgeState = "live" | "dead" | "absent";
+
+/** One edge evaluation: one side of this language, its state, and the finding it holds. */
+export interface EdgeEvaluation<F extends Finding = Finding> extends EdgeSide {
+  readonly state: EdgeState;
+  /** Present exactly when the state is `dead`: the finding a live paired symbol cancels. */
+  readonly finding?: F;
+}
+
+/** The findings a report publishes, and one evaluation per declared side of this language. */
+export interface Evaluated<F extends Finding> {
+  readonly findings: readonly F[];
+  /** Ordered by edge, then by side, each compared bytewise. */
+  readonly evaluations: readonly EdgeEvaluation<F>[];
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/**
+ * Evaluates every declared side of this language over the run's findings. A side naming a
+ * symbol the run enumerates nothing under is `absent`; one naming a symbol the run holds a
+ * finding about is `dead` and carries that finding, pending until a merge reads the other
+ * side and reported nowhere else, a narrowing finding included; any other is `live`.
+ */
+export function evaluateEdges<F extends Finding>(
+  findings: readonly F[],
+  sides: readonly EdgeSide[],
+  symbols: readonly InventorySymbol[],
+): Evaluated<F> {
+  if (sides.length === 0) {
+    return { findings, evaluations: [] };
+  }
+  const byRef = new Map<string, string>();
+  for (const symbol of symbols) {
+    if (symbol.kind !== "file" && !byRef.has(symbol.ref)) {
+      byRef.set(symbol.ref, symbol.id);
+    }
+  }
+  const held = new Map<string, number>();
+  findings.forEach((finding, at) => {
+    held.set(positionKey(finding.position), at);
+  });
+
+  const pending = new Set<number>();
+  const evaluations = sides.map((side): EdgeEvaluation<F> => {
+    const id = byRef.get(side.symbol);
+    if (id === undefined) {
+      return { ...side, state: "absent" };
+    }
+    const at = held.get(id);
+    const finding = at === undefined ? undefined : findings[at];
+    if (at === undefined || finding === undefined) {
+      return { ...side, state: "live" };
+    }
+    pending.add(at);
+    return { ...side, state: "dead", finding };
+  });
+  evaluations.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
+  return { findings: findings.filter((_finding, at) => !pending.has(at)), evaluations };
+}

package/src/finding.ts

@@ -1,6 +1,7 @@
 import type { Confidence, Severity } from "./config.ts";
 import type { Fixability } from "./kinds.ts";
 import type { DependencySection } from "./ref.ts";
+import type { Mechanism } from "./suppress.ts";
 import type { Relation } from "./sweep.ts";
 
 /**
@@ -58,6 +59,18 @@ export interface FindingDetails {
   readonly writePositions?: readonly FindingPosition[];
   /** On `DS1601`: the manifest section that declares the dependency. */
   readonly dependencyClass?: DependencySection;
+  /** On `DS1701` and `DS1702`: the document that holds the refused suppression. */
+  readonly mechanism?: Mechanism;
+  /** On `DS1701` and `DS1702`: the refused suppression as written, a member absent where it lacks one. */
+  readonly entry?: SuppressionEntry;
+}
+
+/** One suppression in the four-member form the ignore file and the baseline share. */
+export interface SuppressionEntry {
+  readonly code: string;
+  readonly symbol?: string;
+  readonly path?: string;
+  readonly reason?: string;
 }
 
 /** One finding as its emitter states it. */