conventional-changelog · escapedcat · Mar 13, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/@commitlint/load/fixtures/parser-preset-partial-user-override/commitlint.config.js b/@commitlint/load/fixtures/parser-preset-partial-user-override/commitlint.config.js
@@ -0,0 +1,8 @@
+module.exports = {
+	extends: ['./extended'],
+	parserPreset: {
+		parserOpts: {
+			issuePrefixes: ['PROJ-'],
+		},
+	},
+};
diff --git a/...ad/fixtures/parser-preset-partial-user-override/extended/conventional-changelog-custom.js b/...ad/fixtures/parser-preset-partial-user-override/extended/conventional-changelog-custom.js
@@ -0,0 +1,6 @@
+module.exports = {
+	parserOpts: {
+		headerPattern: /^(\w*)(?:\((.*)\))?!?: (.*)$/,
+		headerCorrespondence: ['type', 'scope', 'subject'],
+	},
+};
diff --git a/@commitlint/load/fixtures/parser-preset-partial-user-override/extended/index.js b/@commitlint/load/fixtures/parser-preset-partial-user-override/extended/index.js
@@ -0,0 +1,3 @@
+module.exports = {
+	parserPreset: './conventional-changelog-custom',
+};
diff --git a/@commitlint/load/src/load.test.ts b/@commitlint/load/src/load.test.ts
@@ -382,6 +382,21 @@ test("parser preset overwrites completely instead of merging", async () => {
 	});
 });
 
+// https://github.com/conventional-changelog/commitlint/issues/4640
+test("partial user parserPreset merges with extended string parserPreset", async () => {
+	const cwd = await gitBootstrap(
+		"fixtures/parser-preset-partial-user-override",
+	);
+	const actual = await load({}, { cwd });
+
+	expect(actual.parserPreset).toBeDefined();
+	expect(actual.parserPreset!.parserOpts).toMatchObject({
+		headerPattern: /^(\w*)(?:\((.*)\))?!?: (.*)$/,
+		headerCorrespondence: ["type", "scope", "subject"],
+		issuePrefixes: ["PROJ-"],
+	});
+});
+
 test("recursive extends with parserPreset", async () => {
 	const cwd = await gitBootstrap("fixtures/recursive-parser-preset");
 	const actual = await load({}, { cwd });

diff --git a/@commitlint/load/src/utils/load-parser-opts.ts b/@commitlint/load/src/utils/load-parser-opts.ts
@@ -46,7 +46,14 @@ export async function loadParserOpts(
 			isObjectLike(parser.parserOpts) &&
 			isObjectLike(parser.parserOpts.parserOpts)
 		) {
-			parser.parserOpts = parser.parserOpts.parserOpts;
+			// Preserve any user-provided properties (e.g. issuePrefixes) that
+			// were merged at the outer parserOpts level during config resolution,
+			// while unwrapping the inner module-provided parserOpts (#4640).
+			const { parserOpts: inner, ...rest } = parser.parserOpts as Record<
+				string,
+				unknown
+			> & { parserOpts: Record<string, unknown> };
+			parser.parserOpts = { ...inner, ...rest };
 		}
 		return parser;
 	}

diff --git a/@commitlint/resolve-extends/src/index.test.ts b/@commitlint/resolve-extends/src/index.test.ts
@@ -540,6 +540,55 @@ test("parserPreset should be merged correctly", async () => {
 	expect(actual).toEqual(expected);
 });
 
+// https://github.com/conventional-changelog/commitlint/issues/4640
+// Verifies that mergeWith deep-merges parserPreset objects so that a
+// user's partial override (issuePrefixes) coexists with the extended
+// config's properties (headerPattern, headerCorrespondence).
+// The full string-to-object resolution path is covered by the
+// integration test in @commitlint/load ("partial user parserPreset
+// merges with extended string parserPreset").
+test("user partial parserPreset should merge with extended parserPreset", async () => {
+	const input = {
+		extends: ["extender-name"],
+		parserPreset: {
+			parserOpts: {
+				issuePrefixes: ["PROJ-"],
+			},
+		},
+	};
+
+	const dynamicImport = (id: string) => {
+		switch (id) {
+			case "extender-name":
+				return {
+					parserPreset: {
+						parserOpts: {
+							headerPattern: /^(\w*)(?:\((.*)\))?!?: (.*)$/,
+							headerCorrespondence: ["type", "scope", "subject"],
+						},
+					},
+				};
+			default:
+				return {};
+		}
+	};
+
+	const ctx = {
+		resolve: id,
+		dynamicImport: vi.fn(dynamicImport),
+	} as ResolveExtendsContext;
+
+	const actual = await resolveExtends(input, ctx);
+
+	expect(actual.parserPreset).toEqual({
+		parserOpts: {
+			headerPattern: /^(\w*)(?:\((.*)\))?!?: (.*)$/,
+			headerCorrespondence: ["type", "scope", "subject"],
+			issuePrefixes: ["PROJ-"],
+		},
+	});
+});
+
 test("should correctly merge nested configs", async () => {
 	const input = { extends: ["extender-1"] };
 

diff --git a/@commitlint/resolve-extends/src/index.ts b/@commitlint/resolve-extends/src/index.ts
@@ -139,18 +139,21 @@ async function loadExtends(
 	return await ext.reduce(async (configs, raw) => {
 		const resolved = resolveConfig(raw, context);
 
-		const c = await (context.dynamicImport || dynamicImport)<{
-			parserPreset?: string;
-		}>(resolved);
+		// Shallow-copy so we never mutate an ESM namespace object (#4647).
+		const c = {
+			...(await (context.dynamicImport || dynamicImport)<{
+				parserPreset?: string | ParserPreset;
+			}>(resolved)),
+		};
 		const cwd = path.dirname(resolved);
 		const ctx = { ...context, cwd };
 
-		// Resolve parser preset if none was present before
-		if (
-			!context.parserPreset &&
-			typeof c === "object" &&
-			typeof c.parserPreset === "string"
-		) {
+		// Always resolve string parser presets from extended configs so that
+		// their parserOpts (headerPattern, etc.) are available for merging.
+		// Previously this was skipped when the user provided any parserPreset,
+		// which caused partial user overrides (e.g. just issuePrefixes) to
+		// lose the extended preset's headerPattern (see #4640).
+		if (typeof c === "object" && typeof c.parserPreset === "string") {
 			const resolvedParserPreset = resolveFrom(c.parserPreset, cwd);
 
 			const parserPreset: ParserPreset = {
@@ -159,7 +162,7 @@ async function loadExtends(
 			};
 
 			ctx.parserPreset = parserPreset;
-			config.parserPreset = parserPreset;
+			c.parserPreset = parserPreset;
 		}
 
 		validateConfig(resolved, config);