Merge branch 'origin/main' into feat/repo-ecosystem

Author: Shivangi1515

CONTRIBUTING.md

@@ -9,6 +9,7 @@
 
 - [The Standard We Hold](#-the-standard-we-hold)
 - [Local Setup](#-local-setup)
+- [Testing Your Changes](#-testing-your-changes)
 - [What to Contribute](#-what-to-contribute)
 - [Automated Issue Management & Claiming](#-automated-issue-management--claiming)
 - [Branch & Commit Conventions](#-branch--commit-conventions)
@@ -88,6 +89,110 @@ http://localhost:3000/api/streak?user=YOUR_GITHUB_USERNAME
 
 ---
 
+## 🧪 Testing Your Changes
+
+This section covers everything you need to verify your changes work correctly **before opening a PR**. There are two layers of testing: visual browser preview and the automated test suite.
+
+### 1. Visual Browser Preview
+
+With your dev server running (`npm run dev`), open your browser and visit these URLs to preview the SVG output directly:
+
+**Standard badge — valid username:**
+
+```
+http://localhost:3000/api/streak?user=YOUR_GITHUB_USERNAME
+```
+
+**Monthly view:**
+
+```
+http://localhost:3000/api/streak?user=YOUR_GITHUB_USERNAME&view=monthly
+```
+
+**Custom theme — test your color changes:**
+
+```
+http://localhost:3000/api/streak?user=YOUR_GITHUB_USERNAME&theme=YOUR_THEME_NAME
+```
+
+**Invalid username — must render a styled SVG error card, not raw JSON:**
+
+```
+http://localhost:3000/api/streak?user=vivek%20Sangani
+```
+
+**Non-existent username — must render the ghost-city not-found badge:**
+
+```
+http://localhost:3000/api/streak?user=xyzabc999notreallll
+```
+
+> **⚠️ Browser XML error warning:** If your browser shows an `EntityRef: expecting ';'` error instead of rendering the SVG, it means an unescaped `&` character exists somewhere in the SVG output. All `&` characters inside SVG `<style>` blocks (e.g. in Google Fonts `@import` URLs) must be written as `&amp;`. Check `lib/svg/generator.ts` for any raw `&` in template literals.
+
+> **💡 Tip:** For a cleaner SVG preview, open the URL in **Firefox** — it renders SVG directly in the browser with no wrapper page. Chrome wraps it in an XML viewer which can show false parse warnings.
+
+### 2. Running the Vitest Test Suite
+
+CommitPulse uses **Vitest** for unit and integration tests. Run the full test suite with:
+
+```bash
+npm run test
+```
+
+To run tests in watch mode while you develop (reruns on every file save):
+
+```bash
+npm run test -- --watch
+```
+
+To run only a specific test file:
+
+```bash
+npm run test -- lib/calculate.test.ts
+```
+
+**What a passing run looks like:**
+
+```
+✓ lib/calculate.test.ts (12 tests)
+✓ lib/svg/generator.test.ts (8 tests)
+✓ app/api/streak/route.test.ts (6 tests)
+
+Test Files  3 passed (3)
+Tests       26 passed (26)
+```
+
+> **🚨 All tests must pass before you open a PR.** The CI pipeline runs `npm run test` automatically on every pull request and will block merging if any test fails.
+
+### 3. Interpreting SVG Output in the Browser
+
+When you open a badge URL in your browser, here is what each response means:
+
+| What you see                                 | What it means                                              |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| Animated isometric city renders correctly    | ✅ Everything is working                                   |
+| Ghost-city badge with "NOT FOUND" label      | ✅ Working — the username doesn't exist on GitHub          |
+| Styled error card with "Invalid username"    | ✅ Working — the username format was invalid               |
+| Raw JSON `{"error":"Invalid parameters"...}` | ❌ Bug — validation errors must return SVG, not JSON       |
+| Browser XML parse error / blank white page   | ❌ Bug — unescaped `&` or malformed SVG in generator       |
+| `401 Unauthorized` in the terminal           | ❌ Your `GITHUB_PAT` in `.env.local` is missing or invalid |
+
+### 4. Lint and Format
+
+Run these before every commit:
+
+```bash
+# Auto-format all files
+npm run format
+
+# Check for linting errors
+npm run lint
+```
+
+Fix every error before pushing. CI will fail if either check reports issues.
+
+---
+
 ## 🤝 Contributor Onboarding
 
 ### 📁 Project Structure

README.md

@@ -212,7 +212,7 @@ URL Parameter > Theme Default > System Fallback
 | `dark` _(default)_ | GitHub dark                 | `0d1117` | `58a6ff` | `c9d1d9` |
 | `neon`             | Cyberpunk                   | `000000` | `ff00ff` | `00ffcc` |
 | `dracula`          | Dracula Pro                 | `282a36` | `bd93f9` | `f8f8f2` |
-| `github`           | GitHub green                | `0d1117` | `238636` | `ffffff` |
+| `github`           | GitHub green                | `0d1117` | `39d353` | `ffffff` |
 | `light`            | Clean & minimal             | `ffffff` | `0969da` | `24292f` |
 | `gruvbox`          | retro warm dark             | `282828` | `fe8019` | `ebdbb2` |
 | `random`           | Surprise theme on reload    | _varies_ | _varies_ | _varies_ |

THEMES.md

@@ -16,7 +16,7 @@ https://commitpulse.vercel.app/api/badge?username=YOUR_USERNAME&theme=<slug>
 | dark         | `#0d1117`  | `#c9d1d9` | `#58a6ff` |
 | light        | `#ffffff`  | `#24292f` | `#0969da` |
 | neon         | `#000000`  | `#00ffcc` | `#ff00ff` |
-| github       | `#0d1117`  | `#ffffff` | `#238636` |
+| github       | `#0d1117`  | `#ffffff` | `#39d353` |
 | dracula      | `#282a36`  | `#f8f8f2` | `#bd93f9` |
 | ocean        | `#0a192f`  | `#ccd6f6` | `#64ffda` |
 | sunset       | `#1a0a0a`  | `#ffd6c0` | `#ff6b35` |

app/api/github/route.test.ts

@@ -29,6 +29,15 @@ describe('GET /api/github', () => {
     expect(body.error).toContain('Invalid parameters');
   });
 
+  it('returns 400 and skips GitHub when username format is invalid', async () => {
+    const response = await GET(makeRequest({ username: 'bad user' }));
+    const body = await response.json();
+
+    expect(response.status).toBe(400);
+    expect(body.error).toContain('Invalid parameters');
+    expect(getFullDashboardData).not.toHaveBeenCalled();
+  });
+
   // Test 2 — valid username → 200
   it('returns 200 with JSON body for a valid username', async () => {
     vi.mocked(getFullDashboardData).mockResolvedValue({ profile: 'octocat' } as never);

app/api/stats/route.test.ts

@@ -55,6 +55,13 @@ describe('GET /api/stats', () => {
     expect(fetchGitHubContributions).not.toHaveBeenCalled();
   });
 
+  it('returns 400 and skips GitHub when the username format is invalid', async () => {
+    const response = await GET(makeRequest({ user: 'octo/cat' }));
+
+    expect(response.status).toBe(400);
+    expect(fetchGitHubContributions).not.toHaveBeenCalled();
+  });
+
   it('returns 400 for an unknown timezone', async () => {
     const response = await GET(makeRequest({ user: 'testuser', tz: 'Not/ATimezone' }));
     expect(response.status).toBe(400);

app/api/streak/route.test.ts

@@ -437,6 +437,16 @@ describe('GET /api/streak', () => {
       });
     });
 
+    it('passes correct from/to range when ?year=2008 is provided', async () => {
+      await GET(makeRequest({ user: 'octocat', year: '2008' }));
+
+      expect(fetchGitHubContributions).toHaveBeenCalledWith('octocat', {
+        bypassCache: false,
+        from: '2008-01-01T00:00:00Z',
+        to: '2008-12-31T23:59:59Z',
+      });
+    });
+
     it('functions normally when the year parameter is missing', async () => {
       const response = await GET(makeRequest({ user: 'octocat' }));
 
@@ -670,6 +680,17 @@ describe('GET /api/streak', () => {
       expect(response.headers.get('Cache-Control')).toBe('no-store');
     });
 
+    it('sets the SVG Content-Security-Policy header on generic error responses', async () => {
+      vi.mocked(fetchGitHubContributions).mockRejectedValue(new Error('Network failure'));
+
+      const response = await GET(makeRequest({ user: 'octocat' }));
+      const csp = response.headers.get('Content-Security-Policy');
+
+      expect(response.status).toBe(500);
+      expect(csp).toContain("default-src 'none'");
+      expect(csp).not.toContain('script-src');
+    });
+
     it('returns 429 with no-cache headers and rate limit SVG when rate limited', async () => {
       vi.mocked(fetchGitHubContributions).mockRejectedValue(new Error('API Rate Limit Exceeded'));
 
@@ -1178,4 +1199,18 @@ describe('GET /api/streak', () => {
       expect(response.headers.get('Cache-Control')).not.toContain('stale-while-revalidate=86400');
     });
   });
+
+  describe('org parameter validation', () => {
+    it('returns 400 when org parameter is a User instead of an Organization', async () => {
+      vi.mocked(getOrgDashboardData).mockRejectedValueOnce(
+        new Error('This endpoint is strictly for organizations.')
+      );
+
+      const response = await GET(makeRequest({ user: 'octocat', org: 'notanorg' }));
+      expect(response.status).toBe(400);
+
+      const body = await response.text();
+      expect(body).toContain('strictly for organizations');
+    });
+  });
 });

app/api/streak/route.ts

@@ -19,7 +19,7 @@ const SVG_CSP_HEADER =
   "default-src 'none'; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com; connect-src https://fonts.gstatic.com;";
 
 // 1. Define a custom Error class for Validation
-export class ValidationError extends Error {
+class ValidationError extends Error {
   constructor(message: string) {
     super(message);
     this.name = 'ValidationError';
@@ -249,7 +249,8 @@ function buildErrorResponse(error: unknown, parseResult: ParseResult): NextRespo
   const isValidationError =
     (error instanceof Error && error.name === 'ValidationError') ||
     message.toLowerCase().includes('invalid') ||
-    message.toLowerCase().includes('validation');
+    message.toLowerCase().includes('validation') ||
+    message.toLowerCase().includes('strictly for organizations');
 
   const errBg = `#${(parseResult.success && parseResult.data.bg) || '0d1117'}`;
   const errAccent = `#${
@@ -336,6 +337,7 @@ function buildErrorResponse(error: unknown, parseResult: ParseResult): NextRespo
     headers: {
       'Content-Type': 'image/svg+xml',
       'Cache-Control': 'no-store',
+      'Content-Security-Policy': SVG_CSP_HEADER,
     },
   });
 }