@agjs/tsforge 0.1.0

package/src/rule-packs/i18n-keys/rules/static-translation-key-exists.ts

@@ -0,0 +1,173 @@
+import { readFileSync, existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+
+type MessageIds = "missingKey" | "dictionaryReadFailed";
+
+export interface StaticTranslationKeyExistsOptions {
+  readonly dictionary: string;
+}
+
+type RuleOptions = [StaticTranslationKeyExistsOptions];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  required: ["dictionary"],
+  properties: {
+    dictionary: { type: "string", minLength: 1 },
+  },
+};
+
+function collectLeafKeys(
+  value: unknown,
+  prefix: string,
+  out: Set<string>
+): void {
+  if (typeof value === "string") {
+    if (prefix !== "") {
+      out.add(prefix);
+    }
+
+    return;
+  }
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return;
+  }
+
+  for (const [k, v] of Object.entries(value)) {
+    const next = prefix === "" ? k : `${prefix}.${k}`;
+
+    collectLeafKeys(v, next, out);
+  }
+}
+
+function loadDictionary(pathFromRoot: string, cwd: string): Set<string> {
+  const abs = isAbsolute(pathFromRoot)
+    ? pathFromRoot
+    : resolve(cwd, pathFromRoot);
+
+  if (!existsSync(abs)) {
+    throw new Error(`eslint-plugin-i18n-keys: dictionary not found: ${abs}`);
+  }
+
+  const raw = readFileSync(abs, "utf8");
+  const parsed: unknown = JSON.parse(raw);
+  const keys = new Set<string>();
+
+  if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+    for (const [k, v] of Object.entries(parsed)) {
+      collectLeafKeys(v, k, keys);
+    }
+  }
+
+  return keys;
+}
+
+function getStringLiteral(
+  node: TSESTree.CallExpressionArgument | undefined
+): string | null {
+  if (node === undefined) {
+    return null;
+  }
+
+  if (node.type === AST_NODE_TYPES.Literal && typeof node.value === "string") {
+    return node.value;
+  }
+
+  return null;
+}
+
+function isTranslationCall(node: TSESTree.CallExpression): boolean {
+  const { callee } = node;
+
+  if (callee.type === AST_NODE_TYPES.Identifier && callee.name === "t") {
+    return true;
+  }
+
+  if (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "t" &&
+    callee.object.type === AST_NODE_TYPES.Identifier &&
+    callee.object.name === "i18n"
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+export const staticTranslationKeyExistsRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: "static-translation-key-exists",
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        'Static string passed to `t("...")` or `i18n.t("...")` must exist as a leaf path in the canonical locale JSON.',
+    },
+    schema: [optionSchema],
+    messages: {
+      missingKey:
+        'Translation key "{{key}}" is not defined in {{dictionary}} (static keys only; dynamic templates are not checked).',
+      dictionaryReadFailed:
+        "Could not read i18n dictionary at {{path}} (cwd: {{cwd}}).",
+    },
+  },
+  defaultOptions: [{ dictionary: "src/lib/i18n/locales/en/common.json" }],
+  create(context, [options]) {
+    const cwd = context.cwd ?? process.cwd();
+    let keys: Set<string> | undefined;
+
+    try {
+      keys = loadDictionary(options.dictionary, cwd);
+    } catch {
+      keys = undefined;
+    }
+
+    return {
+      Program(node: TSESTree.Program): void {
+        if (keys === undefined) {
+          context.report({
+            node,
+            messageId: "dictionaryReadFailed",
+            data: { path: options.dictionary, cwd },
+          });
+        }
+      },
+      CallExpression(node: TSESTree.CallExpression): void {
+        if (keys === undefined) {
+          return;
+        }
+
+        if (!isTranslationCall(node)) {
+          return;
+        }
+
+        const key = getStringLiteral(node.arguments[0]);
+
+        if (key === null || key === "") {
+          return;
+        }
+
+        if (keys.has(key)) {
+          return;
+        }
+
+        context.report({
+          node: node.arguments[0] ?? node,
+          messageId: "missingKey",
+          data: { key, dictionary: options.dictionary },
+        });
+      },
+    };
+  },
+});

package/src/rule-packs/index.ts

@@ -0,0 +1,139 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { bullmqPack } from "./bullmq";
+import { commentHygienePack } from "./comment-hygiene";
+import { codeFlowPack } from "./code-flow";
+import { drizzlePack } from "./drizzle";
+import { elysiaPack } from "./elysia";
+import { envAccessPack } from "./env-access";
+import { i18nKeysPack } from "./i18n-keys";
+import { jwtCookiesPack } from "./jwt-cookies";
+import { oauthSecurityPack } from "./oauth-security";
+import { reactComponentArchitecturePack } from "./react-component-architecture";
+import { structuredLoggingPack } from "./structured-logging";
+import { tanstackQueryPack } from "./tanstack-query";
+import { testConventionsPack } from "./test-conventions";
+import { PACK_REGISTRY } from "../stack-detection";
+
+/** Registry of all available rule packs, keyed by pack ID. */
+export const RULE_PACKS = {
+  bullmq: bullmqPack,
+  "code-flow": codeFlowPack,
+  "comment-hygiene": commentHygienePack,
+  drizzle: drizzlePack,
+  elysia: elysiaPack,
+  "env-access": envAccessPack,
+  "i18n-keys": i18nKeysPack,
+  "jwt-cookies": jwtCookiesPack,
+  "oauth-security": oauthSecurityPack,
+  "react-component-architecture": reactComponentArchitecturePack,
+  "structured-logging": structuredLoggingPack,
+  "tanstack-query": tanstackQueryPack,
+  "test-conventions": testConventionsPack,
+} as const;
+
+export type IRulePackId = keyof typeof RULE_PACKS;
+
+/** Type guard: check if a string is a valid RULE_PACKS key. */
+function isRulePackId(id: unknown): id is IRulePackId {
+  return typeof id === "string" && id in RULE_PACKS;
+}
+
+/** Apply rule overrides: "off" drops a rule, error/warn replaces its severity. */
+function applyOverrides(
+  mergedRulesConfig: Readonly<Record<string, "error" | "warn">>,
+  overrides?: Readonly<Record<string, "error" | "warn" | "off">>
+): Record<string, "error" | "warn"> {
+  const result: Record<string, "error" | "warn"> = {};
+
+  for (const [key, severity] of Object.entries(mergedRulesConfig)) {
+    const bareName = key.startsWith("tsforge/") ? key.slice(8) : key;
+    const override = overrides?.[bareName];
+
+    if (override === "off") {
+      continue;
+    }
+
+    result[key] = override ?? severity;
+  }
+
+  return result;
+}
+
+/**
+ * Builds an ESLint plugin and merged config from a selection of rule packs.
+ * Pack IDs present in stack-detection's PACK_REGISTRY but absent from RULE_PACKS
+ * are silently skipped (they may carry meta-rules later, not eslint rules).
+ * Throws only for IDs unknown to both registries.
+ *
+ * @param packIds Pack IDs to build config from
+ * @param overrides Optional rule severity overrides (keyed by bare rule name, not tsforge-prefixed)
+ *   - "off" removes the rule from the config
+ *   - "error"/"warn" replaces the severity
+ *
+ * @throws if any two packs define the same rule name
+ * @throws if a pack ID is unknown to both RULE_PACKS and PACK_REGISTRY
+ */
+export function buildPackEslintConfig(
+  packIds: readonly string[],
+  overrides?: Readonly<Record<string, "error" | "warn" | "off">>
+): {
+  plugin: TSESLint.FlatConfig.Plugin;
+  rules: Record<string, "error" | "warn">;
+} {
+  const mergedRules: Record<
+    string,
+    TSESLint.RuleModule<string, readonly unknown[]>
+  > = {};
+  const mergedRulesConfig: Record<string, "error" | "warn"> = {};
+  const seenRuleNames = new Set<string>();
+
+  for (const packId of packIds) {
+    const pack = isRulePackId(packId) ? RULE_PACKS[packId] : undefined;
+
+    // Skip pack IDs known to stack-detection but absent from RULE_PACKS
+    if (pack === undefined) {
+      const knownInRegistry = packId in PACK_REGISTRY;
+
+      if (!knownInRegistry) {
+        throw new Error(`Unknown rule pack: ${packId}`);
+      }
+
+      // Pack is in registry but not in RULE_PACKS — skip silently
+      continue;
+    }
+
+    for (const [ruleName, ruleModule] of Object.entries(pack.rules)) {
+      if (seenRuleNames.has(ruleName)) {
+        throw new Error(
+          `Rule collision: '${ruleName}' defined in multiple packs`
+        );
+      }
+
+      seenRuleNames.add(ruleName);
+      mergedRules[ruleName] = ruleModule;
+      const severity = pack.rulesConfig[ruleName];
+
+      if (severity !== undefined) {
+        mergedRulesConfig[`tsforge/${ruleName}`] = severity;
+      }
+    }
+  }
+
+  const finalRulesConfig = applyOverrides(mergedRulesConfig, overrides);
+
+  const plugin: TSESLint.FlatConfig.Plugin = {
+    meta: {
+      name: "tsforge",
+      version: "0.1.0",
+    },
+    rules: mergedRules,
+  };
+
+  return {
+    plugin,
+    rules: finalRulesConfig,
+  };
+}
+
+export type { IRulePack } from "./rule-packs.types";

package/src/rule-packs/jwt-cookies/index.ts

@@ -0,0 +1,25 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { authCookieMustBeHttpOnlyRule } from "./rules/auth-cookie-must-be-httponly";
+import { authCookieMustBeSecureInProdRule } from "./rules/auth-cookie-must-be-secure-in-prod";
+import { bcryptRoundsMinRule } from "./rules/bcrypt-rounds-min";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "auth-cookie-must-be-httponly": authCookieMustBeHttpOnlyRule,
+  "auth-cookie-must-be-secure-in-prod": authCookieMustBeSecureInProdRule,
+  "bcrypt-rounds-min": bcryptRoundsMinRule,
+};
+
+export const jwtCookiesPack: IRulePack = {
+  id: "jwt-cookies",
+  description: "Secure JWT and cookie handling patterns",
+  rules,
+  rulesConfig: {
+    "auth-cookie-must-be-httponly": "error",
+    "auth-cookie-must-be-secure-in-prod": "error",
+    "bcrypt-rounds-min": "error",
+  },
+};
+
+export default jwtCookiesPack;

package/src/rule-packs/jwt-cookies/rules/auth-cookie-must-be-httponly.ts

@@ -0,0 +1,150 @@
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  DEFAULT_AUTH_COOKIE_NAMES,
+  DEFAULT_SET_COOKIE_FUNCTIONS,
+  DEFAULT_TRUSTED_CONFIG_NAMES,
+  lookupCookieOption,
+  matchAuthCookieSet,
+} from "../utils";
+
+export const RULE_NAME = "auth-cookie-must-be-httponly";
+
+export interface AuthCookieMustBeHttpOnlyOptions {
+  readonly authCookieNames?: readonly string[];
+  readonly trustedConfigNames?: readonly string[];
+  readonly setCookieFunctions?: readonly string[];
+}
+
+type RuleOptions = [AuthCookieMustBeHttpOnlyOptions];
+type MessageIds = "missingHttpOnly";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    authCookieNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    trustedConfigNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+    setCookieFunctions: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+export const authCookieMustBeHttpOnlyRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Auth-cookie writes must set `httpOnly: true` (or spread a trusted cookie-config helper). JS-readable session cookies leak via XSS.",
+      },
+      schema: [optionSchema],
+      messages: {
+        missingHttpOnly:
+          "Auth cookie '{{name}}' missing `httpOnly: true` — JS-readable cookies leak via XSS.",
+      },
+    },
+    defaultOptions: [
+      {
+        authCookieNames: [...DEFAULT_AUTH_COOKIE_NAMES],
+        trustedConfigNames: [...DEFAULT_TRUSTED_CONFIG_NAMES],
+        setCookieFunctions: [...DEFAULT_SET_COOKIE_FUNCTIONS],
+      },
+    ],
+    create(context, [options]) {
+      const authCookieNames = new Set(
+        options.authCookieNames ?? DEFAULT_AUTH_COOKIE_NAMES
+      );
+      const trustedConfigNames = new Set(
+        options.trustedConfigNames ?? DEFAULT_TRUSTED_CONFIG_NAMES
+      );
+      const setCookieFunctions = new Set(
+        options.setCookieFunctions ?? DEFAULT_SET_COOKIE_FUNCTIONS
+      );
+
+      return {
+        CallExpression(node) {
+          const match = matchAuthCookieSet(
+            node,
+            authCookieNames,
+            setCookieFunctions
+          );
+
+          if (match === null) {
+            return;
+          }
+
+          if (match.optionsNode === null) {
+            context.report({
+              node,
+              messageId: "missingHttpOnly",
+              data: { name: match.cookieName },
+            });
+
+            return;
+          }
+
+          const { value, hasTrustedSpread } = lookupCookieOption(
+            match.optionsNode,
+            "httpOnly",
+            trustedConfigNames
+          );
+
+          if (hasTrustedSpread) {
+            // Spreads a trusted helper — assume it sets httpOnly correctly.
+            // If `httpOnly` is also explicitly present, require it to be `true`.
+            if (
+              value !== null &&
+              value.type === AST_NODE_TYPES.Literal &&
+              value.value === false
+            ) {
+              context.report({
+                node: value,
+                messageId: "missingHttpOnly",
+                data: { name: match.cookieName },
+              });
+            }
+
+            return;
+          }
+
+          if (value === null) {
+            context.report({
+              node,
+              messageId: "missingHttpOnly",
+              data: { name: match.cookieName },
+            });
+
+            return;
+          }
+
+          // Literal `true` ok. Literal `false` flagged. Anything else (env-derived
+          // expression, identifier) is conservatively accepted.
+          if (value.type === AST_NODE_TYPES.Literal && value.value !== true) {
+            context.report({
+              node: value,
+              messageId: "missingHttpOnly",
+              data: { name: match.cookieName },
+            });
+          }
+        },
+      };
+    },
+  }
+);

package/src/rule-packs/jwt-cookies/rules/auth-cookie-must-be-secure-in-prod.ts

@@ -0,0 +1,149 @@
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  DEFAULT_AUTH_COOKIE_NAMES,
+  DEFAULT_SET_COOKIE_FUNCTIONS,
+  DEFAULT_TRUSTED_CONFIG_NAMES,
+  lookupCookieOption,
+  matchAuthCookieSet,
+} from "../utils";
+
+export const RULE_NAME = "auth-cookie-must-be-secure-in-prod";
+
+export interface AuthCookieMustBeSecureInProdOptions {
+  readonly authCookieNames?: readonly string[];
+  readonly trustedConfigNames?: readonly string[];
+  readonly setCookieFunctions?: readonly string[];
+}
+
+type RuleOptions = [AuthCookieMustBeSecureInProdOptions];
+type MessageIds = "missingSecure";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    authCookieNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    trustedConfigNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+    setCookieFunctions: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+export const authCookieMustBeSecureInProdRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Auth-cookie writes must set `secure:` to `true` or an env-derived expression (anything non-literal). Cookies leak over HTTP without it.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingSecure:
+        "Auth cookie '{{name}}' missing `secure:` — cookies leak over HTTP in transit.",
+    },
+  },
+  defaultOptions: [
+    {
+      authCookieNames: [...DEFAULT_AUTH_COOKIE_NAMES],
+      trustedConfigNames: [...DEFAULT_TRUSTED_CONFIG_NAMES],
+      setCookieFunctions: [...DEFAULT_SET_COOKIE_FUNCTIONS],
+    },
+  ],
+  create(context, [options]) {
+    const authCookieNames = new Set(
+      options.authCookieNames ?? DEFAULT_AUTH_COOKIE_NAMES
+    );
+    const trustedConfigNames = new Set(
+      options.trustedConfigNames ?? DEFAULT_TRUSTED_CONFIG_NAMES
+    );
+    const setCookieFunctions = new Set(
+      options.setCookieFunctions ?? DEFAULT_SET_COOKIE_FUNCTIONS
+    );
+
+    return {
+      CallExpression(node) {
+        const match = matchAuthCookieSet(
+          node,
+          authCookieNames,
+          setCookieFunctions
+        );
+
+        if (match === null) {
+          return;
+        }
+
+        if (match.optionsNode === null) {
+          context.report({
+            node,
+            messageId: "missingSecure",
+            data: { name: match.cookieName },
+          });
+
+          return;
+        }
+
+        const { value, hasTrustedSpread } = lookupCookieOption(
+          match.optionsNode,
+          "secure",
+          trustedConfigNames
+        );
+
+        if (hasTrustedSpread) {
+          if (
+            value !== null &&
+            value.type === AST_NODE_TYPES.Literal &&
+            value.value === false
+          ) {
+            context.report({
+              node: value,
+              messageId: "missingSecure",
+              data: { name: match.cookieName },
+            });
+          }
+
+          return;
+        }
+
+        if (value === null) {
+          context.report({
+            node,
+            messageId: "missingSecure",
+            data: { name: match.cookieName },
+          });
+
+          return;
+        }
+
+        // Literal `false` is a hard fail. Literal `true` ok. Any non-literal
+        // (env-derived) is accepted on trust.
+        if (value.type === AST_NODE_TYPES.Literal && value.value !== true) {
+          context.report({
+            node: value,
+            messageId: "missingSecure",
+            data: { name: match.cookieName },
+          });
+        }
+      },
+    };
+  },
+});