@saptools/service-flow 0.1.37 → 0.1.39

package/src/linker/odata-path-normalizer.ts

@@ -0,0 +1,236 @@
+export interface NormalizedODataOperationPath {
+  rawOperationPath: string;
+  normalizedOperationPath: string;
+  wasInvocation: boolean;
+  invocationArgumentPlaceholderKeys: string[];
+  normalizationReason?: string;
+  normalizationRejectedReason?: string;
+}
+
+export type ODataPathIntentKind = 'operation_invocation' | 'entity_query' | 'entity_key_read' | 'entity_navigation_query' | 'entity_mutation' | 'entity_delete' | 'entity_media' | 'entity_candidate' | 'unknown';
+
+export interface ODataPathIntent {
+  kind: ODataPathIntentKind;
+  rawPath: string;
+  method: string;
+  pathWithoutQuery: string;
+  queryString?: string;
+  hasQueryString: boolean;
+  entitySegment?: string;
+  placeholderKeys: string[];
+  keyPredicatePlaceholderKeys: string[];
+  invocationArgumentPlaceholderKeys: string[];
+  navigationSuffix?: string;
+  mediaOrPropertySuffix?: string;
+  hasEntityKeyPredicate: boolean;
+  hasNavigationSuffix: boolean;
+  hasMediaOrPropertySuffix: boolean;
+  topLevelOperationName?: string;
+  topLevelOperationNameCandidate: boolean;
+  topLevelOperationInvocation: boolean;
+  reason: string;
+}
+
+export function normalizeODataOperationInvocationPath(path: string | undefined): NormalizedODataOperationPath | undefined {
+  if (path === undefined) return undefined;
+  const raw = path.trim();
+  if (!raw) return undefined;
+  const rejected = (reason: string): NormalizedODataOperationPath => ({ rawOperationPath: raw, normalizedOperationPath: raw, wasInvocation: false, invocationArgumentPlaceholderKeys: [], normalizationRejectedReason: reason });
+  const open = raw.indexOf('(');
+  if (open < 0) return rejected('no_top_level_parenthesis');
+  const query = topLevelQueryIndex(raw);
+  if (query >= 0) return rejected('query_string_paths_are_not_operation_invocations');
+  if (!raw.startsWith('/')) return rejected('path_is_not_absolute');
+  if (raw.slice(1, open).includes('/')) return rejected('operation_segment_contains_navigation_separator');
+  const close = matchingClose(raw, open);
+  if (close === undefined) return rejected('top_level_invocation_parenthesis_is_unbalanced');
+  if (raw.slice(close + 1).trim().length > 0) return rejected('top_level_invocation_does_not_cover_remaining_path');
+  const operationSegment = raw.slice(0, open).trim();
+  if (operationSegment.length <= 1) return rejected('operation_segment_is_empty');
+  return {
+    rawOperationPath: raw,
+    normalizedOperationPath: operationSegment,
+    wasInvocation: true,
+    invocationArgumentPlaceholderKeys: [...new Set(extractTemplatePlaceholders(raw.slice(open + 1, close)))],
+    normalizationReason: 'balanced_top_level_operation_invocation',
+  };
+}
+
+export function classifyODataPathIntent(path: string | undefined, method: string | undefined): ODataPathIntent {
+  const rawPath = (path ?? '').trim();
+  const normalizedMethod = (method ?? 'GET').trim().toUpperCase() || 'GET';
+  const queryIndex = rawPath.indexOf('?');
+  const pathWithoutQuery = queryIndex >= 0 ? rawPath.slice(0, queryIndex) : rawPath;
+  const queryString = queryIndex >= 0 ? rawPath.slice(queryIndex + 1) : undefined;
+  const segments = pathWithoutQuery.replace(/^\//, '').split('/').filter(Boolean);
+  const firstSegment = segments[0] ?? '';
+  const hasNavigationSegments = segments.length > 1;
+  const entitySegment = entitySegmentFromPath(pathWithoutQuery);
+  const placeholderKeys = [...new Set(extractTemplatePlaceholders(rawPath))];
+  const firstOpen = firstSegment.indexOf('(');
+  const firstClose = firstOpen >= 0 ? matchingClose(firstSegment, firstOpen) : undefined;
+  const keyPredicateText = firstOpen >= 0 && firstClose !== undefined ? firstSegment.slice(firstOpen + 1, firstClose) : '';
+  const rawKeyPredicatePlaceholderKeys = [...new Set(extractTemplatePlaceholders(keyPredicateText))];
+  const navigationSuffix = hasNavigationSegments ? segments.slice(1).join('/') : undefined;
+  const lastSegment = segments.at(-1) ?? '';
+  const mediaOrPropertySuffix = hasNavigationSegments ? lastSegment : undefined;
+  const invocation = normalizeODataOperationInvocationPath(pathWithoutQuery);
+  const operationNameFromInvocation = invocation?.wasInvocation ? invocation.normalizedOperationPath.replace(/^\//, '').split('.').at(-1) : undefined;
+  const topLevelName = firstSegment.split('(')[0]?.replace(/^\//, '');
+  const topLevelOperationName = operationNameFromInvocation ?? (!hasNavigationSegments && !firstSegment.includes('(') ? topLevelName : undefined);
+  const topLevelOperationInvocation = Boolean(invocation?.wasInvocation && looksLikeLowerCamelInvocation(firstSegment));
+  const keyPredicatePlaceholderKeys = topLevelOperationInvocation ? [] : rawKeyPredicatePlaceholderKeys;
+  const topLevelOperationNameCandidate = Boolean(topLevelOperationName && !hasNavigationSegments && !firstSegment.includes('('));
+  const base = { rawPath, method: normalizedMethod, pathWithoutQuery, queryString, hasQueryString: queryIndex >= 0, entitySegment, placeholderKeys, keyPredicatePlaceholderKeys, invocationArgumentPlaceholderKeys: invocation?.invocationArgumentPlaceholderKeys ?? [], navigationSuffix, mediaOrPropertySuffix, hasEntityKeyPredicate: firstOpen >= 0 && firstClose !== undefined, hasNavigationSuffix: hasNavigationSegments, hasMediaOrPropertySuffix: Boolean(mediaOrPropertySuffix && isMediaOrPropertySuffix(mediaOrPropertySuffix)), topLevelOperationName, topLevelOperationNameCandidate, topLevelOperationInvocation };
+  if (!rawPath || !rawPath.startsWith('/')) return { ...base, kind: 'unknown', reason: 'path_missing_or_not_absolute' };
+  const upperEntityLike = /^[A-Z][A-Za-z0-9_]*$/.test(entitySegment ?? firstSegment);
+  const mediaLike = isMediaOrPropertySuffix(segments.at(-1) ?? '');
+  if (normalizedMethod !== 'GET') {
+    if (invocation?.wasInvocation && looksLikeLowerCamelInvocation(firstSegment)) return { ...base, kind: 'operation_invocation', reason: 'non_get_balanced_top_level_operation_invocation' };
+    if (mediaLike) return { ...base, kind: 'entity_media', reason: 'non_get_entity_media_stream_path' };
+    if (hasNavigationSegments || firstSegment.includes('(')) return { ...base, kind: normalizedMethod === 'DELETE' ? 'entity_delete' : 'entity_mutation', reason: firstSegment.includes('(') ? 'non_get_entity_key_or_navigation_path_shape' : 'non_get_entity_navigation_path_shape' };
+    if (upperEntityLike) return { ...base, kind: normalizedMethod === 'DELETE' ? 'entity_delete' : 'entity_mutation', reason: 'non_get_entity_path_shape' };
+    return { ...base, kind: 'operation_invocation', reason: 'non_get_lowercase_path_may_be_operation' };
+  }
+  if (queryIndex >= 0) {
+    if (hasNavigationSegments) return { ...base, kind: 'entity_navigation_query', reason: 'get_path_has_navigation_and_query_string' };
+    if (looksLikeLowerCamelInvocation(firstSegment)) return { ...base, kind: 'unknown', reason: 'get_invocation_with_query_string_requires_indexed_operation_evidence' };
+    return { ...base, kind: 'entity_query', reason: 'get_collection_path_has_query_string' };
+  }
+  if (hasNavigationSegments) return mediaLike ? { ...base, kind: 'entity_media', reason: 'get_entity_media_stream_path' } : { ...base, kind: 'entity_navigation_query', reason: 'get_path_has_navigation_segments' };
+  if (firstSegment.includes('(')) {
+    if (invocation?.wasInvocation && looksLikeLowerCamelInvocation(firstSegment)) return { ...base, kind: 'operation_invocation', reason: 'get_balanced_top_level_operation_invocation' };
+    return looksLikeLowerCamelInvocation(firstSegment)
+      ? { ...base, kind: 'operation_invocation', reason: 'get_single_lower_camel_segment_has_top_level_invocation' }
+      : { ...base, kind: 'entity_key_read', reason: 'get_entity_segment_has_key_predicate' };
+  }
+  if (/^[A-Z][A-Za-z0-9_]*$/.test(firstSegment)) return { ...base, kind: 'entity_candidate', reason: 'uppercase_collection_segment_without_indexed_entity_evidence' };
+  return { ...base, kind: 'unknown', reason: 'get_path_has_no_query_key_or_navigation_signal' };
+}
+
+function entitySegmentFromPath(path: string): string | undefined {
+  const first = path.replace(/^\//, '').split('/')[0]?.trim();
+  if (!first) return undefined;
+  const open = first.indexOf('(');
+  const entity = (open >= 0 ? first.slice(0, open) : first).trim();
+  return entity || undefined;
+}
+
+function isMediaOrPropertySuffix(segment: string): boolean {
+  return ['file', 'content', '$value', 'metadata', 'items'].includes(segment.toLowerCase());
+}
+
+function looksLikeLowerCamelInvocation(segment: string): boolean {
+  const open = segment.indexOf('(');
+  if (open <= 0) return false;
+  const name = segment.slice(0, open).split('.').at(-1) ?? segment.slice(0, open);
+  return /^[a-z][A-Za-z0-9_]*$/.test(name);
+}
+
+function extractTemplatePlaceholders(text: string): string[] {
+  const keys: string[] = [];
+  for (let index = 0; index < text.length - 1; index += 1) {
+    if (text[index] !== '$' || text[index + 1] !== '{') continue;
+    const close = matchingPlaceholderClose(text, index + 1);
+    if (close === undefined) continue;
+    const key = text.slice(index + 2, close).trim();
+    if (key) keys.push(key);
+    index = close;
+  }
+  return keys;
+}
+
+function matchingClose(text: string, openIndex: number): number | undefined {
+  let depth = 0;
+  let quote: 'single' | 'double' | 'template' | undefined;
+  for (let index = openIndex; index < text.length; index += 1) {
+    const char = text[index];
+    const prev = text[index - 1];
+    if (quote) {
+      if (prev === '\\') continue;
+      if (quote === 'template' && char === '$' && text[index + 1] === '{') {
+        const close = matchingPlaceholderClose(text, index + 1);
+        if (close === undefined) return undefined;
+        index = close;
+        continue;
+      }
+      if ((quote === 'single' && char === "'") || (quote === 'double' && char === '"') || (quote === 'template' && char === '`')) quote = undefined;
+      continue;
+    }
+    if (char === '$' && text[index + 1] === '{') {
+      const close = matchingPlaceholderClose(text, index + 1);
+      if (close === undefined) return undefined;
+      index = close;
+      continue;
+    }
+    if (char === "'") { quote = 'single'; continue; }
+    if (char === '"') { quote = 'double'; continue; }
+    if (char === '`') { quote = 'template'; continue; }
+    if (char === '(') depth += 1;
+    if (char === ')') {
+      depth -= 1;
+      if (depth === 0) return index;
+      if (depth < 0) return undefined;
+    }
+  }
+  return undefined;
+}
+
+function matchingPlaceholderClose(text: string, openBraceIndex: number): number | undefined {
+  let depth = 0;
+  let quote: 'single' | 'double' | 'template' | undefined;
+  for (let index = openBraceIndex; index < text.length; index += 1) {
+    const char = text[index];
+    const prev = text[index - 1];
+    if (quote) {
+      if (prev === '\\') continue;
+      if (quote === 'template' && char === '$' && text[index + 1] === '{') {
+        depth += 1;
+        index += 1;
+        continue;
+      }
+      if ((quote === 'single' && char === "'") || (quote === 'double' && char === '"') || (quote === 'template' && char === '`')) quote = undefined;
+      continue;
+    }
+    if (char === "'") { quote = 'single'; continue; }
+    if (char === '"') { quote = 'double'; continue; }
+    if (char === '`') { quote = 'template'; continue; }
+    if (char === '{') depth += 1;
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) return index;
+      if (depth < 0) return undefined;
+    }
+  }
+  return undefined;
+}
+
+function topLevelQueryIndex(text: string): number {
+  let quote: 'single' | 'double' | 'template' | undefined;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    const prev = text[index - 1];
+    if (quote) {
+      if (prev === '\\') continue;
+      if (quote === 'template' && char === '$' && text[index + 1] === '{') {
+        const close = matchingPlaceholderClose(text, index + 1);
+        if (close === undefined) return -1;
+        index = close;
+        continue;
+      }
+      if ((quote === 'single' && char === "'") || (quote === 'double' && char === '"') || (quote === 'template' && char === '`')) quote = undefined;
+      continue;
+    }
+    if (char === '$' && text[index + 1] === '{') {
+      const close = matchingPlaceholderClose(text, index + 1);
+      if (close === undefined) return -1;
+      index = close;
+      continue;
+    }
+    if (char === "'") { quote = 'single'; continue; }
+    if (char === '"') { quote = 'double'; continue; }
+    if (char === '`') { quote = 'template'; continue; }
+    if (char === '?') return index;
+  }
+  return -1;
+}

package/src/linker/operation-decorator-normalizer.ts

@@ -0,0 +1,47 @@
+function lowerFirst(value: string): string {
+  return value ? `${value[0]?.toLowerCase() ?? ''}${value.slice(1)}` : value;
+}
+export type DecoratorOperationSignal =
+  | { status: 'resolved'; operationName: string; raw?: string }
+  | { status: 'none'; raw?: string }
+  | { status: 'unsupported'; raw: string; reason: string }
+  | { status: 'malformed'; raw: string; reason: string };
+export function normalizedOperationName(value: string): string {
+  return value.replace(/^\//, '');
+}
+function clean(value: string): string {
+  return value.replace(/^[`'"]|[`'"]$/g, '');
+}
+function generatedFromConstantName(value: string): string | undefined {
+  for (const prefix of ['Action', 'Func']) {
+    if (value.startsWith(prefix) && value.length > prefix.length && /^[A-Z]/.test(value.slice(prefix.length))) return lowerFirst(value.slice(prefix.length));
+  }
+  return undefined;
+}
+function resolved(value: string, raw?: string): DecoratorOperationSignal {
+  const literal = clean(value);
+  const generated = generatedFromConstantName(literal);
+  return { status: 'resolved', operationName: generated ?? normalizedOperationName(literal), raw };
+}
+export function normalizeDecoratorOperationSignal(value: string | undefined, raw: string | undefined, candidateOperation?: string): DecoratorOperationSignal {
+  if (value) return resolved(value, raw);
+  if (!raw || raw.trim().length === 0) return { status: 'none', raw };
+  const expression = raw.trim();
+  const nameMatch = /(?:^|\.)(Action[A-Z][\w$]*|Func[A-Z][\w$]*)\.name$/.exec(expression);
+  if (nameMatch?.[1]) return resolved(nameMatch[1], expression);
+  const stringMatch = /^String\(([A-Za-z_$][\w$]*)\)$/.exec(expression);
+  if (stringMatch?.[1]) {
+    const identifier = stringMatch[1];
+    const generated = generatedFromConstantName(identifier);
+    const normalizedCandidate = candidateOperation ? normalizedOperationName(candidateOperation) : undefined;
+    if (generated) return { status: 'resolved', operationName: generated, raw: expression };
+    if (normalizedCandidate && identifier === normalizedCandidate) return { status: 'resolved', operationName: identifier, raw: expression };
+    return { status: 'unsupported', raw: expression, reason: 'string_wrapper_identifier_not_resolved' };
+  }
+  if (/^[`'"]/.test(expression) && !/[`'"]$/.test(expression)) return { status: 'malformed', raw: expression, reason: 'unterminated_literal' };
+  return { status: 'unsupported', raw: expression, reason: 'unsupported_decorator_expression' };
+}
+export function normalizeDecoratorOperation(value: string | undefined, raw: string | undefined): string | undefined {
+  const signal = normalizeDecoratorOperationSignal(value, raw);
+  return signal.status === 'resolved' ? signal.operationName : undefined;
+}

package/src/linker/remote-query-target.ts

@@ -0,0 +1,39 @@
+export interface RemoteQueryTargetInput {
+  queryEntity?: unknown;
+  servicePath?: string;
+  serviceAlias?: unknown;
+  serviceAliasExpr?: unknown;
+  destination?: string;
+  isDynamic?: boolean;
+  parserWarning?: unknown;
+}
+
+export interface RemoteQueryTarget {
+  toKind: 'remote_entity' | 'remote_query';
+  toId: string;
+  label: string;
+  evidence: Record<string, unknown>;
+}
+
+export function buildRemoteQueryTarget(input: RemoteQueryTargetInput): RemoteQueryTarget {
+  const entity = typeof input.queryEntity === 'string' && input.queryEntity.trim() ? input.queryEntity.trim() : undefined;
+  const servicePath = input.servicePath?.trim();
+  const prefix = servicePath ? `${servicePath}:` : '';
+  const label = entity ? `Remote entity: ${prefix}${entity}` : 'Remote query: unknown';
+  return {
+    toKind: entity ? 'remote_entity' : 'remote_query',
+    toId: entity ? `${prefix}${entity}` : 'unknown',
+    label,
+    evidence: {
+      remoteQueryTarget: label,
+      queryEntity: entity,
+      queryTargetKind: entity ? 'remote_entity' : 'remote_query_unknown',
+      queryEntityDynamic: entity ? undefined : Boolean(input.isDynamic) || undefined,
+      serviceAlias: input.serviceAlias,
+      serviceAliasExpr: input.serviceAliasExpr,
+      destination: input.destination,
+      servicePath,
+      parserWarning: entity ? input.parserWarning : input.parserWarning ?? { code: 'query_entity_unknown', message: 'Remote query entity is dynamic or unavailable' },
+    },
+  };
+}

package/src/linker/service-resolver.ts

@@ -0,0 +1,223 @@
+import type { Db } from '../db/connection.js';
+export interface OperationTarget {
+  operationId: number;
+  repoName: string;
+  serviceName: string;
+  qualifiedName: string;
+  servicePath: string;
+  operationPath: string;
+  operationName: string;
+  sourceFile: string;
+  sourceLine: number;
+  repoId?: number;
+  packageName?: string | null;
+  score: number;
+  reasons: string[];
+}
+export interface OperationResolution {
+  status: 'resolved' | 'ambiguous' | 'unresolved' | 'dynamic';
+  target?: OperationTarget;
+  candidates: OperationTarget[];
+  reasons: string[];
+}
+function rows(
+  db: Db,
+  operationPath: string,
+  workspaceId?: number,
+): OperationTarget[] {
+  const names = operationLookupNames(operationPath);
+  return db
+    .prepare(
+      `SELECT o.id operationId,r.id repoId,r.name repoName,r.package_name packageName,s.service_name serviceName,s.qualified_name qualifiedName,s.service_path servicePath,o.operation_path operationPath,o.operation_name operationName,o.source_file sourceFile,o.source_line sourceLine,0 score,'' reasons
+       FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id
+       WHERE (? IS NULL OR r.workspace_id=?) AND (o.operation_path IN (?,?) OR o.operation_name IN (?,?)) ORDER BY r.name,s.service_path,o.operation_name`,
+    )
+    .all(
+      workspaceId,
+      workspaceId,
+      names.path,
+      names.simplePath,
+      names.name,
+      names.simpleName,
+    ) as unknown as OperationTarget[];
+}
+function operationLookupNames(operationPath: string): { path: string; simplePath: string; name: string; simpleName: string } {
+  const name = operationPath.replace(/^\//, '');
+  const simpleName = name.split('.').at(-1) ?? name;
+  return { path: operationPath, simplePath: `/${simpleName}`, name, simpleName };
+}
+function operationMatches(candidate: OperationTarget, operationPath: string | undefined): boolean {
+  if (!operationPath) return false;
+  const names = operationLookupNames(operationPath);
+  return candidate.operationPath === names.path || candidate.operationPath === names.simplePath || candidate.operationName === names.name || candidate.operationName === names.simpleName;
+}
+export function resolveOperation(
+  db: Db,
+  signals: {
+    servicePath?: string;
+    alias?: string;
+    destination?: string;
+    operationPath?: string;
+    serviceName?: string;
+    repoId?: number;
+    hasExplicitOverride?: boolean;
+    isDynamic?: boolean;
+    localServiceLookup?: string;
+  },
+  workspaceId?: number,
+): OperationResolution {
+  const missing = [signals.servicePath, signals.alias, signals.destination, signals.operationPath].flatMap((value) => [...(value ?? '').matchAll(/\$\{([^}]*)\}/g)].map((match) => (match[1] ?? '').trim())).filter(Boolean);
+  if (missing.length > 0)
+    return {
+      status: 'dynamic',
+      candidates: signals.operationPath ? rows(db, signals.operationPath, workspaceId) : [],
+      reasons: [...new Set(missing)].map((name) => `missing_variable:${name}`),
+    };
+  if (!signals.operationPath)
+    return {
+      status: 'unresolved',
+      candidates: [],
+      reasons: ['missing_operation_path'],
+    };
+  const allCandidates = rows(db, signals.operationPath, workspaceId).map((c) => ({
+    ...c,
+    score: 0.2,
+    reasons: ['operation_path_match'],
+  }));
+  let candidates = allCandidates.filter((c) => matchesLocalRepo(db, c.operationId, signals.repoId));
+  if (candidates.length === 0 && signals.repoId !== undefined && signals.serviceName) {
+    candidates = implementationContextCandidates(db, allCandidates, signals.repoId, signals.serviceName);
+    if (candidates.length === 0)
+      return {
+        status: 'unresolved',
+        candidates: allCandidates.filter((c) => serviceMatches(c, signals.serviceName)),
+        reasons: allCandidates.some((c) => serviceMatches(c, signals.serviceName)) ? ['local_service_candidate_without_caller_ownership'] : ['no_operation_candidates'],
+      };
+  }
+  if (candidates.length === 0)
+    return {
+      status: 'unresolved',
+      candidates: [],
+      reasons: ['no_operation_candidates'],
+    };
+  const hasStrongSignal = Boolean(
+    signals.servicePath ||
+    signals.serviceName ||
+    signals.alias ||
+    signals.destination ||
+    signals.hasExplicitOverride,
+  );
+  for (const c of candidates) {
+    if (signals.servicePath && c.servicePath === signals.servicePath) {
+      c.score += 0.75;
+      c.reasons.push('exact_service_path');
+    }
+    if (signals.servicePath && c.servicePath !== signals.servicePath) {
+      c.score -= 0.1;
+      c.reasons.push('service_path_mismatch');
+    }
+    if (signals.serviceName) {
+      const simple = signals.serviceName.split('.').at(-1) ?? signals.serviceName;
+      if (c.qualifiedName === signals.serviceName) {
+        c.score += 0.8;
+        c.reasons.push('exact_local_qualified_service_name');
+      } else if (c.serviceName === signals.serviceName || c.serviceName === simple) {
+        c.score += 0.75;
+        c.reasons.push('exact_local_simple_service_name');
+      } else if (c.servicePath === signals.serviceName || c.servicePath === `/${signals.serviceName}` || c.servicePath === `/${simple}`) {
+        c.score += 0.7;
+        c.reasons.push('exact_local_service_path');
+      } else if (c.servicePath.endsWith(`/${simple}`)) {
+        c.score += candidates.filter((candidate) => candidate.servicePath.endsWith(`/${simple}`)).length === 1 ? 0.65 : 0.2;
+        c.reasons.push('suffix_local_service_path');
+      } else c.reasons.push('local_service_name_mismatch');
+    }
+    if (signals.hasExplicitOverride) {
+      c.score += 0.2;
+      c.reasons.push(signals.repoId !== undefined ? 'explicit_local_service_call' : 'explicit_dynamic_override');
+    }
+    if (signals.repoId !== undefined && candidates.length === 1 && signals.serviceName && c.reasons.includes('local_service_name_mismatch') && operationMatches(c, signals.operationPath)) {
+      c.score = Math.max(c.score, 0.9);
+      c.reasons.push('same_repo_unique_operation_path_with_lookup_mismatch');
+    }
+  }
+  for (const c of candidates) c.score = Math.max(0, Math.min(1, c.score));
+  candidates.sort(
+    (a, b) => b.score - a.score || a.repoName.localeCompare(b.repoName),
+  );
+  const best = candidates[0];
+  const second = candidates[1];
+  if (signals.isDynamic && !signals.hasExplicitOverride && !signals.servicePath)
+    return {
+      status: 'dynamic',
+      candidates,
+      reasons: ['dynamic_target_without_override'],
+    };
+  if (!hasStrongSignal)
+    return {
+      status: candidates.length > 1 ? 'ambiguous' : 'unresolved',
+      candidates,
+      reasons: ['operation_path_only_has_no_strong_target_signal'],
+    };
+  if (
+    best &&
+    best.score >= 0.9 &&
+    (best.servicePath === signals.servicePath || Boolean(signals.serviceName && (!best.reasons.includes('local_service_name_mismatch') || best.reasons.includes('same_repo_unique_operation_path_with_lookup_mismatch')))) &&
+    operationMatches(best, signals.operationPath) &&
+    (!second || best.score - second.score >= 0.25)
+  )
+    return {
+      status: 'resolved',
+      target: best,
+      candidates,
+      reasons: best.reasons,
+    };
+  return {
+    status: candidates.length > 1 ? 'ambiguous' : 'unresolved',
+    candidates,
+    reasons: ['candidate_score_below_resolution_threshold'],
+  };
+}
+function serviceMatches(candidate: OperationTarget, serviceName: string | undefined): boolean {
+  if (!serviceName) return false;
+  const simple = serviceName.split('.').at(-1) ?? serviceName;
+  return candidate.qualifiedName === serviceName || candidate.serviceName === serviceName || candidate.serviceName === simple || candidate.servicePath === serviceName || candidate.servicePath === `/${serviceName}` || candidate.servicePath === `/${simple}` || candidate.servicePath.endsWith(`/${simple}`);
+}
+function implementationContextCandidates(db: Db, candidates: OperationTarget[], callerRepoId: number, serviceName: string): OperationTarget[] {
+  const matching = candidates.filter((candidate) => serviceMatches(candidate, serviceName));
+  const owned = matching.map((candidate) => ownershipReason(db, candidate, callerRepoId)).filter((item): item is { candidate: OperationTarget; reason: string } => Boolean(item));
+  if (owned.length === 0) return [];
+  const direct = owned.filter((item) => item.reason !== 'caller_depends_on_model_package');
+  const chosen = direct.length > 0 ? direct : owned.length === 1 ? owned : [];
+  return chosen.map((item) => ({ ...item.candidate, score: 0.95, reasons: [...item.candidate.reasons, 'implementation_context_caller_ownership', item.reason] }));
+}
+function ownershipReason(db: Db, candidate: OperationTarget, callerRepoId: number): { candidate: OperationTarget; reason: string } | undefined {
+  const edge = db.prepare("SELECT status,evidence_json,to_id FROM graph_edges WHERE edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND from_kind='operation' AND from_id=? ORDER BY CASE status WHEN 'resolved' THEN 0 WHEN 'ambiguous' THEN 1 ELSE 2 END LIMIT 1").get(String(candidate.operationId)) as { status?: string; evidence_json?: string; to_id?: string } | undefined;
+  if (edge?.status === 'resolved') {
+    const row = db.prepare('SELECT hc.repo_id repoId FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id WHERE hm.id=?').get(edge.to_id) as { repoId?: number } | undefined;
+    if (row?.repoId === callerRepoId) return { candidate, reason: 'resolved_implementation_handler_repo_matches_caller' };
+  }
+  if (edge?.evidence_json) {
+    const evidence = JSON.parse(edge.evidence_json) as { candidates?: Array<{ accepted?: boolean; handlerPackage?: { id?: number }; applicationPackage?: { id?: number } }> };
+    const hit = evidence.candidates?.find((item) => item.accepted && (Number(item.handlerPackage?.id) === callerRepoId || Number(item.applicationPackage?.id) === callerRepoId));
+    if (hit) return { candidate, reason: edge.status === 'ambiguous' ? 'ambiguous_implementation_candidate_repo_matches_caller' : 'registration_package_matches_caller' };
+  }
+  const dep = db.prepare("SELECT 1 FROM graph_edges WHERE edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND status='resolved' AND from_kind='repo' AND from_id=? AND to_id=?").get(String(callerRepoId), String(candidate.repoId));
+  if (dep) return { candidate, reason: 'caller_depends_on_model_package' };
+  return undefined;
+}
+
+function matchesLocalRepo(db: Db, operationId: number, repoId: number | undefined): boolean {
+  if (repoId === undefined) return true;
+  const row = db.prepare('SELECT s.repo_id repoId FROM cds_operations o JOIN cds_services s ON s.id=o.service_id WHERE o.id=?').get(operationId) as { repoId?: number } | undefined;
+  return row?.repoId === repoId;
+}
+export function findOperation(
+  db: Db,
+  servicePath: string | undefined,
+  operationPath: string | undefined,
+  workspaceId?: number,
+): OperationTarget | undefined {
+  return resolveOperation(db, { servicePath, operationPath }, workspaceId)
+    .target;
+}

package/src/output/json-output.ts

@@ -0,0 +1,7 @@
+import type { TraceResult } from '../types.js';
+export function renderJson(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function renderTraceJson(trace: TraceResult): string {
+  return renderJson(trace);
+}

package/src/output/mermaid-output.ts

@@ -0,0 +1,16 @@
+import type { TraceResult } from '../types.js';
+function safe(value: string): string {
+  return value.replace(/[^\w-]/g, '_').slice(0, 60);
+}
+function label(trace: TraceResult, idOrLabel: string): string {
+  const node = trace.nodes.find((item) => item.id === idOrLabel || item.label === idOrLabel);
+  return String(node?.label ?? idOrLabel);
+}
+export function renderMermaid(trace: TraceResult): string {
+  const lines = ['flowchart TD'];
+  for (const e of trace.edges)
+    lines.push(
+      `  ${safe(e.from)}["${label(trace, e.from)}"] -->|${e.type}| ${safe(e.to)}["${label(trace, e.to)}"]`
+    );
+  return `${lines.join('\n')}\n`;
+}

package/src/output/table-output.ts

@@ -0,0 +1,21 @@
+import type { TraceResult } from '../types.js';
+
+function location(evidence: Record<string, unknown>): string {
+  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.length > 0) {
+    const first = candidates[0] as Record<string, unknown>;
+    return `${String(first.sourceFile ?? '')}:${String(first.sourceLine ?? '')}`;
+  }
+  return ':';
+}
+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)}`);
+  }
+  if (result.diagnostics.length > 0) lines.push('', 'Diagnostics:', ...result.diagnostics.map((d) => `${String(d.severity ?? 'info')} ${String(d.code ?? 'diagnostic')} ${String(d.message ?? '')}`));
+  return `${lines.join('\n')}\n`;
+}