@cplieger/deadset-ts 5.2.3 → 6.0.1

package/src/roots.ts

@@ -15,6 +15,7 @@ import {
   isQualifiedName,
   isTypeQueryNode,
   isTypeReferenceNode,
+  isVariableStatement,
   type Node,
   type SourceFile,
 } from "@typescript/native/unstable/ast";
@@ -297,6 +298,7 @@ export function roots<Brand>(
     options.host,
     targetRoot,
     options.parse,
+    options.conventions?.selected,
   );
   const published: SourceFile[] = [];
   const entries = [
@@ -379,7 +381,7 @@ export function roots<Brand>(
   }
 
   const api = options.publishedAPI
-    ? publishedAPI(project, published, exportsOf, held, files.byPath)
+    ? publishedAPI(project, published, exportsOf, held, files.byPath, releaseTagged(held, files))
     : { ids: [], guessed: [] };
   for (const id of api.ids) {
     add(id, "published-api", "");
@@ -453,16 +455,59 @@ function exportTables<Brand>(
   return { tables, answered };
 }
 
+/** A release tag of a documentation comment: `@` and its name, between white space or the ends. */
+const RELEASE_TAG = /(?:^|\s)@(?:public|beta|alpha)(?=\s|$)/u;
+
+/**
+ * Whether the documentation comment of the statement that starts at `start`, the last
+ * `/** *\/` comment before it with only white space between the two, holds a release tag.
+ */
+function releaseTagIn(text: string, from: number, start: number): boolean {
+  const leading = text.slice(from, start);
+  const open = leading.lastIndexOf("/**");
+  const close = open < 0 ? -1 : leading.indexOf("*/", open + 3);
+  if (close < 0 || leading.slice(close + 2).trim() !== "") {
+    return false;
+  }
+  return RELEASE_TAG.test(leading.slice(open + 3, close));
+}
+
+/** The exported top-level declarations of the program's files a release tag marks. */
+function releaseTagged(
+  held: Inventory,
+  files: { readonly byPath: ReadonlyMap<string, SourceFile> },
+): readonly string[] {
+  const exported = new Set(held.symbols.filter((symbol) => symbol.exported).map((one) => one.id));
+  const found: string[] = [];
+  for (const file of files.byPath.values()) {
+    for (const statement of file.statements) {
+      if (!releaseTagIn(file.text, statement.pos, statement.getStart())) {
+        continue;
+      }
+      const nodes: readonly Node[] = isVariableStatement(statement)
+        ? statement.declarationList.declarations
+        : [statement];
+      for (const node of nodes) {
+        const id = held.declarations.get(nodeKey(file, node));
+        if (id !== undefined && exported.has(id)) {
+          found.push(id);
+        }
+      }
+    }
+  }
+  return found;
+}
+
 /** 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 writes: a namespace's exported ones, any other
- * declaration's public and protected ones, never a private one or a type parameter. A
- * declaration a published one's type names is published too, exported or not. A type name
- * the checker leaves unanswered publishes every declaration spelled as it is, and those are
- * `guessed`. A published file is not itself published.
+ * Every declaration a consumer of the library can name: what the published files export,
+ * and below each the members a consumer writes, a namespace's exported ones and any other
+ * declaration's public and protected ones. A declaration a published one's type names is
+ * published too, and so is an exported declaration a release tag marks. A type name the
+ * checker leaves unanswered publishes every declaration spelled as it is, as `guessed`. A
+ * published file is not itself published.
  */
 function publishedAPI<Brand>(
   project: ProjectView<Brand>,
@@ -470,6 +515,7 @@ function publishedAPI<Brand>(
   exportsOf: ReadonlyMap<string, readonly string[]>,
   held: Inventory,
   byPath: ReadonlyMap<string, SourceFile>,
+  tagged: readonly string[],
 ): { readonly ids: readonly string[]; readonly guessed: readonly string[] } {
   const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
   const children = childrenOf(held);
@@ -484,6 +530,9 @@ function publishedAPI<Brand>(
       pending.push(id);
     }
   };
+  for (const id of tagged) {
+    reach(id);
+  }
   for (const file of published) {
     for (const id of exportsOf.get(file.fileName) ?? []) {
       if (byId.get(id)?.kind === "file") {

package/src/suppress-file.ts

@@ -11,6 +11,7 @@ import { jsonChunks } from "./json-chunks.ts";
 import { joinPath } from "./paths.ts";
 import { positionAt, walkDocument } from "./json-document.ts";
 import type { Position } from "./position.ts";
+import { declarationKey } from "./ref.ts";
 import {
   CODE_FORM,
   SUPPRESSION_WITHOUT_REASON,
@@ -84,10 +85,6 @@ interface Read {
 /** The declarations of the run by reference and file, which is what an entry names. */
 type ByReference = ReadonlyMap<string, readonly InventorySymbol[]>;
 
-function referenceKey(ref: string, path: string): string {
-  return `${ref}\u0000${path}`;
-}
-
 /**
  * Reads one entry or row: the records it binds, the refusals it carries, or the
  * malformed value that ends the run.
@@ -148,7 +145,7 @@ function readRecord(value: unknown, site: Position, byReference: ByReference, sh
   if (refusals.length > 0) {
     return { records: [], refusals };
   }
-  const named = byReference.get(referenceKey(symbol, written.path)) ?? [];
+  const named = byReference.get(declarationKey(symbol, written.path)) ?? [];
   if (named.length === 0) {
     return { records: [{ ...written, bound: "" }], refusals: [] };
   }
@@ -158,7 +155,7 @@ function readRecord(value: unknown, site: Position, byReference: ByReference, sh
 function byReferenceOf(symbols: readonly InventorySymbol[]): ByReference {
   const byReference = new Map<string, InventorySymbol[]>();
   for (const symbol of symbols) {
-    const key = referenceKey(symbol.ref, symbol.position.path);
+    const key = declarationKey(symbol.ref, symbol.position.path);
     byReference.set(key, [...(byReference.get(key) ?? []), symbol]);
   }
   return byReference;

package/src/sweep.ts

@@ -27,6 +27,18 @@ export interface Exemption {
    * record holds only while that file is live.
    */
   readonly whileLive?: string;
+  /**
+   * The interface methods the retained member implements, and whether its body is empty.
+   * The record holds only while one of them is called through its interface.
+   */
+  readonly implementing?: Implementing;
+}
+
+/** The interface methods one retained class member implements, and whether its body is empty. */
+export interface Implementing {
+  /** The declarations of the interface's methods the member answers, by identifier. */
+  readonly methods: readonly string[];
+  readonly empty: boolean;
 }
 
 /**

package/src/version.ts

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "5.3.0";
+export const CONTRACT_VERSION = "6.0.0";

package/src/workflow-steps.ts

@@ -0,0 +1,104 @@
+/**
+ * The source files a CI workflow's `run:` steps name by their path from the target root.
+ * A workflow file is read as text, line by line, with no YAML parsed.
+ */
+
+import type { SourceFile } from "@typescript/native/unstable/ast";
+import type { Host } from "./host.ts";
+import { scriptTokens } from "./manifest.ts";
+import { joinPath, resolvePath } from "./paths.ts";
+import type { SourceFiles } from "./source-files.ts";
+
+/** One file a workflow step names. */
+interface WorkflowEntry {
+  readonly file: SourceFile;
+  /** The token that named it, as the command writes it. */
+  readonly source: string;
+}
+
+const WORKFLOWS = ".github/workflows";
+
+/** A line holding a run command: indentation and one sequence marker before `run:`. */
+const RUN_LINE = /^(\s*(?:- )?)run:(.*)$/u;
+
+const BLOCK_SCALAR = /^[|>][+-]?$/u;
+
+const QUOTED = /^(["'])(.*)\1$/su;
+
+/** A token holding one of these is computed or a pattern, so it names no file. */
+const COMPUTED = /[${*?[]/u;
+
+const INDENT = /^\s*/u;
+
+function workflowFiles(host: Host, dir: string): readonly string[] {
+  let entries;
+  try {
+    entries = host.readDirectory(dir);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => !entry.directory && /\.ya?ml$/u.test(entry.name))
+    .map((entry) => joinPath(dir, entry.name))
+    .sort();
+}
+
+/** Every command line one workflow file's `run:` steps hold. */
+export function runCommands(text: string): readonly string[] {
+  const lines = text.split(/\r?\n/u);
+  const found: string[] = [];
+  for (let at = 0; at < lines.length; at += 1) {
+    const match = RUN_LINE.exec(lines[at] ?? "");
+    if (match === null) {
+      continue;
+    }
+    const column = (match[1] ?? "").length;
+    const value = (match[2] ?? "").trim().replace(QUOTED, "$2");
+    if (!BLOCK_SCALAR.test(value)) {
+      found.push(value);
+      continue;
+    }
+    for (let next = at + 1; next < lines.length; next += 1) {
+      const line = lines[next] ?? "";
+      if (line.trim() !== "" && (INDENT.exec(line)?.[0].length ?? 0) <= column) {
+        break;
+      }
+      found.push(line);
+    }
+  }
+  return found;
+}
+
+/**
+ * The own files the `run:` steps of every workflow file in the target root's
+ * `.github/workflows` name: a token equal to a file's path below the target root, with or
+ * without a leading `./`, whatever directory the step runs in.
+ */
+export function workflowEntries(
+  host: Host,
+  targetRoot: string,
+  files: SourceFiles,
+): readonly WorkflowEntry[] {
+  const dir = joinPath(resolvePath(host.workingDirectory(), targetRoot), WORKFLOWS);
+  const found: WorkflowEntry[] = [];
+  for (const path of workflowFiles(host, dir)) {
+    let text: string;
+    try {
+      text = host.readFile(path);
+    } catch {
+      continue;
+    }
+    for (const command of runCommands(text)) {
+      for (const token of scriptTokens(command)) {
+        if (COMPUTED.test(token)) {
+          continue;
+        }
+        const file = files.byPath.get(token.startsWith("./") ? token.slice(2) : token);
+        if (file !== undefined) {
+          found.push({ file, source: token });
+        }
+      }
+    }
+  }
+  return found;
+}

package/src/workspace-programs.ts

@@ -17,7 +17,7 @@ import type {
 import { isStringLiteralLikeNode } from "@typescript/native/unstable/ast";
 import type { StringLiteralLikeNode } from "@typescript/native/unstable/ast";
 import type { Host } from "./host.ts";
-import { dirnamePath, joinPath, resolvePath } from "./paths.ts";
+import { dirnamePath, resolvePath } from "./paths.ts";
 import type { Engine } from "./session.ts";
 import type { WorkspaceResolver } from "./workspace-resolution.ts";
 
@@ -82,34 +82,6 @@ function analysisOptions(parsed: Parsed): CreateSnapshotProgramParams["compilerO
   return composite === true ? { ...kept, declaration: true } : kept;
 }
 
-/**
- * The references a built program can carry: only where every referenced
- * configuration reads and is composite with output, because the compiler reports a
- * broken reference at syntax a built program does not have.
- */
-function carriedReferences(
-  engine: Engine,
-  parsed: Parsed,
-): NonNullable<Parsed["projectReferences"]> {
-  const references = parsed.projectReferences ?? [];
-  for (const reference of references) {
-    // A reference that names a directory names the `tsconfig.json` in it.
-    const configFile = reference.path.endsWith(".json")
-      ? reference.path
-      : joinPath(reference.path, "tsconfig.json");
-    let options: Parsed["options"];
-    try {
-      options = engine.parseConfigFile(configFile).options;
-    } catch {
-      return [];
-    }
-    if (options.composite !== true || options.noEmit === true) {
-      return [];
-    }
-  }
-  return references;
-}
-
 /** The conditions an `exports` lookup under one configuration and one resolution mode reads. */
 function conditionsOf(parsed: Parsed, mode: ResolutionMode | undefined): ReadonlySet<string> {
   const resolution = parsed.options.moduleResolution;
@@ -132,7 +104,6 @@ function resolutionMode(kind: ModuleKind): ResolutionMode | undefined {
 interface Reading {
   readonly configFile: string;
   readonly parsed: Parsed;
-  readonly references: NonNullable<Parsed["projectReferences"]>;
   readonly entries: ModuleResolutionEntry[];
   readonly seen: Set<string>;
   /** Per member specifier, every file an import of it is read as. */
@@ -181,7 +152,7 @@ function configurationOf(
   if (reason !== undefined) {
     return { kind: "unread", reason };
   }
-  const { options } = reading.parsed;
+  const { options, projectReferences: references = [] } = reading.parsed;
   const raw: unknown = (options as Record<string, unknown>)["pathsBasePath"];
   const base = typeof raw === "string" ? raw : dirnamePath(reading.configFile);
   const paths: Record<string, string[]> = {};
@@ -204,8 +175,8 @@ function configurationOf(
       ...(options.composite === true ? { composite: false, declaration: true } : {}),
       paths,
     },
-    ...(reading.references.length > 0
-      ? { references: reading.references.map((reference) => ({ path: reference.path })) }
+    ...(references.length > 0
+      ? { references: references.map((reference) => ({ path: reference.path })) }
       : {}),
     ...(exclude === undefined ? {} : { exclude }),
   });
@@ -240,6 +211,7 @@ function programOf(
   reading: Reading,
 ): { readonly params: CreateSnapshotProgramParams; readonly resolver: ModuleResolver } {
   const compilerOptions = analysisOptions(reading.parsed);
+  const references = reading.parsed.projectReferences ?? [];
   const resolver = engine.createModuleResolver(compilerOptions, reading.entries);
   return {
     resolver,
@@ -249,7 +221,7 @@ function programOf(
       options: {
         moduleResolver: resolver,
         configFileParsingDiagnostics: reading.parsed.errors,
-        ...(reading.references.length > 0 ? { projectReferences: reading.references } : {}),
+        ...(references.length > 0 ? { projectReferences: references } : {}),
       },
     },
   };
@@ -436,7 +408,6 @@ export function workspacePrograms(
       {
         configFile,
         parsed,
-        references: carriedReferences(engine, parsed),
         entries: [],
         seen: new Set<string>(),
         bound: new Map<string, Set<string>>(),