@cplieger/deadset-ts 5.2.2 → 6.0.0

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/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-run.ts

@@ -41,10 +41,9 @@ export interface WorkspaceRun {
   referenceOnly(configFile: string, compiled?: readonly string[]): (file: string) => boolean;
   /**
    * Whether one file a target configuration's program holds is the target's own. A
-   * workspace package's file is by its path alone, whichever import reached it: the
-   * compiler's answer for a file reached both through `node_modules` and from source
-   * depends on which import it followed first. Any other file is unless the compiler
-   * reached it as a library's.
+   * workspace package's file is by its path alone: the run reads another package from
+   * its source, so the compiler holds that package's files as the importer's own, not
+   * as a library's. Any other file is unless the compiler reached it as a library's.
    */
   ownFile(file: string, fromExternalLibrary: boolean): boolean;
   /** The target's own manifest, its targets read back to source. */