@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.10

package/src/fs/manifest.ts

@@ -0,0 +1,92 @@
+import type { Host } from "../host.ts";
+import { isRecord } from "../json-document.ts";
+import { joinPath } from "../paths.ts";
+import { message } from "../product.ts";
+
+/** The file a package's manifest is read from. */
+export const MANIFEST = "package.json";
+
+/** The directory a package manager installs packages into, whose files are no project's own. */
+export const INSTALLED_PACKAGES = "node_modules";
+
+/** The manifest members a package declares the packages it depends on under. */
+export const DEPENDENCY_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const;
+
+/** Whether one path passes through an installed-packages directory. */
+export function inInstalledPackages(path: string): boolean {
+  return path.split("/").includes(INSTALLED_PACKAGES);
+}
+
+/** One JSON file's text and decoded value, or undefined where it cannot be read or parsed. */
+export function readDocument(
+  host: Host,
+  path: string,
+): { text: string; value: unknown } | undefined {
+  let text: string;
+  try {
+    text = host.readFile(path);
+  } catch {
+    return undefined;
+  }
+  try {
+    return { text, value: JSON.parse(text) as unknown };
+  } catch {
+    return undefined;
+  }
+}
+
+/** One JSON file's decoded value, or undefined where it cannot be read or parsed. */
+export function readJSON(host: Host, path: string): unknown {
+  return readDocument(host, path)?.value;
+}
+
+/**
+ * The manifest in one directory, decoded, or undefined where none reads as an object. A
+ * manifest this program cannot read declares nothing, the same answer as an absent one:
+ * the package manager owns the refusal of a manifest it rejects.
+ */
+export function manifestAt(host: Host, dir: string): Record<string, unknown> | undefined {
+  const value = readJSON(host, joinPath(dir, MANIFEST));
+  return isRecord(value) ? value : undefined;
+}
+
+/**
+ * What one directory's manifest reads as: none, an object, a file that does not parse as one,
+ * or a file that cannot be read, with the read's error. Either of the last two still bounds
+ * the package it would declare.
+ */
+export type ManifestRead =
+  | { readonly kind: "absent" }
+  | { readonly kind: "read"; readonly manifest: Record<string, unknown> }
+  | { readonly kind: "malformed" }
+  | { readonly kind: "unread"; readonly reason: string };
+
+/** The manifest in one directory, as {@link ManifestRead} tells its states apart. */
+export function readManifestAt(host: Host, dir: string): ManifestRead {
+  if (!holdsManifest(host, dir)) {
+    return { kind: "absent" };
+  }
+  let text: string;
+  try {
+    text = host.readFile(joinPath(dir, MANIFEST));
+  } catch (error: unknown) {
+    return { kind: "unread", reason: message(error) };
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return { kind: "malformed" };
+  }
+  return isRecord(value) ? { kind: "read", manifest: value } : { kind: "malformed" };
+}
+
+/** Whether one directory holds a manifest file. */
+export function holdsManifest(host: Host, dir: string): boolean {
+  return host.kindOf(joinPath(dir, MANIFEST)) === "file";
+}

package/src/fs/tree.ts

@@ -0,0 +1,110 @@
+import type { DirectoryEntry, Host } from "../host.ts";
+import { ancestors, joinPath, resolvePath } from "../paths.ts";
+import { LANGUAGE_ROWS } from "../contract/contract.generated.ts";
+import { LANGUAGE } from "../product.ts";
+import { bytewise } from "../text/compare.ts";
+import { globExpression } from "../text/glob.ts";
+
+/** The directories no walk of the tree enters, by the patterns the language's row names. */
+const SKIPPED_DIRECTORIES = LANGUAGE_ROWS[LANGUAGE].skippedDirectories.map(globExpression);
+
+function skipped(name: string): boolean {
+  return SKIPPED_DIRECTORIES.some((pattern) => pattern.test(name));
+}
+
+/** A git repository's working tree root, and the `info/exclude` file git reads for it. */
+interface Repository {
+  readonly root: string;
+  /** Undefined where a `.git` file names no repository directory. */
+  readonly exclude: string | undefined;
+}
+
+/** One file's text without its line ending, or undefined where it cannot be read. */
+function lineOf(host: Host, path: string): string | undefined {
+  try {
+    return host.readFile(path).replace(/\r?\n$/u, "");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The repository whose working tree holds `dir`: the nearest directory at or above it with a
+ * `.git`. A `.git` file, which a linked worktree or a submodule holds, names the repository's
+ * directory on its `gitdir:` line; that directory's `commondir` file, where it has one, names
+ * the directory shared with the main worktree, which holds `info/exclude`:
+ * https://git-scm.com/docs/gitrepository-layout
+ */
+export function repositoryOf(host: Host, dir: string): Repository | undefined {
+  for (const root of ancestors(dir)) {
+    const dotGit = joinPath(root, ".git");
+    const kind = host.kindOf(dotGit);
+    if (kind === "directory") {
+      return { root, exclude: joinPath(dotGit, "info/exclude") };
+    }
+    if (kind === "file") {
+      const named = /^gitdir: (.+)$/u.exec(lineOf(host, dotGit) ?? "")?.[1];
+      const gitDir = named === undefined ? undefined : resolvePath(root, named);
+      const common = gitDir === undefined ? undefined : lineOf(host, joinPath(gitDir, "commondir"));
+      const shared =
+        gitDir === undefined || common === undefined ? gitDir : resolvePath(gitDir, common);
+      return { root, exclude: shared === undefined ? undefined : joinPath(shared, "info/exclude") };
+    }
+  }
+  return undefined;
+}
+
+/** The entries of one directory, none where it cannot be read. */
+export function entriesOf(host: Host, dir: string): readonly DirectoryEntry[] {
+  try {
+    return host.readDirectory(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** The names of the files directly in `dir` whose name `accepts`, in bytewise order. */
+export function filesIn(
+  host: Host,
+  dir: string,
+  accepts: (name: string) => boolean,
+): readonly string[] {
+  return entriesOf(host, dir)
+    .filter((entry) => !entry.directory && accepts(entry.name))
+    .map((entry) => entry.name)
+    .sort(bytewise);
+}
+
+/** The names of the directories directly in `dir` a walk enters, in bytewise order. */
+export function directoriesIn(host: Host, dir: string): readonly string[] {
+  return entriesOf(host, dir)
+    .filter((entry) => entry.directory && !skipped(entry.name))
+    .map((entry) => entry.name)
+    .sort(bytewise);
+}
+
+/**
+ * Every file below `root` whose name `accepts`, by its path relative to `root` in bytewise
+ * order, read in no skipped directory.
+ */
+export function filesBelow(
+  host: Host,
+  root: string,
+  accepts: (name: string) => boolean,
+): readonly string[] {
+  const found: string[] = [];
+  const pending = [""];
+  for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
+    for (const entry of entriesOf(host, joinPath(root, dir))) {
+      const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+      if (!entry.directory) {
+        if (accepts(entry.name)) {
+          found.push(path);
+        }
+      } else if (!skipped(entry.name)) {
+        pending.push(path);
+      }
+    }
+  }
+  return found.sort(bytewise);
+}

package/src/generated-file.ts

@@ -1,11 +1,12 @@
 /**
  * The generated-file class on TypeScript: every declaration in a file that marks itself
- * generated, or below a directory an applied convention row names as generated, is
- * retained, because a generator owns the file and a deletion there is undone at the next
+ * generated, below a directory an applied convention row names as generated, or minified,
+ * is retained, because a generator owns the file and a deletion there is undone at the next
  * generation.
  */
 
 import type { DetectorInput, Evidence } from "./exempt.ts";
+import { minified } from "./javascript-file.ts";
 import type { SourceFiles } from "./source-files.ts";
 
 /** The generated-code header, matched against each line of a leading comment. */
@@ -14,6 +15,15 @@ const HEADER_LINE = /^\/\/ Code generated .* DO NOT EDIT\.$/u;
 /** The documentation tag `@generated` as a word of a comment. */
 const GENERATED_TAG = /(?<![\w@$])@generated(?![\w$-])/u;
 
+/** A first comment naming the tool that wrote the file. */
+const GENERATED_BY = /^\/\/ Generated by \S/u;
+
+/** The word a generator's notice holds, beside one of {@link KEEP_OUT}. */
+const GENERATED_WORD = /\bgenerated\b/iu;
+
+/** The phrases a generator's notice asks a reader not to edit the file by. */
+const KEEP_OUT = /\b(?:do not edit|will be overwritten|should not make any changes)\b/iu;
+
 /** The comments before a text's first token, a leading hashbang line skipped. */
 function leadingComments(text: string): readonly string[] {
   const comments: string[] = [];
@@ -53,13 +63,20 @@ export function generatedByComment(text: string): string | undefined {
   if (comments.some((one) => GENERATED_TAG.test(one))) {
     return "generated by the @generated tag its leading comments hold";
   }
+  const notice = comments.join("\n");
+  if (
+    GENERATED_BY.test(comments[0] ?? "") ||
+    (GENERATED_WORD.test(notice) && KEEP_OUT.test(notice))
+  ) {
+    return "generated by the notice its leading comments hold";
+  }
   return undefined;
 }
 
 /**
  * Every own file of one project that is generated, by its path below the target root,
  * with the detail a retention in it names: its leading comments' mark, else the row
- * naming its directory as generated.
+ * naming its directory as generated, else its minified text.
  */
 export function generatedFilesOf(
   files: SourceFiles,
@@ -71,7 +88,9 @@ export function generatedFilesOf(
     const detail =
       generatedByComment(file.text) ??
       (row === undefined
-        ? undefined
+        ? minified(file.fileName, file.text)
+          ? "generated as a minified JavaScript file"
+          : undefined
         : `generated below a directory the convention row ${row} names`);
     if (detail !== undefined) {
       found.set(path, detail);

package/src/git-ignore.ts

@@ -0,0 +1,122 @@
+/**
+ * Which files git ignores below a tree's root, read as git reads its ignore files:
+ * https://git-scm.com/docs/gitignore#_pattern_format
+ */
+
+import type { Host } from "./host.ts";
+import { ancestors, dirnamePath, joinPath, relativePath } from "./paths.ts";
+import { message } from "./product.ts";
+import { gitignoreExpression } from "./text/glob.ts";
+import { repositoryOf } from "./fs/tree.ts";
+
+/** One pattern line of an ignore file. */
+interface Rule {
+  readonly negated: boolean;
+  /** Whether the pattern ends with `/`, so it matches a directory alone. */
+  readonly directoryOnly: boolean;
+  /** The expression over a path below the file's own directory. */
+  readonly expression: RegExp;
+}
+
+/** The rules one ignore file's text writes, in order. */
+function rulesOf(text: string): readonly Rule[] {
+  const rules: Rule[] = [];
+  for (const raw of text.split(/\r?\n/u)) {
+    let line = raw.replace(/(?<!\\)\s+$/u, "");
+    if (line === "" || line.startsWith("#")) {
+      continue;
+    }
+    const negated = line.startsWith("!");
+    line = negated ? line.slice(1) : line;
+    const directoryOnly = line.endsWith("/");
+    line = line.replace(/\/+$/u, "");
+    if (line === "") {
+      continue;
+    }
+    // A separator at the start or in the middle anchors the pattern to the file's
+    // directory; with none, the pattern matches at any depth below it.
+    const anchored = line.includes("/");
+    const pattern = line.replace(/^\//u, "");
+    rules.push({
+      negated,
+      directoryOnly,
+      expression: gitignoreExpression(anchored ? pattern : `**/${pattern}`),
+    });
+  }
+  return rules;
+}
+
+/** Told each ignore file that exists and cannot be read, with why. */
+type UnreadIgnoreFile = (path: string, reason: string) => void;
+
+function rulesIn(host: Host, path: string, unread: UnreadIgnoreFile): readonly Rule[] {
+  try {
+    return rulesOf(host.readFile(path));
+  } catch (error: unknown) {
+    if (host.kindOf(path) !== "absent") {
+      unread(path, message(error));
+    }
+    return [];
+  }
+}
+
+/**
+ * Whether git ignores one absolute path below `root`: by the repository's `info/exclude`, then
+ * the `.gitignore` files from its root down to the path's directory, a later pattern overriding
+ * an earlier one, though a file below an ignored directory stays ignored, as git cannot re-include
+ * it. A path outside `root` is not ignored. With no repository, the files at and below `root` are
+ * read; with one, the directories above `root` give patterns but are not tested. An unreadable
+ * ignore file ignores nothing, and `unread` is told it.
+ */
+export function gitIgnored(
+  host: Host,
+  root: string,
+  unread: UnreadIgnoreFile = () => undefined,
+): (path: string) => boolean {
+  const found = repositoryOf(host, root);
+  const repository = found?.root;
+  const above =
+    repository === undefined ? [] : [...ancestors(dirnamePath(root), repository)].reverse();
+  const excluded = found?.exclude === undefined ? [] : rulesIn(host, found.exclude, unread);
+  const read = new Map<string, readonly Rule[]>();
+  const rulesAt = (dir: string): readonly Rule[] => {
+    let rules = read.get(dir);
+    if (rules === undefined) {
+      rules = rulesIn(host, joinPath(dir, ".gitignore"), unread);
+      read.set(dir, rules);
+    }
+    return rules;
+  };
+  const decided = (path: string, directory: boolean): boolean => {
+    const sources: [string, readonly Rule[]][] = [
+      ...(repository === undefined ? [] : [[repository, excluded] as [string, readonly Rule[]]]),
+      ...[...above, ...[...ancestors(dirnamePath(path), root)].reverse()].map(
+        (dir): [string, readonly Rule[]] => [dir, rulesAt(dir)],
+      ),
+    ];
+    let ignored = false;
+    for (const [dir, rules] of sources) {
+      const below = relativePath(dir, path) ?? "";
+      for (const rule of rules) {
+        if ((directory || !rule.directoryOnly) && rule.expression.test(below)) {
+          ignored = !rule.negated;
+        }
+      }
+    }
+    return ignored;
+  };
+  return (path) => {
+    const below = relativePath(root, path);
+    if (below === undefined) {
+      return false;
+    }
+    const parts = below.split("/");
+    for (let count = 1; count <= parts.length; count += 1) {
+      const at = joinPath(root, parts.slice(0, count).join("/"));
+      if (decided(at, count < parts.length)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}

package/src/graph.ts

@@ -41,9 +41,9 @@ const SWEPT: Readonly<Record<SymbolKind, boolean>> = {
  * Whether a root of each kind names a caller, which holds it live under both relations: a
  * tool reads what it loads and what its strings name, a runtime runs a test, setup or
  * worker file, a page's module script, a command, a script or a workflow step, the manifest
- * names what enters the package, an alias global stands for its export, and an entry file,
- * a configured root and a pattern assert a caller. A library's published API only supposes
- * an unseen consumer, so it is live under reachability alone.
+ * names what enters the package, an alias global stands for its export, an outside
+ * declaration names a global interface merging into it, and an entry file, a configured root
+ * and a pattern assert a caller. A published API supposes a consumer: reachability alone.
  */
 const NAMES_A_CALLER: Readonly<Record<RootKind, boolean>> = {
   "entry-file": true,
@@ -56,13 +56,17 @@ const NAMES_A_CALLER: Readonly<Record<RootKind, boolean>> = {
   pattern: true,
   "type-error": true,
   "type-query-alias": true,
+  "global-augmentation": true,
   "configuration-file": true,
   "configuration-string": true,
+  "bundler-entry": true,
   "test-runner": true,
   "browser-tests": true,
   worker: true,
   "html-entry": true,
   "workflow-step": true,
+  "computed-import": true,
+  "document-import": true,
 };
 
 /** Whether the sweep judges a declaration of one kind. */
@@ -112,6 +116,8 @@ export interface Graph {
   readonly test: readonly boolean[];
   /** Per declaration, whether a test-support file holds it. */
   readonly support: readonly boolean[];
+  /** Per declaration, whether it is ambient, describing code the target does not implement. */
+  readonly ambient: readonly boolean[];
   /** Per declaration, whether the sweep judges its liveness. */
   readonly subject: readonly boolean[];
   /**
@@ -145,6 +151,7 @@ export function graphOf(
   roots: readonly Root[],
   testFiles: readonly string[],
   supportFiles: readonly string[] = [],
+  ambient: ReadonlySet<string> = new Set(),
 ): Graph {
   const supports = new Set(supportFiles);
   const index = new Map(symbols.map((symbol, at) => [symbol.id, at]));
@@ -199,6 +206,7 @@ export function graphOf(
     parent,
     test: symbols.map((symbol) => tests.has(symbol.position.path)),
     support: symbols.map((symbol) => supports.has(symbol.position.path)),
+    ambient: symbols.map((symbol) => ambient.has(symbol.id)),
     subject: symbols.map((symbol) => swept(symbol.kind)),
     exportsOf,
     rooted,

package/src/host.ts

@@ -1,5 +1,5 @@
-/** What one path names. */
-export type PathKind = "file" | "directory" | "absent";
+/** What one path names: `"other"` is anything else there, a named pipe, a device or a socket. */
+export type PathKind = "file" | "directory" | "other" | "absent";
 
 /** One entry of a directory. */
 export interface DirectoryEntry {
@@ -8,24 +8,27 @@ export interface DirectoryEntry {
 }
 
 /**
- * The platform one run reads: the filesystem, the directory relative paths
- * resolve against, and the version of the package this analyzer was installed
- * from.
- *
- * It is a parameter rather than an import because a published module that reads
- * the filesystem directly carries the whole platform's type surface into every
- * consumer's compile, and because the run's own reads are then the one thing a
- * caller can watch. The command line binds it to the platform it runs on; nothing
- * under this module does.
+ * The platform one run reads: the filesystem, the working directory and the analyzer's
+ * installed version. A run may keep what it reads for the host's life, so a caller whose
+ * tree changes passes a new host. It is a parameter, not an import, so a published module
+ * carries no platform type surface into a consumer's compile and a caller can watch the
+ * run's reads. The command line binds it to the platform; nothing under this module does.
  */
 export interface Host {
   /** The directory a relative path resolves against. */
   workingDirectory(): string;
-  /** The text of one file, or a throw naming why it cannot be read. */
-  readFile(path: string): string;
+  /**
+   * The text of one file, or a throw naming why it cannot be read. Given `limit`, the
+   * text of no more than the file's first `limit` bytes, so a caller bounding a document
+   * asks for one byte past its bound and never holds a larger file whole.
+   */
+  readFile(path: string, limit?: number): string;
   /** The entries of one directory, or a throw naming why it cannot be read. */
   readDirectory(path: string): readonly DirectoryEntry[];
-  /** What one path names, `"absent"` where nothing is there. */
+  /**
+   * What one path names once every symbolic link along it is followed, `"absent"` where
+   * nothing is there, or a throw naming why it cannot be known, as for a link loop.
+   */
   kindOf(path: string): PathKind;
   /**
    * The path one path names once every symbolic link along it is followed, or a throw

package/src/html-entries.ts

@@ -12,8 +12,10 @@ import {
 } from "@typescript/native/ast";
 import { resolveRelativeSpecifier, type ParseFile } from "./configuration-files.ts";
 import type { Host } from "./host.ts";
-import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import { ancestors, dirnamePath, joinPath, resolvePath } from "./paths.ts";
 import type { SourceFiles } from "./source-files.ts";
+import { filesBelow } from "./fs/tree.ts";
+import { holdsManifest } from "./fs/manifest.ts";
 
 /** One file a script loads, and the value or specifier that named it. */
 interface HTMLEntry {
@@ -21,9 +23,6 @@ interface HTMLEntry {
   readonly source: string;
 }
 
-/** The directory no HTML file is read below. */
-const SKIPPED = "node_modules";
-
 /** A `<script` start tag, its attribute text captured. */
 const SCRIPT_TAG = /<script(?=[\s>/])([^>]*)>/giu;
 
@@ -42,28 +41,6 @@ const CLASSIC_TYPES: ReadonlySet<string> = new Set(["text/javascript", "applicat
 /** The prefixes an inline script's specifier names a file of the target with. */
 const FILE_PREFIXES = ["/", "./", "../"] as const;
 
-/** Every HTML file below `dir`, outside every `node_modules` directory, by absolute path. */
-function htmlFiles(host: Host, dir: string): readonly string[] {
-  let entries;
-  try {
-    entries = host.readDirectory(dir);
-  } catch {
-    return [];
-  }
-  const found: string[] = [];
-  for (const entry of entries) {
-    const path = joinPath(dir, entry.name);
-    if (entry.directory) {
-      if (entry.name !== SKIPPED) {
-        found.push(...htmlFiles(host, path));
-      }
-    } else if (entry.name.endsWith(".html")) {
-      found.push(path);
-    }
-  }
-  return found.sort();
-}
-
 /** Each attribute of one start tag's attribute text, by its lowercase name. */
 function attributes(text: string): ReadonlyMap<string, string> {
   const found = new Map<string, string>();
@@ -127,12 +104,7 @@ function scriptValues(parse: ParseFile | undefined, path: string, text: string):
 
 /** The directory of the nearest `package.json` at or above `dir`, inside `root`, else `root`. */
 function manifestDirectory(host: Host, root: string, dir: string): string {
-  for (let at = dir; relativePath(root, at) !== undefined; at = dirnamePath(at)) {
-    if (host.kindOf(joinPath(at, "package.json")) === "file") {
-      return at;
-    }
-  }
-  return root;
+  return ancestors(dir, root).find((at) => holdsManifest(host, at)) ?? root;
 }
 
 /**
@@ -150,7 +122,8 @@ export function htmlEntries(
 ): readonly HTMLEntry[] {
   const root = resolvePath(host.workingDirectory(), targetRoot);
   const found: HTMLEntry[] = [];
-  for (const path of htmlFiles(host, root)) {
+  for (const below of filesBelow(host, root, (name) => name.endsWith(".html"))) {
+    const path = joinPath(root, below);
     let text: string;
     try {
       text = host.readFile(path);