refactor: automatically generate the rules-list in README (#397)

MichaelDeBoey · Belco90 · web-flow · commit a6e243a88298 · 2021-07-04T14:40:18.000+02:00
* refactor: automatically generate the rules-list in README

* chore: update rule descriptions

Co-authored-by: Mario Beltrán Alarcón &lt;belco90@gmail.com&gt;
diff --git a/README.md b/README.md
diff --git a/lib/rules/await-async-utils.ts b/lib/rules/await-async-utils.ts
@@ -18,7 +18,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'problem',
     docs: {
-      description: 'Enforce promises from async utils to be handled',
+      description: 'Enforce promises from async utils to be awaited properly',
       category: 'Best Practices',
       recommendedConfig: {
         dom: 'error',
diff --git a/lib/rules/await-fire-event.ts b/lib/rules/await-fire-event.ts
@@ -18,7 +18,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'problem',
     docs: {
-      description: 'Enforce promises from fire event methods to be handled',
+      description: 'Enforce promises from `fireEvent` methods to be handled',
       category: 'Best Practices',
       recommendedConfig: {
         dom: false,
diff --git a/lib/rules/no-container.ts b/lib/rules/no-container.ts
@@ -19,7 +19,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow the use of container methods',
+      description: 'Disallow the use of `container` methods',
       category: 'Best Practices',
       recommendedConfig: {
         dom: false,
diff --git a/lib/rules/no-wait-for-empty-callback.ts b/lib/rules/no-wait-for-empty-callback.ts
@@ -17,7 +17,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description:
-        "It's preferred to avoid empty callbacks in `waitFor` and `waitForElementToBeRemoved`",
+        'Disallow empty callbacks for `waitFor` and `waitForElementToBeRemoved`',
       category: 'Best Practices',
       recommendedConfig: {
         dom: 'error',
diff --git a/lib/rules/no-wait-for-multiple-assertions.ts b/lib/rules/no-wait-for-multiple-assertions.ts
@@ -15,7 +15,8 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'suggestion',
     docs: {
-      description: "It's preferred to avoid multiple assertions in `waitFor`",
+      description:
+        'Disallow the use of multiple `expect` calls inside `waitFor`',
       category: 'Best Practices',
       recommendedConfig: {
         dom: false,
diff --git a/lib/rules/no-wait-for-side-effects.ts b/lib/rules/no-wait-for-side-effects.ts
@@ -19,7 +19,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'suggestion',
     docs: {
-      description: "It's preferred to avoid side effects in `waitFor`",
+      description: 'Disallow the us of side effects in `waitFor`',
       category: 'Best Practices',
       recommendedConfig: {
         dom: false,
diff --git a/lib/rules/prefer-find-by.ts b/lib/rules/prefer-find-by.ts
@@ -55,7 +55,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description:
-        'Suggest using `find*` query instead of `waitFor` + `get*` to wait for elements',
+        'Suggest using `find(All)By*` query instead of `waitFor` + `get(All)By*` to wait for elements',
       category: 'Best Practices',
       recommendedConfig: {
         dom: 'error',
diff --git a/lib/rules/prefer-presence-queries.ts b/lib/rules/prefer-presence-queries.ts
@@ -13,7 +13,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
     docs: {
       category: 'Best Practices',
       description:
-        'Ensure appropriate get*/query* queries are used with their respective matchers',
+        'Ensure appropriate `get*`/`query*` queries are used with their respective matchers',
       recommendedConfig: {
         dom: false,
         angular: false,
diff --git a/lib/rules/prefer-screen-queries.ts b/lib/rules/prefer-screen-queries.ts
@@ -39,7 +39,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'Suggest using screen while querying',
+      description: 'Suggest using `screen` while querying',
       category: 'Best Practices',
       recommendedConfig: {
         dom: 'error',
diff --git a/lib/rules/prefer-user-event.ts b/lib/rules/prefer-user-event.ts
@@ -69,7 +69,8 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'Suggest using userEvent over fireEvent',
+      description:
+        'Suggest using `userEvent` over `fireEvent` for simulating user interactions',
       category: 'Best Practices',
       recommendedConfig: {
         dom: false,
diff --git a/lib/utils/types.ts b/lib/utils/types.ts
@@ -6,20 +6,18 @@ type RecommendedConfig<TOptions extends readonly unknown[]> =
 
 // These 2 types are copied from @typescript-eslint/experimental-utils' CreateRuleMeta
 // and modified to our needs
-type TestingLibraryRuleMetaDocs<TOptions extends readonly unknown[]> = Omit<
-  TSESLint.RuleMetaDataDocs,
-  'recommended' | 'url'
-> & {
-  /**
-   * The recommendation level for the rule on a framework basis.
-   * Used by the build tools to generate the framework config.
-   * Set to false to not include it the config
-   */
-  recommendedConfig: Record<
-    SupportedTestingFramework,
-    RecommendedConfig<TOptions>
-  >;
-};
+export type TestingLibraryRuleMetaDocs<TOptions extends readonly unknown[]> =
+  Omit<TSESLint.RuleMetaDataDocs, 'recommended' | 'url'> & {
+    /**
+     * The recommendation level for the rule on a framework basis.
+     * Used by the build tools to generate the framework config.
+     * Set to false to not include it the config
+     */
+    recommendedConfig: Record<
+      SupportedTestingFramework,
+      RecommendedConfig<TOptions>
+    >;
+  };
 export type TestingLibraryRuleMeta<
   TMessageIds extends string,
   TOptions extends readonly unknown[]
diff --git a/package.json b/package.json
@@ -30,6 +30,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "generate:configs": "ts-node tools/generate-configs",
+    "generate:rules-list": "ts-node tools/generate-rules-list",
     "lint": "eslint . --max-warnings 0 --ext .js,.ts",
     "lint:fix": "npm run lint -- --fix",
     "test": "jest",
@@ -46,6 +47,7 @@
     "@commitlint/cli": "^12.1.4",
     "@commitlint/config-conventional": "^12.1.4",
     "@types/jest": "^26.0.23",
+    "@types/node": "^10.17.60",
     "@typescript-eslint/eslint-plugin": "^4.26.1",
     "@typescript-eslint/parser": "^4.26.1",
     "cpy-cli": "^3.1.1",
@@ -64,6 +66,7 @@
     "prettier": "2.3.2",
     "semantic-release": "^17.4.3",
     "ts-jest": "^27.0.3",
+    "ts-node": "^10.0.0",
     "typescript": "^4.3.2"
   },
   "peerDependencies": {
diff --git a/tools/generate-rules-list/index.ts b/tools/generate-rules-list/index.ts
@@ -0,0 +1,26 @@
+import rules from '../../lib/rules';
+import type { TestingLibraryRuleMetaDocs } from '../../lib/utils';
+
+import { configBadges, emojiKey, RulesList, writeRulesList } from './utils';
+
+export const createRuleLink = (ruleName: string): string =>
+  `[\`testing-library/${ruleName}\`](./docs/rules/${ruleName}.md)`;
+
+export const generateConfigBadges = (
+  recommendedConfig: TestingLibraryRuleMetaDocs<unknown[]>['recommendedConfig']
+): string =>
+  Object.entries(recommendedConfig)
+    .filter(([_, config]) => Boolean(config))
+    .map(([framework]) => configBadges[framework])
+    .join(' ');
+
+const rulesList: RulesList = Object.entries(rules)
+  .sort(([ruleNameA], [ruleNameB]) => ruleNameA.localeCompare(ruleNameB))
+  .map(([name, rule]) => [
+    createRuleLink(name),
+    rule.meta.docs.description,
+    Boolean(rule.meta.fixable) ? emojiKey.fixable : '',
+    generateConfigBadges(rule.meta.docs.recommendedConfig),
+  ]);
+
+writeRulesList(rulesList);
diff --git a/tools/generate-rules-list/utils.ts b/tools/generate-rules-list/utils.ts
@@ -0,0 +1,87 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+import { format, resolveConfig } from 'prettier';
+
+import {
+  SUPPORTED_TESTING_FRAMEWORKS,
+  SupportedTestingFramework,
+} from '../../lib/utils';
+
+const prettierConfig = resolveConfig.sync(__dirname);
+const readmePath = resolve(__dirname, `../../README.md`);
+
+export type RulesList = string[][];
+
+export const configBadges = SUPPORTED_TESTING_FRAMEWORKS.reduce(
+  (badges, framework) => ({
+    ...badges,
+    [framework]: `![${framework}-badge][]`,
+  }),
+  {}
+) as Record<SupportedTestingFramework, string>;
+export const emojiKey = {
+  fixable: '🔧',
+} as const;
+const staticElements = {
+  listHeaderRow: [
+    'Name',
+    'Description',
+    emojiKey.fixable,
+    'Included in configurations',
+  ],
+  listSpacerRow: Array(4).fill('-'),
+  rulesListKey: [
+    `**Key**: ${emojiKey.fixable} = fixable`,
+    '',
+    [
+      `**Configurations**:`,
+      Object.entries(configBadges)
+        .map(([template, badge]) => `${badge} = ${template}`)
+        .join(', '),
+    ].join(' '),
+  ].join('\n'),
+};
+
+const generateRulesListTable = (rulesList: RulesList) =>
+  [staticElements.listHeaderRow, staticElements.listSpacerRow, ...rulesList]
+    .map((column) => `|${column.join('|')}|`)
+    .join('\n');
+
+const generateRulesListMarkdown = (rulesList: RulesList) =>
+  [
+    '',
+    staticElements.rulesListKey,
+    '',
+    generateRulesListTable(rulesList),
+    '',
+  ].join('\n');
+
+const listBeginMarker = '<!-- RULES-LIST:START -->';
+const listEndMarker = '<!-- RULES-LIST:END -->';
+const overWriteRulesList = (rulesList: RulesList, readme: string) => {
+  const listStartIndex = readme.indexOf(listBeginMarker);
+  const listEndIndex = readme.indexOf(listEndMarker);
+
+  if ([listStartIndex, listEndIndex].includes(-1)) {
+    throw new Error(`cannot find start or end rules-list`);
+  }
+
+  return [
+    readme.substring(0, listStartIndex - 1),
+    listBeginMarker,
+    '',
+    generateRulesListMarkdown(rulesList),
+    readme.substring(listEndIndex),
+  ].join('\n');
+};
+
+export const writeRulesList = (rulesList: RulesList): void => {
+  const readme = readFileSync(readmePath, 'utf8');
+  const newReadme = format(overWriteRulesList(rulesList, readme), {
+    parser: 'markdown',
+    ...prettierConfig,
+  });
+
+  writeFileSync(readmePath, newReadme);
+};
