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

package/src/intra-function-parts.ts

@@ -96,6 +96,7 @@ import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
 import { signatureOf, type SignatureNode } from "./signatures.ts";
 import { spellsNoBinding } from "./spelled-names.ts";
+import { parenthesesRemoved } from "./unwrap.ts";
 
 /** The subject kind of each part this module reads. */
 type PartKind = "parameter" | "result" | "statement" | "store" | "case";
@@ -197,11 +198,6 @@ function spanOf(file: SourceFile, root: string, node: Node): FindingPosition {
   return { ...start, endLine };
 }
 
-/** The parenthesized expression's content, through every pair of parentheses. */
-function unwrapped(node: Node): Node {
-  return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
-}
-
 /** The node the parentheses around one expression sit in. */
 function outerParent(node: Node): Node {
   return isParenthesizedExpression(node.parent) ? outerParent(node.parent) : node.parent;
@@ -209,7 +205,7 @@ function outerParent(node: Node): Node {
 
 /** The name a call is made through: the identifier, or the member a property access names. */
 function calleeName(call: CallExpression): Identifier | undefined {
-  const callee = unwrapped(call.expression);
+  const callee = parenthesesRemoved(call.expression);
   if (isIdentifier(callee)) {
     return callee;
   }
@@ -276,7 +272,7 @@ function unreachableExempt(statement: Statement): boolean {
 
 /** The value a case expression is a literal of, as a key two equal literals share, or none. */
 function caseKey(expression: Node): string | undefined {
-  const node = unwrapped(expression);
+  const node = parenthesesRemoved(expression);
   if (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node)) {
     return `s:${node.text}`;
   }
@@ -402,7 +398,7 @@ function extendedNames(files: readonly SourceFile[]): ReadonlySet<string> {
         if (isTypeReferenceNode(type)) {
           named = isQualifiedName(type.typeName) ? type.typeName.right : type.typeName;
         } else {
-          const expression = unwrapped(type.expression);
+          const expression = parenthesesRemoved(type.expression);
           named = isPropertyAccessExpression(expression) ? expression.name : expression;
         }
         if (isIdentifier(named)) {
@@ -455,7 +451,7 @@ function decoratorFixes(constructor: ConstructorDeclaration): boolean {
 
 /** The name an expression spells a class by: an identifier, or the member a property access names. */
 function spelledName(expression: Node): Identifier | undefined {
-  const node = unwrapped(expression);
+  const node = parenthesesRemoved(expression);
   if (isIdentifier(node)) {
     return node;
   }
@@ -724,8 +720,8 @@ export function projectParts<Brand>(
       if ((isImportClause(node) || isNamespaceImport(node)) && node.name !== undefined) {
         specifiers.add(position(node.name));
       }
-      if (isExportAssignment(node) && isIdentifier(unwrapped(node.expression))) {
-        specifiers.add(position(unwrapped(node.expression)));
+      if (isExportAssignment(node) && isIdentifier(parenthesesRemoved(node.expression))) {
+        specifiers.add(position(parenthesesRemoved(node.expression)));
       }
       if (isSwitchStatement(node)) {
         const holder = holderOf(node);
@@ -1325,7 +1321,7 @@ function isPlainWrite(use: Identifier): boolean {
   return (
     isBinaryExpression(parent) &&
     parent.operatorToken.kind === SyntaxKind.EqualsToken &&
-    unwrapped(parent.left) === use
+    parenthesesRemoved(parent.left) === use
   );
 }
 
@@ -1382,14 +1378,14 @@ function deadStores(
       if (!isExpressionStatement(statement)) {
         return undefined;
       }
-      const expression = unwrapped(statement.expression);
+      const expression = parenthesesRemoved(statement.expression);
       if (
         !isBinaryExpression(expression) ||
         expression.operatorToken.kind !== SyntaxKind.EqualsToken
       ) {
         return undefined;
       }
-      const target = unwrapped(expression.left);
+      const target = parenthesesRemoved(expression.left);
       return isIdentifier(target) && uses.includes(target)
         ? { target, value: expression.right }
         : undefined;

package/src/inventory.ts

@@ -50,6 +50,7 @@ import {
 import { computedComponent, nameComponent, renderRef, type Component, type Module } from "./ref.ts";
 import { isAnswered, UNANSWERED } from "./query.ts";
 import type { Handle, ProjectView } from "./session.ts";
+import { manifestAt } from "./fs/manifest.ts";
 
 /**
  * The symbol inventory of one project: every declaration the target's own files
@@ -233,8 +234,6 @@ interface ExportScope {
   readonly nameNode: Node;
 }
 
-const MANIFEST = "package.json";
-
 /** One manifest that names a package, and the directory below the root that holds it. */
 interface Named {
   readonly name: string;
@@ -255,24 +254,7 @@ export function packageScope(host: Host, root: string): (path: string) => Module
   const named = new Map<string, Named | undefined>();
 
   const manifestName = (dir: string): string | undefined => {
-    let text: string;
-    try {
-      text = host.readFile(joinPath(root, dir, MANIFEST));
-    } catch {
-      return undefined;
-    }
-    let value: unknown;
-    try {
-      value = JSON.parse(text);
-    } catch {
-      // A manifest this program cannot read names no package, which is the same
-      // answer as an absent one: the file is then scoped by the target root.
-      return undefined;
-    }
-    if (typeof value !== "object" || value === null) {
-      return undefined;
-    }
-    const name = (value as Record<string, unknown>)["name"];
+    const name = manifestAt(host, joinPath(root, dir))?.["name"];
     return typeof name === "string" && name !== "" ? name : undefined;
   };
 

package/src/json-document.ts

@@ -128,3 +128,8 @@ export function positionAt(text: string, file: string, offset: number): Position
   const lineStart = before.lastIndexOf("\n") + 1;
   return { path: file, line: before.split("\n").length, column: offset - lineStart + 1 };
 }
+
+/** Whether a decoded JSON value is an object: not `null` and not an array. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/keyof-comparisons.ts

@@ -10,7 +10,6 @@ import {
   isCaseClause,
   isElementAccessExpression,
   isIdentifier,
-  isParenthesizedExpression,
   isPropertyAccessExpression,
   isSwitchStatement,
   isTypeOperatorNode,
@@ -27,6 +26,7 @@ import { renderPosition } from "./position.ts";
 import { UNANSWERED } from "./query.ts";
 import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
+import { parenthesesRemoved } from "./unwrap.ts";
 
 /** The operators that compare their operands for equality. */
 const EQUALITIES: ReadonlySet<SyntaxKind> = new Set([
@@ -44,13 +44,9 @@ interface Comparison {
   readonly other: Expression;
 }
 
-function unwrapped(node: Expression): Expression {
-  return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
-}
-
 /** The name node an operand's symbol is read at: an identifier, or a property access's name. */
 function nameOf(node: Expression): Node | undefined {
-  const at = unwrapped(node);
+  const at = parenthesesRemoved(node);
   if (isIdentifier(at)) {
     return at;
   }
@@ -132,7 +128,7 @@ export function keyofComparisonReferences<Brand>(
   }
   const named = comparisons.flatMap((one) => {
     const name = nameOf(one.keyed);
-    return name === undefined || isElementAccessExpression(unwrapped(one.other))
+    return name === undefined || isElementAccessExpression(parenthesesRemoved(one.other))
       ? []
       : [{ ...one, name }];
   });

package/src/manifest.ts

@@ -6,10 +6,12 @@
  */
 
 import type { Host } from "./host.ts";
-import { isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import { isAbsolutePath, relativePath, resolvePath } from "./paths.ts";
+import { isRecord } from "./json-document.ts";
+import { MANIFEST, manifestAt } from "./fs/manifest.ts";
+import { scriptTokens } from "./text/shell.ts";
 
 /** The manifest's own name. */
-const MANIFEST = "package.json";
 
 /** The three members that name an entry point beside `exports` and `bin`. */
 const LEGACY_MEMBERS = ["main", "module", "types"] as const;
@@ -44,10 +46,6 @@ export interface ManifestEntry {
   readonly dir: string;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Whether one member's value names a file of this package rather than another
  * package or a URL. A target written with no leading dot is a path too, which is
@@ -60,24 +58,6 @@ function isTarget(value: string, requireDot: boolean): boolean {
   return !requireDot || value.startsWith("./");
 }
 
-/** Where a script's command line splits into tokens: white space and the shell's operators. */
-const SCRIPT_SEPARATORS = /\s+|&&|\|\||;|\|/u;
-
-/** A token written inside one pair of quotes. */
-const QUOTED = /^(["'])(.*)\1$/su;
-
-/**
- * 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(SCRIPT_SEPARATORS)
-    .map((token) => token.replace(QUOTED, "$2"))
-    .filter((token) => token !== "" && !token.includes("*"));
-}
-
 /** One member's spelling below another: `exports` then `exports["."]`. */
 function below(member: string, key: string): string {
   return `${member}[${JSON.stringify(key)}]`;
@@ -111,27 +91,6 @@ function exportTargets(value: unknown, member: string, found: Omit<ManifestEntry
   }
 }
 
-/** The manifest at the target root, decoded, or undefined where there is none to read. */
-function manifestOf(host: Host, targetRoot: string): Record<string, unknown> | undefined {
-  let text: string;
-  try {
-    text = host.readFile(joinPath(targetRoot, MANIFEST));
-  } catch {
-    return undefined;
-  }
-  let value: unknown;
-  try {
-    value = JSON.parse(text);
-  } catch {
-    // A manifest this program cannot read names no entry point, which is the same
-    // answer as an absent one. What a manifest's contents say is not refused here:
-    // the package manager owns that refusal, and an analysis of a tree it rejects
-    // is not the run's subject.
-    return undefined;
-  }
-  return isRecord(value) ? value : undefined;
-}
-
 /** What one manifest declares about where its package is entered. */
 export interface Manifest {
   /**
@@ -158,7 +117,7 @@ export interface Manifest {
  * it and there is one such configuration per project, while there is one manifest.
  */
 export function readManifest(host: Host, targetRoot: string): Manifest {
-  const manifest = manifestOf(host, targetRoot);
+  const manifest = manifestAt(host, targetRoot);
   if (manifest === undefined) {
     return { entries: [], declaresExports: false };
   }

package/src/mdx-entries.ts

@@ -9,6 +9,7 @@ import { resolveRelativeSpecifier } from "./configuration-files.ts";
 import type { Host } from "./host.ts";
 import { dirnamePath, joinPath, resolvePath } from "./paths.ts";
 import type { SourceFiles } from "./source-files.ts";
+import { filesBelow } from "./fs/tree.ts";
 
 /** One file a document imports, the specifier that named it, and the export names it reads. */
 interface DocumentEntry {
@@ -18,9 +19,6 @@ interface DocumentEntry {
   readonly names: readonly string[] | undefined;
 }
 
-/** The directories no document is read below. */
-const SKIPPED: ReadonlySet<string> = new Set(["node_modules", ".git"]);
-
 /** The extensions of a document whose imports an MDX compiler reads. */
 const DOCUMENT = /\.mdx?$/u;
 
@@ -129,28 +127,6 @@ function clauseNames(clause: string): readonly string[] | undefined {
   return names;
 }
 
-/** Every document below `dir`, outside every skipped directory, by absolute path. */
-function documents(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 (!SKIPPED.has(entry.name)) {
-        found.push(...documents(host, path));
-      }
-    } else if (DOCUMENT.test(entry.name)) {
-      found.push(path);
-    }
-  }
-  return found.sort();
-}
-
 /** The relative specifiers one document's import lines name, its fenced code blocks skipped. */
 function importedBy(
   text: string,
@@ -205,7 +181,8 @@ function documentImports(host: Host, root: string): readonly DocumentImports[] {
   if (known !== undefined) {
     return known;
   }
-  const found = documents(host, root).flatMap((path) => {
+  const found = filesBelow(host, root, (name) => DOCUMENT.test(name)).flatMap((below) => {
+    const path = joinPath(root, below);
     try {
       return [{ path, imports: importedBy(host.readFile(path)) }];
     } catch {

package/src/partial.ts

@@ -1,6 +1,7 @@
 import type { NotBuilt } from "./discover.ts";
 import { relativePath } from "./paths.ts";
 import type { UnansweredQuestion } from "./query.ts";
+import { bytewise } from "./text/compare.ts";
 
 /** What a run read only in part. */
 interface Partial {
@@ -24,7 +25,7 @@ function counted(n: number, one: string, many: string): string {
  */
 export function partialNotes(partial: Partial): readonly string[] {
   const notes = [...partial.notBuilt]
-    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .sort((a, b) => bytewise(a.id, b.id))
     .map(
       (one) =>
         `the derived configuration ${one.id} was not built and is not analyzed: ${one.error}`,

package/src/paths.ts

@@ -1,11 +1,7 @@
 /**
- * Filesystem paths, as the supported platform spells them: a solidus separates
- * segments and a leading solidus makes a path absolute.
- *
- * They are written here rather than taken from the platform's own library because
- * every module below the command line stays free of the platform, and because the
- * supported platform set is one, so a second spelling would be a rule nothing
- * exercises.
+ * Filesystem paths as the supported platform spells them: a solidus between segments, a
+ * leading one for an absolute path. They are written here rather than taken from the
+ * platform's library so every module below the command line stays free of the platform.
  */
 
 const SEPARATOR = "/";
@@ -67,6 +63,25 @@ export function dirnamePath(path: string): string {
   return cut === 0 ? SEPARATOR : normalized.slice(0, cut);
 }
 
+/**
+ * `dir` and every directory above it, nearest first, normalized. With `top`, the list ends
+ * at `top` and is empty where `dir` is neither `top` nor below it; without, it ends at the
+ * root of the path.
+ */
+export function ancestors(dir: string, top?: string): readonly string[] {
+  const end = top === undefined ? undefined : normalizePath(top);
+  const found: string[] = [];
+  for (let at = normalizePath(dir); ; at = dirnamePath(at)) {
+    if (end !== undefined && at !== end && relativePath(end, at) === undefined) {
+      return [];
+    }
+    found.push(at);
+    if (at === end || dirnamePath(at) === at) {
+      return found;
+    }
+  }
+}
+
 /**
  * The extension of one path's last segment, from its last full stop, or the empty string
  * where it has none. A segment that only starts with a full stop has none.
@@ -101,14 +116,11 @@ export function queriedModulePath(specifier: string): string | undefined {
 }
 
 /**
- * One path as it reads below a root, or undefined when it is not below the root.
- * Both are normalized first, so a root written with a trailing separator or a `.`
- * segment reaches the same answer, and the comparison is then lexical, so a root
- * and a path spelled through different symbolic links name nothing in common. The
- * root itself is not below itself.
- *
- * The caller resolves both against the same directory before calling: a relative
- * root and an absolute path are two spellings this cannot reconcile.
+ * One path as it reads below a root, or undefined when it is not strictly below the root:
+ * the root itself is not below itself. Both are normalized, then compared lexically, so a
+ * root and a path spelled through different symbolic links name nothing in common. The
+ * caller resolves both against the same directory first: a relative root and an absolute
+ * path cannot be reconciled.
  */
 export function relativePath(root: string, path: string): string | undefined {
   const at = normalizePath(root);

package/src/position.ts

@@ -1,5 +1,6 @@
 import type { SourceFile } from "@typescript/native/ast";
 import { relativePath } from "./paths.ts";
+import { bytewise } from "./text/compare.ts";
 
 /**
  * Where one declaration is written, as every report renders it.
@@ -87,7 +88,7 @@ export function positionKey(position: Position): string {
  */
 export function byPosition(a: Position, b: Position): number {
   if (a.path !== b.path) {
-    return a.path < b.path ? -1 : 1;
+    return bytewise(a.path, b.path);
   }
   if (a.line !== b.line) {
     return a.line - b.line;

package/src/print.ts

@@ -5,6 +5,7 @@ import {
   type Provenance,
   type Provider,
 } from "./config.ts";
+import { bytewise } from "./text/compare.ts";
 
 /** One declaration entry as a document writes it: the members of its shape alone. */
 function declarationOf(entry: DeclarationEntry): Record<string, string> {
@@ -61,7 +62,7 @@ export function printConfig(config: Config, provenance: Provenance): string {
     },
     consumers: { complete: config.consumersComplete },
     roots: { patterns: config.rootPatterns },
-    severity: Object.fromEntries([...config.severity].sort(([a], [b]) => (a < b ? -1 : 1))),
+    severity: Object.fromEntries([...config.severity].sort(([a], [b]) => bytewise(a, b))),
     exemptions: { disabled: config.exemptionsDisabled },
     reporters: {
       formats: config.reporters.formats,
@@ -88,7 +89,7 @@ export function printConfig(config: Config, provenance: Provenance): string {
     },
     provenance: Object.fromEntries(
       [...provenance]
-        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .sort(([a], [b]) => bytewise(a, b))
         .map(([path, origin]) => [path, renderOrigin(origin)]),
     ),
   };

package/src/product.ts

@@ -0,0 +1,18 @@
+import { LANGUAGE_ROWS } from "./contract/contract.generated.ts";
+import type { Writer } from "./run.ts";
+
+/** The language this analyzer reads. */
+export const LANGUAGE = "ts";
+
+/** The analyzer's name: the one its language's row names, which every output spells it with. */
+export const PRODUCT = LANGUAGE_ROWS[LANGUAGE].analyzer;
+
+/** Writes one diagnostic line to the error stream, named for the analyzer. */
+export function diagnose(err: Writer, text: string): void {
+  err.write(`${PRODUCT}: ${text}\n`);
+}
+
+/** The text one thrown value carries. */
+export function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/references.ts

@@ -38,13 +38,13 @@ import {
   type ParameterDeclaration,
   type SourceFile,
 } from "@typescript/native/ast";
+import { parenthesesRemoved } from "./unwrap.ts";
 import type { Symbol as TSSymbol } from "@typescript/native/sync";
 import { aliasChains, type ChainTarget } from "./alias-chain.ts";
 import { contextualUses, type FlowAt, type LiteralAt } from "./contextual-uses.ts";
 import { destructuring, propertyReadsOf, type PropertyRead } from "./destructuring.ts";
 import { specifierCandidates } from "./configuration-files.ts";
 import { namespaceUses } from "./namespace-objects.ts";
-import { globExpression } from "./glob.ts";
 import {
   declarationsByName,
   isParameterProperty,
@@ -73,6 +73,8 @@ import {
   type KeyedAccess,
 } from "./symbol-keys.ts";
 import { handedOn, valuesOf } from "./value-flow.ts";
+import { bytewise } from "./text/compare.ts";
+import { globExpression } from "./text/glob.ts";
 
 /**
  * Every use one project's own files make of the project's own declarations.
@@ -315,15 +317,6 @@ function isName(node: Node): boolean {
   return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
 }
 
-/** The expression one node is, through however many parentheses are written around it. */
-function unparenthesized(node: Node): Node {
-  let held = node;
-  while (isParenthesizedExpression(held)) {
-    held = held.expression;
-  }
-  return held;
-}
-
 /**
  * Records the name one store writes into.
  *
@@ -333,7 +326,7 @@ function unparenthesized(node: Node): Node {
  * target writes each name it binds, through its spreads and nested patterns.
  */
 function markWrite(target: Node, writes: Set<number>, accesses: Set<Node>): void {
-  const held = unparenthesized(target);
+  const held = parenthesesRemoved(target);
   if (isName(held)) {
     writes.add(held.pos);
     return;
@@ -348,7 +341,7 @@ function markWrite(target: Node, writes: Set<number>, accesses: Set<Node>): void
     accesses.add(held);
     // A store through a member's value lands in storage every holder of the value
     // reads, so it reads the member; a variable only ever stored into stays written.
-    if (!isPropertyAccessExpression(unparenthesized(held.expression))) {
+    if (!isPropertyAccessExpression(parenthesesRemoved(held.expression))) {
       markWrite(held.expression, writes, accesses);
     }
     return;
@@ -524,7 +517,7 @@ interface FileSites {
 
 /** Whether one node is `import.meta.url`. */
 function isImportMetaURL(node: Node): boolean {
-  const at = unparenthesized(node);
+  const at = parenthesesRemoved(node);
   return (
     isPropertyAccessExpression(at) &&
     isMetaProperty(at.expression) &&
@@ -536,7 +529,7 @@ function isImportMetaURL(node: Node): boolean {
 /** The module URL one node builds, where it builds one. */
 function moduleURLOf(node: Node): ModuleURL | undefined {
   const relative = (argument: Node | undefined): string | undefined => {
-    const at = argument === undefined ? undefined : unparenthesized(argument);
+    const at = argument === undefined ? undefined : parenthesesRemoved(argument);
     return at !== undefined &&
       (isStringLiteral(at) || isNoSubstitutionTemplateLiteral(at)) &&
       /^\.\.?\//u.test(at.text)
@@ -551,7 +544,7 @@ function moduleURLOf(node: Node): ModuleURL | undefined {
       : undefined;
   }
   if (isCallExpression(node)) {
-    const callee = unparenthesized(node.expression);
+    const callee = parenthesesRemoved(node.expression);
     const specifier = relative(node.arguments[0]);
     if (
       specifier !== undefined &&
@@ -869,7 +862,7 @@ export function testFileRulesOf(
       };
     }),
     ...(support === 0 ? [] : [{ rule: TEST_SUPPORT_RULE, matched: support }]),
-  ].sort((a, b) => compare(a.rule, b.rule));
+  ].sort((a, b) => bytewise(a.rule, b.rule));
 }
 
 const importedCache = new WeakMap<
@@ -1003,7 +996,7 @@ function aloneIn(
           nodes.every((node) => sameTarget.some((one) => inside(node, one.value))),
       )
       .map(([name]) => name)
-      .sort(compare);
+      .sort(bytewise);
     if (names.length > 0) {
       result.push({ index: write.index, names });
     }
@@ -1011,14 +1004,6 @@ function aloneIn(
   return result;
 }
 
-/** Two strings ordered bytewise, which is the order every set of a run is read in. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
  * Every reference one project's own files make to the project's own declarations, in
  * position order, and the files the test-file rules classified.
@@ -1677,9 +1662,9 @@ export function references<Brand>(
   found.sort(
     (a, b) =>
       byPosition(a.position, b.position) ||
-      compare(a.to, b.to) ||
-      compare(a.from, b.from) ||
-      compare(a.use, b.use),
+      bytewise(a.to, b.to) ||
+      bytewise(a.from, b.from) ||
+      bytewise(a.use, b.use),
   );
 
   return {
@@ -1687,7 +1672,7 @@ export function references<Brand>(
       consumer === undefined
         ? found
         : found.map((reference) => ({ ...reference, consumer: consumer.id })),
-    testFilePaths: tests.sort(compare),
+    testFilePaths: tests.sort(bytewise),
     cost: {
       batched,
       fileBatches,