@cplieger/deadset-ts 6.1.1-dev.1 → 7.0.0-dev.1

package/src/conventions.ts

@@ -53,6 +53,7 @@ import {
   type HelperReading,
   type MoveReading,
   type OptionsCall,
+  type PackageKey,
   type ShortNameReading,
 } from "./convention-rows.ts";
 import { documentStrings } from "./configuration-files.ts";
@@ -873,6 +874,60 @@ function helperUses(
     .map((reading) => reading.package);
 }
 
+/**
+ * The dependencies one manifest declares that an applied row's package keys use: each
+ * whose name a string under a member of a key's name equals, or begins followed by `/` or
+ * by `:` and a name. A member's own name is no such string.
+ */
+function packageKeyUses(
+  host: Host,
+  parse: ParseSource,
+  dir: string,
+  manifest: unknown,
+  keys: readonly PackageKey[],
+): readonly string[] {
+  const declared = DEPENDENCY_SECTIONS.flatMap((section) => {
+    const held = isRecord(manifest) ? manifest[section] : undefined;
+    return isRecord(held) ? Object.keys(held) : [];
+  });
+  const strings: string[] = [];
+  const collect = (node: Node): void => {
+    const text = literalText(node);
+    if (text !== undefined) {
+      strings.push(text);
+    } else if (isPropertyAssignment(node)) {
+      collect(node.initializer);
+    } else {
+      node.forEachChild(collect);
+    }
+  };
+  for (const { key, files } of keys) {
+    const visit = (node: Node): void => {
+      if (isPropertyAssignment(node) && keyOf(node) === key) {
+        collect(node.initializer);
+      }
+      node.forEachChild(visit);
+    };
+    for (const { file } of readingFiles(host, parse, dir, files)) {
+      const values = declaredValues(file);
+      for (const one of defaultExports(file)) {
+        const object = objectOf(one, values, true);
+        if (object !== undefined) {
+          visit(object);
+        }
+      }
+    }
+  }
+  return declared.filter((name) =>
+    strings.some(
+      (text) =>
+        text === name ||
+        text.startsWith(`${name}/`) ||
+        (text.startsWith(`${name}:`) && text.length > name.length + 1),
+    ),
+  );
+}
+
 /** Two strings ordered bytewise. */
 function compare(a: string, b: string): number {
   if (a === b) {
@@ -959,6 +1014,10 @@ export function readConventions(
       for (const name of shortNameUses(host, parse, manifest.dir, declared, row.shortNames ?? [])) {
         uses.add(name);
       }
+      const keys = row.packageKeys ?? [];
+      for (const name of packageKeyUses(host, parse, manifest.dir, declared, keys)) {
+        uses.add(name);
+      }
       for (const name of manifestKeyUses(declared, row.manifestKeys ?? [])) {
         uses.add(name);
       }

package/src/dependencies.ts

@@ -1,19 +1,22 @@
 /**
- * The dependencies the target's manifest and its workspace members' manifests declare, and
- * what the projects' own files need from outside the target. A file needs a package it
- * imports, re-exports from, augments or references the types of, by name or through the
- * file the specifier resolves to; a compiler configuration needs one it names, and a
- * configuration file a tool loads needs each dependency its strings spell. A package one
- * dependency pulls in for itself is that dependency's need, not the target's.
+ * The dependencies the target's manifest and its workspace members' manifests declare, and what the
+ * projects' own files need from outside the target. A file needs a package it imports, re-exports
+ * from, augments, references the types of or asks the runtime to resolve, by name or through the
+ * file the specifier resolves to; a compiler configuration needs one it names, and a configuration
+ * file a tool loads needs each dependency its strings spell. A package one dependency pulls in for
+ * itself is that dependency's need, not the target's.
  */
 
 import {
+  isCallExpression,
   isExportDeclaration,
   isExternalModuleReference,
   isIdentifier,
   isImportDeclaration,
   isImportEqualsDeclaration,
+  isMetaProperty,
   isNamespaceExport,
+  isPropertyAccessExpression,
   isShorthandPropertyAssignment,
   isStringLiteral,
   isNoSubstitutionTemplateLiteral,
@@ -32,11 +35,13 @@ import {
 import type { FindingPosition } from "./finding.ts";
 import type { Host } from "./host.ts";
 import { nodeKey, packageScope, type Inventory } from "./inventory.ts";
+import { scriptTokens } from "./manifest.ts";
 import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import type { DependencySection, Module } from "./ref.ts";
 import { UNANSWERED } from "./query.ts";
 import type { Handle, ProjectView } from "./session.ts";
 import { sourceFilesOf } from "./source-files.ts";
+import { workflowTokens } from "./workflow-steps.ts";
 
 const MANIFEST = "package.json";
 const MODULES_DIR = "node_modules";
@@ -68,16 +73,14 @@ export function configurationNeeds(packages: readonly string[]): ProjectNeeds {
   return {
     packages: new Set(packages),
     uses: new Map([[PROJECT_OWNER, new Set(packages)]]),
-    unanswered: false,
+    unanswered: [],
   };
 }
 
 /** What the installed copy of one declared dependency states about itself. */
 export interface InstalledDependency {
-  /** Whether its manifest declares a command. */
-  readonly command: boolean;
-  /** The peer dependencies its manifest requires: every peer not marked optional. */
-  readonly peers: readonly string[];
+  /** The commands its manifest's `bin` declares, by name. */
+  readonly commands: readonly string[];
 }
 
 /** What one project's own files and configuration need from outside the target. */
@@ -91,20 +94,29 @@ export interface ProjectNeeds {
    */
   readonly uses: ReadonlyMap<string, ReadonlySet<string>>;
   /**
-   * Whether the checker left a module specifier unanswered, so the project may use any
-   * dependency the manifest declares.
+   * The files writing a module specifier the checker left unanswered, each of which may
+   * use any dependency a manifest at or above it declares.
    */
-  readonly unanswered: boolean;
+  readonly unanswered: readonly string[];
 }
 
 /** The run's dependency evidence. */
 export interface Dependencies {
   /** Every declared dependency, manifest by manifest, in the order each writes them. */
   readonly declared: readonly DeclaredDependency[];
-  /** The installed copy of each declared dependency the run found, by name. */
-  readonly installed: ReadonlyMap<string, InstalledDependency>;
   /** Every package some project needs. */
   readonly needed: ReadonlySet<string>;
+  /**
+   * The declared dependencies whose command a script entry of the manifest declaring them,
+   * or a workflow step for the target's manifest, runs, each by {@link declarationKey}.
+   */
+  readonly ran: ReadonlySet<string>;
+  /**
+   * The manifests, by their path below the target root, whose directory holds source only
+   * in configurations the run could not build, so a dependency they declare that nothing
+   * needs is reported at `possible`.
+   */
+  readonly unbuilt: ReadonlySet<string>;
   /**
    * Per deletion candidate, the declared dependencies whose last use in the target is
    * written inside it, sorted bytewise; a candidate holding no last use has no entry.
@@ -325,9 +337,11 @@ export function projectNeeds<Brand>(
   };
   use([PROJECT_OWNER], packages);
 
-  let unanswered = false;
+  const unanswered: string[] = [];
   for (const file of project.ownSourceFiles()) {
-    unanswered = fileNeeds(project, held, file, programPackages, use) || unanswered;
+    if (fileNeeds(project, held, file, programPackages, use)) {
+      unanswered.push(file.fileName);
+    }
   }
 
   const beside = new Map<string, readonly string[]>();
@@ -491,9 +505,43 @@ function fileNeeds<Brand>(
   for (const reference of file.typeReferenceDirectives) {
     use(ownersOf(file, held, file), typePackages(reference.fileName, programPackages));
   }
+  for (const specifier of resolvedSpecifiers(file)) {
+    const named = packageOfSpecifier(specifier.text);
+    if (named !== undefined) {
+      use(ownersOf(file, held, specifier), [named]);
+    }
+  }
   return resolved.slice(0, specifiers.length).includes(UNANSWERED);
 }
 
+/**
+ * The literal specifiers one file asks the runtime to resolve, through `import.meta.resolve`
+ * or `require.resolve`, each of which needs the package it names installed.
+ */
+function resolvedSpecifiers(file: SourceFile): readonly Texted[] {
+  const found: Texted[] = [];
+  if (!file.text.includes(".resolve(")) {
+    return found;
+  }
+  const visit = (node: Node): void => {
+    if (isCallExpression(node) && isPropertyAccessExpression(node.expression)) {
+      const callee = node.expression;
+      const [argument] = node.arguments;
+      const receiver = callee.expression;
+      const resolving =
+        callee.name.text === "resolve" &&
+        ((isMetaProperty(receiver) && receiver.name.text === "meta") ||
+          (isIdentifier(receiver) && receiver.text === "require"));
+      if (resolving && argument !== undefined && isLiteralText(argument)) {
+        found.push(argument);
+      }
+    }
+    node.forEachChild(visit);
+  };
+  visit(file);
+  return found;
+}
+
 /** The offset just past the JSON value that starts at `at` in text the parser has accepted. */
 function valueEnd(text: string, at: number): number {
   const first = text.charAt(at);
@@ -585,21 +633,17 @@ function installedOf(host: Host, root: string, name: string): InstalledDependenc
   for (let dir = root; ; dir = dirnamePath(dir)) {
     const read = readJSON(host, joinPath(dir, MODULES_DIR, name, MANIFEST));
     if (read !== undefined && isRecord(read.value)) {
-      const manifest = read.value;
-      const bin = manifest["bin"];
-      const peers = manifest["peerDependencies"];
-      const meta = isRecord(manifest["peerDependenciesMeta"])
-        ? manifest["peerDependenciesMeta"]
-        : {};
+      const bin = read.value["bin"];
+      // A string `bin` names one command, the package's name without its scope.
       return {
-        command:
-          (typeof bin === "string" && bin !== "") || (isRecord(bin) && Object.keys(bin).length > 0),
-        peers: isRecord(peers)
-          ? Object.keys(peers).filter((peer) => {
-              const about = meta[peer];
-              return !(isRecord(about) && about["optional"] === true);
-            })
-          : [],
+        commands:
+          typeof bin === "string"
+            ? bin === ""
+              ? []
+              : [name.slice(name.indexOf("/") + 1)]
+            : isRecord(bin)
+              ? Object.keys(bin)
+              : [],
       };
     }
     if (dirnamePath(dir) === dir) {
@@ -639,12 +683,37 @@ function declaredIn(
   return declared.sort((a, b) => a.at - b.at).map(({ dependency }) => dependency);
 }
 
+/** The key one declared dependency is known by: its manifest's path and its name. */
+export function declarationKey(dependency: DeclaredDependency): string {
+  return `${dependency.position.path}\u0000${dependency.name}`;
+}
+
+/** Every token of every value of one manifest's `scripts` member. */
+function scriptTokensOf(manifest: Record<string, unknown>): ReadonlySet<string> {
+  const scripts = manifest["scripts"];
+  const found = new Set<string>();
+  if (isRecord(scripts)) {
+    for (const command of Object.values(scripts)) {
+      if (typeof command === "string") {
+        scriptTokens(command).forEach((token) => found.add(token));
+      }
+    }
+  }
+  return found;
+}
+
+/** Whether a path below the target root lies in the directory `dir` below it, `""` being the root. */
+function isInside(path: string, dir: string): boolean {
+  return dir === "" || path.startsWith(`${dir}/`);
+}
+
 /**
  * The run's dependency evidence: the target's manifest and each workspace member's in
  * `members` below the target root, read with the position of every dependency each
- * declares, the installed copy of each found from its manifest's directory, what the
- * projects need, and the last uses each deletion candidate holds. A manifest the
- * program cannot read declares nothing.
+ * declares, what the projects and the commands its scripts and workflow steps run need,
+ * and the last uses each deletion candidate holds. A member in `unbuilt` holds source only
+ * in configurations the run could not build. A manifest the program cannot read declares
+ * nothing.
  */
 export function dependenciesOf(
   host: Host,
@@ -652,30 +721,43 @@ export function dependenciesOf(
   perProject: readonly ProjectNeeds[],
   candidates: readonly string[],
   members: readonly string[] = [],
+  unbuiltMembers: readonly string[] = [],
 ): Dependencies {
   const root = resolvePath(host.workingDirectory(), targetRoot);
   const scopeOf = packageScope(host, targetRoot);
   const manifests = new Map<string, string>([[root, MANIFEST]]);
-  for (const dir of members) {
+  const unbuilt = new Set<string>();
+  for (const dir of [...members, ...unbuiltMembers]) {
     const below = relativePath(root, dir);
     if (below !== undefined && !manifests.has(dir)) {
       manifests.set(dir, `${below}/${MANIFEST}`);
     }
   }
+  for (const dir of unbuiltMembers) {
+    const path = manifests.get(dir);
+    if (path !== undefined && dir !== root) {
+      unbuilt.add(path);
+    }
+  }
+  const workflow = new Set(workflowTokens(host, targetRoot));
   const declared: DeclaredDependency[] = [];
-  const installed = new Map<string, InstalledDependency>();
+  const ran = new Set<string>();
   for (const [dir, path] of manifests) {
     const read = readJSON(host, joinPath(dir, MANIFEST));
     if (read === undefined || !isRecord(read.value)) {
       continue;
     }
+    const tokens = scriptTokensOf(read.value);
     for (const dependency of declaredIn(read.text, read.value, path, scopeOf(path))) {
       declared.push(dependency);
-      if (!installed.has(dependency.name)) {
-        const found = installedOf(host, dir, dependency.name);
-        if (found !== undefined) {
-          installed.set(dependency.name, found);
-        }
+      const found = installedOf(host, dir, dependency.name);
+      if (found === undefined) {
+        continue;
+      }
+      const runs = (command: string): boolean =>
+        tokens.has(command) || (dir === root && workflow.has(command));
+      if (found.commands.some(runs)) {
+        ran.add(declarationKey(dependency));
       }
     }
   }
@@ -685,9 +767,15 @@ export function dependenciesOf(
   const needed = new Set<string>();
   const uses = new Map<string, Set<string>>();
   for (const project of perProject) {
-    // A specifier the checker left unanswered may resolve to any declared dependency,
-    // and what the configuration needs is never deleted, so it is needed there.
-    const unknown = project.unanswered ? declared.map((dependency) => dependency.name) : [];
+    // A specifier the checker left unanswered may resolve to any dependency a manifest at
+    // or above its file declares, and what the configuration needs is never deleted.
+    const unanswered = project.unanswered.flatMap((file) => relativePath(root, file) ?? []);
+    const unknown = declared
+      .filter((dependency) => {
+        const dir = dirnamePath(dependency.position.path);
+        return unanswered.some((file) => isInside(file, dir === "." ? "" : dir));
+      })
+      .map((dependency) => dependency.name);
     const held = unknown.length === 0 ? [] : [[PROJECT_OWNER, new Set(unknown)] as const];
     for (const [id, used] of [...project.uses, ...held]) {
       const merged = uses.get(id) ?? new Set<string>();
@@ -711,5 +799,5 @@ export function dependenciesOf(
       );
     }
   }
-  return { declared, installed, needed, lastUses };
+  return { declared, needed, ran, unbuilt, lastUses };
 }

package/src/finding.ts

@@ -83,6 +83,8 @@ export interface Finding {
   readonly message: string;
   /** Absent where the code carries nothing. */
   readonly details?: FindingDetails;
+  /** The reachability class of a subject that is no declaration, where it is not `certain`. */
+  readonly reachabilityClass?: Confidence;
 }
 
 /** The dead component a finding names, as the finding schema spells its members. */

package/src/findings/completion.ts

@@ -136,12 +136,11 @@ function findingComponents(
 
 /**
  * Every finding of the run completed, in the order given. A dead declaration carries its
- * candidate's relation, counts, configurations and component; a live one carries no
- * relation and holds where it is declared; a file or a manifest row is `certain` and
- * holds in every configuration. A subject in no dead component gets one of its own,
- * numbered past the computed ones in finding order, so no two families mint one; nothing
- * falls with it, so its deletion removes no line. `kinds` is the vocabulary each code's
- * row is read from, the shipped one unless a caller supplies its own.
+ * candidate's relation, counts, configurations and component; a live one carries no relation and
+ * holds where it is declared; a file or a manifest row carries the class its emitter states,
+ * `certain` by default, and holds in every configuration. A subject in no dead component gets one
+ * of its own, numbered past the computed ones in finding order so no two families mint one, whose
+ * deletion removes no line. `kinds` defaults to the shipped vocabulary.
  */
 export function completed(
   input: EmitterInput,
@@ -210,7 +209,8 @@ export function completed(
       candidate === undefined
         ? union.made[at]
         : { production: candidate.productionRefs, test: candidate.testRefs };
-    const reachabilityClass = judged === undefined ? "certain" : classOf(judged.id);
+    const reachabilityClass =
+      judged === undefined ? (finding.reachabilityClass ?? "certain") : classOf(judged.id);
     const generated = input.files.generated?.has(finding.position.path) === true;
     return {
       code: finding.code,

package/src/findings/dependencies-and-module-machinery.ts

@@ -1,4 +1,4 @@
-import type { Dependencies } from "../dependencies.ts";
+import { declarationKey, type Dependencies } from "../dependencies.ts";
 import type { Finding } from "../finding.ts";
 import { renderRef, type DependencySection } from "../ref.ts";
 import type { Emitter } from "./emitter.ts";
@@ -11,39 +11,17 @@ const MESSAGES: Readonly<Record<DependencySection, string>> = {
   "peer-dependency": "no import in the target needs the declared peer dependency",
 };
 
-/**
- * The dependencies the target needs: every package the projects' uses name, every
- * declared dependency that ships a command, which a script, a workflow or a shell
- * runs outside anything the analysis reads, and every peer a needed package
- * requires, which the target satisfies by declaring it.
- */
-function neededBy(dependencies: Dependencies): ReadonlySet<string> {
-  const needed = new Set(dependencies.needed);
-  for (const [name, installed] of dependencies.installed) {
-    if (installed.command) {
-      needed.add(name);
-    }
-  }
-  const pending = [...needed];
-  for (let name = pending.pop(); name !== undefined; name = pending.pop()) {
-    for (const peer of dependencies.installed.get(name)?.peers ?? []) {
-      if (!needed.has(peer)) {
-        needed.add(peer);
-        pending.push(peer);
-      }
-    }
-  }
-  return needed;
-}
-
 /**
  * A dependency, development dependency or peer dependency of a manifest the run reads
  * that the target does not need, at the position of its key.
  */
 function unusedDependencies(dependencies: Dependencies): Finding[] {
-  const needed = neededBy(dependencies);
   return dependencies.declared
-    .filter((dependency) => !needed.has(dependency.name))
+    .filter(
+      (dependency) =>
+        !dependencies.needed.has(dependency.name) &&
+        !dependencies.ran.has(declarationKey(dependency)),
+    )
     .map((dependency) => ({
       code: UNUSED_DEPENDENCY,
       position: dependency.position,
@@ -59,6 +37,9 @@ function unusedDependencies(dependencies: Dependencies): Finding[] {
       },
       message: MESSAGES[dependency.section],
       details: { dependencyClass: dependency.section },
+      ...(dependencies.unbuilt.has(dependency.position.path)
+        ? { reachabilityClass: "possible" as const }
+        : {}),
     }));
 }
 

package/src/html-entries.ts

@@ -1,6 +1,7 @@
 /**
- * The files the module scripts of the target's HTML files load. An HTML file is read as
- * text and no markup is parsed, so a `<script>` inside a comment is read as well.
+ * The files the scripts of the target's HTML files load: a module script's, and a
+ * classic script's that names its file by `src`. An HTML file is read as text and no
+ * markup is parsed, so a `<script>` inside a comment is read as well.
  */
 
 import {
@@ -14,7 +15,7 @@ import type { Host } from "./host.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import type { SourceFiles } from "./source-files.ts";
 
-/** One file a module script loads, and the value or specifier that named it. */
+/** One file a script loads, and the value or specifier that named it. */
 export interface HTMLEntry {
   readonly file: SourceFile;
   readonly source: string;
@@ -35,6 +36,9 @@ const ATTRIBUTE = /([^\s"'=<>/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)
 /** A value that names a resource on another origin, or by another scheme. */
 const ELSEWHERE = /^(?:\/\/|[A-Za-z][A-Za-z\d+.-]*:)/u;
 
+/** The `type` values a classic script carries, compared in lowercase. */
+const CLASSIC_TYPES: ReadonlySet<string> = new Set(["text/javascript", "application/javascript"]);
+
 /** The prefixes an inline script's specifier names a file of the target with. */
 const FILE_PREFIXES = ["/", "./", "../"] as const;
 
@@ -85,18 +89,22 @@ function specifiersOf(parse: ParseFile, fileName: string, content: string): read
 }
 
 /**
- * Every value a module script of one HTML file names a file by: a `src` attribute's
- * value, or each specifier an inline script imports or re-exports that starts with `/`,
- * `./` or `../`.
+ * Every value a script of one HTML file names a file by: the `src` attribute's value of a
+ * module script or of a classic one, or each specifier an inline module script imports or
+ * re-exports that starts with `/`, `./` or `../`.
  */
 function scriptValues(parse: ParseFile | undefined, path: string, text: string): readonly string[] {
   const values: string[] = [];
   for (const match of text.matchAll(SCRIPT_TAG)) {
     const held = attributes(match[1] ?? "");
-    if (held.get("type") !== "module") {
+    const type = held.get("type");
+    const src = held.get("src");
+    if (type !== "module") {
+      if (src !== undefined && (type === undefined || CLASSIC_TYPES.has(type.toLowerCase()))) {
+        values.push(src);
+      }
       continue;
     }
-    const src = held.get("src");
     if (src !== undefined) {
       values.push(src);
       continue;
@@ -131,11 +139,11 @@ function manifestDirectory(host: Host, root: string, dir: string): string {
 }
 
 /**
- * The own files the module scripts of every HTML file below the target root load. A value
+ * The own files the scripts of every HTML file below the target root load. A value
  * starting with a single `/` is read against the nearest manifest's directory, any other
- * against the HTML file's own, and either resolves as a configuration file's relative
- * specifier does. A value naming another origin or scheme, or no source file of the
- * program, loads nothing here.
+ * against the HTML file's own, as a configuration file's relative specifier. One naming no
+ * source file is read back through the project's emit mapping, and a `/` one also against
+ * an output directory that is the HTML file's own. Another origin or scheme loads nothing.
  */
 export function htmlEntries(
   host: Host,
@@ -157,12 +165,22 @@ export function htmlEntries(
       if (ELSEWHERE.test(value)) {
         continue;
       }
-      const reached = value.startsWith("/")
-        ? resolveRelativeSpecifier(host, manifestDirectory(host, root, dir), `.${value}`)
-        : resolveRelativeSpecifier(host, dir, value);
+      const base = value.startsWith("/") ? manifestDirectory(host, root, dir) : dir;
+      const relative = value.startsWith("/") ? `.${value}` : value;
+      const reached = resolveRelativeSpecifier(host, base, relative);
       const file = reached === undefined ? undefined : files.byName.get(reached);
       if (file !== undefined) {
         found.push({ file, source: value });
+        continue;
+      }
+      const served = value.startsWith("/")
+        ? files.outputDirs.filter((outDir) => outDir === dir)
+        : [];
+      const emitting = [base, ...served].flatMap((against) =>
+        files.named(resolvePath(against, relative)),
+      );
+      for (const one of new Set(emitting)) {
+        found.push({ file: one, source: value });
       }
     }
   }