@saptools/service-flow 0.1.67 → 0.1.68

package/src/linker/003-package-import-symbol-resolver.ts

@@ -1,4 +1,16 @@
 import type { Db } from '../db/connection.js';
+import type {
+  PackagePublicScope,
+  PackagePublicSurfaceFact,
+  PublicSurfaceTarget,
+} from '../parsers/003-package-public-surface.js';
+import type {
+  SymbolImportReference,
+} from '../parsers/002-symbol-import-bindings.js';
+import {
+  parsePackageImportReference,
+  parsePackagePublicSurfaceFact,
+} from '../parsers/012-package-fact-contract.js';
 
 export interface PackageSymbolLinkSummary {
   resolved: number;
@@ -6,189 +18,409 @@ export interface PackageSymbolLinkSummary {
   unresolved: number;
 }
 
-interface RepoExports {
-  publicName: Map<string, number[]>;
-  qualified: Map<string, number[]>;
-  fileById: Map<number, string>;
-}
-
 interface PackageCallRow {
   id: number;
   callerRepoId: number;
-  calleeExpression: string;
-  importSource: string;
+  binding: SymbolImportReference;
   evidence: Record<string, unknown>;
 }
 
-interface PackageCallResolution {
+interface PackageRepository {
+  id: number;
+  surface: PackagePublicSurfaceFact;
+}
+
+export interface PackageCallResolution {
   id: number | null;
   status: 'resolved' | 'ambiguous' | 'unresolved';
   reason: string | null;
-  strategy: 'package_import_workspace_resolved' | 'package_import_ambiguous' | 'package_import_unresolved';
+  strategy: string;
   candidateCount: number;
+  eligibleCandidateCount: number;
+  selectedCandidateCount: 0 | 1;
+  candidateSetComplete: boolean;
   resolvedModulePath?: string;
+  targetRepoId?: number;
+  repositoryCandidateIds: number[];
+  publicSurface?: {
+    total: number;
+    shown: number;
+    omitted: number;
+  };
 }
 
-const unresolvedRepositoryReason = 'Package import target resolution requires a post-publication workspace pass';
-const unresolvedSymbolReason = 'Sibling package indexed but no matching exported symbol; the target may be a re-export, barrel, type-only export, or unindexed Receiver.member';
-const ambiguousSymbolReason = 'Multiple exported sibling-package symbol targets matched exactly';
-const stripExt = (value: string): string => value.replace(/\.(ts|tsx|js|jsx|cds)$/, '');
+export interface PackageResolutionInput {
+  callId: number;
+  binding: SymbolImportReference;
+}
 
-function push(map: Map<string, number[]>, key: string, id: number): void {
-  const existing = map.get(key);
-  if (existing) existing.push(id);
-  else map.set(key, [id]);
+export interface PackageResolutionResult extends PackageCallResolution {
+  callId: number;
 }
 
-function nullableString(value: unknown): string | undefined {
-  return typeof value === 'string' ? value : undefined;
+const REPOSITORY_REFERENCE_CAP = 5;
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
 }
 
-function evidenceObject(value: unknown): Record<string, unknown> {
-  if (typeof value !== 'string' || value.length === 0) return {};
+function parseRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'string') return undefined;
   try {
-    const parsed = JSON.parse(value) as unknown;
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-      ? parsed as Record<string, unknown>
-      : {};
+    return record(JSON.parse(value) as unknown);
   } catch {
-    return {};
+    return undefined;
   }
 }
 
-function repoByPackageName(db: Db, workspaceId: number): Map<string, number | null> {
-  const result = new Map<string, number | null>();
-  const rows = db.prepare(`SELECT id,package_name packageName FROM repositories
-    WHERE workspace_id=? AND package_name IS NOT NULL ORDER BY package_name,id`).all(workspaceId);
+function importBinding(
+  evidence: Record<string, unknown>,
+): SymbolImportReference | undefined {
+  return parsePackageImportReference(evidence.importBinding);
+}
+
+function packageCallRows(db: Db, workspaceId: number): PackageCallRow[] {
+  const rows = db.prepare(`SELECT sc.id,sc.repo_id callerRepoId,
+    sc.evidence_json evidenceJson FROM symbol_calls sc
+    JOIN repositories r ON r.id=sc.repo_id
+    WHERE r.workspace_id=?
+      AND json_extract(sc.evidence_json,'$.importBinding.moduleKind')='package'
+    ORDER BY sc.id`).all(workspaceId);
+  return rows.flatMap((row) => {
+    const evidence = parseRecord(row.evidenceJson);
+    const binding = evidence ? importBinding(evidence) : undefined;
+    return typeof row.id === 'number' && typeof row.callerRepoId === 'number'
+      && evidence && binding
+      ? [{ id: row.id, callerRepoId: row.callerRepoId, evidence, binding }]
+      : [];
+  });
+}
+
+function parseSurface(
+  value: unknown,
+  packageName: string,
+): PackagePublicSurfaceFact | undefined {
+  if (typeof value !== 'string') return undefined;
+  try {
+    return parsePackagePublicSurfaceFact(
+      JSON.parse(value) as unknown,
+      packageName,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function repositoriesByPackage(
+  db: Db,
+  workspaceId: number,
+): Map<string, PackageRepository[]> {
+  const rows = db.prepare(`SELECT id,package_name packageName,
+    package_public_surface_json surfaceJson FROM repositories
+    WHERE workspace_id=? AND package_name IS NOT NULL
+    ORDER BY package_name COLLATE BINARY,id`).all(workspaceId);
+  const result = new Map<string, PackageRepository[]>();
   for (const row of rows) {
-    const packageName = nullableString(row.packageName);
-    if (!packageName || typeof row.id !== 'number') continue;
-    result.set(packageName, result.has(packageName) ? null : row.id);
+    if (typeof row.id !== 'number' || typeof row.packageName !== 'string')
+      continue;
+    const surface = parseSurface(row.surfaceJson, row.packageName);
+    if (!surface) continue;
+    const repositories = result.get(row.packageName) ?? [];
+    repositories.push({ id: row.id, surface });
+    result.set(row.packageName, repositories);
   }
   return result;
 }
 
-function packagePrefix(importSource: string): string {
-  const parts = importSource.split('/');
-  if (importSource.startsWith('@')) return parts.length >= 2 ? parts.slice(0, 2).join('/') : importSource;
-  return parts[0] ?? importSource;
+function unresolved(
+  reason: string,
+  options: Partial<PackageCallResolution> = {},
+): PackageCallResolution {
+  return {
+    id: null,
+    status: 'unresolved',
+    reason,
+    strategy: 'package_public_surface_unresolved',
+    candidateCount: 0,
+    eligibleCandidateCount: 0,
+    selectedCandidateCount: 0,
+    candidateSetComplete: true,
+    repositoryCandidateIds: [],
+    ...options,
+  };
 }
 
-function packageRepoId(repos: Map<string, number | null>, importSource: string): number | null {
-  const packageName = repos.has(importSource) ? importSource : packagePrefix(importSource);
-  return repos.get(packageName) ?? null;
+function repositoryScopeResolution(
+  call: PackageCallRow,
+  repositories: Map<string, PackageRepository[]>,
+): PackageRepository | PackageCallResolution {
+  const matches = repositories.get(call.binding.requestedPackageName ?? '')
+    ?? [];
+  if (matches.length === 1 && matches[0]) return matches[0];
+  const ids = matches.map((item) => item.id);
+  if (matches.length > 1) return unresolved(
+    'package_repository_scope_ambiguous',
+    {
+      candidateSetComplete: false,
+      candidateCount: matches.length,
+      repositoryCandidateIds: ids,
+    },
+  );
+  return unresolved('package_repository_not_indexed');
 }
 
-function emptyRepoExports(): RepoExports {
-  return { publicName: new Map(), qualified: new Map(), fileById: new Map() };
+function publicScope(
+  surface: PackagePublicSurfaceFact,
+  binding: SymbolImportReference,
+): PackagePublicScope | PackageCallResolution {
+  const surfaceCounts = {
+    total: surface.total,
+    shown: surface.shown,
+    omitted: surface.omitted,
+  };
+  if (surface.status !== 'complete') return unresolved(
+    surface.status === 'unsupported'
+      ? 'package_public_surface_unsupported'
+      : 'public_surface_evidence_incomplete',
+    { candidateSetComplete: false, publicSurface: surfaceCounts },
+  );
+  if (binding.typeOnly) return unresolved(
+    'package_binding_type_only',
+    { publicSurface: surfaceCounts },
+  );
+  const matches = surface.scopes.filter((scope) =>
+    scope.entry === binding.requestedModuleSubpath
+    && scope.publicName === binding.requestedPublicName);
+  if (matches.length === 1 && matches[0]) return matches[0];
+  if (matches.length > 1) return unresolved(
+    'package_public_scope_duplicate',
+    {
+      candidateSetComplete: false,
+      candidateCount: matches.reduce(
+        (sum, scope) => sum + scope.candidateCount, 0,
+      ),
+      publicSurface: surfaceCounts,
+    },
+  );
+  return unresolved(
+    surface.omitted > 0
+      ? 'public_surface_evidence_incomplete'
+      : 'package_public_name_not_exposed',
+    {
+      candidateSetComplete: surface.omitted === 0,
+      publicSurface: surfaceCounts,
+    },
+  );
 }
 
-function exportsByRepo(db: Db, workspaceId: number): Map<number, RepoExports> {
-  const result = new Map<number, RepoExports>();
-  const rows = db.prepare(`SELECT s.id,s.repo_id repoId,s.name,s.exported_name exportedName,
-      s.qualified_name qualifiedName,s.source_file sourceFile
-    FROM symbols s JOIN repositories r ON r.id=s.repo_id
-    WHERE r.workspace_id=? AND s.exported=1 ORDER BY s.repo_id,s.id`).all(workspaceId);
-  for (const row of rows) addExportRow(result, row);
-  return result;
+function symbolEvidenceMatches(
+  evidenceJson: unknown,
+  target: PublicSurfaceTarget,
+  scope: PackagePublicScope,
+): boolean {
+  const evidence = parseRecord(evidenceJson);
+  if (!evidence) return false;
+  const surface = record(evidence.packagePublicSurface);
+  if (!surface) return false;
+  const body = record(surface.bodyEligibility);
+  const exposures = surface.exposures;
+  if (!body || !Array.isArray(exposures)) return false;
+  const exactProof = [
+    body.eligible === true,
+    body.reason === target.bodyEligibility.reason,
+    surface.recordCap === 256,
+    surface.exposureTotal === exposures.length,
+    surface.shownExposureCount === exposures.length,
+    surface.omittedExposureCount === 0,
+  ];
+  if (exactProof.includes(false)) return false;
+  return exposures.some((item) => {
+    const exposure = record(item);
+    return exposure?.entry === scope.entry
+      && exposure.modulePath === scope.modulePath
+      && exposure.publicName === scope.publicName;
+  });
 }
 
-function addExportRow(result: Map<number, RepoExports>, row: Record<string, unknown>): void {
-  if (typeof row.id !== 'number' || typeof row.repoId !== 'number') return;
-  const exports = result.get(row.repoId) ?? emptyRepoExports();
-  result.set(row.repoId, exports);
-  const publicName = nullableString(row.exportedName) ?? nullableString(row.name);
-  const qualifiedName = nullableString(row.qualifiedName);
-  const sourceFile = nullableString(row.sourceFile);
-  if (publicName) push(exports.publicName, publicName, row.id);
-  if (qualifiedName) push(exports.qualified, qualifiedName, row.id);
-  if (sourceFile) exports.fileById.set(row.id, stripExt(sourceFile));
+function targetSymbolIds(
+  db: Db,
+  repositoryId: number,
+  scope: PackagePublicScope,
+): number[] {
+  return scope.targets.flatMap((target) => {
+    if (!target.bodyEligibility.eligible) return [];
+    const rows = db.prepare(`SELECT id,evidence_json evidenceJson FROM symbols
+      WHERE repo_id=? AND source_file=? AND kind=? AND qualified_name=?
+        AND start_offset=? AND end_offset=?
+      ORDER BY id`).all(
+      repositoryId,
+      target.sourceFile,
+      target.kind,
+      target.qualifiedName,
+      target.startOffset,
+      target.endOffset,
+    );
+    return rows.flatMap((row) =>
+      typeof row.id === 'number'
+        && symbolEvidenceMatches(row.evidenceJson, target, scope)
+        ? [row.id] : []);
+  });
 }
 
-function packageCallRows(db: Db, workspaceId: number): PackageCallRow[] {
-  const rows = db.prepare(`SELECT sc.id,sc.repo_id callerRepoId,
-      sc.callee_expression calleeExpression,sc.import_source importSource,
-      sc.evidence_json evidenceJson
-    FROM symbol_calls sc JOIN repositories r ON r.id=sc.repo_id
-    WHERE r.workspace_id=? AND sc.import_source IS NOT NULL
-      AND sc.import_source NOT LIKE './%' AND sc.import_source NOT LIKE '../%'
-      AND json_extract(sc.evidence_json,'$.relation')='package_import'
-      AND json_extract(sc.evidence_json,'$.candidateStrategy') IN
-        ('package_import_unresolved','package_import_workspace_resolved','package_import_ambiguous')
-    ORDER BY sc.id`).all(workspaceId);
-  return rows.flatMap((row) => packageCallRow(row));
-}
-
-function packageCallRow(row: Record<string, unknown>): PackageCallRow[] {
-  const calleeExpression = nullableString(row.calleeExpression);
-  const importSource = nullableString(row.importSource);
-  if (typeof row.id !== 'number' || typeof row.callerRepoId !== 'number'
-    || !calleeExpression || !importSource) return [];
-  return [{
-    id: row.id,
-    callerRepoId: row.callerRepoId,
-    calleeExpression,
-    importSource,
-    evidence: evidenceObject(row.evidenceJson),
-  }];
-}
-
-function candidatesForCall(call: PackageCallRow, exports: RepoExports | undefined): number[] {
-  if (!exports) return [];
-  const dotCount = [...call.calleeExpression].filter((character) => character === '.').length;
-  if (dotCount === 0) {
-    const targetName = nullableString(call.evidence.targetName);
-    return targetName ? exports.publicName.get(targetName) ?? [] : [];
-  }
-  return dotCount === 1 ? exports.qualified.get(call.calleeExpression) ?? [] : [];
+function scopeResolution(
+  db: Db,
+  repository: PackageRepository,
+  scope: PackagePublicScope,
+): PackageCallResolution {
+  const ids = [...new Set(targetSymbolIds(db, repository.id, scope))];
+  if (ids.length !== scope.eligibleCandidateCount) return unresolved(
+    'public_surface_evidence_incomplete',
+    {
+      candidateCount: scope.candidateCount,
+      eligibleCandidateCount: ids.length,
+      candidateSetComplete: false,
+      resolvedModulePath: scope.modulePath,
+      targetRepoId: repository.id,
+      repositoryCandidateIds: [repository.id],
+    },
+  );
+  const base = {
+    candidateCount: scope.candidateCount,
+    eligibleCandidateCount: scope.eligibleCandidateCount,
+    selectedCandidateCount: 0 as const,
+    candidateSetComplete: scope.candidateSetComplete,
+    resolvedModulePath: scope.modulePath,
+    targetRepoId: repository.id,
+    repositoryCandidateIds: [repository.id],
+  };
+  if (ids.length === 1 && ids[0] !== undefined) return {
+    ...base,
+    id: ids[0],
+    status: 'resolved',
+    reason: null,
+    strategy: 'package_public_surface_exact',
+    selectedCandidateCount: 1,
+  };
+  if (ids.length > 1) return {
+    ...base,
+    id: null,
+    status: 'ambiguous',
+    reason: 'package_public_target_ambiguous',
+    strategy: 'package_public_surface_ambiguous',
+  };
+  return unresolved(
+    scope.candidateCount > 0 && scope.eligibleCandidateCount === 0
+      ? 'public_symbol_has_no_executable_body'
+      : 'package_public_name_not_exposed',
+    base,
+  );
 }
 
 function resolvePackageCall(
+  db: Db,
   call: PackageCallRow,
-  repos: Map<string, number | null>,
-  exports: Map<number, RepoExports>,
+  repositories: Map<string, PackageRepository[]>,
 ): PackageCallResolution {
-  const targetRepoId = packageRepoId(repos, call.importSource);
-  if (targetRepoId === null || targetRepoId === call.callerRepoId) return unresolvedResolution(unresolvedRepositoryReason);
-  const repoExports = exports.get(targetRepoId);
-  const candidates = candidatesForCall(call, repoExports);
-  const [id] = candidates;
-  if (candidates.length === 1 && id !== undefined) {
-    return {
-      id, status: 'resolved', reason: null, strategy: 'package_import_workspace_resolved',
-      candidateCount: 1, resolvedModulePath: repoExports?.fileById.get(id),
-    };
-  }
-  if (candidates.length > 1) {
-    return { id: null, status: 'ambiguous', reason: ambiguousSymbolReason, strategy: 'package_import_ambiguous', candidateCount: candidates.length };
-  }
-  return unresolvedResolution(unresolvedSymbolReason);
+  const repository = repositoryScopeResolution(call, repositories);
+  if ('status' in repository) return repository;
+  const scope = publicScope(repository.surface, call.binding);
+  if ('status' in scope) return {
+    ...scope,
+    targetRepoId: repository.id,
+    repositoryCandidateIds: [repository.id],
+  };
+  return scopeResolution(db, repository, scope);
+}
+
+export function expectedPackageImportResolutions(
+  db: Db,
+  workspaceId: number,
+  inputs: readonly PackageResolutionInput[],
+): PackageResolutionResult[] {
+  const repositories = repositoriesByPackage(db, workspaceId);
+  return inputs.map((input) => ({
+    callId: input.callId,
+    ...resolvePackageCall(
+      db,
+      {
+        id: input.callId,
+        callerRepoId: 0,
+        binding: input.binding,
+        evidence: {},
+      },
+      repositories,
+    ),
+  }));
 }
 
-function unresolvedResolution(reason: string): PackageCallResolution {
-  return { id: null, status: 'unresolved', reason, strategy: 'package_import_unresolved', candidateCount: 0 };
+const resolverEvidenceKeys = new Set([
+  'candidateStrategy', 'candidateCount', 'eligibleCandidateCount',
+  'selectedCandidateCount', 'candidateSetComplete', 'resolvedModulePath',
+  'resolvedTargetRepositoryId', 'unresolvedReason',
+  'targetRepositoryCandidateCount', 'targetRepositoryCandidates',
+  'shownTargetRepositoryCandidateCount',
+  'omittedTargetRepositoryCandidateCount', 'publicSurface',
+]);
+
+function parserEvidence(
+  evidence: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(evidence).filter(
+    ([key]) => !resolverEvidenceKeys.has(key),
+  ));
 }
 
-function resolutionEvidence(call: PackageCallRow, resolution: PackageCallResolution): string {
-  const evidence: Record<string, unknown> = {
-    ...call.evidence,
+function resolutionEvidence(
+  call: PackageCallRow,
+  resolution: PackageCallResolution,
+): string {
+  const ids = resolution.repositoryCandidateIds
+    .slice(0, REPOSITORY_REFERENCE_CAP);
+  return JSON.stringify({
+    ...parserEvidence(call.evidence),
     candidateStrategy: resolution.strategy,
     candidateCount: resolution.candidateCount,
-  };
-  if (resolution.resolvedModulePath) evidence.resolvedModulePath = resolution.resolvedModulePath;
-  else delete evidence.resolvedModulePath;
-  return JSON.stringify(evidence);
+    eligibleCandidateCount: resolution.eligibleCandidateCount,
+    selectedCandidateCount: resolution.selectedCandidateCount,
+    candidateSetComplete: resolution.candidateSetComplete,
+    unresolvedReason: resolution.reason,
+    ...(resolution.resolvedModulePath
+      ? { resolvedModulePath: resolution.resolvedModulePath } : {}),
+    ...(resolution.targetRepoId
+      ? { resolvedTargetRepositoryId: resolution.targetRepoId } : {}),
+    targetRepositoryCandidateCount:
+      resolution.repositoryCandidateIds.length,
+    targetRepositoryCandidates: ids,
+    shownTargetRepositoryCandidateCount: ids.length,
+    omittedTargetRepositoryCandidateCount:
+      resolution.repositoryCandidateIds.length - ids.length,
+    ...(resolution.publicSurface
+      ? { publicSurface: resolution.publicSurface } : {}),
+  });
 }
 
-export function linkPackageImportSymbolCalls(db: Db, workspaceId: number): PackageSymbolLinkSummary {
-  const repos = repoByPackageName(db, workspaceId);
-  const exports = exportsByRepo(db, workspaceId);
-  const update = db.prepare(`UPDATE symbol_calls SET callee_symbol_id=?,status=?,
-    unresolved_reason=?,evidence_json=? WHERE id=?`);
-  const summary: PackageSymbolLinkSummary = { resolved: 0, ambiguous: 0, unresolved: 0 };
+export function linkPackageImportSymbolCalls(
+  db: Db,
+  workspaceId: number,
+): PackageSymbolLinkSummary {
+  const repositories = repositoriesByPackage(db, workspaceId);
+  const update = db.prepare(`UPDATE symbol_calls SET callee_symbol_id=?,
+    status=?,unresolved_reason=?,evidence_json=? WHERE id=?`);
+  const summary: PackageSymbolLinkSummary = {
+    resolved: 0,
+    ambiguous: 0,
+    unresolved: 0,
+  };
   for (const call of packageCallRows(db, workspaceId)) {
-    const resolution = resolvePackageCall(call, repos, exports);
-    update.run(resolution.id, resolution.status, resolution.reason, resolutionEvidence(call, resolution), call.id);
+    const resolution = resolvePackageCall(db, call, repositories);
+    update.run(
+      resolution.id,
+      resolution.status,
+      resolution.reason,
+      resolutionEvidence(call, resolution),
+      call.id,
+    );
     summary[resolution.status] += 1;
   }
   return summary;

package/src/linker/004-event-subscription-handler-linker.ts

@@ -61,6 +61,8 @@ function subscriptionRows(db: Db, workspaceId: number): SubscriptionRow[] {
     c.confidence
     FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
     WHERE r.workspace_id=? AND c.call_type='async_subscribe'
+      AND json_extract(c.evidence_json,'$.handlerReferenceStatus')
+        ='role_required'
     ORDER BY r.name COLLATE BINARY,r.id,c.source_file COLLATE BINARY,
       c.call_site_start_offset,c.call_site_end_offset,c.id`).all(
     workspaceId,