add troubleshoot on documentation and some lint minor refactors (#3934)

* docs: add troubleshooting

* refactor(lint): use RuleConfigSeverity in errors and warnings filter

* refactor(lint): rewrite missing rule error message

Author: marcalexiei

@commitlint/lint/src/lint.test.ts

@@ -93,7 +93,9 @@ test('throws for invalid rule names', async () => {
 		bar: [RuleConfigSeverity.Warning, 'never'],
 	});
 
-	await expect(error).rejects.toThrow(/^Found invalid rule names: foo, bar/);
+	await expect(error).rejects.toThrow(
+		/^Found rules without implementation: foo, bar/
+	);
 });
 
 test('throws for invalid rule config', async () => {

@commitlint/lint/src/lint.ts

@@ -79,9 +79,10 @@ export default async function lint(
 	if (missing.length > 0) {
 		const names = [...allRules.keys()];
 		throw new RangeError(
-			`Found invalid rule names: ${missing.join(
-				', '
-			)}. Supported rule names are: ${names.join(', ')}`
+			[
+				`Found rules without implementation: ${missing.join(', ')}.`,
+				`Supported rules are: ${names.join(', ')}.`,
+			].join('\n')
 		);
 	}
 
@@ -181,10 +182,10 @@ export default async function lint(
 	);
 
 	const errors = results.filter(
-		(result) => result.level === 2 && !result.valid
+		(result) => result.level === RuleConfigSeverity.Error && !result.valid
 	);
 	const warnings = results.filter(
-		(result) => result.level === 1 && !result.valid
+		(result) => result.level === RuleConfigSeverity.Warning && !result.valid
 	);
 
 	const valid = errors.length === 0;

docs/.vitepress/config.ts

@@ -68,6 +68,7 @@ export default defineConfig({
 				base: '/support',
 				collapsed: true,
 				items: [
+					{text: 'Troubleshooting', link: '/troubleshooting'},
 					{text: 'Releases', link: '/releases'},
 					{text: 'Upgrade commitlint', link: '/upgrade'},
 				],

docs/support/troubleshooting.md

@@ -0,0 +1,26 @@
+# Troubleshooting
+
+## Getting `Range error: Found invalid rule names: [...]` after update {#range-error-invalid-rule}
+
+After updating one or more `@commitlint` packages you might encounter an error like:
+
+```text
+Found invalid rule names: header-trim.
+Supported rule names are: body-case, body-empty, ...
+```
+
+The source of this error is likely a mismatch of version between `@commitlint` packages in `node_modules`.
+
+E.g.: you might have a config requesting a rule that is not included in `@commitlint/rules`.
+
+> [!TIP]
+> If you are relying on a config which depends on an earlier version of `@commitlint/config-conventional` be sure to update them:
+>
+> ```sh
+> npm update @commitlint/config-conventional
+> ```
+
+---
+
+> [!NOTE]
+> Detailed explanation about the error can be found in this [comment](https://github.com/conventional-changelog/commitlint/pull/3871#issuecomment-1911455325).