Script API IntelliSense: infer types for undocumented helpers from usage

.changeset/script-types-fixes.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'b2c-vs-extension': patch
+---
+
+Script API IntelliSense fixes: `this` in SFRA middleware is now typed as the route, requests are faster in large cartridge workspaces, and the tsserver plugin no longer resolves `require()` paths outside the bundled types and cartridge roots of a malicious repository.

.changeset/script-types-infer-usage.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': minor
+'b2c-vs-extension': minor
+---
+
+Script API IntelliSense can now infer types for undocumented cartridge helpers from how they are used across the project, so hover and completions keep working where they used to fall back to `any`. Off by default: enable the `b2c-dx.features.scriptTypesInferUsage` VS Code setting, or pass `inferUsage: true` in the tsserver plugin config for other editors. See the IDE integration guide for details.

.changeset/vs-extension-untrusted-workspaces.md

@@ -0,0 +1,5 @@
+---
+'b2c-vs-extension': minor
+---
+
+The VS Code extension is now disabled in untrusted (Restricted Mode) workspaces, because it reads instance settings and credentials from workspace files; trust the workspace to use it.

.github/workflows/ci-vs-extension.yml

@@ -7,6 +7,7 @@ on:
       - develop
     paths:
       - 'packages/b2c-vs-extension/**'
+      - 'packages/b2c-script-types/**'
       - 'packages/b2c-tooling-sdk/**'
       - 'pnpm-lock.yaml'
       - 'pnpm-workspace.yaml'
@@ -17,6 +18,7 @@ on:
       - develop
     paths:
       - 'packages/b2c-vs-extension/**'
+      - 'packages/b2c-script-types/**'
       - 'packages/b2c-tooling-sdk/**'
       - 'pnpm-lock.yaml'
       - 'pnpm-workspace.yaml'

.gitignore

@@ -8,6 +8,7 @@ dist-deploy
 /tmp
 node_modules
 /coverage
+coverage/
 oclif.manifest.json
 *.tsbuildinfo
 

docs/guide/ide-integration.md

@@ -24,6 +24,8 @@ If you have the Salesforce B2C Commerce VS Code extension installed, IntelliSens
 
 You can disable the feature with the `b2c-dx.features.scriptTypes` setting (default: `true`).
 
+The extension only runs in trusted workspaces. It reads instance settings and credentials from workspace files such as `dw.json`, so VS Code keeps it disabled in Restricted Mode; trust the workspace to use it.
+
 The plugin also resolves SFCC cartridge-style requires, matching runtime semantics:
 
 - `require('~/cartridge/scripts/foo')` — resolves only within the cartridge that contains the current file (the SFCC `~` shortcut for "current cartridge"). If `foo` doesn't exist there, IntelliSense reports it unresolved — same as runtime.
@@ -125,6 +127,53 @@ require('lspconfig').ts_ls.setup({
 
 If your editor's LSP client is launched outside the repo root (for example, opening a single cartridge subdirectory), point it at the project root so the plugin's auto-discovery walks the right tree.
 
+### Inferring types for undocumented helpers (experimental)
+
+JSDoc-documented functions get full hover/completion support when the annotation names a real Script API type (`@param {dw.customer.Customer}` / `@param {Customer}`), because TypeScript reads those directly — the same happy path the IntelliJ SFCC plugin relies on. Plain, undocumented helpers don't, and neither do the placeholder SFRA annotations that show up constantly in real cartridges (`@param {Object}`, `{obj}`, `{*}`, `{}`, and arrays of those such as `{Array}`): those widen to an uninformative type and silence completion for everything downstream.
+
+Enable the `b2c-dx.features.scriptTypesInferUsage` setting (default: `false`) or pass `inferUsage: true` in the plugin config (`init_options.plugins` for other LSP hosts) to have the plugin infer a plausible type for these cases the way IntelliJ does: from how the value is actually used across the project, not from what it is called. Deliberate `@param {any}` / `: any` annotations are still respected and never second-guessed; real `dw.*` JSDoc is left alone too.
+
+The evidence it weighs:
+
+- **Call sites** — the arguments a helper receives anywhere in the project: plain calls, `new Model(x)` (constructor functions and ES6 classes alike), SFRA model inheritance through `BaseModel.call(this, x)` and `helper.apply(this, arguments)`, `this` passed from inside a constructor or class (`parameterToArray(this, key, value)` passes the model being built), calls through export maps and aliases (`module.exports = {helper: helper}`, `var run = helper`), and named functions passed as callbacks (`collections.forEach(items, handleItem)`). A function handed to a documented API rather than to a project helper takes the parameter types of the callback that API declares: `basket.getProductLineItems().toArray().forEach(keep)` types `keep`'s parameter as a `ProductLineItem`.
+- **Return values and chains** — return statements, followed through undocumented call chains (a helper calling a helper calling a helper), multi-hop method chains (`product.getPriceModel().getPrice()`) and intermediate local variables (`var priceModel = product.getPriceModel();`), including variables assigned in several branches and `lineItemContainer || {}` fallbacks.
+- **Values and the members they are stored in** — a member is what was put into it: `{apiProduct: apiProduct}`, `this.productSearch = productSearch`, `result.matchingProducts = ...`. Arrays are what was pushed into them (`var items = []; items.push(lineItem)`), a union when unrelated values were (`(Product | Basket)[]`), and element access, `filter`/`find`/`[0]` and native `forEach`/`map`/`reduce` callbacks read their elements. A constructor or model function is followed wherever its value goes — `module.exports = Model`, a factory that returns it (`var Model = getModel(definition)`), or an argument it is passed as (`createModel(..., Model)` → `new Model(...)`) — and a constructor's prototype methods count as usage of what it stores on `this`. Members a constructor defines with `Object.defineProperty(this, 'locale', {...})`, as SFRA's request model does, count as members of the model even though TypeScript leaves them off its type.
+- **Call-specific results** — when a generic helper returns nothing in particular across all of its callers, it is inferred again for the call at hand: `collections.find(basket.shipments, ...)` is a `Shipment`, `collections.find(basket.productLineItems, ...)` a `ProductLineItem`. A callback passed to such a helper is part of the call: `collections.map(basket.shipments, function (shipment) { return new ShippingModel(shipment); })` is a `ShippingModel[]`. Generic Script API calls such as `Transaction.wrap(function () { return order; })` return what their callback returns. IntelliJ does neither.
+- **Hooks** — nothing calls a hook script's exports by name; the platform dispatches `HookMgr.callHook('dw.order.calculate', 'calculate', basket)` to the scripts a cartridge's `hooks.json` (named by the `hooks` entry of its `package.json`) registers for that extension point. The plugin reads those registrations, so a hook function's parameters take the arguments of the `callHook` calls that reach it (from the third argument on), and a `callHook` call returns what the matching hook functions return. Extension points built at runtime (`'app.payment.processor.' + processor.ID.toLowerCase()` or a template literal, inline or in a local variable) reach every registered extension point their literal prefix starts. IntelliJ follows hooks in neither direction.
+- **Typed Script API uses** — a value handed to a documented API takes that API's parameter type, even when the helper is never called: `ShippingMgr.applyShippingCost(basket)` makes `basket` a `LineItemCtnr`, and `ProductMgr.getProduct(pid)` makes `pid` a `string`.
+- **The helper's own body** — the members it reads (`shipment.shippingAddress`), its `'member' in value` checks, and its `instanceof` / `typeof` tests. A call-site type that lacks a member the body relies on is dropped, so a duck-typed view model can't pass for the Script API class the body needs; a member the body only tests for or falls back from (`if (res.setStatusCode)`, `lineItemCtnr.orderNo || lineItemCtnr.UUID`) is not relied on. With no call site at all, the members are matched against every Script API class.
+
+`module.superModule` is understood too: in an overlay cartridge that extends a base module (`var base = module.superModule;`), hover and completions on `base` and on values derived from it resolve against the same-path module in the next cartridge down the cartridge path — including recursing into the base module's own undocumented helpers, and across multi-cartridge plugin stacks where intermediate levels re-export the base and add members (`module.exports = base; module.exports.extra = extra;`).
+
+Two more SFRA idioms are covered:
+
+- **Iteration callbacks** — a callback's parameters are what the helper it is passed to calls it with, for that call's arguments: `collections.forEach(product.getVariants(), function (variant) {...})` types `variant` as a `Variant`, and `collections.reduce(basket.productLineItems, function (total, lineItem) {...}, 0)` types `lineItem`, the second parameter, as a `ProductLineItem`. This reads the helper's own `callback(item)` / `callback.call(scope, item)` calls, so a project's own helpers (`eachShipment(basket, function (shipment) {...})`) and wrappers that hand the callback on to another helper work the same way; an accumulator the callback's result is fed back into stays unknown, as with a native `reduce`. A helper whose source isn't available falls back to its name: `collections.forEach` / `map` / `filter` / `every` / `some` / `find` / `first` take an element of the collection travelling alongside the callback (anything with `iterator()`/`next()`, i.e. `dw.util.Collection` and friends). Manual iterator loops (`var iter = coll.iterator(); while (iter.hasNext()) { var item = iter.next(); }`) and ternary returns like stock `collections.first` (`return it.hasNext() ? it.next() : null`) resolve through the same chain machinery.
+- **Controller middleware** — `server.append('Show', function (req, res, next) {...})` needs no inference at all: when a `modules` cartridge is present, the plugin injects its bundled SFRA ambient declarations and TypeScript types `req`/`res`/`next` contextually from the typed `append` signature, and `this` as the route, so the `req`/`res` of a `this.on('route:BeforeComplete', function (req, res) {...})` listener are typed as well. Inference deliberately stays out of the way there. A named middleware function that lives in its own module (`server.get('Show', cache.applyDefaultCache, ...)`, `consentTracking.consent`) has no contextual type of its own; with inference on, it takes `req`/`res`/`next` from the routes it is handed to. So does the middleware a factory returns (`server.append('Confirm', jsonResponse.responseHandler(fieldMap))`, where `responseHandler` returns `function (req, res, next) {...}`).
+
+Cross-file inference (call sites in other files, `module.superModule`) needs those files in the same TypeScript project. A `jsconfig.json` that includes all cartridge sources — like the one `b2c setup ide vscode-types` generates — provides that; without one, each open file gets its own inferred project and only same-file usage is visible.
+
+Inference stays cheap on large cartridge stacks. A request reads only the files that can name the value it follows: a helper local to one file is looked up in that file, and a module's exports in that module and the files that `require()` it. Each hover or completion runs a bounded number of such searches, and is dropped as soon as the editor cancels it (for example, when you keep typing).
+
+Inferred results are heuristic and clearly labeled:
+
+- Hover text gets an appended `Inferred from usage: <type>` line.
+- Member completions synthesized this way are still offered alongside (not instead of) whatever TypeScript already resolved.
+- Call sites that pass different types show their union, as IntelliJ does (`Product | Category`), up to three types. Different element types of one collection class read as that class (`Collection<Shipment>` and `Collection<ProductLineItem>` show `Collection`). An object literal with only members of a class another call site passes, such as a unit test's `{httpHeaders: {get: ...}}` stand-in for a `Request`, isn't counted as a type of its own. Wider evidence collapses to the closest shared superclass that still fits the body, or the hover stays silent.
+- Usage that a JavaScript built-in fits as well (`value.replace(...)` could be a `String`) and the TopLevel classes describing `module` and `arguments` never produce a Script API guess on their own.
+- Names never add a type of their own; they only break a tie when the usage fits several classes equally well. A `profile` parameter picks `dw.customer.Profile` over `ProductListRegistrant`, `lineItem` / `pli` pick `ProductLineItem`, and qualified names such as `apiProduct`, `currentBasket` or `resettingCustomer` resolve to the class they end in.
+
+This won't recover types TypeScript genuinely can't infer — for example, values that are never called with a consistent, well-typed argument anywhere in the project — and it's off by default because it's new and heuristic.
+
+**Known limitations** — intentionally deferred patterns:
+
+- Destructured function parameters (`function f({a, b})`)
+- Destructured return values (`var {a, b} = undocumentedFn()`)
+- Constructor inheritance via `Foo.prototype = Base.prototype`
+- Hooks the platform itself invokes (OCAPI/SCAPI `dw.ocapi.*` hooks, system extension points such as `dw.order.calculate` when no cartridge calls it): with no `HookMgr.callHook` call there is no call site, so only the hook's own body is evidence. Extension points without a literal prefix (`HookMgr.callHook(hookName, ...)` where `hookName` is a parameter or a variable assigned more than once) aren't matched either
+- Typed Script API uses through a value that is itself inferred (`paymentInstrument.paymentTransaction.setPaymentProcessor(processor)` where `paymentInstrument` is undocumented) don't count as usage of the argument
+- Values ISML templates read from `pdict`
+- Guessing individual custom attribute names on `.custom` (only `.custom` itself is usage evidence)
+
 ### Notes
 
 - The bundle is version-locked to a Script API release (currently 26.9). Re-run `b2c setup ide vscode-types` after upgrading the CLI to refresh the vendored copy; use `--force` to overwrite existing files if they were previously created. The plugin path returned by `b2c setup ide tsserver-plugin` always points at the bundle shipped with your installed CLI.

packages/b2c-script-types/README.md

@@ -56,4 +56,46 @@ in by the host extension via `tsApi.configurePlugin(...)`. Files outside the
 cartridge layout fall straight through to the unwrapped service — non-cartridge
 JavaScript and TypeScript in the same workspace see no behavior change.
 
-See [plugin/index.ts](./plugin/index.ts) for the implementation.
+See [src/index.ts](./src/index.ts) for the implementation.
+
+### Usage-based type inference (experimental, opt-in)
+
+An undocumented helper function (no JSDoc) gets its parameters and return
+value widened to `any` by plain TypeScript inference, and that `any`
+propagates to every caller. Passing `inferUsage: true` in the plugin config
+(off by default) makes the plugin infer a plausible type for these cases the
+way IntelliJ does: from call-site arguments (including `new`, `.call`/`.apply`
+and callbacks), the callback types of the declared APIs a function, or a
+factory's result, is handed to (`server.get('Show', cache.applyDefaultCache)`),
+return values, the typed Script API calls a value is passed to, and the members
+and `instanceof`/`typeof` checks in the helper's own body.
+Values are followed where they go — into object members, `this.x`, pushed
+arrays, factory returns and `module.exports` — and a generic helper such as
+`collections.find(basket.shipments, ...)` is inferred again for the call at
+hand, together with the callback it is passed
+(`collections.map(basket.shipments, fn)` is an array of what `fn` returns,
+and `fn`'s parameter is what `collections.map` calls it with: a `Shipment`).
+Hook scripts registered in a cartridge's `hooks.json` take the arguments of
+the `HookMgr.callHook(...)` calls that reach them, literal or prefixed
+(`'app.payment.processor.' + id`), and those calls return what the hooks return
+([src/resolver/hook-registry.ts](./src/resolver/hook-registry.ts) reads the
+registrations, as JSON only).
+The result is surfaced as an "Inferred from usage" hover note plus synthesized
+member completions; call sites that disagree show a union of up to three
+types, not counting object literals that only stand in for one of them (a
+unit test's `{httpHeaders: ...}` passed where production code passes a
+`Request`). It only kicks in where the checker has already given up (`any`, or a
+placeholder SFRA JSDoc such as `@param {Object}`), never overriding a real
+type from TypeScript or JSDoc.
+
+The engine gathers evidence ([src/inference/core.ts](./src/inference/core.ts))
+and applies one decision policy ([src/inference/policy.ts](./src/inference/policy.ts))
+everywhere, so parameter, member and chain hovers and completions always
+agree. [src/usage-inference.ts](./src/usage-inference.ts) is the barrel and
+lists the modules in reading order.
+
+A request reads only the files that can name the value it follows
+([src/inference/reference-search.ts](./src/inference/reference-search.ts)):
+the declaring file for a file-local helper, and the module plus the files that
+`require()` it for an export. It runs a bounded number of searches and stops
+when the editor cancels it.

packages/b2c-script-types/eslint.config.mjs

@@ -33,4 +33,13 @@ export default [
     files: ['test/**/*.ts'],
     rules: chaiTestRules,
   },
+  {
+    // The usage-inference suites are plain CommonJS .js files that exercise
+    // the compiled plugin/ output directly, so they use require() rather than
+    // the src/ package's ESM-style import syntax.
+    files: ['test/**/*.js'],
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off',
+    },
+  },
 ];

packages/b2c-script-types/package.json

@@ -29,11 +29,12 @@
     "typecheck:agent": "tsc -p . --noEmit --pretty false",
     "format": "prettier --write src test",
     "format:check": "prettier --check src test",
-    "pretest": "tsc --noEmit -p test",
-    "test": "c8 mocha --forbid-only \"test/**/*.test.ts\"",
-    "test:ci": "c8 mocha --forbid-only --reporter json --reporter-option output=test-results.json \"test/**/*.test.ts\"",
-    "test:agent": "mocha --forbid-only --reporter min \"test/**/*.test.ts\"",
-    "test:watch": "mocha --watch \"test/**/*.test.ts\"",
+    "pretest": "tsc --noEmit -p test && pnpm run build",
+    "test": "c8 mocha --forbid-only \"test/**/*.test.{ts,js}\"",
+    "test:ci": "c8 mocha --forbid-only --reporter json --reporter-option output=test-results.json \"test/**/*.test.{ts,js}\"",
+    "test:agent": "pnpm run build && mocha --forbid-only --reporter min \"test/**/*.test.{ts,js}\"",
+    "test:unit": "pnpm run test",
+    "test:watch": "pnpm run build && mocha --watch \"test/**/*.test.{ts,js}\"",
     "coverage": "c8 report",
     "posttest": "pnpm run lint"
   },