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

package/src/{configured-declarations.ts → roots/configured-declarations.ts}

@@ -17,13 +17,13 @@ import {
   type Node,
 } from "@typescript/native/ast";
 import { SymbolFlags, type NodeHandle, type Symbol as TSSymbol } from "@typescript/native/sync";
-import type { AliasChains } from "./alias-chain.ts";
-import { resolvedTargets } from "./calls.ts";
-import type { Config, DeclarationEntry } from "./config.ts";
-import { declaredComponent, type Inventory } from "./inventory.ts";
-import { must, Unanswerable } from "./query.ts";
-import { nameComponent } from "./ref.ts";
-import type { ProjectView } from "./session.ts";
+import type { AliasChains } from "../alias-chain.ts";
+import { resolvedTargets } from "../calls.ts";
+import type { DeclarationEntry, ResolvedConfig } from "../config.ts";
+import { declaredComponent, type Inventory } from "../inventory.ts";
+import { must, Unanswerable } from "../query.ts";
+import { nameComponent } from "../ref.ts";
+import type { ProjectView } from "../session.ts";
 
 /** The meanings a name of the global scope is looked up under: any of them. */
 const ANY_MEANING: SymbolFlags = SymbolFlags.Value | SymbolFlags.Type | SymbolFlags.Namespace;
@@ -204,6 +204,9 @@ function modulesNamed<Brand>(
   project: ProjectView<Brand>,
   specifiers: ReadonlySet<string>,
 ): ReadonlyMap<string, TSSymbol> {
+  if (specifiers.size === 0) {
+    return new Map();
+  }
   const written = new Map<string, Node>();
   for (const file of project.ownSourceFiles()) {
     const visit = (node: Node): void => {
@@ -252,21 +255,21 @@ export function resolveEntries<Brand>(
   }
   const modules = modulesNamed(
     project,
-    new Set(entries.flatMap((entry) => (entry.shape === "module" ? [entry.module] : []))),
+    new Set(entries.flatMap((entry) => ("module" in entry ? [entry.module] : []))),
   );
   return entries.map((entry) => {
-    if (entry.shape === "symbol") {
+    if ("symbol" in entry) {
       return { entry, handles: new Set<string>(), ids: new Set(byRef.get(entry.symbol) ?? []) };
     }
     const { components, static: isStatic } = componentsOf(
-      entry.shape === "module" ? entry.name : entry.global,
+      "module" in entry ? entry.name : entry.global,
     );
     const [first = "", ...rest] = components;
     let start: TSSymbol | undefined;
     if (isStatic && rest.length === 0) {
       // Only a member is static, and a path of one component names no member.
       start = undefined;
-    } else if (entry.shape === "module") {
+    } else if ("module" in entry) {
       const module = modules.get(entry.module);
       start = module === undefined ? undefined : memberOf(project, module, first, false);
     } else if (nameComponent(first) === first) {
@@ -329,14 +332,10 @@ export function entriesAt<Brand>(
  * program the display name the inventory gives it.
  */
 export function spelledEntry(entry: DeclarationEntry, held: Inventory): string {
-  switch (entry.shape) {
-    case "symbol":
-      return held.symbols.find((symbol) => symbol.ref === entry.symbol)?.name ?? entry.symbol;
-    case "module":
-      return entry.name;
-    case "global":
-      return entry.global;
+  if ("symbol" in entry) {
+    return held.symbols.find((symbol) => symbol.ref === entry.symbol)?.name ?? entry.symbol;
   }
+  return "module" in entry ? entry.name : entry.global;
 }
 
 /** One entry of a configuration key that names a declaration, and the key's dotted path. */
@@ -353,14 +352,17 @@ const LIFECYCLE_KEY = "ts.lifecycle_contracts";
  * the injection registrations, each lifecycle contract's components and then its bases,
  * and the serializers.
  */
-export function configuredDeclarations(config: Config): readonly ConfiguredDeclaration[] {
+export function configuredDeclarations(config: ResolvedConfig): readonly ConfiguredDeclaration[] {
   return [
-    ...config.ts.injectionRegistrations.map((entry) => ({
+    ...config.ts.injection_registrations.map((entry) => ({
       key: "ts.injection_registrations",
       entry,
     })),
-    ...config.ts.lifecycleContracts.flatMap((contract) =>
-      [...contract.components, ...contract.bases].map((entry) => ({ key: LIFECYCLE_KEY, entry })),
+    ...config.ts.lifecycle_contracts.flatMap((contract) =>
+      [...(contract.components ?? []), ...(contract.bases ?? [])].map((entry) => ({
+        key: LIFECYCLE_KEY,
+        entry,
+      })),
     ),
     ...config.ts.serializers.map((entry) => ({ key: "ts.serializers", entry })),
   ];
@@ -396,12 +398,8 @@ export function declarationsNamed<Brand>(
  * sign and its name, and a global entry's path after a number sign.
  */
 export function configuredRef(entry: DeclarationEntry): string {
-  switch (entry.shape) {
-    case "symbol":
-      return entry.symbol;
-    case "module":
-      return `${entry.module}#${entry.name}`;
-    case "global":
-      return `#${entry.global}`;
+  if ("symbol" in entry) {
+    return entry.symbol;
   }
+  return "module" in entry ? `${entry.module}#${entry.name}` : `#${entry.global}`;
 }

package/src/{entry-point-gaps.ts → roots/entry-point-gaps.ts}

@@ -1,13 +1,12 @@
 /**
- * Every entry-point convention this analyzer declines, each with the tool it belongs
- * to and why. A file only a declined convention enters is reported as never
- * imported, so a project that relies on one names the file in `ts.entry_files` or
- * `roots.patterns`, and this list is what tells it to.
- *
- * Every row carries a reason, because the list is read where the rows are shown
- * one at a time: beside a finding, or in a report's declared gaps.
+ * Every entry-point convention this analyzer declines, each with its tool and why. A file only
+ * a declined convention enters is reported as never imported, so a project relying on one names
+ * the file in `ts.entry_files` or `roots.patterns`, and this list tells it to. Every row carries
+ * a reason, since rows are shown one at a time, beside a finding or in a report's declared gaps.
  */
 
+import { bytewise } from "../text/compare.ts";
+
 /** One declined entry-point convention. */
 export interface DeclinedConvention {
   /** The tool the convention belongs to, by the name of the package or service. */
@@ -323,16 +322,8 @@ const PARTLY_ENTERED: readonly DeclinedConvention[] = [
   },
 ];
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /** Every declined entry-point convention, ordered by tool and then by convention. */
 export const DECLINED_CONVENTIONS: readonly DeclinedConvention[] = [
   ...UNREAD_TOOLS.map((tool) => ({ tool, convention: EVERY_CONVENTION, reason: UNREAD })),
   ...PARTLY_ENTERED,
-].sort((a, b) => compare(a.tool, b.tool) || compare(a.convention, b.convention));
+].sort((a, b) => bytewise(a.tool, b.tool) || bytewise(a.convention, b.convention));

package/src/roots/manifest.ts

@@ -0,0 +1,303 @@
+/**
+ * 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";
+import { isRecord } from "../json-document.ts";
+import { MANIFEST, manifestAt, readJSON } from "../fs/manifest.ts";
+import type { HeldText } from "../commands/held.ts";
+import { pathsNamed, readCommands } from "../commands/read.ts";
+
+/** The three members that name an entry point beside `exports` and `bin`. */
+const LEGACY_MEMBERS = ["main", "module", "types"] as const;
+
+/** 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 path one of the package's scripts names or runs, or a text layer 3 holds for the package. */
+  | "script";
+
+/** One entry point the manifest names, or one text layer 3 holds for the package. */
+export interface ManifestEntry {
+  /**
+   * 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, or that directory for a held text. */
+  readonly path: string;
+  readonly role: EntryRole;
+  /**
+   * 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;
+  /**
+   * On an entry that names no entry point, whose path is the manifest's directory, the texts
+   * layer 3 reads: a whole command string the package runs, or the values of nodemon's
+   * configuration one is read from. Rooting enters no file for it and holds each file
+   * `spelledFiles` reads their words to name.
+   */
+  readonly held?: readonly HeldText[];
+}
+
+/**
+ * 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)}]`;
+}
+
+/**
+ * The whole text of nodemon's configuration, the manifest's `nodemonConfig` member and the
+ * `nodemon.json` beside it, by the member each is. The dependency rule reads it whole, and
+ * layer 3 each of its values, because nodemon runs commands from keys besides `exec`, `events`
+ * among them: https://github.com/remy/nodemon#config-files
+ */
+export function nodemonTexts(
+  host: Host,
+  dir: string,
+  manifest: Record<string, unknown>,
+): readonly { readonly member: string; readonly text: string }[] {
+  const member = manifest["nodemonConfig"];
+  let file: string | undefined;
+  try {
+    file = host.readFile(joinPath(dir, "nodemon.json"));
+  } catch {
+    file = undefined;
+  }
+  return [
+    ...(member === undefined ? [] : [{ member: "nodemonConfig", text: JSON.stringify(member) }]),
+    ...(file === undefined ? [] : [{ member: "nodemon.json", text: file }]),
+  ];
+}
+
+/**
+ * The texts layer 3 reads of one text of nodemon's configuration: each value of it but its
+ * `exec` command, which is read as a command string of its own, those under `events` read as
+ * command strings too, and the whole text where it does not parse. Its keys are never read.
+ */
+function nodemonValues(text: string): readonly HeldText[] {
+  let config: unknown;
+  try {
+    config = JSON.parse(text);
+  } catch {
+    return [{ text, shell: false }];
+  }
+  const found: HeldText[] = [];
+  const visit = (value: unknown, shell: boolean): void => {
+    if (Array.isArray(value) || isRecord(value)) {
+      for (const one of Object.values(value)) {
+        visit(one, shell);
+      }
+    } else if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      found.push({ text: String(value), shell });
+    }
+  };
+  for (const [key, value] of Object.entries(isRecord(config) ? config : { "": config })) {
+    if (key !== "exec" || typeof value !== "string") {
+      visit(value, key === "events");
+    }
+  }
+  return found;
+}
+
+/**
+ * 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") {
+    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);
+  }
+}
+
+/** What one manifest declares about where its package is entered. */
+export interface Manifest {
+  /**
+   * 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 command string {@link manifestCommands} reads each path `pathsNamed` reads, which
+   * names a file only where one is at it, then one entry of its whole text, and one entry of
+   * each of {@link nodemonTexts}, which are no entry point.
+   */
+  readonly entries: readonly ManifestEntry[];
+  /**
+   * 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;
+}
+
+/**
+ * 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 = manifestAt(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 });
+    }
+  }
+
+  // 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 });
+  } 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);
+
+  for (const { member, command } of manifestCommands(host, targetRoot, manifest)) {
+    // Read against ".", so each path stays relative until the entries are resolved below.
+    for (const path of new Set(pathsNamed(readCommands(command, ".")).map((one) => one.path))) {
+      found.push({ member, path, role: "script", published: false });
+    }
+    found.push({
+      member,
+      path: ".",
+      role: "script",
+      published: false,
+      held: [{ text: command, shell: true, tested: member.startsWith("scripts[") }],
+    });
+  }
+  for (const { member, text } of nodemonTexts(host, targetRoot, manifest)) {
+    const held = nodemonValues(text);
+    if (held.length > 0) {
+      found.push({ member, path: ".", role: "script", published: false, held });
+    }
+  }
+
+  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")),
+    }));
+  });
+}