@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.21

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}#$`,
@@ -52,6 +42,7 @@ export const REF_EXPRESSIONS: readonly string[] = [
   `^${SCOPE}#${TS_HEAD}:import$`,
   `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+$`,
   `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+:static$`,
+  `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+\\.${TS_QUOTED}:case$`,
   `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})*(?::static)?<${TS_IDENT}>$`,
   `^${SCOPE}#(?:${TS_HEAD}(?:\\.${TS_MEMBER})*(?::static)?)?\\(${TS_IDENT}\\)$`,
   `^${MANIFEST_SCOPE}#${TS_PACKAGE}:(?:dependency|dev-dependency|peer-dependency)$`,
@@ -169,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);
 }
 

package/src/references/read-rule.ts

@@ -0,0 +1,60 @@
+import type { Node, SourceFile } from "@typescript/native/ast";
+import type { Type } from "@typescript/native/sync";
+import type { AliasChains } from "../alias-chain.ts";
+import type { Inventory } from "../inventory.ts";
+import type { Position } from "../position.ts";
+import type { Resolution } from "../references.ts";
+import type { ProjectView } from "../session.ts";
+
+/** Where the walk offered a read rule one node: the file, and the declaration enclosing the node. */
+interface ReadSite {
+  readonly file: SourceFile;
+  readonly from: string;
+}
+
+/** What a read rule reads its answers through, after the walk of every file of the side. */
+export interface ReadContext<Brand> {
+  readonly project: ProjectView<Brand>;
+  readonly held: Inventory;
+  readonly chains: AliasChains;
+}
+
+/**
+ * One read a rule makes: a use of the declaration `to` by `from` at a node of a walked file,
+ * or, where a question the read needed went unanswered, a hold. A hold names what the answer
+ * could have made live (program.33): the declarations `ids`, each declaration bearing one of
+ * `names`, each member of one of `types`, or with `members` every member the inventory holds;
+ * the declaration making the read is held as well. A named read sits at a node of `file`, or
+ * at a declaration's own position in it.
+ */
+export type Read =
+  | {
+      readonly kind: "named";
+      readonly from: string;
+      readonly to: string;
+      readonly file: SourceFile;
+      readonly at: Node | Position;
+      readonly use: "read" | "write";
+      readonly via: Resolution;
+      /** A read a rule counts as production code's whoever writes it. */
+      readonly production?: true;
+    }
+  | {
+      readonly kind: "held";
+      readonly from: string;
+      readonly ids?: readonly string[];
+      readonly names?: readonly string[];
+      readonly types?: readonly Type[];
+      readonly members?: true;
+    };
+
+/** One pass of one read rule over the files of one side: it collects while the walk offers nodes, then reads. */
+interface ReadRuleRun {
+  visit(node: Node, site: ReadSite): void;
+  reads<Brand>(context: ReadContext<Brand>): readonly Read[];
+}
+
+/** One rule of the references pages that reads declarations no name node names. */
+export interface ReadRule {
+  start(): ReadRuleRun;
+}

package/src/references/read-rules.ts

@@ -0,0 +1,55 @@
+import { elementAccess } from "../element-access.ts";
+import { indexedAccess } from "../indexed-access.ts";
+import { keyofComparisons } from "../keyof-comparisons.ts";
+import { moduleDeclarations } from "../module-declarations.ts";
+import { overrides } from "../overrides.ts";
+import { isAnswered } from "../query.ts";
+import { iteration } from "../symbol-keys.ts";
+import { typeParameterReads } from "../type-parameter-reads.ts";
+import { unimplementedCallees } from "../unimplemented-callees.ts";
+import type { Read, ReadContext, ReadRule } from "./read-rule.ts";
+
+/** The member kinds a hold of every member names. */
+const MEMBER_KINDS: ReadonlySet<string> = new Set([
+  "method",
+  "class-member",
+  "interface-method",
+  "type-member",
+  "enum-member",
+]);
+
+/**
+ * Every read rule, each run over every side's walked files with the reference sources:
+ * a consumer's read of a target member is a reference as the target's own is.
+ */
+export const READ_RULES: readonly ReadRule[] = [
+  overrides,
+  indexedAccess,
+  elementAccess,
+  keyofComparisons,
+  iteration,
+  typeParameterReads,
+  unimplementedCallees,
+  moduleDeclarations,
+];
+
+/** The declarations one hold names, with the declaration whose read it is. */
+export function heldBy<Brand>(
+  read: Extract<Read, { kind: "held" }>,
+  { project, held, chains }: ReadContext<Brand>,
+): readonly string[] {
+  const ids = [...(read.from === "" ? [] : [read.from]), ...(read.ids ?? [])];
+  for (const name of read.names ?? []) {
+    ids.push(...(held.byName.get(name) ?? []));
+  }
+  for (const type of read.types ?? []) {
+    const properties = project.queries.propertiesOf(type);
+    for (const property of isAnswered(properties) ? properties : []) {
+      ids.push(...chains.declarationsOf(property));
+    }
+  }
+  if (read.members === true) {
+    ids.push(...held.symbols.filter((one) => MEMBER_KINDS.has(one.kind)).map((one) => one.id));
+  }
+  return ids;
+}

package/src/references/sink.ts

@@ -0,0 +1,314 @@
+import {
+  isBinaryExpression,
+  isParenthesizedExpression,
+  isPropertyAccessExpression,
+  SyntaxKind,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/ast";
+import { bindingsOf } from "../import-bindings.ts";
+import type { Site } from "../index/sites.ts";
+import { byPosition, renderPosition, type Position } from "../position.ts";
+import type { ConsumerSide, Reference, Resolution, Use } from "../references.ts";
+import { bytewise } from "../text/compare.ts";
+
+/** One declaration a use names: `guessed` where only its name answered, `stepped` where an alias chain led to it. */
+export interface Target {
+  readonly id: string;
+  readonly guessed?: boolean;
+  readonly stepped?: boolean;
+}
+
+/** One write's index among the records, by its file, with the value it stores. */
+interface Valued {
+  readonly index: number;
+  readonly value: Node;
+}
+
+/** One record by its file, with the node that names its target and whether `from`'s own annotation holds it. */
+interface Named {
+  readonly index: number;
+  readonly at: Node;
+  readonly annotated: boolean;
+}
+
+/**
+ * Where every reference of one pass is made: it renders the position against the side's
+ * root, takes the writing file's test class from the file classes, marks a use only a
+ * declaration's name answered `guessed` and an alias step's `alias`, tags a consumer's
+ * reference with the consumer, and orders the records.
+ */
+export class Sink {
+  readonly #root: string;
+  readonly #testFile: (file: SourceFile) => boolean;
+  readonly #consumer: ConsumerSide | undefined;
+  readonly #found: Reference[] = [];
+  readonly #declaredAt: (node: Node) => string | undefined;
+  readonly #valued = new Map<SourceFile, Valued[]>();
+  readonly #named = new Map<SourceFile, Named[]>();
+  readonly #held = new Set<string>();
+
+  constructor(
+    root: string,
+    testFile: (file: SourceFile) => boolean,
+    consumer: ConsumerSide | undefined,
+    declaredAt: (node: Node) => string | undefined,
+  ) {
+    this.#root = root;
+    this.#testFile = testFile;
+    this.#consumer = consumer;
+    this.#declaredAt = declaredAt;
+  }
+
+  /** Whether a test file wrote one walked file's uses. */
+  isTest(file: SourceFile): boolean {
+    return this.#testFile(file);
+  }
+
+  /** The position one node of a walked file renders at. */
+  position(file: SourceFile, at: Node): Position {
+    return renderPosition(file, this.#root, at.getStart());
+  }
+
+  /**
+   * Records one use of each target, made by `from` at `at` in `file`. A write that stores
+   * `value` is remembered for the import bindings only its values use. A `production` use is
+   * production code's whoever writes it.
+   */
+  add(
+    file: SourceFile,
+    at: Node | Position,
+    from: string,
+    targets: Iterable<Target | string>,
+    use: Use,
+    via: Resolution,
+    value?: Node,
+    production = false,
+  ): void {
+    const position = "column" in at ? at : this.position(file, at);
+    const test = !production && this.#testFile(file);
+    for (const one of targets) {
+      const target = typeof one === "string" ? { id: one } : one;
+      this.#found.push({
+        from,
+        to: target.id,
+        position,
+        use,
+        resolution: target.guessed === true ? "by-name" : target.stepped === true ? "alias" : via,
+        test,
+        ...(target.guessed === true ? { guessed: true as const } : {}),
+      });
+      if (this.#consumer === undefined && !("column" in at)) {
+        const named = this.#named.get(file) ?? [];
+        named.push({ index: this.#found.length - 1, at, annotated: this.#annotates(at, from) });
+        this.#named.set(file, named);
+      }
+      if (use === "write" && value !== undefined) {
+        const valued = this.#valued.get(file) ?? [];
+        valued.push({ index: this.#found.length - 1, value });
+        this.#valued.set(file, valued);
+      }
+    }
+  }
+
+  /**
+   * Whether a name sits in the annotation of `from`'s own declaration. An annotation holds
+   * no block, so the walk stops at the first declaration or block above the name.
+   */
+  #annotates(name: Node, from: string): boolean {
+    if (name.kind === SyntaxKind.SourceFile) {
+      return false;
+    }
+    let child = name;
+    let parent = name.parent;
+    while (parent.kind !== SyntaxKind.Block && parent.kind !== SyntaxKind.SourceFile) {
+      const id = this.#declaredAt(parent);
+      if (id !== undefined) {
+        return id === from && (parent as { readonly type?: Node }).type === child;
+      }
+      child = parent;
+      parent = parent.parent;
+    }
+    return false;
+  }
+
+  /** Holds declarations an unanswered question could have made live, and the one whose read asked it. */
+  hold(ids: Iterable<string>): void {
+    for (const id of ids) {
+      this.#held.add(id);
+    }
+  }
+
+  /** The records made so far, before {@link finish} orders them. */
+  get made(): readonly Reference[] {
+    return this.#found;
+  }
+
+  /** Appends records another stage derived from these, rendered already. */
+  extend(references: readonly Reference[]): void {
+    this.#found.push(...references);
+  }
+
+  /**
+   * The records in position order, then the declaration named, the referencing declaration
+   * and the use, each write marked with the import bindings only its values use, and the
+   * held declarations. `usesOf` gives each walked file's name sites.
+   */
+  finish(usesOf: ReadonlyMap<SourceFile, readonly Site[]>): {
+    readonly references: readonly Reference[];
+    readonly held: readonly string[];
+  } {
+    const found = this.#found;
+    for (const [file, writes] of this.#valued) {
+      for (const { index, names } of aloneIn(file, usesOf.get(file) ?? [], writes, found)) {
+        const reference = found[index];
+        if (reference !== undefined) {
+          found[index] = { ...reference, alone: names };
+        }
+      }
+    }
+    for (const [file, named] of this.#named) {
+      for (const { index, carriers } of carriersIn(named, this.#valued.get(file) ?? [], found)) {
+        const reference = found[index];
+        if (reference !== undefined) {
+          found[index] = { ...reference, carriers };
+        }
+      }
+    }
+    found.sort(
+      (a, b) =>
+        byPosition(a.position, b.position) ||
+        bytewise(a.to, b.to) ||
+        bytewise(a.from, b.from) ||
+        bytewise(a.use, b.use),
+    );
+    const consumer = this.#consumer;
+    return {
+      references:
+        consumer === undefined
+          ? found
+          : found.map((reference) => ({ ...reference, consumer: consumer.id })),
+      held: [...this.#held].sort(bytewise),
+    };
+  }
+}
+
+/** The value one assignment stores through the name it writes, where it is a plain assignment. */
+export function storedValue(name: Node): Node | undefined {
+  let target: Node = name;
+  if (isPropertyAccessExpression(name.parent) && name.parent.name === name) {
+    target = name.parent;
+  }
+  while (isParenthesizedExpression(target.parent)) {
+    target = target.parent;
+  }
+  const parent = target.parent;
+  return isBinaryExpression(parent) &&
+    parent.operatorToken.kind === SyntaxKind.EqualsToken &&
+    parent.left === target
+    ? parent.right
+    : undefined;
+}
+
+/**
+ * The import bindings of one file that only the values written into one declaration
+ * use, for each write into it. A binding is named by an identifier that spells its
+ * local name and is not the member a property access names.
+ */
+function aloneIn(
+  file: SourceFile,
+  uses: readonly Site[],
+  writes: readonly Valued[],
+  found: readonly Reference[],
+): readonly { index: number; names: readonly string[] }[] {
+  const bindings = new Set(bindingsOf(file).map((binding) => binding.name.text));
+  if (bindings.size === 0) {
+    return [];
+  }
+  const occurrences = new Map<string, Node[]>();
+  for (const site of uses) {
+    const text = site.node.getText();
+    const parent = site.node.parent;
+    if (!bindings.has(text) || (isPropertyAccessExpression(parent) && parent.name === site.node)) {
+      continue;
+    }
+    if (!occurrences.get(text)?.includes(site.node)) {
+      occurrences.set(text, [...(occurrences.get(text) ?? []), site.node]);
+    }
+  }
+  const inside = (node: Node, value: Node): boolean =>
+    node.pos >= value.pos && node.end <= value.end;
+  const result: { index: number; names: readonly string[] }[] = [];
+  for (const write of writes) {
+    const to = found[write.index]?.to;
+    const sameTarget = writes.filter((one) => found[one.index]?.to === to);
+    const names = [...occurrences]
+      .filter(
+        ([, nodes]) =>
+          nodes.some((node) => inside(node, write.value)) &&
+          nodes.every((node) => sameTarget.some((one) => inside(node, one.value))),
+      )
+      .map(([name]) => name)
+      .sort(bytewise);
+    if (names.length > 0) {
+      result.push({ index: write.index, names });
+    }
+  }
+  return result;
+}
+
+/**
+ * The carriers of each named record of one file: `from` where its own annotation holds the
+ * name, then the target of each write whose stored value holds it and that names another
+ * declaration, the innermost value first. Values nest or are disjoint.
+ */
+function carriersIn(
+  named: readonly Named[],
+  writes: readonly Valued[],
+  found: readonly Reference[],
+): readonly { index: number; carriers: readonly string[] }[] {
+  const byStart = [...named].sort((a, b) => a.at.pos - b.at.pos);
+  const holding = new Map<number, Valued[]>();
+  for (const write of writes) {
+    let low = 0;
+    let high = byStart.length;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if ((byStart[middle]?.at.pos ?? 0) < write.value.pos) {
+        low = middle + 1;
+      } else {
+        high = middle;
+      }
+    }
+    for (let at = low; at < byStart.length; at += 1) {
+      const one = byStart[at];
+      if (one === undefined || one.at.pos >= write.value.end) {
+        break;
+      }
+      if (one.at.end <= write.value.end) {
+        holding.set(one.index, [...(holding.get(one.index) ?? []), write]);
+      }
+    }
+  }
+  const result: { index: number; carriers: readonly string[] }[] = [];
+  for (const one of named) {
+    const reference = found[one.index];
+    if (reference === undefined) {
+      continue;
+    }
+    const carriers = one.annotated ? [reference.from] : [];
+    const values = [...(holding.get(one.index) ?? [])].sort(
+      (a, b) => a.value.end - a.value.pos - (b.value.end - b.value.pos),
+    );
+    for (const write of values) {
+      const to = found[write.index]?.to;
+      if (to !== undefined && to !== reference.to && !carriers.includes(to)) {
+        carriers.push(to);
+      }
+    }
+    if (carriers.length > 0) {
+      result.push({ index: one.index, carriers });
+    }
+  }
+  return result;
+}