@saptools/service-flow 0.1.20 → 0.1.21

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.21
+
+- Propagate helper-returned connected clients from function declarations, arrow-function variables, function-expression variables, named export lists, and aliased exports into caller destructuring and transaction aliases.
+- Preserve conservative object-return analysis by binding only returned properties backed by local `cds.connect.to(...)` client variables, while ignoring unrelated metadata fields.
+- Document contextual implementation selection evidence and strict doctor checks for operation-path-only remote actions.
+
 ## 0.1.20
 
 - Preserve service-binding evidence when helpers return connected clients inside object properties and callers destructure or create simple transaction aliases.

package/README.md

@@ -227,7 +227,15 @@ service-flow list calls --workspace /path/to/workspace --repo facade-service --o
 - Service bindings are matched to outbound calls by repository, source file, and
   variable name to avoid false cross-file matches. If a helper-returned client is
   not linked, export the helper from a relative import target and ensure it returns
-  `cds.connect.to(...)` directly or through a simple wrapper. Trace evidence includes the caller variable, imported helper, source file, and exported symbol.
+  `cds.connect.to(...)` directly or returns an object property backed by a local
+  connected-client variable. Supported helper shapes include function declarations,
+  arrow-function variables, function-expression variables, named export lists, and
+  aliased exports such as `export { connectCatalog as createCatalogClient }`.
+  Shorthand returns like `return { client }` and explicit returns like
+  `return { serviceClient: client }` are followed only when the returned value is
+  a concrete client. Trace evidence includes the caller variable, returned
+  property, imported helper, source file, exported symbol, placeholders, and
+  transaction alias steps.
 - `SELECT.one.from(Entity)`, `SELECT.from(Entity)`, `INSERT.into(Entity)`,
   `UPDATE(Entity)`, and `DELETE.from(Entity)` are indexed as local database
   query entities when statically knowable.
@@ -410,7 +418,7 @@ Run `service-flow index` after source, CDS, package metadata, or helper-package
 <details>
 <summary><b>Why is an expected call unresolved?</b></summary>
 
-Check `service-flow doctor`, then inspect the facts with `service-flow list services`, `service-flow list operations`, and `service-flow list calls`. Dynamic destinations may need `--var key=value`, and custom wrappers may need new parser support.
+Check `service-flow doctor`, then inspect the facts with `service-flow list services`, `service-flow list operations`, and `service-flow list calls`. Dynamic destinations may need `--var key=value`; the key is the full trimmed expression inside `${...}` and is matched literally without JavaScript evaluation. Operation-path-only ambiguous remote actions usually mean the call had no service binding id; inspect `list calls`, `inspect operation`, and `doctor --strict` to determine whether helper-return propagation or wrapper support is missing. Contextual implementation selection only continues into a handler when static evidence such as caller repository, resolved service path, destination/alias expression, dependency edges, registration package, and local service ownership makes exactly one candidate stronger; ties remain ambiguous with reasons.
 Default doctor output is intended to focus on actionable indexing or trace-impacting issues; use `--strict` when you need exhaustive model-shape diagnostics for entity-only or extension-heavy CDS models. Strict mode also reports normalized OData invocation ambiguity and remote-action target quality, including whether unresolved unknown/dynamic paths are semantic instead of numeric call ids.
 
 </details>

package/TECHNICAL-NOTE.md

@@ -1,5 +1,12 @@
 # Service Flow Resolution Notes
 
+## 0.1.21 helper-return propagation and contextual trace notes
+
+- Helper-return binding analysis uses the same returned-object scanner for `function` declarations, `async function` declarations, arrow-function variables, async arrow-function variables, and function-expression variables. Named export lists and aliases are resolved, so `export { connectCatalog as createCatalogClient }` can be destructured by callers without losing evidence.
+- Returned object properties are bound only when their value is a local variable initialized from `cds.connect.to(...)`. Shorthand properties and explicit property assignments are supported; unrelated strings, codes, and metadata fields are ignored. Destructuring renames and `.tx()` aliases append helper-chain evidence instead of replacing the original binding evidence.
+- Trace-time contextual implementation selection may use caller repository, runtime-resolved service path, destination or alias expression, package dependency evidence, handler and registration packages, and local service ownership to continue from an ambiguous operation edge into one handler. If candidates tie or no static signal is strong enough, trace keeps the ambiguous edge and reports the tie or unresolved reason.
+- `doctor --strict` is the intended place for broad regression aggregates, including helper-return coverage, contextual implementation ambiguity, and remote actions that have an operation path but no service binding id.
+
 ## 0.1.20 helper object clients, expression placeholders, and remote-action target notes
 
 - Helper-return binding analysis now follows concrete `cds.connect.to(...)` clients returned through object shorthand or explicit properties. Callers that destructure those properties, rename them, or assign a simple `.tx()` transaction alias keep helper-chain evidence including caller variable, returned property, helper source, destination expression, service-path expression, and placeholders. Arbitrary object returns are ignored.

package/dist/{chunk-EKLZJJW7.js → chunk-TSMDIKML.js}

@@ -900,6 +900,8 @@ function collectReturnedObjectBindings(fn) {
   const bindings = /* @__PURE__ */ new Map();
   const returns = /* @__PURE__ */ new Map();
   function visit(node) {
+    if (node !== fn && (ts5.isFunctionDeclaration(node) || ts5.isArrowFunction(node) || ts5.isFunctionExpression(node)))
+      return;
     if (ts5.isVariableDeclaration(node) && ts5.isIdentifier(node.name) && node.initializer) {
       const fact = findConnectInExpression(node.initializer);
       if (fact) bindings.set(node.name.text, fact);
@@ -923,6 +925,35 @@ function collectReturnedObjectBindings(fn) {
   }
   return out;
 }
+function functionLikeInitializer(expr) {
+  if (!expr) return void 0;
+  if (ts5.isArrowFunction(expr) || ts5.isFunctionExpression(expr)) return expr;
+  return void 0;
+}
+function directReturnConnectFact(fn) {
+  const localBindings = /* @__PURE__ */ new Map();
+  let returned;
+  function visit(node) {
+    if (node !== fn && (ts5.isFunctionDeclaration(node) || ts5.isArrowFunction(node) || ts5.isFunctionExpression(node)))
+      return;
+    if (ts5.isVariableDeclaration(node) && ts5.isIdentifier(node.name) && node.initializer) {
+      const fact = findConnectInExpression(node.initializer);
+      if (fact) localBindings.set(node.name.text, fact);
+    }
+    if (!returned && ts5.isReturnStatement(node) && node.expression)
+      returned = node.expression;
+    if (!returned) ts5.forEachChild(node, visit);
+  }
+  visit(fn);
+  if (!returned) return void 0;
+  if (ts5.isIdentifier(returned)) return localBindings.get(returned.text);
+  return findConnectInExpression(returned);
+}
+function directConnectFactFromFunctionLike(fn) {
+  if (ts5.isArrowFunction(fn) && fn.body && !ts5.isBlock(fn.body))
+    return findConnectInExpression(fn.body);
+  return directReturnConnectFact(fn);
+}
 function exportedLocalNames(sf) {
   const exports = /* @__PURE__ */ new Map();
   for (const stmt of sf.statements) {
@@ -951,12 +982,7 @@ async function helperBindings(repoPath, filePath) {
   const factsByLocal = /* @__PURE__ */ new Map();
   for (const stmt of sf.statements) {
     if (ts5.isFunctionDeclaration(stmt) && stmt.name) {
-      let fact;
-      stmt.forEachChild(function visit(node) {
-        if (!fact && ts5.isReturnStatement(node) && node.expression)
-          fact = findConnectInExpression(node.expression);
-        if (!fact) ts5.forEachChild(node, visit);
-      });
+      const fact = directConnectFactFromFunctionLike(stmt);
       if (fact) factsByLocal.set(stmt.name.text, { ...fact, sourceLine: lineOf4(sf, stmt) });
       for (const [returnedProperty, objectFact] of collectReturnedObjectBindings(stmt))
         factsByLocal.set(`${stmt.name.text}#${returnedProperty}`, { ...objectFact, returnedProperty, sourceLine: lineOf4(sf, stmt) });
@@ -964,6 +990,22 @@ async function helperBindings(repoPath, filePath) {
     if (ts5.isVariableStatement(stmt))
       for (const decl of stmt.declarationList.declarations) {
         if (!ts5.isIdentifier(decl.name) || !decl.initializer) continue;
+        const helper = functionLikeInitializer(decl.initializer);
+        if (helper) {
+          const directReturn = directConnectFactFromFunctionLike(helper);
+          if (directReturn)
+            factsByLocal.set(decl.name.text, {
+              ...directReturn,
+              sourceLine: lineOf4(sourceFileAst, decl)
+            });
+          for (const [returnedProperty, objectFact] of collectReturnedObjectBindings(helper))
+            factsByLocal.set(`${decl.name.text}#${returnedProperty}`, {
+              ...objectFact,
+              returnedProperty,
+              sourceLine: lineOf4(sourceFileAst, decl)
+            });
+          continue;
+        }
         const fact = findConnectInExpression(decl.initializer);
         if (fact)
           factsByLocal.set(decl.name.text, {
@@ -1002,22 +1044,36 @@ async function parseServiceBindings(repoPath, filePath) {
   const classHelpers = collectClassHelpers(sourceFileAst);
   const localObjectHelpers = /* @__PURE__ */ new Map();
   for (const stmt of sourceFileAst.statements) {
-    if (!ts5.isFunctionDeclaration(stmt) || !stmt.name) continue;
-    const rows2 = [];
-    for (const [returnedProperty, fact] of collectReturnedObjectBindings(stmt))
-      rows2.push({ ...fact, exportedName: stmt.name.text, returnedProperty, sourceFile: normalizePath(filePath), sourceLine: lineOf4(sourceFileAst, stmt) });
-    if (rows2.length > 0) localObjectHelpers.set(stmt.name.text, rows2);
+    if (ts5.isFunctionDeclaration(stmt) && stmt.name) {
+      const rows2 = [];
+      for (const [returnedProperty, fact] of collectReturnedObjectBindings(stmt))
+        rows2.push({ ...fact, exportedName: stmt.name.text, returnedProperty, sourceFile: normalizePath(filePath), sourceLine: lineOf4(sourceFileAst, stmt) });
+      if (rows2.length > 0) localObjectHelpers.set(stmt.name.text, rows2);
+    }
+    if (ts5.isVariableStatement(stmt)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (!ts5.isIdentifier(decl.name)) continue;
+        const helper = functionLikeInitializer(decl.initializer);
+        if (!helper) continue;
+        const rows2 = [];
+        for (const [returnedProperty, fact] of collectReturnedObjectBindings(helper))
+          rows2.push({ ...fact, exportedName: decl.name.text, returnedProperty, sourceFile: normalizePath(filePath), sourceLine: lineOf4(sourceFileAst, decl) });
+        if (rows2.length > 0) localObjectHelpers.set(decl.name.text, rows2);
+      }
+    }
   }
-  async function importedHelper(localName) {
+  async function importedHelpers(localName) {
     const imp = imports.find((i) => i.localName === localName && i.sourceFile);
-    if (!imp?.sourceFile) return void 0;
+    if (!imp?.sourceFile) return [];
     if (!helperCache.has(imp.sourceFile))
       helperCache.set(
         imp.sourceFile,
         await helperBindings(repoPath, imp.sourceFile)
       );
-    const helper = helperCache.get(imp.sourceFile)?.find((h) => h.exportedName === imp.exportedName);
-    return helper ? { imp, helper } : void 0;
+    return (helperCache.get(imp.sourceFile) ?? []).filter((h) => h.exportedName === imp.exportedName).map((helper) => ({ imp, helper }));
+  }
+  async function importedHelper(localName) {
+    return (await importedHelpers(localName)).find((row) => !row.helper.returnedProperty);
   }
   async function recordVariable(decl) {
     if (!ts5.isIdentifier(decl.name) || !decl.initializer) return;
@@ -1057,23 +1113,24 @@ async function parseServiceBindings(repoPath, filePath) {
         });
     }
   }
-  async function helperForCall(call) {
-    if (!ts5.isIdentifier(call.expression)) return void 0;
-    const local = localObjectHelpers.get(call.expression.text)?.[0];
-    if (local) return { helper: local };
-    const resolved = await importedHelper(call.expression.text);
-    return resolved ? { helper: resolved.helper, imp: resolved.imp } : void 0;
+  async function helpersForCall(call) {
+    if (!ts5.isIdentifier(call.expression)) return [];
+    const local = localObjectHelpers.get(call.expression.text) ?? [];
+    const imported = await importedHelpers(call.expression.text);
+    return [...local.map((helper) => ({ helper })), ...imported];
   }
   async function recordDestructuredHelper(decl) {
     if (!ts5.isObjectBindingPattern(decl.name) || !decl.initializer) return;
     const call = unwrapCall(decl.initializer);
     if (!call) return;
-    const resolved = await helperForCall(call);
-    if (!resolved) return;
+    const helpers = await helpersForCall(call);
+    if (helpers.length === 0) return;
     for (const el of decl.name.elements) {
       if (!ts5.isIdentifier(el.name)) continue;
       const propertyName = el.propertyName && ts5.isIdentifier(el.propertyName) ? el.propertyName.text : el.name.text;
-      if (resolved.helper.returnedProperty !== propertyName) continue;
+      const matches = helpers.filter((row) => row.helper.returnedProperty === propertyName);
+      if (matches.length !== 1) continue;
+      const resolved = matches[0];
       out.push({
         variableName: el.name.text,
         alias: resolved.helper.alias,
@@ -1084,7 +1141,7 @@ async function parseServiceBindings(repoPath, filePath) {
         placeholders: resolved.helper.placeholders,
         sourceFile: normalizePath(filePath),
         sourceLine: lineOf4(sourceFileAst, decl),
-        helperChain: [{ callerVariable: el.name.text, helperFunction: call.expression.getText(sourceFileAst), returnedProperty: propertyName, importSource: resolved.imp?.sourceFile, helperSourceFile: resolved.helper.sourceFile, helperSourceLine: resolved.helper.sourceLine }]
+        helperChain: [{ callerVariable: el.name.text, helperFunction: call.expression.getText(sourceFileAst), returnedProperty: propertyName, importSource: resolved.imp?.sourceFile, exportedSymbol: resolved.imp?.exportedName, helperSourceFile: resolved.helper.sourceFile, helperSourceLine: resolved.helper.sourceLine }]
       });
     }
   }
@@ -2221,4 +2278,4 @@ export {
   linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-EKLZJJW7.js.map
+//# sourceMappingURL=chunk-TSMDIKML.js.map