Two files, one repository

bashdeban/fastmind ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.

Compare.cursorrules ↔ Cline rules

A · .cursorrules · 932 words B · .clinerules/.project-consistency-keeper2.md · 986 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	18	32	0%
Commands	0	1	14	0%
Section tags	8	1	7	50%

What each file covers

Sections

0 shared · 18 only in A · 32 only in B

− Rules
− 1. Material UI Imports (CRITICAL - 500KB+ Bundle Impact)
− ✅ CORRECT (Tree-shakeable):
− ❌ WRONG (Bloats bundle):
− 2. Component File Organization (MANDATORY)
− 3. Code Standards
− 4. Performance
− 5. Testing
− 6. TypeScript Type Safety (CRITICAL)
− Prohibited:
− Required Practices:
− 7. Linting and Code Quality (CRITICAL)
− When to Run Linter (REQUIRED):
− Linting Workflow (ENFORCED):
− How to Check Lints:
− Common ESLint Rules to Follow:
− AI Assistant Workflow (MANDATORY):
− Priority:
+ Project Consistency Keeper - Auto-generated
+ Technology Stack
+ Languages & Runtimes
+ Frameworks & Core Libraries
+ Core Architecture Packages
+ Key Dependencies
+ Toolchain Standards
+ Package Management
+ Build System
+ Development Server
+ Code Quality & Formatting
+ Testing Framework
+ Git Workflow
+ Project Architecture
+ Directory Structure
+ Module Organization
+ File Naming Conventions
+ Development Constraints
+ Package Management Commands
+ Prohibited Patterns
+ Required Patterns
+ Version Constraints
+ Bundle Optimization Requirements
+ Testing Requirements
+ Reference Files
+ Core Configuration
+ Package Configuration
+ Documentation
+ Development Scripts
+ Maintenance Notes
+ Performance Monitoring
+ Regular Updates

Commands

0 shared · 1 only in A · 14 only in B

− yarn build:analyze
+ eslint.config.mjs
+ eslint-plugin-react
+ eslint-plugin-react-hooks
+ eslint-plugin-cypress
+ eslint-plugin-storybook
+ eslint-config-prettier
+ cypress-image-snapshot
+ yarn lint && yarn test
+ yarn install
+ yarn clean
+ yarn build
+ yarn test
+ yarn lint
+ yarn lint:fix

Section tags

8 shared · 1 only in A · 7 only in B

− ui
+ setup
+ code-style
+ architecture
+ testing-strategy
+ dependencies
+ deployment
+ docs
build
test
lint-format
types
git-pr
performance
do-not
agent-behaviour

Line diff

+200 added−192 removed38 unchanged16.0% identical

bashdeban/fastmind · .cursorrules

@@ −1 @@

1# Rules

3## 1. Material UI Imports (CRITICAL - 500KB+ Bundle Impact)

5⚠️ Pre-push hook will REJECT incorrect imports

7### ✅ CORRECT (Tree-shakeable):

8```typescript

9// Components - one per line

10import Button from '@mui/material/Button';

11import Box from '@mui/material/Box';

13// Icons - one per line

14import SearchIcon from '@mui/icons-material/Search';

15import EditIcon from '@mui/icons-material/Edit';

17// Hooks from /styles

18import { useTheme, styled } from '@mui/material/styles';

20// Types use 'import type'

21import type { PaletteMode } from '@mui/material';

22import type { SvgIconProps } from '@mui/material/SvgIcon';

23```

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```

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```

42**Validation**: Run `./scripts/check-mui-imports.sh` or `yarn build:analyze`

44## 2. Component File Organization (MANDATORY)

46Every component MUST follow the `index.tsx` pattern:

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```

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`

65**Examples**:

66```

67theme-toggle/

68└── index.tsx

70admin-console/

71├── index.tsx

72├── layout/index.tsx

73├── maps-page/index.tsx

74└── accounts-page/index.tsx

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```

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```

94## 3. Code Standards

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

bashdeban/fastmind · .clinerules/.project-consistency-keeper2.md

@@ +1 @@

1# Project Consistency Keeper - Auto-generated

3**Last Updated**: 2025-01-17

4**Project Root**: `./`

5**Project Name**: WiseMapping Frontend

6**Version**: 6.0.1

8## Technology Stack

10### Languages & Runtimes

11- **Node.js**: >=18.0.0 (required)

12- **TypeScript**: ^5.9.3 (strict mode enforced)

13- **JavaScript**: ES2022 target, ES2020 modules

14- **JSX**: React JSX automatic runtime

16### Frameworks & Core Libraries

17- **React**: ^19.0.0 (peer dependency)

18- **Material-UI (MUI)**: ^7.3.4

19 - `@mui/material`: ^7.3.4

20 - `@mui/icons-material`: ^7.3.4

21- **Emotion**: ^11.14.0+ (styled-components alternative)

22- **Styled Components**: ^6.1.19

24### Core Architecture Packages

25- **@wisemapping/web2d**: SVG abstraction layer for chart rendering

26- **@wisemapping/mindplot**: Vanilla ES6 mind map engine

27- **@wisemapping/editor**: React component wrapper for mindplot

28- **webapp**: Complete React application (not in current scope)

30### Key Dependencies

31- **html2canvas**: ^1.4.1 (for export functionality)

32- **jspdf**: ^3.0.3 (PDF generation)

33- **lodash**: ^4.17.21 (utility functions)

34- **xml-formatter**: ^3.6.7 (XML formatting)

35- **fflate**: Custom vendor version (compression)

37## Toolchain Standards

39### Package Management

40- **Primary**: Yarn with workspaces

41- **Monorepo Tool**: Lerna (independent versioning mode)

42- **Workspace Structure**: `packages/*`

43- **Dependency Linking**: `workspace:*` protocol

45### Build System

46- **Bundler**: Webpack ^5.102.1

47- **Configuration**: `webpack.common.js` (shared), `webpack.prod.js`, `webpack.dev.js`

48- **TypeScript Loader**: ts-loader ^9.5.4 with transpile-only mode

49- **Babel**: @babel/preset-typescript ^7.28.5

50- **Optimization Features**:

51 - Persistent filesystem caching (`.webpack-cache`)

52 - Thread-loader for parallel builds

53 - Deterministic module IDs

54 - Dead code elimination (`usedExports: true`)

56### Development Server

57- **Webpack Dev Server**: ^5.2.2

58- **Port**: Configurable via `$PORT` environment variable

59- **Default Ports**:

60 - Editor Storybook: 6008

61 - Mindplot/Storybook: 6006

62 - Playground: 8081

64### Code Quality & Formatting

66#### ESLint Configuration

67- **Version**: ^9.38.0 with flat config (`eslint.config.mjs`)

68- **Presets**:

69 - `@eslint/js/recommended`

70 - `eslint-plugin-react`

71 - `eslint-plugin-react-hooks`

72 - `eslint-plugin-cypress`

73 - `eslint-plugin-storybook`

74 - `eslint-config-prettier`

75- **Globals**: browser, node, commonjs, jest

76- **Target**: ECMAScript 2022

78#### Prettier Configuration

79- **Print Width**: 100

80- **Tab Width**: 2

81- **Single Quotes**: true

82- **Trailing Commas**: `all`

83- **Semicolons**: true

85#### TypeScript Configuration

86- **Strict Mode**: Enabled (`strict: true`)

87- **Strict Null Checks**: Enabled

88- **Target**: ES2022

89- **Module**: ES2020

90- **JSX**: React automatic runtime

91- **Allow JS**: true (for mixed codebase)

92- **Source Maps**: Enabled

93- **Declaration**: true

95### Testing Framework

97#### Jest Configuration

98- **Version**: ^30.2.0

99- **Environment**: jsdom

100- **Preset**: ts-jest

101- **Transform**:

102 - JS/TS: babel-jest

103 - Assets: jest-transform-stub

104- **Module Extensions**: js, ts, tsx

105- **Verbose**: true

106

107#### Cypress Configuration

108- **Version**: ^15.5.0

109- **Base URLs**:

110 - Playground: `http://localhost:8081`

111 - Storybook: `http://localhost:6006`, `http://localhost:6008`

112- **Features**:

113 - Visual regression testing with `cypress-image-snapshot`

114 - Screenshot/video capture

115

116### Git Workflow

117- **Hooks**: Husky ^9.1.7

118- **Pre-commit**: lint-staged

119- **Pre-push**: `yarn lint && yarn test`

120- **Branch**: Main development flow

121

122## Project Architecture

123

124### Directory Structure

125```

126.

127├── packages/

128│ ├── editor/ # React-based mind map editor

129│ ├── mindplot/ # Core mind map engine (vanilla ES6)

130│ ├── web2d/ # SVG abstraction layer

131│ └── fastmind/ # Additional utilities (if present)

132├── api/ # API-related code

133├── scripts/ # Build and utility scripts

134├── memory-bank/ # Project documentation

135└── .clinerules/ # Development guidelines

136```

137

138### Module Organization

139- **Independent Versioning**: Each package uses independent versions

140- **Workspace Dependencies**: Internal packages use `workspace:*`

141- **Main Entry**: `src/index.ts` for all packages

142- **Files**: `src` directories published (not `dist`)

143

144### File Naming Conventions

145- **TypeScript**: `.ts` for logic, `.tsx` for React components

146- **Tests**: `*.test.ts`, `*.test.tsx`, or `*.cy.ts`

147- **Configuration**: `*.config.js` or `*.config.ts`

148- **Webpack**: `webpack.*.js`

149

150## Development Constraints

151

152### Package Management Commands

153- **Install**: `yarn install` (not npm)

154- **Clean**: `yarn clean` (removes all build artifacts)

155- **Build**: `yarn build` (runs lerna build across packages)

156- **Test**: `yarn test` (unit + integration tests)

157- **Lint**: `yarn lint` (ESLint checks)

158- **Lint Fix**: `yarn lint:fix` (ESLint with auto-fix)

159

160### Prohibited Patterns

161- **DO NOT** use npm commands (use yarn)

162- **DO NOT** commit build artifacts (dist/, build/, coverage/)

163- **DO NOT** use MUI without tree-shaking awareness (500KB+ impact)

164- **DO NOT** disable TypeScript strict mode

165- **DO NOT** skip pre-push hooks

166

167### Required Patterns

168- **ALWAYS** run `yarn lint && yarn test` before pushing

169- **ALWAYS** use `workspace:*` for internal dependencies

170- **ALWAYS** enable source maps in development

171- **ALWAYS** write tests for new features (unit + integration)

172- **ALWAYS** use Prettier for code formatting

173- **ALWAYS** maintain TypeScript strict mode compliance

174

175### Version Constraints

176- **React**: ^19.0.0 (peer dependency)

177- **MUI**: ^7.3.4 (critical for consistency)

178- **Node**: >=18.0.0 (required)

179- **TypeScript**: ^5.9.3 (latest stable)

180

181### Bundle Optimization Requirements

182- **Critical**: Pay special attention to MUI imports (tree-shaking)

183- **Webpack**: Use persistent caching for rebuilds

184- **Threading**: Enable parallel builds with thread-loader

185- **Analyze**: Use `webpack-bundle-analyzer` for optimization

186

187### Testing Requirements

188- **Unit Tests**: Jest for logic/components

189- **Integration Tests**: Cypress E2E tests

190- **Visual Tests**: Cypress image snapshot regression

191- **Coverage**: Maintain comprehensive test coverage

192- **CI**: All tests must pass before merge

193

194## Reference Files

195

196### Core Configuration

197- `package.json` - Root monorepo configuration

198- `lerna.json` - Lerna monorepo settings

199- `webpack.common.js` - Shared Webpack configuration

200- `eslint.config.mjs` - ESLint flat config

201- `.prettierrc.json` - Prettier formatting rules

202

203### Package Configuration

204- `packages/editor/package.json` - React editor component

205- `packages/mindplot/package.json` - Core mind map engine

206- `packages/web2d/package.json` - SVG abstraction layer

207- `packages/*/tsconfig.json` - Package-specific TypeScript config

208- `packages/*/jest.config.js` - Package-specific Jest config

209- `packages/*/cypress.config.*` - Package-specific Cypress config

210

211### Documentation

212- `README.md` - Project overview

213- `CONTRIBUTING.md` - Contribution guidelines

214- `memory-bank/` - Comprehensive project documentation

215 - `projectbrief.md` - Project overview and requirements

216 - `activeContext.md` - Current development focus

217 - `progress.md` - Implementation status

218 - `systemPatterns.md` - Architectural patterns

219 - `techContext.md` - Technology decisions

220

221### Development Scripts

222- `.husky/pre-push` - Git pre-push hook

223- `scripts/check-mui-imports.sh` - MUI import validation

224

225## Maintenance Notes

226

227### Performance Monitoring

228- Webpack build times optimization with persistent caching

229- Bundle size monitoring (especially MUI impact)

230- Cypress test execution speed

231- TypeScript compilation performance

232

233### Regular Updates

234- Keep TypeScript at latest stable version

235- Update MUI dependencies together (core + icons)

236- Maintain React peer dependency compatibility

237- Regular security updates for all dependencies

238

@@ −1 +1 @@

1−# Rules

1+# Project Consistency Keeper - Auto-generated

3−## 1. Material UI Imports (CRITICAL - 500KB+ Bundle Impact)

3+**Last Updated**: 2025-01-17

4+**Project Root**: `./`

5+**Project Name**: WiseMapping Frontend

6+**Version**: 6.0.1

5−⚠️ Pre-push hook will REJECT incorrect imports

8+## Technology Stack

7−### ✅ CORRECT (Tree-shakeable):

8−```typescript

9−// Components - one per line

10−import Button from '@mui/material/Button';

11−import Box from '@mui/material/Box';

10+### Languages & Runtimes

11+- **Node.js**: >=18.0.0 (required)

12+- **TypeScript**: ^5.9.3 (strict mode enforced)

13+- **JavaScript**: ES2022 target, ES2020 modules

14+- **JSX**: React JSX automatic runtime

1215

13−// Icons - one per line

14−import SearchIcon from '@mui/icons-material/Search';

15−import EditIcon from '@mui/icons-material/Edit';

16+### Frameworks & Core Libraries

17+- **React**: ^19.0.0 (peer dependency)

18+- **Material-UI (MUI)**: ^7.3.4

19+ - `@mui/material`: ^7.3.4

20+ - `@mui/icons-material`: ^7.3.4

21+- **Emotion**: ^11.14.0+ (styled-components alternative)

22+- **Styled Components**: ^6.1.19

1623

17−// Hooks from /styles

18−import { useTheme, styled } from '@mui/material/styles';

24+### Core Architecture Packages

25+- **@wisemapping/web2d**: SVG abstraction layer for chart rendering

26+- **@wisemapping/mindplot**: Vanilla ES6 mind map engine

27+- **@wisemapping/editor**: React component wrapper for mindplot

28+- **webapp**: Complete React application (not in current scope)

1929

20−// Types use 'import type'

21−import type { PaletteMode } from '@mui/material';

22−import type { SvgIconProps } from '@mui/material/SvgIcon';

23−```

30+### Key Dependencies

31+- **html2canvas**: ^1.4.1 (for export functionality)

32+- **jspdf**: ^3.0.3 (PDF generation)

33+- **lodash**: ^4.17.21 (utility functions)

34+- **xml-formatter**: ^3.6.7 (XML formatting)

35+- **fflate**: Custom vendor version (compression)

2436

25−### ❌ WRONG (Bloats bundle):

26−```typescript

27−import { Button, Box } from '@mui/material'; // NO!

28−import { Search, Edit } from '@mui/icons-material'; // NO!

29−import { PaletteMode } from '@mui/material'; // NO! Use 'import type'

30−```

37+## Toolchain Standards

3138

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−```

39+### Package Management

40+- **Primary**: Yarn with workspaces

41+- **Monorepo Tool**: Lerna (independent versioning mode)

42+- **Workspace Structure**: `packages/*`

43+- **Dependency Linking**: `workspace:*` protocol

4144

42−**Validation**: Run `./scripts/check-mui-imports.sh` or `yarn build:analyze`

45+### Build System

46+- **Bundler**: Webpack ^5.102.1

47+- **Configuration**: `webpack.common.js` (shared), `webpack.prod.js`, `webpack.dev.js`

48+- **TypeScript Loader**: ts-loader ^9.5.4 with transpile-only mode

49+- **Babel**: @babel/preset-typescript ^7.28.5

50+- **Optimization Features**:

51+ - Persistent filesystem caching (`.webpack-cache`)

52+ - Thread-loader for parallel builds

53+ - Deterministic module IDs

54+ - Dead code elimination (`usedExports: true`)

4355

44−## 2. Component File Organization (MANDATORY)

56+### Development Server

57+- **Webpack Dev Server**: ^5.2.2

58+- **Port**: Configurable via `$PORT` environment variable

59+- **Default Ports**:

60+ - Editor Storybook: 6008

61+ - Mindplot/Storybook: 6006

62+ - Playground: 8081

4563

46−Every component MUST follow the `index.tsx` pattern:

64+### Code Quality & Formatting

4765

48−```

49−ComponentName/

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−```

66+#### ESLint Configuration

67+- **Version**: ^9.38.0 with flat config (`eslint.config.mjs`)

68+- **Presets**:

69+ - `@eslint/js/recommended`

70+ - `eslint-plugin-react`

71+ - `eslint-plugin-react-hooks`

72+ - `eslint-plugin-cypress`

73+ - `eslint-plugin-storybook`

74+ - `eslint-config-prettier`

75+- **Globals**: browser, node, commonjs, jest

76+- **Target**: ECMAScript 2022

5677

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`

78+#### Prettier Configuration

79+- **Print Width**: 100

80+- **Tab Width**: 2

81+- **Single Quotes**: true

82+- **Trailing Commas**: `all`

83+- **Semicolons**: true

6484

65−**Examples**:

66−```

67−theme-toggle/

68−└── index.tsx

85+#### TypeScript Configuration

86+- **Strict Mode**: Enabled (`strict: true`)

87+- **Strict Null Checks**: Enabled

88+- **Target**: ES2022

89+- **Module**: ES2020

90+- **JSX**: React automatic runtime

91+- **Allow JS**: true (for mixed codebase)

92+- **Source Maps**: Enabled

93+- **Declaration**: true

6994

70−admin-console/

71−├── index.tsx

72−├── layout/index.tsx

73−├── maps-page/index.tsx

74−└── accounts-page/index.tsx

95+### Testing Framework

7596

76−action-widget/pane/

77−├── topic-style-editor/

78−│ ├── index.tsx

79−│ ├── IconCollection.tsx

80−│ └── ColorPicker.tsx

81−└── shared/

82− ├── StyledTabs.tsx

83− └── StyledEditorContainer.tsx

84−```

97+#### Jest Configuration

98+- **Version**: ^30.2.0

99+- **Environment**: jsdom

100+- **Preset**: ts-jest

101+- **Transform**:

102+ - JS/TS: babel-jest

103+ - Assets: jest-transform-stub

104+- **Module Extensions**: js, ts, tsx

105+- **Verbose**: true

85106

86−**Clean Imports Result**:

87−```typescript

88−import ThemeToggle from '../common/theme-toggle'; // ✅ Clean

89−import MapsPage from '../admin-console/maps-page'; // ✅ Clean

90−// vs

91−import ThemeToggle from '../common/theme-toggle/ThemeToggle'; // ❌ Redundant

92−```

107+#### Cypress Configuration

108+- **Version**: ^15.5.0

109+- **Base URLs**:

110+ - Playground: `http://localhost:8081`

111+ - Storybook: `http://localhost:6006`, `http://localhost:6008`

112+- **Features**:

113+ - Visual regression testing with `cypress-image-snapshot`

114+ - Screenshot/video capture

93115

94−## 3. Code Standards

116+### Git Workflow

117+- **Hooks**: Husky ^9.1.7

118+- **Pre-commit**: lint-staged

119+- **Pre-push**: `yarn lint && yarn test`

120+- **Branch**: Main development flow

95121

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`

122+## Project Architecture

106123

107−## 4. Performance

124+### Directory Structure

125+```

126+.

127+├── packages/

128+│ ├── editor/ # React-based mind map editor

129+│ ├── mindplot/ # Core mind map engine (vanilla ES6)

130+│ ├── web2d/ # SVG abstraction layer

131+│ └── fastmind/ # Additional utilities (if present)

132+├── api/ # API-related code

133+├── scripts/ # Build and utility scripts

134+├── memory-bank/ # Project documentation

135+└── .clinerules/ # Development guidelines

136+```

108137

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

138+### Module Organization

139+- **Independent Versioning**: Each package uses independent versions

140+- **Workspace Dependencies**: Internal packages use `workspace:*`

141+- **Main Entry**: `src/index.ts` for all packages

142+- **Files**: `src` directories published (not `dist`)

112143

113−## 5. Testing

144+### File Naming Conventions

145+- **TypeScript**: `.ts` for logic, `.tsx` for React components

146+- **Tests**: `*.test.ts`, `*.test.tsx`, or `*.cy.ts`

147+- **Configuration**: `*.config.js` or `*.config.ts`

148+- **Webpack**: `webpack.*.js`

114149

115−- Unit tests: `*.test.ts` or `*.test.tsx`

116−- Integration tests: Cypress

117−- Aim for good coverage on critical paths

150+## Development Constraints

118151

119−## 6. TypeScript Type Safety (CRITICAL)

152+### Package Management Commands

153+- **Install**: `yarn install` (not npm)

154+- **Clean**: `yarn clean` (removes all build artifacts)

155+- **Build**: `yarn build` (runs lerna build across packages)

156+- **Test**: `yarn test` (unit + integration tests)

157+- **Lint**: `yarn lint` (ESLint checks)

158+- **Lint Fix**: `yarn lint:fix` (ESLint with auto-fix)

120159

121−**MANDATORY**: All TypeScript code must be properly typed. NO exceptions.

160+### Prohibited Patterns

161+- **DO NOT** use npm commands (use yarn)

162+- **DO NOT** commit build artifacts (dist/, build/, coverage/)

163+- **DO NOT** use MUI without tree-shaking awareness (500KB+ impact)

164+- **DO NOT** disable TypeScript strict mode

165+- **DO NOT** skip pre-push hooks

122166

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

167+### Required Patterns

168+- **ALWAYS** run `yarn lint && yarn test` before pushing

169+- **ALWAYS** use `workspace:*` for internal dependencies

170+- **ALWAYS** enable source maps in development

171+- **ALWAYS** write tests for new features (unit + integration)

172+- **ALWAYS** use Prettier for code formatting

173+- **ALWAYS** maintain TypeScript strict mode compliance

127174

128−### Required Practices:

175+### Version Constraints

176+- **React**: ^19.0.0 (peer dependency)

177+- **MUI**: ^7.3.4 (critical for consistency)

178+- **Node**: >=18.0.0 (required)

179+- **TypeScript**: ^5.9.3 (latest stable)

129180

130−#### 1. Import Proper Types:

131−```typescript

132−// ✅ CORRECT - Import types from mindplot

133−import { Topic, Designer } from '@wisemapping/mindplot';

181+### Bundle Optimization Requirements

182+- **Critical**: Pay special attention to MUI imports (tree-shaking)

183+- **Webpack**: Use persistent caching for rebuilds

184+- **Threading**: Enable parallel builds with thread-loader

185+- **Analyze**: Use `webpack-bundle-analyzer` for optimization

134186

135−// ❌ WRONG - Using 'any'

136−const topic: any = ...;

137−```

187+### Testing Requirements

188+- **Unit Tests**: Jest for logic/components

189+- **Integration Tests**: Cypress E2E tests

190+- **Visual Tests**: Cypress image snapshot regression

191+- **Coverage**: Maintain comprehensive test coverage

192+- **CI**: All tests must pass before merge

138193

139−#### 2. Handle Nullable Types Correctly:

140−```typescript

141−// ✅ CORRECT - Properly handle Topic | null

142−const 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−};

194+## Reference Files

148195

149−// ❌ WRONG - Type mismatch

150−const getTopicDepth = (topic: Topic): number => {

151− let current = topic; // TypeScript infers Topic

152− current = current.getParent(); // ERROR: Topic | null not assignable to Topic

153−};

154−```

196+### Core Configuration

197+- `package.json` - Root monorepo configuration

198+- `lerna.json` - Lerna monorepo settings

199+- `webpack.common.js` - Shared Webpack configuration

200+- `eslint.config.mjs` - ESLint flat config

201+- `.prettierrc.json` - Prettier formatting rules

155202

156−#### 3. Use Unknown for Truly Unknown Types:

157−```typescript

158−// ✅ If you truly don't know the type

159−const data: unknown = JSON.parse(str);

160−if (typeof data === 'object' && data !== null) {

161− // Type guard before use

162−}

203+### Package Configuration

204+- `packages/editor/package.json` - React editor component

205+- `packages/mindplot/package.json` - Core mind map engine

206+- `packages/web2d/package.json` - SVG abstraction layer

207+- `packages/*/tsconfig.json` - Package-specific TypeScript config

208+- `packages/*/jest.config.js` - Package-specific Jest config

209+- `packages/*/cypress.config.*` - Package-specific Cypress config

163210

164−// ❌ WRONG

165−const data: any = JSON.parse(str);

166−```

211+### Documentation

212+- `README.md` - Project overview

213+- `CONTRIBUTING.md` - Contribution guidelines

214+- `memory-bank/` - Comprehensive project documentation

215+ - `projectbrief.md` - Project overview and requirements

216+ - `activeContext.md` - Current development focus

217+ - `progress.md` - Implementation status

218+ - `systemPatterns.md` - Architectural patterns

219+ - `techContext.md` - Technology decisions

167220

168−## 7. Linting and Code Quality (CRITICAL)

221+### Development Scripts

222+- `.husky/pre-push` - Git pre-push hook

223+- `scripts/check-mui-imports.sh` - MUI import validation

169224

170−**MANDATORY**: AI MUST check linter errors after EVERY file creation or modification.

225+## Maintenance Notes

171226

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**

227+### Performance Monitoring

228+- Webpack build times optimization with persistent caching

229+- Bundle size monitoring (especially MUI impact)

230+- Cypress test execution speed

231+- TypeScript compilation performance

177232

178−### Linting Workflow (ENFORCED):

179−```

180−For EACH file created/modified:

181−1. Write/modify the code

182−2. IMMEDIATELY run read_lints([specific_file_path])

183−3. Fix ALL errors found

184−4. Re-run read_lints to verify

185−5. Only then move to next file

186−

187−At task completion:

188−1. Run read_lints on ALL modified files together

189−2. Fix any remaining issues

190−3. Final verification

191−4. Task complete

192−```

193−

194−### How to Check Lints:

195−```typescript

196−// ✅ CORRECT - Check specific files you modified

197−read_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)

203−read_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−```

215−1. Create/modify TypeScript file

216−2. Add proper type imports (Topic, Designer, etc.)

217−3. Use correct types for all variables and parameters

218−4. Handle nullable types with | null or | undefined

219−5. RUN read_lints([file_path]) - DO NOT SKIP THIS

220−6. Fix all errors found

221−7. Verify with read_lints again

222−8. 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

233+### Regular Updates

234+- Keep TypeScript at latest stable version

235+- Update MUI dependencies together (core + icons)

236+- Maintain React peer dependency compatibility

237+- Regular security updates for all dependencies

230238