@saptools/service-flow 0.1.21 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.22
+
+- Propagate conservative same-file identity aliases of connected service clients, including typed, `as`, `satisfies`, helper-returned, and transitive aliases, while preserving `.tx()` alias evidence.
+- Link outbound `send(...)` calls through identity aliases to the closest same-file binding row so destination, service-path, placeholder, and helper-chain evidence remains available.
+- Add narrow same-file wrapper literal-path propagation for wrappers that pass a client parameter directly to `send({ path })`; dynamic wrapper paths remain semantic dynamic targets with parser warnings.
+- Improve trace-time contextual implementation selection evidence and suppress stale ambiguous unresolved reasons when a unique contextual handler is selected.
+- Expand `doctor --strict` with alias-binding, no-binding remote-action, contextual implementation, and wrapper path propagation quality aggregates.
+
 ## 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.

package/README.md

@@ -318,7 +318,7 @@ service-flow trace --workspace /path/to/workspace --repo facade-service --operat
 
 When a concrete target exists after variable substitution, the trace shows both the parameterized evidence and the resolved match. When it does not, `service-flow` keeps the edge as a dynamic candidate or unresolved edge so the missing link remains visible.
 
-Service-binding evidence keeps these fields distinct: service alias, alias expression, destination expression, service-path expression, operation-path expression, and runtime placeholders. Helpers that return concrete connected clients inside object properties are followed through destructuring and simple transaction aliases while preserving helper-chain evidence. This is important for common CAP helpers such as `cds.connect.to(`remote_${code}`, { credentials: { destination: `remote_${code}`, path: `/${entityType}ProcessService` } })`, where the alias is not the service path.
+Service-binding evidence keeps these fields distinct: service alias, alias expression, destination expression, service-path expression, operation-path expression, and runtime placeholders. Helpers that return concrete connected clients inside object properties are followed through destructuring, simple identity aliases, transitive same-file aliases, and transaction aliases while preserving helper-chain evidence. This is important for common CAP helpers such as `cds.connect.to(`remote_${code}`, { credentials: { destination: `remote_${code}`, path: `/${entityType}ProcessService` } })`, where the alias is not the service path.
 
 By default, production traces should be built from production source files. Keep generated credentials and local state out of git, and use explicit fixture/test workspaces when validating test-only mocked service clients so they do not pollute production graph interpretation.
 
@@ -418,8 +418,8 @@ 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`; 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.
+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; same-file identity aliases are propagated, while property/call-expression aliases and ambiguous wrapper flows remain conservative; 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, remote-action target quality, likely missed identity aliases, no-binding remote actions, contextual implementation stops, and wrapper dynamic-path candidates, including whether unresolved unknown/dynamic paths are semantic instead of numeric call ids.
 
 </details>
 

package/TECHNICAL-NOTE.md

@@ -1,5 +1,13 @@
 # Service Flow Resolution Notes
 
+## 0.1.22 alias, wrapper, contextual trace, and strict doctor notes
+
+- Same-file service-client identity aliases now create their own service binding rows when the right-hand side is a known connected client variable. The parser accepts direct identifier aliases plus typed, `as`, and `satisfies` forms, supports source-order transitive aliases, and records `aliasKind: identity` helper-chain evidence. It still does not infer aliases from property reads, indexed access, function calls, object metadata, or cross-scope guesses.
+- Outbound calls through identity aliases can attach to the closest alias binding row in the same source file, preserving alias, destination, service path, placeholder, and helper-chain evidence for link and trace.
+- Wrapper path propagation is intentionally narrow: same-file wrappers can resolve literal caller paths only when a wrapper client parameter is passed directly to `.send(...)` and a wrapper path parameter is passed as `send({ path })`. Dynamic caller paths remain dynamic with parser-warning evidence.
+- Contextual implementation selection now records selected/tied score evidence. When trace selects a unique contextual handler, the implementation hop sets `contextualImplementationSelected` and no longer renders the original ambiguous reason as a failure.
+- Strict doctor adds compact aggregates for likely missed identity aliases, remote actions with operation paths but no binding id, contextual implementation stops, and wrapper dynamic-path candidates.
+
 ## 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.

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

@@ -638,11 +638,47 @@ function isSupportedEventReceiver(receiver, rootReceiver, serviceVariables) {
   if (/^(srv|service|serviceClient|messaging|messageClient|eventClient)$/.test(candidate)) return true;
   return false;
 }
+function collectWrapperSpecs(source) {
+  const specs = /* @__PURE__ */ new Map();
+  const scanFunction = (name, fn) => {
+    const params = fn.parameters.map((param) => ts4.isIdentifier(param.name) ? param.name.text : void 0);
+    let found;
+    const visit = (node) => {
+      if (found) return;
+      if (node !== fn && (ts4.isFunctionDeclaration(node) || ts4.isArrowFunction(node) || ts4.isFunctionExpression(node))) {
+        ts4.forEachChild(node, visit);
+        return;
+      }
+      if (ts4.isCallExpression(node) && ts4.isPropertyAccessExpression(node.expression) && node.expression.name.text === "send" && ts4.isIdentifier(node.expression.expression)) {
+        const objectArg = node.arguments[0];
+        if (objectArg && ts4.isObjectLiteralExpression(objectArg)) {
+          const pathProp = objectArg.properties.find((property) => ts4.isShorthandPropertyAssignment(property) && property.name.text === "path");
+          if (pathProp) found = { client: node.expression.expression.text, path: pathProp.name.text, method: objectPropertyText(objectArg, "method") };
+        }
+      }
+      ts4.forEachChild(node, visit);
+    };
+    visit(fn);
+    if (!found) return;
+    const clientIndex = params.indexOf(found.client);
+    const pathIndex = params.indexOf(found.path);
+    const methodIndex = found.method && params.includes(found.method) ? params.indexOf(found.method) : void 0;
+    if (clientIndex >= 0 && pathIndex >= 0) specs.set(name, { clientIndex, pathIndex, methodIndex });
+  };
+  for (const stmt of source.statements) {
+    if (ts4.isFunctionDeclaration(stmt) && stmt.name) scanFunction(stmt.name.text, stmt);
+    if (ts4.isVariableStatement(stmt)) {
+      for (const decl of stmt.declarationList.declarations) if (ts4.isIdentifier(decl.name) && decl.initializer && (ts4.isArrowFunction(decl.initializer) || ts4.isFunctionExpression(decl.initializer))) scanFunction(decl.name.text, decl.initializer);
+    }
+  }
+  return specs;
+}
 function classifyOutboundCallsInSource(source, filePath) {
   const calls = [];
   const sourceFile = normalizePath(filePath);
   const initializers = variableInitializers(source);
   const serviceVariables = collectServiceVariables(source);
+  const wrapperSpecs = collectWrapperSpecs(source);
   const add = (node, fact, extra) => {
     calls.push({ node, fact: { ...fact, sourceFile, sourceLine: lineOf3(source.text, node.getStart(source)), confidence: fact.confidence ?? 0.8, evidence: parserEvidence(source, node, extra) } });
   };
@@ -664,6 +700,14 @@ function classifyOutboundCallsInSource(source, filePath) {
           const shorthandPath = objectPropertyIsShorthand(objectArg, "path");
           add(node, { callType: query ? "remote_query" : "remote_action", serviceVariableName: receiver, method: stripQuotes(objectPropertyText(objectArg, "method") ?? "POST"), operationPathExpr: op && !shorthandPath ? `/${stripQuotes(op).replace(/^\//, "")}` : void 0, queryEntity: query ? extractQueryEntity(query) : void 0, payloadSummary: summarizeExpression(objectArg.getText(source)), confidence: op || query ? 0.8 : 0.4, unresolvedReason: !query && shorthandPath ? "dynamic_operation_path_identifier" : void 0 }, { receiver, classifier: "service_client_send_object", operationPathExpression: shorthandPath ? op : void 0, parserWarning: shorthandPath ? "dynamic_operation_path_identifier" : void 0 });
         }
+      } else if (ts4.isCallExpression(expr) && ts4.isIdentifier(expr.expression) && wrapperSpecs.has(expr.expression.text)) {
+        const spec = wrapperSpecs.get(expr.expression.text);
+        const clientArg = spec ? expr.arguments[spec.clientIndex] : void 0;
+        const pathArg = spec ? expr.arguments[spec.pathIndex] : void 0;
+        const methodArg = spec?.methodIndex === void 0 ? void 0 : expr.arguments[spec.methodIndex];
+        if (spec && clientArg && ts4.isIdentifier(clientArg) && isStringLike(pathArg)) {
+          add(node, { callType: "remote_action", serviceVariableName: clientArg.text, method: stripQuotes(methodArg?.getText(source) ?? "POST"), operationPathExpr: `/${pathArg.text.replace(/^\//, "")}`, payloadSummary: summarizeExpression(node.getText(source)), confidence: 0.75 }, { receiver: clientArg.text, classifier: "local_wrapper_literal_path", wrapperFunction: expr.expression.text, literalCallerArgumentDetected: true });
+        }
       } else if (ts4.isPropertyAccessExpression(expr) && ["emit", "publish", "on"].includes(expr.name.text)) {
         const receiver = receiverName(expr.expression);
         const rootReceiver = rootReceiverName(expr.expression);
@@ -815,9 +859,15 @@ function connectFactFromCall(call) {
 }
 function unwrapCall(expr) {
   if (ts5.isAwaitExpression(expr)) return unwrapCall(expr.expression);
+  if (ts5.isAsExpression(expr) || ts5.isSatisfiesExpression(expr)) return unwrapCall(expr.expression);
   if (ts5.isCallExpression(expr)) return expr;
   return void 0;
 }
+function unwrapIdentityExpression(expr) {
+  if (ts5.isAwaitExpression(expr)) return unwrapIdentityExpression(expr.expression);
+  if (ts5.isAsExpression(expr) || ts5.isSatisfiesExpression(expr)) return unwrapIdentityExpression(expr.expression);
+  return expr;
+}
 function findConnectInExpression(expr) {
   const direct = unwrapCall(expr);
   if (direct) {
@@ -1075,6 +1125,35 @@ async function parseServiceBindings(repoPath, filePath) {
   async function importedHelper(localName) {
     return (await importedHelpers(localName)).find((row) => !row.helper.returnedProperty);
   }
+  function bindingForVariable(variableName) {
+    const sourceFile = normalizePath(filePath);
+    return [...out].reverse().find((row) => row.variableName === variableName && row.sourceFile === sourceFile);
+  }
+  function cloneAliasBinding(decl, sourceName, aliasKind) {
+    if (!ts5.isIdentifier(decl.name)) return;
+    const existing = bindingForVariable(sourceName);
+    if (!existing) return;
+    out.push({
+      ...existing,
+      variableName: decl.name.text,
+      sourceLine: lineOf4(sourceFileAst, decl),
+      helperChain: [
+        ...existing.helperChain ?? [],
+        {
+          callerVariable: decl.name.text,
+          aliasOf: sourceName,
+          aliasKind,
+          scopeRule: "same-file-source-order"
+        }
+      ]
+    });
+  }
+  function recordIdentityAlias(decl) {
+    if (!ts5.isIdentifier(decl.name) || !decl.initializer) return;
+    const unwrapped = unwrapIdentityExpression(decl.initializer);
+    if (!ts5.isIdentifier(unwrapped)) return;
+    cloneAliasBinding(decl, unwrapped.text, "identity");
+  }
   async function recordVariable(decl) {
     if (!ts5.isIdentifier(decl.name) || !decl.initializer) return;
     const call = unwrapCall(decl.initializer);
@@ -1187,10 +1266,9 @@ async function parseServiceBindings(repoPath, filePath) {
     await recordDestructuredHelper(decl);
     recordDestructuredClassHelper(decl);
     await recordVariable(decl);
+    recordIdentityAlias(decl);
     if (ts5.isIdentifier(decl.name) && decl.initializer && ts5.isCallExpression(decl.initializer) && ts5.isPropertyAccessExpression(decl.initializer.expression) && decl.initializer.expression.name.text === "tx" && ts5.isIdentifier(decl.initializer.expression.expression)) {
-      const sourceName = decl.initializer.expression.expression.text;
-      const existing = out.find((row) => row.variableName === sourceName && row.sourceFile === normalizePath(filePath));
-      if (existing) out.push({ ...existing, variableName: decl.name.text, sourceLine: lineOf4(sourceFileAst, decl), helperChain: [...existing.helperChain ?? [], { callerVariable: decl.name.text, aliasOf: sourceName, aliasKind: "transaction" }] });
+      cloneAliasBinding(decl, decl.initializer.expression.expression.text, "transaction");
     }
   }
   return out;
@@ -1998,10 +2076,25 @@ function implementationScope(db, operationId) {
   return { repoId: row?.repoId, files: new Set(row?.sourceFile ? [row.sourceFile] : []), symbolId: row?.symbolId, edge };
 }
 function contextImplementationMethodId(edge, callerRepoId) {
-  if (!edge || edge.status !== "ambiguous" || callerRepoId === void 0) return void 0;
+  if (!edge || edge.status !== "ambiguous" || callerRepoId === void 0) return { evidence: { status: "not_applicable" } };
   const evidence = JSON.parse(String(edge.evidence_json || "{}"));
-  const candidate = evidence.candidates?.find((item) => item.accepted && (Number(item.handlerPackage?.id) === callerRepoId || Number(item.applicationPackage?.id) === callerRepoId));
-  return candidate?.methodId === void 0 ? void 0 : String(candidate.methodId);
+  const scores = (evidence.candidates ?? []).filter((item) => item.accepted).map((item) => {
+    const reasons = [];
+    let score = Number(item.score ?? 0);
+    if (Number(item.handlerPackage?.id) === callerRepoId) {
+      score += 10;
+      reasons.push("handler_package_matches_caller_repository");
+    }
+    if (Number(item.applicationPackage?.id) === callerRepoId) {
+      score += 10;
+      reasons.push("registration_package_matches_caller_repository");
+    }
+    return { methodId: item.methodId, score, reasons, handlerPackage: item.handlerPackage, applicationPackage: item.applicationPackage };
+  }).sort((a, b) => b.score - a.score);
+  if (scores.length === 0) return { evidence: { status: "not_applicable", candidateScores: [] } };
+  const [first, second] = scores;
+  if (first && first.methodId !== void 0 && first.score > 0 && (!second || first.score > second.score)) return { methodId: String(first.methodId), evidence: { status: "selected", selectedMethodId: first.methodId, candidateScores: scores } };
+  return { evidence: { status: "tied", tieReason: "no_unique_materially_stronger_candidate", candidateScores: scores } };
 }
 function handlerScope(db, methodId) {
   const row = db.prepare("SELECT hc.repo_id repoId,hc.source_file sourceFile,s.id symbolId FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id LEFT JOIN symbols s ON s.repo_id=hc.repo_id AND s.source_file=hc.source_file AND s.name=hm.method_name WHERE hm.id=?").get(methodId);
@@ -2207,7 +2300,8 @@ function trace(db, start, options) {
         });
         if (effectiveRow.to_kind === "operation") {
           const implementation = implementationScope(db, effectiveRow.to_id);
-          const contextMethodId = contextImplementationMethodId(implementation.edge, current.repoId);
+          const contextSelection = contextImplementationMethodId(implementation.edge, current.repoId);
+          const contextMethodId = contextSelection.methodId;
           const contextNode = contextMethodId ? handlerMethodNode(db, contextMethodId) : void 0;
           if (implementation.edge) {
             const implEvidence = JSON.parse(String(implementation.edge.evidence_json || "{}"));
@@ -2219,9 +2313,9 @@ function trace(db, start, options) {
               type: "operation_implemented_by_handler",
               from: to,
               to: implTo,
-              evidence: implEvidence,
+              evidence: contextMethodId ? { ...implEvidence, contextualImplementationSelected: true, contextualImplementation: contextSelection.evidence } : { ...implEvidence, contextualImplementation: contextSelection.evidence },
               confidence: Number(implementation.edge.confidence ?? 0),
-              unresolvedReason: implementation.edge.status === "resolved" ? void 0 : String(implementation.edge.unresolved_reason ?? implementation.edge.status)
+              unresolvedReason: implementation.edge.status === "resolved" || contextMethodId ? void 0 : String(implementation.edge.unresolved_reason ?? implementation.edge.status)
             });
           }
           if (current.depth >= maxDepth) continue;
@@ -2278,4 +2372,4 @@ export {
   linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-TSMDIKML.js.map
+//# sourceMappingURL=chunk-JIY37C44.js.map