@saptools/service-flow 0.1.65 → 0.1.67

package/src/trace/013-trace-root-scopes.ts

@@ -0,0 +1,279 @@
+import type { Db } from '../db/connection.js';
+import { currentFactLifecycleDiagnostic } from '../db/001-fact-lifecycle.js';
+import type { ContextBinding } from './008-contextual-runtime-state.js';
+import {
+  resolveTraversalWorkspaceId,
+  type TraversalScopeScheduler,
+  type TraversalScopeState,
+} from './010-traversal-scope.js';
+
+export interface TraceQueueScope {
+  repoId?: number;
+  files?: Set<string>;
+  symbolIds?: Set<number>;
+  depth: number;
+  context: Map<string, ContextBinding>;
+  state: TraversalScopeState;
+  unownedOnly?: boolean;
+  rootObservationOnly?: boolean;
+}
+
+export interface PendingTraceRootScope {
+  repoId: number;
+  files: Set<string>;
+  symbolIds: Set<number>;
+  unownedOnly: boolean;
+  rootObservationOnly: boolean;
+}
+
+interface RootCallRow {
+  id: number;
+  repoId: number;
+  repoName: string;
+  workspaceId: number;
+  graphGeneration: number;
+  sourceSymbolId?: number | null;
+  sourceFile: string;
+  callType: string;
+  eventName?: string | null;
+}
+
+export interface TraceRootPlan {
+  workspaceId?: number;
+  queue: TraceQueueScope[];
+  pendingRoots: PendingTraceRootScope[];
+  diagnostic?: Record<string, unknown>;
+}
+
+export function createTraceRootPlan(
+  db: Db,
+  scheduler: TraversalScopeScheduler,
+  scope: {
+    repoId?: number;
+    files?: Set<string>;
+    symbolIds?: Set<number>;
+    selectorMatched: boolean;
+  },
+  requestedWorkspaceId: number | undefined,
+  includeAsync: boolean,
+): TraceRootPlan {
+  const workspaceId = resolveTraversalWorkspaceId(
+    db, requestedWorkspaceId, scope.repoId,
+  );
+  if (workspaceId !== undefined) {
+    const lifecycle = currentFactLifecycleDiagnostic(db, workspaceId);
+    if (lifecycle) return {
+      workspaceId, queue: [], pendingRoots: [], diagnostic: lifecycle,
+    };
+  }
+  if (!scope.selectorMatched)
+    return { workspaceId, queue: [], pendingRoots: [] };
+  if (workspaceId === undefined) return {
+    workspaceId, queue: [], pendingRoots: [],
+    diagnostic: workspaceAmbiguityDiagnostic(db),
+  };
+  const pendingRoots = includeAsync
+    ? rootScopes(db, workspaceId, scope) : undefined;
+  if (pendingRoots)
+    return { workspaceId, queue: [], pendingRoots };
+  return {
+    workspaceId,
+    queue: initialQueue(scheduler, workspaceId, scope),
+    pendingRoots: [],
+  };
+}
+
+export function nextPendingRoot(
+  pendingRoots: PendingTraceRootScope[],
+  scheduler: TraversalScopeScheduler,
+  workspaceId: number,
+): TraceQueueScope | undefined {
+  while (pendingRoots.length > 0) {
+    const root = pendingRoots.shift();
+    if (!root) return undefined;
+    const context = new Map<string, ContextBinding>();
+    const scheduled = scheduler.schedule({
+      workspaceId, repoId: root.repoId, files: root.files,
+      symbolIds: root.symbolIds, context,
+    });
+    if (scheduled.kind !== 'scheduled') continue;
+    return { ...root, depth: 1, context, state: scheduled.state };
+  }
+  return undefined;
+}
+
+export function claimPendingRoot(
+  pendingRoots: PendingTraceRootScope[],
+  target: {
+    repoId?: number;
+    files: ReadonlySet<string>;
+    symbolIds: ReadonlySet<number>;
+  },
+): boolean {
+  const index = pendingRoots.findIndex((root) =>
+    target.repoId === root.repoId
+    && !root.unownedOnly
+    && setsEqual(root.files, target.files)
+    && setsEqual(root.symbolIds, target.symbolIds));
+  if (index < 0) return false;
+  pendingRoots.splice(index, 1);
+  return true;
+}
+
+export function enqueueCausalScope(
+  queue: TraceQueueScope[],
+  pendingRoots: PendingTraceRootScope[],
+  scope: TraceQueueScope,
+): void {
+  if (scope.context.size === 0 && scope.files && scope.symbolIds)
+    claimPendingRoot(pendingRoots, {
+      repoId: scope.repoId, files: scope.files, symbolIds: scope.symbolIds,
+    });
+  queue.push(scope);
+}
+
+function initialQueue(
+  scheduler: TraversalScopeScheduler,
+  workspaceId: number,
+  scope: { repoId?: number; files?: Set<string>; symbolIds?: Set<number> },
+): TraceQueueScope[] {
+  const context = new Map<string, ContextBinding>();
+  const scheduled = scheduler.schedule({
+    workspaceId, repoId: scope.repoId, files: scope.files,
+    symbolIds: scope.symbolIds, context,
+  });
+  return scheduled.kind === 'scheduled' ? [{
+    repoId: scope.repoId, files: scope.files, symbolIds: scope.symbolIds,
+    depth: 1, context, state: scheduled.state,
+  }] : [];
+}
+
+function rootScopes(
+  db: Db,
+  workspaceId: number,
+  scope: { repoId?: number; files?: Set<string>; symbolIds?: Set<number> },
+): PendingTraceRootScope[] | undefined {
+  if (scope.symbolIds && scope.symbolIds.size === 1) return undefined;
+  const calls = scopedRootCalls(db, workspaceId, scope);
+  if (!hasExactDispatch(db, calls)) return undefined;
+  if (scope.symbolIds && scope.symbolIds.size > 1)
+    return selectedSymbolRoots(db, workspaceId, scope.symbolIds);
+  return callOwnerRoots(calls);
+}
+
+function scopedRootCalls(
+  db: Db,
+  workspaceId: number,
+  scope: { repoId?: number; files?: Set<string>; symbolIds?: Set<number> },
+): RootCallRow[] {
+  return rootCalls(db, workspaceId, scope.repoId, scope.files)
+    .filter((call) => !scope.symbolIds
+      || (typeof call.sourceSymbolId === 'number'
+        && scope.symbolIds.has(call.sourceSymbolId)));
+}
+
+function callOwnerRoots(
+  calls: RootCallRow[],
+): PendingTraceRootScope[] | undefined {
+  const roots = new Map<string, PendingTraceRootScope>();
+  for (const call of calls) {
+    const [key, root] = callOwnerRoot(call);
+    if (roots.has(key)) continue;
+    roots.set(key, root);
+  }
+  return roots.size > 0 ? [...roots.values()] : undefined;
+}
+
+function callOwnerRoot(
+  call: RootCallRow,
+): [string, PendingTraceRootScope] {
+  const symbolId = call.sourceSymbolId;
+  const owned = typeof symbolId === 'number';
+  const key = owned
+    ? `symbol:${symbolId}` : `unowned:${call.repoId}:${call.sourceFile}`;
+  return [key, {
+    repoId: call.repoId,
+    files: new Set([call.sourceFile]),
+    symbolIds: owned ? new Set([symbolId]) : new Set(),
+    unownedOnly: !owned,
+    rootObservationOnly: true,
+  }];
+}
+
+function selectedSymbolRoots(
+  db: Db,
+  workspaceId: number,
+  symbolIds: Set<number>,
+): PendingTraceRootScope[] {
+  const ids = [...symbolIds];
+  const rows = db.prepare(`SELECT s.id,s.repo_id repoId,s.source_file sourceFile
+    FROM symbols s JOIN repositories r ON r.id=s.repo_id
+    WHERE r.workspace_id=? AND s.id IN (${ids.map(() => '?').join(',')})
+    ORDER BY r.name COLLATE BINARY,r.id,s.source_file COLLATE BINARY,
+      s.start_offset,s.end_offset,s.id`).all(workspaceId, ...ids);
+  return rows.flatMap((row) => typeof row.id === 'number'
+    && typeof row.repoId === 'number' && typeof row.sourceFile === 'string'
+    ? [{ repoId: row.repoId, files: new Set([row.sourceFile]),
+      symbolIds: new Set([row.id]), unownedOnly: false,
+      rootObservationOnly: false }]
+    : []);
+}
+
+function setsEqual<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): boolean {
+  if (left.size !== right.size) return false;
+  return [...left].every((value) => right.has(value));
+}
+
+function rootCalls(
+  db: Db,
+  workspaceId: number,
+  repoId: number | undefined,
+  files: Set<string> | undefined,
+): RootCallRow[] {
+  const rows = db.prepare(`SELECT c.id,c.repo_id repoId,r.name repoName,
+      r.workspace_id workspaceId,r.graph_generation graphGeneration,
+      c.source_symbol_id sourceSymbolId,c.source_file sourceFile,
+      c.call_type callType,c.event_name_expr eventName
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE r.workspace_id=? AND (? IS NULL OR c.repo_id=?)
+    ORDER BY r.name COLLATE BINARY,r.id,c.source_file COLLATE BINARY,
+      c.call_site_start_offset,c.call_site_end_offset,c.source_line,c.id`).all(
+    workspaceId, repoId, repoId,
+  ) as unknown as RootCallRow[];
+  return files ? rows.filter((row) => files.has(row.sourceFile)) : rows;
+}
+
+function hasExactDispatch(db: Db, calls: RootCallRow[]): boolean {
+  const match = db.prepare(`SELECT 1 matched FROM graph_edges emitted
+    WHERE emitted.workspace_id=? AND emitted.generation=?
+      AND emitted.edge_type='HANDLER_EMITS_EVENT'
+      AND emitted.from_kind='call' AND emitted.from_id=?
+      AND EXISTS (SELECT 1 FROM graph_edges subscriber
+        WHERE subscriber.workspace_id=emitted.workspace_id
+          AND subscriber.generation=emitted.generation
+          AND subscriber.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+          AND subscriber.from_kind='event'
+          AND subscriber.from_id COLLATE BINARY=? COLLATE BINARY)
+    LIMIT 1`);
+  return calls.some((call) => call.callType === 'async_emit'
+    && typeof call.eventName === 'string'
+    && Boolean(match.get(call.workspaceId, call.graphGeneration,
+      String(call.id), call.eventName)));
+}
+
+function workspaceAmbiguityDiagnostic(db: Db): Record<string, unknown> {
+  const total = Number(db.prepare(`SELECT COUNT(DISTINCT w.id) count
+    FROM workspaces w JOIN repositories r ON r.workspace_id=w.id`).get()?.count ?? 0);
+  const workspaceIds = db.prepare(`SELECT DISTINCT w.id FROM workspaces w
+    JOIN repositories r ON r.workspace_id=w.id ORDER BY w.id LIMIT 5`).all()
+    .flatMap((row) => typeof row.id === 'number' ? [row.id] : []);
+  return {
+    severity: 'error', code: 'trace_workspace_ambiguous',
+    message: total > 1
+      ? 'Trace spans multiple indexed workspaces; provide a workspace identity.'
+      : 'No indexed workspace could be selected for this trace.',
+    workspaceCount: total, workspaceIds,
+    omittedWorkspaceCount: Math.max(0, total - workspaceIds.length),
+    remediation: 'Pass TraceOptions.workspaceId or select a repository in one workspace.',
+  };
+}

package/src/trace/014-compact-contract.ts

@@ -0,0 +1,347 @@
+import type { Db } from '../db/connection.js';
+import type {
+  DynamicMode,
+  TraceOptions,
+  TraceResult,
+  TraceStart,
+} from '../types.js';
+
+export type CompactStatus =
+  | 'resolved'
+  | 'terminal'
+  | 'inferred'
+  | 'dynamic'
+  | 'ambiguous'
+  | 'unresolved'
+  | 'cycle';
+
+export type CompactEndpointSide = 'source' | 'target';
+
+export type CompactSemanticEndpoint =
+  | { kind: 'operation'; operationId: number }
+  | { kind: 'symbol'; symbolId: number }
+  | { kind: 'handler_method'; handlerMethodId: number }
+  | { kind: 'event'; workspaceId: number; eventName: string }
+  | {
+      kind: 'target';
+      workspaceId: number;
+      repositoryId?: number;
+      targetKind: string;
+      targetId: string;
+    }
+  | {
+      kind: 'call_site';
+      workspaceId: number;
+      repositoryId: number;
+      repositoryName: string;
+      sourceFile: string;
+      sourceLine: number;
+      startOffset?: number;
+      endOffset?: number;
+      callId: number;
+    }
+  | {
+      kind: 'scope';
+      workspaceId: number;
+      repositoryId?: number;
+      sourceFiles: string[];
+      symbolIds: number[];
+      structuralKey: string;
+    }
+  | {
+      kind: 'unavailable';
+      side: CompactEndpointSide;
+      endpointKind: string;
+      detailedEdgeIndex: number;
+      site?: CompactSourceSite;
+    };
+
+export type CompactRemediationCode =
+  | 'provide_runtime_variables'
+  | 'select_implementation'
+  | 'reindex_and_link'
+  | 'inspect_detailed_edge';
+
+export interface CompactDecisionTargetInput {
+  kind: string;
+  id: string;
+}
+
+export interface CompactDecisionInput {
+  effectiveResolutionStatus?: string;
+  effectiveTarget?: CompactDecisionTargetInput;
+  persistedResolutionStatus?: string;
+  persistedTarget?: CompactDecisionTargetInput;
+  missingVariableNames?: string[];
+  missingVariableCount?: number;
+  dynamicMode?: DynamicMode;
+  candidateCount?: number;
+  viableCandidateCount?: number;
+  rejectedCandidateCount?: number;
+  omittedCandidateCount?: number;
+  implementationStrategy?: string;
+  implementationGuided?: boolean;
+  implementationContextual?: boolean;
+  reasonCode?: string;
+  eventMatchStrategy?: string;
+  dispatchCertainty?: string;
+  eventSubscriptionCount?: number;
+  associationStatus?: string;
+  associationBasis?: string;
+  eventScope?: string;
+  callRole?: string;
+  factOrigin?: string;
+  roleSiteMatchCount?: number;
+  bodyExpansion?: string;
+  remediationCode?: CompactRemediationCode;
+  remediationHintCount?: number;
+}
+
+export interface CompactReferenceInput {
+  graphEdgeIds?: Array<number | string>;
+  outboundCallIds?: Array<number | string>;
+  subscribeCallIds?: Array<number | string>;
+  symbolCallIds?: Array<number | string>;
+  operationIds?: Array<number | string>;
+  symbolIds?: Array<number | string>;
+  handlerMethodIds?: Array<number | string>;
+}
+
+export interface CompactSourceSite {
+  repository?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+  startOffset?: number;
+  endOffset?: number;
+}
+
+export interface CompactEdgeObservation {
+  ordinal: number;
+  step: number;
+  type: string;
+  source: CompactSemanticEndpoint;
+  target: CompactSemanticEndpoint;
+  status: CompactStatus;
+  confidence: number;
+  decision?: CompactDecisionInput;
+  refs?: CompactReferenceInput;
+  site?: CompactSourceSite;
+}
+
+export interface CompactTraceObserver {
+  record(observation: CompactEdgeObservation): void;
+  setWorkspaceId?(workspaceId: number | undefined): void;
+}
+
+export class CompactObservationCollector implements CompactTraceObserver {
+  readonly observations: CompactEdgeObservation[] = [];
+  workspaceId?: number;
+
+  record(observation: CompactEdgeObservation): void {
+    this.observations.push(observation);
+  }
+
+  setWorkspaceId(workspaceId: number | undefined): void {
+    this.workspaceId = workspaceId;
+  }
+}
+
+export interface CompactSourceContext {
+  schemaVersion: number;
+  analyzerVersion: string;
+  graphGeneration: number;
+}
+
+export interface CompactProjectionInput {
+  db: Db;
+  start: TraceStart;
+  options: TraceOptions;
+  source: CompactSourceContext;
+  trace: TraceResult;
+  observations: CompactEdgeObservation[];
+}
+
+export interface CompactHintV1 {
+  servicePath: string | null;
+  operationPath: string | null;
+  packageName: string | null;
+  repositoryName: string | null;
+  candidateFamily: string | null;
+  implementationRepo: string | null;
+}
+
+export interface CompactStartV1 {
+  repo: string | null;
+  servicePath: string | null;
+  operation: string | null;
+  operationPath: string | null;
+  handler: string | null;
+}
+
+export interface CompactQueryV1 {
+  depth: number;
+  includeAsync: boolean;
+  includeDb: boolean;
+  includeExternal: boolean;
+  dynamicMode: DynamicMode;
+  maxDynamicCandidates: number;
+  suppliedVariableNames: string[];
+  runtimeValuesOmitted: true;
+  implementationRepo: string | null;
+  implementationHints: CompactHintV1[];
+}
+
+export interface CompactReferenceGroupV1 {
+  values: Array<number | string>;
+  total: number;
+  shown: number;
+  omitted: number;
+}
+
+export interface CompactReferencesV1 {
+  graphEdgeIds?: CompactReferenceGroupV1;
+  outboundCallIds?: CompactReferenceGroupV1;
+  subscribeCallIds?: CompactReferenceGroupV1;
+  symbolCallIds?: CompactReferenceGroupV1;
+  operationIds?: CompactReferenceGroupV1;
+  symbolIds?: CompactReferenceGroupV1;
+  handlerMethodIds?: CompactReferenceGroupV1;
+}
+
+export 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;
+}
+
+export interface CompactEdgeDetailsV1 {
+  decision: CompactDecisionV1;
+  refs: CompactReferencesV1;
+}
+
+export interface CompactDiagnosticDetailsV1 {
+  reasonCode?: string;
+  missingVariableNames?: string[];
+  missingVariableCount?: number;
+  shownMissingVariableCount?: number;
+  omittedMissingVariableCount?: number;
+  candidateCount?: number;
+  viableCandidateCount?: number;
+  rejectedCandidateCount?: number;
+  remediationHint?: string;
+  omittedHintCount?: number;
+}
+
+export interface CompactProjectedDiagnostic {
+  index: number;
+  severity: 'error' | 'warning' | 'info';
+  code: string;
+  message: string;
+  file?: string;
+  line?: number;
+  details?: CompactDiagnosticDetailsV1;
+}
+
+export type CompactNodeRowV1 = [
+  id: string,
+  kind: string,
+  label: string,
+  repo: number | null,
+  file: number | null,
+  line: number | null,
+];
+
+export type CompactEdgeRowV1 = [
+  id: string,
+  traceOrdinals: number[],
+  step: number,
+  type: string,
+  from: string,
+  to: string,
+  status: CompactStatus,
+  confidence: number,
+  count: number,
+  details: CompactEdgeDetailsV1 | null,
+];
+
+export type CompactDiagnosticRowV1 = [
+  fullDiagnosticIndex: number,
+  severity: 'error' | 'warning' | 'info',
+  code: string,
+  message: string,
+  file: number | null,
+  line: number | null,
+  details: CompactDiagnosticDetailsV1 | null,
+];
+
+export interface CompactStatusCountsV1 {
+  resolved: number;
+  terminal: number;
+  inferred: number;
+  dynamic: number;
+  ambiguous: number;
+  unresolved: number;
+  cycle: number;
+}
+
+export 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[];
+}