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

package/src/query.ts

@@ -8,16 +8,17 @@
  */
 
 import { isIdentifier, type Expression, type Node } from "@typescript/native/ast";
-import type {
-  APIRequestGenerator,
-  Checker,
-  IndexInfo,
-  JSDocTagInfo,
-  Signature,
-  SignatureKind,
-  SymbolFlags,
-  Symbol as TSSymbol,
-  Type,
+import {
+  IndexKind,
+  type APIRequestGenerator,
+  type Checker,
+  type IndexInfo,
+  type JSDocTagInfo,
+  type Signature,
+  type SignatureKind,
+  type SymbolFlags,
+  type Symbol as TSSymbol,
+  type Type,
 } from "@typescript/native/sync";
 
 /**
@@ -205,6 +206,12 @@ export interface Queries {
   targetOf(type: Type): Answer<Type>;
   /** The constraint of a type parameter, where it declares one; none for another type. */
   constraintOf(type: Type): Answer<Type | undefined>;
+  /**
+   * The type a type the checker leaves generic is at most, its constraints resolved, such
+   * as a type parameter, an indexed access, a generic tuple or a union of them; none for
+   * an object type that is not generic.
+   */
+  baseConstraintOf(type: Type): Answer<Type | undefined>;
   /** The object and the index of an indexed-access type; none for another type. */
   indexedAccessOf(type: Type): Answer<{ readonly object: Type; readonly index: Type } | undefined>;
   /**
@@ -232,6 +239,24 @@ export interface Queries {
   genericOf(signature: Signature): Answer<Signature | undefined>;
   /** The type of the parameter an argument at one position binds, a rest element's included. */
   typeAtPosition(signature: Signature, index: number): Answer<Type>;
+  /**
+   * The type of a signature's rest parameter: an array, a tuple, or another type such as
+   * a type parameter or a union of tuples; none where it has none.
+   */
+  restTypeOf(signature: Signature): Answer<Type | undefined>;
+  /**
+   * The type a number index of a type reads, which holds every element type of an array,
+   * a tuple or an array-like interface; none where the type has no number index.
+   */
+  numberIndexOf(type: Type): Answer<Type | undefined>;
+  /**
+   * The type parameters a mapped type is over: every one its alias's arguments, its key
+   * set, its `as` clause or its template names, through the types they are spelled from,
+   * each mapped type's own key parameter aside; none for another type.
+   */
+  mappedParametersOf(type: Type): Answer<readonly Type[]>;
+  /** The type of one named property of a type, its apparent members included; none where it has none. */
+  propertyTypeOf(type: Type, name: string): Answer<Type | undefined>;
   signatureOf(declaration: Node): Answer<Signature | undefined>;
   returnTypeOf(signature: Signature): Answer<Type | undefined>;
   typeToString(type: Type): Answer<string>;
@@ -268,6 +293,43 @@ function partQuestion(type: Type): (() => readonly (Type | undefined)[]) | undef
   return undefined;
 }
 
+/** How deep {@link mappedParameters} reads, as a recursive mapped type makes a new one at each level. */
+const MAPPED_DEPTH = 4;
+
+/** The type parameters a mapped type is over, as {@link Queries.mappedParametersOf} names them. */
+function mappedParameters(checker: Checker, mapped: Type): Type[] {
+  const own = new Set<number>();
+  const found = new Map<number, Type>();
+  const seen = new Set<number>();
+  const visit = (type: Type, depth: number): void => {
+    if (depth > MAPPED_DEPTH || seen.has(type.id)) {
+      return;
+    }
+    seen.add(type.id);
+    if (type.isMappedType()) {
+      own.add(type.getTypeParameter().id);
+    }
+    if (type.isTypeParameter() && !type.isThisType) {
+      found.set(type.id, type);
+    }
+    const aliased = (type as { readonly aliasTypeArguments?: readonly number[] })
+      .aliasTypeArguments;
+    const inner = [
+      ...(type.isUnionType() || type.isIntersectionType() ? type.getTypes() : []),
+      ...(type.isTypeReference() ? checker.getTypeArguments(type) : []),
+      ...(aliased === undefined || aliased.length === 0 ? [] : type.getAliasTypeArguments()),
+      ...(partQuestion(type)?.() ?? []),
+    ];
+    for (const part of inner) {
+      if (part !== undefined) {
+        visit(part, depth + 1);
+      }
+    }
+  };
+  visit(mapped, 0);
+  return [...found.values()].filter((parameter) => !own.has(parameter.id));
+}
+
 /**
  * The guarded questions over one project's checker. `configFile` names the project
  * in the log, `batch` sends many questions in one round trip, `log` is the run's,
@@ -565,6 +627,12 @@ export function queriesOf(
             () => type.getConstraint(),
           )
         : undefined,
+    baseConstraintOf: (type) =>
+      one(
+        "getBaseConstraintOfType",
+        () => typeLocation(type),
+        () => checker.getBaseConstraintOfType(type),
+      ),
     indexedAccessOf: (type) =>
       type.isIndexedAccessType()
         ? one(
@@ -656,6 +724,37 @@ export function queriesOf(
         () => `signature ${String(signature.id)} position ${String(index)}`,
         () => signature.getTypeParameterAtPosition(index),
       ),
+    restTypeOf: (signature) =>
+      signature.hasRestParameter
+        ? one(
+            "getTypeOfSymbol",
+            () => `signature ${String(signature.id)} rest parameter`,
+            () => {
+              const rest = signature.getParameters().at(-1);
+              return rest === undefined ? undefined : checker.getTypeOfSymbol(rest);
+            },
+          )
+        : undefined,
+    numberIndexOf: (type) =>
+      one(
+        "getIndexTypeOfType",
+        () => typeLocation(type),
+        () => checker.getIndexTypeOfType(type, IndexKind.Number),
+      ),
+    mappedParametersOf: (type) =>
+      type.isMappedType()
+        ? one(
+            "getConstraintType",
+            () => typeLocation(type),
+            () => mappedParameters(checker, type),
+          )
+        : [],
+    propertyTypeOf: (type, name) =>
+      one(
+        "getTypeOfPropertyOfType",
+        () => `${typeLocation(type)} property ${name}`,
+        () => checker.getTypeOfPropertyOfType(type, name),
+      ),
     signatureOf: (declaration) =>
       one(
         "getSignatureFromDeclaration",

package/src/roots/configured-declarations.ts

@@ -17,8 +17,7 @@ import {
   type Node,
 } from "@typescript/native/ast";
 import { SymbolFlags, type NodeHandle, type Symbol as TSSymbol } from "@typescript/native/sync";
-import type { AliasChains } from "../alias-chain.ts";
-import { resolvedTargets } from "../calls.ts";
+import { resolvedTargets, type AliasChains } from "../alias-chain.ts";
 import type { DeclarationEntry, ResolvedConfig } from "../config.ts";
 import { declaredComponent, type Inventory } from "../inventory.ts";
 import { must, Unanswerable } from "../query.ts";

package/src/stores.ts

@@ -12,7 +12,7 @@ import {
 import { nodeKey, type Inventory } from "./inventory.ts";
 import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
-import type { Exemption } from "./exempt.ts";
+import type { Exemption } from "./exemptions/lifecycle.ts";
 import type { Mode } from "./tests/file-class.ts";
 import { classedAsTest, madeByTestCode, withheldBy } from "./tests/file-class.ts";
 

package/src/verbs/print-retained.ts

@@ -1,12 +1,40 @@
 import { EXIT_CLEAN } from "../contract/contract.generated.ts";
 import { productionMode, runSweep } from "../analysis.ts";
-import { retainedLines } from "../exempt.ts";
+import type { Exemption } from "../exemptions/lifecycle.ts";
+import type { InventorySymbol } from "../inventory.ts";
 import { partialNotes } from "../partial.ts";
+import { positionKey } from "../position.ts";
 import { resolvePath } from "../paths.ts";
 import { resolve } from "../resolve.ts";
 import { type Verb } from "./verb.ts";
 import { diagnose } from "../product.ts";
 
+/**
+ * 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.
+ */
+function retainedLines(
+  symbols: readonly InventorySymbol[],
+  retained: readonly Exemption[],
+): readonly string[] {
+  const held = new Map<string, Exemption[]>();
+  for (const record of retained) {
+    held.set(record.id, [...(held.get(record.id) ?? []), record]);
+  }
+  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")];
+  });
+}
+
 /**
  * Writes every declaration an exemption held back in the production sweep a report is
  * built from, one per line, and nothing where no exemption held one back. One fact

package/dist/src/exempt.js

@@ -1,164 +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.js";
-import { TS_EXEMPTION_CLASSES, typescriptVisibilityOf, } from "./exempt-classes.js";
-import { byPosition, positionKey } from "./position.js";
-import { Unanswerable } from "./query.js";
-import { bytewise } from "./text/compare.js";
-/**
- * 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) {
-    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, visibility) {
-    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 = new Map(EXEMPTION_CLASSES.flatMap((row) => "ts" in row.retainsKinds ? [[row.class, new Set(row.retainsKinds.ts)]] : []));
-/** 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) {
-    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(exemptionClass, detect, input) {
-    try {
-        return detect(input);
-    }
-    catch (error) {
-        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 }));
-    }
-}
-/**
- * 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(input, detectors, disabled) {
-    const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
-    const found = [];
-    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, written) {
-    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, holding) {
-    const found = [];
-    const inTestFiles = [];
-    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) {
-    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();
-    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) {
-    const grouped = new Map();
-    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, retained) {
-    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/dist/src/value-flow.js

@@ -1,74 +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, } from "@typescript/native/ast";
-/** The operators of an assignment whose right side is stored into the left side's type. */
-const STORES = 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) {
-    return 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) {
-    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) {
-    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 [];
-}

package/src/decorator.ts

@@ -1,78 +0,0 @@
-/**
- * The decorator class: a member a decorator expression is attached to, and every member
- * of a class one is attached to but the member a parameter property declares, is held
- * back, because the decorator may reach the member by its name. The rule is read from
- * the tree alone. The decorator's own use of what it decorates is the reference pass's
- * `decorator` reference; this class records only that the declaration is held back,
- * static members of a decorated class included.
- */
-
-import type { Node } from "@typescript/native/ast";
-import { decoratorsOf, spelledDecorator } from "./calls.ts";
-import type { DetectorInput, Evidence } from "./exempt.ts";
-import {
-  isParameterProperty,
-  nodeKey,
-  type InventorySymbol,
-  type SymbolKind,
-} from "./inventory.ts";
-import { renderPosition } from "./position.ts";
-
-/** The kinds of declaration a decorator is attached to and holds back. */
-const DECORATED: ReadonlySet<SymbolKind> = new Set(["class", "method", "class-member"]);
-
-/**
- * The decorator detector: each decorated member, and each member of a decorated
- * class, recorded at the decorator.
- */
-export function decorator<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
-  const { project, held, targetRoot } = input;
-  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
-  const membersOf = new Map<string, InventorySymbol[]>();
-  for (const symbol of held.symbols) {
-    if (symbol.kind === "method" || symbol.kind === "class-member") {
-      const members = membersOf.get(symbol.parent);
-      if (members === undefined) {
-        membersOf.set(symbol.parent, [symbol]);
-      } else {
-        members.push(symbol);
-      }
-    }
-  }
-
-  const decorated: {
-    readonly symbol: InventorySymbol;
-    readonly detail: string;
-    readonly site: Evidence["site"];
-  }[] = [];
-  // A decorated class's container passes each constructor argument, which keeps the
-  // parameter, not the member a parameter property stores it in.
-  const parameterMembers = new Set<string>();
-  for (const file of project.ownSourceFiles()) {
-    const visit = (node: Node): void => {
-      const id = held.declarations.get(nodeKey(file, node));
-      const symbol = id === undefined ? undefined : byId.get(id);
-      if (id !== undefined && isParameterProperty(node)) {
-        parameterMembers.add(id);
-      }
-      // A parameter property's decorator is attached to its parameter, and to no member.
-      if (symbol !== undefined && DECORATED.has(symbol.kind) && !isParameterProperty(node)) {
-        for (const attached of decoratorsOf(node)) {
-          decorated.push({
-            symbol,
-            detail: `decorated by ${spelledDecorator(attached)}`,
-            site: renderPosition(file, targetRoot, attached.getStart()),
-          });
-        }
-      }
-      node.forEachChild(visit);
-    };
-    file.forEachChild(visit);
-  }
-  return decorated.flatMap(({ symbol, detail, site }) =>
-    (symbol.kind === "class"
-      ? (membersOf.get(symbol.id) ?? []).filter((member) => !parameterMembers.has(member.id))
-      : [symbol]
-    ).map((member) => ({ id: member.id, detail, site })),
-  );
-}