dashboard/QUICK_REFERENCE.md

Quick Reference Guide

For: Daily development with quality improvements

---

🚀 Common Commands

Development

npm run dev           # Start dev server

Code Quality

npm run lint          # Check code quality
npm run lint:fix      # Auto-fix linting issues
npm run format        # Format all files
npm run type-check    # Check TypeScript errors

Testing

npm test              # Run tests (watch mode)
npm run test:run      # Run tests once
npm run test:ui       # Visual test UI
npm run test:coverage # Coverage report

# Backend tests
cd backend
npm test

Building

npm run build         # Build for production
npm run preview       # Preview production build

Git Hooks

git commit            # Automatically lints changed files
git commit --no-verify # Skip hooks (emergency only)

---

🔧 Quick Fixes

"Pre-commit hook failed"

npm run lint:fix      # Auto-fix issues
git add .
git commit -m "your message"

"TypeScript errors"

npm run type-check    # See all errors
# Fix the errors in your editor

"Tests failing"

npm test              # See which tests fail
# Fix the code or update tests

"ESLint errors"

npm run lint          # See errors
npm run lint:fix      # Auto-fix what's possible
# Manually fix remaining issues

---

📋 Pre-Push Checklist

Before pushing to GitHub:

• npm run lint ✅
• npm run type-check ✅
• npm run build ✅
• npm test ✅

One-liner:

npm run lint && npm run type-check && npm run build && npm test -- --run

---

🎯 When Things Go Wrong

CI Failed on GitHub

1. Go to repository → Actions tab
2. Click the failed workflow
3. Read the error logs
4. Fix locally, test, then push again

Can't Commit

• Pre-commit hook is blocking
• Run npm run lint:fix
• Or bypass (emergency): git commit --no-verify

TypeScript Strict Mode Complaints

• Fix the type errors (recommended)
• Or add type assertions (not recommended)

const data = apiResponse as MyType; // Last resort

---

📁 Important Files

File	Purpose
.eslintrc.json	ESLint config (frontend)
backend/.eslintrc.json	ESLint config (backend)
.prettierrc	Code formatting rules
tsconfig.json	TypeScript config (strict mode enabled)
.husky/pre-commit	Git pre-commit hook
.github/workflows/ci.yml	CI/CD pipeline
components/common/ErrorBoundary.tsx	Error boundary component
backend/utils/errors.js	Custom error classes

---

🧪 Writing Tests

Backend Model Test

// backend/models/__tests__/MyModel.test.js
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import MyModel from '../MyModel.js';
import { query } from '../../database/db.js';

describe('MyModel', () => {
  beforeEach(async () => {
    await query('DELETE FROM my_table WHERE id LIKE $1', ['TEST-%']);
  });

  it('should do something', async () => {
    const result = await MyModel.doSomething();
    expect(result).toBeDefined();
  });

  afterEach(async () => {
    await query('DELETE FROM my_table WHERE id LIKE $1', ['TEST-%']);
  });
});

Frontend Component Test

// components/__tests__/MyComponent.test.tsx
import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import MyComponent from '../MyComponent';

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent title="Hello" />);
    expect(screen.getByText('Hello')).toBeInTheDocument();
  });
});

---

🔐 Using Error Classes

Backend Route with Error Handling

const { ValidationError, NotFoundError } = require('./utils/errors');

router.get('/api/cycles/:id', async (req, res, next) => {
  try {
    const { id } = req.params;

    if (!id) {
      throw new ValidationError('Cycle ID is required');
    }

    const cycle = await Cycle.getById(id);

    if (!cycle) {
      throw new NotFoundError('Cycle');
    }

    res.json({ success: true, data: cycle });
  } catch (error) {
    next(error); // Error handler sanitizes for client
  }
});

---

🛡️ Error Boundary Usage

Wrap Risky Components

import ErrorBoundary from '@/components/common/ErrorBoundary';

function MyPage() {
  return (
    <ErrorBoundary>
      <RiskyComponent />
    </ErrorBoundary>
  );
}

// Custom fallback
<ErrorBoundary fallback={<div>Oops, data loading failed</div>}>
  <DataTable />
</ErrorBoundary>;

---

📊 Viewing Test Coverage

npm run test:coverage
# Opens HTML report in coverage/index.html

Coverage Goals:

• Critical models: >80%
• Utility functions: >80%
• Components: >50%

---

🎨 Code Style Tips

Auto-format on save (VS Code)

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Disable ESLint for one line

// eslint-disable-next-line @typescript-eslint/no-explicit-any
const data: any = legacyApi();

Disable TypeScript for one line

// @ts-ignore
const result = oldCode();

---

🚨 Emergency Procedures

Disable Pre-commit Hooks Temporarily

git commit --no-verify -m "emergency fix"

Skip TypeScript Errors Temporarily

Comment out in tsconfig.json:

{
  "compilerOptions": {
    // "strict": true,  // Commented temporarily
  }
}

Remember to re-enable!

---

📞 Getting Help

ESLint issues: Check .eslintrc.json rules
TypeScript errors: Check tsconfig.json compiler options
Test failures: Check test files in __tests__/ directories
CI failures: Check GitHub Actions logs

Full documentation: See QUALITY_IMPROVEMENTS.md