@agjs/tsforge 0.1.0

package/src/rule-packs/elysia/rules/require-plugin-name.ts

@@ -0,0 +1,107 @@
+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 {
+  findObjectProperty,
+  getChainRoot,
+  isNewElysiaExpression,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "require-plugin-name";
+
+export interface RequirePluginNameOptions {
+  readonly allowAnonymousDefault?: boolean;
+}
+
+type RuleOptions = [RequirePluginNameOptions];
+type MessageIds = "missingPluginName";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    allowAnonymousDefault: { type: "boolean" },
+  },
+};
+
+export const requirePluginNameRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Exported Elysia plugin instances must declare `new Elysia({ name: '...' })` so the runtime can deduplicate plugin re-imports.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingPluginName:
+        'Exported Elysia plugin is anonymous — pass `{ name: "..." }` to `new Elysia(...)` so the runtime can deduplicate this plugin across imports.',
+    },
+  },
+  defaultOptions: [{ allowAnonymousDefault: false }],
+  create(context, [options]) {
+    const allowAnonymousDefault = options.allowAnonymousDefault === true;
+
+    return {
+      ExportNamedDeclaration(node) {
+        if (node.declaration?.type !== AST_NODE_TYPES.VariableDeclaration) {
+          return;
+        }
+
+        for (const declarator of node.declaration.declarations) {
+          if (declarator.init) {
+            checkExpression(declarator.init);
+          }
+        }
+      },
+      ExportDefaultDeclaration(node) {
+        if (allowAnonymousDefault) {
+          return;
+        }
+
+        const expr = node.declaration;
+
+        if (
+          expr.type === AST_NODE_TYPES.NewExpression ||
+          expr.type === AST_NODE_TYPES.CallExpression ||
+          expr.type === AST_NODE_TYPES.MemberExpression
+        ) {
+          checkExpression(expr);
+        }
+      },
+    };
+
+    function checkExpression(expression: TSESTree.Expression): void {
+      let root: TSESTree.Node = expression;
+
+      if (
+        expression.type === AST_NODE_TYPES.CallExpression ||
+        expression.type === AST_NODE_TYPES.MemberExpression
+      ) {
+        root = getChainRoot(expression);
+      }
+
+      if (!isNewElysiaExpression(root)) {
+        return;
+      }
+
+      const newExpr = root;
+      const arg = newExpr.arguments[0];
+
+      if (arg?.type === AST_NODE_TYPES.ObjectExpression) {
+        const nameProperty = findObjectProperty(arg, "name");
+
+        if (
+          nameProperty?.value.type === AST_NODE_TYPES.Literal &&
+          typeof nameProperty.value.value === "string" &&
+          nameProperty.value.value.length > 0
+        ) {
+          return;
+        }
+      }
+
+      context.report({ node: newExpr, messageId: "missingPluginName" });
+    }
+  },
+});

package/src/rule-packs/elysia/utils/elysiaChain.ts

@@ -0,0 +1,306 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+export const ROUTE_METHODS = new Set([
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "options",
+  "head",
+  "trace",
+  "all",
+  "ws",
+]);
+
+export const HOOK_METHODS = new Set([
+  "onRequest",
+  "onParse",
+  "onTransform",
+  "onBeforeHandle",
+  "resolve",
+  "onAfterHandle",
+  "mapResponse",
+  "onError",
+  "onAfterResponse",
+  "trace",
+]);
+
+type FunctionLike =
+  | TSESTree.ArrowFunctionExpression
+  | TSESTree.FunctionExpression
+  | TSESTree.FunctionDeclaration;
+
+export function isNewElysiaExpression(
+  node: TSESTree.Node | null | undefined
+): node is TSESTree.NewExpression {
+  return (
+    !!node &&
+    node.type === AST_NODE_TYPES.NewExpression &&
+    node.callee.type === AST_NODE_TYPES.Identifier &&
+    node.callee.name === "Elysia"
+  );
+}
+
+export function getChainRoot(
+  node: TSESTree.CallExpression | TSESTree.MemberExpression
+): TSESTree.Expression {
+  let current: TSESTree.Expression = node;
+
+  while (
+    current.type === AST_NODE_TYPES.CallExpression ||
+    current.type === AST_NODE_TYPES.MemberExpression
+  ) {
+    if (current.type === AST_NODE_TYPES.CallExpression) {
+      current = current.callee;
+      continue;
+    }
+
+    current = current.object;
+  }
+
+  return current;
+}
+
+export function collectElysiaVariables(program: TSESTree.Program): Set<string> {
+  const elysiaVars = new Set<string>();
+
+  for (const stmt of program.body) {
+    visitDeclarations(stmt, elysiaVars);
+  }
+
+  return elysiaVars;
+}
+
+function visitDeclarations(stmt: TSESTree.Node, elysiaVars: Set<string>): void {
+  if (stmt.type === AST_NODE_TYPES.VariableDeclaration) {
+    for (const declarator of stmt.declarations) {
+      if (
+        declarator.id.type === AST_NODE_TYPES.Identifier &&
+        declarator.init &&
+        chainRootIsNewElysia(declarator.init)
+      ) {
+        elysiaVars.add(declarator.id.name);
+      }
+    }
+
+    return;
+  }
+
+  if (stmt.type === AST_NODE_TYPES.ExportNamedDeclaration && stmt.declaration) {
+    visitDeclarations(stmt.declaration, elysiaVars);
+
+    return;
+  }
+
+  if (stmt.type === AST_NODE_TYPES.ExportDefaultDeclaration) {
+    return;
+  }
+}
+
+function chainRootIsNewElysia(expression: TSESTree.Expression): boolean {
+  if (expression.type === AST_NODE_TYPES.NewExpression) {
+    return isNewElysiaExpression(expression);
+  }
+
+  if (
+    expression.type === AST_NODE_TYPES.CallExpression ||
+    expression.type === AST_NODE_TYPES.MemberExpression
+  ) {
+    const root = getChainRoot(expression);
+
+    return isNewElysiaExpression(root);
+  }
+
+  return false;
+}
+
+export function isElysiaRouted(
+  call: TSESTree.CallExpression,
+  elysiaVars: Set<string>
+): boolean {
+  if (call.callee.type !== AST_NODE_TYPES.MemberExpression) {
+    return false;
+  }
+
+  const root = getChainRoot(call);
+
+  if (isNewElysiaExpression(root)) {
+    return true;
+  }
+
+  if (root.type === AST_NODE_TYPES.Identifier && elysiaVars.has(root.name)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function getMemberMethodName(
+  call: TSESTree.CallExpression
+): string | null {
+  if (
+    call.callee.type === AST_NODE_TYPES.MemberExpression &&
+    call.callee.property.type === AST_NODE_TYPES.Identifier
+  ) {
+    return call.callee.property.name;
+  }
+
+  return null;
+}
+
+export function isElysiaRouteCall(
+  call: TSESTree.CallExpression,
+  elysiaVars: Set<string>
+): boolean {
+  const method = getMemberMethodName(call);
+
+  return (
+    method !== null &&
+    ROUTE_METHODS.has(method) &&
+    isElysiaRouted(call, elysiaVars)
+  );
+}
+
+export function isElysiaHookCall(
+  call: TSESTree.CallExpression,
+  elysiaVars: Set<string>
+): boolean {
+  const method = getMemberMethodName(call);
+
+  return (
+    method !== null &&
+    HOOK_METHODS.has(method) &&
+    isElysiaRouted(call, elysiaVars)
+  );
+}
+
+export function getRouteMethod(call: TSESTree.CallExpression): string | null {
+  const method = getMemberMethodName(call);
+
+  return method && ROUTE_METHODS.has(method) ? method : null;
+}
+
+export function getRoutePathLiteral(
+  call: TSESTree.CallExpression
+): string | null {
+  const arg = call.arguments[0];
+
+  if (arg?.type === AST_NODE_TYPES.Literal && typeof arg.value === "string") {
+    return arg.value;
+  }
+
+  return null;
+}
+
+export function getRouteHandlerFunction(
+  call: TSESTree.CallExpression
+): FunctionLike | null {
+  for (let i = call.arguments.length - 1; i >= 0; i--) {
+    const arg = call.arguments[i];
+
+    if (
+      arg &&
+      (arg.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+        arg.type === AST_NODE_TYPES.FunctionExpression)
+    ) {
+      return arg;
+    }
+  }
+
+  return null;
+}
+
+export function getRouteOptionsObject(
+  call: TSESTree.CallExpression
+): TSESTree.ObjectExpression | null {
+  for (let i = call.arguments.length - 1; i >= 0; i--) {
+    const arg = call.arguments[i];
+
+    if (arg?.type === AST_NODE_TYPES.ObjectExpression) {
+      return arg;
+    }
+  }
+
+  return null;
+}
+
+export function findEnclosingRouteHandler(
+  node: TSESTree.Node,
+  elysiaVars: Set<string>
+): {
+  readonly fn: FunctionLike;
+  readonly routeCall: TSESTree.CallExpression;
+} | null {
+  let current: TSESTree.Node | undefined = node.parent;
+
+  while (current) {
+    if (
+      (current.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+        current.type === AST_NODE_TYPES.FunctionExpression) &&
+      current.parent?.type === AST_NODE_TYPES.CallExpression &&
+      current.parent.arguments.includes(current) &&
+      isElysiaRouteCall(current.parent, elysiaVars)
+    ) {
+      return { fn: current, routeCall: current.parent };
+    }
+
+    current = current.parent;
+  }
+
+  return null;
+}
+
+export function getCalleeName(node: TSESTree.CallExpression): string | null {
+  if (node.callee.type === AST_NODE_TYPES.Identifier) {
+    return node.callee.name;
+  }
+
+  if (
+    node.callee.type === AST_NODE_TYPES.MemberExpression &&
+    node.callee.property.type === AST_NODE_TYPES.Identifier
+  ) {
+    if (node.callee.object.type === AST_NODE_TYPES.Identifier) {
+      return `${node.callee.object.name}.${node.callee.property.name}`;
+    }
+
+    if (
+      node.callee.object.type === AST_NODE_TYPES.MemberExpression &&
+      node.callee.object.object.type === AST_NODE_TYPES.Identifier &&
+      node.callee.object.property.type === AST_NODE_TYPES.Identifier
+    ) {
+      return `${node.callee.object.object.name}.${node.callee.object.property.name}.${node.callee.property.name}`;
+    }
+
+    return node.callee.property.name;
+  }
+
+  return null;
+}
+
+export function findObjectProperty(
+  obj: TSESTree.ObjectExpression,
+  name: string
+): TSESTree.Property | null {
+  for (const property of obj.properties) {
+    if (property.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    if (
+      property.key.type === AST_NODE_TYPES.Identifier &&
+      property.key.name === name
+    ) {
+      return property;
+    }
+
+    if (
+      property.key.type === AST_NODE_TYPES.Literal &&
+      property.key.value === name
+    ) {
+      return property;
+    }
+  }
+
+  return null;
+}

package/src/rule-packs/env-access/index.ts

@@ -0,0 +1,23 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { noDirectProcessEnvRule } from "./rules/no-direct-process-env";
+import { noProcessExitRule } from "./rules/no-process-exit";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "no-direct-process-env": noDirectProcessEnvRule,
+  "no-process-exit": noProcessExitRule,
+};
+
+export const envAccessPack: IRulePack = {
+  id: "env-access",
+  description:
+    "Safe environment variable access patterns (validation and typing)",
+  rules,
+  rulesConfig: {
+    "no-direct-process-env": "error",
+    "no-process-exit": "error",
+  },
+};
+
+export default envAccessPack;

package/src/rule-packs/env-access/rules/index.ts

@@ -0,0 +1,2 @@
+export { noDirectProcessEnvRule } from "./no-direct-process-env";
+export { noProcessExitRule } from "./no-process-exit";

package/src/rule-packs/env-access/rules/no-direct-process-env.ts

@@ -0,0 +1,133 @@
+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 { matchesAnyGlobPattern, toPosixRelative } from "../../utils";
+
+export const RULE_NAME = "no-direct-process-env";
+
+export interface NoDirectProcessEnvOptions {
+  readonly allowedFiles?: readonly string[];
+  readonly singletonSuggestion?: string;
+}
+
+type RuleOptions = [NoDirectProcessEnvOptions];
+type MessageIds = "directProcessEnv";
+
+const DEFAULT_ALLOWED_FILES: readonly string[] = [
+  "src/config/env/**",
+  "**/*.config.{ts,js,mjs}",
+  "scripts/**",
+];
+
+const DEFAULT_SUGGESTION = "import { env } from '@/config/env'";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    allowedFiles: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+    singletonSuggestion: { type: "string", minLength: 1 },
+  },
+};
+
+function isProcessEnv(node: TSESTree.Node): boolean {
+  if (node.type !== AST_NODE_TYPES.MemberExpression) {
+    return false;
+  }
+
+  if (node.computed) {
+    return false;
+  }
+
+  if (
+    node.object.type !== AST_NODE_TYPES.Identifier ||
+    node.object.name !== "process"
+  ) {
+    return false;
+  }
+
+  if (
+    node.property.type !== AST_NODE_TYPES.Identifier ||
+    node.property.name !== "env"
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+export const noDirectProcessEnvRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow direct `process.env` access — force every consumer through a typed, boot-validated singleton.",
+    },
+    schema: [optionSchema],
+    messages: {
+      directProcessEnv:
+        "Read environment variables via the validated singleton ({{suggestion}}) — `process.env.X` bypasses the boot-time schema check.",
+    },
+  },
+  defaultOptions: [
+    {
+      allowedFiles: [...DEFAULT_ALLOWED_FILES],
+      singletonSuggestion: DEFAULT_SUGGESTION,
+    },
+  ],
+  create(context, [options]) {
+    const allowedFiles = options.allowedFiles ?? DEFAULT_ALLOWED_FILES;
+    const suggestion = options.singletonSuggestion ?? DEFAULT_SUGGESTION;
+
+    const relative = toPosixRelative(context.filename, context.cwd);
+
+    if (
+      allowedFiles.length > 0 &&
+      matchesAnyGlobPattern(relative, [...allowedFiles])
+    ) {
+      return {};
+    }
+
+    function report(node: TSESTree.Node): void {
+      context.report({
+        node,
+        messageId: "directProcessEnv",
+        data: { suggestion },
+      });
+    }
+
+    return {
+      // `process.env.X` (read or write) and `process.env[X]`
+      MemberExpression(node) {
+        if (isProcessEnv(node.object)) {
+          report(node);
+        }
+      },
+      // `const { X, Y } = process.env`
+      VariableDeclarator(node) {
+        if (node.init === null) {
+          return;
+        }
+
+        if (isProcessEnv(node.init)) {
+          report(node.init);
+        }
+      },
+      // `({ X } = process.env)` assignment-pattern destructure
+      AssignmentExpression(node) {
+        if (
+          node.left.type === AST_NODE_TYPES.ObjectPattern &&
+          isProcessEnv(node.right)
+        ) {
+          report(node.right);
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/env-access/rules/no-process-exit.ts

@@ -0,0 +1,95 @@
+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 { matchesAnyGlobPattern, toPosixRelative } from "../../utils";
+
+export const RULE_NAME = "no-process-exit";
+
+export interface NoProcessExitOptions {
+  readonly allowedFiles?: readonly string[];
+}
+
+type RuleOptions = [NoProcessExitOptions];
+type MessageIds = "processExit";
+
+const DEFAULT_ALLOWED_FILES: readonly string[] = [
+  "src/config/error-handlers/**",
+  "scripts/**",
+  "**/*.test.ts",
+  "tests/**",
+];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    allowedFiles: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+  },
+};
+
+function isProcessExit(node: TSESTree.CallExpression): boolean {
+  if (node.callee.type !== AST_NODE_TYPES.MemberExpression) {
+    return false;
+  }
+
+  if (node.callee.computed) {
+    return false;
+  }
+
+  if (
+    node.callee.object.type !== AST_NODE_TYPES.Identifier ||
+    node.callee.object.name !== "process"
+  ) {
+    return false;
+  }
+
+  if (
+    node.callee.property.type !== AST_NODE_TYPES.Identifier ||
+    node.callee.property.name !== "exit"
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+export const noProcessExitRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow `process.exit()` outside the centralized shutdown and CLI entrypoints — forces graceful teardown through the error-handlers module.",
+    },
+    schema: [optionSchema],
+    messages: {
+      processExit:
+        "`process.exit()` is reserved for graceful shutdown (`src/config/error-handlers/`) and CLI scripts. Route shutdown through the centralized handlers instead.",
+    },
+  },
+  defaultOptions: [{ allowedFiles: [...DEFAULT_ALLOWED_FILES] }],
+  create(context, [options]) {
+    const allowedFiles = options.allowedFiles ?? DEFAULT_ALLOWED_FILES;
+    const relative = toPosixRelative(context.filename, context.cwd);
+
+    if (
+      allowedFiles.length > 0 &&
+      matchesAnyGlobPattern(relative, [...allowedFiles])
+    ) {
+      return {};
+    }
+
+    return {
+      CallExpression(node) {
+        if (isProcessExit(node)) {
+          context.report({ node, messageId: "processExit" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/i18n-keys/index.ts

@@ -0,0 +1,19 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { staticTranslationKeyExistsRule } from "./rules/static-translation-key-exists";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "static-translation-key-exists": staticTranslationKeyExistsRule,
+};
+
+export const i18nKeysPack: IRulePack = {
+  id: "i18n-keys",
+  description: "Internationalization key management and translation patterns",
+  rules,
+  rulesConfig: {
+    "static-translation-key-exists": "error",
+  },
+};
+
+export default i18nKeysPack;