@saptools/service-flow 0.1.43 → 0.1.45

package/src/trace/evidence.ts

@@ -0,0 +1,210 @@
+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';
+
+export interface TraceGraphRow extends Record<string, unknown> {
+  id: number;
+  edge_type: string;
+  from_id: string;
+  to_kind: string;
+  to_id: string;
+  confidence: number;
+  evidence_json: string;
+  unresolved_reason?: string;
+  status?: string;
+}
+
+interface Candidate {
+  servicePath?: string;
+  operationPath?: string;
+  repoName?: string;
+  operationName?: string;
+  score?: number;
+}
+
+export function baseTraceEvidence(
+  row: TraceGraphRow,
+  call: Record<string, unknown>,
+  persistedEvidence: Record<string, unknown>,
+  contextualEvidence: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const evidence = { ...persistedEvidence, ...(contextualEvidence ?? {}) };
+  return {
+    ...evidence,
+    graphEdgeId: row.id,
+    persistedGraphEdgeId: row.id > 0 ? row.id : undefined,
+    outboundCallId: call.id,
+    callSite: { sourceFile: call.source_file, sourceLine: call.source_line },
+    sourceFile: call.source_file,
+    sourceLine: call.source_line,
+    file: call.source_file,
+    line: call.source_line,
+    persistedTarget: { kind: row.to_kind, id: row.to_id },
+    contextualResolutionParticipated: Boolean(contextualEvidence?.contextualServiceBindingAttempted),
+    persistedResolution: persistedResolution(row),
+  };
+}
+
+export function runtimeResolution(
+  db: Db,
+  row: TraceGraphRow,
+  evidence: Record<string, unknown>,
+  vars: Record<string, string> | undefined,
+  workspaceId: number | undefined,
+): { 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 resolution = resolveRuntimeOperation(db, substituted, 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 };
+  }
+  const unresolvedReason = runtimeUnresolvedReason(resolution);
+  return { row, evidence: withEffectiveResolution(substituted, row, unresolvedReason, resolution), unresolvedReason };
+}
+
+export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string, unknown> }>): Record<string, unknown> | undefined {
+  const missing = new Set<string>();
+  for (const edge of edges) {
+    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>))
+      for (const key of value.missing ?? []) missing.add(key);
+  }
+  const missingVariables = [...missing].sort();
+  if (missingVariables.length === 0) return undefined;
+  return {
+    severity: 'warning',
+    code: 'trace_runtime_variables_missing',
+    message: `Runtime variables are required to resolve dynamic trace targets: ${missingVariables.join(', ')}`,
+    missingVariables,
+    suggestions: missingVariables.map((key) => `--var ${key}=<value>`),
+  };
+}
+
+export function edgeTarget(row: TraceGraphRow, evidence: Record<string, unknown>): string {
+  const effective = parseObject(evidence.effectiveResolution);
+  const targetServicePath = stringValue(effective.targetServicePath ?? evidence.targetServicePath);
+  const targetOperationPath = stringValue(effective.targetOperationPath ?? evidence.targetOperationPath);
+  if (targetServicePath && targetOperationPath) return `${targetServicePath}${targetOperationPath}`;
+  const runtimeCandidate = evidence.runtimeResolvedCandidate as Candidate | undefined;
+  if (runtimeCandidate?.servicePath && runtimeCandidate.operationPath) return `${runtimeCandidate.servicePath}${runtimeCandidate.operationPath}`;
+  const servicePath = stringValue(evidence.servicePath);
+  const operationPath = stringValue(evidence.operationPath);
+  const targetOperation = stringValue(evidence.targetOperation);
+  const targetRepo = stringValue(evidence.targetRepo) ?? '';
+  if (row.edge_type === 'HANDLER_RUNS_DB_QUERY') return `Entity: ${row.to_id || 'unknown'}`;
+  if (row.edge_type === 'HANDLER_RUNS_REMOTE_QUERY') return stringValue(evidence.remoteQueryTarget) ?? `Remote query: ${row.to_id || 'unknown'}`;
+  if (row.edge_type === 'HANDLER_CALLS_EXTERNAL_HTTP') {
+    const target = parseObject(evidence.externalTarget);
+    return stringValue(target.label) ?? `External endpoint: ${row.to_id || 'unknown'}`;
+  }
+  if (servicePath && operationPath) return `${servicePath}${operationPath}`;
+  return targetOperation ? `${targetRepo}:${targetOperation}` : row.to_id;
+}
+
+function persistedResolution(row: TraceGraphRow): Record<string, unknown> {
+  return {
+    status: row.status,
+    targetKind: row.to_kind,
+    targetId: row.to_id,
+    edgeId: row.id > 0 ? row.id : undefined,
+    confidence: row.confidence,
+    unresolvedReason: row.unresolved_reason,
+    edgeType: row.edge_type,
+  };
+}
+
+function effectiveResolution(
+  row: TraceGraphRow,
+  evidence: Record<string, unknown>,
+  unresolvedReason: string | undefined,
+  resolution?: ReturnType<typeof resolveRuntimeOperation>,
+): Record<string, unknown> {
+  const target = resolution?.target;
+  return {
+    status: target ? 'resolved' : row.status,
+    targetKind: target ? 'operation' : row.to_kind,
+    targetId: target ? String(target.operationId) : row.to_id,
+    targetRepo: target?.repoName ?? evidence.targetRepo,
+    targetServicePath: target?.servicePath ?? evidence.targetServicePath,
+    targetOperationPath: target?.operationPath ?? evidence.targetOperationPath,
+    targetOperation: target?.operationName ?? evidence.targetOperation,
+    confidence: target?.score ?? row.confidence,
+    reasons: resolution?.reasons ?? evidence.resolutionReasons,
+    unresolvedReason,
+    edgeType: target ? 'REMOTE_CALL_RESOLVES_TO_OPERATION' : row.edge_type,
+  };
+}
+
+function withEffectiveResolution(
+  evidence: Record<string, unknown>,
+  row: TraceGraphRow,
+  unresolvedReason: string | undefined,
+  resolution?: ReturnType<typeof resolveRuntimeOperation>,
+): Record<string, unknown> {
+  const current = effectiveResolution(row, evidence, unresolvedReason, resolution);
+  const rest = { ...evidence };
+  delete rest.runtimeResolvedCandidate;
+  return { ...rest, effectiveResolution: current, linker: { status: current.status, confidence: current.confidence, reason: unresolvedReason, edgeType: current.edgeType } };
+}
+
+function resolveRuntimeOperation(db: Db, evidence: Record<string, unknown>, workspaceId: number | undefined): ReturnType<typeof resolveOperation> {
+  const servicePath = stringValue(evidence.servicePath);
+  const rawOperationPath = stringValue(evidence.operationPath);
+  const normalized = normalizeODataOperationInvocationPath(rawOperationPath);
+  const operationPath = normalized?.wasInvocation
+    ? normalized.normalizedOperationPath
+    : stringValue(evidence.normalizedOperationPath) ?? rawOperationPath;
+  const alias = stringValue(evidence.serviceAliasExpr ?? evidence.serviceAlias);
+  const destination = stringValue(evidence.destination);
+  return resolveOperation(db, { servicePath, operationPath, alias, destination, hasExplicitOverride: true, isDynamic: true }, workspaceId);
+}
+
+function evidenceWithRuntimeVariables(evidence: Record<string, unknown>, vars: Record<string, string> | undefined): Record<string, unknown> {
+  const substitutions = runtimeSubstitutions(evidence, vars ?? {});
+  const next: Record<string, unknown> = { ...evidence, runtimeSubstitutions: substitutions };
+  for (const [key, value] of Object.entries(substitutions)) if (value.effective) next[key] = value.effective;
+  const missing = Object.values(substitutions).flatMap((value) => value.missing);
+  if (missing.length > 0) next.missingRuntimeVariables = [...new Set(missing)].sort();
+  if (Object.keys(vars ?? {}).length > 0) next.runtimeVariablesApplied = true;
+  return next;
+}
+
+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);
+    if (substitution.placeholders.length > 0) substitutions[key] = substitution;
+  }
+  return substitutions;
+}
+
+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;
+  if (!['DYNAMIC_EDGE_CANDIDATE', 'UNRESOLVED_EDGE', 'REMOTE_CALL_RESOLVES_TO_OPERATION'].includes(row.edge_type)) return false;
+  return ['servicePath', 'operationPath', 'serviceAliasExpr', 'serviceAlias', 'destination'].some((key) => hasRuntimeVariable(evidence[key], vars));
+}
+
+function hasRuntimeVariable(value: unknown, vars: Record<string, string>): boolean {
+  return typeof value === 'string' && extractPlaceholders(value).some((key) => Object.hasOwn(vars, key));
+}
+
+function runtimeUnresolvedReason(resolution: ReturnType<typeof resolveRuntimeOperation>): string {
+  if (resolution.status === 'dynamic') return `Dynamic target is missing runtime variables: ${resolution.reasons.join(', ')}`;
+  if (resolution.status === 'ambiguous') return 'Ambiguous runtime operation candidates';
+  return 'No runtime operation candidate matched substituted service and operation path';
+}
+
+function parseObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}

package/src/trace/implementation-hints.ts

@@ -0,0 +1,151 @@
+import type { ImplementationHint } from '../types.js';
+
+interface Candidate {
+  accepted?: boolean;
+  methodId?: number;
+  sourceFile?: string;
+  handlerPackage?: { name?: string; packageName?: string };
+  modelPackage?: { name?: string; packageName?: string };
+  servicePath?: string;
+  operationPath?: string;
+}
+
+interface EdgeEvidence {
+  servicePath?: string;
+  operationPath?: string;
+  ambiguityReasons?: string[];
+  candidateFamilies?: Array<{ packageName?: string }>;
+  candidates?: Candidate[];
+  modelPackage?: { name?: string; packageName?: string };
+}
+
+export interface ImplementationSelection {
+  methodId?: string;
+  blocksAutomatic: boolean;
+  evidence: Record<string, unknown>;
+}
+
+export function parseImplementationHint(value: string): ImplementationHint {
+  const hint: Partial<ImplementationHint> = {};
+  for (const part of value.split(',')) {
+    const separator = part.indexOf('=');
+    if (separator <= 0 || separator === part.length - 1) throw new Error(`Invalid implementation hint field: ${part}`);
+    assignHintField(hint, part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+  }
+  if (!hint.implementationRepo) throw new Error('Scoped implementation hint requires an implementation repo selection');
+  return { ...hint, implementationRepo: hint.implementationRepo };
+}
+
+export function selectImplementation(
+  rawEvidence: Record<string, unknown>,
+  hints: ImplementationHint[] | undefined,
+  legacyRepo: string | undefined,
+): ImplementationSelection {
+  const evidence = asEvidence(rawEvidence);
+  const scoped = hints ?? [];
+  const matchingHints = scoped.filter((hint) => hintMatchesEdge(hint, evidence));
+  if (matchingHints.length === 0) {
+    if (legacyRepo) return selectCandidate(evidence, legacyHint(legacyRepo), 'implementation_repo_hint');
+    const reason = scoped.length > 0 ? 'no_scoped_hint_matched_edge' : 'no_implementation_hint_supplied';
+    return { blocksAutomatic: false, evidence: { status: 'not_matched', reason, strategy: 'scoped_implementation_hint' } };
+  }
+  if (matchingHints.length > 1) {
+    return {
+      blocksAutomatic: true,
+      evidence: {
+        status: 'tied',
+        reason: 'multiple_scoped_hints_matched_edge',
+        strategy: 'scoped_implementation_hint',
+        matchedHints: matchingHints,
+        candidateCount: matchingHints.length,
+      },
+    };
+  }
+  const hint = matchingHints[0];
+  return hint ? selectCandidate(evidence, hint, 'scoped_implementation_hint') : { blocksAutomatic: false, evidence: { status: 'not_matched' } };
+}
+
+export function implementationHintDiagnostic(selection: ImplementationSelection): Record<string, unknown> | undefined {
+  if (!selection.blocksAutomatic || selection.methodId) return undefined;
+  return {
+    severity: 'warning',
+    code: 'implementation_hint_mismatch',
+    message: 'Implementation hint did not select exactly one viable candidate',
+    hintStatus: selection.evidence.status,
+    candidateCount: selection.evidence.candidateCount,
+    implementationSelection: selection.evidence,
+  };
+}
+
+function assignHintField(hint: Partial<ImplementationHint>, key: string, value: string): void {
+  if (key === 'service' || key === 'servicePath') hint.servicePath = value;
+  else if (key === 'operation' || key === 'operationPath') hint.operationPath = value;
+  else if (key === 'package' || key === 'packageName') hint.packageName = value;
+  else if (key === 'repository' || key === 'repositoryName') hint.repositoryName = value;
+  else if (key === 'family' || key === 'candidateFamily') hint.candidateFamily = value;
+  else if (key === 'repo' || key === 'implementationRepo' || key === 'select') hint.implementationRepo = value;
+  else throw new Error(`Unknown implementation hint field: ${key}`);
+}
+
+function selectCandidate(evidence: EdgeEvidence, hint: ImplementationHint, strategy: string): ImplementationSelection {
+  const matches = (evidence.candidates ?? []).filter((candidate) =>
+    candidate.accepted && candidateMatchesRepo(candidate, hint.implementationRepo));
+  const selected = matches.length === 1 ? matches[0] : undefined;
+  if (!selected || selected.methodId === undefined) {
+    return {
+      blocksAutomatic: true,
+      evidence: {
+        status: matches.length > 1 ? 'tied' : 'not_matched',
+        reason: matches.length > 1 ? 'hint_matched_multiple_candidates' : 'hint_matched_zero_candidates',
+        strategy,
+        matchedHint: hint,
+        selectedRepo: hint.implementationRepo,
+        candidateCount: matches.length,
+      },
+    };
+  }
+  return {
+    methodId: String(selected.methodId),
+    blocksAutomatic: false,
+    evidence: {
+      status: 'selected',
+      guided: true,
+      strategy,
+      matchedHint: hint,
+      selectedRepo: hint.implementationRepo,
+      selectedMethodId: selected.methodId,
+      ambiguityReason: evidence.ambiguityReasons?.[0],
+    },
+  };
+}
+
+function hintMatchesEdge(hint: ImplementationHint, evidence: EdgeEvidence): boolean {
+  const model = evidence.modelPackage ?? evidence.candidates?.[0]?.modelPackage;
+  const familyNames = new Set([
+    ...(evidence.candidateFamilies ?? []).flatMap((family) => family.packageName ? [family.packageName] : []),
+    ...(evidence.candidates ?? []).flatMap((candidate) => candidate.handlerPackage?.packageName ? [candidate.handlerPackage.packageName] : []),
+  ]);
+  return matches(hint.servicePath, evidence.servicePath ?? evidence.candidates?.[0]?.servicePath)
+    && matches(hint.operationPath, evidence.operationPath ?? evidence.candidates?.[0]?.operationPath)
+    && matches(hint.packageName, model?.packageName)
+    && matches(hint.repositoryName, model?.name)
+    && (!hint.candidateFamily || familyNames.has(hint.candidateFamily));
+}
+
+function candidateMatchesRepo(candidate: Candidate, value: string): boolean {
+  return candidate.handlerPackage?.name === value
+    || candidate.handlerPackage?.packageName === value
+    || candidate.sourceFile?.startsWith(value) === true;
+}
+
+function matches(expected: string | undefined, actual: string | undefined): boolean {
+  return expected === undefined || expected === actual;
+}
+
+function legacyHint(implementationRepo: string): ImplementationHint {
+  return { implementationRepo };
+}
+
+function asEvidence(value: Record<string, unknown>): EdgeEvidence {
+  return value as EdgeEvidence;
+}