@cplieger/deadset-ts 2.2.1 → 3.0.0

package/src/graph.ts

@@ -0,0 +1,178 @@
+/**
+ * One project's declarations, the references between them and the roots that seed
+ * reachability, indexed for the sweep. The graph reads no file and asks the compiler
+ * nothing, so a sweep over it is a function of the values it was built from, and the
+ * inventory's order is the order every set a sweep answers reads in.
+ */
+
+import type { InventorySymbol, SymbolKind } from "./inventory.ts";
+import type { Reference } from "./references.ts";
+import type { Root, RootKind } from "./roots.ts";
+
+/** The position of a declaration the inventory does not hold. */
+export const OUTSIDE = -1;
+
+/**
+ * Whether the sweep judges a declaration of each kind. A file is not judged by either
+ * relation: whether a file is built and whether anything imports it are the subjects of
+ * the file kinds, which read the program rather than ask whether anything references the
+ * file. The Contract's finding schema names the kinds that carry no liveness relation,
+ * and a test holds this table to that list.
+ */
+const SWEPT: Readonly<Record<SymbolKind, boolean>> = {
+  file: false,
+  function: true,
+  class: true,
+  interface: true,
+  type: true,
+  enum: true,
+  namespace: true,
+  variable: true,
+  "export-alias": true,
+  method: true,
+  "class-member": true,
+  "interface-method": true,
+  "type-member": true,
+  "enum-member": true,
+  "type-parameter": true,
+};
+
+/**
+ * Whether a root of each kind names a caller, which holds it live under both relations: a
+ * tool reads the configuration it loads, a runtime runs a test file, a setup file and a
+ * worker, and a configured root asserts a caller. The other kinds only suppose a consumer
+ * that imports what a manifest entry, a binary or an entry file exports, or names a
+ * library's published API, so such a root is live under reachability alone.
+ */
+const NAMES_A_CALLER: Readonly<Record<RootKind, boolean>> = {
+  "entry-file": false,
+  "manifest-entry": false,
+  "manifest-binary": false,
+  "published-api": false,
+  configured: true,
+  pattern: true,
+  "test-runner": true,
+  "lint-configuration": true,
+  "mutation-testing": true,
+  "browser-tests": true,
+  worker: true,
+};
+
+/** Whether the sweep judges a declaration of one kind. */
+export function swept(kind: SymbolKind): boolean {
+  return SWEPT[kind];
+}
+
+/** Whether a root of one kind names a caller rather than supposing one. */
+export function namesACaller(kind: RootKind): boolean {
+  return NAMES_A_CALLER[kind];
+}
+
+/** One reference as the sweep reads it: the declaration named, and whether a test file made it. */
+export interface Edge {
+  readonly to: number;
+  readonly test: boolean;
+}
+
+/** How many references one declaration carries, split by the classification of the file that made each. */
+export interface Counts {
+  readonly production: number;
+  readonly test: number;
+}
+
+/** One root the inventory holds, at the position of the declaration it names. */
+export interface Rooted {
+  readonly at: number;
+  readonly kind: RootKind;
+}
+
+/** The index the sweep and the component pass read. */
+export interface Graph {
+  /** The declarations, in the order the inventory returns them. */
+  readonly symbols: readonly InventorySymbol[];
+  /** Per declaration, the references it makes to declarations the inventory holds. */
+  readonly out: readonly (readonly Edge[])[];
+  /** Per declaration, the references made to it, whoever made them. */
+  readonly made: readonly Counts[];
+  /** Per declaration, the position of its container, or {@link OUTSIDE} for a file. */
+  readonly parent: readonly number[];
+  /** Per declaration, whether a test file holds it. */
+  readonly test: readonly boolean[];
+  /** Per declaration, whether the sweep judges its liveness. */
+  readonly subject: readonly boolean[];
+  /**
+   * Per declaration, the declarations its export table names where it is a file, and
+   * nothing for any other declaration. A reference to a file is a reference to the
+   * module's namespace, which reaches everything the module exports.
+   */
+  readonly exportsOf: readonly (readonly number[])[];
+  /** Every root naming a declaration the inventory holds, in the order the root set gives them. */
+  readonly rooted: readonly Rooted[];
+  /** The position of the declaration one identifier names, or {@link OUTSIDE}. */
+  at(id: string): number;
+}
+
+/**
+ * Indexes one project's inventory, references and roots. `testFiles` are the paths the
+ * reference pass classified as test files, so a declaration one holds is a test
+ * declaration. A reference to a declaration the inventory does not hold is dropped; one
+ * from such a declaration still counts toward its target, because reference counting
+ * asks whether any declaration names the target. A root naming nothing is dropped.
+ */
+export function graphOf(
+  symbols: readonly InventorySymbol[],
+  references: readonly Reference[],
+  roots: readonly Root[],
+  testFiles: readonly string[],
+): Graph {
+  const index = new Map(symbols.map((symbol, at) => [symbol.id, at]));
+  const at = (id: string): number => index.get(id) ?? OUTSIDE;
+  const tests = new Set(testFiles);
+
+  const out: Edge[][] = symbols.map(() => []);
+  const made = symbols.map(() => ({ production: 0, test: 0 }));
+  for (const reference of references) {
+    const to = at(reference.to);
+    if (to === OUTSIDE) {
+      continue;
+    }
+    const counts = made[to];
+    if (counts !== undefined) {
+      if (reference.test) {
+        counts.test += 1;
+      } else {
+        counts.production += 1;
+      }
+    }
+    out[at(reference.from)]?.push({ to, test: reference.test });
+  }
+
+  const parent = symbols.map((symbol) => at(symbol.parent));
+  const exportsOf: number[][] = symbols.map(() => []);
+  symbols.forEach((symbol, position) => {
+    const container = parent[position] ?? OUTSIDE;
+    if (symbol.exported && symbols[container]?.kind === "file") {
+      exportsOf[container]?.push(position);
+    }
+  });
+
+  const rooted: Rooted[] = [];
+  for (const root of roots) {
+    const position = at(root.id);
+    if (position !== OUTSIDE) {
+      rooted.push({ at: position, kind: root.kind });
+    }
+  }
+
+  return {
+    symbols,
+    out,
+    made,
+    parent,
+    test: symbols.map((symbol) => tests.has(symbol.position.path)),
+    subject: symbols.map((symbol) => swept(symbol.kind)),
+    exportsOf,
+    rooted,
+    at,
+  };
+}

package/src/index.ts

@@ -1,25 +1,6 @@
 export { run, SETTING_OPTIONS, type Writer } from "./run.ts";
 export type { DirectoryEntry, Host, PathKind } from "./host.ts";
-export {
-  inventory,
-  nodeKey,
-  type Inventory,
-  type InventoryCost,
-  type InventorySymbol,
-  type SymbolKind,
-  type Visibility,
-} from "./inventory.ts";
-export {
-  DEFAULT_BATCH_CAP,
-  references,
-  type Reference,
-  type ReferenceCost,
-  type ReferenceOptions,
-  type References,
-  type Resolution,
-  type TestFileRule,
-  type Use,
-} from "./references.ts";
+export { DECLINED_CONVENTIONS, type DeclinedConvention } from "./entry-point-gaps.ts";
 export {
   byPosition,
   positionKey,

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/print.ts

@@ -20,12 +20,11 @@ export function printConfig(config: Config, provenance: Provenance): string {
       min_confidence: config.analysis.minConfidence,
       generated_files: config.analysis.generatedFiles,
       consumer_tests: config.analysis.consumerTests,
-      configurations: config.analysis.configurations.map((entry) => ({
-        id: entry.id,
-        os: entry.os,
-        arch: entry.arch,
-        tags: entry.tags,
-      })),
+      configurations: config.analysis.configurations.map((entry) =>
+        entry.shape === "project"
+          ? { id: entry.id, project: entry.project }
+          : { id: entry.id, os: entry.os, arch: entry.arch, tags: entry.tags },
+      ),
       matrix: { complete: config.analysis.matrixComplete },
       template_dirs: config.analysis.templateDirs,
       template_delimiters: {