@saptools/service-flow 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.10
+
+- Persist unresolved `OPERATION_IMPLEMENTED_BY_HANDLER` audit edges when implementation candidates exist but all are rejected, including ranked candidate evidence and rejected reasons.
+- Added a conservative helper-owned implementation path for unique registered helper handlers that implement model-oriented CDS operations without direct package dependency evidence, while keeping multiple helper matches ambiguous and local service-path contradictions rejected.
+- Trace output now includes operation-to-handler implementation hops and terminal handler nodes in JSON/table/Mermaid-compatible edge data, including runtime-resolved operation targets.
+- Doctor now reports rejected implementation candidates and strict remote-target implementation coverage gaps without making entity-only services noisy by default.
+- Updated Node compatibility errors, package metadata, and README wording so current behavior is not described with stale release-specific version strings.
+
 ## 0.1.9
 
 - Fixed implementation dependency matching by binding graph repository ids as text when comparing against `graph_edges.from_id` and `graph_edges.to_id`, restoring cross-package application-to-model and application-to-handler evidence under `node:sqlite`.

package/README.md

@@ -47,12 +47,12 @@ npm install @saptools/service-flow
 ```
 
 > [!NOTE]
-> Requires **Node.js ≥ 24.0.0** for the bundled `node:sqlite` runtime. Version 0.1.8 uses a persistent SQLite driver (`node:sqlite` in supported Node builds) for bound parameters, transactions, WAL, busy timeouts, and read-only query commands. The analyzer is static: it reads files and package metadata, but it does not start CAP services, connect to SAP BTP, or execute application code.
+> Requires **Node.js ≥ 24.0.0** for the bundled `node:sqlite` runtime. The CLI uses a persistent SQLite driver (`node:sqlite` in supported Node builds) for bound parameters, transactions, WAL, busy timeouts, and read-only query commands. The analyzer is static: it reads files and package metadata, but it does not start CAP services, connect to SAP BTP, or execute application code.
 
 ---
 
 
-### Correctness notes for 0.1.8
+### Correctness notes
 
 - Runtime `--var` values are considered only for dynamic, ambiguous, or unresolved **remote** graph edges whose alias, destination, service path, or operation path expressions contain supplied placeholders. Local database, external HTTP, event, and already resolved static edges keep their persisted status, target, reason, and confidence. Partial substitutions remain dynamic and report the missing placeholder names.
 - `trace` and `graph` both accept repeatable `--var key=value` options. Effective substitutions are rendered in trace evidence without mutating the persisted graph. Confidence values are bounded to `[0, 1]`.
@@ -60,7 +60,7 @@ npm install @saptools/service-flow
 - 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.
-- Traces prefer persisted `OPERATION_IMPLEMENTED_BY_HANDLER` edges after static or runtime remote operation resolution, then fall back to same-repository decorator matching for simple projects.
+- 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.
 - Source discovery, file reads, hashing, parsing, and publication are all inside the repository-level protected indexing flow. A failed read keeps the previous fingerprint and facts, marks the repository failed, and records a `source_read_failed` diagnostic; a later successful index clears superseded read-failure diagnostics during fact publication.

package/dist/{chunk-HQMAFSRR.js → chunk-LQT67AU5.js}

@@ -1177,7 +1177,7 @@ function linkWorkspace(db, workspaceId, vars = {}) {
     const callSummary = linkCalls(db, workspaceId, vars, generation);
     const impl = linkImplementations(db, workspaceId, generation);
     db.prepare("UPDATE repositories SET graph_generation=?, graph_stale_reason=NULL, graph_stale_at=NULL WHERE workspace_id=?").run(generation, workspaceId);
-    return { ...callSummary, edgeCount: deps.edgeCount + callSummary.edgeCount + impl.edgeCount, dependencyResolvedCount: deps.resolvedCount, dependencyAmbiguousCount: deps.ambiguousCount, implementationResolvedCount: impl.resolvedCount, implementationAmbiguousCount: impl.ambiguousCount };
+    return { ...callSummary, edgeCount: deps.edgeCount + callSummary.edgeCount + impl.edgeCount, dependencyResolvedCount: deps.resolvedCount, dependencyAmbiguousCount: deps.ambiguousCount, implementationResolvedCount: impl.resolvedCount, implementationAmbiguousCount: impl.ambiguousCount, implementationUnresolvedCount: impl.unresolvedCount };
   });
 }
 function nextGraphGeneration(db, workspaceId) {
@@ -1225,14 +1225,15 @@ function callEvidence(call, resolution, servicePath, op, destination) {
   return { sourceFile: call.source_file, sourceLine: call.source_line, file: call.source_file, line: call.source_line, repo: call.repoName, serviceAlias: call.alias, serviceAliasExpr: call.aliasExpr, destination, servicePath, operationPath: op, targetRepo: resolution.target?.repoName, targetOperation: resolution.target?.operationName, helperChain: call.helperChainJson ? JSON.parse(String(call.helperChainJson)) : void 0, candidates: resolution.candidates, candidateCount: resolution.candidates.length, resolutionStatus: resolution.status, resolutionReasons: resolution.reasons, analysisCompleteness: call.unresolved_reason ? "partial" : "complete", parserWarning: call.unresolved_reason ? { code: "parser_warning", message: call.unresolved_reason } : void 0 };
 }
 function linkImplementations(db, workspaceId, generation) {
-  const operations = db.prepare(`SELECT o.id operationId,o.operation_path operationPath,o.operation_name operationName,s.service_path servicePath,s.repo_id modelRepoId,r.name modelRepo,r.package_name modelPackage FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE r.workspace_id=?`).all(workspaceId);
+  const operations = db.prepare(`SELECT o.id operationId,o.operation_path operationPath,o.operation_name operationName,s.service_path servicePath,s.repo_id modelRepoId,r.name modelRepo,r.package_name modelPackage,r.kind modelKind FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE r.workspace_id=?`).all(workspaceId);
   let edgeCount = 0;
   let resolvedCount = 0;
   let ambiguousCount = 0;
+  let unresolvedCount = 0;
   for (const operation of operations) {
     const candidates = rankedImplementationCandidates(db, workspaceId, operation);
+    if (candidates.length === 0) continue;
     const accepted = candidates.filter((candidate) => candidate.accepted);
-    if (accepted.length === 0) continue;
     const topScore = accepted[0]?.score ?? 0;
     const winners = accepted.filter((candidate) => candidate.score === topScore);
     const unique = winners.length === 1 ? winners[0] : void 0;
@@ -1243,12 +1244,18 @@ function linkImplementations(db, workspaceId, generation) {
       modelPackage: { id: operation.modelRepoId, name: operation.modelRepo, packageName: operation.modelPackage },
       candidates: candidates.map((candidate, index) => candidateEvidence(candidate, index + 1))
     };
+    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);
+      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) : winners.map((row) => graphId(row.methodId)).join(","), unique ? 0.95 : 0.5, JSON.stringify(evidence), 0, unique ? null : "Ambiguous registered handler implementation candidates", generation);
     edgeCount += 1;
     if (unique) resolvedCount += 1;
     else ambiguousCount += 1;
   }
-  return { edgeCount, resolvedCount, ambiguousCount };
+  return { edgeCount, resolvedCount, ambiguousCount, unresolvedCount };
 }
 function rankedImplementationCandidates(db, workspaceId, operation) {
   const rows2 = implementationCandidates(db, workspaceId, operation);
@@ -1275,6 +1282,7 @@ function implementationCandidates(db, workspaceId, operation) {
       ? modelRepoId,
       ? modelRepo,
       ? modelPackage,
+      ? modelKind,
       ? servicePath,
       ? operationPath,
       ? operationName,
@@ -1283,6 +1291,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 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
@@ -1296,12 +1305,16 @@ function implementationCandidates(db, workspaceId, operation) {
     operation.modelRepoId,
     operation.modelRepo,
     operation.modelPackage,
+    operation.modelKind,
     operation.servicePath,
     operation.operationPath,
     operation.operationName,
     operation.modelRepoId,
     operation.modelRepoId,
     operation.servicePath,
+    normalizedOperation(String(operation.operationPath ?? "")),
+    operation.operationName,
+    operation.operationName,
     modelRepoGraphId,
     modelRepoGraphId,
     workspaceId,
@@ -1319,9 +1332,15 @@ function scoreImplementationCandidate(row, operation) {
   const localServicePathMatch = flag(row.localServicePathMatch);
   const applicationHasLocalServices = flag(row.applicationHasLocalServices);
   const appDependsOnModel = flag(row.appDependsOnModel);
+  const applicationHasLocalRegistrationForOperation = flag(row.applicationHasLocalRegistrationForOperation);
   const appDependsOnHandler = flag(row.appDependsOnHandler);
   const handlerDependsOnModel = flag(row.handlerDependsOnModel);
   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 registeredAndLinked = sameRepoRegistration && importSource;
+  const helperOwned = modelOriented && methodMatches && registeredAndLinked && sameRepoRegistration && !applicationHasLocalServices && !modelIsApplicationRepo && !modelIsHandlerRepo && !localServicePathMatch && !appDependsOnModel && !appDependsOnHandler && !handlerDependsOnModel;
   if (modelIsApplicationRepo) {
     score += 100;
     acceptedReasons.push("model package equals registration package");
@@ -1348,6 +1367,10 @@ function scoreImplementationCandidate(row, operation) {
     score += 20;
     acceptedReasons.push("handler package depends on model package");
   }
+  if (helperOwned) {
+    score += 60;
+    acceptedReasons.push("unique registered helper implementation for model-only operation");
+  }
   if (importSource) {
     score += 10;
     acceptedReasons.push("registration imports handler class");
@@ -1355,8 +1378,8 @@ function scoreImplementationCandidate(row, operation) {
   const hasOwnership = modelIsApplicationRepo || modelIsHandlerRepo;
   const hasCrossPackage = appDependsOnModel && (modelIsHandlerRepo || appDependsOnHandler || !importSource);
   const contradicted = applicationHasLocalServices && !localServicePathMatch && !appDependsOnModel && !hasOwnership;
-  if (!hasOwnership && !localServicePathMatch && !hasCrossPackage) rejectedReasons.push("missing direct ownership, exact local service path, or validated cross-package dependency evidence");
-  const accepted = !contradicted && (hasOwnership || localServicePathMatch || hasCrossPackage || handlerDependsOnModel);
+  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);
   if (!accepted && rejectedReasons.length === 0) rejectedReasons.push("candidate did not meet implementation ownership policy");
   return { ...row, methodId: Number(row.methodId), score, accepted, acceptedReasons, rejectedReasons };
 }
@@ -1383,6 +1406,7 @@ function candidateEvidence(candidate, rank) {
       directOwnership: { modelIsApplicationRepo: flag(candidate.modelIsApplicationRepo), modelIsHandlerRepo: flag(candidate.modelIsHandlerRepo) },
       localServicePathMatch: flag(candidate.localServicePathMatch),
       applicationHasLocalServices: flag(candidate.applicationHasLocalServices),
+      applicationHasLocalRegistrationForOperation: flag(candidate.applicationHasLocalRegistrationForOperation),
       appDependsOnModel: flag(candidate.appDependsOnModel),
       appDependsOnHandler: flag(candidate.appDependsOnHandler),
       handlerDependsOnModel: flag(candidate.handlerDependsOnModel),
@@ -1435,9 +1459,17 @@ function sourceFilesForStart(db, repoId, start) {
     operation,
     operation
   );
-  if (start.servicePath && rows2.length === 0) return void 0;
-  if (rows2.length === 0) return void 0;
-  return new Set(rows2.map((row) => row.sourceFile).filter(Boolean));
+  if (rows2.length > 0) return new Set(rows2.map((row) => row.sourceFile).filter(Boolean));
+  if (start.servicePath && operation) {
+    const implRows = db.prepare(`SELECT DISTINCT hc.source_file sourceFile
+      FROM cds_services s JOIN cds_operations o ON o.service_id=s.id
+      JOIN graph_edges e ON e.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND e.status='resolved' AND e.from_kind='operation' AND e.from_id=CAST(o.id AS TEXT)
+      JOIN handler_methods hm ON hm.id=CAST(e.to_id AS INTEGER)
+      JOIN handler_classes hc ON hc.id=hm.handler_class_id
+      WHERE (? IS NULL OR s.repo_id=?) AND s.service_path=? AND (o.operation_path=? OR o.operation_name=?)`).all(repoId, repoId, start.servicePath, operation, operation);
+    if (implRows.length > 0) return new Set(implRows.map((row) => row.sourceFile).filter(Boolean));
+  }
+  return void 0;
 }
 function startScope(db, start) {
   const repo = start.repo ? db.prepare(
@@ -1470,11 +1502,19 @@ function handlerFilesForOperation(db, operationId) {
   ).all(op.repoId, operation, operation, op.operationName);
   return new Set(rows2.map((row) => row.sourceFile).filter(Boolean));
 }
+function implementationEdge(db, operationId) {
+  return db.prepare("SELECT * 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,id LIMIT 1").get(operationId);
+}
+function handlerMethodNode(db, methodId) {
+  const row = db.prepare(`SELECT hm.id methodId,hm.method_name methodName,hm.decorator_value decoratorValue,hm.source_line sourceLine,hc.class_name className,hc.source_file sourceFile,r.name repoName,r.id repoId FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id JOIN repositories r ON r.id=hc.repo_id WHERE hm.id=?`).get(methodId);
+  if (!row) return void 0;
+  return { id: `handler_method:${methodId}`, kind: "handler_method", label: `${String(row.repoName)}:${String(row.className)}.${String(row.methodName)}`, ...row };
+}
 function implementationScope(db, operationId) {
-  const edge = db.prepare("SELECT * FROM graph_edges WHERE edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND status='resolved' AND from_kind='operation' AND from_id=? ORDER BY id LIMIT 1").get(operationId);
-  if (!edge) return { files: /* @__PURE__ */ new Set() };
+  const edge = implementationEdge(db, operationId);
+  if (!edge || edge.status !== "resolved") return { files: /* @__PURE__ */ new Set(), edge };
   const row = db.prepare("SELECT hc.repo_id repoId,hc.source_file sourceFile FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id WHERE hm.id=?").get(edge.to_id);
-  return { repoId: row?.repoId, files: new Set(row?.sourceFile ? [row.sourceFile] : []) };
+  return { repoId: row?.repoId, files: new Set(row?.sourceFile ? [row.sourceFile] : []), edge };
 }
 function includeCall(type, options) {
   if (!options.includeDb && type === "local_db_query") return false;
@@ -1573,6 +1613,22 @@ function trace(db, start, options) {
   const edges = [];
   const nodes = /* @__PURE__ */ new Map();
   const queue = scope.selectorMatched ? [{ repoId: scope.repo?.id, files: scope.sourceFiles, depth: 1 }] : [];
+  if (start.servicePath && (start.operation ?? start.operationPath)) {
+    const startOperation = normalizeOperation(start.operation ?? start.operationPath);
+    const row = db.prepare(`SELECT o.id operationId FROM cds_operations o JOIN cds_services s ON s.id=o.service_id WHERE s.service_path=? AND (o.operation_path=? OR o.operation_name=?) ORDER BY o.id LIMIT 1`).get(start.servicePath, startOperation, startOperation);
+    if (row?.operationId !== void 0) {
+      const opId = String(row.operationId);
+      const op = operationNode(db, opId);
+      const impl = implementationScope(db, opId);
+      if (op) nodes.set(String(op.id), op);
+      if (impl.edge) {
+        const implEvidence = JSON.parse(String(impl.edge.evidence_json || "{}"));
+        const handlerNode = impl.edge.status === "resolved" ? handlerMethodNode(db, impl.edge.to_id) : void 0;
+        if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);
+        edges.push({ step: 1, type: "operation_implemented_by_handler", from: op?.label ? String(op.label) : `${start.servicePath}/${startOperation ?? ""}`, to: handlerNode?.label ? String(handlerNode.label) : `${impl.edge.to_kind}:${impl.edge.to_id}`, evidence: implEvidence, confidence: Number(impl.edge.confidence ?? 0), unresolvedReason: impl.edge.status === "resolved" ? void 0 : String(impl.edge.unresolved_reason ?? impl.edge.status) });
+      }
+    }
+  }
   const seenScopes = /* @__PURE__ */ new Set();
   const seenEdges = /* @__PURE__ */ new Set();
   while (queue.length > 0) {
@@ -1628,10 +1684,26 @@ function trace(db, start, options) {
           confidence: Number(effectiveRow.confidence ?? call.confidence),
           unresolvedReason: effective.unresolvedReason
         });
-        if (effectiveRow.to_kind === "operation" && current.depth < maxDepth) {
+        if (effectiveRow.to_kind === "operation") {
           const implementation = implementationScope(db, effectiveRow.to_id);
+          if (implementation.edge) {
+            const implEvidence = JSON.parse(String(implementation.edge.evidence_json || "{}"));
+            const handlerNode = implementation.edge.status === "resolved" ? handlerMethodNode(db, implementation.edge.to_id) : void 0;
+            const implTo = handlerNode?.label ? String(handlerNode.label) : `${implementation.edge.to_kind}:${implementation.edge.to_id}`;
+            if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);
+            edges.push({
+              step: current.depth + 1,
+              type: "operation_implemented_by_handler",
+              from: to,
+              to: implTo,
+              evidence: implEvidence,
+              confidence: Number(implementation.edge.confidence ?? 0),
+              unresolvedReason: implementation.edge.status === "resolved" ? void 0 : String(implementation.edge.unresolved_reason ?? implementation.edge.status)
+            });
+          }
+          if (current.depth >= maxDepth) continue;
           const files = implementation.files.size > 0 ? implementation.files : handlerFilesForOperation(db, effectiveRow.to_id);
-          if (files.size > 0) {
+          if (implementation.edge?.status === "resolved" && files.size > 0) {
             const targetRepoId = implementation.repoId ?? 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(effectiveRow.to_id)?.repoId;
@@ -1678,4 +1750,4 @@ export {
   linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-HQMAFSRR.js.map
+//# sourceMappingURL=chunk-LQT67AU5.js.map