@saptools/service-flow 0.1.68 → 0.1.70

package/src/parsers/{012-package-fact-contract.ts → package-fact-contract.ts}

@@ -1,20 +1,20 @@
 import {
   PACKAGE_PUBLIC_SURFACE_RECORD_CAP,
   PACKAGE_PUBLIC_SURFACE_SCHEMA,
-} from './003-package-public-surface.js';
+} from './package-public-surface.js';
 import type {
   ExecutableBodyEligibility,
   PackagePublicEntry,
   PackagePublicScope,
   PackagePublicSurfaceFact,
   PublicSurfaceTarget,
-} from './003-package-public-surface.js';
+} from './package-public-surface.js';
 import {
   packageModuleRequest,
   type SymbolImportBindingKind,
   type SymbolImportReference,
   type SymbolImportReferenceShape,
-} from './002-symbol-import-bindings.js';
+} from './symbol-import-bindings.js';
 
 const bindingKinds = new Set<SymbolImportBindingKind>([
   'esm_named', 'esm_default', 'esm_namespace',

package/src/parsers/{010-package-public-surface-analysis.ts → package-public-surface-analysis.ts}

@@ -4,7 +4,7 @@ import {
   PACKAGE_PUBLIC_SURFACE_RECORD_CAP,
   PACKAGE_PUBLIC_SURFACE_SCHEMA,
   resolveModule,
-} from './003-package-public-surface.js';
+} from './package-public-surface.js';
 import type {
   ModuleInfo,
   ModuleResolution,
@@ -16,7 +16,7 @@ import type {
   PackageSourceModule,
   ResolvedExport,
   SymbolPublicSurfaceEvidence,
-} from './003-package-public-surface.js';
+} from './package-public-surface.js';
 import type { PackageEntrypointManifest } from './package-json-parser.js';
 
 interface EntryResolution {

package/src/parsers/{003-package-public-surface.ts → package-public-surface.ts}

@@ -4,8 +4,8 @@ import {
   hasNestedCommonJsMutation,
   isUnshadowedCommonJsExportExpression,
   unsupportedCommonJsMutation,
-} from './018-package-commonjs-syntax.js';
-import { stableLocalValueReference } from './020-stable-local-value.js';
+} from './package-commonjs-syntax.js';
+import { stableLocalValueReference } from './stable-local-value.js';
 
 export const PACKAGE_PUBLIC_SURFACE_SCHEMA =
   'service-flow/package-public-surface@1';
@@ -658,4 +658,4 @@ export function moduleInfoMap(
 }
 
 export { analyzePackagePublicSurface } from
-  './010-package-public-surface-analysis.js';
+  './package-public-surface-analysis.js';

package/src/parsers/{008-package-surface-publication.ts → package-surface-publication.ts}

@@ -8,7 +8,7 @@ import {
   analyzePackagePublicSurface,
   type PackagePublicSurfaceAnalysis,
   type SymbolPublicSurfaceEvidence,
-} from './003-package-public-surface.js';
+} from './package-public-surface.js';
 import type { RepositorySourceContext } from './ts-project.js';
 
 function symbolIdentity(

package/src/parsers/{001-query-entity-resolution.ts → query-entity-resolution.ts}

@@ -1,5 +1,5 @@
 import ts from 'typescript';
-import { isCapQueryBuilderRootName } from './000-direct-query-execution.js';
+import { isCapQueryBuilderRootName } from './direct-query-execution.js';
 
 export interface BindingResolution {
   declaration?: ts.VariableDeclaration | ts.ParameterDeclaration;

package/src/parsers/{015-service-binding-collector.ts → service-binding-collector.ts}

@@ -15,8 +15,8 @@ import {
   createBindingLexicalIndex,
   type BindingLexicalIndex,
   type BindingSiteCandidate,
-} from './011-binding-lexical-scope.js';
-import { selectVisibleBinding } from './021-binding-visibility.js';
+} from './binding-lexical-scope.js';
+import { selectVisibleBinding } from './binding-visibility.js';
 import {
   arrayAssignmentName,
   arrayBindingName,
@@ -24,7 +24,7 @@ import {
   collectReturnedObjectBindings,
   directConnectFactFromFunctionLike,
   functionLikeInitializer,
-} from './014-service-binding-helper-flow.js';
+} from './service-binding-helper-flow.js';
 
 type ResolvedHelper = { helper: HelperBinding; imp?: ImportBinding };
 type BindingEvent = {

package/src/parsers/{014-service-binding-helper-flow.ts → service-binding-helper-flow.ts}

@@ -11,8 +11,8 @@ import {
   type BindingLexicalIndex,
   type BindingSiteCandidate,
   type VisibleBinding,
-} from './011-binding-lexical-scope.js';
-import { selectVisibleBinding } from './021-binding-visibility.js';
+} from './binding-lexical-scope.js';
+import { selectVisibleBinding } from './binding-visibility.js';
 
 export type LocalBindingFact = Omit<
   HelperBinding,
@@ -157,12 +157,58 @@ function returnedProperty(
   return { propertyName, variableName: property.initializer.text };
 }
 
-function branchDependent(node: ts.Node, fn: ts.FunctionLikeDeclaration): boolean {
+function hazardousTryClause(
+  node: ts.Node | undefined,
+  fn: ts.FunctionLikeDeclaration,
+  anyReturn: boolean,
+): boolean {
+  if (!node) return false;
+  let found = false;
+  const visit = (current: ts.Node): void => {
+    if (found || current !== fn && ts.isFunctionLike(current)) return;
+    if (ts.isReturnStatement(current)
+      && (anyReturn || current.expression !== undefined)
+      || ts.isCallExpression(current) && connectFactFromCall(current)) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(current, visit);
+  };
+  visit(node);
+  return found;
+}
+
+function hasAncestor(node: ts.Node, ancestor: ts.Node): boolean {
+  let current: ts.Node | undefined = node.parent;
+  while (current) {
+    if (current === ancestor) return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+function unsupportedTryAncestor(
+  statement: ts.TryStatement,
+  returned: ts.Node,
+  fn: ts.FunctionLikeDeclaration,
+): boolean {
+  if (!hasAncestor(returned, statement.tryBlock)) return true;
+  if (hazardousTryClause(statement.catchClause?.block, fn, false))
+    return true;
+  return hazardousTryClause(statement.finallyBlock, fn, true);
+}
+
+function branchDependent(
+  node: ts.Node,
+  fn: ts.FunctionLikeDeclaration,
+): boolean {
   let current: ts.Node | undefined = node.parent;
   while (current && current !== fn) {
     if (ts.isIfStatement(current) || ts.isConditionalExpression(current)
-      || ts.isSwitchStatement(current) || ts.isIterationStatement(current, false)
-      || ts.isTryStatement(current)) return true;
+      || ts.isSwitchStatement(current)
+      || ts.isIterationStatement(current, false)) return true;
+    if (ts.isTryStatement(current)
+      && unsupportedTryAncestor(current, node, fn)) return true;
     current = current.parent;
   }
   return false;
@@ -231,10 +277,30 @@ function directReturnConnectFact(
   return directConnectFact(returned);
 }
 
+function hasTryAncestor(
+  returned: ts.ReturnStatement,
+  fn: ts.FunctionLikeDeclaration,
+): boolean {
+  let current: ts.Node | undefined = returned.parent;
+  while (current && current !== fn) {
+    if (ts.isTryStatement(current)) return true;
+    current = current.parent;
+  }
+  return false;
+}
+
 export function directConnectFactFromFunctionLike(
   fn: ts.FunctionLikeDeclaration,
 ): LocalBindingFact | undefined {
   if (ts.isArrowFunction(fn) && fn.body && !ts.isBlock(fn.body))
     return directConnectFact(fn.body);
-  return directReturnConnectFact(fn);
+  const returned = singleReturn(fn);
+  const fact = directReturnConnectFact(fn);
+  if (!fact || !returned || !hasTryAncestor(returned, fn)) return fact;
+  return {
+    ...fact,
+    helperChain: [...(fact.helperChain ?? []), {
+      bindingOrigin: 'single_hop_helper_return',
+    }],
+  };
 }

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

@@ -2,7 +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 { extractPlaceholderKeys } from '../utils/001-placeholders.js';
+import { extractPlaceholderKeys } from '../utils/placeholders.js';
 import type { RepositorySourceContext } from './ts-project.js';
 
 export interface HelperBinding {

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

@@ -15,8 +15,8 @@ import {
   directConnectFactFromFunctionLike,
   functionLikeInitializer,
   type LocalBindingFact,
-} from './014-service-binding-helper-flow.js';
-import { collectServiceBindings } from './015-service-binding-collector.js';
+} from './service-binding-helper-flow.js';
+import { collectServiceBindings } from './service-binding-collector.js';
 import type { RepositorySourceContext } from './ts-project.js';
 
 interface LocalHelperFact extends LocalBindingFact {

package/src/parsers/{007-source-fact-reconciliation.ts → source-fact-reconciliation.ts}

@@ -8,9 +8,9 @@ import type {
 import {
   executableSymbolCandidates,
   selectCallOwner,
-} from './004-fact-identity.js';
-import { reconcileEventSubscriptions } from './005-event-subscription-facts.js';
-import { reconcileBindingAndCallIdentity } from './006-binding-identity.js';
+} from './fact-identity.js';
+import { reconcileEventSubscriptions } from './event-subscription-facts.js';
+import { reconcileBindingAndCallIdentity } from './binding-identity.js';
 import type { ClassifiedOutboundCall } from './outbound-call-parser.js';
 
 export interface ReconciledSourceFacts {

package/src/parsers/{020-stable-local-value.ts → stable-local-value.ts}

@@ -1,10 +1,10 @@
 import ts from 'typescript';
 import {
   identifierMatchesDeclaration,
-} from './002-symbol-import-bindings.js';
+} from './symbol-import-bindings.js';
 import {
   isUnshadowedCommonJsExportExpression,
-} from './018-package-commonjs-syntax.js';
+} from './package-commonjs-syntax.js';
 
 function transparentUse(node: ts.Node): ts.Node {
   const parent = node.parent;

package/src/parsers/{009-symbol-call-facts.ts → symbol-call-facts.ts}

@@ -6,18 +6,18 @@ import type {
 import {
   executableSymbolCandidates,
   selectCallOwner,
-} from './004-fact-identity.js';
+} from './fact-identity.js';
 import {
   derivedMemberImportReference,
   identifierMatchesDeclaration,
   symbolImportReference,
   type SymbolImportBinding,
   type SymbolImportReference,
-} from './002-symbol-import-bindings.js';
+} from './symbol-import-bindings.js';
 import {
   localSymbolTarget,
   type LocalSymbolTargetIdentity,
-} from './016-local-symbol-reference.js';
+} from './local-symbol-reference.js';
 
 export interface SymbolCallProxy {
   importSource: string;

package/src/parsers/{017-symbol-derived-contexts.ts → symbol-derived-contexts.ts}

@@ -3,12 +3,12 @@ import {
   symbolCallName,
   type SymbolCallProxy,
   type SymbolClassInstance,
-} from './009-symbol-call-facts.js';
+} from './symbol-call-facts.js';
 import {
   identifierMatchesDeclaration,
   symbolImportReference,
   type SymbolImportBinding,
-} from './002-symbol-import-bindings.js';
+} from './symbol-import-bindings.js';
 
 interface DerivedContextCollection {
   source: ts.SourceFile;

package/src/parsers/symbol-parser.ts

@@ -9,24 +9,24 @@ import {
 } from './outbound-call-parser.js';
 import type { RepositorySourceContext } from './ts-project.js';
 import { normalizePath } from '../utils/path-utils.js';
-import { reconcileEventSubscriptions } from './005-event-subscription-facts.js';
-import { reconcileSymbolCallOwners } from './007-source-fact-reconciliation.js';
+import { reconcileEventSubscriptions } from './event-subscription-facts.js';
+import { reconcileSymbolCallOwners } from './source-fact-reconciliation.js';
 import {
   collectSymbolImportBindings,
   type SymbolImportBinding,
-} from './002-symbol-import-bindings.js';
+} from './symbol-import-bindings.js';
 import {
   collectSymbolCallFacts,
   symbolCallName,
   type SymbolCallProxy,
   type SymbolClassInstance,
-} from './009-symbol-call-facts.js';
+} from './symbol-call-facts.js';
 import {
   executableBodyEligibility,
-} from './013-executable-body-eligibility.js';
+} from './executable-body-eligibility.js';
 import {
   collectDerivedSymbolContexts,
-} from './017-symbol-derived-contexts.js';
+} from './symbol-derived-contexts.js';
 
 function lineOf(source: ts.SourceFile, pos: number): number {
   return source.getLineAndCharacterOfPosition(pos).line + 1;
@@ -42,6 +42,12 @@ function isFunctionLike(node: ts.Node): node is ts.FunctionLikeDeclaration {
 function exported(node: ts.Node): boolean {
   return Boolean(ts.getCombinedModifierFlags(node as ts.Declaration) & ts.ModifierFlags.Export);
 }
+function defaultExported(node: ts.Node): boolean {
+  return Boolean(
+    ts.getCombinedModifierFlags(node as ts.Declaration)
+      & ts.ModifierFlags.Default,
+  );
+}
 function isPublicClassMethod(node: ts.MethodDeclaration): boolean {
   const flags = ts.getCombinedModifierFlags(node);
   return (flags & ts.ModifierFlags.Private) === 0 && (flags & ts.ModifierFlags.Protected) === 0;
@@ -141,6 +147,7 @@ interface SymbolCollection {
   exportNames: Map<string, string>;
   objectExports: Set<string>;
   exportedClasses: Set<string>;
+  defaultExportedClasses: Set<string>;
   declaredClasses: Set<string>;
   proxies: Map<string, SymbolCallProxy[]>;
   instances: Map<string, SymbolClassInstance[]>;
@@ -153,7 +160,8 @@ function symbolSourceEvidence(
     parentRoot: string;
     qualifiedName: string;
     declaredExportName?: string;
-    classContainerExported: boolean; classMemberExported: boolean;
+    classContainerExported: boolean; classContainerDefaultExported: boolean;
+    classMemberExported: boolean;
     objectExported: boolean;
     evidence?: Record<string, unknown>;
   },
@@ -168,6 +176,8 @@ function symbolSourceEvidence(
   if (options.classContainerExported && ts.isMethodDeclaration(node)
     && isPublicClassMethod(node)) return {
     source: 'exported_class_instance_member', exportedClass: options.parentRoot,
+    exportedClassExportKind: options.classContainerDefaultExported
+      ? 'default' : 'named',
     memberKind: 'class_method',
   };
   if (options.declaredExportName) return {
@@ -201,6 +211,7 @@ interface SymbolNames {
   declaredExportName?: string;
   objectExported: boolean;
   classContainerExported: boolean;
+  classContainerDefaultExported: boolean;
   classMemberExported: boolean;
   effectiveName?: string;
 }
@@ -219,6 +230,24 @@ function exportedClassMember(
     && isPublicClassMethod(node);
 }
 
+function classExportState(
+  collection: SymbolCollection,
+  parentName: string | undefined,
+  parentRoot: string,
+): {
+  classContainerExported: boolean;
+  classContainerDefaultExported: boolean;
+} {
+  return {
+    classContainerExported: Boolean(
+      parentName && collection.exportedClasses.has(parentRoot),
+    ),
+    classContainerDefaultExported: Boolean(
+      parentName && collection.defaultExportedClasses.has(parentRoot),
+    ),
+  };
+}
+
 function symbolNames(
   collection: SymbolCollection,
   kind: string,
@@ -238,12 +267,11 @@ function symbolNames(
   const classMemberExported = exportedClassMember(
     collection, kind, parentName, parentRoot, node,
   );
-  const classContainerExported = Boolean(
-    parentName && collection.exportedClasses.has(parentRoot),
-  );
+  const classState = classExportState(collection, parentName, parentRoot);
   return {
     parentRoot, declaredExportName, qualifiedName,
-    objectExported, classContainerExported, classMemberExported,
+    objectExported, ...classState,
+    classMemberExported,
     effectiveName: classMemberExported || objectExported
       ? qualifiedName : declaredExportName,
   };
@@ -266,6 +294,7 @@ function addExecutableSymbol(
     qualifiedName: names.qualifiedName,
     declaredExportName: names.declaredExportName,
     classContainerExported: names.classContainerExported,
+    classContainerDefaultExported: names.classContainerDefaultExported,
     classMemberExported: names.classMemberExported,
     objectExported: names.objectExported,
     evidence,
@@ -457,6 +486,8 @@ function collectClassDeclaration(
   collection.declaredClasses.add(node.name.text);
   if (exported(node) || collection.exportNames.has(node.name.text))
     collection.exportedClasses.add(node.name.text);
+  if (defaultExported(node))
+    collection.defaultExportedClasses.add(node.name.text);
   for (const member of node.members)
     visitDeclaredSymbol(collection, member, node.name.text);
   return true;
@@ -553,6 +584,7 @@ function createCollection(
     importBindings: collectSymbolImportBindings(source),
     exportNames: exportDeclarations(source),
     objectExports: new Set(), exportedClasses: new Set(),
+    defaultExportedClasses: new Set(),
     declaredClasses: new Set(), proxies: new Map(), instances: new Map(),
   };
 }

package/src/trace/{014-compact-contract.ts → compact-contract.ts}

@@ -82,6 +82,7 @@ export interface CompactDecisionInput {
   implementationStrategy?: string;
   implementationGuided?: boolean;
   implementationContextual?: boolean;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
   reasonCode?: string;
   eventMatchStrategy?: string;
   dispatchCertainty?: string;
@@ -225,6 +226,7 @@ export interface CompactDecisionV1 {
   implementationStrategy?: string;
   implementationGuided?: boolean;
   implementationContextual?: boolean;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
   eventMatchStrategy?: string;
   dispatchCertainty?: string;
   eventSubscriptionCount?: number;
@@ -247,6 +249,10 @@ export interface CompactEdgeDetailsV1 {
 
 export interface CompactDiagnosticDetailsV1 {
   reasonCode?: string;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
+  selectorKind?: string;
+  selectorSuggestions?: CompactReferenceGroupV1;
+  invalidFactCategories?: CompactReferenceGroupV1;
   missingVariableNames?: string[];
   missingVariableCount?: number;
   shownMissingVariableCount?: number;

package/src/trace/{021-compact-decision-normalization.ts → compact-decision-normalization.ts}

@@ -1,11 +1,14 @@
-import { compareBinary } from './010-traversal-scope.js';
+import { compareBinary } from './traversal-scope.js';
 import type {
   CompactDecisionV1,
+  CompactReferenceGroupV1,
   CompactStatus,
-} from './014-compact-contract.js';
+} from './compact-contract.js';
 
 export const COMPACT_MISSING_NAME_LIMIT = 8;
 export const COMPACT_MISSING_NAME_MAX_LENGTH = 160;
+export const COMPACT_REFERENCE_VALUE_LIMIT = 5;
+const COMPACT_REFERENCE_VALUE_MAX_LENGTH = 240;
 
 export interface CompactMissingNameProjection {
   readonly names: string[];
@@ -23,11 +26,17 @@ export function projectCompactMissingNames(
   values: readonly string[] | undefined,
   authoritativeCount: unknown,
 ): CompactMissingNameProjection {
-  const raw = [...new Set((values ?? [])
-    .map((value) => value.trim())
-    .filter(Boolean))]
-    .sort(compareBinary);
-  const safe = raw.filter(isSafeCompactMissingName);
+  const candidates = new Map<string, boolean>();
+  for (const value of values ?? []) {
+    const normalized = value.trim();
+    if (!normalized) continue;
+    candidates.set(
+      normalized,
+      (candidates.get(normalized) ?? true) && isSafeCompactMissingName(value),
+    );
+  }
+  const raw = [...candidates.keys()].sort(compareBinary);
+  const safe = raw.filter((name) => candidates.get(name) === true);
   const names = safe.slice(0, COMPACT_MISSING_NAME_LIMIT);
   const total = Math.max(compactCount(authoritativeCount), raw.length);
   return {
@@ -37,25 +46,58 @@ export function projectCompactMissingNames(
 }
 
 export function isSafeCompactMissingName(value: string): boolean {
+  if (hasControlCharacter(value)) return false;
   const normalized = value.trim();
   return normalized.length > 0
     && normalized.length <= COMPACT_MISSING_NAME_MAX_LENGTH
-    && !hasControlCharacter(normalized)
     && safeMissingName.test(normalized);
 }
 
+export function projectCompactReferenceGroup(
+  values: readonly string[] | undefined,
+  authoritativeCount: unknown,
+  isSafe: (value: string) => boolean,
+): CompactReferenceGroupV1 | undefined {
+  const candidates = normalizedReferenceValues(values, isSafe);
+  const unique = [...candidates.keys()].sort(compareBinary);
+  const safe = unique.filter((value) => candidates.get(value) === true);
+  const shown = safe.slice(0, COMPACT_REFERENCE_VALUE_LIMIT);
+  const total = Math.max(compactCount(authoritativeCount), unique.length);
+  if (total === 0) return undefined;
+  return {
+    values: shown,
+    total,
+    shown: shown.length,
+    omitted: Math.max(0, total - shown.length),
+  };
+}
+
+export function isSafeCompactReferenceName(value: string): boolean {
+  if (!safeReferenceText(value, 160)) return false;
+  return /^[@A-Za-z0-9_$][@A-Za-z0-9_$./:-]*$/.test(value.trim());
+}
+
+export function isSafeCompactSelectorSuggestion(value: string): boolean {
+  if (!safeReferenceText(value, COMPACT_REFERENCE_VALUE_MAX_LENGTH))
+    return false;
+  return /^(?:--(?:repo|service|operation|path|handler) [@A-Za-z0-9_$./:-]+)(?: --(?:repo|service|operation|path|handler) [@A-Za-z0-9_$./:-]+)*$/
+    .test(value.trim());
+}
+
 export function normalizeCompactDecisionEquivalence(
   decision: CompactDecisionV1,
   status: CompactStatus,
   canonicalTarget: string | undefined,
   targetIdentityEqual = false,
   persistedIdentityEqual = false,
+  rawPersistedStatus?: string,
 ): void {
+  if (decision.effectiveResolutionStatus === status)
+    delete decision.effectiveResolutionStatus;
   removeEquivalentPersistedDecision(
     decision, status, canonicalTarget, persistedIdentityEqual,
+    rawPersistedStatus,
   );
-  if (decision.effectiveResolutionStatus === status)
-    delete decision.effectiveResolutionStatus;
   if (targetIdentityEqual && canonicalTarget !== undefined
     && decision.effectiveTarget === canonicalTarget)
     delete decision.effectiveTarget;
@@ -77,9 +119,10 @@ function removeEquivalentPersistedDecision(
   status: CompactStatus,
   canonicalTarget: string | undefined,
   identityEqual: boolean,
+  rawPersistedStatus: string | undefined,
 ): void {
   if (!identityEqual
-    || decision.persistedResolutionStatus !== status
+    || rawPersistedStatus !== status
     || (decision.effectiveResolutionStatus !== undefined
       && decision.persistedResolutionStatus
         !== decision.effectiveResolutionStatus))
@@ -96,6 +139,29 @@ function compactCount(value: unknown): number {
     ? Math.max(0, Math.floor(value)) : 0;
 }
 
+function normalizedReferenceValues(
+  values: readonly string[] | undefined,
+  isSafe: (value: string) => boolean,
+): Map<string, boolean> {
+  const unique = new Map<string, boolean>();
+  for (const raw of values ?? []) {
+    const value = raw.trim();
+    if (!value) continue;
+    unique.set(value, (unique.get(value) ?? true) && isSafe(raw));
+  }
+  return unique;
+}
+
+function safeReferenceText(value: string, maxLength: number): boolean {
+  if (hasControlCharacter(value)) return false;
+  const normalized = value.trim();
+  return normalized.length > 0
+    && normalized.length <= maxLength
+    && !/^[a-z]+:\/\//i.test(normalized)
+    && !/(?:^|[^A-Za-z0-9])(?:authorization|bearer|credential|destination|password|secret|token)(?:$|[^A-Za-z0-9])/i
+      .test(normalized);
+}
+
 function hasControlCharacter(value: string): boolean {
   for (let index = 0; index < value.length; index += 1) {
     const code = value.charCodeAt(index);