@cplieger/deadset-ts 3.2.0 → 3.3.0

package/src/reflective-lookup.ts

@@ -0,0 +1,127 @@
+/**
+ * The reflective-lookup class: a member is held back, at the lowest confidence, when
+ * a string literal equal to its name is the key of an element access or the property
+ * key of a `Reflect.get`, `Reflect.set` or `Reflect.has` call, because the member is
+ * then read by a name the program computes nowhere the reference pass can follow.
+ *
+ * The evidence is a string beside a lookup rather than a type relation, so the
+ * string reaches every member of that name on any type, static members included,
+ * and every record names the string's own position. A key that is not literal text
+ * holds nothing back: a computed name is the case no exact rule serves. `Reflect` is
+ * the global one only: a local declaration of that name is a different object.
+ */
+
+import {
+  isCallExpression,
+  isElementAccessExpression,
+  isIdentifier,
+  isNoSubstitutionTemplateLiteral,
+  isPropertyAccessExpression,
+  isStringLiteral,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import { memberNames } from "./member-names.ts";
+import { renderPosition } from "./position.ts";
+
+/** The `Reflect` methods whose second argument is a property key. */
+const REFLECT_KEYED: ReadonlySet<string> = new Set(["get", "set", "has"]);
+
+/** One literal key at one lookup, and how the lookup is spelled in a record. */
+interface Lookup {
+  readonly key: Node;
+  readonly name: string;
+  readonly callee: string;
+  /** The `Reflect` the call names, where the lookup is a `Reflect` call. */
+  readonly reflect: Node | undefined;
+}
+
+/** The text one key denotes, where it is literal text. */
+function literalText(node: Node | undefined): string | undefined {
+  if (node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))) {
+    return node.text;
+  }
+  return undefined;
+}
+
+/** Every lookup one file writes with a literal key, in source order. */
+function lookupsOf(file: SourceFile): readonly Lookup[] {
+  const found: Lookup[] = [];
+  const visit = (node: Node): void => {
+    if (isElementAccessExpression(node)) {
+      const name = literalText(node.argumentExpression);
+      if (name !== undefined) {
+        found.push({
+          key: node.argumentExpression,
+          name,
+          callee: `[${JSON.stringify(name)}]`,
+          reflect: undefined,
+        });
+      }
+    } else if (isCallExpression(node) && isPropertyAccessExpression(node.expression)) {
+      const target = node.expression.expression;
+      const method = node.expression.name;
+      const key = node.arguments[1];
+      const name = literalText(key);
+      if (
+        isIdentifier(target) &&
+        target.text === "Reflect" &&
+        isIdentifier(method) &&
+        REFLECT_KEYED.has(method.text) &&
+        key !== undefined &&
+        name !== undefined
+      ) {
+        found.push({ key, name, callee: `Reflect.${method.text}`, reflect: target });
+      }
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return found;
+}
+
+/**
+ * The reflective-lookup detector: every member whose name a literal key of a lookup
+ * spells, recorded at the key.
+ */
+export function reflectiveLookup<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { project, held, targetRoot } = input;
+  const files = project.ownSourceFiles();
+  const lookups = files.flatMap(lookupsOf);
+  if (lookups.length === 0) {
+    return [];
+  }
+
+  // Whether each written `Reflect` is the global one, asked in one batch: a
+  // declaration of that name in one of the project's own files shadows it.
+  const ownFiles = new Set(files.map((file) => file.fileName));
+  const reflects = lookups.flatMap((lookup) =>
+    lookup.reflect === undefined ? [] : [lookup.reflect],
+  );
+  const global = new Set<Node>();
+  if (reflects.length > 0) {
+    project.symbolsAt(reflects.map((node) => project.handle(node))).forEach((symbol, index) => {
+      const node = reflects[index];
+      const declaredHere = symbol?.declarations.some((declaration) =>
+        ownFiles.has(declaration.path),
+      );
+      if (node !== undefined && declaredHere === false) {
+        global.add(node);
+      }
+    });
+  }
+
+  const members = memberNames(files, held);
+  const found: Evidence[] = [];
+  for (const lookup of lookups) {
+    if (lookup.reflect !== undefined && !global.has(lookup.reflect)) {
+      continue;
+    }
+    const site = renderPosition(lookup.key.getSourceFile(), targetRoot, lookup.key.getStart());
+    for (const member of members.get(lookup.name) ?? []) {
+      found.push({ id: member.id, detail: `looked up by ${lookup.callee}`, site });
+    }
+  }
+  return found;
+}

package/src/template-field.ts

@@ -0,0 +1,214 @@
+/**
+ * The template-field class: a member is held back, at the lowest confidence, when a
+ * template under a configured template directory writes its name inside an action,
+ * because a template engine reads the member by that name at run time.
+ *
+ * Every file under a configured directory is a template. An action runs from an
+ * opening delimiter to the first closing one after it, at the pair
+ * `analysis.template_delimiters` sets, `{{` and `}}` by default, and each identifier
+ * it writes outside a quoted string is a name it reads: `{{ user.name }}` names `user`
+ * and `name`. A file holding an unclosed action names nothing. A name reaches the
+ * instance members of classes and the members of interfaces and object types, on any
+ * type, because nothing ties the name to a type.
+ */
+
+import { ConfigError, type Analysis, type TemplateDelimiters } from "./config.ts";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import type { Host } from "./host.ts";
+import type { SymbolKind } from "./inventory.ts";
+import { memberNames } from "./member-names.ts";
+import { isAbsolutePath, joinPath, normalizePath } from "./paths.ts";
+import type { Position } from "./position.ts";
+
+/** One template, by its path below the target root. */
+export interface TemplateFile {
+  readonly path: string;
+  readonly text: string;
+}
+
+/** The templates one run scans, and the pair their actions are written with. */
+export interface Templates {
+  readonly delimiters: TemplateDelimiters;
+  readonly files: readonly TemplateFile[];
+}
+
+/** The kinds of declaration an action can name. */
+const READ_BY_A_TEMPLATE: ReadonlySet<SymbolKind> = new Set([
+  "method",
+  "class-member",
+  "interface-method",
+  "type-member",
+]);
+
+/** One identifier, as the grammar of the analyzed language spells one. */
+const IDENTIFIER = /[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*/uy;
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/**
+ * Every template under the configured directories, read once for the run, in path
+ * order and each file once. A directory is named relative to the target root, and
+ * one the target does not hold refuses the run as a usage error: the class would
+ * scan nothing, so a name that no longer matches the tree would silently switch the
+ * exemption it was configured for off. A symbolic link to a directory is not
+ * followed.
+ */
+export function readTemplates(host: Host, targetRoot: string, analysis: Analysis): Templates {
+  const files = new Map<string, string>();
+  const read = (dir: string): void => {
+    const entries = [...host.readDirectory(joinPath(targetRoot, dir))].sort((a, b) =>
+      compare(a.name, b.name),
+    );
+    for (const entry of entries) {
+      const path = joinPath(dir, entry.name);
+      if (entry.directory) {
+        read(path);
+        continue;
+      }
+      const absolute = joinPath(targetRoot, path);
+      if (!files.has(path) && host.kindOf(absolute) === "file") {
+        files.set(path, host.readFile(absolute));
+      }
+    }
+  };
+  for (const configured of analysis.templateDirs) {
+    const dir = normalizePath(configured);
+    if (
+      isAbsolutePath(dir) ||
+      dir === ".." ||
+      dir.startsWith("../") ||
+      host.kindOf(joinPath(targetRoot, dir)) !== "directory"
+    ) {
+      throw new ConfigError(
+        "malformed",
+        "analysis.template_dirs",
+        `analysis.template_dirs: ${JSON.stringify(configured)} is not a directory below the target root`,
+      );
+    }
+    read(dir);
+  }
+  return {
+    delimiters: analysis.templateDelimiters,
+    files: [...files]
+      .map(([path, text]) => ({ path, text }))
+      .sort((a, b) => compare(a.path, b.path)),
+  };
+}
+
+/** One identifier an action writes, where it is written, and the action that writes it. */
+interface Named {
+  readonly name: string;
+  readonly offset: number;
+  readonly action: string;
+}
+
+/** The end of the quoted string that opens at `from`, past its closing quote. */
+function stringEnd(text: string, from: number): number {
+  const quote = text[from];
+  let at = from + 1;
+  while (at < text.length && text[at] !== quote) {
+    at += text[at] === "\\" ? 2 : 1;
+  }
+  return at + 1;
+}
+
+/** The identifiers one action's inner text writes outside a quoted string, with their offsets in it. */
+function identifiersOf(inner: string): readonly { name: string; offset: number }[] {
+  const found: { name: string; offset: number }[] = [];
+  let at = 0;
+  while (at < inner.length) {
+    const char = inner[at] ?? "";
+    if (char === '"' || char === "'" || char === "`") {
+      at = stringEnd(inner, at);
+      continue;
+    }
+    if (/[0-9]/u.test(char)) {
+      // A number's letters are part of the number: `1e3` names nothing.
+      while (at < inner.length && /[0-9A-Za-z_.]/u.test(inner[at] ?? "")) {
+        at += 1;
+      }
+      continue;
+    }
+    IDENTIFIER.lastIndex = at;
+    const match = IDENTIFIER.exec(inner);
+    if (match !== null) {
+      found.push({ name: match[0], offset: at });
+      at += match[0].length;
+      continue;
+    }
+    at += 1;
+  }
+  return found;
+}
+
+/**
+ * Every identifier one template's actions write, in the order the file writes them,
+ * or none where an action is not closed.
+ */
+function namesOf(text: string, delimiters: TemplateDelimiters): readonly Named[] {
+  const found: Named[] = [];
+  let from = 0;
+  for (;;) {
+    const open = text.indexOf(delimiters.left, from);
+    if (open < 0) {
+      return found;
+    }
+    const start = open + delimiters.left.length;
+    const close = text.indexOf(delimiters.right, start);
+    if (close < 0) {
+      return [];
+    }
+    const inner = text.slice(start, close);
+    const action = `${delimiters.left}${inner.trim().replace(/\s+/gu, " ")}${delimiters.right}`;
+    for (const { name, offset } of identifiersOf(inner)) {
+      found.push({ name, offset: start + offset, action });
+    }
+    from = close + delimiters.right.length;
+  }
+}
+
+/** Where one offset of a template is, its column counted in UTF-16 code units. */
+function positionIn(file: TemplateFile, offset: number): Position {
+  const before = file.text.slice(0, offset);
+  const lineStart = before.lastIndexOf("\n") + 1;
+  return {
+    path: file.path,
+    line: before.split("\n").length,
+    column: offset - lineStart + 1,
+  };
+}
+
+/**
+ * The template-field detector: every instance member of a class and every member of
+ * an interface or an object type whose name an action of a configured template
+ * writes, recorded at the identifier.
+ */
+export function templateField<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { templates } = input;
+  if (templates.files.length === 0) {
+    return [];
+  }
+  const members = memberNames(input.project.ownSourceFiles(), input.held);
+  const found: Evidence[] = [];
+  for (const file of templates.files) {
+    for (const named of namesOf(file.text, templates.delimiters)) {
+      for (const member of members.get(named.name) ?? []) {
+        if (!READ_BY_A_TEMPLATE.has(member.kind) || member.static) {
+          continue;
+        }
+        found.push({
+          id: member.id,
+          detail: `named by ${named.action}`,
+          site: positionIn(file, named.offset),
+        });
+      }
+    }
+  }
+  return found;
+}