@mimik/eslint-plugin-document-env

An ESLint plugin that validates that all process.env usages are properly documented in markdown-style block comments.

Installation

npm install --save-dev @mimik/eslint-plugin-document-env

Usage

Add the plugin to your eslint.config.js:

import documentEnv from '@mimik/eslint-plugin-document-env';

export default [
  {
    plugins: {
      '@mimik/document-env': documentEnv,
    },
    rules: {
      '@mimik/document-env/validate-document-env': 'error',
    },
  },
];

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:

 * | 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

| 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 |

Example

/**
 * | 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

isProcessEnvAccess(node) ⇒ boolean

Checks whether an AST node represents a process.env member expression.

Kind: global function
Returns: boolean - true if the node is a non-computed process.env access.

| Param | Type | Description | | --- | --- | --- | | node | Object | The AST MemberExpression node to check. |

regular(propName) ⇒ RegExp

Builds a regex that matches a documentation table row for the given env variable name.

Kind: global function
Returns: RegExp - A multiline, global, unicode regex with two capture groups: (1) the variable name and (2) the description cell content.

| Param | Type | Description | | --- | --- | --- | | propName | string | The environment variable name to search for. |

extractEnvVarName(node, context) ⇒ string | undefined

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: string | undefined - The env variable name, or undefined if the property node is missing.

| Param | Type | Description | | --- | --- | --- | | node | Object | The process.env MemberExpression node. | | context | Object | The ESLint rule context. |

findEnvDocInComments(comments, regex) ⇒ Array.<Object>

Finds block comments that contain a documentation table entry for the given env variable.

Kind: global function
Returns: Array.<Object> - Matching block comments.

| Param | Type | Description | | --- | --- | --- | | comments | Array.<Object> | All comments in the source file. | | regex | RegExp | The regex to match the env variable documentation row. |

License

MIT