@aws-blocks/core 0.4.0 → 0.5.0

package/src/scripts/extract-ts-types.test.ts

@@ -29,6 +29,47 @@ const API_NS_MOCK = `
 	const ApiNamespace: ApiNamespaceConstructor = class {} as any;
 `;
 
+describe('extractMethodTypes — namespaces sharing a method name (regression: #445)', () => {
+	it('keys methods by namespace, so a shared method name does not cross-assign schemas', () => {
+		const dir = createTempProject({
+			'tsconfig.json': JSON.stringify({
+				compilerOptions: { target: 'ESNext', module: 'ESNext', moduleResolution: 'bundler', strict: true },
+			}),
+			'index.ts': `
+				${API_NS_MOCK}
+
+				// Two namespaces both expose \`create\`, with deliberately incompatible contracts.
+				export const widgets = new ApiNamespace(null, 'widgets', (context) => ({
+					async create(label: string): Promise<{ widgetId: string }> {
+						return { widgetId: 'w' };
+					},
+				}));
+				export const subscriptions = new ApiNamespace(null, 'subscriptions', (context) => ({
+					async create(topicCount: number): Promise<{ subId: number }> {
+						return { subId: 1 };
+					},
+				}));
+			`,
+		});
+
+		try {
+			const types = extractMethodTypes(join(dir, 'index.ts'));
+			// Distinct qualified keys — no collision.
+			assert.ok(types.has('widgets.create'), 'widgets.create should be keyed by namespace');
+			assert.ok(types.has('subscriptions.create'), 'subscriptions.create should be keyed by namespace');
+			assert.ok(!types.has('create'), 'no bare-name entry that could cross-assign');
+
+			// Each keeps its OWN parameter type.
+			assert.strictEqual(types.get('widgets.create')!.params[0].name, 'label');
+			assert.strictEqual(types.get('widgets.create')!.params[0].schema.type, 'string');
+			assert.strictEqual(types.get('subscriptions.create')!.params[0].name, 'topicCount');
+			assert.strictEqual(types.get('subscriptions.create')!.params[0].schema.type, 'number');
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});
+
 describe('extractMethodTypes — direct ApiNamespace calls', () => {
 	it('extracts param and return types from inline ApiNamespace', () => {
 		const dir = createTempProject({
@@ -58,15 +99,15 @@ describe('extractMethodTypes — direct ApiNamespace calls', () => {
 
 		try {
 			const types = extractMethodTypes(join(dir, 'index.ts'));
-			assert.ok(types.has('getUser'), 'should find getUser');
-			assert.ok(types.has('createUser'), 'should find createUser');
+			assert.ok(types.has('api.getUser'), 'should find getUser');
+			assert.ok(types.has('api.createUser'), 'should find createUser');
 
-			const getUser = types.get('getUser')!;
+			const getUser = types.get('api.getUser')!;
 			assert.strictEqual(getUser.params.length, 1);
 			assert.strictEqual(getUser.params[0].name, 'id');
 			assert.strictEqual(getUser.params[0].schema.type, 'string');
 
-			const createUser = types.get('createUser')!;
+			const createUser = types.get('api.createUser')!;
 			assert.strictEqual(createUser.params.length, 2);
 			assert.strictEqual(createUser.params[0].schema.type, 'string');
 			assert.strictEqual(createUser.params[1].schema.type, 'number');
@@ -102,9 +143,34 @@ describe('extractSkipCodegenMethods — pure-AST scan', () => {
 		try {
 			const skips = extractSkipCodegenMethods(join(dir, 'index.ts'));
 			assert.strictEqual(skips.size, 1);
-			assert.ok(skips.has('devOnly'));
-			assert.ok(!skips.has('normalMethod'));
-			assert.ok(!skips.has('alsoNormal'));
+			assert.ok(skips.has('api.devOnly'), 'skip set is namespace-qualified');
+			assert.ok(!skips.has('api.normalMethod'));
+			assert.ok(!skips.has('api.alsoNormal'));
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it('qualifies skip names by namespace so a tag on one namespace does not drop another (regression: #445)', () => {
+		const dir = createTempProject({
+			'index.ts': `
+				class ApiNamespace { constructor(scope: any, name: any, handler: any) {} }
+
+				export const widgets = new ApiNamespace(null, 'widgets', () => ({
+					/** @blocksSkipCodegen */
+					async create() { return null; },
+				}));
+				// subscriptions.create is NOT tagged and must survive.
+				export const subscriptions = new ApiNamespace(null, 'subscriptions', () => ({
+					async create() { return null; },
+				}));
+			`,
+		});
+		try {
+			const skips = extractSkipCodegenMethods(join(dir, 'index.ts'));
+			assert.ok(skips.has('widgets.create'), 'tagged method is skipped, qualified');
+			assert.ok(!skips.has('subscriptions.create'), 'untagged same-named method must NOT be skipped');
+			assert.ok(!skips.has('create'), 'no bare key that would drop both');
 		} finally {
 			rmSync(dir, { recursive: true, force: true });
 		}
@@ -155,8 +221,8 @@ describe('extractMethodTypes — @blocksSkipCodegen JSDoc tag', () => {
 
 		try {
 			const types = extractMethodTypes(join(dir, 'index.ts'));
-			assert.strictEqual(types.get('normalMethod')?.skipCodegen, undefined);
-			assert.strictEqual(types.get('getLastCode')?.skipCodegen, true);
+			assert.strictEqual(types.get('api.normalMethod')?.skipCodegen, undefined);
+			assert.strictEqual(types.get('api.getLastCode')?.skipCodegen, true);
 		} finally {
 			rmSync(dir, { recursive: true, force: true });
 		}
@@ -217,23 +283,23 @@ describe('extractMethodTypes — indirect ApiNamespace calls (e.g., auth.createA
 			const types = extractMethodTypes(join(dir, 'index.ts'));
 
 			// Direct ApiNamespace methods should still work
-			assert.ok(types.has('greet'), 'should find greet from direct ApiNamespace');
-			const greet = types.get('greet')!;
+			assert.ok(types.has('api.greet'), 'should find greet from direct ApiNamespace');
+			const greet = types.get('api.greet')!;
 			assert.strictEqual(greet.params[0].name, 'name');
 			assert.strictEqual(greet.params[0].schema.type, 'string');
 
 			// Indirect methods from auth.createApi() should now be resolved
-			assert.ok(types.has('getAuthState'), 'should find getAuthState from auth.createApi()');
-			assert.ok(types.has('setAuthState'), 'should find setAuthState from auth.createApi()');
+			assert.ok(types.has('authApi.getAuthState'), 'should find getAuthState from auth.createApi()');
+			assert.ok(types.has('authApi.setAuthState'), 'should find setAuthState from auth.createApi()');
 
-			const getAuthState = types.get('getAuthState')!;
+			const getAuthState = types.get('authApi.getAuthState')!;
 			assert.strictEqual(getAuthState.params.length, 0, 'getAuthState has no params');
 			assert.strictEqual(getAuthState.returnType.type, 'object', 'return type should be object');
 			assert.ok(getAuthState.returnType.properties, 'return type should have properties');
 			assert.ok('isSignedIn' in getAuthState.returnType.properties!, 'should have isSignedIn');
 			assert.ok('username' in getAuthState.returnType.properties!, 'should have username');
 
-			const setAuthState = types.get('setAuthState')!;
+			const setAuthState = types.get('authApi.setAuthState')!;
 			assert.strictEqual(setAuthState.params.length, 2, 'setAuthState has 2 params');
 			assert.strictEqual(setAuthState.params[0].name, 'action');
 			assert.strictEqual(setAuthState.params[0].schema.type, 'string');
@@ -271,9 +337,9 @@ describe('extractMethodTypes — indirect ApiNamespace calls (e.g., auth.createA
 
 		try {
 			const types = extractMethodTypes(join(dir, 'index.ts'));
-			assert.ok(types.has('greet'), 'should find greet');
+			assert.ok(types.has('api.greet'), 'should find greet');
 			// The AST-walk version should be preserved (it has richer info from the declaration)
-			assert.strictEqual(types.get('greet')!.params[0].name, 'name');
+			assert.strictEqual(types.get('api.greet')!.params[0].name, 'name');
 		} finally {
 			rmSync(dir, { recursive: true, force: true });
 		}
@@ -335,7 +401,7 @@ describe('extractMethodTypes — transferable detection', () => {
 			`,
 		});
 		try {
-			const info = extractMethodTypes(join(dir, 'index.ts')).get('getCursorChannel');
+			const info = extractMethodTypes(join(dir, 'index.ts')).get('api.getCursorChannel');
 			assert.ok(info, 'method should be discovered');
 			assert.ok(info.transferable, 'should be detected as transferable');
 			assert.strictEqual(info.transferable.blocksTag, 'realtime/channel');
@@ -360,7 +426,7 @@ describe('extractMethodTypes — transferable detection', () => {
 			`,
 		});
 		try {
-			const info = extractMethodTypes(join(dir, 'index.ts')).get('getDownload');
+			const info = extractMethodTypes(join(dir, 'index.ts')).get('api.getDownload');
 			assert.ok(info?.transferable);
 			assert.strictEqual(info.transferable.blocksTag, 'file-bucket/download');
 			assert.deepStrictEqual(info.transferable.typeArgs, []);
@@ -382,8 +448,8 @@ describe('extractMethodTypes — transferable detection', () => {
 		});
 		try {
 			const types = extractMethodTypes(join(dir, 'index.ts'));
-			assert.deepStrictEqual(types.get('defaulted')?.transferable?.typeArgs, []);
-			assert.deepStrictEqual(types.get('explicit')?.transferable?.typeArgs, [{}]);
+			assert.deepStrictEqual(types.get('api.defaulted')?.transferable?.typeArgs, []);
+			assert.deepStrictEqual(types.get('api.explicit')?.transferable?.typeArgs, [{}]);
 		} finally {
 			rmSync(dir, { recursive: true, force: true });
 		}
@@ -404,8 +470,8 @@ describe('extractMethodTypes — transferable detection', () => {
 		});
 		try {
 			const types = extractMethodTypes(join(dir, 'index.ts'));
-			assert.strictEqual(types.get('plain')?.transferable, undefined);
-			assert.strictEqual(types.get('loose')?.transferable, undefined);
+			assert.strictEqual(types.get('api.plain')?.transferable, undefined);
+			assert.strictEqual(types.get('api.loose')?.transferable, undefined);
 		} finally {
 			rmSync(dir, { recursive: true, force: true });
 		}
@@ -431,7 +497,7 @@ describe('extractMethodTypes — transferable detection', () => {
 			`,
 		});
 		try {
-			const info = extractMethodTypes(join(dir, 'index.ts')).get('getNotifications');
+			const info = extractMethodTypes(join(dir, 'index.ts')).get('api.getNotifications');
 			assert.ok(info?.transferable);
 			assert.strictEqual(info.transferable.blocksTag, 'realtime/channel');
 			assert.strictEqual(info.transferable.typeArgs[0]?.title, 'Notification');
@@ -465,7 +531,7 @@ describe('extractMethodTypes — open-shape intersections', () => {
 			`,
 		});
 		try {
-			const info = extractMethodTypes(join(dir, 'index.ts')).get('signUp');
+			const info = extractMethodTypes(join(dir, 'index.ts')).get('api.signUp');
 			assert.ok(info, 'should find signUp');
 			const inputSchema = info.params[0].schema as any;
 			assert.strictEqual(inputSchema.type, 'object');
@@ -502,7 +568,7 @@ describe('extractMethodTypes — open-shape intersections', () => {
 			`,
 		});
 		try {
-			const info = extractMethodTypes(join(dir, 'index.ts')).get('tag');
+			const info = extractMethodTypes(join(dir, 'index.ts')).get('api.tag');
 			assert.ok(info, 'should find tag');
 			const inputSchema = info.params[0].schema as any;
 			assert.strictEqual(inputSchema.type, 'object');
@@ -514,3 +580,139 @@ describe('extractMethodTypes — open-shape intersections', () => {
 		}
 	});
 });
+
+describe('extractMethodTypes — namespace returned by a factory, then destructured (regression: #444)', () => {
+	it('keys a destructured factory namespace qualified, with real schemas', () => {
+		const dir = createTempProject({
+			'tsconfig.json': JSON.stringify({
+				compilerOptions: { target: 'ESNext', module: 'ESNext', moduleResolution: 'bundler', strict: true },
+			}),
+			'index.ts': `
+				${API_NS_MOCK}
+				class Scope { constructor(id: string) {} }
+
+				class NamespaceFactory {
+					constructor(private readonly scope: Scope) {}
+					createNamespaces() {
+						return {
+							indirectNamespace: new ApiNamespace(this.scope, 'indirectNamespace', () => ({
+								async getIndirectGreeting(times: number): Promise<string> { return 'hi'; },
+							})),
+						};
+					}
+				}
+
+				const scope = new Scope('repro');
+				export const directNamespace = new ApiNamespace(scope, 'directNamespace', () => ({
+					async getDirectGreeting(name: string): Promise<number> { return name.length; },
+				}));
+				const { indirectNamespace } = new NamespaceFactory(scope).createNamespaces();
+				export { indirectNamespace };
+			`,
+		});
+		try {
+			const types = extractMethodTypes(join(dir, 'index.ts'));
+			// The factory-returned namespace is now attributed to its binding name,
+			// exactly like the directly-constructed one.
+			const indirect = types.get('indirectNamespace.getIndirectGreeting');
+			assert.ok(indirect, 'indirectNamespace.getIndirectGreeting should be keyed by namespace');
+			assert.strictEqual((indirect.params[0].schema as any).type, 'number');
+			assert.strictEqual((indirect.returnType as any).type, 'string');
+
+			const direct = types.get('directNamespace.getDirectGreeting');
+			assert.ok(direct, 'directNamespace.getDirectGreeting should be present');
+			assert.strictEqual((direct.params[0].schema as any).type, 'string');
+			assert.strictEqual((direct.returnType as any).type, 'number');
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it('a factory namespace sharing a method name with a direct one does NOT cross-assign', () => {
+		const dir = createTempProject({
+			'tsconfig.json': JSON.stringify({
+				compilerOptions: { target: 'ESNext', module: 'ESNext', moduleResolution: 'bundler', strict: true },
+			}),
+			'index.ts': `
+				${API_NS_MOCK}
+				class Scope { constructor(id: string) {} }
+
+				class Factory {
+					constructor(private readonly scope: Scope) {}
+					build() {
+						return {
+							subscriptions: new ApiNamespace(this.scope, 'subscriptions', () => ({
+								async create(topicCount: number): Promise<{ subId: number }> { return { subId: 1 }; },
+							})),
+						};
+					}
+				}
+
+				const scope = new Scope('app');
+				export const widgets = new ApiNamespace(scope, 'widgets', () => ({
+					async create(label: string): Promise<{ widgetId: string }> { return { widgetId: 'w' }; },
+				}));
+				const { subscriptions } = new Factory(scope).build();
+				export { subscriptions };
+			`,
+		});
+		try {
+			const types = extractMethodTypes(join(dir, 'index.ts'));
+			// Each namespace keeps its OWN param type under a distinct qualified key.
+			assert.strictEqual((types.get('widgets.create')?.params[0].schema as any)?.type, 'string');
+			assert.strictEqual((types.get('subscriptions.create')?.params[0].schema as any)?.type, 'number');
+			// The first-pass AST walk still emits a lingering bare `create` for the
+			// factory namespace, but it never overrides a qualified key: the
+			// direct namespace's qualified `widgets.create` is unaffected above, and
+			// `generate-spec` prefers the qualified key (see the collision test in
+			// generate-spec.test.ts, which asserts this end-to-end in the output).
+			// So the bare entry can't reintroduce the #445 cross-assignment here.
+			assert.strictEqual((types.get('widgets.create')?.params[0].schema as any)?.type, 'string');
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it('array/nested destructuring falls through to the bare key (documented boundary)', () => {
+		// Only a top-level identifier and a shallow object binding pattern are
+		// attributed to a namespace. An array pattern (`const [ns] = factory()`)
+		// falls through to the bare-key path — the schema is still recovered (the
+		// AST walk found `new ApiNamespace(...)`), just under the bare method name,
+		// which generate-spec's #498 fallback resolves when there's no collision.
+		const dir = createTempProject({
+			'tsconfig.json': JSON.stringify({
+				compilerOptions: { target: 'ESNext', module: 'ESNext', moduleResolution: 'bundler', strict: true },
+			}),
+			'index.ts': `
+				${API_NS_MOCK}
+				class Scope { constructor(id: string) {} }
+
+				class Factory {
+					constructor(private readonly scope: Scope) {}
+					build() {
+						return [
+							new ApiNamespace(this.scope, 'tupleNs', () => ({
+								async ping(count: number): Promise<string> { return 'p'; },
+							})),
+						] as const;
+					}
+				}
+				const scope = new Scope('app');
+				const [tupleNs] = new Factory(scope).build();
+				export { tupleNs };
+			`,
+		});
+		try {
+			const types = extractMethodTypes(join(dir, 'index.ts'));
+			// Not attributed to the binding (array pattern), so no qualified key…
+			assert.ok(!types.has('tupleNs.ping'), 'array pattern is not attributed (documented boundary)');
+			// …but the schema is still present under the bare name (soft fallback).
+			const bare = types.get('ping');
+			assert.ok(bare, 'method schema is still recovered under the bare key');
+			assert.strictEqual((bare.params[0].schema as any)?.type, 'number');
+			assert.strictEqual((bare.returnType as any)?.type, 'string');
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});

package/src/scripts/extract-ts-types.ts

@@ -80,7 +80,7 @@ export function extractSkipCodegenMethods(sourcePath: string): Set<string> {
 		ts.ScriptKind.TS,
 	);
 
-	function visitObjectLiteral(obj: ts.ObjectLiteralExpression) {
+	function visitObjectLiteral(obj: ts.ObjectLiteralExpression, namespaceName?: string) {
 		for (const prop of obj.properties) {
 			if (
 				ts.isMethodDeclaration(prop) &&
@@ -88,7 +88,10 @@ export function extractSkipCodegenMethods(sourcePath: string): Set<string> {
 				ts.isIdentifier(prop.name) &&
 				hasBlocksSkipCodegenTag(prop)
 			) {
-				result.add(prop.name.text);
+				// Qualify by namespace (like extractMethodTypes) so a tag on one
+				// namespace's `create` doesn't cause another namespace's `create` to be
+				// dropped from the spec. Bare key only when the namespace is unknown.
+				result.add(namespaceName ? `${namespaceName}.${prop.name.text}` : prop.name.text);
 			}
 		}
 	}
@@ -98,22 +101,23 @@ export function extractSkipCodegenMethods(sourcePath: string): Set<string> {
 			const callee = node.expression;
 			if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace' && node.arguments && node.arguments.length >= 2) {
 				const handler = node.arguments[node.arguments.length - 1];
+				const nsName = enclosingBindingName(node);
 				if (ts.isArrowFunction(handler) || ts.isFunctionExpression(handler)) {
 					const body = handler.body;
 					if (ts.isParenthesizedExpression(body) && ts.isObjectLiteralExpression(body.expression)) {
-						visitObjectLiteral(body.expression);
+						visitObjectLiteral(body.expression, nsName);
 					} else if (ts.isObjectLiteralExpression(body)) {
-						visitObjectLiteral(body);
+						visitObjectLiteral(body, nsName);
 					} else if (ts.isBlock(body)) {
 						for (const stmt of body.statements) {
 							if (ts.isReturnStatement(stmt) && stmt.expression) {
 								if (ts.isObjectLiteralExpression(stmt.expression)) {
-									visitObjectLiteral(stmt.expression);
+									visitObjectLiteral(stmt.expression, nsName);
 								} else if (
 									ts.isParenthesizedExpression(stmt.expression) &&
 									ts.isObjectLiteralExpression(stmt.expression.expression)
 								) {
-									visitObjectLiteral(stmt.expression.expression);
+									visitObjectLiteral(stmt.expression.expression, nsName);
 								}
 							}
 						}
@@ -197,7 +201,7 @@ export function extractMethodTypes(sourcePath: string): Map<string, MethodTypeIn
 			const fnName = node.expression;
 			if (ts.isIdentifier(fnName) && fnName.text === 'ApiNamespace' && node.arguments && node.arguments.length >= 2) {
 				const handlerArg = node.arguments[node.arguments.length - 1];
-				extractMethodsFromHandler(handlerArg, checker, sourceFile!, result);
+				extractMethodsFromHandler(handlerArg, checker, sourceFile!, result, enclosingBindingName(node));
 			}
 		}
 		ts.forEachChild(node, visit);
@@ -210,18 +214,65 @@ export function extractMethodTypes(sourcePath: string): Map<string, MethodTypeIn
 	ts.forEachChild(sourceFile, (node) => {
 		if (!ts.isVariableStatement(node)) return;
 		for (const decl of node.declarationList.declarations) {
-			if (!decl.initializer || !ts.isIdentifier(decl.name)) continue;
-			// Skip if we already extracted methods for this via the AST walk
-			if (ts.isNewExpression(decl.initializer)) {
-				const callee = decl.initializer.expression;
-				if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace') continue;
+			if (!decl.initializer) continue;
+
+			// (a) Simple binding: `const api = auth.createApi()` /
+			//     `export const api = backend.namespace`.
+			if (ts.isIdentifier(decl.name)) {
+				// Skip if we already extracted methods for this via the AST walk
+				if (ts.isNewExpression(decl.initializer)) {
+					const callee = decl.initializer.expression;
+					if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace') continue;
+				}
+				// Use the type checker to get the type of the initializer expression.
+				// For `auth.createApi()`, this resolves through the method's return type
+				// to the `AsyncAPI<T>` type that ApiNamespace returns.
+				const initType = checker.getTypeAtLocation(decl.initializer);
+				extractMethodsFromResolvedType(initType, checker, result, decl.name.text);
+				continue;
 			}
 
-			// Use the type checker to get the type of the initializer expression.
-			// For `auth.createApi()`, this resolves through the method's return type
-			// to the `AsyncAPI<T>` type that ApiNamespace returns.
-			const initType = checker.getTypeAtLocation(decl.initializer);
-			extractMethodsFromResolvedType(initType, checker, result);
+			// (b) Object binding pattern: `const { indirectNamespace } = factory()`.
+			// Each destructured binding is a separate namespace whose name is the
+			// LOCAL binding name (the name it's exported under). Resolve the property
+			// type off the initializer and extract methods keyed by that name, so a
+			// factory-returned namespace keys qualified (`indirectNamespace.method`)
+			// like a directly-constructed one — instead of landing on a bare key that
+			// collides with same-named methods in other namespaces (#444, #445).
+			//
+			// This adds the qualified key ALONGSIDE the bare key the first-pass AST
+			// walk already emitted for the same `new ApiNamespace(...)` (its
+			// `enclosingBindingName` returns undefined behind the factory, so it keys
+			// bare). Leaving the bare key is harmless: `generate-spec` looks up
+			// `tsTypes.get(qualified) ?? tsTypes.get(bare)`, so the qualified key
+			// added here always wins for an attributable namespace, and the bare
+			// entry never influences the emitted schema (a regression test asserts
+			// this under a name collision). The #498 bare-name fallback is retained
+			// on purpose — it's the last resort for namespaces this pass still can't
+			// attribute (default exports, deeper indirection, the patterns below), so
+			// it is NOT redundant.
+			//
+			// Boundary: only a top-level identifier (a) and a shallow object binding
+			// pattern (b) are attributed. Array patterns (`const [ns] = factory()`)
+			// and nested patterns (`const { a: { b } } = …`) fall through to the
+			// bare-key path, where the #498 fallback still resolves the schema when
+			// there's no collision. These shapes are rare for namespace exports and
+			// fail soft; widening the traversal can come later if a real case appears.
+			if (ts.isObjectBindingPattern(decl.name)) {
+				const initType = checker.getTypeAtLocation(decl.initializer);
+				for (const element of decl.name.elements) {
+					if (!ts.isIdentifier(element.name)) continue;
+					const localName = element.name.text;
+					// `const { foo: bar } = …` binds `bar` but reads property `foo`.
+					const propKey = element.propertyName && ts.isIdentifier(element.propertyName)
+						? element.propertyName.text
+						: localName;
+					const propSymbol = initType.getProperty(propKey);
+					if (!propSymbol) continue;
+					const propType = checker.getTypeOfSymbol(propSymbol);
+					extractMethodsFromResolvedType(propType, checker, result, localName);
+				}
+			}
 		}
 	});
 
@@ -249,6 +300,7 @@ function extractMethodsFromHandler(
 	checker: ts.TypeChecker,
 	sourceFile: ts.SourceFile,
 	result: Map<string, MethodTypeInfo>,
+	namespaceName?: string,
 ): void {
 	let objectLiteral: ts.ObjectLiteralExpression | undefined;
 
@@ -280,11 +332,41 @@ function extractMethodsFromHandler(
 		if (ts.isMethodDeclaration(prop) && prop.name && ts.isIdentifier(prop.name)) {
 			const methodName = prop.name.text;
 			const info = extractMethodTypeInfo(prop, checker, sourceFile);
-			if (info) result.set(methodName, info);
+			// Key by the namespace-qualified name when the namespace is known, so two
+			// namespaces sharing a method name (e.g. widgets.create / subscriptions.create)
+			// don't collide and cross-assign schemas. Fall back to the bare name when the
+			// namespace can't be determined (consumers try qualified, then bare).
+			if (info) result.set(namespaceName ? `${namespaceName}.${methodName}` : methodName, info);
 		}
 	}
 }
 
+/**
+ * Walk up from a `new ApiNamespace(...)` node to the name it's bound to
+ * (`export const widgets = new ApiNamespace(...)` → `"widgets"`). This is the
+ * name the dev server / Lambda handler route by, and the one `generate-spec`
+ * uses to qualify method names. Returns `undefined` when the namespace is
+ * created behind indirection (factory return, etc.), in which case methods key
+ * by their bare name.
+ *
+ * Limitation: this is the local binding name, not the export name. An export
+ * rename — `const widgets = new ApiNamespace(...); export { widgets as gadgets }`
+ * — keys `widgets.*` while `generate-spec` looks up `gadgets.*`, so the qualified
+ * lookup misses and falls back to the bare key (schemas resolve if there's no
+ * collision, else `unknown`). Rare; resolving the export alias would remove it.
+ */
+function enclosingBindingName(node: ts.Node): string | undefined {
+	let current: ts.Node | undefined = node.parent;
+	while (current) {
+		if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name)) return current.name.text;
+		// Don't cross a function/block boundary — beyond it the binding no longer
+		// corresponds to a directly-exported namespace.
+		if (ts.isSourceFile(current) || ts.isBlock(current) || ts.isFunctionLike(current)) return undefined;
+		current = current.parent;
+	}
+	return undefined;
+}
+
 function extractMethodTypeInfo(
 	method: ts.MethodDeclaration,
 	checker: ts.TypeChecker,
@@ -365,6 +447,7 @@ function extractMethodsFromResolvedType(
 	type: ts.Type,
 	checker: ts.TypeChecker,
 	result: Map<string, MethodTypeInfo>,
+	namespaceName?: string,
 ): void {
 	// The runtime value of an ApiNamespace export is the handler function itself
 	// (with the marker symbol attached). Its TS type is `AsyncAPI<T>`, which is
@@ -392,8 +475,9 @@ function extractMethodsFromResolvedType(
 		const propName = prop.getName();
 		// Skip internal symbols and the marker
 		if (propName.startsWith('_') || propName === 'Symbol(blocks:ApiNamespace)') continue;
+		const key = namespaceName ? `${namespaceName}.${propName}` : propName;
 		// Don't overwrite methods already found by the AST walk
-		if (result.has(propName)) continue;
+		if (result.has(key)) continue;
 
 		const propType = checker.getTypeOfSymbol(prop);
 		const methodSigs = propType.getCallSignatures();
@@ -433,7 +517,7 @@ function extractMethodsFromResolvedType(
 			skipCodegen = true;
 		}
 
-		result.set(propName, { params, returnType, transferable, skipCodegen });
+		result.set(key, { params, returnType, transferable, skipCodegen });
 	}
 }