@mimik/eslint-plugin-document-env 2.0.8 → 2.0.9

package/README.md

@@ -1,31 +1,144 @@
-# eslint-plugin-document-env
-An ESLint plugin that validates that all process.env usages are properly documented in markdown-style block comments.
+# @mimik/eslint-plugin-document-env
+
+An ESLint plugin that validates that all `process.env` usages are properly documented in markdown-style block comments.
+
+## Installation
+
+```bash
+npm install --save-dev @mimik/eslint-plugin-document-env
+```
+
 ## Usage
 
-```sh
-npm install @mimik/eslint-plugin-document-env
+Add the plugin to your `eslint.config.js`:
+
+```js
+import documentEnv from '@mimik/eslint-plugin-document-env';
+
+export default [
+  {
+    plugins: {
+      '@mimik/document-env': documentEnv,
+    },
+    rules: {
+      '@mimik/document-env/validate-document-env': 'error',
+    },
+  },
+];
 ```
 
-In your `.eslintrc`:
-
-```json
-{
-  "plugins": [
-    "@mimik/document-env"
-  ],
-  "rules": {
-    "@mimik/document-env/validate-document-env": 2
-  }
-}
+## Rule: `validate-document-env`
+
+Verifies that when an environment variable is used via `process.env`, there is a corresponding documentation entry in a block comment with the following table header:
+
 ```
-## Rules
+ * | Env variable name | Description | Default | Comments |
+ * | ----------------- | ----------- | ------- | -------- |
+```
+
+### What Gets Checked
+
+- Every `process.env.VAR_NAME` or `process.env['VAR_NAME']` access must have a matching row in a documentation table
+- The description column must not be empty or blank
+- The variable must not be documented more than once (across separate tables or within the same table)
+
+### Messages
 
-An [eslint](https://github.com/eslint/eslint) plugin that ...
+| Message ID | Description |
+|---|---|
+| `unDocumentedProcessEnv` | No documentation table entry found for the variable |
+| `unDescribedProcessEnv` | Table entry exists but the description column is empty |
+| `duplicatedProcessEnv` | Variable is documented in multiple tables or multiple rows |
 
-### `document-env/validate-document-env`
+### Example
 
-Verifies that when an environment variable is used, there is a documentation about it after the following header: 
+```js
+/**
  * | Env variable name | Description | Default | Comments |
  * | ----------------- | ----------- | ------- | -------- |
+ * | PORT | The port the server listens on | 3000 | |
+ * | NODE_ENV | Runtime environment | development | |
+ */
+const port = process.env.PORT;        // OK
+const env = process.env.NODE_ENV;     // OK
+const secret = process.env.SECRET;    // Error: Undocumented environment variable: SECRET
+```
+
+## API Reference
+
+## Functions
+
+<dl>
+<dt><a href="#isProcessEnvAccess">isProcessEnvAccess(node)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Checks whether an AST node represents a <code>process.env</code> member expression.</p>
+</dd>
+<dt><a href="#regular">regular(propName)</a> ⇒ <code>RegExp</code></dt>
+<dd><p>Builds a regex that matches a documentation table row for the given env variable name.</p>
+</dd>
+<dt><a href="#extractEnvVarName">extractEnvVarName(node, context)</a> ⇒ <code>string</code> | <code>undefined</code></dt>
+<dd><p>Extracts the environment variable name from a <code>process.env.X</code> or <code>process.env[&#39;X&#39;]</code> access.
+For computed access with a non-literal key (e.g. <code>process.env[varName]</code>), falls back to
+extracting the source text of the computed expression.</p>
+</dd>
+<dt><a href="#findEnvDocInComments">findEnvDocInComments(comments, regex)</a> ⇒ <code>Array.&lt;Object&gt;</code></dt>
+<dd><p>Finds block comments that contain a documentation table entry for the given env variable.</p>
+</dd>
+</dl>
+
+<a name="isProcessEnvAccess"></a>
+
+## isProcessEnvAccess(node) ⇒ <code>boolean</code>
+Checks whether an AST node represents a `process.env` member expression.
+
+**Kind**: global function  
+**Returns**: <code>boolean</code> - `true` if the node is a non-computed `process.env` access.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| node | <code>Object</code> | The AST MemberExpression node to check. |
+
+<a name="regular"></a>
+
+## regular(propName) ⇒ <code>RegExp</code>
+Builds a regex that matches a documentation table row for the given env variable name.
+
+**Kind**: global function  
+**Returns**: <code>RegExp</code> - A multiline, global, unicode regex with two capture groups:
+  (1) the variable name and (2) the description cell content.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| propName | <code>string</code> | The environment variable name to search for. |
+
+<a name="extractEnvVarName"></a>
+
+## extractEnvVarName(node, context) ⇒ <code>string</code> \| <code>undefined</code>
+Extracts the environment variable name from a `process.env.X` or `process.env['X']` access.
+For computed access with a non-literal key (e.g. `process.env[varName]`), falls back to
+extracting the source text of the computed expression.
+
+**Kind**: global function  
+**Returns**: <code>string</code> \| <code>undefined</code> - The env variable name, or `undefined` if the property node is missing.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| node | <code>Object</code> | The `process.env` MemberExpression node. |
+| context | <code>Object</code> | The ESLint rule context. |
+
+<a name="findEnvDocInComments"></a>
+
+## findEnvDocInComments(comments, regex) ⇒ <code>Array.&lt;Object&gt;</code>
+Finds block comments that contain a documentation table entry for the given env variable.
+
+**Kind**: global function  
+**Returns**: <code>Array.&lt;Object&gt;</code> - Matching block comments.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| comments | <code>Array.&lt;Object&gt;</code> | All comments in the source file. |
+| regex | <code>RegExp</code> | The regex to match the env variable documentation row. |
+
+
+## License
 
-The plugin also verifies that there is a non-empty or blank description and that the description is not duplicated.
+MIT

package/index.js

@@ -1,3 +1,7 @@
+import { createRequire } from 'node:module';
+
+const { version, name } = createRequire(import.meta.url)('./package.json');
+
 const HEADER = ' * | Env variable name | Description | Default | Comments |\n';
 const LINE = ' * | ----------------- | ----------- | ------- | -------- |\n';
 const SINGLE = 1;
@@ -5,42 +9,80 @@ const NO_DESCRIPTION = 2;
 const FIRST = 0;
 const EMPTY = 0;
 
+/**
+ * Checks whether an AST node represents a `process.env` member expression.
+ * @param {Object} node - The AST MemberExpression node to check.
+ * @returns {boolean} `true` if the node is a non-computed `process.env` access.
+ */
 const isProcessEnvAccess = node => (
   node.object?.name === 'process'
   && !node.computed
   && node.property?.name === 'env'
 );
+
+/**
+ * Builds a regex that matches a documentation table row for the given env variable name.
+ * @param {string} propName - The environment variable name to search for.
+ * @returns {RegExp} A multiline, global, unicode regex with two capture groups:
+ *   (1) the variable name and (2) the description cell content.
+ */
 const regular = propName => new RegExp(
-  `^ \\* \\| (${propName.replace(/[|\\{}()[\]^$+*?.]/gu, '\\$&')}) \\| *([^\\|]*)`,
+  `^ \\* \\| (${propName.replace(/[|\\{}()[\]^$+*?.]/gu, '\\$&')}) \\| *([^|]*)`,
   'mgu',
 );
-const extractEnvVarName = (node, context) => node.parent?.property?.name
-  || context.getSourceCode().text.slice(node.parent.property.start, node.parent.property.end);
-const findEnvDocInComments = (comments, propName) => {
-  const regex = regular(propName);
 
-  return comments.filter(comment =>
-    comment.type === 'Block'
-    && comment.value.includes(HEADER)
-    && comment.value.includes(LINE)
-    && comment.value.match(regex),
-  );
+/**
+ * Extracts the environment variable name from a `process.env.X` or `process.env['X']` access.
+ * For computed access with a non-literal key (e.g. `process.env[varName]`), falls back to
+ * extracting the source text of the computed expression.
+ * @param {Object} node - The `process.env` MemberExpression node.
+ * @param {Object} context - The ESLint rule context.
+ * @returns {string|undefined} The env variable name, or `undefined` if the property node is missing.
+ */
+const extractEnvVarName = (node, context) => {
+  const prop = node.parent?.property;
+
+  if (!prop) return undefined;
+  if (prop.name) return prop.name;
+  if (prop.value) return String(prop.value);
+
+  return context.sourceCode.text.slice(prop.range[FIRST], prop.range[SINGLE]);
 };
 
+/**
+ * Finds block comments that contain a documentation table entry for the given env variable.
+ * @param {Array.<Object>} comments - All comments in the source file.
+ * @param {RegExp} regex - The regex to match the env variable documentation row.
+ * @returns {Array.<Object>} Matching block comments.
+ */
+const findEnvDocInComments = (comments, regex) => comments.filter(comment =>
+  comment.type === 'Block'
+  && comment.value.includes(HEADER)
+  && comment.value.includes(LINE)
+  && comment.value.match(regex),
+);
+
 const plugin = {
+  meta: {
+    name,
+    version,
+  },
   rules: {
     'validate-document-env': {
       create(context) {
-        const { comments } = context.getSourceCode().ast;
+        const { comments } = context.sourceCode.ast;
 
         return {
           MemberExpression(node) {
             if (!isProcessEnvAccess(node) || !node.parent?.property) return;
 
             const propName = extractEnvVarName(node, context);
-            const matchedComment = findEnvDocInComments(comments, propName);
 
-            if (!matchedComment || matchedComment.length === EMPTY) {
+            if (!propName) return;
+            const regex = regular(propName);
+            const matchedComment = findEnvDocInComments(comments, regex);
+
+            if (matchedComment.length === EMPTY) {
               context.report({
                 node,
                 messageId: 'unDocumentedProcessEnv',
@@ -56,7 +98,6 @@ const plugin = {
               });
               return;
             }
-            const regex = regular(propName);
             let match = matchedComment[FIRST].value.match(regex);
 
             if (match?.length > SINGLE) {
@@ -68,7 +109,7 @@ const plugin = {
             }
             else {
               match = regex.exec(matchedComment[FIRST].value);
-              if (!match[NO_DESCRIPTION]) {
+              if (!match || !match[NO_DESCRIPTION]) {
                 context.report({
                   node,
                   messageId: 'unDescribedProcessEnv',

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@mimik/eslint-plugin-document-env",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "validation of environment variable documentation",
   "main": "./index.js",
   "type": "module",
+  "exports": "./index.js",
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "scripts": {
+    "docs": "jsdoc2md --template docs/README.hbs index.js > README.md",
     "lint": "eslint . --no-error-on-unmatched-pattern",
-    "test": "node --test test/*.test.js",
-    "prepublishOnly": "npm run lint && npm run test"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "npm run commit-ready",
-      "pre-push": "npm run test"
-    }
+    "test": "mocha --reporter mochawesome --bail --exit --check-leaks test/",
+    "test-ci": "c8 --reporter=lcov --reporter=text npm test",
+    "prepublishOnly": "npm run docs && npm run lint && npm run test-ci",
+    "commit-ready": "npm run docs && npm run lint && npm run test-ci"
   },
   "keywords": [
     "mimik",
@@ -29,10 +30,15 @@
     "url": "git+https://bitbucket.org/mimiktech/eslint-plugin-document-env.git"
   },
   "devDependencies": {
-    "@eslint/js": "9.31.0",
-    "@stylistic/eslint-plugin": "5.2.0",
-    "eslint": "9.31.0",
+    "@eslint/js": "9.39.4",
+    "@stylistic/eslint-plugin": "5.10.0",
+    "c8": "11.0.0",
+    "eslint": "9.39.4",
     "eslint-plugin-import": "2.32.0",
-    "husky": "9.1.7"
+    "globals": "17.4.0",
+    "husky": "9.1.7",
+    "jsdoc-to-markdown": "9.1.3",
+    "mocha": "11.7.5",
+    "mochawesome": "7.1.4"
   }
 }

package/eslint.config.js

@@ -1,58 +0,0 @@
-import importPlugin from 'eslint-plugin-import';
-import js from '@eslint/js';
-import stylistic from '@stylistic/eslint-plugin';
-
-const MAX_LENGTH_LINE = 180;
-const MAX_FUNCTION_PARAMETERS = 6;
-const MAX_LINES_IN_FILES = 600;
-const MAX_LINES_IN_FUNCTION = 150;
-const MAX_STATEMENTS_IN_FUNCTION = 45;
-const MIN_KEYS_IN_OBJECT = 10;
-const MAX_COMPLEXITY = 30;
-
-export default [
-  {
-    ignores: ['mochawesome-report/**', 'node_modules/**', 'dist/**'],
-  },
-  importPlugin.flatConfigs.recommended,
-  stylistic.configs['recommended-flat'],
-  js.configs.all,
-  {
-    languageOptions: {
-      ecmaVersion: 2022,
-      globals: {
-        console: 'readonly',
-        describe: 'readonly',
-        it: 'readonly',
-        require: 'readonly',
-      },
-      sourceType: 'module',
-    },
-    rules: {
-      '@stylistic/brace-style': ['warn', 'stroustrup', { allowSingleLine: true }],
-      '@stylistic/line-comment-position': ['off'],
-      '@stylistic/semi': ['error', 'always'],
-      'capitalized-comments': ['off'],
-      'complexity': ['error', MAX_COMPLEXITY],
-      'curly': ['off'],
-      'id-length': ['error', { exceptions: ['x', 'y', 'z', 'i', 'j', 'k'] }],
-      'import/no-extraneous-dependencies': ['error', { devDependencies: true }],
-      'import/no-unresolved': ['error', { amd: true, caseSensitiveStrict: true, commonjs: true }],
-      'init-declarations': ['off'],
-      'linebreak-style': ['off'],
-      'max-len': ['warn', MAX_LENGTH_LINE, { ignoreComments: true }],
-      'max-lines': ['warn', { max: MAX_LINES_IN_FILES, skipComments: true }],
-      'max-lines-per-function': ['warn', { max: MAX_LINES_IN_FUNCTION, skipComments: true }],
-      'max-params': ['error', MAX_FUNCTION_PARAMETERS],
-      'max-statements': ['warn', MAX_STATEMENTS_IN_FUNCTION],
-      'no-confusing-arrow': ['off'], // arrow isnt confusing
-      'no-inline-comments': ['off'],
-      'no-process-env': ['error'],
-      'no-ternary': ['off'],
-      'no-undefined': ['off'],
-      'one-var': ['error', 'never'],
-      'quotes': ['warn', 'single'],
-      'sort-keys': ['error', 'asc', { caseSensitive: true, minKeys: MIN_KEYS_IN_OBJECT, natural: false }],
-    },
-  },
-];

package/test/validate-document-env.test.js

@@ -1,69 +0,0 @@
-import { RuleTester } from 'eslint';
-import rule from '../index.js';
-
-const tester = new RuleTester({
-  languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
-});
-
-tester.run('validate-document-env', rule.rules['validate-document-env'], {
-  valid: [
-    {
-      code: `
-/**
- * | Env variable name | Description | Default | Comments |
- * | ----------------- | ----------- | ------- | -------- |
- * | MY_VAR | when existent on non null, will translate an IPV6 address into IPV4 address when possible | | 
- */
-        const v = process.env.MY_VAR;
-      `,
-    },
-  ],
-  invalid: [
-    {
-      code: `
-        const v = process.env.UNDOCUMENTED_VAR;
-      `,
-      errors: [{ messageId: 'unDocumentedProcessEnv' }],
-    },
-    {
-      code: `
-/**
- * | Env variable name | Description | Default | Comments |
- * | ----------------- | ----------- | ------- | -------- |
- * | UNDESCRIBED_VAR |             | none    | -        |
- */
-        const v = process.env.UNDESCRIBED_VAR;
-      `,
-      errors: [{ messageId: 'unDescribedProcessEnv' }],
-    },
-    {
-      code: `
-/**
- * | Env variable name | Description | Default | Comments |
- * | ----------------- | ----------- | ------- | -------- |
- * | DUP_VAR | a           | none    | -        |
- */
-        const separation = 'test';
-/**
- * | Env variable name | Description | Default | Comments |
- * | ----------------- | ----------- | ------- | -------- |
- * | DUP_VAR | b           | none    | -        |
- */
-        const v = process.env.DUP_VAR;
-      `,
-      errors: [{ messageId: 'duplicatedProcessEnv' }],
-    },
-    {
-      code: `
-/**
- * | Env variable name | Description | Default | Comments |
- * | ----------------- | ----------- | ------- | -------- |
- * | DUP_VAR | a           | none    | -        |
- * | DUP_VAR | b           | none    | -        |
- */
-        const v = process.env.DUP_VAR;
-        `,
-      errors: [{ messageId: 'duplicatedProcessEnv' }],
-    },
-  ],
-});