@saptools/service-flow 0.1.47 → 0.1.49

package/src/output/doctor-output.ts

@@ -0,0 +1,98 @@
+import pc from 'picocolors';
+import { renderJson } from './json-output.js';
+
+type Diagnostic = Record<string, unknown>;
+
+export function renderDoctorDiagnostics(diagnostics: Diagnostic[], format: string | undefined): string {
+  if (format === 'json') return renderJson(diagnostics);
+  if (format === 'table') return renderDoctorTable(diagnostics);
+  if (format) throw new Error(`Unsupported doctor format: ${format}. Expected json or table.`);
+  return renderLegacyDoctorOutput(diagnostics);
+}
+
+function renderLegacyDoctorOutput(diagnostics: Diagnostic[]): string {
+  if (diagnostics.length === 0) return cleanDoctorMessage();
+  return renderJson(diagnostics);
+}
+
+export function renderDoctorTable(diagnostics: Diagnostic[]): string {
+  if (diagnostics.length === 0) return cleanDoctorMessage();
+  const rows = diagnostics.map((diagnostic) => ({
+    severity: String(diagnostic.severity ?? 'info'),
+    code: String(diagnostic.code ?? 'diagnostic'),
+    location: diagnosticLocation(diagnostic),
+    message: compactMessage(diagnostic),
+    hints: suggestedHintLines(diagnostic),
+  }));
+  const widths = {
+    severity: columnWidth('Severity', rows.map((row) => row.severity), 10),
+    code: columnWidth('Code', rows.map((row) => row.code), 44),
+    location: columnWidth('Location', rows.map((row) => row.location), 28),
+  };
+  const lines = [
+    `${'Severity'.padEnd(widths.severity)} ${'Code'.padEnd(widths.code)} ${'Location'.padEnd(widths.location)} Message`,
+    `${'-'.repeat(widths.severity)} ${'-'.repeat(widths.code)} ${'-'.repeat(widths.location)} ${'-'.repeat(7)}`,
+  ];
+  for (const row of rows) {
+    lines.push(`${truncate(row.severity, widths.severity).padEnd(widths.severity)} ${truncate(row.code, widths.code).padEnd(widths.code)} ${truncate(row.location, widths.location).padEnd(widths.location)} ${row.message}`);
+    lines.push(...row.hints.map((hint) => `  try ${hint}`));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function diagnosticLocation(diagnostic: Diagnostic): string {
+  const file = diagnostic.sourceFile ?? diagnostic.file;
+  const line = diagnostic.sourceLine ?? diagnostic.line;
+  if (file || line) return `${String(file ?? '')}:${String(line ?? '')}`;
+  return '-';
+}
+
+function compactMessage(diagnostic: Diagnostic): string {
+  const message = String(diagnostic.message ?? '');
+  const count = typeof diagnostic.count === 'number' ? ` count=${diagnostic.count}` : '';
+  const total = typeof diagnostic.total === 'number' ? ` total=${diagnostic.total}` : '';
+  return `${message}${count}${total}`.trim();
+}
+
+function suggestedHintLines(diagnostic: Diagnostic): string[] {
+  const direct = cliHints(diagnostic.suggestedHints);
+  if (direct.length > 0) return cappedHints(direct);
+  return cappedHints(cliHintsFromSuggestions(diagnostic.implementationHintSuggestions));
+}
+
+function cliHints(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+}
+
+function cliHintsFromSuggestions(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!isRecord(item)) return [];
+    return typeof item.cli === 'string' ? [item.cli] : [];
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function cappedHints(hints: string[]): string[] {
+  const unique = [...new Set(hints)];
+  const shown = unique.slice(0, 3);
+  if (unique.length > shown.length) shown.push(`... ${unique.length - shown.length} more hint(s) available in --format json`);
+  return shown;
+}
+
+function cleanDoctorMessage(): string {
+  return `${pc.green('No diagnostics recorded')}\n`;
+}
+
+function columnWidth(header: string, values: string[], max: number): number {
+  return Math.min(max, Math.max(header.length, ...values.map((value) => value.length)));
+}
+
+function truncate(value: string, width: number): string {
+  if (value.length <= width) return value;
+  if (width <= 1) return value.slice(0, width);
+  return `${value.slice(0, width - 1)}…`;
+}

package/src/output/table-output.ts

@@ -15,8 +15,8 @@ export function renderTraceTable(result: TraceResult): string {
   const lines = ['Step  Type                 From                                To                                  Evidence'];
   for (const e of result.edges) {
     lines.push(`${String(e.step).padEnd(5)} ${e.type.padEnd(20)} ${e.from.slice(0, 34).padEnd(35)} ${e.to.slice(0, 35).padEnd(36)} ${location(e.evidence)}`);
-    const hint = firstHint(e.evidence);
-    if (e.unresolvedReason && hint) lines.push(`      try ${hint}`);
+    if (e.unresolvedReason)
+      lines.push(...hintLines(e.evidence).map((hint) => `      ${hint}`));
   }
   if (result.diagnostics.length > 0) lines.push('', 'Diagnostics:', ...result.diagnostics.flatMap(diagnosticLines));
   return `${lines.join('\n')}\n`;
@@ -24,13 +24,23 @@ export function renderTraceTable(result: TraceResult): string {
 
 function diagnosticLines(diagnostic: Record<string, unknown>): string[] {
   const first = `${String(diagnostic.severity ?? 'info')} ${String(diagnostic.code ?? 'diagnostic')} ${String(diagnostic.message ?? '')}`;
-  const hint = firstHint(diagnostic);
-  return hint ? [first, `  try ${hint}`] : [first];
+  return [first, ...hintLines(diagnostic).map((hint) => `  ${hint}`)];
 }
 
-function firstHint(evidence: Record<string, unknown>): string | undefined {
+function hintLines(evidence: Record<string, unknown>): string[] {
   const suggestions = evidence.implementationHintSuggestions;
-  if (!Array.isArray(suggestions)) return undefined;
-  const first = suggestions.find((item): item is Record<string, unknown> => Boolean(item) && typeof item === 'object');
-  return typeof first?.cli === 'string' ? first.cli : undefined;
+  if (!Array.isArray(suggestions)) return [];
+  const hints = suggestions.flatMap((item) =>
+    isRecord(item) && typeof item.cli === 'string'
+      ? [item.cli]
+      : []);
+  const unique = [...new Set(hints)];
+  const shown = unique.slice(0, 3).map((hint) => `try ${hint}`);
+  if (unique.length > shown.length)
+    shown.push(`... ${unique.length - shown.length} more hint(s) available in JSON`);
+  return shown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }

package/src/parsers/imported-wrapper-parser.ts

@@ -4,6 +4,11 @@ import { classifyODataPathIntent } from '../linker/odata-path-normalizer.js';
 import type { OutboundCallFact } from '../types.js';
 import { normalizePath } from '../utils/path-utils.js';
 import { importsFor, lineOf, readSource, type ImportBinding } from './service-binding-parser-helpers.js';
+import {
+  analyzeOperationPath,
+  operationPathExpression,
+  pathUnresolvedReason,
+} from './operation-path-analysis.js';
 
 interface WrapperSpec {
   clientIndex: number;
@@ -15,12 +20,6 @@ interface WrapperSpec {
   chain: string[];
 }
 
-interface PathValue {
-  value?: string;
-  sourceKind: string;
-  rawExpression: string;
-}
-
 export async function parseImportedWrapperCalls(
   repoPath: string,
   filePath: string,
@@ -143,11 +142,11 @@ function wrapperCallFact(
 ): OutboundCallFact | undefined {
   const client = call.arguments[spec.clientIndex];
   if (!client || !ts.isIdentifier(client) || !serviceBindings.has(client.text)) return undefined;
-  const pathValue = resolveCallerPath(call.arguments[spec.pathIndex], call);
   const methodValue = spec.methodIndex === undefined ? spec.methodLiteral : literal(call.arguments[spec.methodIndex]);
   const method = (methodValue ?? 'POST').toUpperCase();
-  const rawPath = pathValue.rawExpression;
-  const operationPathExpr = pathValue.value ? normalizeOperationPath(pathValue.value) : runtimePathExpression(rawPath);
+  const pathAnalysis = analyzeOperationPath(call.arguments[spec.pathIndex], call, method);
+  const operationPathExpr = operationPathExpression(pathAnalysis);
+  const unresolvedReason = pathUnresolvedReason(pathAnalysis);
   return {
     callType: 'remote_action',
     serviceVariableName: client.text,
@@ -157,46 +156,29 @@ function wrapperCallFact(
     sourceFile: normalizePath(filePath),
     sourceLine: lineOf(source, call),
     confidence: operationPathExpr ? 0.85 : 0.5,
-    unresolvedReason: pathValue.value ? undefined : 'dynamic_operation_path_identifier',
+    unresolvedReason,
     evidence: {
       parser: 'typescript_ast',
-      classifier: pathValue.value ? 'imported_wrapper_literal_path' : 'imported_wrapper_dynamic_path',
+      classifier: importedWrapperClassifier(pathAnalysis.status),
       receiver: client.text,
       wrapperFunction: spec.chain[0],
       wrapperChain: spec.chain,
       callerSite: { sourceFile: normalizePath(filePath), sourceLine: lineOf(source, call) },
       calleeSite: { sourceFile: spec.sourceFile, sourceLine: spec.sourceLine },
-      rawPathExpression: rawPath,
-      missingPathIdentifier: pathValue.value ? undefined : rawPath,
-      odataPathIntent: pathValue.value ? classifyODataPathIntent(operationPathExpr, method) : undefined,
+      rawPathExpression: pathAnalysis.rawExpression,
+      missingPathIdentifier: pathAnalysis.runtimeIdentifier,
+      pathAnalysis,
+      odataPathIntent: operationPathExpr
+        ? classifyODataPathIntent(operationPathExpr, method)
+        : undefined,
     },
   };
 }
 
-function resolveCallerPath(expr: ts.Expression | undefined, use: ts.Node): PathValue {
-  if (!expr) return { sourceKind: 'missing', rawExpression: '' };
-  if (ts.isStringLiteralLike(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) return { value: expr.text, sourceKind: 'literal', rawExpression: expr.getText() };
-  if (ts.isTemplateExpression(expr)) return { value: expr.getText().slice(1, -1), sourceKind: 'template', rawExpression: expr.getText() };
-  if (ts.isIdentifier(expr)) {
-    const initializer = constInitializer(expr.text, use);
-    if (initializer) {
-      const resolved = resolveCallerPath(initializer, initializer);
-      return { ...resolved, sourceKind: 'const', rawExpression: expr.text };
-    }
-  }
-  return { sourceKind: 'dynamic', rawExpression: expr.getText() };
-}
-
-function constInitializer(name: string, use: ts.Node): ts.Expression | undefined {
-  let found: ts.Expression | undefined;
-  const source = use.getSourceFile();
-  const visit = (node: ts.Node): void => {
-    if (node.getStart(source) >= use.getStart(source)) return;
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && node.initializer && (node.parent.flags & ts.NodeFlags.Const) !== 0) found = node.initializer;
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  return found;
+function importedWrapperClassifier(status: string): string {
+  if (status === 'static') return 'imported_wrapper_literal_path';
+  if (status === 'ambiguous') return 'imported_wrapper_ambiguous_path';
+  return 'imported_wrapper_dynamic_path';
 }
 
 function findFunction(source: ts.SourceFile, exportedName: string): { name: string; fn: ts.FunctionLikeDeclaration } | undefined {
@@ -252,11 +234,3 @@ function propertyName(name: ts.PropertyName): string | undefined {
 function literal(expr: ts.Expression | undefined): string | undefined {
   return expr && (ts.isStringLiteralLike(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) ? expr.text : undefined;
 }
-
-function normalizeOperationPath(value: string): string {
-  return value.startsWith('/') ? value : `/${value}`;
-}
-
-function runtimePathExpression(value: string): string | undefined {
-  return value ? `\${${value}}` : undefined;
-}

package/src/parsers/operation-path-analysis.ts

@@ -0,0 +1,350 @@
+import ts from 'typescript';
+import {
+  classifyODataPathIntent,
+  normalizeODataOperationInvocationPath,
+} from '../linker/odata-path-normalizer.js';
+
+export type OperationPathStatus = 'static' | 'ambiguous' | 'dynamic' | 'unknown';
+
+export interface OperationPathAnalysis {
+  status: OperationPathStatus;
+  rawExpression?: string;
+  normalizedOperationPath?: string;
+  candidateRawPaths: string[];
+  candidateNormalizedOperationPaths: string[];
+  placeholderKeys: string[];
+  sourceKind: string;
+  candidateIdentifier?: string;
+  runtimeIdentifier?: string;
+  dynamicReassignments: Array<{ expression: string; sourceLine: number }>;
+  lexicalScope: {
+    declarationLine?: number;
+    assignmentLines: number[];
+    sourceOrderSafe: boolean;
+  };
+}
+
+interface CandidateState {
+  paths: string[];
+  placeholders: string[];
+  dynamic: Array<{ expression: string; sourceLine: number }>;
+  sourceKinds: string[];
+}
+
+interface Binding {
+  declaration: ts.VariableDeclaration | ts.ParameterDeclaration;
+  immutable: boolean;
+}
+
+const maxAliasDepth = 6;
+
+export function analyzeOperationPath(
+  expression: ts.Expression | undefined,
+  use: ts.Node,
+  method = 'POST',
+): OperationPathAnalysis {
+  if (!expression) return emptyAnalysis();
+  const state = collectExpressionState(expression, use, 0, new Set());
+  const paths = unique(state.paths.map(normalizeRawPath));
+  const normalized = unique(paths.flatMap((value) => normalizedCandidate(value, method)));
+  const status = pathStatus(paths, state.placeholders, state.dynamic);
+  const runtimeIdentifier = state.dynamic.at(-1)?.expression;
+  return {
+    status,
+    rawExpression: expression.getText(expression.getSourceFile()),
+    normalizedOperationPath: status === 'static' && normalized.length === 1 ? normalized[0] : undefined,
+    candidateRawPaths: paths,
+    candidateNormalizedOperationPaths: normalized,
+    placeholderKeys: unique([...state.placeholders, ...(runtimeIdentifier ? [runtimeIdentifier] : [])]),
+    sourceKind: unique(state.sourceKinds).join('+') || 'unknown',
+    candidateIdentifier: ts.isIdentifier(expression) ? expression.text : undefined,
+    runtimeIdentifier,
+    dynamicReassignments: state.dynamic,
+    lexicalScope: lexicalEvidence(expression, use),
+  };
+}
+
+export function operationPathExpression(analysis: OperationPathAnalysis): string | undefined {
+  if (analysis.status === 'ambiguous' || analysis.status === 'unknown') return undefined;
+  if (analysis.sourceKind.includes('parameter_binding')) return undefined;
+  if (analysis.candidateRawPaths.length === 1 && analysis.dynamicReassignments.length === 0)
+    return analysis.candidateRawPaths[0];
+  if (!analysis.runtimeIdentifier || analysis.sourceKind.includes('binding_not_found'))
+    return undefined;
+  return isRuntimeIdentifier(analysis.runtimeIdentifier)
+    ? `\${${analysis.runtimeIdentifier}}`
+    : undefined;
+}
+
+export function pathUnresolvedReason(analysis: OperationPathAnalysis): string | undefined {
+  if (analysis.status === 'ambiguous') return 'ambiguous_operation_path_candidates';
+  if (analysis.status === 'dynamic' && !operationPathExpression(analysis))
+    return 'dynamic_operation_path_identifier';
+  if (analysis.dynamicReassignments.length > 0) return 'dynamic_operation_path_identifier';
+  return undefined;
+}
+
+function collectExpressionState(
+  expression: ts.Expression,
+  use: ts.Node,
+  depth: number,
+  seen: Set<ts.Node>,
+): CandidateState {
+  const unwrapped = unwrap(expression);
+  if (ts.isStringLiteral(unwrapped)) return staticState(unwrapped.text, 'string_literal');
+  if (ts.isNoSubstitutionTemplateLiteral(unwrapped))
+    return staticState(unwrapped.text, 'no_substitution_template');
+  if (ts.isTemplateExpression(unwrapped)) return templateState(unwrapped);
+  if (ts.isConditionalExpression(unwrapped))
+    return mergeStates([
+      collectExpressionState(unwrapped.whenTrue, use, depth + 1, seen),
+      collectExpressionState(unwrapped.whenFalse, use, depth + 1, seen),
+    ], 'conditional_candidates');
+  if (ts.isIdentifier(unwrapped))
+    return collectIdentifierState(unwrapped, use, depth, seen);
+  return dynamicState(unwrapped);
+}
+
+function collectIdentifierState(
+  identifier: ts.Identifier,
+  use: ts.Node,
+  depth: number,
+  seen: Set<ts.Node>,
+): CandidateState {
+  if (depth >= maxAliasDepth)
+    return dynamicState(identifier, 'alias_depth_exceeded');
+  const binding = resolveBinding(identifier, use);
+  if (!binding || seen.has(binding.declaration))
+    return dynamicState(identifier, binding ? 'alias_cycle' : 'binding_not_found');
+  seen.add(binding.declaration);
+  if (ts.isParameter(binding.declaration))
+    return dynamicState(identifier, 'parameter_binding');
+  const expressions = reachingExpressions(binding.declaration, use);
+  if (expressions.length === 0) return dynamicState(identifier, 'initializer_missing');
+  const states = expressions.map((item) =>
+    collectExpressionState(item.expression, item.node, depth + 1, seen));
+  const merged = mergeStates(states, binding.immutable ? 'const_alias' : 'mutable_alias');
+  if (merged.dynamic.length === 0) return merged;
+  return {
+    ...merged,
+    dynamic: merged.dynamic.map((item) =>
+      item.expression === identifier.text ? item : item),
+  };
+}
+
+function reachingExpressions(
+  declaration: ts.VariableDeclaration,
+  use: ts.Node,
+): Array<{ expression: ts.Expression; node: ts.Node }> {
+  const rows: Array<{ expression: ts.Expression; node: ts.Node }> = [];
+  if (declaration.initializer) rows.push({ expression: declaration.initializer, node: declaration });
+  if ((declaration.parent.flags & ts.NodeFlags.Const) !== 0) return rows;
+  const source = use.getSourceFile();
+  const visit = (node: ts.Node): void => {
+    if (node.getStart(source) >= use.getStart(source)) return;
+    if (node !== source && ts.isFunctionLike(node) && !contains(node, use)) return;
+    if (isAssignmentTo(node, declaration, use))
+      rows.push({ expression: node.right, node });
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return rows.sort((left, right) =>
+    left.node.getStart(source) - right.node.getStart(source));
+}
+
+function isAssignmentTo(
+  node: ts.Node,
+  declaration: ts.VariableDeclaration,
+  use: ts.Node,
+): node is ts.BinaryExpression {
+  if (!ts.isBinaryExpression(node) || node.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+    return false;
+  if (!ts.isIdentifier(node.left) || !ts.isIdentifier(declaration.name)) return false;
+  return resolveBinding(node.left, node)?.declaration === declaration && contains(declarationScope(declaration), use);
+}
+
+function resolveBinding(identifier: ts.Identifier, use: ts.Node): Binding | undefined {
+  const source = use.getSourceFile();
+  const matches: Array<ts.VariableDeclaration | ts.ParameterDeclaration> = [];
+  const visit = (node: ts.Node): void => {
+    if (isNamedDeclaration(node, identifier.text) && isAccessible(node, use))
+      matches.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  const declaration = matches.sort((left, right) =>
+    right.getStart(source) - left.getStart(source))[0];
+  if (!declaration) return undefined;
+  const immutable = ts.isVariableDeclaration(declaration)
+    && (declaration.parent.flags & ts.NodeFlags.Const) !== 0;
+  return { declaration, immutable };
+}
+
+function isNamedDeclaration(
+  node: ts.Node,
+  name: string,
+): node is ts.VariableDeclaration | ts.ParameterDeclaration {
+  return (ts.isVariableDeclaration(node) || ts.isParameter(node))
+    && ts.isIdentifier(node.name)
+    && node.name.text === name;
+}
+
+function isAccessible(
+  declaration: ts.VariableDeclaration | ts.ParameterDeclaration,
+  use: ts.Node,
+): boolean {
+  const source = use.getSourceFile();
+  if (declaration.name.getStart(source) >= use.getStart(source)) return false;
+  const scope = declarationScope(declaration);
+  return ts.isSourceFile(scope) || contains(scope, use);
+}
+
+function declarationScope(
+  declaration: ts.VariableDeclaration | ts.ParameterDeclaration,
+): ts.Node {
+  if (ts.isParameter(declaration)) return declaration.parent;
+  if (ts.isCatchClause(declaration.parent)) return declaration.parent.block;
+  const list = declaration.parent;
+  if (isLoopInitializer(list.parent)) return list.parent.statement;
+  const blockScoped = (list.flags & (ts.NodeFlags.Const | ts.NodeFlags.Let)) !== 0;
+  let current: ts.Node = list.parent;
+  if (!blockScoped) {
+    while (current.parent && !ts.isFunctionLike(current) && !ts.isSourceFile(current))
+      current = current.parent;
+    return current;
+  }
+  while (current.parent && !isLexicalScope(current)) current = current.parent;
+  return current;
+}
+
+function isLoopInitializer(
+  node: ts.Node,
+): node is ts.ForStatement | ts.ForInStatement | ts.ForOfStatement {
+  return ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node);
+}
+
+function isLexicalScope(node: ts.Node): boolean {
+  return ts.isBlock(node)
+    || ts.isSourceFile(node)
+    || ts.isModuleBlock(node)
+    || ts.isCaseBlock(node)
+    || ts.isFunctionLike(node);
+}
+
+function templateState(expression: ts.TemplateExpression): CandidateState {
+  const value = expression.getText(expression.getSourceFile()).slice(1, -1);
+  return {
+    paths: [value],
+    placeholders: expression.templateSpans.map((span) =>
+      span.expression.getText(expression.getSourceFile())),
+    dynamic: [],
+    sourceKinds: ['template_with_placeholders'],
+  };
+}
+
+function staticState(path: string, sourceKind: string): CandidateState {
+  return { paths: [path], placeholders: [], dynamic: [], sourceKinds: [sourceKind] };
+}
+
+function dynamicState(expression: ts.Expression, sourceKind = 'dynamic_expression'): CandidateState {
+  return {
+    paths: [],
+    placeholders: [],
+    dynamic: [{
+      expression: expression.getText(expression.getSourceFile()),
+      sourceLine: sourceLine(expression),
+    }],
+    sourceKinds: [sourceKind],
+  };
+}
+
+function mergeStates(states: CandidateState[], sourceKind: string): CandidateState {
+  return {
+    paths: states.flatMap((state) => state.paths),
+    placeholders: states.flatMap((state) => state.placeholders),
+    dynamic: states.flatMap((state) => state.dynamic),
+    sourceKinds: [sourceKind, ...states.flatMap((state) => state.sourceKinds)],
+  };
+}
+
+function pathStatus(
+  paths: string[],
+  placeholders: string[],
+  dynamic: CandidateState['dynamic'],
+): OperationPathStatus {
+  if (dynamic.length > 0) return 'dynamic';
+  if (paths.length > 1) return 'ambiguous';
+  if (placeholders.length > 0) return 'dynamic';
+  if (paths.length === 1) return 'static';
+  return 'unknown';
+}
+
+function normalizedCandidate(value: string, method: string): string[] {
+  const invocation = normalizeODataOperationInvocationPath(value);
+  if (invocation?.wasInvocation) return [invocation.normalizedOperationPath];
+  const intent = classifyODataPathIntent(value, method);
+  if (intent.kind.startsWith('entity_')) return [];
+  if (!value.startsWith('/') || value.slice(1).includes('/') || value.includes('?')) return [];
+  return [value];
+}
+
+function lexicalEvidence(expression: ts.Expression, use: ts.Node): OperationPathAnalysis['lexicalScope'] {
+  if (!ts.isIdentifier(expression))
+    return { assignmentLines: [], sourceOrderSafe: expression.getStart() < use.getStart() };
+  const binding = resolveBinding(expression, use);
+  if (!binding) return { assignmentLines: [], sourceOrderSafe: false };
+  const assignmentLines = ts.isVariableDeclaration(binding.declaration)
+    ? reachingExpressions(binding.declaration, use)
+        .slice(binding.declaration.initializer ? 1 : 0)
+        .map((item) => sourceLine(item.node))
+    : [];
+  return {
+    declarationLine: sourceLine(binding.declaration),
+    assignmentLines,
+    sourceOrderSafe: true,
+  };
+}
+
+function unwrap(expression: ts.Expression): ts.Expression {
+  if (ts.isAwaitExpression(expression) || ts.isParenthesizedExpression(expression))
+    return unwrap(expression.expression);
+  if (ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression)
+    || ts.isTypeAssertionExpression(expression))
+    return unwrap(expression.expression);
+  return expression;
+}
+
+function normalizeRawPath(value: string): string {
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function isRuntimeIdentifier(value: string): boolean {
+  return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(value);
+}
+
+function contains(parent: ts.Node, child: ts.Node): boolean {
+  const source = child.getSourceFile();
+  return child.getStart(source) >= parent.getStart(source)
+    && child.getEnd() <= parent.getEnd();
+}
+
+function sourceLine(node: ts.Node): number {
+  const source = node.getSourceFile();
+  return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+function emptyAnalysis(): OperationPathAnalysis {
+  return {
+    status: 'unknown',
+    candidateRawPaths: [],
+    candidateNormalizedOperationPaths: [],
+    placeholderKeys: [],
+    sourceKind: 'missing',
+    dynamicReassignments: [],
+    lexicalScope: { assignmentLines: [], sourceOrderSafe: false },
+  };
+}