Restore configuration field documentation in define* helpers (#15880)

Author: jamesopstad

.changeset/warm-cats-explain.md

@@ -0,0 +1,7 @@
+---
+"@cloudflare/config": patch
+---
+
+Restore configuration field documentation in `define*` helpers
+
+VS Code now displays JSDoc for fields passed to `defineConfig`, `defineContainer`, and `defineWorker` while retaining their exact inferred config types.

packages/config/src/__tests__/config-definition.test-d.ts

@@ -28,6 +28,20 @@ const projectConfig = defineConfig({
 	}),
 });
 
+const inlineConfig = defineConfig({
+	worker: {
+		name: "inline-worker",
+		compatibilityDate: "2026-09-25",
+		env: { MESSAGE: bindings.text("inline") },
+	},
+	containers: [
+		{
+			name: "inline-container",
+			image: { dockerfile: "./Dockerfile" },
+		},
+	],
+});
+
 // @ts-expect-error a workflow export requires a name
 workerExports.workflow({ limits: { steps: 10 } });
 
@@ -41,6 +55,8 @@ const plainConfig = {
 } as const;
 
 type ProjectWorker = UnwrapConfig<UnwrapConfig<typeof projectConfig>["worker"]>;
+type InlineConfig = UnwrapConfig<typeof inlineConfig>;
+type InlineWorker = UnwrapConfig<InlineConfig["worker"]>;
 
 export type PlainConfigWorkerEnvTest = Assert<
 	Equal<
@@ -57,3 +73,12 @@ export type ProjectConfigMainModuleTest = Assert<
 export type ProjectConfigDurableNamespaceTest = Assert<
 	Equal<InferDurableNamespaces<ProjectWorker>, "Counter">
 >;
+export type InlineConfigWorkerNameTest = Assert<
+	Equal<InlineWorker["name"], "inline-worker">
+>;
+export type InlineConfigWorkerEnvTest = Assert<
+	Equal<InferEnv<InlineWorker>["MESSAGE"], "inline">
+>;
+export type InlineConfigContainerNameTest = Assert<
+	Equal<InlineConfig["containers"][0]["name"], "inline-container">
+>;

packages/config/src/__tests__/definition.test.ts

@@ -0,0 +1,97 @@
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { it } from "vitest";
+
+const source = `
+import { defineConfig, defineContainer, defineWorker } from "../definition";
+
+defineConfig({
+	worker: {
+		name: "inline-worker",
+		compatibilityDate: "2026-09-25",
+	},
+	containers: [
+		{
+			name: "inline-container",
+			image: { dockerfile: "./inline.Dockerfile" },
+		},
+	],
+});
+
+defineWorker({
+	name: "standalone-worker",
+	compatibilityDate: "2026-09-25",
+});
+
+defineContainer({
+	name: "standalone-container",
+	image: { dockerfile: "./Dockerfile" },
+});
+`;
+const testFilePath = fileURLToPath(
+	new URL("inline-worker-jsdoc.ts", import.meta.url)
+);
+const canonicalize = (fileName: string) =>
+	ts.sys.useCaseSensitiveFileNames ? fileName : fileName.toLowerCase();
+const canonicalTestFilePath = canonicalize(ts.sys.resolvePath(testFilePath));
+
+it("preserves JSDoc for define helper fields", ({ expect }) => {
+	const host: ts.LanguageServiceHost = {
+		...ts.sys,
+		getCompilationSettings: () => ({
+			module: ts.ModuleKind.ESNext,
+			moduleResolution: ts.ModuleResolutionKind.Bundler,
+			strict: true,
+			target: ts.ScriptTarget.ESNext,
+		}),
+		getDefaultLibFileName: ts.getDefaultLibFilePath,
+		getScriptFileNames: () => [testFilePath],
+		getScriptSnapshot: (fileName) => {
+			const contents =
+				canonicalize(ts.sys.resolvePath(fileName)) === canonicalTestFilePath
+					? source
+					: ts.sys.readFile(fileName);
+			return contents === undefined
+				? undefined
+				: ts.ScriptSnapshot.fromString(contents);
+		},
+		getScriptVersion: () => "0",
+		useCaseSensitiveFileNames: () => ts.sys.useCaseSensitiveFileNames,
+	};
+	const languageService = ts.createLanguageService(host);
+
+	try {
+		expect(languageService.getSemanticDiagnostics(testFilePath)).toEqual([]);
+
+		for (const [marker, expectedDocumentation] of [
+			['name: "inline-worker"', "The name of your Worker."],
+			[
+				'compatibilityDate: "2026-09-25"',
+				"which version of the Workers runtime is used.",
+			],
+			['name: "inline-container"', "Name of the application."],
+			[
+				'image: { dockerfile: "./inline.Dockerfile" }',
+				"The image to build or deploy.",
+			],
+			['dockerfile: "./inline.Dockerfile"', "The path to a Dockerfile."],
+			['name: "standalone-worker"', "The name of your Worker."],
+			['name: "standalone-container"', "Name of the application."],
+			[
+				'image: { dockerfile: "./Dockerfile" }',
+				"The image to build or deploy.",
+			],
+			['dockerfile: "./Dockerfile"', "The path to a Dockerfile."],
+		] as const) {
+			const info = languageService.getQuickInfoAtPosition(
+				testFilePath,
+				source.indexOf(marker)
+			);
+			expect(ts.displayPartsToString(info?.documentation), marker).toContain(
+				expectedDocumentation
+			);
+		}
+	} finally {
+		languageService.dispose();
+	}
+});

packages/config/src/definition.ts

@@ -23,10 +23,42 @@ export type ConfigInput<T> =
 	| Promise<T>
 	| ((ctx: ConfigContext) => T | Promise<T>);
 
+/** Recursively apply declared config properties without expanding open records. */
+type ContextualProperties<
+	TInput extends object,
+	TConfig,
+> = TInput extends readonly unknown[]
+	? TConfig extends readonly (infer TElement)[]
+		? {
+				[K in keyof TInput]: ContextualConfig<TInput[K], TElement>;
+			}
+		: TConfig
+	: string extends keyof TConfig
+		? TConfig
+		: {
+				[K in keyof TConfig]: K extends keyof TInput
+					? ContextualConfig<TInput[K], TConfig[K]>
+					: TConfig[K];
+			};
+
+type ContextualConfig<TInput, TConfig> =
+	TInput extends Promise<infer TValue>
+		? Promise<ContextualConfig<TValue, TConfig>>
+		: TInput extends (ctx: ConfigContext) => infer TResult
+			? (ctx: ConfigContext) => ContextualConfig<TResult, TConfig>
+			: TConfig extends unknown
+				? TInput extends TConfig
+					? TInput &
+							(TInput extends object
+								? ContextualProperties<TInput, TConfig>
+								: TConfig)
+					: never
+				: never;
+
 /** Create a type-safe identity helper for a configuration value or factory. */
 export function createConfigDefiner<TConfig>() {
 	return function define<const TInput extends ConfigInput<TConfig>>(
-		config: TInput
+		config: TInput & ContextualConfig<TInput, TConfig>
 	): TInput {
 		return config;
 	};