FastMind Development Rules

Comprehensive development standards for FastMind, a native VS Code mind mapping extension. These rules enforce bundle optimization, type safety, and maintainable architecture.

Instructions

Follow these rules strictly when working on FastMind codebase. Pre-push hooks enforce many of these patterns.

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

**Always use tree-shakeable imports to prevent massive bundle bloat.**

Import components and icons one per line:

```typescript

// ✅ CORRECT

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

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

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

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

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

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

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

// ❌ WRONG (bloats bundle by 500KB+)

import { Button, Box } from '@mui/material';

import { Search, Edit } from '@mui/icons-material';

import { PaletteMode } from '@mui/material'; // Use 'import type' for types

```

**Common components quick reference:**

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

2. Component File Organization (MANDATORY)

Every component must follow the `index.tsx` pattern:

```

ComponentName/

├── index.tsx # Main component export (REQUIRED)

├── SubComponent.tsx # Sub-components in same directory

├── helpers.ts # Component-specific utilities

├── types.ts # Component-specific types

└── styles.css # Component-specific styles

```

**Rules:**

**Example structure:**

```

theme-toggle/

└── index.tsx

admin-console/

├── index.tsx

├── layout/index.tsx

├── maps-page/index.tsx

└── accounts-page/index.tsx

action-widget/pane/

├── topic-style-editor/

│ ├── index.tsx

│ ├── IconCollection.tsx

│ └── ColorPicker.tsx

└── shared/

├── StyledTabs.tsx

└── StyledEditorContainer.tsx

```

This produces clean imports:

```typescript

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

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

```

3. TypeScript Type Safety (ZERO TOLERANCE)

All TypeScript code must be properly typed. NO exceptions.

**Prohibited:**

**Required practices:**

**Import proper types:**

```typescript

// ✅ CORRECT

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

// ❌ WRONG

const topic: any = ...;

```

**Handle nullable types correctly:**

```typescript

// ✅ CORRECT

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

let current: Topic | null = topic;

while (current && current.getParent() !== null) {

current = current.getParent(); // Returns Topic | null

}

return depth;

};

// ❌ WRONG - Type mismatch

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

let current = topic; // Inferred as Topic

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

};

```

**Use unknown for truly unknown types:**

```typescript

// ✅ CORRECT

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

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

// Type guard before use

}

// ❌ WRONG

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

```

4. Linting and Code Quality (MANDATORY)

**AI agents MUST check linter errors after EVERY file creation or modification.**

**When to run linter:**

**Linting workflow:**

For EACH file created/modified:

1. Write/modify the code

2. IMMEDIATELY run `read_lints([specific_file_path])`

3. Fix ALL errors found

4. Re-run `read_lints` to verify

5. Only then move to next file

At task completion:

1. Run `read_lints` on ALL modified files together

2. Fix any remaining issues

3. Final verification

4. Task complete

**Check specific files you modified:**

```typescript

// ✅ CORRECT

read_lints([

"packages/editor/src/components/new-component/index.tsx",

"packages/editor/src/components/new-component/styled.ts"

])

// ❌ WRONG (too noisy)

read_lints() // Checks entire codebase

```

**Common ESLint rules:**

**Workflow for AI agents:**

1. Create/modify TypeScript file

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

3. Use correct types for all variables and parameters

4. Handle nullable types with `| null` or `| undefined`

5. RUN `read_lints([file_path])` - DO NOT SKIP

6. Fix all errors found

7. Verify with `read_lints` again

8. Move to next file/task

**Priority:** ZERO tolerance for linting errors in completed tasks.

5. Code Standards

- Components: PascalCase (`MyComponent.tsx`)

- Utilities: camelCase (`myUtility.ts`)

- Constants: UPPER_SNAKE_CASE (`MAX_VALUE`)

- Clear commit messages

- No force push to `main`

- Branch names: `feature/name`, `fix/name`

6. Performance

7. Testing

Examples

**Creating a new component:**

1. Create directory: `src/components/my-feature/`

2. Create `index.tsx` with proper Material UI imports

3. Add types in `types.ts` if needed

4. Run `read_lints(["src/components/my-feature/index.tsx"])`

5. Fix all errors

6. Verify with `read_lints` again

**Modifying existing code:**

1. Make changes to file

2. Ensure all types are correct (no `any`)

3. Run `read_lints([modified_file_path])`

4. Fix errors

5. Commit only when lint-clean

Constraints