docs(build): jsdoc annotations (#38)

* actions, align push, pull, docs check
* build, eslint jsdocs, generate code docs
* package, avoid package generated doc

.eslintrc

@@ -3,9 +3,10 @@
     "es2022": true,
     "jest": true
   },
-  "plugins": ["node", "prettier"],
+  "plugins": ["jsdoc", "node", "prettier"],
   "extends": [
     "eslint:recommended",
+    "plugin:jsdoc/recommended",
     "plugin:node/recommended",
     "plugin:prettier/recommended"
   ],
@@ -30,6 +31,27 @@
     "arrow-parens": ["error", "as-needed"],
     "comma-dangle": 0,
     "consistent-return": 1,
+    "jsdoc/no-undefined-types": 2,
+    "jsdoc/require-jsdoc": 2,
+    "jsdoc/require-param": 2,
+    "jsdoc/require-param-description": 0,
+    "jsdoc/require-param-name": 2,
+    "jsdoc/require-param-type": 2,
+    "jsdoc/require-property": 2,
+    "jsdoc/require-property-description": 0,
+    "jsdoc/require-property-name": 2,
+    "jsdoc/require-property-type": 2,
+    "jsdoc/require-returns": 2,
+    "jsdoc/require-returns-description": 0,
+    "jsdoc/require-returns-type": 2,
+    "jsdoc/tag-lines": [
+      "warn",
+      "always",
+      {
+        "count": 0,
+        "noEndLines": true
+      }
+    ],
     "max-len": [
       "error",
       {

.github/workflows/commit_lint.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [16.x]
+        node-version: [18.x]
     steps:
       - uses: actions/checkout@v3
         with:

.github/workflows/documentation_lint.yml

@@ -0,0 +1,48 @@
+name: Documentation lint
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  Documentation:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: yarn
+      - name: Node.js modules cache
+        uses: actions/cache@v3
+        id: modules-cache
+        with:
+          path: ${{ github.workspace }}/node_modules
+          key: ${{ runner.os }}-${{ matrix.node-version }}-modules-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ matrix.node-version }}-modules
+      - name: Install Node.js packages
+        if: ${{ steps.modules-cache.outputs.cache-hit != 'true' }}
+        run: yarn install
+      - name: Build
+        run: yarn build:docs
+      - name: Git modified files
+        if: ${{ success() }}
+        run: |
+          echo 'GIT_MODIFIED<<EOF' >> $GITHUB_ENV
+          git ls-files -m >> $GITHUB_ENV
+          echo 'EOF' >> $GITHUB_ENV
+      - name: Lint
+        if: ${{ success() }}
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const actionCommit = require(`${process.env.GITHUB_WORKSPACE}/scripts/actions.documentation.js`)
+            const { resultsArray, resultsString } = actionCommit(process.env.GIT_MODIFIED)
+            if (resultsArray.length) {
+              core.setFailed(resultsString)
+            }

.npmignore

@@ -7,4 +7,3 @@ src/**/*test.js
 src/**/*.archive
 !LICENSE
 !README.md
-!CHANGELOG.md

package.json

@@ -22,18 +22,24 @@
   "engines": {
     "node": ">=14.0.0"
   },
+  "files": [
+    "src/*.js"
+  ],
   "bin": {
     "changelog": "./bin/cli.js"
   },
   "scripts": {
     "build:deps": "bash ./scripts/dependencies.sh --doctor -u --doctorInstall \"yarn\" --doctorTest \"yarn test:deps\"",
+    "build:docs": "run-s -l test:docs docs:md",
+    "docs:md": "node ./scripts/readme.docs.js",
     "release": "node ./bin/cli.js",
     "start": "./bin/cli.js",
     "test": "run-s -l test:lint test:spell* test:ci",
     "test:ci": "export CI=true; jest --collectCoverage",
     "test:clearCache": "jest --clearCache",
     "test:deps": "run-s test",
     "test:dev": "eslint ./src ./bin; run-s test:spell test:local",
+    "test:docs": "run-s test:spell test:lint",
     "test:integration": "jest --roots=./tests",
     "test:integration-dev": "jest --roots=./tests --watchAll",
     "test:lint": "eslint ./src ./bin",
@@ -78,6 +84,7 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^4.2.1",
     "jest": "^29.4.3",
+    "jsdoc-to-markdown": "^8.0.0",
     "npm-check-updates": "^16.7.9",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.8.4"

scripts/actions.documentation.js

@@ -0,0 +1,33 @@
+/**
+ * Breakout individual files for filtering.
+ *
+ * @param {string} files
+ * @returns {Array<string>}
+ */
+const filterFiles = files =>
+  files
+    .trim()
+    .split(/\n/g)
+    .filter(file => {
+      const updatedFile = file.trim();
+      return updatedFile.length > 0 && /README\.md$/.test(updatedFile);
+    })
+    .map(file => `File > ${file} > is modified. Update README with '$ yarn build:docs'`);
+
+/**
+ * If modified files exist, throw an error.
+ *
+ * @param {string} files
+ * @returns {{resultsArray: Array, resultsString: string}}
+ */
+module.exports = files => {
+  const lintResults = { resultsArray: [], resultsString: '' };
+
+  if (files) {
+    const parsedResults = filterFiles(files);
+    lintResults.resultsArray = parsedResults;
+    lintResults.resultsString = JSON.stringify(parsedResults, null, 2);
+  }
+
+  return lintResults;
+};

scripts/readme.docs.js

@@ -0,0 +1,25 @@
+const { writeFileSync } = require('fs');
+const { join } = require('path');
+const jsdoc2md = require('jsdoc-to-markdown');
+
+/**
+ * Run jsdoc2md on files, output a README
+ *
+ * @param {object} params
+ * @param {string} params.input
+ * @param {string} params.output
+ */
+const generateReadMe = ({ input, output } = {}) => {
+  try {
+    const outputPath = join(process.cwd(), output);
+    const docs = jsdoc2md.renderSync({ files: input, 'no-gfm': true });
+    writeFileSync(outputPath, docs);
+    console.info(`Generate README success > ${input}`);
+  } catch (e) {
+    console.warn(`Generate README failed > ${input} > `, e.message);
+  }
+};
+
+((files = []) => {
+  Promise.all(files.map(obj => generateReadMe(obj)));
+})([{ input: './src/*.js', output: './src/README.md' }]);