@cplieger/deadset-ts 2.2.1 → 2.3.0

package/src/entry-points.ts

@@ -0,0 +1,496 @@
+/**
+ * The files a tool or the platform enters without any import naming them: the
+ * configuration files the test runner, the linter, the mutation tester and the
+ * browser-test runner load by their file name, the test files the runner executes,
+ * and a worker a call addresses by a string literal.
+ *
+ * Each rule is read from the program and nothing else: a file name the tool
+ * itself looks for, a literal written in a configuration file, or a literal
+ * argument of a call the checker resolves to the platform's own declaration. A
+ * value that is not a literal is not evaluated and not guessed, so a file it would
+ * have named is entered by nothing here.
+ */
+
+import {
+  isArrayLiteralExpression,
+  isAsExpression,
+  isCallExpression,
+  isExportAssignment,
+  isIdentifier,
+  isMetaProperty,
+  isNewExpression,
+  isNoSubstitutionTemplateLiteral,
+  isObjectLiteralExpression,
+  isParenthesizedExpression,
+  isPropertyAccessExpression,
+  isPropertyAssignment,
+  isSatisfiesExpression,
+  isStringLiteral,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { globExpression } from "./glob.ts";
+import { dirnamePath, relativePath, resolvePath } from "./paths.ts";
+import type { ProjectView } from "./session.ts";
+import type { SourceFiles } from "./source-files.ts";
+
+/** Which rule entered a file. */
+export type EntryRule =
+  /** The test runner: its configuration, its setup files and the test files. */
+  | "test-runner"
+  /** The linter's flat configuration. */
+  | "lint-configuration"
+  /** The mutation tester's configuration, and the test-runner configuration it names. */
+  | "mutation-testing"
+  /** The browser-test runner's configuration and the test files below its test directory. */
+  | "browser-tests"
+  /** A worker or service worker a call addresses by a string literal. */
+  | "worker";
+
+/** One file a rule enters. */
+export interface EntryPoint {
+  readonly file: SourceFile;
+  readonly rule: EntryRule;
+  /**
+   * What named the file: the file-name convention the tool looks for, the test-file
+   * pattern that classified it, or the literal a configuration or a call writes.
+   */
+  readonly source: string;
+  /**
+   * Whether what the file exports is read too. A tool loading a configuration reads
+   * its default export; a runtime executing a test file or a worker runs its top
+   * level and names none of its exports.
+   */
+  readonly exports: boolean;
+}
+
+/** One file-name convention: the stems a tool looks for, under each extension it loads. */
+interface Convention {
+  readonly rule: EntryRule;
+  readonly stems: readonly string[];
+  readonly extensions: readonly string[];
+  /** Whether the file is a test-runner configuration whose setup files are read. */
+  readonly testRunner: boolean;
+}
+
+/** The extensions the test runner and the browser-test runner load a configuration from. */
+const MODULE_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"] as const;
+
+/** The extensions the linter's flat configuration and the mutation tester's are loaded from. */
+const SCRIPT_EXTENSIONS = ["js", "mjs", "cjs"] as const;
+
+const CONVENTIONS: readonly Convention[] = [
+  {
+    rule: "test-runner",
+    stems: ["vitest.config", "vitest.workspace", "vitest.projects"],
+    extensions: MODULE_EXTENSIONS,
+    testRunner: true,
+  },
+  {
+    rule: "lint-configuration",
+    stems: ["eslint.config"],
+    extensions: MODULE_EXTENSIONS,
+    testRunner: false,
+  },
+  {
+    rule: "mutation-testing",
+    stems: ["stryker.config", "stryker.conf", ".stryker.config", ".stryker.conf"],
+    extensions: SCRIPT_EXTENSIONS,
+    testRunner: false,
+  },
+  {
+    rule: "mutation-testing",
+    stems: ["vitest.stryker.config"],
+    extensions: MODULE_EXTENSIONS,
+    testRunner: true,
+  },
+  {
+    rule: "browser-tests",
+    stems: ["playwright.config"],
+    extensions: MODULE_EXTENSIONS,
+    testRunner: false,
+  },
+];
+
+/** The browser-test runner's own test-file pattern, which holds where a configuration names none. */
+const BROWSER_TEST_MATCH = "**/*.{spec,test}.{js,ts,jsx,tsx,cjs,cts,cjsx,ctsx,mjs,mts,mjsx,mtsx}";
+
+/** The members of a test-runner configuration's `test` object that name setup files. */
+const SETUP_MEMBERS = ["setupFiles", "globalSetup"] as const;
+
+/** A member that moves the directory every path of a test-runner configuration is read from. */
+const ROOT_MEMBER = "root";
+
+/** The prefixes a literal is relative with, in a module specifier and a URL reference alike. */
+const RELATIVE_PREFIXES = ["./", "../"] as const;
+
+/** The constructors whose first argument addresses a worker script. */
+const WORKER_CONSTRUCTORS: ReadonlySet<string> = new Set(["Worker", "SharedWorker"]);
+
+/** The file's name, the last segment of its path. */
+function basename(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+
+/** The convention one file name is, with the spelling a root reports it by. */
+function conventionOf(
+  name: string,
+): { readonly convention: Convention; readonly spelled: string } | undefined {
+  for (const convention of CONVENTIONS) {
+    for (const stem of convention.stems) {
+      if (convention.extensions.some((ext) => name === `${stem}.${ext}`)) {
+        return { convention, spelled: `${stem}.*` };
+      }
+    }
+  }
+  return undefined;
+}
+
+/** The text a string literal or a template with no substitution denotes. */
+function literalOf(node: Node | undefined): string | undefined {
+  if (node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))) {
+    return node.text;
+  }
+  return undefined;
+}
+
+/** The expression a wrapper that changes no value holds: parentheses and type assertions. */
+function unwrapped(node: Node): Node {
+  let at = node;
+  while (isParenthesizedExpression(at) || isAsExpression(at) || isSatisfiesExpression(at)) {
+    at = at.expression;
+  }
+  return at;
+}
+
+/**
+ * The object literals one configuration file's default export is written as: the
+ * literal itself, or each literal argument of the call it is, at any depth of calls.
+ * A default export written as anything else, a name or a computation, yields none,
+ * because its value is not in the file's text.
+ */
+function configObjects(file: SourceFile): readonly Node[] {
+  const found: Node[] = [];
+  const collect = (node: Node): void => {
+    const at = unwrapped(node);
+    if (isObjectLiteralExpression(at)) {
+      found.push(at);
+      return;
+    }
+    if (isCallExpression(at)) {
+      for (const argument of at.arguments) {
+        collect(argument);
+      }
+    }
+  };
+  for (const statement of file.statements) {
+    if (isExportAssignment(statement) && !statement.isExportEquals) {
+      collect(statement.expression);
+    }
+  }
+  return found;
+}
+
+/**
+ * The value one member of an object literal is written with, when it is written as
+ * `name: value`, and undefined where the literal writes no such member.
+ */
+function memberOf(object: Node, name: string): Node | undefined {
+  if (!isObjectLiteralExpression(object)) {
+    return undefined;
+  }
+  for (const property of object.properties) {
+    if (
+      isPropertyAssignment(property) &&
+      isIdentifier(property.name) &&
+      property.name.text === name
+    ) {
+      return property.initializer;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The strings one member holds, when it is written as a literal or an array of
+ * literals. `undefined` is a value the text does not state.
+ */
+function literalsOf(value: Node): readonly string[] | undefined {
+  const at = unwrapped(value);
+  const single = literalOf(at);
+  if (single !== undefined) {
+    return [single];
+  }
+  if (!isArrayLiteralExpression(at)) {
+    return undefined;
+  }
+  const found: string[] = [];
+  for (const element of at.elements) {
+    const text = literalOf(unwrapped(element));
+    if (text === undefined) {
+      return undefined;
+    }
+    found.push(text);
+  }
+  return found;
+}
+
+/** Whether a literal is relative in the sense a module specifier and a URL reference share. */
+function isRelative(text: string): boolean {
+  return RELATIVE_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+
+/** A URL reference with its query and its fragment removed, which name no part of the file. */
+function pathPart(text: string): string {
+  const cut = text.search(/[?#]/u);
+  return cut < 0 ? text : text.slice(0, cut);
+}
+
+/** The own files one relative literal names, read against a directory. */
+function filesNamed(files: SourceFiles, dir: string, text: string): readonly SourceFile[] {
+  if (!isRelative(text)) {
+    return [];
+  }
+  return files.named(resolvePath(dir, pathPart(text)));
+}
+
+/**
+ * The setup files one test-runner configuration names: every literal under
+ * `test.setupFiles` and `test.globalSetup`, read against the configuration's own
+ * directory. A configuration that moves its root names them against a directory its
+ * text may not state, so none is read from it.
+ */
+function setupFilesOf(file: SourceFile, files: SourceFiles): readonly EntryPoint[] {
+  const objects = configObjects(file);
+  const tests = objects
+    .map((object) => memberOf(object, "test"))
+    .filter((value): value is Node => value !== undefined)
+    .map(unwrapped);
+  if ([...objects, ...tests].some((object) => memberOf(object, ROOT_MEMBER) !== undefined)) {
+    return [];
+  }
+  const dir = dirnamePath(file.fileName);
+  const found: EntryPoint[] = [];
+  for (const test of tests) {
+    for (const name of SETUP_MEMBERS) {
+      const value = memberOf(test, name);
+      for (const text of value === undefined ? [] : (literalsOf(value) ?? [])) {
+        for (const named of filesNamed(files, dir, text)) {
+          found.push({ file: named, rule: "test-runner", source: text, exports: false });
+        }
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * The test files one browser-test configuration names: every own file below its
+ * test directory that its test-file pattern matches. The directory is the literal
+ * `testDir` reads against the configuration's directory, or that directory where no
+ * object of the configuration writes one; the pattern is the literal `testMatch`, or
+ * the runner's own where none is written. A member whose value is not a literal
+ * leaves the set unknown, and an unknown set enters nothing.
+ */
+function browserTestsOf(file: SourceFile, files: SourceFiles): readonly EntryPoint[] {
+  const objects = configObjects(file);
+  if (objects.length === 0) {
+    return [];
+  }
+  let testDir: string | undefined = ".";
+  let patterns: readonly string[] | undefined = [BROWSER_TEST_MATCH];
+  for (const object of objects) {
+    const dir = memberOf(object, "testDir");
+    if (dir !== undefined) {
+      testDir = literalOf(unwrapped(dir));
+    }
+    const match = memberOf(object, "testMatch");
+    if (match !== undefined) {
+      patterns = literalsOf(match);
+    }
+  }
+  if (testDir === undefined || patterns === undefined) {
+    return [];
+  }
+  const under = resolvePath(dirnamePath(file.fileName), testDir);
+  const found: EntryPoint[] = [];
+  for (const pattern of patterns) {
+    const expression = globExpression(pattern);
+    for (const candidate of files.byName.values()) {
+      const below = relativePath(under, candidate.fileName);
+      if (below !== undefined && expression.test(below)) {
+        found.push({ file: candidate, rule: "browser-tests", source: pattern, exports: false });
+      }
+    }
+  }
+  return found;
+}
+
+/** One call that addresses a worker, with the names the checker must resolve to the platform. */
+interface WorkerSite {
+  readonly literal: string;
+  readonly platformNames: readonly Node[];
+}
+
+/**
+ * The address one worker argument writes: a relative literal, or a `URL` built from
+ * a literal against `import.meta.url`. Any other argument is computed and addresses
+ * nothing the text states.
+ */
+function workerAddress(
+  argument: Node | undefined,
+): { readonly literal: string; readonly names: readonly Node[] } | undefined {
+  if (argument === undefined) {
+    return undefined;
+  }
+  const at = unwrapped(argument);
+  const literal = literalOf(at);
+  if (literal !== undefined) {
+    return { literal, names: [] };
+  }
+  if (!isNewExpression(at) || !isIdentifier(at.expression) || at.expression.text !== "URL") {
+    return undefined;
+  }
+  const [reference, base] = at.arguments ?? [];
+  const text = literalOf(reference === undefined ? undefined : unwrapped(reference));
+  if (text === undefined || base === undefined) {
+    return undefined;
+  }
+  const meta = unwrapped(base);
+  if (
+    !isPropertyAccessExpression(meta) ||
+    !isMetaProperty(meta.expression) ||
+    !isIdentifier(meta.name) ||
+    meta.name.text !== "url"
+  ) {
+    return undefined;
+  }
+  return { literal: text, names: [at.expression] };
+}
+
+/**
+ * Every call one file writes that addresses a worker: `new Worker(...)`,
+ * `new SharedWorker(...)` and `navigator.serviceWorker.register(...)`, each with an
+ * address its text states.
+ */
+function workerSitesOf(file: SourceFile): readonly WorkerSite[] {
+  const found: WorkerSite[] = [];
+  const visit = (node: Node): void => {
+    if (
+      isNewExpression(node) &&
+      isIdentifier(node.expression) &&
+      WORKER_CONSTRUCTORS.has(node.expression.text)
+    ) {
+      const address = workerAddress(node.arguments?.[0]);
+      if (address !== undefined) {
+        found.push({
+          literal: address.literal,
+          platformNames: [node.expression, ...address.names],
+        });
+      }
+    }
+    if (isCallExpression(node)) {
+      const callee = node.expression;
+      if (
+        isPropertyAccessExpression(callee) &&
+        isIdentifier(callee.name) &&
+        callee.name.text === "register" &&
+        isPropertyAccessExpression(callee.expression) &&
+        isIdentifier(callee.expression.name) &&
+        callee.expression.name.text === "serviceWorker" &&
+        isIdentifier(callee.expression.expression) &&
+        callee.expression.expression.text === "navigator"
+      ) {
+        const address = workerAddress(node.arguments[0]);
+        if (address !== undefined) {
+          found.push({
+            literal: address.literal,
+            platformNames: [callee.expression.expression, ...address.names],
+          });
+        }
+      }
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return found;
+}
+
+/**
+ * The workers one file addresses. A call's names must resolve to the platform's own
+ * declarations, which no file of the target declares and no import brings in; a
+ * name the target binds itself is the target's own constructor or object, which
+ * addresses no worker this rule knows. One batch per file that writes such a call.
+ */
+function workersOf<Brand>(
+  project: ProjectView<Brand>,
+  file: SourceFile,
+  files: SourceFiles,
+): readonly EntryPoint[] {
+  const sites = workerSitesOf(file);
+  if (sites.length === 0) {
+    return [];
+  }
+  const names = sites.flatMap((site) => site.platformNames);
+  const symbols = project.symbolsAt(names.map((name) => project.handle(name)));
+  const platform = new Set<Node>();
+  names.forEach((name, index) => {
+    const symbol = symbols[index];
+    if (
+      symbol !== undefined &&
+      (symbol.flags & SymbolFlags.Alias) === 0 &&
+      symbol.declarations.length > 0 &&
+      symbol.declarations.every((handle) => !files.byName.has(handle.path))
+    ) {
+      platform.add(name);
+    }
+  });
+  const dir = dirnamePath(file.fileName);
+  const found: EntryPoint[] = [];
+  for (const site of sites) {
+    if (!site.platformNames.every((name) => platform.has(name))) {
+      continue;
+    }
+    for (const named of filesNamed(files, dir, site.literal)) {
+      found.push({ file: named, rule: "worker", source: site.literal, exports: false });
+    }
+  }
+  return found;
+}
+
+/**
+ * Every file of one project the lifted rules enter, in no particular order and
+ * possibly more than once: a file two rules enter appears once per rule.
+ *
+ * `testFiles` is the configuration's test-file patterns, matched against each
+ * file's path below the target root; a file one of them matches is a test file the
+ * runner executes.
+ */
+export function entryPoints<Brand>(
+  project: ProjectView<Brand>,
+  files: SourceFiles,
+  testFiles: readonly string[],
+): readonly EntryPoint[] {
+  const found: EntryPoint[] = [];
+  const tests = testFiles.map((pattern) => ({ pattern, expression: globExpression(pattern) }));
+  for (const [path, file] of files.byPath) {
+    const named = conventionOf(basename(path));
+    if (named !== undefined) {
+      found.push({ file, rule: named.convention.rule, source: named.spelled, exports: true });
+      if (named.convention.testRunner) {
+        found.push(...setupFilesOf(file, files));
+      }
+      if (named.convention.rule === "browser-tests") {
+        found.push(...browserTestsOf(file, files));
+      }
+    }
+    for (const { pattern, expression } of tests) {
+      if (expression.test(path)) {
+        found.push({ file, rule: "test-runner", source: pattern, exports: false });
+      }
+    }
+    found.push(...workersOf(project, file, files));
+  }
+  return found;
+}

package/src/finding.ts

@@ -0,0 +1,43 @@
+/**
+ * The members of a finding its emitter decides: the code, where the subject is,
+ * what the subject is, and the sentence the finding reports. They are the
+ * Contract's finding members of the same names, spelled in this language's case.
+ *
+ * Every other member the finding schema requires follows from these and from the
+ * run: the kind's name, its fixability and its ceiling come from the code's row of
+ * the issue-kind vocabulary, the severity and the confidence from the resolved
+ * configuration, the language from the analyzer. A report completes them, so an
+ * emitter cannot state one that disagrees with the vocabulary.
+ */
+
+/** Where the subject of a finding is. */
+export interface FindingPosition {
+  /** The file below the target root, with the solidus as separator. */
+  readonly path: string;
+  /** The line of the subject's first character, counted from one. */
+  readonly line: number;
+  /** The column of the subject's first character, counted from one in UTF-16 code units. */
+  readonly column: number;
+  /** The line of the subject's last character. */
+  readonly endLine: number;
+}
+
+/** What a finding is about. */
+export interface FindingSubject {
+  /** The stable symbol reference, or for a configured root the root as written. */
+  readonly ref: string;
+  /** The subject kind, from the closed vocabulary of the finding schema. */
+  readonly kind: string;
+  /** The display name a text line renders. */
+  readonly name: string;
+  /** The number of source lines the subject spans. */
+  readonly sizeLines: number;
+}
+
+/** One finding, as its emitter states it. */
+export interface Finding {
+  readonly code: string;
+  readonly position: FindingPosition;
+  readonly symbol: FindingSubject;
+  readonly message: string;
+}

package/src/glob.ts

@@ -0,0 +1,67 @@
+/**
+ * Glob patterns over the paths of the target's own files, as the configuration
+ * writes them. Both `ts.test_files` and `ts.entry_files` name files this way, and
+ * one grammar answers for both.
+ *
+ * A configured root is not written in this grammar. It names a symbol reference
+ * rather than a path, `*` there spans the solidus and a brace list means nothing,
+ * so that rule is written where it is read.
+ */
+
+/**
+ * One literal run of a pattern, with every character the expression syntax claims
+ * escaped.
+ *
+ * The set is the syntax characters and the solidus, and it is closed: an escape of any
+ * other character is refused outright by the expression syntax under the unicode flag,
+ * so escaping a hyphen, which needs none outside a character class, would refuse every
+ * pattern that names a hyphenated path.
+ */
+function quoted(text: string): string {
+  return text.replaceAll(/[.*+?^${}()|[\]\\/]/gu, (character) => `\\${character}`);
+}
+
+/**
+ * The expression one glob pattern denotes. `**` spans path separators while `*` and `?`
+ * do not, a brace list is an alternation of its members, and every other character
+ * stands for itself.
+ */
+export function globExpression(pattern: string): RegExp {
+  let source = "^";
+  let at = 0;
+  while (at < pattern.length) {
+    const rest = pattern.slice(at);
+    if (rest.startsWith("**/")) {
+      source += "(?:[^/]*/)*";
+      at += 3;
+      continue;
+    }
+    if (rest.startsWith("**")) {
+      source += ".*";
+      at += 2;
+      continue;
+    }
+    const character = pattern[at] ?? "";
+    at += 1;
+    if (character === "*") {
+      source += "[^/]*";
+      continue;
+    }
+    if (character === "?") {
+      source += "[^/]";
+      continue;
+    }
+    if (character === "{") {
+      const close = pattern.indexOf("}", at);
+      if (close < 0) {
+        source += "\\{";
+        continue;
+      }
+      source += `(?:${pattern.slice(at, close).split(",").map(quoted).join("|")})`;
+      at = close + 1;
+      continue;
+    }
+    source += quoted(character);
+  }
+  return new RegExp(`${source}$`, "u");
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export { run, SETTING_OPTIONS, type Writer } from "./run.ts";
 export type { DirectoryEntry, Host, PathKind } from "./host.ts";
+export { DECLINED_CONVENTIONS, type DeclinedConvention } from "./entry-point-gaps.ts";
 export {
   inventory,
   nodeKey,