@saptools/service-flow 0.1.48 → 0.1.49

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   stripQuotes,
   substituteVariables,
   trace
-} from "./chunk-EGY2A4AT.js";
+} from "./chunk-XOROZHW4.js";
 
 // src/parsers/generated-constants-parser.ts
 import fs from "fs/promises";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saptools/service-flow",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   "type": "module",
   "publishConfig": {

package/src/cli/doctor.ts

@@ -149,6 +149,7 @@ function parserQualityDiagnostics(db: Db, strict: boolean, options: DoctorOption
     implementationCandidateQuality(db, Boolean(options.detail)),
     classInstanceNoiseQuality(db),
     contextualBindingPropagationQuality(db),
+    serviceBindingQuality(db, Boolean(options.detail)),
     nestedThisReceiverQuality(db),
     wrapperPathPropagationQuality(db),
     remoteQueryTargetQuality(db),
@@ -369,6 +370,88 @@ function contextualBindingPropagationQuality(db: Db): Diagnostic {
   return { severity: missing.count + opportunities.length > 0 ? 'warning' : 'info', code: 'strict_contextual_binding_propagation_quality', message: 'Contextual service-client propagation opportunities for trace-time helper resolution', calleeSymbolsMissingParameterMetadata: missing.count, traceTimeContextualOpportunities: opportunities.length, examples: opportunities };
 }
 
+function serviceBindingQuality(db: Db, detail: boolean): Diagnostic {
+  const rows = db.prepare(`
+    SELECT c.source_file sourceFile,c.source_line sourceLine,
+      c.unresolved_reason unresolvedReason,c.evidence_json evidenceJson,
+      s.evidence_json symbolEvidenceJson
+    FROM outbound_calls c
+    LEFT JOIN symbols s ON s.id=c.source_symbol_id
+    WHERE c.call_type='remote_action'
+      AND c.operation_path_expr IS NOT NULL
+      AND c.service_binding_id IS NULL
+    ORDER BY c.source_file,c.source_line
+  `).all() as Diagnostic[];
+  const groups = new Map<string, Diagnostic[]>();
+  for (const row of rows) {
+    const category = bindingCategory(row);
+    groups.set(category, [...(groups.get(category) ?? []), bindingExample(row)]);
+  }
+  const categories = [...groups.entries()].map(([category, examples]) => ({
+    category,
+    count: examples.length,
+    severity: 'warning',
+    suggestedAction: bindingCategoryAction(category),
+    examples: examples.slice(0, 3),
+    expandedExamples: detail ? examples : undefined,
+  }));
+  return {
+    severity: rows.length > 0 ? 'warning' : 'info',
+    code: 'strict_service_binding_quality',
+    message: 'Remote service-client binding quality aggregate',
+    total: rows.length,
+    categories,
+  };
+}
+
+function bindingCategory(row: Diagnostic): string {
+  const evidence = parseObject(row.evidenceJson);
+  const resolution = parseObject(evidence.serviceBindingResolution);
+  if (resolution.status === 'rejected_future_binding') return 'direct_binding_missing';
+  if (resolution.status === 'ambiguous') return 'ambiguous_binding_candidates';
+  const receiver = evidence.receiver;
+  const symbolEvidence = parseObject(row.symbolEvidenceJson);
+  if (symbolHasReceiverParameter(symbolEvidence, receiver))
+    return 'contextual_binding_recoverable';
+  if (!Array.isArray(symbolEvidence.parameterBindings))
+    return 'missing_symbol_parameter_metadata';
+  return 'unrecoverable_binding';
+}
+
+function symbolHasReceiverParameter(evidence: Diagnostic, receiver: unknown): boolean {
+  if (typeof receiver !== 'string' || !Array.isArray(evidence.parameterBindings))
+    return false;
+  return asRecords(evidence.parameterBindings).some((binding) => {
+    if (binding.kind === 'identifier') return binding.name === receiver;
+    if (binding.kind === 'object_pattern')
+      return asRecords(binding.properties).some((property) => property.local === receiver);
+    return asRecords(binding.elements).some((element) => element.local === receiver);
+  });
+}
+
+function bindingExample(row: Diagnostic): Diagnostic {
+  const evidence = parseObject(row.evidenceJson);
+  return {
+    sourceFile: row.sourceFile,
+    sourceLine: row.sourceLine,
+    receiver: evidence.receiver,
+    unresolvedReason: row.unresolvedReason,
+    bindingResolution: evidence.serviceBindingResolution,
+  };
+}
+
+function bindingCategoryAction(category: string): string {
+  if (category === 'direct_binding_missing')
+    return 'Move the binding before the call or bind the call to an earlier immutable client.';
+  if (category === 'contextual_binding_recoverable')
+    return 'Trace from the caller so parameter binding evidence can be applied.';
+  if (category === 'ambiguous_binding_candidates')
+    return 'Split mutable client alternatives or add a statically unique client assignment.';
+  if (category === 'missing_symbol_parameter_metadata')
+    return 'Use named or destructured parameters on an indexed helper symbol.';
+  return 'Add a direct CAP client binding or statically provable helper-return binding.';
+}
+
 function wrapperPathPropagationQuality(db: Db): Diagnostic {
   const examples = db.prepare("SELECT source_file sourceFile,source_line sourceLine,json_extract(evidence_json,'$.receiver') receiverName,json_extract(evidence_json,'$.operationPathExpression') pathIdentifier FROM outbound_calls WHERE call_type='remote_action' AND unresolved_reason='dynamic_operation_path_identifier' ORDER BY source_file,source_line LIMIT 5").all() as Diagnostic[];
   return { severity: examples.length > 0 ? 'warning' : 'info', code: 'strict_wrapper_path_propagation_quality', message: 'Dynamic path sends where send({ path }) used a path identifier', dynamicPathIdentifierCalls: examples.length, examples };
@@ -450,10 +533,53 @@ function externalHttpTargetQuality(db: Db): Diagnostic {
 }
 
 function odataInvocationResolutionQuality(db: Db): Diagnostic {
-  const rows = db.prepare("SELECT c.operation_path_expr operationPathExpr,e.status status FROM outbound_calls c JOIN graph_edges e ON e.from_kind='call' AND e.from_id=CAST(c.id AS TEXT) WHERE c.call_type='remote_action' AND c.operation_path_expr LIKE '%(%'").all() as Array<{ operationPathExpr?: string; status?: string }>;
+  const rows = db.prepare(`SELECT c.operation_path_expr operationPathExpr,
+    c.source_file sourceFile,c.source_line sourceLine,e.id graphEdgeId,
+    e.status status,e.evidence_json evidenceJson
+    FROM outbound_calls c JOIN graph_edges e
+      ON e.from_kind='call' AND e.from_id=CAST(c.id AS TEXT)
+    WHERE c.call_type='remote_action' AND c.operation_path_expr LIKE '%(%'
+    ORDER BY c.source_file,c.source_line`).all() as Array<{
+      operationPathExpr?: string;
+      sourceFile?: string;
+      sourceLine?: number;
+      graphEdgeId?: number;
+      status?: string;
+      evidenceJson?: string;
+    }>;
   const unresolved = rows.filter((row) => row.status === 'unresolved' && normalizeODataOperationInvocationPath(row.operationPathExpr)?.wasInvocation).length;
   const ambiguous = rows.filter((row) => row.status === 'ambiguous' && normalizeODataOperationInvocationPath(row.operationPathExpr)?.wasInvocation).length;
-  return { severity: unresolved + ambiguous > 0 ? 'warning' : 'info', code: 'strict_odata_invocation_resolution_quality', message: 'OData invocation-path resolution quality aggregate', totalInvocationRemoteActions: rows.length, resolvedInvocationCalls: rows.filter((row) => row.status === 'resolved').length, dynamicInvocationCalls: rows.filter((row) => row.status === 'dynamic').length, ambiguousInvocationCalls: rows.filter((row) => row.status === 'ambiguous').length, unresolvedInvocationCalls: rows.filter((row) => row.status === 'unresolved').length, ambiguousNormalizedCalls: ambiguous, unresolvedNormalizedCallsWithIndexedCandidates: unresolved };
+  const examples = rows
+    .filter((row) => row.status === 'ambiguous' || row.status === 'unresolved')
+    .map(odataInvocationExample)
+    .slice(0, 5);
+  return { severity: unresolved + ambiguous > 0 ? 'warning' : 'info', code: 'strict_odata_invocation_resolution_quality', message: 'OData invocation-path resolution quality aggregate', totalInvocationRemoteActions: rows.length, resolvedInvocationCalls: rows.filter((row) => row.status === 'resolved').length, dynamicInvocationCalls: rows.filter((row) => row.status === 'dynamic').length, ambiguousInvocationCalls: rows.filter((row) => row.status === 'ambiguous').length, unresolvedInvocationCalls: rows.filter((row) => row.status === 'unresolved').length, ambiguousNormalizedCalls: ambiguous, unresolvedNormalizedCallsWithIndexedCandidates: unresolved, examples };
+}
+
+function odataInvocationExample(row: {
+  operationPathExpr?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+  graphEdgeId?: number;
+  status?: string;
+  evidenceJson?: string;
+}): Diagnostic {
+  const evidence = parseObject(row.evidenceJson);
+  const normalized = normalizeODataOperationInvocationPath(row.operationPathExpr);
+  return {
+    sourceFile: row.sourceFile,
+    sourceLine: row.sourceLine,
+    graphEdgeId: row.graphEdgeId,
+    status: row.status,
+    rawPath: row.operationPathExpr,
+    normalizedOperationPath: normalized?.wasInvocation
+      ? normalized.normalizedOperationPath
+      : undefined,
+    indexedOperationCandidateCount: evidence.indexedOperationCandidateCount,
+    candidateScores: evidence.candidateScores,
+    entityOperationPrecedence: evidence.entityOperationPrecedence,
+    resolutionReasons: evidence.resolutionReasons,
+  };
 }
 
 function identityAliasBindingQuality(db: Db): Diagnostic {

package/src/db/repositories.ts

@@ -259,11 +259,15 @@ export function insertBindings(
   rows: ServiceBindingFact[],
 ): void {
   const stmt = db.prepare(
-    'INSERT INTO service_bindings(repo_id,variable_name,alias,alias_expr,destination_expr,service_path_expr,is_dynamic,placeholders_json,source_file,source_line,helper_chain_json) VALUES(?,?,?,?,?,?,?,?,?,?,?)',
+    'INSERT INTO service_bindings(repo_id,symbol_id,variable_name,alias,alias_expr,destination_expr,service_path_expr,is_dynamic,placeholders_json,source_file,source_line,helper_chain_json) VALUES(?,(SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND start_line<=? AND end_line>=? ORDER BY (end_line-start_line),id LIMIT 1),?,?,?,?,?,?,?,?,?,?)',
   );
   for (const r of rows)
     stmt.run(
       repoId,
+      repoId,
+      r.sourceFile,
+      r.sourceLine,
+      r.sourceLine,
       r.variableName,
       r.alias,
       r.aliasExpr,
@@ -321,9 +325,14 @@ export function insertCalls(
   rows: OutboundCallFact[],
 ): void {
   const stmt = db.prepare(
-    'INSERT INTO outbound_calls(repo_id,source_symbol_id,call_type,method,operation_path_expr,query_entity,event_name_expr,payload_summary,source_file,source_line,confidence,unresolved_reason,local_service_name,local_service_lookup,alias_chain_json,evidence_json,external_target_kind,external_target_id,external_target_label,external_target_dynamic,service_binding_id) VALUES(?,COALESCE((SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND qualified_name=? ORDER BY id LIMIT 1),(SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND start_line<=? AND end_line>=? ORDER BY (end_line-start_line),id LIMIT 1)),?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,(SELECT id FROM service_bindings WHERE repo_id=? AND variable_name=? AND source_file=? ORDER BY CASE WHEN source_line<=? THEN 0 ELSE 1 END, ABS(source_line-?) ASC, id DESC LIMIT 1))',
+    'INSERT INTO outbound_calls(repo_id,source_symbol_id,call_type,method,operation_path_expr,query_entity,event_name_expr,payload_summary,source_file,source_line,confidence,unresolved_reason,local_service_name,local_service_lookup,alias_chain_json,evidence_json,external_target_kind,external_target_id,external_target_label,external_target_dynamic,service_binding_id) VALUES(?,COALESCE((SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND qualified_name=? ORDER BY id LIMIT 1),(SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND start_line<=? AND end_line>=? ORDER BY (end_line-start_line),id LIMIT 1)),?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)',
   );
-  for (const r of rows)
+  for (const r of rows) {
+    const binding = resolvePersistedBinding(db, repoId, r);
+    const evidence = {
+      ...(r.evidence ?? {}),
+      serviceBindingResolution: binding.evidence,
+    };
     stmt.run(
       repoId,
       repoId,
@@ -342,19 +351,186 @@ export function insertCalls(
       r.sourceFile,
       r.sourceLine,
       r.confidence,
-      r.unresolvedReason,
+      r.unresolvedReason ?? binding.unresolvedReason,
       r.localServiceName,
       r.localServiceLookup,
       r.aliasChain ? JSON.stringify(r.aliasChain) : null,
-      r.evidence ? JSON.stringify(r.evidence) : null,
+      JSON.stringify(evidence),
       r.externalTarget?.kind ?? null,
       r.externalTarget?.stableId ?? null,
       r.externalTarget?.label ?? null,
       r.externalTarget?.dynamic ? 1 : 0,
-      repoId,
-      r.serviceVariableName,
-      r.sourceFile,
-      r.sourceLine,
-      r.sourceLine,
+      binding.bindingId,
     );
+  }
+}
+
+interface BindingCandidate {
+  id: number;
+  symbolId?: number | null;
+  variableName: string;
+  alias?: string | null;
+  aliasExpr?: string | null;
+  destinationExpr?: string | null;
+  servicePathExpr?: string | null;
+  sourceFile: string;
+  sourceLine: number;
+  helperChainJson?: string | null;
+}
+
+function resolvePersistedBinding(
+  db: Db,
+  repoId: number,
+  call: OutboundCallFact,
+): {
+  bindingId: number | null;
+  unresolvedReason?: string;
+  evidence: Record<string, unknown>;
+} {
+  if (!call.serviceVariableName)
+    return { bindingId: null, evidence: { status: 'not_applicable', candidateCount: 0 } };
+  const candidates = bindingCandidates(db, repoId, call);
+  const prior = candidates.filter((candidate) => candidate.sourceLine <= call.sourceLine);
+  const families = new Set(prior.map(bindingSignature));
+  if (prior.length > 0 && families.size === 1) {
+    const selected = prior.at(-1);
+    return {
+      bindingId: selected?.id ?? null,
+      evidence: bindingEvidence('selected', prior, selected),
+    };
+  }
+  if (prior.length > 1) {
+    return {
+      bindingId: null,
+      unresolvedReason: 'ambiguous_service_binding_candidates',
+      evidence: bindingEvidence('ambiguous', prior),
+    };
+  }
+  if (candidates.length > 0) {
+    return {
+      bindingId: null,
+      unresolvedReason: 'service_binding_declared_after_call',
+      evidence: bindingEvidence('rejected_future_binding', candidates),
+    };
+  }
+  return {
+    bindingId: null,
+    evidence: bindingEvidence('unrecoverable', []),
+  };
+}
+
+function bindingCandidates(
+  db: Db,
+  repoId: number,
+  call: OutboundCallFact,
+): BindingCandidate[] {
+  const ownerId = callSymbolId(db, repoId, call);
+  const rows = db.prepare(`
+    SELECT id,symbol_id symbolId,variable_name variableName,alias,alias_expr aliasExpr,
+      destination_expr destinationExpr,service_path_expr servicePathExpr,
+      source_file sourceFile,source_line sourceLine,helper_chain_json helperChainJson
+    FROM service_bindings
+    WHERE repo_id=? AND variable_name=? AND source_file=?
+      AND (? IS NULL OR symbol_id IS NULL OR symbol_id=?)
+    ORDER BY source_line,id
+  `).all(
+    repoId,
+    call.serviceVariableName,
+    call.sourceFile,
+    ownerId,
+    ownerId,
+  ) as Array<Record<string, unknown>>;
+  return rows.flatMap((row) => {
+    if (typeof row.id !== 'number' || typeof row.variableName !== 'string'
+      || typeof row.sourceFile !== 'string' || typeof row.sourceLine !== 'number')
+      return [];
+    return [{
+      id: row.id,
+      symbolId: nullableNumber(row.symbolId),
+      variableName: row.variableName,
+      alias: nullableString(row.alias),
+      aliasExpr: nullableString(row.aliasExpr),
+      destinationExpr: nullableString(row.destinationExpr),
+      servicePathExpr: nullableString(row.servicePathExpr),
+      sourceFile: row.sourceFile,
+      sourceLine: row.sourceLine,
+      helperChainJson: nullableString(row.helperChainJson),
+    }];
+  });
+}
+
+function nullableString(value: unknown): string | null | undefined {
+  return value === null || typeof value === 'string' ? value : undefined;
+}
+
+function nullableNumber(value: unknown): number | null | undefined {
+  return value === null || typeof value === 'number' ? value : undefined;
+}
+
+function callSymbolId(
+  db: Db,
+  repoId: number,
+  call: OutboundCallFact,
+): number | undefined {
+  const row = db.prepare(`
+    SELECT id FROM symbols
+    WHERE repo_id=? AND source_file=?
+      AND ((? IS NOT NULL AND qualified_name=?)
+        OR (start_line<=? AND end_line>=?))
+    ORDER BY CASE WHEN qualified_name=? THEN 0 ELSE 1 END,
+      (end_line-start_line),id
+    LIMIT 1
+  `).get(
+    repoId,
+    call.sourceFile,
+    call.sourceSymbolQualifiedName,
+    call.sourceSymbolQualifiedName,
+    call.sourceLine,
+    call.sourceLine,
+    call.sourceSymbolQualifiedName,
+  );
+  return typeof row?.id === 'number' ? row.id : undefined;
+}
+
+function bindingEvidence(
+  status: string,
+  candidates: BindingCandidate[],
+  selected?: BindingCandidate,
+): Record<string, unknown> {
+  return {
+    status,
+    candidateCount: candidates.length,
+    selectedBindingId: selected?.id,
+    sourceOrderRule: 'binding_source_line_must_not_follow_call',
+    candidates: candidates.map((candidate) => ({
+      bindingId: candidate.id,
+      symbolId: candidate.symbolId,
+      variableName: candidate.variableName,
+      alias: candidate.alias,
+      aliasExpr: candidate.aliasExpr,
+      destinationExpr: candidate.destinationExpr,
+      servicePathExpr: candidate.servicePathExpr,
+      sourceFile: candidate.sourceFile,
+      sourceLine: candidate.sourceLine,
+      helperChain: parseBindingChain(candidate.helperChainJson),
+    })),
+  };
+}
+
+function bindingSignature(candidate: BindingCandidate): string {
+  return JSON.stringify([
+    candidate.alias,
+    candidate.aliasExpr,
+    candidate.destinationExpr,
+    candidate.servicePathExpr,
+  ]);
+}
+
+function parseBindingChain(value: string | null | undefined): unknown {
+  if (!value) return undefined;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
 }

package/src/linker/cross-repo-linker.ts

@@ -78,7 +78,38 @@ function insertCallEdge(db: Db, workspaceId: number, call: Record<string, unknow
   const operationLikeRemoteEntity = isRemoteEntityCall && Boolean(op) && credibleOperationSignal && (!strongEntitySignal || indexedOperationCandidateCount > 0);
   const isOperationCall = operationLikeRemoteEntity || ((callType === 'remote_action' || callType === 'local_service_call') || (callType === 'remote_query' && Boolean(op)));
   const resolution = isOperationCall ? resolveOperation(db, { servicePath, operationPath: op, serviceName: call.local_service_name as string | undefined, repoId: callType === 'local_service_call' ? Number(call.repo_id) : undefined, alias: applyVariables((call.aliasExpr as string | undefined) ?? (call.alias as string | undefined), vars), destination: destination ? applyVariables(destination, vars) : undefined, isDynamic, hasExplicitOverride: Object.keys(vars).length > 0 || callType === 'local_service_call' }, workspaceId) : { status: 'unresolved' as const, candidates: [], reasons: [] };
-  const evidence: Record<string, unknown> = { ...callEvidence(call, resolution, servicePath, op, destination ? applyVariables(destination, vars) : undefined, normalized, intent), indexedOperationCandidateCount, parserCallType: callType };
+  const evidence: Record<string, unknown> = {
+    ...callEvidence(call, resolution, servicePath, op, destination ? applyVariables(destination, vars) : undefined, normalized, intent),
+    indexedOperationCandidateCount,
+    parserCallType: callType,
+    entityOperationPrecedence: operationPrecedence(
+      callType,
+      intent,
+      indexedOperationCandidateCount,
+      Boolean(resolution.target),
+    ),
+  };
+  const pathAnalysis = objectValue(objectJson(call.evidence_json)?.pathAnalysis);
+  if (callType === 'remote_action' && pathAnalysis?.status === 'ambiguous') {
+    const candidatePaths = Array.isArray(pathAnalysis.candidateRawPaths)
+      ? pathAnalysis.candidateRawPaths
+      : [];
+    db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)').run(
+      workspaceId,
+      'UNRESOLVED_EDGE',
+      'ambiguous',
+      'call',
+      String(call.id),
+      'operation_candidates',
+      candidatePaths.join(','),
+      Number(call.confidence ?? 0.5),
+      JSON.stringify(evidence),
+      0,
+      'Ambiguous operation path candidates require explicit disambiguation',
+      generation,
+    );
+    return { status: 'ambiguous', callType };
+  }
   if (isRemoteEntityCall && (resolution.target || resolution.candidates.length > 0 || resolution.status === 'dynamic')) {
     if (resolution.target) {
       db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?)').run(workspaceId, 'REMOTE_CALL_RESOLVES_TO_OPERATION', 'resolved', 'call', String(call.id), 'operation', String(resolution.target.operationId), resolution.target.score, JSON.stringify({ ...evidence, operationEntityPrecedence: 'indexed_operation_over_parser_entity' }), 0, generation);
@@ -125,6 +156,44 @@ function operationCandidateCount(db: Db, workspaceId: number, operationPath: str
   return Number(row?.count ?? 0);
 }
 
+function operationPrecedence(
+  callType: string,
+  intent: ReturnType<typeof classifyODataPathIntent>,
+  indexedOperationCandidateCount: number,
+  resolvedOperation: boolean,
+): Record<string, unknown> {
+  if (resolvedOperation) {
+    return {
+      decision: 'operation',
+      reason: 'indexed_operation_with_strong_service_context',
+      indexedOperationCandidateCount,
+    };
+  }
+  if (callType === 'remote_action' && intent.kind === 'operation_invocation') {
+    return {
+      decision: 'operation_candidate',
+      rejectionReason: indexedOperationCandidateCount > 0
+        ? 'indexed_candidates_lack_unique_strong_service_context'
+        : 'no_indexed_operation_candidate',
+      indexedOperationCandidateCount,
+    };
+  }
+  if (intent.kind.startsWith('entity_')) {
+    return {
+      decision: 'entity',
+      rejectionReason: indexedOperationCandidateCount > 0
+        ? 'entity_shape_has_precedence_without_resolved_operation_context'
+        : 'entity_shape_has_no_indexed_operation_evidence',
+      indexedOperationCandidateCount,
+    };
+  }
+  return {
+    decision: 'unresolved',
+    rejectionReason: 'path_has_no_safe_entity_or_operation_precedence',
+    indexedOperationCandidateCount,
+  };
+}
+
 function unresolvedOperationReason(resolution: { candidates: unknown[]; status: string; reasons: string[] }): string {
   if (resolution.status === 'dynamic') return `Dynamic target requires runtime variable overrides: ${(resolution.reasons.length ? resolution.reasons : ['missing runtime variables']).join(', ')}`;
   if (resolution.candidates.length === 0) return 'No indexed target operation matched';

package/src/output/table-output.ts

@@ -15,8 +15,8 @@ export function renderTraceTable(result: TraceResult): string {
   const lines = ['Step  Type                 From                                To                                  Evidence'];
   for (const e of result.edges) {
     lines.push(`${String(e.step).padEnd(5)} ${e.type.padEnd(20)} ${e.from.slice(0, 34).padEnd(35)} ${e.to.slice(0, 35).padEnd(36)} ${location(e.evidence)}`);
-    const hint = firstHint(e.evidence);
-    if (e.unresolvedReason && hint) lines.push(`      try ${hint}`);
+    if (e.unresolvedReason)
+      lines.push(...hintLines(e.evidence).map((hint) => `      ${hint}`));
   }
   if (result.diagnostics.length > 0) lines.push('', 'Diagnostics:', ...result.diagnostics.flatMap(diagnosticLines));
   return `${lines.join('\n')}\n`;
@@ -24,13 +24,23 @@ export function renderTraceTable(result: TraceResult): string {
 
 function diagnosticLines(diagnostic: Record<string, unknown>): string[] {
   const first = `${String(diagnostic.severity ?? 'info')} ${String(diagnostic.code ?? 'diagnostic')} ${String(diagnostic.message ?? '')}`;
-  const hint = firstHint(diagnostic);
-  return hint ? [first, `  try ${hint}`] : [first];
+  return [first, ...hintLines(diagnostic).map((hint) => `  ${hint}`)];
 }
 
-function firstHint(evidence: Record<string, unknown>): string | undefined {
+function hintLines(evidence: Record<string, unknown>): string[] {
   const suggestions = evidence.implementationHintSuggestions;
-  if (!Array.isArray(suggestions)) return undefined;
-  const first = suggestions.find((item): item is Record<string, unknown> => Boolean(item) && typeof item === 'object');
-  return typeof first?.cli === 'string' ? first.cli : undefined;
+  if (!Array.isArray(suggestions)) return [];
+  const hints = suggestions.flatMap((item) =>
+    isRecord(item) && typeof item.cli === 'string'
+      ? [item.cli]
+      : []);
+  const unique = [...new Set(hints)];
+  const shown = unique.slice(0, 3).map((hint) => `try ${hint}`);
+  if (unique.length > shown.length)
+    shown.push(`... ${unique.length - shown.length} more hint(s) available in JSON`);
+  return shown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }

package/src/parsers/imported-wrapper-parser.ts

@@ -4,6 +4,11 @@ import { classifyODataPathIntent } from '../linker/odata-path-normalizer.js';
 import type { OutboundCallFact } from '../types.js';
 import { normalizePath } from '../utils/path-utils.js';
 import { importsFor, lineOf, readSource, type ImportBinding } from './service-binding-parser-helpers.js';
+import {
+  analyzeOperationPath,
+  operationPathExpression,
+  pathUnresolvedReason,
+} from './operation-path-analysis.js';
 
 interface WrapperSpec {
   clientIndex: number;
@@ -15,12 +20,6 @@ interface WrapperSpec {
   chain: string[];
 }
 
-interface PathValue {
-  value?: string;
-  sourceKind: string;
-  rawExpression: string;
-}
-
 export async function parseImportedWrapperCalls(
   repoPath: string,
   filePath: string,
@@ -143,11 +142,11 @@ function wrapperCallFact(
 ): OutboundCallFact | undefined {
   const client = call.arguments[spec.clientIndex];
   if (!client || !ts.isIdentifier(client) || !serviceBindings.has(client.text)) return undefined;
-  const pathValue = resolveCallerPath(call.arguments[spec.pathIndex], call);
   const methodValue = spec.methodIndex === undefined ? spec.methodLiteral : literal(call.arguments[spec.methodIndex]);
   const method = (methodValue ?? 'POST').toUpperCase();
-  const rawPath = pathValue.rawExpression;
-  const operationPathExpr = pathValue.value ? normalizeOperationPath(pathValue.value) : runtimePathExpression(rawPath);
+  const pathAnalysis = analyzeOperationPath(call.arguments[spec.pathIndex], call, method);
+  const operationPathExpr = operationPathExpression(pathAnalysis);
+  const unresolvedReason = pathUnresolvedReason(pathAnalysis);
   return {
     callType: 'remote_action',
     serviceVariableName: client.text,
@@ -157,46 +156,29 @@ function wrapperCallFact(
     sourceFile: normalizePath(filePath),
     sourceLine: lineOf(source, call),
     confidence: operationPathExpr ? 0.85 : 0.5,
-    unresolvedReason: pathValue.value ? undefined : 'dynamic_operation_path_identifier',
+    unresolvedReason,
     evidence: {
       parser: 'typescript_ast',
-      classifier: pathValue.value ? 'imported_wrapper_literal_path' : 'imported_wrapper_dynamic_path',
+      classifier: importedWrapperClassifier(pathAnalysis.status),
       receiver: client.text,
       wrapperFunction: spec.chain[0],
       wrapperChain: spec.chain,
       callerSite: { sourceFile: normalizePath(filePath), sourceLine: lineOf(source, call) },
       calleeSite: { sourceFile: spec.sourceFile, sourceLine: spec.sourceLine },
-      rawPathExpression: rawPath,
-      missingPathIdentifier: pathValue.value ? undefined : rawPath,
-      odataPathIntent: pathValue.value ? classifyODataPathIntent(operationPathExpr, method) : undefined,
+      rawPathExpression: pathAnalysis.rawExpression,
+      missingPathIdentifier: pathAnalysis.runtimeIdentifier,
+      pathAnalysis,
+      odataPathIntent: operationPathExpr
+        ? classifyODataPathIntent(operationPathExpr, method)
+        : undefined,
     },
   };
 }
 
-function resolveCallerPath(expr: ts.Expression | undefined, use: ts.Node): PathValue {
-  if (!expr) return { sourceKind: 'missing', rawExpression: '' };
-  if (ts.isStringLiteralLike(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) return { value: expr.text, sourceKind: 'literal', rawExpression: expr.getText() };
-  if (ts.isTemplateExpression(expr)) return { value: expr.getText().slice(1, -1), sourceKind: 'template', rawExpression: expr.getText() };
-  if (ts.isIdentifier(expr)) {
-    const initializer = constInitializer(expr.text, use);
-    if (initializer) {
-      const resolved = resolveCallerPath(initializer, initializer);
-      return { ...resolved, sourceKind: 'const', rawExpression: expr.text };
-    }
-  }
-  return { sourceKind: 'dynamic', rawExpression: expr.getText() };
-}
-
-function constInitializer(name: string, use: ts.Node): ts.Expression | undefined {
-  let found: ts.Expression | undefined;
-  const source = use.getSourceFile();
-  const visit = (node: ts.Node): void => {
-    if (node.getStart(source) >= use.getStart(source)) return;
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && node.initializer && (node.parent.flags & ts.NodeFlags.Const) !== 0) found = node.initializer;
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  return found;
+function importedWrapperClassifier(status: string): string {
+  if (status === 'static') return 'imported_wrapper_literal_path';
+  if (status === 'ambiguous') return 'imported_wrapper_ambiguous_path';
+  return 'imported_wrapper_dynamic_path';
 }
 
 function findFunction(source: ts.SourceFile, exportedName: string): { name: string; fn: ts.FunctionLikeDeclaration } | undefined {
@@ -252,11 +234,3 @@ function propertyName(name: ts.PropertyName): string | undefined {
 function literal(expr: ts.Expression | undefined): string | undefined {
   return expr && (ts.isStringLiteralLike(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) ? expr.text : undefined;
 }
-
-function normalizeOperationPath(value: string): string {
-  return value.startsWith('/') ? value : `/${value}`;
-}
-
-function runtimePathExpression(value: string): string | undefined {
-  return value ? `\${${value}}` : undefined;
-}