# Implementation Plan

- [x] 1. Write bug condition exploration test
  - **Property 1: Bug Condition** — Jira API Compliance Violations
  - **CRITICAL**: This test MUST FAIL on unfixed code — failure confirms the bugs exist
  - **DO NOT attempt to fix the test or the code when it fails**
  - **NOTE**: This test encodes the expected behavior — it will validate the fix when it passes after implementation
  - **GOAL**: Surface counterexamples that demonstrate the three compliance violations
  - **Scoped PBT Approach**: Scope properties to the three concrete bug conditions:
    1. `searchIssues()` sends POST instead of GET — generate random JQL strings and assert the HTTP method captured is `GET` and the request path starts with `/rest/api/2/search?` with query parameters (not a JSON body)
    2. `getIssue()` sends a single-issue GET to `/rest/api/2/issue/{key}` — generate random issue keys and assert the request path contains `/rest/api/2/search` (not `/rest/api/2/issue/`)
    3. `searchIssuesByKeys()` builds JQL without `project =` — generate random arrays of issue keys and assert the JQL string passed to the search contains `project =`
  - Mock `jiraRequest` to capture HTTP method, URL path, and body arguments without making real HTTP calls
  - Use `fast-check` arbitraries to generate JQL strings, issue keys (e.g., `fc.tuple(fc.stringMatching(/^[A-Z]{2,6}$/), fc.integer({ min: 1, max: 99999 }))` for `KEY-123` patterns), and key arrays
  - Test file: `backend/__tests__/jira-api-compliance.property.test.js`
  - Run test on UNFIXED code
  - **EXPECTED OUTCOME**: Test FAILS (this is correct — it proves the bugs exist)
  - Document counterexamples found: `searchIssues()` uses POST, `getIssue()` hits `/rest/api/2/issue/{key}`, `searchIssuesByKeys()` JQL lacks `project =`
  - Mark task complete when test is written, run, and failure is documented
  - _Requirements: 1.1, 1.2, 1.3_

- [x] 2. Write preservation property tests (BEFORE implementing fix)
  - **Property 2: Preservation** — Unchanged Jira API Functions
  - **IMPORTANT**: Follow observation-first methodology
  - Observe behavior on UNFIXED code for non-buggy functions:
    - `createIssue({ project: { key: 'TEST' }, summary: 'x', issuetype: { name: 'Task' } })` sends `POST` to `/rest/api/2/issue` with JSON body containing `{ fields: {...} }`
    - `updateIssue('TEST-1', { summary: 'y' })` sends `PUT` to `/rest/api/2/issue/TEST-1` with JSON body containing `{ fields: {...} }`
    - `addComment('TEST-1', 'comment text')` sends `POST` to `/rest/api/2/issue/TEST-1/comment` with JSON body containing `{ body: 'comment text' }`
    - `transitionIssue('TEST-1', '5')` sends `POST` to `/rest/api/2/issue/TEST-1/transitions` with JSON body containing `{ transition: { id: '5' } }`
    - `getTransitions('TEST-1')` sends `GET` to `/rest/api/2/issue/TEST-1/transitions`
    - `testConnection()` sends `GET` to `/rest/api/2/myself`
  - Write property-based tests using `fast-check` that verify for all generated inputs:
    1. `createIssue()` always sends `POST /rest/api/2/issue` with `{ fields }` body — generate random field objects
    2. `updateIssue()` always sends `PUT /rest/api/2/issue/{key}` with `{ fields }` body — generate random keys and field objects
    3. `addComment()` always sends `POST /rest/api/2/issue/{key}/comment` with `{ body }` — generate random keys and comment strings
    4. `transitionIssue()` always sends `POST /rest/api/2/issue/{key}/transitions` with `{ transition: { id } }` — generate random keys and transition IDs
    5. `getTransitions()` always sends `GET /rest/api/2/issue/{key}/transitions` — generate random keys
    6. `testConnection()` always sends `GET /rest/api/2/myself`
    7. Response shape: `searchIssues()` returns `{ ok, data: { total, issues } }` and `getIssue()` returns `{ ok, data: <issue> }` — verify shape is preserved
  - Mock `jiraRequest` to capture method, path, body and return appropriate mock responses
  - Test file: `backend/__tests__/jira-api-preservation.property.test.js`
  - Verify tests pass on UNFIXED code
  - **EXPECTED OUTCOME**: Tests PASS (this confirms baseline behavior to preserve)
  - Mark task complete when tests are written, run, and passing on unfixed code
  - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10_

- [x] 3. Fix the core API helper (`backend/helpers/jiraApi.js`)

  - [x] 3.1 Convert `searchIssues()` from POST to GET with query parameters
    - Replace `jiraPost('/rest/api/2/search', body)` with `jiraGet('/rest/api/2/search?jql=...&fields=...&maxResults=...&startAt=...')`
    - URL-encode JQL string with `encodeURIComponent(jql)`
    - Comma-join and encode fields array with `encodeURIComponent(fields.join(','))`
    - Encode `maxResults` and `startAt` as query parameters
    - Remove the JSON body object `{ jql, startAt, maxResults, fields }`
    - Preserve the `res.status === 200` check and `JSON.parse(res.body)` response parsing
    - Preserve the `{ ok, data }` return shape
    - _Bug_Condition: searchIssues uses POST /rest/api/2/search with JSON body_
    - _Expected_Behavior: searchIssues uses GET /rest/api/2/search?jql=&fields=&maxResults=&startAt=_
    - _Preservation: Response shape { ok, data: { total, issues } } unchanged_
    - _Requirements: 2.1_

  - [x] 3.2 Add project scoping to `searchIssuesByKeys()` JQL
    - Change JQL from `` key in (${keyList}) AND updated >= -24h `` to `` key in (${keyList}) AND updated >= -24h AND project = ${JIRA_PROJECT_KEY} ``
    - `JIRA_PROJECT_KEY` is already available in module scope
    - _Bug_Condition: searchIssuesByKeys JQL lacks project = clause_
    - _Expected_Behavior: JQL includes project = JIRA_PROJECT_KEY_
    - _Preservation: Return shape and searchIssues delegation unchanged_
    - _Requirements: 2.2_

  - [x] 3.3 Refactor `getIssue()` to delegate to `searchIssues()` via JQL
    - Replace `jiraGet('/rest/api/2/issue/${encodeURIComponent(issueKey)}?fields=...')` with a call to `searchIssues()` using JQL `key = "${issueKey}" AND project = ${JIRA_PROJECT_KEY}` and `maxResults: 1`
    - Extract `data.issues[0]` from search results to return as `{ ok: true, data: <issue> }`
    - Return `{ ok: false, status: 404, body: 'Issue not found' }` when search returns empty results
    - Preserve the `{ ok, data: <single-issue> }` return shape for callers
    - _Bug_Condition: getIssue sends GET /rest/api/2/issue/{key} (single-issue GET)_
    - _Expected_Behavior: getIssue delegates to searchIssues with JQL key = "{key}" AND project = KEY_
    - _Preservation: Return shape { ok, data: { key, fields } } unchanged_
    - _Requirements: 2.3_

  - [x] 3.4 Verify bug condition exploration test now passes
    - **Property 1: Expected Behavior** — Jira API Compliance Violations
    - **IMPORTANT**: Re-run the SAME test from task 1 — do NOT write a new test
    - The test from task 1 encodes the expected behavior
    - When this test passes, it confirms the expected behavior is satisfied
    - Run `npx jest backend/__tests__/jira-api-compliance.property.test.js --no-cache`
    - **EXPECTED OUTCOME**: Test PASSES (confirms bugs are fixed)
    - _Requirements: 2.1, 2.2, 2.3_

  - [x] 3.5 Verify preservation tests still pass
    - **Property 2: Preservation** — Unchanged Jira API Functions
    - **IMPORTANT**: Re-run the SAME tests from task 2 — do NOT write new tests
    - Run `npx jest backend/__tests__/jira-api-preservation.property.test.js --no-cache`
    - **EXPECTED OUTCOME**: Tests PASS (confirms no regressions)
    - Confirm all unchanged functions still produce the same HTTP method, path, and body

- [x] 4. Update the UAT test script (`backend/scripts/jira-uat-test.js`)

  - [x] 4.1 Update test case 3 name to reflect JQL-based pattern
    - Change `'3. Get Single Issue (GET /issue/{key})'` to `'3. Get Single Issue (JQL search)'`
    - The test body calls `jiraApi.getIssue()` which now delegates to JQL search — no logic change needed in the test function itself
    - _Requirements: 2.4_

  - [x] 4.2 Update test case 8 name to reflect GET method
    - Change `'8. JQL Search (POST /search)'` to `'8. JQL Search (GET /search)'`
    - Add project-scoped JQL to the test: include `AND project = ${jiraApi.JIRA_PROJECT_KEY}` in the JQL string passed to `searchIssues()`
    - _Requirements: 2.5_

  - [x] 4.3 Update test case 9 to verify project scoping
    - Add a log entry or assertion that the bulk key search includes project scoping
    - The underlying `searchIssuesByKeys()` now includes `project = <KEY>` — the test validates the function works correctly with the compliant JQL
    - _Requirements: 2.5_

- [x] 5. Update the API documentation (`docs/jira-api-use-cases.md`)

  - [x] 5.1 Update compliance summary table
    - Change "Bulk reads via JQL" row endpoint from `POST /rest/api/2/search` to `GET /rest/api/2/search`
    - Add a row for "Single-issue fetch" describing JQL-based lookup via `GET /rest/api/2/search?jql=key="KEY"&...`
    - _Requirements: 2.6, 2.7_

  - [x] 5.2 Update Use Case 3 (Get Single Issue)
    - Change endpoint from `GET /rest/api/2/issue/{issueKey}?fields=...` to `GET /rest/api/2/search?jql=key="ISSUE-KEY" AND project=<KEY>&fields=...&maxResults=1`
    - Update the description to explain the JQL-based pattern
    - _Requirements: 2.7_

  - [x] 5.3 Update Use Case 8 (JQL Search / Bulk Sync)
    - Change endpoint from `POST /rest/api/2/search` to `GET /rest/api/2/search?jql=...&fields=...&maxResults=...&startAt=...`
    - Update JQL pattern to include `project = <KEY>` scoping
    - _Requirements: 2.6_

  - [x] 5.4 Update Use Case 9 (Issue Lookup)
    - Change endpoint from `GET /rest/api/2/issue/{issueKey}?fields=...` to `GET /rest/api/2/search?jql=key="ISSUE-KEY" AND project=<KEY>&fields=...&maxResults=1`
    - Update the description to match the JQL-based lookup pattern
    - _Requirements: 2.7_

- [x] 6. Checkpoint — Ensure all tests pass
  - Run `npx jest backend/__tests__/jira-api-compliance.property.test.js --no-cache` — all bug condition tests pass
  - Run `npx jest backend/__tests__/jira-api-preservation.property.test.js --no-cache` — all preservation tests pass
  - Run `npx jest --no-cache` — all existing tests in the project still pass
  - Ensure all tests pass, ask the user if questions arise.