feat: add ability to filter Nx projects in @commitlint/config-nx-scop…

…es (#3155)

* feat: add ability to filter Nx projects in @commitlint/config-nx-scopes

Solves: #3152

* docs: update example usage of project filtering with @commitlint/config-nx-scopes

* docs: clarify filterFunc api

* refactor: adjust config-nx-scopes filtering implementation

* docs: correct config-nx-scopes project type filtering syntax

* docs: fix typo in config-nx-scopes readme

@commitlint/config-nx-scopes/index.js

@@ -8,7 +8,10 @@ module.exports = {
 	},
 };
 
-function getProjects(context) {
+/**
+ * @param {(params: Pick<Nx.ProjectConfiguration, 'name' | 'projectType' | 'tags'>) => boolean} selector
+ */
+function getProjects(context, selector = () => true) {
 	return Promise.resolve()
 		.then(() => {
 			const ctx = context || {};
@@ -24,6 +27,13 @@ function getProjects(context) {
 		})
 		.then((projects) => {
 			return projects
+				.filter((project) =>
+					selector({
+						name: project.name,
+						projectType: project.projectType,
+						tags: project.tags,
+					})
+				)
 				.filter((project) => project.targets)
 				.map((project) => project.name)
 				.map((name) => (name.charAt(0) === '@' ? name.split('/')[1] : name));

@commitlint/config-nx-scopes/readme.md

@@ -12,6 +12,63 @@ npm install --save-dev @commitlint/config-nx-scopes @commitlint/cli
 echo "module.exports = {extends: ['@commitlint/config-nx-scopes']};" > commitlint.config.js
 ```
 
+## Filtering projects
+
+You can filter projects by providing a filter function as the second parameter to `getProjects()`. The function will be called with an object containing each projects' `name`, `projectType`, and `tags`. Simply return a boolean to indicate whether the project should be included or not.
+
+As an example, the following code demonstrates how to select only applications that are not end-to-end tests.
+
+In your .commitlintrc.js file:
+
+```javascript
+const {
+  utils: {getProjects},
+} = require('@commitlint/config-nx-scopes');
+
+module.exports = {
+  rules: {
+    'scope-enum': async (ctx) => [
+      2,
+      'always',
+      [
+        ...(await getProjects(
+          ctx,
+          ({name, projectType}) =>
+            !name.includes('e2e') && projectType == 'application'
+        )),
+      ],
+    ],
+  },
+  // . . .
+};
+```
+
+Here is another example where projects tagged with 'stage:end-of-life' are not allowed to be used as the scope for a commit.
+
+In your .commitlintrc.js file:
+
+```javascript
+const {
+  utils: {getProjects},
+} = require('@commitlint/config-nx-scopes');
+
+module.exports = {
+  rules: {
+    'scope-enum': async (ctx) => [
+      2,
+      'always',
+      [
+        ...(await getProjects(
+          ctx,
+          ({tags}) => !tags.includes('stage:end-of-life')
+        )),
+      ],
+    ],
+  },
+  // . . .
+};
+```
+
 ## Examples
 
 ```