@saptools/service-flow 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.12
+
+- Resolved same-repository local CAP service calls by qualified CDS name, simple service name, and service path, with explicit local transport and alias-chain evidence.
+- Made implementation matching decorator-aware so generated `Func*`/`Action*` constants outrank method-name fallback and contradictory decorators are rejected without making edges ambiguous.
+- Cleared stale unresolved reasons from resolved symbol calls and suppressed false trace unresolved reasons for symbol edges with concrete callee ids.
+- Made local symbol-call collection conservative, added named export-list support, and indexed one-level object-literal helper methods as executable symbols so traces can reach helper database queries.
+- Added first-class symbol nodes and readable symbol labels/locations to JSON, table, and Mermaid trace output.
+- Deduplicated implementation candidates by method identity while retaining multiple registration rows as nested evidence, and kept default doctor output from failing on explainable source-ownership gaps.
+- Documented the generated-constant decision: this patch uses deterministic decorator normalization for linking while `parseGeneratedConstants` remains a low-level parser export rather than a persisted graph fact.
+
 ## 0.1.11
 
 - Added repository-owned executable symbols, source-symbol ownership for outbound calls, and local symbol-call facts so traces can follow reachable same-file/imported helpers without including unrelated calls from the same file.

package/README.md

@@ -59,7 +59,7 @@ npm install @saptools/service-flow
 - Repository selectors on list, trace, graph, and inspect commands narrow scope. Unknown selectors return empty machine-readable diagnostics instead of falling back to the whole workspace.
 - Helper-package dependency edges prefer exact indexed package names. Duplicate package-name candidates are persisted as ambiguous evidence rather than silently selecting one repository.
 - Handler registration parsing is AST-based for common `createCombinedHandler({ handler: ... })` forms: direct arrays, arrays assembled with spreads, non-`handlers` array names, aliased class imports, default-imported arrays, named exported arrays, and safe relative re-exports. Class-level rows keep registration file/line and import evidence.
-- Implementation edges require both operation compatibility and registration evidence. Same-repository registrations do not need a self-dependency edge; cross-package matches use registration or handler-package dependencies on the model package. Duplicate strong candidates are stored as ambiguous implementation edges.
+- Implementation edges require both operation compatibility and registration evidence. Decorator operation signals are stronger than method-name fallback; common generated names such as `FuncGetConfiguration` and `ActionGetConfiguration` are normalized before comparison, and a contradictory decorator rejects the candidate even when the TypeScript method name collides. Same-repository registrations do not need a self-dependency edge; cross-package matches use registration or handler-package dependencies on the model package. Duplicate strong candidates are stored as ambiguous implementation edges.
 - Traces render persisted `OPERATION_IMPLEMENTED_BY_HANDLER` hops after static or runtime remote operation resolution, including terminal handler nodes and ambiguous or unresolved implementation evidence when traversal cannot continue.
 - Repository fingerprints include source content, package name/version, dependencies and devDependencies, scripts, normalized `cds.requires` (including nested credentials), package file content, and the analyzer version. Metadata-only changes therefore trigger reindexing.
 - Index publication is designed around the last-good snapshot: failed parse or persistence attempts are recorded as diagnostics and must not be mixed with older graph facts. After indexing changes, relink before relying on graph/trace output; doctor reports stale or inconsistent stores where detectable.
@@ -152,7 +152,9 @@ target handler up to `--depth` instead of showing only calls in the first file.
 
 `service-flow trace` starts from the selected handler method symbol, renders outbound calls owned by that symbol, and follows conservative local helper-call facts. Supported helper edges include same-file functions, `this.method()` calls, and exactly mapped relative imports/exports that resolve to an indexed executable symbol. Calls from unrelated functions in the same source file are not included merely because the file path matches.
 
-Local CAP calls through `cds.services.<Service>.<operation>()`, bracket service lookups, and simple aliases are indexed as local operation calls. Entity accessors such as `cds.services.db.entities(...)` are treated as entity metadata access, not operation calls.
+Local CAP calls through `cds.services.<Service>.<operation>()`, bracket service lookups, and simple aliases are indexed as local operation calls. Linking stays within the same repository by default and matches the target operation by exact qualified CDS service name, exact simple service name, exact service path, or an unambiguous service-path suffix. Entity accessors such as `cds.services.db.entities(...)` are treated as entity metadata access, not operation calls.
+
+Conservative local symbol traversal intentionally excludes decorators, built-ins such as `JSON.parse`, collection methods, third-party APIs, and arbitrary property chains unless the callee can plausibly resolve to an indexed local symbol. Named export lists such as `export { loadTemplate as publicLoadTemplate }` are indexed with the public exported name so relative imports can resolve. One-level object-literal helpers are indexed as symbols named like `cacheHelper.getConfiguration`; nested object literals are not yet expanded beyond the first helper level. `parseGeneratedConstants` remains a public low-level parser export for callers that need it, but generated constants are not persisted as graph facts in this patch; linking uses the deterministic decorator normalizer described above.
 JSON output includes typed nodes for calls, operations, database entities,
 external destinations, and unresolved/dynamic candidates when edges exist.
 

package/dist/{chunk-GG4XJGES.js → chunk-MXYYARUP.js}

@@ -1074,7 +1074,7 @@ function substituteVariables(template, vars) {
 // src/linker/service-resolver.ts
 function rows(db, operationPath, workspaceId) {
   return db.prepare(
-    `SELECT o.id operationId,r.name repoName,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.name repoName,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=? OR o.operation_name=?) ORDER BY r.name,s.service_path,o.operation_name`
   ).all(
@@ -1110,7 +1110,7 @@ function resolveOperation(db, signals, workspaceId) {
       reasons: ["no_operation_candidates"]
     };
   const hasStrongSignal = Boolean(
-    signals.servicePath || signals.alias || signals.destination || signals.hasExplicitOverride
+    signals.servicePath || signals.serviceName || signals.alias || signals.destination || signals.hasExplicitOverride
   );
   for (const c of candidates) {
     if (signals.servicePath && c.servicePath === signals.servicePath) {
@@ -1121,14 +1121,25 @@ function resolveOperation(db, signals, workspaceId) {
       c.score -= 0.1;
       c.reasons.push("service_path_mismatch");
     }
-    if (signals.serviceName && (c.servicePath === `/${signals.serviceName}` || c.servicePath.endsWith(`/${signals.serviceName}`))) {
-      c.score += 0.7;
-      c.reasons.push("exact_local_service_name");
+    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.serviceName && c.servicePath !== `/${signals.serviceName}` && !c.servicePath.endsWith(`/${signals.serviceName}`)) c.reasons.push("local_service_name_mismatch");
     if (signals.hasExplicitOverride) {
       c.score += 0.2;
-      c.reasons.push("explicit_dynamic_override");
+      c.reasons.push(signals.repoId !== void 0 ? "explicit_local_service_call" : "explicit_dynamic_override");
     }
   }
   for (const c of candidates) c.score = Math.max(0, Math.min(1, c.score));
@@ -1149,7 +1160,7 @@ function resolveOperation(db, signals, workspaceId) {
       candidates,
       reasons: ["operation_path_only_has_no_strong_target_signal"]
     };
-  if (best && best.score >= 0.9 && (best.servicePath === signals.servicePath || Boolean(signals.serviceName && (best.servicePath === `/${signals.serviceName}` || best.servicePath.endsWith(`/${signals.serviceName}`)))) && (best.operationPath === signals.operationPath || best.operationName === signals.operationPath.replace(/^\//, "")) && (!second || best.score - second.score >= 0.25))
+  if (best && best.score >= 0.9 && (best.servicePath === signals.servicePath || Boolean(signals.serviceName && !best.reasons.includes("local_service_name_mismatch"))) && (best.operationPath === signals.operationPath || best.operationName === signals.operationPath.replace(/^\//, "")) && (!second || best.score - second.score >= 0.25))
     return {
       status: "resolved",
       target: best,
@@ -1307,7 +1318,7 @@ function rankedImplementationCandidates(db, workspaceId, operation) {
 function deduplicateCandidates(rows2) {
   const merged = /* @__PURE__ */ new Map();
   for (const row of rows2) {
-    const key = [row.methodId, row.classId, row.applicationRepoId, row.importSource ?? "", row.registrationKind ?? ""].join(":");
+    const key = [row.methodId, row.classId, row.handlerRepoId].join(":");
     const registration = { file: row.registrationFile, line: row.registrationLine, kind: row.registrationKind, importSource: row.importSource };
     const existing = merged.get(key);
     if (!existing) {
@@ -1335,6 +1346,9 @@ function implementationCandidates(db, workspaceId, operation) {
   const modelRepoGraphId = graphId(operation.modelRepoId);
   return db.prepare(`SELECT DISTINCT
       hm.id methodId,
+      hm.method_name methodName,
+      hm.decorator_value decoratorValue,
+      hm.decorator_raw_expression decoratorRawExpression,
       hc.id classId,
       hc.class_name className,
       hc.source_file sourceFile,
@@ -1361,7 +1375,7 @@ function implementationCandidates(db, workspaceId, operation) {
       CASE WHEN appRepo.id=handlerRepo.id THEN 1 ELSE 0 END sameRepoRegistration,
       CASE WHEN EXISTS (SELECT 1 FROM cds_services localService WHERE localService.repo_id=appRepo.id AND localService.service_path=?) THEN 1 ELSE 0 END localServicePathMatch,
       CASE WHEN EXISTS (SELECT 1 FROM cds_services localService WHERE localService.repo_id=appRepo.id) THEN 1 ELSE 0 END applicationHasLocalServices,
-      CASE WHEN EXISTS (SELECT 1 FROM handler_registrations localReg JOIN handler_classes localClass ON (localClass.id=localReg.handler_class_id OR localClass.class_name=localReg.class_name) JOIN handler_methods localMethod ON localMethod.handler_class_id=localClass.id WHERE localReg.repo_id=appRepo.id AND (localMethod.decorator_value=? OR localMethod.decorator_value=? OR localMethod.method_name=?)) THEN 1 ELSE 0 END applicationHasLocalRegistrationForOperation,
+      CASE WHEN EXISTS (SELECT 1 FROM handler_registrations localReg JOIN handler_classes localClass ON (localClass.id=localReg.handler_class_id OR localClass.class_name=localReg.class_name) JOIN handler_methods localMethod ON localMethod.handler_class_id=localClass.id WHERE localReg.repo_id=appRepo.id AND (localMethod.decorator_value=? OR localMethod.decorator_value=? OR localMethod.method_name=? OR localMethod.decorator_raw_expression LIKE ?)) THEN 1 ELSE 0 END applicationHasLocalRegistrationForOperation,
       CASE WHEN EXISTS (SELECT 1 FROM graph_edges dep WHERE dep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND dep.status='resolved' AND dep.from_kind='repo' AND dep.from_id=CAST(appRepo.id AS TEXT) AND dep.to_id=?) THEN 1 ELSE 0 END appDependsOnModel,
       CASE WHEN EXISTS (SELECT 1 FROM graph_edges dep WHERE dep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND dep.status='resolved' AND dep.from_kind='repo' AND dep.from_id=CAST(appRepo.id AS TEXT) AND dep.to_id=CAST(handlerRepo.id AS TEXT)) THEN 1 ELSE 0 END appDependsOnHandler,
       CASE WHEN EXISTS (SELECT 1 FROM graph_edges dep WHERE dep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND dep.status='resolved' AND dep.from_kind='repo' AND dep.from_id=CAST(handlerRepo.id AS TEXT) AND dep.to_id=?) THEN 1 ELSE 0 END handlerDependsOnModel
@@ -1371,7 +1385,7 @@ function implementationCandidates(db, workspaceId, operation) {
     JOIN handler_registrations hr ON (hr.handler_class_id=hc.id OR (hr.class_name=hc.class_name AND (hr.repo_id=hc.repo_id OR hr.import_source IS NOT NULL)))
     JOIN repositories appRepo ON appRepo.id=hr.repo_id
     WHERE appRepo.workspace_id=?
-      AND (hm.decorator_value=? OR hm.decorator_value=? OR hm.method_name=?)`).all(
+      AND (hm.decorator_value=? OR hm.decorator_value=? OR hm.method_name=? OR hm.decorator_raw_expression LIKE ?)`).all(
     operation.modelRepoId,
     operation.modelRepo,
     operation.modelPackage,
@@ -1385,12 +1399,14 @@ function implementationCandidates(db, workspaceId, operation) {
     normalizedOperation(String(operation.operationPath ?? "")),
     operation.operationName,
     operation.operationName,
+    `%${upperFirst(normalizedOperation(String(operation.operationPath ?? operation.operationName ?? "")))}%`,
     modelRepoGraphId,
     modelRepoGraphId,
     workspaceId,
     normalizedOperation(String(operation.operationPath ?? "")),
     operation.operationName,
-    operation.operationName
+    operation.operationName,
+    `%${upperFirst(normalizedOperation(String(operation.operationPath ?? operation.operationName ?? "")))}%`
   );
 }
 function scoreImplementationCandidate(row, operation) {
@@ -1408,7 +1424,10 @@ function scoreImplementationCandidate(row, operation) {
   const importSource = typeof row.importSource === "string" && row.importSource.length > 0;
   const sameRepoRegistration = flag(row.sameRepoRegistration);
   const modelOriented = row.modelKind === "cap-db-model" || !applicationHasLocalRegistrationForOperation;
-  const methodMatches = true;
+  const methodSignal = implementationMethodSignal(row, operation);
+  const methodMatches = methodSignal.matches;
+  acceptedReasons.push(...methodSignal.acceptedReasons);
+  rejectedReasons.push(...methodSignal.rejectedReasons);
   const registeredAndLinked = sameRepoRegistration && importSource;
   const helperOwned = modelOriented && methodMatches && registeredAndLinked && sameRepoRegistration && !applicationHasLocalServices && !modelIsApplicationRepo && !modelIsHandlerRepo && !localServicePathMatch && !appDependsOnModel && !appDependsOnHandler && !handlerDependsOnModel;
   if (modelIsApplicationRepo) {
@@ -1449,7 +1468,7 @@ function scoreImplementationCandidate(row, operation) {
   const hasCrossPackage = appDependsOnModel && (modelIsHandlerRepo || appDependsOnHandler || !importSource);
   const contradicted = applicationHasLocalServices && !localServicePathMatch && !appDependsOnModel && !hasOwnership;
   if (!hasOwnership && !localServicePathMatch && !hasCrossPackage && !helperOwned) rejectedReasons.push("missing direct ownership, exact local service path, or validated cross-package dependency evidence");
-  const accepted = !contradicted && (hasOwnership || localServicePathMatch || hasCrossPackage || handlerDependsOnModel || helperOwned);
+  const accepted = methodMatches && !methodSignal.contradicted && !contradicted && (hasOwnership || localServicePathMatch || hasCrossPackage || handlerDependsOnModel || helperOwned);
   if (!accepted && rejectedReasons.length === 0) rejectedReasons.push("candidate did not meet implementation ownership policy");
   return { ...row, methodId: Number(row.methodId), score, accepted, acceptedReasons, rejectedReasons };
 }
@@ -1485,6 +1504,29 @@ function candidateEvidence(candidate, rank) {
     }
   };
 }
+function implementationMethodSignal(row, operation) {
+  const op = normalizedOperation(String(operation.operationPath ?? operation.operationName ?? ""));
+  const decorator = normalizeDecoratorOperation(typeof row.decoratorValue === "string" ? row.decoratorValue : void 0, typeof row.decoratorRawExpression === "string" ? row.decoratorRawExpression : void 0);
+  if (decorator && decorator === op) return { matches: true, contradicted: false, acceptedReasons: ["decorator targets operation"], rejectedReasons: [] };
+  if (decorator && decorator !== op) return { matches: false, contradicted: true, acceptedReasons: [], rejectedReasons: ["method_name_matches_but_decorator_targets_different_operation"] };
+  if (String(row.methodName ?? "") === op) return { matches: true, contradicted: false, acceptedReasons: ["method name fallback matched operation"], rejectedReasons: [] };
+  return { matches: false, contradicted: false, acceptedReasons: [], rejectedReasons: ["method name does not match operation"] };
+}
+function normalizeDecoratorOperation(value, raw) {
+  const candidate = value ?? raw?.split(".").filter(Boolean).at(-2);
+  if (!candidate) return void 0;
+  const cleaned = candidate.replace(/^['"`]|['"`]$/g, "");
+  for (const prefix of ["Func", "Action"]) {
+    if (cleaned.startsWith(prefix) && cleaned.length > prefix.length) return lowerFirst(cleaned.slice(prefix.length));
+  }
+  return normalizedOperation(cleaned);
+}
+function upperFirst(value) {
+  return value ? `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}` : value;
+}
+function lowerFirst(value) {
+  return value ? `${value[0]?.toLowerCase() ?? ""}${value.slice(1)}` : value;
+}
 function flag(value) {
   return Boolean(Number(value ?? 0));
 }
@@ -1634,6 +1676,12 @@ function evidenceWithRuntimeVariables(evidence, vars) {
   if (missing.length > 0) next.missingRuntimeVariables = [...new Set(missing)];
   return next;
 }
+function symbolNode(db, symbolId) {
+  const row = db.prepare(`SELECT s.id symbolId,s.name symbolName,s.qualified_name qualifiedName,s.source_file sourceFile,s.start_line startLine,s.end_line endLine,r.name repoName,r.id repoId FROM symbols s JOIN repositories r ON r.id=s.repo_id WHERE s.id=?`).get(symbolId);
+  if (!row) return void 0;
+  const fileName = String(row.sourceFile ?? "").split("/").at(-1) ?? String(row.sourceFile ?? "");
+  return { id: `symbol:${symbolId}`, kind: "symbol", label: `${fileName}:${String(row.qualifiedName ?? row.symbolName)}`, ...row };
+}
 function operationNode(db, operationId) {
   const row = db.prepare(`SELECT o.id operationId,o.operation_name operationName,o.operation_type operationType,o.operation_path operationPath,o.source_file sourceFile,o.source_line sourceLine,s.id serviceId,s.service_name serviceName,s.qualified_name qualifiedName,s.service_path servicePath,r.id repoId,r.name repoName FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE o.id=?`).get(operationId);
   if (!row) return void 0;
@@ -1728,7 +1776,10 @@ function trace(db, start, options) {
         const nextFiles = /* @__PURE__ */ new Set([String(symbolCall.calleeFile)]);
         const nextRepoId = Number(symbolCall.calleeRepoId);
         const nextKey = `${nextRepoId}:${[...nextSymbols].join(",")}:${[...nextFiles].join(",")}`;
-        edges.push({ step: current.depth, type: "local_symbol_call", from: String(symbolCall.callee_expression), to: `symbol:${String(symbolCall.callee_symbol_id)}`, evidence: JSON.parse(String(symbolCall.evidence_json || "{}")), confidence: Number(symbolCall.confidence ?? 0.8), unresolvedReason: symbolCall.unresolved_reason ? String(symbolCall.unresolved_reason) : void 0 });
+        const calleeNode = symbolNode(db, Number(symbolCall.callee_symbol_id));
+        if (calleeNode) nodes.set(String(calleeNode.id), calleeNode);
+        const evidence = { ...JSON.parse(String(symbolCall.evidence_json || "{}")), sourceFile: symbolCall.source_file, sourceLine: symbolCall.source_line, calleeSymbolId: symbolCall.callee_symbol_id, calleeSymbolName: calleeNode?.symbolName, calleeSymbolFile: calleeNode?.sourceFile, resolutionStatus: symbolCall.status };
+        edges.push({ step: current.depth, type: "local_symbol_call", from: String(symbolCall.callee_expression), to: calleeNode?.label ? String(calleeNode.label) : `symbol:${String(symbolCall.callee_symbol_id)}`, evidence, confidence: Number(symbolCall.confidence ?? 0.8), unresolvedReason: String(symbolCall.status) === "resolved" ? void 0 : symbolCall.unresolved_reason ? String(symbolCall.unresolved_reason) : void 0 });
         if (seenScopes.has(nextKey)) edges.push({ step: current.depth, type: "cycle", from: String(symbolCall.callee_expression), to: nextKey, evidence: { cycle: true, symbolCallId: symbolCall.id }, confidence: 1, unresolvedReason: "Cycle detected; downstream symbol already visited" });
         else queue.push({ repoId: nextRepoId, files: nextFiles, symbolIds: nextSymbols, depth: current.depth + 1 });
       }
@@ -1842,4 +1893,4 @@ export {
   linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-GG4XJGES.js.map
+//# sourceMappingURL=chunk-MXYYARUP.js.map