@cplieger/deadset-ts 2.2.1 → 3.0.0

package/src/references.ts

@@ -3,8 +3,10 @@ import {
   isBinaryExpression,
   isDeleteExpression,
   isElementAccessExpression,
+  isExportDeclaration,
   isForInStatement,
   isForOfStatement,
+  isNamespaceExport,
   isObjectLiteralExpression,
   isParenthesizedExpression,
   isPostfixUnaryExpression,
@@ -19,6 +21,7 @@ import {
   type SourceFile,
 } from "@typescript/native/unstable/ast";
 import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import { globExpression } from "./glob.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { byPosition, renderPosition, type Position } from "./position.ts";
 import type { ProjectView } from "./session.ts";
@@ -109,6 +112,12 @@ export interface References {
   readonly references: readonly Reference[];
   /** The rules that classified files as test files, ordered by rule. */
   readonly testFileRules: readonly TestFileRule[];
+  /**
+   * Every file the rules classified as a test file, by its path below the target root,
+   * ascending. A declaration such a file holds is a test declaration, by the same
+   * classification that marks the references the file makes.
+   */
+  readonly testFilePaths: readonly string[];
   readonly cost: ReferenceCost;
 }
 
@@ -272,22 +281,88 @@ interface Site {
   readonly use: Use;
 }
 
+/**
+ * One re-export the walk found, which names what it carries forward without a name
+ * that is a use: an export specifier, a namespace export, or a bare star re-export.
+ */
+interface Link {
+  /**
+   * The node whose symbol says what the re-export carries: the alias a specifier or a
+   * namespace export declares, or the module a bare star re-export names.
+   */
+  readonly node: Node;
+  /** Where the reference is written: the name a specifier re-exports, or the module specifier. */
+  readonly at: Node;
+  /** The re-export's own declaration, or for a bare star the declaration enclosing it. */
+  readonly from: string;
+  /** Whether the node's symbol is an alias, which is followed one link along. */
+  readonly alias: boolean;
+}
+
+/** Everything one file's walk found to resolve. */
+interface FileSites {
+  readonly uses: readonly Site[];
+  readonly links: readonly Link[];
+}
+
+/**
+ * The re-exports one node writes, if it is an export declaration. A specifier and a
+ * namespace export are declarations whose names are where they are written, so no use is
+ * read from them; each references what it carries forward instead. A bare star declares
+ * nothing, so the declaration enclosing it, at the top level the file, references the
+ * module it names.
+ */
+function linksOf(
+  file: SourceFile,
+  node: Node,
+  declarations: ReadonlyMap<string, string>,
+  enclosing: string,
+): Link[] {
+  if (!isExportDeclaration(node)) {
+    return [];
+  }
+  const clause = node.exportClause;
+  const specifier = node.moduleSpecifier;
+  if (clause === undefined) {
+    return specifier === undefined
+      ? []
+      : [{ node: specifier, at: specifier, from: enclosing, alias: false }];
+  }
+  if (isNamespaceExport(clause)) {
+    const from = declarations.get(nodeKey(file, clause));
+    return from === undefined
+      ? []
+      : [{ node: clause.name, at: specifier ?? clause.name, from, alias: true }];
+  }
+  const found: Link[] = [];
+  for (const element of clause.elements) {
+    const from = declarations.get(nodeKey(file, element));
+    if (from !== undefined) {
+      found.push({
+        node: element.name,
+        at: element.propertyName ?? element.name,
+        from,
+        alias: true,
+      });
+    }
+  }
+  return found;
+}
+
 /**
  * Every name node one file holds that is a use rather than a declaration, in source
- * order, each with the declaration that encloses it and the use it makes.
- *
- * One walk answers all three, because the three facts are positional and a second walk
- * would have to agree with this one about which nodes are names. A name that is the
- * declared name of the declaration it belongs to is left out: it is where that
- * declaration is written rather than a use of it, which is what makes a declaration
- * referenced only from its own site an unreferenced declaration.
+ * order, each with its enclosing declaration and its use, and every re-export the file
+ * writes. One walk answers all of it, because a second would have to agree with this one
+ * about which nodes are names. A declaration's own declared name is left out, which is
+ * what makes a declaration referenced only from its own site an unreferenced one.
  */
 function sitesOf(
   file: SourceFile,
   declarations: ReadonlyMap<string, string>,
   fileId: string,
-): Site[] {
+): FileSites {
   const found: Site[] = [];
+  const links: Link[] = [];
   const writes = new Set<number>();
   const declared = new Set<number>();
   const shorthands = new Map<number, Node>();
@@ -325,6 +400,7 @@ function sitesOf(
     }
     markNames(node);
     markStores(node, writes);
+    links.push(...linksOf(file, node, declarations, enclosing));
     const held = declarations.get(nodeKey(file, node));
     const outer = enclosing;
     if (held !== undefined) {
@@ -335,65 +411,7 @@ function sitesOf(
   };
 
   file.forEachChild(visit);
-  return found;
-}
-
-/**
- * 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.
- */
-function expressionOf(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");
+  return { uses: found, links };
 }
 
 /**
@@ -440,10 +458,12 @@ export function references<Brand>(
 ): References {
   const cap = options.batchCap ?? DEFAULT_BATCH_CAP;
   const declarations = held.declarations;
-  const patterns = options.testFiles.map(expressionOf);
+  const patterns = options.testFiles.map(globExpression);
   const matched = options.testFiles.map(() => 0);
   const found: Reference[] = [];
+  const tests: string[] = [];
   const reached = new Map<number, readonly Target[]>();
+  const steps = new Map<number, TSSymbol | undefined>();
   let batched = 0;
   let fileBatches = 0;
   let residueFallbacks = 0;
@@ -457,23 +477,53 @@ export function references<Brand>(
   const declaredAt = (node: Node): string | undefined =>
     declarations.get(nodeKey(node.getSourceFile(), node));
 
+  /**
+   * The declarations of the inventory one symbol is.
+   *
+   * A declaration handle carries the file it is in, so the question is answered before
+   * the handle is resolved: a declaration outside the project's own files belongs to
+   * another program and is never read, which is what keeps the pass from fetching a
+   * library file to discover that the inventory does not hold what is in it.
+   */
+  const declarationsOf = (symbol: TSSymbol): string[] => {
+    const ids: string[] = [];
+    for (const handle of symbol.declarations) {
+      if (!ownFiles.has(handle.path)) {
+        continue;
+      }
+      const node = project.declarationAt(handle)?.node;
+      const id = node === undefined ? undefined : declaredAt(node);
+      if (id !== undefined && !ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+    return ids;
+  };
+
+  /**
+   * What one alias names, one link along, asked once per alias whatever the number of
+   * chains it is a link of. Only a symbol the binder flagged an alias is asked, which is
+   * the condition the step asserts on: a default export of an expression is written in
+   * an alias form and names nothing declared elsewhere, so its chain ends at itself.
+   */
+  const stepOf = (symbol: TSSymbol): TSSymbol | undefined => {
+    if ((symbol.flags & SymbolFlags.Alias) === 0) {
+      return undefined;
+    }
+    if (steps.has(symbol.id)) {
+      return steps.get(symbol.id);
+    }
+    const next = project.aliasStepOf(symbol);
+    aliasSteps += 1;
+    steps.set(symbol.id, next);
+    return next;
+  };
+
   /**
    * The declarations one symbol names: the declaration it is, and every link of the
    * alias chain it stands at the head of. A re-export something imports is used and so
    * is the declaration behind it, so both are named; a link this project does not
    * declare is stepped over rather than recorded.
-   *
-   * A symbol is asked to step only where the binder flagged it an alias, which is the
-   * same condition the step itself asserts on. The declaration's syntax is not that
-   * condition and does not stand in for it: a default export of an expression is
-   * written as one of the alias forms and names nothing declared elsewhere, so it is
-   * recorded as the declaration it is and the chain ends there.
-   *
-   * A declaration handle carries the file it is in, so the question the walk asks of a
-   * declaration is answered before it is resolved: a declaration outside the project's
-   * own files belongs to another program and is never read, which is what keeps the
-   * pass from fetching a library file to discover that the inventory does not hold what
-   * is in it.
    */
   const targetsOf = (symbol: TSSymbol): readonly Target[] => {
     const cached = reached.get(symbol.id);
@@ -486,35 +536,49 @@ export function references<Brand>(
     let stepped = false;
     while (at !== undefined && !walked.has(at.id)) {
       walked.add(at.id);
-      const alias = (at.flags & SymbolFlags.Alias) !== 0;
-      for (const handle of at.declarations) {
-        if (!ownFiles.has(handle.path)) {
-          continue;
-        }
-        const node = project.declarationAt(handle)?.node;
-        const id = node === undefined ? undefined : declaredAt(node);
-        if (id !== undefined && !targets.some((target) => target.id === id)) {
+      for (const id of declarationsOf(at)) {
+        if (!targets.some((target) => target.id === id)) {
           targets.push({ id, stepped });
         }
       }
-      if (!alias) {
-        break;
-      }
-      at = project.aliasStepOf(at);
-      aliasSteps += 1;
+      at = stepOf(at);
       stepped = true;
     }
     reached.set(symbol.id, targets);
     return targets;
   };
 
+  /**
+   * The declarations one re-export carries forward: for an alias, the first link along
+   * its chain that the inventory declares, stepping over the links it does not, such as
+   * an import the re-export is written against; for a bare star, the module it names.
+   * Each later link is a declaration of its own that references the next, so one link
+   * per re-export is what lets a chain be followed one declaration at a time.
+   */
+  const carriedBy = (link: Link, symbol: TSSymbol): readonly string[] => {
+    if (!link.alias) {
+      return declarationsOf(symbol);
+    }
+    const walked = new Set<number>([symbol.id]);
+    let at = stepOf(symbol);
+    while (at !== undefined && !walked.has(at.id)) {
+      walked.add(at.id);
+      const ids = declarationsOf(at);
+      if (ids.length > 0) {
+        return ids;
+      }
+      at = stepOf(at);
+    }
+    return [];
+  };
+
   /** The symbol one site resolves to, asking only the accessor the site's form names. */
-  const symbolFor = (site: Site, answered: ReadonlyMap<number, TSSymbol>): TSSymbol | undefined => {
+  const symbolFor = (site: Site, answered: ReadonlyMap<Node, TSSymbol>): TSSymbol | undefined => {
     if (site.shorthand !== undefined) {
       shorthandLookups += 1;
       return project.shorthandValueAt(project.handle(site.shorthand));
     }
-    const batched = answered.get(site.node.pos);
+    const batched = answered.get(site.node);
     if (batched !== undefined) {
       return batched;
     }
@@ -524,38 +588,63 @@ export function references<Brand>(
 
   for (const file of files) {
     const path = renderPosition(file, targetRoot, 0).path;
-    let test = false;
-    patterns.forEach((pattern, index) => {
-      if (pattern.test(path)) {
+    const hits = patterns.map((pattern) => pattern.test(path));
+    hits.forEach((hit, index) => {
+      if (hit) {
         matched[index] = (matched[index] ?? 0) + 1;
-        test = true;
       }
     });
-    const sites = sitesOf(file, declarations, declaredAt(file) ?? "");
-
-    // One batch per capped run of the file's name nodes. A shorthand is left out of
-    // the batch: its name resolves to the property the literal declares, so the batch's
-    // answer for it would name something this project's inventory never holds.
-    const batching = sites.filter((site) => site.shorthand === undefined);
-    const answered = new Map<number, TSSymbol>();
+    const test = hits.includes(true);
+    if (test) {
+      tests.push(path);
+    }
+    const { uses, links } = sitesOf(file, declarations, declaredAt(file) ?? "");
+
+    // One batch per capped run of the file's name nodes, the re-exports' nodes after
+    // the uses. A shorthand is left out of the batch: its name resolves to the property
+    // the literal declares, so the batch's answer for it would name something this
+    // project's inventory never holds.
+    const batching = [
+      ...uses.filter((site) => site.shorthand === undefined).map((site) => site.node),
+      ...links.map((link) => link.node),
+    ];
+    const answered = new Map<Node, TSSymbol>();
     batched += batching.length;
     for (let from = 0; from < batching.length; from += cap) {
       const run = batching.slice(from, from + cap);
-      const answers = project.symbolsAt(run.map((site) => project.handle(site.node)));
+      const answers = project.symbolsAt(run.map((node) => project.handle(node)));
       fileBatches += 1;
-      run.forEach((site, index) => {
+      run.forEach((node, index) => {
         const symbol = answers[index];
         if (symbol !== undefined) {
-          answered.set(site.node.pos, symbol);
+          answered.set(node, symbol);
         }
       });
     }
 
-    for (const site of sites) {
+    for (const link of links) {
+      const symbol = answered.get(link.node);
+      if (symbol === undefined) {
+        continue;
+      }
+      const position = renderPosition(file, targetRoot, link.at.getStart());
+      for (const id of carriedBy(link, symbol)) {
+        found.push({
+          from: link.from,
+          to: id,
+          position,
+          use: "read",
+          resolution: link.alias ? "alias" : "batch",
+          test,
+        });
+      }
+    }
+
+    for (const site of uses) {
       const direct: Resolution =
         site.shorthand !== undefined
           ? "shorthand"
-          : answered.has(site.node.pos)
+          : answered.has(site.node)
             ? "batch"
             : "resolved-symbol";
       const symbol = symbolFor(site, answered);
@@ -590,6 +679,7 @@ export function references<Brand>(
     testFileRules: options.testFiles
       .map((_pattern, index) => ({ rule: patternRule(index), matched: matched[index] ?? 0 }))
       .sort((a, b) => compare(a.rule, b.rule)),
+    testFilePaths: tests.sort(compare),
     cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps },
   };
 }

package/src/resolve.ts

@@ -38,6 +38,24 @@ const SEVERITY_KEY = /^DS[0-9]{2}([0-9]{2})?$/u;
 const EXEMPTION_CLASS = /^[a-z][a-z0-9-]*$/u;
 const CONTRACT_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/u;
 
+/** The members only a platform build configuration carries. */
+const PLATFORM_MEMBERS = ["os", "arch", "tags"] as const;
+
+/** The member only a project build configuration carries. */
+const PROJECT_MEMBER = "project";
+
+/**
+ * One segment of a project path: not empty, not `.` or `..`, and holding no
+ * solidus, backslash or line break.
+ */
+const PROJECT_SEGMENT = String.raw`(?:[^/\\.\r\n][^/\\\r\n]*|\.[^/\\.\r\n][^/\\\r\n]*|\.\.[^/\\\r\n]+)`;
+
+/**
+ * A project path: segments joined by a solidus, so the path is relative, below
+ * the root it is read against, and spelled one way on every machine.
+ */
+const PROJECT_PATH = new RegExp(`^${PROJECT_SEGMENT}(?:/${PROJECT_SEGMENT})*$`, "u");
+
 const TARGET_KINDS: readonly TargetKind[] = ["application", "library"];
 const CONFIDENCES: readonly Confidence[] = ["certain", "probable", "possible"];
 const GENERATED_FILES: readonly GeneratedFiles[] = ["exclude", "include"];
@@ -252,10 +270,75 @@ function requireMember(value: string | undefined, path: string, label: string):
   return value;
 }
 
+/** One build configuration entry as a platform: an identifier, an operating system and an architecture. */
+function readPlatform(
+  entry: Record<string, unknown>,
+  at: string,
+  label: string,
+): BuildConfiguration {
+  return {
+    shape: "platform",
+    id: requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label),
+    os: requireMember(readString(entry, "os", `${at}.os`, label), `${at}.os`, label),
+    arch: requireMember(readString(entry, "arch", `${at}.arch`, label), `${at}.arch`, label),
+    tags: readStrings(entry, "tags", `${at}.tags`, label, 0) ?? [],
+  };
+}
+
+/** One build configuration entry as a project: an identifier and a configuration file below the target root. */
+function readProject(
+  entry: Record<string, unknown>,
+  at: string,
+  label: string,
+): BuildConfiguration {
+  const id = requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label);
+  const path = `${at}.${PROJECT_MEMBER}`;
+  const project = requireMember(readString(entry, PROJECT_MEMBER, path, label), path, label);
+  if (!PROJECT_PATH.test(project)) {
+    throw malformed(
+      label,
+      path,
+      `${JSON.stringify(project)} is not a path below the target root: segments joined by /, ` +
+        "none empty, . or .., and no backslash or line break",
+    );
+  }
+  return { shape: "project", id, project };
+}
+
 /**
- * The build matrix: every entry names an identifier, an operating system and an
- * architecture.
+ * One build configuration entry, read as the one shape its members name: a member
+ * only a platform carries makes it a platform, the member only a project carries
+ * makes it a project, and an entry naming members of both, or of neither, is
+ * refused at the entry, because the two shapes are exclusive.
  */
+function readConfiguration(entry: unknown, at: string, label: string): BuildConfiguration {
+  if (!isRecord(entry)) {
+    throw malformed(label, at, "is not an object");
+  }
+  const platform = PLATFORM_MEMBERS.filter((name) => Object.hasOwn(entry, name));
+  const project = Object.hasOwn(entry, PROJECT_MEMBER);
+  if (platform.length > 0 && project) {
+    throw malformed(
+      label,
+      at,
+      `carries ${spell(platform)} of a platform and ${JSON.stringify(PROJECT_MEMBER)} of a ` +
+        "project, and an entry is one shape or the other",
+    );
+  }
+  if (project) {
+    return readProject(entry, at, label);
+  }
+  if (platform.length === 0) {
+    throw malformed(
+      label,
+      at,
+      `names neither a platform's "os" and "arch" nor a project's ${JSON.stringify(PROJECT_MEMBER)}`,
+    );
+  }
+  return readPlatform(entry, at, label);
+}
+
+/** The build matrix, one entry in one shape at a time. */
 function readConfigurations(
   analysis: Record<string, unknown> | undefined,
   label: string,
@@ -267,18 +350,9 @@ function readConfigurations(
   if (!Array.isArray(value)) {
     throw malformed(label, "analysis.configurations", "is not an array");
   }
-  return (value as unknown[]).map((entry, index) => {
-    const at = `analysis.configurations[${String(index)}]`;
-    if (!isRecord(entry)) {
-      throw malformed(label, at, "is not an object");
-    }
-    return {
-      id: requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label),
-      os: requireMember(readString(entry, "os", `${at}.os`, label), `${at}.os`, label),
-      arch: requireMember(readString(entry, "arch", `${at}.arch`, label), `${at}.arch`, label),
-      tags: readStrings(entry, "tags", `${at}.tags`, label, 0) ?? [],
-    };
-  });
+  return (value as unknown[]).map((entry, index) =>
+    readConfiguration(entry, `analysis.configurations[${String(index)}]`, label),
+  );
 }
 
 /**
@@ -642,6 +716,35 @@ function checkLabels(provenance: ReadonlyMap<string, Origin>): void {
  * the usage exit code.
  */
 export function resolve(inputs: Inputs): { config: Config; provenance: Provenance } {
+  const { config, provenance } = settleAll(inputs);
+  if (config.targetKind === "") {
+    throw new ConfigError(
+      "missing-target-kind",
+      "target.kind",
+      "target.kind is not set, it has no default and is never inferred: searched " +
+        `${describeSource("the repository configuration", inputs.repository, inputs.repositoryLabel)} and ` +
+        describeSource("the central configuration", inputs.central, inputs.centralLabel),
+    );
+  }
+  checkLabels(provenance);
+  return { config, provenance };
+}
+
+/**
+ * The build matrix the configuration documents resolve to, every document read and
+ * refused as {@link resolve} refuses it, and nothing else required of them: which
+ * projects a run analyzes depends on the matrix alone, so a question about the
+ * projects asks no target kind.
+ */
+export function resolveMatrix(inputs: Inputs): readonly BuildConfiguration[] {
+  return settleAll(inputs).config.analysis.configurations;
+}
+
+/**
+ * Every setting the documents supply, each from the highest-ranked source carrying
+ * it, with the origin of each. The target kind is empty where no source names one.
+ */
+function settleAll(inputs: Inputs): { config: Config; provenance: Map<string, Origin> } {
   const sources = readSources(inputs);
   const defaults = defaultConfig();
   const provenance = new Map<string, Origin>();
@@ -718,15 +821,5 @@ export function resolve(inputs: Inputs): { config: Config; provenance: Provenanc
     },
   };
 
-  if (config.targetKind === "") {
-    throw new ConfigError(
-      "missing-target-kind",
-      "target.kind",
-      "target.kind is not set, it has no default and is never inferred: searched " +
-        `${describeSource("the repository configuration", inputs.repository, inputs.repositoryLabel)} and ` +
-        describeSource("the central configuration", inputs.central, inputs.centralLabel),
-    );
-  }
-  checkLabels(provenance);
   return { config, provenance };
 }