@saptools/service-flow 0.1.50 → 0.1.52

package/src/parsers/handler-registration-parser.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import ts from 'typescript';
 import type { HandlerRegistrationFact } from '../types.js';
 import { normalizePath } from '../utils/path-utils.js';
+import type { RepositorySourceContext } from './ts-project.js';
 
 interface ImportEvidence { importedName: string; source: string }
 interface ClassEvidence { className: string; importSource?: string }
@@ -26,16 +27,26 @@ function importSourceFor(identifier: string, imports: Map<string, ImportEvidence
   return evidence ? `${evidence.source}#${evidence.importedName}` : undefined;
 }
 
-export async function parseHandlerRegistrations(repoPath: string, filePath: string): Promise<HandlerRegistrationFact[]> {
+export async function parseHandlerRegistrations(
+  repoPath: string,
+  filePath: string,
+  context?: RepositorySourceContext,
+): Promise<HandlerRegistrationFact[]> {
   const absolutePath = path.join(repoPath, filePath);
-  const text = await fs.readFile(absolutePath, 'utf8');
-  const sourceFile = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const snapshot = context?.get(filePath);
+  const text = snapshot?.text ?? await fs.readFile(absolutePath, 'utf8');
+  const sourceFile = snapshot?.sourceFile() ?? ts.createSourceFile(
+    filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS,
+  );
   const imports = collectImports(sourceFile);
-  const localArrays = collectLocalArrays(sourceFile, imports, new Map(), repoPath, filePath);
+  const localArrays = collectLocalArrays(
+    sourceFile, imports, new Map(), repoPath, filePath, context,
+  );
   const out: HandlerRegistrationFact[] = [];
-
   function emitFromExpression(expression: ts.Expression, call: ts.CallExpression): void {
-    const classes = resolveArrayExpression(expression, localArrays, imports, repoPath, filePath, new Set());
+    const classes = resolveArrayExpression(
+      expression, localArrays, imports, repoPath, filePath, new Set(), context,
+    );
     for (const cls of classes) {
       out.push({
         className: cls.className,
@@ -55,7 +66,6 @@ export async function parseHandlerRegistrations(repoPath: string, filePath: stri
       });
     }
   }
-
   function visit(node: ts.Node): void {
     if (ts.isCallExpression(node) && isRegistrationCall(node)) {
       const handlerExpr = handlerExpression(node, sourceFile);
@@ -98,45 +108,47 @@ function collectImports(sourceFile: ts.SourceFile): Map<string, ImportEvidence>
   }
   return imports;
 }
-function collectLocalArrays(sourceFile: ts.SourceFile, imports: Map<string, ImportEvidence>, seed: Map<string, ClassEvidence[]>, repoPath = '', fromFile = ''): Map<string, ClassEvidence[]> {
+function collectLocalArrays(sourceFile: ts.SourceFile, imports: Map<string, ImportEvidence>, seed: Map<string, ClassEvidence[]>, repoPath = '', fromFile = '', context?: RepositorySourceContext): Map<string, ClassEvidence[]> {
   const arrays = new Map(seed);
   for (const statement of sourceFile.statements) {
     if (ts.isVariableStatement(statement)) {
       for (const decl of statement.declarationList.declarations) {
         if (ts.isIdentifier(decl.name) && decl.initializer && ts.isArrayLiteralExpression(decl.initializer)) {
-          arrays.set(decl.name.text, resolveArrayLiteral(decl.initializer, arrays, imports, repoPath, fromFile, new Set()));
+          arrays.set(decl.name.text, resolveArrayLiteral(
+            decl.initializer, arrays, imports, repoPath, fromFile, new Set(), context,
+          ));
         }
       }
     }
   }
   return arrays;
 }
-function resolveArrayExpression(expr: ts.Expression, arrays: Map<string, ClassEvidence[]>, imports: Map<string, ImportEvidence>, repoPath: string, fromFile: string, seen: Set<string>): ClassEvidence[] {
-  if (ts.isArrayLiteralExpression(expr)) return resolveArrayLiteral(expr, arrays, imports, repoPath, fromFile, seen);
+function resolveArrayExpression(expr: ts.Expression, arrays: Map<string, ClassEvidence[]>, imports: Map<string, ImportEvidence>, repoPath: string, fromFile: string, seen: Set<string>, context?: RepositorySourceContext): ClassEvidence[] {
+  if (ts.isArrayLiteralExpression(expr)) return resolveArrayLiteral(expr, arrays, imports, repoPath, fromFile, seen, context);
   if (ts.isIdentifier(expr)) {
     const local = arrays.get(expr.text);
     if (local) return local;
     const evidence = imports.get(expr.text);
-    if (evidence && isRelative(evidence.source)) return resolveImportedArray(repoPath, fromFile, evidence, seen);
+    if (evidence && isRelative(evidence.source)) return resolveImportedArray(repoPath, fromFile, evidence, seen, context);
     if (evidence) return [{ className: evidence.importedName === 'default' ? expr.text : evidence.importedName, importSource: `${evidence.source}#${evidence.importedName}` }];
   }
   return [];
 }
-function resolveArrayLiteral(array: ts.ArrayLiteralExpression, arrays: Map<string, ClassEvidence[]>, imports: Map<string, ImportEvidence>, repoPath: string, fromFile: string, seen: Set<string>): ClassEvidence[] {
+function resolveArrayLiteral(array: ts.ArrayLiteralExpression, arrays: Map<string, ClassEvidence[]>, imports: Map<string, ImportEvidence>, repoPath: string, fromFile: string, seen: Set<string>, context?: RepositorySourceContext): ClassEvidence[] {
   const out: ClassEvidence[] = [];
   for (const element of array.elements) {
-    if (ts.isSpreadElement(element)) out.push(...resolveArrayExpression(element.expression, arrays, imports, repoPath, fromFile, seen));
+    if (ts.isSpreadElement(element)) out.push(...resolveArrayExpression(element.expression, arrays, imports, repoPath, fromFile, seen, context));
     else if (ts.isIdentifier(element)) out.push({ className: element.text, importSource: importSourceFor(element.text, imports) });
   }
   return out;
 }
-function resolveImportedArray(repoPath: string, fromFile: string, evidence: ImportEvidence, seen: Set<string>): ClassEvidence[] {
+function resolveImportedArray(repoPath: string, fromFile: string, evidence: ImportEvidence, seen: Set<string>, context?: RepositorySourceContext): ClassEvidence[] {
   const moduleFile = resolveRelativeModule(repoPath, fromFile, evidence.source);
   if (!moduleFile) return [];
   const key = `${moduleFile}:${evidence.importedName}`;
   if (seen.has(key) || seen.size > MAX_EXPORT_DEPTH) return [];
   seen.add(key);
-  const exports = readExports(repoPath, moduleFile, seen);
+  const exports = readExports(repoPath, moduleFile, seen, context);
   if (evidence.importedName === 'default') return exports.defaultArray ?? [];
   return exports.arrays.get(evidence.importedName) ?? exports.arrays.get(exports.aliases.get(evidence.importedName) ?? evidence.importedName) ?? [];
 }
@@ -150,13 +162,16 @@ function resolveRelativeModule(repoPath: string, fromFile: string, specifier: st
   }
   return undefined;
 }
-function readExports(repoPath: string, filePath: string, seen: Set<string>): FileExports {
+function readExports(repoPath: string, filePath: string, seen: Set<string>, context?: RepositorySourceContext): FileExports {
   const absolute = path.join(repoPath, filePath);
   let text: string;
-  try { text = fsSync.readFileSync(absolute, 'utf8'); } catch { return { arrays: new Map(), aliases: new Map() }; }
-  const sourceFile = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const snapshot = context?.get(filePath);
+  try { text = snapshot?.text ?? fsSync.readFileSync(absolute, 'utf8'); } catch { return { arrays: new Map(), aliases: new Map() }; }
+  const sourceFile = snapshot?.sourceFile() ?? ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
   const imports = collectImports(sourceFile);
-  const arrays = collectLocalArrays(sourceFile, imports, new Map(), repoPath, filePath);
+  const arrays = collectLocalArrays(
+    sourceFile, imports, new Map(), repoPath, filePath, context,
+  );
   const aliases = new Map<string, string>();
   let defaultArray: ClassEvidence[] | undefined;
   for (const statement of sourceFile.statements) {
@@ -167,7 +182,9 @@ function readExports(repoPath: string, filePath: string, seen: Set<string>): Fil
         const local = element.propertyName?.text ?? element.name.text;
         aliases.set(element.name.text, local);
         if (module && isRelative(module)) {
-          const imported = resolveImportedArray(repoPath, filePath, { source: module, importedName: local }, seen);
+          const imported = resolveImportedArray(
+            repoPath, filePath, { source: module, importedName: local }, seen, context,
+          );
           if (imported.length > 0) arrays.set(element.name.text, imported);
         }
       }

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

@@ -4,6 +4,7 @@ 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 type { RepositorySourceContext } from './ts-project.js';
 import {
   analyzeOperationPath,
   operationPathExpression,
@@ -25,6 +26,7 @@ export async function parseImportedWrapperCalls(
   filePath: string,
   source: ts.SourceFile,
   serviceBindings: Set<string>,
+  context?: RepositorySourceContext,
 ): Promise<OutboundCallFact[]> {
   const imports = await importsFor(repoPath, filePath, source);
   const importedByLocal = new Map(imports.filter((item) => item.sourceFile).map((item) => [item.localName, item]));
@@ -35,7 +37,7 @@ export async function parseImportedWrapperCalls(
     if (!ts.isIdentifier(call.expression)) continue;
     const imported = importedByLocal.get(call.expression.text);
     if (!imported?.sourceFile) continue;
-    const spec = await loadWrapperSpec(repoPath, imported, cache, 0);
+    const spec = await loadWrapperSpec(repoPath, imported, cache, 0, context);
     const fact = spec ? wrapperCallFact(source, filePath, call, spec, serviceBindings) : undefined;
     if (fact) out.push(fact);
   }
@@ -57,12 +59,15 @@ async function loadWrapperSpec(
   imported: ImportBinding,
   cache: Map<string, Promise<WrapperSpec | undefined>>,
   depth: number,
+  context?: RepositorySourceContext,
 ): Promise<WrapperSpec | undefined> {
   if (!imported.sourceFile || depth > 5) return undefined;
   const key = `${imported.sourceFile}#${imported.exportedName}`;
   const existing = cache.get(key);
   if (existing) return existing;
-  const pending = inspectWrapper(repoPath, imported.sourceFile, imported.exportedName, cache, depth);
+  const pending = inspectWrapper(
+    repoPath, imported.sourceFile, imported.exportedName, cache, depth, context,
+  );
   cache.set(key, pending);
   return pending;
 }
@@ -73,14 +78,19 @@ async function inspectWrapper(
   exportedName: string,
   cache: Map<string, Promise<WrapperSpec | undefined>>,
   depth: number,
+  context?: RepositorySourceContext,
 ): Promise<WrapperSpec | undefined> {
-  const source = await readSource(path.join(repoPath, sourceFile));
+  const source = await readSource(
+    path.join(repoPath, sourceFile), context, sourceFile,
+  );
   if (!source) return undefined;
   const named = findFunction(source, exportedName);
   if (!named) return undefined;
   const direct = directSendSpec(source, sourceFile, named.name, named.fn);
   if (direct) return direct;
-  return nestedSendSpec(repoPath, sourceFile, source, named.name, named.fn, cache, depth);
+  return nestedSendSpec(
+    repoPath, sourceFile, source, named.name, named.fn, cache, depth, context,
+  );
 }
 
 function directSendSpec(source: ts.SourceFile, sourceFile: string, name: string, fn: ts.FunctionLikeDeclaration): WrapperSpec | undefined {
@@ -113,6 +123,7 @@ async function nestedSendSpec(
   fn: ts.FunctionLikeDeclaration,
   cache: Map<string, Promise<WrapperSpec | undefined>>,
   depth: number,
+  context?: RepositorySourceContext,
 ): Promise<WrapperSpec | undefined> {
   const imports = await importsFor(repoPath, sourceFile, source);
   const byLocal = new Map(imports.filter((item) => item.sourceFile).map((item) => [item.localName, item]));
@@ -123,7 +134,9 @@ async function nestedSendSpec(
   if (calls.length !== 1) return undefined;
   const call = calls[0];
   const imported = call && ts.isIdentifier(call.expression) ? byLocal.get(call.expression.text) : undefined;
-  const nested = imported ? await loadWrapperSpec(repoPath, imported, cache, depth + 1) : undefined;
+  const nested = imported
+    ? await loadWrapperSpec(repoPath, imported, cache, depth + 1, context)
+    : undefined;
   if (!call || !nested) return undefined;
   const params = parameterNames(fn);
   const clientIndex = mappedParameterIndex(call.arguments[nested.clientIndex], params);

package/src/parsers/outbound-call-parser.ts

@@ -8,6 +8,7 @@ import { summarizeExpression } from '../utils/redaction.js';
 import { classifyODataPathIntent } from '../linker/odata-path-normalizer.js';
 import { parseServiceBindings } from './service-binding-parser.js';
 import { parseImportedWrapperCalls } from './imported-wrapper-parser.js';
+import type { RepositorySourceContext } from './ts-project.js';
 import {
   analyzeOperationPath,
   operationPathExpression,
@@ -510,15 +511,31 @@ export function containsSupportedOutboundCall(node: ts.Node): boolean {
 export async function parseOutboundCalls(
   repoPath: string,
   filePath: string,
+  context?: RepositorySourceContext,
 ): Promise<OutboundCallFact[]> {
-  const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');
-  const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
-  const bindingNames = new Set((await parseServiceBindings(repoPath, filePath)).map((binding) => binding.variableName));
-  const importedWrappers = await parseImportedWrapperCalls(repoPath, filePath, source, bindingNames);
-  return [...classifyOutboundCallsInSource(source, filePath).map((call) => call.fact), ...importedWrappers, ...parseLocalServiceCalls(text, filePath)];
-}
-function parseLocalServiceCalls(text: string, filePath: string): OutboundCallFact[] {
-  const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
+  const snapshot = context?.get(filePath);
+  const text = snapshot?.text
+    ?? await fs.readFile(path.join(repoPath, filePath), 'utf8');
+  const source = snapshot?.sourceFile() ?? ts.createSourceFile(
+    filePath, text, ts.ScriptTarget.Latest, true,
+    filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS,
+  );
+  const bindingNames = new Set((await parseServiceBindings(
+    repoPath, filePath, context,
+  )).map((binding) => binding.variableName));
+  const importedWrappers = await parseImportedWrapperCalls(
+    repoPath, filePath, source, bindingNames, context,
+  );
+  return [...classifyOutboundCallsInSource(source, filePath).map((call) => call.fact), ...importedWrappers, ...parseLocalServiceCalls(text, filePath, source)];
+}
+function parseLocalServiceCalls(
+  text: string,
+  filePath: string,
+  source = ts.createSourceFile(
+    filePath, text, ts.ScriptTarget.Latest, true,
+    filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS,
+  ),
+): OutboundCallFact[] {
   const aliases = new Map<string, { service: string; lookup: string; chain: string[] }>();
   const calls: OutboundCallFact[] = [];
   const visit = (node: ts.Node): void => {

package/src/parsers/package-json-parser.ts

@@ -1,6 +1,17 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { CdsRequire, PackageFacts } from '../types.js';
+interface ParsePackageJsonOptions {
+  strict?: boolean;
+  allowMissing?: boolean;
+}
+export interface PackageJsonSnapshot {
+  facts: PackageFacts;
+  rawText: string;
+}
+function emptyPackageFacts(): PackageFacts {
+  return { dependencies: {}, cdsRequires: [], scripts: {} };
+}
 function recordOfString(value: unknown): Record<string, string> {
   if (!value || typeof value !== 'object') return {};
   return Object.fromEntries(
@@ -41,23 +52,37 @@ function readRequires(cds: unknown): CdsRequire[] {
   });
 }
 export async function parsePackageJson(
-  repoPath: string
+  repoPath: string,
+  options: ParsePackageJsonOptions = {},
 ): Promise<PackageFacts> {
+  return (await loadPackageJsonSnapshot(repoPath, options)).facts;
+}
+export async function loadPackageJsonSnapshot(
+  repoPath: string,
+  options: ParsePackageJsonOptions = {},
+): Promise<PackageJsonSnapshot> {
   try {
     const raw = await fs.readFile(path.join(repoPath, 'package.json'), 'utf8');
     const json = JSON.parse(raw) as Record<string, unknown>;
     return {
-      packageName: typeof json.name === 'string' ? json.name : undefined,
-      packageVersion:
-        typeof json.version === 'string' ? json.version : undefined,
-      dependencies: {
-        ...recordOfString(json.dependencies),
-        ...recordOfString(json.devDependencies)
+      rawText: raw,
+      facts: {
+        packageName: typeof json.name === 'string' ? json.name : undefined,
+        packageVersion:
+          typeof json.version === 'string' ? json.version : undefined,
+        dependencies: {
+          ...recordOfString(json.dependencies),
+          ...recordOfString(json.devDependencies),
+        },
+        cdsRequires: readRequires(json.cds),
+        scripts: recordOfString(json.scripts),
       },
-      cdsRequires: readRequires(json.cds),
-      scripts: recordOfString(json.scripts)
     };
-  } catch {
-    return { dependencies: {}, cdsRequires: [], scripts: {} };
+  } catch (error) {
+    const missing = typeof error === 'object' && error !== null
+      && 'code' in error && error.code === 'ENOENT';
+    if (!options.strict || (options.allowMissing && missing))
+      return { facts: emptyPackageFacts(), rawText: '' };
+    throw error;
   }
 }

package/src/parsers/service-binding-parser-helpers.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import ts from 'typescript';
 import { normalizePath } from '../utils/path-utils.js';
+import type { RepositorySourceContext } from './ts-project.js';
 
 export interface HelperBinding {
   exportedName: string;
@@ -123,7 +124,13 @@ export function findConnectInExpression(expr: ts.Expression): Omit<HelperBinding
   return found;
 }
 
-export async function readSource(abs: string): Promise<ts.SourceFile | undefined> {
+export async function readSource(
+  abs: string,
+  context?: RepositorySourceContext,
+  filePath?: string,
+): Promise<ts.SourceFile | undefined> {
+  const snapshot = filePath ? context?.get(filePath) : undefined;
+  if (snapshot) return snapshot.sourceFile();
   try {
     const text = await fs.readFile(abs, 'utf8');
     return ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);

package/src/parsers/service-binding-parser.ts

@@ -15,6 +15,7 @@ import {
   type HelperBinding,
   type ImportBinding,
 } from './service-binding-parser-helpers.js';
+import type { RepositorySourceContext } from './ts-project.js';
 
 function collectLocalBindingFacts(
   fn: ts.FunctionLikeDeclaration,
@@ -125,8 +126,9 @@ function exportedLocalNames(sf: ts.SourceFile): Map<string, string> {
 async function helperBindings(
   repoPath: string,
   filePath: string,
+  context?: RepositorySourceContext,
 ): Promise<HelperBinding[]> {
-  const sf = await readSource(path.join(repoPath, filePath));
+  const sf = await readSource(path.join(repoPath, filePath), context, filePath);
   if (!sf) return [];
   const sourceFileAst = sf;
   const out: HelperBinding[] = [];
@@ -195,8 +197,9 @@ async function helperBindings(
 export async function parseServiceBindings(
   repoPath: string,
   filePath: string,
+  context?: RepositorySourceContext,
 ): Promise<ServiceBindingFact[]> {
-  const sf = await readSource(path.join(repoPath, filePath));
+  const sf = await readSource(path.join(repoPath, filePath), context, filePath);
   if (!sf) return [];
   const sourceFileAst = sf;
   const out: ServiceBindingFact[] = [];
@@ -237,7 +240,7 @@ export async function parseServiceBindings(
     if (!helperCache.has(imp.sourceFile))
       helperCache.set(
         imp.sourceFile,
-        await helperBindings(repoPath, imp.sourceFile),
+        await helperBindings(repoPath, imp.sourceFile, context),
       );
     return (helperCache.get(imp.sourceFile) ?? [])
       .filter((h) => h.exportedName === imp.exportedName)

package/src/parsers/symbol-parser.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import ts from 'typescript';
 import type { ExecutableSymbolFact, SymbolCallFact } from '../types.js';
 import { containsSupportedOutboundCall } from './outbound-call-parser.js';
+import type { RepositorySourceContext } from './ts-project.js';
 import { normalizePath } from '../utils/path-utils.js';
 
 function lineOf(source: ts.SourceFile, pos: number): number {
@@ -167,9 +168,18 @@ function parameterBindings(params: ts.NodeArray<ts.ParameterDeclaration>): Param
     return [];
   });
 }
-export async function parseExecutableSymbols(repoPath: string, filePath: string): Promise<{ symbols: ExecutableSymbolFact[]; calls: SymbolCallFact[] }> {
-  const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');
-  const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
+export async function parseExecutableSymbols(
+  repoPath: string,
+  filePath: string,
+  context?: RepositorySourceContext,
+): Promise<{ symbols: ExecutableSymbolFact[]; calls: SymbolCallFact[] }> {
+  const snapshot = context?.get(filePath);
+  const text = snapshot?.text
+    ?? await fs.readFile(path.join(repoPath, filePath), 'utf8');
+  const source = snapshot?.sourceFile() ?? ts.createSourceFile(
+    filePath, text, ts.ScriptTarget.Latest, true,
+    filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS,
+  );
   const sourceFile = normalizePath(filePath);
   const symbols: ExecutableSymbolFact[] = [];
   const calls: SymbolCallFact[] = [];

package/src/parsers/ts-project.ts

@@ -1,4 +1,58 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import ts from 'typescript';
+import { normalizePath } from '../utils/path-utils.js';
+
+export interface SourceContextInstrumentation {
+  onSourceRead?: (
+    repoPath: string,
+    filePath: string,
+  ) => void | Promise<void>;
+  onAstCreated?: (repoPath: string, filePath: string) => void;
+}
+
+export interface SourceFileSnapshot {
+  repoPath: string;
+  filePath: string;
+  text: string;
+  sizeBytes: number;
+  sourceFile: () => ts.SourceFile;
+}
+
+export interface RepositorySourceContext {
+  get: (filePath: string) => SourceFileSnapshot | undefined;
+  entries: () => SourceFileSnapshot[];
+}
+
+export async function loadRepositorySourceContext(
+  repoPath: string,
+  filePaths: string[],
+  instrumentation?: SourceContextInstrumentation,
+): Promise<RepositorySourceContext> {
+  const snapshots = new Map<string, SourceFileSnapshot>();
+  for (const inputPath of filePaths) {
+    const filePath = normalizePath(inputPath);
+    await instrumentation?.onSourceRead?.(repoPath, filePath);
+    const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');
+    let ast: ts.SourceFile | undefined;
+    snapshots.set(filePath, {
+      repoPath,
+      filePath,
+      text,
+      sizeBytes: Buffer.byteLength(text),
+      sourceFile: () => {
+        if (ast) return ast;
+        instrumentation?.onAstCreated?.(repoPath, filePath);
+        ast = createSourceFile(filePath, text);
+        return ast;
+      },
+    });
+  }
+  return {
+    get: (filePath) => snapshots.get(normalizePath(filePath)),
+    entries: () => [...snapshots.values()],
+  };
+}
 export function createSourceFile(
   filePath: string,
   text: string

package/src/trace/000-dynamic-target-types.ts

@@ -0,0 +1,84 @@
+import type { DynamicMode } from '../types.js';
+
+export interface DynamicTemplates {
+  servicePath?: string;
+  operationPath?: string;
+  alias?: string;
+  destination?: string;
+}
+
+export interface DynamicVariableProvenance extends Record<string, unknown> {
+  sourceKind: string;
+  value: string;
+  rule: string;
+  template?: string;
+  matchedName?: string;
+  normalizedForm?: string;
+  sourceRepo?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+}
+
+export interface DynamicVariableConflict {
+  key: string;
+  values: string[];
+  reason: string;
+  sources: string[];
+}
+
+export interface DynamicTargetCandidate {
+  candidateOperationId: number;
+  repoId?: number;
+  repoName: string;
+  packageName?: string;
+  serviceName: string;
+  qualifiedName: string;
+  servicePath: string;
+  operationPath: string;
+  operationName: string;
+  sourceFile: string;
+  sourceLine: number;
+  originalTemplates: DynamicTemplates;
+  effectiveValues: DynamicTemplates;
+  requiredVariables: string[];
+  requiredVariableSources: Record<string, string[]>;
+  suppliedVariables: Record<string, string>;
+  completeVariables: Record<string, string>;
+  derivedVariables: Record<string, string>;
+  derivedVariableSources: Record<string, DynamicVariableProvenance>;
+  derivationProvenance: Record<string, DynamicVariableProvenance[]>;
+  missingVariables: string[];
+  conflicts: DynamicVariableConflict[];
+  score: number;
+  explicitSignalStrength: number;
+  reasons: string[];
+  rejectedReasons: string[];
+  inferenceBlockReasons: string[];
+  viable: boolean;
+  rejected: boolean;
+  selected: boolean;
+  exploratory: boolean;
+  cli?: string;
+}
+
+export interface DynamicTargetAnalysis {
+  mode: DynamicMode;
+  maxCandidates: number;
+  candidateCount: number;
+  viableCandidateCount: number;
+  rejectedCandidateCount: number;
+  shownCandidateCount: number;
+  omittedCandidateCount: number;
+  shownRejectedCandidateCount: number;
+  omittedRejectedCandidateCount: number;
+  missingVariables: string[];
+  requiredVariables: string[];
+  suppliedVariables: Record<string, string>;
+  appliedSuppliedVariables: Record<string, string>;
+  substitutedSignals: DynamicTemplates;
+  candidates: DynamicTargetCandidate[];
+  shownCandidates: DynamicTargetCandidate[];
+  rejectedCandidates: DynamicTargetCandidate[];
+  suggestedVarSets: Array<{ variables: Record<string, string>; cli: string }>;
+  inference: Record<string, unknown>;
+}