@agjs/tsforge 0.1.0

package/src/rule-packs/drizzle/rules/tables-must-have-timestamps.ts

@@ -0,0 +1,312 @@
+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 { isPgTableCall } from "../utils";
+
+export const RULE_NAME = "tables-must-have-timestamps";
+
+export interface TablesMustHaveTimestampsOptions {
+  readonly requireColumns?: readonly string[];
+  readonly requireOnUpdate?: readonly string[];
+  readonly ignoreTablePattern?: string;
+}
+
+type RuleOptions = [TablesMustHaveTimestampsOptions];
+type MessageIds = "missingTimestamp" | "missingOnUpdate";
+
+const DEFAULT_REQUIRE_COLUMNS = ["createdAt"] as const;
+const DEFAULT_REQUIRE_ON_UPDATE: readonly string[] = [];
+const ON_UPDATE_METHODS = new Set(["$onUpdate", "$onUpdateFn"]);
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    requireColumns: {
+      type: "array",
+      items: {
+        type: "string",
+      },
+      uniqueItems: true,
+    },
+    requireOnUpdate: {
+      type: "array",
+      items: {
+        type: "string",
+      },
+      uniqueItems: true,
+    },
+    ignoreTablePattern: {
+      type: "string",
+    },
+  },
+};
+
+export const tablesMustHaveTimestampsRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "suggestion",
+      docs: {
+        description:
+          "Require Drizzle tables to declare standard timestamp columns (createdAt by default).",
+      },
+      schema: [optionSchema],
+      messages: {
+        missingTimestamp:
+          "Table '{{name}}' missing required column(s): {{missing}}.",
+        missingOnUpdate:
+          "Column '{{column}}' on table '{{name}}' is in `requireOnUpdate` but its `timestamp(...)` chain does not include `.$onUpdate(...)` — without it, the column will not auto-update on row mutations.",
+      },
+    },
+    defaultOptions: [
+      {
+        requireColumns: [...DEFAULT_REQUIRE_COLUMNS],
+        requireOnUpdate: [...DEFAULT_REQUIRE_ON_UPDATE],
+      },
+    ],
+    create(context, [options]) {
+      const requireColumns = options.requireColumns ?? DEFAULT_REQUIRE_COLUMNS;
+      const requireOnUpdate =
+        options.requireOnUpdate ?? DEFAULT_REQUIRE_ON_UPDATE;
+      const ignorePattern = compilePattern(options.ignoreTablePattern);
+
+      return {
+        VariableDeclarator(node) {
+          if (node.init?.type !== AST_NODE_TYPES.CallExpression) {
+            return;
+          }
+
+          if (!isPgTableCall(node.init)) {
+            return;
+          }
+
+          const tableName = getTableName(node);
+
+          if (!tableName) {
+            return;
+          }
+
+          if (ignorePattern?.test(tableName)) {
+            return;
+          }
+
+          const columnsArg = node.init.arguments[1];
+
+          const definedColumns =
+            columnsArg?.type === AST_NODE_TYPES.ObjectExpression
+              ? columnsArg
+              : null;
+
+          const reportNode =
+            node.id.type === AST_NODE_TYPES.Identifier ? node.id : node;
+
+          if (requireColumns.length > 0) {
+            const missing = requireColumns.filter(
+              (column) => !hasTimestampColumn(definedColumns, column)
+            );
+
+            if (missing.length > 0) {
+              context.report({
+                node: reportNode,
+                messageId: "missingTimestamp",
+                data: {
+                  name: tableName,
+                  missing: missing.join(", "),
+                },
+              });
+            }
+          }
+
+          if (definedColumns) {
+            for (const violation of findOnUpdateViolations(
+              definedColumns,
+              requireOnUpdate
+            )) {
+              context.report({
+                node: violation.property,
+                messageId: "missingOnUpdate",
+                data: {
+                  name: tableName,
+                  column: violation.column,
+                },
+              });
+            }
+          }
+        },
+      };
+    },
+  }
+);
+
+function compilePattern(source: string | undefined): RegExp | null {
+  if (!source) {
+    return null;
+  }
+
+  try {
+    return new RegExp(source);
+  } catch {
+    return null;
+  }
+}
+
+function getTableName(node: TSESTree.VariableDeclarator): string | null {
+  if (node.id.type === AST_NODE_TYPES.Identifier) {
+    return node.id.name;
+  }
+
+  if (node.init?.type === AST_NODE_TYPES.CallExpression) {
+    const firstArg = node.init.arguments[0];
+
+    if (
+      firstArg?.type === AST_NODE_TYPES.Literal &&
+      typeof firstArg.value === "string"
+    ) {
+      return firstArg.value;
+    }
+  }
+
+  return null;
+}
+
+function findTimestampProperty(
+  columns: TSESTree.ObjectExpression,
+  columnName: string
+): TSESTree.Property | null {
+  for (const property of columns.properties) {
+    if (property.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    if (!matchesPropertyKey(property, columnName)) {
+      continue;
+    }
+
+    if (
+      property.value.type === AST_NODE_TYPES.CallExpression &&
+      isTimestampInitializer(property.value)
+    ) {
+      return property;
+    }
+  }
+
+  return null;
+}
+
+function matchesPropertyKey(
+  property: TSESTree.Property,
+  name: string
+): boolean {
+  if (
+    property.key.type === AST_NODE_TYPES.Identifier &&
+    property.key.name === name
+  ) {
+    return true;
+  }
+
+  if (
+    property.key.type === AST_NODE_TYPES.Literal &&
+    property.key.value === name
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function isTimestampInitializer(node: TSESTree.CallExpression): boolean {
+  const calleeName = getCalleeIdentifierName(node);
+
+  return calleeName === "timestamp";
+}
+
+function getCalleeIdentifierName(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
+  ) {
+    return node.callee.property.name;
+  }
+
+  return null;
+}
+
+function chainHasOnUpdate(startCall: TSESTree.CallExpression): boolean {
+  let current: TSESTree.Node = startCall;
+  let parent = getParent(current);
+
+  while (parent !== undefined) {
+    if (
+      parent.type === AST_NODE_TYPES.MemberExpression &&
+      parent.object === current &&
+      parent.property.type === AST_NODE_TYPES.Identifier &&
+      ON_UPDATE_METHODS.has(parent.property.name)
+    ) {
+      const methodCall = getParent(parent);
+
+      if (methodCall?.type === AST_NODE_TYPES.CallExpression) {
+        return true;
+      }
+    }
+
+    if (
+      parent.type === AST_NODE_TYPES.MemberExpression ||
+      parent.type === AST_NODE_TYPES.CallExpression
+    ) {
+      current = parent;
+      parent = getParent(current);
+
+      continue;
+    }
+
+    break;
+  }
+
+  return false;
+}
+
+function getParent(node: TSESTree.Node): TSESTree.Node | undefined {
+  return node.parent;
+}
+
+/** Columns from `requireOnUpdate` whose timestamp chain lacks `.$onUpdate(...)`. */
+function findOnUpdateViolations(
+  definedColumns: TSESTree.ObjectExpression,
+  requireOnUpdate: readonly string[]
+): { property: TSESTree.Property; column: string }[] {
+  const violations: { property: TSESTree.Property; column: string }[] = [];
+
+  for (const column of requireOnUpdate) {
+    const property = findTimestampProperty(definedColumns, column);
+
+    if (!property) {
+      continue;
+    }
+
+    if (
+      property.value.type === AST_NODE_TYPES.CallExpression &&
+      !chainHasOnUpdate(property.value)
+    ) {
+      violations.push({ property, column });
+    }
+  }
+
+  return violations;
+}
+
+function hasTimestampColumn(
+  columns: TSESTree.ObjectExpression | null,
+  columnName: string
+): boolean {
+  if (!columns) {
+    return false;
+  }
+
+  return findTimestampProperty(columns, columnName) !== null;
+}

package/src/rule-packs/drizzle/rules/timestamp-must-specify-mode.ts

@@ -0,0 +1,166 @@
+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 = "timestamp-must-specify-mode";
+
+export interface TimestampMustSpecifyModeOptions {
+  readonly allowedModes?: readonly ("date" | "string")[];
+}
+
+type RuleOptions = [TimestampMustSpecifyModeOptions];
+type MessageIds = "missingMode" | "invalidMode";
+
+const DEFAULT_ALLOWED_MODES = ["date", "string"] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    allowedModes: {
+      type: "array",
+      uniqueItems: true,
+      items: {
+        type: "string",
+        enum: ["date", "string"],
+      },
+      minItems: 1,
+    },
+  },
+};
+
+export const timestampMustSpecifyModeRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Require every Drizzle timestamp(...) call to explicitly set `mode: 'date'` or `mode: 'string'`.",
+      },
+      schema: [optionSchema],
+      messages: {
+        missingMode:
+          "timestamp(...) call does not specify `mode` — pass `{ mode: 'date' }` or `{ mode: 'string' }` so return types are deterministic across drivers.",
+        invalidMode:
+          "timestamp(...) `mode` must be one of: {{allowed}}. Got: {{actual}}.",
+      },
+    },
+    defaultOptions: [{ allowedModes: [...DEFAULT_ALLOWED_MODES] }],
+    create(context, [options]) {
+      const allowedModes = options.allowedModes ?? DEFAULT_ALLOWED_MODES;
+
+      return {
+        CallExpression(node) {
+          if (!isTimestampCallee(node)) {
+            return;
+          }
+
+          const optionsArg = node.arguments[1];
+
+          if (optionsArg?.type !== AST_NODE_TYPES.ObjectExpression) {
+            context.report({ node, messageId: "missingMode" });
+
+            return;
+          }
+
+          const modeProperty = findModeProperty(optionsArg);
+
+          if (!modeProperty) {
+            context.report({ node: optionsArg, messageId: "missingMode" });
+
+            return;
+          }
+
+          if (
+            modeProperty.value.type !== AST_NODE_TYPES.Literal ||
+            typeof modeProperty.value.value !== "string"
+          ) {
+            context.report({
+              node: modeProperty,
+              messageId: "invalidMode",
+              data: {
+                allowed: allowedModes.join(" | "),
+                actual: "<non-literal>",
+              },
+            });
+
+            return;
+          }
+
+          const modeValue = modeProperty.value.value;
+
+          if (!allowedModesIncludes(allowedModes, modeValue)) {
+            context.report({
+              node: modeProperty,
+              messageId: "invalidMode",
+              data: {
+                allowed: allowedModes.join(" | "),
+                actual: modeValue,
+              },
+            });
+          }
+        },
+      };
+    },
+  }
+);
+
+function isTimestampCallee(node: TSESTree.CallExpression): boolean {
+  if (
+    node.callee.type === AST_NODE_TYPES.Identifier &&
+    node.callee.name === "timestamp"
+  ) {
+    return true;
+  }
+
+  if (
+    node.callee.type === AST_NODE_TYPES.MemberExpression &&
+    node.callee.property.type === AST_NODE_TYPES.Identifier &&
+    node.callee.property.name === "timestamp"
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function findModeProperty(
+  obj: TSESTree.ObjectExpression
+): TSESTree.Property | null {
+  for (const property of obj.properties) {
+    if (property.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    if (propertyKeyMatches(property, "mode")) {
+      return property;
+    }
+  }
+
+  return null;
+}
+
+function propertyKeyMatches(
+  property: TSESTree.Property,
+  name: string
+): boolean {
+  if (
+    property.key.type === AST_NODE_TYPES.Identifier &&
+    property.key.name === name
+  ) {
+    return true;
+  }
+
+  return (
+    property.key.type === AST_NODE_TYPES.Literal && property.key.value === name
+  );
+}
+
+function allowedModesIncludes(
+  allowedModes: readonly string[],
+  value: string
+): boolean {
+  return allowedModes.includes(value);
+}

package/src/rule-packs/drizzle/utils.ts

@@ -0,0 +1,115 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { walkAll } from "../utils";
+
+/**
+ * Helper utilities for Drizzle rules.
+ */
+
+export function isPgTableCall(node: TSESTree.CallExpression): boolean {
+  if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  const name = node.callee.name;
+
+  return name === "pgTable" || name === "pgTableCreator";
+}
+
+export function isRelationsCall(node: TSESTree.CallExpression): boolean {
+  if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  return node.callee.name === "relations";
+}
+
+export function isForeignKeyCall(node: TSESTree.CallExpression): boolean {
+  if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  return node.callee.name === "foreignKey";
+}
+
+export function isSchemaBuilderCall(node: TSESTree.CallExpression): boolean {
+  const calleeName = getCalleeIdentifierName(node);
+
+  if (!calleeName) {
+    return false;
+  }
+
+  // Drizzle schema builders: tables, relations, indices, checks, uniqueConstraints, etc.
+  const schemaBuilders = new Set([
+    "pgTable",
+    "pgTableCreator",
+    "relations",
+    "index",
+    "uniqueIndex",
+    "primaryKey",
+    "foreignKey",
+    "check",
+    "unique",
+    "schema",
+    "serial",
+    "smallserial",
+    "bigserial",
+    "varchar",
+    "char",
+    "text",
+    "integer",
+    "smallint",
+    "bigint",
+    "decimal",
+    "numeric",
+    "real",
+    "doublePrecision",
+    "boolean",
+    "date",
+    "time",
+    "timestamp",
+    "interval",
+    "json",
+    "jsonb",
+    "uuid",
+    "bytea",
+    "citext",
+    "inet",
+    "array",
+    "enum",
+    "geometry",
+    "geography",
+  ]);
+
+  return schemaBuilders.has(calleeName);
+}
+
+function getCalleeIdentifierName(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
+  ) {
+    return node.callee.property.name;
+  }
+
+  return null;
+}
+
+export function findCallExpressionsDeep(
+  root: TSESTree.Node,
+  predicate: (node: TSESTree.CallExpression) => boolean
+): TSESTree.CallExpression[] {
+  const results: TSESTree.CallExpression[] = [];
+
+  walkAll(root, (node) => {
+    if (node.type === AST_NODE_TYPES.CallExpression && predicate(node)) {
+      results.push(node);
+    }
+  });
+
+  return results;
+}

package/src/rule-packs/elysia/index.ts

@@ -0,0 +1,43 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { consistentStatusViaSetRule } from "./rules/consistent-status-via-set";
+import { noDecorateStateCollisionRule } from "./rules/no-decorate-state-collision";
+import { noSeparateModelInterfacesRule } from "./rules/no-separate-model-interfaces";
+import { preferDestructuredContextRule } from "./rules/prefer-destructured-context";
+import { preferDirectReturnRule } from "./rules/prefer-direct-return";
+import { preferStaticServicesRule } from "./rules/prefer-static-services";
+import { preferThrowStatusRule } from "./rules/prefer-throw-status";
+import { requireHooksBeforeRoutesRule } from "./rules/require-hooks-before-routes";
+import { requirePluginNameRule } from "./rules/require-plugin-name";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "consistent-status-via-set": consistentStatusViaSetRule,
+  "no-decorate-state-collision": noDecorateStateCollisionRule,
+  "no-separate-model-interfaces": noSeparateModelInterfacesRule,
+  "prefer-destructured-context": preferDestructuredContextRule,
+  "prefer-direct-return": preferDirectReturnRule,
+  "prefer-static-services": preferStaticServicesRule,
+  "prefer-throw-status": preferThrowStatusRule,
+  "require-hooks-before-routes": requireHooksBeforeRoutesRule,
+  "require-plugin-name": requirePluginNameRule,
+};
+
+export const elysiaPack: IRulePack = {
+  id: "elysia",
+  description: "Elysia framework best practices and type-safety patterns",
+  rules,
+  rulesConfig: {
+    "consistent-status-via-set": "error",
+    "no-decorate-state-collision": "error",
+    "no-separate-model-interfaces": "warn",
+    "prefer-destructured-context": "warn",
+    "prefer-direct-return": "warn",
+    "prefer-static-services": "warn",
+    "prefer-throw-status": "warn",
+    "require-hooks-before-routes": "error",
+    "require-plugin-name": "error",
+  },
+};
+
+export default elysiaPack;

package/src/rule-packs/elysia/rules/consistent-status-via-set.ts

@@ -0,0 +1,69 @@
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  collectElysiaVariables,
+  findEnclosingRouteHandler,
+  findObjectProperty,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "consistent-status-via-set";
+
+type RuleOptions = [];
+type MessageIds = "useSetStatus";
+
+export const consistentStatusViaSetRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Inside Elysia route handlers, set HTTP status via `set.status = N`, not by returning a `new Response(body, { status: N })`.",
+    },
+    schema: [],
+    messages: {
+      useSetStatus:
+        "Do not return `new Response(body, { status })` from an Elysia route handler — assign `set.status = N` and return the body directly.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let elysiaVars = new Set<string>();
+
+    return {
+      Program(program) {
+        elysiaVars = collectElysiaVariables(program);
+      },
+      ReturnStatement(node) {
+        if (node.argument?.type !== AST_NODE_TYPES.NewExpression) {
+          return;
+        }
+
+        const newExpr = node.argument;
+
+        if (
+          newExpr.callee.type !== AST_NODE_TYPES.Identifier ||
+          newExpr.callee.name !== "Response"
+        ) {
+          return;
+        }
+
+        const optionsArg = newExpr.arguments[1];
+
+        if (optionsArg?.type !== AST_NODE_TYPES.ObjectExpression) {
+          return;
+        }
+
+        if (!findObjectProperty(optionsArg, "status")) {
+          return;
+        }
+
+        if (!findEnclosingRouteHandler(node, elysiaVars)) {
+          return;
+        }
+
+        context.report({ node: newExpr, messageId: "useSetStatus" });
+      },
+    };
+  },
+});