docs: update developer tools (#3382)

build/generate-eslint-plugin.ts

@@ -0,0 +1,24 @@
+import { createBuilder } from './util';
+
+const update = createBuilder([
+  [
+    'Update config',
+    () => require('../modules/eslint-plugin/scripts/generate-config'),
+  ],
+  [
+    'Update overview',
+    () => require('../modules/eslint-plugin/scripts/generate-overview'),
+  ],
+  [
+    'Update docs',
+    () => require('../modules/eslint-plugin/scripts/generate-docs'),
+  ],
+]);
+
+update({
+  scope: '@ngrx',
+  packages: [{ name: 'eslint-plugin' }],
+}).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

modules/eslint-plugin/scripts/generate-config.ts

@@ -6,8 +6,8 @@ import { rules } from '../src/rules';
 
 const prettierConfig = resolveConfig.sync(__dirname);
 
-const RULE_NAME_PREFIX = 'ngrx/';
-const CONFIG_DIRECTORY = './src/configs/';
+const RULE_MODULE = '@ngrx';
+const CONFIG_DIRECTORY = './modules/eslint-plugin/src/configs/';
 
 writeConfig(
   'recommended',
@@ -113,7 +113,7 @@ function writeConfig(
   );
   const configRules = rulesForConfig.reduce<Record<string, string>>(
     (rules, [ruleName, rule]) => {
-      rules[`${RULE_NAME_PREFIX}${ruleName}`] = setting(rule);
+      rules[`${RULE_MODULE}/${ruleName}`] = setting(rule);
       return rules;
     },
     {}
@@ -130,14 +130,13 @@ function writeConfig(
   const code = `
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {
   parser: "@typescript-eslint/parser",
   ${parserOptions ? `parserOptions: ${JSON.stringify(parserOptions)},` : ''}
-  plugins: ["ngrx"],
+  plugins: ["${RULE_MODULE}"],
   rules: ${JSON.stringify(configRules)},
 }
 `;

modules/eslint-plugin/scripts/generate-docs.ts

@@ -4,23 +4,26 @@ import { format, resolveConfig } from 'prettier';
 import { rules } from '../src/rules';
 
 const prettierConfig = resolveConfig.sync(__dirname);
-const placeholder = '<!-- MANUAL-DOC:START -->';
+const PLACEHOLDER = '<!-- MANUAL-DOC:START -->';
+const RULES_PATH = './projects/ngrx.io/content/guide/eslint-plugin/rules';
 
 for (const [ruleName, { meta }] of Object.entries(rules)) {
-  const docPath = path.join('docs', 'rules', `${ruleName}.md`);
+  const docPath = path.join(RULES_PATH, `${ruleName}.md`);
   const doc = readFileSync(docPath, 'utf-8');
-  const docContent = doc.substr(doc.indexOf(placeholder) + placeholder.length);
-  const frontMatter = [
-    `Fixable: ${meta.fixable ? 'yes' : 'no'}`,
-    meta.version ? `Required NgRx Version Range: ${meta.version}` : '',
-  ];
+  const docContent = doc.substr(doc.indexOf(PLACEHOLDER) + PLACEHOLDER.length);
   const newDoc = format(
-    `---
-${frontMatter.filter(Boolean).join('\n')}
----
-# ${ruleName}
+    `# ${ruleName}
 
-> ${meta.docs?.description}
+${meta.version ? '> Required NgRx Version Range: ${meta.version}' : ''} 
+
+${meta.docs?.description}
+
+- **Type**: ${meta.type}
+- **Recommended**: ${meta.docs?.recommended ? 'Yes' : 'No'}
+- **Fixable**: ${meta.fixable ? 'Yes' : 'No'}
+- **Suggestion**: ${meta.hasSuggestions ? 'Yes' : 'No'}
+- **Requires type checking**: ${meta.docs?.requiresTypeChecking ? 'Yes' : 'No'}
+- **Configurable**: ${meta.schema.length ? 'Yes' : 'No'}
 
 <!-- Everything above this generated, do not edit -->
 <!-- MANUAL-DOC:START -->

modules/eslint-plugin/scripts/generate-overview.ts

@@ -0,0 +1,101 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { EOL } from 'os';
+import { format, resolveConfig } from 'prettier';
+import { rules } from '../src/rules';
+import { configs } from '../src/configs';
+
+const prettierConfig = resolveConfig.sync(__dirname);
+const OVERVIEW = './projects/ngrx.io/content/guide/eslint-plugin/overview.md';
+const GH_CONFIGS =
+  'https://github.com/ngrx/platform/blob/master/modules/eslint-plugin/src/configs';
+
+generateRules();
+generateConfigurations();
+
+function generateRules() {
+  const moduleRules = Object.entries(rules).reduce<Record<string, string[][]>>(
+    (all, [ruleName, { meta }]) => {
+      all[meta.ngrxModule] = (all[meta.ngrxModule] ?? []).concat([
+        [
+          `[@ngrx/${ruleName}]${
+            meta.docs?.url
+              ? '(' +
+                meta.docs.url
+                  .replace('https://ngrx.io', '')
+                  .replace('.md', '') +
+                ')'
+              : ''
+          }`,
+          meta.docs?.description ?? 'TODO',
+          meta.type,
+          `${meta.docs?.recommended}`,
+          meta.fixable ? 'Yes' : 'No',
+          meta.hasSuggestions ? 'Yes' : 'No',
+          meta.schema.length ? 'Yes' : 'No',
+          meta.docs?.requiresTypeChecking ? 'Yes' : 'No',
+        ],
+      ]);
+      return all;
+    },
+    {}
+  );
+
+  const tableHeader = `| Name | Description | Recommended | Category | Fixable | Has suggestions | Configurable | Requires type information
+| --- | --- | --- | --- | --- | --- | --- | --- |`;
+
+  const configTable = Object.entries(moduleRules).map(
+    ([ngrxModule, pluginRules]) => {
+      const tableBody = pluginRules
+        .map((rule) => `|${rule.join('|')}|`)
+        .join(EOL);
+      const table = [tableHeader, tableBody].join(EOL);
+
+      return [`### ${ngrxModule}`, table].join(EOL);
+    }
+  );
+
+  const overview = readFileSync(OVERVIEW, 'utf-8');
+  const start = overview.indexOf('<!-- RULES-CONFIG:START -->');
+  const end = overview.indexOf('<!-- RULES-CONFIG:END -->');
+
+  const newOverview = format(
+    `${overview.substring(0, start + '<!-- RULES-CONFIG:START -->'.length)}
+${configTable.join(EOL)}
+${overview.substring(end)}`,
+    {
+      parser: 'markdown',
+      ...prettierConfig,
+    }
+  );
+
+  writeFileSync(OVERVIEW, newOverview);
+}
+
+function generateConfigurations() {
+  const tableHeader = `| Name |
+  | --- |`;
+
+  const config = Object.keys(configs);
+
+  const overview = readFileSync(OVERVIEW, 'utf-8');
+  const start = overview.indexOf('<!-- CONFIGURATIONS-CONFIG:START -->');
+  const end = overview.indexOf('<!-- CONFIGURATIONS-CONFIG:END -->');
+
+  const configTable = config.map(
+    (configName) => `| [${configName}](${GH_CONFIGS}/${configName}.ts) |`
+  );
+  const newOverview = format(
+    `${overview.substring(
+      0,
+      start + '<!-- CONFIGURATIONS-CONFIG:START -->'.length
+    )}
+  ${[tableHeader, ...configTable].join(EOL)}
+  ${overview.substring(end)}`,
+    {
+      parser: 'markdown',
+      ...prettierConfig,
+    }
+  );
+
+  writeFileSync(OVERVIEW, newOverview);
+}

modules/eslint-plugin/src/configs/all-requiring-type-checking.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/all.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/component-store-strict.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/component-store.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/effects-requiring-type-checking.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/effects-strict-requiring-type-checking.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/effects-strict.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/effects.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/recommended-requiring-type-checking.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/recommended.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/store-strict.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/store.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/strict-requiring-type-checking.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/configs/strict.ts

@@ -1,7 +1,6 @@
 /**
  * DO NOT EDIT
- *
- * This file is automatically generated (as a pre-commit step)
+ * This file is generated
  */
 
 export = {

modules/eslint-plugin/src/utils/helper-functions/docs.ts

@@ -1,2 +1,2 @@
 export const docsUrl = (ruleName: string) =>
-  `https://github.com/timdeschryver/eslint-plugin-ngrx/tree/main/docs/rules/${ruleName}.md`;
+  `https://ngrx.io/guide/eslint-plugin/rules/${ruleName}.md`;

package.json

@@ -51,7 +51,8 @@
     "lint": "nx workspace-lint && ng lint",
     "dep-graph": "nx dep-graph",
     "help": "nx help",
-    "workspace-generator": "nx workspace-generator"
+    "workspace-generator": "nx workspace-generator",
+    "eslint-plugin:update": "ts-node ./build/generate-eslint-plugin.ts"
   },
   "engines": {
     "node": "^12.20.0 || >=14.0.0",