refactor: Expand and refactor next-issue-recommendation bot

[parvninama]

Summary:

• This PR refactors the next-issue recommendation bot to improve scalability, maintainability, and contributor guidance. It extends support beyond beginner-level issues to include intermediate and advanced recommendations, introduces cross-repository support, and replaces hardcoded logic with a configuration-driven design.

Changes:

• Added support for beginner, intermediate, and advanced issue recommendations
• Implemented eligibility-based progression (contributors must complete required issues to level up)
• Introduced structured fallback strategy:
  • level up → same level → other repos → level down (bounded)
• Enabled cross-repository recommendations with repo-specific label mapping
• Refactored monolithic script into modular structure:
  • core/ (recommendation, eligibility)
  • api/ (GitHub API)
  • helpers/ (utils, PR helpers, comments)
  • centralized config and labels
• Reduced hardcoding and improved flexibility for future scaling
• Hardened GitHub Actions workflow

Testing:

1. Basic recommendation flow

   • merged PR linked to beginner issue
   • comment successfully posted
   • PR: chore: Testing next issue recommendation bot parvninama/hiero-sdk-python#109
   • Log: https://github.com/parvninama/hiero-sdk-python/actions/runs/25500716216/job/74832520049

2. Eligibility progression

   • beginner completion unlocks intermediate recommendations
   • PR: chore: Testing next issue Eligibility progression for recommendation bot parvninama/hiero-sdk-python#113
   • Log: https://github.com/parvninama/hiero-sdk-python/actions/runs/25547147306/job/74986027343

3. Cross-repo fallback

   • no suitable issues in python repo
   • fallback recommends from cpp repo
   • PR: chore: Testing cross repo fallback for next issue recommendation parvninama/hiero-sdk-python#115
   • Log: https://github.com/parvninama/hiero-sdk-python/actions/runs/25547625465/job/74987593675

4. No recommendable issues available

   • PR: chore: Testing No issues available for next issue recommendation bot parvninama/hiero-sdk-python#120
   • Log: https://github.com/parvninama/hiero-sdk-python/actions/runs/25552781969/job/75004432740

Linked Issue

• Fixes [Advanced]: Expand and Refactor .github/scripts/bot-next-issue-recommendation.js #1891

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 93 complexity

Metric	Results
Complexity	93

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[parvninama]

@exploreriii I noticed PR #2213 introduces a utils/ folder for Python-based workflow helpers

In this PR I’ve structured the JS bot logic under .github/scripts/shared (e.g. core/, helpers/). Since these are handling different concerns (workflow utilities vs recommendation logic), do we want to standardize naming or structure to avoid confusion as this grows?

Not blocking anything—just thinking ahead as the scripts here continue to grow across shell, Python, and JS

[github-actions]

Hello, this is the OfficeHourBot.

This is a reminder that the Hiero Python SDK Office Hours are scheduled in approximately 4 hours (14:00 UTC).

This session provides an opportunity to ask questions regarding this Pull Request.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.

From,
The Python SDK Team

[exploreriii]

Hi @parvninama this structure is good, we can slowly migrate in this direction, can I mark this ready for review?

[exploreriii]

have you tested this please parv?

[parvninama]

have you tested this please parv?

I’ve tested the core recommendation logic locally with lightweight Node test files and also validated the main flows manually with mocked inputs/logging.
I haven’t completed full end-to-end testing with real merged PR events yet since pull_request_target workflows are limited in forks due to permissions, but I’ll also be testing this flow using real merged PR events before finalizing.

[parvninama]

Curious to hear other opinions on this tradeoff as well — whether we should prioritize broader pagination for recommendation accuracy, or keep the current bounded/scalable approach for lower API usage across repos and fallback steps.

[coderabbitai]

Actionable comments posted: 3

♻️ Duplicate comments (2)

.github/scripts/shared/config.js (1)

60-76: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

repositoryUrl still duplicates owner/repo.

If owner or repo is updated in this entry, repositoryUrl must be hand-edited too, and a mismatch would silently break the "Star this repository" / "Watch for new issues" links posted in PR comments. Either derive it in buildRecommendationComment from owner/repo, or interpolate it here so there is a single source of truth.

♻️ Proposed refactor — derive in builder, drop from config

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

-  const {
-    repositoryUrl: repoUrl = '',
-    communityLinks = {},
-    botSignature = 'Hiero Team',
-  } = homeRepo;
+  const { communityLinks = {}, botSignature = 'Hiero Team' } = homeRepo;
+  const repoUrl = homeRepo.owner && homeRepo.repo
+    ? `https://github.com/${homeRepo.owner}/${homeRepo.repo}`
+    : '';

And in config.js:

       isHome: true,
-      repositoryUrl: 'https://github.com/hiero-ledger/hiero-sdk-python',
         communityLinks: {

.github/scripts/shared/helpers/utils.js (1)

14-16: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

repoLabelFor still throws when repoConfig.labels is undefined.

validateRepoLabels in config.js tolerates a missing labels field (repo.labels ?? {}), so a repo entry without labels will pass module init and then crash here at every call site (filterIssuesByLevel, passesBypassCheck, getHighestSkillLevelKey, detectUnlockedLevel) with a TypeError. The optional chain needs to extend to labels.

🛡️ Proposed fix

 function repoLabelFor(repoConfig, levelKey) {
-  return repoConfig?.labels[levelKey] ?? null;
+  return repoConfig?.labels?.[levelKey] ?? null;
 }

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2d2fae9d-0de4-4c1a-aef2-1c1eef5c3d80

📥 Commits

Reviewing files that changed from the base of the PR and between 70dbab8 and 42c6f13.

📒 Files selected for processing (10)

• .github/scripts/bot-next-issue-recommendation.js
• .github/scripts/shared/api/github-api.js
• .github/scripts/shared/config.js
• .github/scripts/shared/core/eligibility.js
• .github/scripts/shared/core/recommendation.js
• .github/scripts/shared/helpers/comment.js
• .github/scripts/shared/helpers/pr-helpers.js
• .github/scripts/shared/helpers/utils.js
• .github/scripts/shared/helpers/validation.js
• .github/scripts/tests/recommendation.test.js

[aceppaluni]

@parvninama This LGTM! Great job with testing!

Please update your branch so we can merge, thank you!

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 563678d6-3395-4ec8-aa75-8061462099ea

📥 Commits

Reviewing files that changed from the base of the PR and between 42c6f13 and b8fc59f.

📒 Files selected for processing (4)

• .github/scripts/bot-next-issue-recommendation.js
• .github/scripts/shared/api/github-api.js
• .github/scripts/shared/helpers/comment.js
• .github/scripts/tests/recommendation.test.js

[github-actions]

👋 Hi @parvninama! Great work completing a Advanced issue! 🎉

Thanks for your contribution! 🚀

Here are some issues you might want to explore next:

• [Intermediate]: Normalize Mnemonic Passphrases to NFKD
• [Intermediate]: Integrate `include-what-you-use` into CMake Build System
• [Intermediate]: Add HIP-869 Dynamic Address Book Example
• [Intermediate]: Add HIP-632 Hedera Account Service (HAS) System Contract Example
• [Intermediate]: Support Jumbo EthereumTransaction (HIP-1086)

🌟 Stay connected:

• ⭐ Star this repository
• 👀 Watch for new issues
• 💬 Join us on Discord

Happy coding! 🚀
— Hiero Python SDK Team