diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000000..57c6cafa40 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,41 @@ +--- +name: Bug Report +about: Create a report to help us improve +title: "[BUG] " +labels: bug +assignees: "" + +--- + +## Bug Description +A clear and concise description of what the bug is. + +## Steps to Reproduce +1. Go to "..." +2. Click on "..." +3. Scroll down to "..." +4. See error + +## Expected Behavior +A clear and concise description of what you expected to happen. + +## Actual Behavior +A clear and concise description of what actually happened. + +## Screenshots +If applicable, add screenshots to help explain your problem. + +## Environment +- OS: [e.g. iOS, Windows, Linux] +- Browser: [e.g. Chrome, Firefox, Safari] +- Version: [e.g. 22] +- Node.js version: [e.g. 18.17.0] + +## Additional Context +Add any other context about the problem here. + +## Logs +``` +Paste relevant logs here +``` + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000000..e5f154b52e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,35 @@ +--- +name: Feature Request +about: Suggest an idea for this project +title: "[FEATURE] " +labels: enhancement +assignees: "" + +--- + +## Feature Description +A clear and concise description of what you want to happen. + +## Problem Statement +Is your feature request related to a problem? Please describe. +A clear and concise description of what the problem is. Ex. I am always frustrated when [...] + +## Proposed Solution +Describe the solution you would like +A clear and concise description of what you want to happen. + +## Alternatives Considered +Describe alternatives you have considered +A clear and concise description of any alternative solutions or features you have considered. + +## Benefits +- Benefit 1 +- Benefit 2 +- Benefit 3 + +## Implementation Notes +Any specific technical considerations or implementation details. + +## Additional Context +Add any other context or screenshots about the feature request here. + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..5b08ca7560 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,42 @@ +## Description +Brief description of the changes in this PR. + +## Type of Change +- [ ] ๐Ÿ› Bug fix (non-breaking change which fixes an issue) +- [ ] โœจ New feature (non-breaking change which adds functionality) +- [ ] ๐Ÿ’ฅ Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] ๐Ÿ“š Documentation update +- [ ] ๐Ÿ”ง Refactor (code change that neither fixes a bug nor adds a feature) +- [ ] โšก Performance improvement +- [ ] ๐Ÿงช Test addition or update + +## Changes Made +- Change 1 +- Change 2 +- Change 3 + +## Testing +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Visual regression tests passed +- [ ] Manual testing completed + +## Screenshots (if applicable) +Please add screenshots to help explain your changes. + +## Checklist +- [ ] My code follows the project style guidelines +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published + +## Related Issues +Closes #(issue_number) + +## Additional Notes +Any additional information that might be helpful for reviewers. + diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml new file mode 100644 index 0000000000..8cec04bbb6 --- /dev/null +++ b/.github/workflows/ci-cd.yml @@ -0,0 +1,153 @@ +name: CI/CD Pipeline + +on: + push: + branches: [leader, main] + pull_request: + branches: [leader, main] + +jobs: + # 1. Fast, parallel validation for linting and unit tests + unit_tests: + runs-on: ubuntu-latest # 2-core runner is sufficient for fast tests + strategy: + matrix: + node-version: [18.x, 20.x] + + steps: + - name: Checkout Code + uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: "npm" + + - name: Install Dependencies + # The `npm ci` is fast enough if caching is effective. + run: npm ci + + - name: Run Linting and Formatting Checks + run: | + npm run lint + npm run format:check + + - name: Run Unit Tests + run: npm run test:coverage + + - name: Upload Coverage (runs only once per matrix iteration) + uses: codecov/codecov-action@v3 + with: + # Use a flag to differentiate coverage runs in Codecov UI + flags: node-${{ matrix.node-version }}-unittests + file: ./coverage/lcov.info + + # 2. Sequential, resource-heavy build and E2E/visual tests (runs only once) + build_and_e2e: + needs: [unit_tests] + # For self-hosted or larger runners, specify here: + # runs-on: self-hosted-8core + runs-on: ubuntu-latest # Consider upgrading this to ubuntu-latest-8-cores for speed + + # We only need the latest, validated Node version here. + steps: + - name: Checkout Code + uses: actions/checkout@v4 + + - name: Setup Node.js 20.x + uses: actions/setup-node@v4 + with: + node-version: "20.x" + cache: "npm" + + - name: Install Dependencies + run: npm ci + + - name: ๐Ÿ—๏ธ Next.js Production Build Cache Restore + # This is the most critical step for performance. + # Utilize the Next.js cache feature for subsequent runs. + uses: actions/cache/restore@v3 + with: + path: | + .next/cache + key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/*.ts', '**/*.tsx') }} + restore-keys: | + ${{ runner.os }}-nextjs- + + - name: Execute Build + run: npm run build + + - name: ๐Ÿ’พ Save Next.js Build Cache + uses: actions/cache/save@v3 + with: + path: .next/cache + key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/*.ts', '**/*.tsx') }} + + - name: ๐Ÿ–ผ๏ธ Run Visual Regression Tests (Playwright) + # This step should only run once after a successful build. + # You may want to configure Playwright to cache its browser binaries too. + run: npm run test:visual + + - name: Upload Test Artifacts on Failure + uses: actions/upload-artifact@v4 + if: failure() + with: + name: test-artifacts + path: | + tests/playwright/screenshots/ + tests/playwright/test-results/ + + - name: ๐Ÿ“ฆ Upload Build Artifact + uses: actions/upload-artifact@v4 + with: + name: production-build-output + path: | + .next/ + dist/ + node_modules/ + package.json + pnpm-lock.yaml + next.config.js + ecosystem.config.cjs + + # 3. Security remains separate + security: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20.x" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Run security audit + run: npm audit --audit-level=high + + - name: Run custom security scan + run: ./scripts/security-audit.sh || true + + # 4. Deployment now depends on the single build step + # deploy: + # needs: [build_and_e2e, security] + # runs-on: ubuntu-latest + # if: github.ref == "refs/heads/leader" && github.event_name == "push" + + # steps: + # # NOTE: You no longer need to run `npm ci` and `npm run build` here. + # # The artifact from `build_and_e2e` should be used. + + # - name: โฌ‡๏ธ Download Build Artifact + # uses: actions/download-artifact@v4 + # with: + # name: production-build-output + # path: . + + # - name: Deploy Notification + # run: echo "Deployment would happen here, using the downloaded build artifact." \ No newline at end of file diff --git a/.github/workflows/pr-quality.yml b/.github/workflows/pr-quality.yml new file mode 100644 index 0000000000..42571ef436 --- /dev/null +++ b/.github/workflows/pr-quality.yml @@ -0,0 +1,47 @@ +name: PR Quality Gate + +on: + workflow_dispatch: + +jobs: + pr-quality: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20.x" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Check PR title format + run: | + # This check is informational for manual runs. + # In a real PR context, you would use github.event.pull_request.title + echo "Note: This check is for a manual run. In a PR, it would validate the title." + + - name: Check for large files + run: | + find . -type f -size +1M -not -path "./node_modules/*" -not -path "./.git/*" | while read file; do + echo "::warning::Large file detected: $file ($(du -h "$file" | cut -f1))" + done + + - name: Lint commit messages + run: | + echo "Note: This check is for a manual run. In a PR, it would lint commit messages." + if git rev-parse --verify HEAD~1 >/dev/null 2>&1; then + git log --oneline HEAD~1..HEAD | while read line; do + if [[ ! "$line" =~ ^[a-f0-9]+\ (feat|fix|docs|style|refactor|test|chore|perf|ci)(\(.+\))?: ]]; then + echo "::warning::Commit message should follow conventional commits: $line" + fi + done + fi + diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml new file mode 100644 index 0000000000..c5329c21d8 --- /dev/null +++ b/.github/workflows/security-scan.yml @@ -0,0 +1,55 @@ +name: Dependency Security Scan + +on: + schedule: + - cron: "0 6 * * 1" # Every Monday at 6 AM + workflow_dispatch: # Allow manual trigger + +jobs: + security-scan: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20.x" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Run comprehensive security audit + run: | + echo "## Security Audit Report - $(date)" >> $GITHUB_STEP_SUMMARY + echo "### NPM Audit" >> $GITHUB_STEP_SUMMARY + npm audit --audit-level=low --json > audit.json || true + echo "\`\`\`json" >> $GITHUB_STEP_SUMMARY + cat audit.json >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY + + - name: Check for security vulnerabilities + run: | + VULNERABILITIES=$(npm audit --audit-level=high --json | jq ".metadata.vulnerabilities.total") + echo "Found $VULNERABILITIES high+ severity vulnerabilities" + if [ "$VULNERABILITIES" -gt 0 ]; then + echo "::warning::Found $VULNERABILITIES high+ severity vulnerabilities" + npm audit --audit-level=high + fi + + - name: Create issue on security findings + if: failure() + uses: actions/github-script@v6 + with: + script: | + github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: "Security Vulnerabilities Detected - Weekly Scan", + body: "Automated security scan has detected vulnerabilities. Please review the audit report and update dependencies accordingly.\n\nScan date: " + new Date().toISOString(), + labels: ["security", "automated"] + }) + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..46b5e5f3c1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,208 @@ +# Contributing to HRM + +Thank you for your interest in contributing to the HRM (Heart Rate Monitor) project! This document provides guidelines and instructions for contributing to this project. + +## Development Setup + +1. **Clone the repository** + ```bash + git clone https://github.com/arii/hrm.git + cd hrm + ``` + +2. **Install dependencies** + ```bash + npm install + ``` + +3. **Set up environment variables** + ```bash + cp .env.example .env.local + # Edit .env.local with your configuration + ``` + +4. **Start development server** + ```bash + npm run dev + ``` + +## Code Style and Standards + +### TypeScript +- Use strict TypeScript configuration +- Prefer explicit types over `any` +- Use interfaces for object shapes +- Follow naming conventions (camelCase for variables, PascalCase for components) + +### React Components +- Use functional components with hooks +- Prefer named exports over default exports for components +- Keep components small and focused +- Use TypeScript for prop types + +### Code Formatting +- We use Prettier for code formatting +- ESLint for code linting +- Run `npm run format` before committing +- Run `npm run lint:fix` to fix linting issues + +## Testing + +### Running Tests +```bash +# Run all tests +npm test + +# Run tests with coverage +npm run test:coverage + +# Run tests in watch mode +npm run test:watch + +# Run visual regression tests +npm run test:visual +``` + +### Writing Tests +- Write unit tests for utilities and hooks +- Write integration tests for components +- Aim for 70%+ code coverage +- Use Testing Library best practices +- Mock external dependencies appropriately + +## Commit Message Format + +We use [Conventional Commits](https://conventionalcommits.org/) format: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +### Types: +- `feat`: A new feature +- `fix`: A bug fix +- `docs`: Documentation only changes +- `style`: Changes that do not affect the meaning of the code +- `refactor`: A code change that neither fixes a bug nor adds a feature +- `perf`: A code change that improves performance +- `test`: Adding missing tests or correcting existing tests +- `chore`: Changes to the build process or auxiliary tools + +### Examples: +``` +feat(timer): add pause functionality to Tabata timer +fix(websocket): resolve connection drop on network change +docs: update API documentation for WebSocket events +test: add unit tests for timer utilities +``` + +## Pull Request Process + +1. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** + - Write clean, well-documented code + - Add tests for new functionality + - Update documentation as needed + +3. **Test your changes** + ```bash + npm run lint + npm run test:coverage + npm run build + npm run test:visual + ``` + +4. **Commit your changes** + ```bash + git add . + git commit -m "feat: your descriptive commit message" + ``` + +5. **Push to your branch** + ```bash + git push origin feature/your-feature-name + ``` + +6. **Create a Pull Request** + - Use the PR template + - Provide clear description of changes + - Link related issues + - Request appropriate reviewers + +## Code Review Process + +- All changes require review before merging +- Address all review feedback +- Ensure CI checks pass +- Maintain code coverage thresholds +- Update documentation for user-facing changes + +## Issue Reporting + +### Bug Reports +- Use the bug report template +- Provide clear reproduction steps +- Include environment details +- Attach screenshots if applicable + +### Feature Requests +- Use the feature request template +- Explain the problem being solved +- Describe proposed solution +- Consider implementation complexity + +## Release Process + +1. **Version Bumping** + - Follow semantic versioning (semver) + - Update CHANGELOG.md + - Update package.json version + +2. **Testing** + - Ensure all tests pass + - Run full regression testing + - Verify deployment builds + +3. **Documentation** + - Update README if needed + - Update API documentation + - Update migration guides + +## Getting Help + +- Join our development discussions in issues +- Ask questions in pull request comments +- Review existing documentation and issues first + +## Code of Conduct + +- Be respectful and inclusive +- Focus on what is best for the community +- Show empathy towards other community members +- Accept constructive criticism gracefully + +## Development Tools + +### Recommended VS Code Extensions +- TypeScript and JavaScript Language Features +- ESLint +- Prettier +- GitLens +- Thunder Client (for API testing) + +### Git Workflow +- Use descriptive branch names +- Rebase feature branches before merging +- Keep commits atomic and focused +- Write meaningful commit messages + +Thank you for contributing to HRM! ๐ŸŽ‰ + diff --git a/test-proof.json b/test-proof.json deleted file mode 100644 index 5fb04f13ce..0000000000 --- a/test-proof.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "version": "1.0", - "timestamp": "2025-11-28T08:46:23.920Z", - "sourceHash": "70c0f15f519324ad863fe364df4f0b074e584244", - "status": "success", - "details": { - "infrastructure": { - "total": 4, - "passed": 4, - "failed": 0 - }, - "simple-smoke": { - "total": 1, - "passed": 1, - "failed": 0 - }, - "spotify-debug": { - "total": 2, - "passed": 2, - "failed": 0 - }, - "visual-regression": { - "total": 6, - "passed": 6, - "failed": 0 - } - } -} \ No newline at end of file