[Beginner]: Bot inactivity comments can be abstracted #1598

🐥 Beginner Friendly

This issue is a great fit for contributors who are ready to explore the Hiero C++ codebase a little more and take on slightly more independent work.

Beginner Issues often involve reading existing C++ code, understanding how different parts of the SDK fit together, and making small, thoughtful updates that follow established patterns.

The goal is to support skill growth while keeping the experience approachable, well-scoped, and enjoyable.

👾 Description of the Task

The bot inactivity logic in .github/scripts/bot-inactivity.js is long (703 lines) and mixes comment-building with execution logic. The file currently defines four comment builders inline:

• buildWarningComment
• buildClosureComment
• buildLinkedPRClosedComment
• buildBlockedCheckinComment

along with their related HTML markers:

const WARN_MARKER            = '<!-- bot:inactivity-warning -->';
const BLOCKED_CHECKIN_MARKER = '<!-- bot:blocked-checkin -->';

Other bots in the repo separate the comment-building logic from the execution logic — see the *.js ↔ *-comments.js pairs in .github/scripts/commands/ (assign, finalize, unassign). bot-inactivity.js is the only bot script that hasn't done this yet. Following the same convention here would make the file easier to read, easier to test, and consistent with the rest of the bot system.

Relevant files:

.github/scripts/bot-inactivity.js
.github/scripts/tests/test-inactivity-bot.js

💡 Proposed Approach

Extract the four builders and the two HTML markers into a new sibling file, and have bot-inactivity.js import them.

Placement: the new file should live at the top level as .github/scripts/bot-inactivity-comments.js, colocated next to bot-inactivity.js. It does not belong under commands/ — that directory backs contributor-issued slash commands (/assign, /finalize, /unassign), and the inactivity bot is scheduled, not command-driven. The colocated top-level placement keeps the comment builders next to their consumer (which is the readability win the commands/ pattern provides) and preserves the bot- prefix that signals scheduled execution.

What moves: the four builder functions and the two HTML marker constants. Internal helpers used only by the builders (if any) move with them.

What stays: the duration constants at .github/scripts/bot-inactivity.js:47-49 — WARN_AFTER_MS, CLOSE_AFTER_MS, BLOCKED_CHECKIN_AFTER_MS. These are also used by handleStaleItem and handleBlockedItem, so they should remain a single source of truth in bot-inactivity.js. The builders should accept duration values as parameters rather than importing the constants back from the comments file.

👩‍💻 Implementation Steps

• Create new file .github/scripts/bot-inactivity-comments.js. Copy the SPDX header and a short top-of-file comment matching the style of commands/assign-comments.js.
• Move the following from bot-inactivity.js into the new file:
  - WARN_MARKER
  - BLOCKED_CHECKIN_MARKER
  - buildWarningComment
  - buildClosureComment
  - buildLinkedPRClosedComment
  - buildBlockedCheckinComment
• Update the builder signatures so any duration values they format come in as parameters rather than reading module-level constants. (Today buildWarningComment reads WARN_AFTER_MS and CLOSE_AFTER_MS, and buildClosureComment reads CLOSE_AFTER_MS — these should be passed in.)
• Add a module.exports block listing the moved markers and builders.
• In bot-inactivity.js, replace the inline definitions with a require('./bot-inactivity-comments') import.
• Update the call sites in handleStaleItem and handleBlockedItem to pass the duration constants into the builders.
• Run the bot script test suite locally:
  bash cd .github/scripts && npm test
• Lint:
  bash cd .github/scripts && npx eslint .
• Open a pull request referencing this issue.

✔️ Acceptance Criteria

• .github/scripts/bot-inactivity-comments.js exists at the top level, colocated with bot-inactivity.js.
• The four builders and the two HTML markers live in the new file.
• bot-inactivity.js imports them and no longer defines them inline.
• Duration constants (WARN_AFTER_MS, CLOSE_AFTER_MS, BLOCKED_CHECKIN_AFTER_MS) remain in bot-inactivity.js.
• Existing tests in tests/test-inactivity-bot.js continue to pass without behavioral changes (require-path adjustments are fine if needed).
• ESLint is clean.
• No behavioral change to any inactivity comment — warn, close, linked-PR-closed, and blocked-checkin comments render identically before and after.
• No unrelated changes to bot logic or other files.

📋 Step-by-Step Contribution Guide

To help keep contributions consistent and easy to review, we recommend following these steps:

• Comment /assign to request the issue
• Wait for assignment
• Fork the repository and create a branch
• Set up the project using the instructions in README.md
• Make the requested changes
• Sign each commit using -s -S
• Push your branch and open a pull request

Read Workflow Guide for step-by-step workflow guidance.
Read README.md for setup instructions.

❗ Pull requests cannot be merged without S and s signed commits.
See the Signing Guide.

🤔 Additional Information

This issue follows the same shape as #1577 (light refactor of bot-on-comment.js).

There is a related but independent piece of cleanup tracked separately: .github/scripts/helpers/comments.js is misnamed (it's the PR Helper Bot's dashboard renderer, not a generic helper) and helpers/api.js reaches into it, which is a coupling smell. That cleanup is intermediate-level work and does not block this issue — either can land first.

If you have questions while working on this issue, feel free to ask!

You can reach the community and maintainers here: Hiero-SDK-C++ Discord

Whether you need help finding the right file, understanding existing code, or confirming your approach — we're happy to help.