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

package/src/erased-stores.ts

@@ -16,7 +16,6 @@ import {
   isNoSubstitutionTemplateLiteral,
   isNumericLiteral,
   isObjectLiteralExpression,
-  isParenthesizedExpression,
   isPropertyAccessExpression,
   isPropertyAssignment,
   isShorthandPropertyAssignment,
@@ -31,6 +30,7 @@ import { SymbolFlags, TypeFlags, type Type } from "@typescript/native/sync";
 import { must } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 import { checkedTypes } from "./value-reach.ts";
+import { parenthesesRemoved } from "./unwrap.ts";
 
 /** The types that keep nothing of the value they are given. */
 const ERASED = TypeFlags.Any | TypeFlags.Unknown;
@@ -81,10 +81,6 @@ function literalKey(node: Expression): string | undefined {
     : undefined;
 }
 
-function unwrapped(node: Expression): Expression {
-  return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
-}
-
 /**
  * Whether a variable declaration's type can differ from what is stored in it: it carries an
  * annotation, or it has neither an annotation nor an initializer, so its type evolves.
@@ -150,8 +146,8 @@ function propertyAt(source: Expression, name: string): Expression | undefined {
  * here, and a default value is stored in its target too.
  */
 function patternTargets(pattern: Expression, from: Stored, out: Target[]): void {
-  const target = unwrapped(pattern);
-  const source = from.path.length === 0 ? unwrapped(from.value) : from.value;
+  const target = parenthesesRemoved(pattern);
+  const source = from.path.length === 0 ? parenthesesRemoved(from.value) : from.value;
   const into = (element: Expression, step: Step, literal: Expression | undefined): void => {
     patternTargets(
       element,

package/src/exempt-classes.ts

@@ -1,12 +1,4 @@
-/**
- * The exemption classes of the Contract's vocabulary, in its order: each class's name, its
- * languages and, for a TypeScript class, which private members it may retain. The rows are
- * written out, as the fixed severity codes are, and a test holds them equal to the Contract.
- * A class name is a type, so a table or a record naming a class outside the vocabulary, or
- * one of another language only, does not compile.
- */
-
-import type { Language } from "./config.ts";
+import { EXEMPTION_CLASSES, type Language } from "./contract/contract.generated.ts";
 
 /**
  * Whether a class may retain a member declared with the `private` modifier, and one
@@ -19,67 +11,6 @@ export interface TypeScriptVisibility {
   readonly privateName: boolean;
 }
 
-/** One class of the vocabulary. */
-interface ExemptionClassRow {
-  readonly class: string;
-  readonly languages: readonly Language[];
-  /** Present exactly on a class that runs on TypeScript. */
-  readonly typescriptVisibility?: TypeScriptVisibility;
-}
-
-/** Every class of the vocabulary, in the order the Contract lists them. */
-export const EXEMPTION_CLASSES = [
-  {
-    class: "interface-satisfaction",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: false, privateName: false },
-  },
-  { class: "encoding-reflection", languages: ["go"] },
-  { class: "format-verb-contract", languages: ["go"] },
-  { class: "errors-duck-typing", languages: ["go"] },
-  {
-    class: "enum-group",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: false, privateName: false },
-  },
-  {
-    class: "generated-file",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  { class: "linkname-cgo-asm-plugin", languages: ["go"] },
-  {
-    class: "template-field",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "reflective-lookup",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "decorator",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "injection-container",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "framework-lifecycle",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "serialization-contract",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-] as const satisfies readonly ExemptionClassRow[];
-
 type Row = (typeof EXEMPTION_CLASSES)[number];
 
 /** The name of a class of the vocabulary. */
@@ -116,8 +47,3 @@ const VISIBILITY: ReadonlyMap<TSExemptionClass, TypeScriptVisibility> = new Map(
 export function typescriptVisibilityOf(exemptionClass: TSExemptionClass): TypeScriptVisibility {
   return VISIBILITY.get(exemptionClass) ?? { private: false, privateName: false };
 }
-
-/** Whether one name is a class of the vocabulary, whichever language it runs on. */
-export function isExemptionClass(name: string): name is ExemptionClass {
-  return EXEMPTION_CLASSES.some((row) => row.class === name);
-}

package/src/exempt.ts

@@ -7,24 +7,23 @@
  * hands it the table of the classes it has.
  */
 
-import type { Config, TSSection } from "./config.ts";
-import { ConfigError } from "./config.ts";
+import { EXEMPTION_CLASSES } from "./contract/contract.generated.ts";
+import type { ResolvedConfig } from "./config.ts";
 import {
-  EXEMPTION_CLASSES,
-  isExemptionClass,
   TS_EXEMPTION_CLASSES,
   typescriptVisibilityOf,
   type ExemptionClass,
   type TSExemptionClass,
   type TypeScriptVisibility,
 } from "./exempt-classes.ts";
-import type { Inventory, InventorySymbol, SymbolKind, Visibility } from "./inventory.ts";
+import type { Inventory, InventorySymbol, Visibility } from "./inventory.ts";
 import type { Matrix } from "./matrix.ts";
 import { byPosition, positionKey, type Position } from "./position.ts";
 import { Unanswerable } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 import type { Templates } from "./template-field.ts";
 import { sweep, type Exemption, type Implementing, type Mode, type SweepInput } from "./sweep.ts";
+import { bytewise } from "./text/compare.ts";
 
 /** One declaration a detector holds back, and where and why. */
 export interface Evidence {
@@ -37,6 +36,8 @@ export interface Evidence {
   readonly whileLive?: string;
   /** Where the evidence is an implementation of interface methods, which and how. */
   readonly implementing?: Implementing;
+  /** Whether the evidence holds only where a write the mode counts stores into the declaration. */
+  readonly whileWritten?: true;
 }
 
 /** What a detector reads of one project, while the project's view is open. */
@@ -47,7 +48,7 @@ export interface DetectorInput<Brand> {
   /** The configured templates, read once for the run. */
   readonly templates: Templates;
   /** The `ts` section, whose declarations the configured classes read. */
-  readonly ts: TSSection;
+  readonly ts: ResolvedConfig["ts"];
   /** The absolute path of each declared consumer, whose modules are part of the analysis. */
   readonly consumers: readonly string[];
   /** The project's generated files, by path below the target root, each with the detail its retentions name. */
@@ -71,24 +72,11 @@ interface Holding {
 }
 
 /**
- * The classes `exemptions.disabled` switches off. A name is refused unless the
- * vocabulary holds it; a class that runs on another language only is admitted and
- * switches nothing off here, so one configuration serves every analyzer.
+ * The classes `exemptions.disabled` switches off. A class that runs on another language
+ * only switches nothing off here, so one configuration serves every analyzer.
  */
-export function disabledClasses(config: Config): ReadonlySet<ExemptionClass> {
-  const disabled = new Set<ExemptionClass>();
-  for (const name of config.exemptionsDisabled) {
-    if (!isExemptionClass(name)) {
-      const known = EXEMPTION_CLASSES.map((row) => row.class).join(", ");
-      throw new ConfigError(
-        "malformed",
-        "exemptions.disabled",
-        `exemptions.disabled: ${JSON.stringify(name)} is not an exemption class: the classes are ${known}`,
-      );
-    }
-    disabled.add(name);
-  }
-  return disabled;
+export function disabledClasses(config: ResolvedConfig): ReadonlySet<ExemptionClass> {
+  return new Set(config.exemptions.disabled);
 }
 
 /**
@@ -105,20 +93,12 @@ function retainable(allowed: TypeScriptVisibility, visibility: Visibility | unde
   return true;
 }
 
-/**
- * The kinds of declaration each class can hold back, which a detector that stops holds
- * back whole. A class with no row here holds back every declaration but a file.
- */
-const RETAINABLE: ReadonlyMap<TSExemptionClass, ReadonlySet<SymbolKind>> = new Map([
-  ["interface-satisfaction", new Set<SymbolKind>(["method", "class-member"])],
-  ["enum-group", new Set<SymbolKind>(["enum-member"])],
-  ["injection-container", new Set<SymbolKind>(["method", "class-member"])],
-  ["framework-lifecycle", new Set<SymbolKind>(["method", "class-member"])],
-  [
-    "serialization-contract",
-    new Set<SymbolKind>(["method", "class-member", "interface-method", "type-member"]),
-  ],
-]);
+/** The kinds of declaration each class can hold back, which a detector that stops holds back whole. */
+const RETAINABLE: ReadonlyMap<string, ReadonlySet<string>> = new Map(
+  EXEMPTION_CLASSES.flatMap((row) =>
+    "ts" in row.retainsKinds ? [[row.class, new Set<string>(row.retainsKinds.ts)] as const] : [],
+  ),
+);
 
 /** The detail of a record a detector that could not finish holds. */
 const UNANSWERED_DETAIL = "kept live by a question the checker did not answer";
@@ -147,7 +127,7 @@ function detected<Brand>(
     }
     const kinds = RETAINABLE.get(exemptionClass);
     return input.held.symbols
-      .filter((symbol) => (kinds === undefined ? symbol.kind !== "file" : kinds.has(symbol.kind)))
+      .filter((symbol) => kinds?.has(symbol.kind) === true)
       .map((symbol) => ({ id: symbol.id, detail: UNANSWERED_DETAIL, site: symbol.position }));
   }
 }
@@ -193,12 +173,26 @@ export function evidenceRecords<Brand>(
         site: evidence.site,
         ...(evidence.whileLive === undefined ? {} : { whileLive: evidence.whileLive }),
         ...(evidence.implementing === undefined ? {} : { implementing: evidence.implementing }),
+        ...(evidence.whileWritten === undefined ? {} : { whileWritten: evidence.whileWritten }),
       });
     }
   }
   return found;
 }
 
+/**
+ * The records that hold given the declarations a write the mode counts stores into: one
+ * that holds only while written holds where its declaration is among them.
+ */
+export function writtenRecords(
+  records: readonly Exemption[],
+  written: ReadonlySet<string>,
+): readonly Exemption[] {
+  return records.flatMap(({ whileWritten, ...record }) =>
+    whileWritten === undefined || written.has(record.id) ? [record] : [],
+  );
+}
+
 /** The records that hold under one mode, beside the evidence a production mode found in a test file. */
 export function heldRecords(records: readonly Exemption[], holding: Holding): Detected {
   const found: Exemption[] = [];
@@ -213,14 +207,6 @@ export function heldRecords(records: readonly Exemption[], holding: Holding): De
   return { records: exemptionsOf(found), inTestFiles };
 }
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
  * Records as a run holds them: ordered by site, then class, then declaration, and one
  * per declaration, class, detail and file it holds while live, the one at the first
@@ -228,7 +214,7 @@ function compare(a: string, b: string): number {
  */
 export function exemptionsOf(found: readonly Exemption[]): readonly Exemption[] {
   const ordered = [...found].sort(
-    (a, b) => byPosition(a.site, b.site) || compare(a.class, b.class) || compare(a.id, b.id),
+    (a, b) => byPosition(a.site, b.site) || bytewise(a.class, b.class) || bytewise(a.id, b.id),
   );
   const seen = new Set<string>();
   return ordered.filter((record) => {
@@ -300,8 +286,8 @@ export function retainedIn(
 }
 
 /**
- * One line per held-back declaration, in site order: its reference, then each record's
- * class, site and detail, all separated by tabs.
+ * One line per held-back declaration, in site order: its reference and position, then
+ * each record's class, site and detail, all separated by tabs.
  */
 export function retainedLines(
   symbols: readonly InventorySymbol[],
@@ -318,6 +304,6 @@ export function retainedLines(
       positionKey(record.site),
       record.detail,
     ]);
-    return [[symbol.ref, ...fields].join("\t")];
+    return [[symbol.ref, positionKey(symbol.position), ...fields].join("\t")];
   });
 }

package/src/failure.ts

@@ -0,0 +1,63 @@
+import { FAILURE_CLASSES, FAILURE_PREFIXES } from "./contract/contract.generated.ts";
+import type { LocatedDiagnostic } from "./load/diagnostics.ts";
+import { PRODUCT } from "./product.ts";
+
+/** A class of failure the Contract's exit-code table names, of either group. */
+type FailureClass = keyof typeof FAILURE_CLASSES;
+
+/** One cause the run ends with the failure code for. */
+export interface Failure {
+  readonly failureClass: FailureClass;
+  /** What fails and the fix, on one line. */
+  readonly detail: string;
+}
+
+/** The failure as a class line of the error stream, opened by its group's prefix. */
+export function failureLine(failure: Failure): string {
+  return `${FAILURE_PREFIXES[FAILURE_CLASSES[failure.failureClass]]}${failure.failureClass}: ${failure.detail}`;
+}
+
+/**
+ * The lines of the error stream that name the failures: the first one's class line, the run's
+ * only one, then each further failure as its class and detail with no group prefix.
+ */
+export function failureLines([first, ...further]: readonly [Failure, ...Failure[]]): string[] {
+  return [failureLine(first), ...further.map((one) => `${one.failureClass}: ${one.detail}`)];
+}
+
+/**
+ * A run the analysis cannot answer. It ends the run with the failure code and no finding
+ * list, printing the compiler's located errors and then the failures' lines.
+ */
+export class FailureExit extends Error {
+  readonly failures: readonly [Failure, ...Failure[]];
+  /** The compiler's errors behind the failures, in the order it reported them. */
+  readonly diagnostics: readonly LocatedDiagnostic[];
+
+  constructor(
+    failures: readonly [Failure, ...Failure[]],
+    diagnostics: readonly LocatedDiagnostic[] = [],
+  ) {
+    super(failureLines(failures).join("\n"));
+    this.name = "FailureExit";
+    this.failures = failures;
+    this.diagnostics = diagnostics;
+  }
+}
+
+/** A failure exit of one failure. */
+export function failureExit(
+  failureClass: FailureClass,
+  detail: string,
+  diagnostics: readonly LocatedDiagnostic[] = [],
+): FailureExit {
+  return new FailureExit([{ failureClass, detail }], diagnostics);
+}
+
+/** A fault of this analyzer itself, `fault` saying what it cannot do. */
+export function productFault(fault: string): FailureExit {
+  return failureExit(
+    "product-fault",
+    `${PRODUCT} ${fault}: reinstall ${PRODUCT}, and report the fault to its maintainers if a reinstalled ${PRODUCT} fails the same way`,
+  );
+}

package/src/file-facts.ts

@@ -5,12 +5,13 @@
  */
 
 import type { SourceFile } from "@typescript/native/ast";
-import { IGNORED_DIRECTORIES } from "./discover.ts";
 import type { Host } from "./host.ts";
 import { packageScope } from "./inventory.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import { renderRef } from "./ref.ts";
 import type { ProjectView } from "./session.ts";
+import type { UnseenLoad } from "./unseen-loads.ts";
+import { filesBelow } from "./fs/tree.ts";
 
 /** A file name the compiler reads as a source file. */
 const SOURCE_FILE = /\.(?:ts|tsx|mts|cts)$/u;
@@ -51,6 +52,8 @@ export interface FileFacts {
   readonly generated?: ReadonlySet<string>;
   /** The property names an `in` expression of a production file tests by a literal. */
   readonly inOperands?: ReadonlySet<string>;
+  /** The loads of production files whose target the analysis cannot resolve. */
+  readonly unseenLoads?: readonly UnseenLoad[];
 }
 
 /** The line of the last character of one text, counted from one; an empty text is one line. */
@@ -71,29 +74,11 @@ function lastLine(text: string): number {
  * that cannot be read is skipped, as discovery skips it.
  */
 export function sourcePaths(host: Host, targetRoot: string): readonly string[] {
-  const found: string[] = [];
-  const pending = [""];
-  for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
-    let entries: readonly { readonly name: string; readonly directory: boolean }[];
-    try {
-      entries = host.readDirectory(joinPath(targetRoot, dir));
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
-      if (entry.directory) {
-        if (!IGNORED_DIRECTORIES.has(entry.name)) {
-          pending.push(path);
-        }
-        continue;
-      }
-      if (SOURCE_FILE.test(entry.name) && !DECLARATION_FILE.test(entry.name)) {
-        found.push(path);
-      }
-    }
-  }
-  return found.sort((a, b) => (a < b ? -1 : 1));
+  return filesBelow(
+    host,
+    targetRoot,
+    (name) => SOURCE_FILE.test(name) && !DECLARATION_FILE.test(name),
+  );
 }
 
 /**

package/src/finding.ts

@@ -1,8 +1,8 @@
-import type { Confidence, Severity } from "./config.ts";
-import type { Fixability } from "./kinds.ts";
+import type { Fixability, Confidence, Severity } from "./contract/contract.generated.ts";
 import type { DependencySection } from "./ref.ts";
 import type { Mechanism } from "./suppress.ts";
 import type { Relation } from "./sweep.ts";
+import type { FindingSymbol } from "./contract/report.generated.ts";
 
 /**
  * The finding: what an emitter decides about one subject, and every member the
@@ -29,11 +29,17 @@ interface FindingSubject {
   /** The stable symbol reference, or for a configured root the root as written. */
   readonly ref: string;
   /** The subject kind, from the closed vocabulary of the finding schema. */
-  readonly kind: string;
+  readonly kind: FindingSymbol["kind"];
   /** The display name a text line renders. */
   readonly name: string;
   /** The number of source lines the subject spans. */
   readonly sizeLines: number;
+  /**
+   * Where the subject is a part whose reference is its own, a parameter's, the reference
+   * of the declaration that holds it, which a record binding that declaration matches.
+   * No report carries it.
+   */
+  readonly holder?: string;
 }
 
 /** A declaration a finding names beside the subject, with where it is written. */
@@ -49,19 +55,19 @@ export interface PositionedSymbol {
  */
 export interface FindingDetails {
   /**
-   * On `DS1101` and `DS1104`: the widest scope that holds every reference to the
+   * On `DS1501` and `DS1503`: the widest scope that holds every reference to the
    * subject, which is the visibility its references support.
    */
   readonly narrowerVisibility?: "file" | "package";
-  /** On `DS1201` and `DS1203`: the classes implementing the interface, in site order. */
+  /** On `DS1201` and `DS1202`: the classes implementing the interface, in site order. */
   readonly implementations?: readonly PositionedSymbol[];
-  /** On `DS1301` and `DS1807`: every position the subject is written at, in site order. */
+  /** On `DS1301` and `DS1404`: every position the subject is written at, in site order. */
   readonly writePositions?: readonly FindingPosition[];
-  /** On `DS1601`: the manifest section that declares the dependency. */
+  /** On `DS1701`: the manifest section that declares the dependency. */
   readonly dependencyClass?: DependencySection;
-  /** On `DS1701` and `DS1702`: the document that holds the refused suppression. */
+  /** On `DS9001` and `DS9002`: 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. */
+  /** On `DS9001` and `DS9002`: the refused suppression as written, a member absent where it lacks one. */
   readonly entry?: SuppressionEntry;
   /** On the intra-function kinds: the external rules that report the same kind, as the vocabulary lists them. */
   readonly overlap?: readonly string[];
@@ -87,6 +93,10 @@ export interface Finding {
   readonly details?: FindingDetails;
   /** The reachability class of a subject that is no declaration, where it is not `certain`. */
   readonly reachabilityClass?: Confidence;
+  /** Whether references to a subject that is no declaration exist, all from dead code. */
+  readonly unreachableOnly?: true;
+  /** The dead declarations and files whose component a subject that is no declaration falls with. */
+  readonly fallsWith?: readonly string[];
 }
 
 /** The dead component a finding names, as the finding schema spells its members. */
@@ -109,6 +119,11 @@ export interface CompletedFinding extends Finding {
   readonly reachabilityClass: Confidence;
   /** The reachability class capped by the code's ceiling. */
   readonly confidence: Confidence;
+  /**
+   * Where test-used code alone lowers the confidence, the one the finding would carry
+   * otherwise, which its component's cap and the dials read.
+   */
+  readonly componentConfidence?: Confidence;
   /**
    * The relation that decided the subject: present on a declaration the sweep judged
    * dead, absent on a live one and on a subject that is no declaration.

package/src/findings/boundary.ts

@@ -25,4 +25,6 @@ export interface Boundary {
   readonly encapsulated: boolean;
   /** Every side of a declared cross-language edge that names a symbol of this language. */
   readonly edges: readonly EdgeSide[];
+  /** The members a function outside the analysis fills, which it may read unseen. */
+  readonly filledOutside?: ReadonlySet<string>;
 }