chore: Add documentation validation tool (#531)

typescript-eslint · May 16, 2019 · 4edf0d7 · 4edf0d7
1 parent c480eab
commit 4edf0d7
Show file tree

Hide file tree

Showing 60 changed files with 405 additions and 181 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -7,3 +7,4 @@
 **/.nyc_output
 packages/eslint-plugin-tslint/tests/test-tslint-rules-directory/alwaysFailRule.js
 .github
+packages/eslint-plugin/src/configs/*.json
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -31,6 +31,10 @@ jobs:
           yarn lint
         displayName: 'Run linting'
 
+      - script: |
+          yarn docs:check
+        displayName: 'Validate documentation'
+
       - script: |
           yarn test
         displayName: 'Run unit tests'

diff --git a/package.json b/package.json
@@ -20,6 +20,7 @@
     "build": "lerna run build",
     "clean": "lerna clean && lerna run clean",
     "cz": "git-cz",
+    "docs:check": "lerna run docs:check",
     "generate-contributors": "yarn ts-node ./tools/generate-contributors.ts && yarn all-contributors generate",
     "format": "prettier --write \"./**/*.{ts,js,json,md}\"",
     "format-check": "prettier --list-different \"./**/*.{ts,js,json,md}\"",

diff --git a/packages/eslint-plugin/README.md b/packages/eslint-plugin/README.md
diff --git a/packages/eslint-plugin/package.json b/packages/eslint-plugin/package.json
@@ -28,12 +28,12 @@
     "build": "tsc -p tsconfig.build.json",
     "clean": "rimraf dist/",
     "docs": "eslint-docs",
-    "docs:check": "eslint-docs check",
-    "test": "jest --coverage",
-    "generate:configs": "ts-node --files tools/generate-configs.ts",
+    "docs:check": "ts-node --files ./tools/validate-docs/index.ts",
     "format": "prettier --write \"./**/*.{ts,js,json,md}\" --ignore-path ../../.prettierignore",
+    "generate:configs": "ts-node --files tools/generate-configs.ts",
     "prebuild": "npm run clean",
     "recommended:update": "ts-node tools/update-recommended.ts",
+    "test": "jest --coverage",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -44,7 +44,9 @@
     "tsutils": "^3.7.0"
   },
   "devDependencies": {
-    "eslint-docs": "^0.2.6"
+    "@types/marked": "^0.6.5",
+    "chalk": "^2.4.2",
+    "marked": "^0.6.2"
   },
   "peerDependencies": {
     "@typescript-eslint/parser": "1.9.0",

diff --git a/packages/eslint-plugin/src/configs/all.json b/packages/eslint-plugin/src/configs/all.json
@@ -11,6 +11,7 @@
     "@typescript-eslint/class-name-casing": "error",
     "@typescript-eslint/explicit-function-return-type": "error",
     "@typescript-eslint/explicit-member-accessibility": "error",
+    "func-call-spacing": "off",
     "@typescript-eslint/func-call-spacing": "error",
     "@typescript-eslint/generic-type-naming": "error",
     "indent": "off",
@@ -24,10 +25,12 @@
     "@typescript-eslint/no-array-constructor": "error",
     "@typescript-eslint/no-empty-interface": "error",
     "@typescript-eslint/no-explicit-any": "error",
+    "no-extra-parens": "off",
     "@typescript-eslint/no-extra-parens": "error",
     "@typescript-eslint/no-extraneous-class": "error",
     "@typescript-eslint/no-for-in-array": "error",
     "@typescript-eslint/no-inferrable-types": "error",
+    "no-magic-numbers": "off",
     "@typescript-eslint/no-magic-numbers": "error",
     "@typescript-eslint/no-misused-new": "error",
     "@typescript-eslint/no-namespace": "error",
@@ -42,6 +45,7 @@
     "@typescript-eslint/no-unnecessary-type-assertion": "error",
     "no-unused-vars": "off",
     "@typescript-eslint/no-unused-vars": "error",
+    "no-use-before-define": "off",
     "@typescript-eslint/no-use-before-define": "error",
     "no-useless-constructor": "off",
     "@typescript-eslint/no-useless-constructor": "error",
@@ -56,6 +60,7 @@
     "@typescript-eslint/promise-function-async": "error",
     "@typescript-eslint/require-array-sort-compare": "error",
     "@typescript-eslint/restrict-plus-operands": "error",
+    "semi": "off",
     "@typescript-eslint/semi": "error",
     "@typescript-eslint/type-annotation-spacing": "error",
     "@typescript-eslint/unbound-method": "error",

diff --git a/packages/eslint-plugin/src/configs/recommended.json b/packages/eslint-plugin/src/configs/recommended.json
@@ -27,6 +27,7 @@
     "@typescript-eslint/no-triple-slash-reference": "error",
     "no-unused-vars": "off",
     "@typescript-eslint/no-unused-vars": "warn",
+    "no-use-before-define": "off",
     "@typescript-eslint/no-use-before-define": "error",
     "@typescript-eslint/no-var-requires": "error",
     "@typescript-eslint/prefer-interface": "error",

diff --git a/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts b/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts
@@ -19,7 +19,6 @@ export default util.createRule({
     docs: {
       description: 'Require that member overloads be consecutive',
       category: 'Best Practices',
-      tslintName: 'adjacent-overload-signatures',
       recommended: 'error',
     },
     schema: [],

diff --git a/packages/eslint-plugin/src/rules/array-type.ts b/packages/eslint-plugin/src/rules/array-type.ts
@@ -85,7 +85,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Requires using either `T[]` or `Array<T>` for arrays',
-      tslintRuleName: 'array-type',
       category: 'Stylistic Issues',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/await-thenable.ts b/packages/eslint-plugin/src/rules/await-thenable.ts
@@ -10,7 +10,6 @@ export default util.createRule({
       description: 'Disallows awaiting a value that is not a Thenable',
       category: 'Best Practices',
       recommended: false,
-      tslintName: 'await-thenable',
     },
     messages: {
       await: 'Unexpected `await` of a non-Promise (non-"Thenable") value.',

diff --git a/packages/eslint-plugin/src/rules/ban-ts-ignore.ts b/packages/eslint-plugin/src/rules/ban-ts-ignore.ts
@@ -5,8 +5,7 @@ export default util.createRule({
   meta: {
     type: 'problem',
     docs: {
-      description: 'Bans “// @ts-ignore” comments from being used.',
-      tslintRuleName: 'ban-ts-ignore',
+      description: 'Bans “// @ts-ignore” comments from being used',
       category: 'Best Practices',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/ban-types.ts b/packages/eslint-plugin/src/rules/ban-types.ts
@@ -26,7 +26,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Enforces that types will not to be used',
-      tslintRuleName: 'ban-types',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/class-name-casing.ts b/packages/eslint-plugin/src/rules/class-name-casing.ts
@@ -10,7 +10,6 @@ export default util.createRule({
     type: 'suggestion',
     docs: {
       description: 'Require PascalCased class and interface names',
-      tslintRuleName: 'class-name',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts b/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts
@@ -33,7 +33,6 @@ export default util.createRule<Options, MessageIds>({
     docs: {
       description:
         'Require explicit accessibility modifiers on class properties and methods',
-      tslintRuleName: 'member-access',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/func-call-spacing.ts b/packages/eslint-plugin/src/rules/func-call-spacing.ts
@@ -16,7 +16,7 @@ export default util.createRule<Options, MessageIds>({
     type: 'layout',
     docs: {
       description:
-        'require or disallow spacing between function identifiers and their invocations',
+        'Require or disallow spacing between function identifiers and their invocations',
       category: 'Stylistic Issues',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/indent.ts b/packages/eslint-plugin/src/rules/indent.ts
@@ -88,7 +88,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'layout',
     docs: {
       description: 'Enforce consistent indentation',
-      tslintRuleName: 'indent',
       category: 'Stylistic Issues',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/interface-name-prefix.ts b/packages/eslint-plugin/src/rules/interface-name-prefix.ts
@@ -9,7 +9,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Require that interface names be prefixed with `I`',
-      tslintRuleName: 'interface-name',
       category: 'Stylistic Issues',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/member-naming.ts b/packages/eslint-plugin/src/rules/member-naming.ts
@@ -16,7 +16,7 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description:
-        'Enforces naming conventions for class members by visibility.',
+        'Enforces naming conventions for class members by visibility',
       category: 'Stylistic Issues',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/member-ordering.ts b/packages/eslint-plugin/src/rules/member-ordering.ts
@@ -46,7 +46,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Require a consistent member declaration order',
-      tslintRuleName: 'member-ordering',
       category: 'Stylistic Issues',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/no-angle-bracket-type-assertion.ts b/packages/eslint-plugin/src/rules/no-angle-bracket-type-assertion.ts
@@ -7,7 +7,6 @@ export default util.createRule({
     docs: {
       description:
         'Enforces the use of `as Type` assertions instead of `<Type>` assertions',
-      tslintRuleName: 'no-angle-bracket-type-assertion',
       category: 'Stylistic Issues',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-empty-interface.ts b/packages/eslint-plugin/src/rules/no-empty-interface.ts
@@ -13,7 +13,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Disallow the declaration of empty interfaces',
-      tslintRuleName: 'no-empty-interface',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-explicit-any.ts b/packages/eslint-plugin/src/rules/no-explicit-any.ts
@@ -6,7 +6,6 @@ export default util.createRule({
     type: 'suggestion',
     docs: {
       description: 'Disallow usage of the `any` type',
-      tslintRuleName: 'no-any',
       category: 'Best Practices',
       recommended: 'warn',
     },

diff --git a/packages/eslint-plugin/src/rules/no-extra-parens.ts b/packages/eslint-plugin/src/rules/no-extra-parens.ts
@@ -14,7 +14,7 @@ export default util.createRule<Options, MessageIds>({
   meta: {
     type: 'layout',
     docs: {
-      description: 'disallow unnecessary parentheses',
+      description: 'Disallow unnecessary parentheses',
       category: 'Possible Errors',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/no-extraneous-class.ts b/packages/eslint-plugin/src/rules/no-extraneous-class.ts
@@ -19,7 +19,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Forbids the use of classes as namespaces',
-      tslintRuleName: 'no-unnecessary-class',
       category: 'Best Practices',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/no-for-in-array.ts b/packages/eslint-plugin/src/rules/no-for-in-array.ts
@@ -8,7 +8,6 @@ export default util.createRule({
       description: 'Disallow iterating over an array with a for-in loop',
       category: 'Best Practices',
       recommended: false,
-      tslintName: 'no-for-in-array',
     },
     messages: {
       forInViolation:

diff --git a/packages/eslint-plugin/src/rules/no-inferrable-types.ts b/packages/eslint-plugin/src/rules/no-inferrable-types.ts
@@ -18,8 +18,7 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description:
-        'Disallows explicit type declarations for variables or parameters initialized to a number, string, or boolean.',
-      tslintRuleName: 'no-inferrable-types',
+        'Disallows explicit type declarations for variables or parameters initialized to a number, string, or boolean',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-magic-numbers.ts b/packages/eslint-plugin/src/rules/no-magic-numbers.ts
@@ -1,8 +1,3 @@
-/**
- * @fileoverview Rule to flag statements that use magic numbers (adapted from https://github.com/danielstjules/buddy.js)
- * @author Scott O'Hara
- */
-
 import {
   TSESTree,
   AST_NODE_TYPES,
@@ -21,7 +16,7 @@ export default util.createRule<Options, MessageIds>({
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'Disallow magic numbers',
+      description: 'Disallows magic numbers',
       category: 'Best Practices',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/no-misused-new.ts b/packages/eslint-plugin/src/rules/no-misused-new.ts
@@ -9,8 +9,7 @@ export default util.createRule({
   meta: {
     type: 'problem',
     docs: {
-      description: 'Enforce valid definition of `new` and `constructor`.',
-      tslintRuleName: 'no-misused-new',
+      description: 'Enforce valid definition of `new` and `constructor`',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-namespace.ts b/packages/eslint-plugin/src/rules/no-namespace.ts
@@ -19,7 +19,6 @@ export default util.createRule<Options, MessageIds>({
     docs: {
       description:
         'Disallow the use of custom TypeScript modules and namespaces',
-      tslintRuleName: 'no-namespace',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-non-null-assertion.ts b/packages/eslint-plugin/src/rules/no-non-null-assertion.ts
@@ -7,7 +7,6 @@ export default util.createRule({
     docs: {
       description:
         'Disallows non-null assertions using the `!` postfix operator',
-      tslintRuleName: 'no-non-null-assertion',
       category: 'Stylistic Issues',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-object-literal-type-assertion.ts b/packages/eslint-plugin/src/rules/no-object-literal-type-assertion.ts
@@ -18,7 +18,6 @@ export default util.createRule<Options, MessageIds>({
     docs: {
       description:
         'Forbids an object literal to appear in a type assertion expression',
-      tslintRuleName: 'no-object-literal-type-assertion',
       category: 'Stylistic Issues',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-parameter-properties.ts b/packages/eslint-plugin/src/rules/no-parameter-properties.ts
@@ -25,8 +25,7 @@ export default util.createRule<Options, MessageIds>({
     type: 'problem',
     docs: {
       description:
-        'Disallow the use of parameter properties in class constructors.',
-      tslintRuleName: 'no-parameter-properties',
+        'Disallow the use of parameter properties in class constructors',
       category: 'Stylistic Issues',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-require-imports.ts b/packages/eslint-plugin/src/rules/no-require-imports.ts
@@ -6,8 +6,7 @@ export default util.createRule({
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallows invocation of `require()`.',
-      tslintName: 'no-require-imports',
+      description: 'Disallows invocation of `require()`',
       category: 'Best Practices',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/no-this-alias.ts b/packages/eslint-plugin/src/rules/no-this-alias.ts
@@ -18,7 +18,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Disallow aliasing `this`',
-      tslintRuleName: 'no-this-assignment',
       category: 'Best Practices',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/no-triple-slash-reference.ts b/packages/eslint-plugin/src/rules/no-triple-slash-reference.ts
@@ -6,7 +6,6 @@ export default util.createRule({
     type: 'suggestion',
     docs: {
       description: 'Disallow `/// <reference path="" />` comments',
-      tslintRuleName: 'no-reference',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/no-type-alias.ts b/packages/eslint-plugin/src/rules/no-type-alias.ts
@@ -36,7 +36,6 @@ export default util.createRule<Options, MessageIds>({
     type: 'suggestion',
     docs: {
       description: 'Disallow the use of type aliases',
-      tslintRuleName: 'interface-over-type-literal',
       category: 'Stylistic Issues',
       recommended: false,
     },

diff --git a/packages/eslint-plugin/src/rules/no-unnecessary-qualifier.ts b/packages/eslint-plugin/src/rules/no-unnecessary-qualifier.ts
@@ -8,9 +8,8 @@ export default util.createRule({
   meta: {
     docs: {
       category: 'Best Practices',
-      description: 'Warns when a namespace qualifier is unnecessary.',
+      description: 'Warns when a namespace qualifier is unnecessary',
       recommended: false,
-      tslintName: 'no-unnecessary-qualifier',
     },
     fixable: 'code',
     messages: {

diff --git a/packages/eslint-plugin/src/rules/no-unnecessary-type-assertion.ts b/packages/eslint-plugin/src/rules/no-unnecessary-type-assertion.ts
@@ -28,7 +28,6 @@ export default util.createRule<Options, MessageIds>({
         'Warns if a type assertion does not change the type of an expression',
       category: 'Best Practices',
       recommended: false,
-      tslintRuleName: 'no-unnecessary-type-assertion',
     },
     fixable: 'code',
     messages: {

diff --git a/packages/eslint-plugin/src/rules/no-unused-vars.ts b/packages/eslint-plugin/src/rules/no-unused-vars.ts
@@ -11,7 +11,6 @@ export default util.createRule({
     type: 'problem',
     docs: {
       description: 'Disallow unused variables',
-      tslintRuleName: 'no-unused-variable',
       category: 'Variables',
       recommended: 'warn',
     },

diff --git a/packages/eslint-plugin/src/rules/no-var-requires.ts b/packages/eslint-plugin/src/rules/no-var-requires.ts
@@ -11,7 +11,6 @@ export default util.createRule<Options, MessageIds>({
     docs: {
       description:
         'Disallows the use of require statements except in import statements',
-      tslintRuleName: 'no-var-requires',
       category: 'Best Practices',
       recommended: 'error',
     },

diff --git a/packages/eslint-plugin/src/rules/prefer-for-of.ts b/packages/eslint-plugin/src/rules/prefer-for-of.ts
@@ -11,10 +11,9 @@ export default util.createRule({
     type: 'suggestion',
     docs: {
       description:
-        'Prefer a ‘for-of’ loop over a standard ‘for’ loop if the index is only used to access the array being iterated.',
+        'Prefer a ‘for-of’ loop over a standard ‘for’ loop if the index is only used to access the array being iterated',
       category: 'Stylistic Issues',
       recommended: false,
-      tslintName: 'prefer-for-of',
     },
     messages: {
       preferForOf: