@saptools/service-flow 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.4
+
+- Resolved helper-returned service bindings exported through named export lists, including aliased exports, while preserving helper-chain evidence.
+- Parsed `cds.connect.to(alias, options)` as separate alias, destination, and service-path evidence so dynamic service paths can resolve with runtime variables.
+- Improved repository discovery so valid workspace-root Git repositories no longer prevent nested repository discovery, and empty `.git` markers are ignored.
+- Added explicit SQLite foreign-key constraints for fresh databases and recorded alias-expression evidence for service bindings.
+- Documented clearer operator guidance for test-file hygiene, doctor severity, and list/trace selector semantics.
+
+## 0.1.3
+
+- Propagated imported helper-returned `cds.connect.to(...)` bindings to caller-local service variables with helper-chain evidence.
+- Changed operation resolution to prefer ambiguous/dynamic/unresolved graph edges over confident operation-path-only links.
+- Improved chained CAP query entity extraction and table/JSON source-location evidence.
+- Hardened trace traversal with repo-aware downstream scopes, stable visited keys, edge de-duplication, and cycle markers.
+- Added safer clean behavior that only recursively removes marker-owned state directories.
+- Added `doctor --strict` to separate entity-only service noise from action-oriented default diagnostics.
+
 ## 0.1.2
 
 - Hardened SQLite CLI access with busy timeouts, retries, and larger read buffers for large graph/link runs.

package/README.md

@@ -27,6 +27,8 @@ Index independent Git repositories, persist CAP/CDS facts in SQLite, resolve cro
 - 🧠 **Dynamic edge support** — preserves parameterized destinations and service paths such as `svc_${objectCode}_process`, then lets traces apply runtime `--var key=value` values
 - 📊 **Multiple output modes** — renders human-readable tables, JSON for automation, and Mermaid diagrams for architecture docs
 - 🩺 **Diagnostics-first workflow** — records parse/index issues and exposes them through `service-flow doctor` instead of hiding partial analysis
+- 🧩 **CAP helper-aware binding evidence** — follows imported helpers exported directly or through named export lists and separates alias, destination, and service-path expressions for dynamic `cds.connect.to(alias, options)` calls
+- 🧭 **Nested workspace discovery** — scans nested repositories even when the selected root is itself a valid Git repository, while ignoring empty `.git` placeholders
 - 🔐 **Secret-aware summaries** — redacts sensitive keys in persisted summaries and CLI output while keeping useful source evidence
 - 📦 **Standalone CLI & typed package** — ships as an npm CLI with TypeScript definitions for integration into other saptools workflows
 
@@ -107,7 +109,6 @@ service-flow index --workspace /path/to/workspace --repo identity-service --forc
 | `--workspace <path>` | Workspace root or a path that can load the saved workspace configuration |
 | `--repo <name>` | Index only one repository by discovered repository name |
 | `--force` | Re-index even when file hashes indicate nothing changed |
-| `--concurrency <n>` | Reserved for future parallel indexing; currently defaults to `1` |
 
 ### 🔗 `service-flow link`
 
@@ -134,7 +135,8 @@ external destinations, and unresolved/dynamic candidates when edges exist.
 ```bash
 service-flow trace --workspace /path/to/workspace --repo facade-service --operation doWork
 service-flow trace --workspace /path/to/workspace --service /FacadeService --path /doWork --format json
-service-flow trace --workspace /path/to/workspace --handler EntryHandler --include-db --include-external --include-async
+service-flow trace --workspace /path/to/workspace --handler EntryHandler --depth 1 --format json
+service-flow trace --workspace /path/to/workspace --service /FacadeService --path /doWork --depth 2
 service-flow trace --workspace /path/to/workspace --repo facade-service --operation doWork --var objectCode=xx --var objectType=Thing
 ```
 
@@ -180,6 +182,7 @@ service-flow list repos --workspace /path/to/workspace
 service-flow list services --workspace /path/to/workspace --repo facade-service
 service-flow list operations --workspace /path/to/workspace --repo facade-service --service /FacadeService
 service-flow list calls --workspace /path/to/workspace --repo facade-service --operation doWork
+# `--operation` filters outgoing call paths/payloads; use trace/graph `--operation` for handler-origin traversal.
 ```
 
 | Command | Description |
@@ -193,11 +196,11 @@ service-flow list calls --workspace /path/to/workspace --repo facade-service --o
 
 - If a remote edge is unresolved, run `service-flow list calls --operation <name>`
   and `service-flow inspect operation <name>` to compare the captured call path
-  with indexed CDS operations.
+  with indexed CDS operations. Operation-path-only matches are shown as ambiguous/unresolved with candidate counts instead of high-confidence cross-repo links.
 - Service bindings are matched to outbound calls by repository, source file, and
   variable name to avoid false cross-file matches. If a helper-returned client is
-  not linked, keep the helper local/exported and ensure it returns
-  `cds.connect.to(...)` directly.
+  not linked, export the helper from a relative import target and ensure it returns
+  `cds.connect.to(...)` directly or through a simple wrapper. Trace evidence includes the caller variable, imported helper, source file, and exported symbol.
 - `SELECT.one.from(Entity)`, `SELECT.from(Entity)`, `INSERT.into(Entity)`,
   `UPDATE(Entity)`, and `DELETE.from(Entity)` are indexed as local database
   query entities when statically knowable.
@@ -221,10 +224,11 @@ service-flow inspect operation /doWork --workspace /path/to/workspace
 
 ### 🩺 `service-flow doctor`
 
-Print stored diagnostics. A clean workspace prints `No diagnostics recorded`.
+Print stored diagnostics. Default output suppresses high-noise entity-only service checks; `--strict` includes them. A clean workspace prints `No diagnostics recorded`.
 
 ```bash
 service-flow doctor --workspace /path/to/workspace
+service-flow doctor --workspace /path/to/workspace --strict
 ```
 
 ### 🧹 `service-flow clean`
@@ -239,7 +243,7 @@ service-flow clean --workspace /path/to/workspace
 | Flag | Description |
 | --- | --- |
 | `--db-only` | Remove only the configured SQLite database |
-| *(default)* | Remove the whole `.service-flow` state directory for the workspace |
+| *(default)* | Remove the marker-owned `.service-flow` state directory; custom/unowned or dangerous parent directories are refused |
 
 ---
 
@@ -279,6 +283,10 @@ service-flow trace --workspace /path/to/workspace --repo facade-service --operat
 
 When a concrete target exists after variable substitution, the trace shows both the parameterized evidence and the resolved match. When it does not, `service-flow` keeps the edge as a dynamic candidate or unresolved edge so the missing link remains visible.
 
+Service-binding evidence keeps these fields distinct: service alias, alias expression, destination expression, service-path expression, operation-path expression, and runtime placeholders. This is important for common CAP helpers such as `cds.connect.to(`remote_${code}`, { credentials: { destination: `remote_${code}`, path: `/${entityType}ProcessService` } })`, where the alias is not the service path.
+
+By default, production traces should be built from production source files. Keep generated credentials and local state out of git, and use explicit fixture/test workspaces when validating test-only mocked service clients so they do not pollute production graph interpretation.
+
 ---
 
 ## 📁 Workspace State
@@ -376,6 +384,7 @@ Run `service-flow index` after source, CDS, package metadata, or helper-package
 <summary><b>Why is an expected call unresolved?</b></summary>
 
 Check `service-flow doctor`, then inspect the facts with `service-flow list services`, `service-flow list operations`, and `service-flow list calls`. Dynamic destinations may need `--var key=value`, and custom wrappers may need new parser support.
+Default doctor output is intended to focus on actionable indexing or trace-impacting issues; use `--strict` when you need exhaustive model-shape diagnostics for entity-only or extension-heavy CDS models.
 
 </details>
 

package/TECHNICAL-NOTE.md

@@ -0,0 +1,14 @@
+# Service Flow 0.1.4 Resolution Notes
+
+- Imported helper bindings: TypeScript imports are resolved for relative modules. When a caller assigns `const client = await connectToService()`, the analyzer follows the imported symbol to an exported helper that returns `cds.connect.to(...)` and persists caller-variable evidence plus the helper source/export chain.
+- Candidate ranking: operation-path matches start as weak candidates. A resolved operation edge requires a strong signal such as exact service path, CDS alias/destination context, or explicit dynamic variable overrides. Otherwise candidates are preserved in edge evidence as ambiguous or unresolved.
+- Edge states: `REMOTE_CALL_RESOLVES_TO_OPERATION` is used only above the resolution threshold; `DYNAMIC_EDGE_CANDIDATE` preserves runtime-dependent service paths/destinations; `UNRESOLVED_EDGE` carries candidate counts and reasons when static evidence is insufficient.
+- Trace cycle safety: trace queues carry repository IDs, visited scope keys are independent of depth, graph edge IDs are emitted once, and revisiting an already-seen downstream operation scope creates a cycle marker instead of recursive expansion.
+- SQLite reliability: the package uses WAL, foreign keys, busy timeouts, and retries around the SQLite adapter. Statement failures throw before output rendering so commands do not report successful JSON/table/Mermaid results after an internal database failure.
+
+## 0.1.4 trace-correctness additions
+
+- Helper exports are normalized through a public-to-local export map, so `export { helper }` and `export { helper as publicHelper }` both resolve to the local declaration that contains the `cds.connect.to(...)` call.
+- Two-argument CAP connections keep alias expressions distinct from `credentials.destination` and `credentials.path` / `credentials.servicePath`; dynamic placeholders from all three fields are retained for later `--var` substitution.
+- Repository discovery validates `.git` markers using `HEAD`, `config`, or gitfile `gitdir:` content and keeps scanning children so outer workspaces can contain many nested repositories.
+- Fresh SQLite stores now declare core parent/child foreign keys with cascading cleanup for repository-owned facts.