fallow-type-aware 3.34.0 → 3.35.0

package/README.md

@@ -14,6 +14,9 @@ zero-based UTF-8 byte column, and optional owner. Results keep their semantic
 assertion separate from `complete`, `partial`, or `unavailable` status. Evidence
 and every operation-specific array are deterministic and bounded, with totals,
 omissions, reason codes, actions, and truncation reported explicitly.
+The request `evidence_limit` is at most 40. A `type-coupling` query can set its
+own `evidence_limit` of at most 10,000, because its result is one report for
+the whole project.
 
 Structural diagnostics,
 unknown identities, missing projects, unsupported syntax, dynamic behavior,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow-type-aware",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "description": "Optional TypeScript-Go semantic refinement sidecar for Fallow",
   "license": "MIT",
   "repository": {

package/src/protocol.mjs

@@ -56,7 +56,13 @@ const API_SURFACE_QUERY_KEYS = new Set([
   "include_cycles",
   "private_leak_candidates",
 ]);
-const TYPE_COUPLING_QUERY_KEYS = new Set(["id", "operation", "entry_points", "include_cycles"]);
+const TYPE_COUPLING_QUERY_KEYS = new Set([
+  "id",
+  "operation",
+  "entry_points",
+  "include_cycles",
+  "evidence_limit",
+]);
 const PRIVATE_LEAK_CANDIDATE_KEYS = new Set(["id", "path", "export_name", "type_name"]);
 const SYMBOL_KEYS = new Set([
   "path",
@@ -77,6 +83,10 @@ const MAX_QUERIES = 25_000;
 const MAX_GRAPH_QUERIES = 256;
 const MAX_PRIVATE_LEAK_CANDIDATES = 25_000;
 const MAX_EVIDENCE_PER_RESULT = 40;
+// A type-coupling result is one project-wide report, so it can carry more
+// evidence than a per-symbol result. This bound keeps the response well below
+// the native client's semantic response byte limit.
+const MAX_TYPE_COUPLING_EVIDENCE = 10_000;
 const MAX_STRING_CHARS = 4_096;
 
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -257,13 +267,31 @@ const parseFrameworkContracts = (value, field) =>
 const parseIncludeCycles = (value, field) =>
   value === undefined ? false : requireBoolean(value, field);
 
+const parseTypeCouplingEvidenceLimit = (value, field) => {
+  const limit = requireInteger(value, field, 1);
+  if (limit > MAX_TYPE_COUPLING_EVIDENCE) {
+    throw new Error(`${field} exceeds the ${MAX_TYPE_COUPLING_EVIDENCE} item limit`);
+  }
+  return limit;
+};
+
 const parseGraphQuery = (value, field, root, query) => {
   const graphQuery = {
     ...query,
     entryPoints: parseEntryPoints(value.entry_points, `${field}.entry_points`, root),
     includeCycles: parseIncludeCycles(value.include_cycles, `${field}.include_cycles`),
   };
-  if (query.operation !== "api-surface") return graphQuery;
+  if (query.operation === "type-coupling") {
+    return value.evidence_limit === undefined
+      ? graphQuery
+      : {
+          ...graphQuery,
+          evidenceLimit: parseTypeCouplingEvidenceLimit(
+            value.evidence_limit,
+            `${field}.evidence_limit`,
+          ),
+        };
+  }
   return {
     ...graphQuery,
     privateLeakCandidates: parsePrivateLeakCandidates(

package/src/reference-names.mjs

@@ -0,0 +1,75 @@
+import {
+  isExportDeclaration,
+  isImportDeclaration,
+  isImportEqualsDeclaration,
+  isModuleBlock,
+  isModuleDeclaration,
+  isNamedExports,
+  isNamespaceExportDeclaration,
+  isNamespaceImport,
+} from "typescript/unstable/ast/is";
+
+const JAVASCRIPT_FILE = /\.[cm]?jsx?$/iu;
+
+// In JavaScript, require bindings and export assignments also create aliases.
+// The scan keeps every identifier of these files.
+export const isJavaScriptFile = (sourceFile) => JAVASCRIPT_FILE.test(sourceFile.fileName);
+
+const importNames = ({ importClause }) => {
+  const bindings = importClause?.namedBindings;
+  if (!bindings) return [importClause?.name];
+  if (isNamespaceImport(bindings)) return [importClause.name, bindings.name];
+  return [importClause.name, ...bindings.elements.map((element) => element.name)];
+};
+
+const exportNames = ({ exportClause }) => {
+  if (!exportClause) return [];
+  if (isNamedExports(exportClause)) return exportClause.elements.map((element) => element.name);
+  return [exportClause.name];
+};
+
+const moduleBodyNames = (body) => {
+  if (body && isModuleDeclaration(body)) return moduleBodyNames(body.body);
+  return body && isModuleBlock(body) ? body.statements.flatMap(statementAliasNames) : [];
+};
+
+const statementAliasNames = (statement) => {
+  if (isImportDeclaration(statement)) return importNames(statement);
+  if (isImportEqualsDeclaration(statement) || isNamespaceExportDeclaration(statement)) {
+    return [statement.name];
+  }
+  if (isExportDeclaration(statement)) return exportNames(statement);
+  if (isModuleDeclaration(statement)) return moduleBodyNames(statement.body);
+  return [];
+};
+
+// Default-library and external-library files sit below node_modules. The
+// path check skips them before the source file and its metadata, which each
+// cost a checker round trip.
+const NODE_MODULES_SEGMENT = /[\\/]node_modules[\\/]/u;
+
+const isOwnSourceFile = (project, sourceFile) =>
+  Boolean(sourceFile) &&
+  !project.program.isSourceFileDefaultLibrary(sourceFile) &&
+  !project.program.isSourceFileFromExternalLibrary(sourceFile);
+
+const programAliasNames = (project) =>
+  project.program
+    .getSourceFileNames()
+    .filter((fileName) => !NODE_MODULES_SEGMENT.test(fileName))
+    .map((fileName) => project.program.getSourceFile(fileName))
+    .filter((sourceFile) => isOwnSourceFile(project, sourceFile))
+    .flatMap((sourceFile) => sourceFile.statements.flatMap(statementAliasNames))
+    .map((name) => name?.text)
+    .filter((text) => typeof text === "string");
+
+/**
+ * Returns the identifier names that can reach a symbol-use target.
+ *
+ * An identifier resolves to a declaration with its own name, or to an alias
+ * that an import or export declares under that name. So the scan needs only
+ * the target names and the names that the alias declarations of the project
+ * files declare, project declaration files included.
+ */
+export const referenceNames = (projects, targetNames) =>
+  new Set([...targetNames, "default", ...projects.flatMap(programAliasNames)]);

package/src/semantic.mjs

@@ -15,7 +15,6 @@ import {
   isGetAccessorDeclaration,
   isIdentifier,
   isImportDeclaration,
-  isImportClause,
   isImportSpecifier,
   isImportTypeNode,
   isNamespaceImport,
@@ -51,6 +50,8 @@ import {
   symbolForDeclaration,
 } from "./semantic-identity.mjs";
 import { analyzeSymbolImpact } from "./symbol-impact.mjs";
+import { isJavaScriptFile, referenceNames } from "./reference-names.mjs";
+import { matchingAliasEntries, matchingSymbolEntries, targetName } from "./symbol-targets.mjs";
 import { analyzeTypeCoupling } from "./type-coupling.mjs";
 
 const ATTACHED_COMMENT_PATTERN = /\/\/|\/\*/u;
@@ -352,15 +353,10 @@ const semanticUse = (root, node, namespace) => {
   };
 };
 
-const isDefaultImportReference = (node) => isImportClause(node.parent) && node.parent.name === node;
-
 const candidateNameMatches = (candidateNames, name) => !candidateNames || candidateNames.has(name);
 
-const isIdentifierReference = (node, candidateNames, includeDefaultImports) => {
-  if (!isIdentifier(node)) return false;
-  if (candidateNameMatches(candidateNames, node.text)) return true;
-  return includeDefaultImports && isDefaultImportReference(node);
-};
+const isIdentifierReference = (node, names) =>
+  isIdentifier(node) && candidateNameMatches(names, node.text);
 
 const isElementNameNode = (node) =>
   isStringLiteralLikeNode(node) &&
@@ -396,8 +392,11 @@ const symbolUseBatchState = (resolvedQueries, evidenceLimit) => {
     uncertaintiesByQuery: new Map(resolvedQueries.map(({ query }) => [query.id, new Set()])),
     declarationLocationsByQuery: new Map(resolvedQueries.map(({ query }) => [query.id, new Set()])),
     targetsByKey: new Map(),
+    targetNames: new Set(),
+    aliasEntriesByProject: new Map(),
     exportEntriesByModule: new Map(),
     exportEntriesByProject: new Map(),
+    exportedNames: new Set(),
     candidateNames: new Set(),
     classMemberEntries,
     classMemberEntriesByName: entriesByName(classMemberEntries),
@@ -412,6 +411,7 @@ const addSymbolTarget = (root, state, entry, declaration, namespace) => {
   state.declarationLocationsByQuery
     .get(entry.query.id)
     .add(locationKey(location(root, declaration.name ?? declaration)));
+  state.targetNames.add(targetName(declaration));
   const key = stableDeclarationKey(declaration, namespace);
   const targets = state.targetsByKey.get(key) ?? [];
   targets.push(entry);
@@ -422,6 +422,7 @@ const registerSymbolTargets = (root, state, entry) => {
   state.candidateNames.add(entry.query.symbol.localName);
   state.candidateNames.add(entry.query.symbol.exportedName);
   if (entry.query.symbol.declarationKind === "export") {
+    state.exportedNames.add(entry.query.symbol.exportedName);
     const moduleIdentity = canonicalFileIdentity(entry.query.symbol.absolutePath);
     const entries = state.exportEntriesByModule.get(moduleIdentity) ?? new Set();
     entries.add(entry);
@@ -447,45 +448,6 @@ const registerSymbolTargets = (root, state, entry) => {
   state.contractRelationsByQuery.set(entry.query.id, entry.resolved.contractRelations);
 };
 
-const matchingSymbolEntries = (project, symbol, namespace, targetsByKey) => {
-  const declarations = declarationsForSymbol(project, symbol);
-  const matchingLane = declarations.filter((declaration) =>
-    declarationNamespaces(declaration).has(namespace),
-  );
-  if (matchingLane.length > 0) {
-    return new Set(
-      matchingLane.flatMap(
-        (declaration) => targetsByKey.get(stableDeclarationKey(declaration, namespace)) ?? [],
-      ),
-    );
-  }
-  return new Set(
-    declarations.flatMap((declaration) =>
-      [...declarationNamespaces(declaration)].flatMap(
-        (declaredNamespace) =>
-          targetsByKey.get(stableDeclarationKey(declaration, declaredNamespace)) ?? [],
-      ),
-    ),
-  );
-};
-
-const matchingAliasEntries = (project, symbol, namespace, targetsByKey) => {
-  const entries = new Set();
-  const seen = new Set();
-  let current = symbol;
-  while (current && !seen.has(current)) {
-    seen.add(current);
-    matchingSymbolEntries(project, current, namespace, targetsByKey).forEach((entry) =>
-      entries.add(entry),
-    );
-    if ((current.flags & SymbolFlags.Alias) === 0) break;
-    const aliased = project.checker.getAliasedSymbol(current);
-    if (project.checker.isUnknownSymbol(aliased) || aliased === current) break;
-    current = aliased;
-  }
-  return entries;
-};
-
 const isDeclarationReference = (root, state, entry, node) => {
   const locations = state.declarationLocationsByQuery.get(entry.query.id);
   if (locations.has(locationKey(location(root, node)))) return true;
@@ -683,9 +645,7 @@ const recordComputedMemberAccess = (state, project, entries, node) => {
   const matched = new Set(
     receiverProperties
       .filter((property) => state.candidateNames.has(property.name))
-      .flatMap((property) => [
-        ...matchingSymbolEntries(project, property, "value", state.targetsByKey),
-      ]),
+      .flatMap((property) => [...matchingSymbolEntries(project, property, "value", state)]),
   );
   matched.forEach((entry) => recordSymbolUncertainty(state, entry, "dynamic-member-access"));
 };
@@ -706,22 +666,24 @@ const recordDynamicImportUncertainty = (state, project, node) => {
   );
 };
 
-const referenceNamespaces = (project, node, symbol) => {
+const referenceNamespaces = (project, node, rawSymbol) => {
   const alias = aliasNode(node);
   if (!alias || !isExportSpecifier(alias)) {
     return [isTypePosition(node) ? "type" : "value"];
   }
   if (alias.isTypeOnly || alias.parent?.parent?.isTypeOnly) return ["type"];
   const namespaces = new Set(
-    declarationsForSymbol(project, symbol).flatMap((declaration) => [
-      ...declarationNamespaces(declaration),
-    ]),
+    declarationsForSymbol(project, resolveAlias(project.checker, rawSymbol)).flatMap(
+      (declaration) => [...declarationNamespaces(declaration)],
+    ),
   );
   return namespaces.size > 0 ? [...namespaces] : [isTypePosition(node) ? "type" : "value"];
 };
 
 const surfaceEntriesForNode = (state, project, node, namespace) => {
-  if (moduleEdgeDeclaration(node)) return new Set();
+  // Resolving the referenced module costs checker round trips, so skip every
+  // identifier that cannot name an export query.
+  if (!state.exportedNames.has(node.text) || moduleEdgeDeclaration(node)) return new Set();
   const moduleIdentity = referencedModuleIdentity(project, node);
   if (!moduleIdentity) return new Set();
   const direct = [...(state.exportEntriesByModule.get(moduleIdentity) ?? [])].filter(
@@ -732,7 +694,7 @@ const surfaceEntriesForNode = (state, project, node, namespace) => {
   for (const entry of direct) {
     for (const { declaration } of entry.resolved.ownerContexts) {
       const symbol = resolveAlias(project.checker, symbolForDeclaration(project, declaration));
-      matchingSymbolEntries(project, symbol, namespace, state.targetsByKey).forEach((related) =>
+      matchingSymbolEntries(project, symbol, namespace, state).forEach((related) =>
         entries.add(related),
       );
     }
@@ -740,7 +702,7 @@ const surfaceEntriesForNode = (state, project, node, namespace) => {
   return entries;
 };
 
-const scanSymbolUseFile = (root, state, project, sourceFile, includeDefaultImports) => {
+const scanSymbolUseFile = (root, state, project, sourceFile, names) => {
   const projectEntries = classMemberEntrySetForProject(state, project);
   const nodes = [];
   visit(sourceFile, (node) => {
@@ -749,7 +711,7 @@ const scanSymbolUseFile = (root, state, project, sourceFile, includeDefaultImpor
       recordStringDispatchedMemberAccess(state, projectEntries, node);
       recordComputedMemberAccess(state, project, projectEntries, node);
     }
-    if (isIdentifierReference(node, undefined, includeDefaultImports)) {
+    if (isIdentifierReference(node, isJavaScriptFile(sourceFile) ? undefined : names)) {
       nodes.push(node);
       return;
     }
@@ -758,10 +720,9 @@ const scanSymbolUseFile = (root, state, project, sourceFile, includeDefaultImpor
   const symbols = project.checker.getSymbolAtLocation(nodes);
   nodes.forEach((node, index) => {
     const rawSymbol = symbols[index];
-    const symbol = resolveAlias(project.checker, rawSymbol);
-    referenceNamespaces(project, node, symbol).forEach((namespace) => {
+    referenceNamespaces(project, node, rawSymbol).forEach((namespace) => {
       const entries = new Set([
-        ...matchingAliasEntries(project, rawSymbol, namespace, state.targetsByKey),
+        ...matchingAliasEntries(project, rawSymbol, namespace, state),
         ...surfaceEntriesForNode(state, project, node, namespace),
       ]);
       entries.forEach((entry) => recordSymbolUse(root, state, project, entry, node, namespace));
@@ -769,7 +730,7 @@ const scanSymbolUseFile = (root, state, project, sourceFile, includeDefaultImpor
   });
 };
 
-const scanSymbolUseProjects = (root, state, projects, includeDefaultImports) => {
+const scanSymbolUseProjects = (root, state, projects, names) => {
   const scannedFiles = new Set();
   let sourceScanCount = 0;
   for (const project of projects) {
@@ -778,7 +739,7 @@ const scanSymbolUseProjects = (root, state, projects, includeDefaultImports) =>
       if (scannedFiles.has(fileIdentity)) continue;
       scannedFiles.add(fileIdentity);
       sourceScanCount += 1;
-      scanSymbolUseFile(root, state, project, sourceFile, includeDefaultImports);
+      scanSymbolUseFile(root, state, project, sourceFile, names);
     }
   }
   return sourceScanCount;
@@ -787,10 +748,8 @@ const scanSymbolUseProjects = (root, state, projects, includeDefaultImports) =>
 const batchSymbolUseEvidence = (root, resolvedQueries, scanProjects, evidenceLimit) => {
   const state = symbolUseBatchState(resolvedQueries, evidenceLimit);
   resolvedQueries.forEach((entry) => registerSymbolTargets(root, state, entry));
-  const includeDefaultImports = resolvedQueries.some(
-    ({ query }) => query.symbol.exportedName === "default",
-  );
-  const sourceScanCount = scanSymbolUseProjects(root, state, scanProjects, includeDefaultImports);
+  const names = referenceNames(scanProjects, [...state.candidateNames, ...state.targetNames]);
+  const sourceScanCount = scanSymbolUseProjects(root, state, scanProjects, names);
   return {
     evidenceByQuery: state.evidenceByQuery,
     totalByQuery: state.totalByQuery,
@@ -1891,7 +1850,7 @@ const analyzeGraphSemanticQuery = (root, query, graphStates, evidenceLimit) => {
     return analyzeApiSurface(root, query, graphStates, evidenceLimit);
   }
   return analyzeTypeCoupling(
-    { root, query, states: graphStates, evidenceLimit },
+    { root, query, states: graphStates, evidenceLimit: query.evidenceLimit ?? evidenceLimit },
     {
       boundedResult,
       discoverEntryPoints,

package/src/symbol-targets.mjs

@@ -0,0 +1,68 @@
+import { SymbolFlags } from "typescript/unstable/sync";
+
+import {
+  declarationName,
+  declarationNamespaces,
+  declarationsForSymbol,
+  stableDeclarationKey,
+} from "./semantic-identity.mjs";
+
+export const targetName = (declaration) => declarationName(declaration) ?? "default";
+
+// A target key contains the declaration name. The name check skips the key
+// and its file identity for every declaration that cannot match.
+const targetsForDeclaration = (state, declaration, namespace) =>
+  state.targetNames.has(targetName(declaration))
+    ? (state.targetsByKey.get(stableDeclarationKey(declaration, namespace)) ?? [])
+    : [];
+
+export const matchingSymbolEntries = (project, symbol, namespace, state) => {
+  const declarations = declarationsForSymbol(project, symbol);
+  const matchingLane = declarations.filter((declaration) =>
+    declarationNamespaces(declaration).has(namespace),
+  );
+  if (matchingLane.length > 0) {
+    return new Set(
+      matchingLane.flatMap((declaration) => targetsForDeclaration(state, declaration, namespace)),
+    );
+  }
+  return new Set(
+    declarations.flatMap((declaration) =>
+      [...declarationNamespaces(declaration)].flatMap((declaredNamespace) =>
+        targetsForDeclaration(state, declaration, declaredNamespace),
+      ),
+    ),
+  );
+};
+
+const resolveAliasEntries = (project, symbol, namespace, state) => {
+  const entries = new Set();
+  const seen = new Set();
+  let current = symbol;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    matchingSymbolEntries(project, current, namespace, state).forEach((entry) =>
+      entries.add(entry),
+    );
+    if ((current.flags & SymbolFlags.Alias) === 0) break;
+    const aliased = project.checker.getAliasedSymbol(current);
+    if (project.checker.isUnknownSymbol(aliased) || aliased === current) break;
+    current = aliased;
+  }
+  return entries;
+};
+
+// The scan visits every identifier, so one symbol occurs many times. Each
+// checker call is a round trip, and the targets do not change during a batch,
+// so the batch keeps one answer for each symbol and namespace.
+export const matchingAliasEntries = (project, symbol, namespace, state) => {
+  if (!symbol) return new Set();
+  const bySymbol = state.aliasEntriesByProject.get(project) ?? new Map();
+  state.aliasEntriesByProject.set(project, bySymbol);
+  const byNamespace = bySymbol.get(symbol) ?? new Map();
+  bySymbol.set(symbol, byNamespace);
+  if (!byNamespace.has(namespace)) {
+    byNamespace.set(namespace, resolveAliasEntries(project, symbol, namespace, state));
+  }
+  return byNamespace.get(namespace);
+};