@levironexe/architect 0.1.0

package/skills/patterns/drizzle.skill.yaml

@@ -0,0 +1,277 @@
+schema_version: "2.0.0"
+id: drizzle
+name: "Drizzle ORM"
+version: "2.0.0"
+description: "SQL-first Drizzle ORM with TypeScript schema as source of truth, drizzle-kit migrations, singleton database connection, inferred types, and explicit query building."
+category: pattern
+language: javascript
+frameworks:
+  - drizzle-orm
+dependencies:
+  none:
+    - prisma
+    - "@prisma/client"
+    - mongoose
+detection:
+  dependencies:
+    any:
+      - drizzle-orm
+  source_indicators:
+    - "drizzle("
+    - "pgTable("
+    - "mysqlTable("
+    - "sqliteTable("
+    - "from 'drizzle-orm'"
+structure:
+  required_dirs:
+    - path: src/db
+      purpose: "Drizzle schema definitions in schema.ts — the single source of truth for all table structures and TypeScript types. Every table, column, index, and relation is defined here as TypeScript. The generated types (via `typeof users.$inferSelect`) come from these definitions — never from separate type files."
+    - path: drizzle
+      purpose: "Generated migration SQL files created by `npx drizzle-kit generate`. These files represent the canonical migration history. Never edit them manually — drizzle-kit detects checksum changes and may regenerate or fail on the next run."
+  recommended_dirs:
+    - path: src/lib
+      purpose: "Drizzle database connection singleton in db.ts — the only place that creates the database connection and passes it to drizzle(). Imported by all repository files. Prevents multiple connections in serverless environments with the same global caching pattern as Prisma."
+    - path: src/db/queries
+      purpose: "Reusable query functions organized by resource — e.g. queries/users.ts, queries/posts.ts. Functions use Drizzle's query builder API and return typed results. Services and API routes call these functions rather than building queries inline."
+separation:
+  rules:
+    - concern: schema_definition
+      belongs_in: src/db
+      rule_text: "Define all table schemas in src/db/schema.ts using Drizzle's TypeScript API. Export the table objects so that drizzle-kit can discover them for migration generation. Use `typeof table.$inferSelect` and `typeof table.$inferInsert` for type inference — never manually write type interfaces for database rows."
+      example: |
+        // src/db/schema.ts — single source of truth
+        import { pgTable, text, timestamp, uuid, boolean } from 'drizzle-orm/pg-core';
+
+        export const users = pgTable('users', {
+          id: uuid('id').primaryKey().defaultRandom(),
+          email: text('email').notNull().unique(),
+          name: text('name'),
+          emailVerified: boolean('email_verified').notNull().default(false),
+          createdAt: timestamp('created_at').defaultNow().notNull(),
+          updatedAt: timestamp('updated_at').defaultNow().notNull(),
+        });
+
+        export const posts = pgTable('posts', {
+          id: uuid('id').primaryKey().defaultRandom(),
+          title: text('title').notNull(),
+          content: text('content'),
+          userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+          publishedAt: timestamp('published_at'),
+          createdAt: timestamp('created_at').defaultNow().notNull(),
+        });
+
+        // Inferred types — never write these manually
+        export type User = typeof users.$inferSelect;
+        export type NewUser = typeof users.$inferInsert;
+        export type Post = typeof posts.$inferSelect;
+        export type NewPost = typeof posts.$inferInsert;
+      indicators:
+        - "pgTable("
+        - "mysqlTable("
+        - "sqliteTable("
+        - "$inferSelect"
+        - "$inferInsert"
+    - concern: database_connection
+      belongs_in: src/lib
+      rule_text: "Create the Drizzle database connection in src/lib/db.ts using a module-level or global singleton. Pass the underlying driver instance (e.g., postgres from 'postgres' or Pool from 'pg') to drizzle(). Never create a new connection per query or per request."
+      example: |
+        // src/lib/db.ts — singleton pattern for serverless compatibility
+        import { drizzle } from 'drizzle-orm/postgres-js';
+        import postgres from 'postgres';
+        import * as schema from '@/db/schema';
+
+        // Singleton: reuse connection across hot reloads in development
+        const globalForDb = globalThis as unknown as {
+          connection: ReturnType<typeof postgres> | undefined;
+        };
+
+        const connection =
+          globalForDb.connection ??
+          postgres(process.env.DATABASE_URL!, {
+            max: process.env.NODE_ENV === 'production' ? 10 : 1,
+          });
+
+        if (process.env.NODE_ENV !== 'production') globalForDb.connection = connection;
+
+        export const db = drizzle(connection, { schema });
+      indicators:
+        - "drizzle("
+        - "DATABASE_URL"
+        - "from 'drizzle-orm"
+    - concern: migrations
+      belongs_in: drizzle
+      rule_text: "Use drizzle-kit to generate and apply migrations. Configure drizzle.config.ts with the schema path and migration output directory. Run `npx drizzle-kit generate` to create migration SQL from schema changes, and `npx drizzle-kit migrate` (or `push` for prototyping) to apply them."
+      example: |
+        // drizzle.config.ts — tells drizzle-kit where to find schema and write migrations
+        import { defineConfig } from 'drizzle-kit';
+        export default defineConfig({
+          schema: './src/db/schema.ts',
+          out: './drizzle',
+          dialect: 'postgresql',
+          dbCredentials: { url: process.env.DATABASE_URL! },
+        });
+
+        # Development workflow:
+        # 1. Edit src/db/schema.ts
+        # 2. Generate migration:
+        npx drizzle-kit generate
+        # 3. Apply migration:
+        npx drizzle-kit migrate
+        # 4. The db object's types update automatically (schema is the source)
+      indicators:
+        - "drizzle-kit generate"
+        - "drizzle-kit migrate"
+        - "drizzle.config.ts"
+        - "defineConfig("
+    - concern: query_building
+      belongs_in: src/db/queries
+      rule_text: "Use Drizzle's query builder API for all queries. For complex SQL, use the `sql` template tag with parameterized values — never string concatenation. Queries live in src/db/queries/ functions; services call these functions rather than building queries inline."
+      example: |
+        // src/db/queries/users.ts
+        import { db } from '@/lib/db';
+        import { users, posts } from '@/db/schema';
+        import { eq, and, desc, ilike, sql } from 'drizzle-orm';
+
+        export async function findUserByEmail(email: string) {
+          return db.query.users.findFirst({
+            where: eq(users.email, email),
+          });
+        }
+
+        export async function listUsersWithPostCount(limit = 20) {
+          return db
+            .select({
+              id: users.id,
+              email: users.email,
+              name: users.name,
+              postCount: sql<number>`count(${posts.id})`.mapWith(Number),
+            })
+            .from(users)
+            .leftJoin(posts, eq(posts.userId, users.id))
+            .groupBy(users.id)
+            .orderBy(desc(users.createdAt))
+            .limit(limit);
+        }
+      anti_indicators:
+        - "db.execute(`SELECT"
+        - "db.execute(\"SELECT"
+        - "+ email +"
+    - concern: transactions
+      belongs_in: src/db/queries
+      rule_text: "Use db.transaction() for operations that must succeed or fail atomically. The transaction callback receives a `tx` context — use `tx` instead of `db` for all queries inside the transaction."
+      example: |
+        // src/db/queries/orders.ts
+        import { db } from '@/lib/db';
+        import { orders, inventory } from '@/db/schema';
+        import { eq, sql } from 'drizzle-orm';
+
+        export async function createOrderWithInventoryDecrement(
+          userId: string,
+          productId: string,
+          quantity: number,
+          price: number
+        ) {
+          return db.transaction(async (tx) => {
+            // Atomically decrement inventory
+            const [product] = await tx
+              .update(inventory)
+              .set({ stock: sql`${inventory.stock} - ${quantity}` })
+              .where(and(eq(inventory.productId, productId), sql`${inventory.stock} >= ${quantity}`))
+              .returning();
+
+            if (!product) throw new Error('Insufficient stock');
+
+            return tx.insert(orders).values({ userId, productId, quantity, total: price * quantity }).returning();
+          });
+        }
+      indicators:
+        - "db.transaction("
+        - "tx.insert("
+        - "tx.update("
+patterns:
+  data_flow:
+    direction: "API Route/Server Action → Service → Query Function (src/db/queries/) → Drizzle → Database"
+    rules:
+      - "src/db/schema.ts is the source of truth — TypeScript types are inferred from it, never written manually."
+      - "db in src/lib/db.ts is the only Drizzle instance — imported by all query files."
+      - "Query functions in src/db/queries/ own all SQL — services call these functions, never db.select() directly."
+      - "Migrations are generated by drizzle-kit from schema changes — never write migration SQL manually."
+      - "Use $inferSelect and $inferInsert for parameter and return types — keeps types in sync with schema automatically."
+  error_handling:
+    recommended: "Drizzle does not wrap errors — database errors bubble as driver-level errors. Check error.code: '23505' = PostgreSQL unique violation, '23503' = foreign key violation. Wrap in try/catch in repositories."
+  naming:
+    schema: "src/db/schema.ts — all pgTable/mysqlTable definitions with $inferSelect/$inferInsert exports"
+    connection: "src/lib/db.ts — drizzle(connection, { schema }) singleton"
+    queries: "src/db/queries/[resource].ts — e.g. users.ts, posts.ts"
+    config: "drizzle.config.ts — drizzle-kit configuration at project root"
+anti_patterns:
+  - id: raw_sql_strings
+    severity: warning
+    description: "Building SQL queries with string concatenation or unparameterized template literals. Even with Drizzle available, some developers fall back to raw strings when queries get complex. This loses type safety and creates SQL injection risk."
+    bad_example: |
+      // ❌ String concatenation — SQL injection risk, no type safety
+      const email = req.body.email;
+      await db.execute(`SELECT * FROM users WHERE email = '${email}'`);
+      // If email = "' OR '1'='1" → returns all users
+    good_example: |
+      // ✓ Drizzle query builder — parameterized and type-safe
+      import { eq } from 'drizzle-orm';
+      const user = await db.select().from(users).where(eq(users.email, email));
+
+      // ✓ For complex SQL: use sql tag with parameters (not string concat)
+      import { sql } from 'drizzle-orm';
+      const result = await db.execute(sql`SELECT * FROM users WHERE email = ${email}`);
+  - id: multiple_db_connections
+    severity: critical
+    description: "Creating a new Drizzle instance (and underlying driver connection/pool) in multiple files instead of importing from src/lib/db.ts. In serverless environments, each function invocation may create a new connection pool, exhausting database connections under load."
+    bad_example: |
+      // ❌ New drizzle instance in every repository file
+      // src/db/queries/users.ts
+      import postgres from 'postgres';
+      import { drizzle } from 'drizzle-orm/postgres-js';
+      const db = drizzle(postgres(process.env.DATABASE_URL!)); // new connection pool
+
+      // src/db/queries/posts.ts
+      const db = drizzle(postgres(process.env.DATABASE_URL!)); // another pool
+    good_example: |
+      // ✓ Import the singleton from src/lib/db.ts everywhere
+      import { db } from '@/lib/db';
+      const users = await db.select().from(usersTable).where(eq(usersTable.id, id));
+  - id: schema_outside_db_dir
+    severity: warning
+    description: "Defining table schemas outside src/db/schema.ts. drizzle-kit looks for schemas in the path configured in drizzle.config.ts — schemas defined elsewhere are invisible to the migration tool and won't generate migrations."
+    bad_example: |
+      // ❌ Schema scattered in model files — drizzle-kit can't find it
+      // src/models/user.model.ts
+      export const users = pgTable('users', { id: text('id') });
+      // drizzle-kit generate → no migration generated for this table
+    good_example: |
+      // ✓ All schemas in src/db/schema.ts — drizzle-kit finds them all
+      // drizzle.config.ts: schema: './src/db/schema.ts'
+      export const users = pgTable('users', { id: uuid('id').primaryKey() });
+  - id: manual_type_interfaces
+    severity: warning
+    description: "Writing TypeScript interfaces for database row types by hand instead of using `typeof table.$inferSelect`. When the schema changes, the manual interface goes stale — the database returns columns the interface doesn't know about, or the interface references columns that no longer exist."
+    bad_example: |
+      // ❌ Manual type — gets out of sync when schema changes
+      interface User {
+        id: string;
+        email: string;
+        name: string; // What if 'name' is renamed to 'fullName' in the schema?
+      }
+    good_example: |
+      // ✓ Inferred type — always in sync with schema.ts
+      import { users } from '@/db/schema';
+      export type User = typeof users.$inferSelect;
+      export type NewUser = typeof users.$inferInsert;
+  - id: push_in_production
+    severity: critical
+    description: "Using `npx drizzle-kit push` in production environments. `push` modifies the database directly without creating a migration file — there is no migration history, no rollback path, and no CI/CD audit trail. Use `push` only for local prototyping; use `migrate` in all deployed environments."
+    bad_example: |
+      # ❌ In production CI/CD pipeline — no migration history
+      npx drizzle-kit push
+      # Database changed but no migration file created — next deploy may push again
+    good_example: |
+      # ✓ Production: apply versioned migrations from the drizzle/ directory
+      npx drizzle-kit migrate
+      # Each migration is a timestamped SQL file with a checksum — safe to replay

package/skills/patterns/mongoose.skill.yaml

@@ -0,0 +1,290 @@
+schema_version: "2.0.0"
+id: mongoose
+name: "Mongoose"
+version: "2.0.0"
+description: "Mongoose ODM for MongoDB with typed schemas, single connection, model-layer queries with .lean(), and index-backed query performance."
+category: pattern
+language: javascript
+frameworks:
+  - mongoose
+dependencies:
+  none:
+    - prisma
+    - drizzle-orm
+    - "@prisma/client"
+detection:
+  dependencies:
+    any:
+      - mongoose
+  source_indicators:
+    - "mongoose.connect("
+    - "new Schema("
+    - "model("
+    - "mongoose.model("
+    - "from 'mongoose'"
+structure:
+  required_dirs:
+    - path: src/models
+      purpose: "Mongoose schema and model definitions — one file per collection (e.g., user.model.ts, post.model.ts). Each file exports the Mongoose model and the TypeScript interface that describes the document shape. Models are the only layer that calls mongoose.model() and defines Schema instances."
+    - path: src/lib
+      purpose: "Database connection singleton in db.ts — the only place that calls mongoose.connect(). This module is imported once (in the app entry point or Next.js instrumentation) and handles reconnect logic. Never call mongoose.connect() in route handlers or models."
+  recommended_dirs:
+    - path: src/repositories
+      purpose: "Data access layer — one file per model (e.g., user.repository.ts) containing all queries for that collection. Repository functions call Model.find(), Model.findById(), etc. and return typed lean documents. Services call repositories — never the Mongoose Model directly."
+    - path: src/types
+      purpose: "Shared TypeScript interfaces for document types (HydratedDocument<User>, lean User). Keeps model files focused on schema definition and separates type definitions for reuse across layers."
+separation:
+  rules:
+    - concern: schema_definition
+      belongs_in: src/models
+      rule_text: "Define all Mongoose schemas in src/models/ with explicit types matching the TypeScript interface. Always include { timestamps: true } in schema options — Mongoose then manages createdAt and updatedAt automatically. Add index: true or unique: true to fields you query frequently."
+      example: |
+        // src/models/user.model.ts
+        import { Schema, model, type Document } from 'mongoose';
+
+        export interface IUser {
+          email: string;
+          name: string;
+          role: 'user' | 'admin';
+          profileId?: string;
+          createdAt: Date; // added by { timestamps: true }
+          updatedAt: Date;
+        }
+
+        const userSchema = new Schema<IUser>(
+          {
+            email: { type: String, required: true, unique: true, lowercase: true, trim: true },
+            name:  { type: String, required: true, trim: true },
+            role:  { type: String, enum: ['user', 'admin'], default: 'user' },
+            profileId: { type: String, index: true }, // indexed for fast lookup
+          },
+          {
+            timestamps: true, // auto-manages createdAt and updatedAt
+            toJSON: { virtuals: true }, // include virtuals in JSON output
+          }
+        );
+
+        export const User = model<IUser>('User', userSchema);
+      indicators:
+        - "new Schema("
+        - "mongoose.model("
+        - "model<I"
+        - "timestamps: true"
+    - concern: single_connection
+      belongs_in: src/lib
+      rule_text: "Call mongoose.connect() exactly once in src/lib/db.ts using the cached connection pattern. In Next.js, the connection is shared across hot reloads — without caching the connection promise, each module reload creates a new connection to MongoDB until the pool limit is hit."
+      example: |
+        // src/lib/db.ts
+        import mongoose from 'mongoose';
+
+        declare global {
+          // eslint-disable-next-line no-var
+          var mongoose: { conn: typeof import('mongoose') | null; promise: Promise<typeof import('mongoose')> | null };
+        }
+
+        let cached = global.mongoose ?? { conn: null, promise: null };
+        if (!global.mongoose) global.mongoose = cached;
+
+        export async function connectDB() {
+          if (cached.conn) return cached.conn;
+          if (!cached.promise) {
+            cached.promise = mongoose.connect(process.env.MONGODB_URI!, {
+              bufferCommands: false,
+              maxPoolSize: process.env.NODE_ENV === 'production' ? 10 : 2,
+            });
+          }
+          cached.conn = await cached.promise;
+          return cached.conn;
+        }
+      anti_indicators:
+        - "mongoose.connect("
+    - concern: query_performance
+      belongs_in: src/repositories
+      rule_text: "Use .lean() on read queries that don't need Mongoose document methods (.save(), virtuals, middleware). lean() returns plain JavaScript objects instead of full Mongoose documents — 2-10x faster for large result sets. Use .select() to limit returned fields and .limit() to cap result size."
+      example: |
+        // src/repositories/user.repository.ts
+        import { connectDB } from '@/lib/db';
+        import { User, type IUser } from '@/models/user.model';
+
+        // lean() + select(): fast, minimal-payload read
+        export async function listUsers(limit = 50): Promise<Partial<IUser>[]> {
+          await connectDB();
+          return User.find({ role: 'user' })
+            .select('email name createdAt') // only the fields callers need
+            .sort({ createdAt: -1 })
+            .limit(limit)
+            .lean(); // plain objects — no Mongoose overhead
+        }
+
+        // No .lean() when mutation is needed (need .save())
+        export async function findUserById(id: string) {
+          await connectDB();
+          return User.findById(id); // returns HydratedDocument<IUser>
+        }
+      indicators:
+        - ".lean()"
+        - ".find({"
+        - ".sort("
+        - ".select("
+        - ".limit("
+    - concern: population
+      belongs_in: src/repositories
+      rule_text: "Use .populate() to fetch referenced documents in a single aggregated query instead of manually fetching references in a loop. Pre-populate only the fields the caller needs using the second argument or select option."
+      example: |
+        // src/repositories/post.repository.ts
+        export async function listPostsWithAuthors(limit = 20) {
+          await connectDB();
+          return Post.find({ publishedAt: { $ne: null } })
+            .populate<{ author: IUser }>('author', 'name email') // only name + email from User
+            .sort({ publishedAt: -1 })
+            .limit(limit)
+            .lean();
+        }
+      indicators:
+        - ".populate("
+    - concern: transactions
+      belongs_in: src/repositories
+      rule_text: "Use Mongoose sessions and transactions for operations that span multiple collections and must be atomic. Requires a MongoDB replica set (available on Atlas M10+ or local replica set). Pass the session to every operation that participates in the transaction."
+      example: |
+        // src/repositories/transfer.repository.ts
+        import mongoose from 'mongoose';
+        import { Account } from '@/models/account.model';
+        import { Transaction } from '@/models/transaction.model';
+
+        export async function transferFunds(fromId: string, toId: string, amount: number) {
+          const session = await mongoose.startSession();
+          session.startTransaction();
+          try {
+            await Account.findByIdAndUpdate(fromId, { $inc: { balance: -amount } }, { session });
+            await Account.findByIdAndUpdate(toId, { $inc: { balance: amount } }, { session });
+            await Transaction.create([{ fromId, toId, amount }], { session });
+            await session.commitTransaction();
+          } catch (err) {
+            await session.abortTransaction();
+            throw err;
+          } finally {
+            session.endSession();
+          }
+        }
+      indicators:
+        - "mongoose.startSession"
+        - "startTransaction"
+        - "commitTransaction"
+        - "abortTransaction"
+patterns:
+  data_flow:
+    direction: "API Route/Server Action → Service → Repository → Mongoose Model → MongoDB"
+    rules:
+      - "src/lib/db.ts connectDB() is called before every repository operation — safely no-ops if already connected."
+      - "Repositories return plain JavaScript objects (via .lean()) or HydratedDocument only when mutation is needed."
+      - "Services call repository functions — never import Mongoose Models directly."
+      - "Use .populate() for relations — never loop with findById() to fetch referenced documents."
+      - "All queries on frequently-filtered fields have matching index: true in the schema."
+  error_handling:
+    recommended: "Mongoose validation errors are instanceof mongoose.Error.ValidationError — catch separately from MongoDB driver errors. For duplicate key errors, check err.code === 11000 (MongoDB duplicate key)."
+  naming:
+    models: "src/models/[resource].model.ts — e.g. user.model.ts exports User model + IUser interface"
+    connection: "src/lib/db.ts — exports connectDB() using cached connection pattern"
+    repositories: "src/repositories/[resource].repository.ts — e.g. user.repository.ts"
+anti_patterns:
+  - id: multiple_connections
+    severity: critical
+    description: "Calling mongoose.connect() in individual model files, route handlers, or repository functions. In serverless environments, each function invocation recreates the connection — MongoDB Atlas free-tier clusters hit connection limits instantly."
+    bad_example: |
+      // ❌ mongoose.connect() in a route handler — new connection per request
+      export async function GET() {
+        await mongoose.connect(process.env.MONGODB_URI!); // new connection every request!
+        const users = await User.find().lean();
+        return Response.json(users);
+      }
+    good_example: |
+      // ✓ Call connectDB() which uses the cached singleton
+      import { connectDB } from '@/lib/db';
+      export async function GET() {
+        await connectDB(); // no-op if already connected
+        const users = await User.find().lean();
+        return Response.json(users);
+      }
+  - id: schema_in_route
+    severity: critical
+    description: "Defining Mongoose schemas inside route handlers or service functions — the schema and model are recreated on every call. In Next.js, this also triggers a `Cannot overwrite model once compiled` error after HMR because the model name is already registered."
+    bad_example: |
+      // ❌ Schema defined inside a route handler — recreated every call
+      export async function GET() {
+        const UserSchema = new Schema({ email: String }); // recreated every request
+        const User = model('User', UserSchema); // throws on second call: model already registered
+        return Response.json(await User.find());
+      }
+    good_example: |
+      // ✓ Schema defined once in src/models/user.model.ts
+      // import the model from there in all route handlers and repositories
+      import { User } from '@/models/user.model';
+  - id: populate_n_plus_one
+    severity: warning
+    description: "Fetching documents with references and then manually looping to fetch each referenced document. This creates N+1 database round trips — one query for the list, then one per document for its reference."
+    bad_example: |
+      // ❌ N+1: 1 query for posts + 1 query per post for its author
+      const posts = await Post.find({ publishedAt: { $ne: null } }).lean();
+      for (const post of posts) {
+        post.author = await User.findById(post.authorId).lean(); // N separate queries
+      }
+    good_example: |
+      // ✓ Single aggregated query via populate
+      const posts = await Post.find({ publishedAt: { $ne: null } })
+        .populate('author', 'name email') // single JOIN-like query
+        .lean();
+  - id: missing_schema_index
+    severity: warning
+    description: "Querying a field frequently without adding index: true (or a compound index) to the schema. Without an index, MongoDB scans every document in the collection on each query — O(n) queries that degrade linearly as data grows."
+    bad_example: |
+      // ❌ userId queried often but no index — full collection scan on every query
+      const userSchema = new Schema({
+        email: String,
+        userId: String, // frequently queried but not indexed
+      }, { timestamps: true });
+
+      // In repository:
+      User.find({ userId }) // COLLSCAN on 1M documents = slow
+    good_example: |
+      // ✓ Add index to frequently-queried fields
+      const userSchema = new Schema({
+        email: { type: String, unique: true }, // unique implies index
+        userId: { type: String, index: true }, // explicit index for fast lookup
+      }, { timestamps: true });
+  - id: schema_without_timestamps
+    severity: warning
+    description: "Defining schemas without `{ timestamps: true }` and manually managing createdAt/updatedAt fields. Manual timestamp management is error-prone — it's easy to forget to update updatedAt on every modification."
+    bad_example: |
+      // ❌ Manual timestamps — easy to forget updatedAt on updates
+      const postSchema = new Schema({
+        title: String,
+        content: String,
+        createdAt: { type: Date, default: Date.now }, // missing from updates
+        updatedAt: Date, // must manually set on every save
+      });
+    good_example: |
+      // ✓ Mongoose manages both createdAt and updatedAt automatically
+      const postSchema = new Schema(
+        {
+          title: { type: String, required: true },
+          content: String,
+        },
+        { timestamps: true } // auto-sets createdAt and updatedAt
+      );
+  - id: excessive_lean
+    severity: warning
+    description: "Using .lean() on queries where you then call Mongoose document methods (.save(), .validate(), middleware hooks). .lean() returns plain JavaScript objects — calling .save() on them throws at runtime."
+    bad_example: |
+      // ❌ .lean() then .save() — TypeError at runtime
+      const user = await User.findById(id).lean(); // plain object, not a Mongoose doc
+      user.name = 'New Name';
+      await user.save(); // TypeError: user.save is not a function
+    good_example: |
+      // ✓ Skip .lean() when you need to mutate and save
+      const user = await User.findById(id); // HydratedDocument<IUser>
+      if (!user) throw new Error('User not found');
+      user.name = 'New Name';
+      await user.save(); // works — Mongoose document method
+
+      // ✓ Or use findByIdAndUpdate for simpler mutations
+      await User.findByIdAndUpdate(id, { name: 'New Name' }, { new: true });