Skip to content

Commit 836ff5a

Browse files
ntindlentindle
authored
Merge branch 'main' into dependabot/github_actions/actions/checkout-5
2 parents 1be486d + 076a198 commit 836ff5a

File tree

5 files changed

+322
-436
lines changed

5 files changed

+322
-436
lines changed

‎.github/copilot-instructions.md

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Gridfinity Space Optimizer - GitHub Copilot Instructions
2+
3+
**ALWAYS follow these instructions first and only fallback to additional search and context gathering if the information in the instructions is incomplete or found to be in error.**
4+
5+
## Project Overview
6+
7+
Gridfinity Space Optimizer is a TypeScript React web application that calculates optimal Gridfinity storage system layouts. It helps users determine the best configuration of Gridfinity bins to fit their drawer dimensions and 3D printer build volumes. Built with React 18, Vite, TypeScript, Tailwind CSS, and Shadcn/ui components.
8+
9+
## Working Effectively
10+
11+
### Prerequisites
12+
- Node.js version 22.5 or later (verified with v20.19.4+)
13+
- npm (comes with Node.js)
14+
15+
### Bootstrap, Build, and Test the Repository
16+
17+
**CRITICAL**: Set timeouts of 60+ minutes for build commands and 30+ minutes for test commands. NEVER CANCEL long-running operations.
18+
19+
1. **Install dependencies**:
20+
```bash
21+
npm install
22+
```
23+
- Takes ~2 minutes to complete
24+
- May show deprecation warnings (expected)
25+
- May show 2-3 moderate severity vulnerabilities (known issue)
26+
27+
2. **Run all quality checks**:
28+
```bash
29+
npm run lint
30+
```
31+
- Takes ~5 seconds
32+
- NEVER CANCEL: Wait for completion
33+
- Must show 0 warnings/errors for CI to pass
34+
35+
```bash
36+
npx tsc --noEmit
37+
```
38+
- Takes ~4 seconds
39+
- TypeScript type checking
40+
- NEVER CANCEL: Wait for completion
41+
42+
3. **Run tests**:
43+
```bash
44+
npm test
45+
```
46+
- Takes ~11 seconds. NEVER CANCEL. Set timeout to 30+ minutes.
47+
- Currently 202 tests passing, 11 skipped
48+
- Memory-intensive due to large calculation tests
49+
- May show debug output for test scenarios (expected)
50+
51+
4. **Build production**:
52+
```bash
53+
npm run build
54+
```
55+
- Takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ minutes.
56+
- Creates optimized build in `dist/` directory
57+
- Shows bundle size warnings for mathjs library (expected)
58+
59+
5. **Build development**:
60+
```bash
61+
npm run build:dev
62+
```
63+
- Takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ minutes.
64+
- Creates development build with source maps
65+
66+
### Running the Application
67+
68+
1. **Development server**:
69+
```bash
70+
npm run dev
71+
```
72+
- Starts on port 8080 (or next available port)
73+
- Hot module replacement enabled
74+
- Access via http://localhost:8080 (or displayed port)
75+
76+
2. **Preview production build**:
77+
```bash
78+
npm run preview
79+
```
80+
- Serves production build on port 4173
81+
- Must run `npm run build` first
82+
83+
## Validation
84+
85+
### Manual Testing Requirements
86+
**ALWAYS run through complete end-to-end scenarios after making changes.**
87+
88+
**Required Test Scenario**:
89+
1. Start development server with `npm run dev`
90+
2. Open application in browser
91+
3. Verify default drawer dimensions (22.5" x 16.5") are loaded
92+
4. Toggle units from inches to mm - verify conversion (571.5mm x 419.1mm)
93+
5. Change width dimension - verify results update automatically
94+
6. Verify visual preview updates with new layout
95+
7. Check that spacers are generated correctly
96+
8. Test with "Use only half-size bins" enabled - verify spacers still work
97+
9. Change printer selection - verify build volume updates
98+
99+
**Critical Areas to Always Test**:
100+
- Unit conversion (inches ↔ mm) must be precise
101+
- Real-time calculation updates when dimensions change
102+
- Spacer generation with both full-size and half-size bins
103+
- Visual preview accuracy with layout changes
104+
105+
### Pre-commit Validation
106+
**ALWAYS run these before committing changes:**
107+
```bash
108+
npm run lint
109+
npx tsc --noEmit
110+
npm test
111+
npm run build
112+
```
113+
114+
## Architecture and Important Locations
115+
116+
### Entry Points
117+
- `src/main.tsx` - Application entry point
118+
- `src/App.tsx` - Root component with routing and providers
119+
- `src/pages/Index.tsx` - Main page layout
120+
121+
### Core Components
122+
- **Main Calculator**: `src/components/GridfinityCalculator.tsx`
123+
- Central orchestration component
124+
- Manages all calculation state
125+
- **Calculator Sections**: `src/components/GridfinityCalculator/`
126+
- `DrawerDimensions.tsx` - Input for drawer size with unit conversion
127+
- `PrinterSettings.tsx` - 3D printer selection with build volumes
128+
- `BinOptions.tsx` - Half-size bin toggles
129+
- `DrawerOptions.tsx` - Number of duplicate drawers
130+
- `CustomPrinterDialog.tsx` - Custom printer dimension input
131+
- **Results Display**:
132+
- `src/components/GridfinityResults.tsx` - Calculated bin quantities
133+
- `src/components/GridfinityVisualPreview.tsx` - Visual layout grid
134+
135+
### Core Logic
136+
- **Calculation Engine**: `src/utils/gridfinityUtils.ts`
137+
- Main function: `calculateGrids()` - Computes optimal bin layout
138+
- Constants: `FULL_GRID_SIZE = 42mm`, `HALF_GRID_SIZE = 21mm`
139+
- **Precision Math**: `src/services/unitMath.ts`
140+
- **CRITICAL**: ALL math operations must use this service
141+
- Fixes floating-point precision issues with BigNumber arithmetic
142+
- **Unit Conversion**: `src/services/unitConversion.ts`
143+
- Handles inch/mm conversions with validation
144+
145+
### State Management
146+
- **Global Settings**: `src/contexts/SettingsContext.tsx`
147+
- Centralized application state using React Context
148+
- Automatic localStorage persistence
149+
- **Focused Hooks**:
150+
- `useSettings()` - Access all settings
151+
- `useDrawerSettings()` - Drawer-specific settings
152+
- `usePrinterSettings()` - Printer-specific settings
153+
- `useBinOptions()` - Bin option toggles
154+
155+
### Styling
156+
- **Tailwind CSS** for utility-first styling
157+
- **Shadcn/ui components** in `src/components/ui/`
158+
- Custom layouts using CSS Grid with `repeat(auto-fit, minmax(300px, 1fr))`
159+
160+
## Critical Development Rules
161+
162+
### ⚠️ NEVER use native JavaScript math in calculations
163+
```javascript
164+
// ❌ WRONG - will cause precision issues
165+
const total = width + height;
166+
const area = width * height;
167+
168+
// ✅ CORRECT - use unitMath service
169+
import { unitMath } from '@/services/unitMath';
170+
const total = unitMath.add(width, height);
171+
const area = unitMath.multiply(width, height);
172+
```
173+
174+
### ⚠️ Always use @/ import alias
175+
```javascript
176+
// ❌ WRONG - inconsistent relative imports
177+
import { something } from '../../../lib/utils';
178+
179+
// ✅ CORRECT - use @ alias
180+
import { something } from '@/lib/utils';
181+
```
182+
183+
### ⚠️ TypeScript Required
184+
- Project is 100% TypeScript
185+
- All new files must be .ts/.tsx
186+
- Full type safety enforced
187+
- Use existing type definitions in `src/types/`
188+
189+
### ⚠️ Test Coverage Requirements
190+
- Always add tests for algorithm changes
191+
- Update snapshots with `npx vitest --run -u` when precision changes
192+
- Test both full-size and half-size bin scenarios
193+
194+
## Common Tasks and Commands
195+
196+
### File Structure Overview
197+
```
198+
├── src/
199+
│ ├── components/ # React components
200+
│ │ ├── ui/ # Shadcn/ui component library
201+
│ │ └── GridfinityCalculator/ # Calculator components
202+
│ ├── contexts/ # React Context providers
203+
│ ├── hooks/ # Custom React hooks
204+
│ ├── services/ # Core services (unitMath, unitConversion)
205+
│ ├── utils/ # Utility functions (gridfinityUtils)
206+
│ ├── lib/ # Library configurations
207+
│ └── types/ # TypeScript type definitions
208+
├── .github/workflows/ # CI/CD pipeline definitions
209+
└── docs/ # Documentation
210+
```
211+
212+
### Key Configuration Files
213+
- `package.json` - Dependencies and scripts
214+
- `vite.config.js` - Build configuration (port 8080)
215+
- `vite.config.test.js` - Test configuration
216+
- `eslint.config.js` - Linting rules (max warnings: 0)
217+
- `tsconfig.json` - TypeScript configuration
218+
- `tailwind.config.js` - CSS framework configuration
219+
220+
### Development Workflow
221+
1. **Start development**: `npm run dev`
222+
2. **Make changes** with TypeScript and proper imports
223+
3. **Test changes** with complete user scenarios
224+
4. **Run quality checks**: `npm run lint && npx tsc --noEmit`
225+
5. **Run tests**: `npm test`
226+
6. **Build verification**: `npm run build`
227+
228+
### Debugging Common Issues
229+
- **Build failures**: Check TypeScript errors with `npx tsc --noEmit`
230+
- **Test failures**: Often related to precision - use unitMath service
231+
- **Lint failures**: Must fix all warnings/errors (max-warnings: 0)
232+
- **Memory issues**: Tests may use significant memory due to calculations
233+
234+
## CI/CD Pipeline
235+
236+
The project uses GitHub Actions across multiple workflows:
237+
- **CI Pipeline**: Tests on Node.js 18.x, 20.x, 22.x
238+
- **Code Quality**: ESLint and TypeScript checking
239+
- **Security**: CodeQL, SAST tools, secret detection
240+
- **Deployment**: Automatic deployment to GitHub Pages
241+
242+
All pull requests must pass:
243+
- TypeScript type checking (`npx tsc --noEmit`)
244+
- ESLint with zero warnings (`npm run lint`)
245+
- All tests passing (`npm test`)
246+
- Successful production build (`npm run build`)
247+
248+
## Known Issues and Gotchas
249+
250+
1. **Memory Usage**: Tests may consume significant memory due to large calculation matrices
251+
2. **Precision Requirements**: Always use `unitMath` service for calculations to avoid floating-point errors
252+
3. **Snapshot Tests**: Will fail when precision changes - update with `npx vitest --run -u`
253+
4. **Half-size Bin Testing**: Critical bug was fixed - always test spacer generation with half-size bins enabled
254+
5. **Build Warnings**: mathjs library causes bundle size warnings (expected and acceptable)
255+
256+
## Performance Considerations
257+
258+
- **Build Time**: ~14 seconds (normal)
259+
- **Test Time**: ~11 seconds (can spike with memory-intensive tests)
260+
- **Development Server**: Starts in ~200ms with HMR
261+
- **Bundle Size**: math-vendor chunk is large (~633KB) due to mathjs precision library
262+
263+
Remember: This application prioritizes calculation accuracy over bundle size due to the precision requirements of Gridfinity layout calculations.

‎.github/workflows/ci.yml

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,13 @@ jobs:
2929
run: npm ci
3030

3131
- name: Run tests
32-
run: npm test -- --run --reporter=verbose
32+
run: npm test -- --run --reporter=verbose --reporter=junit --outputFile=test-report.junit.xml
33+
34+
- name: Upload test results to Codecov
35+
if: ${{ !cancelled() }}
36+
uses: codecov/test-results-action@v1
37+
with:
38+
token: ${{ secrets.CODECOV_TOKEN }}
3339

3440
- name: Upload test results
3541
if: always()
@@ -39,6 +45,7 @@ jobs:
3945
path: |
4046
coverage/
4147
test-results/
48+
test-report.junit.xml
4249
retention-days: 7
4350

4451
lint:

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,6 @@ dist-ssr
2323
*.sln
2424
*.sw?
2525
/coverage
26+
27+
# Test reports
28+
test-report.junit.xml

0 commit comments

Comments
 (0)