@saptools/service-flow 0.1.69 → 0.1.72

package/src/trace/{029-trace-start-implementation.ts → trace-start-implementation.ts}

@@ -1,22 +1,22 @@
 import type { Db } from '../db/connection.js';
 import type { TraceEdge } from '../types.js';
-import { hintedImplementationSelection } from './005-implementation-selection.js';
+import { hintedImplementationSelection } from './implementation-selection.js';
 import {
   handlerMethodNode,
   withSelectedHandlerProvenance,
   type SelectedHandlerEvidence,
-} from './009-selected-handler-provenance.js';
+} from './selected-handler-provenance.js';
 import {
   operationNode,
   type TraceGraphEdgeRow,
-} from './012-trace-graph-lookups.js';
-import { parseTraceEvidence } from './017-trace-context.js';
-import { recordImplementationObservation } from './019-trace-edge-semantics.js';
+} from './trace-graph-lookups.js';
+import { parseTraceEvidence } from './trace-context.js';
+import { recordImplementationObservation } from './trace-edge-semantics.js';
 import {
   handlerScope,
   implementationScope,
-} from './025-trace-implementation-scope.js';
-import type { TraceExecutionRuntime } from './027-trace-scope-execution.js';
+} from './trace-implementation-scope.js';
+import type { TraceExecutionRuntime } from './trace-scope-execution.js';
 
 interface StartImplementationSelection {
   edge: TraceGraphEdgeRow;

package/src/trace/{026-trace-start-scope.ts → trace-start-scope.ts}

@@ -1,15 +1,15 @@
 import type { Db } from '../db/connection.js';
 import type { TraceStart } from '../types.js';
 import { implementationHintDiagnostic } from './implementation-hints.js';
-import { hintedImplementationSelection } from './005-implementation-selection.js';
-import { implementationStartDiagnostic } from './007-implementation-start-diagnostic.js';
-import { parseTraceEvidence } from './017-trace-context.js';
-import { shouldDeferTraceStartSelection } from './022-trace-fact-preflight.js';
+import { hintedImplementationSelection } from './implementation-selection.js';
+import { implementationStartDiagnostic } from './implementation-start-diagnostic.js';
+import { parseTraceEvidence } from './trace-context.js';
+import { shouldDeferTraceStartSelection } from './trace-fact-preflight.js';
 import {
   handlerScope,
   implementationScope,
   type ImplementationHintOptions,
-} from './025-trace-implementation-scope.js';
+} from './trace-implementation-scope.js';
 import {
   ambiguousStartDiagnostic,
   selectorRepoAmbiguousDiagnostic,

package/src/trace/{010-traversal-scope.ts → traversal-scope.ts}

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import type { Db } from '../db/connection.js';
-import type { ContextBinding } from './008-contextual-runtime-state.js';
+import type { ContextBinding } from './contextual-runtime-state.js';
 
 export interface TraversalScopeIdentity {
   workspaceId?: number;

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { EventSkeletonFact } from './utils/event-skeleton.js';
+
 export type RepoKind =
   | 'cap-service'
   | 'cap-db-model'
@@ -36,6 +38,7 @@ export type EdgeType =
   | 'HANDLER_EMITS_EVENT'
   | 'EVENT_CONSUMED_BY_HANDLER'
   | 'EVENT_SUBSCRIPTION_HANDLED_BY'
+  | 'EVENT_SHAPE_CANDIDATE_SUBSCRIBER'
   | 'REPO_IMPORTS_HELPER_PACKAGE'
   | 'HELPER_PACKAGE_PROVIDES_HANDLER'
   | 'DYNAMIC_EDGE_CANDIDATE'
@@ -229,6 +232,7 @@ export interface OutboundCallFact {
   operationPathExpr?: string;
   queryEntity?: string;
   eventNameExpr?: string;
+  eventSkeleton?: EventSkeletonFact;
   payloadSummary?: string;
   sourceFile: string;
   sourceLine: number;
@@ -272,9 +276,21 @@ export interface SymbolCallFact {
 }
 export interface GeneratedConstantFact {
   name: string;
-  value: string;
+  value?: string;
   sourceFile: string;
   sourceLine: number;
+  containerName?: string;
+  memberName?: string;
+  constantKind: 'const_identifier' | 'enum_member' | 'const_object_property';
+  exported: boolean;
+  stable: boolean;
+  resolutionStatus: 'resolved' | 'refused';
+  unresolvedReason?: 'event_name_constant_member_not_string'
+    | 'event_name_constant_container_mutable';
+  declarationStartOffset: number;
+  declarationEndOffset: number;
+  valueStartOffset: number;
+  valueEndOffset: number;
 }
 export interface TraceStart {
   repo?: string;

package/src/utils/event-skeleton.ts

@@ -0,0 +1,207 @@
+import { sha256Text } from './hashing.js';
+import { scanPlaceholderStructure } from './placeholders.js';
+import type {
+  EventEnvironmentReference,
+} from '../parsers/event-environment-reference.js';
+
+export const EVENT_SKELETON_SCHEMA = 'service-flow/event-skeleton@1';
+export const EVENT_SKELETON_LITERAL_THRESHOLD = 8;
+export const EVENT_SKELETON_TEXT_LIMIT = 512;
+
+export interface EventSkeletonFact {
+  schema: typeof EVENT_SKELETON_SCHEMA;
+  status: 'complete' | 'malformed' | 'too_large';
+  signature: string | null;
+  literalSpans: string[];
+  holeCount: number;
+  sourceKeys: string[];
+  canonicalKeys: string[];
+  candidateEligible: boolean;
+  environmentBindings: EventEnvironmentReference[];
+  reason?: string;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+function parseJson(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every((item) =>
+    typeof item === 'string')
+    ? value as string[] : undefined;
+}
+
+function canonicalKey(signature: string, index: number): string {
+  return `event.${signature.slice(0, 16)}.hole${index + 1}`;
+}
+
+function skeletonSignature(
+  literalSpans: readonly string[],
+  holeCount: number,
+): string {
+  return sha256Text(JSON.stringify({ literalSpans, holeCount }));
+}
+
+function completeSkeleton(
+  template: string,
+): EventSkeletonFact {
+  const scan = scanPlaceholderStructure(template);
+  if (scan.status === 'malformed') return {
+    schema: EVENT_SKELETON_SCHEMA,
+    status: 'malformed',
+    signature: null,
+    literalSpans: [],
+    holeCount: 0,
+    sourceKeys: [],
+    canonicalKeys: [],
+    candidateEligible: false,
+    environmentBindings: [],
+    reason: scan.reason,
+  };
+  const literals: string[] = [];
+  let cursor = 0;
+  for (const span of scan.spans) {
+    literals.push(template.slice(cursor, span.start));
+    cursor = span.end;
+  }
+  literals.push(template.slice(cursor));
+  const signature = skeletonSignature(literals, scan.spans.length);
+  return {
+    schema: EVENT_SKELETON_SCHEMA,
+    status: 'complete',
+    signature,
+    literalSpans: literals,
+    holeCount: scan.spans.length,
+    sourceKeys: scan.spans.map((span) => span.key.trim()),
+    canonicalKeys: scan.spans.map((_, index) =>
+      canonicalKey(signature, index)),
+    candidateEligible: scan.spans.length > 0
+      && literals.some((literal) =>
+        literal.length >= EVENT_SKELETON_LITERAL_THRESHOLD),
+    environmentBindings: [],
+  };
+}
+
+function validCompleteSkeleton(
+  item: Record<string, unknown>,
+  literals: string[],
+  sourceKeys: string[],
+  canonicalKeys: string[],
+): boolean {
+  const holes = item.holeCount;
+  const signature = item.signature;
+  if (!Number.isInteger(holes) || Number(holes) < 1
+    || typeof signature !== 'string'
+    || !/^[a-f0-9]{64}$/.test(signature)) return false;
+  const count = Number(holes);
+  return literals.length === count + 1
+    && sourceKeys.length === count
+    && canonicalKeys.length === count
+    && sourceKeys.every((key) => key.length > 0 && key === key.trim())
+    && canonicalKeys.every((key, index) =>
+      key === canonicalKey(signature, index))
+    && new Set(canonicalKeys).size === canonicalKeys.length
+    && signature === skeletonSignature(literals, count)
+    && item.candidateEligible === literals.some((literal) =>
+      literal.length >= EVENT_SKELETON_LITERAL_THRESHOLD)
+    && item.reason === undefined;
+}
+
+function validClosedSkeleton(
+  item: Record<string, unknown>,
+  literals: string[],
+  sourceKeys: string[],
+  canonicalKeys: string[],
+): boolean {
+  const reason = item.reason;
+  if (item.signature !== null || item.holeCount !== 0
+    || item.candidateEligible !== false
+    || literals.length > 0 || sourceKeys.length > 0
+    || canonicalKeys.length > 0
+    || !Array.isArray(item.environmentBindings)
+    || item.environmentBindings.length > 0) return false;
+  if (item.status === 'too_large')
+    return reason === 'event_skeleton_text_limit_exceeded';
+  return item.status === 'malformed'
+    && typeof reason === 'string' && reason.length > 0;
+}
+
+export function parseEventSkeletonFact(
+  value: unknown,
+): EventSkeletonFact | undefined {
+  const item = record(parseJson(value));
+  if (!item || item.schema !== EVENT_SKELETON_SCHEMA
+    || !['complete', 'malformed', 'too_large'].includes(String(item.status))
+    || !Array.isArray(item.environmentBindings)) return undefined;
+  const literals = stringArray(item.literalSpans);
+  const sourceKeys = stringArray(item.sourceKeys);
+  const canonicalKeys = stringArray(item.canonicalKeys);
+  if (!literals || !sourceKeys || !canonicalKeys) return undefined;
+  const valid = item.status === 'complete'
+    ? validCompleteSkeleton(item, literals, sourceKeys, canonicalKeys)
+    : validClosedSkeleton(item, literals, sourceKeys, canonicalKeys);
+  return valid ? item as unknown as EventSkeletonFact : undefined;
+}
+
+export function deriveEventSkeleton(
+  template: string | undefined,
+): EventSkeletonFact | undefined {
+  if (!template || !template.includes('${')) return undefined;
+  if (template.length <= EVENT_SKELETON_TEXT_LIMIT)
+    return completeSkeleton(template);
+  return {
+    schema: EVENT_SKELETON_SCHEMA,
+    status: 'too_large',
+    signature: null,
+    literalSpans: [],
+    holeCount: 0,
+    sourceKeys: [],
+    canonicalKeys: [],
+    candidateEligible: false,
+    environmentBindings: [],
+    reason: 'event_skeleton_text_limit_exceeded',
+  };
+}
+
+export function eventTemplateVariables(
+  skeleton: EventSkeletonFact | undefined,
+  variables: Record<string, string>,
+): Record<string, string> {
+  if (!skeleton || skeleton.status !== 'complete') return variables;
+  const expanded = { ...variables };
+  for (let index = 0; index < skeleton.sourceKeys.length; index += 1) {
+    const sourceKey = skeleton.sourceKeys[index];
+    const canonicalKeyValue = skeleton.canonicalKeys[index];
+    if (!sourceKey || !canonicalKeyValue
+      || Object.hasOwn(expanded, sourceKey)
+      || !Object.hasOwn(expanded, canonicalKeyValue)) continue;
+    expanded[sourceKey] = expanded[canonicalKeyValue] ?? '';
+  }
+  return expanded;
+}
+
+export function eventMissingVariableNames(
+  skeleton: EventSkeletonFact | undefined,
+  missingSourceKeys: readonly string[],
+): string[] {
+  const names = new Set(missingSourceKeys);
+  if (skeleton?.status === 'complete')
+    for (let index = 0; index < skeleton.sourceKeys.length; index += 1) {
+      const sourceKey = skeleton.sourceKeys[index];
+      const canonical = skeleton.canonicalKeys[index];
+      if (sourceKey && canonical && names.has(sourceKey))
+        names.add(canonical);
+    }
+  return [...names].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0);
+}

package/src/version.ts

@@ -1,4 +1,4 @@
 import packageJson from '../package.json' with { type: 'json' };
 
 export const VERSION = packageJson.version;
-export const ANALYZER_VERSION = '0.1.69-facts.1';
+export const ANALYZER_VERSION = '0.1.71-facts.1';