@techsquidtv/eslint-plugin-structured-logging 0.1.0

package/LICENSE.md

@@ -0,0 +1,20 @@
+# MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+<h1 align="center">Structured Logging ESLint Plugin</h1>
+
+<p align="center">Library-agnostic ESLint rules for writing safer, more consistent structured logs in TypeScript.</p>
+
+## Installation
+
+Install the plugin alongside ESLint, TypeScript, and `@typescript-eslint/parser`:
+
+```shell
+pnpm add -D @techsquidtv/eslint-plugin-structured-logging eslint typescript @typescript-eslint/parser
+```
+
+```shell
+npm install --save-dev @techsquidtv/eslint-plugin-structured-logging eslint typescript @typescript-eslint/parser
+```
+
+```shell
+yarn add --dev @techsquidtv/eslint-plugin-structured-logging eslint typescript @typescript-eslint/parser
+```
+
+This package requires Node.js 20.19 or newer, ESLint 9 or newer, and TypeScript 5 or newer.
+
+## Usage
+
+The plugin exports flat ESLint configs. Add one to your `eslint.config.js` or `eslint.config.mjs`:
+
+```js
+import structuredLogging from "@techsquidtv/eslint-plugin-structured-logging";
+
+export default [structuredLogging.configs.recommended];
+```
+
+By default the rules match calls on a `logger` or `log` identifier (for example
+`logger.info(...)`). Point them at whatever logging API your codebase uses via
+the shared rule options — see [Rule Options](#rule-options).
+
+## Compatibility
+
+The rules are library-agnostic. Both common argument orders are supported:
+
+- **Message-first** — `logger.info("message", { attributes })` (e.g. winston, Sentry)
+- **Attributes-first** — `logger.info({ attributes }, "message")` (e.g. pino, bunyan) via the `attributesFirst*` options
+
+Level methods (`trace`, `debug`, `info`, `warn`, `error`, `fatal`) are matched by
+default and are configurable via `levelMethods` for libraries with additional
+levels (for example winston's `http`, `verbose`, and `silly`).
+
+## Configs
+
+The plugin exports two configs:
+
+- `recommended`: Enables the recommended structured-logging rules as warnings.
+- `strict`: Enables the recommended rules as errors and additionally requires logger attribute values to be statically known primitives where possible.
+
+Neither config requires type information.
+
+## Rules
+
+<!-- begin auto-generated rules list -->
+
+⚠️ Configurations set to warn in.\
+💼 Configurations enabled in.\
+✅ Set in the `recommended` configuration.\
+🔒 Set in the `strict` configuration.\
+🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).
+
+| Name                                                                                     | Description                                                                | ⚠️  | 💼  | 🔧  |
+| :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :-- | :-- | :-- |
+| [require-logger-inline-attributes](docs/rules/require-logger-inline-attributes.md)       | Require logger attributes to be inline object literals with explicit keys. | ✅  | 🔒  |     |
+| [require-logger-message](docs/rules/require-logger-message.md)                           | Require logger calls to include a static text message.                     | ✅  | 🔒  |     |
+| [require-logger-primitive-attributes](docs/rules/require-logger-primitive-attributes.md) | Require logger attribute values to be primitives or arrays of primitives.  | ✅  | 🔒  |     |
+| [require-logger-scoped-dot-notation](docs/rules/require-logger-scoped-dot-notation.md)   | Require logger messages and attribute keys to use dotted snake case.       | ✅  | 🔒  | 🔧  |
+
+<!-- end auto-generated rules list -->
+
+## Examples
+
+Prefer scoped event names with safe, searchable attributes:
+
+```ts
+logger.info("checkout.completed", {
+	"checkout.id": checkoutId,
+	"item.count": 3,
+	"guest.is": false,
+	"tag.names": ["priority", "guest"],
+});
+```
+
+Avoid dynamic messages, nested data, and non-primitive values:
+
+```ts
+logger.info(`Checkout completed for ${email}`, {
+	user: { email },
+	items: [{ id: 1 }],
+});
+```
+
+## Rule Options
+
+The logger rules share options for matching the logging APIs used in your codebase:
+
+```js
+{
+	"@techsquidtv/structured-logging/require-logger-message": [
+		"warn",
+		{
+			allowedLoggerObjects: [],
+			allowedLoggerIdentifiers: ["logger", "log"],
+			attributesFirstLoggerObjects: [],
+			attributesFirstLoggerIdentifiers: [],
+			levelMethods: ["trace", "debug", "info", "warn", "error", "fatal"],
+			ignoreDynamicLevelMethods: false,
+		},
+	],
+	"@techsquidtv/structured-logging/require-logger-primitive-attributes": [
+		"warn",
+		{
+			disallowUnknownAttributeValues: false,
+		},
+	],
+	"@techsquidtv/structured-logging/require-logger-scoped-dot-notation": [
+		"warn",
+		{
+			attributeKeyFormat: "dotted-snake-case",
+			messageFormat: "dotted-snake-case",
+		},
+	],
+}
+```
+
+- `allowedLoggerObjects`: Fully-qualified logger object paths that expose logger level methods, such as `log.child`. Defaults to `[]`.
+- `allowedLoggerIdentifiers`: Identifier names that expose logger level methods. Defaults to `["logger", "log"]`.
+- `attributesFirstLoggerObjects`: Object paths whose logger methods receive attributes before the message. Defaults to `[]`.
+- `attributesFirstLoggerIdentifiers`: Identifier names whose logger methods receive attributes before the message. Defaults to `[]`.
+- `levelMethods`: Method names treated as logger level calls. Defaults to `["trace", "debug", "info", "warn", "error", "fatal"]`.
+- `ignoreDynamicLevelMethods`: Skip computed logger level methods such as `logger[level](...)` instead of matching them. Defaults to `false`.
+- `disallowUnknownAttributeValues`: Available on `@techsquidtv/structured-logging/require-logger-primitive-attributes`. Set to `true` to require statically known primitive attribute values. Defaults to `false`.
+- `attributeKeyFormat`: Available on `@techsquidtv/structured-logging/require-logger-scoped-dot-notation`. Set to `"off"` to allow non-dotted attribute keys. Defaults to `"dotted-snake-case"`.
+- `messageFormat`: Available on `@techsquidtv/structured-logging/require-logger-scoped-dot-notation`. Set to `"off"` to allow prose logger messages. Defaults to `"dotted-snake-case"`.
+
+### Example: pino / bunyan (attributes-first)
+
+```js
+{
+	"@techsquidtv/structured-logging/require-logger-message": [
+		"warn",
+		{ attributesFirstLoggerIdentifiers: ["logger", "log"] },
+	],
+}
+```
+
+### Example: winston (extra levels)
+
+```js
+{
+	"@techsquidtv/structured-logging/require-logger-message": [
+		"warn",
+		{
+			levelMethods: ["error", "warn", "info", "http", "verbose", "debug", "silly"],
+		},
+	],
+}
+```
+
+## Development
+
+See [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md), then [`.github/DEVELOPMENT.md`](.github/DEVELOPMENT.md).

package/docs/rules/require-logger-inline-attributes.md

@@ -0,0 +1,22 @@
+# @techsquidtv/structured-logging/require-logger-inline-attributes
+
+📝 Require logger attributes to be inline object literals with explicit keys.
+
+💼⚠️ This rule is enabled in the 🔒 `strict` config. This rule _warns_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name                               | Description                                                                               | Type     | Default                                              |
+| :--------------------------------- | :---------------------------------------------------------------------------------------- | :------- | :--------------------------------------------------- |
+| `allowedLoggerIdentifiers`         | Bare logger object identifiers accepted as logger callees.                                | String[] | [`logger`, `log`]                                    |
+| `allowedLoggerObjects`             | Fully-qualified logger object paths, such as `log.child`.                                 | String[] | `[]`                                                 |
+| `attributesFirstLoggerIdentifiers` | Logger identifiers whose calls pass attributes before the message.                        | String[] | `[]`                                                 |
+| `attributesFirstLoggerObjects`     | Logger object paths whose calls pass attributes before the message.                       | String[] | `[]`                                                 |
+| `ignoreDynamicLevelMethods`        | Skip computed logger level methods such as `logger[level](...)` instead of matching them. | Boolean  | `false`                                              |
+| `levelMethods`                     | Method names treated as logger level calls, such as `info` or `error`.                    | String[] | [`trace`, `debug`, `info`, `warn`, `error`, `fatal`] |
+
+<!-- end auto-generated rule options list -->

package/docs/rules/require-logger-message.md

@@ -0,0 +1,22 @@
+# @techsquidtv/structured-logging/require-logger-message
+
+📝 Require logger calls to include a static text message.
+
+💼⚠️ This rule is enabled in the 🔒 `strict` config. This rule _warns_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name                               | Description                                                                               | Type     | Default                                              |
+| :--------------------------------- | :---------------------------------------------------------------------------------------- | :------- | :--------------------------------------------------- |
+| `allowedLoggerIdentifiers`         | Bare logger object identifiers accepted as logger callees.                                | String[] | [`logger`, `log`]                                    |
+| `allowedLoggerObjects`             | Fully-qualified logger object paths, such as `log.child`.                                 | String[] | `[]`                                                 |
+| `attributesFirstLoggerIdentifiers` | Logger identifiers whose calls pass attributes before the message.                        | String[] | `[]`                                                 |
+| `attributesFirstLoggerObjects`     | Logger object paths whose calls pass attributes before the message.                       | String[] | `[]`                                                 |
+| `ignoreDynamicLevelMethods`        | Skip computed logger level methods such as `logger[level](...)` instead of matching them. | Boolean  | `false`                                              |
+| `levelMethods`                     | Method names treated as logger level calls, such as `info` or `error`.                    | String[] | [`trace`, `debug`, `info`, `warn`, `error`, `fatal`] |
+
+<!-- end auto-generated rule options list -->

package/docs/rules/require-logger-primitive-attributes.md

@@ -0,0 +1,23 @@
+# @techsquidtv/structured-logging/require-logger-primitive-attributes
+
+📝 Require logger attribute values to be primitives or arrays of primitives.
+
+💼⚠️ This rule is enabled in the 🔒 `strict` config. This rule _warns_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name                               | Description                                                                                          | Type     | Default                                              |
+| :--------------------------------- | :--------------------------------------------------------------------------------------------------- | :------- | :--------------------------------------------------- |
+| `allowedLoggerIdentifiers`         | Bare logger object identifiers accepted as logger callees.                                           | String[] | [`logger`, `log`]                                    |
+| `allowedLoggerObjects`             | Fully-qualified logger object paths, such as `log.child`.                                            | String[] | `[]`                                                 |
+| `attributesFirstLoggerIdentifiers` | Logger identifiers whose calls pass attributes before the message.                                   | String[] | `[]`                                                 |
+| `attributesFirstLoggerObjects`     | Logger object paths whose calls pass attributes before the message.                                  | String[] | `[]`                                                 |
+| `disallowUnknownAttributeValues`   | Reject expressions whose static value shape is unknown instead of allowing them as attribute values. | Boolean  | `false`                                              |
+| `ignoreDynamicLevelMethods`        | Skip computed logger level methods such as `logger[level](...)` instead of matching them.            | Boolean  | `false`                                              |
+| `levelMethods`                     | Method names treated as logger level calls, such as `info` or `error`.                               | String[] | [`trace`, `debug`, `info`, `warn`, `error`, `fatal`] |
+
+<!-- end auto-generated rule options list -->

package/docs/rules/require-logger-scoped-dot-notation.md

@@ -0,0 +1,31 @@
+# @techsquidtv/structured-logging/require-logger-scoped-dot-notation
+
+📝 Require logger messages and attribute keys to use dotted snake case.
+
+💼⚠️ This rule is enabled in the 🔒 `strict` config. This rule _warns_ in the ✅ `recommended` config.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+## Dotted Snake Case
+
+Dotted snake case means at least two dot-separated segments, where each segment
+is lower `snake_case`, such as `payment.capture_failed` or `request.user_id`.
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name                               | Description                                                                               | Type     | Choices                    | Default                                              |
+| :--------------------------------- | :---------------------------------------------------------------------------------------- | :------- | :------------------------- | :--------------------------------------------------- |
+| `allowedLoggerIdentifiers`         | Bare logger object identifiers accepted as logger callees.                                | String[] |                            | [`logger`, `log`]                                    |
+| `allowedLoggerObjects`             | Fully-qualified logger object paths, such as `log.child`.                                 | String[] |                            | `[]`                                                 |
+| `attributeKeyFormat`               | Format required for inline attribute keys.                                                | String   | `dotted-snake-case`, `off` | `dotted-snake-case`                                  |
+| `attributesFirstLoggerIdentifiers` | Logger identifiers whose calls pass attributes before the message.                        | String[] |                            | `[]`                                                 |
+| `attributesFirstLoggerObjects`     | Logger object paths whose calls pass attributes before the message.                       | String[] |                            | `[]`                                                 |
+| `ignoreDynamicLevelMethods`        | Skip computed logger level methods such as `logger[level](...)` instead of matching them. | Boolean  |                            | `false`                                              |
+| `levelMethods`                     | Method names treated as logger level calls, such as `info` or `error`.                    | String[] |                            | [`trace`, `debug`, `info`, `warn`, `error`, `fatal`] |
+| `messageFormat`                    | Format required for logger messages.                                                      | String   | `dotted-snake-case`, `off` | `dotted-snake-case`                                  |
+
+<!-- end auto-generated rule options list -->

package/lib/index.d.ts

@@ -0,0 +1,31 @@
+import { LoggerMatcherOptions } from "./rules/logger/utils.js";
+import { StructuredLoggingPluginDocs } from "./utils.js";
+import { RequireLoggerPrimitiveAttributesOptions } from "./rules/logger/require-logger-primitive-attributes.js";
+import { RequireLoggerScopedDotNotationOptions } from "./rules/logger/require-logger-scoped-dot-notation.js";
+import { TSESLint } from "@typescript-eslint/utils";
+
+//#region src/index.d.ts
+declare const plugin: {
+  meta: {
+    name: string;
+    version: string;
+  };
+  rules: {
+    "require-logger-inline-attributes": TSESLint.RuleModule<"nonInlineAttributes" | "noAttributeSpread" | "staticAttributeKeys", [LoggerMatcherOptions], StructuredLoggingPluginDocs, TSESLint.RuleListener> & {
+      name: string;
+    };
+    "require-logger-message": TSESLint.RuleModule<"messageRequired" | "messageMustBeText", [LoggerMatcherOptions], StructuredLoggingPluginDocs, TSESLint.RuleListener> & {
+      name: string;
+    };
+    "require-logger-primitive-attributes": TSESLint.RuleModule<"primitiveAttributeValue", [RequireLoggerPrimitiveAttributesOptions], StructuredLoggingPluginDocs, TSESLint.RuleListener> & {
+      name: string;
+    };
+    "require-logger-scoped-dot-notation": TSESLint.RuleModule<"dottedSnakeCaseAttributeKey" | "dottedSnakeCaseMessage", [RequireLoggerScopedDotNotationOptions], StructuredLoggingPluginDocs, TSESLint.RuleListener> & {
+      name: string;
+    };
+  };
+  configs: Record<string, TSESLint.FlatConfig.Config>;
+};
+//#endregion
+export { plugin as default };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;cAmDM,MAAA;;;;;;kIAOL,oBAAA;;;;;;;;;;;;;WADe,MAAA,SAAe,QAAA,CAAS,UAAA,CAAW,MAAA;AAAA"}

package/lib/index.js

@@ -0,0 +1,55 @@
+import { version } from "./package.js";
+import { requireLoggerInlineAttributes } from "./rules/logger/require-logger-inline-attributes.js";
+import { requireLoggerMessage } from "./rules/logger/require-logger-message.js";
+import { requireLoggerPrimitiveAttributes } from "./rules/logger/require-logger-primitive-attributes.js";
+import { requireLoggerScopedDotNotation } from "./rules/logger/require-logger-scoped-dot-notation.js";
+import "./rules/index.js";
+//#region src/index.ts
+const rules = {
+	"require-logger-inline-attributes": requireLoggerInlineAttributes,
+	"require-logger-message": requireLoggerMessage,
+	"require-logger-primitive-attributes": requireLoggerPrimitiveAttributes,
+	"require-logger-scoped-dot-notation": requireLoggerScopedDotNotation
+};
+const pluginName = "@techsquidtv/structured-logging";
+const strictAttributeRuleName = "require-logger-primitive-attributes";
+function createRecommendedRules({ severity, strictAttributes }) {
+	const configRules = {};
+	for (const [ruleName, rule] of Object.entries(rules)) {
+		const docs = rule.meta.docs;
+		if (!docs || !("recommended" in docs) || !docs.recommended) continue;
+		const ruleId = `${pluginName}/${ruleName}`;
+		configRules[ruleId] = strictAttributes && ruleName === strictAttributeRuleName ? [severity, { disallowUnknownAttributeValues: true }] : severity;
+	}
+	return configRules;
+}
+const plugin = {
+	meta: {
+		name: "@techsquidtv/eslint-plugin-structured-logging",
+		version
+	},
+	rules,
+	configs: {}
+};
+Object.assign(plugin.configs, {
+	recommended: {
+		name: `${pluginName}/recommended`,
+		plugins: { [pluginName]: plugin },
+		rules: createRecommendedRules({
+			severity: "warn",
+			strictAttributes: false
+		})
+	},
+	strict: {
+		name: `${pluginName}/strict`,
+		plugins: { [pluginName]: plugin },
+		rules: createRecommendedRules({
+			severity: "error",
+			strictAttributes: true
+		})
+	}
+});
+//#endregion
+export { plugin as default };
+
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["packageJson.version"],"sources":["../src/index.ts"],"sourcesContent":["import type { TSESLint } from \"@typescript-eslint/utils\";\n\nimport packageJson from \"../package.json\" with { type: \"json\" };\n\nimport {\n\trequireLoggerInlineAttributes,\n\trequireLoggerMessage,\n\trequireLoggerPrimitiveAttributes,\n\trequireLoggerScopedDotNotation,\n} from \"@/rules/index\";\n\nconst rules = {\n\t\"require-logger-inline-attributes\": requireLoggerInlineAttributes,\n\t\"require-logger-message\": requireLoggerMessage,\n\t\"require-logger-primitive-attributes\": requireLoggerPrimitiveAttributes,\n\t\"require-logger-scoped-dot-notation\": requireLoggerScopedDotNotation,\n};\n\ntype Severity = \"warn\" | \"error\";\ntype Rules = NonNullable<TSESLint.FlatConfig.Config[\"rules\"]>;\n\nconst pluginName = \"@techsquidtv/structured-logging\";\nconst strictAttributeRuleName = \"require-logger-primitive-attributes\";\n\nfunction createRecommendedRules({\n\tseverity,\n\tstrictAttributes,\n}: {\n\tseverity: Severity;\n\tstrictAttributes: boolean;\n}): Rules {\n\tconst configRules: Rules = {};\n\n\tfor (const [ruleName, rule] of Object.entries(rules)) {\n\t\tconst docs = rule.meta.docs;\n\n\t\tif (!docs || !(\"recommended\" in docs) || !docs.recommended) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst ruleId = `${pluginName}/${ruleName}`;\n\n\t\tconfigRules[ruleId] =\n\t\t\tstrictAttributes && ruleName === strictAttributeRuleName\n\t\t\t\t? [severity, { disallowUnknownAttributeValues: true }]\n\t\t\t\t: severity;\n\t}\n\n\treturn configRules;\n}\n\nconst plugin = {\n\tmeta: {\n\t\tname: \"@techsquidtv/eslint-plugin-structured-logging\",\n\t\tversion: packageJson.version,\n\t},\n\trules,\n\tconfigs: {} as Record<string, TSESLint.FlatConfig.Config>,\n};\n\nObject.assign(plugin.configs, {\n\trecommended: {\n\t\tname: `${pluginName}/recommended`,\n\t\tplugins: { [pluginName]: plugin },\n\t\trules: createRecommendedRules({\n\t\t\tseverity: \"warn\",\n\t\t\tstrictAttributes: false,\n\t\t}),\n\t} satisfies TSESLint.FlatConfig.Config,\n\tstrict: {\n\t\tname: `${pluginName}/strict`,\n\t\tplugins: { [pluginName]: plugin },\n\t\trules: createRecommendedRules({\n\t\t\tseverity: \"error\",\n\t\t\tstrictAttributes: true,\n\t\t}),\n\t} satisfies TSESLint.FlatConfig.Config,\n});\n\nexport default plugin;\n"],"mappings":";;;;;;;AAWA,MAAM,QAAQ;CACb,oCAAoC;CACpC,0BAA0B;CAC1B,uCAAuC;CACvC,sCAAsC;AACvC;AAKA,MAAM,aAAa;AACnB,MAAM,0BAA0B;AAEhC,SAAS,uBAAuB,EAC/B,UACA,oBAIS;CACT,MAAM,cAAqB,CAAC;CAE5B,KAAK,MAAM,CAAC,UAAU,SAAS,OAAO,QAAQ,KAAK,GAAG;EACrD,MAAM,OAAO,KAAK,KAAK;EAEvB,IAAI,CAAC,QAAQ,EAAE,iBAAiB,SAAS,CAAC,KAAK,aAC9C;EAGD,MAAM,SAAS,GAAG,WAAW,GAAG;EAEhC,YAAY,UACX,oBAAoB,aAAa,0BAC9B,CAAC,UAAU,EAAE,gCAAgC,KAAK,CAAC,IACnD;CACL;CAEA,OAAO;AACR;AAEA,MAAM,SAAS;CACd,MAAM;EACL,MAAM;EACGA;CACV;CACA;CACA,SAAS,CAAC;AACX;AAEA,OAAO,OAAO,OAAO,SAAS;CAC7B,aAAa;EACZ,MAAM,GAAG,WAAW;EACpB,SAAS,GAAG,aAAa,OAAO;EAChC,OAAO,uBAAuB;GAC7B,UAAU;GACV,kBAAkB;EACnB,CAAC;CACF;CACA,QAAQ;EACP,MAAM,GAAG,WAAW;EACpB,SAAS,GAAG,aAAa,OAAO;EAChC,OAAO,uBAAuB;GAC7B,UAAU;GACV,kBAAkB;EACnB,CAAC;CACF;AACD,CAAC"}

package/lib/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.1.0";
+//#endregion
+export { version };
+
+//# sourceMappingURL=package.js.map

package/lib/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":[""],"mappings":""}

package/lib/rules/index.d.ts

@@ -0,0 +1,5 @@
+import { requireLoggerPrimitiveAttributes } from "./logger/require-logger-primitive-attributes.js";
+import { requireLoggerScopedDotNotation } from "./logger/require-logger-scoped-dot-notation.js";
+import { requireLoggerInlineAttributes } from "./logger/require-logger-inline-attributes.js";
+import { requireLoggerMessage } from "./logger/require-logger-message.js";
+export { requireLoggerInlineAttributes, requireLoggerMessage, requireLoggerPrimitiveAttributes, requireLoggerScopedDotNotation };

package/lib/rules/index.js

@@ -0,0 +1,5 @@
+import { requireLoggerInlineAttributes } from "./logger/require-logger-inline-attributes.js";
+import { requireLoggerMessage } from "./logger/require-logger-message.js";
+import { requireLoggerPrimitiveAttributes } from "./logger/require-logger-primitive-attributes.js";
+import { requireLoggerScopedDotNotation } from "./logger/require-logger-scoped-dot-notation.js";
+export { requireLoggerInlineAttributes, requireLoggerMessage, requireLoggerPrimitiveAttributes, requireLoggerScopedDotNotation };

package/lib/rules/logger/require-logger-inline-attributes.d.ts

@@ -0,0 +1,13 @@
+import { LoggerMatcherOptions } from "./utils.js";
+import { StructuredLoggingPluginDocs } from "../../utils.js";
+
+//#region src/rules/logger/require-logger-inline-attributes.d.ts
+type MessageIds = "nonInlineAttributes" | "noAttributeSpread" | "staticAttributeKeys";
+type RuleOptions = [LoggerMatcherOptions];
+/** Enforces statically inspectable inline attribute objects for logger calls. */
+declare const requireLoggerInlineAttributes: import("@typescript-eslint/utils/ts-eslint").RuleModule<MessageIds, RuleOptions, StructuredLoggingPluginDocs, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+  name: string;
+};
+//#endregion
+export { requireLoggerInlineAttributes };
+//# sourceMappingURL=require-logger-inline-attributes.d.ts.map

package/lib/rules/logger/require-logger-inline-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-logger-inline-attributes.d.ts","names":[],"sources":["../../../src/rules/logger/require-logger-inline-attributes.ts"],"mappings":";;;;KAUK,UAAA;AAAA,KAIA,WAAA,IAAe,oBAAoB;;cAG3B,6BAAA,+CAA6B,UAAA,CAAA,UAAA,EAAA,WAAA,EAAA,2BAAA,+CAAA,YAAA"}

package/lib/rules/logger/require-logger-inline-attributes.js

@@ -0,0 +1,46 @@
+import { createRule } from "../../utils.js";
+import { DEFAULT_LOGGER_MATCHER_OPTIONS, LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES, buildLoggerMatcherSets, collectAttrsEntries, getLoggerArguments } from "./utils.js";
+//#region src/rules/logger/require-logger-inline-attributes.ts
+/** Enforces statically inspectable inline attribute objects for logger calls. */
+const requireLoggerInlineAttributes = createRule({
+	name: "require-logger-inline-attributes",
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require logger attributes to be inline object literals with explicit keys.",
+			recommended: true
+		},
+		messages: {
+			nonInlineAttributes: "Log attributes must be an inline object literal. Inline the attributes object so lint rules can validate its keys and values.",
+			noAttributeSpread: "Do not spread into log attributes. List each safe scalar attribute explicitly.",
+			staticAttributeKeys: "Attribute keys must be static identifiers or string literals. Replace the computed key with an explicit key."
+		},
+		schema: [{
+			type: "object",
+			properties: { ...LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES },
+			additionalProperties: false
+		}],
+		defaultOptions: [DEFAULT_LOGGER_MATCHER_OPTIONS]
+	},
+	create(context) {
+		const sets = buildLoggerMatcherSets(context.options[0]);
+		return { CallExpression(node) {
+			const args = getLoggerArguments(node, sets);
+			if (!args) return;
+			collectAttrsEntries(args.attrsArg, {
+				reportMalformedProperties: true,
+				reportNonLiteral: true,
+				report: (reportNode, messageId) => {
+					context.report({
+						node: reportNode,
+						messageId
+					});
+				}
+			});
+		} };
+	}
+});
+//#endregion
+export { requireLoggerInlineAttributes };
+
+//# sourceMappingURL=require-logger-inline-attributes.js.map

package/lib/rules/logger/require-logger-inline-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-logger-inline-attributes.js","names":[],"sources":["../../../src/rules/logger/require-logger-inline-attributes.ts"],"sourcesContent":["import { createRule } from \"@/utils\";\nimport {\n\tLOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES,\n\tDEFAULT_LOGGER_MATCHER_OPTIONS,\n\tbuildLoggerMatcherSets,\n\tcollectAttrsEntries,\n\tgetLoggerArguments,\n\ttype LoggerMatcherOptions,\n} from \"@/rules/logger/utils\";\n\ntype MessageIds =\n\t| \"nonInlineAttributes\"\n\t| \"noAttributeSpread\"\n\t| \"staticAttributeKeys\";\ntype RuleOptions = [LoggerMatcherOptions];\n\n/** Enforces statically inspectable inline attribute objects for logger calls. */\nexport const requireLoggerInlineAttributes = createRule<\n\tRuleOptions,\n\tMessageIds\n>({\n\tname: \"require-logger-inline-attributes\",\n\tmeta: {\n\t\ttype: \"problem\",\n\t\tdocs: {\n\t\t\tdescription:\n\t\t\t\t\"Require logger attributes to be inline object literals with explicit keys.\",\n\t\t\trecommended: true,\n\t\t},\n\t\tmessages: {\n\t\t\tnonInlineAttributes:\n\t\t\t\t\"Log attributes must be an inline object literal. Inline the attributes object so lint rules can validate its keys and values.\",\n\t\t\tnoAttributeSpread:\n\t\t\t\t\"Do not spread into log attributes. List each safe scalar attribute explicitly.\",\n\t\t\tstaticAttributeKeys:\n\t\t\t\t\"Attribute keys must be static identifiers or string literals. Replace the computed key with an explicit key.\",\n\t\t},\n\t\tschema: [\n\t\t\t{\n\t\t\t\ttype: \"object\",\n\t\t\t\tproperties: { ...LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES },\n\t\t\t\tadditionalProperties: false,\n\t\t\t},\n\t\t],\n\t\tdefaultOptions: [DEFAULT_LOGGER_MATCHER_OPTIONS],\n\t},\n\tcreate(context) {\n\t\tconst sets = buildLoggerMatcherSets(context.options[0]);\n\n\t\treturn {\n\t\t\tCallExpression(node) {\n\t\t\t\tconst args = getLoggerArguments(node, sets);\n\t\t\t\tif (!args) return;\n\n\t\t\t\tcollectAttrsEntries(args.attrsArg, {\n\t\t\t\t\treportMalformedProperties: true,\n\t\t\t\t\treportNonLiteral: true,\n\t\t\t\t\treport: (reportNode, messageId) => {\n\t\t\t\t\t\tcontext.report({\n\t\t\t\t\t\t\tnode: reportNode,\n\t\t\t\t\t\t\tmessageId: messageId as MessageIds,\n\t\t\t\t\t\t});\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t},\n\t\t};\n\t},\n});\n"],"mappings":";;;;AAiBA,MAAa,gCAAgC,WAG3C;CACD,MAAM;CACN,MAAM;EACL,MAAM;EACN,MAAM;GACL,aACC;GACD,aAAa;EACd;EACA,UAAU;GACT,qBACC;GACD,mBACC;GACD,qBACC;EACF;EACA,QAAQ,CACP;GACC,MAAM;GACN,YAAY,EAAE,GAAG,wCAAwC;GACzD,sBAAsB;EACvB,CACD;EACA,gBAAgB,CAAC,8BAA8B;CAChD;CACA,OAAO,SAAS;EACf,MAAM,OAAO,uBAAuB,QAAQ,QAAQ,EAAE;EAEtD,OAAO,EACN,eAAe,MAAM;GACpB,MAAM,OAAO,mBAAmB,MAAM,IAAI;GAC1C,IAAI,CAAC,MAAM;GAEX,oBAAoB,KAAK,UAAU;IAClC,2BAA2B;IAC3B,kBAAkB;IAClB,SAAS,YAAY,cAAc;KAClC,QAAQ,OAAO;MACd,MAAM;MACK;KACZ,CAAC;IACF;GACD,CAAC;EACF,EACD;CACD;AACD,CAAC"}

package/lib/rules/logger/require-logger-message.d.ts

@@ -0,0 +1,13 @@
+import { LoggerMatcherOptions } from "./utils.js";
+import { StructuredLoggingPluginDocs } from "../../utils.js";
+
+//#region src/rules/logger/require-logger-message.d.ts
+type MessageIds = "messageRequired" | "messageMustBeText";
+type RuleOptions = [LoggerMatcherOptions];
+/** Enforces static message arguments for logger calls. */
+declare const requireLoggerMessage: import("@typescript-eslint/utils/ts-eslint").RuleModule<MessageIds, RuleOptions, StructuredLoggingPluginDocs, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+  name: string;
+};
+//#endregion
+export { requireLoggerMessage };
+//# sourceMappingURL=require-logger-message.d.ts.map

package/lib/rules/logger/require-logger-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-logger-message.d.ts","names":[],"sources":["../../../src/rules/logger/require-logger-message.ts"],"mappings":";;;;KAUK,UAAA;AAAA,KACA,WAAA,IAAe,oBAAoB;;cAG3B,oBAAA,+CAAoB,UAAA,CAAA,UAAA,EAAA,WAAA,EAAA,2BAAA,+CAAA,YAAA"}

package/lib/rules/logger/require-logger-message.js

@@ -0,0 +1,46 @@
+import { createRule } from "../../utils.js";
+import { DEFAULT_LOGGER_MATCHER_OPTIONS, LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES, buildLoggerMatcherSets, getLoggerArguments, isClearlyNotMessage } from "./utils.js";
+//#region src/rules/logger/require-logger-message.ts
+/** Enforces static message arguments for logger calls. */
+const requireLoggerMessage = createRule({
+	name: "require-logger-message",
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require logger calls to include a static text message.",
+			recommended: true
+		},
+		messages: {
+			messageRequired: "Logger call must include a static message. Add a descriptive string literal as the message.",
+			messageMustBeText: "Logger call message must be static text. Use a string literal message, and put variable data in the attributes object."
+		},
+		schema: [{
+			type: "object",
+			properties: { ...LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES },
+			additionalProperties: false
+		}],
+		defaultOptions: [DEFAULT_LOGGER_MATCHER_OPTIONS]
+	},
+	create(context) {
+		const sets = buildLoggerMatcherSets(context.options[0]);
+		return { CallExpression(node) {
+			const args = getLoggerArguments(node, sets);
+			if (!args) return;
+			if (!args.messageArg) {
+				context.report({
+					node,
+					messageId: "messageRequired"
+				});
+				return;
+			}
+			if (isClearlyNotMessage(args.messageArg)) context.report({
+				node: args.messageArg,
+				messageId: "messageMustBeText"
+			});
+		} };
+	}
+});
+//#endregion
+export { requireLoggerMessage };
+
+//# sourceMappingURL=require-logger-message.js.map

package/lib/rules/logger/require-logger-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-logger-message.js","names":[],"sources":["../../../src/rules/logger/require-logger-message.ts"],"sourcesContent":["import { createRule } from \"@/utils\";\nimport {\n\tLOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES,\n\tDEFAULT_LOGGER_MATCHER_OPTIONS,\n\tbuildLoggerMatcherSets,\n\tgetLoggerArguments,\n\tisClearlyNotMessage,\n\ttype LoggerMatcherOptions,\n} from \"@/rules/logger/utils\";\n\ntype MessageIds = \"messageRequired\" | \"messageMustBeText\";\ntype RuleOptions = [LoggerMatcherOptions];\n\n/** Enforces static message arguments for logger calls. */\nexport const requireLoggerMessage = createRule<RuleOptions, MessageIds>({\n\tname: \"require-logger-message\",\n\tmeta: {\n\t\ttype: \"problem\",\n\t\tdocs: {\n\t\t\tdescription: \"Require logger calls to include a static text message.\",\n\t\t\trecommended: true,\n\t\t},\n\t\tmessages: {\n\t\t\tmessageRequired:\n\t\t\t\t\"Logger call must include a static message. Add a descriptive string literal as the message.\",\n\t\t\tmessageMustBeText:\n\t\t\t\t\"Logger call message must be static text. Use a string literal message, and put variable data in the attributes object.\",\n\t\t},\n\t\tschema: [\n\t\t\t{\n\t\t\t\ttype: \"object\",\n\t\t\t\tproperties: { ...LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES },\n\t\t\t\tadditionalProperties: false,\n\t\t\t},\n\t\t],\n\t\tdefaultOptions: [DEFAULT_LOGGER_MATCHER_OPTIONS],\n\t},\n\tcreate(context) {\n\t\tconst sets = buildLoggerMatcherSets(context.options[0]);\n\n\t\treturn {\n\t\t\tCallExpression(node) {\n\t\t\t\tconst args = getLoggerArguments(node, sets);\n\t\t\t\tif (!args) return;\n\n\t\t\t\tif (!args.messageArg) {\n\t\t\t\t\tcontext.report({ node, messageId: \"messageRequired\" });\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tif (isClearlyNotMessage(args.messageArg)) {\n\t\t\t\t\tcontext.report({\n\t\t\t\t\t\tnode: args.messageArg,\n\t\t\t\t\t\tmessageId: \"messageMustBeText\",\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t},\n\t\t};\n\t},\n});\n"],"mappings":";;;;AAcA,MAAa,uBAAuB,WAAoC;CACvE,MAAM;CACN,MAAM;EACL,MAAM;EACN,MAAM;GACL,aAAa;GACb,aAAa;EACd;EACA,UAAU;GACT,iBACC;GACD,mBACC;EACF;EACA,QAAQ,CACP;GACC,MAAM;GACN,YAAY,EAAE,GAAG,wCAAwC;GACzD,sBAAsB;EACvB,CACD;EACA,gBAAgB,CAAC,8BAA8B;CAChD;CACA,OAAO,SAAS;EACf,MAAM,OAAO,uBAAuB,QAAQ,QAAQ,EAAE;EAEtD,OAAO,EACN,eAAe,MAAM;GACpB,MAAM,OAAO,mBAAmB,MAAM,IAAI;GAC1C,IAAI,CAAC,MAAM;GAEX,IAAI,CAAC,KAAK,YAAY;IACrB,QAAQ,OAAO;KAAE;KAAM,WAAW;IAAkB,CAAC;IACrD;GACD;GAEA,IAAI,oBAAoB,KAAK,UAAU,GACtC,QAAQ,OAAO;IACd,MAAM,KAAK;IACX,WAAW;GACZ,CAAC;EAEH,EACD;CACD;AACD,CAAC"}

package/lib/rules/logger/require-logger-primitive-attributes.d.ts

@@ -0,0 +1,20 @@
+import { LoggerMatcherOptions } from "./utils.js";
+import { StructuredLoggingPluginDocs } from "../../utils.js";
+
+//#region src/rules/logger/require-logger-primitive-attributes.d.ts
+/** Options for primitive logger attribute enforcement. */
+interface RequireLoggerPrimitiveAttributesOptions extends LoggerMatcherOptions {
+  /**
+   * Reject expressions whose static value shape is unknown instead of
+   * allowing them as attribute values.
+   */
+  disallowUnknownAttributeValues?: boolean;
+}
+type RuleOptions = [RequireLoggerPrimitiveAttributesOptions];
+/** Enforces primitive values (or arrays of primitives) for logger attributes. */
+declare const requireLoggerPrimitiveAttributes: import("@typescript-eslint/utils/ts-eslint").RuleModule<"primitiveAttributeValue", RuleOptions, StructuredLoggingPluginDocs, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+  name: string;
+};
+//#endregion
+export { RequireLoggerPrimitiveAttributesOptions, requireLoggerPrimitiveAttributes };
+//# sourceMappingURL=require-logger-primitive-attributes.d.ts.map

package/lib/rules/logger/require-logger-primitive-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-logger-primitive-attributes.d.ts","names":[],"sources":["../../../src/rules/logger/require-logger-primitive-attributes.ts"],"mappings":";;;;;UAciB,uCAAA,SAAgD,oBAAoB;;AAArF;;;EAKC,8BAA8B;AAAA;AAAA,KAG1B,WAAA,IAAe,uCAAuC;;cAG9C,gCAAA,+CAAgC,UAAA,4BAAA,WAAA,EAAA,2BAAA,+CAAA,YAAA"}

package/lib/rules/logger/require-logger-primitive-attributes.js

@@ -0,0 +1,48 @@
+import { createRule } from "../../utils.js";
+import { DEFAULT_LOGGER_MATCHER_OPTIONS, LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES, buildLoggerMatcherSets, collectAttrsEntries, getLoggerArguments, isDisallowedAttributeValue } from "./utils.js";
+//#region src/rules/logger/require-logger-primitive-attributes.ts
+/** Enforces primitive values (or arrays of primitives) for logger attributes. */
+const requireLoggerPrimitiveAttributes = createRule({
+	name: "require-logger-primitive-attributes",
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require logger attribute values to be primitives or arrays of primitives.",
+			recommended: true
+		},
+		messages: { primitiveAttributeValue: "Attribute \"{{key}}\" must be a primitive or an array of primitives. Use a string, number, or boolean (or an array of those), or flatten nested data into separate attributes." },
+		schema: [{
+			type: "object",
+			properties: {
+				...LOGGER_MATCHER_OPTION_SCHEMA_PROPERTIES,
+				disallowUnknownAttributeValues: {
+					description: "Reject expressions whose static value shape is unknown instead of allowing them as attribute values.",
+					type: "boolean"
+				}
+			},
+			additionalProperties: false
+		}],
+		defaultOptions: [{
+			...DEFAULT_LOGGER_MATCHER_OPTIONS,
+			disallowUnknownAttributeValues: false
+		}]
+	},
+	create(context) {
+		const sets = buildLoggerMatcherSets(context.options[0]);
+		return { CallExpression(node) {
+			const args = getLoggerArguments(node, sets);
+			if (!args) return;
+			const entries = collectAttrsEntries(args.attrsArg);
+			if (!entries) return;
+			for (const entry of entries) if (isDisallowedAttributeValue(entry.valueNode, context.options[0])) context.report({
+				node: entry.valueNode,
+				messageId: "primitiveAttributeValue",
+				data: { key: entry.key }
+			});
+		} };
+	}
+});
+//#endregion
+export { requireLoggerPrimitiveAttributes };
+
+//# sourceMappingURL=require-logger-primitive-attributes.js.map