.cursorrules (deprecated)

1# Rules
2 
3## 1. Material UI Imports (CRITICAL - 500KB+ Bundle Impact)
4 
5⚠️ Pre-push hook will REJECT incorrect imports
6 
7### ✅ CORRECT (Tree-shakeable):
8```typescript
9// Components - one per line
10import Button from '@mui/material/Button';
11import Box from '@mui/material/Box';
12 
13// Icons - one per line
14import SearchIcon from '@mui/icons-material/Search';
15import EditIcon from '@mui/icons-material/Edit';
16 
17// Hooks from /styles
18import { useTheme, styled } from '@mui/material/styles';
19 
20// Types use 'import type'
21import type { PaletteMode } from '@mui/material';
22import type { SvgIconProps } from '@mui/material/SvgIcon';
23```
24 
25### ❌ WRONG (Bloats bundle):
26```typescript
27import { Button, Box } from '@mui/material';           // NO!
28import { Search, Edit } from '@mui/icons-material';    // NO!
29import { PaletteMode } from '@mui/material';           // NO! Use 'import type'
30```
31 
32**Common Components Quick Reference**:
33```typescript
34// Layout: Box, Container, Grid, Stack
35// Inputs: Button, TextField, Select, MenuItem, Checkbox, Switch
36// Feedback: Alert, Dialog, Snackbar, CircularProgress
37// Data: Table, TableBody, TableCell, TableHead, TableRow, Chip, Tooltip
38// Navigation: Tabs, Tab, Drawer
39// Utils: IconButton, Divider, Paper, Typography
40```
41 
42**Validation**: Run `./scripts/check-mui-imports.sh` or `yarn build:analyze`
43 
44## 2. Component File Organization (MANDATORY)
45 
46Every component MUST follow the `index.tsx` pattern:
47 
48```
49ComponentName/
50├── index.tsx              # Main component (REQUIRED)
51├── SubComponent.tsx       # Sub-components in same dir
52├── helpers.ts             # Component-specific utilities
53├── types.ts               # Component-specific types
54└── styles.css             # Component-specific styles
55```
56 
57**Rules**:
58- ✅ Every component dir has `index.tsx` (main entry point)
59- ✅ Sub-components stay in parent directory, named `PascalCase.tsx`
60- ✅ Helper files: `helpers.ts`, `types.ts`, `constants.ts`, `utils.ts`
61- ✅ Shared/reusable → `shared/` or `common/` directory
62- ❌ NO components at root level without directory
63- ❌ NO redundant naming: `MyComponent/MyComponent.tsx` → use `MyComponent/index.tsx`
64 
65**Examples**:
66```
67theme-toggle/
68└── index.tsx
69 
70admin-console/
71├── index.tsx
72├── layout/index.tsx
73├── maps-page/index.tsx
74└── accounts-page/index.tsx
75 
76action-widget/pane/
77├── topic-style-editor/
78│   ├── index.tsx
79│   ├── IconCollection.tsx
80│   └── ColorPicker.tsx
81└── shared/
82    ├── StyledTabs.tsx
83    └── StyledEditorContainer.tsx
84```
85 
86**Clean Imports Result**:
87```typescript
88import ThemeToggle from '../common/theme-toggle';        // ✅ Clean
89import MapsPage from '../admin-console/maps-page';       // ✅ Clean
90// vs
91import ThemeToggle from '../common/theme-toggle/ThemeToggle'; // ❌ Redundant
92```
93 
94## 3. Code Standards
95 
96- **Language**: TypeScript preferred over JavaScript
97- **React**: Functional components + hooks (no class components)
98- **Naming**:
99  - Components: `PascalCase` (`MyComponent.tsx`)
100  - Utilities: `camelCase` (`myUtility.ts`)
101  - Constants: `UPPER_SNAKE_CASE` (`MAX_VALUE`)
102- **Git**:
103  - Clear commit messages
104  - No force push to `main`
105  - Branch names: `feature/name`, `fix/name`
106 
107## 4. Performance
108 
109- Check for duplicate dependencies before adding packages
110- Use dynamic imports for code splitting when appropriate
111- Run `yarn build:analyze` to verify bundle sizes
112 
113## 5. Testing
114 
115- Unit tests: `*.test.ts` or `*.test.tsx`
116- Integration tests: Cypress
117- Aim for good coverage on critical paths
118 
119## 6. TypeScript Type Safety (CRITICAL)
120 
121**MANDATORY**: All TypeScript code must be properly typed. NO exceptions.
122 
123### Prohibited:
124- ❌ **NEVER use `any` type** - Always use specific types
125- ❌ **NEVER use `@ts-ignore` or `@ts-expect-error`** without discussion
126- ❌ **NEVER leave implicit `any`** from function parameters or variables
127 
128### Required Practices:
129 
130#### 1. Import Proper Types:
131```typescript
132// ✅ CORRECT - Import types from mindplot
133import { Topic, Designer } from '@wisemapping/mindplot';
134 
135// ❌ WRONG - Using 'any'
136const topic: any = ...;
137```
138 
139#### 2. Handle Nullable Types Correctly:
140```typescript
141// ✅ CORRECT - Properly handle Topic | null
142const getTopicDepth = (topic: Topic): number => {
143  let current: Topic | null = topic;
144  while (current && current.getParent() !== null) {
145    current = current.getParent();  // Returns Topic | null
146  }
147};
148 
149// ❌ WRONG - Type mismatch
150const getTopicDepth = (topic: Topic): number => {
151  let current = topic;  // TypeScript infers Topic
152  current = current.getParent();  // ERROR: Topic | null not assignable to Topic
153};
154```
155 
156#### 3. Use Unknown for Truly Unknown Types:
157```typescript
158// ✅ If you truly don't know the type
159const data: unknown = JSON.parse(str);
160if (typeof data === 'object' && data !== null) {
161  // Type guard before use
162}
163 
164// ❌ WRONG
165const data: any = JSON.parse(str);
166```
167 
168## 7. Linting and Code Quality (CRITICAL)
169 
170**MANDATORY**: AI MUST check linter errors after EVERY file creation or modification.
171 
172### When to Run Linter (REQUIRED):
173- ✅ **IMMEDIATELY after creating a new file**
174- ✅ **IMMEDIATELY after modifying an existing file**
175- ✅ **Before declaring a task complete**
176- ✅ **After any code generation or refactoring**
177 
178### Linting Workflow (ENFORCED):
179```
180For EACH file created/modified:
1811. Write/modify the code
1822. IMMEDIATELY run read_lints([specific_file_path])
1833. Fix ALL errors found
1844. Re-run read_lints to verify
1855. Only then move to next file
186 
187At task completion:
1881. Run read_lints on ALL modified files together
1892. Fix any remaining issues
1903. Final verification
1914. Task complete
192```
193 
194### How to Check Lints:
195```typescript
196// ✅ CORRECT - Check specific files you modified
197read_lints([
198  "packages/editor/src/components/new-component/index.tsx",
199  "packages/editor/src/components/new-component/styled.ts"
200])
201 
202// ❌ WRONG - Checking entire codebase (too noisy)
203read_lints()  // or read_lints([])
204```
205 
206### Common ESLint Rules to Follow:
207- `@typescript-eslint/no-explicit-any` - NO `any` types
208- `@typescript-eslint/no-unused-vars` - Remove unused imports/variables
209- `@typescript-eslint/explicit-function-return-type` - Type function returns when needed
210- Proper null/undefined handling
211- Material UI imports must follow tree-shakeable pattern (see rule #2)
212 
213### AI Assistant Workflow (MANDATORY):
214```
2151. Create/modify TypeScript file
2162. Add proper type imports (Topic, Designer, etc.)
2173. Use correct types for all variables and parameters
2184. Handle nullable types with | null or | undefined
2195. RUN read_lints([file_path]) - DO NOT SKIP THIS
2206. Fix all errors found
2217. Verify with read_lints again
2228. Move to next file/task
223```
224 
225### Priority:
226- **ZERO tolerance for linting errors** in completed tasks
227- Fix ALL errors before declaring task complete
228- If a linting rule seems incorrect, discuss with user before bypassing
229- Never commit code with linting errors
230