Craze-Data-check/AGENTS.md

AGENTS.md - Developer Guidelines for Craze-Data-check

Build, Lint, and Test Commands

Development

npm run dev              # Start dev server on port 3000
npm run build            # Production build
npm run preview          # Preview production build
npm run clean            # Remove dist folder

Linting & Type Checking

npm run lint             # TypeScript type check only (tsc --noEmit)

Note: This project does not have a separate test framework configured. To add tests, consider installing Vitest or Jest.

---

Code Style Guidelines

General Principles

• Use TypeScript for all new code
• Prefer functional components with hooks over class components
• Keep components focused and modular
• Use meaningful variable and function names

Imports

Order (top to bottom):

1. React imports (react)
2. External libraries (lucide-react, xlsx, etc.)
3. Internal components (./components/...)
4. Internal lib/utils (./lib/...)
5. Types (./types)

import React, { useState, useMemo } from 'react';
import { Search, Filter, Edit2 } from 'lucide-react';
import { ExcelRow, COLUMNS } from '../types';
import { cn } from '../lib/utils';

TypeScript Conventions

• Use explicit types for props and function parameters
• Use any sparingly; prefer union types or interfaces
• Define column indices in a centralized COLUMNS object (see src/types.ts)

// Good
interface ProductDescriptionsProps {
  data: ExcelRow[];
  onEdit: (index: number) => void;
}

// Good - centralized constants
export const COLUMNS = {
  ARTICLE_NO: 0,
  ARTICLE_NAME: 2,
  LINE: 7,
};

Naming Conventions

Element	Convention	Example
Components	PascalCase	ProductDescriptions, MatrixView
Functions	camelCase	handleFileUpload, formatCellValue
Variables	camelCase	activeModule, paginatedData
Constants	UPPER_SNAKE_CASE	ARTICLE_NO, MAX_UPLOAD_SIZE
Interfaces	PascalCase	AppState, ExcelRow
Types	PascalCase	TabType, SortDirection

React Patterns

• Destructure props in function signature
• Use useMemo for expensive computations
• Use useCallback for event handlers passed to child components
• Keep useState calls at the top of component

export function ProductDescriptions({ data, onEdit }: ProductDescriptionsProps) {
  const [activeTab, setActiveTab] = useState<TabType>('all');
  const [search, setSearch] = useState('');

  const filteredData = useMemo(() => {
    // expensive computation
  }, [data, activeTab, search]);
}

Error Handling

• Use TypeScript's type system for runtime safety
• Use optional chaining (?.) and nullish coalescing (??)
• Validate file uploads with proper type checks

const file = e.target.files?.[0];
if (!file) return;

// Validate Excel data
if (data.length > 0) {
  const rawHeaders = data[0];
  const rawRows = data.slice(1);
}

UI/Styling

• Use Tailwind CSS for all styling
• Use cn() utility from lib/utils for conditional classes
• Follow existing color scheme (slate, blue, green, red for status)
• Use lucide-react for icons
• Keep responsive design in mind

import { cn } from '../lib/utils';

<button
  className={cn(
    "px-4 py-2 rounded-md text-sm font-medium",
    isActive 
      ? "bg-blue-600 text-white" 
      : "bg-slate-800 text-slate-400"
  )}
>

File Organization

src/
├── components/       # React components
│   ├── Sidebar.tsx
│   ├── MatrixView.tsx
│   └── ...
├── lib/             # Utilities and helpers
│   ├── utils.ts     # cn(), helpers
│   ├── auth.ts      # Authentication
│   └── supabase.ts  # Database operations
├── services/        # External API integrations
│   ├── gemini.ts
│   └── anthropic.ts
├── types.ts         # TypeScript types and constants
├── App.tsx          # Main application
└── main.tsx         # Entry point

Data Processing

• When processing Excel data, handle both string and number types
• Use centralized column index constants
• Format numbers consistently (2 decimal places for prices/weights)
• Handle Excel date serial numbers properly (convert to readable dates)

// Handle date columns from Excel
if (header.includes('date') || header.includes('launch')) {
  if (typeof val === 'number' && val >= 25569 && val <= 60000) {
    const excelEpoch = new Date(1899, 11, 30);
    const date = new Date(excelEpoch.getTime() + val * 86400000);
    return date.toLocaleDateString('en-GB');
  }
}

Git Workflow

• Make small, focused commits
• Write clear commit messages describing what changed
• Push to main to trigger Vercel deployment automatically

Running Single Components

When testing or developing specific features:

npm run dev    # Start dev server - access at http://localhost:3000

Environment Variables

• Use .env file for local development
• Never commit secrets - use Vercel dashboard for production env vars

Required environment variables (production):

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• VITE_GEMINI_API_KEY
• VITE_ANTHROPIC_API_KEY