@saptools/service-flow 0.1.45 → 0.1.47

package/dist/index.js

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

package/src/cli/doctor.ts

@@ -1,5 +1,6 @@
 import type { Db } from '../db/connection.js';
 import { classifyODataPathIntent, normalizeODataOperationInvocationPath } from '../linker/odata-path-normalizer.js';
+import { implementationHintSuggestions } from '../trace/implementation-hints.js';
 import { ANALYZER_VERSION } from '../version.js';
 
 type Diagnostic = Record<string, unknown>;
@@ -198,6 +199,7 @@ function implementationEdgeCategories(db: Db, detail: boolean): Array<Diagnostic
     ...item,
     servicePathPattern: pathPattern(servicePaths),
     suggestedAction: categoryAction(String(item.category)),
+    suggestedHints: suggestedHints(item.examples),
     examples: item.examples.slice(0, 3),
     expandedExamples: detail ? item.examples : undefined,
   }));
@@ -211,12 +213,27 @@ function addImplementationCategory(grouped: Map<string, Diagnostic & { count: nu
   const baseOperation = String(row.baseOperation ?? row.operationName ?? evidence.operationName ?? 'unknown');
   const key = [category, baseOperation, reason, family].join('\0');
   const current = grouped.get(key) ?? { category, baseOperation, reason, candidateFamily: family, count: 0, servicePaths: [], examples: [] };
+  const hintSuggestions = implementationSuggestions(evidence);
   current.count += 1;
   current.servicePaths.push(String(row.servicePath ?? evidence.servicePath ?? ''));
-  current.examples.push({ servicePath: row.servicePath, operation: row.operationName, status: row.status, reason: row.unresolvedReason });
+  current.examples.push({ servicePath: row.servicePath, operation: row.operationName, status: row.status, reason: row.unresolvedReason, implementationHintSuggestions: hintSuggestions });
   grouped.set(key, current);
 }
 
+function implementationSuggestions(evidence: Diagnostic): Diagnostic[] | undefined {
+  const persisted = asRecords(evidence.implementationHintSuggestions);
+  const suggestions = persisted.length ? persisted : implementationHintSuggestions(evidence);
+  return suggestions.length ? suggestions : undefined;
+}
+
+function suggestedHints(examples: Diagnostic[]): string[] | undefined {
+  const hints = examples.flatMap((example) =>
+    asRecords(example.implementationHintSuggestions)
+      .flatMap((suggestion) => typeof suggestion.cli === 'string' ? [String(suggestion.cli)] : []));
+  const unique = [...new Set(hints)].slice(0, 3);
+  return unique.length ? unique : undefined;
+}
+
 function missingParameterMetadataCategory(db: Db, detail = false): Diagnostic & { count: number } {
   const examples = db.prepare(`SELECT sc.source_file sourceFile,sc.source_line sourceLine,sc.callee_expression calleeExpression
     FROM symbol_calls sc JOIN symbols s ON s.id=sc.callee_symbol_id

package/src/linker/cross-repo-linker.ts

@@ -6,6 +6,7 @@ import { resolveOperation } from './service-resolver.js';
 import { linkHelperPackages } from './helper-package-linker.js';
 import { normalizeDecoratorOperationSignal, normalizedOperationName } from './operation-decorator-normalizer.js';
 import { externalHttpTarget } from './external-http-target.js';
+import { implementationHintSuggestions } from '../trace/implementation-hints.js';
 export interface LinkWorkspaceResult {
   edgeCount: number;
   unresolvedCount: number;
@@ -201,13 +202,14 @@ function linkImplementations(db: Db, workspaceId: number, generation: number): {
       candidateFamilies: duplicateFamilies,
       candidates: candidates.map((candidate, index) => candidateEvidence(candidate, index + 1)),
     };
+    const evidenceWithHints = unique ? evidence : { ...evidence, implementationHintSuggestions: implementationHintSuggestions(evidence) };
     if (accepted.length === 0) {
-      db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)').run(workspaceId, 'OPERATION_IMPLEMENTED_BY_HANDLER', 'unresolved', 'operation', graphId(operation.operationId), 'handler_method_candidates', candidates.map((row) => graphId(row.methodId)).join(','), 0, JSON.stringify(evidence), 0, 'No implementation candidate passed policy', generation);
+      db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)').run(workspaceId, 'OPERATION_IMPLEMENTED_BY_HANDLER', 'unresolved', 'operation', graphId(operation.operationId), 'handler_method_candidates', candidates.map((row) => graphId(row.methodId)).join(','), 0, JSON.stringify(evidenceWithHints), 0, 'No implementation candidate passed policy', generation);
       edgeCount += 1;
       unresolvedCount += 1;
       continue;
     }
-    db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)').run(workspaceId, 'OPERATION_IMPLEMENTED_BY_HANDLER', unique ? 'resolved' : 'ambiguous', 'operation', graphId(operation.operationId), unique ? 'handler_method' : 'handler_method_candidates', unique ? graphId(unique.methodId) : selected.map((row) => graphId(row.methodId)).join(','), unique ? 0.95 : 0.5, JSON.stringify(evidence), 0, unique ? null : 'Ambiguous registered handler implementation candidates', generation);
+    db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)').run(workspaceId, 'OPERATION_IMPLEMENTED_BY_HANDLER', unique ? 'resolved' : 'ambiguous', 'operation', graphId(operation.operationId), unique ? 'handler_method' : 'handler_method_candidates', unique ? graphId(unique.methodId) : selected.map((row) => graphId(row.methodId)).join(','), unique ? 0.95 : 0.5, JSON.stringify(evidenceWithHints), 0, unique ? null : 'Ambiguous registered handler implementation candidates', generation);
     edgeCount += 1;
     if (unique) resolvedCount += 1;
     else ambiguousCount += 1;

package/src/output/table-output.ts

@@ -15,7 +15,22 @@ 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)}`);
+    const hint = firstHint(e.evidence);
+    if (e.unresolvedReason && hint) lines.push(`      try ${hint}`);
   }
-  if (result.diagnostics.length > 0) lines.push('', 'Diagnostics:', ...result.diagnostics.map((d) => `${String(d.severity ?? 'info')} ${String(d.code ?? 'diagnostic')} ${String(d.message ?? '')}`));
+  if (result.diagnostics.length > 0) lines.push('', 'Diagnostics:', ...result.diagnostics.flatMap(diagnosticLines));
   return `${lines.join('\n')}\n`;
 }
+
+function diagnosticLines(diagnostic: Record<string, unknown>): string[] {
+  const first = `${String(diagnostic.severity ?? 'info')} ${String(diagnostic.code ?? 'diagnostic')} ${String(diagnostic.message ?? '')}`;
+  const hint = firstHint(diagnostic);
+  return hint ? [first, `  try ${hint}`] : [first];
+}
+
+function firstHint(evidence: Record<string, unknown>): string | undefined {
+  const suggestions = evidence.implementationHintSuggestions;
+  if (!Array.isArray(suggestions)) return undefined;
+  const first = suggestions.find((item): item is Record<string, unknown> => Boolean(item) && typeof item === 'object');
+  return typeof first?.cli === 'string' ? first.cli : undefined;
+}

package/src/trace/implementation-hints.ts

@@ -65,7 +65,10 @@ export function selectImplementation(
   return hint ? selectCandidate(evidence, hint, 'scoped_implementation_hint') : { blocksAutomatic: false, evidence: { status: 'not_matched' } };
 }
 
-export function implementationHintDiagnostic(selection: ImplementationSelection): Record<string, unknown> | undefined {
+export function implementationHintDiagnostic(
+  selection: ImplementationSelection,
+  suggestions?: unknown,
+): Record<string, unknown> | undefined {
   if (!selection.blocksAutomatic || selection.methodId) return undefined;
   return {
     severity: 'warning',
@@ -73,10 +76,41 @@ export function implementationHintDiagnostic(selection: ImplementationSelection)
     message: 'Implementation hint did not select exactly one viable candidate',
     hintStatus: selection.evidence.status,
     candidateCount: selection.evidence.candidateCount,
+    implementationHintSuggestions: Array.isArray(suggestions) && suggestions.length > 0 ? suggestions : undefined,
     implementationSelection: selection.evidence,
   };
 }
 
+export function implementationHintSuggestions(rawEvidence: Record<string, unknown>): Array<Record<string, unknown>> {
+  const evidence = asEvidence(rawEvidence);
+  const accepted = (evidence.candidates ?? []).filter((candidate) => candidate.accepted);
+  if (accepted.length < 2) return [];
+  const repos = selectableRepositories(accepted);
+  return accepted
+    .flatMap((candidate) => {
+      const repo = candidate.handlerPackage?.name;
+      if (!repo || !repos.includes(repo)) return [];
+      const hint = suggestionHint(evidence, candidate, repo);
+      return [{
+        servicePath: hint.servicePath,
+        operationPath: hint.operationPath,
+        ambiguityReason: evidence.ambiguityReasons?.[0],
+        candidateFamily: hint.candidateFamily,
+        selectableImplementationRepositories: repos,
+        implementationRepo: repo,
+        hint,
+        cli: `--implementation-hint ${hintString(hint)}`,
+      }];
+    });
+}
+
+function selectableRepositories(candidates: Candidate[]): string[] {
+  const repos = new Set(candidates.flatMap((candidate) => candidate.handlerPackage?.name ? [candidate.handlerPackage.name] : []));
+  return [...repos]
+    .filter((repo) => candidates.filter((candidate) => candidateMatchesRepo(candidate, repo)).length === 1)
+    .sort();
+}
+
 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;
@@ -119,6 +153,44 @@ function selectCandidate(evidence: EdgeEvidence, hint: ImplementationHint, strat
   };
 }
 
+function suggestionHint(evidence: EdgeEvidence, candidate: Candidate, repo: string): ImplementationHint {
+  const servicePath = evidence.servicePath ?? candidate.servicePath;
+  const operationPath = evidence.operationPath ?? candidate.operationPath;
+  const family = usefulCandidateFamily(evidence, candidate);
+  return {
+    ...(servicePath ? { servicePath } : {}),
+    ...(operationPath ? { operationPath } : {}),
+    ...(evidence.modelPackage?.packageName ? { packageName: evidence.modelPackage.packageName } : {}),
+    ...(evidence.modelPackage?.name ? { repositoryName: evidence.modelPackage.name } : {}),
+    ...(family ? { candidateFamily: family } : {}),
+    implementationRepo: repo,
+  };
+}
+
+function usefulCandidateFamily(evidence: EdgeEvidence, candidate: Candidate): string | undefined {
+  const family = candidate.handlerPackage?.packageName;
+  if (!family) return undefined;
+  if ((evidence.candidateFamilies ?? []).some((item) => item.packageName === family)) return family;
+  const acceptedFamilies = new Set(
+    (evidence.candidates ?? [])
+      .filter((item) => item.accepted)
+      .flatMap((item) => item.handlerPackage?.packageName ? [item.handlerPackage.packageName] : []),
+  );
+  return acceptedFamilies.size > 1 ? family : undefined;
+}
+
+function hintString(hint: ImplementationHint): string {
+  const fields = [
+    ['service', hint.servicePath],
+    ['operation', hint.operationPath],
+    ['package', hint.packageName],
+    ['repository', hint.repositoryName],
+    ['family', hint.candidateFamily],
+    ['repo', hint.implementationRepo],
+  ];
+  return fields.flatMap(([key, value]) => value ? [`${key}=${value}`] : []).join(',');
+}
+
 function hintMatchesEdge(hint: ImplementationHint, evidence: EdgeEvidence): boolean {
   const model = evidence.modelPackage ?? evidence.candidates?.[0]?.modelPackage;
   const familyNames = new Set([

package/src/trace/trace-engine.ts

@@ -98,8 +98,8 @@ function operationStartScope(db: Db, repoId: number | undefined, start: TraceSta
   }
   if (impl.edge) {
     const evidence = parseEvidence(impl.edge.evidence_json);
-    const hintDiagnostic = implementationHintDiagnostic(hinted);
-    const diagnostics = [{ severity: 'warning', code: impl.edge.status === 'ambiguous' ? 'trace_start_ambiguous' : 'trace_start_implementation_unresolved', message: `Indexed operation matched but implementation edge is ${String(impl.edge.status ?? 'unresolved')}`, resolutionStage: 'implementation', resolutionStatus: impl.edge.status === 'ambiguous' ? 'ambiguous_implementation' : 'rejected_implementation', implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, implementationAmbiguityReasons: evidence.ambiguityReasons, candidates: evidence.candidates }];
+    const hintDiagnostic = implementationHintDiagnostic(hinted, evidence.implementationHintSuggestions);
+    const diagnostics = [{ severity: 'warning', code: impl.edge.status === 'ambiguous' ? 'trace_start_ambiguous' : 'trace_start_implementation_unresolved', message: `Indexed operation matched but implementation edge is ${String(impl.edge.status ?? 'unresolved')}`, resolutionStage: 'implementation', resolutionStatus: impl.edge.status === 'ambiguous' ? 'ambiguous_implementation' : 'rejected_implementation', implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, implementationAmbiguityReasons: evidence.ambiguityReasons, implementationHintSuggestions: evidence.implementationHintSuggestions, candidates: evidence.candidates }];
     return { operationId, diagnostics: hintDiagnostic ? [hintDiagnostic, ...diagnostics] : diagnostics };
   }
   return { operationId, diagnostics: [{ severity: 'warning', code: 'trace_start_implementation_unresolved', message: 'Indexed operation matched but no implementation candidate exists', resolutionStage: 'implementation', resolutionStatus: 'operation_without_implementation' }] };
@@ -547,9 +547,9 @@ export function trace(
           const contextMethodId = contextSelection.methodId;
           const contextNode = contextMethodId ? handlerMethodNode(db, contextMethodId) : undefined;
           if (implementation.edge) {
-            const hintDiagnostic = implementationHintDiagnostic(contextSelection);
-            if (hintDiagnostic) diagnostics.unshift(hintDiagnostic);
             const implEvidence = JSON.parse(String(implementation.edge.evidence_json || '{}')) as Record<string, unknown>;
+            const hintDiagnostic = implementationHintDiagnostic(contextSelection, implEvidence.implementationHintSuggestions);
+            if (hintDiagnostic) diagnostics.unshift(hintDiagnostic);
             const handlerNode = implementation.edge.status === 'resolved' ? handlerMethodNode(db, implementation.edge.to_id) : contextNode;
             const implTo = handlerNode?.label ? String(handlerNode.label) : `${implementation.edge.to_kind}:${implementation.edge.to_id}`;
             if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);