@apifuse/provider-sdk 2.2.0-beta.50 → 2.2.0-beta.52

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.52
+
+- Release candidate for main commit 6e64ae0ad2e735b3de0c115f5ea29517efcf4ff2.
+
+## 2.2.0-beta.51
+
+- Release candidate for main commit a1269b0a7161618e5fc25e532aaa45de0efd632f.
+
 ## 2.2.0-beta.50
 
 - Release candidate for main commit 341c2f0e55a4159cac423fec0bf4f84625191731.

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

@@ -62,6 +62,7 @@ export function migrateOperationDeclaration(sourceText, fileName, options = {})
         };
     }
     const constObjects = collectModuleConstObjects(source);
+    const constArrays = collectModuleConstArrays(source);
     const discovery = discoverOperationSites(source, fileName, constObjects, options.operationIds);
     if (discovery.refusals.length > 0) {
         return { status: "refused", refusals: discovery.refusals };
@@ -70,7 +71,7 @@ export function migrateOperationDeclaration(sourceText, fileName, options = {})
     const todos = [];
     const refusals = [];
     for (const site of discovery.sites) {
-        const plan = planOperationMigration(source, fileName, site, constObjects, options.localeFiles ?? []);
+        const plan = planOperationMigration(source, fileName, site, constObjects, constArrays, options.localeFiles ?? []);
         if ("refusal" in plan) {
             refusals.push(plan.refusal);
             continue;
@@ -87,7 +88,11 @@ export function migrateOperationDeclaration(sourceText, fileName, options = {})
             operations: discovery.sites.length,
         };
     }
-    const code = applyEdits(sourceText, edits);
+    const normalizedEdits = normalizeEdits(edits, fileName);
+    if ("refusal" in normalizedEdits) {
+        return { status: "refused", refusals: [normalizedEdits.refusal] };
+    }
+    const code = applyEdits(sourceText, normalizedEdits.edits);
     const outputRefusal = verifyOperationDeclarationRewrite(code, fileName);
     if (outputRefusal !== undefined) {
         return {
@@ -109,7 +114,7 @@ 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, localeFiles) {
+function planOperationMigration(source, fileName, site, constObjects, constArrays, localeFiles) {
     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."),
@@ -216,7 +221,7 @@ function planOperationMigration(source, fileName, site, constObjects, localeFile
         if (merged.insert !== undefined)
             addInsertion(insertions, "docs", merged.insert);
     }
-    const examples = planExamples(top.byName.get("inputExamples"), top.byName.get("examples"), fileName, site, source, localeFiles);
+    const examples = planExamples(top.byName.get("inputExamples"), top.byName.get("examples"), fileName, site, source, constArrays, localeFiles);
     if ("refusal" in examples)
         return examples;
     const edits = [...examples.edits];
@@ -376,7 +381,7 @@ function mergeFlatAndNested(field, flat, nested, fileName, operationKey, source,
     }
     return {};
 }
-function planExamples(inputExamples, existingExamples, fileName, site, source, localeFiles) {
+function planExamples(inputExamples, existingExamples, fileName, site, source, constArrays, localeFiles) {
     if (inputExamples === undefined)
         return { edits: [], localeTodos: [] };
     if (existingExamples !== undefined) {
@@ -388,12 +393,15 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, l
     if (array === undefined || !ts.isArrayLiteralExpression(array)) {
         return nonLiteral(fileName, site.operationKey, "inputExamples must be an array literal.");
     }
-    if (array.elements.length > 0 && !site.operationIdProven) {
+    const expanded = expandArrayElements(array, constArrays, fileName, site.operationKey);
+    if ("refusal" in expanded)
+        return expanded;
+    if (expanded.elements.length > 0 && !site.operationIdProven) {
         return {
             refusal: refusal(fileName, site.operationKey, "operation_id_unresolved", "inputExamples requires an exact operation id proven from a static operations map."),
         };
     }
-    if (array.elements.length > 0 && !localeFiles.includes("locales/en.json")) {
+    if (expanded.elements.length > 0 && !localeFiles.includes("locales/en.json")) {
         return {
             refusal: refusal(fileName, site.operationKey, "missing_english_locale", "inputExamples cannot be migrated because locales/en.json does not exist."),
         };
@@ -409,8 +417,8 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, l
         end: propertyNameNode.getEnd(),
         text: "examples",
     });
-    for (let index = 0; index < array.elements.length; index += 1) {
-        const element = array.elements[index];
+    for (let index = 0; index < expanded.elements.length; index += 1) {
+        const element = expanded.elements[index];
         const object = element === undefined ? undefined : unwrapExpression(element);
         if (object === undefined || !ts.isObjectLiteralExpression(object)) {
             return nonLiteral(fileName, site.operationKey, `inputExamples[${index}] must be an object literal.`);
@@ -696,6 +704,51 @@ function collectModuleConstObjects(source) {
     }
     return objects;
 }
+function collectModuleConstArrays(source) {
+    const arrays = new Map();
+    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.initializer === undefined)
+                continue;
+            const expression = unwrapExpression(declaration.initializer);
+            if (expression !== undefined && ts.isArrayLiteralExpression(expression)) {
+                arrays.set(declaration.name.text, expression);
+            }
+        }
+    }
+    return arrays;
+}
+function expandArrayElements(array, constArrays, fileName, operationKey, seen = new Set()) {
+    if (seen.has(array)) {
+        return nonLiteral(fileName, operationKey, "A module-level array spread is recursive.");
+    }
+    seen.add(array);
+    const elements = [];
+    for (const element of array.elements) {
+        if (!ts.isSpreadElement(element)) {
+            elements.push(element);
+            continue;
+        }
+        const expression = unwrapExpression(element.expression);
+        const spreadArray = expression !== undefined && ts.isArrayLiteralExpression(expression)
+            ? expression
+            : expression !== undefined && ts.isIdentifier(expression)
+                ? constArrays.get(expression.text)
+                : undefined;
+        if (spreadArray === undefined) {
+            return nonLiteral(fileName, operationKey, "inputExamples contains an unresolved array spread.");
+        }
+        const expanded = expandArrayElements(spreadArray, constArrays, fileName, operationKey, new Set(seen));
+        if ("refusal" in expanded)
+            return expanded;
+        elements.push(...expanded.elements);
+    }
+    return { elements };
+}
 function expandMembers(object, constObjects, fileName, operationKey, seen = new Set()) {
     if (seen.has(object)) {
         return nonLiteral(fileName, operationKey, "A module-level object spread is recursive.");
@@ -929,6 +982,21 @@ function applyEdits(sourceText, edits) {
     }
     return code;
 }
+function normalizeEdits(edits, fileName) {
+    const unique = new Map();
+    for (const edit of edits) {
+        const key = `${edit.start}:${edit.end}`;
+        const previous = unique.get(key);
+        if (previous === undefined) {
+            unique.set(key, edit);
+            continue;
+        }
+        if (previous.text !== edit.text) {
+            return nonLiteral(fileName, "<shared>", "A module-level input examples array is shared by operations that need different locale keys.");
+        }
+    }
+    return { edits: [...unique.values()] };
+}
 function indentationAt(text, position) {
     const lineStart = text.lastIndexOf("\n", position - 1) + 1;
     return text.slice(lineStart, position).match(/^\s*/)?.[0] ?? "";
@@ -1020,6 +1088,9 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
     if (refusals.length > 0) {
         return { status: "refused", providerRoot, refusals };
     }
+    for (const [path, code] of renderLocaleCatalogWrites(providerRoot, todos)) {
+        pendingWrites.set(path, code);
+    }
     if (pendingWrites.size === 0) {
         return {
             status: "unchanged",
@@ -1054,6 +1125,89 @@ export function renderLocaleTodoSidecar(todos) {
     }
     return `${JSON.stringify({ schemaVersion: 1, localeFiles }, null, 2)}\n`;
 }
+function renderLocaleCatalogWrites(providerRoot, todos) {
+    const todosByFile = new Map();
+    for (const todo of todos) {
+        const fileTodos = todosByFile.get(todo.localeFile) ?? [];
+        fileTodos.push(todo);
+        todosByFile.set(todo.localeFile, fileTodos);
+    }
+    const englishPath = "locales/en.json";
+    const englishTodos = todosByFile.get(englishPath);
+    if (englishTodos === undefined)
+        return new Map();
+    const english = readLocaleCatalog(join(providerRoot, englishPath));
+    applyLocaleTodos(english, englishTodos);
+    const writes = new Map([
+        [join(providerRoot, englishPath), renderCanonicalLocaleCatalog(english)],
+    ]);
+    for (const [localeFile, fileTodos] of todosByFile) {
+        if (localeFile === englishPath)
+            continue;
+        const catalog = readLocaleCatalog(join(providerRoot, localeFile));
+        applyLocaleTodos(catalog, fileTodos);
+        writes.set(join(providerRoot, localeFile), renderCanonicalLocaleCatalog(reorderLikeReference(english, catalog)));
+    }
+    return writes;
+}
+function readLocaleCatalog(path) {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    if (!isRecord(value))
+        throw new Error(`${path} must contain a JSON object.`);
+    return value;
+}
+function applyLocaleTodos(catalog, todos) {
+    for (const todo of todos) {
+        const segments = todo.key.split(".");
+        const leaf = segments.pop();
+        if (leaf === undefined)
+            continue;
+        let cursor = catalog;
+        for (const segment of segments) {
+            const child = cursor[segment];
+            if (isRecord(child)) {
+                cursor = child;
+                continue;
+            }
+            const created = {};
+            cursor[segment] = created;
+            cursor = created;
+        }
+        cursor[leaf] = todo.originalProse;
+    }
+}
+/** Match provider-contract's canonical locale serialization exactly. */
+function renderCanonicalLocaleCatalog(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/**
+ * Put shared keys first in English order, then retain locale-only authored order.
+ * Arrays keep their shape and use the English item at the same index as a reference.
+ */
+function reorderLikeReference(reference, value) {
+    if (Array.isArray(value)) {
+        const referenceArray = Array.isArray(reference) ? reference : [];
+        return value.map((item, index) => reorderLikeReference(referenceArray[index], item));
+    }
+    if (!isRecord(value))
+        return value;
+    const referenceRecord = isRecord(reference) ? reference : {};
+    const ordered = {};
+    for (const key of Object.keys(referenceRecord)) {
+        if (Object.hasOwn(value, key)) {
+            ordered[key] = reorderLikeReference(referenceRecord[key], value[key]);
+        }
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (!Object.hasOwn(ordered, key)) {
+            ordered[key] = reorderLikeReference(Object.hasOwn(referenceRecord, key) ? referenceRecord[key] : undefined, child);
+        }
+    }
+    return ordered;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function findLocaleTodoConflict(todos) {
     const values = new Map();
     for (const todo of todos) {
@@ -1075,7 +1229,10 @@ function collectSourceFiles(root) {
             if (entry.isDirectory()) {
                 if (SOURCE_SKIP_DIRECTORIES.has(entry.name))
                     continue;
-                walk(join(directory, entry.name));
+                const child = join(directory, entry.name);
+                if (existsSync(join(child, ".git")))
+                    continue;
+                walk(child);
                 continue;
             }
             if (!entry.name.endsWith(".ts"))
@@ -1099,6 +1256,8 @@ function collectLocaleFiles(root) {
 }
 function buildOperationIdIndex(sourceFiles) {
     const result = new Map();
+    const idsByPath = new Map();
+    const ambiguousBindingsByPath = new Map();
     const sources = new Map();
     for (const path of sourceFiles) {
         const source = parseSource(path, readFileSync(path, "utf8"));
@@ -1107,12 +1266,38 @@ function buildOperationIdIndex(sourceFiles) {
     }
     const record = (path, binding, operationId) => {
         const map = result.get(path) ?? new Map();
-        const previous = map.get(binding);
-        if (previous === undefined || previous === operationId)
-            map.set(binding, operationId);
-        else
+        const ids = idsByPath.get(path) ?? new Map();
+        const ambiguousBindings = ambiguousBindingsByPath.get(path) ?? new Set();
+        // An operation id is usable only when it identifies exactly one binding.
+        // Keep an explicit null marker for an ambiguous id so a later occurrence
+        // cannot accidentally make it usable again.
+        const previousBinding = ids.get(operationId);
+        if (ids.has(operationId)) {
+            if (previousBinding !== undefined &&
+                previousBinding !== null &&
+                previousBinding !== binding) {
+                map.delete(previousBinding);
+                map.delete(binding);
+                ambiguousBindings.add(previousBinding);
+                ambiguousBindings.add(binding);
+                ids.set(operationId, null);
+            }
+        }
+        else {
+            ids.set(operationId, binding);
+        }
+        // A binding registered under two different ids is likewise ambiguous.
+        const previousId = map.get(binding);
+        if (previousId !== undefined && previousId !== operationId) {
             map.delete(binding);
+            ambiguousBindings.add(binding);
+        }
+        else if (!ambiguousBindings.has(binding) && ids.get(operationId) === binding) {
+            map.set(binding, operationId);
+        }
         result.set(path, map);
+        idsByPath.set(path, ids);
+        ambiguousBindingsByPath.set(path, ambiguousBindings);
     };
     for (const [path, source] of sources) {
         const imports = collectImports(source, path, sources);
@@ -1135,9 +1320,92 @@ function buildOperationIdIndex(sourceFiles) {
                     record(imported.path, imported.exportedName, operationId);
             }
         }
+        // Some providers keep their operation registry in a same-file const with
+        // an arbitrary name (for example, `companionsOperations`). This scan is
+        // deliberately ID-only: it accepts only static object members whose value
+        // is a same-file operation binding, and never evaluates spreads, factories,
+        // or imported values.
+        const operationBindings = collectModuleOperationBindings(source);
+        const importedBindings = collectImportedBindingNames(source);
+        for (const entry of collectStaticOperationRegistryEntries(source, operationBindings)) {
+            if (importedBindings.has(entry.binding))
+                continue;
+            record(path, entry.binding, entry.operationId);
+        }
     }
     return result;
 }
+function collectModuleOperationBindings(source) {
+    const bindings = new Set();
+    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.initializer === undefined)
+                continue;
+            const initializer = unwrapExpression(declaration.initializer);
+            if (initializer !== undefined &&
+                ts.isCallExpression(initializer) &&
+                isOperationHelperCall(initializer)) {
+                bindings.add(declaration.name.text);
+            }
+        }
+    }
+    return bindings;
+}
+function collectImportedBindingNames(source) {
+    const bindings = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const clause = statement.importClause;
+        if (clause?.name !== undefined)
+            bindings.add(clause.name.text);
+        const named = clause?.namedBindings;
+        if (named === undefined)
+            continue;
+        if (ts.isNamespaceImport(named)) {
+            bindings.add(named.name.text);
+            continue;
+        }
+        for (const element of named.elements)
+            bindings.add(element.name.text);
+    }
+    return bindings;
+}
+function collectStaticOperationRegistryEntries(source, operationBindings) {
+    const entries = [];
+    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.initializer === undefined)
+                continue;
+            const object = unwrapExpression(declaration.initializer);
+            if (object === undefined || !ts.isObjectLiteralExpression(object))
+                continue;
+            for (const property of object.properties) {
+                if (ts.isSpreadAssignment(property))
+                    continue;
+                const name = property.name;
+                if (name === undefined || (!ts.isIdentifier(name) && !ts.isStringLiteral(name)))
+                    continue;
+                const value = propertyValue(property);
+                const binding = unwrapExpression(value);
+                if (binding === undefined || !ts.isIdentifier(binding))
+                    continue;
+                if (!operationBindings.has(binding.text))
+                    continue;
+                entries.push({ operationId: name.text, binding: binding.text });
+            }
+        }
+    }
+    return entries;
+}
 function collectImports(source, containingPath, sources) {
     const imports = new Map();
     for (const statement of source.statements) {

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.50",
+	"version": "2.2.0-beta.52",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-hoisted-array-spread.ts.txt

@@ -0,0 +1,15 @@
+const LIST_INPUT_EXAMPLES = [
+	{
+		scenario: "List a full year",
+		rationale: "Shows the common calendar query",
+		input: { year: 2026 },
+	},
+] as const;
+
+const listOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [...LIST_INPUT_EXAMPLES],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-imported-array-spread.ts.txt

@@ -0,0 +1,9 @@
+import { LIST_INPUT_EXAMPLES } from "./shared.js";
+
+const importedExamplesOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [...LIST_INPUT_EXAMPLES],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-mixed-array-spread.ts.txt

@@ -0,0 +1,24 @@
+const SHARED_INPUT_EXAMPLES = [
+	{
+		scenario: "Shared middle example",
+		input: { page: 2 },
+	},
+] as const;
+
+const mixedOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [
+		{
+			scenario: "Literal first example",
+			input: { page: 1 },
+		},
+		...SHARED_INPUT_EXAMPLES,
+		{
+			scenario: "Literal last example",
+			input: { page: 3 },
+		},
+	],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-en.json

@@ -0,0 +1 @@
+{"meta":{"displayName":"Canonical fixture"},"operations":{"alpha":{"title":"Alpha"},"search":{"description":"English description","title":"English title","steps":[{"first":"one","second":"two"}]},"omega":{"title":"Omega"}},"tail":"English tail","enOnly":"Keep this last"}

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-ja.json

@@ -0,0 +1 @@
+{"jaOnlyFirst":"最初","operations":{"search":{"steps":[{"second":"二","first":"一"}],"title":"検索","jaOnly":"順序を保持","description":"日本語の説明"},"omega":{"title":"オメガ"},"jaOnlyOperation":{"title":"日本語のみ"},"alpha":{"title":"アルファ"}},"tail":"日本語の末尾","meta":{"displayName":"正規 fixture"},"jaOnlyLast":"最後"}

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-ko.json

@@ -0,0 +1 @@
+{"koOnlyFirst":"첫 번째","tail":"한국어 꼬리말","operations":{"omega":{"title":"오메가"},"search":{"title":"검색","steps":[{"second":"둘","first":"하나"}],"description":"한국어 설명","koOnly":"순서 유지"},"alpha":{"title":"알파"},"koOnlyOperation":{"title":"한국어 전용"}},"meta":{"displayName":"정규 fixture"},"koOnlyLast":"마지막"}

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-binding-ambiguous.ts.txt

@@ -0,0 +1,12 @@
+const operation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Ambiguous", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const registry = {
+	first: operation,
+	second: operation,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-imported-other.ts.txt

@@ -0,0 +1,7 @@
+export const importedOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Imported", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-imported.ts.txt

@@ -0,0 +1,5 @@
+import { importedOperation } from "./other";
+
+const registry = {
+	imported: importedOperation,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-key-ambiguous.ts.txt

@@ -0,0 +1,19 @@
+const firstOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "First", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+const secondOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Second", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const registry = {
+	shared: firstOperation,
+	"shared": secondOperation,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-shorthand.ts.txt

@@ -0,0 +1,9 @@
+const searchOperation = defineStreamOperation({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Search", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const arbitraryRegistry = { searchOperation };

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-typed.ts.txt

@@ -0,0 +1,11 @@
+const permissionsRevoke = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Revoke permissions", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+export const companionsOperations: Record<string, OperationDefinition> = {
+	"permissions-revoke": permissionsRevoke,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-unrelated.ts.txt

@@ -0,0 +1,13 @@
+const detailOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Detail", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const unrelated = {
+	detail: detailOperation,
+	count: 42,
+	created: makeValue(),
+};

package/src/cli/migrate-operation-declaration.ts

@@ -154,6 +154,7 @@ export function migrateOperationDeclaration(
 	}
 
 	const constObjects = collectModuleConstObjects(source);
+	const constArrays = collectModuleConstArrays(source);
 	const discovery = discoverOperationSites(source, fileName, constObjects, options.operationIds);
 	if (discovery.refusals.length > 0) {
 		return { status: "refused", refusals: discovery.refusals };
@@ -168,6 +169,7 @@ export function migrateOperationDeclaration(
 			fileName,
 			site,
 			constObjects,
+			constArrays,
 			options.localeFiles ?? [],
 		);
 		if ("refusal" in plan) {
@@ -187,7 +189,12 @@ export function migrateOperationDeclaration(
 		};
 	}
 
-	const code = applyEdits(sourceText, edits);
+	const normalizedEdits = normalizeEdits(edits, fileName);
+	if ("refusal" in normalizedEdits) {
+		return { status: "refused", refusals: [normalizedEdits.refusal] };
+	}
+
+	const code = applyEdits(sourceText, normalizedEdits.edits);
 	const outputRefusal = verifyOperationDeclarationRewrite(code, fileName);
 	if (outputRefusal !== undefined) {
 		return {
@@ -224,6 +231,7 @@ function planOperationMigration(
 	fileName: string,
 	site: OperationSite,
 	constObjects: ReadonlyMap<string, TS.ObjectLiteralExpression>,
+	constArrays: ReadonlyMap<string, TS.ArrayLiteralExpression>,
 	localeFiles: readonly string[],
 ): PlannedOperation | { readonly refusal: OperationDeclarationRefusal } {
 	if (site.object.properties.some(ts.isSpreadAssignment)) {
@@ -398,6 +406,7 @@ function planOperationMigration(
 		fileName,
 		site,
 		source,
+		constArrays,
 		localeFiles,
 	);
 	if ("refusal" in examples) return examples;
@@ -653,6 +662,7 @@ function planExamples(
 	fileName: string,
 	site: OperationSite,
 	source: TS.SourceFile,
+	constArrays: ReadonlyMap<string, TS.ArrayLiteralExpression>,
 	localeFiles: readonly string[],
 ):
 	| { readonly edits: readonly TextEdit[]; readonly localeTodos: readonly LocaleTodo[] }
@@ -672,7 +682,9 @@ function planExamples(
 	if (array === undefined || !ts.isArrayLiteralExpression(array)) {
 		return nonLiteral(fileName, site.operationKey, "inputExamples must be an array literal.");
 	}
-	if (array.elements.length > 0 && !site.operationIdProven) {
+	const expanded = expandArrayElements(array, constArrays, fileName, site.operationKey);
+	if ("refusal" in expanded) return expanded;
+	if (expanded.elements.length > 0 && !site.operationIdProven) {
 		return {
 			refusal: refusal(
 				fileName,
@@ -682,7 +694,7 @@ function planExamples(
 			),
 		};
 	}
-	if (array.elements.length > 0 && !localeFiles.includes("locales/en.json")) {
+	if (expanded.elements.length > 0 && !localeFiles.includes("locales/en.json")) {
 		return {
 			refusal: refusal(
 				fileName,
@@ -709,8 +721,8 @@ function planExamples(
 		text: "examples",
 	});
 
-	for (let index = 0; index < array.elements.length; index += 1) {
-		const element = array.elements[index];
+	for (let index = 0; index < expanded.elements.length; index += 1) {
+		const element = expanded.elements[index];
 		const object = element === undefined ? undefined : unwrapExpression(element);
 		if (object === undefined || !ts.isObjectLiteralExpression(object)) {
 			return nonLiteral(
@@ -1070,6 +1082,66 @@ function collectModuleConstObjects(source: TS.SourceFile): Map<string, TS.Object
 	return objects;
 }
 
+function collectModuleConstArrays(source: TS.SourceFile): Map<string, TS.ArrayLiteralExpression> {
+	const arrays = new Map<string, TS.ArrayLiteralExpression>();
+	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.initializer === undefined) continue;
+			const expression = unwrapExpression(declaration.initializer);
+			if (expression !== undefined && ts.isArrayLiteralExpression(expression)) {
+				arrays.set(declaration.name.text, expression);
+			}
+		}
+	}
+	return arrays;
+}
+
+function expandArrayElements(
+	array: TS.ArrayLiteralExpression,
+	constArrays: ReadonlyMap<string, TS.ArrayLiteralExpression>,
+	fileName: string,
+	operationKey: string,
+	seen = new Set<TS.ArrayLiteralExpression>(),
+): { readonly elements: TS.Expression[] } | { readonly refusal: OperationDeclarationRefusal } {
+	if (seen.has(array)) {
+		return nonLiteral(fileName, operationKey, "A module-level array spread is recursive.");
+	}
+	seen.add(array);
+	const elements: TS.Expression[] = [];
+	for (const element of array.elements) {
+		if (!ts.isSpreadElement(element)) {
+			elements.push(element);
+			continue;
+		}
+		const expression = unwrapExpression(element.expression);
+		const spreadArray =
+			expression !== undefined && ts.isArrayLiteralExpression(expression)
+				? expression
+				: expression !== undefined && ts.isIdentifier(expression)
+					? constArrays.get(expression.text)
+					: undefined;
+		if (spreadArray === undefined) {
+			return nonLiteral(
+				fileName,
+				operationKey,
+				"inputExamples contains an unresolved array spread.",
+			);
+		}
+		const expanded = expandArrayElements(
+			spreadArray,
+			constArrays,
+			fileName,
+			operationKey,
+			new Set(seen),
+		);
+		if ("refusal" in expanded) return expanded;
+		elements.push(...expanded.elements);
+	}
+	return { elements };
+}
+
 function expandMembers(
 	object: TS.ObjectLiteralExpression,
 	constObjects: ReadonlyMap<string, TS.ObjectLiteralExpression>,
@@ -1357,6 +1429,29 @@ function applyEdits(sourceText: string, edits: readonly TextEdit[]): string {
 	return code;
 }
 
+function normalizeEdits(
+	edits: readonly TextEdit[],
+	fileName: string,
+): { readonly edits: readonly TextEdit[] } | { readonly refusal: OperationDeclarationRefusal } {
+	const unique = new Map<string, TextEdit>();
+	for (const edit of edits) {
+		const key = `${edit.start}:${edit.end}`;
+		const previous = unique.get(key);
+		if (previous === undefined) {
+			unique.set(key, edit);
+			continue;
+		}
+		if (previous.text !== edit.text) {
+			return nonLiteral(
+				fileName,
+				"<shared>",
+				"A module-level input examples array is shared by operations that need different locale keys.",
+			);
+		}
+	}
+	return { edits: [...unique.values()] };
+}
+
 function indentationAt(text: string, position: number): string {
 	const lineStart = text.lastIndexOf("\n", position - 1) + 1;
 	return text.slice(lineStart, position).match(/^\s*/)?.[0] ?? "";
@@ -1481,6 +1576,9 @@ export function migrateOperationDeclarationRepository(
 	if (refusals.length > 0) {
 		return { status: "refused", providerRoot, refusals };
 	}
+	for (const [path, code] of renderLocaleCatalogWrites(providerRoot, todos)) {
+		pendingWrites.set(path, code);
+	}
 
 	if (pendingWrites.size === 0) {
 		return {
@@ -1521,6 +1619,103 @@ export function renderLocaleTodoSidecar(todos: readonly LocaleTodo[]): string {
 	return `${JSON.stringify({ schemaVersion: 1, localeFiles }, null, 2)}\n`;
 }
 
+function renderLocaleCatalogWrites(
+	providerRoot: string,
+	todos: readonly LocaleTodo[],
+): Map<string, string> {
+	const todosByFile = new Map<string, LocaleTodo[]>();
+	for (const todo of todos) {
+		const fileTodos = todosByFile.get(todo.localeFile) ?? [];
+		fileTodos.push(todo);
+		todosByFile.set(todo.localeFile, fileTodos);
+	}
+
+	const englishPath = "locales/en.json";
+	const englishTodos = todosByFile.get(englishPath);
+	if (englishTodos === undefined) return new Map();
+
+	const english = readLocaleCatalog(join(providerRoot, englishPath));
+	applyLocaleTodos(english, englishTodos);
+	const writes = new Map<string, string>([
+		[join(providerRoot, englishPath), renderCanonicalLocaleCatalog(english)],
+	]);
+
+	for (const [localeFile, fileTodos] of todosByFile) {
+		if (localeFile === englishPath) continue;
+		const catalog = readLocaleCatalog(join(providerRoot, localeFile));
+		applyLocaleTodos(catalog, fileTodos);
+		writes.set(
+			join(providerRoot, localeFile),
+			renderCanonicalLocaleCatalog(reorderLikeReference(english, catalog)),
+		);
+	}
+	return writes;
+}
+
+function readLocaleCatalog(path: string): Record<string, unknown> {
+	const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+	if (!isRecord(value)) throw new Error(`${path} must contain a JSON object.`);
+	return value;
+}
+
+function applyLocaleTodos(catalog: Record<string, unknown>, todos: readonly LocaleTodo[]): void {
+	for (const todo of todos) {
+		const segments = todo.key.split(".");
+		const leaf = segments.pop();
+		if (leaf === undefined) continue;
+		let cursor = catalog;
+		for (const segment of segments) {
+			const child = cursor[segment];
+			if (isRecord(child)) {
+				cursor = child;
+				continue;
+			}
+			const created: Record<string, unknown> = {};
+			cursor[segment] = created;
+			cursor = created;
+		}
+		cursor[leaf] = todo.originalProse;
+	}
+}
+
+/** Match provider-contract's canonical locale serialization exactly. */
+function renderCanonicalLocaleCatalog(value: unknown): string {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/**
+ * Put shared keys first in English order, then retain locale-only authored order.
+ * Arrays keep their shape and use the English item at the same index as a reference.
+ */
+function reorderLikeReference(reference: unknown, value: unknown): unknown {
+	if (Array.isArray(value)) {
+		const referenceArray = Array.isArray(reference) ? reference : [];
+		return value.map((item, index) => reorderLikeReference(referenceArray[index], item));
+	}
+	if (!isRecord(value)) return value;
+
+	const referenceRecord = isRecord(reference) ? reference : {};
+	const ordered: Record<string, unknown> = {};
+	for (const key of Object.keys(referenceRecord)) {
+		if (Object.hasOwn(value, key)) {
+			ordered[key] = reorderLikeReference(referenceRecord[key], value[key]);
+		}
+	}
+	for (const [key, child] of Object.entries(value)) {
+		if (!Object.hasOwn(ordered, key)) {
+			ordered[key] = reorderLikeReference(
+				Object.hasOwn(referenceRecord, key) ? referenceRecord[key] : undefined,
+				child,
+			);
+		}
+	}
+	return ordered;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function findLocaleTodoConflict(
 	todos: readonly LocaleTodo[],
 ): OperationDeclarationRefusal | undefined {
@@ -1548,7 +1743,9 @@ function collectSourceFiles(root: string): string[] {
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
 			if (entry.isDirectory()) {
 				if (SOURCE_SKIP_DIRECTORIES.has(entry.name)) continue;
-				walk(join(directory, entry.name));
+				const child = join(directory, entry.name);
+				if (existsSync(join(child, ".git"))) continue;
+				walk(child);
 				continue;
 			}
 			if (!entry.name.endsWith(".ts")) continue;
@@ -1571,6 +1768,8 @@ function collectLocaleFiles(root: string): string[] {
 
 function buildOperationIdIndex(sourceFiles: readonly string[]): Map<string, Map<string, string>> {
 	const result = new Map<string, Map<string, string>>();
+	const idsByPath = new Map<string, Map<string, string | null>>();
+	const ambiguousBindingsByPath = new Map<string, Set<string>>();
 	const sources = new Map<string, TS.SourceFile>();
 	for (const path of sourceFiles) {
 		const source = parseSource(path, readFileSync(path, "utf8"));
@@ -1579,10 +1778,40 @@ function buildOperationIdIndex(sourceFiles: readonly string[]): Map<string, Map<
 
 	const record = (path: string, binding: string, operationId: string): void => {
 		const map = result.get(path) ?? new Map<string, string>();
-		const previous = map.get(binding);
-		if (previous === undefined || previous === operationId) map.set(binding, operationId);
-		else map.delete(binding);
+		const ids = idsByPath.get(path) ?? new Map<string, string | null>();
+		const ambiguousBindings = ambiguousBindingsByPath.get(path) ?? new Set<string>();
+
+		// An operation id is usable only when it identifies exactly one binding.
+		// Keep an explicit null marker for an ambiguous id so a later occurrence
+		// cannot accidentally make it usable again.
+		const previousBinding = ids.get(operationId);
+		if (ids.has(operationId)) {
+			if (
+				previousBinding !== undefined &&
+				previousBinding !== null &&
+				previousBinding !== binding
+			) {
+				map.delete(previousBinding);
+				map.delete(binding);
+				ambiguousBindings.add(previousBinding);
+				ambiguousBindings.add(binding);
+				ids.set(operationId, null);
+			}
+		} else {
+			ids.set(operationId, binding);
+		}
+
+		// A binding registered under two different ids is likewise ambiguous.
+		const previousId = map.get(binding);
+		if (previousId !== undefined && previousId !== operationId) {
+			map.delete(binding);
+			ambiguousBindings.add(binding);
+		} else if (!ambiguousBindings.has(binding) && ids.get(operationId) === binding) {
+			map.set(binding, operationId);
+		}
 		result.set(path, map);
+		idsByPath.set(path, ids);
+		ambiguousBindingsByPath.set(path, ambiguousBindings);
 	};
 
 	for (const [path, source] of sources) {
@@ -1603,10 +1832,91 @@ function buildOperationIdIndex(sourceFiles: readonly string[]): Map<string, Map<
 				else record(imported.path, imported.exportedName, operationId);
 			}
 		}
+
+		// Some providers keep their operation registry in a same-file const with
+		// an arbitrary name (for example, `companionsOperations`). This scan is
+		// deliberately ID-only: it accepts only static object members whose value
+		// is a same-file operation binding, and never evaluates spreads, factories,
+		// or imported values.
+		const operationBindings = collectModuleOperationBindings(source);
+		const importedBindings = collectImportedBindingNames(source);
+		for (const entry of collectStaticOperationRegistryEntries(source, operationBindings)) {
+			if (importedBindings.has(entry.binding)) continue;
+			record(path, entry.binding, entry.operationId);
+		}
 	}
 	return result;
 }
 
+type StaticOperationRegistryEntry = {
+	readonly operationId: string;
+	readonly binding: string;
+};
+
+function collectModuleOperationBindings(source: TS.SourceFile): ReadonlySet<string> {
+	const bindings = new Set<string>();
+	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.initializer === undefined) continue;
+			const initializer = unwrapExpression(declaration.initializer);
+			if (
+				initializer !== undefined &&
+				ts.isCallExpression(initializer) &&
+				isOperationHelperCall(initializer)
+			) {
+				bindings.add(declaration.name.text);
+			}
+		}
+	}
+	return bindings;
+}
+
+function collectImportedBindingNames(source: TS.SourceFile): ReadonlySet<string> {
+	const bindings = new Set<string>();
+	for (const statement of source.statements) {
+		if (!ts.isImportDeclaration(statement)) continue;
+		const clause = statement.importClause;
+		if (clause?.name !== undefined) bindings.add(clause.name.text);
+		const named = clause?.namedBindings;
+		if (named === undefined) continue;
+		if (ts.isNamespaceImport(named)) {
+			bindings.add(named.name.text);
+			continue;
+		}
+		for (const element of named.elements) bindings.add(element.name.text);
+	}
+	return bindings;
+}
+
+function collectStaticOperationRegistryEntries(
+	source: TS.SourceFile,
+	operationBindings: ReadonlySet<string>,
+): StaticOperationRegistryEntry[] {
+	const entries: StaticOperationRegistryEntry[] = [];
+	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.initializer === undefined) continue;
+			const object = unwrapExpression(declaration.initializer);
+			if (object === undefined || !ts.isObjectLiteralExpression(object)) continue;
+			for (const property of object.properties) {
+				if (ts.isSpreadAssignment(property)) continue;
+				const name = property.name;
+				if (name === undefined || (!ts.isIdentifier(name) && !ts.isStringLiteral(name))) continue;
+				const value = propertyValue(property);
+				const binding = unwrapExpression(value);
+				if (binding === undefined || !ts.isIdentifier(binding)) continue;
+				if (!operationBindings.has(binding.text)) continue;
+				entries.push({ operationId: name.text, binding: binding.text });
+			}
+		}
+	}
+	return entries;
+}
+
 function collectImports(
 	source: TS.SourceFile,
 	containingPath: string,