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

package/src/components.ts

@@ -37,12 +37,31 @@ export interface Component {
    * cycle with a live container is one, so a component has at least one.
    */
   readonly roots: readonly string[];
-  /** The source lines one deletion of the component removes: the distinct lines its members span. */
+  /**
+   * The source lines one deletion of the component removes: the distinct lines its
+   * members span, and none for a component of held declarations.
+   */
   readonly deletableLines: number;
+  /**
+   * Whether its members are held declarations, which no mechanical edit deletes: a dead
+   * declaration whose deletion changes a live declaration's value, and every dead
+   * declaration such a one references or whose deletion would change its value.
+   */
+  readonly held: boolean;
+}
+
+/**
+ * What the held-declaration rule reads of a graph, by place: the places of the later
+ * declarations whose value each one's deletion changes, and whether reachability holds
+ * each one live in some configuration.
+ */
+export interface Positional {
+  readonly dependents: readonly (readonly number[])[];
+  readonly live: readonly boolean[];
 }
 
 /** What a report carries for one dead component under one cascade mode. */
-export interface Listing {
+interface Listing {
   readonly roots: readonly string[];
   /** Every member under the full mode, and nothing under the default one. */
   readonly members: readonly string[];
@@ -63,41 +82,97 @@ export function listing(component: Component, cascade: Cascade): Listing {
 /**
  * Groups the declarations `dead` marks into components, ordered by their first member's
  * site; `dead`, `testOfDeadCode` and `unreferencedTest` hold one flag per declaration of
- * the graph. Root members sit on the cycles no other cycle references. A cycle two roots
- * both reach is dead only through both, so a component is a weakly connected part of the
- * dead subgraph: no dead declaration of one references a declaration of another.
+ * the graph. Root members sit on the cycles no other cycle references. A component is a
+ * weakly connected part of the dead subgraph, because a cycle two roots reach is dead only
+ * through both. The held declarations `positional` decides form components of their own,
+ * and a dead declaration that is not held shares one with each of its dead dependents.
  */
 export function componentsOf(
   graph: Graph,
   dead: readonly boolean[],
   testOfDeadCode: readonly boolean[],
   unreferencedTest: readonly boolean[] = [],
+  positional: Positional = { dependents: [], live: [] },
 ): readonly Component[] {
-  const { at, adjacent } = deadSubgraph(graph, dead, testOfDeadCode, unreferencedTest);
+  const { at, position, adjacent, references } = deadSubgraph(
+    graph,
+    dead,
+    testOfDeadCode,
+    unreferencedTest,
+  );
   if (at.length === 0) {
     return [];
   }
-  const { componentOf, members } = connected(adjacent);
-  const referenced = referencedCycles(adjacent, componentOf, members.length);
-  const groups = joined(adjacent);
-  const idOf = (position: number): string => graph.symbols[at[position] ?? 0]?.id ?? "";
+  const dependents = at.map((index) =>
+    (positional.dependents[index] ?? []).map((to) => ({
+      to: position[to] ?? UNVISITED,
+      live: positional.live[to] === true,
+    })),
+  );
+  const held = heldSet(dependents, references);
+  const kept = adjacent.map((targets, from) => targets.filter((to) => held[to] === held[from]));
+  const { componentOf, members } = connected(kept);
+  const referenced = referencedCycles(kept, componentOf, members.length);
+  const groups = joined(
+    kept.map((targets, from) => [
+      ...targets,
+      ...(held[from] === true
+        ? []
+        : (dependents[from] ?? []).flatMap(({ to }) =>
+            to === UNVISITED || held[to] === true ? [] : [to],
+          )),
+    ]),
+  );
+  const idOf = (place: number): string => graph.symbols[at[place] ?? 0]?.id ?? "";
 
   return groups.map((group, place) => {
-    const roots = group.filter((position) => {
+    const roots = group.filter((one) => {
       // A dead member's dead container is on the member's own cycle, and the container
       // is where the deletion starts.
-      const container = graph.parent[at[position] ?? 0] ?? OUTSIDE;
-      return referenced[componentOf[position] ?? 0] !== true && dead[container] !== true;
+      const container = graph.parent[at[one] ?? 0] ?? OUTSIDE;
+      return referenced[componentOf[one] ?? 0] !== true && dead[container] !== true;
     });
+    const isHeld = group.every((one) => held[one] === true);
     return {
       id: componentId(place + 1),
       members: group.map(idOf),
       roots: roots.map(idOf),
-      deletableLines: linesSpanned(group.map((position) => graph.symbols[at[position] ?? 0])),
+      deletableLines: isHeld ? 0 : linesSpanned(group.map((one) => graph.symbols[at[one] ?? 0])),
+      held: isHeld,
     };
   });
 }
 
+/**
+ * Per place of the dead subgraph, whether the declaration is held: one with a live
+ * dependent, and each dead declaration a held one references or has as a dependent,
+ * until no further one joins.
+ */
+function heldSet(
+  dependents: readonly (readonly { readonly to: number; readonly live: boolean }[])[],
+  references: readonly (readonly number[])[],
+): readonly boolean[] {
+  const held = dependents.map((after) => after.some((one) => one.live));
+  const before: number[][] = dependents.map(() => []);
+  dependents.forEach((after, from) => {
+    for (const { to } of after) {
+      if (to !== UNVISITED) {
+        before[to]?.push(from);
+      }
+    }
+  });
+  const pending = held.flatMap((one, place) => (one ? [place] : []));
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    for (const reached of [...(references[next] ?? []), ...(before[next] ?? [])]) {
+      if (held[reached] !== true) {
+        held[reached] = true;
+        pending.push(reached);
+      }
+    }
+  }
+  return held;
+}
+
 /**
  * The distinct source lines a set of declarations spans, each declaration at least the
  * line it starts on. A member written inside its container's span adds no line, because
@@ -133,19 +208,24 @@ function linesSpanned(symbols: readonly (InventorySymbol | undefined)[]): number
 }
 
 /**
- * The dead declarations by their place in the subgraph, a test file's declaration only
- * where it is a test of dead code or nothing the tests reach, and the edges between them:
- * each reference one makes to another, except an unreferenced test-file declaration's
- * reference to production code, which decides nothing of its target, an edge each way
- * between a dead member and its dead container, and an edge back from each production
- * target of an admitted test, which puts the test in its subject's component.
+ * The dead declarations by subgraph place (`at`, and `position` per graph declaration),
+ * a test file's only where it tests dead code or nothing the tests reach. `adjacent` holds
+ * each reference one makes to another, except an unreferenced test-file declaration's to
+ * production code, which decides nothing of its target; an edge each way between a dead
+ * member and its dead container; and one back from each production target of an admitted
+ * test, which puts the test in its subject's component. `references` holds the first alone.
  */
 function deadSubgraph(
   graph: Graph,
   dead: readonly boolean[],
   testOfDeadCode: readonly boolean[],
   unreferencedTest: readonly boolean[],
-): { readonly at: readonly number[]; readonly adjacent: readonly (readonly number[])[] } {
+): {
+  readonly at: readonly number[];
+  readonly position: readonly number[];
+  readonly adjacent: readonly (readonly number[])[];
+  readonly references: readonly (readonly number[])[];
+} {
   const at: number[] = [];
   const position = graph.symbols.map((_symbol, index) => {
     const judged = testOfDeadCode[index] === true || unreferencedTest[index] === true;
@@ -156,6 +236,7 @@ function deadSubgraph(
     return at.length - 1;
   });
   const adjacent: number[][] = at.map(() => []);
+  const references: number[][] = at.map(() => []);
   at.forEach((index, from) => {
     for (const edge of graph.out[index] ?? []) {
       const to = position[edge.to] ?? UNVISITED;
@@ -163,6 +244,7 @@ function deadSubgraph(
         continue;
       }
       adjacent[from]?.push(to);
+      references[from]?.push(to);
       if (
         testOfDeadCode[index] === true &&
         graph.test[edge.to] !== true &&
@@ -177,7 +259,7 @@ function deadSubgraph(
       adjacent[container]?.push(from);
     }
   });
-  return { at, adjacent };
+  return { at, position, adjacent, references };
 }
 
 /** One frame of the component walk: a declaration, and the next of its edges to follow. */

package/src/config.ts

@@ -50,7 +50,7 @@ export type Cascade = "roots" | "full";
  * tags in effect. It is the shape a language built under build constraints reads,
  * and this analyzer leaves it to that analysis.
  */
-export interface PlatformConfiguration {
+interface PlatformConfiguration {
   readonly shape: "platform";
   readonly id: string;
   readonly os: string;
@@ -97,7 +97,7 @@ export interface Analysis {
 }
 
 /** How findings are rendered. */
-export interface Reporters {
+interface Reporters {
   readonly formats: readonly Format[];
   readonly sort: Sort;
   readonly cascade: Cascade;
@@ -154,7 +154,7 @@ export type Provider =
     };
 
 /** The analyzers the orchestrator runs. */
-export interface Providers {
+interface Providers {
   readonly analyzers: readonly Provider[];
 }
 
@@ -293,7 +293,7 @@ export interface Inputs {
 }
 
 /** Which refusal a {@link ConfigError} carries. */
-export type ErrorKind =
+type ErrorKind =
   /**
    * A document that is not one JSON instance of the closed key list: a syntax
    * error, a value of the wrong type, a value outside the closed set a key

package/src/configuration-files.ts

@@ -69,11 +69,19 @@ export const RESOLVED_EXTENSIONS = [
   ".cjs",
 ] as const;
 
+/** The directory a package manager installs packages into, whose files are no project's own. */
+const MODULES_DIR = "node_modules";
+
 /** The file's name, the last segment of its path. */
 function basename(path: string): string {
   return path.slice(path.lastIndexOf("/") + 1);
 }
 
+/** Whether one path is the project's own: below the target root and in no `node_modules`. */
+function isProjectPath(root: string, path: string): boolean {
+  return relativePath(root, path)?.split("/").includes(MODULES_DIR) === false;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -92,6 +100,8 @@ export function isConfigurationDocumentName(name: string): boolean {
 interface ConfigurationDocument {
   /** The file, absolute. */
   readonly path: string;
+  /** The directories of the manifests whose dependencies the strings are read against. */
+  readonly manifestDirs: readonly string[];
   /** Every string value at any depth, in document order; a member's name is no value. */
   readonly strings: readonly string[];
 }
@@ -100,11 +110,169 @@ interface ConfigurationDocument {
 export type ParseFile = (fileName: string, text: string) => SourceFile;
 
 /** One file no program holds that a configuration module outside the program leads to. */
-export interface OutsideModule {
+interface OutsideModule {
   /** The file, parsed alone. */
   readonly file: SourceFile;
-  /** The directory of the configuration module the file was reached from, which holds its manifest. */
-  readonly manifestDir: string;
+  /** The directories of the manifests of the configuration files the file was reached from. */
+  readonly manifestDirs: readonly string[];
+}
+
+/** The flags a tool's command line names its configuration file with. */
+const CONFIG_FLAGS: ReadonlySet<string> = new Set(["--config", "-c"]);
+
+/** The extensions of a module a configuration flag may name. */
+const MODULE_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"] as const;
+
+/** The characters that end a word outside quotes and separate nothing: blanks. */
+const BLANK = /[ \t\r\f\v]/u;
+
+/** The characters that end a word outside quotes and begin an operator: newline included. */
+const OPERATOR = /[\n;&|()<>]/u;
+
+/** The characters a backslash escapes inside double quotes; before any other it stands for itself. */
+const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
+
+/**
+ * The words of one command line, as POSIX token recognition reads quotes, backslashes,
+ * line continuations, comments and operators. A word an expansion may change (an unquoted
+ * `$`, backquote, glob character or leading `~`, or a `$` or backquote in double quotes)
+ * is computed, and so is the rest of a line whose quote is never closed. A computed word
+ * and each operator are undefined, so a flag's file is never read across them.
+ */
+function shellWords(command: string): readonly (string | undefined)[] {
+  const words: (string | undefined)[] = [];
+  let word: string | undefined;
+  let computed = false;
+  const end = (): void => {
+    if (word !== undefined) {
+      words.push(computed ? undefined : word);
+    }
+    word = undefined;
+    computed = false;
+  };
+  for (let at = 0; at < command.length; at += 1) {
+    const char = command.charAt(at);
+    if (char === "\\" && command.charAt(at + 1) === "\n") {
+      at += 1;
+    } else if (BLANK.test(char)) {
+      end();
+    } else if (OPERATOR.test(char)) {
+      end();
+      words.push(undefined);
+    } else if (char === "#" && word === undefined) {
+      const newline = command.indexOf("\n", at);
+      at = newline < 0 ? command.length : newline - 1;
+    } else if (char === "\\") {
+      at += 1;
+      word = (word ?? "") + command.charAt(at);
+    } else if (char === "'" || char === '"') {
+      const close = closingQuote(command, at);
+      if (close < 0) {
+        word ??= "";
+        computed = true;
+        break;
+      }
+      const quoted =
+        char === "'"
+          ? { text: command.slice(at + 1, close), computed: false }
+          : doubleQuoted(command.slice(at + 1, close));
+      word = (word ?? "") + quoted.text;
+      computed ||= quoted.computed;
+      at = close;
+    } else {
+      computed ||= /[$`*?[]/u.test(char) || (char === "~" && word === undefined);
+      word = (word ?? "") + char;
+    }
+  }
+  end();
+  return words;
+}
+
+/** The text between one pair of double quotes, unescaped, and whether an expansion may change it. */
+function doubleQuoted(inner: string): { readonly text: string; readonly computed: boolean } {
+  let text = "";
+  let computed = false;
+  for (let at = 0; at < inner.length; at += 1) {
+    const char = inner.charAt(at);
+    const next = inner.charAt(at + 1);
+    if (char === "\\" && next === "\n") {
+      at += 1;
+    } else if (char === "\\" && DOUBLE_QUOTE_ESCAPES.has(next)) {
+      text += next;
+      at += 1;
+    } else {
+      computed ||= char === "$" || char === "`";
+      text += char;
+    }
+  }
+  return { text, computed };
+}
+
+/** The index of the quote that closes the one at `open`, or -1 where none does. */
+function closingQuote(command: string, open: number): number {
+  const quote = command.charAt(open);
+  for (let at = open + 1; at < command.length; at += 1) {
+    const char = command.charAt(at);
+    if (char === quote) {
+      return at;
+    }
+    if (quote === '"' && char === "\\") {
+      at += 1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * The files the scripts of the manifest in one directory name after a configuration flag,
+ * `--config <file>`, `-c <file>` or `--config=<file>`, each a JSON file or a module below
+ * the target root and in no `node_modules`.
+ */
+function scriptConfigurations(host: Host, root: string, dir: string): readonly string[] {
+  let scripts: unknown;
+  try {
+    const manifest: unknown = JSON.parse(host.readFile(joinPath(dir, MANIFEST)));
+    scripts = isRecord(manifest) ? manifest["scripts"] : undefined;
+  } catch {
+    return [];
+  }
+  if (!isRecord(scripts)) {
+    return [];
+  }
+  const found: string[] = [];
+  for (const command of Object.values(scripts)) {
+    if (typeof command !== "string") {
+      continue;
+    }
+    const words = shellWords(command);
+    words.forEach((word, at) => {
+      const named =
+        word !== undefined && CONFIG_FLAGS.has(word)
+          ? words[at + 1]
+          : word === undefined
+            ? undefined
+            : /^--config=(.+)$/su.exec(word)?.[1];
+      const path = named === undefined ? undefined : resolvePath(dir, named);
+      if (
+        path !== undefined &&
+        [".json", ...MODULE_EXTENSIONS].some((extension) => path.endsWith(extension)) &&
+        isProjectPath(root, path) &&
+        host.kindOf(path) === "file"
+      ) {
+        found.push(path);
+      }
+    });
+  }
+  return found;
+}
+
+/** The decoded value of one JSON file, or undefined where it cannot be read or parsed. */
+function readDocument(host: Host, path: string): unknown {
+  try {
+    return JSON.parse(host.readFile(path)) as unknown;
+  } catch {
+    return undefined;
+  }
 }
 
 /** The configuration files one project holds and sits beside. */
@@ -117,7 +285,12 @@ interface ConfigurationFiles {
    * the program does not hold either, read where a parser is given.
    */
   readonly outside: readonly OutsideModule[];
-  /** Every JSON configuration file in a directory of the project's files or above one. */
+  /**
+   * Every JSON configuration file in a directory of the project's files or above one, every
+   * JSON file a script's configuration flag names, and every JSON file below the target
+   * root and in no `node_modules` a relative string of either names, read against each
+   * manifest whose chain reaches it.
+   */
   readonly documents: readonly ConfigurationDocument[];
 }
 
@@ -187,7 +360,8 @@ export function configurationFiles(
     }
   }
 
-  const documents: ConfigurationDocument[] = [];
+  const pending: { path: string; manifestDir: string }[] = [];
+  const named: { path: string; manifestDir: string }[] = [];
   for (const dir of [...dirs].sort()) {
     if (!holdsManifest(dir)) {
       continue;
@@ -200,24 +374,59 @@ export function configurationFiles(
         .map((entry) => entry.name)
         .sort();
     } catch {
+      names = [];
+    }
+    pending.push(...names.map((name) => ({ path: joinPath(dir, name), manifestDir: dir })));
+    for (const path of scriptConfigurations(host, root, dir)) {
+      const held = files.byName.get(path);
+      if (path.endsWith(".json")) {
+        pending.push({ path, manifestDir: dir });
+      } else if (held !== undefined) {
+        modules.push({ file: held, form: "a script's configuration flag" });
+      } else {
+        named.push({ path, manifestDir: dir });
+      }
+    }
+  }
+
+  // A document reached from two manifests is read against each, so a chain is keyed by both.
+  const documents = new Map<string, { path: string; manifestDirs: string[]; strings: string[] }>();
+  const unreadable = new Set<string>();
+  for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+    let document = documents.get(next.path);
+    if (unreadable.has(next.path) || document?.manifestDirs.includes(next.manifestDir) === true) {
       continue;
     }
-    for (const name of names) {
-      const path = joinPath(dir, name);
-      let value: unknown;
-      try {
-        value = JSON.parse(host.readFile(path));
-      } catch {
+    if (document === undefined) {
+      const value = readDocument(host, next.path);
+      if (value === undefined) {
+        unreadable.add(next.path);
         continue;
       }
-      documents.push({ path, strings: documentStrings(value) });
+      document = { path: next.path, manifestDirs: [], strings: documentStrings(value) };
+      documents.set(next.path, document);
+    }
+    document.manifestDirs.push(next.manifestDir);
+    for (const text of document.strings) {
+      const path = RELATIVE_PREFIXES.some((prefix) => text.startsWith(prefix))
+        ? resolvePath(dirnamePath(next.path), text)
+        : undefined;
+      if (
+        path?.endsWith(".json") === true &&
+        isProjectPath(root, path) &&
+        host.kindOf(path) === "file"
+      ) {
+        pending.push({ path, manifestDir: next.manifestDir });
+      }
     }
   }
   return {
     modules,
-    documents,
+    documents: [...documents.values()],
     outside:
-      parse === undefined ? [] : outsideModules(host, [...dirs], files, holdsManifest, parse),
+      parse === undefined
+        ? []
+        : outsideModules(host, root, [...dirs], files, holdsManifest, parse, named),
   };
 }
 
@@ -271,17 +480,19 @@ export function resolveRelativeSpecifier(
 
 /**
  * The configuration modules of the directories that hold a manifest which the program
- * does not hold, and the files they import by a relative specifier, until no further
- * file joins. A file that cannot be read is skipped.
+ * does not hold, and the project files below `root` they import by a relative specifier,
+ * until no further file joins. A file that cannot be read is skipped.
  */
 function outsideModules(
   host: Host,
+  root: string,
   dirs: readonly string[],
   files: SourceFiles,
   holdsManifest: (dir: string) => boolean,
   parse: ParseFile,
+  named: readonly { readonly path: string; readonly manifestDir: string }[],
 ): readonly OutsideModule[] {
-  const pending: { path: string; manifestDir: string }[] = [];
+  const pending: { path: string; manifestDir: string }[] = [...named];
   for (const dir of [...dirs].sort()) {
     if (!holdsManifest(dir)) {
       continue;
@@ -298,29 +509,37 @@ function outsideModules(
     }
     pending.push(...names.map((name) => ({ path: joinPath(dir, name), manifestDir: dir })));
   }
-  const found: OutsideModule[] = [];
-  const seen = new Set<string>();
+  const found = new Map<string, { file: SourceFile; manifestDirs: string[] }>();
+  const unreadable = new Set<string>();
   for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
-    if (seen.has(next.path) || files.byName.has(next.path)) {
+    let outside = found.get(next.path);
+    if (
+      unreadable.has(next.path) ||
+      files.byName.has(next.path) ||
+      outside?.manifestDirs.includes(next.manifestDir) === true
+    ) {
       continue;
     }
-    seen.add(next.path);
-    let text: string;
-    try {
-      text = host.readFile(next.path);
-    } catch {
-      continue;
+    if (outside === undefined) {
+      let text: string;
+      try {
+        text = host.readFile(next.path);
+      } catch {
+        unreadable.add(next.path);
+        continue;
+      }
+      outside = { file: parse(next.path, text), manifestDirs: [] };
+      found.set(next.path, outside);
     }
-    const file = parse(next.path, text);
-    found.push({ file, manifestDir: next.manifestDir });
-    for (const specifier of relativeSpecifiers(file)) {
+    outside.manifestDirs.push(next.manifestDir);
+    for (const specifier of relativeSpecifiers(outside.file)) {
       const reached = resolveRelativeSpecifier(host, dirnamePath(next.path), specifier);
-      if (reached !== undefined) {
+      if (reached !== undefined && isProjectPath(root, reached)) {
         pending.push({ path: reached, manifestDir: next.manifestDir });
       }
     }
   }
-  return found;
+  return [...found.values()];
 }
 
 /** Every dependency the manifest in one directory declares, or none where it holds none to read. */

package/src/conformance-record.ts

@@ -4,7 +4,7 @@ export const RECORD = {
   conformance: {
     corpusVersion: "5.0.0",
     result: "pass",
-    digest: "sha256:26c486907df44fb8eaf3f749f60a6010ac94e7cfeeda70c4aa406445193ab80a",
+    digest: "sha256:c46c7d06b6f0c58504c5f311870efefc0b85f18c2c46ba7d7b722081cb370c0c",
   },
   gaps: [],
 } as const;