@saptools/service-flow 0.1.45 → 0.1.47

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.46
+
+- Improved ambiguous implementation diagnostics with ready-to-copy scoped hint suggestions for each blocked helper hop.
+- Persisted deterministic service-client ownership across helper boundaries, object and tuple destructuring, returned clients, and transaction aliases while preserving dynamic evidence for ambiguous flows.
+- Tightened OData operation-invocation normalization and dynamic wrapper-path evidence without promoting entity addressing paths to operation calls.
+- Kept strict doctor output concise by default with actionable categories and detail-mode evidence expansion.
+
 ## 0.1.45
 
 - Added repeatable scoped implementation hints with explicit selection and mismatch evidence while preserving conservative automatic and legacy repository selection.

package/README.md

@@ -481,39 +481,3 @@ MIT
 ---
 
 Made with ❤️ to make your work life easier!
-
-
-### Service-only trace policy
-
-`service-flow trace --service <path>` is intentionally not a broad workspace traversal. Provide `--operation`, `--path`, or `--handler`; otherwise the command returns a typed `trace_start_not_found` diagnostic and no edges.
-
-### Graph freshness and last-good snapshots
-
-Repository facts are parsed before publication and committed atomically. Failed indexing attempts record diagnostics and retain the last complete published snapshot and successful fingerprint. Successful fact publication marks the workspace graph stale until `service-flow link` rebuilds dependency, remote-call, and implementation edges for the current fact generation.
-
-### Cross-package implementation evidence
-
-Handler registrations persist parsed class names and import sources. Linking resolves implementation edges only through registered application evidence plus model and handler package dependency edges; a decorator-name match alone is not enough.
-
-### Graph variables
-
-The `graph` command accepts repeatable `--var key=value` options, matching `trace`, for runtime substitution previews in JSON or Mermaid output.
-
-
-### 0.1.17 parser ownership policy
-
-Outbound call extraction is AST-based and ignores comments, block comments, and string literals. CAP/service `.on(...)` registrations are indexed only when the receiver has CAP/service evidence, and top-level registrations receive `module:<relative-file>#event:<event-name>:<line>` synthetic owners. Generic event emitters such as desktop or window events are ignored by default rather than guessed as CAP async edges. Unsupported source shapes are surfaced through diagnostics and strict doctor ownerless categories instead of guessed graph edges.
-
-
-## 0.1.32 hardening notes
-
-Operation trace starts resolve indexed CDS operations before handler fallback. Ambiguous operation matches, ambiguous/rejected implementation edges, and resolved edges without an executable handler scope now fail closed with structured `resolutionStage` and `resolutionStatus` diagnostics and no speculative traversal. Handler fallback is only considered when no indexed CDS operation matches and the fallback is unique under the existing registration and ownership policy.
-
-Decorator signals are interpreted as resolved, absent, unsupported, or malformed. Only resolved string/template values, generated `Action<Name>.name`/`Func<Name>.name` constants, qualified generated constants ending in `.name`, and narrow safe `String(identifier)` wrappers can contradict method-name fallback. Unsupported expressions are preserved as evidence but are not treated as proof that a handler targets another operation.
-
-External HTTP facts persist queryable target kind, stable id, safe label, and dynamic flag on `outbound_calls`; graph evidence uses the same sanitized model. URL user info, fragments, query values, headers, cookies, credentials, tokens, API keys, and request/response bodies are not persisted. Legacy workspaces may relink from old evidence when possible, but full semantic enrichment requires re-index plus relink when old parser facts did not contain safe target metadata.
-
-Graph taxonomy now keeps CAP operation candidates separate from external HTTP targets. Dynamic, ambiguous, and unresolved CAP calls use operation-candidate semantics, external destinations/endpoints are produced only by `external_http` calls, and terminal local transport-client methods use transport-method semantics rather than external HTTP edges. `doctor --strict` reports external target quality and taxonomy consistency.
-### Runtime and parser hardening
-
-`service-flow` treats URL and destination templates with substitutions as dynamic external targets, preserves operation-path template evidence without promoting unrelated variables, and parses CDS `@(path: ...)` annotations from original source text. Service extension declarations using both `extend Name` and `extend service Name` are recognized for routing provenance.

package/dist/{chunk-BXSCE5CR.js → chunk-EGY2A4AT.js}

@@ -2316,6 +2316,171 @@ function substituteVariables(template, vars) {
   };
 }
 
+// src/trace/implementation-hints.ts
+function parseImplementationHint(value) {
+  const hint = {};
+  for (const part of value.split(",")) {
+    const separator = part.indexOf("=");
+    if (separator <= 0 || separator === part.length - 1) throw new Error(`Invalid implementation hint field: ${part}`);
+    assignHintField(hint, part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+  }
+  if (!hint.implementationRepo) throw new Error("Scoped implementation hint requires an implementation repo selection");
+  return { ...hint, implementationRepo: hint.implementationRepo };
+}
+function selectImplementation(rawEvidence, hints, legacyRepo) {
+  const evidence = asEvidence(rawEvidence);
+  const scoped = hints ?? [];
+  const matchingHints = scoped.filter((hint2) => hintMatchesEdge(hint2, evidence));
+  if (matchingHints.length === 0) {
+    if (legacyRepo) return selectCandidate(evidence, legacyHint(legacyRepo), "implementation_repo_hint");
+    const reason = scoped.length > 0 ? "no_scoped_hint_matched_edge" : "no_implementation_hint_supplied";
+    return { blocksAutomatic: false, evidence: { status: "not_matched", reason, strategy: "scoped_implementation_hint" } };
+  }
+  if (matchingHints.length > 1) {
+    return {
+      blocksAutomatic: true,
+      evidence: {
+        status: "tied",
+        reason: "multiple_scoped_hints_matched_edge",
+        strategy: "scoped_implementation_hint",
+        matchedHints: matchingHints,
+        candidateCount: matchingHints.length
+      }
+    };
+  }
+  const hint = matchingHints[0];
+  return hint ? selectCandidate(evidence, hint, "scoped_implementation_hint") : { blocksAutomatic: false, evidence: { status: "not_matched" } };
+}
+function implementationHintDiagnostic(selection, suggestions) {
+  if (!selection.blocksAutomatic || selection.methodId) return void 0;
+  return {
+    severity: "warning",
+    code: "implementation_hint_mismatch",
+    message: "Implementation hint did not select exactly one viable candidate",
+    hintStatus: selection.evidence.status,
+    candidateCount: selection.evidence.candidateCount,
+    implementationHintSuggestions: Array.isArray(suggestions) && suggestions.length > 0 ? suggestions : void 0,
+    implementationSelection: selection.evidence
+  };
+}
+function implementationHintSuggestions(rawEvidence) {
+  const evidence = asEvidence(rawEvidence);
+  const accepted = (evidence.candidates ?? []).filter((candidate) => candidate.accepted);
+  if (accepted.length < 2) return [];
+  const repos = selectableRepositories(accepted);
+  return accepted.flatMap((candidate) => {
+    const repo = candidate.handlerPackage?.name;
+    if (!repo || !repos.includes(repo)) return [];
+    const hint = suggestionHint(evidence, candidate, repo);
+    return [{
+      servicePath: hint.servicePath,
+      operationPath: hint.operationPath,
+      ambiguityReason: evidence.ambiguityReasons?.[0],
+      candidateFamily: hint.candidateFamily,
+      selectableImplementationRepositories: repos,
+      implementationRepo: repo,
+      hint,
+      cli: `--implementation-hint ${hintString(hint)}`
+    }];
+  });
+}
+function selectableRepositories(candidates) {
+  const repos = new Set(candidates.flatMap((candidate) => candidate.handlerPackage?.name ? [candidate.handlerPackage.name] : []));
+  return [...repos].filter((repo) => candidates.filter((candidate) => candidateMatchesRepo(candidate, repo)).length === 1).sort();
+}
+function assignHintField(hint, key, value) {
+  if (key === "service" || key === "servicePath") hint.servicePath = value;
+  else if (key === "operation" || key === "operationPath") hint.operationPath = value;
+  else if (key === "package" || key === "packageName") hint.packageName = value;
+  else if (key === "repository" || key === "repositoryName") hint.repositoryName = value;
+  else if (key === "family" || key === "candidateFamily") hint.candidateFamily = value;
+  else if (key === "repo" || key === "implementationRepo" || key === "select") hint.implementationRepo = value;
+  else throw new Error(`Unknown implementation hint field: ${key}`);
+}
+function selectCandidate(evidence, hint, strategy) {
+  const matches2 = (evidence.candidates ?? []).filter((candidate) => candidate.accepted && candidateMatchesRepo(candidate, hint.implementationRepo));
+  const selected = matches2.length === 1 ? matches2[0] : void 0;
+  if (!selected || selected.methodId === void 0) {
+    return {
+      blocksAutomatic: true,
+      evidence: {
+        status: matches2.length > 1 ? "tied" : "not_matched",
+        reason: matches2.length > 1 ? "hint_matched_multiple_candidates" : "hint_matched_zero_candidates",
+        strategy,
+        matchedHint: hint,
+        selectedRepo: hint.implementationRepo,
+        candidateCount: matches2.length
+      }
+    };
+  }
+  return {
+    methodId: String(selected.methodId),
+    blocksAutomatic: false,
+    evidence: {
+      status: "selected",
+      guided: true,
+      strategy,
+      matchedHint: hint,
+      selectedRepo: hint.implementationRepo,
+      selectedMethodId: selected.methodId,
+      ambiguityReason: evidence.ambiguityReasons?.[0]
+    }
+  };
+}
+function suggestionHint(evidence, candidate, repo) {
+  const servicePath = evidence.servicePath ?? candidate.servicePath;
+  const operationPath = evidence.operationPath ?? candidate.operationPath;
+  const family = usefulCandidateFamily(evidence, candidate);
+  return {
+    ...servicePath ? { servicePath } : {},
+    ...operationPath ? { operationPath } : {},
+    ...evidence.modelPackage?.packageName ? { packageName: evidence.modelPackage.packageName } : {},
+    ...evidence.modelPackage?.name ? { repositoryName: evidence.modelPackage.name } : {},
+    ...family ? { candidateFamily: family } : {},
+    implementationRepo: repo
+  };
+}
+function usefulCandidateFamily(evidence, candidate) {
+  const family = candidate.handlerPackage?.packageName;
+  if (!family) return void 0;
+  if ((evidence.candidateFamilies ?? []).some((item) => item.packageName === family)) return family;
+  const acceptedFamilies = new Set(
+    (evidence.candidates ?? []).filter((item) => item.accepted).flatMap((item) => item.handlerPackage?.packageName ? [item.handlerPackage.packageName] : [])
+  );
+  return acceptedFamilies.size > 1 ? family : void 0;
+}
+function hintString(hint) {
+  const fields = [
+    ["service", hint.servicePath],
+    ["operation", hint.operationPath],
+    ["package", hint.packageName],
+    ["repository", hint.repositoryName],
+    ["family", hint.candidateFamily],
+    ["repo", hint.implementationRepo]
+  ];
+  return fields.flatMap(([key, value]) => value ? [`${key}=${value}`] : []).join(",");
+}
+function hintMatchesEdge(hint, evidence) {
+  const model = evidence.modelPackage ?? evidence.candidates?.[0]?.modelPackage;
+  const familyNames = /* @__PURE__ */ new Set([
+    ...(evidence.candidateFamilies ?? []).flatMap((family) => family.packageName ? [family.packageName] : []),
+    ...(evidence.candidates ?? []).flatMap((candidate) => candidate.handlerPackage?.packageName ? [candidate.handlerPackage.packageName] : [])
+  ]);
+  return matches(hint.servicePath, evidence.servicePath ?? evidence.candidates?.[0]?.servicePath) && matches(hint.operationPath, evidence.operationPath ?? evidence.candidates?.[0]?.operationPath) && matches(hint.packageName, model?.packageName) && matches(hint.repositoryName, model?.name) && (!hint.candidateFamily || familyNames.has(hint.candidateFamily));
+}
+function candidateMatchesRepo(candidate, value) {
+  return candidate.handlerPackage?.name === value || candidate.handlerPackage?.packageName === value || candidate.sourceFile?.startsWith(value) === true;
+}
+function matches(expected, actual) {
+  return expected === void 0 || expected === actual;
+}
+function legacyHint(implementationRepo) {
+  return { implementationRepo };
+}
+function asEvidence(value) {
+  return value;
+}
+
 // src/linker/remote-query-target.ts
 function buildRemoteQueryTarget(input) {
   const entity = typeof input.queryEntity === "string" && input.queryEntity.trim() ? input.queryEntity.trim() : void 0;
@@ -2760,13 +2925,14 @@ function linkImplementations(db, workspaceId, generation) {
       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;
@@ -3005,112 +3171,6 @@ function normalizedOperation(value) {
   return value.startsWith("/") ? value.slice(1) : value;
 }
 
-// src/trace/implementation-hints.ts
-function parseImplementationHint(value) {
-  const hint = {};
-  for (const part of value.split(",")) {
-    const separator = part.indexOf("=");
-    if (separator <= 0 || separator === part.length - 1) throw new Error(`Invalid implementation hint field: ${part}`);
-    assignHintField(hint, part.slice(0, separator).trim(), part.slice(separator + 1).trim());
-  }
-  if (!hint.implementationRepo) throw new Error("Scoped implementation hint requires an implementation repo selection");
-  return { ...hint, implementationRepo: hint.implementationRepo };
-}
-function selectImplementation(rawEvidence, hints, legacyRepo) {
-  const evidence = asEvidence(rawEvidence);
-  const scoped = hints ?? [];
-  const matchingHints = scoped.filter((hint2) => hintMatchesEdge(hint2, evidence));
-  if (matchingHints.length === 0) {
-    if (legacyRepo) return selectCandidate(evidence, legacyHint(legacyRepo), "implementation_repo_hint");
-    const reason = scoped.length > 0 ? "no_scoped_hint_matched_edge" : "no_implementation_hint_supplied";
-    return { blocksAutomatic: false, evidence: { status: "not_matched", reason, strategy: "scoped_implementation_hint" } };
-  }
-  if (matchingHints.length > 1) {
-    return {
-      blocksAutomatic: true,
-      evidence: {
-        status: "tied",
-        reason: "multiple_scoped_hints_matched_edge",
-        strategy: "scoped_implementation_hint",
-        matchedHints: matchingHints,
-        candidateCount: matchingHints.length
-      }
-    };
-  }
-  const hint = matchingHints[0];
-  return hint ? selectCandidate(evidence, hint, "scoped_implementation_hint") : { blocksAutomatic: false, evidence: { status: "not_matched" } };
-}
-function implementationHintDiagnostic(selection) {
-  if (!selection.blocksAutomatic || selection.methodId) return void 0;
-  return {
-    severity: "warning",
-    code: "implementation_hint_mismatch",
-    message: "Implementation hint did not select exactly one viable candidate",
-    hintStatus: selection.evidence.status,
-    candidateCount: selection.evidence.candidateCount,
-    implementationSelection: selection.evidence
-  };
-}
-function assignHintField(hint, key, value) {
-  if (key === "service" || key === "servicePath") hint.servicePath = value;
-  else if (key === "operation" || key === "operationPath") hint.operationPath = value;
-  else if (key === "package" || key === "packageName") hint.packageName = value;
-  else if (key === "repository" || key === "repositoryName") hint.repositoryName = value;
-  else if (key === "family" || key === "candidateFamily") hint.candidateFamily = value;
-  else if (key === "repo" || key === "implementationRepo" || key === "select") hint.implementationRepo = value;
-  else throw new Error(`Unknown implementation hint field: ${key}`);
-}
-function selectCandidate(evidence, hint, strategy) {
-  const matches2 = (evidence.candidates ?? []).filter((candidate) => candidate.accepted && candidateMatchesRepo(candidate, hint.implementationRepo));
-  const selected = matches2.length === 1 ? matches2[0] : void 0;
-  if (!selected || selected.methodId === void 0) {
-    return {
-      blocksAutomatic: true,
-      evidence: {
-        status: matches2.length > 1 ? "tied" : "not_matched",
-        reason: matches2.length > 1 ? "hint_matched_multiple_candidates" : "hint_matched_zero_candidates",
-        strategy,
-        matchedHint: hint,
-        selectedRepo: hint.implementationRepo,
-        candidateCount: matches2.length
-      }
-    };
-  }
-  return {
-    methodId: String(selected.methodId),
-    blocksAutomatic: false,
-    evidence: {
-      status: "selected",
-      guided: true,
-      strategy,
-      matchedHint: hint,
-      selectedRepo: hint.implementationRepo,
-      selectedMethodId: selected.methodId,
-      ambiguityReason: evidence.ambiguityReasons?.[0]
-    }
-  };
-}
-function hintMatchesEdge(hint, evidence) {
-  const model = evidence.modelPackage ?? evidence.candidates?.[0]?.modelPackage;
-  const familyNames = /* @__PURE__ */ new Set([
-    ...(evidence.candidateFamilies ?? []).flatMap((family) => family.packageName ? [family.packageName] : []),
-    ...(evidence.candidates ?? []).flatMap((candidate) => candidate.handlerPackage?.packageName ? [candidate.handlerPackage.packageName] : [])
-  ]);
-  return matches(hint.servicePath, evidence.servicePath ?? evidence.candidates?.[0]?.servicePath) && matches(hint.operationPath, evidence.operationPath ?? evidence.candidates?.[0]?.operationPath) && matches(hint.packageName, model?.packageName) && matches(hint.repositoryName, model?.name) && (!hint.candidateFamily || familyNames.has(hint.candidateFamily));
-}
-function candidateMatchesRepo(candidate, value) {
-  return candidate.handlerPackage?.name === value || candidate.handlerPackage?.packageName === value || candidate.sourceFile?.startsWith(value) === true;
-}
-function matches(expected, actual) {
-  return expected === void 0 || expected === actual;
-}
-function legacyHint(implementationRepo) {
-  return { implementationRepo };
-}
-function asEvidence(value) {
-  return value;
-}
-
 // src/trace/evidence.ts
 function baseTraceEvidence(row, call, persistedEvidence, contextualEvidence) {
   const evidence = { ...persistedEvidence, ...contextualEvidence ?? {} };
@@ -3292,8 +3352,8 @@ function operationStartScope(db, repoId, start, hintOptions) {
   }
   if (impl.edge) {
     const evidence = parseEvidence(impl.edge.evidence_json);
-    const hintDiagnostic = implementationHintDiagnostic(hinted);
-    const diagnostics = [{ severity: "warning", code: impl.edge.status === "ambiguous" ? "trace_start_ambiguous" : "trace_start_implementation_unresolved", message: `Indexed operation matched but implementation edge is ${String(impl.edge.status ?? "unresolved")}`, resolutionStage: "implementation", resolutionStatus: impl.edge.status === "ambiguous" ? "ambiguous_implementation" : "rejected_implementation", implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, implementationAmbiguityReasons: evidence.ambiguityReasons, candidates: evidence.candidates }];
+    const hintDiagnostic = implementationHintDiagnostic(hinted, evidence.implementationHintSuggestions);
+    const diagnostics = [{ severity: "warning", code: impl.edge.status === "ambiguous" ? "trace_start_ambiguous" : "trace_start_implementation_unresolved", message: `Indexed operation matched but implementation edge is ${String(impl.edge.status ?? "unresolved")}`, resolutionStage: "implementation", resolutionStatus: impl.edge.status === "ambiguous" ? "ambiguous_implementation" : "rejected_implementation", implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, implementationAmbiguityReasons: evidence.ambiguityReasons, implementationHintSuggestions: evidence.implementationHintSuggestions, candidates: evidence.candidates }];
     return { operationId, diagnostics: hintDiagnostic ? [hintDiagnostic, ...diagnostics] : diagnostics };
   }
   return { operationId, diagnostics: [{ severity: "warning", code: "trace_start_implementation_unresolved", message: "Indexed operation matched but no implementation candidate exists", resolutionStage: "implementation", resolutionStatus: "operation_without_implementation" }] };
@@ -3691,9 +3751,9 @@ function trace(db, start, options) {
           const contextMethodId = contextSelection.methodId;
           const contextNode = contextMethodId ? handlerMethodNode(db, contextMethodId) : void 0;
           if (implementation.edge) {
-            const hintDiagnostic = implementationHintDiagnostic(contextSelection);
-            if (hintDiagnostic) diagnostics.unshift(hintDiagnostic);
             const implEvidence = JSON.parse(String(implementation.edge.evidence_json || "{}"));
+            const hintDiagnostic = implementationHintDiagnostic(contextSelection, implEvidence.implementationHintSuggestions);
+            if (hintDiagnostic) diagnostics.unshift(hintDiagnostic);
             const handlerNode = implementation.edge.status === "resolved" ? handlerMethodNode(db, implementation.edge.to_id) : contextNode;
             const implTo = handlerNode?.label ? String(handlerNode.label) : `${implementation.edge.to_kind}:${implementation.edge.to_id}`;
             if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);
@@ -3761,8 +3821,9 @@ export {
   applyVariables,
   extractPlaceholders,
   substituteVariables,
-  linkWorkspace,
   parseImplementationHint,
+  implementationHintSuggestions,
+  linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-BXSCE5CR.js.map
+//# sourceMappingURL=chunk-EGY2A4AT.js.map