@saptools/service-flow 0.1.54 → 0.1.56

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.56
+
+- Completed direct CAP query-builder execution-context indexing for builders returned by async or syntactically guaranteed-Promise callables and for static builder elements in awaited `Promise.all(...)`, while retaining one fact per logical statement and the existing conservative unknown-entity behavior.
+- Recorded stable direct execution-context evidence (`await`, `async_return`, `promise_return`, or `promise_aggregate`) without changing the SQLite schema, graph edge type, trace filters, or wrapper ownership.
+
+## 0.1.55
+
+- Indexed directly awaited CAP query-builder statements as local database calls, preserving exact builder-root evidence, fluent statement offsets, dynamic-entity warnings, method ownership, and the existing single `cds.run(...)` fact.
+- Made normal CLI stdout pipeline-safe: an early downstream pipe close stops further output without an unhandled `EPIPE` stack trace, while unrelated stream failures remain non-zero diagnostics.
+
 ## 0.1.54
 
 - Made contextual dynamic trace diagnostics runtime-current after `--var` substitution while retaining labelled pre-substitution binding state and distinct structural blockers.

package/README.md

@@ -156,6 +156,10 @@ service-flow link --workspace /path/to/workspace --force
 | `--workspace <path>` | Workspace to link |
 | `--force` | Accepted for workflow symmetry; linking always rebuilds graph edges |
 
+### Pipeline-safe output
+
+Normal command output is safe to pipe to a Unix consumer that intentionally stops reading early. A closed stdout pipe stops further output without an unhandled `EPIPE` stack trace; unrelated stdout failures still use the normal stderr diagnostic and non-zero exit outcome. Complete JSON, table, and Mermaid output bytes are unchanged.
+
 ### 🧵 `service-flow trace`
 
 Trace one starting point and render table, JSON, or Mermaid output. Trace now
@@ -170,7 +174,7 @@ Local CAP calls through `cds.services.<Service>.<operation>()`, bracket service
 
 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. Chained CAP DB queries inside `cds.run(...)` are parsed with TypeScript AST evidence for `SELECT`, `INSERT`, `UPDATE`, and `DELETE` forms. When the query target is genuinely dynamic, graph status remains terminal and JSON retains `parserWarning` evidence, while table and Mermaid render the target as `Entity: unknown` rather than a numeric call id.
+external destinations, and unresolved/dynamic candidates when edges exist. Chained CAP DB queries inside `cds.run(...)` and direct supported builders are parsed with TypeScript AST evidence for `SELECT`, `INSERT`, `UPSERT`, `UPDATE`, and `DELETE` forms. A direct builder needs both a recognized CAP root and a proven execution context: direct `await`, return from an `async` or syntactically guaranteed-Promise callable, or a static element of awaited `Promise.all([...])`. Plain query factories and unrelated methods named `from`, `where`, or `set` are not promoted to database facts. When the query target is genuinely dynamic, graph status remains terminal and JSON retains `parserWarning` evidence, while table and Mermaid render the target as `Entity: unknown` rather than a numeric call id.
 
 ```bash
 service-flow trace --workspace /path/to/workspace --repo facade-service --operation doWork
@@ -270,9 +274,13 @@ External HTTP facts use semantic terminal nodes instead of outbound-call row ids
   a concrete client. Trace evidence includes the caller variable, returned
   property, imported helper, source file, exported symbol, placeholders, and
   transaction alias steps.
-- `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.
+- Direct `SELECT.one.from(Entity)`, `SELECT.from(Entity)`,
+  `INSERT.into(Entity)`, `UPSERT.into(Entity)`, `UPDATE(Entity)`, and
+  `DELETE.from(Entity)` statements are indexed when directly awaited, returned
+  by an `async` or guaranteed-Promise callable, or supplied as static elements
+  to awaited `Promise.all([...])`; equivalent `cds.run(...)` queries retain
+  their wrapper classification. Plain non-promise query factories stay out of
+  local database facts.
 - `doctor` reports silent quality problems such as services without operations,
   handler repositories without CDS service facts, and an empty search index.
 
@@ -336,7 +344,7 @@ service-flow clean --workspace /path/to/workspace
 | Handler facts | `cds-routing-handlers` decorators, handler classes/methods, server registrations |
 | Service bindings | `cds.connect.to("alias")`, aliases from `package.json#cds.requires`, destination/service path expressions |
 | Outbound calls | `remote.send({ method, path })`, `remote.send({ query })`, `cds.services.Service.operation()`, service wrapper calls |
-| Local data access | `cds.run(SELECT...)` and local entity query evidence |
+| Local data access | directly executed CAP query builders, `cds.run(SELECT...)`, and local entity query evidence |
 | Async channels | Event Mesh-style `emit`, `publish`, and `on` facts |
 | External calls | Cloud SDK-style HTTP/destination calls and external edge evidence |
 | Generated constants | low-level `parseGeneratedConstants` parser output for integrations; not persisted as first-class graph facts in this patch |

package/TECHNICAL-NOTE.md

@@ -1,5 +1,17 @@
 # Service Flow Resolution Notes
 
+## 0.1.56 direct query execution-context notes
+
+- A structural direct CAP builder root now produces one `local_db_query` fact in four proven contexts: direct `await`, a return from the nearest `async` callable, a return from a callable with an AST-guaranteed `Promise` or `PromiseLike` contract, and a static direct element of awaited `Promise.all([...])`. Evidence adds `queryExecutionContext` as `await`, `async_return`, `promise_return`, or `promise_aggregate`, while retaining the existing direct dispatch and bounded source offsets.
+- Promise contracts accept direct, `globalThis`/`global` qualified, parenthesized, all-promise union, and promise-containing intersection forms. Plain returns, unresolved aliases, non-guaranteed unions, and async generators remain unindexed so a query factory is not mistaken for execution. Aggregate detection is limited to an awaited, unshadowed `Promise.all` array; arbitrary consumers and other aggregate methods are not promoted.
+- The parser still emits one fact for one logical statement. Direct builders nested in `cds.run(...)`, known service-client query payloads, or an already awaited aggregate element retain their established single owner/classifier. No schema or linker change is needed: normal source-symbol ownership, `HANDLER_RUNS_DB_QUERY` edges, and `--include-db` rendering consume these facts unchanged.
+
+## 0.1.55 direct query-builder and stdout notes
+
+- Direct, awaited CAP builders now create one `local_db_query` fact when their AST root is a supported `SELECT`, `INSERT`, `UPSERT`, `UPDATE`, or `DELETE` form. The parser follows fluent continuations and transparent TypeScript wrappers, records the direct dispatch marker plus root and statement offsets, and keeps ordinary member-name lookalikes out of database facts. A builder nested in `cds.run(...)` remains one wrapper-dispatched fact.
+- Static entities retain high confidence. Dynamic entity expressions retain the existing terminal unknown-entity behavior and parser warning; neither form evaluates application expressions. Fact insertion continues to use the logical statement location, so the narrowest executable symbol owns lifecycle and operation-method queries independently.
+- CLI command output uses one shared stdout policy. `EPIPE` from an early-closing Unix consumer marks output complete and suppresses later writes. Other stdout errors are reported through the existing failure path, so valid full JSON, table, and Mermaid bytes are unchanged and genuine failures still exit non-zero.
+
 ## 0.1.54 runtime-current diagnostics and selected handler notes
 
 - Contextual service-binding resolution now emits typed local trace state instead of passing a message string as control flow. `dynamic_missing`, `ambiguous_binding`, `ambiguous_operation`, `no_matching_operation`, and other conservative blockers remain distinguishable; `contextualPreSubstitutionState` preserves the historical attempt without changing a persisted graph row.