@cplieger/deadset-ts 3.3.0 → 3.4.0

package/src/config.ts

@@ -97,10 +97,38 @@ export interface Reporters {
   readonly failOn: Severity;
 }
 
+/**
+ * One declaration a configuration entry names, in exactly one of three shapes: a
+ * declaration of the analyzed program by its stable symbol reference, a declaration a
+ * module exports by the bare specifier an import writes for the module and the
+ * declaration's path from its exports, or a declaration of the global scope by its
+ * path from that scope. A path joins the name and each member with dots and spells a
+ * static member with `:static` after it.
+ */
+export type DeclarationEntry =
+  | { readonly shape: "symbol"; readonly symbol: string }
+  | { readonly shape: "module"; readonly module: string; readonly name: string }
+  | { readonly shape: "global"; readonly global: string };
+
+/**
+ * One framework's lifecycle contract: the declarations whose use makes a class one of
+ * the framework's components, the classes whose subclasses are its components, and the
+ * names of the members the framework calls on a component, each spelled as the last
+ * component of a member's stable symbol reference.
+ */
+export interface LifecycleContract {
+  readonly components: readonly DeclarationEntry[];
+  readonly bases: readonly DeclarationEntry[];
+  readonly members: readonly string[];
+}
+
 /** The section the TypeScript analyzer owns. */
 export interface TSSection {
   readonly testFiles: readonly string[];
   readonly entryFiles: readonly string[];
+  readonly injectionRegistrations: readonly DeclarationEntry[];
+  readonly lifecycleContracts: readonly LifecycleContract[];
+  readonly serializers: readonly DeclarationEntry[];
 }
 
 /**
@@ -159,6 +187,9 @@ export function defaultConfig(): Config {
     ts: {
       testFiles: ["**/*.test.{ts,tsx,mts,cts}"],
       entryFiles: [],
+      injectionRegistrations: [],
+      lifecycleContracts: [],
+      serializers: [],
     },
   };
 }

package/src/configured-declarations.ts

@@ -0,0 +1,308 @@
+/**
+ * The declarations the configuration's entries name, resolved in one project, and
+ * which of them a symbol is. Declarations are compared rather than symbols, because a
+ * member read through an instantiation of a generic type is a symbol of its own that
+ * keeps the declarations of the member it instantiates.
+ */
+
+import {
+  isCallExpression,
+  isExportDeclaration,
+  isExternalModuleReference,
+  isImportDeclaration,
+  isImportEqualsDeclaration,
+  isNoSubstitutionTemplateLiteral,
+  isStringLiteral,
+  SyntaxKind,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import {
+  SymbolFlags,
+  type NodeHandle,
+  type Symbol as TSSymbol,
+} from "@typescript/native/unstable/sync";
+import type { AliasChains } from "./alias-chain.ts";
+import { resolvedTargets } from "./calls.ts";
+import type { DeclarationEntry } from "./config.ts";
+import type { Inventory } from "./inventory.ts";
+import { nameComponent } from "./ref.ts";
+import type { ProjectView } from "./session.ts";
+
+/** The meanings a name of the global scope is looked up under: any of them. */
+const ANY_MEANING: SymbolFlags = SymbolFlags.Value | SymbolFlags.Type | SymbolFlags.Namespace;
+
+/** The suffix that marks a static member at the end of a path. */
+const STATIC = ":static";
+
+/**
+ * One entry and the declaration it names in one project. Both sets are empty where
+ * the entry names no declaration there, which is how an entry that names nothing is
+ * told from one that names something no call reaches.
+ */
+export interface ResolvedEntry {
+  readonly entry: DeclarationEntry;
+  /** The declarations a module or global entry resolves to, each as its handle's key. */
+  readonly handles: ReadonlySet<string>;
+  /** The inventory's identifier of the declaration a symbol entry names. */
+  readonly ids: ReadonlySet<string>;
+}
+
+/** The key one declaration handle is compared by: its file and its index in that file. */
+function handleKey(handle: NodeHandle): string {
+  return `${handle.path}:${String(handle.index)}`;
+}
+
+/**
+ * The components of one declaration path and whether its last one is a static member.
+ * A path is split at the dots outside a quoted or a bracketed component, and each
+ * component keeps the spelling a reference gives it.
+ */
+function componentsOf(path: string): { readonly components: string[]; readonly static: boolean } {
+  const isStatic = path.endsWith(STATIC);
+  const body = isStatic ? path.slice(0, -STATIC.length) : path;
+  const components: string[] = [];
+  let current = "";
+  let closing = "";
+  for (let at = 0; at < body.length; at += 1) {
+    const ch = body.charAt(at);
+    if (closing === "'" && ch === "\\") {
+      current += ch + body.charAt(at + 1);
+      at += 1;
+      continue;
+    }
+    if (closing !== "") {
+      closing = ch === closing ? "" : closing;
+    } else if (ch === "'" || ch === "[") {
+      closing = ch === "'" ? "'" : "]";
+    } else if (ch === ".") {
+      components.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  components.push(current);
+  return { components, static: isStatic };
+}
+
+/** What a symbol is once every alias it stands for is followed. */
+function unaliased<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): TSSymbol | undefined {
+  if ((symbol.flags & SymbolFlags.Alias) === 0) {
+    return symbol;
+  }
+  const target = project.checker.getAliasedSymbol(symbol);
+  return target.declarations.length === 0 ? undefined : target;
+}
+
+/** Whether one symbol is a member a class declares: a property, a method or an accessor. */
+function isClassMember(symbol: TSSymbol): boolean {
+  return (symbol.flags & SymbolFlags.ClassMember) !== 0;
+}
+
+/**
+ * The members of one container a path component may name. A class keeps its static
+ * members among its exports beside what a merged namespace exports, so a component
+ * with the static suffix names one of the first and a component without it names an
+ * instance member or one of the second.
+ */
+function candidatesOf(container: TSSymbol, isStatic: boolean): readonly TSSymbol[] {
+  const exported = [...container.getExports().values()];
+  if (isStatic) {
+    return exported.filter(isClassMember);
+  }
+  const isClass = (container.flags & SymbolFlags.Class) !== 0;
+  return [
+    ...container.getMembers().values(),
+    ...exported.filter((member) => !isClass || !isClassMember(member)),
+  ];
+}
+
+/** The member of one container a path component spells, followed through any alias. */
+function memberOf<Brand>(
+  project: ProjectView<Brand>,
+  container: TSSymbol,
+  component: string,
+  isStatic: boolean,
+): TSSymbol | undefined {
+  const member = candidatesOf(container, isStatic).find(
+    (candidate) => nameComponent(candidate.name) === component,
+  );
+  return member === undefined ? undefined : unaliased(project, member);
+}
+
+/** The declaration a path names from one starting symbol, component by component. */
+function walkPath<Brand>(
+  project: ProjectView<Brand>,
+  start: TSSymbol | undefined,
+  rest: readonly string[],
+  isStatic: boolean,
+): TSSymbol | undefined {
+  let at = start;
+  rest.forEach((component, index) => {
+    if (at !== undefined) {
+      at = memberOf(project, at, component, isStatic && index === rest.length - 1);
+    }
+  });
+  return at;
+}
+
+/** Whether one node is literal text: a string literal or a template with no substitution. */
+function isLiteralText(node: Node | undefined): node is Node & { readonly text: string } {
+  return node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node));
+}
+
+/** The module specifier one node writes, for each form that imports or re-exports a module. */
+function specifierOf(node: Node): Node | undefined {
+  if (isImportDeclaration(node) || isExportDeclaration(node)) {
+    return node.moduleSpecifier;
+  }
+  if (isImportEqualsDeclaration(node) && isExternalModuleReference(node.moduleReference)) {
+    return node.moduleReference.expression;
+  }
+  if (isCallExpression(node) && node.expression.kind === SyntaxKind.ImportKeyword) {
+    return node.arguments[0];
+  }
+  return undefined;
+}
+
+/**
+ * The module each specifier the entries name resolves to in one project, read from a
+ * specifier the project's own files write, so the module is the one the target's own
+ * import resolves. A specifier no file writes resolves to no module.
+ */
+function modulesNamed<Brand>(
+  project: ProjectView<Brand>,
+  specifiers: ReadonlySet<string>,
+): ReadonlyMap<string, TSSymbol> {
+  const written = new Map<string, Node>();
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      const specifier = specifierOf(node);
+      if (
+        isLiteralText(specifier) &&
+        specifiers.has(specifier.text) &&
+        !written.has(specifier.text)
+      ) {
+        written.set(specifier.text, specifier);
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  const specified = [...written];
+  const symbols = project.symbolsAt(specified.map(([, node]) => project.handle(node)));
+  const modules = new Map<string, TSSymbol>();
+  specified.forEach(([name], index) => {
+    const symbol = symbols[index];
+    if (symbol !== undefined) {
+      modules.set(name, symbol);
+    }
+  });
+  return modules;
+}
+
+/**
+ * The declaration each entry names in one project. A symbol entry names the
+ * inventory's declaration whose reference it spells exactly; a module entry names the
+ * declaration its path reaches from the exports of the module its specifier resolves
+ * to; a global entry names the declaration its path reaches from the global scope.
+ * Every alias along a path is followed to the declaration it stands for.
+ */
+export function resolveEntries<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  entries: readonly DeclarationEntry[],
+): readonly ResolvedEntry[] {
+  if (entries.length === 0) {
+    return [];
+  }
+  const byRef = new Map(held.symbols.map((symbol) => [symbol.ref, symbol.id]));
+  const modules = modulesNamed(
+    project,
+    new Set(entries.flatMap((entry) => (entry.shape === "module" ? [entry.module] : []))),
+  );
+  return entries.map((entry) => {
+    if (entry.shape === "symbol") {
+      const id = byRef.get(entry.symbol);
+      return { entry, handles: new Set<string>(), ids: new Set(id === undefined ? [] : [id]) };
+    }
+    const { components, static: isStatic } = componentsOf(
+      entry.shape === "module" ? entry.name : entry.global,
+    );
+    const [first = "", ...rest] = components;
+    let start: TSSymbol | undefined;
+    if (isStatic && rest.length === 0) {
+      // Only a member is static, and a path of one component names no member.
+      start = undefined;
+    } else if (entry.shape === "module") {
+      const module = modules.get(entry.module);
+      start = module === undefined ? undefined : memberOf(project, module, first, false);
+    } else if (nameComponent(first) === first) {
+      const global = project.checker.resolveName(first, ANY_MEANING, undefined, false);
+      start = global === undefined ? undefined : unaliased(project, global);
+    }
+    const declared = walkPath(project, start, rest, isStatic);
+    return {
+      entry,
+      handles: new Set(declared?.declarations.map(handleKey) ?? []),
+      ids: new Set<string>(),
+    };
+  });
+}
+
+/**
+ * Whether one symbol is the declaration a resolved entry names: it shares one of the
+ * entry's declarations, or, for an entry naming a declaration of the program, it is
+ * declared there. `chains` reads the symbol's declarations against the inventory the
+ * entries were resolved with.
+ */
+export function names(resolved: ResolvedEntry, symbol: TSSymbol, chains: AliasChains): boolean {
+  if (symbol.declarations.some((handle) => resolved.handles.has(handleKey(handle)))) {
+    return true;
+  }
+  return resolved.ids.size > 0 && chains.declarationsOf(symbol).some((id) => resolved.ids.has(id));
+}
+
+/** Whether a resolved entry names a declaration, so that some symbol can be it. */
+export function namesADeclaration(resolved: ResolvedEntry): boolean {
+  return resolved.handles.size > 0 || resolved.ids.size > 0;
+}
+
+/**
+ * The entries each of a batch of name nodes is: what the node resolves to, every alias
+ * followed, is the declaration each of them names. A node that is none is absent.
+ */
+export function entriesAt<Brand>(
+  project: ProjectView<Brand>,
+  chains: AliasChains,
+  nodes: readonly Node[],
+  resolved: readonly ResolvedEntry[],
+): ReadonlyMap<Node, readonly ResolvedEntry[]> {
+  const naming = resolved.filter(namesADeclaration);
+  const found = new Map<Node, readonly ResolvedEntry[]>();
+  if (naming.length === 0) {
+    return found;
+  }
+  for (const [node, target] of resolvedTargets(project, nodes)) {
+    const entries = naming.filter((entry) => names(entry, target, chains));
+    if (entries.length > 0) {
+      found.set(node, entries);
+    }
+  }
+  return found;
+}
+
+/**
+ * How one entry is spelled in a record's detail: its path, or for a declaration of the
+ * program the display name the inventory gives it.
+ */
+export function spelledEntry(entry: DeclarationEntry, held: Inventory): string {
+  switch (entry.shape) {
+    case "symbol":
+      return held.symbols.find((symbol) => symbol.ref === entry.symbol)?.name ?? entry.symbol;
+    case "module":
+      return entry.name;
+    case "global":
+      return entry.global;
+  }
+}

package/src/decorator.ts

@@ -11,12 +11,8 @@
  * the inventory holds for the class, static members included.
  */
 
-import {
-  isCallExpression,
-  isDecorator,
-  type Decorator,
-  type Node,
-} from "@typescript/native/unstable/ast";
+import type { Node } from "@typescript/native/unstable/ast";
+import { decoratorsOf, spelledDecorator } from "./calls.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";
 import { nodeKey, type InventorySymbol, type SymbolKind } from "./inventory.ts";
 import { renderPosition } from "./position.ts";
@@ -24,13 +20,6 @@ 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"]);
 
-/** How one decorator is spelled in a record: its expression, without a call's arguments. */
-function spelled(decorator: Decorator): string {
-  const expression = decorator.expression;
-  const named = isCallExpression(expression) ? expression.expression : expression;
-  return `@${named.getText().replace(/\s+/gu, "")}`;
-}
-
 /**
  * The decorator detector: each decorated member, and each member of a decorated
  * class, recorded at the decorator.
@@ -56,9 +45,8 @@ export function decorator<Brand>(input: DetectorInput<Brand>): readonly Evidence
       const id = held.declarations.get(nodeKey(file, node));
       const symbol = id === undefined ? undefined : byId.get(id);
       if (symbol !== undefined && DECORATED.has(symbol.kind)) {
-        const modifiers = (node as { readonly modifiers?: readonly Node[] }).modifiers ?? [];
-        for (const attached of modifiers.filter(isDecorator)) {
-          const detail = `decorated by ${spelled(attached)}`;
+        for (const attached of decoratorsOf(node)) {
+          const detail = `decorated by ${spelledDecorator(attached)}`;
           const site = renderPosition(file, targetRoot, attached.getStart());
           const reached = symbol.kind === "class" ? (membersOf.get(symbol.id) ?? []) : [symbol];
           for (const member of reached) {

package/src/exempt.ts

@@ -7,7 +7,7 @@
  * hands it the table of the classes it has.
  */
 
-import type { Config } from "./config.ts";
+import type { Config, TSSection } from "./config.ts";
 import { ConfigError } from "./config.ts";
 import {
   EXEMPTION_CLASSES,
@@ -41,6 +41,10 @@ export interface DetectorInput<Brand> {
   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: TSSection;
+  /** The absolute path of each declared consumer, whose modules are part of the analysis. */
+  readonly consumers: readonly string[];
 }
 
 /**

package/src/findings/dependencies-and-module-machinery.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
+export const dependenciesAndModuleMachinery: Emitter = () => [];

package/src/findings/emitter.ts

@@ -0,0 +1,19 @@
+import type { RunSweep } from "../analysis.ts";
+import type { Config } from "../config.ts";
+import type { Finding } from "../finding.ts";
+
+/** What every emitter reads: the configuration the run resolved and the run's sweep. */
+export interface EmitterInput {
+  readonly config: Config;
+  /** The production sweep a report is built from, beside the matrix it judged. */
+  readonly swept: RunSweep;
+}
+
+/**
+ * One kind family's rule over one run: the findings of the codes in its family's range
+ * of the Contract's code space, in no particular order.
+ */
+export type Emitter = (input: EmitterInput) => readonly Finding[];
+
+/** The emitter of each kind family, by the family's name in the Contract, in code order. */
+export type Emitters = ReadonlyMap<string, Emitter>;

package/src/findings/emitters.ts

@@ -0,0 +1,21 @@
+import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
+import type { Emitter, Emitters } from "./emitter.ts";
+import { interfaces } from "./interfaces.ts";
+import { intraFunction } from "./intra-function.ts";
+import { nonCodeArtifacts } from "./non-code-artifacts.ts";
+import { readsAndWrites } from "./reads-and-writes.ts";
+import { selfCheck } from "./self-check.ts";
+import { unusedDeclarations } from "./unused-declarations.ts";
+import { visibilityNarrowing } from "./visibility-narrowing.ts";
+
+/** Every kind family this analyzer reports, each by its emitter, in code order. */
+export const EMITTERS: Emitters = new Map<string, Emitter>([
+  ["unused-declarations", unusedDeclarations],
+  ["visibility-narrowing", visibilityNarrowing],
+  ["interfaces", interfaces],
+  ["reads-and-writes", readsAndWrites],
+  ["non-code-artifacts", nonCodeArtifacts],
+  ["dependencies-and-module-machinery", dependenciesAndModuleMachinery],
+  ["self-check", selfCheck],
+  ["intra-function", intraFunction],
+]);

package/src/findings/interfaces.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the interfaces family, `DS1200` to `DS1299`. */
+export const interfaces: Emitter = () => [];

package/src/findings/intra-function.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the intra-function family, `DS1800` to `DS1899`. */
+export const intraFunction: Emitter = () => [];

package/src/findings/non-code-artifacts.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the non-code-artifacts family, `DS1500` to `DS1599`. */
+export const nonCodeArtifacts: Emitter = () => [];

package/src/findings/reads-and-writes.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the reads-and-writes family, `DS1300` to `DS1399`. */
+export const readsAndWrites: Emitter = () => [];

package/src/findings/self-check.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the self-check family, `DS1700` to `DS1799`. */
+export const selfCheck: Emitter = () => [];

package/src/findings/unused-declarations.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+export const unusedDeclarations: Emitter = () => [];

package/src/findings/visibility-narrowing.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+export const visibilityNarrowing: Emitter = () => [];