Merge pull request #148 from exploreriii/shared-libraries-guards

chore: added eligibility flexible guards, routing and logging extensive

Author: exploreriii

.github/scripts/lib/comments/rejection-router.js

@@ -12,18 +12,29 @@ const REJECTION_REASONS =
 
 const rejectionRouter = ({ reason, context = {}, username, urls = {} }) => {
     switch (reason) {
-        // ───── Beginner → Intermediate ladder
+        // ─────────────────────────────────────────
+        // Beginner eligibility failures
+        // ─────────────────────────────────────────
         case REJECTION_REASONS.MISSING_GFI:
+            return beginnerRejection({
+                username,
+                completedGfiCount: context.completedGfiCount ?? 0,
+                browseGfiUrl: urls.gfi,
+            });
+
+        // ─────────────────────────────────────────
+        // Intermediate eligibility failures
+        // ─────────────────────────────────────────
         case REJECTION_REASONS.MISSING_BEGINNER:
             return intermediateRejection({
                 username,
-                requiredGfiCount: context.requiredGfiCount ?? 1,
                 requiredBeginnerCount: context.requiredBeginnerCount ?? 1,
-                browseGfiUrl: urls.gfi,
                 browseBeginnerUrl: urls.beginner,
             });
 
-        // ───── Intermediate → Advanced ladder
+        // ─────────────────────────────────────────
+        // Advanced eligibility failures
+        // ─────────────────────────────────────────
         case REJECTION_REASONS.MISSING_INTERMEDIATE:
             return advancedRejection({
                 username,
@@ -49,7 +60,7 @@ const rejectionRouter = ({ reason, context = {}, username, urls = {} }) => {
             });
 
         // ─────────────────────────────────────────
-        // Spam attempting non-GFI assignment
+        // Spam attempting disallowed assignment
         // ─────────────────────────────────────────
         case REJECTION_REASONS.SPAM:
             return spamNonGfiAssignment(username);

.github/scripts/lib/eligibility/has-eligibility-01-gfi.js

@@ -1,8 +1,41 @@
+/**
+ * Determines whether a contributor is eligible to be assigned
+ * a Good First Issue (GFI).
+ *
+ * ELIGIBILITY RULES:
+ * - Repository team members (triage / write / maintain / admin)
+ *   always bypass GFI eligibility checks.
+ * - Spam-listed contributors may have at most
+ *   `MAX_OPEN_ISSUES_SPAM_LIST` open GFI assignments.
+ * - All other contributors may have at most
+ *   `MAX_OPEN_ISSUES_NORMAL` open GFI assignments.
+ *
+ * IMPORTANT:
+ * - This helper is policy-only.
+ * - It does NOT assign issues.
+ * - It does NOT post comments.
+ * - Callers must route rejections via `rejectionRouter`.
+ *
+ * @param {Object} params
+ * @param {import('@actions/github').GitHub} params.github
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.username
+ * @returns {Promise<{
+ *   eligible: boolean,
+ *   reason?: string,
+ *   context?: Object
+ * }>}
+ */
 const { isTeam } = require('../team/has-team');
 const { isOnSpamList } = require('../counts/is-on-spam-list');
-const { countOpenAssignedIssues } = require('../counts/count-opened-assigned-issues');
+const { countOpenAssignedIssues } =
+    require('../counts/count-opened-assigned-issues');
 const REJECTION_REASONS = require('./rejection-reasons');
 
+// ─────────────────────────────────────────────
+// Policy configuration
+// ─────────────────────────────────────────────
 const MAX_OPEN_ISSUES_NORMAL = 2;
 const MAX_OPEN_ISSUES_SPAM_LIST = 1;
 
@@ -12,10 +45,26 @@ const hasGfiEligibility = async ({
     repo,
     username,
 }) => {
+    console.log('[has-gfi-eligibility] Start', {
+        owner,
+        repo,
+        username,
+    });
+
+    // ─────────────────────────────────────────────
+    // Team members bypass all GFI restrictions
+    // ─────────────────────────────────────────────
     if (await isTeam({ github, owner, repo, username })) {
+        console.log('[has-gfi-eligibility] Bypass: team member', {
+            username,
+        });
+
         return { eligible: true };
     }
 
+    // ─────────────────────────────────────────────
+    // Spam list evaluation
+    // ─────────────────────────────────────────────
     const isSpamListed = await isOnSpamList({
         github,
         owner,
@@ -27,14 +76,28 @@ const hasGfiEligibility = async ({
         ? MAX_OPEN_ISSUES_SPAM_LIST
         : MAX_OPEN_ISSUES_NORMAL;
 
+    // ─────────────────────────────────────────────
+    // Capacity check
+    // ─────────────────────────────────────────────
     const openAssignedCount = await countOpenAssignedIssues({
         github,
         owner,
         repo,
         username,
     });
 
+    console.log('[has-gfi-eligibility] Capacity evaluation', {
+        username,
+        isSpamListed,
+        openAssignedCount,
+        maxAllowed,
+    });
+
     if (openAssignedCount >= maxAllowed) {
+        console.log('[has-gfi-eligibility] Rejected: capacity exceeded', {
+            username,
+        });
+
         return {
             eligible: false,
             reason: REJECTION_REASONS.CAPACITY,
@@ -46,6 +109,13 @@ const hasGfiEligibility = async ({
         };
     }
 
+    // ─────────────────────────────────────────────
+    // Eligible
+    // ─────────────────────────────────────────────
+    console.log('[has-gfi-eligibility] Eligible', {
+        username,
+    });
+
     return { eligible: true };
 };
 

.github/scripts/lib/eligibility/has-eligibility-02-beginner.js

@@ -1,9 +1,35 @@
+/**
+ * Determines whether a contributor is eligible to be assigned
+ * a Beginner issue.
+ *
+ * ELIGIBILITY RULES:
+ * - Team members bypass all checks
+ * - Spam-listed users are never eligible
+ * - Max open assignments enforced
+ * - Must have completed at least N Good First Issues
+ *
+ * @param {Object} params
+ * @param {import('@actions/github').GitHub} params.github
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.username
+ * @returns {Promise<{
+ *   eligible: boolean,
+ *   reason?: string,
+ *   context?: Object
+ * }>}
+ */
 const { isTeam } = require('../team/has-team');
 const { isOnSpamList } = require('../counts/is-on-spam-list');
-const { hasCompletedGfi } = require('../counts/has-completed-n-01-gfi');
-const { countOpenAssignedIssues } = require('../counts/count-opened-assigned-issues');
+const { hasCompletedGfi } =
+    require('../counts/has-completed-n-01-gfi');
+const { countOpenAssignedIssues } =
+    require('../counts/count-opened-assigned-issues');
 const REJECTION_REASONS = require('./rejection-reasons');
 
+// ─────────────────────────────────────────────
+// Policy configuration
+// ─────────────────────────────────────────────
 const MAX_OPEN_ASSIGNED_ISSUES = 2;
 const REQUIRED_GFI_COUNT = 1;
 
@@ -19,39 +45,73 @@ const hasBeginnerEligibility = async ({
         username,
     });
 
+    // ─────────────────────────────────────────────
     // Team members bypass everything
+    // ─────────────────────────────────────────────
     if (await isTeam({ github, owner, repo, username })) {
+        console.log('[has-beginner-eligibility] Bypass: team member', {
+            username,
+        });
+
         return { eligible: true };
     }
 
+    // ─────────────────────────────────────────────
     // Spam-listed users are never eligible
-    if (await isOnSpamList({ github, owner, repo, username })) {
+    // ─────────────────────────────────────────────
+    const isSpamListed = await isOnSpamList({
+        github,
+        owner,
+        repo,
+        username,
+    });
+
+    if (isSpamListed) {
+        console.log('[has-beginner-eligibility] Rejected: spam listed', {
+            username,
+        });
+
         return {
             eligible: false,
             reason: REJECTION_REASONS.SPAM,
         };
     }
 
+    // ─────────────────────────────────────────────
     // Capacity check
+    // ─────────────────────────────────────────────
     const openAssignedCount = await countOpenAssignedIssues({
         github,
         owner,
         repo,
         username,
     });
 
+    console.log('[has-beginner-eligibility] Capacity evaluation', {
+        username,
+        openAssignedCount,
+        maxAllowed: MAX_OPEN_ASSIGNED_ISSUES,
+    });
+
     if (openAssignedCount >= MAX_OPEN_ASSIGNED_ISSUES) {
+        console.log('[has-beginner-eligibility] Rejected: capacity exceeded', {
+            username,
+        });
+
         return {
             eligible: false,
             reason: REJECTION_REASONS.CAPACITY,
             context: {
                 openAssignedCount,
                 maxAllowed: MAX_OPEN_ASSIGNED_ISSUES,
+                isSpamListed: false,
             },
         };
     }
 
+    // ─────────────────────────────────────────────
     // GFI prerequisite
+    // ─────────────────────────────────────────────
     const hasRequiredGfi = await hasCompletedGfi({
         github,
         owner,
@@ -60,18 +120,34 @@ const hasBeginnerEligibility = async ({
         requiredCount: REQUIRED_GFI_COUNT,
     });
 
+    console.log('[has-beginner-eligibility] GFI prerequisite', {
+        username,
+        requiredGfiCount: REQUIRED_GFI_COUNT,
+        satisfied: hasRequiredGfi,
+    });
+
     if (!hasRequiredGfi) {
+        console.log('[has-beginner-eligibility] Rejected: missing GFI', {
+            username,
+        });
+
         return {
             eligible: false,
             reason: REJECTION_REASONS.MISSING_GFI,
             context: {
-                completedGfiCount: 0, // safe fallback
+                requiredGfiCount: REQUIRED_GFI_COUNT,
             },
         };
     }
 
+    // ─────────────────────────────────────────────
+    // Eligible
+    // ─────────────────────────────────────────────
+    console.log('[has-beginner-eligibility] Eligible', {
+        username,
+    });
+
     return { eligible: true };
 };
 
 module.exports = { hasBeginnerEligibility };
-