@cplieger/deadset-ts 8.0.0-dev.20 → 8.0.0-dev.21

package/src/exempt.ts

@@ -1,295 +0,0 @@
-/**
- * The exemption framework: the classes of reason for which a declaration the reference
- * graph alone would report is live all the same. A class is policy over what one
- * project's checker answers, and its detector names the declarations it holds back;
- * this module runs the detectors, decides which of their records stand, and answers
- * which records held something back. It names no class's detector: the composition
- * hands it the table of the classes it has.
- */
-
-import { EXEMPTION_CLASSES } from "./contract/contract.generated.ts";
-import type { GeneratedFact } from "./generated-file.ts";
-import type { ResolvedConfig } from "./config.ts";
-import {
-  TS_EXEMPTION_CLASSES,
-  typescriptVisibilityOf,
-  type ExemptionClass,
-  type TSExemptionClass,
-  type TypeScriptVisibility,
-} from "./exempt-classes.ts";
-import type { Inventory, InventorySymbol, Visibility } from "./inventory.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 type { Mode } from "./tests/file-class.ts";
-import { bytewise } from "./text/compare.ts";
-
-/** One declaration an exemption class holds back, and the evidence it was found by. */
-export interface Exemption {
-  /** The identifier of the declaration held back. */
-  readonly id: string;
-  readonly class: TSExemptionClass;
-  /** One clause naming the relation, then the thing it relates to: `passed to JSON.stringify`. */
-  readonly detail: string;
-  /** Where the evidence is written. */
-  readonly site: Position;
-  /**
-   * The component file, below the target root, whose markup holds the evidence. The
-   * record holds only while that file is live.
-   */
-  readonly whileLive?: string;
-  /**
-   * The interface methods the retained member implements, and whether its body is empty.
-   * The record holds only while one of them is called through its interface.
-   */
-  readonly implementing?: Implementing;
-  /** Whether the record holds only where a write the mode counts stores into the declaration. */
-  readonly whileWritten?: true;
-}
-
-/** The interface methods one retained class member implements, and whether its body is empty. */
-interface Implementing {
-  /** The declarations of the interface's methods the member answers, by identifier. */
-  readonly methods: readonly string[];
-  readonly empty: boolean;
-}
-
-/** One declaration a detector holds back, and where and why. */
-export interface Evidence {
-  /** The identifier of the declaration held back. */
-  readonly id: string;
-  /** One clause naming the relation, then the thing it relates to. */
-  readonly detail: string;
-  readonly site: Position;
-  /** The component file, below the target root, whose markup holds the 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. */
-export interface DetectorInput<Brand> {
-  readonly project: ProjectView<Brand>;
-  readonly held: Inventory;
-  readonly targetRoot: string;
-  /** The configured templates, read once for the run. */
-  readonly templates: Templates;
-  /** The `ts` section, whose declarations the configured classes read. */
-  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 what decided it. */
-  readonly generated?: ReadonlyMap<string, GeneratedFact>;
-}
-
-/**
- * One class's detection over one project. The framework records each piece of evidence
- * under the class the table names the detector by, so a detector names no class.
- */
-export type Detector = <Brand>(input: DetectorInput<Brand>) => readonly Evidence[];
-
-/** The detector of each class one composition implements. */
-export type Detectors = ReadonlyMap<TSExemptionClass, Detector>;
-
-/** What decides which records of one project stand. */
-interface Holding {
-  readonly mode: Mode;
-  /** The paths the reference pass classified as test files. */
-  readonly testFiles: ReadonlySet<string>;
-}
-
-/**
- * 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: ResolvedConfig): ReadonlySet<ExemptionClass> {
-  return new Set(config.exemptions.disabled);
-}
-
-/**
- * Whether a class whose row states `allowed` may retain a member of one visibility. A
- * declaration the inventory does not hold has no visibility to refuse it by.
- */
-function retainable(allowed: TypeScriptVisibility, visibility: Visibility | undefined): boolean {
-  if (visibility === "private") {
-    return allowed.private;
-  }
-  if (visibility === "private-name") {
-    return allowed.privateName;
-  }
-  return true;
-}
-
-/** 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";
-
-/** Whether one record is held by a detector that could not finish. */
-export function isUnansweredRecord(record: Exemption): boolean {
-  return record.detail === UNANSWERED_DETAIL;
-}
-
-/**
- * What one detector holds back over one project. A detector that stops because the
- * checker left a question it needs unanswered holds back every declaration of the
- * project its class could hold back, each recorded at its own position, so the gap
- * never yields a finding.
- */
-function detected<Brand>(
-  exemptionClass: TSExemptionClass,
-  detect: Detector,
-  input: DetectorInput<Brand>,
-): readonly Evidence[] {
-  try {
-    return detect(input);
-  } catch (error: unknown) {
-    if (!(error instanceof Unanswerable)) {
-      throw error;
-    }
-    const kinds = RETAINABLE.get(exemptionClass);
-    return input.held.symbols
-      .filter((symbol) => kinds?.has(symbol.kind) === true)
-      .map((symbol) => ({ id: symbol.id, detail: UNANSWERED_DETAIL, site: symbol.position }));
-  }
-}
-
-/** One project's records, and the evidence a production mode found in a test file. */
-interface Detected {
-  readonly records: readonly Exemption[];
-  /**
-   * Under a production mode, each record whose evidence is written in a test file. It
-   * holds nothing, and it is a test reference to its declaration, as a reference the
-   * test file wrote would be.
-   */
-  readonly inTestFiles: readonly Exemption[];
-}
-
-/**
- * Every record one project's detectors found, one per piece of evidence, before the
- * mode decides which of them hold: what {@link heldRecords} reads. Classes run in the
- * vocabulary's order and a switched-off class runs not at all; evidence on a private
- * member the class's row says it cannot retain is dropped, whatever the detector found.
- */
-export function evidenceRecords<Brand>(
-  input: DetectorInput<Brand>,
-  detectors: Detectors,
-  disabled: ReadonlySet<ExemptionClass>,
-): readonly Exemption[] {
-  const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
-  const found: Exemption[] = [];
-  for (const exemptionClass of TS_EXEMPTION_CLASSES) {
-    const detect = detectors.get(exemptionClass);
-    if (detect === undefined || disabled.has(exemptionClass)) {
-      continue;
-    }
-    const allowed = typescriptVisibilityOf(exemptionClass);
-    for (const evidence of detected(exemptionClass, detect, input)) {
-      if (!retainable(allowed, visibility.get(evidence.id))) {
-        continue;
-      }
-      found.push({
-        id: evidence.id,
-        class: exemptionClass,
-        detail: evidence.detail,
-        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[] = [];
-  const inTestFiles: Exemption[] = [];
-  for (const record of records) {
-    if (holding.mode.production && holding.testFiles.has(record.site.path)) {
-      inTestFiles.push(record);
-    } else {
-      found.push(record);
-    }
-  }
-  return { records: exemptionsOf(found), inTestFiles };
-}
-
-/**
- * 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
- * site. A fact found at many sites, or by several projects, is one record.
- */
-export function exemptionsOf(found: readonly Exemption[]): readonly Exemption[] {
-  const ordered = [...found].sort(
-    (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) => {
-    const fact = [record.id, record.class, record.detail, record.whileLive ?? ""].join("\u0000");
-    if (seen.has(fact)) {
-      return false;
-    }
-    seen.add(fact);
-    return true;
-  });
-}
-
-/** The records per declaration, each declaration's in the order given. */
-function byDeclaration(records: readonly Exemption[]): ReadonlyMap<string, readonly Exemption[]> {
-  const grouped = new Map<string, Exemption[]>();
-  for (const record of records) {
-    const held = grouped.get(record.id);
-    if (held === undefined) {
-      grouped.set(record.id, [record]);
-    } else {
-      held.push(record);
-    }
-  }
-  return grouped;
-}
-
-/**
- * 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[],
-  retained: readonly Exemption[],
-): readonly string[] {
-  const held = byDeclaration(retained);
-  return symbols.flatMap((symbol) => {
-    const records = held.get(symbol.id);
-    if (records === undefined) {
-      return [];
-    }
-    const fields = records.flatMap((record) => [
-      record.class,
-      positionKey(record.site),
-      record.detail,
-    ]);
-    return [[symbol.ref, positionKey(symbol.position), ...fields].join("\t")];
-  });
-}

package/src/value-flow.ts

@@ -1,104 +0,0 @@
-/**
- * The values a program hands to a position the checker types from its context: the
- * initializer of a declaration whose type is written, an assignment's right side, an
- * argument, a returned value, an arrow function's expression body, an array element, an
- * object property, and the operand of `as` or `satisfies`.
- */
-
-import {
-  isArrayLiteralExpression,
-  isArrowFunction,
-  isAsExpression,
-  isBinaryExpression,
-  isCallExpression,
-  isConditionalExpression,
-  isIdentifier,
-  isNewExpression,
-  isParameterDeclaration,
-  isParenthesizedExpression,
-  isPropertyAssignment,
-  isPropertyDeclaration,
-  isReturnStatement,
-  isSatisfiesExpression,
-  isShorthandPropertyAssignment,
-  isSpreadElement,
-  isVariableDeclaration,
-  SyntaxKind,
-  type Expression,
-  type Node,
-} from "@typescript/native/ast";
-
-/** The operators of an assignment whose right side is stored into the left side's type. */
-const STORES: ReadonlySet<SyntaxKind> = new Set([
-  SyntaxKind.EqualsToken,
-  SyntaxKind.QuestionQuestionEqualsToken,
-  SyntaxKind.BarBarEqualsToken,
-  SyntaxKind.AmpersandAmpersandEqualsToken,
-]);
-
-/** Whether a declaration writes its type, so its initializer is read in that type's context. */
-function writesType(node: Node): boolean {
-  return (node as { readonly type?: Node }).type !== undefined;
-}
-
-/**
- * The values one written expression hands on: the expression itself, or what it
- * evaluates to through parentheses, a conditional and the operators whose result is
- * one of their operands.
- */
-export function valuesOf(expression: Expression): readonly Expression[] {
-  if (isParenthesizedExpression(expression)) {
-    return valuesOf(expression.expression);
-  }
-  if (isConditionalExpression(expression)) {
-    return [...valuesOf(expression.whenTrue), ...valuesOf(expression.whenFalse)];
-  }
-  if (isBinaryExpression(expression)) {
-    const operator = expression.operatorToken.kind;
-    if (operator === SyntaxKind.QuestionQuestionToken || operator === SyntaxKind.BarBarToken) {
-      return [...valuesOf(expression.left), ...valuesOf(expression.right)];
-    }
-    if (operator === SyntaxKind.AmpersandAmpersandToken || operator === SyntaxKind.CommaToken) {
-      return valuesOf(expression.right);
-    }
-  }
-  return [expression];
-}
-
-/** The expressions one node hands to a position typed by its context. */
-export function handedOn(node: Node): readonly Expression[] {
-  if (
-    (isVariableDeclaration(node) || isPropertyDeclaration(node) || isParameterDeclaration(node)) &&
-    node.initializer !== undefined &&
-    writesType(node)
-  ) {
-    return [node.initializer];
-  }
-  if (isBinaryExpression(node) && STORES.has(node.operatorToken.kind)) {
-    return [node.right];
-  }
-  if (isCallExpression(node) || isNewExpression(node)) {
-    return (node.arguments ?? []).filter((argument) => !isSpreadElement(argument));
-  }
-  if (isReturnStatement(node)) {
-    return node.expression === undefined ? [] : [node.expression];
-  }
-  if (isArrowFunction(node)) {
-    return node.body.kind === SyntaxKind.Block ? [] : [node.body];
-  }
-  if (isArrayLiteralExpression(node)) {
-    return node.elements.filter(
-      (element) => !isSpreadElement(element) && element.kind !== SyntaxKind.OmittedExpression,
-    );
-  }
-  if (isPropertyAssignment(node)) {
-    return [node.initializer];
-  }
-  if (isShorthandPropertyAssignment(node)) {
-    return isIdentifier(node.name) ? [node.name] : [];
-  }
-  if (isAsExpression(node) || isSatisfiesExpression(node)) {
-    return [node.expression];
-  }
-  return [];
-}