Forge Adapter

Contract Test Pattern

// test/forge/contract.test.ts
import { describe, it, expect } from 'vitest';

function forgeContractTests(name: string, createAdapter: () => ForgeAdapter) {
  describe(`${name} ForgeAdapter contract`, () => {
    it('getIssue returns issue with required fields', async () => {
      const adapter = createAdapter();
      const issue = await adapter.getIssue('owner', 'repo', 1);
      expect(issue).toHaveProperty('number');
      expect(issue).toHaveProperty('title');
      expect(issue).toHaveProperty('body');
      expect(issue).toHaveProperty('labels');
    });
    // ... more contract tests
  });
}

// Run for both adapters
forgeContractTests('GitHub', () => new GitHubAdapter(mockOctokit));
forgeContractTests('Forgejo', () => new ForgejoAdapter(mockClient));

Rate Limit Handling

• Check x-ratelimit-remaining header on responses
• When remaining < 10, add delay between requests
• On 429 (rate limited), wait for x-ratelimit-reset timestamp
• Log rate limit events at warn level
• NEVER retry indefinitely — max 3 retries with exponential backoff

Security Rules

• Tokens are created in the adapter constructor and stored as private fields
• NEVER expose tokens in method signatures, logs, or error messages
• Log API call summaries (method, URL, status code) at debug level — never full bodies
• Error messages must not include auth headers

When Working on Forge Code

1. Check the phase spec: docs/specs-active/phase-11-forgejo.md (Forgejo) or relevant phase
2. Always modify interface first, then both implementations
3. Run contract tests: pnpm test -- --run test/forge/contract.test.ts
4. Consider rate limits for any new API call
5. Never access tokens outside the adapter