@cplieger/deadset-ts 8.0.0-dev.14 → 8.0.0-dev.16

package/src/platform-symbols.ts

@@ -0,0 +1,205 @@
+/**
+ * The platform's names read through a program's checker: its `require` and `URL`, as
+ * `platform-calls.ts` decides them, its worker constructors and `navigator`, and Node's
+ * `Worker`.
+ */
+
+import {
+  isArrowFunction,
+  isClassDeclaration,
+  isClassExpression,
+  isFunctionDeclaration,
+  isFunctionExpression,
+  isMethodDeclaration,
+  isModuleDeclaration,
+  isPropertyAssignment,
+  isPropertyDeclaration,
+  isSourceFile,
+  isStringLiteralLikeNode,
+  isVariableDeclaration,
+  type Identifier,
+  type Node,
+} from "@typescript/native/ast";
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/sync";
+import { UNANSWERED, type Answer } from "./query.ts";
+import type { ProjectView } from "./session.ts";
+import { boundExports, NAMESPACE } from "./entries/static-module.ts";
+import { isAmbient } from "./inventory.ts";
+import { callsPlatformBy, carriedNames, type BindingOf, type Bound } from "./platform-calls.ts";
+import { unwrapped } from "./unwrap.ts";
+
+/** Counts one request a platform decision puts to the checker. */
+type Asked = () => void;
+
+/** The symbol one symbol names through its aliases, or the symbol itself where it is none. */
+function dealiased<Brand>(
+  project: ProjectView<Brand>,
+  symbol: TSSymbol,
+  asked: Asked,
+): Answer<TSSymbol> {
+  if ((symbol.flags & SymbolFlags.Alias) === 0) {
+    return symbol;
+  }
+  asked();
+  return project.queries.aliased(symbol);
+}
+
+/** Each declaration of `symbol` in a file of the target, read in this project's program. */
+function ownDeclarations<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): readonly Node[] {
+  const own = project.ownPaths();
+  return symbol.declarations.flatMap((handle) => {
+    const node = own.has(handle.path) ? project.declarationAt(handle)?.node : undefined;
+    return node === undefined ? [] : [node];
+  });
+}
+
+/**
+ * Whether one declaration writes a function or a class with a body (roots.23): a function
+ * or method declaration with a body, a class declaration, or a variable, a property or a
+ * class field whose initializer is a function, an arrow function or a class expression,
+ * under no `declare` modifier and in no declaration file.
+ */
+function writesBody(node: Node): boolean {
+  const value =
+    (isVariableDeclaration(node) || isPropertyAssignment(node) || isPropertyDeclaration(node)) &&
+    node.initializer !== undefined
+      ? unwrapped(node.initializer)
+      : node;
+  return (
+    (isFunctionDeclaration(value) || isMethodDeclaration(value)
+      ? value.body !== undefined
+      : isFunctionExpression(value) ||
+        isArrowFunction(value) ||
+        isClassDeclaration(value) ||
+        isClassExpression(value)) && !isAmbient(value.getSourceFile(), value)
+  );
+}
+
+/**
+ * What the checker binds `symbol` to, one alias step at a time: every name a step of the
+ * chain carries it by, and the declarations of the target its last step reaches, which
+ * prove it the target's own where one {@link writesBody}. A chain that ends at no
+ * declaration, or that the checker leaves unanswered, reaches none.
+ */
+function boundBy<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+  asked: Asked,
+): Bound | undefined {
+  if (typeof symbol !== "object") {
+    return undefined;
+  }
+  const names = new Set<string>();
+  const stepped = new Set<number>();
+  for (let at: TSSymbol | undefined = symbol; at !== undefined && !stepped.has(at.id);) {
+    stepped.add(at.id);
+    names.add(at.name);
+    const own = ownDeclarations(project, at);
+    for (const node of own) {
+      carriedNames(node).forEach((one) => names.add(one));
+    }
+    if ((at.flags & SymbolFlags.Alias) === 0) {
+      return { names, own, provenOwn: own.some(writesBody) };
+    }
+    asked();
+    const next = project.aliasStepOf(at);
+    at = typeof next === "object" ? next : undefined;
+  }
+  return { names, own: [], provenOwn: false };
+}
+
+/** Each written name's binding, as this project's checker answers it. */
+function checkerBinding<Brand>(project: ProjectView<Brand>, asked: Asked): BindingOf {
+  return (written) => {
+    asked();
+    return boundBy(project, project.symbolsAt([project.handle(written)])[0], asked);
+  };
+}
+
+/**
+ * Whether a call or construction through `callee`, the batch's answer for which is `symbol`,
+ * is one of the platform's `require` or `URL` (roots.23, references-ts.1), as
+ * {@link callsPlatformBy} decides it over this project's checker, each request it puts
+ * counted by `asked`.
+ */
+export function callsPlatform<Brand>(
+  project: ProjectView<Brand>,
+  name: "require" | "URL",
+  callee: Identifier,
+  symbol: Answer<TSSymbol> | undefined,
+  asked: Asked,
+): boolean {
+  const others = checkerBinding(project, asked);
+  return callsPlatformBy(name, callee, (written) =>
+    written === callee ? boundBy(project, symbol, asked) : others(written),
+  );
+}
+
+/**
+ * Whether a worker's constructor or `navigator`, the batch's answer for which is `symbol`, is
+ * the platform's (references-ts.2): a name the checker leaves unanswered, or one whose symbol
+ * is no alias and has a declaration outside the target's files.
+ */
+export function isPlatformGlobal<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+): boolean {
+  if (symbol === UNANSWERED) {
+    return true;
+  }
+  const own = project.ownPaths();
+  return (
+    symbol !== undefined &&
+    (symbol.flags & SymbolFlags.Alias) === 0 &&
+    symbol.declarations.some((handle) => !own.has(handle.path))
+  );
+}
+
+/** The module names Node's worker threads are imported by. */
+const THREADS: ReadonlySet<string> = new Set(["worker_threads", "node:worker_threads"]);
+
+function namesThreads(node: Node | undefined): boolean {
+  return node !== undefined && isStringLiteralLikeNode(node) && THREADS.has(node.text);
+}
+
+/** Whether one declaration is written in the body of `declare module "worker_threads"`. */
+function inThreadsModule(node: Node): boolean {
+  for (let at = node; !isSourceFile(at); at = at.parent) {
+    if (isModuleDeclaration(at) && namesThreads(at.name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a `Worker` constructor, the batch's answer for which is `symbol`, is Node's
+ * (references-ts.2): its symbol resolves to a declaration of `worker_threads`, or one of its
+ * own declarations binds the module's `Worker`, or `holder`, the namespace it is read
+ * through, binds the module, each binding read as {@link boundExports} reads one, which
+ * decides where the module has no declaration. Each request it puts is counted by `asked`.
+ */
+export function startsThread<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+  holder: Answer<TSSymbol> | undefined,
+  asked: Asked,
+): boolean {
+  const bindingOf = checkerBinding(project, asked);
+  const declared = (one: Answer<TSSymbol> | undefined, member: string): boolean =>
+    typeof one === "object" &&
+    ownDeclarations(project, one).some((node) =>
+      boundExports(node, (specifier) => THREADS.has(specifier), bindingOf).includes(member),
+    );
+  if (declared(symbol, "Worker") || declared(holder, NAMESPACE)) {
+    return true;
+  }
+  const named = typeof symbol === "object" ? dealiased(project, symbol, asked) : undefined;
+  return (
+    typeof named === "object" &&
+    named.declarations.some((handle) => {
+      const node = project.declarationAt(handle)?.node;
+      return node !== undefined && inThreadsModule(node);
+    })
+  );
+}

package/src/position.ts

@@ -48,6 +48,48 @@ export function writtenLength(file: SourceFile): number {
   return isComponentFile(file) ? file.originalText.length : file.text.length;
 }
 
+/** Whether one character ends a line, under the language's line terminators. */
+function endsLine(char: string | undefined): boolean {
+  return char === "\n" || char === "\r" || char === "\u2028" || char === "\u2029";
+}
+
+/** The offset where the line holding `from` ends. */
+export function lineEnd(text: string, from: number): number {
+  let at = from;
+  while (at < text.length && !endsLine(text[at])) {
+    at += 1;
+  }
+  return at;
+}
+
+/**
+ * The offset of the first token at or after `from`: whitespace, comments and a leading
+ * hashbang are trivia.
+ */
+export function tokenStart(text: string, from: number): number {
+  let at = from;
+  if (at === 0 && text.startsWith("#!")) {
+    at = lineEnd(text, 0);
+  }
+  for (;;) {
+    if (/\s/u.test(text[at] ?? "")) {
+      at += 1;
+    } else if (text.startsWith("//", at)) {
+      at = lineEnd(text, at);
+    } else if (text.startsWith("/*", at)) {
+      const close = text.indexOf("*/", at + 2);
+      at = close < 0 ? text.length : close + 2;
+    } else {
+      return at;
+    }
+  }
+}
+
+/** The line, counted from one, of the first token at or after one offset of one file. */
+export function startLine(file: SourceFile, offset: number): number {
+  return file.getLineAndCharacterOfPosition(tokenStart(file.text, offset)).line + 1;
+}
+
 /**
  * The position of one offset of one file, rendered against the target root.
  *

package/src/ref.ts

@@ -1,13 +1,9 @@
 /**
- * The stable symbol reference: the identifier that names one declaration across
- * runs, across reports, in an ignore entry, in a configured root and in a
- * cross-language edge. It is built from names and containers only, so an edit above
- * a declaration leaves it unchanged, and it is compared as bytes, so there is one
- * canonical spelling per declaration and this module is where that spelling is
- * written.
- *
- * The position key of {@link ./position.ts} is the other identifier and has the
- * other job: it locates a finding inside one run, and the two never mix.
+ * The stable symbol reference: the identifier that names one declaration across runs,
+ * reports, ignore entries, configured roots and cross-language edges. It is built from
+ * names and containers only, so an edit above a declaration leaves it unchanged, and it
+ * is compared as bytes, so this module writes the one canonical spelling. The position
+ * key of {@link ./position.ts} locates a finding inside one run; the two never mix.
  */
 
 /** The language prefix, which namespaces every reference this analyzer emits. */
@@ -34,16 +30,10 @@ const SCOPE = `${PREFIX}${TS_PACKAGE}/${TS_FILE}`;
 const MANIFEST_SCOPE = `${PREFIX}${TS_PACKAGE}/${TS_DIRS}package\\.json`;
 
 /**
- * One expression per form the grammar defines, each anchored and each the whole of
- * a reference. Several forms share one expression because they differ in what the
- * symbol is rather than in how the reference is spelled, so the list is the set of
- * spellings and not the set of subjects. A reference is valid when it matches one.
- *
- * They are written here rather than read from the Contract at run time: the Contract
- * is data a reader outside this program consults, and a product that read it while
- * running would need it installed beside itself. A test compares this list against
- * the release this analyzer is written against, so a grammar that grows a form
- * arrives here as a failing test.
+ * One anchored expression per spelling the grammar defines; a reference is valid when it
+ * matches one. They are written here rather than read from the Contract at run time, so
+ * the product needs no Contract installed beside it; a test compares this list against
+ * the release this analyzer implements, so a grammar that grows a form fails it.
  */
 export const REF_EXPRESSIONS: readonly string[] = [
   `^${SCOPE}#$`,
@@ -170,7 +160,8 @@ export function aliasFragment(name: string, block?: string): string {
   return `${head}${nameComponent(name)}:alias`;
 }
 
-function spell(component: Component): string {
+/** The canonical spelling of one component: a name, or a computed key. */
+export function spell(component: Component): string {
   return component.computed ? computedComponent(component.text) : nameComponent(component.text);
 }