@saptools/service-flow 0.1.72 → 0.1.73

package/dist/index.d.ts

@@ -242,7 +242,7 @@ interface GeneratedConstantFact {
     exported: boolean;
     stable: boolean;
     resolutionStatus: 'resolved' | 'refused';
-    unresolvedReason?: 'event_name_constant_member_not_string' | 'event_name_constant_container_mutable';
+    unresolvedReason?: 'event_name_constant_member_not_string' | 'event_name_constant_container_mutable' | 'event_name_constant_container_unsafe_reference' | 'event_name_constant_container_unsupported_shape';
     declarationStartOffset: number;
     declarationEndOffset: number;
     valueStartOffset: number;
@@ -353,6 +353,7 @@ interface LinkWorkspaceResult {
     subscriptionHandlerUnresolvedCount: number;
     subscriptionHandlerMissingAssociationCount: number;
     eventShapeCandidateCount: number;
+    eventShapeCandidateOmittedCount: number;
 }
 declare function linkWorkspace(db: Db, workspaceId: number, vars?: Record<string, string>): LinkWorkspaceResult;
 

package/dist/index.js

@@ -18,7 +18,7 @@ import {
   substituteVariables,
   trace,
   traceAndCompact
-} from "./chunk-Z6D433R5.js";
+} from "./chunk-32WOTGTS.js";
 export {
   applyVariables,
   compactTrace,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saptools/service-flow",
-  "version": "0.1.72",
+  "version": "0.1.73",
   "description": "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   "type": "module",
   "publishConfig": {

package/src/cli/doctor-event-quality.ts

@@ -8,6 +8,16 @@ const eventNameReason = `COALESCE(
     OR c.unresolved_reason GLOB 'event_name_*'
     THEN c.unresolved_reason END
 )`;
+const receiverReason = `CASE
+  WHEN json_extract(c.evidence_json,
+    '$.receiverClassification')='name_fallback'
+    THEN COALESCE(json_extract(c.evidence_json,
+      '$.receiverFallbackRefusedReason'),'name_fallback')
+  WHEN json_extract(c.evidence_json,
+    '$.receiverClassification')='unproven'
+    THEN COALESCE(json_extract(c.evidence_json,
+      '$.receiverUnresolvedReason'),'unproven')
+  ELSE 'missing' END`;
 
 function workspacePredicate(alias: string): string {
   return `(? IS NULL OR ${alias}.workspace_id=?)`;
@@ -52,6 +62,13 @@ function eventNameResolutionQuality(
     workspaceId, workspaceId,
   );
   const unresolved = count(aggregate?.unresolved);
+  const reasonCount = count(db.prepare(`SELECT COUNT(DISTINCT reason) count
+    FROM (SELECT ${eventNameReason} reason
+      FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+      WHERE c.call_type='async_emit' AND ${workspacePredicate('r')}
+        AND ${eventNameReason} IS NOT NULL)`).get(
+    workspaceId, workspaceId,
+  )?.count);
   return {
     severity: unresolved > 0 ? 'warning' : 'info',
     code: 'strict_event_name_resolution_quality',
@@ -59,6 +76,9 @@ function eventNameResolutionQuality(
     publicationTotal: count(aggregate?.total),
     unresolvedPublicationCount: unresolved,
     reasonBuckets: reasons,
+    reasonBucketCount: reasonCount,
+    shownReasonBucketCount: reasons.length,
+    omittedReasonBucketCount: Math.max(0, reasonCount - reasons.length),
     examples: unresolvedEventNameExamples(db, workspaceId),
     exampleCount: unresolved,
   };
@@ -204,8 +224,12 @@ function unmatchedSubscriptionQuality(
   db: Db,
   workspaceId?: number,
 ): Diagnostic {
-  const row = db.prepare(`SELECT COUNT(*) siteCount,
+  const row = db.prepare(`SELECT
+    COUNT(DISTINCT json_extract(e.evidence_json,'$.subscribeCallId'))
+      siteCount,
     SUM(CASE
+      WHEN json_extract(e.evidence_json,'$.materializedLoopEventName')
+        IS NOT NULL THEN 1
       WHEN json_extract(c.evidence_json,
         '$.subscriptionLoopRegistrationStatus')='enumerated'
         THEN CAST(json_extract(c.evidence_json,
@@ -215,7 +239,7 @@ function unmatchedSubscriptionQuality(
       ELSE 1 END) count,
     SUM(CASE WHEN json_extract(c.evidence_json,
       '$.subscriptionLoopRegistrationStatus')='unresolved'
-      THEN 1 ELSE 0 END) unknownMultiplicitySiteCount
+      THEN 1 ELSE 0 END) unknownMultiplicityEdgeCount
     FROM graph_edges e LEFT JOIN outbound_calls c
       ON c.id=CAST(json_extract(e.evidence_json,'$.subscribeCallId') AS INTEGER)
     WHERE e.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
@@ -228,23 +252,45 @@ function unmatchedSubscriptionQuality(
           AND publication.to_id=e.from_id)`).get(workspaceId, workspaceId);
   const total = count(row?.count);
   const siteCount = count(row?.siteCount);
+  const unknownSites = unknownMultiplicitySiteCount(db, workspaceId);
   return {
     severity: siteCount > 0 ? 'warning' : 'info',
     code: 'strict_event_subscription_without_publication_quality',
     message: 'Event subscriptions without a matching publication',
     unmatchedSubscriptionCount: total,
     unmatchedSubscriptionSiteCount: siteCount,
-    unknownMultiplicitySiteCount: count(row?.unknownMultiplicitySiteCount),
+    unknownMultiplicitySiteCount: unknownSites,
     examples: unmatchedSubscriptionRows(db, workspaceId),
     exampleCount: siteCount,
   };
 }
 
-function receiverProofQuality(
+function unknownMultiplicitySiteCount(
   db: Db,
   workspaceId?: number,
-): Diagnostic {
-  const row = db.prepare(`SELECT COUNT(*) eventTotal,
+): number {
+  const row = db.prepare(`SELECT COUNT(DISTINCT
+    json_extract(e.evidence_json,'$.subscribeCallId')) count
+    FROM graph_edges e LEFT JOIN outbound_calls c
+      ON c.id=CAST(json_extract(e.evidence_json,'$.subscribeCallId') AS INTEGER)
+    WHERE e.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND ${workspacePredicate('e')}
+      AND json_extract(c.evidence_json,
+        '$.subscriptionLoopRegistrationStatus')='unresolved'
+      AND NOT EXISTS (SELECT 1 FROM graph_edges publication
+        WHERE publication.workspace_id=e.workspace_id
+          AND publication.generation=e.generation
+          AND publication.edge_type='HANDLER_EMITS_EVENT'
+          AND publication.to_kind='event'
+          AND publication.to_id=e.from_id)`).get(workspaceId, workspaceId);
+  return count(row?.count);
+}
+
+function receiverProofAggregate(
+  db: Db,
+  workspaceId?: number,
+): Record<string, unknown> | undefined {
+  return db.prepare(`SELECT COUNT(*) eventTotal,
     SUM(CASE WHEN json_extract(c.evidence_json,
       '$.receiverClassification')='cap_evidence' THEN 1 ELSE 0 END) proven,
     SUM(CASE WHEN json_extract(c.evidence_json,
@@ -255,13 +301,13 @@ function receiverProofQuality(
     FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
     WHERE c.call_type IN ('async_emit','async_subscribe')
       AND ${workspacePredicate('r')}`).get(workspaceId, workspaceId);
-  const buckets = db.prepare(`SELECT CASE
-      WHEN json_extract(c.evidence_json,
-        '$.receiverClassification')='name_fallback' THEN 'name_fallback'
-      WHEN json_extract(c.evidence_json,
-        '$.receiverClassification')='unproven'
-        THEN COALESCE(c.unresolved_reason,'unproven')
-      ELSE 'missing' END reason,COUNT(*) count
+}
+
+function receiverReasonBuckets(
+  db: Db,
+  workspaceId?: number,
+): Array<Record<string, unknown>> {
+  return db.prepare(`SELECT ${receiverReason} reason,COUNT(*) count
     FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
     WHERE c.call_type IN ('async_emit','async_subscribe')
       AND ${workspacePredicate('r')}
@@ -270,6 +316,29 @@ function receiverProofQuality(
     GROUP BY reason ORDER BY count DESC,reason COLLATE BINARY LIMIT 16`).all(
     workspaceId, workspaceId,
   );
+}
+
+function receiverReasonBucketCount(
+  db: Db,
+  workspaceId?: number,
+): number {
+  const row = db.prepare(`SELECT COUNT(DISTINCT reason) count
+    FROM (SELECT ${receiverReason} reason
+      FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+      WHERE c.call_type IN ('async_emit','async_subscribe')
+        AND ${workspacePredicate('r')}
+        AND json_extract(c.evidence_json,'$.receiverClassification')
+          <>'cap_evidence')`).get(workspaceId, workspaceId);
+  return count(row?.count);
+}
+
+function receiverProofQuality(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic {
+  const row = receiverProofAggregate(db, workspaceId);
+  const buckets = receiverReasonBuckets(db, workspaceId);
+  const bucketCount = receiverReasonBucketCount(db, workspaceId);
   const questionable = count(row?.nameFallback) + count(row?.unproven);
   return {
     severity: questionable > 0 ? 'warning' : 'info',
@@ -281,6 +350,9 @@ function receiverProofQuality(
     unproven: count(row?.unproven),
     questionable,
     reasonBuckets: buckets,
+    reasonBucketCount: bucketCount,
+    shownReasonBucketCount: buckets.length,
+    omittedReasonBucketCount: Math.max(0, bucketCount - buckets.length),
     examples: receiverProofExamples(db, workspaceId),
     exampleCount: questionable,
   };
@@ -293,8 +365,11 @@ function receiverProofExamples(
   return db.prepare(`SELECT r.name repositoryName,c.call_type callType,
     c.source_file sourceFile,c.source_line sourceLine,
     json_extract(c.evidence_json,'$.receiverClassification')
-      receiverClassification,
-    c.unresolved_reason reason
+    receiverClassification,
+    COALESCE(json_extract(c.evidence_json,'$.receiverUnresolvedReason'),
+      json_extract(c.evidence_json,'$.receiverFallbackRefusedReason')) reason,
+    json_array_length(json_extract(c.evidence_json,
+      '$.consideredBindingSites')) consideredBindingSiteCount
     FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
     WHERE c.call_type IN ('async_emit','async_subscribe')
       AND ${workspacePredicate('r')}

package/src/cli.ts

@@ -4,6 +4,7 @@ import {
   createWorkspaceConfig,
   loadWorkspaceConfig,
   saveWorkspaceConfig,
+  type WorkspaceConfig,
 } from './config/workspace-config.js';
 import { openDatabase, openReadOnlyDatabase, type Db } from './db/connection.js';
 import {
@@ -20,6 +21,7 @@ import { classifyRepository } from './discovery/classify-repository.js';
 import { indexWorkspace } from './indexer/workspace-indexer.js';
 import { linkWorkspace } from './linker/cross-repo-linker.js';
 import { doctorDiagnostics, linkUpgradeWarnings } from './cli/doctor.js';
+import { factLifecycleDiagnostic } from './db/fact-lifecycle.js';
 import { trace } from './trace/trace-engine.js';
 import { compactTrace } from './trace/compact-trace.js';
 import {
@@ -33,6 +35,9 @@ import { renderDoctorDiagnostics } from './output/doctor-output.js';
 import { renderMermaid } from './output/mermaid-output.js';
 import { createStdoutWriter } from './output/stdout-policy.js';
 import { renderCompactJson } from './output/compact-json-output.js';
+import {
+  projectRepositoryInspection,
+} from './output/repository-inspection.js';
 import { VERSION } from './version.js';
 import type {
   DynamicMode,
@@ -122,6 +127,7 @@ async function withWorkspace<T>(
     db: ReturnType<typeof openDatabase>,
     workspaceId: number,
     rootPath: string,
+    config: WorkspaceConfig,
   ) => Promise<T> | T,
 ): Promise<T> {
   const config = await loadWorkspaceConfig(workspace);
@@ -130,7 +136,7 @@ async function withWorkspace<T>(
     const row = getWorkspace(db, config.rootPath);
     const workspaceId =
       row?.id ?? upsertWorkspace(db, config.rootPath, config.dbPath);
-    return await fn(db, workspaceId, config.rootPath);
+    return await fn(db, workspaceId, config.rootPath, config);
   } finally {
     db.close();
   }
@@ -275,10 +281,11 @@ function registerIndexCommand(program: Command): void {
     .option('--force')
     .action(
       (opts: { workspace?: string; repo?: string; force?: boolean }) =>
-        void withWorkspace(opts.workspace, async (db, workspaceId) => {
+        void withWorkspace(opts.workspace, async (db, workspaceId, _root, config) => {
           const r = await indexWorkspace(db, workspaceId, {
             repo: opts.repo,
             force: Boolean(opts.force),
+            eventEnvironmentKeys: config.eventEnvironmentKeys,
           });
           const outcome = indexCommandOutcome(r);
           writeStdout(outcome.stdout);
@@ -298,7 +305,7 @@ function registerLinkCommand(program: Command): void {
           const r = linkWorkspace(db, workspaceId);
           const upgradeWarnings = linkUpgradeWarnings(db, workspaceId);
           writeStdout(
-            `${upgradeWarnings.length ? `Warnings: ${upgradeWarnings.map((item) => String(item.code)).join(', ')}. Run service-flow doctor --strict for remediation.\n` : ''}Linked ${r.edgeCount} edges: ${r.remoteResolvedCount} remote operation calls resolved, ${r.localResolvedCount} local operation calls resolved, ${r.unresolvedCount} unresolved operation calls, ${r.ambiguousCount} ambiguous operation calls, ${r.dynamicCount} dynamic operation calls, ${r.terminalCount} terminal call edges, ${r.dependencyResolvedCount} dependency resolved, ${r.dependencyAmbiguousCount} dependency ambiguous, ${r.implementationResolvedCount} implementation resolved, ${r.implementationAmbiguousCount} implementation ambiguous, ${r.implementationUnresolvedCount} implementation unresolved, ${r.subscriptionHandlerResolvedCount} subscription handlers resolved, ${r.subscriptionHandlerAmbiguousCount} subscription handlers ambiguous, ${r.subscriptionHandlerUnresolvedCount} subscription handlers unresolved, ${r.subscriptionHandlerMissingAssociationCount} subscription handler associations missing, ${r.eventShapeCandidateCount} event shape candidates\n`,
+            `${upgradeWarnings.length ? `Warnings: ${upgradeWarnings.map((item) => String(item.code)).join(', ')}. Run service-flow doctor --strict for remediation.\n` : ''}Linked ${r.edgeCount} edges: ${r.remoteResolvedCount} remote operation calls resolved, ${r.localResolvedCount} local operation calls resolved, ${r.unresolvedCount} unresolved operation calls, ${r.ambiguousCount} ambiguous operation calls, ${r.dynamicCount} dynamic operation calls, ${r.terminalCount} terminal call edges, ${r.dependencyResolvedCount} dependency resolved, ${r.dependencyAmbiguousCount} dependency ambiguous, ${r.implementationResolvedCount} implementation resolved, ${r.implementationAmbiguousCount} implementation ambiguous, ${r.implementationUnresolvedCount} implementation unresolved, ${r.subscriptionHandlerResolvedCount} subscription handlers resolved, ${r.subscriptionHandlerAmbiguousCount} subscription handlers ambiguous, ${r.subscriptionHandlerUnresolvedCount} subscription handlers unresolved, ${r.subscriptionHandlerMissingAssociationCount} subscription handler associations missing, ${r.eventShapeCandidateCount} event shape candidates, ${r.eventShapeCandidateOmittedCount} event shape candidates omitted by the link cap\n`,
           );
         }).catch(fail),
     );
@@ -329,22 +336,23 @@ function registerTraceCommand(program: Command): void {
 function listRepositoriesCommand(
   opts: { workspace?: string },
 ): Promise<void> {
-  return withReadOnlyWorkspace(opts.workspace, (db, workspaceId) =>
-    writeStdout(
-      renderJson(
-        listRepositories(db, workspaceId).map((repo) => ({
-          name: repo.name,
-          kind: repo.kind,
-          packageName: repo.package_name,
-        })),
-      ),
+  return withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+    if (writeLifecycleBlock(db, workspaceId)) return;
+    writeStdout(renderJson(
+      listRepositories(db, workspaceId).map((repo) => ({
+        name: repo.name,
+        kind: repo.kind,
+        packageName: repo.package_name,
+      })),
     ));
+  });
 }
 
 function listServicesCommand(
   opts: { workspace?: string; repo?: string },
 ): Promise<void> {
   return withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+    if (writeLifecycleBlock(db, workspaceId)) return;
     const selection = opts.repo
       ? selectRepository(db, opts.repo, workspaceId) : {};
     if (selection.diagnostic) {
@@ -363,6 +371,7 @@ function listOperationsCommand(
   opts: { workspace?: string; repo?: string; service?: string },
 ): Promise<void> {
   return withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+    if (writeLifecycleBlock(db, workspaceId)) return;
     const selection = opts.repo
       ? selectRepository(db, opts.repo, workspaceId) : {};
     if (selection.diagnostic) {
@@ -383,6 +392,7 @@ function listCallsCommand(
   opts: { workspace?: string; repo?: string; operation?: string },
 ): Promise<void> {
   return withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+    if (writeLifecycleBlock(db, workspaceId)) return;
     const selection = opts.repo
       ? selectRepository(db, opts.repo, workspaceId) : {};
     if (selection.diagnostic) {
@@ -460,9 +470,12 @@ function inspectRepositoryCommand(
   opts: { workspace?: string },
 ): Promise<void> {
   return withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+    if (writeLifecycleBlock(db, workspaceId)) return;
     const selection = selectRepository(db, name, workspaceId);
     writeStdout(renderJson(
-      selection.repo ?? selection.diagnostic ?? { error: 'repo not found' },
+      selection.repo
+        ? projectRepositoryInspection(selection.repo)
+        : selection.diagnostic ?? { error: 'repo not found' },
     ));
   });
 }
@@ -472,6 +485,7 @@ function inspectOperationCommand(
   opts: { workspace?: string },
 ): Promise<void> {
   return withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+    if (writeLifecycleBlock(db, workspaceId)) return;
     const rows = db.prepare(
       'SELECT o.* 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=? AND (o.operation_name=? OR o.operation_path=?)',
     ).all(workspaceId, selector, selector);
@@ -479,6 +493,14 @@ function inspectOperationCommand(
   });
 }
 
+function writeLifecycleBlock(db: Db, workspaceId: number): boolean {
+  const diagnostic = factLifecycleDiagnostic(db, workspaceId);
+  if (!diagnostic) return false;
+  writeStdout(renderJson([diagnostic]));
+  process.exitCode = 1;
+  return true;
+}
+
 function registerInspectCommands(program: Command): void {
   const inspect = program.command('inspect');
   inspect

package/src/config/workspace-config.ts

@@ -7,10 +7,24 @@ import {
   DEFAULT_DB_FILE,
   DEFAULT_IGNORES,
 } from './defaults.js';
+import {
+  DEFAULT_EVENT_ENVIRONMENT_KEYS,
+  EVENT_ENVIRONMENT_KEY_CAP,
+  normalizeEventEnvironmentKeys,
+  validEventEnvironmentKey,
+} from '../parsers/environment-declarations.js';
+const environmentKeys = z.array(
+  z.string().refine(validEventEnvironmentKey),
+).min(1).max(EVENT_ENVIRONMENT_KEY_CAP).transform(
+  normalizeEventEnvironmentKeys,
+);
 const schema = z.object({
   rootPath: z.string(),
   dbPath: z.string(),
   ignore: z.array(z.string()),
+  eventEnvironmentKeys: environmentKeys.default(
+    [...DEFAULT_EVENT_ENVIRONMENT_KEYS],
+  ),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -55,6 +69,7 @@ export function createWorkspaceConfig(
     rootPath: root,
     dbPath: path.resolve(dbPath ?? defaultDbPath(root)),
     ignore,
+    eventEnvironmentKeys: [...DEFAULT_EVENT_ENVIRONMENT_KEYS],
     createdAt: now,
     updatedAt: now,
   };

package/src/db/current-fact-semantics.ts

@@ -12,6 +12,7 @@ import {
 } from './binding-fact-semantics.js';
 import { invalidSymbolFactCategories } from './symbol-call-semantics.js';
 import { invalidEventFactCategories } from './event-fact-semantics.js';
+import { eventSiteCategories } from './event-site-semantics.js';
 
 export type PackageFactPhase = 'pre_package' | 'terminal';
 
@@ -257,31 +258,6 @@ function duplicateSymbolCallCategories(
   return category('symbol_call_site_duplicate', duplicate);
 }
 
-function eventNameCategories(
-  db: Db,
-  workspaceId?: number,
-): FactSemanticCategoryCount[] {
-  const invalidName = count(db, `SELECT COUNT(*) count
-    FROM outbound_calls fact JOIN repositories r ON r.id=fact.repo_id
-    WHERE ${currentRepositoryPredicate()}
-      AND fact.call_type IN ('async_emit','async_subscribe')
-      AND (typeof(fact.event_name_expr)<>'text'
-        OR length(fact.event_name_expr)=0)`, workspaceId);
-  const duplicate = count(db, `SELECT COUNT(*) count FROM (
-    SELECT fact.repo_id,fact.source_file,fact.call_site_start_offset,
-      fact.call_site_end_offset,COUNT(*) duplicate_count
-    FROM outbound_calls fact JOIN repositories r ON r.id=fact.repo_id
-    WHERE ${currentRepositoryPredicate()}
-      AND fact.call_type='async_subscribe'
-    GROUP BY fact.repo_id,fact.source_file,fact.call_site_start_offset,
-      fact.call_site_end_offset HAVING COUNT(*)<>1
-  )`, workspaceId);
-  return [
-    ...category('event_name_invalid', invalidName),
-    ...category('async_subscription_site_duplicate', duplicate),
-  ];
-}
-
 function outboundOwnerCount(db: Db, workspaceId?: number): number {
   return count(db, `WITH eligible AS (
     SELECT fact.id fact_id,s.id symbol_id,
@@ -684,7 +660,7 @@ export function invalidFactSemanticCategories(
     ...operationCategories(db, workspaceId),
     ...callSpanCategories(db, workspaceId),
     ...duplicateSymbolCallCategories(db, workspaceId),
-    ...eventNameCategories(db, workspaceId),
+    ...eventSiteCategories(db, workspaceId),
     ...invalidEventFactCategories(db, workspaceId, phase),
     ...ownerCategories(db, workspaceId),
     ...bindingCategories(db, workspaceId),