feat: add Phase 1 review queue label sync

Introduce a cron-based workflow (every 30 min) that classifies every
open non-draft PR into one of three review stages based on the number
and permission level of approvals:

  queue:junior-committer → queue:committers → ready-to-merge

Phase 1 of 4 — label sync only. No assignments, comments, or routing.

Label determination:
  - writeApproval >= 2 → ready-to-merge
  - anyApproval  >= 1  → queue:committers
  - else               → queue:junior-committer

Key design decisions:
  - Add-first-then-remove label ordering prevents zero-label state
  - Rate-limit guard (floor=200) prevents partial runs
  - DRY_RUN mode for safe manual testing via workflow_dispatch
  - 422/404 errors handled silently (race conditions, external users)
  - Old step:/reviewer: labels coexist intentionally until future cleanup
  - Bot-authored PRs (Dependabot) receive labels (acknowledged)

Files added:
  .github/workflows/review-sync.yml
  .github/scripts/review-sync/index.js
  .github/scripts/review-sync/labels.js

Signed-off-by: darshit2308 <darshitpatel2003@gmail.com>

Author: darshit2308

.github/scripts/review-sync/index.js

@@ -0,0 +1,126 @@
+// .github/scripts/review-sync/index.js
+//
+// Entry point for the Review Queue Label Sync cron job.
+//
+// Responsibilities:
+//   1. Rate-limit guard — abort if remaining calls < 200
+//   2. Fetch all open non-draft PRs (paginated)
+//   3. Ensure the three queue labels exist in the repo
+//   4. Sync the correct label on every PR via labels.js
+//   5. Print a summary of what changed
+//
+// Phase 1 of 4 — label sync only.
+
+const { QUEUE_LABELS, syncLabel } = require('./labels.js');
+
+const RATE_LIMIT_FLOOR = 200;
+
+/**
+ * Ensure a single label exists in the repo.
+ * Silently handles 422 (label already exists).
+ */
+async function ensureLabel(github, owner, repo, label, dryRun) {
+  try {
+    await github.rest.issues.getLabel({ owner, repo, name: label.name });
+    console.log(`  Label "${label.name}" already exists. Skipping creation.`);
+  } catch (error) {
+    if (error.status === 404) {
+      if (dryRun) {
+        console.log(`  [DRY RUN] Would create label "${label.name}" (${label.color}).`);
+        return;
+      }
+      try {
+        await github.rest.issues.createLabel({
+          owner,
+          repo,
+          name: label.name,
+          color: label.color,
+          description: label.description,
+        });
+        console.log(`  Created label "${label.name}" (#${label.color}).`);
+      } catch (createError) {
+        // 422 = label already exists (race condition or concurrent run)
+        if (createError.status === 422) {
+          console.log(`  Label "${label.name}" already exists (422). Skipping.`);
+        } else {
+          throw createError;
+        }
+      }
+    } else {
+      throw error;
+    }
+  }
+}
+
+module.exports = async ({ github, context, core }) => {
+  const dryRun = (process.env.DRY_RUN || 'false').toLowerCase() === 'true';
+  const { owner, repo } = context.repo;
+
+  if (dryRun) {
+    console.log('=== DRY RUN MODE — no labels will be created or modified ===\n');
+  }
+
+  // ── 1. Rate-limit guard ──────────────────────────────────────────────────
+  console.log('--- Rate Limit Check ---');
+  const { data: rateLimit } = await github.rest.rateLimit.get();
+  const remaining = rateLimit.resources.core.remaining;
+  console.log(`  Core API remaining: ${remaining}`);
+
+  if (remaining < RATE_LIMIT_FLOOR) {
+    console.log(`  ⚠ Skipping run: rate limit too low (${remaining} < ${RATE_LIMIT_FLOOR}).`);
+    return;
+  }
+
+  // ── 2. Fetch all open non-draft PRs (paginated) ──────────────────────────
+  console.log('\n--- Fetching Open PRs ---');
+  const allPRs = await github.paginate(github.rest.pulls.list, {
+    owner,
+    repo,
+    state: 'open',
+    per_page: 100,
+  });
+
+  const prs = allPRs.filter((pr) => !pr.draft);
+  console.log(`  Total open PRs: ${allPRs.length}`);
+  console.log(`  Non-draft PRs to process: ${prs.length}`);
+  console.log(`  Draft PRs skipped: ${allPRs.length - prs.length}`);
+
+  if (prs.length === 0) {
+    console.log('  No non-draft PRs found. Exiting.');
+    return;
+  }
+
+  // ── 3. Ensure queue labels exist ─────────────────────────────────────────
+  console.log('\n--- Ensuring Queue Labels Exist ---');
+  for (const label of Object.values(QUEUE_LABELS)) {
+    await ensureLabel(github, owner, repo, label, dryRun);
+  }
+
+  // ── 4. Sync label on each PR ─────────────────────────────────────────────
+  console.log('\n--- Syncing Labels ---');
+  let changed = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for (const pr of prs) {
+    try {
+      const didChange = await syncLabel(github, owner, repo, pr, dryRun);
+      if (didChange) {
+        changed++;
+      } else {
+        skipped++;
+      }
+    } catch (error) {
+      errors++;
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  ✗ Error on PR #${pr.number}: ${message}`);
+    }
+  }
+
+  // ── 5. Summary ───────────────────────────────────────────────────────────
+  console.log('\n=== Summary ===');
+  console.log(`  PRs processed: ${prs.length}`);
+  console.log(`  Labels changed: ${changed}`);
+  console.log(`  Labels already correct: ${skipped}`);
+  console.log(`  Errors: ${errors}`);
+};

.github/scripts/review-sync/labels.js

@@ -0,0 +1,252 @@
+// .github/scripts/review-sync/labels.js
+//
+// Core label determination and application for the Review Queue Sync.
+//
+// Logic (Phase 1 — simplified, no difficulty routing):
+//   1. Fetch all reviews on a PR (paginated)
+//   2. Build username → latest review state map
+//   3. Ignore COMMENTED and DISMISSED
+//   4. For each APPROVED reviewer, check permission level
+//   5. Determine correct queue label based on approval counts
+//   6. Apply label: add new FIRST, then remove stale (non-negotiable order)
+//
+// Phase 2 will add difficulty-based routing on top of this logic.
+
+/**
+ * The three mutually exclusive queue labels managed by this bot.
+ * Colours and names match the Phase 1 specification.
+ */
+const QUEUE_LABELS = {
+  JUNIOR: {
+    name: 'queue:junior-committer',
+    color: 'e4e669',
+    description: 'PR awaiting initial quality review',
+  },
+  COMMITTERS: {
+    name: 'queue:committers',
+    color: '0075ca',
+    description: 'PR awaiting committer technical review',
+  },
+  MERGE: {
+    name: 'ready-to-merge',
+    color: '0e8a16',
+    description: 'PR has 2+ write approvals and is ready to merge',
+  },
+};
+
+/** All queue label names, used for cleanup operations. */
+const ALL_QUEUE_LABEL_NAMES = Object.values(QUEUE_LABELS).map((l) => l.name);
+
+/**
+ * Fetch all reviews on a PR, returning only the latest state per reviewer.
+ * COMMENTED and DISMISSED reviews are discarded entirely.
+ *
+ * @param {object} github   - Octokit instance
+ * @param {string} owner    - Repository owner
+ * @param {string} repo     - Repository name
+ * @param {number} prNumber - Pull request number
+ * @returns {Map<string, string>} username → latest review state (APPROVED | CHANGES_REQUESTED)
+ */
+async function getLatestReviewStates(github, owner, repo, prNumber) {
+  const reviews = await github.paginate(github.rest.pulls.listReviews, {
+    owner,
+    repo,
+    pull_number: prNumber,
+    per_page: 100,
+  });
+
+  // Build a map keyed by reviewer login.
+  // Reviews come back sorted by submitted_at ascending, so later entries
+  // naturally overwrite earlier ones — giving us the latest state per user.
+  const latestByUser = new Map();
+
+  for (const review of reviews) {
+    const login = review.user?.login;
+    const state = review.state?.toUpperCase();
+
+    if (!login || !state) continue;
+
+    // Only track actionable states
+    if (state === 'APPROVED' || state === 'CHANGES_REQUESTED') {
+      latestByUser.set(login, state);
+    }
+    // COMMENTED and DISMISSED are intentionally ignored
+  }
+
+  return latestByUser;
+}
+
+/**
+ * Check the repository permission level for a given user.
+ *
+ * @param {object} github   - Octokit instance
+ * @param {string} owner    - Repository owner
+ * @param {string} repo     - Repository name
+ * @param {string} username - GitHub username
+ * @returns {string} 'admin' | 'write' | 'read' | 'none'
+ */
+async function getPermissionLevel(github, owner, repo, username) {
+  try {
+    const { data } = await github.rest.repos.getCollaboratorPermissionLevel({
+      owner,
+      repo,
+      username,
+    });
+    return data.permission || 'none';
+  } catch (error) {
+    if (error.status === 404) {
+      // External contributor — not a collaborator
+      return 'none';
+    }
+    // Log unexpected errors but don't crash the run
+    const message = error instanceof Error ? error.message : String(error);
+    console.log(`    ⚠ Permission check failed for ${username}: ${message}. Treating as "none".`);
+    return 'none';
+  }
+}
+
+/**
+ * Count approvals on a PR, split by permission level.
+ *
+ * @param {object} github   - Octokit instance
+ * @param {string} owner    - Repository owner
+ * @param {string} repo     - Repository name
+ * @param {number} prNumber - Pull request number
+ * @returns {{ writeApproval: number, softApproval: number, anyApproval: number }}
+ */
+async function countApprovals(github, owner, repo, prNumber) {
+  const latestStates = await getLatestReviewStates(github, owner, repo, prNumber);
+
+  let writeApproval = 0;
+  let softApproval = 0;
+
+  for (const [username, state] of latestStates) {
+    if (state !== 'APPROVED') continue;
+
+    const permission = await getPermissionLevel(github, owner, repo, username);
+
+    if (permission === 'admin' || permission === 'write') {
+      writeApproval++;
+    } else {
+      // read, none, or any unexpected value → soft approval
+      softApproval++;
+    }
+  }
+
+  return {
+    writeApproval,
+    softApproval,
+    anyApproval: writeApproval + softApproval,
+  };
+}
+
+/**
+ * Determine the correct queue label for a PR based on approval counts.
+ *
+ * Phase 1 logic (no difficulty routing):
+ *   writeApproval >= 2  → ready-to-merge
+ *   anyApproval  >= 1   → queue:committers
+ *   else                → queue:junior-committer
+ *
+ * @param {{ writeApproval: number, anyApproval: number }} approvals
+ * @returns {object} The correct QUEUE_LABELS entry
+ */
+function determineLabel(approvals) {
+  if (approvals.writeApproval >= 2) {
+    return QUEUE_LABELS.MERGE;
+  }
+  if (approvals.anyApproval >= 1) {
+    return QUEUE_LABELS.COMMITTERS;
+  }
+  return QUEUE_LABELS.JUNIOR;
+}
+
+/**
+ * Sync the queue label on a single PR.
+ *
+ * Order of operations (non-negotiable):
+ *   1. Check if the correct label is already present → skip if yes
+ *   2. ADD the correct label first
+ *   3. THEN remove any stale queue labels
+ *
+ * This ensures a PR never has zero queue labels, even if the process
+ * crashes mid-run.
+ *
+ * @param {object}  github - Octokit instance
+ * @param {string}  owner  - Repository owner
+ * @param {string}  repo   - Repository name
+ * @param {object}  pr     - Pull request object from the list API
+ * @param {boolean} dryRun - If true, log without making changes
+ * @returns {boolean} true if the label was changed, false if already correct
+ */
+async function syncLabel(github, owner, repo, pr, dryRun) {
+  const prNumber = pr.number;
+  const currentLabels = (pr.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+
+  // Count approvals and determine the correct label
+  const approvals = await countApprovals(github, owner, repo, prNumber);
+  const correctLabel = determineLabel(approvals);
+
+  console.log(
+    `  PR #${prNumber}: writeApproval=${approvals.writeApproval}, ` +
+    `softApproval=${approvals.softApproval}, anyApproval=${approvals.anyApproval} ` +
+    `→ ${correctLabel.name}`
+  );
+
+  // Check if the correct label is already present
+  if (currentLabels.includes(correctLabel.name)) {
+    console.log(`    ✓ Already has "${correctLabel.name}". No change needed.`);
+    return false;
+  }
+
+  // Determine which stale queue labels to remove
+  const staleLabels = currentLabels.filter(
+    (name) => ALL_QUEUE_LABEL_NAMES.includes(name) && name !== correctLabel.name
+  );
+
+  if (dryRun) {
+    console.log(`    [DRY RUN] Would add "${correctLabel.name}".`);
+    if (staleLabels.length > 0) {
+      console.log(`    [DRY RUN] Would remove: ${staleLabels.join(', ')}.`);
+    }
+    return true;
+  }
+
+  // Step 1: ADD the correct label FIRST (crash-safe: PR always has at least one label)
+  await github.rest.issues.addLabels({
+    owner,
+    repo,
+    issue_number: prNumber,
+    labels: [correctLabel.name],
+  });
+  console.log(`    + Added "${correctLabel.name}".`);
+
+  // Step 2: THEN remove stale queue labels one by one
+  for (const stale of staleLabels) {
+    try {
+      await github.rest.issues.removeLabel({
+        owner,
+        repo,
+        issue_number: prNumber,
+        name: stale,
+      });
+      console.log(`    - Removed "${stale}".`);
+    } catch (error) {
+      // 404 = label was already removed (race condition or manual action)
+      if (error.status === 404) {
+        console.log(`    - Label "${stale}" already gone (404). Skipping.`);
+      } else {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`    ✗ Failed to remove "${stale}": ${message}`);
+      }
+    }
+  }
+
+  return true;
+}
+
+module.exports = {
+  QUEUE_LABELS,
+  ALL_QUEUE_LABEL_NAMES,
+  syncLabel,
+};