@mimik/eslint-plugin-logger 1.0.0

package/README.md

@@ -0,0 +1,204 @@
+# @mimik/eslint-plugin-logger
+
+ESLint plugin that validates logger call arguments for mimik services.
+
+## Installation
+
+```bash
+npm install --save-dev @mimik/eslint-plugin-logger
+```
+
+## Usage
+
+Add the plugin to your `eslint.config.js`:
+
+```js
+import loggerPlugin from '@mimik/eslint-plugin-logger';
+
+export default [
+  {
+    plugins: { logger: loggerPlugin },
+    rules: {
+      'logger/validate-logger-args': 'error',
+    },
+  },
+];
+```
+
+## Rule: `validate-logger-args`
+
+Validates that logger calls (on default-imported modules) use the correct argument signatures.
+
+### Valid Signatures
+
+```js
+import logger from '@mimik/sumologic-winston-logger';
+
+// (message, correlationId)
+logger.info('User logged in', correlationId);
+
+// (message, meta, correlationId)
+logger.info('User logged in', { userId: 123 }, correlationId);
+
+// (message, correlationId, options)
+logger.info('User logged in', correlationId, { type: 'audit' });
+
+// (message, meta, correlationId, options)
+logger.info('User logged in', { userId: 123 }, correlationId, { type: 'audit' });
+```
+
+### Arguments
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `message` | `string` | Yes | Log message |
+| `meta` | `object` | No | Metadata object with additional context |
+| `correlationId` | `string` | Yes | Correlation ID for request tracing |
+| `options` | `object` | No | Options object, must contain a `type` string property |
+
+### Supported Log Levels
+
+`error`, `warn`, `info`, `verbose`, `debug`, `silly`
+
+### What Gets Checked
+
+- The rule only applies to **default imports** (e.g. `import logger from '...'`)
+- Named imports (`import { logger } from '...'`) are ignored
+- Minimum 2 arguments, maximum 4
+- `message` must be a string (when passed as a literal)
+- `correlationId` must be a string (when passed as a literal)
+- `options` object must contain a `type` property with a string value
+- When 3 arguments are passed, the 2nd argument type determines the signature:
+  - Object literal → `(message, meta, correlationId)`
+  - Otherwise → `(message, correlationId, options)`
+
+## API Reference
+
+## Constants
+
+<dl>
+<dt><a href="#plugin">plugin</a> : <code>Object</code></dt>
+<dd><p>ESLint plugin for validating logger call arguments.</p>
+</dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#isNonStringLiteral">isNonStringLiteral(node)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Check whether an AST node is a non-string literal (number, boolean, null).</p>
+</dd>
+<dt><a href="#isObjectNode">isObjectNode(node)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Check whether an AST node is an object expression.</p>
+</dd>
+<dt><a href="#isTypeKey">isTypeKey(prop)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Check whether a property node has the key <code>type</code> (identifier or string literal).</p>
+</dd>
+<dt><a href="#findTypeProperty">findTypeProperty(node)</a> ⇒ <code>Object</code> | <code>undefined</code></dt>
+<dd><p>Find the <code>type</code> property node inside an ObjectExpression.
+Handles both identifier keys (<code>{ type: ... }</code>) and string-literal keys (<code>{ &quot;type&quot;: ... }</code>).</p>
+</dd>
+<dt><a href="#validateOptions">validateOptions(context, optionsArg, level)</a></dt>
+<dd><p>Validate the options argument of a logger call.
+Reports an error when the options object is missing a <code>type</code> property or when the
+<code>type</code> value is a non-string literal. Variable references (e.g. <code>{ type: someVar }</code>)
+are allowed because their runtime type cannot be determined statically.</p>
+</dd>
+<dt><a href="#validateStringArg">validateStringArg(context, argNode, level, messageId)</a></dt>
+<dd><p>Validate that a logger argument is a string when it is a literal.
+Non-literal nodes (identifiers, call expressions) are skipped because their
+runtime type cannot be determined statically.</p>
+</dd>
+</dl>
+
+<a name="plugin"></a>
+
+## plugin : <code>Object</code>
+ESLint plugin for validating logger call arguments.
+
+**Kind**: global constant  
+<a name="isNonStringLiteral"></a>
+
+## isNonStringLiteral(node) ⇒ <code>boolean</code>
+Check whether an AST node is a non-string literal (number, boolean, null).
+
+**Kind**: global function  
+**Returns**: <code>boolean</code> - True when the node is a literal whose value is not a string.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| node | <code>Object</code> | The AST node to check. |
+
+<a name="isObjectNode"></a>
+
+## isObjectNode(node) ⇒ <code>boolean</code>
+Check whether an AST node is an object expression.
+
+**Kind**: global function  
+**Returns**: <code>boolean</code> - True when the node is an ObjectExpression.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| node | <code>Object</code> | The AST node to check. |
+
+<a name="isTypeKey"></a>
+
+## isTypeKey(prop) ⇒ <code>boolean</code>
+Check whether a property node has the key `type` (identifier or string literal).
+
+**Kind**: global function  
+**Returns**: <code>boolean</code> - True when the key is `type`.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| prop | <code>Object</code> | The property node. |
+
+<a name="findTypeProperty"></a>
+
+## findTypeProperty(node) ⇒ <code>Object</code> \| <code>undefined</code>
+Find the `type` property node inside an ObjectExpression.
+Handles both identifier keys (`{ type: ... }`) and string-literal keys (`{ "type": ... }`).
+
+**Kind**: global function  
+**Returns**: <code>Object</code> \| <code>undefined</code> - The property node, or undefined if not found.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| node | <code>Object</code> | The object expression node. |
+
+<a name="validateOptions"></a>
+
+## validateOptions(context, optionsArg, level)
+Validate the options argument of a logger call.
+Reports an error when the options object is missing a `type` property or when the
+`type` value is a non-string literal. Variable references (e.g. `{ type: someVar }`)
+are allowed because their runtime type cannot be determined statically.
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| context | <code>Object</code> | The ESLint rule context. |
+| optionsArg | <code>Object</code> | The options argument AST node. |
+| level | <code>string</code> | The logger level (e.g. 'info', 'error'). |
+
+<a name="validateStringArg"></a>
+
+## validateStringArg(context, argNode, level, messageId)
+Validate that a logger argument is a string when it is a literal.
+Non-literal nodes (identifiers, call expressions) are skipped because their
+runtime type cannot be determined statically.
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| context | <code>Object</code> | The ESLint rule context. |
+| argNode | <code>Object</code> | The argument AST node. |
+| level | <code>string</code> | The logger level (e.g. 'info', 'error'). |
+| messageId | <code>string</code> | The ESLint message ID to report on failure. |
+
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,176 @@
+const LEVELS = new Set(['error', 'warn', 'info', 'verbose', 'debug', 'silly']);
+const MIN_ARGS = 2;
+const THREE_ARGS = 3;
+const MAX_ARGS = 4;
+
+/**
+ * Check whether an AST node is a non-string literal (number, boolean, null).
+ * @param {Object} node - The AST node to check.
+ * @returns {boolean} True when the node is a literal whose value is not a string.
+ */
+const isNonStringLiteral = node => node.type === 'Literal' && typeof node.value !== 'string';
+
+/**
+ * Check whether an AST node is an object expression.
+ * @param {Object} node - The AST node to check.
+ * @returns {boolean} True when the node is an ObjectExpression.
+ */
+const isObjectNode = node => node.type === 'ObjectExpression';
+
+/**
+ * Check whether a property node has the key `type` (identifier or string literal).
+ * @param {Object} prop - The property node.
+ * @returns {boolean} True when the key is `type`.
+ */
+const isTypeKey = prop => prop.type === 'Property'
+  && !prop.computed
+  && ((prop.key.type === 'Identifier' && prop.key.name === 'type')
+    || (prop.key.type === 'Literal' && prop.key.value === 'type'));
+
+/**
+ * Find the `type` property node inside an ObjectExpression.
+ * Handles both identifier keys (`{ type: ... }`) and string-literal keys (`{ "type": ... }`).
+ * @param {Object} node - The object expression node.
+ * @returns {Object|undefined} The property node, or undefined if not found.
+ */
+const findTypeProperty = node => node.properties.find(isTypeKey);
+
+/**
+ * Validate the options argument of a logger call.
+ * Reports an error when the options object is missing a `type` property or when the
+ * `type` value is a non-string literal. Variable references (e.g. `{ type: someVar }`)
+ * are allowed because their runtime type cannot be determined statically.
+ * @param {Object} context - The ESLint rule context.
+ * @param {Object} optionsArg - The options argument AST node.
+ * @param {string} level - The logger level (e.g. 'info', 'error').
+ */
+const validateOptions = (context, optionsArg, level) => {
+  if (!isObjectNode(optionsArg)) return;
+  const typeProp = findTypeProperty(optionsArg);
+  if (!typeProp) {
+    context.report({
+      node: optionsArg,
+      messageId: 'optionsMissingType',
+      data: { level },
+    });
+  }
+  else if (isNonStringLiteral(typeProp.value)) {
+    context.report({
+      node: optionsArg,
+      messageId: 'optionsTypeNotString',
+      data: { level },
+    });
+  }
+};
+
+/**
+ * Validate that a logger argument is a string when it is a literal.
+ * Non-literal nodes (identifiers, call expressions) are skipped because their
+ * runtime type cannot be determined statically.
+ * @param {Object} context - The ESLint rule context.
+ * @param {Object} argNode - The argument AST node.
+ * @param {string} level - The logger level (e.g. 'info', 'error').
+ * @param {string} messageId - The ESLint message ID to report on failure.
+ */
+const validateStringArg = (context, argNode, level, messageId) => {
+  if (isNonStringLiteral(argNode)) {
+    context.report({
+      node: argNode,
+      messageId,
+      data: { level, actualType: typeof argNode.value },
+    });
+  }
+};
+
+/**
+ * ESLint plugin for validating logger call arguments.
+ * @type {Object}
+ */
+const plugin = {
+  rules: {
+    'validate-logger-args': {
+      meta: {
+        type: 'problem',
+        docs: {
+          category: 'Logging',
+          description: 'Validate logger call arguments match the required signature: (message, correlationId), (message, meta, correlationId), (message, correlationId, options), or (message, meta, correlationId, options).',
+        },
+        schema: [],
+        messages: {
+          tooFewArguments: 'logger.{{ level }}() requires at least 2 arguments: (message, correlationId). Found {{ count }}.',
+          tooManyArguments: 'logger.{{ level }}() accepts at most 4 arguments: (message, meta, correlationId, options). Found {{ count }}.',
+          messageNotString: 'logger.{{ level }}() message (1st argument) must be a string. Found {{ actualType }}.',
+          correlationIdNotString: 'logger.{{ level }}() correlationId must be a string. Found {{ actualType }}.',
+          optionsMissingType: 'logger.{{ level }}() options object must contain a "type" property.',
+          optionsTypeNotString: 'logger.{{ level }}() options "type" property must be a string.',
+        },
+      },
+      create(context) {
+        const defaultImports = new Set();
+
+        return {
+          ImportDefaultSpecifier(node) {
+            defaultImports.add(node.local.name);
+          },
+
+          CallExpression(node) {
+            if (node.callee.type !== 'MemberExpression') return;
+            if (node.callee.object.type !== 'Identifier') return;
+            if (!defaultImports.has(node.callee.object.name)) return;
+            if (node.callee.computed) return;
+
+            const level = node.callee.property.name;
+            if (!LEVELS.has(level)) return;
+
+            const args = node.arguments;
+
+            if (args.length < MIN_ARGS) {
+              context.report({
+                node,
+                messageId: 'tooFewArguments',
+                data: { level, count: String(args.length) },
+              });
+              return;
+            }
+
+            if (args.length > MAX_ARGS) {
+              context.report({
+                node,
+                messageId: 'tooManyArguments',
+                data: { level, count: String(args.length) },
+              });
+              return;
+            }
+
+            // Validate message (always 1st argument)
+            validateStringArg(context, args[0], level, 'messageNotString');
+
+            if (args.length === MIN_ARGS) {
+              // (message, correlationId)
+              validateStringArg(context, args[1], level, 'correlationIdNotString');
+            }
+            else if (args.length === THREE_ARGS) {
+              // Disambiguate: (message, meta, correlationId) vs (message, correlationId, options)
+              if (isObjectNode(args[1])) {
+                // (message, meta, correlationId)
+                validateStringArg(context, args[MIN_ARGS], level, 'correlationIdNotString');
+              }
+              else {
+                // (message, correlationId, options)
+                validateStringArg(context, args[1], level, 'correlationIdNotString');
+                validateOptions(context, args[MIN_ARGS], level);
+              }
+            }
+            else if (args.length === MAX_ARGS) {
+              // (message, meta, correlationId, options)
+              validateStringArg(context, args[MIN_ARGS], level, 'correlationIdNotString');
+              validateOptions(context, args[THREE_ARGS], level);
+            }
+          },
+        };
+      },
+    },
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mimik/eslint-plugin-logger",
+  "version": "1.0.0",
+  "description": "validation of the logger parameters for mimik",
+  "main": "./index.js",
+  "type": "module",
+  "scripts": {
+    "lint": "eslint . --no-error-on-unmatched-pattern",
+    "docs": "jsdoc2md --template docs/README.hbs index.js > README.md",
+    "test": "mocha --reporter mochawesome test/ --recursive",
+    "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",
+    "eslint",
+    "eslint-plugin",
+    "eslintplugin",
+    "logger"
+  ],
+  "author": "mimik technology inc <support@mimik.com> (https://developer.mimik.com/)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://bitbucket.org/mimiktech/eslint-plugin-logger.git"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.3",
+    "@stylistic/eslint-plugin": "5.10.0",
+    "c8": "11.0.0",
+    "eslint": "9.39.3",
+    "eslint-plugin-import": "2.32.0",
+    "globals": "17.4.0",
+    "husky": "9.1.7",
+    "jsdoc-to-markdown": "9.1.3",
+    "mocha": "11.7.5",
+    "mochawesome": "7.1.4"
+  }
+}