@saptools/service-flow 0.1.48 → 0.1.50

package/src/parsers/operation-path-analysis.ts

@@ -0,0 +1,350 @@
+import ts from 'typescript';
+import {
+  classifyODataPathIntent,
+  normalizeODataOperationInvocationPath,
+} from '../linker/odata-path-normalizer.js';
+
+export type OperationPathStatus = 'static' | 'ambiguous' | 'dynamic' | 'unknown';
+
+export interface OperationPathAnalysis {
+  status: OperationPathStatus;
+  rawExpression?: string;
+  normalizedOperationPath?: string;
+  candidateRawPaths: string[];
+  candidateNormalizedOperationPaths: string[];
+  placeholderKeys: string[];
+  sourceKind: string;
+  candidateIdentifier?: string;
+  runtimeIdentifier?: string;
+  dynamicReassignments: Array<{ expression: string; sourceLine: number }>;
+  lexicalScope: {
+    declarationLine?: number;
+    assignmentLines: number[];
+    sourceOrderSafe: boolean;
+  };
+}
+
+interface CandidateState {
+  paths: string[];
+  placeholders: string[];
+  dynamic: Array<{ expression: string; sourceLine: number }>;
+  sourceKinds: string[];
+}
+
+interface Binding {
+  declaration: ts.VariableDeclaration | ts.ParameterDeclaration;
+  immutable: boolean;
+}
+
+const maxAliasDepth = 6;
+
+export function analyzeOperationPath(
+  expression: ts.Expression | undefined,
+  use: ts.Node,
+  method = 'POST',
+): OperationPathAnalysis {
+  if (!expression) return emptyAnalysis();
+  const state = collectExpressionState(expression, use, 0, new Set());
+  const paths = unique(state.paths.map(normalizeRawPath));
+  const normalized = unique(paths.flatMap((value) => normalizedCandidate(value, method)));
+  const status = pathStatus(paths, state.placeholders, state.dynamic);
+  const runtimeIdentifier = state.dynamic.at(-1)?.expression;
+  return {
+    status,
+    rawExpression: expression.getText(expression.getSourceFile()),
+    normalizedOperationPath: status === 'static' && normalized.length === 1 ? normalized[0] : undefined,
+    candidateRawPaths: paths,
+    candidateNormalizedOperationPaths: normalized,
+    placeholderKeys: unique([...state.placeholders, ...(runtimeIdentifier ? [runtimeIdentifier] : [])]),
+    sourceKind: unique(state.sourceKinds).join('+') || 'unknown',
+    candidateIdentifier: ts.isIdentifier(expression) ? expression.text : undefined,
+    runtimeIdentifier,
+    dynamicReassignments: state.dynamic,
+    lexicalScope: lexicalEvidence(expression, use),
+  };
+}
+
+export function operationPathExpression(analysis: OperationPathAnalysis): string | undefined {
+  if (analysis.status === 'ambiguous' || analysis.status === 'unknown') return undefined;
+  if (analysis.sourceKind.includes('parameter_binding')) return undefined;
+  if (analysis.candidateRawPaths.length === 1 && analysis.dynamicReassignments.length === 0)
+    return analysis.candidateRawPaths[0];
+  if (!analysis.runtimeIdentifier || analysis.sourceKind.includes('binding_not_found'))
+    return undefined;
+  return isRuntimeIdentifier(analysis.runtimeIdentifier)
+    ? `\${${analysis.runtimeIdentifier}}`
+    : undefined;
+}
+
+export function pathUnresolvedReason(analysis: OperationPathAnalysis): string | undefined {
+  if (analysis.status === 'ambiguous') return 'ambiguous_operation_path_candidates';
+  if (analysis.status === 'dynamic' && !operationPathExpression(analysis))
+    return 'dynamic_operation_path_identifier';
+  if (analysis.dynamicReassignments.length > 0) return 'dynamic_operation_path_identifier';
+  return undefined;
+}
+
+function collectExpressionState(
+  expression: ts.Expression,
+  use: ts.Node,
+  depth: number,
+  seen: Set<ts.Node>,
+): CandidateState {
+  const unwrapped = unwrap(expression);
+  if (ts.isStringLiteral(unwrapped)) return staticState(unwrapped.text, 'string_literal');
+  if (ts.isNoSubstitutionTemplateLiteral(unwrapped))
+    return staticState(unwrapped.text, 'no_substitution_template');
+  if (ts.isTemplateExpression(unwrapped)) return templateState(unwrapped);
+  if (ts.isConditionalExpression(unwrapped))
+    return mergeStates([
+      collectExpressionState(unwrapped.whenTrue, use, depth + 1, seen),
+      collectExpressionState(unwrapped.whenFalse, use, depth + 1, seen),
+    ], 'conditional_candidates');
+  if (ts.isIdentifier(unwrapped))
+    return collectIdentifierState(unwrapped, use, depth, seen);
+  return dynamicState(unwrapped);
+}
+
+function collectIdentifierState(
+  identifier: ts.Identifier,
+  use: ts.Node,
+  depth: number,
+  seen: Set<ts.Node>,
+): CandidateState {
+  if (depth >= maxAliasDepth)
+    return dynamicState(identifier, 'alias_depth_exceeded');
+  const binding = resolveBinding(identifier, use);
+  if (!binding || seen.has(binding.declaration))
+    return dynamicState(identifier, binding ? 'alias_cycle' : 'binding_not_found');
+  seen.add(binding.declaration);
+  if (ts.isParameter(binding.declaration))
+    return dynamicState(identifier, 'parameter_binding');
+  const expressions = reachingExpressions(binding.declaration, use);
+  if (expressions.length === 0) return dynamicState(identifier, 'initializer_missing');
+  const states = expressions.map((item) =>
+    collectExpressionState(item.expression, item.node, depth + 1, seen));
+  const merged = mergeStates(states, binding.immutable ? 'const_alias' : 'mutable_alias');
+  if (merged.dynamic.length === 0) return merged;
+  return {
+    ...merged,
+    dynamic: merged.dynamic.map((item) =>
+      item.expression === identifier.text ? item : item),
+  };
+}
+
+function reachingExpressions(
+  declaration: ts.VariableDeclaration,
+  use: ts.Node,
+): Array<{ expression: ts.Expression; node: ts.Node }> {
+  const rows: Array<{ expression: ts.Expression; node: ts.Node }> = [];
+  if (declaration.initializer) rows.push({ expression: declaration.initializer, node: declaration });
+  if ((declaration.parent.flags & ts.NodeFlags.Const) !== 0) return rows;
+  const source = use.getSourceFile();
+  const visit = (node: ts.Node): void => {
+    if (node.getStart(source) >= use.getStart(source)) return;
+    if (node !== source && ts.isFunctionLike(node) && !contains(node, use)) return;
+    if (isAssignmentTo(node, declaration, use))
+      rows.push({ expression: node.right, node });
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return rows.sort((left, right) =>
+    left.node.getStart(source) - right.node.getStart(source));
+}
+
+function isAssignmentTo(
+  node: ts.Node,
+  declaration: ts.VariableDeclaration,
+  use: ts.Node,
+): node is ts.BinaryExpression {
+  if (!ts.isBinaryExpression(node) || node.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+    return false;
+  if (!ts.isIdentifier(node.left) || !ts.isIdentifier(declaration.name)) return false;
+  return resolveBinding(node.left, node)?.declaration === declaration && contains(declarationScope(declaration), use);
+}
+
+function resolveBinding(identifier: ts.Identifier, use: ts.Node): Binding | undefined {
+  const source = use.getSourceFile();
+  const matches: Array<ts.VariableDeclaration | ts.ParameterDeclaration> = [];
+  const visit = (node: ts.Node): void => {
+    if (isNamedDeclaration(node, identifier.text) && isAccessible(node, use))
+      matches.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  const declaration = matches.sort((left, right) =>
+    right.getStart(source) - left.getStart(source))[0];
+  if (!declaration) return undefined;
+  const immutable = ts.isVariableDeclaration(declaration)
+    && (declaration.parent.flags & ts.NodeFlags.Const) !== 0;
+  return { declaration, immutable };
+}
+
+function isNamedDeclaration(
+  node: ts.Node,
+  name: string,
+): node is ts.VariableDeclaration | ts.ParameterDeclaration {
+  return (ts.isVariableDeclaration(node) || ts.isParameter(node))
+    && ts.isIdentifier(node.name)
+    && node.name.text === name;
+}
+
+function isAccessible(
+  declaration: ts.VariableDeclaration | ts.ParameterDeclaration,
+  use: ts.Node,
+): boolean {
+  const source = use.getSourceFile();
+  if (declaration.name.getStart(source) >= use.getStart(source)) return false;
+  const scope = declarationScope(declaration);
+  return ts.isSourceFile(scope) || contains(scope, use);
+}
+
+function declarationScope(
+  declaration: ts.VariableDeclaration | ts.ParameterDeclaration,
+): ts.Node {
+  if (ts.isParameter(declaration)) return declaration.parent;
+  if (ts.isCatchClause(declaration.parent)) return declaration.parent.block;
+  const list = declaration.parent;
+  if (isLoopInitializer(list.parent)) return list.parent.statement;
+  const blockScoped = (list.flags & (ts.NodeFlags.Const | ts.NodeFlags.Let)) !== 0;
+  let current: ts.Node = list.parent;
+  if (!blockScoped) {
+    while (current.parent && !ts.isFunctionLike(current) && !ts.isSourceFile(current))
+      current = current.parent;
+    return current;
+  }
+  while (current.parent && !isLexicalScope(current)) current = current.parent;
+  return current;
+}
+
+function isLoopInitializer(
+  node: ts.Node,
+): node is ts.ForStatement | ts.ForInStatement | ts.ForOfStatement {
+  return ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node);
+}
+
+function isLexicalScope(node: ts.Node): boolean {
+  return ts.isBlock(node)
+    || ts.isSourceFile(node)
+    || ts.isModuleBlock(node)
+    || ts.isCaseBlock(node)
+    || ts.isFunctionLike(node);
+}
+
+function templateState(expression: ts.TemplateExpression): CandidateState {
+  const value = expression.getText(expression.getSourceFile()).slice(1, -1);
+  return {
+    paths: [value],
+    placeholders: expression.templateSpans.map((span) =>
+      span.expression.getText(expression.getSourceFile())),
+    dynamic: [],
+    sourceKinds: ['template_with_placeholders'],
+  };
+}
+
+function staticState(path: string, sourceKind: string): CandidateState {
+  return { paths: [path], placeholders: [], dynamic: [], sourceKinds: [sourceKind] };
+}
+
+function dynamicState(expression: ts.Expression, sourceKind = 'dynamic_expression'): CandidateState {
+  return {
+    paths: [],
+    placeholders: [],
+    dynamic: [{
+      expression: expression.getText(expression.getSourceFile()),
+      sourceLine: sourceLine(expression),
+    }],
+    sourceKinds: [sourceKind],
+  };
+}
+
+function mergeStates(states: CandidateState[], sourceKind: string): CandidateState {
+  return {
+    paths: states.flatMap((state) => state.paths),
+    placeholders: states.flatMap((state) => state.placeholders),
+    dynamic: states.flatMap((state) => state.dynamic),
+    sourceKinds: [sourceKind, ...states.flatMap((state) => state.sourceKinds)],
+  };
+}
+
+function pathStatus(
+  paths: string[],
+  placeholders: string[],
+  dynamic: CandidateState['dynamic'],
+): OperationPathStatus {
+  if (dynamic.length > 0) return 'dynamic';
+  if (paths.length > 1) return 'ambiguous';
+  if (placeholders.length > 0) return 'dynamic';
+  if (paths.length === 1) return 'static';
+  return 'unknown';
+}
+
+function normalizedCandidate(value: string, method: string): string[] {
+  const invocation = normalizeODataOperationInvocationPath(value);
+  if (invocation?.wasInvocation) return [invocation.normalizedOperationPath];
+  const intent = classifyODataPathIntent(value, method);
+  if (intent.kind.startsWith('entity_')) return [];
+  if (!value.startsWith('/') || value.slice(1).includes('/') || value.includes('?')) return [];
+  return [value];
+}
+
+function lexicalEvidence(expression: ts.Expression, use: ts.Node): OperationPathAnalysis['lexicalScope'] {
+  if (!ts.isIdentifier(expression))
+    return { assignmentLines: [], sourceOrderSafe: expression.getStart() < use.getStart() };
+  const binding = resolveBinding(expression, use);
+  if (!binding) return { assignmentLines: [], sourceOrderSafe: false };
+  const assignmentLines = ts.isVariableDeclaration(binding.declaration)
+    ? reachingExpressions(binding.declaration, use)
+        .slice(binding.declaration.initializer ? 1 : 0)
+        .map((item) => sourceLine(item.node))
+    : [];
+  return {
+    declarationLine: sourceLine(binding.declaration),
+    assignmentLines,
+    sourceOrderSafe: true,
+  };
+}
+
+function unwrap(expression: ts.Expression): ts.Expression {
+  if (ts.isAwaitExpression(expression) || ts.isParenthesizedExpression(expression))
+    return unwrap(expression.expression);
+  if (ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression)
+    || ts.isTypeAssertionExpression(expression))
+    return unwrap(expression.expression);
+  return expression;
+}
+
+function normalizeRawPath(value: string): string {
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function isRuntimeIdentifier(value: string): boolean {
+  return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(value);
+}
+
+function contains(parent: ts.Node, child: ts.Node): boolean {
+  const source = child.getSourceFile();
+  return child.getStart(source) >= parent.getStart(source)
+    && child.getEnd() <= parent.getEnd();
+}
+
+function sourceLine(node: ts.Node): number {
+  const source = node.getSourceFile();
+  return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+function emptyAnalysis(): OperationPathAnalysis {
+  return {
+    status: 'unknown',
+    candidateRawPaths: [],
+    candidateNormalizedOperationPaths: [],
+    placeholderKeys: [],
+    sourceKind: 'missing',
+    dynamicReassignments: [],
+    lexicalScope: { assignmentLines: [], sourceOrderSafe: false },
+  };
+}

package/src/parsers/outbound-call-parser.ts

@@ -8,6 +8,12 @@ import { summarizeExpression } from '../utils/redaction.js';
 import { classifyODataPathIntent } from '../linker/odata-path-normalizer.js';
 import { parseServiceBindings } from './service-binding-parser.js';
 import { parseImportedWrapperCalls } from './imported-wrapper-parser.js';
+import {
+  analyzeOperationPath,
+  operationPathExpression,
+  pathUnresolvedReason,
+  type OperationPathAnalysis,
+} from './operation-path-analysis.js';
 function lineOf(text: string, idx: number): number {
   return text.slice(0, idx).split('\n').length;
 }
@@ -180,44 +186,9 @@ function staticExpressionText(expr: ts.Expression | undefined, initializers: Map
   if (ts.isIdentifier(expr) && initializers.has(expr.text)) return staticExpressionText(initializers.get(expr.text), initializers);
   return undefined;
 }
-interface StaticPathResolution { text?: string; sourceKind: 'literal' | 'template' | 'const' | 'dynamic'; rawExpression?: string; constName?: string; resolution: ExpressionResolution }
-function staticPathExpression(expr: ts.Expression | undefined, use: ts.Node): StaticPathResolution {
-  const resolution = resolveExpression(expr, use, 'operation_path');
-  const sourceKind = resolution.sourceKind === 'const_alias' ? 'const' : resolution.sourceKind === 'template_with_substitutions' || resolution.sourceKind === 'no_substitution_template' ? 'template' : resolution.status === 'static' ? 'literal' : 'dynamic';
-  return { text: resolution.value, sourceKind, rawExpression: resolution.rawExpression, constName: resolution.constName, resolution };
-}
 function operationPathFromStatic(text: string | undefined): string | undefined {
   return text ? `/${stripQuotes(text).replace(/^\//, '')}` : undefined;
 }
-interface PathCandidateEvidence { candidatePaths: string[]; normalizedCandidateOperations: string[]; candidateSourceKind: string; candidateIdentifier: string; hasDynamicAssignments: boolean; conservativeReason?: string }
-function staticPathCandidates(identifier: ts.Identifier, call: ts.Node, method: string): PathCandidateEvidence | undefined {
-  const binding = resolveBinding(identifier, call);
-  const declaration = binding.declaration;
-  if (!declaration) return undefined;
-  const source = call.getSourceFile();
-  const paths: string[] = [];
-  let hasDynamicAssignments = false;
-  const addExpr = (expr: ts.Expression | undefined, origin: ts.Node): void => {
-    const resolved = staticPathExpression(expr, origin);
-    if (resolved.text) paths.push(operationPathFromStatic(resolved.text) ?? resolved.text);
-    else hasDynamicAssignments = true;
-  };
-  if (ts.isVariableDeclaration(declaration)) addExpr(declaration.initializer, declaration);
-  const visit = (node: ts.Node): void => {
-    if (node !== source && isFunctionLikeScope(node) && !nodeContains(node, call)) return;
-    if (node.getStart(source) >= call.getStart(source)) return;
-    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(node.left)) {
-      const target = resolveBinding(node.left, node);
-      if (target.declaration === declaration) addExpr(node.right, node);
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  const candidatePaths = [...new Set(paths)];
-  if (candidatePaths.length === 0) return undefined;
-  const normalizedCandidateOperations = [...new Set(candidatePaths.map((candidate) => classifyODataPathIntent(candidate, method).topLevelOperationName).filter((value): value is string => Boolean(value)))];
-  return { candidatePaths, normalizedCandidateOperations, candidateSourceKind: 'static candidates observed before call in lexical scope', candidateIdentifier: identifier.text, hasDynamicAssignments, conservativeReason: hasDynamicAssignments ? 'dynamic_assignment_observed' : normalizedCandidateOperations.length > 1 ? 'candidate_tie' : undefined };
-}
 function destinationExpressionShape(expr: ts.Expression | undefined): string | undefined {
   if (!expr) return undefined;
   if (ts.isIdentifier(expr)) return 'identifier';
@@ -252,6 +223,33 @@ function safeOperationName(value: string | undefined): string | undefined {
   if (!value || !/^[A-Za-z_$][\w$]*(?:[./][A-Za-z_$][\w$]*)*$/.test(value)) return undefined;
   return operationPathFromStatic(value);
 }
+function wrapperSourceKind(sourceKind: string): string {
+  if (sourceKind.includes('const_alias')) return 'const';
+  if (sourceKind.includes('template')) return 'template';
+  if (sourceKind.includes('string_literal')) return 'literal';
+  return sourceKind.includes('conditional') ? 'ambiguous' : 'dynamic';
+}
+function literalPathSource(analysis: OperationPathAnalysis): string | undefined {
+  if (analysis.status !== 'static') return undefined;
+  if (analysis.sourceKind.includes('const_alias')) return 'same_scope_const_initializer';
+  if (analysis.sourceKind.includes('no_substitution_template')) return 'template';
+  return analysis.sourceKind.includes('string_literal') ? 'literal' : analysis.sourceKind;
+}
+function legacyPathCandidates(analysis: OperationPathAnalysis): Record<string, unknown> | undefined {
+  if (analysis.candidateRawPaths.length < 2 && analysis.dynamicReassignments.length === 0)
+    return undefined;
+  return {
+    candidatePaths: analysis.candidateRawPaths,
+    normalizedCandidateOperations: analysis.candidateNormalizedOperationPaths
+      .map((value) => value.replace(/^\//, '')),
+    candidateSourceKind: analysis.sourceKind,
+    candidateIdentifier: analysis.candidateIdentifier,
+    hasDynamicAssignments: analysis.dynamicReassignments.length > 0,
+    conservativeReason: analysis.dynamicReassignments.length > 0
+      ? 'dynamic_assignment_observed'
+      : 'candidate_tie',
+  };
+}
 function hasTemplatePlaceholder(value: string): boolean { return /\$\{|%7B|%7D/i.test(value); }
 function urlTargetFromExpression(expr: ts.Expression | undefined, use: ts.Node): Record<string, unknown> {
   const resolved = resolveExpression(expr, use, 'external');
@@ -346,15 +344,16 @@ function collectWrapperSpecs(source: ts.SourceFile): Map<string, WrapperSpec> {
   const serviceVariables = collectServiceVariables(source);
   const calledNames = new Set<string>();
   const collectCalls = (node: ts.Node): void => {
-    if (ts.isCallExpression(node)) {
-      if (ts.isIdentifier(node.expression)) calledNames.add(node.expression.text);
-      if (ts.isCallExpression(node.expression) && ts.isIdentifier(node.expression.expression)) calledNames.add(node.expression.expression.text);
-    }
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression))
+      calledNames.add(node.expression.text);
+    if (ts.isCallExpression(node) && ts.isCallExpression(node.expression)
+      && ts.isIdentifier(node.expression.expression))
+      calledNames.add(node.expression.expression.text);
     ts.forEachChild(node, collectCalls);
   };
   collectCalls(source);
   const scanFunction = (name: string, fn: ts.FunctionLikeDeclaration): void => {
-    if (!calledNames.has(name)) return;
+    if (!calledNames.has(name) && !isExportedWrapper(fn)) return;
     const params = fn.parameters.map((param) => ts.isIdentifier(param.name) ? param.name.text : undefined);
     const sends: Array<{ client: string; path: string; method?: string; methodLiteral?: string; nestedWrapperFunction?: string; start: number; end: number }> = [];
     const visit = (node: ts.Node): void => {
@@ -396,6 +395,16 @@ function collectWrapperSpecs(source: ts.SourceFile): Map<string, WrapperSpec> {
   visitTop(source);
   return specs;
 }
+function isExportedWrapper(fn: ts.FunctionLikeDeclaration): boolean {
+  const declaration = ts.isFunctionDeclaration(fn)
+    ? fn
+    : ts.isVariableDeclaration(fn.parent)
+      ? fn.parent.parent.parent
+      : undefined;
+  if (!declaration || !ts.canHaveModifiers(declaration)) return false;
+  return ts.getModifiers(declaration)?.some((modifier) =>
+    modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
 export function classifyOutboundCallsInSource(source: ts.SourceFile, filePath: string): ClassifiedOutboundCall[] {
   const calls: ClassifiedOutboundCall[] = [];
   const sourceFile = normalizePath(filePath);
@@ -425,17 +434,16 @@ export function classifyOutboundCallsInSource(source: ts.SourceFile, filePath: s
           const query = objectPropertyText(objectArg, 'query');
           const method = stripQuotes(resolveExpression(propertyInitializer(objectArg, 'method'), node, 'literal').value ?? objectPropertyText(objectArg, 'method') ?? 'POST');
           const pathExpr = propertyInitializer(objectArg, 'path') ?? propertyInitializer(objectArg, 'event');
-          const resolvedPath = staticPathExpression(pathExpr, node);
-          const op = pathExpr ? resolvedPath.text ?? pathExpr.getText(source) : undefined;
+          const pathAnalysis = analyzeOperationPath(pathExpr, node, method);
+          const op = pathExpr ? operationPathExpression(pathAnalysis) ?? pathExpr.getText(source) : undefined;
           const shorthandPath = objectPropertyIsShorthand(objectArg, 'path');
-          const candidateEvidence = pathExpr && ts.isIdentifier(pathExpr) && !resolvedPath.text ? staticPathCandidates(pathExpr, node, method) : undefined;
-          const candidateOperationPath = candidateEvidence && !candidateEvidence.hasDynamicAssignments && candidateEvidence.normalizedCandidateOperations.length === 1 && candidateEvidence.candidatePaths.length > 0 ? candidateEvidence.candidatePaths[0] : undefined;
-          const operationPathExpr = operationPathFromStatic(resolvedPath.text) ?? candidateOperationPath;
+          const operationPathExpr = operationPathExpression(pathAnalysis);
           const intent = classifyODataPathIntent(operationPathExpr, method);
           const entityCallTypes: Record<string, OutboundCallFact['callType']> = { entity_mutation: 'remote_entity_mutation', entity_delete: 'remote_entity_delete', entity_media: 'remote_entity_media', entity_candidate: 'remote_entity_candidate' };
           const entityCallType = entityCallTypes[intent.kind];
           const isODataQueryRead = method.toUpperCase() === 'GET' && ['entity_query', 'entity_key_read', 'entity_navigation_query'].includes(intent.kind);
-          add(node, { callType: query ? 'remote_query' : entityCallType ?? (isODataQueryRead ? 'remote_query' : 'remote_action'), serviceVariableName: receiver, method, operationPathExpr, queryEntity: query ? extractQueryEntity(query) : isODataQueryRead ? intent.entitySegment : undefined, payloadSummary: summarizeExpression(objectArg.getText(source)), confidence: op || query ? 0.8 : 0.4, unresolvedReason: !query && pathExpr && !operationPathExpr ? 'dynamic_operation_path_identifier' : undefined }, { receiver, classifier: 'service_client_send_object', operationPathExpression: shorthandPath ? op : undefined, rawPathExpression: resolvedPath.rawExpression, literalPathSource: resolvedPath.text ? (resolvedPath.sourceKind === 'const' ? 'same_scope_const_initializer' : resolvedPath.sourceKind) : undefined, odataPathIntent: operationPathExpr ? intent : undefined, staticPathCandidates: candidateEvidence, parserWarning: !query && pathExpr && !operationPathExpr ? 'dynamic_operation_path_identifier' : undefined });
+          const unresolvedReason = !query && pathExpr ? pathUnresolvedReason(pathAnalysis) : undefined;
+          add(node, { callType: query ? 'remote_query' : entityCallType ?? (isODataQueryRead ? 'remote_query' : 'remote_action'), serviceVariableName: receiver, method, operationPathExpr, queryEntity: query ? extractQueryEntity(query) : isODataQueryRead ? intent.entitySegment : undefined, payloadSummary: summarizeExpression(objectArg.getText(source)), confidence: op || query ? 0.8 : 0.4, unresolvedReason }, { receiver, classifier: 'service_client_send_object', operationPathExpression: shorthandPath ? op : undefined, rawPathExpression: pathAnalysis.rawExpression, literalPathSource: literalPathSource(pathAnalysis), odataPathIntent: operationPathExpr ? intent : undefined, pathAnalysis, staticPathCandidates: legacyPathCandidates(pathAnalysis), parserWarning: unresolvedReason });
         } else {
           const receiver = receiverName(expr.expression);
           const rootReceiver = rootReceiverName(expr.expression);
@@ -444,10 +452,11 @@ export function classifyOutboundCallsInSource(source: ts.SourceFile, filePath: s
           const pathArg = node.arguments[1];
           const supported = method && supportedHttpMethods.has(method);
           if (receiver && supported && serviceVariables.has(rootReceiver ?? receiver)) {
-            const resolvedPath = staticPathExpression(pathArg, node);
-            const operationPathExpr = operationPathFromStatic(resolvedPath.text);
+            const pathAnalysis = analyzeOperationPath(pathArg, node, method);
+            const operationPathExpr = operationPathExpression(pathAnalysis);
             const intent = classifyODataPathIntent(operationPathExpr, method);
-            add(node, { callType: 'remote_action', serviceVariableName: rootReceiver ?? receiver, method, operationPathExpr, payloadSummary: summarizeExpression(node.getText(source)), confidence: operationPathExpr ? 0.8 : 0.45, unresolvedReason: operationPathExpr ? undefined : 'dynamic_operation_path_identifier' }, { receiver, rootReceiver, classifier: 'service_client_send_method_path', rawPathExpression: resolvedPath.rawExpression, literalPathSource: resolvedPath.text ? (resolvedPath.sourceKind === 'const' ? 'same_scope_const_initializer' : resolvedPath.sourceKind) : undefined, odataPathIntent: operationPathExpr ? intent : undefined, parserWarning: operationPathExpr ? undefined : 'dynamic_operation_path_identifier' });
+            const unresolvedReason = pathUnresolvedReason(pathAnalysis);
+            add(node, { callType: 'remote_action', serviceVariableName: rootReceiver ?? receiver, method, operationPathExpr, payloadSummary: summarizeExpression(node.getText(source)), confidence: operationPathExpr ? 0.8 : 0.45, unresolvedReason }, { receiver, rootReceiver, classifier: 'service_client_send_method_path', rawPathExpression: pathAnalysis.rawExpression, literalPathSource: literalPathSource(pathAnalysis), odataPathIntent: operationPathExpr ? intent : undefined, pathAnalysis, staticPathCandidates: legacyPathCandidates(pathAnalysis), parserWarning: unresolvedReason });
           } else if (receiver && serviceVariables.has(rootReceiver ?? receiver)) {
             const operationPathExpr = safeOperationName(firstArg.value);
             add(node, { callType: 'remote_action', serviceVariableName: rootReceiver ?? receiver, operationPathExpr, payloadSummary: summarizeExpression(node.getText(source)), confidence: operationPathExpr ? 0.75 : 0.35, unresolvedReason: operationPathExpr ? undefined : 'unsupported_cap_send_signature' }, { receiver, rootReceiver, classifier: operationPathExpr ? 'service_client_send_operation_event' : 'service_client_send_unsupported_signature', rawOperationExpression: firstArg.rawExpression, literalOperationSource: firstArg.value ? firstArg.sourceKind : undefined, parserWarning: operationPathExpr ? undefined : 'unsupported_cap_send_signature' });
@@ -462,13 +471,14 @@ export function classifyOutboundCallsInSource(source: ts.SourceFile, filePath: s
         const methodArg = spec?.methodIndex === undefined ? undefined : wrapperArgs[spec.methodIndex];
         const receiver = clientArg && ts.isIdentifier(clientArg) ? clientArg.text : spec?.clientName;
         const method = stripQuotes(resolveExpression(methodArg, node, 'literal').value ?? spec?.methodLiteral ?? 'POST');
-        const resolvedPath = staticPathExpression(pathArg, node);
-        const operationPathExpr = operationPathFromStatic(resolvedPath.text);
+        const pathAnalysis = analyzeOperationPath(pathArg, node, method);
+        const operationPathExpr = operationPathExpression(pathAnalysis);
         const normalizedOperationPath = operationPathExpr ? classifyODataPathIntent(operationPathExpr, method).topLevelOperationName : undefined;
+        const unresolvedReason = pathUnresolvedReason(pathAnalysis);
         if (spec && receiver && operationPathExpr) {
-          add(node, { callType: 'remote_action', serviceVariableName: receiver, method, operationPathExpr, payloadSummary: summarizeExpression(node.getText(source)), confidence: 0.75 }, { receiver, classifier: resolvedPath.sourceKind === 'literal' ? 'higher_order_wrapper_literal_path' : 'higher_order_wrapper_static_path', wrapperFunction: wrapperName, nestedWrapperFunction: spec.nestedWrapperFunction, wrapperDefinitionLine: spec.definitionLine, callerLine: lineOf(source.text, node.getStart(source)), wrapperPathSourceKind: resolvedPath.sourceKind, rawPathExpression: resolvedPath.rawExpression, normalizedOperationPath, literalPathSource: resolvedPath.sourceKind === 'const' ? 'same_scope_const_initializer' : `wrapper_call_${resolvedPath.sourceKind}`, literalCallerArgumentDetected: true });
+          add(node, { callType: 'remote_action', serviceVariableName: receiver, method, operationPathExpr, payloadSummary: summarizeExpression(node.getText(source)), confidence: 0.75, unresolvedReason }, { receiver, classifier: pathAnalysis.sourceKind.includes('string_literal') ? 'higher_order_wrapper_literal_path' : 'higher_order_wrapper_static_path', wrapperFunction: wrapperName, nestedWrapperFunction: spec.nestedWrapperFunction, wrapperDefinitionLine: spec.definitionLine, callerLine: lineOf(source.text, node.getStart(source)), wrapperPathSourceKind: wrapperSourceKind(pathAnalysis.sourceKind), rawPathExpression: pathAnalysis.rawExpression, normalizedOperationPath, literalPathSource: pathAnalysis.sourceKind.includes('const_alias') ? 'same_scope_const_initializer' : `wrapper_call_${wrapperSourceKind(pathAnalysis.sourceKind)}`, literalCallerArgumentDetected: true, pathAnalysis });
         } else if (spec && receiver) {
-          add(node, { callType: 'remote_action', serviceVariableName: receiver, method, payloadSummary: summarizeExpression(node.getText(source)), confidence: 0.45, unresolvedReason: 'dynamic_operation_path_identifier' }, { receiver, classifier: 'higher_order_wrapper_dynamic_path', wrapperFunction: wrapperName, wrapperDefinitionLine: spec.definitionLine, callerLine: lineOf(source.text, node.getStart(source)), wrapperPathSourceKind: resolvedPath.sourceKind, rawPathExpression: resolvedPath.rawExpression, parserWarning: 'dynamic_operation_path_identifier' });
+          add(node, { callType: 'remote_action', serviceVariableName: receiver, method, payloadSummary: summarizeExpression(node.getText(source)), confidence: 0.45, unresolvedReason }, { receiver, classifier: pathAnalysis.status === 'ambiguous' ? 'higher_order_wrapper_ambiguous_path' : 'higher_order_wrapper_dynamic_path', wrapperFunction: wrapperName, wrapperDefinitionLine: spec.definitionLine, callerLine: lineOf(source.text, node.getStart(source)), wrapperPathSourceKind: wrapperSourceKind(pathAnalysis.sourceKind), rawPathExpression: pathAnalysis.rawExpression, pathAnalysis, parserWarning: unresolvedReason });
         }
       } else if (ts.isPropertyAccessExpression(expr) && ['emit', 'publish', 'on'].includes(expr.name.text)) {
         const receiver = receiverName(expr.expression);

package/src/trace/evidence.ts

@@ -52,11 +52,13 @@ export function runtimeResolution(
   evidence: Record<string, unknown>,
   vars: Record<string, string> | undefined,
   workspaceId: number | undefined,
+  contextualUnresolvedReason?: string,
 ): { row: TraceGraphRow; evidence: Record<string, unknown>; target?: OperationTarget; unresolvedReason?: string } {
   const substituted = evidenceWithRuntimeVariables(evidence, vars);
   if (!isRemoteRuntimeCandidate(row, evidence, vars)) {
-    const withSections = withEffectiveResolution(substituted, row, row.unresolved_reason);
-    return { row, evidence: withSections, unresolvedReason: row.unresolved_reason };
+    const unresolvedReason = contextualUnresolvedReason ?? row.unresolved_reason;
+    const withSections = withEffectiveResolution(substituted, row, unresolvedReason);
+    return { row, evidence: withSections, unresolvedReason };
   }
   const resolution = resolveRuntimeOperation(db, substituted, workspaceId);
   if (resolution.target) {
@@ -70,6 +72,9 @@ export function runtimeResolution(
 export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string, unknown> }>): Record<string, unknown> | undefined {
   const missing = new Set<string>();
   for (const edge of edges) {
+    const effective = parseObject(edge.evidence.effectiveResolution);
+    if (!['dynamic', 'unresolved', 'ambiguous'].includes(String(effective.status ?? '')))
+      continue;
     const substitutions = edge.evidence.runtimeSubstitutions;
     if (!substitutions || typeof substitutions !== 'object' || Array.isArray(substitutions)) continue;
     for (const value of Object.values(substitutions as Record<string, RuntimeSubstitution>))
@@ -178,12 +183,22 @@ function evidenceWithRuntimeVariables(evidence: Record<string, unknown>, vars: R
 function runtimeSubstitutions(evidence: Record<string, unknown>, vars: Record<string, string>): Record<string, RuntimeSubstitution> {
   const substitutions: Record<string, RuntimeSubstitution> = {};
   for (const key of ['servicePath', 'operationPath', 'serviceAliasExpr', 'serviceAlias', 'destination']) {
-    const substitution = substituteVariables(stringValue(evidence[key]), vars);
+    const substitution = substituteVariables(substitutionValue(evidence, key), vars);
     if (substitution.placeholders.length > 0) substitutions[key] = substitution;
   }
   return substitutions;
 }
 
+function substitutionValue(
+  evidence: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = stringValue(evidence[key]);
+  if (key !== 'operationPath') return value;
+  const normalized = normalizeODataOperationInvocationPath(value);
+  return normalized?.wasInvocation ? normalized.normalizedOperationPath : value;
+}
+
 function isRemoteRuntimeCandidate(row: TraceGraphRow, evidence: Record<string, unknown>, vars: Record<string, string> | undefined): boolean {
   if (!vars || Object.keys(vars).length === 0) return false;
   if (!['dynamic', 'ambiguous', 'unresolved'].includes(String(row.status ?? ''))) return false;

package/src/trace/selectors.ts

@@ -18,3 +18,39 @@ export function startLabel(start: TraceStart): string {
     .filter(Boolean)
     .join(' ');
 }
+export function ambiguousStartDiagnostic(
+  requested: string,
+  candidates: Array<Record<string, unknown>>,
+  message: string,
+): Record<string, unknown> {
+  const serviceSuggestions = [...new Set(candidates
+    .flatMap((row) => typeof row.servicePath === 'string'
+      ? [`--service ${row.servicePath}`]
+      : []))].sort();
+  return {
+    severity: 'warning',
+    code: 'trace_start_ambiguous',
+    message,
+    normalizedSelectorValue: requested,
+    resolutionStage: 'operation',
+    resolutionStatus: 'ambiguous_operation',
+    candidates,
+    serviceSuggestions,
+    selectorSuggestions: fullSelectorSuggestions(candidates),
+  };
+}
+function fullSelectorSuggestions(
+  candidates: Array<Record<string, unknown>>,
+): string[] {
+  const includeRepo = new Set(candidates.map((row) => row.repoName)).size > 1;
+  return [...new Set(candidates.flatMap((row) => {
+    if (typeof row.servicePath !== 'string'
+      || typeof row.operationPath !== 'string') return [];
+    const repoSelector = includeRepo && typeof row.repoName === 'string'
+      ? `--repo ${row.repoName} `
+      : '';
+    return [
+      `${repoSelector}--service ${row.servicePath} --path ${row.operationPath}`,
+    ];
+  }))].sort();
+}