fix(resolve-extends): always resolve extended parser presets for proper merging (#4647)

* fix(resolve-extends): always resolve extended parser presets for proper merging

When a user provides a partial parserPreset (e.g. only issuePrefixes),
the extended config's string parser preset was skipped because
loadExtends checked !context.parserPreset before resolving. This meant
the extended preset's headerPattern was never loaded, so it got lost
during the config merge.

Two changes fix this:

1. Remove the !context.parserPreset guard in loadExtends so string
   parser presets from extended configs are always resolved, making
   their parserOpts available for merging.

2. Preserve user-provided properties during the nested parserOpts
   unwrapping in loadParserOpts. Previously the unwrap replaced the
   outer object entirely, dropping any user additions that were merged
   at that level during config resolution.

Fixes #4640

* fix: address review feedback from qodo and copilot

- Shallow-copy the dynamicImport result to avoid mutating an immutable
  ESM namespace object when assigning the resolved parserPreset.
- Add explicit type cast in load-parser-opts destructuring so inner
  is Record<string, unknown> instead of unknown.
- Clarify unit test scope: it covers the merge path while the
  integration test covers string-to-object resolution.

Author: omar-y-abdi

@commitlint/load/fixtures/parser-preset-partial-user-override/commitlint.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+	extends: ['./extended'],
+	parserPreset: {
+		parserOpts: {
+			issuePrefixes: ['PROJ-'],
+		},
+	},
+};

@commitlint/load/fixtures/parser-preset-partial-user-override/extended/conventional-changelog-custom.js

@@ -0,0 +1,6 @@
+module.exports = {
+	parserOpts: {
+		headerPattern: /^(\w*)(?:\((.*)\))?!?: (.*)$/,
+		headerCorrespondence: ['type', 'scope', 'subject'],
+	},
+};

@commitlint/load/fixtures/parser-preset-partial-user-override/extended/index.js

@@ -0,0 +1,3 @@
+module.exports = {
+	parserPreset: './conventional-changelog-custom',
+};

@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 });

@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;
 	}

@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"] };
 

@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);