javascript-refactoring

Files (1)

• SKILL.md

SKILL.md (first lines)

# JavaScript Code Refactoring Guide

This guide explains how to refactor JavaScript code into a separate `.cjs` file in the gh-aw repository. Follow these steps when extracting shared functionality or creating new JavaScript modules.

## Overview

The gh-aw project uses CommonJS modules (`.cjs` files) for JavaScript code that runs in GitHub Actions workflows. These files are:
- Embedded in the Go binary using `//go:embed` directives
- Bundled using a custom JavaScript bundler that inlines local `require()` calls
- Executed in GitHub Actions using `actions/github-script@v8`

### Top-Level Script Pattern

Top-level `.cjs` scripts (those that are executed directly in workflows) follow a specific pattern:

**✅ Correct Pattern - Export main, but don't call it:**
```javascript
async function main() {
  // Script logic here
  core.info("Running the script");
}

module.exports = { main };
```

**❌ Incorrect Pattern - Don't call main in the file:**
```javascript
async function main() {
  // Script logic here
  core.info("Running the script");
}

await main(); // ❌ Don't do this!

module.exports = { main };
```

**Why this pattern?**
- The bundler automatically injects `await main()` during inline execution in GitHub Actions
- This allows the script to be both imported (for testing) and executed (in workflows)
- It provides a clean separation between module definition and execution
- It enables better testing by allowing tests to import and call `main()` with mocks

**Examples of top-level scripts:**
- `create_issue.cjs` - Creates GitHub issues
- `add_comment.cjs` - Adds comments to issues/PRs
- `add_labels.cjs` - Adds labels to issues/PRs
- `update_project.cjs` - Updates GitHub Projects

All of these files export `main` but do not call it directly.

## Step 1: Create the New .cjs File

Create your new file in `/home/runner/work/gh-aw/gh-aw/pkg/workflow/js/` with a descriptive name:

**File naming convention:**
- Use snake_case for filenames (e.g., `sanitize_content.cjs`, `load_agent_output.cjs`)
- Use `.cjs` extension (CommonJS module)
- Choose names that clearly describe the module's purpose

**Example file structure:**
```javascript
// @ts-check
/// <reference types="@actions/github-script" />

/**
 * Brief description of what this module does
 */

/**
 * Function documentation
 * @param {string} input - Description of parameter
 * @returns {string} Description of return value
 */
function myFunction(input) {
  // Implementation
  return input;
}

// Export the function(s)
module.exports = {
  myFunction,
};
```

**Key points:**
- Include `// @ts-check` for TypeScript checking
- Include `/// <reference types="@actions/github-script" />` for GitHub Actions types
- Use JSDoc comments for documentation
- Export functions using `module.exports = { ... }`
- Do NOT import `@actions/core` or `@actions/github` - these are available globally in GitHub Actions

## Step 2: Add Tests

Create a test file with the same base name plus `.test.cjs`:

**Example: `pkg/workflow/js/my_module.test.cjs`**
```javascript
import { describe, it, expect, beforeEach, vi } from "vitest";

// Mock the global objects that GitHub Actions provides
const mockCore = {
  debug: vi.fn(),
  info: vi.fn(),
  warning: vi.fn(),
  error: vi.fn(),
  setFailed: vi.fn(),
  setOutput: vi.fn(),
  summary: {
    addRaw: vi.fn().mockReturnThis(),
    write: vi.fn().mockResolvedValue(),
  },
};

// Set up global mocks before importing the module
global.core = mockCore;

describe("myFunction", () => {

From az9713/gh-aw, MIT.

More from az9713/gh-aw