@cplieger/deadset-ts 2.2.1 → 2.3.0

package/src/roots.ts

@@ -0,0 +1,467 @@
+/**
+ * The root set of one project: every declaration the analysis keeps live without a
+ * reference, and why.
+ *
+ * A root makes its declaration live under REACHABILITY and plays no part in
+ * reference counting, which asks only whether some declaration of the loaded graph
+ * names it. The two relations are different sets, so an exported declaration that
+ * something outside the program reaches is live under the first and still a
+ * candidate under the second.
+ */
+
+import type { SourceFile } from "@typescript/native/unstable/ast";
+import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import { REPOSITORY_DOCUMENT } from "./config.ts";
+import { entryPoints, type EntryRule } from "./entry-points.ts";
+import type { Finding } from "./finding.ts";
+import { globExpression } from "./glob.ts";
+import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import type { Manifest, ManifestEntry } from "./manifest.ts";
+import { byPosition } from "./position.ts";
+import type { ProjectView } from "./session.ts";
+import { sourceFilesOf } from "./source-files.ts";
+
+/** Why one declaration is a root. */
+export type RootKind =
+  /** A file `ts.entry_files` names, and what it exports. */
+  | "entry-file"
+  /** A file the manifest names as an importable entry point, and what it exports. */
+  | "manifest-entry"
+  /** A file the manifest names as a command, and what it exports. */
+  | "manifest-binary"
+  /** A declaration a consumer of a library target can name. */
+  | "published-api"
+  /** A declaration an exact reference from the configuration names. */
+  | "configured"
+  /** A declaration a pattern from the configuration names. */
+  | "pattern"
+  /** A file a tool or the platform enters by its own convention, and what it exports where the tool reads it. */
+  | EntryRule;
+
+/** One declaration the analysis keeps live under reachability, and why. */
+export interface Root {
+  /** The identifier of the declaration, as the inventory spells it. */
+  readonly id: string;
+  readonly kind: RootKind;
+  /**
+   * The string from a document that named this root: the configured root or pattern,
+   * the entry-file or test-file pattern that matched, the manifest member that named
+   * the file, the file-name convention a tool looks for, or the literal a
+   * configuration or a call writes. It is empty where a rule alone decided the root.
+   */
+  readonly source: string;
+}
+
+/** One project's roots, and every configured string that named nothing in it. */
+export interface Roots {
+  /** The compiler configuration the project was opened from. */
+  readonly configFile: string;
+  /**
+   * Every root of this project, ordered by the site of the declaration it names,
+   * then by kind, then by the string that named it. A declaration that is a root for
+   * more than one reason appears once per reason, so an explanation can name every
+   * reason it is live.
+   *
+   * The member says which relation the set feeds: every declaration here is live
+   * under reachability, and nothing here is live under reference counting.
+   */
+  readonly liveUnderReachability: readonly Root[];
+  /**
+   * Every configured root and pattern that named no declaration of this project, in
+   * configuration order and each once. It is per project, and a finding is per run:
+   * {@link unmatchedEverywhere} is what turns one into the other.
+   */
+  readonly unmatched: readonly string[];
+}
+
+/** What decides the roots beside the declarations themselves. */
+export interface RootOptions {
+  /** The target's own manifest. */
+  readonly manifest: Manifest;
+  /** `roots.patterns` from the resolved configuration. */
+  readonly patterns: readonly string[];
+  /** `ts.entry_files` from the resolved configuration. */
+  readonly entryFiles: readonly string[];
+  /** `ts.test_files` from the resolved configuration. */
+  readonly testFiles: readonly string[];
+  /** Whether the target is a library, so a consumer outside it reaches its published API. */
+  readonly publishedAPI: boolean;
+}
+
+/** The code the Contract gives a configured root that matches nothing. */
+const UNMATCHED_ROOT_CODE = "DS1704";
+
+/** The subject kind a finding under that code carries, from the Contract's vocabulary. */
+const UNMATCHED_ROOT_SUBJECT = "root";
+
+/** The fixed position of a finding about a document rather than about a line of one. */
+const DOCUMENT_POSITION = 1;
+
+/** Whether a configured string carries either special character. */
+function isPattern(text: string): boolean {
+  return text.includes("*") || text.includes("?");
+}
+
+/**
+ * Whether ref matches a pattern whose only special characters are `*`, which stands
+ * for any run of characters including the solidus, and `?`, which stands for exactly
+ * one character counted as a code point. A star keeps the position it last stood at,
+ * so the shortest run it can stand for is tried first.
+ */
+function matchGlob(pattern: readonly string[], ref: readonly string[]): boolean {
+  let next = 0;
+  let star = -1;
+  let resume = 0;
+  let at = 0;
+  while (at < ref.length) {
+    if (next < pattern.length && (pattern[next] === "?" || pattern[next] === ref[at])) {
+      next += 1;
+      at += 1;
+    } else if (next < pattern.length && pattern[next] === "*") {
+      star = next;
+      resume = at;
+      next += 1;
+    } else if (star >= 0) {
+      resume += 1;
+      next = star + 1;
+      at = resume;
+    } else {
+      return false;
+    }
+  }
+  while (next < pattern.length && pattern[next] === "*") {
+    next += 1;
+  }
+  return next === pattern.length;
+}
+
+/**
+ * Whether one configured string names the symbol reference ref. A string carrying
+ * neither special character names only the reference it spells.
+ *
+ * Both sides are read as code points: a character outside the basic plane is two
+ * string units, and `?` stands for one character.
+ */
+export function matchRef(pattern: string, ref: string): boolean {
+  if (!isPattern(pattern)) {
+    return pattern === ref;
+  }
+  return matchGlob(Array.from(pattern), Array.from(ref));
+}
+
+/** 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;
+}
+
+/** The members of one declaration, indexed by the container that holds them. */
+function childrenOf(held: Inventory): ReadonlyMap<string, readonly InventorySymbol[]> {
+  const byParent = new Map<string, InventorySymbol[]>();
+  for (const symbol of held.symbols) {
+    const siblings = byParent.get(symbol.parent);
+    if (siblings === undefined) {
+      byParent.set(symbol.parent, [symbol]);
+    } else {
+      siblings.push(symbol);
+    }
+  }
+  return byParent;
+}
+
+/**
+ * The roots one project holds, and every configured string that named nothing in it.
+ *
+ * A file a manifest member, an entry-file pattern or a tool's configuration names
+ * is a root with everything its module exports: each name of the module's export
+ * table, and where a name is a re-export, every link of the chain to the declaration
+ * it carries, so a re-exported declaration is a root of the file that publishes it.
+ * A file a runtime executes without reading its exports, a test file or a worker, is
+ * a root by itself.
+ */
+export function roots<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  targetRoot: string,
+  options: RootOptions,
+): Roots {
+  const files = sourceFilesOf(project, targetRoot);
+  const declared = held.declarations;
+  const fileIds = new Map<string, string>();
+  for (const file of files.byName.values()) {
+    const id = declared.get(nodeKey(file, file));
+    if (id !== undefined) {
+      fileIds.set(file.fileName, id);
+    }
+  }
+  const found = new Map<string, Root>();
+  const add = (id: string, kind: RootKind, source: string): void => {
+    found.set([id, kind, source].join("\u0000"), { id, kind, source });
+  };
+
+  const entered: { file: SourceFile; kind: RootKind; source: string; exports: boolean }[] = [];
+  const enter = (file: SourceFile, kind: RootKind, source: string, exports: boolean): void => {
+    entered.push({ file, kind, source, exports });
+  };
+
+  const published: SourceFile[] = [];
+  const publishes = (entry: ManifestEntry): boolean =>
+    entry.published &&
+    (options.manifest.declaresExports ? entry.member.startsWith("exports") : true);
+  for (const entry of options.manifest.entries) {
+    for (const file of files.named(entry.path)) {
+      enter(file, entry.role === "run" ? "manifest-binary" : "manifest-entry", entry.member, true);
+      if (options.publishedAPI && publishes(entry)) {
+        published.push(file);
+      }
+    }
+  }
+  for (const pattern of options.entryFiles) {
+    const expression = globExpression(pattern);
+    for (const [path, file] of files.byPath) {
+      if (expression.test(path)) {
+        enter(file, "entry-file", pattern, true);
+      }
+    }
+  }
+  for (const point of entryPoints(project, files, options.testFiles)) {
+    enter(point.file, point.rule, point.source, point.exports);
+  }
+
+  const exportsOf = exportTables(
+    project,
+    held,
+    [...entered.filter((entry) => entry.exports).map((entry) => entry.file), ...published],
+    files.byName,
+  );
+  for (const entry of entered) {
+    const id = fileIds.get(entry.file.fileName);
+    if (id === undefined) {
+      continue;
+    }
+    add(id, entry.kind, entry.source);
+    if (entry.exports) {
+      for (const exported of exportsOf.get(entry.file.fileName) ?? []) {
+        add(exported, entry.kind, entry.source);
+      }
+    }
+  }
+
+  if (options.publishedAPI) {
+    for (const id of publishedAPI(published, exportsOf, held)) {
+      add(id, "published-api", "");
+    }
+  }
+
+  const unmatched = configured(held, options.patterns, add);
+
+  const sites = new Map(held.symbols.map((symbol) => [symbol.id, symbol.position]));
+  const ordered = [...found.values()].sort((a, b) => {
+    const left = sites.get(a.id);
+    const right = sites.get(b.id);
+    const site = left === undefined || right === undefined ? 0 : byPosition(left, right);
+    return site || compare(a.kind, b.kind) || compare(a.source, b.source);
+  });
+
+  return { configFile: project.configFile, liveUnderReachability: ordered, unmatched };
+}
+
+/**
+ * Every declaration each file's module exports, by the file's name: the declaration
+ * each name of the export table is, and every link of a re-export's chain. A name
+ * whose declaration is outside the project's own files belongs to another program
+ * and names nothing here.
+ *
+ * One batch resolves every file to its module and one request per module reads
+ * its export table, star re-exports resolved into it. A file that is no module
+ * exports nothing.
+ */
+function exportTables<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  wanted: readonly SourceFile[],
+  ownFiles: ReadonlyMap<string, SourceFile>,
+): ReadonlyMap<string, readonly string[]> {
+  const unique = [...new Map(wanted.map((file) => [file.fileName, file])).values()];
+  const tables = new Map<string, readonly string[]>();
+  if (unique.length === 0) {
+    return tables;
+  }
+  const modules = project.symbolsAt(unique.map((file) => project.handle(file)));
+  const chains = new Map<number, readonly string[]>();
+
+  const chainOf = (symbol: TSSymbol): readonly string[] => {
+    const cached = chains.get(symbol.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const ids: string[] = [];
+    const walked = new Set<number>();
+    let at: TSSymbol | undefined = symbol;
+    while (at !== undefined && !walked.has(at.id)) {
+      walked.add(at.id);
+      for (const handle of at.declarations) {
+        if (!ownFiles.has(handle.path)) {
+          continue;
+        }
+        const node = project.declarationAt(handle)?.node;
+        const id =
+          node === undefined
+            ? undefined
+            : held.declarations.get(nodeKey(node.getSourceFile(), node));
+        if (id !== undefined && !ids.includes(id)) {
+          ids.push(id);
+        }
+      }
+      at = project.aliasStepOf(at);
+    }
+    chains.set(symbol.id, ids);
+    return ids;
+  };
+
+  unique.forEach((file, index) => {
+    const module = modules[index];
+    if (module === undefined) {
+      tables.set(file.fileName, []);
+      return;
+    }
+    const ids = new Set<string>();
+    for (const exported of project.checker.getExportsOfModule(module)) {
+      for (const id of chainOf(exported)) {
+        ids.add(id);
+      }
+    }
+    tables.set(file.fileName, [...ids]);
+  });
+  return tables;
+}
+
+/** The kinds of container whose export table, not its members' visibility, says what it publishes. */
+const EXPORTING_CONTAINERS: ReadonlySet<string> = new Set(["file", "namespace"]);
+
+/**
+ * Every declaration a consumer of the library can name: what the published files
+ * export, and below each, the members a consumer reaches through it.
+ *
+ * The published files are the ones `exports` reaches where the manifest declares
+ * one, because a package that declares `exports` has said exactly what a consumer may
+ * import; where it declares none, they are the ones the members that preceded it
+ * name. Below a published module or namespace the walk follows what its export table
+ * names; below any other published declaration it follows every member a consumer
+ * can write: a public one, and a protected one, which a consumer's subclass names. A
+ * private member is not published, nor is anything below one, and a type parameter
+ * is not published either, because a consumer supplies a type argument by position.
+ *
+ * A published file is not itself published. A consumer imports a module and names
+ * what it exports; the file is a root because the manifest names it, which is a
+ * different reason.
+ */
+function publishedAPI(
+  published: readonly SourceFile[],
+  exportsOf: ReadonlyMap<string, readonly string[]>,
+  held: Inventory,
+): readonly string[] {
+  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+  const children = childrenOf(held);
+  const reached = new Set<string>();
+  const pending: string[] = [];
+  for (const file of published) {
+    for (const id of exportsOf.get(file.fileName) ?? []) {
+      if (byId.get(id)?.kind === "file") {
+        pending.push(id);
+      } else if (!reached.has(id)) {
+        reached.add(id);
+        pending.push(id);
+      }
+    }
+  }
+  for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+    const exporting = EXPORTING_CONTAINERS.has(byId.get(next)?.kind ?? "");
+    for (const member of children.get(next) ?? []) {
+      const reachable = exporting
+        ? member.exported
+        : member.visibility !== "private" && member.visibility !== "private-name";
+      if (member.kind === "type-parameter" || reached.has(member.id) || !reachable) {
+        continue;
+      }
+      reached.add(member.id);
+      pending.push(member.id);
+    }
+  }
+  return [...reached];
+}
+
+/**
+ * Keeps every declaration the configuration names and returns every string that
+ * named none, in configuration order. A string the configuration lists twice is one
+ * configured root.
+ */
+function configured(
+  held: Inventory,
+  patterns: readonly string[],
+  add: (id: string, kind: RootKind, source: string) => void,
+): readonly string[] {
+  const unmatched: string[] = [];
+  for (const pattern of new Set(patterns)) {
+    const kind: RootKind = isPattern(pattern) ? "pattern" : "configured";
+    let matched = false;
+    for (const symbol of held.symbols) {
+      if (matchRef(pattern, symbol.ref)) {
+        add(symbol.id, kind, pattern);
+        matched = true;
+      }
+    }
+    if (!matched) {
+      unmatched.push(pattern);
+    }
+  }
+  return unmatched;
+}
+
+/**
+ * Every configured string that named no declaration in ANY project of the run, in
+ * configuration order and each once.
+ *
+ * A finding about a configured root is about the configuration and not about a
+ * declaration, so there is one per run: a string that names a declaration of one
+ * project has named something, and the projects it named nothing in are not a
+ * finding. A run with no project names nothing with any of them.
+ */
+export function unmatchedEverywhere(
+  patterns: readonly string[],
+  perProject: readonly Roots[],
+): readonly string[] {
+  return [...new Set(patterns)].filter((pattern) =>
+    perProject.every((project) => project.unmatched.includes(pattern)),
+  );
+}
+
+/**
+ * The findings a run reports for the configured strings that named nothing.
+ *
+ * `document` is the path of the document that declared the roots, below the target
+ * root; where the run read them from no document of the target it is empty and the
+ * finding names the conventional repository configuration, which is the document a
+ * maintainer writes a configured root in. Every finding of one run sits at that
+ * document's first position: the roots are written as an array whose members carry
+ * no line of their own, so the string each finding names is what tells one from
+ * another.
+ */
+export function unmatchedRoots(sources: readonly string[], document: string): readonly Finding[] {
+  const position = {
+    path: document === "" ? REPOSITORY_DOCUMENT : document,
+    line: DOCUMENT_POSITION,
+    column: DOCUMENT_POSITION,
+    endLine: DOCUMENT_POSITION,
+  };
+  return sources.map((source) => ({
+    code: UNMATCHED_ROOT_CODE,
+    position,
+    symbol: { ref: source, kind: UNMATCHED_ROOT_SUBJECT, name: source, sizeLines: 1 },
+    message: isPattern(source)
+      ? "configured root pattern matches no symbol of the inventory"
+      : "configured root matches no symbol of the inventory",
+  }));
+}

package/src/run.ts

@@ -1,4 +1,5 @@
-import { ConfigError, type Inputs } from "./config.ts";
+import { runRoots, type RunRoot } from "./analysis.ts";
+import { ConfigError, REPOSITORY_DOCUMENT, type Inputs } from "./config.ts";
 import {
   diagnosticErrors,
   discoverProjects,
@@ -18,11 +19,9 @@ export interface Writer {
   write(text: string): void;
 }
 
-/** The repository configuration's name at the target root. */
-const REPOSITORY_DOCUMENT = "deadset.json";
-
 /** The exit codes the Contract's exit-code table names. */
 const EXIT_CLEAN = 0;
+const EXIT_FINDINGS = 1;
 const EXIT_USAGE = 2;
 const EXIT_FAILURE = 3;
 
@@ -219,6 +218,9 @@ export function run(
   if (verb === "print-projects") {
     return printProjectsVerb(args.slice(1), out, err, host, openClient);
   }
+  if (verb === "print-roots") {
+    return printRootsVerb(args.slice(1), out, err, host, openClient);
+  }
   if (verb !== undefined && (VERBS as readonly string[]).includes(verb)) {
     err.write(`deadset-ts: ${verb} is not implemented\n`);
     return EXIT_USAGE;
@@ -282,6 +284,55 @@ function printProjectsVerb(
   }
 }
 
+/**
+ * One root as a line: the declaration's reference, why it is a root, and the string
+ * that named it, separated by tabs. A run of several configurations adds the ones
+ * whose project holds the root as a fourth field, and writes the third present and
+ * empty where no string named the root, so every line of one run holds the same
+ * fields.
+ */
+function rootLine(root: RunRoot, several: boolean): string {
+  const line = `${root.ref}\t${root.kind}`;
+  if (several) {
+    return `${line}\t${root.source}\t${root.configurations.join(" ")}`;
+  }
+  return root.source === "" ? line : `${line}\t${root.source}`;
+}
+
+/**
+ * Writes the root set of the run, one root per line, and then names on the error
+ * stream, by its issue kind, every configured root or pattern that named nothing;
+ * one such string fails the run. The line shape is this command's own rather than a
+ * Contract format, so that sort and cut read it.
+ */
+function printRootsVerb(
+  args: readonly string[],
+  out: Writer,
+  err: Writer,
+  host: Host,
+  openClient: (collectTiming: boolean) => Engine,
+): number {
+  let engine: Engine | undefined;
+  try {
+    const options = readOptions(args);
+    const { config, provenance } = resolve(inputsOf(host, options));
+    const scope = scopeOf(host, options);
+    engine = openClient(false);
+    const answer = runRoots(engine, host, scope, config, provenance);
+    const several = answer.configurations.length > 1;
+    for (const root of answer.roots) {
+      out.write(`${rootLine(root, several)}\n`);
+    }
+    for (const finding of answer.findings) {
+      err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
+    }
+    return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
+  } catch (error: unknown) {
+    engine?.close();
+    return refuse(error, err);
+  }
+}
+
 /** Turns one refusal into the exit code the Contract's table gives it. */
 function refuse(error: unknown, err: Writer): number {
   if (error instanceof ConfigError) {

package/src/session.ts

@@ -1,4 +1,4 @@
-import { API } from "@typescript/native/unstable/sync";
+import { API, SymbolFlags } from "@typescript/native/unstable/sync";
 import type {
   Checker,
   Diagnostic,
@@ -174,6 +174,11 @@ function viewOf<Brand>(project: Project): ProjectView<Brand> {
       isIdentifier(node) ? project.checker.getResolvedSymbol(node) : undefined,
     shorthandValueAt: ({ node }) => project.checker.getShorthandAssignmentValueSymbol(node),
     aliasStepOf: (symbol) => {
+      // The step is asked of an alias only: asked of any other symbol, the compiler
+      // fails an assertion and the session ends.
+      if ((symbol.flags & SymbolFlags.Alias) === 0) {
+        return undefined;
+      }
       const held = project.checker.getImmediateAliasedSymbol(symbol);
       // An alias that resolves to nothing answers with the checker's own unknown
       // symbol, which declares nothing; a symbol that is no alias answers with