@saptools/service-flow 0.1.70 → 0.1.73

package/src/parsers/event-call-analysis.ts

@@ -0,0 +1,370 @@
+import ts from 'typescript';
+import type { OutboundCallFact } from '../types.js';
+import {
+  CDS_LIFECYCLE_EVENTS,
+  resolveExpression,
+  type ExpressionResolution,
+} from './outbound-expression-analysis.js';
+import {
+  createEventReceiverIndex,
+  proveEventReceiver,
+  type EventReceiverIndex,
+  type EventReceiverProof,
+} from './event-receiver-analysis.js';
+import {
+  collectStringConstantLookups,
+  resolveStringConstant,
+  type StaticStringConstant,
+  type StaticStringLookupResult,
+  type StringConstantLookups,
+} from './string-constant-lookups.js';
+import type {
+  ImportedEventNameResult,
+  ImportedEventNameResolver,
+} from './event-name-import-resolution.js';
+import type {
+  SymbolImportReference,
+} from './symbol-import-bindings.js';
+import {
+  deriveEventSkeleton,
+  type EventSkeletonFact,
+} from '../utils/event-skeleton.js';
+import type {
+  EventEnvironmentReferenceResolver,
+} from './event-environment-reference.js';
+
+type EventFact = Pick<OutboundCallFact,
+  'callType' | 'serviceVariableName' | 'eventNameExpr'
+  | 'eventSkeleton' | 'confidence' | 'unresolvedReason'>;
+
+export interface EventCallAnalysisContext {
+  source: ts.SourceFile;
+  receivers: EventReceiverIndex;
+  constants: StringConstantLookups;
+  importedConstant?: ImportedEventNameResolver;
+  environmentReference?: EventEnvironmentReferenceResolver;
+}
+
+export type EventCallAnalysis =
+  | { status: 'classified'; fact: EventFact; evidence: Record<string, unknown> }
+  | { status: 'excluded' }
+  | { status: 'unclassified' };
+
+interface EventNameState {
+  eventName: string;
+  resolved: ExpressionResolution;
+  unresolvedReason?: string;
+  constant?: StaticStringConstant;
+  foldedConstants?: StaticStringConstant[];
+  packageImportReference?: SymbolImportReference;
+}
+
+const CAP_CRUD_EVENTS = new Set(['READ', 'CREATE', 'UPDATE', 'DELETE']);
+const KNOWN_NON_CAP_EVENT_RECEIVERS = new Set([
+  'io', 'socket', 'writeStream', 'file', 'win', 'app',
+]);
+
+function eventNameReason(
+  resolved: ExpressionResolution,
+): string | undefined {
+  if (resolved.status === 'static') return undefined;
+  return resolved.value !== undefined && resolved.placeholderKeys.length > 0
+    ? 'dynamic_event_name_identifier'
+    : 'dynamic_event_name_unsupported_expression';
+}
+
+function stringConstantLookup(
+  expression: ts.Expression,
+  context: EventCallAnalysisContext,
+): ImportedEventNameResult | StaticStringLookupResult {
+  const local = resolveStringConstant(expression, context.constants);
+  return local.status === 'not_found'
+    ? context.importedConstant?.(expression) ?? local : local;
+}
+
+function foldedTemplateState(
+  expression: ts.TemplateExpression,
+  context: EventCallAnalysisContext,
+): EventNameState | undefined {
+  let eventName = expression.head.text;
+  const placeholderKeys: string[] = [];
+  const constants: StaticStringConstant[] = [];
+  for (const span of expression.templateSpans) {
+    const key = span.expression.getText(expression.getSourceFile()).trim();
+    const lookup = stringConstantLookup(span.expression, context);
+    if (lookup.status === 'resolved') {
+      eventName += lookup.constant.value;
+      constants.push(lookup.constant);
+    } else {
+      eventName += `\${${key}}`;
+      placeholderKeys.push(key);
+    }
+    eventName += span.literal.text;
+  }
+  if (constants.length === 0) return undefined;
+  const empty = eventName.length === 0;
+  return {
+    eventName: empty ? expression.getText(expression.getSourceFile()) : eventName,
+    resolved: {
+      status: empty ? 'dynamic'
+        : placeholderKeys.length > 0 ? 'dynamic' : 'static',
+      sourceKind: 'template_with_substitutions',
+      value: empty ? undefined : eventName,
+      rawExpression: expression.getText(expression.getSourceFile()),
+      placeholderKeys,
+      evidence: ['event_name_template_static_holes_folded'],
+    },
+    unresolvedReason: empty
+      ? 'event_name_constant_value_empty'
+      : placeholderKeys.length > 0
+        ? 'dynamic_event_name_identifier' : undefined,
+    foldedConstants: constants,
+  };
+}
+
+function resolvedConstantState(
+  expression: ts.Expression,
+  constant: StaticStringConstant,
+): EventNameState {
+  const empty = constant.value.length === 0;
+  return {
+    eventName: empty ? expression.getText(expression.getSourceFile())
+      : constant.value,
+    resolved: {
+      status: empty ? 'dynamic' : 'static',
+      sourceKind: constant.kind,
+      value: empty ? undefined : constant.value,
+      rawExpression: expression.getText(expression.getSourceFile()),
+      placeholderKeys: [],
+      evidence: [`event_name_${constant.kind}`],
+    },
+    unresolvedReason: empty ? 'event_name_constant_value_empty' : undefined,
+    constant,
+  };
+}
+
+function refusedConstantState(
+  expression: ts.Expression,
+  lookup: ImportedEventNameResult | StaticStringLookupResult,
+): EventNameState | undefined {
+  if (lookup.status !== 'refused') return undefined;
+  const raw = expression.getText(expression.getSourceFile());
+  return {
+    eventName: raw,
+    resolved: {
+      status: 'dynamic',
+      sourceKind: 'dynamic_expression',
+      rawExpression: raw,
+      placeholderKeys: [],
+      evidence: [lookup.reason],
+    },
+    unresolvedReason: lookup.reason,
+    packageImportReference: packageReference(lookup),
+  };
+}
+
+function eventNameState(
+  node: ts.CallExpression,
+  context: EventCallAnalysisContext,
+): EventNameState | undefined {
+  const expression = node.arguments[0];
+  if (expression) {
+    if (ts.isTemplateExpression(expression)) {
+      const folded = foldedTemplateState(expression, context);
+      if (folded) return folded;
+    }
+    const lookup = stringConstantLookup(expression, context);
+    if (lookup.status === 'resolved')
+      return resolvedConstantState(expression, lookup.constant);
+    const refused = refusedConstantState(expression, lookup);
+    if (refused) return refused;
+  }
+  const resolved = resolveExpression(expression, node, 'operation_path');
+  const eventName = resolved.value
+    ?? resolved.rawExpression
+    ?? expression?.getText(node.getSourceFile());
+  return eventName ? {
+    eventName,
+    resolved,
+    unresolvedReason: eventNameReason(resolved),
+  } : undefined;
+}
+
+function packageReference(
+  value: ImportedEventNameResult | StaticStringLookupResult,
+): SymbolImportReference | undefined {
+  return 'packageImportReference' in value
+    ? value.packageImportReference : undefined;
+}
+
+function eventConfidence(
+  receiver: EventReceiverProof,
+  eventReason: string | undefined,
+): number {
+  const receiverConfidence = receiver.receiverClassification === 'unproven'
+    ? 0.2 : receiver.receiverClassification === 'name_fallback' ? 0.5 : 0.8;
+  const nameConfidence = !eventReason
+    ? 0.8 : eventReason === 'dynamic_event_name_identifier' ? 0.6 : 0.3;
+  return Math.min(receiverConfidence, nameConfidence);
+}
+
+function excludedEvent(
+  method: string,
+  receiver: EventReceiverProof,
+  state: EventNameState,
+): boolean {
+  if (state.resolved.status !== 'static') return false;
+  if (receiver.effectiveReceiver === 'cds'
+    && CDS_LIFECYCLE_EVENTS.has(state.eventName)) return true;
+  return method === 'on'
+    && (state.eventName === 'error'
+      || (CAP_CRUD_EVENTS.has(state.eventName)
+        && capCrudReceiver(receiver)));
+}
+
+function capCrudReceiver(receiver: EventReceiverProof): boolean {
+  const name = receiver.rootReceiver ?? receiver.effectiveReceiver;
+  return name === 'this'
+    || ['cds', 'srv', 'service', 'serviceClient'].includes(name);
+}
+
+function receiverRootName(expression: ts.Expression): string | undefined {
+  if (ts.isIdentifier(expression)) return expression.text;
+  if (ts.isPropertyAccessExpression(expression)
+    || ts.isElementAccessExpression(expression))
+    return receiverRootName(expression.expression);
+  if (ts.isCallExpression(expression))
+    return receiverRootName(expression.expression);
+  return undefined;
+}
+
+function pipeReceiver(expression: ts.Expression): boolean {
+  return ts.isCallExpression(expression)
+    && ts.isPropertyAccessExpression(expression.expression)
+    && expression.expression.name.text === 'pipe';
+}
+
+function knownNonCapReceiver(
+  expression: ts.Expression,
+  receiver: EventReceiverProof,
+): boolean {
+  if (receiver.receiverClassification !== 'unproven') return false;
+  const root = receiverRootName(expression);
+  return Boolean(root && KNOWN_NON_CAP_EVENT_RECEIVERS.has(root))
+    || pipeReceiver(expression);
+}
+
+function eventEvidence(
+  method: string,
+  receiver: EventReceiverProof,
+  state: EventNameState,
+): Record<string, unknown> {
+  return {
+    receiver: receiver.receiver,
+    rootReceiver: receiver.rootReceiver,
+    classifier: method === 'on'
+      ? 'cap_service_event_subscription' : 'cap_service_event_emit',
+    receiverClassification: receiver.receiverClassification,
+    receiverProof: receiver.receiverProof,
+    receiverUnresolvedReason: receiver.unresolvedReason,
+    receiverFallbackRefusedReason: receiver.fallbackRefusedReason,
+    consideredBindingSites: receiver.consideredBindingSites,
+    eventNameUnresolvedReason: state.unresolvedReason,
+    eventNameConstantImportBinding: state.packageImportReference,
+    eventNameConstantSourceExpression: state.packageImportReference
+      ? state.eventName : undefined,
+    ...(state.constant ? {
+      eventNameConstant: {
+        sourceKind: state.constant.kind,
+        sourceFile: state.constant.sourceFile,
+        declarationStartOffset: state.constant.declarationStartOffset,
+        declarationEndOffset: state.constant.declarationEndOffset,
+      },
+    } : {}),
+    ...(state.foldedConstants ? {
+      eventNameTemplateFoldedConstants: state.foldedConstants.slice(0, 8)
+        .map((constant) => ({
+          sourceKind: constant.kind,
+          sourceFile: constant.sourceFile,
+          declarationStartOffset: constant.declarationStartOffset,
+          declarationEndOffset: constant.declarationEndOffset,
+        })),
+      eventNameTemplateFoldedConstantCount: state.foldedConstants.length,
+    } : {}),
+    ...(state.resolved.status === 'static' ? {} : {
+      eventNameStatus: state.resolved.status,
+      eventNameSourceKind: state.resolved.sourceKind,
+      eventNamePlaceholderKeys: state.resolved.placeholderKeys,
+    }),
+  };
+}
+
+export function createEventCallAnalysisContext(
+  source: ts.SourceFile,
+  importedConstant?: ImportedEventNameResolver,
+  environmentReference?: EventEnvironmentReferenceResolver,
+): EventCallAnalysisContext {
+  return {
+    source,
+    receivers: createEventReceiverIndex(source),
+    constants: collectStringConstantLookups(source),
+    importedConstant,
+    environmentReference,
+  };
+}
+
+function eventSkeleton(
+  node: ts.CallExpression,
+  eventName: string,
+  resolver: EventEnvironmentReferenceResolver | undefined,
+): EventSkeletonFact | undefined {
+  const expression = node.arguments[0];
+  if (!expression) return undefined;
+  if (!ts.isTemplateExpression(expression))
+    return eventName.includes('${')
+      ? deriveEventSkeleton(eventName) : undefined;
+  const skeleton = deriveEventSkeleton(eventName);
+  if (!skeleton || !resolver) return skeleton;
+  return {
+    ...skeleton,
+    environmentBindings: expression.templateSpans.flatMap((span) => {
+      const reference = resolver(span.expression);
+      return reference ? [{
+        ...reference,
+        sourceKey: span.expression.getText(node.getSourceFile()).trim(),
+      }] : [];
+    }),
+  };
+}
+
+export function analyzeEventCall(
+  node: ts.CallExpression,
+  expression: ts.PropertyAccessExpression,
+  context: EventCallAnalysisContext,
+): EventCallAnalysis {
+  const method = expression.name.text;
+  const state = eventNameState(node, context);
+  if (!state) return { status: 'unclassified' };
+  const receiver = proveEventReceiver(
+    expression.expression, node, context.receivers,
+  );
+  if (receiver.unresolvedReason === 'event_receiver_not_cap_client'
+    || receiver.receiverProof === 'binding_not_found'
+    || knownNonCapReceiver(expression.expression, receiver))
+    return { status: 'excluded' };
+  if (excludedEvent(method, receiver, state)) return { status: 'excluded' };
+  return {
+    status: 'classified',
+    fact: {
+      callType: method === 'on' ? 'async_subscribe' : 'async_emit',
+      serviceVariableName: receiver.effectiveReceiver,
+      eventNameExpr: state.eventName,
+      eventSkeleton: eventSkeleton(
+        node, state.eventName, context.environmentReference,
+      ),
+      confidence: eventConfidence(receiver, state.unresolvedReason),
+      unresolvedReason: state.unresolvedReason,
+    },
+    evidence: eventEvidence(method, receiver, state),
+  };
+}

package/src/parsers/event-environment-reference.ts

@@ -0,0 +1,242 @@
+import { posix } from 'node:path';
+import ts from 'typescript';
+import { normalizePath } from '../utils/path-utils.js';
+import { resolveBinding } from './query-entity-resolution.js';
+import {
+  collectSymbolImportBindings,
+  lexicalIdentifierDeclaration,
+  type SymbolImportBinding,
+} from './symbol-import-bindings.js';
+import type { RepositorySourceContext } from './ts-project.js';
+import {
+  DEFAULT_EVENT_ENVIRONMENT_KEYS,
+  normalizeEventEnvironmentKeys,
+} from
+  './environment-declarations.js';
+
+export type EventEnvironmentTransform = 'toUpperCase' | 'toLowerCase';
+
+export interface EventEnvironmentReference {
+  status: 'resolved' | 'refused';
+  sourceKey: string;
+  environmentKey?: string;
+  transforms: EventEnvironmentTransform[];
+  sourceFile?: string;
+  startOffset?: number;
+  endOffset?: number;
+  reason?: string;
+}
+
+export type EventEnvironmentReferenceResolver = (
+  expression: ts.Expression,
+) => EventEnvironmentReference | undefined;
+
+interface ResolutionContext {
+  sources: RepositorySourceContext;
+  source: ts.SourceFile;
+  sourceFile: string;
+  depth: number;
+  seen: Set<string>;
+  allowedKeys: ReadonlySet<string>;
+}
+
+const maxEnvironmentReferenceDepth = 6;
+function unwrapExpression(expression: ts.Expression): ts.Expression {
+  if (ts.isParenthesizedExpression(expression)
+    || ts.isAsExpression(expression)
+    || ts.isSatisfiesExpression(expression)
+    || ts.isTypeAssertionExpression(expression)
+    || ts.isNonNullExpression(expression))
+    return unwrapExpression(expression.expression);
+  return expression;
+}
+
+function processEnvironmentKey(
+  expression: ts.Expression,
+): string | undefined {
+  if (!ts.isPropertyAccessExpression(expression)
+    || !ts.isPropertyAccessExpression(expression.expression)
+    || !ts.isIdentifier(expression.expression.expression)
+    || expression.expression.expression.text !== 'process'
+    || expression.expression.name.text !== 'env'
+    || lexicalIdentifierDeclaration(expression.expression.expression))
+    return undefined;
+  return expression.name.text;
+}
+
+function relativeCandidates(
+  callerFile: string,
+  specifier: string,
+): string[] {
+  const base = normalizePath(posix.normalize(
+    posix.join(posix.dirname(callerFile), specifier),
+  ));
+  return /\.[jt]s$/.test(base)
+    ? [base]
+    : [`${base}.ts`, `${base}.js`, `${base}/index.ts`, `${base}/index.js`];
+}
+
+function bindingFor(
+  identifier: ts.Identifier,
+  bindings: readonly SymbolImportBinding[],
+): SymbolImportBinding | undefined {
+  const declaration = lexicalIdentifierDeclaration(identifier);
+  if (!declaration) return undefined;
+  const start = declaration.getStart(identifier.getSourceFile());
+  const end = declaration.getEnd();
+  const matches = bindings.filter((binding) =>
+    binding.localName === identifier.text
+    && binding.bindingSiteStartOffset === start
+    && binding.bindingSiteEndOffset === end);
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
+function exportedVariableInitializer(
+  source: ts.SourceFile,
+  name: string,
+): ts.Expression | undefined {
+  const exportNames = new Set(source.statements.flatMap((statement) =>
+    ts.isExportDeclaration(statement) && !statement.moduleSpecifier
+      && statement.exportClause && ts.isNamedExports(statement.exportClause)
+      ? statement.exportClause.elements.map((element) =>
+          element.propertyName?.text ?? element.name.text)
+      : []));
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    const exported = ts.canHaveModifiers(statement)
+      && ts.getModifiers(statement)?.some((modifier) =>
+        modifier.kind === ts.SyntaxKind.ExportKeyword);
+    for (const declaration of statement.declarationList.declarations)
+      if (ts.isIdentifier(declaration.name)
+        && declaration.name.text === name
+        && (exported || exportNames.has(name))
+        && (statement.declarationList.flags & ts.NodeFlags.Const) !== 0)
+        return declaration.initializer;
+  }
+  return undefined;
+}
+
+function importedIdentifier(
+  identifier: ts.Identifier,
+  context: ResolutionContext,
+): { source: ts.SourceFile; sourceFile: string;
+  initializer: ts.Expression } | undefined {
+  const binding = bindingFor(
+    identifier, collectSymbolImportBindings(context.source),
+  );
+  if (!binding || binding.typeOnly || binding.moduleKind !== 'relative'
+    || !binding.importedName) return undefined;
+  const candidates = relativeCandidates(
+    context.sourceFile, binding.rawModuleSpecifier,
+  ).flatMap((filePath) => {
+    const snapshot = context.sources.get(filePath);
+    return snapshot ? [{ sourceFile: filePath, source: snapshot.sourceFile() }]
+      : [];
+  });
+  if (candidates.length !== 1 || !candidates[0]) return undefined;
+  const initializer = exportedVariableInitializer(
+    candidates[0].source, binding.importedName,
+  );
+  return initializer ? { ...candidates[0], initializer } : undefined;
+}
+
+function transformedReference(
+  expression: ts.CallExpression,
+  context: ResolutionContext,
+): EventEnvironmentReference | undefined {
+  if (!ts.isPropertyAccessExpression(expression.expression)) return undefined;
+  const method = expression.expression.name.text;
+  const base = resolveEnvironmentReference(
+    expression.expression.expression, context,
+  );
+  if (!base) return undefined;
+  if (expression.arguments.length !== 0
+    || !['toUpperCase', 'toLowerCase'].includes(method)) return {
+    ...base,
+    status: 'refused',
+    reason: 'event_environment_transform_unsupported',
+  };
+  return base.status === 'resolved'
+    ? {
+        ...base,
+        transforms: [
+          ...base.transforms, method as EventEnvironmentTransform,
+        ],
+      }
+    : base;
+}
+
+function identifierReference(
+  identifier: ts.Identifier,
+  context: ResolutionContext,
+): EventEnvironmentReference | undefined {
+  const local = resolveBinding(identifier, identifier);
+  if (local.declaration && local.initializer && local.immutable)
+    return resolveEnvironmentReference(local.initializer, context);
+  const binding = bindingFor(
+    identifier, collectSymbolImportBindings(context.source),
+  );
+  if (binding?.moduleKind === 'package') return {
+    status: 'refused',
+    sourceKey: identifier.getText(context.source),
+    transforms: [],
+    reason: 'event_environment_package_import_unsupported',
+  };
+  const imported = importedIdentifier(identifier, context);
+  if (!imported) return undefined;
+  return resolveEnvironmentReference(imported.initializer, {
+    ...context,
+    source: imported.source,
+    sourceFile: imported.sourceFile,
+    depth: context.depth + 1,
+  });
+}
+
+function resolveEnvironmentReference(
+  expression: ts.Expression,
+  context: ResolutionContext,
+): EventEnvironmentReference | undefined {
+  const sourceKey = expression.getText(context.source);
+  if (context.depth >= maxEnvironmentReferenceDepth
+    || context.seen.has(`${context.sourceFile}\0${sourceKey}`)) return {
+    status: 'refused', sourceKey, transforms: [],
+    reason: 'event_environment_reference_ambiguous',
+  };
+  const seen = new Set(context.seen).add(
+    `${context.sourceFile}\0${sourceKey}`,
+  );
+  const next = { ...context, depth: context.depth + 1, seen };
+  const value = unwrapExpression(expression);
+  const key = processEnvironmentKey(value);
+  if (key && context.allowedKeys.has(key)) return {
+    status: 'resolved', sourceKey, environmentKey: key, transforms: [],
+    sourceFile: context.sourceFile,
+    startOffset: value.getStart(context.source), endOffset: value.getEnd(),
+  };
+  if (key) return undefined;
+  if (ts.isCallExpression(value))
+    return transformedReference(value, next);
+  return ts.isIdentifier(value)
+    ? identifierReference(value, next) : undefined;
+}
+
+export function createEventEnvironmentReferenceResolver(
+  sources: RepositorySourceContext,
+  source: ts.SourceFile,
+  sourceFile: string,
+  configuredKeys: readonly string[] = DEFAULT_EVENT_ENVIRONMENT_KEYS,
+): EventEnvironmentReferenceResolver {
+  const allowedKeys = new Set(normalizeEventEnvironmentKeys(configuredKeys));
+  return (expression) => resolveEnvironmentReference(expression, {
+    sources, source, sourceFile, depth: 0, seen: new Set(), allowedKeys,
+  });
+}
+
+export function applyEventEnvironmentTransforms(
+  value: string,
+  transforms: readonly EventEnvironmentTransform[],
+): string {
+  return transforms.reduce((current, transform) =>
+    transform === 'toUpperCase'
+      ? current.toUpperCase() : current.toLowerCase(), value);
+}