Skip to content

docs: update documentation for accuracy and completeness #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jamie-BitFlight merged 1 commit into from
Jan 25, 2026
Merged

docs: update documentation for accuracy and completeness #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 43 additions & 11 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,14 @@ Usage example in a workflow:

### Core Classes (src/)

- **`Jira`** - Wrapper around `jira.js` Version2Client. Handles all Jira API calls including fetching/creating versions and updating issue fixVersions.
- **`Issue`** - Represents a single Jira issue. Fetches current fixVersions, applies new versions, and tracks before/after state for reporting.
- **`EventManager`** - Parses issue keys from input, applies project filters (include/exclude), and orchestrates the fixVersion update process.
- **`Action`** - Entry point. Creates Jira client and EventManager, executes the update workflow.
- **`index.ts`** - Entry point that imports Action and input-helper, executes the action workflow, and handles top-level error reporting via `core.setFailed()`.
- **`action.ts`** - Main action orchestrator. Creates Jira client and EventManager, executes the fixVersion update workflow.
- **`Jira.ts`** - Wrapper around `jira.js` Version2Client. Handles all Jira API calls including fetching/creating versions and updating issue fixVersions.
- **`Issue.ts`** - Represents a single Jira issue. Fetches current fixVersions, applies new versions, and tracks before/after state for reporting.
- **`EventManager.ts`** - Parses issue keys from input, applies project filters (include/exclude), and orchestrates the fixVersion update process.
- **`input-helper.ts`** - Parses and validates GitHub Action inputs from environment variables (`JIRA_BASE_URL`, `JIRA_API_TOKEN`, `JIRA_USER_EMAIL`, `GITHUB_TOKEN`, `GITHUB_WORKSPACE`) and action inputs (`jira_base_url`, `jira_api_token`, `jira_user_email`, `token`, `projects`, `projects_ignore`, `fix_versions`, `issues`, `fail_on_error`).
- **`fs-helper.ts`** - File system utilities providing `existsSync()`, `directoryExistsSync()`, `fileExistsSync()`, and `loadFileSync()` with input validation and error handling.
- **`utils.ts`** - General utility functions including `issueIdRegEx` (Jira issue key regex pattern), `isError()` (type guard for Node.js errors), `toCommaDelimitedString()`, `nullIfEmpty()`, and `formatDate()` (ISO 8601 date formatting).

### Key Dependency: jira.js

Expand Down Expand Up @@ -61,18 +65,28 @@ yarn lint:markdown # Check markdown syntax
yarn lint:markdown:fix # Auto-fix markdown issues

# Unit tests (Vitest, mocked Jira)
yarn test
yarn test:watch
yarn test -- --testNamePattern="pattern" # Run specific test
yarn test # Run all tests
yarn test:watch # Run tests in watch mode
yarn test -- --testNamePattern="pattern" # Run specific test by name
yarn test:unit # Run unit tests only (sets defaults, handles missing)
yarn test:integration # Run integration tests only (GitHub Event)
yarn test-ci # Run tests with JUnit reporter for CI (outputs junit.xml)

# Full build + validation pipeline
yarn all # Build, format, lint, package, and test in sequence

# Commit helper
yarn commit # Interactive conventional commit helper (git-cz)

# E2E tests (requires Docker and Playwright)
yarn e2e:up # Start Jira + MySQL containers
yarn e2e:setup # Run Playwright setup wizard automation
yarn e2e:setup # Run Playwright setup wizard automation (headless Chromium)
yarn e2e:setup:http # Alternative HTTP-based Jira setup (non-Playwright, uses direct HTTP/database)
yarn e2e:wait # Wait for Jira API ready
yarn e2e:seed # Create test project/issues
yarn e2e:test # Run E2E test suite
yarn e2e:logs # Show Docker container logs
yarn e2e:down # Stop containers
yarn e2e:down # Stop containers and remove volumes
yarn e2e:all # Full E2E sequence (up -> setup -> wait -> seed -> test)
yarn e2e:fast # Fast E2E (restore from snapshots if valid, else full setup)

Expand All @@ -86,24 +100,42 @@ yarn e2e:snapshot:save # Save current Docker volumes as snapshots

### Unit Tests

Located in `__tests__/`. Uses Vitest with mocked Jira client via `vi.mock('../src/Jira')`. Mock data is inline in test files due to Vitest hoisting. Test fixtures are in `__tests__/fixtures/`.
Located in `__tests__/`. Uses Vitest with mocked Jira client via `vi.mock('../src/Jira')`. Test fixtures are in `__tests__/fixtures/`.

**Mock Infrastructure** (`__tests__/mocks/`):

- `jira-api.ts` - Provides mock implementations for Jira class methods, including `mockJiraData` (in-memory storage for issues, projects, versions), `resetMockData()`, `setupDefaultMockData()`, and `createMockJiraInstance()` factory function for creating fully-mocked Jira clients.

### E2E Tests

Located in `e2e/`. Uses a Dockerized Jira Data Center instance (`haxqer/jira:9.17.5`).

**E2E Scripts** (`e2e/scripts/`):

- `e2e-config.ts` - Central E2E configuration interface. Defines `E2EConfig` type and `getE2EConfig()` function that returns Data Center config (basic auth) by default, or Jira Cloud config when `E2E_JIRA_EMAIL` and `E2E_JIRA_API_TOKEN` environment variables are set.
- `setup-jira-playwright.ts` - Automates Jira setup wizard via headless Chromium (handles XSRF)
- `setup-jira.ts` - Alternative HTTP-based Jira setup. Uses direct HTTP requests and database insertion to configure Jira without Playwright. Handles license generation via atlassian-agent, database license insertion, container restart, and admin account setup.
- `jira-client.ts` - E2E test client using jira.js (same library as main action)
- `seed-jira.ts` - Creates test project, versions, and issues
- `wait-for-jira.ts` - Polls until Jira API is ready
- `snapshot-*.ts` - Docker volume snapshot management for CI caching
- `snapshot-check.ts` - Validates Docker volume snapshots
- `snapshot-save.ts` - Saves Docker volumes as snapshots
- `snapshot-restore.ts` - Restores Docker volumes from snapshots

**E2E Test Files** (`e2e/tests/`):

- `fixversion.e2e.test.ts` - Tests fixVersion creation and assignment via the Jira API

## CI Workflows

Located in `.github/workflows/`:

- **`ci.yml`** - Main CI pipeline. Runs on PRs to main/develop and pushes to main. Includes validate job (type check, lint, build, verify dist up-to-date) and unit tests.
- **`unit-tests.yml`** - Standalone unit test runner. Runs on PRs to main/develop and pushes to main. Executes `yarn test` and builds.
- **`e2e-jira.yml`** - E2E tests with Dockerized Jira Data Center. Supports snapshot restore for faster runs. Has `skip_snapshots` workflow_dispatch input to force full setup.
- **`build-e2e-snapshots.yml`** - Scheduled workflow (every 5 days at 3am UTC) to build and upload E2E Docker volume snapshots. Supports `force_rebuild` workflow_dispatch input.
- **`push_code_linting.yml`** - Biome linting on pull requests with reviewdog integration for PR review comments.

Comment on lines +129 to +138
Copy link

Copilot AI Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new "CI Workflows" list is incomplete: the repo also contains workflows like claude.yml, claude-code-review.yml, create_tag.yml, publish_action.yml, pull_request_cleanup_tags_and_releases.yml, and respond-to-ci-failures.yml under .github/workflows/. Either add the missing workflow files here, or clarify that this section lists only the primary CI workflows (and update the PR description accordingly).

Copilot uses AI. Check for mistakes.
## Build and TypeScript Configuration

- **Build System**: Rollup with TypeScript plugin (see `rollup.config.ts`)
Expand Down
30 changes: 30 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,3 +79,33 @@ This action will add the supplied list of FixVersions to the list of Jira Issue
TODO:

- [ ] Add a `operation` input that can take an `add`, `set`, or `remove` modifier for the list of fixversions, for how to treat the list of FixVersions supplied. Append would add any new fixversions to the issues fixversions list, replace removes existing fix versions first, and remove would remove any fix versions from the issue that are supplied from the input list of fix_versions

## Development

### Prerequisites

- Node.js >= 22.0.0
- Yarn package manager
- Docker (for E2E tests)

### Available Scripts

```bash
yarn build # Build the action (Rollup ESM bundle)
yarn test # Run unit tests (Vitest)
yarn lint # Check linting (Biome)
yarn lint:fix # Auto-fix linting issues
yarn format # Format code (Biome)
yarn e2e:all # Run full E2E test suite
```

### Tooling

- **Biome** for linting and formatting (replaces ESLint + Prettier)
- **Vitest** for unit testing (replaces Jest)
- **Rollup** for bundling (ESM output)

### Node Version Note

- Development requires **Node 22+**
- GitHub Actions runtime uses **Node 20** (GitHub doesn't support node22 yet)
Comment on lines +83 to +111
Copy link

@coderabbitai coderabbitai bot Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Minor wording polish for Node version note.

The last bullet uses “node22”; consider capitalizing for consistency with earlier lines.

✏️ Proposed edit 
-- GitHub Actions runtime uses **Node 20** (GitHub doesn't support node22 yet)
+- GitHub Actions runtime uses **Node 20** (GitHub doesn't support Node 22 yet)
🧰 Tools
🪛 LanguageTool

[grammar] ~111-~111: Ensure spelling is correct
Context: ...ses Node 20 (GitHub doesn't support node22 yet)

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents 
In `@README.md` around lines 83 - 111, In the "Node Version Note" section of the
README, the last bullet uses lowercase "node22"; update that bullet to use the
same capitalization as the earlier line (e.g., "Node 22" or "Node 22+"),
ensuring consistency with the "Development" prerequisites and the other Node
mentions in the file.

Comment on lines +110 to +111
Copy link

Copilot AI Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Node version note is internally inconsistent with the repo setup: workflows in .github/workflows/* already use actions/setup-node with Node 22, and action.yml specifies runs.using: node20 (action runtime), not a GitHub platform limitation. Consider rewording to distinguish (1) development/CI using Node 22 (per engines.node), vs (2) the published GitHub Action runtime being Node 20 due to runs.using: node20, and remove/adjust the "GitHub doesn't support node22 yet" claim.

Suggested change
- Development requires **Node 22+**
- GitHub Actions runtime uses **Node 20** (GitHub doesn't support node22 yet)
- Development and CI use **Node 22+** (see `engines.node` and workflows)
- The published GitHub Action runtime currently runs on **Node 20** (configured via `runs.using: node20` in `action.yml`)

Copilot uses AI. Check for mistakes.
3 changes: 2 additions & 1 deletion e2e/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,4 +365,5 @@ UI testing is brittle and slow. REST API testing is:

- [Jira REST API Documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v2/)
- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Atlassian Docker Images](https://hub.docker.com/r/atlassian/jira-software)
- [haxqer/jira Docker Image](https://hub.docker.com/r/haxqer/jira) - Third-party Jira Data Center image used by this project (`haxqer/jira:9.17.5`)
- [Atlassian Docker Images](https://hub.docker.com/r/atlassian/jira-software) - Official images (for reference; not used in this project)
Copy link

Copilot AI Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The note "Official images (for reference; not used in this project)" is inaccurate: the repo uses an official Atlassian image in docker-compose.test.yml (atlassian/jira-software:9.12-jdk17) for integration testing. Consider rewording to something narrower like "not used for the E2E Docker harness" or explicitly distinguishing E2E (haxqer) vs integration test compose (Atlassian).

Suggested change
- [Atlassian Docker Images](https://hub.docker.com/r/atlassian/jira-software) - Official images (for reference; not used in this project)
- [Atlassian Docker Images](https://hub.docker.com/r/atlassian/jira-software) - Official images (used by integration tests; not used by the E2E Docker harness)

Copilot uses AI. Check for mistakes.
Loading