@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.21

package/src/manifest.ts

@@ -1,234 +0,0 @@
-/**
- * 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 or one of its scripts. {@link readManifest} reads one
- * directory's manifest, {@link packageEntries} those of the packages below the target root.
- */
-
-import type { Host } from "./host.ts";
-import { isAbsolutePath, joinPath, relativePath, 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. */
-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. */
-  | "script";
-
-/** 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;
-  /** 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);
-}
-
-/**
- * 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("./");
-}
-
-/** 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.
- */
-function exportTargets(value: unknown, member: string, found: Omit<ManifestEntry, "dir">[]): 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 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.
-   */
-  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 manifest in `targetRoot` declares about where its 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: Omit<ManifestEntry, "dir">[] = [];
-  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);
-
-  const scripts = manifest["scripts"];
-  if (isRecord(scripts)) {
-    for (const [name, command] of Object.entries(scripts)) {
-      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,
-        });
-      }
-    }
-  }
-
-  return {
-    entries: found.map((entry) => ({
-      ...entry,
-      path: resolvePath(targetRoot, entry.path),
-      dir: targetRoot,
-    })),
-    declaresExports: manifest["exports"] !== undefined,
-  };
-}
-
-/**
- * The entry points the manifests of the nested packages in `dirs` name. Each entry is
- * spelled under its manifest's path below the target root, and is published by its own
- * manifest's rule, as the target's own entries are.
- */
-export function packageEntries(
-  host: Host,
-  targetRoot: string,
-  dirs: readonly string[],
-): readonly ManifestEntry[] {
-  return dirs.flatMap((dir) => {
-    const manifest = readManifest(host, dir);
-    const where = `${relativePath(targetRoot, dir) ?? dir}/${MANIFEST}`;
-    return manifest.entries.map((entry) => ({
-      ...entry,
-      member: `${where} ${entry.member}`,
-      published:
-        entry.published && (!manifest.declaresExports || entry.member.startsWith("exports")),
-    }));
-  });
-}

package/src/matrix.ts

@@ -1,423 +0,0 @@
-/**
- * One run's projects as one matrix: every declaration any project holds, keyed by its
- * position and carrying the configurations that hold it, swept once per configuration
- * and intersected, with the dead components computed once over every configuration.
- */
-
-import { componentsOf, type Component, type Positional } from "./components.ts";
-import { graphOf, OUTSIDE, type Graph } from "./graph.ts";
-import type { InventorySymbol } from "./inventory.ts";
-import { byPosition } from "./position.ts";
-import type { Reference } from "./references.ts";
-import type { Root } from "./roots.ts";
-import {
-  reachedWithTheTests,
-  sweep,
-  type Candidate,
-  type Liveness,
-  type Relation,
-  type SweepInput,
-} from "./sweep.ts";
-
-/** What the passes answered for one configuration of the run. */
-export interface Configured {
-  /** The name discovery gives the configuration's project. */
-  readonly configuration: string;
-  readonly symbols: readonly InventorySymbol[];
-  readonly references: readonly Reference[];
-  readonly roots: readonly Root[];
-  /** The paths the reference pass classified as test files. */
-  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;
-  /**
-   * The paths of the workspace-package files the configuration holds but does not
-   * compile itself. Their declarations count in its graph and its verdict on them is no
-   * finding.
-   */
-  readonly referenceOnly?: readonly string[] | undefined;
-  /** Each declaration's dependents, by id, as the configuration's inventory states them. */
-  readonly dependents?: ReadonlyMap<string, readonly string[]> | undefined;
-}
-
-/** The run's configurations, indexed for the sweep. */
-export interface Matrix {
-  /** The configurations, in the run's order. */
-  readonly configurations: readonly string[];
-  /** Per configuration, in the same order, the graph of what that configuration holds. */
-  readonly graphs: readonly Graph[];
-  /**
-   * The graph over every configuration at once: every declaration a configuration
-   * holds in a file it does not hold only for its references, once per position and in
-   * site order, and every reference any configuration makes, a reference several
-   * configurations make at one position counted once.
-   */
-  readonly union: Graph;
-  /**
-   * Per declaration of {@link Matrix.union}, at its position there, the configurations
-   * 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[]>;
-}
-
-/** One declaration dead in every configuration that holds it. */
-export interface MatrixCandidate extends Candidate {
-  /** The configurations the declaration is dead in, which are every one that holds it. */
-  readonly configurations: readonly string[];
-  /**
-   * The declaration of test-support code that test code references, outside the
-   * test-of-dead-code rule, that is or contains this one, the outermost where two do.
-   * Such a declaration is not dead while test code references it, so neither it nor a
-   * declaration it contains is a member of a dead component.
-   */
-  readonly heldByTests: string | undefined;
-  /**
-   * Whether a test file declares it, no test of dead code, and the run that counts test
-   * references does not reach it: it is reported as a production declaration of its
-   * 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. */
-export interface SweepResult {
-  /**
-   * Per declaration, the relations that hold it live in at least one configuration,
-   * reference counting first. A declaration no relation holds live anywhere has no entry.
-   */
-  readonly liveUnder: ReadonlyMap<string, readonly Relation[]>;
-  /** The declarations dead in every configuration that holds them, in site order. */
-  readonly candidates: readonly MatrixCandidate[];
-  /** The dead components, each before every component it reaches, each identifier once per run. */
-  readonly components: readonly Component[];
-}
-
-/**
- * What makes one reference one reference, whichever configuration made it. A consumer's
- * position is rendered against its own root, so the consumer is part of what it names.
- */
-export function referenceKey(reference: Reference): string {
-  const { path, line, column } = reference.position;
-  return [
-    reference.consumer ?? "",
-    reference.from,
-    reference.to,
-    path,
-    String(line),
-    String(column),
-    reference.use,
-  ].join("\u0000");
-}
-
-/**
- * Indexes what the passes answered for each configuration of one run, in the run's order.
- * A declaration is keyed by its rendered position, with the fields of the first
- * configuration that judges it; one in a file every holder holds only for its references
- * is judged by none and is not in the union. One reference at one position of a file
- * several configurations compile is one reference; two one configuration makes are two.
- */
-export function matrixOf(per: readonly Configured[]): Matrix {
-  const symbols: InventorySymbol[] = [];
-  const holders = new Map<string, string[]>();
-  const references: Reference[] = [];
-  const firstSeen = new Map<string, number>();
-  const judged = new Set<string>();
-  const dependents = new Map<string, readonly string[]>();
-  per.forEach((one, index) => {
-    for (const [id, after] of one.dependents ?? []) {
-      if (!dependents.has(id)) {
-        dependents.set(id, after);
-      }
-    }
-    const referenceOnly = new Set(one.referenceOnly);
-    for (const symbol of one.symbols) {
-      const held = holders.get(symbol.id);
-      if (held === undefined) {
-        holders.set(symbol.id, [one.configuration]);
-      } else if (!held.includes(one.configuration)) {
-        held.push(one.configuration);
-      }
-      if (!referenceOnly.has(symbol.position.path) && !judged.has(symbol.id)) {
-        judged.add(symbol.id);
-        symbols.push(symbol);
-      }
-    }
-    for (const reference of one.references) {
-      const key = referenceKey(reference);
-      const seen = firstSeen.get(key);
-      if (seen === undefined) {
-        firstSeen.set(key, index);
-      } else if (seen !== index) {
-        continue;
-      }
-      references.push(reference);
-    }
-  });
-  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),
-    graphs: per.map((one) =>
-      graphOf(one.symbols, one.references, one.roots, one.testFiles, one.supportFiles, one.ambient),
-    ),
-    union: graphOf(
-      symbols,
-      references,
-      per.flatMap((one) => one.roots),
-      [...new Set(per.flatMap((one) => one.testFiles))],
-      [...new Set(per.flatMap((one) => one.supportFiles ?? []))],
-      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,
-  };
-}
-
-/**
- * Answers which declarations of the run are dead in every configuration that holds them.
- *
- * Liveness is a question about one configuration, because a file another configuration
- * does not compile makes no reference there and a root it does not hold seeds nothing
- * there, so each configuration is swept on its own graph under the run's input. A
- * declaration is a candidate when every configuration holding it judged it one: a
- * reference under one configuration is a reference, so what one project uses is never
- * reported, and a configuration that does not hold a declaration says nothing about it.
- * The candidate's relation is reference counting where every configuration found it so,
- * and reachability otherwise; its counts are the union's, one per reference.
- *
- * The components are computed once, over the union and the intersected dead set, so one
- * dead component is one entry of the run with one identifier.
- */
-export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
-  const per = matrix.graphs.map((graph) => sweep(graph, input));
-  const byConfiguration = new Map<string, ReadonlyMap<string, Candidate>>(
-    matrix.configurations.map((configuration, index) => [
-      configuration,
-      new Map((per[index]?.candidates ?? []).map((candidate) => [candidate.id, candidate])),
-    ]),
-  );
-
-  const union = matrix.union;
-  const heldBy: (string | undefined)[] = union.symbols.map(() => undefined);
-  const testReached = reachedWithTheTests(union, [
-    ...input.marked,
-    ...(input.exempt ?? []).map((record) => record.id),
-    ...(input.unanswered ?? []),
-  ]);
-  const judged = 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);
-  });
-  // 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.
-  const subjectsDead = (at: number): boolean =>
-    (union.out[at] ?? []).every(
-      (edge) =>
-        union.test[edge.to] === true ||
-        union.support[edge.to] === true ||
-        union.ambient[edge.to] === true ||
-        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 && testReached[at] === true),
-    judged.map((one) => one !== undefined),
-  );
-  const candidates: MatrixCandidate[] = [];
-  union.symbols.forEach((symbol, at) => {
-    const all = judged[at];
-    if (all === undefined) {
-      return;
-    }
-    const held = matrix.heldIn[at] ?? [];
-    const admitted = admittedAt(at);
-    const testRefs = union.made[at]?.test ?? 0;
-    const heldByTests =
-      heldBy[union.parent[at] ?? OUTSIDE] ??
-      (union.support[at] === true && testRefs > 0 && !admitted ? symbol.id : undefined);
-    const unreferenced = union.test[at] === true && !admitted && testReached[at] !== true;
-    heldBy[at] = heldByTests;
-    const productionRefs = union.made[at]?.production ?? 0;
-    const counted = all.every((candidate) => candidate.relation === "reference-counting");
-    candidates.push({
-      id: symbol.id,
-      productionRefs,
-      testRefs,
-      // The run that judges a test-file declaration counts its test references.
-      relation: (unreferenced ? productionRefs + testRefs === 0 : counted)
-        ? "reference-counting"
-        : "reachability",
-      testOfDeadCode: admitted,
-      configurations: held,
-      heldByTests,
-      unreferencedTest: unreferenced,
-      testUsed: testUsed[at] === true,
-      keptByTests: kept[at] === true,
-    });
-  });
-
-  const liveUnder = liveAnywhere(union.symbols, per);
-  return {
-    liveUnder,
-    candidates,
-    components: deadComponents(matrix, { liveUnder, candidates }, new Set()),
-  };
-}
-
-/** 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
- * dead declaration only its top level references with it.
- */
-export function deadComponents(
-  matrix: Matrix,
-  result: Pick<SweepResult, "liveUnder" | "candidates">,
-  files: ReadonlySet<number>,
-): readonly Component[] {
-  const union = matrix.union;
-  const byId = new Map(result.candidates.map((candidate) => [candidate.id, candidate]));
-  const candidateAt = (at: number): MatrixCandidate | undefined =>
-    byId.get(union.symbols[at]?.id ?? "");
-  return componentsOf(
-    union,
-    union.symbols.map((_symbol, at) => {
-      const candidate = candidateAt(at);
-      return files.has(at) || (candidate !== undefined && candidate.heldByTests === undefined);
-    }),
-    union.symbols.map((_symbol, at) => candidateAt(at)?.testOfDeadCode === true),
-    union.symbols.map((_symbol, at) => candidateAt(at)?.unreferencedTest === true),
-    positionsOf(union, matrix.dependents, result.liveUnder),
-  );
-}
-
-/**
- * The file declarations at `paths`, below the target root, that one sweep holds live
- * under both relations, the rule a judged declaration is live by.
- */
-export function liveFilesAt(
-  matrix: Matrix,
-  result: SweepResult,
-  paths: ReadonlySet<string>,
-): readonly InventorySymbol[] {
-  return matrix.union.symbols.filter(
-    (symbol) =>
-      symbol.kind === "file" &&
-      paths.has(symbol.position.path) &&
-      (result.liveUnder.get(symbol.id)?.length ?? 0) === RELATIONS.length,
-  );
-}
-
-/**
- * Each declaration's dependents by its place in the union, and per place whether the
- * declaration is live under reachability in some configuration.
- */
-function positionsOf(
-  union: Graph,
-  dependents: ReadonlyMap<string, readonly string[]>,
-  liveUnder: ReadonlyMap<string, readonly Relation[]>,
-): Positional {
-  return {
-    dependents: union.symbols.map((symbol) =>
-      (dependents.get(symbol.id) ?? []).map((id) => union.at(id)).filter((at) => at !== OUTSIDE),
-    ),
-    live: union.symbols.map(
-      (symbol) => liveUnder.get(symbol.id)?.includes("reachability") === true,
-    ),
-  };
-}
-
-/** The relations in the order a declaration's entry lists them. */
-const RELATIONS: readonly Relation[] = ["reference-counting", "reachability"];
-
-/**
- * Per declaration, in site order, every relation that holds it live in at least one
- * configuration.
- */
-function liveAnywhere(
-  symbols: readonly InventorySymbol[],
-  per: readonly Liveness[],
-): ReadonlyMap<string, readonly Relation[]> {
-  const live = new Map<string, readonly Relation[]>();
-  for (const symbol of symbols) {
-    const relations = RELATIONS.filter((relation) =>
-      per.some((liveness) => (liveness.liveUnder.get(symbol.id) ?? []).includes(relation)),
-    );
-    if (relations.length > 0) {
-      live.set(symbol.id, relations);
-    }
-  }
-  return live;
-}