@saptools/service-flow 0.1.65 → 0.1.67

package/dist/index.d.ts

@@ -125,6 +125,8 @@ interface OutboundCallFact {
     payloadSummary?: string;
     sourceFile: string;
     sourceLine: number;
+    callSiteStartOffset?: number;
+    callSiteEndOffset?: number;
     confidence: number;
     unresolvedReason?: string;
     evidence?: Record<string, unknown>;
@@ -248,6 +250,10 @@ interface LinkWorkspaceResult {
     implementationResolvedCount: number;
     implementationAmbiguousCount: number;
     implementationUnresolvedCount: number;
+    subscriptionHandlerResolvedCount: number;
+    subscriptionHandlerAmbiguousCount: number;
+    subscriptionHandlerUnresolvedCount: number;
+    subscriptionHandlerMissingAssociationCount: number;
 }
 declare function linkWorkspace(db: Db, workspaceId: number, vars?: Record<string, string>): LinkWorkspaceResult;
 
@@ -263,11 +269,200 @@ declare function applyVariables(template: string | undefined, vars: Record<strin
 declare function extractPlaceholders(template: string | undefined): string[];
 declare function substituteVariables(template: string | undefined, vars: Record<string, string>): RuntimeSubstitution;
 
+type CompactStatus = 'resolved' | 'terminal' | 'inferred' | 'dynamic' | 'ambiguous' | 'unresolved' | 'cycle';
+interface CompactSourceContext {
+    schemaVersion: number;
+    analyzerVersion: string;
+    graphGeneration: number;
+}
+interface CompactHintV1 {
+    servicePath: string | null;
+    operationPath: string | null;
+    packageName: string | null;
+    repositoryName: string | null;
+    candidateFamily: string | null;
+    implementationRepo: string | null;
+}
+interface CompactStartV1 {
+    repo: string | null;
+    servicePath: string | null;
+    operation: string | null;
+    operationPath: string | null;
+    handler: string | null;
+}
+interface CompactQueryV1 {
+    depth: number;
+    includeAsync: boolean;
+    includeDb: boolean;
+    includeExternal: boolean;
+    dynamicMode: DynamicMode;
+    maxDynamicCandidates: number;
+    suppliedVariableNames: string[];
+    runtimeValuesOmitted: true;
+    implementationRepo: string | null;
+    implementationHints: CompactHintV1[];
+}
+interface CompactReferenceGroupV1 {
+    values: Array<number | string>;
+    total: number;
+    shown: number;
+    omitted: number;
+}
+interface CompactReferencesV1 {
+    graphEdgeIds?: CompactReferenceGroupV1;
+    outboundCallIds?: CompactReferenceGroupV1;
+    subscribeCallIds?: CompactReferenceGroupV1;
+    symbolCallIds?: CompactReferenceGroupV1;
+    operationIds?: CompactReferenceGroupV1;
+    symbolIds?: CompactReferenceGroupV1;
+    handlerMethodIds?: CompactReferenceGroupV1;
+}
+interface CompactDecisionV1 {
+    effectiveResolutionStatus?: string;
+    effectiveTarget?: string;
+    persistedResolutionStatus?: string;
+    persistedTarget?: string;
+    missingVariableNames?: string[];
+    missingVariableCount?: number;
+    shownMissingVariableCount?: number;
+    omittedMissingVariableCount?: number;
+    dynamicMode?: DynamicMode;
+    candidateCount?: number;
+    viableCandidateCount?: number;
+    rejectedCandidateCount?: number;
+    omittedCandidateCount?: number;
+    implementationStrategy?: string;
+    implementationGuided?: boolean;
+    implementationContextual?: boolean;
+    eventMatchStrategy?: string;
+    dispatchCertainty?: string;
+    eventSubscriptionCount?: number;
+    associationStatus?: string;
+    associationBasis?: string;
+    eventScope?: string;
+    callRole?: string;
+    factOrigin?: string;
+    roleSiteMatchCount?: number;
+    bodyExpansion?: string;
+    reasonCode?: string;
+    remediationHint?: string;
+    omittedRemediationHintCount?: number;
+}
+interface CompactEdgeDetailsV1 {
+    decision: CompactDecisionV1;
+    refs: CompactReferencesV1;
+}
+interface CompactDiagnosticDetailsV1 {
+    reasonCode?: string;
+    missingVariableNames?: string[];
+    missingVariableCount?: number;
+    shownMissingVariableCount?: number;
+    omittedMissingVariableCount?: number;
+    candidateCount?: number;
+    viableCandidateCount?: number;
+    rejectedCandidateCount?: number;
+    remediationHint?: string;
+    omittedHintCount?: number;
+}
+type CompactNodeRowV1 = [
+    id: string,
+    kind: string,
+    label: string,
+    repo: number | null,
+    file: number | null,
+    line: number | null
+];
+type CompactEdgeRowV1 = [
+    id: string,
+    traceOrdinals: number[],
+    step: number,
+    type: string,
+    from: string,
+    to: string,
+    status: CompactStatus,
+    confidence: number,
+    count: number,
+    details: CompactEdgeDetailsV1 | null
+];
+type CompactDiagnosticRowV1 = [
+    fullDiagnosticIndex: number,
+    severity: 'error' | 'warning' | 'info',
+    code: string,
+    message: string,
+    file: number | null,
+    line: number | null,
+    details: CompactDiagnosticDetailsV1 | null
+];
+interface CompactStatusCountsV1 {
+    resolved: number;
+    terminal: number;
+    inferred: number;
+    dynamic: number;
+    ambiguous: number;
+    unresolved: number;
+    cycle: number;
+}
+interface CompactGraphV1 {
+    schema: 'service-flow/compact-graph@1';
+    start: CompactStartV1;
+    query: CompactQueryV1;
+    source: CompactSourceContext;
+    summary: {
+        completeness: 'complete' | 'partial' | 'blocked';
+        fullTraceNodes: number;
+        fullTraceEdges: number;
+        fullTraceDiagnostics: number;
+        nodes: number;
+        edges: number;
+        collapsedEdges: number;
+        statusCounts: CompactStatusCountsV1;
+        projection: {
+            evidence: 'summary-only';
+            syntheticEndpoints: number;
+            omittedUnreferencedFullNodes: number;
+        };
+    };
+    repos: string[];
+    files: string[];
+    nodeColumns: ['id', 'kind', 'label', 'repo', 'file', 'line'];
+    nodes: CompactNodeRowV1[];
+    edgeColumns: [
+        'id',
+        'traceOrdinals',
+        'step',
+        'type',
+        'from',
+        'to',
+        'status',
+        'confidence',
+        'count',
+        'details'
+    ];
+    edges: CompactEdgeRowV1[];
+    diagnosticColumns: [
+        'fullDiagnosticIndex',
+        'severity',
+        'code',
+        'message',
+        'file',
+        'line',
+        'details'
+    ];
+    diagnostics: CompactDiagnosticRowV1[];
+}
+
 declare function trace(db: Db, start: TraceStart, options: TraceOptions): TraceResult;
 
+interface CompactTraceExecution {
+    trace: TraceResult;
+    compact: CompactGraphV1;
+}
+declare function compactTrace(db: Db, start: TraceStart, options: TraceOptions): CompactGraphV1;
+declare function traceAndCompact(db: Db, start: TraceStart, options: TraceOptions): CompactTraceExecution;
+
 declare function parseImplementationHint(value: string): ImplementationHint;
 
 declare function redactText(text: string): string;
 declare function redactValue(value: unknown): unknown;
 
-export { type DynamicMode, type ImplementationHint, type RuntimeSubstitution, type TraceOptions, applyVariables, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseImplementationHint, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace };
+export { type CompactDecisionV1, type CompactDiagnosticDetailsV1, type CompactDiagnosticRowV1, type CompactEdgeDetailsV1, type CompactEdgeRowV1, type CompactGraphV1, type CompactHintV1, type CompactNodeRowV1, type CompactQueryV1, type CompactReferenceGroupV1, type CompactReferencesV1, type CompactSourceContext, type CompactStartV1, type CompactStatus, type CompactStatusCountsV1, type CompactTraceExecution, type DynamicMode, type ImplementationHint, type RuntimeSubstitution, type TraceOptions, applyVariables, compactTrace, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseImplementationHint, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace, traceAndCompact };

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   applyVariables,
+  compactTrace,
   discoverRepositories,
   extractPlaceholders,
   linkWorkspace,
@@ -16,8 +17,9 @@ import {
   redactValue,
   stripQuotes,
   substituteVariables,
-  trace
-} from "./chunk-OONNRIDL.js";
+  trace,
+  traceAndCompact
+} from "./chunk-ZQABU7MR.js";
 
 // src/parsers/generated-constants-parser.ts
 import fs from "fs/promises";
@@ -40,6 +42,7 @@ async function parseGeneratedConstants(repoPath, filePath) {
 }
 export {
   applyVariables,
+  compactTrace,
   discoverRepositories,
   extractPlaceholders,
   linkWorkspace,
@@ -54,6 +57,7 @@ export {
   redactText,
   redactValue,
   substituteVariables,
-  trace
+  trace,
+  traceAndCompact
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/parsers/generated-constants-parser.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport type { GeneratedConstantFact } from '../types.js';\nimport { normalizePath, stripQuotes } from '../utils/path-utils.js';\nfunction lineOf(text: string, idx: number): number {\n  return text.slice(0, idx).split('\\n').length;\n}\nexport async function parseGeneratedConstants(\n  repoPath: string,\n  filePath: string\n): Promise<GeneratedConstantFact[]> {\n  const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');\n  return [\n    ...text.matchAll(\n      /(?:export\\s+)?(?:const|static\\s+readonly)\\s+(\\w+)\\s*=\\s*(['\"])([^'\"]+)\\2/g\n    )\n  ].map((m) => ({\n    name: m[1] ?? 'constant',\n    value: stripQuotes(m[3] ?? ''),\n    sourceFile: normalizePath(filePath),\n    sourceLine: lineOf(text, m.index ?? 0)\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AAGjB,SAAS,OAAO,MAAc,KAAqB;AACjD,SAAO,KAAK,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,EAAE;AACxC;AACA,eAAsB,wBACpB,UACA,UACkC;AAClC,QAAM,OAAO,MAAM,GAAG,SAAS,KAAK,KAAK,UAAU,QAAQ,GAAG,MAAM;AACpE,SAAO;AAAA,IACL,GAAG,KAAK;AAAA,MACN;AAAA,IACF;AAAA,EACF,EAAE,IAAI,CAAC,OAAO;AAAA,IACZ,MAAM,EAAE,CAAC,KAAK;AAAA,IACd,OAAO,YAAY,EAAE,CAAC,KAAK,EAAE;AAAA,IAC7B,YAAY,cAAc,QAAQ;AAAA,IAClC,YAAY,OAAO,MAAM,EAAE,SAAS,CAAC;AAAA,EACvC,EAAE;AACJ;","names":[]}
+{"version":3,"sources":["../src/parsers/generated-constants-parser.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport type { GeneratedConstantFact } from '../types.js';\nimport { normalizePath, stripQuotes } from '../utils/path-utils.js';\nfunction lineOf(text: string, idx: number): number {\n  return text.slice(0, idx).split('\\n').length;\n}\nexport async function parseGeneratedConstants(\n  repoPath: string,\n  filePath: string\n): Promise<GeneratedConstantFact[]> {\n  const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');\n  return [\n    ...text.matchAll(\n      /(?:export\\s+)?(?:const|static\\s+readonly)\\s+(\\w+)\\s*=\\s*(['\"])([^'\"]+)\\2/g\n    )\n  ].map((m) => ({\n    name: m[1] ?? 'constant',\n    value: stripQuotes(m[3] ?? ''),\n    sourceFile: normalizePath(filePath),\n    sourceLine: lineOf(text, m.index ?? 0)\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AAGjB,SAAS,OAAO,MAAc,KAAqB;AACjD,SAAO,KAAK,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,EAAE;AACxC;AACA,eAAsB,wBACpB,UACA,UACkC;AAClC,QAAM,OAAO,MAAM,GAAG,SAAS,KAAK,KAAK,UAAU,QAAQ,GAAG,MAAM;AACpE,SAAO;AAAA,IACL,GAAG,KAAK;AAAA,MACN;AAAA,IACF;AAAA,EACF,EAAE,IAAI,CAAC,OAAO;AAAA,IACZ,MAAM,EAAE,CAAC,KAAK;AAAA,IACd,OAAO,YAAY,EAAE,CAAC,KAAK,EAAE;AAAA,IAC7B,YAAY,cAAc,QAAQ;AAAA,IAClC,YAAY,OAAO,MAAM,EAAE,SAAS,CAAC;AAAA,EACvC,EAAE;AACJ;","names":[]}

package/package.json

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

package/src/cli/002-doctor-lifecycle.ts

@@ -0,0 +1,66 @@
+import type { Db } from '../db/connection.js';
+import { factLifecycleDiagnostic } from '../db/001-fact-lifecycle.js';
+import { ANALYZER_VERSION } from '../version.js';
+
+type Diagnostic = Record<string, unknown>;
+
+export function linkUpgradeWarnings(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  const lifecycle = factLifecycleDiagnostic(db, workspaceId);
+  if (lifecycle) return [lifecycle];
+  return [
+    ...schemaDriftDiagnostics(db, true, workspaceId),
+    ...analyzerVersionDiagnostics(db, true, workspaceId),
+  ].filter((item) => [
+    'schema_legacy_columns_present',
+    'external_target_columns_missing_data',
+    'reindex_required_after_upgrade',
+    'reindex_required_after_analyzer_upgrade',
+  ].includes(String(item.code)));
+}
+
+export function schemaDriftDiagnostics(
+  db: Db,
+  strict: boolean,
+  workspaceId?: number,
+): Diagnostic[] {
+  if (!strict) return [];
+  const columns = db.prepare('PRAGMA table_info(symbols)').all() as Array<{ name?: string }>;
+  const legacy = columns.filter((row) => [
+    'external_target_kind', 'external_target_id', 'external_target_label',
+    'external_target_dynamic',
+  ].includes(String(row.name))).map((row) => row.name);
+  const missing = db.prepare(`SELECT c.id id,c.source_file sourceFile,
+    c.source_line sourceLine FROM outbound_calls c
+    JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type='external_http'
+      AND (? IS NULL OR r.workspace_id=?)
+      AND (c.external_target_id IS NULL OR c.external_target_label IS NULL
+        OR c.external_target_kind IS NULL) LIMIT 20`).all(
+    workspaceId, workspaceId,
+  ) as Diagnostic[];
+  const out: Diagnostic[] = [];
+  if (legacy.length > 0) out.push({ severity: 'warning', code: 'schema_legacy_columns_present', message: 'Legacy external-target columns are present on symbols; run service-flow clean --db-only, then init/index/link to rebuild with the current schema.', scope: 'workspace', affectedColumns: legacy, remediation: 'service-flow clean --db-only && service-flow init <workspace> && service-flow index && service-flow link' });
+  if (missing.length > 0) out.push({ severity: 'warning', code: 'external_target_columns_missing_data', message: 'External HTTP calls are missing queryable external target metadata; reindex is required after upgrade.', scope: 'workspace', affectedRows: missing, remediation: 'service-flow index --force && service-flow link' });
+  if (legacy.length > 0 || missing.length > 0) out.push({ severity: 'warning', code: 'reindex_required_after_upgrade', message: 'This database cannot be made equivalent to a fresh index by relink alone.', scope: 'workspace', remediation: 'Rebuild or force reindex the workspace, then run service-flow doctor --strict.' });
+  return out;
+}
+
+export function analyzerVersionDiagnostics(
+  db: Db,
+  strict: boolean,
+  workspaceId?: number,
+): Diagnostic[] {
+  if (!strict) return [];
+  const rows = db.prepare(`SELECT name,
+    COALESCE(fact_analyzer_version,'legacy') factAnalyzerVersion
+    FROM repositories WHERE index_status='indexed'
+      AND (? IS NULL OR workspace_id=?)
+      AND COALESCE(fact_analyzer_version,'legacy')<>?`).all(
+    workspaceId, workspaceId, ANALYZER_VERSION,
+  ) as Diagnostic[];
+  if (rows.length === 0) return [];
+  return [{ severity: 'warning', code: 'reindex_required_after_analyzer_upgrade', message: 'Repository facts were produced by an older or unknown analyzer; run service-flow index --force before relink to apply current parser semantics.', scope: 'workspace', affectedRepositoryCount: rows.length, currentAnalyzerVersion: ANALYZER_VERSION, repositories: rows, remediation: 'service-flow index --force && service-flow link' }];
+}

package/src/cli/doctor.ts

@@ -2,27 +2,33 @@ import type { Db } from '../db/connection.js';
 import { classifyODataPathIntent, normalizeODataOperationInvocationPath } from '../linker/odata-path-normalizer.js';
 import { implementationHintSuggestions } from '../trace/implementation-hints.js';
 import { boundDoctorDiagnostics } from './001-doctor-projection.js';
-import { ANALYZER_VERSION } from '../version.js';
+import { factLifecycleDiagnostic } from '../db/001-fact-lifecycle.js';
+import {
+  analyzerVersionDiagnostics,
+  schemaDriftDiagnostics,
+} from './002-doctor-lifecycle.js';
+export { linkUpgradeWarnings } from './002-doctor-lifecycle.js';
 
 type Diagnostic = Record<string, unknown>;
 interface DoctorOptions {
   detail?: boolean;
-}
-
-export function linkUpgradeWarnings(db: Db): Diagnostic[] {
-  return [...schemaDriftDiagnostics(db, true), ...analyzerVersionDiagnostics(db, true)]
-    .filter((item) => ['schema_legacy_columns_present', 'external_target_columns_missing_data', 'reindex_required_after_upgrade', 'reindex_required_after_analyzer_upgrade'].includes(String(item.code)));
+  workspaceId?: number;
 }
 
 export function doctorDiagnostics(db: Db, strict: boolean, options: DoctorOptions = {}): Diagnostic[] {
+  const lifecycle = factLifecycleDiagnostic(db, options.workspaceId);
+  if (lifecycle?.code === 'schema_upgrade_required'
+    || lifecycle?.code === 'unsupported_future_schema')
+    return boundDoctorDiagnostics([lifecycle]);
   const diagnostics = db.prepare('SELECT severity,code,message,source_file sourceFile,source_line sourceLine FROM diagnostics ORDER BY id').all() as Diagnostic[];
   return boundDoctorDiagnostics([
+    ...(lifecycle ? [lifecycle] : []),
     ...diagnostics,
     ...healthDiagnostics(db, strict),
     ...remoteTargetWithoutImplementationDiagnostics(db, strict, Boolean(options.detail)),
     ...localServiceDiagnostics(db, strict),
-    ...schemaDriftDiagnostics(db, strict),
-    ...analyzerVersionDiagnostics(db, strict),
+    ...schemaDriftDiagnostics(db, strict, options.workspaceId),
+    ...analyzerVersionDiagnostics(db, strict, options.workspaceId),
     ...parserQualityDiagnostics(db, strict, options),
   ]);
 }
@@ -105,25 +111,6 @@ function remoteTargetWithoutImplementationExamples(db: Db, servicePath: string,
     ORDER BY r.name,c.source_file,c.source_line`).all(servicePath, operationPath) as Diagnostic[];
 }
 
-function schemaDriftDiagnostics(db: Db, strict: boolean): Diagnostic[] {
-  if (!strict) return [];
-  const columns = db.prepare('PRAGMA table_info(symbols)').all() as Array<{ name?: string }>;
-  const legacy = columns.filter((row) => ['external_target_kind', 'external_target_id', 'external_target_label', 'external_target_dynamic'].includes(String(row.name))).map((row) => row.name);
-  const missing = db.prepare("SELECT id id,source_file sourceFile,source_line sourceLine FROM outbound_calls WHERE call_type='external_http' AND (external_target_id IS NULL OR external_target_label IS NULL OR external_target_kind IS NULL) LIMIT 20").all() as Diagnostic[];
-  const out: Diagnostic[] = [];
-  if (legacy.length > 0) out.push({ severity: 'warning', code: 'schema_legacy_columns_present', message: 'Legacy external-target columns are present on symbols; run service-flow clean --db-only, then init/index/link to rebuild with the current schema.', scope: 'workspace', affectedColumns: legacy, remediation: 'service-flow clean --db-only && service-flow init <workspace> && service-flow index && service-flow link' });
-  if (missing.length > 0) out.push({ severity: 'warning', code: 'external_target_columns_missing_data', message: 'External HTTP calls are missing queryable external target metadata; reindex is required after upgrade.', scope: 'workspace', affectedRows: missing, remediation: 'service-flow index --force && service-flow link' });
-  if (legacy.length > 0 || missing.length > 0) out.push({ severity: 'warning', code: 'reindex_required_after_upgrade', message: 'This database cannot be made equivalent to a fresh index by relink alone.', scope: 'workspace', remediation: 'Rebuild or force reindex the workspace, then run service-flow doctor --strict.' });
-  return out;
-}
-
-function analyzerVersionDiagnostics(db: Db, strict: boolean): Diagnostic[] {
-  if (!strict) return [];
-  const rows = db.prepare("SELECT name,COALESCE(fact_analyzer_version,'legacy') factAnalyzerVersion FROM repositories WHERE index_status='indexed' AND COALESCE(fact_analyzer_version,'legacy')<>?").all(ANALYZER_VERSION) as Diagnostic[];
-  if (rows.length === 0) return [];
-  return [{ severity: 'warning', code: 'reindex_required_after_analyzer_upgrade', message: 'Repository facts were produced by an older or unknown analyzer; run service-flow index --force before relink to apply current parser semantics.', scope: 'workspace', affectedRepositoryCount: rows.length, currentAnalyzerVersion: ANALYZER_VERSION, repositories: rows, remediation: 'service-flow index --force && service-flow link' }];
-}
-
 function localServiceDiagnostics(db: Db, strict: boolean): Diagnostic[] {
   const rows = db.prepare("SELECT e.status status,e.unresolved_reason reason,e.evidence_json evidenceJson FROM graph_edges e JOIN outbound_calls c ON e.from_kind='call' AND c.id=CAST(e.from_id AS INTEGER) WHERE c.call_type='local_service_call'").all() as Array<{ status?: string; reason?: string | null; evidenceJson?: string }>;
   const implementationContext = rows.filter((row) => row.status === 'resolved' && String(row.evidenceJson ?? '').includes('implementation_context_caller_ownership')).length;