@agjs/tsforge 0.1.0

package/src/rule-packs/structured-logging/rules/mask-pii-fields.ts

@@ -0,0 +1,221 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  DEFAULT_LOGGER_METHODS,
+  DEFAULT_LOGGER_NAMES,
+  getStructuredPayload,
+  matchLoggerCall,
+} from "../utils/logger";
+
+export const RULE_NAME = "mask-pii-fields";
+
+export interface MaskPiiFieldsOptions {
+  readonly loggerNames?: readonly string[];
+  readonly loggerMethods?: readonly string[];
+  readonly piiFieldNames?: readonly string[];
+  readonly maskFunctions?: readonly string[];
+}
+
+type RuleOptions = [MaskPiiFieldsOptions];
+type MessageIds = "unmaskedPii";
+
+const DEFAULT_PII_FIELDS: readonly string[] = [
+  "email",
+  "phone",
+  "password",
+  "token",
+  "apiKey",
+  "secret",
+  "ssn",
+  "creditCard",
+  "authorization",
+];
+
+const DEFAULT_MASK_FUNCTIONS: readonly string[] = [
+  "maskEmailForLogging",
+  "maskToken",
+  "maskPii",
+  "redact",
+  "mask",
+];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    loggerNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    loggerMethods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    piiFieldNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+    maskFunctions: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+  },
+};
+
+function getPropertyKeyName(prop: TSESTree.Property): string | null {
+  if (prop.computed) {
+    return null;
+  }
+
+  if (prop.key.type === AST_NODE_TYPES.Identifier) {
+    return prop.key.name;
+  }
+
+  if (
+    prop.key.type === AST_NODE_TYPES.Literal &&
+    typeof prop.key.value === "string"
+  ) {
+    return prop.key.value;
+  }
+
+  return null;
+}
+
+const REDACTED_LITERAL = /^(\[?REDACTED\]?|\*+|<masked>|<redacted>)$/i;
+
+const PATTERN_TYPES = new Set<string>([
+  AST_NODE_TYPES.AssignmentPattern,
+  AST_NODE_TYPES.RestElement,
+  AST_NODE_TYPES.ArrayPattern,
+  AST_NODE_TYPES.ObjectPattern,
+  AST_NODE_TYPES.TSEmptyBodyFunctionExpression,
+]);
+
+function isExpression(
+  node: TSESTree.Property["value"]
+): node is TSESTree.Expression {
+  return !PATTERN_TYPES.has(node.type);
+}
+
+function isMaskedValue(
+  value: TSESTree.Expression,
+  maskFunctions: ReadonlySet<string>
+): boolean {
+  // Already-masked literal: `"[REDACTED]"`, `"***"`, etc.
+  if (
+    value.type === AST_NODE_TYPES.Literal &&
+    typeof value.value === "string" &&
+    REDACTED_LITERAL.test(value.value)
+  ) {
+    return true;
+  }
+
+  // Wrapped in a configured mask function: `maskEmailForLogging(email)`,
+  // `redact(token)`, `someObj.maskToken(t)`.
+  if (value.type !== AST_NODE_TYPES.CallExpression) {
+    return false;
+  }
+
+  const callee = value.callee;
+
+  if (callee.type === AST_NODE_TYPES.Identifier) {
+    return maskFunctions.has(callee.name);
+  }
+
+  if (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.property.type === AST_NODE_TYPES.Identifier
+  ) {
+    return maskFunctions.has(callee.property.name);
+  }
+
+  return false;
+}
+
+export const maskPiiFieldsRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow unmasked PII (email, phone, password, token, ...) in structured-logger payloads — the #1 way data leaks quietly.",
+    },
+    schema: [optionSchema],
+    messages: {
+      unmaskedPii:
+        "Field '{{field}}' may contain PII — wrap it in {{maskExample}}(...) or use a literal mask before logging.",
+    },
+  },
+  defaultOptions: [
+    {
+      loggerNames: [...DEFAULT_LOGGER_NAMES],
+      loggerMethods: [...DEFAULT_LOGGER_METHODS],
+      piiFieldNames: [...DEFAULT_PII_FIELDS],
+      maskFunctions: [...DEFAULT_MASK_FUNCTIONS],
+    },
+  ],
+  create(context, [options]) {
+    const loggerNames = new Set(options.loggerNames ?? DEFAULT_LOGGER_NAMES);
+    const loggerMethods = new Set(
+      options.loggerMethods ?? DEFAULT_LOGGER_METHODS
+    );
+    const piiFieldNames = new Set(options.piiFieldNames ?? DEFAULT_PII_FIELDS);
+    const maskFunctions = new Set(
+      options.maskFunctions ?? DEFAULT_MASK_FUNCTIONS
+    );
+    const maskExample =
+      options.maskFunctions?.[0] ?? DEFAULT_MASK_FUNCTIONS[0] ?? "mask";
+
+    return {
+      CallExpression(node) {
+        if (matchLoggerCall(node, loggerNames, loggerMethods) === null) {
+          return;
+        }
+
+        const payload = getStructuredPayload(node);
+
+        if (payload === null) {
+          return;
+        }
+
+        for (const prop of payload.properties) {
+          if (prop.type !== AST_NODE_TYPES.Property) {
+            continue;
+          }
+
+          const name = getPropertyKeyName(prop);
+
+          if (name === null || !piiFieldNames.has(name)) {
+            continue;
+          }
+
+          const value = prop.value;
+
+          if (!isExpression(value)) {
+            // Pattern nodes appear only in destructuring contexts; skip.
+            continue;
+          }
+
+          if (isMaskedValue(value, maskFunctions)) {
+            continue;
+          }
+
+          context.report({
+            node: prop,
+            messageId: "unmaskedPii",
+            data: { field: name, maskExample },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/structured-logging/rules/no-error-stringify.ts

@@ -0,0 +1,217 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-error-stringify";
+
+export interface NoErrorStringifyOptions {
+  readonly errorIdentifierNames?: readonly string[];
+  readonly extractorName?: string;
+}
+
+type RuleOptions = [NoErrorStringifyOptions];
+type MessageIds = "noErrorStringify";
+
+const DEFAULT_ERROR_NAMES: readonly string[] = ["error", "err", "e", "cause"];
+const DEFAULT_EXTRACTOR = "getErrorMessage";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    errorIdentifierNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    extractorName: { type: "string", minLength: 1 },
+  },
+};
+
+function isErrorIdentifier(
+  node: TSESTree.Node,
+  names: ReadonlySet<string>
+): node is TSESTree.Identifier {
+  return node.type === AST_NODE_TYPES.Identifier && names.has(node.name);
+}
+
+function isExtractorImported(
+  program: TSESTree.Program,
+  extractor: string
+): boolean {
+  for (const statement of program.body) {
+    if (statement.type !== AST_NODE_TYPES.ImportDeclaration) {
+      continue;
+    }
+
+    for (const spec of statement.specifiers) {
+      if (
+        spec.type === AST_NODE_TYPES.ImportSpecifier &&
+        spec.local.name === extractor
+      ) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export const noErrorStringifyRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow stringifying errors with `String(error)` / `${error}` / `error.toString()` — strips the cause chain. Use a configured extractor instead.",
+    },
+    fixable: "code",
+    schema: [optionSchema],
+    messages: {
+      noErrorStringify:
+        "Stringifying an error drops its cause chain — call `{{extractor}}(error)` instead.",
+    },
+  },
+  defaultOptions: [
+    {
+      errorIdentifierNames: [...DEFAULT_ERROR_NAMES],
+      extractorName: DEFAULT_EXTRACTOR,
+    },
+  ],
+  create(context, [options]) {
+    const errorNames = new Set(
+      options.errorIdentifierNames ?? DEFAULT_ERROR_NAMES
+    );
+    const extractor = options.extractorName ?? DEFAULT_EXTRACTOR;
+
+    let extractorImported = false;
+
+    return {
+      Program(program) {
+        extractorImported = isExtractorImported(program, extractor);
+      },
+      // `String(error)` / `String(err)` ...
+      CallExpression(node) {
+        const firstArg = node.arguments[0];
+
+        if (
+          node.callee.type === AST_NODE_TYPES.Identifier &&
+          node.callee.name === "String" &&
+          node.arguments.length === 1 &&
+          firstArg !== undefined &&
+          isErrorIdentifier(firstArg, errorNames)
+        ) {
+          const errIdent = firstArg;
+
+          context.report({
+            node,
+            messageId: "noErrorStringify",
+            data: { extractor },
+            ...(extractorImported
+              ? {
+                  fix(fixer) {
+                    return fixer.replaceText(
+                      node,
+                      `${extractor}(${errIdent.name})`
+                    );
+                  },
+                }
+              : {}),
+          });
+        }
+      },
+      // `error.toString()`
+      "CallExpression[callee.type='MemberExpression']"(
+        node: TSESTree.CallExpression
+      ) {
+        const { callee } = node;
+
+        if (callee.type !== AST_NODE_TYPES.MemberExpression) {
+          return;
+        }
+
+        if (
+          !callee.computed &&
+          callee.property.type === AST_NODE_TYPES.Identifier &&
+          callee.property.name === "toString" &&
+          isErrorIdentifier(callee.object, errorNames) &&
+          node.arguments.length === 0
+        ) {
+          const errIdent = callee.object;
+
+          context.report({
+            node,
+            messageId: "noErrorStringify",
+            data: { extractor },
+            ...(extractorImported
+              ? {
+                  fix(fixer) {
+                    return fixer.replaceText(
+                      node,
+                      `${extractor}(${errIdent.name})`
+                    );
+                  },
+                }
+              : {}),
+          });
+        }
+      },
+      // `${error}` inside a TemplateLiteral
+      TemplateLiteral(node) {
+        for (const expr of node.expressions) {
+          if (isErrorIdentifier(expr, errorNames)) {
+            const errIdent = expr;
+
+            context.report({
+              node: expr,
+              messageId: "noErrorStringify",
+              data: { extractor },
+              ...(extractorImported
+                ? {
+                    fix(fixer) {
+                      return fixer.replaceText(
+                        errIdent,
+                        `${extractor}(${errIdent.name})`
+                      );
+                    },
+                  }
+                : {}),
+            });
+          }
+        }
+      },
+      // `error + ""` or `"" + error`
+      BinaryExpression(node) {
+        if (node.operator !== "+") {
+          return;
+        }
+
+        const sides: TSESTree.Node[] = [node.left, node.right];
+        const hasEmptyString = sides.some(
+          (n) =>
+            n.type === AST_NODE_TYPES.Literal &&
+            typeof n.value === "string" &&
+            n.value === ""
+        );
+
+        if (!hasEmptyString) {
+          return;
+        }
+
+        for (const side of sides) {
+          if (isErrorIdentifier(side, errorNames)) {
+            context.report({
+              node,
+              messageId: "noErrorStringify",
+              data: { extractor },
+            });
+
+            return;
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/structured-logging/rules/require-event-field.ts

@@ -0,0 +1,136 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  DEFAULT_LOGGER_METHODS,
+  DEFAULT_LOGGER_NAMES,
+  getStructuredPayload,
+  matchLoggerCall,
+} from "../utils/logger";
+
+export const RULE_NAME = "require-event-field";
+
+export interface RequireEventFieldOptions {
+  readonly loggerNames?: readonly string[];
+  readonly loggerMethods?: readonly string[];
+  readonly eventField?: string;
+}
+
+type RuleOptions = [RequireEventFieldOptions];
+type MessageIds = "missingEventField";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    loggerNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    loggerMethods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    eventField: { type: "string", minLength: 1 },
+  },
+};
+
+function payloadHasField(
+  payload: TSESTree.ObjectExpression,
+  field: string
+): boolean {
+  for (const prop of payload.properties) {
+    if (prop.type === AST_NODE_TYPES.SpreadElement) {
+      // Spread of an external object — can't inspect statically.
+      // Be permissive: assume the spread might supply the field.
+      return true;
+    }
+
+    if (prop.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    if (
+      prop.key.type === AST_NODE_TYPES.Identifier &&
+      prop.key.name === field
+    ) {
+      return true;
+    }
+
+    if (
+      prop.key.type === AST_NODE_TYPES.Literal &&
+      typeof prop.key.value === "string" &&
+      prop.key.value === field
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export const requireEventFieldRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require structured logger calls to include an `event` field in their payload, so log searches in ELK/Datadog/Loki don't fall back to substring match.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingEventField:
+        "Logger call '{{method}}' missing `{{field}}:` field — add a stable string identifier so searches can filter by event.",
+    },
+  },
+  defaultOptions: [
+    {
+      loggerNames: [...DEFAULT_LOGGER_NAMES],
+      loggerMethods: [...DEFAULT_LOGGER_METHODS],
+      eventField: "event",
+    },
+  ],
+  create(context, [options]) {
+    const loggerNames = new Set(options.loggerNames ?? DEFAULT_LOGGER_NAMES);
+    const loggerMethods = new Set(
+      options.loggerMethods ?? DEFAULT_LOGGER_METHODS
+    );
+    const eventField = options.eventField ?? "event";
+
+    return {
+      CallExpression(node) {
+        const method = matchLoggerCall(node, loggerNames, loggerMethods);
+
+        if (method === null) {
+          return;
+        }
+
+        const payload = getStructuredPayload(node);
+
+        if (payload === null) {
+          // No structured payload at all — report on the whole call.
+          context.report({
+            node,
+            messageId: "missingEventField",
+            data: { method, field: eventField },
+          });
+
+          return;
+        }
+
+        if (!payloadHasField(payload, eventField)) {
+          context.report({
+            node: payload,
+            messageId: "missingEventField",
+            data: { method, field: eventField },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/structured-logging/utils/logger.ts

@@ -0,0 +1,104 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+export const DEFAULT_LOGGER_NAMES: readonly string[] = [
+  "logger",
+  "log",
+  "reqLogger",
+  "requestLogger",
+];
+
+export const DEFAULT_LOGGER_METHODS: readonly string[] = [
+  "fatal",
+  "error",
+  "warn",
+  "info",
+  "debug",
+  "trace",
+];
+
+/**
+ * Returns the matched method name when `node` is a logger call —
+ * `<id>.<method>(...)` where the receiver name is in `loggerNames`
+ * and the method is in `loggerMethods`. Returns null otherwise.
+ *
+ * Best-effort: we don't try to resolve types. A symbol named `logger`
+ * is the strong convention; project-specific aliases (e.g. `reqLogger`
+ * from `logger.child(...)`) are configurable via `loggerNames`.
+ */
+export function matchLoggerCall(
+  node: TSESTree.CallExpression,
+  loggerNames: ReadonlySet<string>,
+  loggerMethods: ReadonlySet<string>
+): string | null {
+  const callee = node.callee;
+
+  if (callee.type !== AST_NODE_TYPES.MemberExpression || callee.computed) {
+    return null;
+  }
+
+  if (callee.property.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+
+  if (!loggerMethods.has(callee.property.name)) {
+    return null;
+  }
+
+  const receiver = unwrapReceiver(callee.object);
+
+  if (!receiver) {
+    return null;
+  }
+
+  if (!loggerNames.has(receiver)) {
+    return null;
+  }
+
+  return callee.property.name;
+}
+
+/**
+ * Walks down a possibly-chained MemberExpression, returning the
+ * leftmost identifier name. Catches `this.logger.info(...)`,
+ * `ctx.log.info(...)`, etc. (returns "logger" / "log" — useful when
+ * those names are in the configured set).
+ */
+function unwrapReceiver(node: TSESTree.Expression): string | null {
+  if (node.type === AST_NODE_TYPES.Identifier) {
+    return node.name;
+  }
+
+  if (
+    node.type === AST_NODE_TYPES.MemberExpression &&
+    !node.computed &&
+    node.property.type === AST_NODE_TYPES.Identifier
+  ) {
+    return node.property.name;
+  }
+
+  return null;
+}
+
+/**
+ * Returns the second positional argument when it's an ObjectExpression
+ * — that's where structured-logging payloads live. Many loggers also
+ * accept `(obj, message)` (e.g. pino) — handle both shapes by checking
+ * the FIRST arg if no ObjectExpression is found at index 1.
+ */
+export function getStructuredPayload(
+  node: TSESTree.CallExpression
+): TSESTree.ObjectExpression | null {
+  const second = node.arguments[1];
+
+  if (second?.type === AST_NODE_TYPES.ObjectExpression) {
+    return second;
+  }
+
+  const first = node.arguments[0];
+
+  if (first?.type === AST_NODE_TYPES.ObjectExpression) {
+    return first;
+  }
+
+  return null;
+}

package/src/rule-packs/tanstack-query/index.ts

@@ -0,0 +1,20 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { prefixQueryKeyMustUseSetQueriesDataRule } from "./rules/prefix-query-key-must-use-set-queries-data";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "prefix-query-key-must-use-set-queries-data":
+    prefixQueryKeyMustUseSetQueriesDataRule,
+};
+
+export const tanstackQueryPack: IRulePack = {
+  id: "tanstack-query",
+  description: "Patterns for data fetching with TanStack Query",
+  rules,
+  rulesConfig: {
+    "prefix-query-key-must-use-set-queries-data": "error",
+  },
+};
+
+export default tanstackQueryPack;