Add `formatIssueId` to `IssueTracker` interface and `IssueTrackerFactory`

[NoahCardoza]

Summary

Add the core formatting infrastructure: a formatIssueId method on the IssueTracker interface and a static utility on IssueTrackerFactory.

Context

This is the foundation for provider-aware issue ID formatting (Epic #595). All other issues depend on this one.

Files to Modify

• src/lib/IssueTracker.ts — Add formatIssueId(identifier: string | number): string to interface
• src/lib/GitHubService.ts — Implement: return `#${identifier}`
• src/lib/LinearService.ts — Implement: return this.normalizeIdentifier(identifier)
• src/lib/providers/jira/JiraIssueTracker.ts — Implement: return this.normalizeIdentifier(identifier)
• src/lib/IssueTrackerFactory.ts — Add static formatIssueId(providerType: IssueTrackerProviderType, identifier: string | number): string:
  • 'github' → `#${id}`
  • 'linear' / 'jira' → String(id) (no prefix)
  • default → `#${id}`

Acceptance Criteria

• formatIssueId method added to IssueTracker interface
• All three providers implement formatIssueId correctly
• IssueTrackerFactory.formatIssueId static method works without a provider instance
• Unit tests cover each implementation:
  • GitHub: formatIssueId(123) → "#123", formatIssueId("456") → "#456"
  • Linear: formatIssueId("eng-123") → "ENG-123"
  • Jira: formatIssueId("qlh-4404") → "QLH-4404"
  • Factory: same expected behavior per provider type
• pnpm build passes
• pnpm test passes

Dependencies

None — this is the foundation issue.

[acreeger]

Starting automated workflow for this issue.

[acreeger]

Codebase Analysis

The IssueTracker interface in src/lib/IssueTracker.ts defines the contract for all issue tracking providers (GitHub, Linear). Currently there are two implementations: GitHubService and LinearService. There is no Jira provider in the codebase — IssueTrackerProviderType only includes 'github' | 'linear'. The issue references a JiraIssueTracker and normalizeIdentifier method, but neither exists yet. The IssueTrackerFactory is a static factory that creates provider instances from settings and also has a getProviderName utility.

Full Analysis

Key Files

• src/lib/IssueTracker.ts — Interface with 10 methods (core + optional PR + status). No formatIssueId method exists yet.
• src/lib/GitHubService.ts — Full implementation of IssueTracker. Prefixes issue IDs with # in user-facing strings (e.g., extractContext). 361 lines.
• src/lib/LinearService.ts — Full implementation for Linear. Uses string identifiers like ENG-123. Uppercases identifiers via toUpperCase() in detectInputType. 222 lines.
• src/lib/IssueTrackerFactory.ts — Static factory with create() and getProviderName(). No formatIssueId static method yet.
• IssueTrackerProviderType = 'github' | 'linear' — No 'jira' variant yet.

Test Patterns

• GitHubService.test.ts — 711 lines, uses vi.mock for github.js utils, creates service with mockPrompter.
• LinearService.test.ts — 68 lines, minimal tests mostly for constructor/env behavior.
• No IssueTrackerFactory.test.ts exists.

Missing Pieces for This Issue

1. No formatIssueId on IssueTracker interface
2. No normalizeIdentifier method on any service (issue references this but it doesn't exist)
3. No Jira provider at all (issue mentions JiraIssueTracker but it's not in the codebase)
4. No static formatIssueId on IssueTrackerFactory

Approach Considerations

Since Jira doesn't exist in the codebase, we should:

• Add formatIssueId to the interface
• Implement it in GitHubService (prefix with #)
• Implement it in LinearService (uppercase the identifier)
• Add the static factory method covering github, linear, and a future jira type
• Skip creating a JiraIssueTracker file since it doesn't exist (the factory method can handle the jira case)
• The IssueTrackerProviderType may need 'jira' added for the factory method signature

[acreeger]

Implementation Plan

Add formatIssueId method to the IssueTracker interface, implement it in GitHubService (prefix #) and LinearService (uppercase), then add a static formatIssueId to IssueTrackerFactory that works without a provider instance. Add 'jira' to IssueTrackerProviderType so the factory method can handle it. Write tests for all implementations.

Full Plan

Step 1: src/lib/IssueTracker.ts

• Add formatIssueId(identifier: string | number): string to the interface

Step 2: src/lib/GitHubService.ts

• Add method: formatIssueId(identifier: string | number): string returning `#${identifier}`

Step 3: src/lib/LinearService.ts

• Add method: formatIssueId(identifier: string | number): string returning String(identifier).toUpperCase()
• This normalizes eng-123 -> ENG-123 matching existing Linear uppercasing pattern in detectInputType

Step 4: src/lib/IssueTrackerFactory.ts

• Add 'jira' to IssueTrackerProviderType
• Add static method formatIssueId(providerType, identifier):
  • 'github' -> #${identifier}
  • 'linear' / 'jira' -> String(identifier).toUpperCase()
  • default -> #${identifier}

Step 5: Tests

• GitHubService.test.ts: Add formatIssueId describe block with number and string inputs
• LinearService.test.ts: Add formatIssueId describe block testing uppercasing
• New IssueTrackerFactory.test.ts: Test static method for all provider types

Step 6: Verification

• pnpm build passes
• pnpm test passes

[acreeger]

Plan Review (Gemini)

Verdict: approved

Gemini confirmed the plan covers all acceptance criteria. Key insight: the approach of adding 'jira' to the type union and handling it in the static factory method (without creating a full JiraIssueTracker class) is the right strategy since no Jira provider exists yet. No critical issues, security concerns, or missed edge cases identified.

Full Review

Completeness

• Plan covers all acceptance criteria: interface method, provider implementations, factory static method, and tests.
• The "Jira Paradox" is handled correctly: add to types and factory logic without building a full Jira service class.

Key Observations

• The static factory method addresses the need to format IDs without instantiating a provider (useful for UI/display contexts).
• The plan correctly distinguishes between numeric inputs (GitHub) and alphanumeric string inputs (Linear/Jira).
• The plan is self-correcting, noting that normalizeIdentifier referenced in the issue doesn't exist and using String(identifier).toUpperCase() instead.

No Issues Found

• No security concerns
• No missed edge cases
• Approach is sound and minimal

[acreeger]

Code Review (Gemini)

Result: clean - no critical or high issues found

Gemini noted the logic duplication between provider implementations and the static factory method as a medium concern, and suggested extracting pure formatter functions. However, this level of DRY optimization is outside the scope of this foundation issue -- the duplication is intentional to allow the factory to work without instantiating providers. The default case in the switch was flagged as potentially misleading for unknown types, but since TypeScript enforces the union type at compile time, this is acceptable as a safety fallback.

Full Code Review

Findings (all low severity):

1. Logic Duplication (Medium): Formatting logic exists in both Service classes and the Factory static method. This is intentional -- the Factory needs to format without instantiating a provider. Future refactoring could extract pure functions.

2. Default Case (Low): The default branch falls back to # prefix. Since IssueTrackerProviderType is a TypeScript union type, invalid values are caught at compile time. The default is a runtime safety net.

3. Input Validation (Low): No null/undefined check on identifier. The interface contract requires string | number, so callers are responsible for valid input.

Verdict

All findings are low/medium severity and acceptable for this foundation issue. No changes needed.

[acreeger]

Implementation complete. Changes committed with fixes #596.

[acreeger]

Implemented on branch epic/595