merge: sync tracking test configurations with upstream main updates

Author: Sameeksha Katiyar

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/scripts/issue-management/claim-handler.js

@@ -30,9 +30,10 @@ async function handleClaim({ github, context }) {
 
   const issueAuthor = context.payload.issue.user.login;
 
-  const isAuthorJhasourav07 = issueAuthor.toLowerCase() === 'jhasourav07';
+  const MAINTAINERS = ['jhasourav07', 'aamod007', 'souravjhahind'];
+  const isOpenedByMaintainer = MAINTAINERS.includes(issueAuthor.toLowerCase());
 
-  if (!isAuthorJhasourav07 && commenter.toLowerCase() !== issueAuthor.toLowerCase()) {
+  if (!isOpenedByMaintainer && commenter.toLowerCase() !== issueAuthor.toLowerCase()) {
     await github.rest.issues.createComment({
       owner,
       repo,
@@ -89,7 +90,7 @@ async function handleClaim({ github, context }) {
     owner,
     repo,
     issue_number: issueNumber,
-    body: `✅ Successfully assigned issue to @${commenter}\n\n> 💡 Please read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md) if you haven't already. Good luck! 🚀`,
+    body: `🎉 **Assigned!** Welcome to the project, @${commenter}.\n\n⏳ **Reminder:** You have **2 days** to submit a Pull Request. After 2 days of inactivity, you will be automatically unassigned to give others a chance (as per our GSSoC anti-hoarding policy).\n\n> 💡 Please read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md) if you haven't already.\n\nHappy coding! 🚀`,
   });
 }
 

.github/scripts/issue-management/stale-assignment.js

@@ -1,6 +1,6 @@
 async function handleStaleAssignments({ github, context, core }) {
   const { owner, repo } = context.repo;
-  const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
+  const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
   const now = new Date();
 
   console.log(`Starting stale assignment check for ${owner}/${repo}`);
@@ -27,7 +27,7 @@ async function handleStaleAssignments({ github, context, core }) {
       const updatedAt = new Date(issue.updated_at);
       const timeSinceUpdate = now.getTime() - updatedAt.getTime();
 
-      if (timeSinceUpdate > THREE_DAYS_MS) {
+      if (timeSinceUpdate > TWO_DAYS_MS) {
         console.log(
           `Issue #${issue.number} has been inactive since ${issue.updated_at}. Removing assignees.`
         );

.github/workflows/assign-request-reminder.yml

@@ -42,7 +42,7 @@ jobs:
         contains(github.event.comment.body, 'can i be assigned') ||
         contains(github.event.comment.body, 'assign me to this') ||
         contains(github.event.comment.body, 'assign me this') ||
-        contains(github.event.comment.body, 'i will work on this') ||
+        contains(github.event.comment.body, 'work on this') ||
         contains(github.event.comment.body, 'i''ll work on this') ||
         contains(github.event.comment.body, 'ill work on this') ||
         contains(github.event.comment.body, 'i can work on this') ||

.github/workflows/conflict-notifier.yml

@@ -2,7 +2,12 @@ name: Merge Conflict Notifier
 
 on:
   schedule:
-    - cron: '0 * * * *'
+    - cron: '*/30 * * * *' # Hourly/half-hourly fallback
+  push:
+    branches:
+      - main
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited]
   workflow_dispatch:
 
 permissions:
@@ -76,20 +81,33 @@ jobs:
                   });
                 }
 
-                // Check if we've already posted a conflict comment to avoid spam
+                // Check existing comments to enforce a 2-hour notification gap
                 const { data: comments } = await github.rest.issues.listComments({
                   owner: context.repo.owner,
                   repo: context.repo.repo,
                   issue_number: pr.number,
                   per_page: 100,
                 });
 
-                const alreadyCommented = comments.some(c =>
+                const conflictComments = comments.filter(c =>
                   c.user?.login === 'github-actions[bot]' &&
                   c.body?.includes('merge conflicts with the main branch')
                 );
 
-                if (!alreadyCommented) {
+                let shouldComment = false;
+                if (conflictComments.length === 0) {
+                  shouldComment = true;
+                } else {
+                  const lastComment = conflictComments[conflictComments.length - 1];
+                  const lastCommentTime = new Date(lastComment.created_at).getTime();
+                  const nowTime = new Date().getTime();
+                  const TWO_HOURS_MS = 2 * 60 * 60 * 1000;
+                  if (nowTime - lastCommentTime >= TWO_HOURS_MS) {
+                    shouldComment = true;
+                  }
+                }
+
+                if (shouldComment) {
                   await github.rest.issues.createComment({
                     owner: context.repo.owner,
                     repo: context.repo.repo,

.gitignore

@@ -1,42 +1,42 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
-# dependencies
-/node_modules
-/.pnp
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/versions
-
-# testing
-/coverage
-
-# next.js
-/.next/
-/out/
-
-# production
-/build
-
-# misc
-.DS_Store
-*.pem
-
-# debug
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.pnpm-debug.log*
-
-# env files — ignore all local secrets but commit the example template
-.env*
-!.env.local.example
-
-# vercel
-.vercel
-
-# typescript
-*.tsbuildinfo
-next-env.d.ts
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files — ignore all local secrets but commit the example template
+.env*
+!.env.local.example
+.env.local
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

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
@@ -241,7 +346,7 @@ Our automation runs entirely through issue comments. Here is how you interact wi
 
 To keep the project moving, assignments are not permanent.
 
-- **The 3-Day Rule:** If an issue has an assignee but sees **no activity for 3 days**, our automated background job will remove the assignment.
+- **The 2-Day Rule:** If an issue has an assignee but sees **no activity for 2 days**, our automated background job will remove the assignment.
 - **What counts as activity?** Posting a comment, opening a linked PR, or a maintainer adding a label.
 - **Why?** It frees up stale issues so other active contributors can pick them up. If your issue expires, you can always `/claim` it again if it's still available!
 
@@ -250,7 +355,7 @@ To keep the project moving, assignments are not permanent.
 1. Create a new issue describing the bug or feature request you want to work on using our **Structured Issue Templates** (or find an open issue you authored).
 2. Comment `/claim` on the issue to lock it in.
 3. Need labels? Comment `/addlabel good-first-issue` (labels must already exist in the repo).
-4. Work on your code and submit a PR within 3 days to avoid expiry.
+4. Work on your code and submit a PR within 2 days to avoid expiry.
 5. Once your PR is merged and the issue is closed, you can create and `/claim` your next one!
 
 ### 🆘 Troubleshooting & Edge Cases

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sourav Jha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.