@saptools/service-flow 0.1.49 → 0.1.51

package/src/trace/evidence.ts

@@ -2,6 +2,8 @@ import type { Db } from '../db/connection.js';
 import { extractPlaceholders, substituteVariables, type RuntimeSubstitution } from '../linker/dynamic-edge-resolver.js';
 import { normalizeODataOperationInvocationPath } from '../linker/odata-path-normalizer.js';
 import { resolveOperation, type OperationTarget } from '../linker/service-resolver.js';
+import type { DynamicMode } from '../types.js';
+import { analyzeDynamicTargetCandidates, type DynamicTargetAnalysis, type DynamicTargetCandidate } from './dynamic-targets.js';
 
 export interface TraceGraphRow extends Record<string, unknown> {
   id: number;
@@ -50,27 +52,49 @@ export function runtimeResolution(
   db: Db,
   row: TraceGraphRow,
   evidence: Record<string, unknown>,
-  vars: Record<string, string> | undefined,
+  options: { vars?: Record<string, string>; dynamicMode?: DynamicMode; maxDynamicCandidates?: number },
   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 substituted = evidenceWithRuntimeVariables(evidence, options.vars);
+  const dynamicMode = options.dynamicMode ?? 'strict';
+  const analysis = analyzeDynamicTargetCandidates(
+    db,
+    substituted,
+    workspaceId,
+    dynamicMode,
+    positiveCandidateCap(options.maxDynamicCandidates),
+  );
+  const enriched = analysis ? evidenceWithDynamicAnalysis(substituted, analysis) : substituted;
+  if (dynamicMode === 'infer') {
+    const inferred = inferredTarget(analysis);
+    if (inferred) {
+      const resolvedRow = { ...row, status: 'resolved', to_kind: 'operation', to_id: String(inferred.operationId), unresolved_reason: undefined, confidence: inferred.score };
+      const resolution = { status: 'resolved' as const, target: inferred, candidates: [], reasons: inferred.reasons };
+      return { row: resolvedRow, evidence: withEffectiveResolution(enriched, resolvedRow, undefined, resolution), target: inferred };
+    }
+  }
+  if (!isRemoteRuntimeCandidate(row, evidence, options.vars)) {
     const unresolvedReason = contextualUnresolvedReason ?? row.unresolved_reason;
-    const withSections = withEffectiveResolution(substituted, row, unresolvedReason);
+    const withSections = withEffectiveResolution(enriched, row, unresolvedReason);
     return { row, evidence: withSections, unresolvedReason };
   }
-  const resolution = resolveRuntimeOperation(db, substituted, workspaceId);
+  const resolution = resolveRuntimeOperation(db, enriched, workspaceId);
   if (resolution.target) {
     const resolvedRow = { ...row, status: 'resolved', to_kind: 'operation', to_id: String(resolution.target.operationId), unresolved_reason: undefined, confidence: Math.max(0, Math.min(1, resolution.target.score)) };
-    return { row: resolvedRow, evidence: withEffectiveResolution(substituted, resolvedRow, undefined, resolution), target: resolution.target };
+    return { row: resolvedRow, evidence: withEffectiveResolution(enriched, resolvedRow, undefined, resolution), target: resolution.target };
   }
   const unresolvedReason = runtimeUnresolvedReason(resolution);
-  return { row, evidence: withEffectiveResolution(substituted, row, unresolvedReason, resolution), unresolvedReason };
+  return { row, evidence: withEffectiveResolution(enriched, row, unresolvedReason, resolution), unresolvedReason };
 }
 
 export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string, unknown> }>): Record<string, unknown> | undefined {
   const missing = new Set<string>();
+  let candidateCount = 0;
+  let shownCandidateCount = 0;
+  let omittedCandidateCount = 0;
+  const candidateSuggestions: Record<string, unknown>[] = [];
+  const suggestedVarSets: Record<string, unknown>[] = [];
   for (const edge of edges) {
     const effective = parseObject(edge.evidence.effectiveResolution);
     if (!['dynamic', 'unresolved', 'ambiguous'].includes(String(effective.status ?? '')))
@@ -79,6 +103,12 @@ export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string
     if (!substitutions || typeof substitutions !== 'object' || Array.isArray(substitutions)) continue;
     for (const value of Object.values(substitutions as Record<string, RuntimeSubstitution>))
       for (const key of value.missing ?? []) missing.add(key);
+    const exploration = parseObject(edge.evidence.dynamicTargetExploration);
+    candidateCount += numeric(exploration.candidateCount);
+    shownCandidateCount += numeric(exploration.shownCandidateCount);
+    omittedCandidateCount += numeric(exploration.omittedCandidateCount);
+    candidateSuggestions.push(...recordArray(edge.evidence.dynamicTargetCandidateSuggestions));
+    suggestedVarSets.push(...recordArray(exploration.suggestedVarSets));
   }
   const missingVariables = [...missing].sort();
   if (missingVariables.length === 0) return undefined;
@@ -88,6 +118,16 @@ export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string
     message: `Runtime variables are required to resolve dynamic trace targets: ${missingVariables.join(', ')}`,
     missingVariables,
     suggestions: missingVariables.map((key) => `--var ${key}=<value>`),
+    candidateCount,
+    shownCandidateCount,
+    omittedCandidateCount,
+    candidateSuggestions: candidateSuggestions.slice(0, 5),
+    suggestedVarSets: uniqueCliRows(suggestedVarSets).slice(0, 5),
+    copyableExamples: [
+      ...uniqueCliRows(suggestedVarSets).slice(0, 3).flatMap((row) =>
+        typeof row.cli === 'string' ? [row.cli] : []),
+      ...(candidateCount > 0 ? ['--dynamic-mode candidates --max-dynamic-candidates 20'] : []),
+    ],
   };
 }
 
@@ -180,6 +220,26 @@ function evidenceWithRuntimeVariables(evidence: Record<string, unknown>, vars: R
   return next;
 }
 
+function evidenceWithDynamicAnalysis(
+  evidence: Record<string, unknown>,
+  analysis: DynamicTargetAnalysis,
+): Record<string, unknown> {
+  return {
+    ...evidence,
+    dynamicTargetExploration: {
+      mode: analysis.mode,
+      missingVariables: analysis.missingVariables,
+      candidateCount: analysis.candidateCount,
+      shownCandidateCount: analysis.shownCandidateCount,
+      omittedCandidateCount: analysis.omittedCandidateCount,
+      suggestedVarSets: analysis.suggestedVarSets,
+    },
+    dynamicTargetCandidates: analysis.candidates,
+    dynamicTargetCandidateSuggestions: analysis.shownCandidates,
+    dynamicTargetInference: analysis.inference,
+  };
+}
+
 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']) {
@@ -206,6 +266,31 @@ function isRemoteRuntimeCandidate(row: TraceGraphRow, evidence: Record<string, u
   return ['servicePath', 'operationPath', 'serviceAliasExpr', 'serviceAlias', 'destination'].some((key) => hasRuntimeVariable(evidence[key], vars));
 }
 
+function inferredTarget(analysis: DynamicTargetAnalysis | undefined): OperationTarget | undefined {
+  if (analysis?.inference.status !== 'resolved') return undefined;
+  const id = Number(analysis.inference.candidateOperationId);
+  const candidate = analysis.candidates.find((item) => item.candidateOperationId === id);
+  if (!candidate) return undefined;
+  return targetFromCandidate(candidate);
+}
+
+function targetFromCandidate(candidate: DynamicTargetCandidate): OperationTarget {
+  return {
+    operationId: candidate.candidateOperationId,
+    repoName: candidate.repoName,
+    serviceName: '',
+    qualifiedName: '',
+    servicePath: candidate.servicePath,
+    operationPath: candidate.operationPath,
+    operationName: candidate.operationName,
+    packageName: candidate.packageName,
+    score: candidate.score,
+    reasons: candidate.reasons,
+    sourceFile: '',
+    sourceLine: 0,
+  };
+}
+
 function hasRuntimeVariable(value: unknown, vars: Record<string, string>): boolean {
   return typeof value === 'string' && extractPlaceholders(value).some((key) => Object.hasOwn(vars, key));
 }
@@ -223,3 +308,28 @@ function parseObject(value: unknown): Record<string, unknown> {
 function stringValue(value: unknown): string | undefined {
   return typeof value === 'string' ? value : undefined;
 }
+
+function numeric(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function recordArray(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> =>
+        Boolean(item && typeof item === 'object' && !Array.isArray(item)))
+    : [];
+}
+
+function uniqueCliRows(rows: Record<string, unknown>[]): Record<string, unknown>[] {
+  const seen = new Set<string>();
+  return rows.filter((row) => {
+    const cli = typeof row.cli === 'string' ? row.cli : JSON.stringify(row);
+    if (seen.has(cli)) return false;
+    seen.add(cli);
+    return true;
+  });
+}
+
+function positiveCandidateCap(value: number | undefined): number {
+  return Number.isFinite(value) && Number(value) > 0 ? Math.floor(Number(value)) : 5;
+}

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();
+}

package/src/trace/trace-engine.ts

@@ -2,9 +2,11 @@ import type { Db } from '../db/connection.js';
 import { extractPlaceholders } from '../linker/dynamic-edge-resolver.js';
 import { normalizeODataOperationInvocationPath } from '../linker/odata-path-normalizer.js';
 import { resolveOperation } from '../linker/service-resolver.js';
-import type { ImplementationHint, TraceEdge, TraceResult, TraceStart } from '../types.js';
+import type { ImplementationHint, TraceEdge, TraceOptions, TraceResult, TraceStart } from '../types.js';
 import { baseTraceEvidence, edgeTarget, runtimeResolution, runtimeVariableDiagnostic, type TraceGraphRow } from './evidence.js';
+import { dynamicCandidateBranches } from './dynamic-branches.js';
 import { implementationHintDiagnostic, selectImplementation, type ImplementationSelection } from './implementation-hints.js';
+import { ambiguousStartDiagnostic } from './selectors.js';
 interface RepoRef {
   id: number;
   name: string;
@@ -120,26 +122,6 @@ function implementationRejectionReasons(evidence: Record<string, unknown>): stri
       : []);
   return [...new Set(reasons)].sort();
 }
-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,
-  };
-}
 function sourceFilesForStart(
   db: Db,
   repoId: number | undefined,
@@ -326,6 +308,7 @@ function operationNode(db: Db, operationId: string): Record<string, unknown> | u
   if (!row) return undefined;
   return { id: `operation:${operationId}`, kind: 'operation', label: `${String(row.repoName)}:${String(row.servicePath)}${String(row.operationPath)}`, ...row };
 }
+
 function workspaceIdForCall(db: Db, callId: string): number | undefined {
   return (db.prepare('SELECT r.workspace_id workspaceId FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id WHERE c.id=?').get(callId) as { workspaceId?: number } | undefined)?.workspaceId;
 }
@@ -505,15 +488,7 @@ function contextualRuntimeResolution(db: Db, call: CallRow, binding: ContextBind
 export function trace(
   db: Db,
   start: TraceStart,
-  options: {
-    depth: number;
-    vars?: Record<string, string>;
-    includeExternal?: boolean;
-    includeDb?: boolean;
-    includeAsync?: boolean;
-    implementationRepo?: string;
-    implementationHints?: ImplementationHint[];
-  },
+  options: TraceOptions,
 ): TraceResult {
   const hintOptions = { implementationRepo: options.implementationRepo, implementationHints: options.implementationHints };
   const scope = startScope(db, start, hintOptions);
@@ -614,7 +589,11 @@ export function trace(
           String(row.evidence_json || '{}'),
         ) as Record<string, unknown>;
         const rawEvidence = baseTraceEvidence(row as TraceGraphRow, call, persistedEvidence, contextual.evidence);
-        const effective = runtimeResolution(db, row as TraceGraphRow, rawEvidence, options.vars, workspaceIdForCall(db, String(call.id)), contextual.unresolvedReason);
+        const effective = runtimeResolution(db, row as TraceGraphRow, rawEvidence, {
+          vars: options.vars,
+          dynamicMode: options.dynamicMode ?? 'strict',
+          maxDynamicCandidates: options.maxDynamicCandidates,
+        }, workspaceIdForCall(db, String(call.id)), contextual.unresolvedReason);
         const evidence = effective.evidence;
         const effectiveRow = effective.row;
         const targetNode = `${effectiveRow.to_kind}:${effectiveRow.to_id}`;
@@ -634,6 +613,8 @@ export function trace(
           confidence: Number(effectiveRow.confidence ?? call.confidence),
           unresolvedReason: effective.unresolvedReason,
         });
+        if ((options.dynamicMode ?? 'strict') === 'candidates')
+          edges.push(...dynamicCandidateBranches(current.depth, call, evidence));
         if (effectiveRow.to_kind === 'operation') {
           const implementation = implementationScope(db, effectiveRow.to_id);
           const contextSelection = contextImplementationMethodId(implementation.edge, current.repoId, evidence, hintOptions);

package/src/types.ts

@@ -101,6 +101,18 @@ export interface HandlerMethodFact {
   decoratorKind: string;
   decoratorValue?: string;
   decoratorRawExpression: string;
+  decoratorResolution: {
+    rawExpression: string;
+    resolvedValue?: string;
+    resolutionKind:
+      | 'literal'
+      | 'const_identifier'
+      | 'enum_member'
+      | 'const_object_property'
+      | 'generated_constant_name'
+      | 'unresolved';
+    unresolvedReason?: string;
+  };
   sourceFile: string;
   sourceLine: number;
 }
@@ -187,6 +199,18 @@ export interface ImplementationHint {
   candidateFamily?: string;
   implementationRepo: string;
 }
+export type DynamicMode = 'strict' | 'candidates' | 'infer';
+export interface TraceOptions {
+  depth: number;
+  vars?: Record<string, string>;
+  includeExternal?: boolean;
+  includeDb?: boolean;
+  includeAsync?: boolean;
+  implementationRepo?: string;
+  implementationHints?: ImplementationHint[];
+  dynamicMode?: DynamicMode;
+  maxDynamicCandidates?: number;
+}
 export interface TraceEdge {
   step: number;
   type: string;