@suss/adapter-typescript 0.22.3 → 0.22.4

package/dist/index.js

@@ -3716,6 +3716,18 @@ var ResolutionStore = class {
     const target = factKeyOf(value);
     return this.askAbout(target, "wanted", () => this.lookupObject(target));
   }
+  /**
+   * The function a call returns: `app.use(requireCaller(config))`
+   * registers what the factory gives back. A separate question from
+   * `resolveCallable`, which keeps a call unresolved on purpose so an
+   * unwrapping answer wins; this one is asked only after that has
+   * declined. Two returned functions give null, like every other
+   * single-answer question here.
+   */
+  resolveReturnedCallable(call) {
+    const target = factKeyOf(call);
+    return this.askAbout(target, "wanted", () => this.lookupReturned(target));
+  }
   /**
    * For a value that is neither a function nor an object, such as a
    * GraphQL document kept in a constant in another file.
@@ -4159,6 +4171,21 @@ var ResolutionStore = class {
     }
     return [...candidates][0];
   }
+  lookupReturned(call) {
+    this.derive();
+    const candidates = /* @__PURE__ */ new Set();
+    for (const target of this.answersFor("wantedGivesBack", nodeId(call))) {
+      const node = this.table.byId.get(target);
+      if (node === void 0 || !isFunctionRoot(node)) {
+        continue;
+      }
+      candidates.add(node);
+    }
+    if (candidates.size !== 1) {
+      return null;
+    }
+    return [...candidates][0];
+  }
   /**
    * Two candidates give null, since ambiguity is nothing. The value
    * itself is never a result either, or an identifier whose chain went
@@ -5286,7 +5313,27 @@ function functionValueOf(value, resolution) {
     return null;
   }
   const resolved = resolution.resolveCallable(written);
-  return resolved === null ? null : toFunctionRoot(resolved);
+  if (resolved !== null) {
+    return toFunctionRoot(resolved);
+  }
+  if (!Node17.isCallExpression(written)) {
+    return null;
+  }
+  const returned = resolution.resolveReturnedCallable(written);
+  return returned === null ? null : toFunctionRoot(returned);
+}
+function propertyNameOf(property) {
+  if (Node17.isPropertyAssignment(property) || Node17.isShorthandPropertyAssignment(property) || Node17.isMethodDeclaration(property)) {
+    return property.getName();
+  }
+  return null;
+}
+function propertyFunctionOf(property, resolution) {
+  if (Node17.isMethodDeclaration(property)) {
+    return property;
+  }
+  const held = propertyValueOf(property);
+  return held === null ? null : functionValueOf(held, resolution);
 }
 function objectLiteralOf(value, resolution) {
   return literalValueOf(
@@ -8760,7 +8807,7 @@ function discoverResolverMaps(sourceFile, match, kind, resolution) {
     }
     const schemaSdl = extractTypeDefsSdl(config, store);
     for (const typeProp of propertiesOf(resolversObj, store)) {
-      const typeName = resolverPropertyName(typeProp);
+      const typeName = propertyNameOf(typeProp);
       if (typeName === null || excludeTypes.has(typeName)) {
         continue;
       }
@@ -8769,11 +8816,11 @@ function discoverResolverMaps(sourceFile, match, kind, resolution) {
         continue;
       }
       for (const fieldProp of propertiesOf(typeObj, store)) {
-        const fieldName = resolverPropertyName(fieldProp);
+        const fieldName = propertyNameOf(fieldProp);
         if (fieldName === null) {
           continue;
         }
-        const fn = resolverPropertyFunction(fieldProp, store);
+        const fn = propertyFunctionOf(fieldProp, store);
         if (fn === null) {
           continue;
         }
@@ -8837,22 +8884,6 @@ function writtenSdl(expr) {
   }
   return null;
 }
-function resolverPropertyName(prop) {
-  if (Node36.isPropertyAssignment(prop) || Node36.isMethodDeclaration(prop)) {
-    return prop.getName();
-  }
-  if (Node36.isShorthandPropertyAssignment(prop)) {
-    return prop.getName();
-  }
-  return null;
-}
-function resolverPropertyFunction(prop, resolution) {
-  if (Node36.isMethodDeclaration(prop)) {
-    return prop;
-  }
-  const held = propertyValueOf(prop);
-  return held === null ? null : functionValueOf(held, resolution);
-}
 
 // src/discovery/index.ts
 function runPattern(sourceFile, pattern, resolution, mountPrefixes, expandedElsewhere) {
@@ -12265,7 +12296,7 @@ function countUnmatchedReturns(func, terminals, barriers = NO_BARRIERS) {
   });
   return unmatched;
 }
-function extractRawBranches(func, terminalPatterns, invocationRecognizers = [], accessRecognizers = [], barriers = NO_BARRIERS, resolution, originatesFrom, anchorCallsOf, resolveCallee2) {
+function extractRawBranches(func, terminalPatterns, invocationRecognizers = [], accessRecognizers = [], barriers = NO_BARRIERS, resolution, originatesFrom, anchorCallsOf, resolveCallee2, collectCallAccounting = false) {
   const terminals = findTerminals(
     func,
     terminalPatterns,
@@ -12353,8 +12384,8 @@ function extractRawBranches(func, terminalPatterns, invocationRecognizers = [],
     seenBranches.add(key);
     return true;
   });
+  const terminalNodes = new Set(terminals.map(({ node }) => node));
   if (invocations.length > 0) {
-    const terminalNodes = new Set(terminals.map(({ node }) => node));
     const sideEffects = invocations.filter(
       (i) => !writesTerminal(i.node, terminalNodes)
     );
@@ -12370,7 +12401,39 @@ function extractRawBranches(func, terminalPatterns, invocationRecognizers = [],
       branch.extraEffects = [...branch.extraEffects ?? [], ...extra];
     }
   }
-  return { branches: distinctBranches, terminals };
+  return {
+    branches: distinctBranches,
+    terminals,
+    ...collectCallAccounting ? {
+      callAccounting: invocations.map(
+        (site) => accountFor(site, terminalNodes, distinctBranches)
+      )
+    } : {}
+  };
+}
+function accountFor(site, terminalNodes, branches) {
+  const { node, line } = site;
+  const callee = node.getExpression().getText();
+  if (writesTerminal(node, terminalNodes)) {
+    return { node, callee, line, outcome: "terminal" };
+  }
+  const call = {
+    line,
+    alwaysRuns: site.alwaysRuns,
+    preconditions: preconditionsOf(site.effect)
+  };
+  if (branches.some((branch) => firesOn(call, branch))) {
+    return { node, callee, line, outcome: "invocation" };
+  }
+  const reachable = branches.some(
+    (branch) => site.alwaysRuns || runsBefore(line, branch.terminal.location.end)
+  );
+  return {
+    node,
+    callee,
+    line,
+    outcome: reachable ? "unrecorded" : "unreachable"
+  };
 }
 
 // src/bootstrap/sourceFileLookup.ts
@@ -12585,7 +12648,7 @@ function unwrapContractInit(init) {
   }
   return null;
 }
-function extractEndpointContract(endpointNode, pattern, framework) {
+function extractEndpointContract(endpointNode, pattern, framework, resolution) {
   if (!Node54.isObjectLiteralExpression(endpointNode)) {
     return null;
   }
@@ -12610,9 +12673,10 @@ function extractEndpointContract(endpointNode, pattern, framework) {
       }
     }
     if (propName === pattern.responseExtraction.property) {
-      const val = prop.getInitializer();
-      if (val !== void 0 && Node54.isObjectLiteralExpression(val)) {
-        for (const respProp of val.getProperties()) {
+      const written = prop.getInitializer();
+      const val = written === void 0 ? null : objectLiteralOf(written, resolution);
+      if (val !== null) {
+        for (const respProp of propertiesOf(val, resolution)) {
           if (!Node54.isPropertyAssignment(respProp)) {
             continue;
           }
@@ -12651,7 +12715,12 @@ function readContract(unit, pattern, framework, resolution) {
     if (endpointNode === null) {
       return null;
     }
-    return extractEndpointContract(endpointNode, pattern, framework);
+    return extractEndpointContract(
+      endpointNode,
+      pattern,
+      framework,
+      resolution
+    );
   }
   const routerInfo = findRouterCall(unit);
   if (routerInfo === null) {
@@ -12672,7 +12741,12 @@ function readContract(unit, pattern, framework, resolution) {
     if (endpointInit === void 0) {
       continue;
     }
-    return extractEndpointContract(endpointInit, pattern, framework);
+    return extractEndpointContract(
+      endpointInit,
+      pattern,
+      framework,
+      resolution
+    );
   }
   return null;
 }
@@ -12749,7 +12823,12 @@ function readContractForClientCall(callExpression, methodName, pattern, framewor
     if (endpointInit === void 0) {
       continue;
     }
-    return extractEndpointContract(endpointInit, pattern, framework);
+    return extractEndpointContract(
+      endpointInit,
+      pattern,
+      framework,
+      resolution
+    );
   }
   return null;
 }
@@ -13509,7 +13588,11 @@ function recordEdge(edgesByChild, candidate) {
 // src/discovery/wrapperIndex.ts
 import { Node as Node58 } from "ts-morph";
 import { joinMountedPath as joinMountedPath3 } from "@suss/resolution";
-var NO_WRAPPERS = { wrappersFor: () => [], unitsIn: () => [] };
+var NO_WRAPPERS = {
+  wrappersFor: () => [],
+  unfollowedFor: () => [],
+  unitsIn: () => []
+};
 var ANONYMOUS = "<anon>";
 function buildWrapperIndex(packsByFile, resolution, mountPrefixes) {
   const workByPack = /* @__PURE__ */ new Map();
@@ -13535,21 +13618,32 @@ function buildWrapperIndex(packsByFile, resolution, mountPrefixes) {
     }
   }
   const bySubject = /* @__PURE__ */ new Map();
+  const unfollowedBySubject = /* @__PURE__ */ new Map();
   const unitsByFile = /* @__PURE__ */ new Map();
+  const stopsSeen = /* @__PURE__ */ new Set();
   let found = false;
   for (const [packName, work] of workByPack) {
     const candidates = [];
     for (const { sourceFile, pattern, match, wraps } of work) {
-      candidates.push(
-        ...discoverWrapperRegistrations(
-          sourceFile,
-          pattern,
-          match,
-          wraps,
-          resolution,
-          mountPrefixes
-        )
+      const scan = discoverWrapperRegistrations(
+        sourceFile,
+        pattern,
+        match,
+        wraps,
+        resolution,
+        mountPrefixes
       );
+      candidates.push(...scan.candidates);
+      for (const { subjectId, callId, stop } of scan.unresolved) {
+        if (stopsSeen.has(callId)) {
+          continue;
+        }
+        stopsSeen.add(callId);
+        found = true;
+        const stops = unfollowedBySubject.get(subjectId) ?? [];
+        stops.push(stop);
+        unfollowedBySubject.set(subjectId, stops);
+      }
     }
     for (const candidate of mostSpecific(candidates)) {
       found = true;
@@ -13567,6 +13661,7 @@ function buildWrapperIndex(packsByFile, resolution, mountPrefixes) {
   }
   return {
     wrappersFor: (subjectId) => bySubject.get(subjectId) ?? [],
+    unfollowedFor: (subjectId) => unfollowedBySubject.get(subjectId) ?? [],
     unitsIn: (file, pack) => unitsByFile.get(unitKey(file, pack)) ?? []
   };
 }
@@ -13600,10 +13695,20 @@ function discoverWrapperRegistrations(sourceFile, pattern, match, wraps, resolut
     match.importName,
     resolution
   );
+  if ("constructorOption" in wraps) {
+    return discoverConstructorOptions(
+      sourceFile,
+      pattern,
+      wraps,
+      subjects,
+      resolution
+    );
+  }
   if (subjects.size === 0 && !storeCanFindSubjects(sourceFile, match, resolution)) {
-    return [];
+    return { candidates: [], unresolved: [] };
   }
   const candidates = [];
+  const unresolved = [];
   sourceFile.forEachDescendant((node) => {
     if (!Node58.isCallExpression(node)) {
       return;
@@ -13626,8 +13731,13 @@ function discoverWrapperRegistrations(sourceFile, pattern, match, wraps, resolut
     if (targetArg === void 0) {
       return;
     }
+    const subjectId = nodeId(subjectNode);
     const target = functionValueOf(targetArg, resolution);
     if (target === null) {
+      const stop = factoryStopOf(targetArg);
+      if (stop !== null) {
+        unresolved.push({ subjectId, callId: nodeId(node), stop });
+      }
       return;
     }
     if (wraps.arity !== void 0 && target.getParameters().length !== wraps.arity) {
@@ -13637,29 +13747,136 @@ function discoverWrapperRegistrations(sourceFile, pattern, match, wraps, resolut
     if (scope === null) {
       return;
     }
-    const subjectId = nodeId(subjectNode);
     const mountedScope = scope === void 0 ? void 0 : mountedAt(subjectId, mountPrefixes, scope);
-    const named2 = functionNameOrAnon(target) !== ANONYMOUS;
-    candidates.push({
-      subjectId,
-      callId: nodeId(node),
-      targetId: nodeId(target),
-      byArity: wraps.arity !== void 0,
-      target,
-      pattern,
-      registeredIn: sourceFile.getFilePath(),
-      named: named2,
-      reference: {
-        file: target.getSourceFile().getFilePath(),
-        // A function written out at the registration call has no name
-        // of its own, so it goes by the method that registered it.
-        name: named2 ? functionNameOrAnon(target) : wraps.method,
-        ...wraps.throwParam === void 0 ? {} : { onThrow: true },
-        ...mountedScope === void 0 ? {} : { scope: mountedScope }
-      }
-    });
+    candidates.push(
+      candidateOf(
+        {
+          subjectId,
+          callId: nodeId(node),
+          target,
+          label: labelFor(targetArg, wraps),
+          byArity: wraps.arity !== void 0,
+          onThrow: wraps.throwParam !== void 0,
+          scope: mountedScope
+        },
+        pattern,
+        sourceFile
+      )
+    );
   });
-  return candidates;
+  return { candidates, unresolved };
+}
+function discoverConstructorOptions(sourceFile, pattern, wraps, subjects, resolution) {
+  const candidates = [];
+  const unresolved = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const construction of subjects.values()) {
+    const subjectId = nodeId(construction);
+    if (seen.has(subjectId) || construction.getSourceFile() !== sourceFile) {
+      continue;
+    }
+    seen.add(subjectId);
+    const option = constructorOptionOf(construction, wraps, resolution);
+    if (option === void 0) {
+      continue;
+    }
+    const callId = nodeId(option);
+    const written = propertyValueOf(option);
+    const target = propertyFunctionOf(option, resolution);
+    if (target === null) {
+      const stop = written === null ? null : factoryStopOf(written);
+      if (stop !== null) {
+        unresolved.push({ subjectId, callId, stop });
+      }
+      continue;
+    }
+    candidates.push(
+      candidateOf(
+        {
+          subjectId,
+          callId,
+          target,
+          label: (written === null ? void 0 : factoryNameOf(written)) ?? wraps.constructorOption,
+          byArity: false,
+          onThrow: wraps.throwParam !== void 0,
+          scope: void 0
+        },
+        pattern,
+        sourceFile
+      )
+    );
+  }
+  return { candidates, unresolved };
+}
+function constructorOptionOf(construction, wraps, resolution) {
+  if (!(Node58.isNewExpression(construction) || Node58.isCallExpression(construction))) {
+    return void 0;
+  }
+  const optionsArg = construction.getArguments()[wraps.targetPosition];
+  if (optionsArg === void 0) {
+    return void 0;
+  }
+  const options = objectLiteralOf(optionsArg, resolution);
+  if (options === null) {
+    return void 0;
+  }
+  return propertiesOf(options, resolution).find(
+    (property) => propertyNameOf(property) === wraps.constructorOption
+  );
+}
+function candidateOf(registration, pattern, sourceFile) {
+  const { target, label, onThrow, scope } = registration;
+  const named2 = functionNameOrAnon(target) !== ANONYMOUS;
+  return {
+    subjectId: registration.subjectId,
+    callId: registration.callId,
+    targetId: nodeId(target),
+    byArity: registration.byArity,
+    target,
+    pattern,
+    registeredIn: sourceFile.getFilePath(),
+    named: named2,
+    reference: {
+      file: target.getSourceFile().getFilePath(),
+      name: named2 ? functionNameOrAnon(target) : label,
+      ...onThrow ? { onThrow: true } : {},
+      ...scope === void 0 ? {} : { scope }
+    }
+  };
+}
+function labelFor(targetArg, wraps) {
+  return factoryNameOf(targetArg) ?? wraps.method;
+}
+function factoryNameOf(targetArg) {
+  const written = factKeyOf(targetArg);
+  if (!Node58.isCallExpression(written)) {
+    return void 0;
+  }
+  const callee = written.getExpression();
+  if (Node58.isIdentifier(callee)) {
+    return callee.getText();
+  }
+  if (Node58.isPropertyAccessExpression(callee)) {
+    return callee.getName();
+  }
+  return void 0;
+}
+function factoryStopOf(targetArg) {
+  const written = factKeyOf(targetArg);
+  if (!Node58.isCallExpression(written)) {
+    return null;
+  }
+  const callee = factoryNameOf(targetArg);
+  if (callee === void 0) {
+    return null;
+  }
+  const reason = classifyStop(
+    declarationsBehind(written.getExpression().getSymbol())
+  );
+  if (!worthRecording(reason)) {
+    return null;
+  }
+  return { callee, reason: "unresolvedWrapper" };
 }
 function mountedAt(subjectId, mountPrefixes, scope) {
   const prefix = mountPrefixes?.prefixForId?.(subjectId) ?? "";
@@ -14034,22 +14251,23 @@ import { Node as Node60 } from "ts-morph";
 import { functionCallBinding, TargetPlacements } from "@suss/behavioral-ir";
 import { Database as Database3, evaluate as evaluate4, lit as lit4, rule as rule4, variable as variable2 } from "@suss/datalog";
 import { assembleSummary as assembleSummary2 } from "@suss/extractor";
+var GENERIC_TERMINALS = [
+  { kind: "return", match: { type: "returnStatement" }, extraction: {} },
+  { kind: "throw", match: { type: "throwExpression" }, extraction: {} },
+  {
+    // Implicit fall-through at the end of a function body: covers
+    // void-returning orchestrators that never write `return`.
+    kind: "return",
+    match: { type: "functionFallthrough" },
+    extraction: {}
+  }
+];
 var reachablePack = {
   name: "reachable",
   languages: ["typescript"],
   protocol: "in-process",
   discovery: [],
-  terminals: [
-    { kind: "return", match: { type: "returnStatement" }, extraction: {} },
-    { kind: "throw", match: { type: "throwExpression" }, extraction: {} },
-    {
-      // Implicit fall-through at the end of a function body: covers
-      // void-returning orchestrators that never write `return`.
-      kind: "return",
-      match: { type: "functionFallthrough" },
-      extraction: {}
-    }
-  ],
+  terminals: GENERIC_TERMINALS,
   inputMapping: { type: "allPositional" }
 };
 function nodeKey(func) {
@@ -15854,10 +16072,10 @@ var FUNCTION_FALLTHROUGH_TERMINAL = {
   match: { type: "functionFallthrough" },
   extraction: {}
 };
-function thrownValueAt(unit) {
-  return unit.pattern?.wraps?.throwParam;
+function frameworkValueAt(unit) {
+  return unit.pattern?.wraps?.throwParam ?? unit.pattern?.wraps?.resultParam;
 }
-function pastThrownValue(terminals, at) {
+function pastFrameworkValue(terminals, at) {
   if (at === void 0) {
     return terminals;
   }
@@ -15871,7 +16089,7 @@ function pastThrownValue(terminals, at) {
     } : pattern
   );
 }
-function rolesPastThrownValue(mapping, at) {
+function rolesPastFrameworkValue(mapping, at) {
   if (at === void 0 || mapping.type !== "positionalParams") {
     return mapping;
   }
@@ -15897,7 +16115,7 @@ function continuationTerminal(unit) {
 }
 function terminalsFor(unit, pack) {
   const declared = [
-    ...unit.terminals ?? pastThrownValue(pack.terminals, thrownValueAt(unit)),
+    ...unit.terminals ?? pastFrameworkValue(pack.terminals, frameworkValueAt(unit)),
     ...continuationTerminal(unit)
   ];
   if (unit.callSite === void 0) {
@@ -15915,7 +16133,7 @@ function readCodeStructure(unit, pack, invocationRecognizers, accessRecognizers,
   }
   const params = extractParameters(
     func,
-    unit.inputMapping ?? rolesPastThrownValue(pack.inputMapping, thrownValueAt(unit))
+    unit.inputMapping ?? rolesPastFrameworkValue(pack.inputMapping, frameworkValueAt(unit))
   );
   const extracted = extractRawBranches(
     func,
@@ -16417,8 +16635,10 @@ function extractFromSourceFile(sourceFile, frameworks, claimedUnits, options, ta
         }
       }
       const summary = assembleSummary3(raw, options);
-      if (unit.unfollowed !== void 0 && options?.gapHandling !== "silent") {
-        summary.gaps.push(unfollowedCallGap(unit.unfollowed));
+      if (options?.gapHandling !== "silent") {
+        for (const stop of unfollowedStopsOf(unit, wrappers)) {
+          summary.gaps.push(unfollowedCallGap(stop));
+        }
       }
       if (unit.metadata !== void 0 && Object.keys(unit.metadata).length > 0) {
         summary.metadata = {
@@ -16471,6 +16691,13 @@ function stampWrappers(raw, unit, wrappers) {
     recordFileDependency(wrapper.file);
   }
 }
+function unfollowedStopsOf(unit, wrappers) {
+  const stops = unit.unfollowed === void 0 ? [] : [unit.unfollowed];
+  if (wrappers === void 0 || unit.registrationSubjectId === void 0) {
+    return stops;
+  }
+  return [...stops, ...wrappers.unfollowedFor(unit.registrationSubjectId)];
+}
 function emitLibraryEnvReadMarkers(summaries, project, frameworks) {
   for (const pack of frameworks) {
     for (const declared of pack.libraryEnvVars ?? []) {
@@ -17185,7 +17412,7 @@ function createTypeScriptAdapter(suppliedConfig) {
       });
       const composed = timer.time(
         "composeWrappers",
-        () => composeWrappers(enriched)
+        () => composeWrappers(enriched, config.extractorOptions ?? {})
       );
       if (config.onTiming !== void 0) {
         config.onTiming(timer.report());
@@ -17809,6 +18036,8 @@ function stubEvidence(options) {
 }
 export {
   ADAPTER_VERSION,
+  GENERIC_TERMINALS,
+  NO_BARRIERS,
   ResolutionStore,
   TypeScriptWhySession,
   accessContextFor,
@@ -17829,6 +18058,7 @@ export {
   findNearestTsconfig,
   findTerminals,
   functionTargetOf,
+  hasBody,
   importDeclarationsOf,
   importedNamesOf,
   importedRootsOf,
@@ -17844,6 +18074,7 @@ export {
   resolveAliasedSymbol,
   resolveSubject,
   rootIdentifier,
+  startsItsOwnScope,
   stubEvidence,
   stubEvidenceIn,
   workspaceRootFor

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@suss/adapter-typescript",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "type": "module",
-  "description": "TypeScript adapter for suss — walks source files with ts-morph and emits raw extractions for the suss pipeline.",
+  "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": [
     "suss",
-    "behavioral-summary",
     "static-analysis",
     "typescript",
+    "javascript",
     "ts-morph",
-    "ast"
+    "api-contract",
+    "api-drift",
+    "code-review"
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
@@ -46,11 +48,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.22.3",
-    "@suss/datalog": "0.22.3",
-    "@suss/extractor": "0.22.3",
-    "@suss/resolution": "0.22.3",
-    "@suss/values": "0.22.3",
+    "@suss/behavioral-ir": "0.22.4",
+    "@suss/datalog": "0.22.4",
+    "@suss/extractor": "0.22.4",
+    "@suss/resolution": "0.22.4",
+    "@suss/values": "0.22.4",
     "graphql": "^16.8.0",
     "picomatch": "^4.0.4",
     "ts-morph": "^23.0.0",