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

package/src/inventory/enumerate.ts

@@ -0,0 +1,202 @@
+import { isShorthandPropertyAssignment, ModifierFlags, type Node } from "@typescript/native/ast";
+import type { Symbol as TSSymbol } from "@typescript/native/sync";
+import type { Host } from "../host.ts";
+import {
+  Builder,
+  modifiersOf,
+  type Building,
+  type Container,
+  type DeclarationSource,
+  type Inventory,
+  type InventoryCost,
+} from "../inventory.ts";
+import { packageScope, packageTypeIsModule } from "../load/package-scope.ts";
+import { relativePath } from "../paths.ts";
+import { renderPosition } from "../position.ts";
+import { isAnswered, UNANSWERED } from "../query.ts";
+import type { Handle, ProjectView } from "../session.ts";
+import { commonJS, type Resolved } from "./commonjs.ts";
+import { SYNTAX } from "./syntax.ts";
+
+/**
+ * Every declaration one project's own files hold, in rendered position order.
+ *
+ * `targetRoot` is the absolute path every position is rendered against; a file the program
+ * holds that is not below it ends the enumeration. `host` is the filesystem the manifests
+ * that name each file's package are read through, and nothing else is read from it.
+ */
+export function inventory<Brand>(
+  project: ProjectView<Brand>,
+  host: Host,
+  targetRoot: string,
+): Inventory {
+  const files = project.ownSourceFiles();
+  const moduleOf = packageScope(host, targetRoot);
+  const sources: readonly DeclarationSource[] = [
+    SYNTAX,
+    commonJS(packageTypeIsModule(host, targetRoot), resolvedIn(project)),
+  ];
+  const into = new Builder(targetRoot);
+  for (const file of files) {
+    const path = relativePath(targetRoot, file.fileName);
+    if (path === undefined) {
+      // renderPosition states the refusal, with the root it was rendered against.
+      renderPosition(file, targetRoot, 0);
+      continue;
+    }
+    const owner = into.file(file, moduleOf(path), path);
+    for (const source of sources) {
+      source.declare(file, owner, into);
+    }
+  }
+  return into.build(readTables(project, into, new Set(files.map((file) => file.fileName))));
+}
+
+/** The declarations of this program each occurrence resolves to, asked in one batch. */
+function resolvedIn<Brand>(project: ProjectView<Brand>): Resolved {
+  return (occurrences) => {
+    const symbols = project.symbolsAt(occurrences.map((occurrence) => project.handle(occurrence)));
+    return occurrences.map((occurrence, index) => {
+      // A shorthand property's name resolves to the property it declares, not the binding.
+      const symbol = isShorthandPropertyAssignment(occurrence.parent)
+        ? project.shorthandValueAt(project.handle(occurrence.parent))
+        : symbols[index];
+      return typeof symbol === "object"
+        ? symbol.declarations.flatMap(
+            (declaration) => project.declarationAt(declaration)?.node ?? [],
+          )
+        : [];
+    });
+  };
+}
+
+/**
+ * The binder's half: which declarations each module and namespace exports, and the members
+ * each container's symbol tables hold, then the members only its tree holds. One batch
+ * resolves every scope and container, because an accessor with an array overload costs one
+ * round trip for the batch and one per node without it.
+ */
+function readTables<Brand>(
+  project: ProjectView<Brand>,
+  into: Builder,
+  ownFiles: ReadonlySet<string>,
+): InventoryCost {
+  const scopes = into.exportScopes;
+  const named = into.containers.filter((container) => container.nameNode !== undefined);
+  const batched: Node[] = [
+    ...scopes.map((scope) => scope.nameNode),
+    ...named.flatMap((container) => container.nameNode ?? []),
+  ];
+  const handles: Handle<Brand>[] = batched.map((node) => project.handle(node));
+  const resolved = project.symbolsAt(handles);
+  const symbolOf = new Map<Node, TSSymbol>();
+  batched.forEach((node, index) => {
+    const symbol = resolved[index];
+    if (typeof symbol === "object") {
+      symbolOf.set(node, symbol);
+    }
+  });
+  // A scope or a container whose symbol or table went unanswered keeps what its syntax
+  // declares, and everything under it is recorded unanswered.
+  scopes.forEach((scope, index) => {
+    if (resolved[index] === UNANSWERED) {
+      into.unanswered(scope.owner);
+    }
+  });
+  named.forEach((container, index) => {
+    if (resolved[scopes.length + index] === UNANSWERED) {
+      into.unanswered(container.owner);
+    }
+  });
+
+  let exportTables = 0;
+  for (const scope of scopes) {
+    const symbol = symbolOf.get(scope.nameNode);
+    if (symbol === undefined) {
+      continue;
+    }
+    exportTables += 1;
+    const table = project.queries.exportsOf(symbol);
+    if (!isAnswered(table)) {
+      into.unanswered(scope.owner);
+      continue;
+    }
+    for (const [, exported] of table) {
+      for (const declaration of exported.declarations) {
+        const held = project.declarationAt(declaration);
+        const record = held === undefined ? undefined : into.recordAt(held.node);
+        if (record !== undefined) {
+          record.exported = true;
+        }
+      }
+    }
+  }
+
+  let memberTables = 0;
+  const readTable = (
+    container: Container,
+    table: ReadonlyMap<string, TSSymbol>,
+    seen: Map<string, Building>,
+    areStatic: boolean,
+  ): void => {
+    for (const [, member] of table) {
+      const declarations = member.declarations.flatMap(
+        (handle) => project.declarationAt(handle) ?? [],
+      );
+      // A member with no declaration is the language's own (a class's `prototype`), and a
+      // member declared outside the target's own files belongs to another program. A
+      // merged symbol's table holds the members every one of its declarations writes, and
+      // each member is kept once, by the declaration that writes it.
+      for (const held of declarations) {
+        const node = held.node;
+        if (
+          ownFiles.has(node.getSourceFile().fileName) &&
+          writtenInside(container.declaration, node)
+        ) {
+          into.member(container, node, seen, areStatic);
+        }
+      }
+    }
+  };
+  for (const container of into.containers) {
+    const symbol = container.nameNode === undefined ? undefined : symbolOf.get(container.nameNode);
+    const seen = new Map<string, Building>();
+    const isClass = container.memberKind === "class-member";
+    const isEnum = container.memberKind === "enum-member";
+    if (symbol !== undefined) {
+      if (!isEnum) {
+        memberTables += 1;
+        const table = project.queries.membersOf(symbol);
+        if (isAnswered(table)) {
+          readTable(container, table, seen, false);
+        } else {
+          into.unanswered(container.owner);
+        }
+      }
+      if (isEnum || isClass) {
+        memberTables += 1;
+        const table = project.queries.exportsOf(symbol);
+        if (isAnswered(table)) {
+          readTable(container, table, seen, isClass);
+        } else {
+          into.unanswered(container.owner);
+        }
+      }
+    }
+    // A member whose key is computed is bound to the container's type later than the
+    // table is built, so only the container's own declaration names it.
+    for (const member of container.members) {
+      into.member(container, member, seen, (modifiersOf(member) & ModifierFlags.Static) !== 0);
+    }
+  }
+  return { batches: 1, exportTables, memberTables };
+}
+
+/** Whether `node` is written inside `declaration`, compared by file and range. */
+function writtenInside(declaration: Node, node: Node): boolean {
+  return (
+    node.getSourceFile().fileName === declaration.getSourceFile().fileName &&
+    declaration.pos <= node.pos &&
+    node.end <= declaration.end
+  );
+}

package/src/inventory/syntax.ts

@@ -0,0 +1,311 @@
+import {
+  isArrayBindingPattern,
+  isBindingElement,
+  isClassDeclaration,
+  isConstructorDeclaration,
+  isEnumDeclaration,
+  isExportAssignment,
+  isExportDeclaration,
+  isFunctionDeclaration,
+  isIdentifier,
+  isInterfaceDeclaration,
+  isIntersectionTypeNode,
+  isModuleBlock,
+  isModuleDeclaration,
+  isNamespaceExport,
+  isObjectBindingPattern,
+  isParenthesizedTypeNode,
+  isStringLiteral,
+  isTypeAliasDeclaration,
+  isTypeLiteralNode,
+  isUnionTypeNode,
+  isVariableStatement,
+  SyntaxKind,
+  type BindingElement,
+  type ClassDeclaration,
+  type Identifier,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/ast";
+import {
+  componentOf,
+  exportedAs,
+  isParameterProperty,
+  memberKey,
+  nameNodeOf,
+  type Builder,
+  type Building,
+  type Container,
+  type DeclarationSource,
+  type SymbolKind,
+} from "../inventory.ts";
+import { writtenLength } from "../position.ts";
+
+/** What one statement form declares under `owner`; `walk` reads a statement it holds. */
+type Arm = (node: Node, owner: Building, into: Builder, walk: Walk) => void;
+type Walk = (statement: Node, owner: Building) => void;
+
+/** An arm for one statement form, which reads only a node the guard admits. */
+function arm<T extends Node>(
+  guard: (node: Node) => node is T,
+  declare: (node: T, owner: Building, into: Builder, walk: Walk) => void,
+): Arm {
+  return (node, owner, into, walk) => {
+    if (guard(node)) {
+      declare(node, owner, into, walk);
+    }
+  };
+}
+
+/** The members a named declaration's container holds, where it holds any. */
+type Members<T> = (node: T) => Omit<Container, "owner" | "declaration"> | undefined;
+
+/** A declaration named by its own name, or `default` as a default export, and its members. */
+function named<T extends Node>(
+  guard: (node: Node) => node is T,
+  kind: SymbolKind,
+  members?: Members<T>,
+): Arm {
+  return arm(guard, (node, owner, into) => {
+    const name = nameNodeOf(node);
+    const { component, localName } = exportedAs(node, name);
+    if (component === undefined) {
+      return;
+    }
+    const record = into.declare(node, owner, kind, name, { component, localName });
+    const held = members?.(node);
+    if (held !== undefined) {
+      into.container({ owner: record, declaration: node, ...held });
+    }
+  });
+}
+
+/** The parameter properties every constructor of one class declares. */
+function parameterPropertiesOf(node: ClassDeclaration): readonly Node[] {
+  return node.members.flatMap((member) =>
+    isConstructorDeclaration(member) ? member.parameters.filter(isParameterProperty) : [],
+  );
+}
+
+// A type alias keeps no member table of its own: the members belong to the object types
+// its declaration writes, so the declaration is what carries them.
+const TYPE_ALIAS = named(isTypeAliasDeclaration, "type", (node) => {
+  const members = aliasMembers(node.type);
+  return members.length === 0
+    ? undefined
+    : {
+        nameNode: undefined,
+        members,
+        memberKind: "type-member",
+      };
+});
+
+/** The statement forms that declare, each with what it declares. */
+const ARMS: ReadonlyMap<SyntaxKind, Arm> = new Map([
+  [SyntaxKind.FunctionDeclaration, named(isFunctionDeclaration, "function")],
+  [
+    SyntaxKind.ClassDeclaration,
+    named(isClassDeclaration, "class", (node) => ({
+      nameNode: node.name,
+      members: [...node.members, ...parameterPropertiesOf(node)],
+      memberKind: "class-member",
+    })),
+  ],
+  [
+    SyntaxKind.InterfaceDeclaration,
+    named(isInterfaceDeclaration, "interface", (node) => ({
+      nameNode: node.name,
+      members: node.members,
+      memberKind: "interface-method",
+    })),
+  ],
+  [SyntaxKind.TypeAliasDeclaration, TYPE_ALIAS],
+  // A JavaScript file's `@typedef` is reparsed into this declaration.
+  [SyntaxKind.JSTypeAliasDeclaration, TYPE_ALIAS],
+  [
+    SyntaxKind.EnumDeclaration,
+    named(isEnumDeclaration, "enum", (node) => ({
+      nameNode: node.name,
+      members: node.members,
+      memberKind: "enum-member",
+    })),
+  ],
+  [
+    SyntaxKind.ModuleDeclaration,
+    arm(isModuleDeclaration, (node, owner, into, walk) => {
+      const component = componentOf(node.name);
+      if (component === undefined) {
+        return;
+      }
+      const record = into.declare(node, owner, "namespace", node.name, {
+        component,
+        localName: undefined,
+      });
+      into.exportScope(record, node.name);
+      if (isStringLiteral(node.name)) {
+        into.module(record, node.name.text);
+      }
+      const body = node.body;
+      if (body === undefined) {
+        return;
+      }
+      for (const statement of isModuleBlock(body) ? body.statements : [body]) {
+        walk(statement, record);
+      }
+    }),
+  ],
+  [
+    SyntaxKind.VariableStatement,
+    arm(isVariableStatement, (node, owner, into) => {
+      for (const declaration of node.declarationList.declarations) {
+        const component = componentOf(declaration.name);
+        if (component !== undefined) {
+          into.declare(declaration, owner, "variable", declaration.name, {
+            component,
+            localName: undefined,
+          });
+          continue;
+        }
+        for (const { element, name } of patternElements(declaration.name)) {
+          into.declare(element, owner, "variable", name, {
+            component: { text: name.text, computed: false },
+            localName: undefined,
+          });
+        }
+      }
+    }),
+  ],
+  [
+    SyntaxKind.ExportDeclaration,
+    arm(isExportDeclaration, (node, owner, into) => {
+      const clause = node.exportClause;
+      // A bare star re-export declares nothing: the names it carries are the named module's.
+      if (clause === undefined) {
+        return;
+      }
+      const specifiers = isNamespaceExport(clause) ? [clause] : clause.elements;
+      for (const specifier of specifiers) {
+        const component = componentOf(specifier.name);
+        if (component !== undefined) {
+          into.declare(specifier, owner, "export-alias", specifier.name, {
+            component,
+            localName: undefined,
+          });
+        }
+      }
+    }),
+  ],
+  [
+    SyntaxKind.ExportAssignment,
+    arm(isExportAssignment, (node, owner, into) => {
+      if (!node.isExportEquals) {
+        into.declare(node, owner, "export-alias", undefined, {
+          component: { text: "default", computed: false },
+          localName: undefined,
+        });
+      }
+    }),
+  ],
+]);
+
+/** The declarations a module, a namespace or a container body writes. */
+export const SYNTAX: DeclarationSource = {
+  declare(file: SourceFile, owner: Building, into: Builder): void {
+    const walk: Walk = (statement, holder) => {
+      ARMS.get(statement.kind)?.(statement, holder, into, walk);
+    };
+    // A statement a component file's module appends is not written in the file.
+    const written = writtenLength(file);
+    for (const statement of file.statements) {
+      if (statement.end <= written) {
+        walk(statement, owner);
+      }
+    }
+  },
+};
+
+/** The type one node is, through however many parentheses are written around it. */
+function unparenthesizedType(type: Node): Node {
+  let held = type;
+  while (isParenthesizedTypeNode(held)) {
+    held = held.type;
+  }
+  return held;
+}
+
+/**
+ * The direct constituents of one type. Parentheses are syntax and are not a constituent, so
+ * the constituents of `(A | B) & C` are `A`, `B` and `C`; a union or an intersection written
+ * without them stays one constituent.
+ */
+function constituentsOf(type: Node): readonly Node[] {
+  const held = unparenthesizedType(type);
+  if (!isUnionTypeNode(held) && !isIntersectionTypeNode(held)) {
+    return [held];
+  }
+  return held.types.flatMap((member) =>
+    isParenthesizedTypeNode(member) ? constituentsOf(member) : [member],
+  );
+}
+
+/**
+ * The members one type alias declares: those of each object type that is the alias or a
+ * direct constituent of it. A name two constituents both declare is left out of all of
+ * them: the alias stands for it, and neither declaration is the one a reference names.
+ */
+function aliasMembers(type: Node): readonly Node[] {
+  const literals = constituentsOf(type).filter(isTypeLiteralNode);
+  if (literals.length < 2) {
+    return literals[0]?.members ?? [];
+  }
+  const declaring = new Map<string, number>();
+  for (const literal of literals) {
+    for (const key of new Set(literal.members.map(keyOf))) {
+      if (key !== undefined) {
+        declaring.set(key, (declaring.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  return literals.flatMap((literal) =>
+    literal.members.filter((member) => {
+      const key = keyOf(member);
+      return key !== undefined && declaring.get(key) === 1;
+    }),
+  );
+}
+
+/** One type member's identity, and undefined for a member the grammar cannot name. */
+function keyOf(member: Node): string | undefined {
+  const component = componentOf(nameNodeOf(member));
+  return component === undefined ? undefined : memberKey(component, false);
+}
+
+/**
+ * The binding elements of a destructuring declaration that each declare a name of their
+ * own, at any depth, but one with a default, whose removal skips the default's evaluation,
+ * and one beside a rest element of its object pattern, whose removal changes the rest.
+ */
+function patternElements(
+  name: Node,
+): readonly { readonly element: BindingElement; readonly name: Identifier }[] {
+  if (!isObjectBindingPattern(name) && !isArrayBindingPattern(name)) {
+    return [];
+  }
+  const rest =
+    isObjectBindingPattern(name) &&
+    name.elements.some((element) => element.dotDotDotToken !== undefined);
+  return name.elements.flatMap((element) => {
+    if (
+      !isBindingElement(element) ||
+      element.initializer !== undefined ||
+      (rest && element.dotDotDotToken === undefined)
+    ) {
+      return [];
+    }
+    const bound = element.name;
+    if (bound === undefined) {
+      return [];
+    }
+    return isIdentifier(bound) ? [{ element, name: bound }] : patternElements(bound);
+  });
+}