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

[github-actions]

🏥 CI Failure Investigation - Run #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 corresponding JSDoc annotations

Root Cause of Prevention Failure

PR #10069 was likely committed without running the test suite. The AGENTS.md file clearly states:

**🚨 BEFORE EVERY COMMIT - NO EXCEPTIONS:**
make agent-finish  # Runs build, test, recompile, fmt, lint

This is precisely the type of failure this check is designed to prevent.

AI Team Self-Improvement

Add these additional instructions to AGENTS.md for AI coding agents:

### JavaScript Type Safety

**CRITICAL - TypeScript JSDoc Type Checking:**

When modifying JavaScript (.cjs) files:

1. **Return Type Changes**: If you modify what a function returns, ALWAYS update the `@returns` JSDoc annotation to match
   
2. **Type Check Before Commit**: Run `cd actions/setup/js && npm run typecheck` to catch type mismatches
   
3. **Common Pitfall**: Changing from returning an array to returning an object with properties (or vice versa) without updating JSDoc
   
   ❌ WRONG:
   ```javascript
   @returns {Promise<Array<Item>>}
   async function search() {
     return { items: [], stats: {} }; // Type mismatch!
   }

✅ CORRECT:

@returns {Promise<{items: Array<Item>, stats: Object}>}
async function search() {
  return { items: [], stats: {} };
}

4. Pre-Commit Validation: The npm test command runs typecheck first, so running make agent-finish will catch these errors

5. No Shortcuts: Even for "minor" changes to JavaScript files, type checking is mandatory

## Historical Context

This is a **new type of failure** - while there have been previous JS test failures (see issue #9965), those were related to actual test execution, not TypeScript compilation errors.

**Similar Past Failures:**
- Issue #9965: JS test failures (46 tests failing) - different root cause
- Multiple lint-go failures in January 2026 - formatting issues

**Key Difference:**
This failure is specifically about JSDoc type annotation mismatch, which is preventable by running the test suite before committing.

## Pattern Classification

- **Category**: Code Issue - Type System Violation
- **Severity**: Medium (blocks CI but easy to fix)
- **Frequency**: First occurrence of this specific pattern
- **Fix Complexity**: Low (simple JSDoc update)
- **Prevention**: Mandatory test execution before commit

---

**Investigation completed**: 2026-01-15T14:06:00Z  
**Status**: Ready for fix




> AI generated by [CI Failure Doctor](https://github.com/githubnext/gh-aw/actions/runs/21034098033)
>
> To add this workflow in your repository, run `gh aw add githubnext/agentics/workflows/ci-doctor.md@ea350161ad5dcc9624cf510f134c6a9e39a6f94d`. See [usage guide](https://githubnext.github.io/gh-aw/tools/cli/).

<!-- agentic-workflow: CI Failure Doctor, engine: copilot, run: https://github.com/githubnext/gh-aw/actions/runs/21034098033 -->