@saptools/service-flow 0.1.44 → 0.1.46

package/dist/index.d.ts

@@ -121,6 +121,14 @@ interface TraceStart {
     operationPath?: string;
     handler?: string;
 }
+interface ImplementationHint {
+    servicePath?: string;
+    operationPath?: string;
+    packageName?: string;
+    repositoryName?: string;
+    candidateFamily?: string;
+    implementationRepo: string;
+}
 interface TraceEdge {
     step: number;
     type: string;
@@ -206,9 +214,12 @@ declare function trace(db: Db, start: TraceStart, options: {
     includeDb?: boolean;
     includeAsync?: boolean;
     implementationRepo?: string;
+    implementationHints?: ImplementationHint[];
 }): TraceResult;
 
+declare function parseImplementationHint(value: string): ImplementationHint;
+
 declare function redactText(text: string): string;
 declare function redactValue(value: unknown): unknown;
 
-export { type RuntimeSubstitution, applyVariables, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace };
+export { type ImplementationHint, type RuntimeSubstitution, applyVariables, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseImplementationHint, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace };

package/dist/index.js

@@ -8,6 +8,7 @@ import {
   parseCdsFile,
   parseDecorators,
   parseHandlerRegistrations,
+  parseImplementationHint,
   parseOutboundCalls,
   parsePackageJson,
   parseServiceBindings,
@@ -16,7 +17,7 @@ import {
   stripQuotes,
   substituteVariables,
   trace
-} from "./chunk-UKNPHTUS.js";
+} from "./chunk-EGY2A4AT.js";
 
 // src/parsers/generated-constants-parser.ts
 import fs from "fs/promises";
@@ -46,6 +47,7 @@ export {
   parseDecorators,
   parseGeneratedConstants,
   parseHandlerRegistrations,
+  parseImplementationHint,
   parseOutboundCalls,
   parsePackageJson,
   parseServiceBindings,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/parsers/generated-constants-parser.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport type { GeneratedConstantFact } from '../types.js';\nimport { normalizePath, stripQuotes } from '../utils/path-utils.js';\nfunction lineOf(text: string, idx: number): number {\n  return text.slice(0, idx).split('\\n').length;\n}\nexport async function parseGeneratedConstants(\n  repoPath: string,\n  filePath: string\n): Promise<GeneratedConstantFact[]> {\n  const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');\n  return [\n    ...text.matchAll(\n      /(?:export\\s+)?(?:const|static\\s+readonly)\\s+(\\w+)\\s*=\\s*(['\"])([^'\"]+)\\2/g\n    )\n  ].map((m) => ({\n    name: m[1] ?? 'constant',\n    value: stripQuotes(m[3] ?? ''),\n    sourceFile: normalizePath(filePath),\n    sourceLine: lineOf(text, m.index ?? 0)\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AAGjB,SAAS,OAAO,MAAc,KAAqB;AACjD,SAAO,KAAK,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,EAAE;AACxC;AACA,eAAsB,wBACpB,UACA,UACkC;AAClC,QAAM,OAAO,MAAM,GAAG,SAAS,KAAK,KAAK,UAAU,QAAQ,GAAG,MAAM;AACpE,SAAO;AAAA,IACL,GAAG,KAAK;AAAA,MACN;AAAA,IACF;AAAA,EACF,EAAE,IAAI,CAAC,OAAO;AAAA,IACZ,MAAM,EAAE,CAAC,KAAK;AAAA,IACd,OAAO,YAAY,EAAE,CAAC,KAAK,EAAE;AAAA,IAC7B,YAAY,cAAc,QAAQ;AAAA,IAClC,YAAY,OAAO,MAAM,EAAE,SAAS,CAAC;AAAA,EACvC,EAAE;AACJ;","names":[]}
+{"version":3,"sources":["../src/parsers/generated-constants-parser.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport type { GeneratedConstantFact } from '../types.js';\nimport { normalizePath, stripQuotes } from '../utils/path-utils.js';\nfunction lineOf(text: string, idx: number): number {\n  return text.slice(0, idx).split('\\n').length;\n}\nexport async function parseGeneratedConstants(\n  repoPath: string,\n  filePath: string\n): Promise<GeneratedConstantFact[]> {\n  const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');\n  return [\n    ...text.matchAll(\n      /(?:export\\s+)?(?:const|static\\s+readonly)\\s+(\\w+)\\s*=\\s*(['\"])([^'\"]+)\\2/g\n    )\n  ].map((m) => ({\n    name: m[1] ?? 'constant',\n    value: stripQuotes(m[3] ?? ''),\n    sourceFile: normalizePath(filePath),\n    sourceLine: lineOf(text, m.index ?? 0)\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AAGjB,SAAS,OAAO,MAAc,KAAqB;AACjD,SAAO,KAAK,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,EAAE;AACxC;AACA,eAAsB,wBACpB,UACA,UACkC;AAClC,QAAM,OAAO,MAAM,GAAG,SAAS,KAAK,KAAK,UAAU,QAAQ,GAAG,MAAM;AACpE,SAAO;AAAA,IACL,GAAG,KAAK;AAAA,MACN;AAAA,IACF;AAAA,EACF,EAAE,IAAI,CAAC,OAAO;AAAA,IACZ,MAAM,EAAE,CAAC,KAAK;AAAA,IACd,OAAO,YAAY,EAAE,CAAC,KAAK,EAAE;AAAA,IAC7B,YAAY,cAAc,QAAQ;AAAA,IAClC,YAAY,OAAO,MAAM,EAAE,SAAS,CAAC;AAAA,EACvC,EAAE;AACJ;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saptools/service-flow",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "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,15 +1,19 @@
 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>;
+interface DoctorOptions {
+  detail?: boolean;
+}
 
 export function linkUpgradeWarnings(db: Db): Diagnostic[] {
   return [...schemaDriftDiagnostics(db, true), ...analyzerVersionDiagnostics(db, true)]
     .filter((item) => ['schema_legacy_columns_present', 'external_target_columns_missing_data', 'reindex_required_after_upgrade', 'reindex_required_after_analyzer_upgrade'].includes(String(item.code)));
 }
 
-export function doctorDiagnostics(db: Db, strict: boolean): Diagnostic[] {
+export function doctorDiagnostics(db: Db, strict: boolean, options: DoctorOptions = {}): Diagnostic[] {
   const diagnostics = db.prepare('SELECT severity,code,message,source_file sourceFile,source_line sourceLine FROM diagnostics ORDER BY id').all() as Diagnostic[];
   return [
     ...diagnostics,
@@ -17,7 +21,7 @@ export function doctorDiagnostics(db: Db, strict: boolean): Diagnostic[] {
     ...localServiceDiagnostics(db, strict),
     ...schemaDriftDiagnostics(db, strict),
     ...analyzerVersionDiagnostics(db, strict),
-    ...parserQualityDiagnostics(db, strict),
+    ...parserQualityDiagnostics(db, strict, options),
   ];
 }
 
@@ -99,7 +103,7 @@ function localServiceDiagnostics(db: Db, strict: boolean): Diagnostic[] {
   return out;
 }
 
-function parserQualityDiagnostics(db: Db, strict: boolean): Diagnostic[] {
+function parserQualityDiagnostics(db: Db, strict: boolean, options: DoctorOptions): Diagnostic[] {
   if (!strict) return [];
   const symbol = symbolCallQuality(db);
   const dbq = dbQueryQuality(db);
@@ -108,7 +112,7 @@ function parserQualityDiagnostics(db: Db, strict: boolean): Diagnostic[] {
     identityAliasBindingQuality(db),
     remoteActionNoBindingQuality(db),
     contextualImplementationQuality(db),
-    implementationCandidateQuality(db),
+    implementationCandidateQuality(db, Boolean(options.detail)),
     classInstanceNoiseQuality(db),
     contextualBindingPropagationQuality(db),
     nestedThisReceiverQuality(db),
@@ -178,20 +182,27 @@ function graphDynamicFlagQuality(db: Db): Diagnostic {
   return { severity: Number(row.count ?? 0) > 0 ? 'warning' : 'info', code: 'strict_graph_dynamic_flag_consistency', message: 'Graph dynamic flag consistency aggregate', dynamicTerminalEdges: Number(row.count ?? 0) };
 }
 
-function implementationCandidateQuality(db: Db): Diagnostic {
-  const categories = [...implementationEdgeCategories(db), missingParameterMetadataCategory(db)].filter((item) => item.count > 0);
+function implementationCandidateQuality(db: Db, detail: boolean): Diagnostic {
+  const categories = [...implementationEdgeCategories(db, detail), missingParameterMetadataCategory(db, detail), dynamicWrapperCategory(db, detail)].filter((item) => item.count > 0);
   const total = categories.reduce((sum, item) => sum + item.count, 0);
-  return { severity: total > 0 ? 'warning' : 'info', code: 'strict_implementation_candidate_quality', message: 'Implementation candidate ambiguity and rejection aggregate', total, categories };
+  return { severity: total > 0 ? 'warning' : 'info', code: 'strict_implementation_candidate_quality', message: 'Implementation candidate ambiguity and rejection aggregate', total, summary: implementationSummary(categories), categories };
 }
 
-function implementationEdgeCategories(db: Db): Array<Diagnostic & { count: number }> {
+function implementationEdgeCategories(db: Db, detail: boolean): Array<Diagnostic & { count: number }> {
   const rows = db.prepare(`SELECT e.status,e.unresolved_reason unresolvedReason,e.evidence_json evidenceJson,o.operation_name operationName,base.operation_name baseOperation,s.service_path servicePath
     FROM graph_edges e JOIN cds_operations o ON o.id=CAST(e.from_id AS INTEGER)
     JOIN cds_services s ON s.id=o.service_id LEFT JOIN cds_operations base ON base.id=o.base_operation_id
     WHERE e.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND e.status IN ('ambiguous','unresolved') ORDER BY s.service_path,o.operation_name,e.id`).all() as Diagnostic[];
   const grouped = new Map<string, Diagnostic & { count: number; servicePaths: string[]; examples: Diagnostic[] }>();
   for (const row of rows) addImplementationCategory(grouped, row);
-  return [...grouped.values()].map(({ servicePaths, ...item }) => ({ ...item, servicePathPattern: pathPattern(servicePaths), examples: item.examples.slice(0, 3) }));
+  return [...grouped.values()].map(({ servicePaths, ...item }) => ({
+    ...item,
+    servicePathPattern: pathPattern(servicePaths),
+    suggestedAction: categoryAction(String(item.category)),
+    suggestedHints: suggestedHints(item.examples),
+    examples: item.examples.slice(0, 3),
+    expandedExamples: detail ? item.examples : undefined,
+  }));
 }
 
 function addImplementationCategory(grouped: Map<string, Diagnostic & { count: number; servicePaths: string[]; examples: Diagnostic[] }>, row: Diagnostic): void {
@@ -202,22 +213,65 @@ 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 missingParameterMetadataCategory(db: Db): Diagnostic & { count: number } {
+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
     WHERE sc.status='resolved' AND json_extract(sc.evidence_json,'$.callArguments[0].kind') IN ('identifier','object_literal')
       AND (s.evidence_json IS NULL OR json_extract(s.evidence_json,'$.parameterBindings') IS NULL)
-    ORDER BY sc.source_file,sc.source_line LIMIT 3`).all() as Diagnostic[];
+    ORDER BY sc.source_file,sc.source_line`).all() as Diagnostic[];
   const row = db.prepare(`SELECT COUNT(*) count FROM symbol_calls sc JOIN symbols s ON s.id=sc.callee_symbol_id
     WHERE sc.status='resolved' AND json_extract(sc.evidence_json,'$.callArguments[0].kind') IN ('identifier','object_literal')
       AND (s.evidence_json IS NULL OR json_extract(s.evidence_json,'$.parameterBindings') IS NULL)`).get() as { count?: number };
-  return { category: 'missing_parameter_metadata', reason: 'callee symbol is missing parameter binding metadata', candidateFamily: 'symbol_parameter_metadata', count: Number(row.count ?? 0), examples };
+  return { category: 'missing_parameter_metadata', reason: 'callee symbol is missing parameter binding metadata', candidateFamily: 'symbol_parameter_metadata', count: Number(row.count ?? 0), suggestedAction: categoryAction('missing_parameter_metadata'), examples: examples.slice(0, 3), expandedExamples: detail ? examples : undefined };
+}
+
+function dynamicWrapperCategory(db: Db, detail: boolean): Diagnostic & { count: number } {
+  const rows = db.prepare(`SELECT source_file sourceFile,source_line sourceLine,
+      json_extract(evidence_json,'$.receiver') receiverName,
+      COALESCE(json_extract(evidence_json,'$.missingPathIdentifier'),json_extract(evidence_json,'$.operationPathExpression')) pathIdentifier
+    FROM outbound_calls WHERE call_type='remote_action' AND unresolved_reason='dynamic_operation_path_identifier'
+    ORDER BY source_file,source_line`).all() as Diagnostic[];
+  return { category: 'dynamic_wrapper_paths', reason: 'wrapper path cannot be proven statically', candidateFamily: 'wrapper_path', count: rows.length, suggestedAction: categoryAction('dynamic_wrapper_paths'), examples: rows.slice(0, 3), expandedExamples: detail ? rows : undefined };
+}
+
+function implementationSummary(categories: Array<Diagnostic & { count: number }>): Diagnostic[] {
+  const grouped = new Map<string, Diagnostic & { count: number }>();
+  for (const category of categories) {
+    const key = [category.category, category.candidateFamily, category.reason].join('\0');
+    const current = grouped.get(key) ?? { category: category.category, candidateFamily: category.candidateFamily, reason: category.reason, severity: 'warning', suggestedAction: category.suggestedAction, count: 0 };
+    current.count += category.count;
+    grouped.set(key, current);
+  }
+  return [...grouped.values()].sort((left, right) => String(left.category).localeCompare(String(right.category)) || String(left.candidateFamily).localeCompare(String(right.candidateFamily)));
+}
+
+function categoryAction(category: string): string {
+  if (category === 'duplicate_package_name_candidates') return 'Use scoped --implementation-hint fields to select one repository for each ambiguous hop.';
+  if (category === 'missing_strong_ownership_evidence') return 'Add an explicit package dependency, local service-path ownership, or registration ownership evidence.';
+  if (category === 'missing_parameter_metadata') return 'Export a statically analyzable helper with named or destructured parameters.';
+  if (category === 'dynamic_wrapper_paths') return 'Pass a literal path or provide the reported runtime identifier with --var key=value.';
+  return 'Inspect the capped examples and add stronger implementation ownership evidence.';
 }
 
 function implementationCategory(row: Diagnostic, evidence: Diagnostic): string {

package/src/cli.ts

@@ -24,6 +24,7 @@ import { linkWorkspace } from './linker/cross-repo-linker.js';
 import { doctorDiagnostics, linkUpgradeWarnings } from './cli/doctor.js';
 import { trace } from './trace/trace-engine.js';
 import { parseVars } from './trace/selectors.js';
+import { parseImplementationHint } from './trace/implementation-hints.js';
 import { renderTraceTable } from './output/table-output.js';
 import { renderTraceJson, renderJson } from './output/json-output.js';
 import { renderMermaid } from './output/mermaid-output.js';
@@ -152,6 +153,7 @@ export function createProgram(): Command {
     .option('--include-db')
     .option('--include-async')
     .option('--implementation-repo <name>')
+    .option('--implementation-hint <scope>', 'scoped implementation hint', collect, [])
     .option('--var <key=value>', 'dynamic variable', collect, [])
     .action(
       (opts: {
@@ -167,6 +169,7 @@ export function createProgram(): Command {
         includeDb?: boolean;
         includeAsync?: boolean;
         implementationRepo?: string;
+        implementationHint: string[];
         var: string[];
       }) =>
         void withReadOnlyWorkspace(opts.workspace, (db) => {
@@ -186,6 +189,7 @@ export function createProgram(): Command {
               includeDb: Boolean(opts.includeDb),
               includeAsync: Boolean(opts.includeAsync),
               implementationRepo: opts.implementationRepo,
+              implementationHints: opts.implementationHint.map(parseImplementationHint),
             },
           );
           process.stdout.write(
@@ -293,6 +297,7 @@ export function createProgram(): Command {
     .option('--path <operationPath>')
     .option('--format <format>', 'mermaid|json', 'mermaid')
     .option('--implementation-repo <name>')
+    .option('--implementation-hint <scope>', 'scoped implementation hint', collect, [])
     .option('--var <key=value>', 'dynamic variable', collect, [])
     .action(
       (opts: {
@@ -303,6 +308,7 @@ export function createProgram(): Command {
         path?: string;
         format: string;
         implementationRepo?: string;
+        implementationHint: string[];
         var: string[];
       }) =>
         void withReadOnlyWorkspace(opts.workspace, (db) => {
@@ -321,6 +327,7 @@ export function createProgram(): Command {
               includeExternal: true,
               vars: parseVars(opts.var),
               implementationRepo: opts.implementationRepo,
+              implementationHints: opts.implementationHint.map(parseImplementationHint),
             },
           );
           process.stdout.write(
@@ -362,10 +369,11 @@ export function createProgram(): Command {
     .command('doctor')
     .option('--workspace <path>')
     .option('--strict')
+    .option('--detail')
     .action(
-      (opts: { workspace?: string; strict?: boolean }) =>
+      (opts: { workspace?: string; strict?: boolean; detail?: boolean }) =>
         void withReadOnlyWorkspace(opts.workspace, (db) => {
-          const allDiagnostics = doctorDiagnostics(db, Boolean(opts.strict));
+          const allDiagnostics = doctorDiagnostics(db, Boolean(opts.strict), { detail: Boolean(opts.detail) });
           process.stdout.write(
             allDiagnostics.length
               ? renderJson(allDiagnostics)

package/src/index.ts

@@ -10,4 +10,6 @@ export { linkWorkspace } from './linker/cross-repo-linker.js';
 export { applyVariables, extractPlaceholders, substituteVariables } from './linker/dynamic-edge-resolver.js';
 export type { RuntimeSubstitution } from './linker/dynamic-edge-resolver.js';
 export { trace } from './trace/trace-engine.js';
+export { parseImplementationHint } from './trace/implementation-hints.js';
+export type { ImplementationHint } from './types.js';
 export { redactValue, redactText } from './utils/redaction.js';

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;
@@ -146,7 +147,29 @@ function objectJson(value: unknown): Record<string, unknown> | undefined {
 }
 function callEvidence(call: Record<string, unknown>, resolution: { target?: { repoName?: string; servicePath?: string; operationPath?: string; operationName?: string }; candidates: unknown[]; status: string; reasons: string[] }, servicePath: string | undefined, op: string | undefined, destination: string | undefined, normalized?: NormalizedODataOperationPath, odataPathIntent?: ReturnType<typeof classifyODataPathIntent>): Record<string, unknown> {
   const bindingHasDynamicExpression = Boolean(Number(call.isDynamic ?? 0));
-  return { sourceFile: call.source_file, sourceLine: call.source_line, file: call.source_file, line: call.source_line, callId: call.id, repo: call.repoName, serviceAlias: call.alias, serviceAliasExpr: call.aliasExpr, destination, servicePath, operationPath: op, rawOperationPath: normalized?.wasInvocation ? normalized.rawOperationPath : odataPathIntent?.rawPath, normalizedOperationPath: normalized?.wasInvocation ? normalized.normalizedOperationPath : undefined, invocationArgumentPlaceholderKeys: normalized?.invocationArgumentPlaceholderKeys.length ? normalized.invocationArgumentPlaceholderKeys : undefined, odataOperationNormalizationReason: normalized?.normalizationReason, odataOperationNormalizationRejectedReason: normalized?.normalizationRejectedReason, localServiceName: call.local_service_name, localServiceLookup: call.local_service_lookup, aliasChain: parseJson(call.alias_chain_json), transport: call.call_type === 'local_service_call' ? 'local' : undefined, targetRepo: resolution.target?.repoName, targetServicePath: resolution.target?.servicePath, targetOperationPath: resolution.target?.operationPath, targetOperation: resolution.target?.operationName, helperChain: parseJson(call.helperChainJson), candidates: resolution.candidates, candidateCount: resolution.candidates.length, resolutionStatus: resolution.status, resolutionReasons: resolution.reasons, odataPathIntent, queryStringPresent: odataPathIntent?.hasQueryString || undefined, queryPlaceholderKeys: odataPathIntent?.placeholderKeys.length ? odataPathIntent.placeholderKeys : undefined, bindingHasDynamicExpression: bindingHasDynamicExpression || undefined, outboundEvidence: objectJson(call.evidence_json), analysisCompleteness: call.unresolved_reason ? 'partial' : 'complete', parserWarning: call.unresolved_reason ? { code: 'parser_warning', message: call.unresolved_reason } : undefined };
+  const routingPlaceholderKeys = placeholderKeys([servicePath, destination, stringValue(call.aliasExpr), stringValue(call.alias)]);
+  return { sourceFile: call.source_file, sourceLine: call.source_line, file: call.source_file, line: call.source_line, callId: call.id, repo: call.repoName, serviceAlias: call.alias, serviceAliasExpr: call.aliasExpr, destination, servicePath, operationPath: op, rawOperationPath: normalized?.wasInvocation ? normalized.rawOperationPath : odataPathIntent?.rawPath, normalizedOperationPath: normalized?.wasInvocation ? normalized.normalizedOperationPath : undefined, invocationArguments: normalized?.wasInvocation ? normalized.invocationArguments : undefined, invocationArgumentPlaceholderKeys: normalized?.invocationArgumentPlaceholderKeys.length ? normalized.invocationArgumentPlaceholderKeys : undefined, routingPlaceholderKeys: routingPlaceholderKeys.length ? routingPlaceholderKeys : undefined, odataOperationNormalizationReason: normalized?.normalizationReason, odataOperationNormalizationRejectedReason: normalized?.normalizationRejectedReason, localServiceName: call.local_service_name, localServiceLookup: call.local_service_lookup, aliasChain: parseJson(call.alias_chain_json), transport: call.call_type === 'local_service_call' ? 'local' : undefined, targetRepo: resolution.target?.repoName, targetServicePath: resolution.target?.servicePath, targetOperationPath: resolution.target?.operationPath, targetOperation: resolution.target?.operationName, helperChain: parseJson(call.helperChainJson), candidates: resolution.candidates, candidateScores: compactCandidateScores(resolution.candidates), candidateCount: resolution.candidates.length, resolutionStatus: resolution.status, resolutionReasons: resolution.reasons, odataPathIntent, queryStringPresent: odataPathIntent?.hasQueryString || undefined, queryPlaceholderKeys: odataPathIntent?.placeholderKeys.length ? odataPathIntent.placeholderKeys : undefined, bindingHasDynamicExpression: bindingHasDynamicExpression || undefined, outboundEvidence: objectJson(call.evidence_json), analysisCompleteness: call.unresolved_reason ? 'partial' : 'complete', parserWarning: call.unresolved_reason ? { code: 'parser_warning', message: call.unresolved_reason } : undefined };
+}
+
+function compactCandidateScores(candidates: unknown[]): Array<Record<string, unknown>> {
+  return candidates.flatMap((candidate): Array<Record<string, unknown>> => {
+    const row = objectValue(candidate);
+    if (!row) return [];
+    return [{ repo: row.repoName, servicePath: row.servicePath, operationPath: row.operationPath, score: row.score, reasons: row.reasons }];
+  });
+}
+
+function placeholderKeys(values: Array<string | undefined>): string[] {
+  const keys = values.flatMap((value) => [...(value ?? '').matchAll(/\$\{([^}]*)\}/g)].map((match) => (match[1] ?? '').trim()).filter(Boolean));
+  return [...new Set(keys)].sort();
+}
+
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
 }
 
 function linkImplementations(db: Db, workspaceId: number, generation: number): { edgeCount: number; resolvedCount: number; ambiguousCount: number; unresolvedCount: number } {
@@ -179,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/linker/odata-path-normalizer.ts

@@ -2,6 +2,7 @@ export interface NormalizedODataOperationPath {
   rawOperationPath: string;
   normalizedOperationPath: string;
   wasInvocation: boolean;
+  invocationArguments?: string;
   invocationArgumentPlaceholderKeys: string[];
   normalizationReason?: string;
   normalizationRejectedReason?: string;
@@ -20,6 +21,7 @@ export interface ODataPathIntent {
   placeholderKeys: string[];
   keyPredicatePlaceholderKeys: string[];
   invocationArgumentPlaceholderKeys: string[];
+  invocationArguments?: string;
   navigationSuffix?: string;
   mediaOrPropertySuffix?: string;
   hasEntityKeyPredicate: boolean;
@@ -51,6 +53,7 @@ export function normalizeODataOperationInvocationPath(path: string | undefined):
     rawOperationPath: raw,
     normalizedOperationPath: operationSegment,
     wasInvocation: true,
+    invocationArguments: raw.slice(open + 1, close),
     invocationArgumentPlaceholderKeys: [...new Set(extractTemplatePlaceholders(raw.slice(open + 1, close)))],
     normalizationReason: 'balanced_top_level_operation_invocation',
   };
@@ -81,7 +84,7 @@ export function classifyODataPathIntent(path: string | undefined, method: string
   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 };
+  const base = { rawPath, method: normalizedMethod, pathWithoutQuery, queryString, hasQueryString: queryIndex >= 0, entitySegment, placeholderKeys, keyPredicatePlaceholderKeys, invocationArguments: invocation?.invocationArguments, 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) ?? '');

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;
+}