npm package: @mimik/eslint-plugin-document-env
Description: validation of environment variable documentation
Author: mimik technology inc
Latest version: 2.1.0

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

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',
    },
  },
];
```

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

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

MIT