refactor: separate test and doc checks

Author: gajus

CONTRIBUTING.md

@@ -6,7 +6,7 @@
 
 When making a commit, the following Pre-Commit hooks run:
 
-* tests and docs checks
+* test and documentation checks
 * tests
 * lint
 * commit message validation (see "Commit Messages" below)
@@ -21,11 +21,11 @@ All commit messages must begin with one of the following prefixes:
 * `docs: `
 * `chore: `
 
-The prefix is used to bump the correct segment of the version number automatically during deploy.
+The prefix is used to bump the correct segment of the version number during the automatic release.
 
 ## Tests
 
-Run them with `npm t`.
+Run them with `npm test`.
 
 ## Lint
 
@@ -50,4 +50,4 @@ Run with `npm run lint`.
 
 A CI service will build and publish the new documentation.
 
-Note: The section "The following patterns are considered problems:" and "The following patterns are not considered problems:" is **generated automatically** using the test cases.
+Note: Sections "The following patterns are considered problems:" and "The following patterns are not considered problems:" are **generated automatically** using the test cases.

bin/testsAndDocsCheck.js

@@ -29,6 +29,12 @@
   "engines": {
     "node": ">=4"
   },
+  "husky": {
+    "hooks": {
+      "post-commit": "npm run create-readme && git add README.md && git commit -m 'docs: generate docs' --no-verify",
+      "pre-commit": "npm run check-docs && npm run check-tests && npm run lint && npm run test && npm run build && npm run format-json"
+    }
+  },
   "keywords": [
     "eslint",
     "plugin",
@@ -40,22 +46,17 @@
   "peerDependencies": {
     "eslint": ">=2.0.0"
   },
-  "husky": {
-    "hooks": {
-      "post-commit": "npm run create-readme && git add README.md && git commit -m 'docs: generate docs' --no-verify",
-      "pre-commit": "npm run tests-docs-check && npm run lint && npm run test && npm run build && npm run format-json"
-    }
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/gajus/eslint-plugin-flowtype"
   },
   "scripts": {
     "build": "rm -fr ./dist && babel ./src --out-dir ./dist --copy-files",
+    "check-docs": "babel-node ./src/bin/checkDocs",
+    "check-tests": "babel-node ./src/bin/checkTests",
     "create-readme": "gitdown ./.README/README.md --output-file ./README.md && npm run documentation-add-assertions",
-    "documentation-add-assertions": "babel-node ./bin/readmeAssertions",
+    "documentation-add-assertions": "babel-node ./bin/addAssertions",
     "format-json": "jsonlint --sort-keys --in-place --indent '  ' ./src/configs/recommended.json && echo '' >> ./src/configs/recommended.json",
-    "tests-docs-check": "babel-node ./bin/testsAndDocsCheck",
     "lint": "eslint ./src ./tests",
     "test": "mocha --compilers js:babel-register ./tests/rules/index.js"
   },

package.json

@@ -1,5 +1,7 @@
+#!/usr/bin/env node
+
 /**
- * This script is used to inline assertions into the README.md documents.
+ * @file This script is used to inline assertions into the README.md documents.
  */
 
 import path from 'path';

bin/readmeAssertions.js renamed to src/bin/addAssertions.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+// @flow
+
+import fs from 'fs';
+import path from 'path';
+import {
+  getRules,
+  isFile
+} from './utilities';
+
+const windows = (array, size) => {
+  const output = [];
+
+  for (let ii = 0; ii < array.length - size + 1; ii++) {
+    output.push(array.slice(ii, ii + size));
+  }
+
+  return output;
+};
+
+const getDocIndexRules = () => {
+  const content = fs.readFileSync(path.resolve(__dirname, '../../.README/README.md'), 'utf-8');
+
+  const rules = content.split('\n').map((line) => {
+    const match = /^{"gitdown": "include", "file": "([^"]+)"}$/.exec(line);
+
+    if (match === null) {
+      return null;
+    } else {
+      return match[1].replace('./rules/', '').replace('.md', '');
+    }
+  }).filter((rule) => {
+    return rule !== null;
+  });
+
+  if (rules.length === 0) {
+    throw new Error('Docs checker is broken - it could not extract rules from docs index file.');
+  }
+
+  return rules;
+};
+
+const hasCorrectAssertions = (docPath, name) => {
+  const content = fs.readFileSync(docPath, 'utf-8');
+
+  const match = /<!-- assertions ([a-zA-Z]+) -->/.exec(content);
+
+  if (match === null) {
+    return false;
+  } else {
+    return match[1] === name;
+  }
+};
+
+/**
+ * Performed checks:
+ *  - file `/.README/rules/<rule>.md` exists
+ *  - file `/.README/rules/<rule>.md` contains correct assertions placeholder (`<!-- assertions ... -->`)
+ *  - rule is included in gitdown directive in `/.README/README.md`
+ *  - rules in `/.README/README.md` are alphabetically sorted
+ */
+const checkDocs = (rulesNames) => {
+  const docIndexRules = getDocIndexRules();
+
+  const sorted = windows(docIndexRules, 2)
+    .every((chunk) => {
+      return chunk[0] < chunk[1];
+    });
+
+  if (!sorted) {
+    throw new Error('Rules are not alphabetically sorted in `.README/README.md` file.');
+  }
+
+  const invalid = rulesNames.filter((names) => {
+    const docPath = path.resolve(__dirname, '../../.README/rules', names[1] + '.md');
+    const docExists = isFile(docPath);
+    const inIndex = docIndexRules.indexOf(names[1]) !== -1;
+    const hasAssertions = docExists ? hasCorrectAssertions(docPath, names[0]) : false;
+
+    return !(docExists && inIndex && hasAssertions);
+  });
+
+  if (invalid.length > 0) {
+    const invalidList = invalid
+      .map((names) => {
+        return names[0];
+      }).join(', ');
+
+    throw new Error(
+      'Docs checker encountered an error in: ' + invalidList + '. ' +
+      'Make sure that for every rule you created documentation file with assertions placeholder in camelCase ' +
+      'and included the file path in `.README/README.md` file.'
+    );
+  }
+};
+
+checkDocs(getRules());