Fix JSDoc return type annotations in close_expired_*.cjs

[Copilot]

TypeScript type checking failed because JSDoc annotations declared the search functions returned an array, but they actually return an object with discussions/issues and stats properties.

Changes

Fixed return type annotations:

• searchDiscussionsWithExpiration() in close_expired_discussions.cjs
• searchIssuesWithExpiration() in close_expired_issues.cjs

Before:

@returns {Promise<Array<{id: string, number: number, ...}>>}

After:

@returns {Promise<{discussions: Array<{...}>, stats: {pageCount: number, totalScanned: number}}>}

Cleanup:

• Removed duplicate require("./error_helpers.cjs") statements on line 39 (already imported on line 4)

The functions return this structure, which now matches the JSDoc:

return {
  discussions,  // or issues
  stats: {
    pageCount,
    totalScanned,
  },
};

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[CI Failure Doctor] TypeScript Type Check Failure in close_expired_*.cjs - JSDoc Return Type Mismatch (Run #21033922615)</issue_title>
<issue_description># 🏥 CI Failure Investigation - Run githubnext/gh-aw#21033922615

Summary

TypeScript type checking failed in the js job due to incorrect JSDoc return type annotations in two JavaScript files modified by PR #10069.

Failure Details

• Run: 21033922615
• Commit: b149d67
• PR: Add comprehensive logging and step summaries to expired issues/discussions cleanup scripts #10069 - "Add comprehensive logging and step summaries to expired issues/discussions cleanup scripts"
• Author: Copilot (github-actions bot)
• Merged: 2026-01-15T13:59:40Z
• Trigger: push to main branch
• Failed Job: js
• Failed Step: Run tests (step Weekly Research Report: AI Workflow Automation Landscape and Market Opportunities - August 2025 #7)
• Duration: 20 seconds

Root Cause Analysis

The CI failure was caused by incorrect JSDoc type annotations in two functions that were modified to add comprehensive logging:

Affected Files

1. actions/setup/js/close_expired_discussions.cjs
2. actions/setup/js/close_expired_issues.cjs

The Problem

Both files declare their search functions with incorrect return type annotations:

Declared (line 30):

@returns {Promise<Array<{id: string, number: number, title: string, url: string, body: string, createdAt: string}>>}

Actual return (lines 118-124):

return {
  discussions,  // or issues
  stats: {
    pageCount,
    totalScanned,
  },
};

The functions return an object with two properties (discussions/issues and stats), but the JSDoc declares they return just an array.

TypeScript Errors

close_expired_discussions.cjs:119:5 - error TS2353: Object literal may only specify known properties, and 'discussions' does not exist in type '{ id: string; number: number; title: string; url: string; body: string; createdAt: string; }[]'.

close_expired_discussions.cjs:215:11 - error TS2339: Property 'discussions' does not exist on type '{ id: string; number: number; title: string; url: string; body: string; createdAt: string; }[]'.

close_expired_discussions.cjs:215:51 - error TS2339: Property 'stats' does not exist on type '{ id: string; number: number; title: string; url: string; body: string; createdAt: string; }[]'.

(Same 3 errors for close_expired_issues.cjs)

Failed Jobs and Errors

Job: js

• ✅ Set up job
• ✅ Checkout code
• ✅ Set up Node.js
• ✅ Report Node cache status
• ✅ Install npm dependencies
• ✅ Setup prompt templates for tests
• ❌ Run tests - TypeScript compilation failed with 6 errors

Investigation Findings

Primary Issue

The PR added comprehensive logging and step summaries, which included modifying the return structure of the search functions to include statistics. However, the JSDoc type annotations were not updated to reflect this change.

Secondary Issue (Non-Breaking)

Both files have duplicate require statements:

• Line 4: const { getErrorMessage } = require("./error_helpers.cjs");
• Line 39: const { getErrorMessage } = require("./error_helpers.cjs"); ← Duplicate

This doesn't cause the failure but should be cleaned up.

Recommended Actions

Immediate Fix Required

Update JSDoc annotations in both files:

For close_expired_discussions.cjs (line 30):

/**
 * Search for open discussions with expiration markers
 * @param {any} github - GitHub GraphQL instance
 * @param {string} owner - Repository owner
 * @param {string} repo - Repository name
 * @returns {Promise<{discussions: Array<{id: string, number: number, title: string, url: string, body: string, createdAt: string}>, stats: {pageCount: number, totalScanned: number}}>}
 */

For close_expired_issues.cjs (line 30):

/**
 * Search for open issues with expiration markers
 * @param {any} github - GitHub GraphQL instance
 * @param {string} owner - Repository owner
 * @param {string} repo - Repository name
 * @returns {Promise<{issues: Array<{id: string, number: number, title: string, url: string, body: string, createdAt: string}>, stats: {pageCount: number, totalScanned: number}}>}
 */

Optional Cleanup

• Remove duplicate require statements on line 39 in both files (the one at line 4 is sufficient)

Prevention Strategies

For AI Coding Agents (Copilot)

This failure could have been prevented by following the mandatory pre-commit checklist:

1. ALWAYS run make agent-finish before committing JavaScript changes

   • This runs: build, test, recompile, fmt, lint
   • The npm test step includes TypeScript type checking

2. Minimum requirement for JavaScript files: Run npm test in actions/setup/js/

   • This would have caught the TypeScript errors immediately

3. When modifying return types: Always update corresp...

• Fixes [CI Failure Doctor] TypeScript Type Check Failure in close_expired_*.cjs - JSDoc Return Type Mismatch (Run #21033922615) #10082

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.