@cplieger/deadset-ts 3.1.0 → 3.3.0

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;
+}

package/src/version.ts

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "2.2.0";
+export const CONTRACT_VERSION = "3.0.0";