@suss/adapter-typescript 0.31.1 → 0.32.0

package/dist/index.cjs

@@ -1498,13 +1498,14 @@ function isWriteTarget(name) {
 function fact(db, relation, ...tuple) {
   db.add(relation, tuple);
 }
-function createNodeTable() {
+function createNodeTable(environmentObjects = []) {
   return {
     byId: /* @__PURE__ */ new Map(),
     seenFunctions: /* @__PURE__ */ new Set(),
     seenBindings: /* @__PURE__ */ new Set(),
     seenValues: /* @__PURE__ */ new Set(),
-    seenClasses: /* @__PURE__ */ new Set()
+    seenClasses: /* @__PURE__ */ new Set(),
+    environmentObjects
   };
 }
 function nodeId(node) {
@@ -1649,6 +1650,40 @@ function literalIndexOf(index) {
   }
   return null;
 }
+function readsEnvironment(table, access) {
+  if (table.environmentObjects.length === 0) {
+    return false;
+  }
+  const path14 = dottedPathOf(access.getExpression());
+  return path14 !== null && table.environmentObjects.includes(path14);
+}
+function isEnvironmentNameRead(table, node) {
+  if (!import_ts_morph6.Node.isElementAccessExpression(node)) {
+    return false;
+  }
+  const argument = node.getArgumentExpression();
+  return argument !== void 0 && literalIndexOf(argument) === null && readsEnvironment(table, node);
+}
+function environmentNameReadsIn(table, sourceFile) {
+  if (table.environmentObjects.length === 0) {
+    return [];
+  }
+  const text = sourceFile.getFullText();
+  if (!table.environmentObjects.some((path14) => text.includes(path14))) {
+    return [];
+  }
+  return sourceFile.getDescendantsOfKind(import_ts_morph6.SyntaxKind.ElementAccessExpression).filter((access) => isEnvironmentNameRead(table, access));
+}
+function dottedPathOf(expression) {
+  if (import_ts_morph6.Node.isIdentifier(expression)) {
+    return expression.getText();
+  }
+  if (!import_ts_morph6.Node.isPropertyAccessExpression(expression)) {
+    return null;
+  }
+  const object = dottedPathOf(expression.getExpression());
+  return object === null ? null : `${object}.${expression.getName()}`;
+}
 function asFallbackExpression(expression) {
   if (!import_ts_morph6.Node.isBinaryExpression(expression)) {
     return null;
@@ -1720,6 +1755,10 @@ function emitValue(db, table, value) {
       );
       return id;
     }
+    const argument = expression.getArgumentExpression();
+    if (argument !== void 0 && readsEnvironment(table, expression)) {
+      fact(db, "readsEnvNamed", id, emitValue(db, table, argument));
+    }
     fact(db, "writtenValue", id);
     return id;
   }
@@ -2184,6 +2223,9 @@ function recordBodyCalls(db, table, fnId, node) {
   if (!import_ts_morph6.Node.isExpression(node)) {
     return false;
   }
+  if (isEnvironmentNameRead(table, node)) {
+    emitValue(db, table, node);
+  }
   const call = unwrapExpression(node);
   if (import_ts_morph6.Node.isCallExpression(call)) {
     const callee = unwrapExpression(call.getExpression());
@@ -2409,9 +2451,10 @@ var QUERY_FACTS = (0, import_resolution2.queryFacts)(RESOLUTION_PROGRAM);
 var MODULE_DEMANDS = RESOLUTION_PROGRAM.demands.filter(
   (one) => (one.relation === "moduleExport" || one.relation === "moduleForwards") && one.bound[0] === true
 ).map((one) => one.demand);
+var NO_NAMERS = { sitesNaming: () => [] };
 var ResolutionStore = class {
   db = new import_datalog2.Database();
-  table = createNodeTable();
+  table;
   fullyExtracted = /* @__PURE__ */ new Set();
   seededValues = /* @__PURE__ */ new Set();
   importedNames = /* @__PURE__ */ new Map();
@@ -2429,13 +2472,18 @@ var ResolutionStore = class {
   constructionSites = /* @__PURE__ */ new Map();
   /** Files the most recent query read, for the memo to keep. */
   lastQueryWalked = [];
+  /** See `environmentSiteFiles`; null until the first env question. */
+  envSiteFiles = null;
+  envNamersAnswer = NO_NAMERS;
+  envNamersExtractedAt = -1;
   declarations = /* @__PURE__ */ new Map();
   graph = new ModuleGraph();
   /** See `notePossibleCallers`. */
   possibleCallers = /* @__PURE__ */ new Set();
   callerFilesRead = /* @__PURE__ */ new Set();
   stale = true;
-  constructor(wrappers = []) {
+  constructor(wrappers = [], environmentObjects = []) {
+    this.table = createNodeTable(environmentObjects);
     (0, import_resolution2.addPackWords)(this.db, { unwrapsByName: wrappers });
   }
   /**
@@ -2648,6 +2696,89 @@ var ResolutionStore = class {
     }
     return found;
   }
+  /**
+   * Which parameters an environment read takes its variable's name
+   * from, for a reader standing at a call. One question covers the
+   * whole project: a project has a handful of environment reads and
+   * thousands of parameters, and with the read bound the rules run from
+   * each callee to its callers.
+   *
+   * `definedIn` is the callee's own file, read into the store before
+   * the question so a helper nothing had extracted yet is among the
+   * facts the rules run over.
+   */
+  envNamers(definedIn) {
+    const siteFiles = this.environmentSiteFiles(definedIn.getProject());
+    if (siteFiles.length === 0) {
+      return NO_NAMERS;
+    }
+    this.extractFile(definedIn);
+    if (this.envNamersExtractedAt === this.fullyExtracted.size) {
+      return this.envNamersAnswer;
+    }
+    const answered = this.askEnvNamers([...siteFiles, definedIn]);
+    const siteFilePaths = new Set(siteFiles.map((one) => one.getFilePath()));
+    this.envNamersAnswer = {
+      sitesNaming: (parameter) => this.sitesNamedBy(answered, siteFilePaths, parameter)
+    };
+    this.envNamersExtractedAt = this.fullyExtracted.size;
+    return this.envNamersAnswer;
+  }
+  sitesNamedBy(answered, siteFilePaths, parameter) {
+    const key = nodeId(parameter);
+    const sites = answered.get(key);
+    if (sites !== void 0) {
+      return sites;
+    }
+    if (!siteFilePaths.has(parameter.getSourceFile().getFilePath())) {
+      return [];
+    }
+    return this.db.lookup("paramOf", 2, key).length > 0 ? [] : null;
+  }
+  /**
+   * Seed every read the store knows of, derive, and take the sites back
+   * per parameter. The question is dropped afterwards, so a later ask
+   * over a larger fact set derives it again.
+   */
+  askEnvNamers(seeds) {
+    const byParameter = /* @__PURE__ */ new Map();
+    try {
+      for (const [site] of this.db.facts("readsEnvNamed")) {
+        this.wantKey("wantedEnvSite", String(site));
+      }
+      this.extractDemanded(seeds);
+      this.derive();
+      for (const [parameter, site] of this.db.facts("wantedParamNamesEnv")) {
+        const node = this.table.byId.get(String(site));
+        if (node === void 0) {
+          continue;
+        }
+        const sites = byParameter.get(String(parameter)) ?? [];
+        sites.push(node);
+        byParameter.set(String(parameter), sites);
+      }
+    } finally {
+      this.forgetQuery();
+    }
+    return byParameter;
+  }
+  /**
+   * The project's files that spell an environment read with a computed
+   * index, read into the store. Which files those are cannot depend on
+   * what a reader happened to ask about first, so the scan is over the
+   * project's own sources and it happens once.
+   */
+  environmentSiteFiles(project) {
+    if (this.envSiteFiles !== null) {
+      return this.envSiteFiles;
+    }
+    const found = project.getSourceFiles().filter(
+      (one) => !one.isInNodeModules() && environmentNameReadsIn(this.table, one).length > 0
+    );
+    this.envSiteFiles = found;
+    this.extractFiles(found);
+    return found;
+  }
   /**
    * Whether running this function hands back that call: returned
    * outright, written into a name and returned, or a shorthand body.
@@ -3058,7 +3189,11 @@ var ResolutionStore = class {
     this.stale = false;
   }
   wantValue(question, value) {
-    if (this.db.add(question, [nodeId(value)]) === "added") {
+    this.wantKey(question, nodeId(value));
+  }
+  /** For a question seeded with a fact key the store read out of the database. */
+  wantKey(question, key) {
+    if (this.db.add(question, [key]) === "added") {
       this.stale = true;
     }
   }
@@ -17623,11 +17758,14 @@ function createTypeScriptAdapter(suppliedConfig) {
   const packWrappers = config.frameworks.flatMap(
     (pack) => pack.transparentWrappers ?? []
   );
+  const packEnvironments = config.frameworks.flatMap(
+    (pack) => pack.environmentObjects ?? []
+  );
   return {
     tsProject: project,
     async extractFromFiles(filePaths) {
       const summaries = [];
-      const resolution = new ResolutionStore(packWrappers);
+      const resolution = new ResolutionStore(packWrappers, packEnvironments);
       const claimedUnits = /* @__PURE__ */ new Map();
       for (const fp of filePaths) {
         let sourceFile = project.getSourceFile(fp);
@@ -17730,7 +17868,7 @@ function createTypeScriptAdapter(suppliedConfig) {
         timer
       );
       timer.time("warmExportChains", () => warmExportChains(deep.deepRoots));
-      const resolution = new ResolutionStore(packWrappers);
+      const resolution = new ResolutionStore(packWrappers, packEnvironments);
       const packsByFile = timer.time(
         "preFilter",
         () => computePackApplicability(sourceFiles, config.frameworks, resolution)

package/dist/index.d.cts

@@ -46,6 +46,18 @@ interface PassedArgument {
     call: Node;
     argument: Node;
 }
+/** See `ResolutionStore.envNamers`. */
+interface EnvironmentNamers {
+    /**
+     * The environment reads that take their variable's name from this
+     * parameter, however many helpers forward it along the way. Empty for
+     * a parameter no read ever takes a name from, and null where the
+     * rules had nothing to go on: a file that exports nothing states no
+     * facts, so their silence about its parameters means neither yes nor
+     * no, and the asker settles what it can by reading the syntax.
+     */
+    sitesNaming(parameter: Node): readonly Node[] | null;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
@@ -66,13 +78,17 @@ declare class ResolutionStore {
     private readonly constructionSites;
     /** Files the most recent query read, for the memo to keep. */
     private lastQueryWalked;
+    /** See `environmentSiteFiles`; null until the first env question. */
+    private envSiteFiles;
+    private envNamersAnswer;
+    private envNamersExtractedAt;
     private readonly declarations;
     private readonly graph;
     /** See `notePossibleCallers`. */
     private readonly possibleCallers;
     private readonly callerFilesRead;
     private stale;
-    constructor(wrappers?: TransparentWrapper[]);
+    constructor(wrappers?: TransparentWrapper[], environmentObjects?: readonly string[]);
     /**
      * `alsoFrom` is a second file to walk out from, for a caller that
      * knows where the value it is asking about was set up. The walk
@@ -144,6 +160,32 @@ declare class ResolutionStore {
      * parameter's own function with no join against `bodyCalls` needed.
      */
     callsPassing(parameter: Node): PassedArgument[];
+    /**
+     * Which parameters an environment read takes its variable's name
+     * from, for a reader standing at a call. One question covers the
+     * whole project: a project has a handful of environment reads and
+     * thousands of parameters, and with the read bound the rules run from
+     * each callee to its callers.
+     *
+     * `definedIn` is the callee's own file, read into the store before
+     * the question so a helper nothing had extracted yet is among the
+     * facts the rules run over.
+     */
+    envNamers(definedIn: SourceFile): EnvironmentNamers;
+    private sitesNamedBy;
+    /**
+     * Seed every read the store knows of, derive, and take the sites back
+     * per parameter. The question is dropped afterwards, so a later ask
+     * over a larger fact set derives it again.
+     */
+    private askEnvNamers;
+    /**
+     * The project's files that spell an environment read with a computed
+     * index, read into the store. Which files those are cannot depend on
+     * what a reader happened to ask about first, so the scan is over the
+     * project's own sources and it happens once.
+     */
+    private environmentSiteFiles;
     /**
      * Whether running this function hands back that call: returned
      * outright, written into a name and returned, or a shorthand body.
@@ -247,6 +289,8 @@ declare class ResolutionStore {
      */
     private forgetQuery;
     private wantValue;
+    /** For a question seeded with a fact key the store read out of the database. */
+    private wantKey;
     private wantExportsOf;
     /**
      * Discovery walks the table in order, and the rounds derive it in
@@ -1579,4 +1623,4 @@ declare function climbSyntax(node: Node): Node;
  */
 declare function peelValue(node: Node): Node;
 
-export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, TSCONFIG_NAMES, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, arrayLiteralOf, buildProjectHelperIndex, callOpsFor, climbSyntax, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, couldNameAValue, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findEnclosingFunction, findNearestTsconfig, findTerminals, functionTargetOf, functionValueOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isDefaultedAt, isImportedFrom, methodDeclaredIn, namedImportsOf, objectLiteralOf, parseConditionExpression, peelSyntax, peelValue, propertiesOf, propertyFunctionOf, propertyNameOf, propertyOf, propertyValueOf, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, workspaceRootFor, writtenNodeOf };
+export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type EnvironmentNamers, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, TSCONFIG_NAMES, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, arrayLiteralOf, buildProjectHelperIndex, callOpsFor, climbSyntax, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, couldNameAValue, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findEnclosingFunction, findNearestTsconfig, findTerminals, functionTargetOf, functionValueOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isDefaultedAt, isImportedFrom, methodDeclaredIn, namedImportsOf, objectLiteralOf, parseConditionExpression, peelSyntax, peelValue, propertiesOf, propertyFunctionOf, propertyNameOf, propertyOf, propertyValueOf, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, workspaceRootFor, writtenNodeOf };

package/dist/index.d.ts

@@ -46,6 +46,18 @@ interface PassedArgument {
     call: Node;
     argument: Node;
 }
+/** See `ResolutionStore.envNamers`. */
+interface EnvironmentNamers {
+    /**
+     * The environment reads that take their variable's name from this
+     * parameter, however many helpers forward it along the way. Empty for
+     * a parameter no read ever takes a name from, and null where the
+     * rules had nothing to go on: a file that exports nothing states no
+     * facts, so their silence about its parameters means neither yes nor
+     * no, and the asker settles what it can by reading the syntax.
+     */
+    sitesNaming(parameter: Node): readonly Node[] | null;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
@@ -66,13 +78,17 @@ declare class ResolutionStore {
     private readonly constructionSites;
     /** Files the most recent query read, for the memo to keep. */
     private lastQueryWalked;
+    /** See `environmentSiteFiles`; null until the first env question. */
+    private envSiteFiles;
+    private envNamersAnswer;
+    private envNamersExtractedAt;
     private readonly declarations;
     private readonly graph;
     /** See `notePossibleCallers`. */
     private readonly possibleCallers;
     private readonly callerFilesRead;
     private stale;
-    constructor(wrappers?: TransparentWrapper[]);
+    constructor(wrappers?: TransparentWrapper[], environmentObjects?: readonly string[]);
     /**
      * `alsoFrom` is a second file to walk out from, for a caller that
      * knows where the value it is asking about was set up. The walk
@@ -144,6 +160,32 @@ declare class ResolutionStore {
      * parameter's own function with no join against `bodyCalls` needed.
      */
     callsPassing(parameter: Node): PassedArgument[];
+    /**
+     * Which parameters an environment read takes its variable's name
+     * from, for a reader standing at a call. One question covers the
+     * whole project: a project has a handful of environment reads and
+     * thousands of parameters, and with the read bound the rules run from
+     * each callee to its callers.
+     *
+     * `definedIn` is the callee's own file, read into the store before
+     * the question so a helper nothing had extracted yet is among the
+     * facts the rules run over.
+     */
+    envNamers(definedIn: SourceFile): EnvironmentNamers;
+    private sitesNamedBy;
+    /**
+     * Seed every read the store knows of, derive, and take the sites back
+     * per parameter. The question is dropped afterwards, so a later ask
+     * over a larger fact set derives it again.
+     */
+    private askEnvNamers;
+    /**
+     * The project's files that spell an environment read with a computed
+     * index, read into the store. Which files those are cannot depend on
+     * what a reader happened to ask about first, so the scan is over the
+     * project's own sources and it happens once.
+     */
+    private environmentSiteFiles;
     /**
      * Whether running this function hands back that call: returned
      * outright, written into a name and returned, or a shorthand body.
@@ -247,6 +289,8 @@ declare class ResolutionStore {
      */
     private forgetQuery;
     private wantValue;
+    /** For a question seeded with a fact key the store read out of the database. */
+    private wantKey;
     private wantExportsOf;
     /**
      * Discovery walks the table in order, and the rounds derive it in
@@ -1579,4 +1623,4 @@ declare function climbSyntax(node: Node): Node;
  */
 declare function peelValue(node: Node): Node;
 
-export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, TSCONFIG_NAMES, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, arrayLiteralOf, buildProjectHelperIndex, callOpsFor, climbSyntax, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, couldNameAValue, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findEnclosingFunction, findNearestTsconfig, findTerminals, functionTargetOf, functionValueOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isDefaultedAt, isImportedFrom, methodDeclaredIn, namedImportsOf, objectLiteralOf, parseConditionExpression, peelSyntax, peelValue, propertiesOf, propertyFunctionOf, propertyNameOf, propertyOf, propertyValueOf, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, workspaceRootFor, writtenNodeOf };
+export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type EnvironmentNamers, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, TSCONFIG_NAMES, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, arrayLiteralOf, buildProjectHelperIndex, callOpsFor, climbSyntax, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, couldNameAValue, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findEnclosingFunction, findNearestTsconfig, findTerminals, functionTargetOf, functionValueOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isDefaultedAt, isImportedFrom, methodDeclaredIn, namedImportsOf, objectLiteralOf, parseConditionExpression, peelSyntax, peelValue, propertiesOf, propertyFunctionOf, propertyNameOf, propertyOf, propertyValueOf, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, workspaceRootFor, writtenNodeOf };

package/dist/index.js

@@ -1454,13 +1454,14 @@ function isWriteTarget(name) {
 function fact(db, relation, ...tuple) {
   db.add(relation, tuple);
 }
-function createNodeTable() {
+function createNodeTable(environmentObjects = []) {
   return {
     byId: /* @__PURE__ */ new Map(),
     seenFunctions: /* @__PURE__ */ new Set(),
     seenBindings: /* @__PURE__ */ new Set(),
     seenValues: /* @__PURE__ */ new Set(),
-    seenClasses: /* @__PURE__ */ new Set()
+    seenClasses: /* @__PURE__ */ new Set(),
+    environmentObjects
   };
 }
 function nodeId(node) {
@@ -1605,6 +1606,40 @@ function literalIndexOf(index) {
   }
   return null;
 }
+function readsEnvironment(table, access) {
+  if (table.environmentObjects.length === 0) {
+    return false;
+  }
+  const path14 = dottedPathOf(access.getExpression());
+  return path14 !== null && table.environmentObjects.includes(path14);
+}
+function isEnvironmentNameRead(table, node) {
+  if (!Node5.isElementAccessExpression(node)) {
+    return false;
+  }
+  const argument = node.getArgumentExpression();
+  return argument !== void 0 && literalIndexOf(argument) === null && readsEnvironment(table, node);
+}
+function environmentNameReadsIn(table, sourceFile) {
+  if (table.environmentObjects.length === 0) {
+    return [];
+  }
+  const text = sourceFile.getFullText();
+  if (!table.environmentObjects.some((path14) => text.includes(path14))) {
+    return [];
+  }
+  return sourceFile.getDescendantsOfKind(SyntaxKind2.ElementAccessExpression).filter((access) => isEnvironmentNameRead(table, access));
+}
+function dottedPathOf(expression) {
+  if (Node5.isIdentifier(expression)) {
+    return expression.getText();
+  }
+  if (!Node5.isPropertyAccessExpression(expression)) {
+    return null;
+  }
+  const object = dottedPathOf(expression.getExpression());
+  return object === null ? null : `${object}.${expression.getName()}`;
+}
 function asFallbackExpression(expression) {
   if (!Node5.isBinaryExpression(expression)) {
     return null;
@@ -1676,6 +1711,10 @@ function emitValue(db, table, value) {
       );
       return id;
     }
+    const argument = expression.getArgumentExpression();
+    if (argument !== void 0 && readsEnvironment(table, expression)) {
+      fact(db, "readsEnvNamed", id, emitValue(db, table, argument));
+    }
     fact(db, "writtenValue", id);
     return id;
   }
@@ -2140,6 +2179,9 @@ function recordBodyCalls(db, table, fnId, node) {
   if (!Node5.isExpression(node)) {
     return false;
   }
+  if (isEnvironmentNameRead(table, node)) {
+    emitValue(db, table, node);
+  }
   const call = unwrapExpression(node);
   if (Node5.isCallExpression(call)) {
     const callee = unwrapExpression(call.getExpression());
@@ -2365,9 +2407,10 @@ var QUERY_FACTS = queryFacts(RESOLUTION_PROGRAM);
 var MODULE_DEMANDS = RESOLUTION_PROGRAM.demands.filter(
   (one) => (one.relation === "moduleExport" || one.relation === "moduleForwards") && one.bound[0] === true
 ).map((one) => one.demand);
+var NO_NAMERS = { sitesNaming: () => [] };
 var ResolutionStore = class {
   db = new Database2();
-  table = createNodeTable();
+  table;
   fullyExtracted = /* @__PURE__ */ new Set();
   seededValues = /* @__PURE__ */ new Set();
   importedNames = /* @__PURE__ */ new Map();
@@ -2385,13 +2428,18 @@ var ResolutionStore = class {
   constructionSites = /* @__PURE__ */ new Map();
   /** Files the most recent query read, for the memo to keep. */
   lastQueryWalked = [];
+  /** See `environmentSiteFiles`; null until the first env question. */
+  envSiteFiles = null;
+  envNamersAnswer = NO_NAMERS;
+  envNamersExtractedAt = -1;
   declarations = /* @__PURE__ */ new Map();
   graph = new ModuleGraph();
   /** See `notePossibleCallers`. */
   possibleCallers = /* @__PURE__ */ new Set();
   callerFilesRead = /* @__PURE__ */ new Set();
   stale = true;
-  constructor(wrappers = []) {
+  constructor(wrappers = [], environmentObjects = []) {
+    this.table = createNodeTable(environmentObjects);
     addPackWords(this.db, { unwrapsByName: wrappers });
   }
   /**
@@ -2604,6 +2652,89 @@ var ResolutionStore = class {
     }
     return found;
   }
+  /**
+   * Which parameters an environment read takes its variable's name
+   * from, for a reader standing at a call. One question covers the
+   * whole project: a project has a handful of environment reads and
+   * thousands of parameters, and with the read bound the rules run from
+   * each callee to its callers.
+   *
+   * `definedIn` is the callee's own file, read into the store before
+   * the question so a helper nothing had extracted yet is among the
+   * facts the rules run over.
+   */
+  envNamers(definedIn) {
+    const siteFiles = this.environmentSiteFiles(definedIn.getProject());
+    if (siteFiles.length === 0) {
+      return NO_NAMERS;
+    }
+    this.extractFile(definedIn);
+    if (this.envNamersExtractedAt === this.fullyExtracted.size) {
+      return this.envNamersAnswer;
+    }
+    const answered = this.askEnvNamers([...siteFiles, definedIn]);
+    const siteFilePaths = new Set(siteFiles.map((one) => one.getFilePath()));
+    this.envNamersAnswer = {
+      sitesNaming: (parameter) => this.sitesNamedBy(answered, siteFilePaths, parameter)
+    };
+    this.envNamersExtractedAt = this.fullyExtracted.size;
+    return this.envNamersAnswer;
+  }
+  sitesNamedBy(answered, siteFilePaths, parameter) {
+    const key = nodeId(parameter);
+    const sites = answered.get(key);
+    if (sites !== void 0) {
+      return sites;
+    }
+    if (!siteFilePaths.has(parameter.getSourceFile().getFilePath())) {
+      return [];
+    }
+    return this.db.lookup("paramOf", 2, key).length > 0 ? [] : null;
+  }
+  /**
+   * Seed every read the store knows of, derive, and take the sites back
+   * per parameter. The question is dropped afterwards, so a later ask
+   * over a larger fact set derives it again.
+   */
+  askEnvNamers(seeds) {
+    const byParameter = /* @__PURE__ */ new Map();
+    try {
+      for (const [site] of this.db.facts("readsEnvNamed")) {
+        this.wantKey("wantedEnvSite", String(site));
+      }
+      this.extractDemanded(seeds);
+      this.derive();
+      for (const [parameter, site] of this.db.facts("wantedParamNamesEnv")) {
+        const node = this.table.byId.get(String(site));
+        if (node === void 0) {
+          continue;
+        }
+        const sites = byParameter.get(String(parameter)) ?? [];
+        sites.push(node);
+        byParameter.set(String(parameter), sites);
+      }
+    } finally {
+      this.forgetQuery();
+    }
+    return byParameter;
+  }
+  /**
+   * The project's files that spell an environment read with a computed
+   * index, read into the store. Which files those are cannot depend on
+   * what a reader happened to ask about first, so the scan is over the
+   * project's own sources and it happens once.
+   */
+  environmentSiteFiles(project) {
+    if (this.envSiteFiles !== null) {
+      return this.envSiteFiles;
+    }
+    const found = project.getSourceFiles().filter(
+      (one) => !one.isInNodeModules() && environmentNameReadsIn(this.table, one).length > 0
+    );
+    this.envSiteFiles = found;
+    this.extractFiles(found);
+    return found;
+  }
   /**
    * Whether running this function hands back that call: returned
    * outright, written into a name and returned, or a shorthand body.
@@ -3014,7 +3145,11 @@ var ResolutionStore = class {
     this.stale = false;
   }
   wantValue(question, value) {
-    if (this.db.add(question, [nodeId(value)]) === "added") {
+    this.wantKey(question, nodeId(value));
+  }
+  /** For a question seeded with a fact key the store read out of the database. */
+  wantKey(question, key) {
+    if (this.db.add(question, [key]) === "added") {
       this.stale = true;
     }
   }
@@ -17654,11 +17789,14 @@ function createTypeScriptAdapter(suppliedConfig) {
   const packWrappers = config.frameworks.flatMap(
     (pack) => pack.transparentWrappers ?? []
   );
+  const packEnvironments = config.frameworks.flatMap(
+    (pack) => pack.environmentObjects ?? []
+  );
   return {
     tsProject: project,
     async extractFromFiles(filePaths) {
       const summaries = [];
-      const resolution = new ResolutionStore(packWrappers);
+      const resolution = new ResolutionStore(packWrappers, packEnvironments);
       const claimedUnits = /* @__PURE__ */ new Map();
       for (const fp of filePaths) {
         let sourceFile = project.getSourceFile(fp);
@@ -17761,7 +17899,7 @@ function createTypeScriptAdapter(suppliedConfig) {
         timer
       );
       timer.time("warmExportChains", () => warmExportChains(deep.deepRoots));
-      const resolution = new ResolutionStore(packWrappers);
+      const resolution = new ResolutionStore(packWrappers, packEnvironments);
       const packsByFile = timer.time(
         "preFilter",
         () => computePackApplicability(sourceFiles, config.frameworks, resolution)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/adapter-typescript",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "type": "module",
   "description": "Read a TypeScript or JavaScript codebase with suss and check what each handler returns against every caller, spec and template it can see.",
   "keywords": [
@@ -48,11 +48,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.31.1",
-    "@suss/datalog": "0.31.1",
-    "@suss/extractor": "0.31.1",
-    "@suss/resolution": "0.31.1",
-    "@suss/values": "0.31.1",
+    "@suss/behavioral-ir": "0.32.0",
+    "@suss/datalog": "0.32.0",
+    "@suss/extractor": "0.32.0",
+    "@suss/resolution": "0.32.0",
+    "@suss/values": "0.32.0",
     "graphql": "^16.8.0",
     "picomatch": "^4.0.4",
     "ts-morph": "^23.0.0",