@noctcore/eslint-plugin-observability 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @noctcore/eslint-plugin-observability
+
+Structured-logging discipline rules — context objects over interpolated messages, no sensitive fields
+in logs, no error-detail loss. Flat-config only, ESLint 9+.
+
+## Install
+
+```sh
+bun add -D @noctcore/eslint-plugin-observability   # or npm i -D / pnpm add -D
+```
+
+## Use
+
+```js
+// eslint.config.js
+import observability from '@noctcore/eslint-plugin-observability';
+
+export default [
+  observability.configs.recommended,
+];
+```
+
+Or wire rules individually:
+
+```js
+import observability from '@noctcore/eslint-plugin-observability';
+
+export default [
+  {
+    plugins: { 'noctcore-observability': observability },
+    rules: {
+      'noctcore-observability/structured-log-arguments': ['error', { loggers: ['log', 'audit'] }],
+    },
+  },
+];
+```
+
+## Rules
+
+| Rule | Description | Recommended |
+| --- | --- | --- |
+| [`structured-log-arguments`](./docs/rules/structured-log-arguments.md) | Pass dynamic values in a structured context object, not interpolated into the message string. | `error` |
+| [`no-sensitive-fields-in-logs`](./docs/rules/no-sensitive-fields-in-logs.md) | Name-heuristic guard against writing credentials/secrets into log sinks. | `warn` |
+| [`no-error-detail-loss`](./docs/rules/no-error-detail-loss.md) | A catch block that reports failure must log the error itself, not only `e.message`. | `error` |

package/dist/index.cjs

@@ -0,0 +1,354 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  configs: () => configs,
+  default: () => index_default,
+  rules: () => rules
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/configs/recommended.ts
+var recommended = {
+  "noctcore-observability/structured-log-arguments": "error",
+  "noctcore-observability/no-sensitive-fields-in-logs": "warn",
+  "noctcore-observability/no-error-detail-loss": "error"
+};
+
+// src/rules/no-error-detail-loss.ts
+var import_utils2 = require("@typescript-eslint/utils");
+
+// src/createRule.ts
+var import_eslint_utils = require("@noctcore/eslint-utils");
+var createRule = (0, import_eslint_utils.makeCreateRule)("observability");
+
+// src/utils.ts
+var import_utils = require("@typescript-eslint/utils");
+var DEFAULT_LOGGERS = ["console", "logger", "log"];
+var LOG_METHODS = /* @__PURE__ */ new Set([
+  "info",
+  "warn",
+  "error",
+  "debug"
+]);
+function loggerObjectName(object) {
+  if (object.type === import_utils.AST_NODE_TYPES.Identifier) {
+    return object.name;
+  }
+  if (object.type === import_utils.AST_NODE_TYPES.MemberExpression && !object.computed && object.property.type === import_utils.AST_NODE_TYPES.Identifier) {
+    return object.property.name;
+  }
+  return void 0;
+}
+function loggerCallMethod(node, loggers) {
+  const callee = node.callee;
+  if (callee.type !== import_utils.AST_NODE_TYPES.MemberExpression || callee.computed || callee.property.type !== import_utils.AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+  const method = callee.property.name;
+  if (!LOG_METHODS.has(method)) {
+    return null;
+  }
+  const name = loggerObjectName(callee.object);
+  if (name === void 0 || !loggers.has(name)) {
+    return null;
+  }
+  return method;
+}
+
+// src/rules/no-error-detail-loss.ts
+var RULE_NAME = "no-error-detail-loss";
+function containsLoggerCall(block, loggers) {
+  let found = false;
+  function walk(node) {
+    if (found) {
+      return;
+    }
+    if (node.type === import_utils2.AST_NODE_TYPES.CallExpression && loggerCallMethod(node, loggers) !== null) {
+      found = true;
+      return;
+    }
+    for (const key of Object.keys(node)) {
+      if (key === "parent") {
+        continue;
+      }
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child && typeof child.type === "string") {
+            walk(child);
+          }
+        }
+      } else if (value && typeof value.type === "string") {
+        walk(value);
+      }
+    }
+  }
+  walk(block);
+  return found;
+}
+function isLossyReference(id) {
+  const parent = id.parent;
+  if (parent.type === import_utils2.AST_NODE_TYPES.MemberExpression && parent.object === id && !parent.computed && parent.property.type === import_utils2.AST_NODE_TYPES.Identifier && parent.property.name === "message") {
+    return true;
+  }
+  if (parent.type === import_utils2.AST_NODE_TYPES.CallExpression && parent.callee.type === import_utils2.AST_NODE_TYPES.Identifier && parent.callee.name === "String" && parent.arguments.includes(id)) {
+    return true;
+  }
+  if (parent.type === import_utils2.AST_NODE_TYPES.TemplateLiteral) {
+    return true;
+  }
+  return false;
+}
+var noErrorDetailLossRule = createRule({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "A catch block that reports a failure must not reduce the error to only `e.message` / `String(e)` / `${e}` \u2014 log the error itself so its stack and cause survive."
+    },
+    schema: [],
+    messages: {
+      detailLoss: "This catch logs only the error message \u2014 its stack and `cause` are lost. Log the error object itself (e.g. `log.error('...', { err: {{name}} })`) so the failure is diagnosable."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    const loggers = new Set(DEFAULT_LOGGERS);
+    return {
+      CatchClause(node) {
+        if (node.param === null || node.param.type !== import_utils2.AST_NODE_TYPES.Identifier) {
+          return;
+        }
+        if (!containsLoggerCall(node.body, loggers)) {
+          return;
+        }
+        const [variable] = context.sourceCode.getDeclaredVariables(node);
+        if (variable === void 0) {
+          return;
+        }
+        const reads = variable.references.filter((ref) => ref.isRead());
+        if (reads.length === 0) {
+          return;
+        }
+        const allLossy = reads.every(
+          (ref) => isLossyReference(ref.identifier)
+        );
+        if (!allLossy) {
+          return;
+        }
+        context.report({
+          node: node.param,
+          messageId: "detailLoss",
+          data: { name: node.param.name }
+        });
+      }
+    };
+  }
+});
+
+// src/rules/no-sensitive-fields-in-logs.ts
+var import_utils4 = require("@typescript-eslint/utils");
+var RULE_NAME2 = "no-sensitive-fields-in-logs";
+var DEFAULT_DENY_NAMES = [
+  "password",
+  "token",
+  "secret",
+  "authorization",
+  "cookie",
+  "apiKey",
+  "ssn"
+];
+var optionSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    denyNames: {
+      type: "array",
+      items: { type: "string" }
+    }
+  }
+};
+function nameSegments(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^a-zA-Z0-9]+/).join(" ").toLowerCase().split(/\s+/).filter(Boolean);
+}
+function compact(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function makeMatcher(denyNames) {
+  const single = [];
+  const multi = [];
+  for (const deny of denyNames) {
+    const segs = nameSegments(deny);
+    if (segs.length <= 1) {
+      single.push(compact(deny));
+    } else {
+      multi.push(compact(deny));
+    }
+  }
+  return (name) => {
+    const segs = new Set(nameSegments(name));
+    if (single.some((deny) => segs.has(deny))) {
+      return true;
+    }
+    const flat = compact(name);
+    return multi.some((deny) => flat.includes(deny));
+  };
+}
+var noSensitiveFieldsInLogsRule = createRule({
+  name: RULE_NAME2,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "A logger call must not reference an identifier, property, or object key whose name matches a sensitive-field denylist (password, token, secret, ...). Redact it before logging."
+    },
+    schema: [optionSchema],
+    messages: {
+      sensitiveField: "`{{name}}` looks like a sensitive field being written to a log sink. Redact it before logging (e.g. `redact({{name}})`) or omit it \u2014 logs are long-lived and widely readable."
+    }
+  },
+  defaultOptions: [{ denyNames: DEFAULT_DENY_NAMES }],
+  create(context, [options]) {
+    const matches = makeMatcher(options.denyNames ?? DEFAULT_DENY_NAMES);
+    function walk(node, visit) {
+      visit(node);
+      for (const key of Object.keys(node)) {
+        if (key === "parent") {
+          continue;
+        }
+        const value = node[key];
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            if (child && typeof child.type === "string") {
+              walk(child, visit);
+            }
+          }
+        } else if (value && typeof value.type === "string") {
+          walk(value, visit);
+        }
+      }
+    }
+    return {
+      CallExpression(node) {
+        if (loggerCallMethod(node, new Set(DEFAULT_LOGGERS)) === null) {
+          return;
+        }
+        const reported = /* @__PURE__ */ new Set();
+        const report = (name, target) => {
+          const at = target.range[0];
+          if (reported.has(at)) {
+            return;
+          }
+          reported.add(at);
+          context.report({
+            node: target,
+            messageId: "sensitiveField",
+            data: { name }
+          });
+        };
+        for (const arg of node.arguments) {
+          walk(arg, (n) => {
+            if (n.type === import_utils4.AST_NODE_TYPES.Identifier && matches(n.name)) {
+              report(n.name, n);
+            } else if (n.type === import_utils4.AST_NODE_TYPES.Property && n.key.type === import_utils4.AST_NODE_TYPES.Literal && typeof n.key.value === "string" && matches(n.key.value)) {
+              report(n.key.value, n.key);
+            }
+          });
+        }
+      }
+    };
+  }
+});
+
+// src/rules/structured-log-arguments.ts
+var import_utils6 = require("@typescript-eslint/utils");
+var RULE_NAME3 = "structured-log-arguments";
+var optionSchema2 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    loggers: {
+      type: "array",
+      items: { type: "string" }
+    }
+  }
+};
+var structuredLogArgumentsRule = createRule({
+  name: RULE_NAME3,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "A logger call must not interpolate dynamic values into the message string (a template literal with expressions). Pass a static message and a structured context object instead."
+    },
+    schema: [optionSchema2],
+    messages: {
+      interpolatedMessage: "This `.{{method}}(...)` call interpolates dynamic values into the message string \u2014 they become unqueryable free text. Pass a static message plus a structured context object (e.g. `log.{{method}}('processing task', { taskId })`) so each field stays indexable."
+    }
+  },
+  defaultOptions: [{ loggers: DEFAULT_LOGGERS }],
+  create(context, [options]) {
+    const loggers = new Set(options.loggers ?? DEFAULT_LOGGERS);
+    return {
+      CallExpression(node) {
+        const method = loggerCallMethod(node, loggers);
+        if (method === null) {
+          return;
+        }
+        for (const arg of node.arguments) {
+          if (arg.type === import_utils6.AST_NODE_TYPES.TemplateLiteral && arg.expressions.length > 0) {
+            context.report({
+              node: arg,
+              messageId: "interpolatedMessage",
+              data: { method }
+            });
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/rules/index.ts
+var rules = {
+  "structured-log-arguments": structuredLogArgumentsRule,
+  "no-sensitive-fields-in-logs": noSensitiveFieldsInLogsRule,
+  "no-error-detail-loss": noErrorDetailLossRule
+};
+
+// src/index.ts
+var NAMESPACE = "noctcore-observability";
+var VERSION = "0.1.0";
+var plugin = {
+  meta: { name: "@noctcore/eslint-plugin-observability", version: VERSION },
+  rules,
+  configs: {}
+};
+plugin.configs.recommended = {
+  plugins: { [NAMESPACE]: plugin },
+  rules: recommended
+};
+var configs = plugin.configs;
+var index_default = plugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  configs,
+  rules
+});

package/dist/index.d.cts

@@ -0,0 +1,45 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+
+interface NoSensitiveFieldsInLogsOptions {
+    readonly denyNames?: readonly string[];
+}
+
+interface StructuredLogArgumentsOptions {
+    readonly loggers?: readonly string[];
+}
+
+/** Every rule this plugin exposes, keyed by its (unprefixed) rule id. */
+declare const rules: {
+    'structured-log-arguments': _typescript_eslint_utils_ts_eslint.RuleModule<"interpolatedMessage", [StructuredLogArgumentsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'no-sensitive-fields-in-logs': _typescript_eslint_utils_ts_eslint.RuleModule<"sensitiveField", [NoSensitiveFieldsInLogsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+};
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'structured-log-arguments': _typescript_eslint_utils_ts_eslint.RuleModule<"interpolatedMessage", [StructuredLogArgumentsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'no-sensitive-fields-in-logs': _typescript_eslint_utils_ts_eslint.RuleModule<"sensitiveField", [NoSensitiveFieldsInLogsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+    };
+    configs: Record<string, unknown>;
+};
+
+declare const configs: Record<string, unknown>;
+
+export { configs, plugin as default, rules };

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+
+interface NoSensitiveFieldsInLogsOptions {
+    readonly denyNames?: readonly string[];
+}
+
+interface StructuredLogArgumentsOptions {
+    readonly loggers?: readonly string[];
+}
+
+/** Every rule this plugin exposes, keyed by its (unprefixed) rule id. */
+declare const rules: {
+    'structured-log-arguments': _typescript_eslint_utils_ts_eslint.RuleModule<"interpolatedMessage", [StructuredLogArgumentsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'no-sensitive-fields-in-logs': _typescript_eslint_utils_ts_eslint.RuleModule<"sensitiveField", [NoSensitiveFieldsInLogsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+};
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'structured-log-arguments': _typescript_eslint_utils_ts_eslint.RuleModule<"interpolatedMessage", [StructuredLogArgumentsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'no-sensitive-fields-in-logs': _typescript_eslint_utils_ts_eslint.RuleModule<"sensitiveField", [NoSensitiveFieldsInLogsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+    };
+    configs: Record<string, unknown>;
+};
+
+declare const configs: Record<string, unknown>;
+
+export { configs, plugin as default, rules };

package/dist/index.js

@@ -0,0 +1,326 @@
+// src/configs/recommended.ts
+var recommended = {
+  "noctcore-observability/structured-log-arguments": "error",
+  "noctcore-observability/no-sensitive-fields-in-logs": "warn",
+  "noctcore-observability/no-error-detail-loss": "error"
+};
+
+// src/rules/no-error-detail-loss.ts
+import { AST_NODE_TYPES as AST_NODE_TYPES2 } from "@typescript-eslint/utils";
+
+// src/createRule.ts
+import { makeCreateRule } from "@noctcore/eslint-utils";
+var createRule = makeCreateRule("observability");
+
+// src/utils.ts
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+var DEFAULT_LOGGERS = ["console", "logger", "log"];
+var LOG_METHODS = /* @__PURE__ */ new Set([
+  "info",
+  "warn",
+  "error",
+  "debug"
+]);
+function loggerObjectName(object) {
+  if (object.type === AST_NODE_TYPES.Identifier) {
+    return object.name;
+  }
+  if (object.type === AST_NODE_TYPES.MemberExpression && !object.computed && object.property.type === AST_NODE_TYPES.Identifier) {
+    return object.property.name;
+  }
+  return void 0;
+}
+function loggerCallMethod(node, loggers) {
+  const callee = node.callee;
+  if (callee.type !== AST_NODE_TYPES.MemberExpression || callee.computed || callee.property.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+  const method = callee.property.name;
+  if (!LOG_METHODS.has(method)) {
+    return null;
+  }
+  const name = loggerObjectName(callee.object);
+  if (name === void 0 || !loggers.has(name)) {
+    return null;
+  }
+  return method;
+}
+
+// src/rules/no-error-detail-loss.ts
+var RULE_NAME = "no-error-detail-loss";
+function containsLoggerCall(block, loggers) {
+  let found = false;
+  function walk(node) {
+    if (found) {
+      return;
+    }
+    if (node.type === AST_NODE_TYPES2.CallExpression && loggerCallMethod(node, loggers) !== null) {
+      found = true;
+      return;
+    }
+    for (const key of Object.keys(node)) {
+      if (key === "parent") {
+        continue;
+      }
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child && typeof child.type === "string") {
+            walk(child);
+          }
+        }
+      } else if (value && typeof value.type === "string") {
+        walk(value);
+      }
+    }
+  }
+  walk(block);
+  return found;
+}
+function isLossyReference(id) {
+  const parent = id.parent;
+  if (parent.type === AST_NODE_TYPES2.MemberExpression && parent.object === id && !parent.computed && parent.property.type === AST_NODE_TYPES2.Identifier && parent.property.name === "message") {
+    return true;
+  }
+  if (parent.type === AST_NODE_TYPES2.CallExpression && parent.callee.type === AST_NODE_TYPES2.Identifier && parent.callee.name === "String" && parent.arguments.includes(id)) {
+    return true;
+  }
+  if (parent.type === AST_NODE_TYPES2.TemplateLiteral) {
+    return true;
+  }
+  return false;
+}
+var noErrorDetailLossRule = createRule({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "A catch block that reports a failure must not reduce the error to only `e.message` / `String(e)` / `${e}` \u2014 log the error itself so its stack and cause survive."
+    },
+    schema: [],
+    messages: {
+      detailLoss: "This catch logs only the error message \u2014 its stack and `cause` are lost. Log the error object itself (e.g. `log.error('...', { err: {{name}} })`) so the failure is diagnosable."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    const loggers = new Set(DEFAULT_LOGGERS);
+    return {
+      CatchClause(node) {
+        if (node.param === null || node.param.type !== AST_NODE_TYPES2.Identifier) {
+          return;
+        }
+        if (!containsLoggerCall(node.body, loggers)) {
+          return;
+        }
+        const [variable] = context.sourceCode.getDeclaredVariables(node);
+        if (variable === void 0) {
+          return;
+        }
+        const reads = variable.references.filter((ref) => ref.isRead());
+        if (reads.length === 0) {
+          return;
+        }
+        const allLossy = reads.every(
+          (ref) => isLossyReference(ref.identifier)
+        );
+        if (!allLossy) {
+          return;
+        }
+        context.report({
+          node: node.param,
+          messageId: "detailLoss",
+          data: { name: node.param.name }
+        });
+      }
+    };
+  }
+});
+
+// src/rules/no-sensitive-fields-in-logs.ts
+import { AST_NODE_TYPES as AST_NODE_TYPES3 } from "@typescript-eslint/utils";
+var RULE_NAME2 = "no-sensitive-fields-in-logs";
+var DEFAULT_DENY_NAMES = [
+  "password",
+  "token",
+  "secret",
+  "authorization",
+  "cookie",
+  "apiKey",
+  "ssn"
+];
+var optionSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    denyNames: {
+      type: "array",
+      items: { type: "string" }
+    }
+  }
+};
+function nameSegments(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^a-zA-Z0-9]+/).join(" ").toLowerCase().split(/\s+/).filter(Boolean);
+}
+function compact(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function makeMatcher(denyNames) {
+  const single = [];
+  const multi = [];
+  for (const deny of denyNames) {
+    const segs = nameSegments(deny);
+    if (segs.length <= 1) {
+      single.push(compact(deny));
+    } else {
+      multi.push(compact(deny));
+    }
+  }
+  return (name) => {
+    const segs = new Set(nameSegments(name));
+    if (single.some((deny) => segs.has(deny))) {
+      return true;
+    }
+    const flat = compact(name);
+    return multi.some((deny) => flat.includes(deny));
+  };
+}
+var noSensitiveFieldsInLogsRule = createRule({
+  name: RULE_NAME2,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "A logger call must not reference an identifier, property, or object key whose name matches a sensitive-field denylist (password, token, secret, ...). Redact it before logging."
+    },
+    schema: [optionSchema],
+    messages: {
+      sensitiveField: "`{{name}}` looks like a sensitive field being written to a log sink. Redact it before logging (e.g. `redact({{name}})`) or omit it \u2014 logs are long-lived and widely readable."
+    }
+  },
+  defaultOptions: [{ denyNames: DEFAULT_DENY_NAMES }],
+  create(context, [options]) {
+    const matches = makeMatcher(options.denyNames ?? DEFAULT_DENY_NAMES);
+    function walk(node, visit) {
+      visit(node);
+      for (const key of Object.keys(node)) {
+        if (key === "parent") {
+          continue;
+        }
+        const value = node[key];
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            if (child && typeof child.type === "string") {
+              walk(child, visit);
+            }
+          }
+        } else if (value && typeof value.type === "string") {
+          walk(value, visit);
+        }
+      }
+    }
+    return {
+      CallExpression(node) {
+        if (loggerCallMethod(node, new Set(DEFAULT_LOGGERS)) === null) {
+          return;
+        }
+        const reported = /* @__PURE__ */ new Set();
+        const report = (name, target) => {
+          const at = target.range[0];
+          if (reported.has(at)) {
+            return;
+          }
+          reported.add(at);
+          context.report({
+            node: target,
+            messageId: "sensitiveField",
+            data: { name }
+          });
+        };
+        for (const arg of node.arguments) {
+          walk(arg, (n) => {
+            if (n.type === AST_NODE_TYPES3.Identifier && matches(n.name)) {
+              report(n.name, n);
+            } else if (n.type === AST_NODE_TYPES3.Property && n.key.type === AST_NODE_TYPES3.Literal && typeof n.key.value === "string" && matches(n.key.value)) {
+              report(n.key.value, n.key);
+            }
+          });
+        }
+      }
+    };
+  }
+});
+
+// src/rules/structured-log-arguments.ts
+import { AST_NODE_TYPES as AST_NODE_TYPES4 } from "@typescript-eslint/utils";
+var RULE_NAME3 = "structured-log-arguments";
+var optionSchema2 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    loggers: {
+      type: "array",
+      items: { type: "string" }
+    }
+  }
+};
+var structuredLogArgumentsRule = createRule({
+  name: RULE_NAME3,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "A logger call must not interpolate dynamic values into the message string (a template literal with expressions). Pass a static message and a structured context object instead."
+    },
+    schema: [optionSchema2],
+    messages: {
+      interpolatedMessage: "This `.{{method}}(...)` call interpolates dynamic values into the message string \u2014 they become unqueryable free text. Pass a static message plus a structured context object (e.g. `log.{{method}}('processing task', { taskId })`) so each field stays indexable."
+    }
+  },
+  defaultOptions: [{ loggers: DEFAULT_LOGGERS }],
+  create(context, [options]) {
+    const loggers = new Set(options.loggers ?? DEFAULT_LOGGERS);
+    return {
+      CallExpression(node) {
+        const method = loggerCallMethod(node, loggers);
+        if (method === null) {
+          return;
+        }
+        for (const arg of node.arguments) {
+          if (arg.type === AST_NODE_TYPES4.TemplateLiteral && arg.expressions.length > 0) {
+            context.report({
+              node: arg,
+              messageId: "interpolatedMessage",
+              data: { method }
+            });
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/rules/index.ts
+var rules = {
+  "structured-log-arguments": structuredLogArgumentsRule,
+  "no-sensitive-fields-in-logs": noSensitiveFieldsInLogsRule,
+  "no-error-detail-loss": noErrorDetailLossRule
+};
+
+// src/index.ts
+var NAMESPACE = "noctcore-observability";
+var VERSION = "0.1.0";
+var plugin = {
+  meta: { name: "@noctcore/eslint-plugin-observability", version: VERSION },
+  rules,
+  configs: {}
+};
+plugin.configs.recommended = {
+  plugins: { [NAMESPACE]: plugin },
+  rules: recommended
+};
+var configs = plugin.configs;
+var index_default = plugin;
+export {
+  configs,
+  index_default as default,
+  rules
+};

package/docs/rules/no-error-detail-loss.md

@@ -0,0 +1,54 @@
+# `noctcore-observability/no-error-detail-loss`
+
+> When a catch block reports a failure, log the error itself — not just its message.
+
+## Why
+
+A caught error carries a **stack trace** and often a **`cause`** — the parts you actually need to
+debug a production failure. A catch block that logs only `e.message`, `String(e)`, or `` `${e}` ``
+throws that away: the log records _that_ something failed but not _where_ or _why_.
+
+```ts
+// ✗ stack and cause are gone
+try { await run(); } catch (e) {
+  logger.error(`run failed: ${e.message}`);
+}
+
+// ✓ the whole error survives
+try { await run(); } catch (e) {
+  logger.error('run failed', { err: e });
+}
+```
+
+## What it flags
+
+A `catch (e)` block where **all** of the following hold:
+
+- the catch binding is a plain identifier (`catch (e)`);
+- the block contains a logger call (so a failure is actually being reported);
+- the binding **is** referenced (an unused binding is a different concern); and
+- **every** reference to the binding is a lossy form — `e.message`, `String(e)`, or bare `` `${e}` ``.
+
+If the error is passed whole anywhere (`logger.error('x', e)`, `{ err: e }`), or `.stack` / `.cause` /
+any other property is read, or it is re-thrown, its diagnostics survive and the rule stays silent:
+
+```ts
+// ✓ .stack is read — not a lossy form
+catch (e) { logger.error(`failed: ${e.stack}`); }
+
+// ✓ mixed use — the full capture wins
+catch (e) { logger.error(`${e.message}`, { err: e }); }
+```
+
+Distinct from a fully-**unused** catch binding (`catch (e) { cleanup(); }`), which this rule
+deliberately does not touch.
+
+## Options
+
+This rule has no options.
+
+## When not to use it
+
+If you deliberately log only messages (e.g. to a user-facing channel that must not include stack
+traces) **and** capture the full error elsewhere, this rule will be noisy — scope it off for those
+files.

package/docs/rules/no-sensitive-fields-in-logs.md

@@ -0,0 +1,58 @@
+# `noctcore-observability/no-sensitive-fields-in-logs`
+
+> A name-heuristic guard against writing credentials and secrets into log sinks. Ships at `warn`.
+
+## Why
+
+Logs are long-lived, widely readable, and shipped to third-party aggregators. A `password`, `token`,
+`secret`, or `authorization` header written into a log line is a credential leak that outlives the
+request by months. This rule catches the most common shape — a variable, property, or object key
+whose **name** matches a sensitive-field denylist appearing inside a logger call.
+
+It reads **names, never values**, so it is a heuristic and ships at `warn`, not `error` — treat a hit
+as "look here", not "definitely a bug".
+
+## What it flags
+
+Inside a logger call (`<logger>.<method>(...)`), any identifier, member-access property, or object key
+whose name matches the denylist:
+
+```ts
+// ✗ all three flag
+logger.info('login', { password });
+logger.error('auth failed', { userPassword: pw });
+logger.info('session', user.token);
+
+// ✓ redact first
+logger.info('login', { password: redact(password) });
+```
+
+Matching is **name-segment aware**. A single-word denyName (`token`) matches a camelCase or
+snake_case segment (`accessToken`, `access_token`) but **not** a longer word that merely contains it
+(`tokenize`, `tokenizer`). A multi-word denyName (`apiKey`) matches the compacted name
+(`myApiKey` → contains `apikey`).
+
+String **literals** are never inspected — only names — so a message that mentions a sensitive word is
+fine:
+
+```ts
+// ✓ a literal, not a value
+logger.info('password reset email sent');
+```
+
+## Options
+
+```ts
+type Options = {
+  /**
+   * Field names to treat as sensitive (case-insensitive, segment-aware).
+   * Default: ['password', 'token', 'secret', 'authorization', 'cookie', 'apiKey', 'ssn'].
+   */
+  denyNames?: string[];
+};
+```
+
+## When not to use it
+
+If your logging pipeline already redacts sensitive fields centrally (a serializer denylist), this
+rule is redundant. Otherwise keep it on at `warn` as a second line of defence.

package/docs/rules/structured-log-arguments.md

@@ -0,0 +1,64 @@
+# `noctcore-observability/structured-log-arguments`
+
+> Pass dynamic values in a structured context object, not interpolated into the log message string.
+
+## Why
+
+Dynamic values baked into a log **message** string are unqueryable. When you write
+
+```ts
+logger.info(`processing task ${taskId} for ${userId}`);
+```
+
+a log aggregator stores one opaque line of free text — it cannot index, filter, group, or alert on
+`taskId` or `userId`, because they are fused into the message. The value belongs in a structured
+context object, where each field stays a first-class, queryable attribute:
+
+```ts
+logger.info('processing task', { taskId, userId });
+```
+
+## What it flags
+
+A logger call — `<logger>.<method>(...)` where `<method>` is `info` / `warn` / `error` / `debug` and
+`<logger>` is a configured logger name — that receives a **template literal with expressions** as a
+**direct** positional argument.
+
+```ts
+// ✗ dynamic values interpolated into the message
+logger.error(`failed: ${err.code}`);
+
+// ✓ static message + structured context
+logger.error('request failed', { code: err.code });
+```
+
+Matched purely structurally (no type information). Both `logger.info(...)` and a logger held on a
+namespace or `this` (`this.logger.info(...)`, `app.log.warn(...)`) are recognised.
+
+Only **direct** arguments are inspected. A template literal nested inside a context object is building
+a value, not the message, and is never flagged:
+
+```ts
+// ✓ the template builds a URL field, not the message
+logger.info('fetching', { url: `${base}/tasks` });
+```
+
+A template with **no** expressions carries no dynamic value and is ignored
+(`logger.info(\`ready\`)`).
+
+> Note: `console.log(...)` uses the `log` method, which is not one of the tracked log levels
+> (`info` / `warn` / `error` / `debug`), so it is out of scope by design.
+
+## Options
+
+```ts
+type Options = {
+  /** Logger object names to scan. Default: ['console', 'logger', 'log']. */
+  loggers?: string[];
+};
+```
+
+## When not to use it
+
+If your logging layer only accepts a single formatted string (no structured-context argument), this
+rule cannot be satisfied — turn it off for that codebase.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@noctcore/eslint-plugin-observability",
+  "version": "0.1.0",
+  "description": "Structured-logging discipline ESLint rules — context objects over interpolated messages, no sensitive fields in logs, no error-detail loss.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "observability",
+    "logging",
+    "noctcore"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noctcore/eslint-plugins.git",
+    "directory": "packages/eslint-plugin-observability"
+  },
+  "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/eslint-plugin-observability",
+  "bugs": "https://github.com/noctcore/eslint-plugins/issues",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@noctcore/eslint-utils": "^0.1.0",
+    "@typescript-eslint/utils": "^8.61.1"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@noctcore/eslint-test-utils": "workspace:*",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/parser": "^8.61.1",
+    "@typescript-eslint/rule-tester": "^8.61.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0",
+    "vitest": "^3"
+  }
+}