@cplieger/deadset-ts 4.0.1 → 5.0.0

package/src/pnpm-workspace.ts

@@ -0,0 +1,135 @@
+/**
+ * The `packages` list of a `pnpm-workspace.yaml`. The document is read as far as that
+ * one key needs and no further: a top-level `packages` key holding a block sequence or
+ * a one-line flow sequence of plain or quoted strings. Any other value of the key is
+ * refused rather than guessed at, because a list read wrong names the wrong packages.
+ */
+
+/** What the document says about `packages`. */
+export type PnpmPackages =
+  | { readonly kind: "listed"; readonly patterns: readonly string[] }
+  /** The document declares no `packages` key. */
+  | { readonly kind: "absent" }
+  /** The key holds something this reader does not read, with what it holds. */
+  | { readonly kind: "refused"; readonly reason: string };
+
+/** The characters a plain scalar may not start with. */
+const INDICATORS = new Set(["[", "]", "{", "}", ",", "&", "*", "!", "|", ">", "%", "@", "`", "#"]);
+
+/** One line with its comment removed, a `#` inside quotes kept. */
+function uncommented(line: string): string {
+  let quote: string | undefined;
+  for (let at = 0; at < line.length; at += 1) {
+    const character = line[at];
+    if (quote !== undefined) {
+      if (character === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+    } else if (character === "#" && (at === 0 || /\s/u.test(line[at - 1] ?? ""))) {
+      return line.slice(0, at).trimEnd();
+    }
+  }
+  return line.trimEnd();
+}
+
+/** One scalar as written, or `undefined` where it is not a string this reader reads. */
+function scalarOf(text: string): string | undefined {
+  const value = text.trim();
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    const inner = value.slice(1, -1);
+    return /'(?!')/u.test(inner.replaceAll("''", "")) ? undefined : inner.replaceAll("''", "'");
+  }
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    const inner = value.slice(1, -1);
+    return inner.includes("\\") || inner.includes('"') ? undefined : inner;
+  }
+  if (
+    value === "" ||
+    INDICATORS.has(value[0] ?? "") ||
+    value.startsWith("'") ||
+    value.startsWith('"')
+  ) {
+    return undefined;
+  }
+  if (value.startsWith("- ") || value.startsWith("? ") || /:(?:\s|$)/u.test(value)) {
+    return undefined;
+  }
+  return value;
+}
+
+/** The entries of a one-line flow sequence, or `undefined` where one does not read. */
+function flowOf(text: string): readonly string[] | undefined {
+  const inner = text.slice(1, -1).trim();
+  if (inner === "") {
+    return [];
+  }
+  const entries = inner.split(",");
+  if (entries.length > 1 && entries.at(-1)?.trim() === "") {
+    entries.pop();
+  }
+  const found: string[] = [];
+  for (const entry of entries) {
+    const value = scalarOf(entry);
+    if (value === undefined) {
+      return undefined;
+    }
+    found.push(value);
+  }
+  return found;
+}
+
+const KEY = /^(?:packages|'packages'|"packages")\s*:(?:\s(.*))?$/u;
+
+/** The `packages` list one `pnpm-workspace.yaml` text declares. */
+export function pnpmPackages(text: string): PnpmPackages {
+  const lines = text.split(/\r?\n/u).map(uncommented);
+  const keys = lines.flatMap((line, at) => (KEY.test(line) ? [at] : []));
+  const [at] = keys;
+  if (at === undefined) {
+    return { kind: "absent" };
+  }
+  if (keys.length > 1) {
+    return { kind: "refused", reason: "the packages key is declared more than once" };
+  }
+  const rest = (KEY.exec(lines[at] ?? "")?.[1] ?? "").trim();
+  if (rest !== "") {
+    const listed = rest.startsWith("[") && rest.endsWith("]") ? flowOf(rest) : undefined;
+    return listed === undefined
+      ? {
+          kind: "refused",
+          reason: `packages holds ${JSON.stringify(rest)}, not a sequence of strings`,
+        }
+      : { kind: "listed", patterns: listed };
+  }
+  const patterns: string[] = [];
+  for (const line of lines.slice(at + 1)) {
+    if (line.trim() === "") {
+      continue;
+    }
+    const item = /^(\s*)-(?:\s+(.*))?$/u.exec(line);
+    if (item === null) {
+      if (/^\s/u.test(line)) {
+        return {
+          kind: "refused",
+          reason: `packages holds ${JSON.stringify(line.trim())}, not a sequence item`,
+        };
+      }
+      break;
+    }
+    const value = scalarOf(item[2] ?? "");
+    if (value === undefined) {
+      return {
+        kind: "refused",
+        reason: `the packages item ${JSON.stringify(line.trim())} is not a plain or quoted string`,
+      };
+    }
+    patterns.push(value);
+  }
+  return patterns.length === 0
+    ? { kind: "refused", reason: "packages holds no sequence" }
+    : { kind: "listed", patterns };
+}

package/src/position.ts

@@ -34,18 +34,39 @@ export class PositionError extends Error {
   }
 }
 
+/** Whether the compiler read one file through a content mapper, which makes it a component file. */
+export function isComponentFile(file: SourceFile): boolean {
+  return file.contentMapper !== undefined;
+}
+
+/**
+ * The length of the file as it is written. A component file's module holds the file's
+ * text at its own offsets and appends what it needs past its end.
+ */
+export function writtenLength(file: SourceFile): number {
+  return isComponentFile(file) ? file.originalText.length : file.text.length;
+}
+
 /**
  * The position of one offset of one file, rendered against the target root.
  *
  * `offset` is a UTF-16 code unit offset into the file's text, which is what every
- * node of the tree carries.
+ * node of the tree carries. An offset a component file's module appends renders where
+ * the module's span map places it in the file.
  */
 export function renderPosition(file: SourceFile, root: string, offset: number): Position {
   const path = relativePath(root, file.fileName);
   if (path === undefined) {
     throw new PositionError(file.fileName, root);
   }
-  const { line, character } = file.getLineAndCharacterOfPosition(offset);
+  const written =
+    isComponentFile(file) && offset >= file.originalText.length
+      ? Math.min(
+          file.spanMap?.virtualToOriginalPosition(offset).position ?? offset,
+          file.originalText.length,
+        )
+      : offset;
+  const { line, character } = file.getLineAndCharacterOfPosition(written);
   return { path, line: line + 1, column: character + 1 };
 }
 

package/src/print.ts

@@ -75,6 +75,8 @@ export function printConfig(config: Config, provenance: Provenance): string {
     ts: {
       test_files: config.ts.testFiles,
       entry_files: config.ts.entryFiles,
+      component_extensions: config.ts.componentExtensions,
+      disabled_conventions: config.ts.disabledConventions,
       injection_registrations: config.ts.injectionRegistrations.map(declarationOf),
       lifecycle_contracts: config.ts.lifecycleContracts.map((entry) => ({
         components: entry.components.map(declarationOf),

package/src/references.ts

@@ -6,9 +6,11 @@ import {
   isDeleteExpression,
   isElementAccessExpression,
   isExportDeclaration,
+  isExpressionStatement,
   isExternalModuleReference,
   isForInStatement,
   isForOfStatement,
+  isForStatement,
   isImportDeclaration,
   isImportEqualsDeclaration,
   isNamespaceExport,
@@ -23,6 +25,7 @@ import {
   isSpreadAssignment,
   isSpreadElement,
   isStringLiteral,
+  isVoidExpression,
   SyntaxKind,
   type Node,
   type SourceFile,
@@ -31,11 +34,12 @@ import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
 import { aliasChains, type ChainTarget } from "./alias-chain.ts";
 import { destructuring, propertyReadsOf, type PropertyRead } from "./destructuring.ts";
 import { globExpression } from "./glob.ts";
-import { declarationsByName, nodeKey, type Inventory } from "./inventory.ts";
+import { declarationsByName, nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
 import { relativePath } from "./paths.ts";
-import { byPosition, renderPosition, type Position } from "./position.ts";
+import { byPosition, isComponentFile, renderPosition, type Position } from "./position.ts";
 import { DEFAULT_BATCH_CAP, UNANSWERED, type Answer } from "./query.ts";
 import type { ProjectView } from "./session.ts";
+import { typeQueryAliases } from "./type-query-alias.ts";
 
 /**
  * Every use one project's own files make of the project's own declarations.
@@ -64,11 +68,11 @@ import type { ProjectView } from "./session.ts";
 export type Use = "read" | "write" | "evaluation" | "decorator";
 
 /**
- * Which path answered for one reference: `batch`, the batched lookup over a file's name
- * nodes; `resolved-symbol`, the per-node lookup for the residue a batch left;
- * `shorthand`, the lookup for the value `{ a }` reads; `alias`, a step along an import
- * or export chain; `syntax`, the tree alone, which says what a decorator is attached to;
- * `destructured`, the property a pattern names, on the destructured value's type; and
+ * Which path answered for one reference: `batch`, the batched lookup over a file's name nodes;
+ * `resolved-symbol`, the per-node lookup for the residue a batch left; `shorthand`, the lookup
+ * for the value `{ a }` reads; `alias`, a step along an import or export chain; `syntax`, the
+ * tree alone, which says what a decorator is attached to and what a component's markup may
+ * read; `destructured`, the property a pattern names, on the destructured value's type; and
  * `by-name`, every declaration bearing the name a site spells, where the checker failed.
  */
 export type Resolution =
@@ -184,9 +188,8 @@ export interface ReferenceOptions {
 
 /**
  * The operators whose left side one assignment stores into. A compound assignment is
- * among them: it reads its target only to write the result back, so nothing else
- * receives what it read, and a declaration whose every other reference is one of these
- * carries no information out of itself.
+ * among them: where its value is discarded it reads its target only to write the result
+ * back, so nothing else receives what it read.
  */
 const ASSIGNMENTS: ReadonlySet<SyntaxKind> = new Set([
   SyntaxKind.EqualsToken,
@@ -207,6 +210,40 @@ const ASSIGNMENTS: ReadonlySet<SyntaxKind> = new Set([
   SyntaxKind.CaretEqualsToken,
 ]);
 
+/**
+ * The assignments that read their target to decide whether to store at all, so the read
+ * carries information out whatever becomes of the result.
+ */
+const LOGICAL_ASSIGNMENTS: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.BarBarEqualsToken,
+  SyntaxKind.AmpersandAmpersandEqualsToken,
+  SyntaxKind.QuestionQuestionEqualsToken,
+]);
+
+/**
+ * Whether the value of one store expression is discarded: it is a statement of its own, a
+ * clause of a `for` loop, the operand of `void`, or the left operand of a comma.
+ */
+function valueDiscarded(node: Node): boolean {
+  let child = node;
+  let parent = node.parent;
+  while (isParenthesizedExpression(parent)) {
+    child = parent;
+    parent = parent.parent;
+  }
+  if (isExpressionStatement(parent) || isVoidExpression(parent)) {
+    return true;
+  }
+  if (isForStatement(parent)) {
+    return parent.initializer === child || parent.incrementor === child;
+  }
+  return (
+    isBinaryExpression(parent) &&
+    parent.operatorToken.kind === SyntaxKind.CommaToken &&
+    parent.left === child
+  );
+}
+
 /** Whether one node is an identifier or a private name, the two forms a name takes. */
 function isName(node: Node): boolean {
   return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
@@ -277,12 +314,20 @@ function markWrite(target: Node, writes: Set<number>): void {
  * Records every store one node performs: an assignment, a compound assignment, an
  * increment or a decrement, a `delete`, and an iteration that assigns to a name declared
  * elsewhere. An iteration that declares its own name stores into nothing the inventory
- * holds.
+ * holds. A store that reads its target as well records it in `reads`: a logical
+ * assignment, and a compound assignment, an increment or a decrement whose value is used.
  */
-function markStores(node: Node, writes: Set<number>): void {
+function markStores(node: Node, writes: Set<number>, reads: Set<number>): void {
   if (isBinaryExpression(node)) {
-    if (ASSIGNMENTS.has(node.operatorToken.kind)) {
+    const operator = node.operatorToken.kind;
+    if (ASSIGNMENTS.has(operator)) {
       markWrite(node.left, writes);
+      if (
+        LOGICAL_ASSIGNMENTS.has(operator) ||
+        (operator !== SyntaxKind.EqualsToken && !valueDiscarded(node))
+      ) {
+        markWrite(node.left, reads);
+      }
     }
     return;
   }
@@ -292,6 +337,9 @@ function markStores(node: Node, writes: Set<number>): void {
       node.operator === SyntaxKind.MinusMinusToken
     ) {
       markWrite(node.operand, writes);
+      if (!valueDiscarded(node)) {
+        markWrite(node.operand, reads);
+      }
     }
     return;
   }
@@ -448,12 +496,14 @@ function linksOf(
  * order, each with its enclosing declaration and its use, and every re-export the file
  * writes. One walk answers all of it, because a second would have to agree with this one
  * about which nodes are names. A declaration's own declared name is left out, which is
- * what makes a declaration referenced only from its own site an unreferenced one.
+ * what makes a declaration referenced only from its own site an unreferenced one, and so
+ * is every node of `unread`, a subtree that is no use.
  */
 function sitesOf(
   file: SourceFile,
   declarations: ReadonlyMap<string, string>,
   fileId: string,
+  unread: ReadonlySet<Node>,
 ): FileSites {
   const found: Site[] = [];
   const reads: Read[] = [];
@@ -461,6 +511,7 @@ function sitesOf(
   const evaluations: Evaluation[] = [];
   const decorated: Decorated[] = [];
   const writes = new Set<number>();
+  const alsoRead = new Set<number>();
   const declared = new Set<number>();
   const shorthands = new Map<number, Node>();
   let enclosing = fileId;
@@ -484,19 +535,23 @@ function sitesOf(
   };
 
   const visit = (node: Node): void => {
+    if (unread.has(node)) {
+      return;
+    }
     if (isName(node)) {
       if (!declared.has(node.pos)) {
-        found.push({
-          node,
-          shorthand: shorthands.get(node.pos),
-          from: enclosing,
-          use: writes.has(node.pos) ? "write" : "read",
-        });
+        const site = { node, shorthand: shorthands.get(node.pos), from: enclosing };
+        if (writes.has(node.pos)) {
+          found.push({ ...site, use: "write" });
+        }
+        if (!writes.has(node.pos) || alsoRead.has(node.pos)) {
+          found.push({ ...site, use: "read" });
+        }
       }
       return;
     }
     markNames(node);
-    markStores(node, writes);
+    markStores(node, writes, alsoRead);
     for (const read of propertyReadsOf(node)) {
       reads.push({ ...read, from: enclosing });
     }
@@ -523,6 +578,9 @@ function sitesOf(
   return { uses: found, reads, links, evaluations, decorated };
 }
 
+/** The rule a file the analysis classified as test-support code is counted under. */
+const TEST_SUPPORT_RULE = "test-support";
+
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
  * vocabulary spells, which cannot carry a pattern, so a rule is named by the place of
@@ -539,17 +597,20 @@ function patternRule(index: number): string {
 export function testFileRulesOf(
   testFiles: readonly string[],
   paths: readonly string[],
+  supportFiles: readonly string[] = [],
 ): readonly TestFileRule[] {
   const distinct = [...new Set(paths)];
-  return testFiles
-    .map((pattern, index) => {
+  const support = new Set(supportFiles).size;
+  return [
+    ...testFiles.map((pattern, index) => {
       const expression = globExpression(pattern);
       return {
         rule: patternRule(index),
         matched: distinct.filter((path) => expression.test(path)).length,
       };
-    })
-    .sort((a, b) => compare(a.rule, b.rule));
+    }),
+    ...(support === 0 ? [] : [{ rule: TEST_SUPPORT_RULE, matched: support }]),
+  ].sort((a, b) => compare(a.rule, b.rule));
 }
 
 const importedCache = new WeakMap<
@@ -599,6 +660,37 @@ function importedNames(file: SourceFile): ReadonlyMap<string, readonly (string |
   return names;
 }
 
+/**
+ * The name node of every import binding one file's top level declares, and whether it
+ * binds a whole module.
+ */
+function importBindings(file: SourceFile): readonly { node: Node; whole: boolean }[] {
+  const found: { node: Node; whole: boolean }[] = [];
+  for (const statement of file.statements) {
+    if (isImportEqualsDeclaration(statement)) {
+      found.push({ node: statement.name, whole: true });
+      continue;
+    }
+    const clause = isImportDeclaration(statement) ? statement.importClause : undefined;
+    if (clause === undefined) {
+      continue;
+    }
+    if (clause.name !== undefined) {
+      found.push({ node: clause.name, whole: false });
+    }
+    const bindings = clause.namedBindings;
+    if (bindings === undefined) {
+      continue;
+    }
+    if (bindings.kind === SyntaxKind.NamespaceImport) {
+      found.push({ node: bindings.name, whole: true });
+    } else {
+      found.push(...bindings.elements.map((element) => ({ node: element.name, whole: false })));
+    }
+  }
+  return found;
+}
+
 /** 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) {
@@ -656,6 +748,20 @@ export function references<Brand>(
   const fileIds = new Set(
     held.symbols.filter((symbol) => symbol.kind === "file").map((symbol) => symbol.id),
   );
+  let topLevel: ReadonlyMap<string, readonly InventorySymbol[]> | undefined;
+  /** The declarations one file's top level holds. */
+  const declaredIn = (fileId: string): readonly InventorySymbol[] => {
+    if (topLevel === undefined) {
+      const byParent = new Map<string, InventorySymbol[]>();
+      for (const symbol of held.symbols) {
+        if (fileIds.has(symbol.parent)) {
+          byParent.set(symbol.parent, [...(byParent.get(symbol.parent) ?? []), symbol]);
+        }
+      }
+      topLevel = byParent;
+    }
+    return topLevel.get(fileId) ?? [];
+  };
 
   /** The identifier of the declaration one node of this program is, where it is one. */
   const declaredAt = (node: Node): string | undefined =>
@@ -693,6 +799,49 @@ export function references<Brand>(
     ];
   };
 
+  // A type-query alias's own type names its export without using it; a use of the
+  // global is the use, so it names every link of the export's chain as well.
+  const aliases = project.ownSourceFiles().flatMap(typeQueryAliases);
+  const unread = new Set(aliases.map((alias) => alias.type));
+  const aliased = new Map<string, readonly ChainTarget[]>();
+  if (aliases.length > 0) {
+    const exported = project.symbolsAt(aliases.map((alias) => project.handle(alias.exported)));
+    aliases.forEach((alias, index) => {
+      const id = declaredAt(alias.declaration);
+      const symbol = exported[index];
+      if (id === undefined || symbol === undefined) {
+        return;
+      }
+      aliased.set(
+        id,
+        symbol === UNANSWERED
+          ? (declarationsByName(held).get(alias.name) ?? []).map((one) => ({
+              id: one,
+              stepped: true,
+              guessed: true,
+            }))
+          : chains.chainOf(symbol).map((target) => ({ ...target, stepped: true })),
+      );
+    });
+  }
+  /** One use's targets, then every link an alias global among them stands for, each once. */
+  const throughAliases = (targets: readonly ChainTarget[]): readonly ChainTarget[] => {
+    if (aliased.size === 0) {
+      return targets;
+    }
+    const all = [...targets];
+    const seen = new Set(targets.map((target) => target.id));
+    for (const target of targets) {
+      for (const forwarded of aliased.get(target.id) ?? []) {
+        if (!seen.has(forwarded.id)) {
+          seen.add(forwarded.id);
+          all.push(forwarded);
+        }
+      }
+    }
+    return all;
+  };
+
   /** The symbol one site resolves to, asking only the accessor the site's form names. */
   const symbolFor = (
     site: Site,
@@ -716,11 +865,16 @@ export function references<Brand>(
     if (test) {
       tests.push(path);
     }
+    const fileId = declaredAt(file) ?? "";
     const { uses, reads, links, evaluations, decorated } = sitesOf(
       file,
       declarations,
-      declaredAt(file) ?? "",
+      fileId,
+      unread,
     );
+    // A component file's markup may use any binding its blocks declare at the top level.
+    const markup = isComponentFile(file);
+    const bindings = markup ? importBindings(file) : [];
 
     // A decorator is written inside the declaration it is attached to and receives it,
     // so the declaration is used where the decorator is written, whatever the
@@ -746,6 +900,7 @@ export function references<Brand>(
         ...uses.filter((site) => site.shorthand === undefined).map((site) => site.node),
         ...links.map((link) => link.node),
         ...evaluations.map((evaluation) => evaluation.node),
+        ...bindings.map((binding) => binding.node),
       ]),
     ];
     const answered = new Map<Node, Answer<TSSymbol>>();
@@ -809,6 +964,49 @@ export function references<Brand>(
       }
     }
 
+    if (markup) {
+      for (const symbol of declaredIn(fileId)) {
+        found.push({
+          from: fileId,
+          to: symbol.id,
+          position: symbol.position,
+          use: "read",
+          resolution: "syntax",
+          test,
+        });
+      }
+      for (const binding of bindings) {
+        const symbol = answered.get(binding.node);
+        if (symbol === undefined) {
+          continue;
+        }
+        const position = renderPosition(file, root, binding.node.getStart());
+        const chained =
+          symbol === UNANSWERED
+            ? named(binding.node).map((id) => ({ id, stepped: false, guessed: true }))
+            : chains.chainOf(symbol);
+        // The markup may name any export of a module a binding holds whole.
+        const targets = binding.whole
+          ? chained.flatMap((target) => [
+              target,
+              ...declaredIn(target.id)
+                .filter((one) => one.exported)
+                .map((one) => ({ ...target, id: one.id })),
+            ])
+          : chained;
+        for (const target of targets) {
+          found.push({
+            from: fileId,
+            to: target.id,
+            position,
+            use: "read",
+            resolution: target.guessed ? "by-name" : target.stepped ? "alias" : "batch",
+            test,
+          });
+        }
+      }
+    }
+
     // A pattern names a property of the value it destructures, which no name node of
     // the pattern resolves to: a shorthand's name is the local it binds.
     destructured.resolve(reads).forEach((symbol, index) => {
@@ -851,10 +1049,11 @@ export function references<Brand>(
       const position = renderPosition(file, root, site.node.getStart());
       // A re-export something imports is used and so is the declaration behind it, so
       // the use names every link of the chain its name stands at the head of.
-      const targets =
+      const targets = throughAliases(
         symbol === UNANSWERED
           ? named(site.node).map((id) => ({ id, stepped: false, guessed: true }))
-          : chains.chainOf(symbol);
+          : chains.chainOf(symbol),
+      );
       for (const target of targets) {
         found.push({
           from: site.from,