@cplieger/deadset-ts 8.0.0-dev.6 → 8.0.0-dev.8

package/src/text/compare.ts

@@ -0,0 +1,27 @@
+/**
+ * Two strings in the order of their UTF-8 bytes, the order every set of a run is read in.
+ * That is code point order, which UTF-16 code unit order (`<` on strings) breaks above
+ * U+FFFF: a surrogate unit is below U+E000 while the code point it encodes is above U+FFFF.
+ */
+export function bytewise(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  const length = Math.min(a.length, b.length);
+  for (let at = 0; at < length; at += 1) {
+    const x = a.charCodeAt(at);
+    const y = b.charCodeAt(at);
+    if (x !== y) {
+      return ranked(x) < ranked(y) ? -1 : 1;
+    }
+  }
+  return a.length < b.length ? -1 : 1;
+}
+
+/** One UTF-16 unit moved so that a surrogate ranks above every unit of U+E000 to U+FFFF. */
+function ranked(unit: number): number {
+  if (unit >= 0xe000) {
+    return unit - 0x800;
+  }
+  return unit >= 0xd800 ? unit + 0x2000 : unit;
+}

package/src/text/glob.ts

@@ -0,0 +1,210 @@
+/**
+ * Glob patterns over paths in two forms. The configured form (the configuration, convention
+ * rows, bundler entries, workspace member patterns) has `*` and `?` within a segment, `**`
+ * across segments and brace lists. A `.gitignore` line has git's form: bracket expressions
+ * and backslash escapes, no brace lists (https://git-scm.com/docs/gitignore#_pattern_format).
+ * A configured root is not a glob: it names a symbol reference, and is read where it is used.
+ */
+
+type GlobForm = "configured" | "gitignore";
+
+/**
+ * One character of a pattern as the expression syntax reads it literally. The set escaped
+ * is closed: under the unicode flag an escape of any other character is refused outright.
+ */
+function quoted(character: string): string {
+  return /[.*+?^${}()|[\]\\/]/u.test(character) ? `\\${character}` : character;
+}
+
+/**
+ * The ASCII ranges each POSIX class a bracket expression may name holds, as git's own
+ * character table reads them, each range written as its first and last character.
+ */
+const CLASSES: ReadonlyMap<string, string> = new Map([
+  ["alnum", "09AZaz"],
+  ["alpha", "AZaz"],
+  ["blank", "\t\t  "],
+  ["cntrl", "\0\x1f\x7f\x7f"],
+  ["digit", "09"],
+  ["graph", "!~"],
+  ["lower", "az"],
+  ["print", " ~"],
+  ["punct", "!/:@[`{~"],
+  ["space", "\t\n\r\r  "],
+  ["upper", "AZ"],
+  ["xdigit", "09AFaf"],
+]);
+
+/** What a pattern git cannot read matches: nothing, as git aborts the whole match. */
+const NOTHING = "(?!)";
+
+/** One code point as a member of an expression class. */
+function member(point: number): string {
+  return `\\u{${point.toString(16)}}`;
+}
+
+/**
+ * The class a bracket expression opening at `open` denotes, and the index past its `]`,
+ * read as git's wildmatch reads it: a leading `!` or `^` negates it, a `]` first is a
+ * member, `\` escapes one character, `x-y` is a range (one whose `y` is below `x` holds
+ * `x` alone) and `[:name:]` a POSIX class. An unclosed bracket or an unknown class name
+ * matches nothing. Neither form matches the solidus.
+ */
+function bracket(pattern: string, open: number): { source: string; end: number } {
+  let at = open + 1;
+  const negated = pattern[at] === "!" || pattern[at] === "^";
+  if (negated) {
+    at += 1;
+  }
+  const next = (): number | undefined => {
+    const point = pattern.codePointAt(at);
+    at += point !== undefined && point > 0xffff ? 2 : 1;
+    return point;
+  };
+  let members = "";
+  let low: number | undefined;
+  for (let first = true; ; first = false) {
+    let point = next();
+    if (point === undefined) {
+      return { source: NOTHING, end: pattern.length };
+    }
+    if (point === 0x5d && !first) {
+      return { source: negated ? `[^/${members}]` : `(?!/)[${members}]`, end: at };
+    }
+    if (point === 0x2d && low !== undefined && at < pattern.length && pattern[at] !== "]") {
+      let high = next();
+      if (high === 0x5c) {
+        high = next();
+      }
+      if (high === undefined) {
+        return { source: NOTHING, end: pattern.length };
+      }
+      members += high >= low ? `${member(low)}-${member(high)}` : "";
+      low = undefined;
+      continue;
+    }
+    if (point === 0x5b && pattern[at] === ":") {
+      const close = pattern.indexOf("]", at + 1);
+      if (close < 0) {
+        return { source: NOTHING, end: pattern.length };
+      }
+      if (close > at + 1 && pattern[close - 1] === ":") {
+        const ranges = CLASSES.get(pattern.slice(at + 1, close - 1));
+        if (ranges === undefined) {
+          return { source: NOTHING, end: pattern.length };
+        }
+        for (let one = 0; one < ranges.length; one += 2) {
+          members += `${member(ranges.charCodeAt(one))}-${member(ranges.charCodeAt(one + 1))}`;
+        }
+        low = undefined;
+        at = close + 1;
+        continue;
+      }
+    }
+    if (point === 0x5c) {
+      point = next();
+      if (point === undefined) {
+        return { source: NOTHING, end: pattern.length };
+      }
+    }
+    members += member(point);
+    low = point;
+  }
+}
+
+/** The expression source of one pattern with no brace list. */
+function source(pattern: string, form: GlobForm): string {
+  let text = "";
+  let at = 0;
+  while (at < pattern.length) {
+    if (pattern.startsWith("**/", at)) {
+      text += "(?:[^/]*/)*";
+      at += 3;
+      continue;
+    }
+    if (pattern.startsWith("**", at)) {
+      text += ".*";
+      at += 2;
+      continue;
+    }
+    const character = pattern[at] ?? "";
+    if (form === "gitignore" && character === "[") {
+      const read = bracket(pattern, at);
+      text += read.source;
+      at = read.end;
+      continue;
+    }
+    if (form === "gitignore" && character === "\\" && at + 1 < pattern.length) {
+      text += quoted(pattern[at + 1] ?? "");
+      at += 2;
+      continue;
+    }
+    at += 1;
+    text += character === "*" ? "[^/]*" : character === "?" ? "[^/]" : quoted(character);
+  }
+  return text;
+}
+
+/** A pattern with every brace list expanded into its alternatives; a lone `{` stands for itself. */
+export function braceExpanded(pattern: string): readonly string[] {
+  const open = pattern.indexOf("{");
+  const close = open < 0 ? -1 : pattern.indexOf("}", open);
+  if (close < 0) {
+    return [pattern];
+  }
+  const before = pattern.slice(0, open);
+  const after = pattern.slice(close + 1);
+  return pattern
+    .slice(open + 1, close)
+    .split(",")
+    .flatMap((member) => braceExpanded(before + member + after));
+}
+
+/** The expression one whole-path pattern of the configured form denotes. */
+export function globExpression(pattern: string): RegExp {
+  const alternatives = braceExpanded(pattern).map((one) => source(one, "configured"));
+  return new RegExp(`^(?:${alternatives.join("|")})$`, "u");
+}
+
+/** The expression one `.gitignore` pattern denotes over a path below its file's directory. */
+export function gitignoreExpression(pattern: string): RegExp {
+  return new RegExp(`^${source(pattern, "gitignore")}$`, "u");
+}
+
+const SEGMENTS = new Map<string, RegExp>();
+
+/**
+ * Whether one directory name matches one segment of a workspace's member pattern, its brace
+ * lists already expanded. Neither `*` nor `?` matches a leading dot, as npm's workspaces read
+ * them: https://docs.npmjs.com/cli/using-npm/workspaces
+ */
+export function segmentMatches(segment: string, name: string): boolean {
+  if (name.startsWith(".") && !segment.startsWith(".")) {
+    return false;
+  }
+  let expression = SEGMENTS.get(segment);
+  if (expression === undefined) {
+    expression = globExpression(segment);
+    SEGMENTS.set(segment, expression);
+  }
+  return expression.test(name);
+}
+
+/**
+ * Whether one path's segments match a member pattern's, `**` standing for any run of segments
+ * that starts with no dot.
+ */
+export function pathMatches(pattern: readonly string[], path: readonly string[]): boolean {
+  const [head, ...rest] = pattern;
+  if (head === undefined) {
+    return path.length === 0;
+  }
+  if (head === "**") {
+    return (
+      pathMatches(rest, path) ||
+      (path.length > 0 && !(path[0] ?? "").startsWith(".") && pathMatches(pattern, path.slice(1)))
+    );
+  }
+  const [name, ...below] = path;
+  return name !== undefined && segmentMatches(head, name) && pathMatches(rest, below);
+}

package/src/text/shell.ts

@@ -0,0 +1,161 @@
+/**
+ * Shell command lines read as text, never run: the commands a line runs, the tokens the
+ * Contract splits a command into, and the words POSIX token recognition reads.
+ */
+
+/**
+ * The shell's list and pipeline operators, each of which ends one command. An `&` beside a
+ * redirection's `<` or `>` (`2>&1`, and bash's `&>log`) is part of the redirection.
+ */
+const COMMAND_OPERATORS = /&&|\|\||;|\||(?<![<>])&(?!>)/u;
+
+/** Where a command splits into tokens: white space and the operators the Contract names. */
+const TOKEN_SEPARATORS = /\s+|&&|\|\||;|\|/u;
+
+/** A text written inside one pair of quotes. */
+const QUOTED = /^(["'])(.*)\1$/su;
+
+/** The commands one line runs, the text between two of the shell's list and pipeline operators. */
+export function commandsOf(line: string): readonly string[] {
+  return line.split(COMMAND_OPERATORS);
+}
+
+/** One text with one pair of enclosing quotes removed. */
+export function unquoted(text: string): string {
+  return text.replace(QUOTED, "$2");
+}
+
+/**
+ * Every token one script's command line holds, each with one pair of enclosing quotes
+ * removed. A token holding a wildcard is a pattern rather than a path, and names no
+ * entry point.
+ */
+export function scriptTokens(command: string): readonly string[] {
+  return command
+    .split(TOKEN_SEPARATORS)
+    .map(unquoted)
+    .filter((token) => token !== "" && !token.includes("*"));
+}
+
+/** One shell line up to its comment: a `#` that starts a word outside quotes. */
+export function withoutComment(line: string): string {
+  let quote = "";
+  for (let at = 0; at < line.length; at += 1) {
+    const char = line[at];
+    if (quote !== "") {
+      if (char === quote) {
+        quote = "";
+      } else if (char === "\\" && quote === '"') {
+        at += 1;
+      }
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "\\") {
+      at += 1;
+    } else if (char === "#" && (at === 0 || /\s/u.test(line[at - 1] ?? ""))) {
+      return line.slice(0, at);
+    }
+  }
+  return line;
+}
+
+/** The characters that end a word outside quotes and separate nothing: blanks. */
+// Stryker disable next-line Regex: its \v to \V mutant is no valid escape under the u flag, so the whole module fails to parse
+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.
+ */
+export 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;
+}

package/src/{yaml-document.ts → text/yaml.ts}

@@ -6,6 +6,8 @@
  * as a JSON document that does not parse has none.
  */
 
+import { isRecord } from "../json-document.ts";
+
 /** One line of the document with its comment removed, by its indentation and its content. */
 interface Line {
   readonly indent: number;
@@ -375,3 +377,47 @@ export function yamlDocument(text: string): unknown {
     throw error;
   }
 }
+
+/** What one top-level key of a YAML document holds, read by {@link yamlKey}. */
+type YamlKey =
+  | { readonly kind: "value"; readonly value: unknown }
+  | { readonly kind: "absent" }
+  | { readonly kind: "refused"; readonly reason: string };
+
+/** The key one line of the document's top-level mapping opens, or undefined where it opens none. */
+function topLevelKey(raw: string): string | undefined {
+  const content = withoutComment(raw).trimEnd();
+  const end = /^\s/u.test(content) ? -1 : keyEnd(content);
+  if (end < 0) {
+    return undefined;
+  }
+  try {
+    const key = scalar(content.slice(0, end));
+    return typeof key === "object" && key !== null ? undefined : String(key);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The value of one key of a document's top-level block mapping, read from that key's lines
+ * alone, so a document whose other keys lie outside the subset still yields it. A key
+ * declared twice, or one whose own lines lie outside the subset, is refused.
+ */
+export function yamlKey(text: string, key: string): YamlKey {
+  const lines = text.replace(/^\uFEFF/u, "").split(/\r?\n/u);
+  const starts = lines.flatMap((line, at) => (topLevelKey(line) === undefined ? [] : [at]));
+  const named = starts.filter((at) => topLevelKey(lines[at] ?? "") === key);
+  const [start] = named;
+  if (start === undefined) {
+    return { kind: "absent" };
+  }
+  if (named.length > 1) {
+    return { kind: "refused", reason: `the ${key} key is declared more than once` };
+  }
+  const end = starts.find((at) => at > start) ?? lines.length;
+  const value = yamlDocument(lines.slice(start, end).join("\n"));
+  return isRecord(value)
+    ? { kind: "value", value: value[key] }
+    : { kind: "refused", reason: `the value of ${key} is outside the YAML subset read here` };
+}

package/src/type-errors.ts

@@ -21,12 +21,21 @@ import { packageOfSpecifier } from "./dependencies.ts";
 import type { LocatedDiagnostic } from "./discover.ts";
 import type { Host } from "./host.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
-import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import {
+  ancestors,
+  dirnamePath,
+  isAbsolutePath,
+  joinPath,
+  relativePath,
+  resolvePath,
+} from "./paths.ts";
 import { isAnswered } from "./query.ts";
 import type { TypeErrorSkip } from "./report.ts";
 import type { Engine, ProjectView } from "./session.ts";
 import type { SetupFailure } from "./setup-failure.ts";
 import { findWorkspace, type Workspace } from "./workspace.ts";
+import { entriesOf } from "./fs/tree.ts";
+import { INSTALLED_PACKAGES, MANIFEST, manifestAt } from "./fs/manifest.ts";
 
 /** The compiler's codes for an import whose module it cannot find. */
 const MODULE_NOT_FOUND: ReadonlySet<number> = new Set([2307, 2792]);
@@ -38,7 +47,6 @@ const MODULE_NOT_FOUND: ReadonlySet<number> = new Set([2307, 2792]);
  */
 const CONFIGURATION_LEVEL: ReadonlySet<number> = new Set([5055, 5056, 6059, 6307]);
 
-const MANIFEST = "package.json";
 const MANIFEST_SECTIONS = [
   "dependencies",
   "devDependencies",
@@ -156,13 +164,9 @@ function provided(host: Host, path: string, fileOnly: boolean): boolean {
   }
   const dir = dirnamePath(path);
   const stem = `${path.slice(dir.length + 1)}.`;
-  try {
-    return host
-      .readDirectory(dir)
-      .some((entry) => entry.name.startsWith(stem) && counts(joinPath(dir, entry.name)));
-  } catch {
-    return false;
-  }
+  return entriesOf(host, dir).some(
+    (entry) => entry.name.startsWith(stem) && counts(joinPath(dir, entry.name)),
+  );
 }
 
 /** The manifest at or above `dir`, no higher than the target root, that declares `name`. */
@@ -172,28 +176,18 @@ function declaringManifest(
   targetRoot: string,
   name: string,
 ): string | undefined {
-  for (let at = dir; ; at = dirnamePath(at)) {
-    const path = joinPath(at, MANIFEST);
-    let manifest: unknown;
-    try {
-      manifest = JSON.parse(host.readFile(path)) as unknown;
-    } catch {
-      manifest = undefined;
-    }
-    if (typeof manifest === "object" && manifest !== null) {
-      const sections = manifest as Record<string, unknown>;
-      for (const section of MANIFEST_SECTIONS) {
-        const declared = sections[section];
-        if (typeof declared === "object" && declared !== null && Object.hasOwn(declared, name)) {
-          return path;
-        }
+  const chain = ancestors(dir, targetRoot);
+  // A directory outside the target root reads its own manifest alone.
+  for (const at of chain.length > 0 ? chain : [dir]) {
+    const manifest = manifestAt(host, at);
+    for (const section of MANIFEST_SECTIONS) {
+      const declared = manifest?.[section];
+      if (typeof declared === "object" && declared !== null && Object.hasOwn(declared, name)) {
+        return joinPath(at, MANIFEST);
       }
     }
-    // The target root is not below itself, so the walk stops after reading its manifest.
-    if (relativePath(targetRoot, at) === undefined) {
-      return undefined;
-    }
   }
+  return undefined;
 }
 
 /**
@@ -201,14 +195,9 @@ function declaringManifest(
  * `dir` or of any ancestor, above the target root too, as Node and the compiler look.
  */
 function installed(host: Host, dir: string, name: string): boolean {
-  for (let at = dir; ; at = dirnamePath(at)) {
-    if (host.kindOf(joinPath(at, "node_modules", name)) === "directory") {
-      return true;
-    }
-    if (dirnamePath(at) === at) {
-      return false;
-    }
-  }
+  return ancestors(dir).some(
+    (at) => host.kindOf(joinPath(at, INSTALLED_PACKAGES, name)) === "directory",
+  );
 }
 
 /**

package/src/unseen-loads.ts

@@ -6,13 +6,10 @@
  */
 
 import {
-  isAsExpression,
   isBinaryExpression,
   isCallExpression,
   isIdentifier,
   isNoSubstitutionTemplateLiteral,
-  isParenthesizedExpression,
-  isSatisfiesExpression,
   isStringLiteral,
   isTemplateExpression,
   SyntaxKind,
@@ -23,6 +20,7 @@ import { renderPosition, type Position } from "./position.ts";
 import { UNANSWERED } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 import { sourceFilesOf } from "./source-files.ts";
+import { unwrapped } from "./unwrap.ts";
 
 /** One load the analysis cannot resolve, in the configuration whose production file writes it. */
 export interface UnseenLoad {
@@ -31,15 +29,6 @@ export interface UnseenLoad {
   readonly position: Position;
 }
 
-/** The expression a wrapper that changes no value holds: parentheses and type assertions. */
-function unwrapped(node: Node): Node {
-  let at = node;
-  while (isParenthesizedExpression(at) || isAsExpression(at) || isSatisfiesExpression(at)) {
-    at = at.expression;
-  }
-  return at;
-}
-
 /** The literal text a computed path starts with: a template's head, or a concatenation's first literal. */
 export function leadingLiteral(node: Node): string | undefined {
   const at = unwrapped(node);

package/src/unwrap.ts

@@ -0,0 +1,34 @@
+import {
+  isAsExpression,
+  isNonNullExpression,
+  isParenthesizedExpression,
+  isSatisfiesExpression,
+  type Expression,
+  type Node,
+} from "@typescript/native/ast";
+
+/** The expression inside every pair of parentheses around `node`. */
+export function parenthesesRemoved<T extends Node>(node: T): T | Expression {
+  let at: T | Expression = node;
+  while (isParenthesizedExpression(at)) {
+    at = at.expression;
+  }
+  return at;
+}
+
+/**
+ * The expression inside every wrapper around `node` that changes no value it evaluates to:
+ * parentheses, `as` and `satisfies` assertions and the non-null assertion.
+ */
+export function unwrapped<T extends Node>(node: T): T | Expression {
+  let at: T | Expression = node;
+  while (
+    isParenthesizedExpression(at) ||
+    isAsExpression(at) ||
+    isSatisfiesExpression(at) ||
+    isNonNullExpression(at)
+  ) {
+    at = at.expression;
+  }
+  return at;
+}

package/src/usage.ts

@@ -0,0 +1,10 @@
+/**
+ * A refusal of the invocation: the fix is to the command line or to a document it
+ * names, so the run ends with the usage code before any analysis.
+ */
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UsageError";
+  }
+}