chore: refactor comments and jsdocs

Signed-off-by: Parv Ninama <ninamaparv@gmail.com>

Author: parvninama

.github/scripts/shared/api/github-api.js

@@ -16,8 +16,8 @@ const { CONFIG } = require('../config');
  * @param {string} repo        - Repo name.
  * @param {string} username    - GitHub login of the contributor.
  * @param {string} labelString - Repo-specific label string to filter by.
- * @param {number} cap         - Maximum results to request (capped at 100).
- * @returns {Promise<number|null>} Count of matching issues, or null on API failure.
+ * @param {number} cap - Maximum number of results to fetch (first page only, capped at 100).
+ * @returns {Promise<number|null>} Number of fetched matching issues (not total count), or null on API failure.
  */
 async function countClosedIssuesByAssignee(github, owner, repo, username, labelString, cap) {
   try {
@@ -38,7 +38,7 @@ async function countClosedIssuesByAssignee(github, owner, repo, username, labelS
  *
  * @param {import('@actions/github').GitHub} github
  * @param {object} repoConfig - Repo entry from CONFIG.repos.
- * @returns {Promise<Array|null>} Issue array, or null on API failure.
+ * @returns {Promise<Array<object>|null>} Issue array, or null on API failure.
  */
 async function fetchIssuesBatch(github, repoConfig) {
   try {

.github/scripts/shared/config.js

@@ -47,6 +47,7 @@ const CONFIG = {
     },
   ],
 
+  repositoryUrl: 'https://github.com/hiero-ledger/hiero-sdk-python',
   maxRecommendations: 5,
   fetchPerPage:       50,
   commentMarker:      '<!-- hiero-next-issue-bot -->',

.github/scripts/shared/core/eligibility.js

@@ -8,16 +8,18 @@ const { countClosedIssuesByAssignee } = require('../api/github-api');
 
 // Fast path: user has already completed ≥1 issue at this level or higher
 async function passesBypassCheck(github, homeRepo, username, candidate) {
-  const atOrAbove = CONFIG.skillHierarchy.slice(CONFIG.skillHierarchy.indexOf(candidate));
+  const idx = CONFIG.skillHierarchy.indexOf(candidate);
+  if (idx === -1) return false;
+  const atOrAbove = CONFIG.skillHierarchy.slice(idx);
 
-  const counts = await Promise.all(
-    atOrAbove.map(key => countClosedIssuesByAssignee(
+  for (const key of atOrAbove) {
+    const count = await countClosedIssuesByAssignee(
       github, homeRepo.owner, homeRepo.repo, username,
       repoLabelFor(homeRepo, key), 1,
-    ))
-  );
-
-  return counts.some(count => count !== null && count >= 1);
+    );
+    if (count !== null && count >= 1) return true;
+  }
+  return false;
 }
 
 /**
@@ -49,7 +51,7 @@ async function passesNormalCheck(github, homeRepo, username, prereq) {
  * @param {object} homeRepo  - Home repo entry from CONFIG.repos.
  * @param {string} username  - GitHub login of the contributor.
  * @param {string} candidate - Canonical level key being evaluated.
- * @returns {Promise<boolean|null>} True if eligible, false if not, null on API failure.
+ * @returns {Promise<boolean>} True if eligible, false otherwise (API failures treated as false).
  */
 async function isEligibleFor(github, homeRepo, username, candidate) {
   const prereq = CONFIG.skillPrerequisites[candidate];
@@ -84,10 +86,10 @@ async function isEligibleFor(github, homeRepo, username, candidate) {
 async function resolveEligibleLevel(github, homeRepo, username) {
   for (const candidate of [...CONFIG.skillHierarchy].reverse()) {
     const eligible = await isEligibleFor(github, homeRepo, username, candidate);
-    // eligible === null means API failure — skip conservatively.
+    // false includes API failures (treated conservatively as ineligible)
     if (eligible === true) return candidate;
   }
-  return 'gfi';
+  return CONFIG.skillHierarchy[0];
 }
 
 /**
@@ -131,8 +133,10 @@ function adjustEligibilityForCurrentPR(completedKey, eligibleKey) {
 async function detectUnlockedLevel(github, homeRepo, username, currentLevelKey) {
   const hierarchy    = CONFIG.skillHierarchy;
   const currentIndex = hierarchy.indexOf(currentLevelKey);
-  const nextKey      = hierarchy[currentIndex + 1] ?? null;
 
+  if (currentIndex === -1) return null;
+
+  const nextKey      = hierarchy[currentIndex + 1] ?? null;
   if (!nextKey) return null;
 
   const nextPrereq = CONFIG.skillPrerequisites[nextKey];
@@ -144,6 +148,7 @@ async function detectUnlockedLevel(github, homeRepo, username, currentLevelKey)
   );
 
   if (count === null) return null;
+  // NOTE: count is derived from first-page results only; safe because requiredCount is small.
   return count === nextPrereq.requiredCount ? nextKey : null;
 }
 

.github/scripts/shared/core/recommendation.js

@@ -13,7 +13,7 @@ const {
 
 /**
  * Order: level up → same → level down (floored at beginner, capped by eligibility)
- * 
+ *
  * @param {string} completedLevelKey - Canonical key of the level just completed.
  * @param {string} eligibleLevelKey  - Adjusted eligibility ceiling.
  * @returns {number[]} Deduplicated, ordered array of hierarchy indices to try.

.github/scripts/shared/helpers/comment.js

@@ -4,18 +4,28 @@
 
 const { CONFIG } = require('../config');
 
-function buildIssueListBlock(issues) {
+function buildIssueListBlock(issues = []) {
   if (issues.length > 0) {
     return [
       'Here are some issues you might want to explore next:',
       '',
-      ...issues.map(i => `- [${i.title}](${i.html_url})`),
+      ...issues.map(i => {
+        const title = i?.title ?? 'Untitled issue';
+        const url   = i?.html_url ?? '#';
+        return `- [${title}](${url})`;
+      }),
       '',
     ];
   }
   return ['No suitable issues are available right now — check back soon!', ''];
 }
 
+/**
+ * Builds a milestone banner if a new level was unlocked.
+ *
+ * @param {string|null} unlockedLevelKey
+ * @returns {string[]} Lines to include in the comment.
+ */
 function buildMilestoneBlock(unlockedLevelKey) {
   const displayName = unlockedLevelKey
     ? CONFIG.skillPrerequisites[unlockedLevelKey]?.displayName
@@ -43,19 +53,23 @@ function buildMilestoneBlock(unlockedLevelKey) {
  * @returns {string} Fully rendered comment body.
  */
 function buildRecommendationComment(username, issues, completedDisplayName, unlockedLevelKey = null) {
+  const repoUrl = CONFIG.repositoryUrl ?? '';
+  const hasRepoUrl = Boolean(repoUrl);
   return [
     CONFIG.commentMarker,
     '',
     `👋 Hi @${username}! Great work completing a **${completedDisplayName}** issue! 🎉`,
     '',
-    'Thank you for your contribution to the Hiero Python SDK!',
+    'Thanks for your contribution! 🚀',
     '',
     ...buildMilestoneBlock(unlockedLevelKey),
     ...buildIssueListBlock(issues),
+    ...(hasRepoUrl ? [
     '🌟 **Stay connected:**',
-    '- ⭐ [Star this repository](https://github.com/hiero-ledger/hiero-sdk-python)',
-    '- 👀 [Watch for new issues](https://github.com/hiero-ledger/hiero-sdk-python/watchers)',
-    '- 💬 [Join us on Discord](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/discord.md)',
+    `- ⭐ [Star this repository](${repoUrl})`,
+    `- 👀 [Watch for new issues](${repoUrl}/watchers)`,
+    `- 💬 [Join us on Discord](${repoUrl}/blob/main/docs/discord.md)`,
+    ]:[]),
     '',
     'Happy coding! 🚀',
     '_— Hiero Python SDK Team_',

.github/scripts/shared/helpers/utils.js

@@ -4,26 +4,51 @@
 
 const { CONFIG } = require('../config');
 
+/**
+ * Returns the repo-specific label string for a given canonical level key.
+ *
+ * @param {object} repoConfig - Repo config containing label mappings.
+ * @param {string} levelKey   - Canonical skill level (e.g., 'beginner').
+ * @returns {string|null} Label string or null if not defined.
+ */
 function repoLabelFor(repoConfig, levelKey) {
-  return repoConfig.labels[levelKey];
+  return repoConfig.labels[levelKey] ?? null;
 }
 
 function hasLabel(issue, labelName) {
+  if (!labelName) return false;
+
   const target = labelName.toLowerCase();
-  return (issue.labels ?? []).some(l => l.name.toLowerCase() === target);
+  return (issue.labels ?? []).some(l => l.name?.toLowerCase() === target);
 }
 
+/**
+ * Filters issues by a specific skill level and caps the result size.
+ */
 function filterIssuesByLevel(issues, levelKey, repoConfig) {
   const labelString = repoLabelFor(repoConfig, levelKey);
+  if (!labelString) return [];
+
   return issues
     .filter(issue => hasLabel(issue, labelString))
     .slice(0, CONFIG.maxRecommendations);
 }
 
+/**
+ * Determines the highest skill level label present on an issue.
+ * Iterates from highest → lowest so the first match represents the ceiling.
+ *
+ * @param {object} issue
+ * @param {object} repoConfig
+ * @returns {string|null} Canonical level key or null if none found.
+ */
 function getHighestSkillLevelKey(issue, repoConfig) {
   return [...CONFIG.skillHierarchy]
     .reverse()
-    .find(key => hasLabel(issue, repoLabelFor(repoConfig, key))) ?? null;
+    .find(key => {
+      const label = repoLabelFor(repoConfig, key);
+      return label && hasLabel(issue, label);
+    }) ?? null;
 }
 
 module.exports = {

.github/scripts/shared/index.js

@@ -14,14 +14,11 @@ const {
 const { CONFIG } = require('./config');
 
 module.exports = {
-  // core
   getRecommendedIssues,
-  // helpers
   getHighestSkillLevelKey,
   buildRecommendationComment,
   postComment,
   alreadyCommented,
   extractLinkedIssueNumber,
-  // config
   CONFIG,
 };