@saptools/service-flow 0.1.67 → 0.1.68

package/src/linker/odata-path-normalizer.ts

@@ -1,3 +1,8 @@
+import {
+  analyzeODataPathStructure,
+  type ODataPathStructure,
+} from './005-odata-path-structure.js';
+
 export interface NormalizedODataOperationPath {
   rawOperationPath: string;
   normalizedOperationPath: string;
@@ -33,207 +38,295 @@ export interface ODataPathIntent {
   reason: string;
 }
 
-export function normalizeODataOperationInvocationPath(path: string | undefined): NormalizedODataOperationPath | undefined {
+interface NavigationEvidence {
+  readonly navigation: boolean;
+  readonly suffix?: string;
+  readonly navigationSuffix?: string;
+}
+
+interface OperationEvidence {
+  readonly invocation: boolean;
+  readonly name?: string;
+}
+
+export function normalizeODataOperationInvocationPath(
+  path: string | undefined,
+): NormalizedODataOperationPath | undefined {
   if (path === undefined) return undefined;
   const raw = path.trim();
   if (!raw) return undefined;
-  const rejected = (reason: string): NormalizedODataOperationPath => ({ rawOperationPath: raw, normalizedOperationPath: raw, wasInvocation: false, invocationArgumentPlaceholderKeys: [], normalizationRejectedReason: reason });
-  const open = raw.indexOf('(');
-  if (open < 0) return rejected('no_top_level_parenthesis');
-  const query = topLevelQueryIndex(raw);
-  if (query >= 0) return rejected('query_string_paths_are_not_operation_invocations');
-  if (!raw.startsWith('/')) return rejected('path_is_not_absolute');
-  if (raw.slice(1, open).includes('/')) return rejected('operation_segment_contains_navigation_separator');
-  const close = matchingClose(raw, open);
-  if (close === undefined) return rejected('top_level_invocation_parenthesis_is_unbalanced');
-  if (raw.slice(close + 1).trim().length > 0) return rejected('top_level_invocation_does_not_cover_remaining_path');
-  const operationSegment = raw.slice(0, open).trim();
-  if (operationSegment.length <= 1) return rejected('operation_segment_is_empty');
+  const structure = analyzeODataPathStructure(raw);
+  const rejection = normalizationRejection(raw, structure);
+  if (rejection) return rejectedNormalization(raw, rejection);
+  const operationSegment = raw.slice(
+    0, structure.firstParenthesisOpen ?? 0,
+  ).trim();
+  if (operationSegment.length <= 1)
+    return rejectedNormalization(raw, 'operation_segment_is_empty');
   return {
     rawOperationPath: raw,
     normalizedOperationPath: operationSegment,
     wasInvocation: true,
-    invocationArguments: raw.slice(open + 1, close),
-    invocationArgumentPlaceholderKeys: [...new Set(extractTemplatePlaceholders(raw.slice(open + 1, close)))],
+    invocationArguments: structure.firstParenthesisArguments,
+    invocationArgumentPlaceholderKeys:
+      structure.firstParenthesisPlaceholderKeys,
     normalizationReason: 'balanced_top_level_operation_invocation',
   };
 }
 
-export function classifyODataPathIntent(path: string | undefined, method: string | undefined): ODataPathIntent {
+function normalizationRejection(
+  raw: string,
+  structure: ODataPathStructure,
+): string | undefined {
+  if (structure.status === 'malformed')
+    return structure.reason ?? 'path_structure_is_malformed';
+  if (structure.firstParenthesisOpen === undefined)
+    return 'no_top_level_parenthesis';
+  if (structure.queryIndex !== undefined)
+    return 'query_string_paths_are_not_operation_invocations';
+  if (!raw.startsWith('/')) return 'path_is_not_absolute';
+  if (structure.segments.length !== 1)
+    return 'operation_segment_contains_navigation_separator';
+  if (structure.firstSegmentHeadRuntimeDependent)
+    return 'operation_segment_is_runtime_dependent';
+  if (structure.firstParenthesisClose === undefined)
+    return 'top_level_invocation_parenthesis_is_unbalanced';
+  return undefined;
+}
+
+function rejectedNormalization(
+  raw: string,
+  reason: string,
+): NormalizedODataOperationPath {
+  return {
+    rawOperationPath: raw, normalizedOperationPath: raw,
+    wasInvocation: false, invocationArgumentPlaceholderKeys: [],
+    normalizationRejectedReason: reason,
+  };
+}
+
+export function classifyODataPathIntent(
+  path: string | undefined,
+  method: string | undefined,
+): ODataPathIntent {
   const rawPath = (path ?? '').trim();
   const normalizedMethod = (method ?? 'GET').trim().toUpperCase() || 'GET';
-  const queryIndex = rawPath.indexOf('?');
-  const pathWithoutQuery = queryIndex >= 0 ? rawPath.slice(0, queryIndex) : rawPath;
-  const queryString = queryIndex >= 0 ? rawPath.slice(queryIndex + 1) : undefined;
-  const segments = pathWithoutQuery.replace(/^\//, '').split('/').filter(Boolean);
-  const firstSegment = segments[0] ?? '';
-  const hasNavigationSegments = segments.length > 1;
-  const entitySegment = entitySegmentFromPath(pathWithoutQuery);
-  const placeholderKeys = [...new Set(extractTemplatePlaceholders(rawPath))];
-  const firstOpen = firstSegment.indexOf('(');
-  const firstClose = firstOpen >= 0 ? matchingClose(firstSegment, firstOpen) : undefined;
-  const keyPredicateText = firstOpen >= 0 && firstClose !== undefined ? firstSegment.slice(firstOpen + 1, firstClose) : '';
-  const rawKeyPredicatePlaceholderKeys = [...new Set(extractTemplatePlaceholders(keyPredicateText))];
-  const navigationSuffix = hasNavigationSegments ? segments.slice(1).join('/') : undefined;
-  const lastSegment = segments.at(-1) ?? '';
-  const mediaOrPropertySuffix = hasNavigationSegments ? lastSegment : undefined;
-  const invocation = normalizeODataOperationInvocationPath(pathWithoutQuery);
-  const operationNameFromInvocation = invocation?.wasInvocation ? invocation.normalizedOperationPath.replace(/^\//, '').split('.').at(-1) : undefined;
-  const topLevelName = firstSegment.split('(')[0]?.replace(/^\//, '');
-  const topLevelOperationName = operationNameFromInvocation ?? (!hasNavigationSegments && !firstSegment.includes('(') ? topLevelName : undefined);
-  const topLevelOperationInvocation = Boolean(invocation?.wasInvocation && looksLikeLowerCamelInvocation(firstSegment));
-  const keyPredicatePlaceholderKeys = topLevelOperationInvocation ? [] : rawKeyPredicatePlaceholderKeys;
-  const topLevelOperationNameCandidate = Boolean(topLevelOperationName && !hasNavigationSegments && !firstSegment.includes('('));
-  const base = { rawPath, method: normalizedMethod, pathWithoutQuery, queryString, hasQueryString: queryIndex >= 0, entitySegment, placeholderKeys, keyPredicatePlaceholderKeys, invocationArguments: invocation?.invocationArguments, invocationArgumentPlaceholderKeys: invocation?.invocationArgumentPlaceholderKeys ?? [], navigationSuffix, mediaOrPropertySuffix, hasEntityKeyPredicate: firstOpen >= 0 && firstClose !== undefined, hasNavigationSuffix: hasNavigationSegments, hasMediaOrPropertySuffix: Boolean(mediaOrPropertySuffix && isMediaOrPropertySuffix(mediaOrPropertySuffix)), topLevelOperationName, topLevelOperationNameCandidate, topLevelOperationInvocation };
-  if (!rawPath || !rawPath.startsWith('/')) return { ...base, kind: 'unknown', reason: 'path_missing_or_not_absolute' };
-  const upperEntityLike = /^[A-Z][A-Za-z0-9_]*$/.test(entitySegment ?? firstSegment);
-  const mediaLike = isMediaOrPropertySuffix(segments.at(-1) ?? '');
-  if (normalizedMethod !== 'GET') {
-    if (invocation?.wasInvocation && looksLikeLowerCamelInvocation(firstSegment)) return { ...base, kind: 'operation_invocation', reason: 'non_get_balanced_top_level_operation_invocation' };
-    if (mediaLike) return { ...base, kind: 'entity_media', reason: 'non_get_entity_media_stream_path' };
-    if (hasNavigationSegments || firstSegment.includes('(')) return { ...base, kind: normalizedMethod === 'DELETE' ? 'entity_delete' : 'entity_mutation', reason: firstSegment.includes('(') ? 'non_get_entity_key_or_navigation_path_shape' : 'non_get_entity_navigation_path_shape' };
-    if (upperEntityLike) return { ...base, kind: normalizedMethod === 'DELETE' ? 'entity_delete' : 'entity_mutation', reason: 'non_get_entity_path_shape' };
-    return { ...base, kind: 'operation_invocation', reason: 'non_get_lowercase_path_may_be_operation' };
-  }
-  if (queryIndex >= 0) {
-    if (hasNavigationSegments) return { ...base, kind: 'entity_navigation_query', reason: 'get_path_has_navigation_and_query_string' };
-    if (looksLikeLowerCamelInvocation(firstSegment)) return { ...base, kind: 'unknown', reason: 'get_invocation_with_query_string_requires_indexed_operation_evidence' };
-    return { ...base, kind: 'entity_query', reason: 'get_collection_path_has_query_string' };
-  }
-  if (hasNavigationSegments) return mediaLike ? { ...base, kind: 'entity_media', reason: 'get_entity_media_stream_path' } : { ...base, kind: 'entity_navigation_query', reason: 'get_path_has_navigation_segments' };
-  if (firstSegment.includes('(')) {
-    if (invocation?.wasInvocation && looksLikeLowerCamelInvocation(firstSegment)) return { ...base, kind: 'operation_invocation', reason: 'get_balanced_top_level_operation_invocation' };
-    return looksLikeLowerCamelInvocation(firstSegment)
-      ? { ...base, kind: 'operation_invocation', reason: 'get_single_lower_camel_segment_has_top_level_invocation' }
-      : { ...base, kind: 'entity_key_read', reason: 'get_entity_segment_has_key_predicate' };
-  }
-  if (/^[A-Z][A-Za-z0-9_]*$/.test(firstSegment)) return { ...base, kind: 'entity_candidate', reason: 'uppercase_collection_segment_without_indexed_entity_evidence' };
-  return { ...base, kind: 'unknown', reason: 'get_path_has_no_query_key_or_navigation_signal' };
-}
-
-function entitySegmentFromPath(path: string): string | undefined {
-  const first = path.replace(/^\//, '').split('/')[0]?.trim();
-  if (!first) return undefined;
-  const open = first.indexOf('(');
-  const entity = (open >= 0 ? first.slice(0, open) : first).trim();
-  return entity || undefined;
+  const structure = analyzeODataPathStructure(rawPath);
+  const invocation = normalizeODataOperationInvocationPath(
+    structure.pathWithoutQuery,
+  );
+  const base = intentBase(structure, normalizedMethod, invocation);
+  if (!rawPath || !rawPath.startsWith('/'))
+    return { ...base, kind: 'unknown', reason: 'path_missing_or_not_absolute' };
+  if (structure.status === 'malformed')
+    return {
+      ...base, kind: 'unknown',
+      reason: structure.reason ?? 'path_structure_is_malformed',
+    };
+  if (structure.firstSegmentHeadRuntimeDependent)
+    return {
+      ...base, kind: 'unknown',
+      reason: 'path_classification_head_is_runtime_dependent',
+    };
+  return normalizedMethod === 'GET'
+    ? classifyGet(structure, base, invocation)
+    : classifyMutation(structure, base, invocation, normalizedMethod);
 }
 
-function isMediaOrPropertySuffix(segment: string): boolean {
-  return ['file', 'content', '$value', 'metadata', 'items'].includes(segment.toLowerCase());
+function intentBase(
+  structure: ODataPathStructure,
+  method: string,
+  invocation: NormalizedODataOperationPath | undefined,
+): Omit<ODataPathIntent, 'kind' | 'reason'> {
+  const segments = structure.segments;
+  const navigation = navigationEvidence(segments);
+  const operation = operationEvidence(structure, invocation, navigation.navigation);
+  return {
+    rawPath: structure.rawPath, method,
+    pathWithoutQuery: structure.pathWithoutQuery,
+    queryString: structure.queryString,
+    hasQueryString: structure.queryIndex !== undefined,
+    entitySegment: structure.firstSegmentHead,
+    placeholderKeys: structure.placeholderKeys,
+    keyPredicatePlaceholderKeys: operation.invocation
+      ? [] : structure.firstParenthesisPlaceholderKeys,
+    invocationArgumentPlaceholderKeys:
+      invocation?.invocationArgumentPlaceholderKeys ?? [],
+    invocationArguments: invocation?.invocationArguments,
+    navigationSuffix: navigation.navigationSuffix,
+    mediaOrPropertySuffix: navigation.suffix,
+    hasEntityKeyPredicate: structure.firstParenthesisOpen !== undefined,
+    hasNavigationSuffix: navigation.navigation,
+    hasMediaOrPropertySuffix: Boolean(
+      navigation.suffix && isMediaOrPropertySuffix(navigation.suffix),
+    ),
+    topLevelOperationName: operation.name,
+    topLevelOperationNameCandidate:
+      operationNameIsCandidate(operation, structure, navigation.navigation),
+    topLevelOperationInvocation: operation.invocation,
+  };
 }
 
-function looksLikeLowerCamelInvocation(segment: string): boolean {
-  const open = segment.indexOf('(');
-  if (open <= 0) return false;
-  const name = segment.slice(0, open).split('.').at(-1) ?? segment.slice(0, open);
-  return /^[a-z][A-Za-z0-9_]*$/.test(name);
+function navigationEvidence(
+  segments: readonly { text: string }[],
+): NavigationEvidence {
+  if (segments.length <= 1) return { navigation: false };
+  return {
+    navigation: true,
+    suffix: segments.at(-1)?.text,
+    navigationSuffix: segments.slice(1).map((item) => item.text).join('/'),
+  };
 }
 
-function extractTemplatePlaceholders(text: string): string[] {
-  const keys: string[] = [];
-  for (let index = 0; index < text.length - 1; index += 1) {
-    if (text[index] !== '$' || text[index + 1] !== '{') continue;
-    const close = matchingPlaceholderClose(text, index + 1);
-    if (close === undefined) continue;
-    const key = text.slice(index + 2, close).trim();
-    if (key) keys.push(key);
-    index = close;
-  }
-  return keys;
-}
-
-function matchingClose(text: string, openIndex: number): number | undefined {
-  let depth = 0;
-  let quote: 'single' | 'double' | 'template' | undefined;
-  for (let index = openIndex; index < text.length; index += 1) {
-    const char = text[index];
-    const prev = text[index - 1];
-    if (quote) {
-      if (prev === '\\') continue;
-      if (quote === 'template' && char === '$' && text[index + 1] === '{') {
-        const close = matchingPlaceholderClose(text, index + 1);
-        if (close === undefined) return undefined;
-        index = close;
-        continue;
-      }
-      if ((quote === 'single' && char === "'") || (quote === 'double' && char === '"') || (quote === 'template' && char === '`')) quote = undefined;
-      continue;
-    }
-    if (char === '$' && text[index + 1] === '{') {
-      const close = matchingPlaceholderClose(text, index + 1);
-      if (close === undefined) return undefined;
-      index = close;
-      continue;
-    }
-    if (char === "'") { quote = 'single'; continue; }
-    if (char === '"') { quote = 'double'; continue; }
-    if (char === '`') { quote = 'template'; continue; }
-    if (char === '(') depth += 1;
-    if (char === ')') {
-      depth -= 1;
-      if (depth === 0) return index;
-      if (depth < 0) return undefined;
-    }
-  }
-  return undefined;
+function operationEvidence(
+  structure: ODataPathStructure,
+  normalized: NormalizedODataOperationPath | undefined,
+  navigation: boolean,
+): OperationEvidence {
+  if (normalized?.wasInvocation)
+    return {
+      invocation: looksLikeLowerCamelHead(structure.firstSegmentHead),
+      name: simpleName(normalized.normalizedOperationPath),
+    };
+  if (!navigation && structure.firstParenthesisOpen === undefined)
+    return { invocation: false, name: structure.firstSegmentHead };
+  return { invocation: false };
 }
 
-function matchingPlaceholderClose(text: string, openBraceIndex: number): number | undefined {
-  let depth = 0;
-  let quote: 'single' | 'double' | 'template' | undefined;
-  for (let index = openBraceIndex; index < text.length; index += 1) {
-    const char = text[index];
-    const prev = text[index - 1];
-    if (quote) {
-      if (prev === '\\') continue;
-      if (quote === 'template' && char === '$' && text[index + 1] === '{') {
-        depth += 1;
-        index += 1;
-        continue;
-      }
-      if ((quote === 'single' && char === "'") || (quote === 'double' && char === '"') || (quote === 'template' && char === '`')) quote = undefined;
-      continue;
-    }
-    if (char === "'") { quote = 'single'; continue; }
-    if (char === '"') { quote = 'double'; continue; }
-    if (char === '`') { quote = 'template'; continue; }
-    if (char === '{') depth += 1;
-    if (char === '}') {
-      depth -= 1;
-      if (depth === 0) return index;
-      if (depth < 0) return undefined;
-    }
-  }
-  return undefined;
+function operationNameIsCandidate(
+  operation: OperationEvidence,
+  structure: ODataPathStructure,
+  navigation: boolean,
+): boolean {
+  return Boolean(
+    operation.name && !navigation
+    && structure.firstParenthesisOpen === undefined,
+  );
+}
+
+function classifyGet(
+  structure: ODataPathStructure,
+  base: Omit<ODataPathIntent, 'kind' | 'reason'>,
+  invocation: NormalizedODataOperationPath | undefined,
+): ODataPathIntent {
+  if (structure.queryIndex !== undefined) return classifyGetQuery(base);
+  if (base.hasNavigationSuffix)
+    return classifyGetNavigation(base);
+  if (structure.firstParenthesisOpen !== undefined)
+    return classifyGetParenthesis(base, invocation);
+  if (isUpperEntity(base.entitySegment))
+    return {
+      ...base, kind: 'entity_candidate',
+      reason: 'uppercase_collection_segment_without_indexed_entity_evidence',
+    };
+  return {
+    ...base, kind: 'unknown',
+    reason: 'get_path_has_no_query_key_or_navigation_signal',
+  };
+}
+
+function classifyGetQuery(
+  base: Omit<ODataPathIntent, 'kind' | 'reason'>,
+): ODataPathIntent {
+  if (base.hasNavigationSuffix)
+    return {
+      ...base, kind: 'entity_navigation_query',
+      reason: 'get_path_has_navigation_and_query_string',
+    };
+  if (base.topLevelOperationInvocation)
+    return {
+      ...base, kind: 'unknown',
+      reason: 'get_invocation_with_query_string_requires_indexed_operation_evidence',
+    };
+  return {
+    ...base, kind: 'entity_query',
+    reason: 'get_collection_path_has_query_string',
+  };
+}
+
+function classifyGetNavigation(
+  base: Omit<ODataPathIntent, 'kind' | 'reason'>,
+): ODataPathIntent {
+  return base.hasMediaOrPropertySuffix
+    ? { ...base, kind: 'entity_media', reason: 'get_entity_media_stream_path' }
+    : {
+        ...base, kind: 'entity_navigation_query',
+        reason: 'get_path_has_navigation_segments',
+      };
+}
+
+function classifyGetParenthesis(
+  base: Omit<ODataPathIntent, 'kind' | 'reason'>,
+  invocation: NormalizedODataOperationPath | undefined,
+): ODataPathIntent {
+  if (invocation?.wasInvocation && base.topLevelOperationInvocation)
+    return {
+      ...base, kind: 'operation_invocation',
+      reason: 'get_balanced_top_level_operation_invocation',
+    };
+  return {
+    ...base, kind: 'entity_key_read',
+    reason: 'get_entity_segment_has_key_predicate',
+  };
+}
+
+function classifyMutation(
+  structure: ODataPathStructure,
+  base: Omit<ODataPathIntent, 'kind' | 'reason'>,
+  invocation: NormalizedODataOperationPath | undefined,
+  method: string,
+): ODataPathIntent {
+  if (invocation?.wasInvocation && base.topLevelOperationInvocation)
+    return {
+      ...base, kind: 'operation_invocation',
+      reason: 'non_get_balanced_top_level_operation_invocation',
+    };
+  if (base.hasMediaOrPropertySuffix)
+    return {
+      ...base, kind: 'entity_media',
+      reason: 'non_get_entity_media_stream_path',
+    };
+  if (base.hasNavigationSuffix || structure.firstParenthesisOpen !== undefined)
+    return mutationEntityIntent(base, method,
+      structure.firstParenthesisOpen !== undefined
+        ? 'non_get_entity_key_or_navigation_path_shape'
+        : 'non_get_entity_navigation_path_shape');
+  if (isUpperEntity(base.entitySegment))
+    return mutationEntityIntent(base, method, 'non_get_entity_path_shape');
+  return {
+    ...base, kind: 'operation_invocation',
+    reason: 'non_get_lowercase_path_may_be_operation',
+  };
 }
 
-function topLevelQueryIndex(text: string): number {
-  let quote: 'single' | 'double' | 'template' | undefined;
-  for (let index = 0; index < text.length; index += 1) {
-    const char = text[index];
-    const prev = text[index - 1];
-    if (quote) {
-      if (prev === '\\') continue;
-      if (quote === 'template' && char === '$' && text[index + 1] === '{') {
-        const close = matchingPlaceholderClose(text, index + 1);
-        if (close === undefined) return -1;
-        index = close;
-        continue;
-      }
-      if ((quote === 'single' && char === "'") || (quote === 'double' && char === '"') || (quote === 'template' && char === '`')) quote = undefined;
-      continue;
-    }
-    if (char === '$' && text[index + 1] === '{') {
-      const close = matchingPlaceholderClose(text, index + 1);
-      if (close === undefined) return -1;
-      index = close;
-      continue;
-    }
-    if (char === "'") { quote = 'single'; continue; }
-    if (char === '"') { quote = 'double'; continue; }
-    if (char === '`') { quote = 'template'; continue; }
-    if (char === '?') return index;
-  }
-  return -1;
+function mutationEntityIntent(
+  base: Omit<ODataPathIntent, 'kind' | 'reason'>,
+  method: string,
+  reason: string,
+): ODataPathIntent {
+  return {
+    ...base,
+    kind: method === 'DELETE' ? 'entity_delete' : 'entity_mutation',
+    reason,
+  };
+}
+
+function simpleName(path: string): string {
+  const value = path.replace(/^\//, '');
+  return value.split('.').at(-1) ?? value;
+}
+
+function isUpperEntity(value: string | undefined): boolean {
+  return Boolean(value && /^[A-Z][A-Za-z0-9_]*$/.test(value));
+}
+
+function looksLikeLowerCamelHead(value: string | undefined): boolean {
+  if (!value) return false;
+  const name = value.split('.').at(-1) ?? value;
+  return /^[a-z][A-Za-z0-9_]*$/.test(name);
+}
+
+function isMediaOrPropertySuffix(segment: string): boolean {
+  return ['file', 'content', '$value', 'metadata', 'items']
+    .includes(segment.toLowerCase());
 }