@noctcore/eslint-plugin-observability 0.3.0 → 0.3.1

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

@@ -83,7 +83,7 @@ The purge job needs the registry at run time and this rule needs it at lint time
 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
+```ts prose reason="the registry module the config imports, not a lint example"
 // 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;
@@ -111,28 +111,33 @@ export default [
 
 ## Examples
 
-```ts
-// Bad: raw email in the payload, and no declaration that the purger must scrub it
+```ts bad reports=4 options={"auditCallees":["auditService.log","auditService.logOrThrow"]}
+// 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
+// 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
+// the rule cannot see what this bag carries
 await this.auditService.log({ action, metadata: { ...grant.auditMetadata } });
+```
+
+Declaring the keys is the fix, so this example runs with `registeredFields: ['newEmail', 'email']`:
 
-// Good, with registeredFields: ['newEmail', 'email']
+```ts good reconfigured options={"auditCallees":["auditService.log","auditService.logOrThrow"],"registeredFields":["newEmail","email"]}
 await this.auditService.log({ action, userId, metadata: { newEmail: normalizedEmail } });
+```
 
-// Good: nothing PII-shaped; `emailSent` is a flag about the data
+```ts good options={"auditCallees":["auditService.log","auditService.logOrThrow"]}
+// nothing PII-shaped; `emailSent` is a flag about the data
 await this.auditService.log({ action, metadata: { role, outcome, emailSent } });
 ```
 

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

@@ -8,13 +8,15 @@ A caught error carries a **stack trace** and often a **`cause`** — the parts y
 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
+```ts bad
+// stack and cause are gone
 try { await run(); } catch (e) {
   logger.error(`run failed: ${e.message}`);
 }
+```
 
-// ✓ the whole error survives
+```ts good
+// the whole error survives
 try { await run(); } catch (e) {
   logger.error('run failed', { err: e });
 }
@@ -32,12 +34,12 @@ A `catch (e)` block where **all** of the following hold:
 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}`); }
+```ts good
+// .stack is read: not a lossy form
+try { await run(); } catch (e) { logger.error(`failed: ${e.stack}`); }
 
-// ✓ mixed use — the full capture wins
-catch (e) { logger.error(`${e.message}`, { err: e }); }
+// mixed use: the full capture wins
+try { await run(); } catch (e) { logger.error(`${e.message}`, { err: e }); }
 ```
 
 Distinct from a fully-**unused** catch binding (`catch (e) { cleanup(); }`), which this rule

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

@@ -10,7 +10,7 @@ request by months. This rule catches the most common shape — a variable, prope
 whose **name** matches a sensitive-field denylist appearing inside a logger call.
 
 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()`.
+credential in a long-lived log sink, while a false positive costs a rename.
 Tests that log a secret on purpose (to prove a redaction boundary works) should turn the rule off for
 those files in config.
 
@@ -19,16 +19,24 @@ those files in config.
 Inside a logger call (`<logger>.<method>(...)`), any identifier, member-access property, or object key
 whose name matches the denylist:
 
-```ts
-// ✗ all three flag
+```ts bad reports=3
+// 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) });
+```ts good
+// log who, not the credential
+logger.info('login', { userId });
+logger.error('auth failed', { userId, reason: 'bad-credentials' });
+logger.info('session', { sessionId: user.sessionId });
 ```
 
+Wrapping the value in a call does not help: `{ password: redact(password) }` is still reported,
+twice, because the key and the argument are both named `password`. The rule has no notion of a
+redaction helper. Omit the field and log an identifier for the subject instead.
+
 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
@@ -37,14 +45,14 @@ snake_case segment (`accessToken`, `access_token`) but **not** a longer word tha
 String **literals** are never inspected — only names — so a message that mentions a sensitive word is
 fine:
 
-```ts
-// ✓ a literal, not a value
+```ts good
+// a literal, not a value
 logger.info('password reset email sent');
 ```
 
 ## Options
 
-```ts
+```ts prose reason="the options type, not a lint example"
 type Options = {
   /**
    * Field names to treat as sensitive (case-insensitive, segment-aware).

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

@@ -6,7 +6,7 @@
 
 Dynamic values baked into a log **message** string are unqueryable. When you write
 
-```ts
+```ts bad
 logger.info(`processing task ${taskId} for ${userId}`);
 ```
 
@@ -14,7 +14,7 @@ a log aggregator stores one opaque line of free text — it cannot index, filter
 `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
+```ts good
 logger.info('processing task', { taskId, userId });
 ```
 
@@ -24,11 +24,13 @@ A logger call — `<logger>.<method>(...)` where `<method>` is `info` / `warn` /
 `<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
+```ts bad
+// dynamic values interpolated into the message
 logger.error(`failed: ${err.code}`);
+```
 
-// ✓ static message + structured context
+```ts good
+// static message + structured context
 logger.error('request failed', { code: err.code });
 ```
 
@@ -38,8 +40,8 @@ namespace or `this` (`this.logger.info(...)`, `app.log.warn(...)`) are recognise
 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
+```ts good
+// the template builds a URL field, not the message
 logger.info('fetching', { url: `${base}/tasks` });
 ```
 
@@ -51,7 +53,7 @@ A template with **no** expressions carries no dynamic value and is ignored
 
 ## Options
 
-```ts
+```ts prose reason="the options type, not a lint example"
 type Options = {
   /** Logger object names to scan. Default: ['console', 'logger', 'log']. */
   loggers?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-observability",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Structured-logging discipline ESLint rules — context objects over interpolated messages, no sensitive fields in logs, no error-detail loss.",
   "license": "MIT",
   "type": "module",