@saptools/service-flow 0.1.42 → 0.1.44

package/src/parsers/service-binding-parser.ts

@@ -1,250 +1,21 @@
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import ts from 'typescript';
 import type { ServiceBindingFact } from '../types.js';
 import { normalizePath } from '../utils/path-utils.js';
+import {
+  connectFactFromCall,
+  findConnectInExpression,
+  importsFor,
+  lineOf,
+  readSource,
+  transactionReceiverName,
+  unwrapCall,
+  unwrapIdentityExpression,
+  type ClassHelperReturn,
+  type HelperBinding,
+  type ImportBinding,
+} from './service-binding-parser-helpers.js';
 
-interface HelperBinding {
-  exportedName: string;
-  returnedProperty?: string;
-  alias?: string;
-  aliasExpr?: string;
-  destinationExpr?: string;
-  servicePathExpr?: string;
-  isDynamic: boolean;
-  placeholders: string[];
-  helperChain?: Array<Record<string, unknown>>;
-  sourceFile: string;
-  sourceLine: number;
-}
-interface ImportBinding {
-  localName: string;
-  exportedName: string;
-  sourceFile?: string;
-}
-interface ClassHelperReturn {
-  className: string;
-  helperName: string;
-  propertyName: string;
-  variableName: string;
-  fact: Omit<HelperBinding, 'exportedName' | 'sourceFile' | 'sourceLine'>;
-  sourceLine: number;
-}
-
-function lineOf(sf: ts.SourceFile, node: ts.Node): number {
-  return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
-}
-function stringValue(node: ts.Expression | undefined): string | undefined {
-  if (!node) return undefined;
-  if (ts.isStringLiteralLike(node) || ts.isNoSubstitutionTemplateLiteral(node))
-    return node.text;
-  if (ts.isTemplateExpression(node))
-    return node.getText().replace(/^`|`$/g, '');
-  return node.getText();
-}
-function placeholders(value?: string): string[] {
-  return [...(value ?? '').matchAll(/\$\{([^}]*)\}/g)]
-    .map((m) => (m[1] ?? '').trim())
-    .filter(Boolean);
-}
-function connectFactFromCall(
-  call: ts.CallExpression,
-):
-  | Omit<HelperBinding, 'exportedName' | 'sourceFile' | 'sourceLine'>
-  | undefined {
-  const expr = call.expression;
-  if (!ts.isPropertyAccessExpression(expr) || expr.name.text !== 'to')
-    return undefined;
-  const inner = expr.expression;
-  if (
-    !ts.isPropertyAccessExpression(inner) ||
-    inner.name.text !== 'connect' ||
-    inner.expression.getText() !== 'cds'
-  )
-    return undefined;
-  const first = call.arguments[0];
-  if (!first) return undefined;
-  const second = call.arguments[1];
-  const objectArg = ts.isObjectLiteralExpression(first)
-    ? first
-    : second && ts.isObjectLiteralExpression(second)
-      ? second
-      : undefined;
-  let alias: string | undefined;
-  let aliasExpr: string | undefined;
-  if (ts.isStringLiteralLike(first) || ts.isNoSubstitutionTemplateLiteral(first))
-    alias = first.text;
-  else if (!ts.isObjectLiteralExpression(first))
-    aliasExpr = stringValue(first);
-  if (
-    (ts.isStringLiteralLike(first) || ts.isNoSubstitutionTemplateLiteral(first)) &&
-    !objectArg
-  )
-    return { alias: first.text, isDynamic: false, placeholders: [] };
-  if (!objectArg && aliasExpr)
-    return {
-      aliasExpr,
-      isDynamic: true,
-      placeholders: placeholders(aliasExpr),
-    };
-  let destinationExpr: string | undefined;
-  let servicePathExpr: string | undefined;
-  function visitObject(obj: ts.ObjectLiteralExpression): void {
-    for (const prop of obj.properties) {
-      if (!ts.isPropertyAssignment(prop)) continue;
-      const name =
-        ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name)
-          ? prop.name.text
-          : undefined;
-      if (name === 'destination')
-        destinationExpr = stringValue(prop.initializer);
-      if (name === 'path' || name === 'servicePath')
-        servicePathExpr = stringValue(prop.initializer);
-      if (ts.isObjectLiteralExpression(prop.initializer))
-        visitObject(prop.initializer);
-    }
-  }
-  if (objectArg) visitObject(objectArg);
-  const ph = [
-    ...placeholders(aliasExpr ?? alias),
-    ...placeholders(destinationExpr),
-    ...placeholders(servicePathExpr),
-  ];
-  return {
-    alias,
-    aliasExpr,
-    destinationExpr,
-    servicePathExpr,
-    isDynamic: ph.length > 0 || (!destinationExpr && !servicePathExpr),
-    placeholders: ph,
-  };
-}
-function unwrapCall(expr: ts.Expression): ts.CallExpression | undefined {
-  if (ts.isAwaitExpression(expr)) return unwrapCall(expr.expression);
-  if (ts.isParenthesizedExpression(expr)) return unwrapCall(expr.expression);
-  if (ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr)) return unwrapCall(expr.expression);
-  if (ts.isTypeAssertionExpression(expr)) return unwrapCall(expr.expression);
-  if (ts.isCallExpression(expr)) return expr;
-  return undefined;
-}
-function unwrapIdentityExpression(expr: ts.Expression): ts.Expression {
-  if (ts.isAwaitExpression(expr)) return unwrapIdentityExpression(expr.expression);
-  if (ts.isParenthesizedExpression(expr)) return unwrapIdentityExpression(expr.expression);
-  if (ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr)) return unwrapIdentityExpression(expr.expression);
-  if (ts.isTypeAssertionExpression(expr)) return unwrapIdentityExpression(expr.expression);
-  return expr;
-}
-
-function transactionReceiverName(expr: ts.Expression): string | undefined {
-  const call = unwrapCall(expr);
-  if (call && ts.isPropertyAccessExpression(call.expression) && ['tx', 'transaction'].includes(call.expression.name.text) && ts.isIdentifier(call.expression.expression)) return call.expression.expression.text;
-  const unwrapped = unwrapIdentityExpression(expr);
-  if (ts.isConditionalExpression(unwrapped)) {
-    const left = transactionReceiverName(unwrapped.whenTrue);
-    const right = transactionReceiverName(unwrapped.whenFalse);
-    return left && left === right ? left : undefined;
-  }
-  return undefined;
-}
-
-function findConnectInExpression(
-  expr: ts.Expression,
-):
-  | Omit<HelperBinding, 'exportedName' | 'sourceFile' | 'sourceLine'>
-  | undefined {
-  const direct = unwrapCall(expr);
-  if (direct) {
-    const fact = connectFactFromCall(direct);
-    if (fact) return fact;
-  }
-  let found:
-    | Omit<HelperBinding, 'exportedName' | 'sourceFile' | 'sourceLine'>
-    | undefined;
-  function visit(node: ts.Node): void {
-    if (found) return;
-    if (ts.isCallExpression(node)) found = connectFactFromCall(node);
-    if (!found) ts.forEachChild(node, visit);
-  }
-  visit(expr);
-  return found;
-}
-async function readSource(abs: string): Promise<ts.SourceFile | undefined> {
-  try {
-    const text = await fs.readFile(abs, 'utf8');
-    return ts.createSourceFile(
-      abs,
-      text,
-      ts.ScriptTarget.Latest,
-      true,
-      ts.ScriptKind.TS,
-    );
-  } catch {
-    return undefined;
-  }
-}
-async function resolveImport(
-  repoPath: string,
-  fromFile: string,
-  spec: string,
-): Promise<string | undefined> {
-  if (!spec.startsWith('.')) return undefined;
-  const rawBase = path.resolve(repoPath, path.dirname(fromFile), spec);
-  const parsed = path.parse(rawBase);
-  const base = ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(parsed.ext)
-    ? path.join(parsed.dir, parsed.name)
-    : rawBase;
-  for (const candidate of [
-    base,
-    `${base}.ts`,
-    `${base}.js`,
-    path.join(base, 'index.ts'),
-    path.join(base, 'index.js'),
-  ]) {
-    try {
-      const st = await fs.stat(candidate);
-      if (st.isFile()) return normalizePath(path.relative(repoPath, candidate));
-    } catch {
-      /* continue */
-    }
-  }
-  return undefined;
-}
-async function importsFor(
-  repoPath: string,
-  filePath: string,
-  sf: ts.SourceFile,
-): Promise<ImportBinding[]> {
-  const imports: ImportBinding[] = [];
-  for (const stmt of sf.statements) {
-    if (
-      !ts.isImportDeclaration(stmt) ||
-      !ts.isStringLiteralLike(stmt.moduleSpecifier)
-    )
-      continue;
-    const sourceFile = await resolveImport(
-      repoPath,
-      filePath,
-      stmt.moduleSpecifier.text,
-    );
-    const clause = stmt.importClause;
-    if (!clause) continue;
-    if (clause.name)
-      imports.push({
-        localName: clause.name.text,
-        exportedName: 'default',
-        sourceFile,
-      });
-    const bindings = clause.namedBindings;
-    if (bindings && ts.isNamedImports(bindings))
-      for (const el of bindings.elements)
-        imports.push({
-          localName: el.name.text,
-          exportedName: el.propertyName?.text ?? el.name.text,
-          sourceFile,
-        });
-  }
-  return imports;
-}
 function collectLocalBindingFacts(
   fn: ts.FunctionLikeDeclaration,
 ): Map<string, Omit<HelperBinding, 'exportedName' | 'sourceFile' | 'sourceLine'>> {
@@ -434,6 +205,7 @@ export async function parseServiceBindings(
   const classHelpers = collectClassHelpers(sourceFileAst);
   const localObjectHelpers = new Map<string, HelperBinding[]>();
   const localDirectHelpers = new Map<string, HelperBinding>();
+  const objectHelperVariables = new Map<string, Array<{ helper: HelperBinding; imp?: ImportBinding }>>();
   for (const stmt of sourceFileAst.statements) {
     if (ts.isFunctionDeclaration(stmt) && stmt.name) {
       const directFact = directConnectFactFromFunctionLike(stmt);
@@ -562,6 +334,46 @@ export async function parseServiceBindings(
     const imported = await importedHelpers(call.expression.text);
     return [...local.map((helper) => ({ helper })), ...imported];
   }
+  async function rememberObjectHelperVariable(decl: ts.VariableDeclaration): Promise<void> {
+    if (!ts.isIdentifier(decl.name) || !decl.initializer) return;
+    const call = unwrapCall(decl.initializer);
+    if (!call) return;
+    const helpers = (await helpersForCall(call)).filter((row) => row.helper.returnedProperty);
+    if (helpers.length > 0) objectHelperVariables.set(decl.name.text, helpers);
+  }
+  function recordObjectPropertyBinding(targetName: string, expr: ts.Expression, node: ts.Node): boolean {
+    const unwrapped = unwrapIdentityExpression(expr);
+    if (!ts.isPropertyAccessExpression(unwrapped) || !ts.isIdentifier(unwrapped.expression)) return false;
+    const helpers = objectHelperVariables.get(unwrapped.expression.text) ?? [];
+    const matches = helpers.filter((row) => row.helper.returnedProperty === unwrapped.name.text);
+    if (matches.length !== 1) return false;
+    const resolved = matches[0];
+    out.push({
+      variableName: targetName,
+      alias: resolved.helper.alias,
+      aliasExpr: resolved.helper.aliasExpr,
+      destinationExpr: resolved.helper.destinationExpr,
+      servicePathExpr: resolved.helper.servicePathExpr,
+      isDynamic: resolved.helper.isDynamic,
+      placeholders: resolved.helper.placeholders,
+      sourceFile: normalizePath(filePath),
+      sourceLine: lineOf(sourceFileAst, node),
+      helperChain: [
+        ...(resolved.helper.helperChain ?? []),
+        {
+          callerVariable: targetName,
+          sourceVariable: unwrapped.expression.text,
+          returnedProperty: unwrapped.name.text,
+          assignedFromProperty: unwrapped.getText(sourceFileAst),
+          importSource: resolved.imp?.sourceFile,
+          exportedSymbol: resolved.imp?.exportedName,
+          helperSourceFile: resolved.helper.sourceFile,
+          helperSourceLine: resolved.helper.sourceLine,
+        },
+      ],
+    });
+    return true;
+  }
   async function recordDestructuredHelper(decl: ts.VariableDeclaration): Promise<void> {
     if (!ts.isObjectBindingPattern(decl.name) || !decl.initializer) return;
     const call = unwrapCall(decl.initializer);
@@ -737,6 +549,8 @@ export async function parseServiceBindings(
       await recordDestructuredHelper(decl);
       await recordArrayDestructuredVariable(decl);
       recordDestructuredClassHelper(decl);
+      await rememberObjectHelperVariable(decl);
+      if (ts.isIdentifier(decl.name) && decl.initializer) recordObjectPropertyBinding(decl.name.text, decl.initializer, decl);
       await recordVariable(decl);
       recordIdentityAlias(decl);
       if (ts.isIdentifier(decl.name) && decl.initializer) {
@@ -752,6 +566,7 @@ export async function parseServiceBindings(
         cloneAliasBinding(assignment.left.text, rhs.text, 'identity-assignment', assignment);
         continue;
       }
+      if (recordObjectPropertyBinding(assignment.left.text, assignment.right, assignment)) continue;
       await recordBindingFromExpression(assignment.left.text, assignment.right, assignment, 'assignment');
       continue;
     }

package/src/trace/evidence.ts

@@ -0,0 +1,205 @@
+import type { Db } from '../db/connection.js';
+import { extractPlaceholders, substituteVariables, type RuntimeSubstitution } from '../linker/dynamic-edge-resolver.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 operationPath = stringValue(evidence.normalizedOperationPath ?? evidence.operationPath);
+  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;
+}