fallow-type-aware 3.34.1 → 3.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow-type-aware",
-  "version": "3.34.1",
+  "version": "3.36.0",
   "description": "Optional TypeScript-Go semantic refinement sidecar for Fallow",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,14 @@
   "dependencies": {
     "typescript": "7.0.2"
   },
+  "peerDependencies": {
+    "tsrs": "0.18.0-ts7.1.0-dev.20260929"
+  },
+  "peerDependenciesMeta": {
+    "tsrs": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=20"
   },
@@ -33,6 +41,7 @@
   "devDependencies": {
     "@codspeed/tinybench-plugin": "5.7.1",
     "tinybench": "6.1.2",
+    "tsrs": "0.18.0-ts7.1.0-dev.20260929",
     "zod": "4.4.3"
   }
 }

package/src/backend-preflight.mjs

@@ -1,7 +1,8 @@
 import { createRequire } from "node:module";
 import path from "node:path";
 
-import { BACKEND_VERSION } from "./generated-protocol.mjs";
+import { selectBackend } from "./backend-selection.mjs";
+import { BACKEND_VERSION, BACKEND_FAMILY } from "./generated-protocol.mjs";
 
 const REQUIRED_MAJOR = Number.parseInt(BACKEND_VERSION, 10);
 const INSTALL_HINT =
@@ -9,7 +10,7 @@ const INSTALL_HINT =
 
 /**
  * Verify that module resolution hands the sidecar a typescript install that
- * provides the `typescript/unstable/sync` backend entry point.
+ * provides the `typescript` sync API backend entry point.
  *
  * The semantic modules import that entry point statically, so an incompatible
  * resolution (for example a typescript 6 hoisted into an ancestor
@@ -18,11 +19,23 @@ const INSTALL_HINT =
  * and names the resolved version, its location, and the fix. Exact
  * backend-version parity stays enforced in `protocol.mjs`.
  *
+ * A backend that `FALLOW_TYPE_AWARE_BACKEND` selects instead of the default
+ * must resolve at its exact pinned version.
+ *
  * @param {string | URL} resolveFrom Module URL or file path to resolve from;
  *   defaults to this module so the check mirrors the semantic imports.
+ * @param {NodeJS.ProcessEnv} env Environment that selects the backend.
  */
-export const assertTypescriptBackendResolvable = (resolveFrom = import.meta.url) => {
+export const assertTypescriptBackendResolvable = (
+  resolveFrom = import.meta.url,
+  env = process.env,
+) => {
+  const backend = selectBackend(env);
   const sidecarRequire = createRequire(resolveFrom);
+  if (backend.family !== BACKEND_FAMILY) {
+    assertPinnedBackendResolvable(sidecarRequire, backend);
+    return;
+  }
   let manifestPath;
   try {
     manifestPath = sidecarRequire.resolve("typescript/package.json");
@@ -36,7 +49,23 @@ export const assertTypescriptBackendResolvable = (resolveFrom = import.meta.url)
   }
   throw new Error(
     `resolved typescript ${version} from ${path.dirname(manifestPath)}, which lacks the ` +
-      `typescript/unstable/sync backend; fallow-type-aware needs typescript ${BACKEND_VERSION}; ` +
+      `typescript sync API backend; fallow-type-aware needs typescript ${BACKEND_VERSION}; ` +
       INSTALL_HINT,
   );
 };
+
+const assertPinnedBackendResolvable = (sidecarRequire, backend) => {
+  const install = `install ${backend.package}@${backend.version} where fallow-type-aware can resolve it`;
+  let manifestPath;
+  try {
+    manifestPath = sidecarRequire.resolve(`${backend.package}/package.json`);
+  } catch {
+    throw new Error(`the ${backend.family} backend is not installed; ${install}`);
+  }
+  const { version } = sidecarRequire(manifestPath);
+  if (version === backend.version) return;
+  throw new Error(
+    `resolved ${backend.package} ${version} from ${path.dirname(manifestPath)}; ` +
+      `the ${backend.family} backend needs exactly ${backend.version}; ${install}`,
+  );
+};

package/src/backend-selection.mjs

@@ -0,0 +1,18 @@
+import { BACKENDS, BACKEND_FAMILY } from "./generated-protocol.mjs";
+
+const BACKEND_ENV = "FALLOW_TYPE_AWARE_BACKEND";
+
+/**
+ * Resolve the backend that `FALLOW_TYPE_AWARE_BACKEND` selects. An unset or
+ * empty value selects the default backend.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ family: string, package: string, version: string }}
+ */
+export const selectBackend = (env = process.env) => {
+  const requested = env[BACKEND_ENV]?.trim() || BACKEND_FAMILY;
+  const backend = BACKENDS.find((candidate) => candidate.family === requested);
+  if (backend) return backend;
+  const known = BACKENDS.map((candidate) => candidate.family).join(", ");
+  throw new Error(`unknown ${BACKEND_ENV} value \`${requested}\`; expected one of: ${known}`);
+};

package/src/backend.mjs

@@ -0,0 +1,169 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { selectBackend } from "./backend-selection.mjs";
+
+export const BACKEND = selectBackend();
+
+const { version: resolvedVersion } = await import(BACKEND.package);
+// TypeScript 7.1 serves the API at `typescript/sync`. TypeScript 7.0 and its
+// 7.1 dev builds serve it at `typescript/unstable/sync`.
+const importApi = async (subpath) => {
+  try {
+    return await import(`${BACKEND.package}/${subpath}`);
+  } catch (error) {
+    if (error?.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") throw error;
+    return import(`${BACKEND.package}/unstable/${subpath}`);
+  }
+};
+export const sync = await importApi("sync");
+export const ast = await importApi("ast/is");
+export const { SyntaxKind } = await importApi("ast");
+const { serverFS } = await importApi("fs");
+
+if (resolvedVersion !== BACKEND.version) {
+  throw new Error(
+    `${BACKEND.package} backend version ${resolvedVersion} does not match protocol ${BACKEND.version}`,
+  );
+}
+
+/**
+ * The value a `readFile` callback returns to read the file from disk.
+ * TypeScript 7.0 reads from disk on `undefined`. TypeScript 7.1 treats
+ * `undefined` as a missing file and needs the `serverFS.useOS` sentinel.
+ */
+export const READ_FROM_DISK = serverFS?.useOS;
+
+const FS_CALLBACK_DEFAULTS = serverFS
+  ? {
+      readFile: serverFS.useOS,
+      fileExists: serverFS.useOS,
+      directoryExists: serverFS.useOS,
+      getAccessibleEntries: serverFS.useOS,
+      realpath: serverFS.useOS,
+      stat: serverFS.useOS,
+      writeFile: serverFS.useOS,
+      removeFile: serverFS.useOS,
+    }
+  : {};
+
+/**
+ * TypeScript 7.0 finds a project by its config file name. TypeScript 7.1 keys
+ * `getProject` by project id and finds a config file through
+ * `getConfiguredProject`.
+ */
+const getProject = (snapshot, name) =>
+  snapshot.getProject(name) ?? snapshot.getConfiguredProject(name);
+
+/**
+ * Give a TypeScript 7.1 API the TypeScript 7.0 `updateSnapshot(changes)`
+ * contract: each call applies `changes` to the newest snapshot and returns
+ * current programs.
+ *
+ * - 7.0 `fileChanges` become 7.1 `fileNotifications`, and `ensurePrograms`
+ *   rebuilds the programs that those notifications make dirty.
+ * - 7.1 derives a snapshot from a live base snapshot, so a snapshot that the
+ *   caller disposes stays alive while it is the newest one. The caller's
+ *   handle still acts as disposed, as it does on 7.0.
+ * - 7.1 rejects the whole update when an `openFiles` entry does not exist.
+ *   7.0 ignores that file, so the wrapper drops missing files first.
+ */
+const withLinearSnapshots = (api) => {
+  const entries = new Set();
+  let head;
+  const disposeWhenUnused = (entry) => {
+    if (entry === head || entry.open > 0) return;
+    entries.delete(entry);
+    if (!entry.snapshot.isDisposed()) entry.snapshot.dispose();
+  };
+  const handle = (entry) => {
+    entry.open += 1;
+    let released = false;
+    const dispose = () => {
+      if (released) return;
+      released = true;
+      entry.open -= 1;
+      disposeWhenUnused(entry);
+    };
+    return new Proxy(entry.snapshot, {
+      get(target, property) {
+        if (property === "dispose" || property === Symbol.dispose) return dispose;
+        if (property === "isDisposed") return () => released || target.isDisposed();
+        if (released) throw new Error("Snapshot is disposed");
+        if (property === "getProject") return getProject.bind(undefined, target);
+        const value = Reflect.get(target, property, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+  };
+  const updateSnapshot = ({ fileChanges, openFiles, ...rest } = {}) => {
+    const changes = {
+      ...rest,
+      ...(openFiles ? { openFiles: openFiles.filter((file) => existsSync(file)) } : {}),
+      ...(fileChanges ? { fileNotifications: fileChanges } : {}),
+      ensurePrograms: true,
+    };
+    const previous = head;
+    head = {
+      snapshot: previous ? previous.snapshot.update(changes) : api.createSnapshot(changes),
+      open: 0,
+    };
+    entries.add(head);
+    if (previous) disposeWhenUnused(previous);
+    return handle(head);
+  };
+  const close = () => {
+    for (const entry of entries) {
+      if (!entry.snapshot.isDisposed()) entry.snapshot.dispose();
+    }
+    entries.clear();
+    head = undefined;
+    api.close();
+  };
+  return new Proxy(api, {
+    get(target, property) {
+      if (property === "updateSnapshot") return updateSnapshot;
+      if (property === "close") return close;
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+};
+
+/**
+ * Create a backend API with the TypeScript 7.0 snapshot contract.
+ *
+ * @param {{ cwd?: string, fs?: Record<string, unknown> }} options
+ */
+export const createApi = (options = {}) => {
+  const fs = options.fs ? { ...FS_CALLBACK_DEFAULTS, ...options.fs } : undefined;
+  const api = new sync.API({ ...options, ...(fs ? { fs } : {}) });
+  return typeof api.createSnapshot === "function" ? withLinearSnapshots(api) : api;
+};
+
+const INFERRED_PROJECT_ID = "/dev/null/inferred";
+
+/**
+ * Whether a project is the inferred project. Both versions give it the id
+ * `/dev/null/inferred`. Only 7.0 also uses that id as its config file name.
+ */
+export const isInferredProject = (project) =>
+  project.id.split(path.sep).join("/") === INFERRED_PROJECT_ID;
+
+/** Config file name with the 7.0 value `/dev/null/inferred` for the inferred project. */
+export const projectConfigFileName = (project) =>
+  isInferredProject(project) ? INFERRED_PROJECT_ID : project.configFileName;
+
+/**
+ * Name node of a heritage clause type. TypeScript 7.0 wraps it in an
+ * ExpressionWithTypeArguments (`expression`). TypeScript 7.1 uses a
+ * TypeReference (`typeName`) in `implements` and interface `extends` clauses.
+ */
+export const heritageTypeName = (heritageType) => heritageType.expression ?? heritageType.typeName;
+
+/**
+ * Compiler options of a project. TypeScript 7.1 beta moves them from
+ * `compilerOptions` to `parsedCommandLine.options`.
+ */
+export const projectCompilerOptions = (project) =>
+  project.compilerOptions ?? project.parsedCommandLine?.options ?? {};

package/src/computed-member-access.mjs

@@ -0,0 +1,45 @@
+import { ast } from "./backend.mjs";
+import { patternOfKey, patternSourceType } from "./shorthand-references.mjs";
+import { matchingSymbolEntries, recordSymbolUncertainty } from "./symbol-targets.mjs";
+
+const { isComputedPropertyName, isElementAccessExpression, isStringLiteralLikeNode } = ast;
+
+const isComputedAccess = (node) =>
+  isElementAccessExpression(node) &&
+  node.argumentExpression !== undefined &&
+  !isStringLiteralLikeNode(node.argumentExpression);
+
+const isComputedKey = (node) =>
+  isComputedPropertyName(node) && !isStringLiteralLikeNode(node.expression);
+
+// `object[key]` and `const { [key]: value } = object` both read a member of
+// `object` that the checker cannot name. A null type is an unknown receiver.
+const computedReceiverType = (project, node) => {
+  if (isComputedAccess(node)) return project.checker.getTypeAtLocation(node.expression);
+  if (!isComputedKey(node)) return undefined;
+  const pattern = patternOfKey(node.expression);
+  if (!pattern) return undefined;
+  return patternSourceType(project, pattern) ?? null;
+};
+
+/**
+ * Records a `dynamic-member-access` uncertainty for the class members that a
+ * computed member access or a computed pattern key can read.
+ */
+export const recordComputedMemberAccess = (state, project, entries, node) => {
+  if (entries.size === 0 || state.projectsWithUnknownDynamicAccess.has(project)) return;
+  const receiverType = computedReceiverType(project, node);
+  if (receiverType === undefined) return;
+  const receiverProperties = receiverType ? project.checker.getPropertiesOfType(receiverType) : [];
+  if (receiverProperties.length === 0) {
+    entries.forEach((entry) => recordSymbolUncertainty(state, entry, "dynamic-member-access"));
+    state.projectsWithUnknownDynamicAccess.add(project);
+    return;
+  }
+  const matched = new Set(
+    receiverProperties
+      .filter((property) => state.candidateNames.has(property.name))
+      .flatMap((property) => [...matchingSymbolEntries(project, property, "value", state)]),
+  );
+  matched.forEach((entry) => recordSymbolUncertainty(state, entry, "dynamic-member-access"));
+};

package/src/generated-protocol.mjs

@@ -11,7 +11,15 @@ export const TYPE_AWARE_PROTOCOL = Object.freeze({
   backend: {
     family: "typescript-go",
     version: "7.0.2",
+    package: "typescript",
   },
+  experimental_backends: [
+    {
+      family: "tsrs",
+      package: "tsrs",
+      version: "0.18.0-ts7.1.0-dev.20260929",
+    },
+  ],
   sidecar: {
     package: "fallow-type-aware",
     version_source: "workspace-package",
@@ -26,4 +34,8 @@ export const QUERY_OPERATIONS = Object.freeze(TYPE_AWARE_PROTOCOL.query_operatio
 export const SESSION_ENVELOPE_TYPES = Object.freeze(TYPE_AWARE_PROTOCOL.session_envelope_types);
 export const BACKEND_FAMILY = TYPE_AWARE_PROTOCOL.backend.family;
 export const BACKEND_VERSION = TYPE_AWARE_PROTOCOL.backend.version;
+export const BACKENDS = Object.freeze([
+  TYPE_AWARE_PROTOCOL.backend,
+  ...TYPE_AWARE_PROTOCOL.experimental_backends,
+]);
 export const SIDECAR_PACKAGE = TYPE_AWARE_PROTOCOL.sidecar.package;

package/src/mutant-typecheck.mjs

@@ -10,10 +10,18 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 
-import { API, DiagnosticCategory } from "typescript/unstable/sync";
+import {
+  READ_FROM_DISK,
+  createApi as createBackendApi,
+  isInferredProject,
+  projectCompilerOptions,
+  sync,
+} from "./backend.mjs";
 
 import { canonicalFileIdentity } from "./file-identity.mjs";
 
+const { DiagnosticCategory } = sync;
+
 const JAVASCRIPT_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs"]);
 const LEADING_COMMENTS = /^(?:\s|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*/u;
 const NO_CHECK_PRAGMA = /@ts-nocheck\b/u;
@@ -21,15 +29,12 @@ const MAX_CODES = 8;
 
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 
-const isInferredProject = (project) =>
-  project.configFileName.split(path.sep).join("/").endsWith("/dev/null/inferred");
-
 const hasNoCheckPragma = (text) => NO_CHECK_PRAGMA.test(LEADING_COMMENTS.exec(text)?.[0] ?? "");
 
 const isChecked = (project, absolutePath, text) => {
   if (hasNoCheckPragma(text)) return false;
   if (!JAVASCRIPT_EXTENSIONS.has(path.extname(absolutePath).toLowerCase())) return true;
-  return project.compilerOptions?.checkJs === true;
+  return projectCompilerOptions(project).checkJs === true;
 };
 
 const errorKey = (diagnostic) => `${diagnostic.code}\u0000${diagnostic.text}`;
@@ -99,7 +104,8 @@ const createOverlayApi = (root, createApi) => {
     cwd: root,
     fs: {
       readFile: (fileName) =>
-        overlay.size === 0 ? undefined : overlay.get(canonicalFileIdentity(fileName)),
+        (overlay.size === 0 ? undefined : overlay.get(canonicalFileIdentity(fileName))) ??
+        READ_FROM_DISK,
     },
   });
   return { api, overlay };
@@ -163,10 +169,7 @@ const checkFile = (context, file) => {
 };
 
 /** Type-checks each mutant of a parsed `mutant-typecheck` request. */
-export const checkMutants = (
-  { root, files },
-  { createApi = (options) => new API(options) } = {},
-) => {
+export const checkMutants = ({ root, files }, { createApi = createBackendApi } = {}) => {
   if (files.length === 0) return [];
   const context = createOverlayApi(root, createApi);
   try {