@cplieger/deadset-ts 2.2.0 → 2.3.0

package/src/manifest.ts

@@ -0,0 +1,174 @@
+/**
+ * The entry points a package manifest names, which are roots because something
+ * outside the analyzed program reaches them: a consumer importing the package, or a
+ * shell running its command.
+ *
+ * Only the target's own manifest is read. A manifest below the target root belongs
+ * to another package, whose entry points are that package's roots and not this
+ * target's.
+ */
+
+import type { Host } from "./host.ts";
+import { isAbsolutePath, joinPath, resolvePath } from "./paths.ts";
+
+/** The manifest's own name. */
+const MANIFEST = "package.json";
+
+/** The three members that name an entry point beside `exports` and `bin`. */
+const LEGACY_MEMBERS = ["main", "module", "types"] as const;
+
+/** What reaches one entry point the manifest names. */
+export type EntryRole =
+  /** A consumer importing the package, which is a caller the analysis cannot see. */
+  | "import"
+  /** A shell running the package's command, which is a caller that exists. */
+  | "run";
+
+/** One entry point the manifest names. */
+export interface ManifestEntry {
+  /**
+   * The member that named it, spelled as a reader of the manifest reads one:
+   * `main`, `bin["deadset-ts"]`, `exports["."]["import"]`. It is what a maintainer
+   * edits, so it is what a root reports as the string that named it.
+   */
+  readonly member: string;
+  /** The target the member carries, resolved against the manifest's directory. */
+  readonly path: string;
+  readonly role: EntryRole;
+  /**
+   * Whether the member declares what a consumer may import, which is `exports` and
+   * the three members that preceded it. A command is published too, and is not this:
+   * `exports` is the surface a library's published API is read from.
+   */
+  readonly published: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether one member's value names a file of this package rather than another
+ * package or a URL. A target written with no leading dot is a path too, which is
+ * how the members that preceded `exports` are written.
+ */
+function isTarget(value: string, requireDot: boolean): boolean {
+  if (value === "" || isAbsolutePath(value) || value.includes("://")) {
+    return false;
+  }
+  return !requireDot || value.startsWith("./");
+}
+
+/** One member's spelling below another: `exports` then `exports["."]`. */
+function below(member: string, key: string): string {
+  return `${member}[${JSON.stringify(key)}]`;
+}
+
+/**
+ * Every target one `exports` value carries, at the member each is written under.
+ *
+ * The value is a string, an object whose keys are subpaths or conditions, or an
+ * array of alternatives, nested to any depth, and a `null` blocks a subpath rather
+ * than naming a target. Every level is walked because a condition names a different
+ * file of the same package and each is an entry point of its own; a key's meaning
+ * is not read, because a subpath and a condition both lead to a target and the
+ * walk needs no more than that.
+ */
+function exportTargets(value: unknown, member: string, found: ManifestEntry[]): void {
+  if (typeof value === "string") {
+    if (isTarget(value, true)) {
+      found.push({ member, path: value, role: "import", published: true });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((alternative, index) => {
+      exportTargets(alternative, below(member, String(index)), found);
+    });
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+  for (const [key, held] of Object.entries(value)) {
+    exportTargets(held, below(member, key), found);
+  }
+}
+
+/** The manifest at the target root, decoded, or undefined where there is none to read. */
+function manifestOf(host: Host, targetRoot: string): Record<string, unknown> | undefined {
+  let text: string;
+  try {
+    text = host.readFile(joinPath(targetRoot, MANIFEST));
+  } catch {
+    return undefined;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    // A manifest this program cannot read names no entry point, which is the same
+    // answer as an absent one. What a manifest's contents say is not refused here:
+    // the package manager owns that refusal, and an analysis of a tree it rejects
+    // is not the run's subject.
+    return undefined;
+  }
+  return isRecord(value) ? value : undefined;
+}
+
+/** What the target's own manifest declares about where the package is entered. */
+export interface Manifest {
+  /**
+   * Every entry point the manifest names, in the order the members are read: `main`,
+   * `module`, `types`, then each `bin` command, then every target of `exports`. Each
+   * path is absolute.
+   */
+  readonly entries: readonly ManifestEntry[];
+  /**
+   * Whether an `exports` member is written at all. A package that declares one has
+   * said exactly what a consumer may import, so its published API is what `exports`
+   * reaches; a package that declares none publishes whatever the members that
+   * preceded it name.
+   */
+  readonly declaresExports: boolean;
+}
+
+/**
+ * What the target's own manifest declares about where the package is entered.
+ *
+ * A target is taken as written. It is not resolved to a source file here, because
+ * which file a target names is a fact about the compiler configuration that emits
+ * it and there is one such configuration per project, while there is one manifest.
+ */
+export function readManifest(host: Host, targetRoot: string): Manifest {
+  const manifest = manifestOf(host, targetRoot);
+  if (manifest === undefined) {
+    return { entries: [], declaresExports: false };
+  }
+
+  const found: ManifestEntry[] = [];
+  for (const member of LEGACY_MEMBERS) {
+    const value = manifest[member];
+    if (typeof value === "string" && isTarget(value, false)) {
+      found.push({ member, path: value, role: "import", published: true });
+    }
+  }
+
+  const bin = manifest["bin"];
+  if (typeof bin === "string" && isTarget(bin, false)) {
+    found.push({ member: "bin", path: bin, role: "run", published: false });
+  } else if (isRecord(bin)) {
+    for (const [command, value] of Object.entries(bin)) {
+      if (typeof value === "string" && isTarget(value, false)) {
+        found.push({ member: below("bin", command), path: value, role: "run", published: false });
+      }
+    }
+  }
+
+  exportTargets(manifest["exports"], "exports", found);
+
+  return {
+    entries: found.map((entry) => ({ ...entry, path: resolvePath(targetRoot, entry.path) })),
+    declaresExports: manifest["exports"] !== undefined,
+  };
+}

package/src/references.ts

@@ -18,7 +18,8 @@ import {
   type Node,
   type SourceFile,
 } from "@typescript/native/unstable/ast";
-import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+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";
@@ -159,22 +160,6 @@ const ASSIGNMENTS: ReadonlySet<SyntaxKind> = new Set([
   SyntaxKind.CaretEqualsToken,
 ]);
 
-/**
- * The declaration forms that name something declared elsewhere. Each is a link rather
- * than a declaration of what it names, so a reference through one names the next link
- * and, at the end of the chain, the declaration itself: a re-export something imports
- * is used, and so is the declaration behind it.
- */
-const ALIASES: ReadonlySet<SyntaxKind> = new Set([
-  SyntaxKind.ImportClause,
-  SyntaxKind.ImportEqualsDeclaration,
-  SyntaxKind.ImportSpecifier,
-  SyntaxKind.NamespaceImport,
-  SyntaxKind.ExportAssignment,
-  SyntaxKind.ExportSpecifier,
-  SyntaxKind.NamespaceExport,
-]);
-
 /** Whether one node is an identifier or a private name, the two forms a name takes. */
 function isName(node: Node): boolean {
   return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
@@ -354,64 +339,6 @@ function sitesOf(
   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");
-}
-
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
  * vocabulary spells, which cannot carry a pattern, so a rule is named by the place of
@@ -456,7 +383,7 @@ 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 reached = new Map<number, readonly Target[]>();
@@ -479,11 +406,17 @@ export function references<Brand>(
    * is the declaration behind it, so both are named; a link this project does not
    * declare is stepped over rather than recorded.
    *
-   * A declaration handle carries the file it is in and the syntax it is written as, so
-   * both questions the walk asks of a declaration are 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.
+   * 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);
@@ -496,9 +429,8 @@ export function references<Brand>(
     let stepped = false;
     while (at !== undefined && !walked.has(at.id)) {
       walked.add(at.id);
-      let alias = false;
+      const alias = (at.flags & SymbolFlags.Alias) !== 0;
       for (const handle of at.declarations) {
-        alias = alias || ALIASES.has(handle.kind);
         if (!ownFiles.has(handle.path)) {
           continue;
         }