@saptools/service-flow 0.1.53 → 0.1.54

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   stripQuotes,
   substituteVariables,
   trace
-} from "./chunk-LFH7C46B.js";
+} from "./chunk-ERIZHM5C.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.53",
+  "version": "0.1.54",
   "description": "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   "type": "module",
   "publishConfig": {

package/src/cli/001-doctor-projection.ts

@@ -1,6 +1,5 @@
 import {
-  projectBounded,
-  stableProjectionValue,
+  projectBoundedInOrder,
   type BoundedProjection,
 } from '../utils/000-bounded-projection.js';
 
@@ -54,7 +53,8 @@ function boundDoctorValue(value: unknown): unknown {
       output[key] = boundDoctorValue(child);
       continue;
     }
-    const projection = projectBounded(child.map(boundDoctorValue), compareDiagnostic);
+    // Doctor producers already query or assemble deterministic semantic order.
+    const projection = projectBoundedInOrder(child.map(boundDoctorValue));
     output[key] = projection.items;
     addProjectionMetadata(output, input, key, projection);
   }
@@ -127,10 +127,6 @@ function projectionStem(key: string): string {
   return stems[key] ?? 'repository';
 }
 
-function compareDiagnostic(left: unknown, right: unknown): number {
-  return stableProjectionValue(left).localeCompare(stableProjectionValue(right));
-}
-
 function numericValue(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }

package/src/linker/000-implementation-candidates.ts

@@ -4,6 +4,8 @@ import { normalizeDecoratorOperationSignal, normalizedOperationName } from './op
 import {
   boundedImplementationEvidence,
   boundedImplementationTargetIds,
+  displayImplementationCandidates,
+  selectedHandlerProvenance,
 } from './001-implementation-evidence-projection.js';
 
 interface ImplementationCandidate extends Record<string, unknown> {
@@ -107,6 +109,7 @@ function implementationDecision(
     : winners.length > 1 ? ['multiple_equal_score_implementation_candidates'] : [];
   const evidence = implementationEvidence(
     operation, implementationContext, candidates, duplicateFamilies, ambiguityReasons,
+    unique,
   );
   const hintProjection = implementationHintSuggestionProjection(evidence);
   return {
@@ -174,6 +177,7 @@ function implementationEvidence(
   candidates: ImplementationCandidate[],
   duplicateFamilies: Array<Record<string, unknown>>,
   ambiguityReasons: string[],
+  selected: ImplementationCandidate | undefined,
 ): Record<string, unknown> {
   return {
     servicePath: operation.servicePath,
@@ -191,7 +195,13 @@ function implementationEvidence(
     implementationOperationId: context.operationId,
     ambiguityReasons,
     candidateFamilies: duplicateFamilies,
-    candidates: candidates.map((candidate, index) => candidateEvidence(candidate, index + 1)),
+    selectedHandler: selected
+      ? selectedHandlerProvenance(selectedHandlerSource(selected))
+      : undefined,
+    candidates: displayImplementationCandidates(
+      candidates.map((candidate, index) => candidateEvidence(candidate, index + 1)),
+      selected?.methodId,
+    ),
   };
 }
 
@@ -350,7 +360,7 @@ function implementationCandidates(
       hm.id methodId,hm.method_name methodName,hm.decorator_value decoratorValue,
       hm.decorator_raw_expression decoratorRawExpression,
       hm.decorator_resolution_json decoratorResolutionJson,hc.id classId,
-      hc.class_name className,hc.source_file sourceFile,hc.source_line sourceLine,
+      hc.class_name className,hc.source_file sourceFile,hm.source_line sourceLine,
       hr.id registrationId,hr.handler_class_id registrationHandlerClassId,
       hr.class_name registrationClassName,hr.repo_id applicationRepoId,
       hr.registration_file registrationFile,hr.registration_line registrationLine,
@@ -526,6 +536,7 @@ function ownershipScore(
 function candidateEvidence(candidate: ImplementationCandidate, rank: number): Record<string, unknown> {
   return {
     rank,
+    rankKind: 'discovery_score',
     score: candidate.score,
     accepted: candidate.accepted,
     acceptedReasons: candidate.acceptedReasons,
@@ -580,6 +591,28 @@ function candidateEvidence(candidate: ImplementationCandidate, rank: number): Re
   };
 }
 
+function selectedHandlerSource(candidate: ImplementationCandidate): {
+  methodId: number;
+  className?: string;
+  methodName?: string;
+  repositoryId?: number;
+  repositoryName?: string;
+  repositoryPackageName?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+} {
+  return {
+    methodId: candidate.methodId,
+    className: stringValue(candidate.className),
+    methodName: stringValue(candidate.methodName),
+    repositoryId: numberValue(candidate.handlerRepoId),
+    repositoryName: stringValue(candidate.handlerRepo),
+    repositoryPackageName: stringValue(candidate.handlerPackage),
+    sourceFile: stringValue(candidate.sourceFile),
+    sourceLine: numberValue(candidate.sourceLine),
+  };
+}
+
 function implementationMethodSignal(
   row: Record<string, unknown>,
   operation: Record<string, unknown>,

package/src/linker/001-implementation-evidence-projection.ts

@@ -1,14 +1,91 @@
 import {
   projectBounded,
+  projectBoundedInOrder,
   type BoundedProjection,
 } from '../utils/000-bounded-projection.js';
 
+export interface SelectedHandlerSource {
+  methodId: number;
+  className?: string;
+  methodName?: string;
+  repositoryId?: number;
+  repositoryName?: string;
+  repositoryPackageName?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+}
+
+export interface SelectedHandlerProvenance {
+  status: 'selected';
+  accepted: true;
+  graphTargetId: string;
+  methodId: number;
+  className?: string;
+  methodName?: string;
+  repository?: {
+    id?: number;
+    name?: string;
+    packageName?: string;
+  };
+  sourceFile?: string;
+  sourceLine?: number;
+}
+
+export function selectedHandlerProvenance(
+  source: SelectedHandlerSource,
+): SelectedHandlerProvenance {
+  return {
+    status: 'selected',
+    accepted: true,
+    graphTargetId: String(source.methodId),
+    methodId: source.methodId,
+    className: source.className,
+    methodName: source.methodName,
+    repository: {
+      id: source.repositoryId,
+      name: source.repositoryName,
+      packageName: source.repositoryPackageName,
+    },
+    sourceFile: source.sourceFile,
+    sourceLine: source.sourceLine,
+  };
+}
+
+export function displayImplementationCandidates(
+  candidates: Array<Record<string, unknown>>,
+  selectedMethodId: number | undefined,
+): Array<Record<string, unknown>> {
+  return [...candidates]
+    .sort((left, right) => compareDisplayCandidate(
+      left, right, selectedMethodId,
+    ))
+    .map((candidate, index) => ({
+      ...candidate,
+      discoveryRank: candidate.rank,
+      displayRank: index + 1,
+      selected: selectedMethodId !== undefined
+        && Number(candidate.methodId) === selectedMethodId,
+    }));
+}
+
+function compareDisplayCandidate(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>,
+  selectedMethodId: number | undefined,
+): number {
+  return Number(Number(right.methodId) === selectedMethodId)
+    - Number(Number(left.methodId) === selectedMethodId)
+    || Number(right.accepted === true) - Number(left.accepted === true)
+    || numberValue(left.rank) - numberValue(right.rank)
+    || compareTargetCandidates(left, right);
+}
+
 export function boundedImplementationEvidence(
   evidence: Record<string, unknown>,
   targetCandidateCount: number,
 ): Record<string, unknown> {
   const candidates = recordArray(evidence.candidates);
-  const candidateProjection = projectBounded(candidates, compareCandidateEvidence);
+  const candidateProjection = projectBoundedInOrder(candidates);
   const families = recordArray(evidence.candidateFamilies);
   const familyProjection = projectBounded(families, compareFamilies);
   const hints = recordArray(evidence.implementationHintSuggestions);
@@ -80,11 +157,6 @@ function compareTargetCandidates(left: Record<string, unknown>, right: Record<st
     || Number(left.methodId ?? 0) - Number(right.methodId ?? 0);
 }
 
-function compareCandidateEvidence(left: Record<string, unknown>, right: Record<string, unknown>): number {
-  return Number(left.rank ?? 0) - Number(right.rank ?? 0)
-    || compareTargetCandidates(left, right);
-}
-
 function compareFamilies(left: Record<string, unknown>, right: Record<string, unknown>): number {
   return String(left.packageName ?? '').localeCompare(String(right.packageName ?? ''))
     || String(left.reason ?? '').localeCompare(String(right.reason ?? ''));

package/src/output/table-output.ts

@@ -1,13 +1,22 @@
 import type { TraceResult } from '../types.js';
 
 function location(evidence: Record<string, unknown>): string {
+  const selected = isRecord(evidence.selectedHandler)
+    ? evidence.selectedHandler : undefined;
+  const selectedFile = selected?.sourceFile;
+  const selectedLine = selected?.sourceLine;
+  if (selectedFile || selectedLine)
+    return `${String(selectedFile ?? '')}:${String(selectedLine ?? '')}`;
   const file = evidence.file ?? evidence.sourceFile ?? evidence.handlerSourceFile ?? evidence.operationSourceFile ?? evidence.registrationSourceFile;
   const line = evidence.line ?? evidence.sourceLine ?? evidence.handlerSourceLine ?? evidence.operationSourceLine ?? evidence.registrationSourceLine;
   if (file || line) return `${String(file ?? '')}:${String(line ?? '')}`;
   const candidates = evidence.candidates;
+  if (Array.isArray(candidates) && candidates.some((candidate) =>
+    isRecord(candidate) && candidate.methodId !== undefined)) return ':';
   if (Array.isArray(candidates) && candidates.length > 0) {
-    const first = candidates[0] as Record<string, unknown>;
-    return `${String(first.sourceFile ?? '')}:${String(first.sourceLine ?? '')}`;
+    const first = candidates.find(isRecord);
+    if (first)
+      return `${String(first.sourceFile ?? '')}:${String(first.sourceLine ?? '')}`;
   }
   return ':';
 }

package/src/trace/008-contextual-runtime-state.ts

@@ -0,0 +1,294 @@
+import type { Db } from '../db/connection.js';
+import { normalizeODataOperationInvocationPath } from '../linker/odata-path-normalizer.js';
+import { resolveOperation, type OperationResolution } from '../linker/service-resolver.js';
+import { boundedContextCandidates } from './006-contextual-projection.js';
+
+export interface ContextBinding {
+  bindingId?: number;
+  alias?: string;
+  aliasExpr?: string;
+  destinationExpr?: string;
+  servicePathExpr?: string;
+  requireServicePath?: string;
+  requireDestination?: string;
+  effectiveServicePath?: string;
+  effectiveDestination?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+  source: string;
+  callerArgument?: string;
+  callerProperty?: string;
+  calleeParameter?: string;
+  calleeObjectProperty?: string;
+  calleeLocalDestructuredIdentifier?: string;
+  parameterPropertyAliasKind?: unknown;
+  parameterPropertyAliasLine?: unknown;
+  calleeReceiver: string;
+  callerSite?: { sourceFile?: string; sourceLine?: number };
+  calleeSite?: { sourceFile?: string; sourceLine?: number };
+  resolutionStatus?: 'selected' | 'ambiguous';
+  bindingCandidates?: Array<Record<string, unknown>>;
+}
+
+interface ContextualCall {
+  id: number;
+  call_type: string;
+  operation_path_expr?: unknown;
+}
+
+interface PersistedGraphRow {
+  status?: string;
+}
+
+export interface ContextualGraphRow {
+  id: number;
+  edge_type: string;
+  from_id: string;
+  to_kind: string;
+  to_id: string;
+  confidence: number;
+  evidence_json: string;
+  status: 'resolved';
+}
+
+export type ContextualResolutionCategory =
+  | 'none'
+  | 'dynamic_missing'
+  | 'ambiguous_binding'
+  | 'ambiguous_operation'
+  | 'no_matching_operation'
+  | 'other_blocker';
+
+export interface ContextualRuntimeState {
+  category: ContextualResolutionCategory;
+  message?: string;
+  missingVariables?: string[];
+  resolutionStatus?: string;
+  phase?: 'before_runtime_substitution';
+}
+
+export interface ContextualRuntimeResolution {
+  row?: ContextualGraphRow;
+  evidence?: Record<string, unknown>;
+  state: ContextualRuntimeState;
+}
+
+export function dynamicMissingReason(keys: readonly string[]): string {
+  const missing = normalizedKeys(keys);
+  return missing.length > 0
+    ? `Dynamic target is missing runtime variables: ${missing.join(', ')}`
+    : 'Dynamic target still requires runtime variables';
+}
+
+export function isStructuralContextualBlocker(
+  state: ContextualRuntimeState | undefined,
+): boolean {
+  return state?.category === 'ambiguous_binding'
+    || state?.category === 'ambiguous_operation'
+    || state?.category === 'no_matching_operation'
+    || state?.category === 'other_blocker';
+}
+
+export function contextualRuntimeResolution(
+  db: Db,
+  call: ContextualCall,
+  binding: ContextBinding | undefined,
+  workspaceId: number | undefined,
+  persistedRows: PersistedGraphRow[] = [],
+): ContextualRuntimeResolution {
+  if (!binding || call.call_type !== 'remote_action'
+    || call.operation_path_expr === undefined || call.operation_path_expr === null)
+    return { state: { category: 'none' } };
+  if (binding.resolutionStatus === 'ambiguous')
+    return ambiguousBindingResolution(binding);
+  return selectedBindingResolution(db, call, binding, workspaceId, persistedRows);
+}
+
+function ambiguousBindingResolution(
+  binding: ContextBinding,
+): ContextualRuntimeResolution {
+  const candidates = boundedContextCandidates(binding.bindingCandidates ?? []);
+  const state: ContextualRuntimeState = {
+    category: 'ambiguous_binding',
+    message: 'Ambiguous contextual service binding candidates',
+    resolutionStatus: 'ambiguous',
+  };
+  return {
+    evidence: {
+      contextualServiceBindingAttempted: true,
+      contextualBinding: {
+        source: binding.source,
+        status: 'tied',
+        candidates: candidates.candidates,
+        candidateCount: candidates.candidateCount,
+        shownCandidateCount: candidates.shownCandidateCount,
+        omittedCandidateCount: candidates.omittedCandidateCount,
+      },
+      contextualResolutionStatus: 'ambiguous',
+      contextualCandidateCount: candidates.candidateCount,
+      contextualPreSubstitutionState: historicalState(state),
+    },
+    state,
+  };
+}
+
+function selectedBindingResolution(
+  db: Db,
+  call: ContextualCall,
+  binding: ContextBinding,
+  workspaceId: number | undefined,
+  persistedRows: PersistedGraphRow[],
+): ContextualRuntimeResolution {
+  const normalized = normalizeODataOperationInvocationPath(
+    String(call.operation_path_expr),
+  );
+  const operationPath = normalized?.normalizedOperationPath
+    ?? withLeadingSlash(String(call.operation_path_expr));
+  const servicePath = binding.effectiveServicePath
+    ?? binding.servicePathExpr ?? binding.requireServicePath;
+  const destination = binding.effectiveDestination
+    ?? binding.destinationExpr ?? binding.requireDestination;
+  const resolution = resolveOperation(db, {
+    servicePath,
+    operationPath,
+    alias: binding.aliasExpr ?? binding.alias,
+    destination,
+    hasExplicitOverride: true,
+    isDynamic: false,
+  }, workspaceId);
+  const state = stateForResolution(resolution);
+  const evidence = contextualEvidence(
+    binding, normalized, operationPath, servicePath, destination, resolution, state,
+  );
+  if (!resolution.target) return { evidence, state };
+  const resolvedEvidence = {
+    ...evidence,
+    contextualServiceBindingSelected: true,
+    targetRepo: resolution.target.repoName,
+    targetServicePath: resolution.target.servicePath,
+    targetOperationPath: resolution.target.operationPath,
+    targetOperation: resolution.target.operationName,
+  };
+  if (persistedRows.some((row) => row.status === 'resolved'))
+    return { evidence: { ...resolvedEvidence, contextualPreservedPersistedResolvedEdge: true }, state };
+  return {
+    row: {
+      id: -call.id,
+      edge_type: 'REMOTE_CALL_RESOLVES_TO_OPERATION',
+      from_id: String(call.id),
+      to_kind: 'operation',
+      to_id: String(resolution.target.operationId),
+      confidence: resolution.target.score,
+      evidence_json: JSON.stringify(resolvedEvidence),
+      status: 'resolved',
+    },
+    evidence: resolvedEvidence,
+    state,
+  };
+}
+
+function contextualEvidence(
+  binding: ContextBinding,
+  normalized: ReturnType<typeof normalizeODataOperationInvocationPath>,
+  operationPath: string,
+  servicePath: string | undefined,
+  destination: string | undefined,
+  resolution: OperationResolution,
+  state: ContextualRuntimeState,
+): Record<string, unknown> {
+  const candidates = boundedContextCandidates(resolution.candidates);
+  return {
+    contextualServiceBindingAttempted: true,
+    contextualBinding: bindingEvidence(binding),
+    operationPath,
+    rawOperationPath: normalized?.rawOperationPath,
+    normalizedOperationPath: normalized?.wasInvocation
+      ? normalized.normalizedOperationPath : undefined,
+    invocationArgumentPlaceholderKeys: normalized?.invocationArgumentPlaceholderKeys.length
+      ? normalized.invocationArgumentPlaceholderKeys : undefined,
+    servicePath,
+    serviceAlias: binding.alias,
+    serviceAliasExpr: binding.aliasExpr,
+    destination,
+    requireServicePath: binding.requireServicePath,
+    requireDestination: binding.requireDestination,
+    effectiveServicePath: binding.effectiveServicePath,
+    effectiveDestination: binding.effectiveDestination,
+    contextualResolutionStatus: resolution.status,
+    contextualCandidateCount: candidates.candidateCount,
+    shownContextualCandidateCount: candidates.shownCandidateCount,
+    omittedContextualCandidateCount: candidates.omittedCandidateCount,
+    candidates: candidates.candidates,
+    contextualResolutionReasons: resolution.reasons,
+    resolutionReasons: resolution.reasons,
+    contextualPreSubstitutionState: historicalState(state),
+  };
+}
+
+function bindingEvidence(binding: ContextBinding): Record<string, unknown> {
+  return {
+    source: binding.source,
+    callerArgument: binding.callerArgument,
+    callerProperty: binding.callerProperty,
+    calleeParameter: binding.calleeParameter,
+    calleeReceiver: binding.calleeReceiver,
+    callerSite: binding.callerSite,
+    calleeSite: binding.calleeSite,
+    bindingSourceFile: binding.sourceFile,
+    bindingSourceLine: binding.sourceLine,
+    alias: binding.alias,
+    aliasExpr: binding.aliasExpr,
+    requireServicePath: binding.requireServicePath,
+    requireDestination: binding.requireDestination,
+    effectiveServicePath: binding.effectiveServicePath,
+    effectiveDestination: binding.effectiveDestination,
+  };
+}
+
+function stateForResolution(
+  resolution: OperationResolution,
+): ContextualRuntimeState {
+  if (resolution.status === 'resolved') return { category: 'none' };
+  if (resolution.status === 'dynamic') {
+    const missingVariables = missingVariableKeys(resolution.reasons);
+    return {
+      category: 'dynamic_missing',
+      message: dynamicMissingReason(missingVariables),
+      missingVariables,
+      resolutionStatus: resolution.status,
+    };
+  }
+  if (resolution.status === 'ambiguous') return {
+    category: 'ambiguous_operation',
+    message: 'Ambiguous contextual operation candidates',
+    resolutionStatus: resolution.status,
+  };
+  return {
+    category: resolution.status === 'unresolved'
+      ? 'no_matching_operation' : 'other_blocker',
+    message: resolution.status === 'unresolved'
+      ? 'No contextual operation candidate matched'
+      : 'Contextual operation resolution is blocked',
+    resolutionStatus: resolution.status,
+  };
+}
+
+function historicalState(
+  state: ContextualRuntimeState,
+): ContextualRuntimeState {
+  return { ...state, phase: 'before_runtime_substitution' };
+}
+
+function missingVariableKeys(reasons: string[]): string[] {
+  return normalizedKeys(reasons.flatMap((reason) =>
+    reason.startsWith('missing_variable:')
+      ? [reason.slice('missing_variable:'.length)] : []));
+}
+
+function normalizedKeys(keys: readonly string[]): string[] {
+  return [...new Set(keys.filter((key) => key.length > 0))].sort();
+}
+
+function withLeadingSlash(value: string): string {
+  return value.startsWith('/') ? value : `/${value}`;
+}