@apifuse/provider-sdk 2.2.0-beta.53 → 2.2.0-beta.55

package/dist/cli/migrate-operation-declaration.js

@@ -55,6 +55,9 @@ const SIDECAR_NAME = "migrate-operation-declaration.locales-todo.json";
  * copies every untouched source slice byte-for-byte.
  */
 export function migrateOperationDeclaration(sourceText, fileName, options = {}) {
+    return migrateOperationDeclarationInternal(sourceText, fileName, options);
+}
+function migrateOperationDeclarationInternal(sourceText, fileName, options, context = {}) {
     const source = parseSource(fileName, sourceText);
     const parseError = firstSyntaxError(source);
     if (parseError !== undefined) {
@@ -65,7 +68,7 @@ export function migrateOperationDeclaration(sourceText, fileName, options = {})
     }
     const constObjects = collectModuleConstObjects(source);
     const constArrays = collectModuleConstArrays(source);
-    const discovery = discoverOperationSites(source, fileName, constObjects, options.operationIds);
+    const discovery = discoverOperationSites(source, fileName, constObjects, options.operationIds, context.operationSites, context.excludedBindings);
     if (discovery.refusals.length > 0) {
         return { status: "refused", refusals: discovery.refusals };
     }
@@ -73,7 +76,7 @@ export function migrateOperationDeclaration(sourceText, fileName, options = {})
     const todos = [];
     const refusals = [];
     for (const site of discovery.sites) {
-        const plan = planOperationMigration(source, fileName, site, constObjects, constArrays, options.localeFiles ?? []);
+        const plan = planOperationMigration(source, fileName, site, constObjects, constArrays, options.localeFiles ?? [], context.staticObjectResolver);
         if ("refusal" in plan) {
             refusals.push(plan.refusal);
             continue;
@@ -120,13 +123,13 @@ export function verifyOperationDeclarationRewrite(code, fileName) {
         return undefined;
     return refusal(fileName, "<file>", "codemod_syntax", `Transform output did not parse: ${outputError}`);
 }
-function planOperationMigration(source, fileName, site, constObjects, constArrays, localeFiles) {
+function planOperationMigration(source, fileName, site, constObjects, constArrays, localeFiles, staticObjectResolver) {
     if (site.object.properties.some(ts.isSpreadAssignment)) {
         return {
             refusal: refusal(fileName, site.operationKey, "non_literal", "Top-level operation spreads cannot be rewritten without changing their shared declaration."),
         };
     }
-    const expanded = expandMembers(site.object, constObjects, fileName, site.operationKey);
+    const expanded = expandMembers(site.object, source, constObjects, fileName, site.operationKey, staticObjectResolver);
     if ("refusal" in expanded)
         return expanded;
     const top = indexMembers(expanded.members, fileName, site.operationKey);
@@ -142,13 +145,13 @@ function planOperationMigration(source, fileName, site, constObjects, constArray
         const member = top.byName.get(containerName);
         if (member === undefined)
             continue;
-        const object = resolveObjectInitializer(member, constObjects);
-        if (object === undefined) {
+        const resolvedObject = resolveObjectInitializer(member, source, constObjects, staticObjectResolver);
+        if (resolvedObject === undefined) {
             return {
                 refusal: refusal(fileName, site.operationKey, "non_literal", `${containerName} must be an object literal or a module-level const object literal.`),
             };
         }
-        const members = expandMembers(object, constObjects, fileName, site.operationKey);
+        const members = expandMembers(resolvedObject.object, resolvedObject.source, constObjects, fileName, site.operationKey, staticObjectResolver);
         if ("refusal" in members)
             return members;
         const indexed = indexMembers(members.members, fileName, site.operationKey);
@@ -196,24 +199,24 @@ function planOperationMigration(source, fileName, site, constObjects, constArray
         const sourceContainer = risk.source === "annotations" ? "annotations" : "toolRouter";
         addInsertion(insertions, sourceContainer, `riskClass: ${risk.text}`);
     }
-    const timeout = mergeFlatAndNested("timeoutMs", top.byName.get("timeoutMs"), annotations.get("timeoutMs"), fileName, site.operationKey, source, "execution_conflict");
+    const timeout = mergeFlatAndNested("timeoutMs", top.byName.get("timeoutMs"), annotations.get("timeoutMs"), fileName, site.operationKey, "execution_conflict");
     if ("refusal" in timeout)
         return timeout;
     if (timeout.insert !== undefined)
         addInsertion(insertions, "annotations", timeout.insert);
-    const connection = resolveConnectionMode(top.byName, toolRouter, fileName, site.operationKey, source);
+    const connection = resolveConnectionMode(top.byName, toolRouter, fileName, site.operationKey);
     if ("refusal" in connection)
         return connection;
     if (connection.insert !== undefined) {
         addInsertion(insertions, "toolRouter", connection.insert);
     }
-    const externalRef = mergeFlatAndNested("connectionExternalRefParam", top.byName.get("connectionExternalRefParam"), toolRouter.get("connectionExternalRefParam"), fileName, site.operationKey, source, "connection_mode_conflict");
+    const externalRef = mergeFlatAndNested("connectionExternalRefParam", top.byName.get("connectionExternalRefParam"), toolRouter.get("connectionExternalRefParam"), fileName, site.operationKey, "connection_mode_conflict");
     if ("refusal" in externalRef)
         return externalRef;
     if (externalRef.insert !== undefined) {
         addInsertion(insertions, "toolRouter", externalRef.insert);
     }
-    const approval = resolveApproval(top.byName.get("approval"), toolRouter.get("approval"), risk.value, fileName, site.operationKey, source);
+    const approval = resolveApproval(top.byName.get("approval"), toolRouter.get("approval"), risk.value, fileName, site.operationKey);
     if ("refusal" in approval)
         return approval;
     if (approval.removeTop !== undefined)
@@ -221,7 +224,7 @@ function planOperationMigration(source, fileName, site, constObjects, constArray
     if (approval.insert !== undefined)
         addInsertion(insertions, "toolRouter", approval.insert);
     for (const field of DOCS_FIELDS) {
-        const merged = mergeFlatAndNested(field, top.byName.get(field), docs.get(field), fileName, site.operationKey, source, "locale_key_conflict");
+        const merged = mergeFlatAndNested(field, top.byName.get(field), docs.get(field), fileName, site.operationKey, "locale_key_conflict");
         if ("refusal" in merged)
             return merged;
         if (merged.insert !== undefined)
@@ -380,7 +383,7 @@ function resolveRiskClass(top, annotations, toolRouter, fileName, operationKey)
         refusal: refusal(fileName, operationKey, "no_safety", "No authored riskClass, annotations.destructive: true, or annotations.readOnly: true declaration exists; refusing to invent write."),
     };
 }
-function resolveConnectionMode(top, toolRouter, fileName, operationKey, source) {
+function resolveConnectionMode(top, toolRouter, fileName, operationKey) {
     const flat = top.get("connectionMode");
     const nested = toolRouter.get("connectionMode");
     if (flat !== undefined && nested !== undefined) {
@@ -398,7 +401,7 @@ function resolveConnectionMode(top, toolRouter, fileName, operationKey, source)
     if (flat !== undefined)
         return {};
     if (nested !== undefined) {
-        return { insert: memberText(nested, "connectionMode", source) };
+        return { insert: memberText(nested, "connectionMode") };
     }
     const required = toolRouter.get("requiresConnection");
     if (required === undefined)
@@ -408,7 +411,7 @@ function resolveConnectionMode(top, toolRouter, fileName, operationKey, source)
         return value;
     return { insert: `connectionMode: ${value.value ? '"required"' : '"none"'}` };
 }
-function resolveApproval(flat, nested, riskClass, fileName, operationKey, source) {
+function resolveApproval(flat, nested, riskClass, fileName, operationKey) {
     let selected = flat ?? nested;
     if (flat !== undefined && nested !== undefined) {
         const same = equivalentLiteral(flat.initializer, nested.initializer);
@@ -434,7 +437,7 @@ function resolveApproval(flat, nested, riskClass, fileName, operationKey, source
     }
     if (flat !== undefined)
         return {};
-    return { insert: memberText(selected, "approval", source) };
+    return { insert: memberText(selected, "approval") };
 }
 function defaultApprovalPolicy(riskClass) {
     if (riskClass === "read")
@@ -443,16 +446,22 @@ function defaultApprovalPolicy(riskClass) {
         return "risk-based";
     return "always";
 }
-function mergeFlatAndNested(field, flat, nested, fileName, operationKey, source, reason) {
+function mergeFlatAndNested(field, flat, nested, fileName, operationKey, reason) {
     if (nested === undefined)
         return {};
     if (flat === undefined)
-        return { insert: memberText(nested, field, source) };
+        return { insert: memberText(nested, field) };
     const same = equivalentLiteral(flat.initializer, nested.initializer);
     if (same === undefined) {
         return nonLiteral(fileName, operationKey, `${field} must be literal when both top-level and nested declarations exist.`);
     }
     if (!same) {
+        // A shared imported docs template is intentionally lower-precedence than
+        // an operation's explicit flat locale key. Keep direct-vs-direct
+        // conflicts fail-closed, but do not let a spread default replace the
+        // operation-specific key during flattening.
+        if (reason === "locale_key_conflict" && nested.fromSpread === true)
+            return {};
         return {
             refusal: refusal(fileName, operationKey, reason, `Top-level ${field} conflicts with nested ${field}.`),
         };
@@ -550,7 +559,9 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, c
 }
 function resolveOperationLocaleNamespace(members, fileName, site) {
     const authoredNamespaces = new Set();
-    for (const member of members) {
+    const directMembers = members.filter((member) => member !== undefined && member.fromSpread !== true);
+    const namespaceMembers = directMembers.length > 0 ? directMembers : members;
+    for (const member of namespaceMembers) {
         const localeKey = literalString(member?.initializer);
         if (localeKey === undefined)
             continue;
@@ -567,6 +578,11 @@ function resolveOperationLocaleNamespace(members, fileName, site) {
     const authored = authoredNamespaces.values().next().value;
     if (authored !== undefined)
         return { namespace: authored };
+    // planExamples proves the id before using this placeholder to construct a
+    // locale key. Avoid validating an unproven binding such as <anonymous> as
+    // though it were an authored operation id.
+    if (!site.operationIdProven)
+        return { namespace: site.operationKey };
     try {
         return { namespace: operationIdToLocaleNamespace(site.operationKey) };
     }
@@ -583,10 +599,13 @@ function replaceExampleLocaleMember(member, newName, localeKey, source) {
         text: `${newName}: ${JSON.stringify(localeKey)}`,
     };
 }
-function discoverOperationSites(source, fileName, constObjects, operationIds) {
+function discoverOperationSites(source, fileName, constObjects, operationIds, operationSites, excludedBindings) {
     const sitesByStart = new Map();
     const localIds = new Map(operationIds ?? []);
+    const localExcludedBindings = new Set(excludedBindings ?? []);
     const refusals = [];
+    const operationFactories = collectSimpleOperationFactories(source);
+    const factoryCallIds = new Map();
     for (const map of collectOperationsMaps(source, constObjects, fileName, refusals)) {
         for (const property of map.properties) {
             if (ts.isSpreadAssignment(property))
@@ -615,6 +634,16 @@ function discoverOperationSites(source, fileName, constObjects, operationIds) {
                 });
                 continue;
             }
+            if (ts.isCallExpression(unwrapped) &&
+                ts.isIdentifier(unwrapped.expression) &&
+                operationFactories.has(unwrapped.expression.text) &&
+                !localExcludedBindings.has(unwrapped.expression.text)) {
+                const factoryName = unwrapped.expression.text;
+                const operationIdsForFactory = factoryCallIds.get(factoryName) ?? new Set();
+                operationIdsForFactory.add(key);
+                factoryCallIds.set(factoryName, operationIdsForFactory);
+                continue;
+            }
             if (ts.isObjectLiteralExpression(unwrapped)) {
                 sitesByStart.set(unwrapped.getStart(source), {
                     object: unwrapped,
@@ -624,10 +653,35 @@ function discoverOperationSites(source, fileName, constObjects, operationIds) {
             }
         }
     }
+    for (const [factoryName, operationIdsForFactory] of factoryCallIds) {
+        const ids = [...operationIdsForFactory];
+        if (ids.length === 1) {
+            const operationId = ids[0];
+            if (operationId !== undefined)
+                localIds.set(factoryName, operationId);
+            continue;
+        }
+        localExcludedBindings.add(factoryName);
+        refusals.push(refusal(fileName, factoryName, "factory_operation_id_ambiguous", `Factory ${factoryName} is registered under multiple operation ids: ${ids
+            .map((id) => JSON.stringify(id))
+            .join(", ")}. A shared operation body cannot own one examples locale namespace.`));
+    }
     const visit = (node) => {
+        if (ts.isObjectLiteralExpression(node)) {
+            const indexedOperationKey = operationSites?.get(node.getStart(source));
+            if (indexedOperationKey !== undefined) {
+                sitesByStart.set(node.getStart(source), {
+                    object: node,
+                    operationKey: indexedOperationKey,
+                    operationIdProven: true,
+                });
+            }
+        }
         if (ts.isCallExpression(node) && isOperationHelperCall(node)) {
             const argument = operationArgument(node);
             const bindingName = enclosingBindingName(node);
+            if (bindingName !== undefined && localExcludedBindings.has(bindingName))
+                return;
             const operationKey = (bindingName === undefined ? undefined : localIds.get(bindingName)) ??
                 bindingName ??
                 "<anonymous>";
@@ -662,6 +716,31 @@ function discoverOperationSites(source, fileName, constObjects, operationIds) {
         refusals,
     };
 }
+function collectSimpleOperationFactories(source) {
+    const factories = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isFunctionDeclaration(statement) ||
+            statement.name === undefined ||
+            statement.body === undefined ||
+            statement.body.statements.length !== 1) {
+            continue;
+        }
+        const returned = statement.body.statements[0];
+        if (!ts.isReturnStatement(returned) || returned.expression === undefined)
+            continue;
+        const expression = unwrapExpression(returned.expression);
+        if (expression !== undefined &&
+            ts.isCallExpression(expression) &&
+            isOperationHelperCall(expression)) {
+            const argument = operationArgument(expression);
+            const object = argument === undefined ? undefined : unwrapExpression(argument);
+            if (object !== undefined && ts.isObjectLiteralExpression(object)) {
+                factories.add(statement.name.text);
+            }
+        }
+    }
+    return factories;
+}
 function collectOperationsMaps(source, constObjects, fileName, refusals) {
     const maps = new Map();
     const inspect = (expression, label) => {
@@ -784,6 +863,9 @@ function enclosingBindingName(node) {
         if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name)) {
             return current.name.text;
         }
+        if (ts.isFunctionDeclaration(current) && current.name !== undefined) {
+            return current.name.text;
+        }
         if (ts.isPropertyAssignment(current))
             return staticPropertyName(current.name);
         if (ts.isExportAssignment(current))
@@ -855,7 +937,7 @@ function expandArrayElements(array, constArrays, fileName, operationKey, seen =
     }
     return { elements };
 }
-function expandMembers(object, constObjects, fileName, operationKey, seen = new Set()) {
+function expandMembers(object, source, constObjects, fileName, operationKey, staticObjectResolver, seen = new Set()) {
     if (seen.has(object)) {
         return nonLiteral(fileName, operationKey, "A module-level object spread is recursive.");
     }
@@ -863,17 +945,12 @@ function expandMembers(object, constObjects, fileName, operationKey, seen = new
     const members = [];
     for (const property of object.properties) {
         if (ts.isSpreadAssignment(property)) {
-            const expression = unwrapExpression(property.expression);
-            const spreadObject = expression !== undefined && ts.isObjectLiteralExpression(expression)
-                ? expression
-                : expression !== undefined && ts.isIdentifier(expression)
-                    ? constObjects.get(expression.text)
-                    : undefined;
+            const spreadObject = resolveStaticObjectExpression(property.expression, source, constObjects, staticObjectResolver);
             if (spreadObject === undefined) {
-                members.push({ name: "<spread>", property });
+                members.push({ name: "<spread>", property, source });
                 continue;
             }
-            const expanded = expandMembers(spreadObject, constObjects, fileName, operationKey, new Set(seen));
+            const expanded = expandMembers(spreadObject.object, spreadObject.source, constObjects, fileName, operationKey, staticObjectResolver, new Set(seen));
             if ("refusal" in expanded)
                 return expanded;
             members.push(...expanded.members.map((member) => ({ ...member, fromSpread: true })));
@@ -884,7 +961,7 @@ function expandMembers(object, constObjects, fileName, operationKey, seen = new
             return nonLiteral(fileName, operationKey, "A declaration member uses a computed name.");
         }
         const initializer = propertyValue(property);
-        members.push({ name, property, initializer });
+        members.push({ name, property, initializer, source });
     }
     return { members };
 }
@@ -915,21 +992,32 @@ function indexMembersFromObject(object, fileName, operationKey) {
         if (name === undefined || initializer === undefined) {
             return nonLiteral(fileName, operationKey, "Example members must be literal properties.");
         }
-        members.push({ name, property, initializer });
+        members.push({ name, property, initializer, source: object.getSourceFile() });
     }
     const indexed = indexMembers(members, fileName, operationKey);
     if ("refusal" in indexed)
         return indexed;
     return { byName: indexed.byName };
 }
-function resolveObjectInitializer(member, constObjects) {
-    const initializer = unwrapExpression(member.initializer);
-    if (initializer === undefined)
+function resolveObjectInitializer(member, rootSource, constObjects, staticObjectResolver) {
+    if (member.initializer === undefined)
         return undefined;
-    if (ts.isObjectLiteralExpression(initializer))
-        return initializer;
-    if (ts.isIdentifier(initializer))
-        return constObjects.get(initializer.text);
+    return resolveStaticObjectExpression(member.initializer, member.source, constObjects, staticObjectResolver, rootSource);
+}
+function resolveStaticObjectExpression(expression, source, constObjects, staticObjectResolver, rootSource = source) {
+    const unwrapped = unwrapExpression(expression);
+    if (unwrapped === undefined)
+        return undefined;
+    if (ts.isObjectLiteralExpression(unwrapped))
+        return { object: unwrapped, source };
+    const externallyResolved = staticObjectResolver?.(unwrapped, source);
+    if (externallyResolved !== undefined)
+        return externallyResolved;
+    if (source === rootSource && ts.isIdentifier(unwrapped)) {
+        const object = constObjects.get(unwrapped.text);
+        if (object !== undefined)
+            return { object, source };
+    }
     return undefined;
 }
 function memberMap(members) {
@@ -1020,10 +1108,10 @@ function literalValue(expression) {
     }
     return NOT_LITERAL;
 }
-function memberText(member, name, source) {
+function memberText(member, name) {
     if (member.initializer === undefined)
         return name;
-    return `${name}: ${member.initializer.getText(source)}`;
+    return `${name}: ${member.initializer.getText(member.source)}`;
 }
 function addInsertion(insertions, sourceContainer, text) {
     const items = insertions.get(sourceContainer) ?? [];
@@ -1180,17 +1268,21 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
     const providerRoot = resolve(providerRootInput);
     const sourceFiles = collectSourceFiles(providerRoot);
     const localeFiles = collectLocaleFiles(providerRoot);
-    const operationIds = buildOperationIdIndex(sourceFiles);
+    const repositoryIndex = buildRepositoryOperationIndex(sourceFiles, providerRoot);
     const pendingWrites = new Map();
     const changedFiles = [];
     const todos = [];
-    const refusals = [];
+    const refusals = [...repositoryIndex.refusals];
     let operationCount = 0;
     for (const sourcePath of sourceFiles) {
         const relativePath = slash(relative(providerRoot, sourcePath));
-        const result = migrateOperationDeclaration(readFileSync(sourcePath, "utf8"), relativePath, {
-            operationIds: operationIds.get(sourcePath),
+        const result = migrateOperationDeclarationInternal(readFileSync(sourcePath, "utf8"), relativePath, {
+            operationIds: repositoryIndex.operationIds.get(sourcePath),
             localeFiles,
+        }, {
+            operationSites: repositoryIndex.operationSites.get(sourcePath),
+            excludedBindings: repositoryIndex.excludedBindings.get(sourcePath),
+            staticObjectResolver: repositoryIndex.staticObjectResolverFor(sourcePath),
         });
         if (result.status === "refused") {
             refusals.push(...result.refusals);
@@ -1203,11 +1295,23 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
             todos.push(...result.localeTodos);
         }
     }
+    if (repositoryIndex.declarations.length > 0 && repositoryIndex.discoveredCount === 0) {
+        for (const declaration of repositoryIndex.declarations) {
+            refusals.push(refusal(slash(relative(providerRoot, declaration.path)), "<operations>", "no_operations_discovered", `Provider construct ${declaration.construct} declares operations via unresolved initializer ${JSON.stringify(declaration.initializer.getText(declaration.initializer.getSourceFile()))}, but repository-wide discovery found zero operation sites.`));
+        }
+    }
     const todoConflict = findLocaleTodoConflict(todos);
     if (todoConflict !== undefined)
         refusals.push(todoConflict);
     if (refusals.length > 0) {
-        return { status: "refused", providerRoot, refusals };
+        return {
+            status: "refused",
+            providerRoot,
+            refusals,
+            operationCount,
+            changedFiles,
+            localeTodoCount: todos.length,
+        };
     }
     for (const [path, code] of renderLocaleCatalogWrites(providerRoot, todos)) {
         pendingWrites.set(path, code);
@@ -1375,6 +1479,496 @@ function collectLocaleFiles(root) {
         .map((entry) => `locales/${entry.name}`)
         .sort();
 }
+function buildRepositoryOperationIndex(sourceFiles, providerRoot) {
+    const sources = new Map();
+    for (const path of sourceFiles) {
+        const source = parseSource(path, readFileSync(path, "utf8"));
+        if (firstSyntaxError(source) === undefined)
+            sources.set(path, source);
+    }
+    const operationIds = buildOperationIdIndex(sourceFiles);
+    const operationSites = new Map();
+    const excludedBindings = new Map();
+    const refusals = [];
+    const declarations = [];
+    const indexedProviderProperties = new Set();
+    const factoryIds = new Map();
+    const bindingCandidates = new Map();
+    let discoveredCount = 0;
+    const relativePath = (path) => slash(relative(providerRoot, path));
+    const resolutionRefusal = (path, operationKey, detail) => {
+        refusals.push(refusal(relativePath(path), operationKey, "non_literal", detail));
+    };
+    const resolveExport = (path, exportedName, active) => {
+        const key = `${path}\0export\0${exportedName}`;
+        if (active.has(key)) {
+            return {
+                status: "refused",
+                detail: `Static relative export cycle while resolving ${JSON.stringify(exportedName)} from ${relativePath(path)}.`,
+            };
+        }
+        const source = sources.get(path);
+        if (source === undefined)
+            return { status: "missing" };
+        const nextActive = new Set(active);
+        nextActive.add(key);
+        const explicit = [];
+        const exportStars = [];
+        for (const statement of source.statements) {
+            if (ts.isVariableStatement(statement) && hasExportModifier(statement)) {
+                for (const declaration of statement.declarationList.declarations) {
+                    if (ts.isIdentifier(declaration.name) &&
+                        declaration.name.text === exportedName &&
+                        declaration.initializer !== undefined) {
+                        const initializer = declaration.initializer;
+                        const bindingName = declaration.name.text;
+                        explicit.push(() => ({
+                            status: "resolved",
+                            value: {
+                                path,
+                                source,
+                                expression: initializer,
+                                bindingName,
+                            },
+                        }));
+                    }
+                }
+            }
+            if (ts.isExportAssignment(statement) &&
+                !statement.isExportEquals &&
+                exportedName === "default") {
+                explicit.push(() => ({
+                    status: "resolved",
+                    value: { path, source, expression: statement.expression },
+                }));
+            }
+            if (!ts.isExportDeclaration(statement))
+                continue;
+            const specifier = statement.moduleSpecifier !== undefined && ts.isStringLiteral(statement.moduleSpecifier)
+                ? statement.moduleSpecifier.text
+                : undefined;
+            if (statement.exportClause === undefined) {
+                if (specifier !== undefined)
+                    exportStars.push(specifier);
+                continue;
+            }
+            if (!ts.isNamedExports(statement.exportClause))
+                continue;
+            for (const element of statement.exportClause.elements) {
+                if (element.name.text !== exportedName)
+                    continue;
+                const localName = element.propertyName?.text ?? element.name.text;
+                explicit.push(() => {
+                    if (specifier === undefined) {
+                        return resolveIdentifier(path, localName, nextActive);
+                    }
+                    const target = resolveStaticModule(path, specifier, sources);
+                    if (target.status !== "resolved")
+                        return target;
+                    return resolveExport(target.path, localName, nextActive);
+                });
+            }
+        }
+        if (explicit.length > 1) {
+            return {
+                status: "refused",
+                detail: `Export ${JSON.stringify(exportedName)} is ambiguous in ${relativePath(path)}.`,
+            };
+        }
+        if (explicit.length === 1)
+            return explicit[0]?.() ?? { status: "missing" };
+        const resolvedStars = [];
+        let firstStarRefusal;
+        for (const specifier of exportStars) {
+            const target = resolveStaticModule(path, specifier, sources);
+            if (target.status !== "resolved") {
+                if (target.status === "refused")
+                    firstStarRefusal ??= target;
+                continue;
+            }
+            const candidate = resolveExport(target.path, exportedName, nextActive);
+            if (candidate.status === "resolved")
+                resolvedStars.push(candidate.value);
+            else if (candidate.status === "refused")
+                firstStarRefusal ??= candidate;
+        }
+        const origins = new Set(resolvedStars.map((item) => `${item.path}\0${item.expression.getStart(item.source)}`));
+        if (origins.size > 1) {
+            return {
+                status: "refused",
+                detail: `Export ${JSON.stringify(exportedName)} is ambiguous across relative re-exports from ${relativePath(path)}.`,
+            };
+        }
+        if (firstStarRefusal !== undefined)
+            return firstStarRefusal;
+        const resolved = resolvedStars[0];
+        return resolved === undefined ? { status: "missing" } : { status: "resolved", value: resolved };
+    };
+    const resolveIdentifier = (path, name, active) => {
+        const source = sources.get(path);
+        if (source === undefined)
+            return { status: "missing" };
+        for (const statement of source.statements) {
+            if (!ts.isVariableStatement(statement))
+                continue;
+            if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+                continue;
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name) &&
+                    declaration.name.text === name &&
+                    declaration.initializer !== undefined) {
+                    return {
+                        status: "resolved",
+                        value: {
+                            path,
+                            source,
+                            expression: declaration.initializer,
+                            bindingName: name,
+                        },
+                    };
+                }
+            }
+        }
+        for (const statement of source.statements) {
+            if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+                continue;
+            }
+            let exportedName;
+            if (statement.importClause?.name?.text === name)
+                exportedName = "default";
+            const bindings = statement.importClause?.namedBindings;
+            if (bindings !== undefined && ts.isNamedImports(bindings)) {
+                for (const element of bindings.elements) {
+                    if (element.name.text === name) {
+                        exportedName = element.propertyName?.text ?? element.name.text;
+                    }
+                }
+            }
+            if (exportedName === undefined)
+                continue;
+            const specifier = statement.moduleSpecifier.text;
+            const target = resolveStaticModule(path, specifier, sources);
+            if (target.status !== "resolved")
+                return target;
+            return resolveExport(target.path, exportedName, active);
+        }
+        return { status: "missing" };
+    };
+    const resolveLocatedExpression = (located, active) => {
+        const expression = unwrapExpression(located.expression);
+        if (expression === undefined)
+            return { status: "missing" };
+        if (!ts.isIdentifier(expression)) {
+            return { status: "resolved", value: { ...located, expression } };
+        }
+        const key = `${located.path}\0identifier\0${expression.text}`;
+        if (active.has(key)) {
+            return {
+                status: "refused",
+                detail: `Static identifier cycle while resolving ${JSON.stringify(expression.text)} in ${relativePath(located.path)}.`,
+            };
+        }
+        const nextActive = new Set(active);
+        nextActive.add(key);
+        const resolved = resolveIdentifier(located.path, expression.text, nextActive);
+        return resolved.status === "resolved"
+            ? resolveLocatedExpression(resolved.value, nextActive)
+            : resolved;
+    };
+    const flattenRegistry = (locatedInput, active) => {
+        const resolved = resolveLocatedExpression(locatedInput, active);
+        if (resolved.status === "refused")
+            return { detail: resolved.detail };
+        if (resolved.status === "missing") {
+            return {
+                detail: `Operations initializer ${JSON.stringify(locatedInput.expression.getText(locatedInput.source))} is not a static local or relative-imported object.`,
+            };
+        }
+        const expression = unwrapExpression(resolved.value.expression);
+        if (expression === undefined || !ts.isObjectLiteralExpression(expression)) {
+            return {
+                detail: `Operations initializer ${JSON.stringify(resolved.value.expression.getText(resolved.value.source))} is not a static object literal.`,
+            };
+        }
+        const cycleKey = `${resolved.value.path}\0object\0${expression.getStart(resolved.value.source)}`;
+        if (active.has(cycleKey)) {
+            return {
+                detail: `Static operations registry spread cycle reaches ${relativePath(resolved.value.path)}.`,
+            };
+        }
+        const nextActive = new Set(active);
+        nextActive.add(cycleKey);
+        const entries = new Map();
+        for (const property of expression.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                const spread = flattenRegistry({
+                    path: resolved.value.path,
+                    source: resolved.value.source,
+                    expression: property.expression,
+                }, nextActive);
+                if ("detail" in spread)
+                    return spread;
+                for (const [operationId, entry] of spread.entries)
+                    entries.set(operationId, entry);
+                continue;
+            }
+            const operationId = staticPropertyName(property.name);
+            const value = propertyValue(property);
+            if (operationId === undefined) {
+                return {
+                    detail: `Operations registry in ${relativePath(resolved.value.path)} uses a computed key.`,
+                };
+            }
+            if (value === undefined) {
+                return { detail: `Operation ${JSON.stringify(operationId)} has a non-static initializer.` };
+            }
+            entries.set(operationId, {
+                operationId,
+                value: {
+                    path: resolved.value.path,
+                    source: resolved.value.source,
+                    expression: value,
+                },
+            });
+        }
+        return { entries };
+    };
+    const addBindingCandidate = (path, name, operationId) => {
+        const key = `${path}\0${name}`;
+        const candidate = bindingCandidates.get(key) ?? { path, name, ids: new Set() };
+        candidate.ids.add(operationId);
+        bindingCandidates.set(key, candidate);
+    };
+    const addObjectSite = (path, source, object, operationId) => {
+        const sites = operationSites.get(path) ?? new Map();
+        const start = object.getStart(source);
+        const previous = sites.get(start);
+        if (previous !== undefined && previous !== operationId) {
+            resolutionRefusal(path, operationId, `One static operation object is registered under both ${JSON.stringify(previous)} and ${JSON.stringify(operationId)}.`);
+            return;
+        }
+        sites.set(start, operationId);
+        operationSites.set(path, sites);
+        discoveredCount += 1;
+    };
+    const classifyEntry = (entry) => {
+        const resolved = resolveLocatedExpression(entry.value, new Set());
+        if (resolved.status === "refused") {
+            resolutionRefusal(entry.value.path, entry.operationId, resolved.detail);
+            return;
+        }
+        if (resolved.status === "missing") {
+            resolutionRefusal(entry.value.path, entry.operationId, `Operation initializer ${JSON.stringify(entry.value.expression.getText(entry.value.source))} is not statically resolvable.`);
+            return;
+        }
+        const expression = unwrapExpression(resolved.value.expression);
+        if (expression === undefined)
+            return;
+        if (ts.isObjectLiteralExpression(expression)) {
+            addObjectSite(resolved.value.path, resolved.value.source, expression, entry.operationId);
+            return;
+        }
+        if (ts.isCallExpression(expression) && isOperationHelperCall(expression)) {
+            const argument = operationArgument(expression);
+            const object = argument === undefined ? undefined : unwrapExpression(argument);
+            if (object === undefined || !ts.isObjectLiteralExpression(object)) {
+                resolutionRefusal(resolved.value.path, entry.operationId, "Operation helper argument must be a static object literal.");
+                return;
+            }
+            if (resolved.value.bindingName !== undefined) {
+                addBindingCandidate(resolved.value.path, resolved.value.bindingName, entry.operationId);
+            }
+            addObjectSite(resolved.value.path, resolved.value.source, object, entry.operationId);
+            return;
+        }
+        if (ts.isCallExpression(expression) &&
+            ts.isIdentifier(expression.expression) &&
+            collectSimpleOperationFactories(resolved.value.source).has(expression.expression.text)) {
+            const name = expression.expression.text;
+            const key = `${resolved.value.path}\0${name}`;
+            const factory = factoryIds.get(key) ?? {
+                path: resolved.value.path,
+                name,
+                ids: new Set(),
+            };
+            factory.ids.add(entry.operationId);
+            factoryIds.set(key, factory);
+            discoveredCount += 1;
+            return;
+        }
+        resolutionRefusal(resolved.value.path, entry.operationId, `Operation initializer ${JSON.stringify(expression.getText(resolved.value.source))} is not a raw object, operation helper, or simple same-file factory call.`);
+    };
+    const inspectProviderProperty = (path, source, node, construct) => {
+        const key = `${path}\0${node.getStart(source)}`;
+        if (indexedProviderProperties.has(key))
+            return;
+        indexedProviderProperties.add(key);
+        declarations.push({ path, construct, initializer: node.initializer });
+        const flattened = flattenRegistry({ path, source, expression: node.initializer }, new Set());
+        if ("detail" in flattened) {
+            resolutionRefusal(path, "<operations>", flattened.detail);
+        }
+        else {
+            for (const entry of flattened.entries.values())
+                classifyEntry(entry);
+        }
+    };
+    for (const [path, source] of sources) {
+        const constObjects = collectModuleConstObjects(source);
+        const visit = (node) => {
+            if (ts.isPropertyAssignment(node) &&
+                staticPropertyName(node.name) === "operations" &&
+                isProviderOperationsProperty(node, constObjects)) {
+                inspectProviderProperty(path, source, node, providerConstructName(node));
+            }
+            if (ts.isCallExpression(node)) {
+                const construct = providerCallConstruct(node);
+                if (construct !== undefined) {
+                    for (const argument of node.arguments) {
+                        const resolved = resolveLocatedExpression({ path, source, expression: argument }, new Set());
+                        if (resolved.status !== "resolved")
+                            continue;
+                        const object = unwrapExpression(resolved.value.expression);
+                        if (object === undefined || !ts.isObjectLiteralExpression(object))
+                            continue;
+                        for (const property of object.properties) {
+                            if (ts.isPropertyAssignment(property) &&
+                                staticPropertyName(property.name) === "operations") {
+                                inspectProviderProperty(resolved.value.path, resolved.value.source, property, construct);
+                            }
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    for (const candidate of bindingCandidates.values()) {
+        const ids = [...candidate.ids];
+        const indexed = operationIds.get(candidate.path) ?? new Map();
+        if (ids.length === 1) {
+            const operationId = ids[0];
+            if (operationId !== undefined)
+                indexed.set(candidate.name, operationId);
+        }
+        else {
+            indexed.delete(candidate.name);
+            const excluded = excludedBindings.get(candidate.path) ?? new Set();
+            excluded.add(candidate.name);
+            excludedBindings.set(candidate.path, excluded);
+        }
+        operationIds.set(candidate.path, indexed);
+    }
+    for (const factory of factoryIds.values()) {
+        const indexed = operationIds.get(factory.path) ?? new Map();
+        const ids = [...factory.ids];
+        if (ids.length === 1) {
+            const operationId = ids[0];
+            if (operationId !== undefined)
+                indexed.set(factory.name, operationId);
+        }
+        else {
+            indexed.delete(factory.name);
+            const excluded = excludedBindings.get(factory.path) ?? new Set();
+            excluded.add(factory.name);
+            excludedBindings.set(factory.path, excluded);
+            refusals.push(refusal(relativePath(factory.path), factory.name, "factory_operation_id_ambiguous", `Factory ${factory.name} is registered under multiple operation ids: ${ids
+                .map((id) => JSON.stringify(id))
+                .join(", ")}. A shared operation body cannot own one examples locale namespace.`));
+        }
+        operationIds.set(factory.path, indexed);
+    }
+    const resolveStaticObject = (expressionInput, path, active = new Set()) => {
+        const expression = unwrapExpression(expressionInput);
+        if (expression === undefined)
+            return undefined;
+        if (ts.isObjectLiteralExpression(expression)) {
+            const source = sources.get(path) ?? expression.getSourceFile();
+            return { object: expression, source };
+        }
+        if (ts.isIdentifier(expression)) {
+            const key = `${path}\0member\0${expression.text}`;
+            if (active.has(key))
+                return undefined;
+            const nextActive = new Set(active);
+            nextActive.add(key);
+            const resolved = resolveIdentifier(path, expression.text, nextActive);
+            return resolved.status === "resolved"
+                ? resolveStaticObject(resolved.value.expression, resolved.value.path, nextActive)
+                : undefined;
+        }
+        if (ts.isPropertyAccessExpression(expression)) {
+            const owner = resolveStaticObject(expression.expression, path, active);
+            if (owner === undefined)
+                return undefined;
+            for (const property of owner.object.properties) {
+                if (ts.isSpreadAssignment(property))
+                    continue;
+                if (staticPropertyName(property.name) !== expression.name.text)
+                    continue;
+                const value = propertyValue(property);
+                if (value === undefined)
+                    return undefined;
+                return resolveStaticObject(value, owner.source.fileName, active);
+            }
+        }
+        return undefined;
+    };
+    return {
+        operationIds,
+        operationSites,
+        excludedBindings,
+        refusals,
+        declarations,
+        discoveredCount,
+        staticObjectResolverFor: (currentPath) => (expression, source) => resolveStaticObject(expression, sources.has(source.fileName) ? source.fileName : currentPath),
+    };
+}
+function hasExportModifier(node) {
+    return (ts.canHaveModifiers(node) &&
+        ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ===
+            true);
+}
+function resolveStaticModule(containingPath, specifier, sources) {
+    if (!specifier.startsWith(".")) {
+        return {
+            status: "refused",
+            detail: `Static operation discovery refuses non-relative import ${JSON.stringify(specifier)}.`,
+        };
+    }
+    const path = resolveLocalModule(containingPath, specifier, sources);
+    if (path === undefined) {
+        return {
+            status: "refused",
+            detail: `Static relative import ${JSON.stringify(specifier)} from ${containingPath} could not be resolved.`,
+        };
+    }
+    return { status: "resolved", path };
+}
+function providerConstructName(node) {
+    let current = node;
+    while (current.parent !== undefined) {
+        const parent = current.parent;
+        if (ts.isCallExpression(parent)) {
+            return providerCallConstruct(parent) ?? parent.expression.getText();
+        }
+        current = parent;
+    }
+    return "provider declaration";
+}
+function providerCallConstruct(call) {
+    if (ts.isIdentifier(call.expression) &&
+        /(?:defineProvider|Provider)\b/.test(call.expression.text)) {
+        return call.expression.text;
+    }
+    if (ts.isCallExpression(call.expression) &&
+        ts.isIdentifier(call.expression.expression) &&
+        /\bdefineProvider\b/.test(call.expression.expression.text)) {
+        return call.expression.expression.text;
+    }
+    return undefined;
+}
 function buildOperationIdIndex(sourceFiles) {
     const result = new Map();
     const idsByPath = new Map();
@@ -1556,7 +2150,12 @@ function resolveLocalModule(containingPath, specifier, sources) {
     if (!specifier.startsWith("."))
         return undefined;
     const base = resolve(dirname(containingPath), specifier);
-    for (const candidate of [base, `${base}.ts`, join(base, "index.ts")]) {
+    const emittedExtensionSource = /\.(?:c|m)?js$/.test(base)
+        ? base.replace(/\.(?:c|m)?js$/, ".ts")
+        : undefined;
+    for (const candidate of [base, emittedExtensionSource, `${base}.ts`, join(base, "index.ts")]) {
+        if (candidate === undefined)
+            continue;
         if (sources.has(candidate))
             return candidate;
     }