@smicolon/ai-kit 0.1.0 → 0.2.0

package/packs/nextjs/skills/import-convention-enforcer/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: nextjs-import-enforcer
+description: Automatically enforce consistent import patterns using Next.js path aliases and proper organization. Use when writing imports, creating new files, or organizing code structure.
+---
+
+# Import Convention Enforcer (Next.js/React)
+
+Auto-enforces consistent import patterns using Next.js path aliases for clean, maintainable code.
+
+## Activation Triggers
+
+This skill activates when:
+- Writing or modifying TypeScript/JavaScript files
+- Creating new components, hooks, utilities
+- Importing from other files
+- Organizing project structure
+- Mentioning "import", "add", "create"
+
+## Required Import Pattern (MANDATORY)
+
+Use path aliases for internal imports:
+
+```tsx
+// ✅ CORRECT - Path aliases
+import { Button } from '@/components/ui'
+import { useAuth } from '@/hooks'
+import { formatDate } from '@/lib/utils'
+import { User } from '@/types'
+
+// ❌ WRONG - Relative paths
+import { Button } from '../../components/ui/Button'
+import { useAuth } from '../../../hooks/useAuth'
+```
+
+## Path Alias Configuration
+
+**tsconfig.json:**
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@/components/*": ["./src/components/*"],
+      "@/lib/*": ["./src/lib/*"],
+      "@/hooks/*": ["./src/hooks/*"],
+      "@/types/*": ["./src/types/*"],
+      "@/app/*": ["./src/app/*"]
+    }
+  }
+}
+```
+
+## Auto-Fix Process
+
+### Step 1: Detect Relative Imports
+
+```tsx
+// ❌ User writes
+import { Button } from '../../../components/ui/Button'
+import { Card } from '../../components/ui/Card'
+import { useUser } from '../hooks/useUser'
+```
+
+### Step 2: Convert to Path Aliases
+
+```tsx
+// ✅ Auto-fixed to
+import { Button } from '@/components/ui'
+import { Card } from '@/components/ui'
+import { useUser } from '@/hooks'
+```
+
+### Step 3: Organize Imports
+
+```tsx
+// ✅ Final organized imports
+// 1. React/Next.js
+import { useState } from 'react'
+import Link from 'next/link'
+
+// 2. Third-party libraries
+import { z } from 'zod'
+import { useForm } from 'react-hook-form'
+
+// 3. Internal - path aliases
+import { Button, Card } from '@/components/ui'
+import { useUser } from '@/hooks'
+import { formatDate } from '@/lib/utils'
+import type { User } from '@/types'
+```
+
+## Import Organization Rules
+
+### 1. Import Order (Top to Bottom)
+
+```tsx
+// 1. React/Next.js core
+import { useState, useEffect } from 'react'
+import Image from 'next/image'
+import Link from 'next/link'
+
+// 2. Third-party libraries
+import { z } from 'zod'
+import clsx from 'clsx'
+
+// 3. Internal modules (using @/ aliases)
+import { Button } from '@/components/ui'
+import { useAuth } from '@/hooks'
+import { api } from '@/lib/api'
+
+// 4. Types (separate or with type keyword)
+import type { User, Post } from '@/types'
+
+// 5. Styles (if needed)
+import styles from './Component.module.css'
+```
+
+### 2. Named Imports (Alphabetical)
+
+```tsx
+// ✅ CORRECT - Alphabetical
+import { Button, Card, Dialog, Input } from '@/components/ui'
+
+// ❌ WRONG - Random order
+import { Dialog, Input, Button, Card } from '@/components/ui'
+```
+
+### 3. Type-Only Imports
+
+```tsx
+// ✅ CORRECT - Explicit type imports
+import type { User } from '@/types'
+import type { ButtonProps } from '@/components/ui'
+
+// ✅ CORRECT - Inline type keyword
+import { type User, type Post } from '@/types'
+```
+
+## Path Alias Patterns by Directory
+
+### Components
+
+```tsx
+// UI components
+import { Button, Card, Input } from '@/components/ui'
+
+// Feature components
+import { UserProfile } from '@/components/features'
+
+// Layout components
+import { Header, Footer } from '@/components/layout'
+```
+
+### Hooks
+
+```tsx
+// Custom hooks
+import { useAuth, useUser, useLocalStorage } from '@/hooks'
+
+// Or specific hook files
+import { useAuth } from '@/hooks/useAuth'
+```
+
+### Utilities/Lib
+
+```tsx
+// Utilities
+import { cn, formatDate, truncate } from '@/lib/utils'
+
+// API client
+import { api } from '@/lib/api'
+
+// Constants
+import { ROUTES, API_URL } from '@/lib/constants'
+```
+
+### Types
+
+```tsx
+// All types from types directory
+import type { User, Post, Comment } from '@/types'
+
+// Or specific type files
+import type { ApiResponse } from '@/types/api'
+```
+
+### App Router (Next.js 13+)
+
+```tsx
+// Route components/utilities
+import { generateMetadata } from '@/app/utils'
+import { PageProps } from '@/app/types'
+```
+
+## Barrel Exports (index.ts)
+
+Encourage barrel exports for cleaner imports:
+
+```tsx
+// components/ui/index.ts
+export { Button } from './Button'
+export { Card } from './Card'
+export { Input } from './Input'
+export { Dialog } from './Dialog'
+
+// Usage - clean!
+import { Button, Card, Input } from '@/components/ui'
+```
+
+## Dynamic Imports
+
+```tsx
+// ✅ CORRECT - Dynamic import with path alias
+const Chart = dynamic(() => import('@/components/Chart'), {
+  loading: () => <Skeleton />,
+  ssr: false,
+})
+
+// ❌ WRONG - Relative path
+const Chart = dynamic(() => import('../../components/Chart'))
+```
+
+## Server/Client Component Imports
+
+```tsx
+// Server Component
+import { db } from '@/lib/database'  // Server-only
+import { ServerComponent } from '@/components/server'
+
+// Client Component
+'use client'
+import { useState } from 'react'
+import { Button } from '@/components/ui'  // Client component
+```
+
+## CSS/Style Imports
+
+```tsx
+// ✅ CORRECT - At the end
+import { Button } from '@/components/ui'
+import styles from './Component.module.css'
+
+// ✅ CORRECT - Global styles in _app or layout
+import '@/styles/globals.css'
+```
+
+## Image Imports
+
+```tsx
+// ✅ CORRECT - Next.js Image with path alias
+import Image from 'next/image'
+import logo from '@/public/logo.png'
+
+// ✅ CORRECT - Public path
+<Image src="/logo.png" alt="Logo" width={200} height={50} />
+```
+
+## Common Violations
+
+### Violation 1: Deep Relative Paths
+
+```tsx
+// ❌ WRONG
+import { Button } from '../../../components/ui/Button'
+
+// ✅ CORRECT
+import { Button } from '@/components/ui'
+```
+
+### Violation 2: Missing Barrel Export
+
+```tsx
+// ❌ WRONG - Importing from specific files
+import { Button } from '@/components/ui/Button'
+import { Card } from '@/components/ui/Card'
+
+// ✅ CORRECT - Import from barrel
+import { Button, Card } from '@/components/ui'
+```
+
+### Violation 3: Mixing Import Styles
+
+```tsx
+// ❌ WRONG - Inconsistent
+import { Button } from '@/components/ui'
+import { useAuth } from '../../hooks/useAuth'  // Relative!
+
+// ✅ CORRECT - All use aliases
+import { Button } from '@/components/ui'
+import { useAuth } from '@/hooks'
+```
+
+### Violation 4: Type Import Without Keyword
+
+```tsx
+// ❌ WRONG - Importing type as value
+import { User } from '@/types'  // Adds to bundle
+
+// ✅ CORRECT - Explicit type import
+import type { User } from '@/types'  // No runtime cost
+```
+
+## Project Structure Best Practices
+
+```
+src/
+├── app/                    # Next.js App Router
+│   ├── (auth)/
+│   ├── (dashboard)/
+│   └── api/
+├── components/
+│   ├── ui/                # Shadcn components
+│   │   ├── button.tsx
+│   │   ├── card.tsx
+│   │   └── index.ts       # Barrel export
+│   ├── features/          # Feature components
+│   └── layout/            # Layout components
+├── hooks/
+│   ├── useAuth.ts
+│   ├── useUser.ts
+│   └── index.ts           # Barrel export
+├── lib/
+│   ├── api.ts
+│   ├── utils.ts
+│   └── constants.ts
+├── types/
+│   ├── api.ts
+│   ├── models.ts
+│   └── index.ts           # Barrel export
+└── styles/
+    └── globals.css
+```
+
+## ESLint Integration
+
+Suggest ESLint rules:
+
+```json
+{
+  "rules": {
+    "import/order": [
+      "error",
+      {
+        "groups": [
+          "builtin",
+          "external",
+          "internal",
+          "parent",
+          "sibling",
+          "index"
+        ],
+        "pathGroups": [
+          {
+            "pattern": "@/**",
+            "group": "internal",
+            "position": "after"
+          }
+        ],
+        "alphabetize": {
+          "order": "asc"
+        }
+      }
+    ],
+    "import/no-relative-packages": "error"
+  }
+}
+```
+
+## Success Criteria
+
+✅ ALL internal imports use path aliases
+✅ NO deep relative paths (../..)
+✅ Barrel exports for component directories
+✅ Imports organized by category
+✅ Type imports use `type` keyword
+✅ Consistent import style across project
+
+## Behavior
+
+**Proactive enforcement:**
+- Detect relative imports automatically
+- Convert to path aliases immediately
+- Organize import order
+- Suggest barrel exports
+- Explain import patterns
+
+**Never:**
+- Require explicit "fix imports" request
+- Allow deep relative paths
+- Wait for linter errors
+
+**Always:**
+- Use `@/` path aliases
+- Organize imports by category
+- Add barrel exports where beneficial
+- Add type keyword for type imports
+
+This ensures clean, maintainable import structure from day one.