@cplieger/deadset-ts 8.0.0-dev.1 → 8.0.0-dev.10

package/src/manifest.ts

@@ -7,45 +7,47 @@
 
 import type { Host } from "./host.ts";
 import { isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import { isRecord } from "./json-document.ts";
+import { MANIFEST, manifestAt, readJSON } from "./fs/manifest.ts";
+import { scriptTokens } from "./text/shell.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. */
+/** What reaches one entry the manifest names. */
 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"
-  /** A token of one of the package's scripts, which the package manager runs. */
+  /** A token of one of the package's scripts, or the whole of a command string the package runs. */
   | "script";
 
-/** One entry point the manifest names. */
+/** One entry point the manifest names, or the whole of one command string the package runs. */
 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.
+   * The member that named it as a maintainer edits it, `main`, `bin["deadset-ts"]` or
+   * `exports["."]["import"]`: what a root reports as the string that named it.
    */
   readonly member: string;
-  /** The target the member carries, resolved against the manifest's directory. */
+  /** The target the member carries, resolved against the manifest's directory, or that directory for a whole command string. */
   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.
+   * Whether the member declares what a consumer may import, the surface a library's published
+   * API is read from: `exports`, `browser` and the three members that preceded `exports`.
    */
   readonly published: boolean;
   /** The directory of the manifest that names it, which `path` was resolved against. */
   readonly dir: string;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  /**
+   * On the entry of a whole command string, which names no entry point and whose path is the
+   * manifest's directory, that string: rooting enters no file for it and holds each file
+   * `spelledFiles` reads it to name.
+   */
+  readonly command?: string;
 }
 
 /**
@@ -60,35 +62,45 @@ function isTarget(value: string, requireDot: boolean): boolean {
   return !requireDot || value.startsWith("./");
 }
 
-/** Where a script's command line splits into tokens: white space and the shell's operators. */
-const SCRIPT_SEPARATORS = /\s+|&&|\|\||;|\|/u;
-
-/** A token written inside one pair of quotes. */
-const QUOTED = /^(["'])(.*)\1$/su;
-
-/**
- * Every token one script's command line holds, each with one pair of enclosing quotes
- * removed. A token holding a wildcard is a pattern rather than a path, and names no
- * entry point.
- */
-export function scriptTokens(command: string): readonly string[] {
-  return command
-    .split(SCRIPT_SEPARATORS)
-    .map((token) => token.replace(QUOTED, "$2"))
-    .filter((token) => token !== "" && !token.includes("*"));
-}
-
 /** 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 nests strings, subpath or condition objects and alternative arrays to
- * any depth; a `null` blocks a subpath. Every level is walked, because each
- * condition names its own entry file, and a key's meaning is never read.
+ * The command strings one manifest runs, each at the member it is written under: each of its
+ * `scripts`, and the `exec` command of nodemon's configuration, in the manifest's `nodemonConfig`
+ * or the `nodemon.json` beside it, which nodemon runs the watched script with:
+ * https://github.com/remy/nodemon#config-files
+ */
+export function manifestCommands(
+  host: Host,
+  dir: string,
+  manifest: Record<string, unknown>,
+): readonly { readonly member: string; readonly command: string }[] {
+  const scripts = manifest["scripts"];
+  const nodemon = {
+    nodemonConfig: manifest["nodemonConfig"],
+    "nodemon.json": readJSON(host, joinPath(dir, "nodemon.json")),
+  };
+  const written = [
+    ...Object.entries(isRecord(scripts) ? scripts : {}).map(
+      ([name, value]) => [below("scripts", name), value] as const,
+    ),
+    ...Object.entries(nodemon).map(
+      ([member, config]) =>
+        [below(member, "exec"), isRecord(config) ? config["exec"] : undefined] as const,
+    ),
+  ];
+  return written.flatMap(([member, command]) =>
+    typeof command === "string" ? [{ member, command }] : [],
+  );
+}
+
+/**
+ * Every target one `exports` value carries, at the member each is written under. Every level of
+ * strings, subpath or condition objects and alternative arrays is walked, because each condition
+ * names its own entry file; a `null` blocks a subpath, and a key's meaning is never read.
  */
 function exportTargets(value: unknown, member: string, found: Omit<ManifestEntry, "dir">[]): void {
   if (typeof value === "string") {
@@ -111,41 +123,18 @@ function exportTargets(value: unknown, member: string, found: Omit<ManifestEntry
   }
 }
 
-/** 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 one manifest declares about where its 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`, then
-   * every token of each script, which names a file only where one is at its path. Each
-   * path is absolute.
+   * Every entry the manifest names, by absolute path, in the order read: the entry points `main`,
+   * `module`, `types`, `browser` and each file it maps, each `bin` command, every `exports` target
+   * and per script each token, which names a file only where one is at its path; and per command
+   * string {@link manifestCommands} reads one entry of its whole text, which is no entry point.
    */
   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.
+   * Whether an `exports` member is written: then the published API is what `exports` reaches,
+   * and otherwise whatever the members that preceded it name.
    */
   readonly declaresExports: boolean;
 }
@@ -158,7 +147,7 @@ export interface Manifest {
  * 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);
+  const manifest = manifestAt(host, targetRoot);
   if (manifest === undefined) {
     return { entries: [], declaresExports: false };
   }
@@ -171,6 +160,24 @@ export function readManifest(host: Host, targetRoot: string): Manifest {
     }
   }
 
+  // A `browser` string replaces `main` in a browser bundle, and an object replaces each
+  // module it maps with the file it names: https://github.com/defunctzombie/package-browser-field-spec
+  const browser = manifest["browser"];
+  if (typeof browser === "string" && isTarget(browser, false)) {
+    found.push({ member: "browser", path: browser, role: "import", published: true });
+  } else if (isRecord(browser)) {
+    for (const [replaced, value] of Object.entries(browser)) {
+      if (typeof value === "string" && isTarget(value, true)) {
+        found.push({
+          member: below("browser", replaced),
+          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 });
@@ -190,16 +197,15 @@ export function readManifest(host: Host, targetRoot: string): Manifest {
       if (typeof command !== "string") {
         continue;
       }
-      for (const token of new Set(scriptTokens(command))) {
-        found.push({
-          member: below("scripts", name),
-          path: token,
-          role: "script",
-          published: false,
-        });
+      const member = below("scripts", name);
+      for (const path of new Set(scriptTokens(command))) {
+        found.push({ member, path, role: "script", published: false });
       }
     }
   }
+  for (const { member, command } of manifestCommands(host, targetRoot, manifest)) {
+    found.push({ member, path: ".", role: "script", published: false, command });
+  }
 
   return {
     entries: found.map((entry) => ({

package/src/matrix.ts

@@ -30,6 +30,8 @@ export interface Configured {
   readonly testFiles: readonly string[];
   /** The paths of the test-support files, which only test code imports. */
   readonly supportFiles?: readonly string[] | undefined;
+  /** The paths of the files only tests reach that are no test-support file. */
+  readonly testUsedFiles?: readonly string[] | undefined;
   /** The ids of the ambient declarations, which describe code the target does not implement. */
   readonly ambient?: ReadonlySet<string> | undefined;
   /**
@@ -60,6 +62,11 @@ export interface Matrix {
    * whose project holds it, in the run's order.
    */
   readonly heldIn: readonly (readonly string[])[];
+  /**
+   * Per declaration of {@link Matrix.union}, whether a file only tests reach that is no
+   * test-support file holds it in some configuration: production code only tests use.
+   */
+  readonly testUsed: readonly boolean[];
   /** Each declaration's dependents, by id, as the first configuration holding it states them. */
   readonly dependents: ReadonlyMap<string, readonly string[]>;
 }
@@ -81,6 +88,17 @@ export interface MatrixCandidate extends Candidate {
    * shape nothing references would be.
    */
   readonly unreferencedTest: boolean;
+  /**
+   * Whether it is dead only because code only tests use is: production code only tests
+   * use holds it and the run that counts test references reaches it, or such a
+   * declaration reaches it through dead declarations.
+   */
+  readonly testUsed: boolean;
+  /**
+   * Whether test code the run that counts test references reaches, and that is no test of
+   * dead code, references it: a test that stays keeps it.
+   */
+  readonly keptByTests: boolean;
 }
 
 /** One run's sweep. */
@@ -158,6 +176,7 @@ export function matrixOf(per: readonly Configured[]): Matrix {
     }
   });
   symbols.sort((a, b) => byPosition(a.position, b.position));
+  const testUsed = new Set(per.flatMap((one) => one.testUsedFiles ?? []));
 
   return {
     configurations: per.map((one) => one.configuration),
@@ -173,6 +192,7 @@ export function matrixOf(per: readonly Configured[]): Matrix {
       new Set(per.flatMap((one) => [...(one.ambient ?? [])])),
     ),
     heldIn: symbols.map((symbol) => holders.get(symbol.id) ?? []),
+    testUsed: symbols.map((symbol) => testUsed.has(symbol.position.path)),
     dependents,
   };
 }
@@ -203,18 +223,32 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
 
   const union = matrix.union;
   const heldBy: (string | undefined)[] = union.symbols.map(() => undefined);
-  const testReached = reachedWithTheTests(union, [
+  const held = [
     ...input.marked,
     ...(input.exempt ?? []).map((record) => record.id),
     ...(input.unanswered ?? []),
-  ]);
-  const judged = union.symbols.map((symbol, at): readonly Candidate[] | undefined => {
+  ];
+  const testReached = reachedWithTheTests(union, held);
+  // A test uses what it names: a file a test reads through a star re-export or a
+  // namespace keeps the exports nothing names at their own class.
+  const testNamed = reachedWithTheTests(union, held, false);
+  const everywhere = union.symbols.map((symbol, at): readonly Candidate[] | undefined => {
     const held = matrix.heldIn[at] ?? [];
     const found = held.map((configuration) => byConfiguration.get(configuration)?.get(symbol.id));
     return held.length === 0 || found.some((candidate) => candidate === undefined)
       ? undefined
       : found.filter((candidate): candidate is Candidate => candidate !== undefined);
   });
+  const compiled = compiledReferences(
+    matrix,
+    new Set(
+      union.symbols.flatMap((symbol, at) => (everywhere[at] === undefined ? [] : [symbol.id])),
+    ),
+    input.mode,
+  );
+  const judged = everywhere.map((found, at) =>
+    compiled.has(union.symbols[at]?.id ?? "") ? undefined : found,
+  );
   // A configuration that does not hold a test's subject's caller finds the subject dead,
   // so a test is of dead code only where every production subject it names is dead in
   // every configuration that holds it.
@@ -227,6 +261,14 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
         union.subject[edge.to] !== true ||
         judged[edge.to] !== undefined,
     );
+  const admittedAt = (at: number): boolean =>
+    judged[at]?.every((candidate) => candidate.testOfDeadCode) === true && subjectsDead(at);
+  const kept = keptByTests(union, testReached, admittedAt);
+  const testUsed = testUsedReach(
+    union,
+    union.symbols.map((_symbol, at) => matrix.testUsed[at] === true && testNamed[at] === true),
+    judged.map((one) => one !== undefined),
+  );
   const candidates: MatrixCandidate[] = [];
   union.symbols.forEach((symbol, at) => {
     const all = judged[at];
@@ -234,7 +276,7 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
       return;
     }
     const held = matrix.heldIn[at] ?? [];
-    const admitted = all.every((candidate) => candidate.testOfDeadCode) && subjectsDead(at);
+    const admitted = admittedAt(at);
     const testRefs = union.made[at]?.test ?? 0;
     const heldByTests =
       heldBy[union.parent[at] ?? OUTSIDE] ??
@@ -255,6 +297,8 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
       configurations: held,
       heldByTests,
       unreferencedTest: unreferenced,
+      testUsed: testUsed[at] === true,
+      keptByTests: kept[at] === true,
     });
   });
 
@@ -266,6 +310,80 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
   };
 }
 
+/**
+ * Every declaration of `dead`, those dead in every configuration that holds them, that a
+ * configuration's graph references from a judged declaration outside `dead` or already
+ * kept, until none joins: deleting one would break that configuration's compile. A
+ * production run counts no reference a test file made.
+ */
+function compiledReferences(
+  matrix: Matrix,
+  dead: ReadonlySet<string>,
+  mode: SweepInput["mode"],
+): ReadonlySet<string> {
+  const kept = new Set<string>();
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const graph of matrix.graphs) {
+      graph.out.forEach((edges, from) => {
+        const id = graph.symbols[from]?.id ?? "";
+        if (graph.subject[from] !== true || (dead.has(id) && !kept.has(id))) {
+          return;
+        }
+        for (const edge of edges) {
+          const to = graph.symbols[edge.to]?.id ?? "";
+          if ((!mode.production || !edge.test) && dead.has(to) && !kept.has(to)) {
+            kept.add(to);
+            changed = true;
+          }
+        }
+      });
+    }
+  }
+  return kept;
+}
+
+/** Per declaration of the union, whether one of `seeds` is it or reaches it through `dead` declarations. */
+function testUsedReach(
+  union: Graph,
+  seeds: readonly boolean[],
+  dead: readonly boolean[],
+): readonly boolean[] {
+  // A file is no candidate, and its top level is what reaches what it alone calls.
+  const reached = seeds.map((seed, at) => seed && dead[at] === true);
+  const queue = seeds.flatMap((one, at) => (one ? [at] : []));
+  for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
+    for (const edge of union.out[at] ?? []) {
+      if (dead[edge.to] === true && reached[edge.to] !== true) {
+        reached[edge.to] = true;
+        queue.push(edge.to);
+      }
+    }
+  }
+  return reached;
+}
+
+/** Per declaration of the union, whether test code `reached` holds and `admitted` rejects references it. */
+function keptByTests(
+  union: Graph,
+  reached: readonly boolean[],
+  admitted: (at: number) => boolean,
+): readonly boolean[] {
+  const kept = union.symbols.map(() => false);
+  union.out.forEach((edges, from) => {
+    const testCode = union.test[from] === true || union.support[from] === true;
+    if (!testCode || reached[from] !== true || admitted(from)) {
+      return;
+    }
+    for (const edge of edges) {
+      if (edge.test) {
+        kept[edge.to] = true;
+      }
+    }
+  });
+  return kept;
+}
+
 /**
  * The dead components of one sweep over the union, with the file declarations at `files`
  * dead as well: a file that is deleted whole takes the declarations it holds and every

package/src/mdx-entries.ts

@@ -9,6 +9,7 @@ import { resolveRelativeSpecifier } from "./configuration-files.ts";
 import type { Host } from "./host.ts";
 import { dirnamePath, joinPath, resolvePath } from "./paths.ts";
 import type { SourceFiles } from "./source-files.ts";
+import { filesBelow } from "./fs/tree.ts";
 
 /** One file a document imports, the specifier that named it, and the export names it reads. */
 interface DocumentEntry {
@@ -18,9 +19,6 @@ interface DocumentEntry {
   readonly names: readonly string[] | undefined;
 }
 
-/** The directories no document is read below. */
-const SKIPPED: ReadonlySet<string> = new Set(["node_modules", ".git"]);
-
 /** The extensions of a document whose imports an MDX compiler reads. */
 const DOCUMENT = /\.mdx?$/u;
 
@@ -129,28 +127,6 @@ function clauseNames(clause: string): readonly string[] | undefined {
   return names;
 }
 
-/** Every document below `dir`, outside every skipped directory, by absolute path. */
-function documents(host: Host, dir: string): readonly string[] {
-  let entries;
-  try {
-    entries = host.readDirectory(dir);
-  } catch {
-    return [];
-  }
-  const found: string[] = [];
-  for (const entry of entries) {
-    const path = joinPath(dir, entry.name);
-    if (entry.directory) {
-      if (!SKIPPED.has(entry.name)) {
-        found.push(...documents(host, path));
-      }
-    } else if (DOCUMENT.test(entry.name)) {
-      found.push(path);
-    }
-  }
-  return found.sort();
-}
-
 /** The relative specifiers one document's import lines name, its fenced code blocks skipped. */
 function importedBy(
   text: string,
@@ -205,7 +181,8 @@ function documentImports(host: Host, root: string): readonly DocumentImports[] {
   if (known !== undefined) {
     return known;
   }
-  const found = documents(host, root).flatMap((path) => {
+  const found = filesBelow(host, root, (name) => DOCUMENT.test(name)).flatMap((below) => {
+    const path = joinPath(root, below);
     try {
       return [{ path, imports: importedBy(host.readFile(path)) }];
     } catch {

package/src/outside-tests.ts

@@ -20,7 +20,7 @@ import {
   type SourceFile,
 } from "@typescript/native/ast";
 import { RESOLVED_EXTENSIONS, type ParseFile } from "./configuration-files.ts";
-import { emittedFrom } from "./emit-map.ts";
+import { emittedFrom } from "./load/emit-map.ts";
 import type { Host } from "./host.ts";
 import type { Inventory } from "./inventory.ts";
 import { namesImported } from "./module-declarations.ts";

package/src/partial.ts

@@ -1,6 +1,7 @@
-import type { NotBuilt } from "./discover.ts";
+import type { NotBuilt } from "./load/discover.ts";
 import { relativePath } from "./paths.ts";
 import type { UnansweredQuestion } from "./query.ts";
+import { bytewise } from "./text/compare.ts";
 
 /** What a run read only in part. */
 interface Partial {
@@ -24,7 +25,7 @@ function counted(n: number, one: string, many: string): string {
  */
 export function partialNotes(partial: Partial): readonly string[] {
   const notes = [...partial.notBuilt]
-    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .sort((a, b) => bytewise(a.id, b.id))
     .map(
       (one) =>
         `the derived configuration ${one.id} was not built and is not analyzed: ${one.error}`,

package/src/paths.ts

@@ -1,11 +1,7 @@
 /**
- * Filesystem paths, as the supported platform spells them: a solidus separates
- * segments and a leading solidus makes a path absolute.
- *
- * They are written here rather than taken from the platform's own library because
- * every module below the command line stays free of the platform, and because the
- * supported platform set is one, so a second spelling would be a rule nothing
- * exercises.
+ * Filesystem paths as the supported platform spells them: a solidus between segments, a
+ * leading one for an absolute path. They are written here rather than taken from the
+ * platform's library so every module below the command line stays free of the platform.
  */
 
 const SEPARATOR = "/";
@@ -67,6 +63,25 @@ export function dirnamePath(path: string): string {
   return cut === 0 ? SEPARATOR : normalized.slice(0, cut);
 }
 
+/**
+ * `dir` and every directory above it, nearest first, normalized. With `top`, the list ends
+ * at `top` and is empty where `dir` is neither `top` nor below it; without, it ends at the
+ * root of the path.
+ */
+export function ancestors(dir: string, top?: string): readonly string[] {
+  const end = top === undefined ? undefined : normalizePath(top);
+  const found: string[] = [];
+  for (let at = normalizePath(dir); ; at = dirnamePath(at)) {
+    if (end !== undefined && at !== end && relativePath(end, at) === undefined) {
+      return [];
+    }
+    found.push(at);
+    if (at === end || dirnamePath(at) === at) {
+      return found;
+    }
+  }
+}
+
 /**
  * The extension of one path's last segment, from its last full stop, or the empty string
  * where it has none. A segment that only starts with a full stop has none.
@@ -101,14 +116,11 @@ export function queriedModulePath(specifier: string): string | undefined {
 }
 
 /**
- * One path as it reads below a root, or undefined when it is not below the root.
- * Both are normalized first, so a root written with a trailing separator or a `.`
- * segment reaches the same answer, and the comparison is then lexical, so a root
- * and a path spelled through different symbolic links name nothing in common. The
- * root itself is not below itself.
- *
- * The caller resolves both against the same directory before calling: a relative
- * root and an absolute path are two spellings this cannot reconcile.
+ * One path as it reads below a root, or undefined when it is not strictly below the root:
+ * the root itself is not below itself. Both are normalized, then compared lexically, so a
+ * root and a path spelled through different symbolic links name nothing in common. The
+ * caller resolves both against the same directory first: a relative root and an absolute
+ * path cannot be reconciled.
  */
 export function relativePath(root: string, path: string): string | undefined {
   const at = normalizePath(root);

package/src/position.ts

@@ -1,5 +1,6 @@
 import type { SourceFile } from "@typescript/native/ast";
 import { relativePath } from "./paths.ts";
+import { bytewise } from "./text/compare.ts";
 
 /**
  * Where one declaration is written, as every report renders it.
@@ -87,7 +88,7 @@ export function positionKey(position: Position): string {
  */
 export function byPosition(a: Position, b: Position): number {
   if (a.path !== b.path) {
-    return a.path < b.path ? -1 : 1;
+    return bytewise(a.path, b.path);
   }
   if (a.line !== b.line) {
     return a.line - b.line;