@noctcore/eslint-plugin-observability 0.1.0 → 0.3.0

package/README.md

@@ -40,5 +40,6 @@ export default [
 | 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-sensitive-fields-in-logs`](./docs/rules/no-sensitive-fields-in-logs.md) | Name-heuristic guard against writing credentials/secrets into log sinks. | `error` |
 | [`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` |
+| [`audit-pii-declared`](./docs/rules/audit-pii-declared.md) | A PII-shaped key written into an audit payload must be declared: registered for scrubbing on purge, or declared non-PII. Enforces declaration, not deletion. Inert until `auditCallees` is set. | `error` |

package/dist/index.cjs

@@ -29,11 +29,13 @@ 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"
+  "noctcore-observability/no-sensitive-fields-in-logs": "error",
+  "noctcore-observability/no-error-detail-loss": "error",
+  // Inert until you set `auditCallees`, so it ships enabled but checks nothing by default.
+  "noctcore-observability/audit-pii-declared": "error"
 };
 
-// src/rules/no-error-detail-loss.ts
+// src/rules/audit-pii-declared.ts
 var import_utils2 = require("@typescript-eslint/utils");
 
 // src/createRule.ts
@@ -43,12 +45,7 @@ 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"
-]);
+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;
@@ -73,16 +70,310 @@ function loggerCallMethod(node, loggers) {
   }
   return method;
 }
+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 compactName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function makeNameMatcher(patterns) {
+  const single = [];
+  const multi = [];
+  for (const pattern of patterns) {
+    const segs = nameSegments(pattern);
+    if (segs.length <= 1) {
+      single.push(compactName(pattern));
+    } else {
+      multi.push(compactName(pattern));
+    }
+  }
+  return (name) => {
+    const segs = new Set(nameSegments(name));
+    if (single.some((p) => segs.has(p))) {
+      return true;
+    }
+    const flat = compactName(name);
+    return multi.some((p) => flat.includes(p));
+  };
+}
+
+// src/rules/audit-pii-declared.ts
+var RULE_NAME = "audit-pii-declared";
+var DEFAULT_PAYLOAD_KEYS = ["metadata", "before", "after"];
+var DEFAULT_PII_FIELDS = [
+  "email",
+  "phone",
+  "mobile",
+  "address",
+  "firstName",
+  "lastName",
+  "fullName",
+  "displayName",
+  "surname",
+  "birthDate",
+  "dateOfBirth"
+];
+var DEFAULT_NON_PII_PREFIXES = ["is", "has", "was", "should", "can"];
+var DEFAULT_NON_PII_SUFFIXES = [
+  "sent",
+  "verified",
+  "confirmed",
+  "enabled",
+  "disabled",
+  "changed",
+  "required",
+  "count",
+  "type",
+  "kind",
+  "status",
+  "id",
+  "ids"
+];
+var stringList = { type: "array", items: { type: "string" }, uniqueItems: true };
+var optionSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    auditCallees: { ...stringList, default: [] },
+    payloadKeys: { ...stringList, default: [...DEFAULT_PAYLOAD_KEYS] },
+    piiFields: { ...stringList, default: [...DEFAULT_PII_FIELDS] },
+    registeredFields: { ...stringList, default: [] },
+    nonPiiFields: { ...stringList, default: [] },
+    nonPiiPrefixes: { ...stringList, default: [...DEFAULT_NON_PII_PREFIXES] },
+    nonPiiSuffixes: { ...stringList, default: [...DEFAULT_NON_PII_SUFFIXES] },
+    reportOpaque: { type: "boolean", default: true }
+  }
+};
+function calleeText(node) {
+  if (node.type === import_utils2.AST_NODE_TYPES.Identifier) {
+    return node.name;
+  }
+  if (node.type === import_utils2.AST_NODE_TYPES.ThisExpression) {
+    return "this";
+  }
+  if (node.type === import_utils2.AST_NODE_TYPES.MemberExpression && !node.computed && node.property.type === import_utils2.AST_NODE_TYPES.Identifier) {
+    const object = calleeText(node.object);
+    return object === null ? null : `${object}.${node.property.name}`;
+  }
+  return null;
+}
+function staticKeyName(property) {
+  if (property.computed) {
+    return null;
+  }
+  const key = property.key;
+  if (key.type === import_utils2.AST_NODE_TYPES.Identifier) {
+    return key.name;
+  }
+  if (key.type === import_utils2.AST_NODE_TYPES.Literal && typeof key.value === "string") {
+    return key.value;
+  }
+  return null;
+}
+function valueName(node) {
+  if (node.type === import_utils2.AST_NODE_TYPES.Identifier) {
+    return node.name;
+  }
+  if (node.type === import_utils2.AST_NODE_TYPES.MemberExpression && !node.computed && node.property.type === import_utils2.AST_NODE_TYPES.Identifier) {
+    return node.property.name;
+  }
+  if (node.type === import_utils2.AST_NODE_TYPES.ChainExpression) {
+    return valueName(node.expression);
+  }
+  if (node.type === import_utils2.AST_NODE_TYPES.TSNonNullExpression || node.type === import_utils2.AST_NODE_TYPES.TSAsExpression) {
+    return valueName(node.expression);
+  }
+  return null;
+}
+function isEmptyValue(node) {
+  return node.type === import_utils2.AST_NODE_TYPES.Literal && node.value === null || node.type === import_utils2.AST_NODE_TYPES.Identifier && node.name === "undefined";
+}
+function isScalarFlag(node) {
+  return node.type === import_utils2.AST_NODE_TYPES.Literal && (typeof node.value === "boolean" || typeof node.value === "number" || node.value === null);
+}
+function spreadSources(node) {
+  if (node.type === import_utils2.AST_NODE_TYPES.ObjectExpression) {
+    return [node];
+  }
+  if (isEmptyValue(node)) {
+    return [];
+  }
+  if (node.type === import_utils2.AST_NODE_TYPES.ConditionalExpression) {
+    const consequent = spreadSources(node.consequent);
+    const alternate = spreadSources(node.alternate);
+    return consequent === null || alternate === null ? null : [...consequent, ...alternate];
+  }
+  if (node.type === import_utils2.AST_NODE_TYPES.LogicalExpression && node.operator === "&&") {
+    return spreadSources(node.right);
+  }
+  return null;
+}
+var auditPiiDeclaredRule = createRule({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "A PII-shaped key written into an audit payload must be declared, either registered for scrubbing on purge or declared non-PII."
+    },
+    schema: [optionSchema],
+    messages: {
+      undeclaredPiiKey: "`{{key}}` looks like personal data in audit `{{payload}}`. Add it to `registeredFields` (the keys your purger scrubs) or, if it is not personal data, to `nonPiiFields`.",
+      undeclaredPiiValue: "`{{key}}` in audit `{{payload}}` holds `{{value}}`, which looks like personal data. Add `{{key}}` to `registeredFields` (the keys your purger scrubs) or, if it is not personal data, to `nonPiiFields`.",
+      opaquePayload: "Audit `{{payload}}` cannot be read statically ({{why}}), so its keys cannot be checked against the PII registry. Write it as an object literal."
+    }
+  },
+  defaultOptions: [
+    {
+      auditCallees: [],
+      payloadKeys: DEFAULT_PAYLOAD_KEYS,
+      piiFields: DEFAULT_PII_FIELDS,
+      registeredFields: [],
+      nonPiiFields: [],
+      nonPiiPrefixes: DEFAULT_NON_PII_PREFIXES,
+      nonPiiSuffixes: DEFAULT_NON_PII_SUFFIXES,
+      reportOpaque: true
+    }
+  ],
+  create(context, [options]) {
+    const auditCallees = options.auditCallees ?? [];
+    if (auditCallees.length === 0) {
+      return {};
+    }
+    const payloadKeys = new Set(options.payloadKeys ?? DEFAULT_PAYLOAD_KEYS);
+    const looksLikePii = makeNameMatcher(options.piiFields ?? DEFAULT_PII_FIELDS);
+    const declared = /* @__PURE__ */ new Set([
+      ...options.registeredFields ?? [],
+      ...options.nonPiiFields ?? []
+    ]);
+    const reportOpaque = options.reportOpaque ?? true;
+    const nonPiiPrefixes = new Set(options.nonPiiPrefixes ?? DEFAULT_NON_PII_PREFIXES);
+    const nonPiiSuffixes = new Set(options.nonPiiSuffixes ?? DEFAULT_NON_PII_SUFFIXES);
+    const exactPii = new Set(
+      (options.piiFields ?? DEFAULT_PII_FIELDS).map((field) => compactName(field))
+    );
+    const isPiiName = (name) => {
+      if (!looksLikePii(name)) {
+        return false;
+      }
+      if (exactPii.has(compactName(name))) {
+        return true;
+      }
+      const segments = nameSegments(name);
+      const first = segments[0];
+      const last = segments[segments.length - 1];
+      const isAbout = segments.length > 1 && (first !== void 0 && nonPiiPrefixes.has(first) || last !== void 0 && nonPiiSuffixes.has(last));
+      return !isAbout;
+    };
+    const isAuditCall = (callee) => {
+      const text = calleeText(callee);
+      return text !== null && auditCallees.some((entry) => text === entry || text.endsWith(`.${entry}`));
+    };
+    const opaque = (node, payload, why) => {
+      if (reportOpaque) {
+        context.report({ node, messageId: "opaquePayload", data: { payload, why } });
+      }
+    };
+    const checkObject = (object, payload) => {
+      for (const property of object.properties) {
+        if (property.type === import_utils2.AST_NODE_TYPES.SpreadElement) {
+          const sources = spreadSources(property.argument);
+          if (sources === null) {
+            opaque(property, payload, "it spreads a value that is not an object literal");
+          } else {
+            sources.forEach((source) => checkObject(source, payload));
+          }
+          continue;
+        }
+        const key = staticKeyName(property);
+        if (key === null) {
+          opaque(property.key, payload, "it has a computed key");
+          continue;
+        }
+        const value = property.value;
+        if (!declared.has(key) && !isScalarFlag(value)) {
+          if (isPiiName(key)) {
+            context.report({
+              node: property.key,
+              messageId: "undeclaredPiiKey",
+              data: { key, payload }
+            });
+          } else {
+            const name = valueName(value);
+            if (name !== null && isPiiName(name)) {
+              context.report({
+                node: property.key,
+                messageId: "undeclaredPiiValue",
+                data: { key, payload, value: context.sourceCode.getText(value) }
+              });
+            }
+          }
+        }
+        checkNested(value, payload);
+      }
+    };
+    const checkNested = (node, payload) => {
+      if (node.type === import_utils2.AST_NODE_TYPES.ObjectExpression) {
+        checkObject(node, payload);
+      } else if (node.type === import_utils2.AST_NODE_TYPES.ArrayExpression) {
+        for (const element of node.elements) {
+          if (element !== null && element.type !== import_utils2.AST_NODE_TYPES.SpreadElement) {
+            checkNested(element, payload);
+          }
+        }
+      }
+    };
+    const checkParams = (params) => {
+      for (const property of params.properties) {
+        if (property.type === import_utils2.AST_NODE_TYPES.SpreadElement) {
+          const sources = spreadSources(property.argument);
+          if (sources === null) {
+            opaque(property, "params", "it spreads a value that is not an object literal");
+          } else {
+            sources.forEach(checkParams);
+          }
+          continue;
+        }
+        const key = staticKeyName(property);
+        if (key === null || !payloadKeys.has(key)) {
+          continue;
+        }
+        const value = property.value;
+        if (value.type === import_utils2.AST_NODE_TYPES.ObjectExpression) {
+          checkObject(value, key);
+        } else if (!isEmptyValue(value)) {
+          opaque(value, key, "it is not an object literal");
+        }
+      }
+    };
+    return {
+      CallExpression(node) {
+        if (!isAuditCall(node.callee)) {
+          return;
+        }
+        const [params] = node.arguments;
+        if (params === void 0) {
+          return;
+        }
+        if (params.type !== import_utils2.AST_NODE_TYPES.ObjectExpression) {
+          opaque(params, "params", "the audit call is not given an object literal");
+          return;
+        }
+        checkParams(params);
+      }
+    };
+  }
+});
 
 // src/rules/no-error-detail-loss.ts
-var RULE_NAME = "no-error-detail-loss";
+var import_utils4 = require("@typescript-eslint/utils");
+var RULE_NAME2 = "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) {
+    if (node.type === import_utils4.AST_NODE_TYPES.CallExpression && loggerCallMethod(node, loggers) !== null) {
       found = true;
       return;
     }
@@ -107,19 +398,19 @@ function containsLoggerCall(block, loggers) {
 }
 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") {
+  if (parent.type === import_utils4.AST_NODE_TYPES.MemberExpression && parent.object === id && !parent.computed && parent.property.type === import_utils4.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)) {
+  if (parent.type === import_utils4.AST_NODE_TYPES.CallExpression && parent.callee.type === import_utils4.AST_NODE_TYPES.Identifier && parent.callee.name === "String" && parent.arguments.includes(id)) {
     return true;
   }
-  if (parent.type === import_utils2.AST_NODE_TYPES.TemplateLiteral) {
+  if (parent.type === import_utils4.AST_NODE_TYPES.TemplateLiteral) {
     return true;
   }
   return false;
 }
 var noErrorDetailLossRule = createRule({
-  name: RULE_NAME,
+  name: RULE_NAME2,
   meta: {
     type: "suggestion",
     docs: {
@@ -135,7 +426,7 @@ var noErrorDetailLossRule = createRule({
     const loggers = new Set(DEFAULT_LOGGERS);
     return {
       CatchClause(node) {
-        if (node.param === null || node.param.type !== import_utils2.AST_NODE_TYPES.Identifier) {
+        if (node.param === null || node.param.type !== import_utils4.AST_NODE_TYPES.Identifier) {
           return;
         }
         if (!containsLoggerCall(node.body, loggers)) {
@@ -166,8 +457,8 @@ var noErrorDetailLossRule = createRule({
 });
 
 // src/rules/no-sensitive-fields-in-logs.ts
-var import_utils4 = require("@typescript-eslint/utils");
-var RULE_NAME2 = "no-sensitive-fields-in-logs";
+var import_utils6 = require("@typescript-eslint/utils");
+var RULE_NAME3 = "no-sensitive-fields-in-logs";
 var DEFAULT_DENY_NAMES = [
   "password",
   "token",
@@ -177,7 +468,7 @@ var DEFAULT_DENY_NAMES = [
   "apiKey",
   "ssn"
 ];
-var optionSchema = {
+var optionSchema2 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -187,47 +478,21 @@ var optionSchema = {
     }
   }
 };
-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,
+  name: RULE_NAME3,
   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],
+    schema: [optionSchema2],
     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);
+    const matches = makeNameMatcher(options.denyNames ?? DEFAULT_DENY_NAMES);
     function walk(node, visit) {
       visit(node);
       for (const key of Object.keys(node)) {
@@ -266,9 +531,9 @@ var noSensitiveFieldsInLogsRule = createRule({
         };
         for (const arg of node.arguments) {
           walk(arg, (n) => {
-            if (n.type === import_utils4.AST_NODE_TYPES.Identifier && matches(n.name)) {
+            if (n.type === import_utils6.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)) {
+            } else if (n.type === import_utils6.AST_NODE_TYPES.Property && n.key.type === import_utils6.AST_NODE_TYPES.Literal && typeof n.key.value === "string" && matches(n.key.value)) {
               report(n.key.value, n.key);
             }
           });
@@ -279,9 +544,9 @@ var noSensitiveFieldsInLogsRule = createRule({
 });
 
 // src/rules/structured-log-arguments.ts
-var import_utils6 = require("@typescript-eslint/utils");
-var RULE_NAME3 = "structured-log-arguments";
-var optionSchema2 = {
+var import_utils8 = require("@typescript-eslint/utils");
+var RULE_NAME4 = "structured-log-arguments";
+var optionSchema3 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -292,13 +557,13 @@ var optionSchema2 = {
   }
 };
 var structuredLogArgumentsRule = createRule({
-  name: RULE_NAME3,
+  name: RULE_NAME4,
   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],
+    schema: [optionSchema3],
     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."
     }
@@ -313,7 +578,7 @@ var structuredLogArgumentsRule = createRule({
           return;
         }
         for (const arg of node.arguments) {
-          if (arg.type === import_utils6.AST_NODE_TYPES.TemplateLiteral && arg.expressions.length > 0) {
+          if (arg.type === import_utils8.AST_NODE_TYPES.TemplateLiteral && arg.expressions.length > 0) {
             context.report({
               node: arg,
               messageId: "interpolatedMessage",
@@ -330,12 +595,13 @@ var structuredLogArgumentsRule = createRule({
 var rules = {
   "structured-log-arguments": structuredLogArgumentsRule,
   "no-sensitive-fields-in-logs": noSensitiveFieldsInLogsRule,
-  "no-error-detail-loss": noErrorDetailLossRule
+  "no-error-detail-loss": noErrorDetailLossRule,
+  "audit-pii-declared": auditPiiDeclaredRule
 };
 
 // src/index.ts
 var NAMESPACE = "noctcore-observability";
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-observability", version: VERSION },
   rules,

package/dist/index.d.cts

@@ -1,5 +1,16 @@
 import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
 
+interface AuditPiiDeclaredOptions {
+    readonly auditCallees?: readonly string[];
+    readonly payloadKeys?: readonly string[];
+    readonly piiFields?: readonly string[];
+    readonly registeredFields?: readonly string[];
+    readonly nonPiiFields?: readonly string[];
+    readonly nonPiiPrefixes?: readonly string[];
+    readonly nonPiiSuffixes?: readonly string[];
+    readonly reportOpaque?: boolean;
+}
+
 interface NoSensitiveFieldsInLogsOptions {
     readonly denyNames?: readonly string[];
 }
@@ -19,6 +30,9 @@ declare const rules: {
     'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    'audit-pii-declared': _typescript_eslint_utils_ts_eslint.RuleModule<"undeclaredPiiKey" | "undeclaredPiiValue" | "opaquePayload", [AuditPiiDeclaredOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 
 declare const plugin: {
@@ -36,6 +50,9 @@ declare const plugin: {
         'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        'audit-pii-declared': _typescript_eslint_utils_ts_eslint.RuleModule<"undeclaredPiiKey" | "undeclaredPiiValue" | "opaquePayload", [AuditPiiDeclaredOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: Record<string, unknown>;
 };

package/dist/index.d.ts

@@ -1,5 +1,16 @@
 import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
 
+interface AuditPiiDeclaredOptions {
+    readonly auditCallees?: readonly string[];
+    readonly payloadKeys?: readonly string[];
+    readonly piiFields?: readonly string[];
+    readonly registeredFields?: readonly string[];
+    readonly nonPiiFields?: readonly string[];
+    readonly nonPiiPrefixes?: readonly string[];
+    readonly nonPiiSuffixes?: readonly string[];
+    readonly reportOpaque?: boolean;
+}
+
 interface NoSensitiveFieldsInLogsOptions {
     readonly denyNames?: readonly string[];
 }
@@ -19,6 +30,9 @@ declare const rules: {
     'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    'audit-pii-declared': _typescript_eslint_utils_ts_eslint.RuleModule<"undeclaredPiiKey" | "undeclaredPiiValue" | "opaquePayload", [AuditPiiDeclaredOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 
 declare const plugin: {
@@ -36,6 +50,9 @@ declare const plugin: {
         'no-error-detail-loss': _typescript_eslint_utils_ts_eslint.RuleModule<"detailLoss", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        'audit-pii-declared': _typescript_eslint_utils_ts_eslint.RuleModule<"undeclaredPiiKey" | "undeclaredPiiValue" | "opaquePayload", [AuditPiiDeclaredOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: Record<string, unknown>;
 };

package/dist/index.js

@@ -1,11 +1,13 @@
 // 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"
+  "noctcore-observability/no-sensitive-fields-in-logs": "error",
+  "noctcore-observability/no-error-detail-loss": "error",
+  // Inert until you set `auditCallees`, so it ships enabled but checks nothing by default.
+  "noctcore-observability/audit-pii-declared": "error"
 };
 
-// src/rules/no-error-detail-loss.ts
+// src/rules/audit-pii-declared.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES2 } from "@typescript-eslint/utils";
 
 // src/createRule.ts
@@ -15,12 +17,7 @@ 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"
-]);
+var LOG_METHODS = /* @__PURE__ */ new Set(["info", "warn", "error", "debug"]);
 function loggerObjectName(object) {
   if (object.type === AST_NODE_TYPES.Identifier) {
     return object.name;
@@ -45,16 +42,310 @@ function loggerCallMethod(node, loggers) {
   }
   return method;
 }
+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 compactName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function makeNameMatcher(patterns) {
+  const single = [];
+  const multi = [];
+  for (const pattern of patterns) {
+    const segs = nameSegments(pattern);
+    if (segs.length <= 1) {
+      single.push(compactName(pattern));
+    } else {
+      multi.push(compactName(pattern));
+    }
+  }
+  return (name) => {
+    const segs = new Set(nameSegments(name));
+    if (single.some((p) => segs.has(p))) {
+      return true;
+    }
+    const flat = compactName(name);
+    return multi.some((p) => flat.includes(p));
+  };
+}
+
+// src/rules/audit-pii-declared.ts
+var RULE_NAME = "audit-pii-declared";
+var DEFAULT_PAYLOAD_KEYS = ["metadata", "before", "after"];
+var DEFAULT_PII_FIELDS = [
+  "email",
+  "phone",
+  "mobile",
+  "address",
+  "firstName",
+  "lastName",
+  "fullName",
+  "displayName",
+  "surname",
+  "birthDate",
+  "dateOfBirth"
+];
+var DEFAULT_NON_PII_PREFIXES = ["is", "has", "was", "should", "can"];
+var DEFAULT_NON_PII_SUFFIXES = [
+  "sent",
+  "verified",
+  "confirmed",
+  "enabled",
+  "disabled",
+  "changed",
+  "required",
+  "count",
+  "type",
+  "kind",
+  "status",
+  "id",
+  "ids"
+];
+var stringList = { type: "array", items: { type: "string" }, uniqueItems: true };
+var optionSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    auditCallees: { ...stringList, default: [] },
+    payloadKeys: { ...stringList, default: [...DEFAULT_PAYLOAD_KEYS] },
+    piiFields: { ...stringList, default: [...DEFAULT_PII_FIELDS] },
+    registeredFields: { ...stringList, default: [] },
+    nonPiiFields: { ...stringList, default: [] },
+    nonPiiPrefixes: { ...stringList, default: [...DEFAULT_NON_PII_PREFIXES] },
+    nonPiiSuffixes: { ...stringList, default: [...DEFAULT_NON_PII_SUFFIXES] },
+    reportOpaque: { type: "boolean", default: true }
+  }
+};
+function calleeText(node) {
+  if (node.type === AST_NODE_TYPES2.Identifier) {
+    return node.name;
+  }
+  if (node.type === AST_NODE_TYPES2.ThisExpression) {
+    return "this";
+  }
+  if (node.type === AST_NODE_TYPES2.MemberExpression && !node.computed && node.property.type === AST_NODE_TYPES2.Identifier) {
+    const object = calleeText(node.object);
+    return object === null ? null : `${object}.${node.property.name}`;
+  }
+  return null;
+}
+function staticKeyName(property) {
+  if (property.computed) {
+    return null;
+  }
+  const key = property.key;
+  if (key.type === AST_NODE_TYPES2.Identifier) {
+    return key.name;
+  }
+  if (key.type === AST_NODE_TYPES2.Literal && typeof key.value === "string") {
+    return key.value;
+  }
+  return null;
+}
+function valueName(node) {
+  if (node.type === AST_NODE_TYPES2.Identifier) {
+    return node.name;
+  }
+  if (node.type === AST_NODE_TYPES2.MemberExpression && !node.computed && node.property.type === AST_NODE_TYPES2.Identifier) {
+    return node.property.name;
+  }
+  if (node.type === AST_NODE_TYPES2.ChainExpression) {
+    return valueName(node.expression);
+  }
+  if (node.type === AST_NODE_TYPES2.TSNonNullExpression || node.type === AST_NODE_TYPES2.TSAsExpression) {
+    return valueName(node.expression);
+  }
+  return null;
+}
+function isEmptyValue(node) {
+  return node.type === AST_NODE_TYPES2.Literal && node.value === null || node.type === AST_NODE_TYPES2.Identifier && node.name === "undefined";
+}
+function isScalarFlag(node) {
+  return node.type === AST_NODE_TYPES2.Literal && (typeof node.value === "boolean" || typeof node.value === "number" || node.value === null);
+}
+function spreadSources(node) {
+  if (node.type === AST_NODE_TYPES2.ObjectExpression) {
+    return [node];
+  }
+  if (isEmptyValue(node)) {
+    return [];
+  }
+  if (node.type === AST_NODE_TYPES2.ConditionalExpression) {
+    const consequent = spreadSources(node.consequent);
+    const alternate = spreadSources(node.alternate);
+    return consequent === null || alternate === null ? null : [...consequent, ...alternate];
+  }
+  if (node.type === AST_NODE_TYPES2.LogicalExpression && node.operator === "&&") {
+    return spreadSources(node.right);
+  }
+  return null;
+}
+var auditPiiDeclaredRule = createRule({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "A PII-shaped key written into an audit payload must be declared, either registered for scrubbing on purge or declared non-PII."
+    },
+    schema: [optionSchema],
+    messages: {
+      undeclaredPiiKey: "`{{key}}` looks like personal data in audit `{{payload}}`. Add it to `registeredFields` (the keys your purger scrubs) or, if it is not personal data, to `nonPiiFields`.",
+      undeclaredPiiValue: "`{{key}}` in audit `{{payload}}` holds `{{value}}`, which looks like personal data. Add `{{key}}` to `registeredFields` (the keys your purger scrubs) or, if it is not personal data, to `nonPiiFields`.",
+      opaquePayload: "Audit `{{payload}}` cannot be read statically ({{why}}), so its keys cannot be checked against the PII registry. Write it as an object literal."
+    }
+  },
+  defaultOptions: [
+    {
+      auditCallees: [],
+      payloadKeys: DEFAULT_PAYLOAD_KEYS,
+      piiFields: DEFAULT_PII_FIELDS,
+      registeredFields: [],
+      nonPiiFields: [],
+      nonPiiPrefixes: DEFAULT_NON_PII_PREFIXES,
+      nonPiiSuffixes: DEFAULT_NON_PII_SUFFIXES,
+      reportOpaque: true
+    }
+  ],
+  create(context, [options]) {
+    const auditCallees = options.auditCallees ?? [];
+    if (auditCallees.length === 0) {
+      return {};
+    }
+    const payloadKeys = new Set(options.payloadKeys ?? DEFAULT_PAYLOAD_KEYS);
+    const looksLikePii = makeNameMatcher(options.piiFields ?? DEFAULT_PII_FIELDS);
+    const declared = /* @__PURE__ */ new Set([
+      ...options.registeredFields ?? [],
+      ...options.nonPiiFields ?? []
+    ]);
+    const reportOpaque = options.reportOpaque ?? true;
+    const nonPiiPrefixes = new Set(options.nonPiiPrefixes ?? DEFAULT_NON_PII_PREFIXES);
+    const nonPiiSuffixes = new Set(options.nonPiiSuffixes ?? DEFAULT_NON_PII_SUFFIXES);
+    const exactPii = new Set(
+      (options.piiFields ?? DEFAULT_PII_FIELDS).map((field) => compactName(field))
+    );
+    const isPiiName = (name) => {
+      if (!looksLikePii(name)) {
+        return false;
+      }
+      if (exactPii.has(compactName(name))) {
+        return true;
+      }
+      const segments = nameSegments(name);
+      const first = segments[0];
+      const last = segments[segments.length - 1];
+      const isAbout = segments.length > 1 && (first !== void 0 && nonPiiPrefixes.has(first) || last !== void 0 && nonPiiSuffixes.has(last));
+      return !isAbout;
+    };
+    const isAuditCall = (callee) => {
+      const text = calleeText(callee);
+      return text !== null && auditCallees.some((entry) => text === entry || text.endsWith(`.${entry}`));
+    };
+    const opaque = (node, payload, why) => {
+      if (reportOpaque) {
+        context.report({ node, messageId: "opaquePayload", data: { payload, why } });
+      }
+    };
+    const checkObject = (object, payload) => {
+      for (const property of object.properties) {
+        if (property.type === AST_NODE_TYPES2.SpreadElement) {
+          const sources = spreadSources(property.argument);
+          if (sources === null) {
+            opaque(property, payload, "it spreads a value that is not an object literal");
+          } else {
+            sources.forEach((source) => checkObject(source, payload));
+          }
+          continue;
+        }
+        const key = staticKeyName(property);
+        if (key === null) {
+          opaque(property.key, payload, "it has a computed key");
+          continue;
+        }
+        const value = property.value;
+        if (!declared.has(key) && !isScalarFlag(value)) {
+          if (isPiiName(key)) {
+            context.report({
+              node: property.key,
+              messageId: "undeclaredPiiKey",
+              data: { key, payload }
+            });
+          } else {
+            const name = valueName(value);
+            if (name !== null && isPiiName(name)) {
+              context.report({
+                node: property.key,
+                messageId: "undeclaredPiiValue",
+                data: { key, payload, value: context.sourceCode.getText(value) }
+              });
+            }
+          }
+        }
+        checkNested(value, payload);
+      }
+    };
+    const checkNested = (node, payload) => {
+      if (node.type === AST_NODE_TYPES2.ObjectExpression) {
+        checkObject(node, payload);
+      } else if (node.type === AST_NODE_TYPES2.ArrayExpression) {
+        for (const element of node.elements) {
+          if (element !== null && element.type !== AST_NODE_TYPES2.SpreadElement) {
+            checkNested(element, payload);
+          }
+        }
+      }
+    };
+    const checkParams = (params) => {
+      for (const property of params.properties) {
+        if (property.type === AST_NODE_TYPES2.SpreadElement) {
+          const sources = spreadSources(property.argument);
+          if (sources === null) {
+            opaque(property, "params", "it spreads a value that is not an object literal");
+          } else {
+            sources.forEach(checkParams);
+          }
+          continue;
+        }
+        const key = staticKeyName(property);
+        if (key === null || !payloadKeys.has(key)) {
+          continue;
+        }
+        const value = property.value;
+        if (value.type === AST_NODE_TYPES2.ObjectExpression) {
+          checkObject(value, key);
+        } else if (!isEmptyValue(value)) {
+          opaque(value, key, "it is not an object literal");
+        }
+      }
+    };
+    return {
+      CallExpression(node) {
+        if (!isAuditCall(node.callee)) {
+          return;
+        }
+        const [params] = node.arguments;
+        if (params === void 0) {
+          return;
+        }
+        if (params.type !== AST_NODE_TYPES2.ObjectExpression) {
+          opaque(params, "params", "the audit call is not given an object literal");
+          return;
+        }
+        checkParams(params);
+      }
+    };
+  }
+});
 
 // src/rules/no-error-detail-loss.ts
-var RULE_NAME = "no-error-detail-loss";
+import { AST_NODE_TYPES as AST_NODE_TYPES3 } from "@typescript-eslint/utils";
+var RULE_NAME2 = "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) {
+    if (node.type === AST_NODE_TYPES3.CallExpression && loggerCallMethod(node, loggers) !== null) {
       found = true;
       return;
     }
@@ -79,19 +370,19 @@ function containsLoggerCall(block, loggers) {
 }
 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") {
+  if (parent.type === AST_NODE_TYPES3.MemberExpression && parent.object === id && !parent.computed && parent.property.type === AST_NODE_TYPES3.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)) {
+  if (parent.type === AST_NODE_TYPES3.CallExpression && parent.callee.type === AST_NODE_TYPES3.Identifier && parent.callee.name === "String" && parent.arguments.includes(id)) {
     return true;
   }
-  if (parent.type === AST_NODE_TYPES2.TemplateLiteral) {
+  if (parent.type === AST_NODE_TYPES3.TemplateLiteral) {
     return true;
   }
   return false;
 }
 var noErrorDetailLossRule = createRule({
-  name: RULE_NAME,
+  name: RULE_NAME2,
   meta: {
     type: "suggestion",
     docs: {
@@ -107,7 +398,7 @@ var noErrorDetailLossRule = createRule({
     const loggers = new Set(DEFAULT_LOGGERS);
     return {
       CatchClause(node) {
-        if (node.param === null || node.param.type !== AST_NODE_TYPES2.Identifier) {
+        if (node.param === null || node.param.type !== AST_NODE_TYPES3.Identifier) {
           return;
         }
         if (!containsLoggerCall(node.body, loggers)) {
@@ -138,8 +429,8 @@ var noErrorDetailLossRule = createRule({
 });
 
 // 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";
+import { AST_NODE_TYPES as AST_NODE_TYPES4 } from "@typescript-eslint/utils";
+var RULE_NAME3 = "no-sensitive-fields-in-logs";
 var DEFAULT_DENY_NAMES = [
   "password",
   "token",
@@ -149,7 +440,7 @@ var DEFAULT_DENY_NAMES = [
   "apiKey",
   "ssn"
 ];
-var optionSchema = {
+var optionSchema2 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -159,47 +450,21 @@ var optionSchema = {
     }
   }
 };
-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,
+  name: RULE_NAME3,
   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],
+    schema: [optionSchema2],
     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);
+    const matches = makeNameMatcher(options.denyNames ?? DEFAULT_DENY_NAMES);
     function walk(node, visit) {
       visit(node);
       for (const key of Object.keys(node)) {
@@ -238,9 +503,9 @@ var noSensitiveFieldsInLogsRule = createRule({
         };
         for (const arg of node.arguments) {
           walk(arg, (n) => {
-            if (n.type === AST_NODE_TYPES3.Identifier && matches(n.name)) {
+            if (n.type === AST_NODE_TYPES4.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)) {
+            } else if (n.type === AST_NODE_TYPES4.Property && n.key.type === AST_NODE_TYPES4.Literal && typeof n.key.value === "string" && matches(n.key.value)) {
               report(n.key.value, n.key);
             }
           });
@@ -251,9 +516,9 @@ var noSensitiveFieldsInLogsRule = createRule({
 });
 
 // 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 = {
+import { AST_NODE_TYPES as AST_NODE_TYPES5 } from "@typescript-eslint/utils";
+var RULE_NAME4 = "structured-log-arguments";
+var optionSchema3 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -264,13 +529,13 @@ var optionSchema2 = {
   }
 };
 var structuredLogArgumentsRule = createRule({
-  name: RULE_NAME3,
+  name: RULE_NAME4,
   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],
+    schema: [optionSchema3],
     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."
     }
@@ -285,7 +550,7 @@ var structuredLogArgumentsRule = createRule({
           return;
         }
         for (const arg of node.arguments) {
-          if (arg.type === AST_NODE_TYPES4.TemplateLiteral && arg.expressions.length > 0) {
+          if (arg.type === AST_NODE_TYPES5.TemplateLiteral && arg.expressions.length > 0) {
             context.report({
               node: arg,
               messageId: "interpolatedMessage",
@@ -302,12 +567,13 @@ var structuredLogArgumentsRule = createRule({
 var rules = {
   "structured-log-arguments": structuredLogArgumentsRule,
   "no-sensitive-fields-in-logs": noSensitiveFieldsInLogsRule,
-  "no-error-detail-loss": noErrorDetailLossRule
+  "no-error-detail-loss": noErrorDetailLossRule,
+  "audit-pii-declared": auditPiiDeclaredRule
 };
 
 // src/index.ts
 var NAMESPACE = "noctcore-observability";
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-observability", version: VERSION },
   rules,

package/docs/rules/audit-pii-declared.md

@@ -0,0 +1,143 @@
+# `noctcore-observability/audit-pii-declared`
+
+> A PII-shaped key written into an audit payload must be declared: registered for scrubbing when its
+> subject is purged, or declared not to be personal data.
+
+## What this rule does and does not prove
+
+Read this section before enabling the rule.
+
+It **enforces declaration, not deletion.** It proves that every PII-shaped key an audit write puts
+into a payload it can read appears in a list you maintain. It does **not** prove:
+
+- that anything reads that list, or that your purge job runs, succeeds, or scrubs those keys;
+- that a registered value is actually personal data, or that a `nonPiiFields` entry is not;
+- anything about payloads it cannot read (see `reportOpaque`) or keys its name heuristic does not
+  recognise as PII (a `note` holding an email address passes);
+- anything about audit columns outside the payload keys (`ipAddress`, `userAgent`), or about audit
+  rows written by code that does not go through `auditCallees`.
+
+The rule is one half of a contract. The other half is a purge job that anonymizes the registered keys
+in the audit rows of a user it deletes, and a test of that job. Without that half, this rule is a
+list with no reader.
+
+## Why
+
+Audit rows outlive the request that wrote them, and usually outlive the user. A policy of "raw email
+stays in audit metadata while the user exists and is scrubbed when the user is purged" keeps the trail
+useful for who-did-what while the data does not outlive the person. The purge job can only scrub keys
+it knows about. This rule keeps that list complete as new audit writes are added: a new
+`metadata: { newEmail }` fails lint until someone decides whether `newEmail` goes in the registry.
+
+## What it flags
+
+An audit write is a call whose callee text is an `auditCallees` entry, or ends with `.<entry>`
+(`this.auditService.log` matches `auditService.log`). The rule reads the first argument's
+`payloadKeys` properties (`metadata`, `before`, `after` by default). In a payload object literal, at
+any depth, including nested objects, array elements and literal spreads, it reports:
+
+- **`undeclaredPiiKey`**: a key matching `piiFields` that is in neither `registeredFields` nor
+  `nonPiiFields`;
+- **`undeclaredPiiValue`**: an undeclared, neutral key whose value is an identifier or member access
+  named like PII (`target: user.email`). The key is what the purger would have to scrub, so the key
+  is what must be declared;
+- **`opaquePayload`**: a payload the rule cannot read: a payload or params that is not an object
+  literal, a spread of a non-literal (`...subject.fence`, `...(extra ?? {})`), or a computed key. A
+  bag the rule cannot see is a bag it cannot vouch for. Turn this off with `reportOpaque: false` if
+  you accept that gap.
+
+A spread the rule *can* read is not opaque: `...{ a }`, both branches of `...(ok ? { a } : {})`, the
+right side of `...(ok && { a })`, and `null` / `undefined`.
+
+### Name matching
+
+`piiFields` entries match like `no-sensitive-fields-in-logs`: a single-word entry (`email`) matches a
+camelCase or snake_case segment (`newEmail`, `previous_email`) but not a word that merely contains it;
+a multi-word entry (`firstName`) matches the compacted name (`contactFirstName`).
+
+Some PII-shaped names describe the data rather than hold it. A name whose first segment is in
+`nonPiiPrefixes` (`isEmailPublic`) or whose last segment is in `nonPiiSuffixes` (`emailSent`,
+`phoneVerified`, `addressId`) is not reported. A key whose value is a boolean, number or `null`
+literal is not reported either. A name equal to a `piiFields` entry (`nationalId`) is always PII,
+whatever its suffix.
+
+Bare `name` is not in the default list, because it would flag `fileName` and `templateName`. Add it
+if your audit payloads carry person names under that key.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `auditCallees` | `string[]` | `[]` | Callee texts that are audit writes. Empty means the rule is inert. |
+| `payloadKeys` | `string[]` | `['metadata', 'before', 'after']` | Properties of the audit call's params that hold free-form payload. |
+| `piiFields` | `string[]` | `email`, `phone`, `mobile`, `address`, `firstName`, `lastName`, `fullName`, `displayName`, `surname`, `birthDate`, `dateOfBirth` | Name patterns that are PII-shaped. |
+| `registeredFields` | `string[]` | `[]` | Exact keys the purger scrubs. Declared PII. |
+| `nonPiiFields` | `string[]` | `[]` | Exact keys declared not to be personal data. |
+| `nonPiiPrefixes` | `string[]` | `is`, `has`, `was`, `should`, `can` | A first name segment that marks a flag. |
+| `nonPiiSuffixes` | `string[]` | `sent`, `verified`, `confirmed`, `enabled`, `disabled`, `changed`, `required`, `count`, `type`, `kind`, `status`, `id`, `ids` | A last name segment that marks a flag, count or reference. |
+| `reportOpaque` | `boolean` | `true` | Report payloads the rule cannot read. |
+
+## Wiring: one registry, not two
+
+The purge job needs the registry at run time and this rule needs it at lint time. Keep **one** copy,
+in code both can import, and pass it into the ESLint config. Never retype it into the config: two
+hand-kept copies of one list drift.
+
+```ts
+// packages/shared/src/audit/pii-registry.ts
+/** Audit payload keys holding personal data. The user purge anonymizes these. */
+export const AUDIT_PII_FIELDS = ['newEmail', 'email'] as const;
+```
+
+```js
+// eslint.config.mjs
+import { AUDIT_PII_FIELDS } from '@acme/shared/audit/pii-registry';
+
+export default [
+  {
+    rules: {
+      'noctcore-observability/audit-pii-declared': [
+        'error',
+        {
+          auditCallees: ['auditService.log', 'auditService.logOrThrow'],
+          registeredFields: [...AUDIT_PII_FIELDS],
+          nonPiiFields: ['emailTemplate'],
+        },
+      ],
+    },
+  },
+];
+```
+
+## Examples
+
+```ts
+// Bad: raw email in the payload, and no declaration that the purger must scrub it
+await this.auditService.log({
+  action: 'auth.email_change.requested',
+  userId,
+  metadata: { newEmail: normalizedEmail },
+});
+
+// Bad: before/after snapshots of a PII column
+await this.auditService.log({
+  action: 'auth.email_changed',
+  before: { email: previousEmail },
+  after: { email: pending.newEmail },
+});
+
+// Bad: the rule cannot see what this bag carries
+await this.auditService.log({ action, metadata: { ...grant.auditMetadata } });
+
+// Good, with registeredFields: ['newEmail', 'email']
+await this.auditService.log({ action, userId, metadata: { newEmail: normalizedEmail } });
+
+// Good: nothing PII-shaped; `emailSent` is a flag about the data
+await this.auditService.log({ action, metadata: { role, outcome, emailSent } });
+```
+
+## When not to use it
+
+If your audit payloads never carry personal data by policy, `no-sensitive-fields-in-logs`-style
+denial (fail on any PII-shaped key) is simpler: set `registeredFields` to `[]` and treat every report
+as a key to remove. If you have no purge job, do not enable this rule as if it gave you one.

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

@@ -1,6 +1,6 @@
 # `noctcore-observability/no-sensitive-fields-in-logs`
 
-> A name-heuristic guard against writing credentials and secrets into log sinks. Ships at `warn`.
+> A name-heuristic guard against writing credentials and secrets into log sinks. Ships at `error`.
 
 ## Why
 
@@ -9,8 +9,10 @@ Logs are long-lived, widely readable, and shipped to third-party aggregators. A
 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".
+It reads **names, never values**, so it is a heuristic. It still ships at `error`: a miss puts a
+credential in a long-lived log sink, while a false positive costs a rename or an explicit `redact()`.
+Tests that log a secret on purpose (to prove a redaction boundary works) should turn the rule off for
+those files in config.
 
 ## What it flags
 
@@ -55,4 +57,4 @@ type Options = {
 ## 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.
+rule is redundant. Otherwise keep it on at `error` as a second line of defence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-observability",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -60,6 +60,6 @@
     "@typescript-eslint/rule-tester": "^8.61.1",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0",
-    "vitest": "^3"
+    "vitest": "^4"
   }
 }