|
| 1 | +# Coding Guidelines |
| 2 | + |
| 3 | +## General Standards |
| 4 | + |
| 5 | +- **Function Declarations**: Always use arrow functions (`const fn = () => {}`) instead of function declarations (`function fn() {}`) |
| 6 | +- **TypeScript**: Use strict typing throughout the codebase |
| 7 | +- **Path Aliases**: Always use `@frontend/` and `@backend/` instead of relative paths |
| 8 | + |
| 9 | +## Testing Standards |
| 10 | + |
| 11 | +### Test Framework |
| 12 | + |
| 13 | +- **Bun Test**: Use Bun's native test runner for all tests |
| 14 | +- **Import Pattern**: `import { describe, test, expect } from 'bun:test'` |
| 15 | +- **File Naming**: Tests must use `.test.ts` or `.spec.ts` suffix |
| 16 | + |
| 17 | +### Test Structure |
| 18 | + |
| 19 | +- **Frontend Tests**: Place in `src/**/__tests__/` directories |
| 20 | +- **Backend Tests**: Place in `tests/` directory mirroring `src/` structure |
| 21 | +- **Test Organization**: Group related tests using `describe` blocks |
| 22 | +- **Test Naming**: Use descriptive names that explain the behavior being tested |
| 23 | + |
| 24 | +### Testing Approach |
| 25 | + |
| 26 | +- **Logic Testing**: Focus on testing component logic, business rules, and data transformations |
| 27 | +- **Type Validation**: Test TypeScript interfaces and type definitions |
| 28 | +- **State Management**: Test store interactions and state mutations |
| 29 | +- **Integration**: Test composable interactions and data flow |
| 30 | +- **Avoid DOM Testing**: Prefer logic testing over complex DOM manipulation tests |
| 31 | + |
| 32 | +### Test Examples |
| 33 | + |
| 34 | +```typescript |
| 35 | +import { describe, test, expect } from 'bun:test' |
| 36 | + |
| 37 | +describe('Component Logic', () => { |
| 38 | + test('should compute values correctly', () => { |
| 39 | + const input = 'test' |
| 40 | + const result = processInput(input) |
| 41 | + expect(result).toBe('expected') |
| 42 | + }) |
| 43 | + |
| 44 | + test('should handle edge cases', () => { |
| 45 | + const emptyInput = '' |
| 46 | + const result = processInput(emptyInput) |
| 47 | + expect(result).toBe('default') |
| 48 | + }) |
| 49 | +}) |
| 50 | +``` |
| 51 | + |
| 52 | +## Vue Component Standards |
| 53 | + |
| 54 | +### Single File Component Structure |
| 55 | + |
| 56 | +Vue components MUST follow this exact order: |
| 57 | + |
| 58 | +1. **`<script setup lang="ts">`** - Always at the top |
| 59 | +2. **`<template>`** - In the middle |
| 60 | +3. **`<style scoped>`** - Should not be used |
| 61 | + |
| 62 | +### Styling Guidelines |
| 63 | + |
| 64 | +- **Tailwind Only**: Always use Tailwind CSS utility classes instead of custom CSS |
| 65 | +- **No Custom CSS**: `<style>` sections should not be used |
| 66 | +- **Custom CSS Exception**: Only use `<style scoped>` for complex animations or styles that cannot be achieved with Tailwind utilities |
| 67 | + |
| 68 | +### Component Best Practices |
| 69 | + |
| 70 | +- Use `<script setup lang="ts">` syntax exclusively |
| 71 | +- Define props with `defineProps<Props>()` and `withDefaults()` |
| 72 | +- Define emits with `defineEmits<{}>()` |
| 73 | +- Use computed properties for reactive derived state |
| 74 | +- Leverage auto-imports for Vue APIs and PrimeVue components |
| 75 | + |
| 76 | +### Variable Naming Restrictions |
| 77 | + |
| 78 | +- **Avoid Reserved Names**: Never use `column`, `message, `row` as variable names in frontend code |
| 79 | +- **PrimeVue Conflicts**: These names trigger PrimeVue auto-imports and cause runtime errors |
| 80 | +- **Alternative Names**: Use a similar descriptive name |
| 81 | + |
| 82 | +## Auto-Import Configuration |
| 83 | + |
| 84 | +The frontend uses `unplugin-auto-import` and `unplugin-vue-components` for automatic imports. |
| 85 | + |
| 86 | +### Auto-Import Rules |
| 87 | + |
| 88 | +- **Framework APIs**: All Vue, Vue Router, and Pinia APIs are automatically imported |
| 89 | +- **Third-party Libraries**: VueUse composables and PrimeVue utilities are auto-imported |
| 90 | +- **Custom Code**: All files in `src/**` (all subdirectories under src) are auto-imported |
| 91 | +- **Components**: All PrimeVue components and custom components in `src/*` (direct subdirectories) are auto-imported |
| 92 | + |
| 93 | +### Usage Guidelines |
| 94 | + |
| 95 | +- No need to import Vue APIs, VueUse composables, or PrimeVue components |
| 96 | +- All exported functions from any file under `src/` are automatically available |
| 97 | +- Components from direct subdirectories of `src/` are automatically available |
| 98 | +- Type definitions are generated in `auto-imports.d.ts` and `components.d.ts` |
| 99 | +- ESLint configuration is automatically updated for auto-imports |
| 100 | +- Avoid manual imports for auto-imported items to prevent conflicts |
| 101 | + |
| 102 | +## Path Aliasing |
| 103 | + |
| 104 | +The project uses TypeScript path mapping for clean imports across the monorepo. |
| 105 | + |
| 106 | +### Path Mapping Rules |
| 107 | + |
| 108 | +- `@backend` → `./backend/src` |
| 109 | +- `@backend/*` → `./backend/src/*` |
| 110 | +- `@backend/tests/*` → `./backend/tests/*` |
| 111 | +- `@frontend` → `./frontend/src` |
| 112 | +- `@frontend/*` → `./frontend/src/*` |
| 113 | + |
| 114 | +### Best Practices |
| 115 | + |
| 116 | +- Always use path aliases `@frontend/` and `@backend/` instead of relative paths |
| 117 | +- Use aliases consistently across both TypeScript and test files |
| 118 | +- Path aliases work in both development and build environments |
| 119 | + |
| 120 | +## Code Review Checklist |
| 121 | + |
| 122 | +When reviewing code for compliance, check in this order: |
| 123 | + |
| 124 | +### 1. Basic Structure (Check First) |
| 125 | + |
| 126 | +- [ ] `<script setup lang="ts">` is at the top (Vue components) |
| 127 | +- [ ] `<template>` is in the middle (Vue components) |
| 128 | +- [ ] `<style scoped>` is at bottom (if present in exception cases) |
| 129 | +- [ ] All functions use arrow function syntax |
| 130 | + |
| 131 | +### 2. Styling Compliance |
| 132 | + |
| 133 | +- [ ] No custom CSS that can be replaced with Tailwind utilities |
| 134 | +- [ ] All styling uses Tailwind classes where possible |
| 135 | +- [ ] `<style>` section only exists for complex animations or unavoidable custom styles |
| 136 | + |
| 137 | +### 3. TypeScript & Composition API |
| 138 | + |
| 139 | +- [ ] Uses `<script setup lang="ts">` syntax (Vue components) |
| 140 | +- [ ] Props defined with `defineProps<Props>()` and `withDefaults()` (Vue components) |
| 141 | +- [ ] Emits defined with `defineEmits<{}>()` (Vue components) |
| 142 | +- [ ] Proper TypeScript typing throughout |
| 143 | + |
| 144 | +### 4. Auto-Imports & Path Aliases |
| 145 | + |
| 146 | +- [ ] No manual imports for auto-imported Vue APIs or PrimeVue components |
| 147 | +- [ ] Uses `@frontend/` and `@backend/` path aliases instead of relative paths |
| 148 | +- [ ] No import conflicts with auto-import system |
| 149 | + |
| 150 | +## Backend Coding Standards |
| 151 | + |
| 152 | +### API Development |
| 153 | + |
| 154 | +- Use Elysia framework patterns and conventions |
| 155 | +- Implement proper error handling with Elysia plugins |
| 156 | +- Define schemas in `schemas.ts` files |
| 157 | +- Group routes by domain (e.g., `/api/project/*`) |
| 158 | + |
| 159 | +### Database Operations |
| 160 | + |
| 161 | +- Use DuckDB for data processing operations |
| 162 | +- Use SQLite for project persistence |
| 163 | +- Implement proper connection management |
| 164 | +- Use prepared statements for security |
| 165 | + |
| 166 | +## Testing Standards |
| 167 | + |
| 168 | +### Test Structure |
| 169 | + |
| 170 | +- Backend tests mirror `src/` structure |
| 171 | +- Frontend tests in `__tests__/` subdirectories |
| 172 | +- Integration tests for API endpoints |
| 173 | +- Unit tests for composables and utilities |
| 174 | +- Do not mock, but test real implementation |
| 175 | +- Do not create any logic in tests, only test behavior |
| 176 | +- Do not create unit tests for Vue components |
| 177 | + |
| 178 | +### Test Naming |
| 179 | + |
| 180 | +- Descriptive test names that explain the behavior being tested |
| 181 | +- Group related tests using `describe` blocks |
| 182 | +- Use `it` or `test` for individual test cases |
0 commit comments