@saptools/service-flow 0.1.50 → 0.1.51

package/dist/index.d.ts

@@ -135,6 +135,18 @@ interface ImplementationHint {
     candidateFamily?: string;
     implementationRepo: string;
 }
+type DynamicMode = 'strict' | 'candidates' | 'infer';
+interface TraceOptions {
+    depth: number;
+    vars?: Record<string, string>;
+    includeExternal?: boolean;
+    includeDb?: boolean;
+    includeAsync?: boolean;
+    implementationRepo?: string;
+    implementationHints?: ImplementationHint[];
+    dynamicMode?: DynamicMode;
+    maxDynamicCandidates?: number;
+}
 interface TraceEdge {
     step: number;
     type: string;
@@ -213,19 +225,11 @@ declare function applyVariables(template: string | undefined, vars: Record<strin
 declare function extractPlaceholders(template: string | undefined): string[];
 declare function substituteVariables(template: string | undefined, vars: Record<string, string>): RuntimeSubstitution;
 
-declare function trace(db: Db, start: TraceStart, options: {
-    depth: number;
-    vars?: Record<string, string>;
-    includeExternal?: boolean;
-    includeDb?: boolean;
-    includeAsync?: boolean;
-    implementationRepo?: string;
-    implementationHints?: ImplementationHint[];
-}): TraceResult;
+declare function trace(db: Db, start: TraceStart, options: TraceOptions): TraceResult;
 
 declare function parseImplementationHint(value: string): ImplementationHint;
 
 declare function redactText(text: string): string;
 declare function redactValue(value: unknown): unknown;
 
-export { type ImplementationHint, type RuntimeSubstitution, applyVariables, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseImplementationHint, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace };
+export { type DynamicMode, type ImplementationHint, type RuntimeSubstitution, type TraceOptions, applyVariables, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseImplementationHint, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace };

package/dist/index.js

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

package/src/cli.ts

@@ -29,6 +29,7 @@ import { renderTraceJson, renderJson } from './output/json-output.js';
 import { renderDoctorDiagnostics } from './output/doctor-output.js';
 import { renderMermaid } from './output/mermaid-output.js';
 import { VERSION } from './version.js';
+import type { DynamicMode } from './types.js';
 async function init(
   workspace: string,
   options: { db?: string; ignore?: string[] },
@@ -155,6 +156,8 @@ export function createProgram(): Command {
     .option('--implementation-repo <name>')
     .option('--implementation-hint <scope>', 'scoped implementation hint', collect, [])
     .option('--var <key=value>', 'dynamic variable', collect, [])
+    .option('--dynamic-mode <mode>', 'strict|candidates|infer', 'strict')
+    .option('--max-dynamic-candidates <n>', 'maximum dynamic candidates to show', '5')
     .action(
       (opts: {
         workspace?: string;
@@ -171,6 +174,8 @@ export function createProgram(): Command {
         implementationRepo?: string;
         implementationHint: string[];
         var: string[];
+        dynamicMode: string;
+        maxDynamicCandidates: string;
       }) =>
         void withReadOnlyWorkspace(opts.workspace, (db) => {
           const result = trace(
@@ -190,6 +195,8 @@ export function createProgram(): Command {
               includeAsync: Boolean(opts.includeAsync),
               implementationRepo: opts.implementationRepo,
               implementationHints: opts.implementationHint.map(parseImplementationHint),
+              dynamicMode: parseDynamicMode(opts.dynamicMode),
+              maxDynamicCandidates: parsePositiveInteger(opts.maxDynamicCandidates, 5),
             },
           );
           process.stdout.write(
@@ -299,6 +306,8 @@ export function createProgram(): Command {
     .option('--implementation-repo <name>')
     .option('--implementation-hint <scope>', 'scoped implementation hint', collect, [])
     .option('--var <key=value>', 'dynamic variable', collect, [])
+    .option('--dynamic-mode <mode>', 'strict|candidates|infer', 'strict')
+    .option('--max-dynamic-candidates <n>', 'maximum dynamic candidates to show', '5')
     .action(
       (opts: {
         workspace?: string;
@@ -310,6 +319,8 @@ export function createProgram(): Command {
         implementationRepo?: string;
         implementationHint: string[];
         var: string[];
+        dynamicMode: string;
+        maxDynamicCandidates: string;
       }) =>
         void withReadOnlyWorkspace(opts.workspace, (db) => {
           const result = trace(
@@ -328,6 +339,8 @@ export function createProgram(): Command {
               vars: parseVars(opts.var),
               implementationRepo: opts.implementationRepo,
               implementationHints: opts.implementationHint.map(parseImplementationHint),
+              dynamicMode: parseDynamicMode(opts.dynamicMode),
+              maxDynamicCandidates: parsePositiveInteger(opts.maxDynamicCandidates, 5),
             },
           );
           process.stdout.write(
@@ -418,6 +431,15 @@ function collect(value: string, previous: string[]): string[] {
   previous.push(value);
   return previous;
 }
+function parseDynamicMode(value: string | undefined): DynamicMode {
+  if (value === undefined || value === 'strict') return 'strict';
+  if (value === 'candidates' || value === 'infer') return value;
+  throw new Error(`Invalid --dynamic-mode ${value}; expected strict, candidates, or infer`);
+}
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
 function fail(error: unknown): void {
   process.stderr.write(
     `${error instanceof Error ? error.message : String(error)}\n`,

package/src/index.ts

@@ -11,5 +11,5 @@ export { applyVariables, extractPlaceholders, substituteVariables } from './link
 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 type { DynamicMode, ImplementationHint, TraceOptions } from './types.js';
 export { redactValue, redactText } from './utils/redaction.js';

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

@@ -224,7 +224,15 @@ function compactCandidateScores(candidates: unknown[]): Array<Record<string, unk
   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 }];
+    return [{
+      repo: row.repoName,
+      servicePath: row.servicePath,
+      operationPath: row.operationPath,
+      score: row.score,
+      reasons: Array.isArray(row.reasons)
+        ? row.reasons.filter((reason): reason is string => typeof reason === 'string')
+        : ['operation_path_match'],
+    }];
   });
 }
 

package/src/linker/service-resolver.ts

@@ -26,9 +26,9 @@ function rows(
   workspaceId?: number,
 ): OperationTarget[] {
   const names = operationLookupNames(operationPath);
-  return db
+  const result = 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
+      `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
        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`,
     )
@@ -39,7 +39,12 @@ function rows(
       names.simplePath,
       names.name,
       names.simpleName,
-    ) as unknown as OperationTarget[];
+    ) as Array<Omit<OperationTarget, 'reasons'>>;
+  return result.map((row) => ({
+    ...row,
+    score: Number(row.score ?? 0),
+    reasons: [],
+  }));
 }
 function operationLookupNames(operationPath: string): { path: string; simplePath: string; name: string; simpleName: string } {
   const name = operationPath.replace(/^\//, '');
@@ -70,7 +75,13 @@ export function resolveOperation(
   if (missing.length > 0)
     return {
       status: 'dynamic',
-      candidates: signals.operationPath ? rows(db, signals.operationPath, workspaceId) : [],
+      candidates: signals.operationPath
+        ? rows(db, signals.operationPath, workspaceId).map((candidate) => ({
+            ...candidate,
+            score: 0.2,
+            reasons: ['operation_path_match'],
+          }))
+        : [],
       reasons: [...new Set(missing)].map((name) => `missing_variable:${name}`),
     };
   if (!signals.operationPath)

package/src/output/table-output.ts

@@ -28,8 +28,9 @@ function diagnosticLines(diagnostic: Record<string, unknown>): string[] {
 }
 
 function hintLines(evidence: Record<string, unknown>): string[] {
+  const dynamicLines = dynamicHintLines(evidence);
   const suggestions = evidence.implementationHintSuggestions;
-  if (!Array.isArray(suggestions)) return [];
+  if (!Array.isArray(suggestions)) return dynamicLines;
   const hints = suggestions.flatMap((item) =>
     isRecord(item) && typeof item.cli === 'string'
       ? [item.cli]
@@ -38,9 +39,35 @@ function hintLines(evidence: Record<string, unknown>): string[] {
   const shown = unique.slice(0, 3).map((hint) => `try ${hint}`);
   if (unique.length > shown.length)
     shown.push(`... ${unique.length - shown.length} more hint(s) available in JSON`);
-  return shown;
+  return [...dynamicLines, ...shown];
+}
+
+function dynamicHintLines(evidence: Record<string, unknown>): string[] {
+  const exploration = isRecord(evidence.dynamicTargetExploration)
+    ? evidence.dynamicTargetExploration
+    : evidence;
+  const count = numberValue(exploration.candidateCount);
+  if (count === 0) return [];
+  const shown = numberValue(exploration.shownCandidateCount);
+  const omitted = numberValue(exploration.omittedCandidateCount);
+  const lines = [`candidates: ${shown} shown, ${omitted} omitted`];
+  lines.push(...varSetHints(exploration.suggestedVarSets));
+  if (omitted > 0 || shown < count)
+    lines.push('use --dynamic-mode candidates --max-dynamic-candidates 20 to explore candidate branches');
+  return lines;
+}
+
+function varSetHints(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const hints = value.flatMap((item) =>
+    isRecord(item) && typeof item.cli === 'string' ? [`try ${item.cli}`] : []);
+  return [...new Set(hints)].slice(0, 3);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
+
+function numberValue(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}

package/src/trace/dynamic-branches.ts

@@ -0,0 +1,45 @@
+import type { TraceEdge } from '../types.js';
+
+interface DynamicBranchCall {
+  repoName: string;
+  source_file: string;
+  source_line: number;
+}
+
+export function dynamicCandidateBranches(
+  depth: number,
+  call: DynamicBranchCall,
+  evidence: Record<string, unknown>,
+): TraceEdge[] {
+  const exploration = objectRecord(evidence.dynamicTargetExploration);
+  return recordArray(evidence.dynamicTargetCandidateSuggestions).map((candidate) => ({
+    step: depth,
+    type: 'dynamic_candidate_branch',
+    from: `${call.repoName}:${call.source_file}:${call.source_line}`,
+    to: `${String(candidate.servicePath ?? '')}${String(candidate.operationPath ?? '')}`,
+    evidence: {
+      ...candidate,
+      exploratory: true,
+      dynamicMode: String(exploration.mode ?? 'candidates'),
+      selected: false,
+      omittedCandidateCount: numericValue(exploration.omittedCandidateCount),
+    },
+    confidence: numericValue(candidate.score),
+    unresolvedReason: 'Exploratory dynamic target candidate; provide runtime variables to select it',
+  }));
+}
+
+function objectRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function recordArray(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> =>
+        Boolean(item && typeof item === 'object' && !Array.isArray(item)))
+    : [];
+}
+
+function numericValue(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}