git-contribution-graph/TODO.md

# TODO: persist contribution history in SQLite + audit cleanup

Backend-only work. Follow Red → Green → Refactor per `CLAUDE.md` for every
step that adds behavior (store, retention, provider `$since` handling).
Order matters — later steps assume earlier ones are done.

## 1. Audit cleanup

- [x] **Remove `eightpoints/guzzle-bundle` + `idci/graphql-client-bundle`.**
  They exist only to build one near-static GitHub GraphQL query string
  (`GitHubProvider.php:59-74`); the bundle's own HTTP transport is already
  bypassed (comment at `GitHubProvider.php:76-77`). 
     - [x] Replace
  `$graphqlClient->buildQuery(...)->getGraphQLQuery()` with a plain
  `sprintf`/heredoc query string. Delete the two packages from
  `composer.json`, `config/bundles.php`, and delete
  `config/packages/eight_points_guzzle.yaml` +
  `config/packages/idci_graphql_client.yaml`. Run `composer update` and
  commit the regenerated `composer.lock`.
 
- [x] **Dedupe `baseUrl` normalization.** `GitLabProvider.php` (lines 41,
  53) and `GiteaProvider.php` (lines 42, 54) each call
  `rtrim($this->baseUrl..., '/')` twice — once in `ping()`, once in
  `fetch()`. Compute it once as a `private readonly string $baseUrl` in
  the constructor instead.

## 2. Fix stale `config/services.yaml` (found during exploration, blocks step 1 & 4)

- [x] `services.yaml` still binds `$username`/`$token`/`$baseUrl` to the
  pre-refactor FQCNs (`App\Service\GitHubProvider` etc.) and
  `_instanceof: App\Service\ProviderInterface`, left over from the
  `Service/` → `Provider/`+`Renderer/` namespace reorg. Update all of
  these to `App\Service\Provider\...`. Currently these bindings silently
  no-op, and scalar constructor args can't autowire without them — any
  edit to these constructors (steps 1, 4) needs this fixed first, or the
  container fails to compile.

## 3. `ContributionStore` (SQLite via native PDO)

> Docs: [PDO](https://www.php.net/manual/en/book.pdo.php) ·
> [PDO_SQLITE driver](https://www.php.net/manual/en/ref.pdo-sqlite.php) ·
> [PDO::prepare / prepared statements](https://www.php.net/manual/en/pdo.prepare.php) ·
> [SQLite `INSERT ... ON CONFLICT` upsert](https://www.sqlite.org/lang_upsert.html) ·
> [SQLite `STRICT` tables](https://www.sqlite.org/stricttables.html) ·
> [SQLite `WITHOUT ROWID` tables](https://www.sqlite.org/withoutrowid.html) ·
> [SQLite datatypes (why `date` is `INTEGER`/unixtime, not `TEXT`)](https://www.sqlite.org/datatype3.html)

- [x] New `src/Service/ContributionStore.php`. PDO SQLite, DB file at
  `%kernel.project_dir%/var/data/contributions.db` (configurable
  constructor arg), table created lazily. **Schema note:** `date` is
  stored as a Unix timestamp (`INTEGER`), not `TEXT` — matches the
  current implementation:
  ```sql
  CREATE TABLE IF NOT EXISTS contributions (
      provider TEXT NOT NULL,
      date     INTEGER NOT NULL,
      count    INTEGER NOT NULL CHECK (count >= 0),
      PRIMARY KEY (provider, date)
  ) WITHOUT ROWID, STRICT;
  ```
- [x] `add(string $provider, int $unixtime, int $count): void` — plain
  insert (done, needs test coverage — see below).
- [x] Fix `add()`: currently a plain `INSERT`, so re-adding an existing
  `(provider, date)` throws a unique-constraint violation instead of
  upserting. Switch to
  `INSERT ... ON CONFLICT(provider, date) DO UPDATE SET count = excluded.count`
  (see SQLite upsert doc above), or keep `add()` insert-only and add a
  separate `merge()` for the upsert case used by step 5.
- [x] `remove(string $provider, int $unixtime): void` — started, has a
  bug: `DELETE contributions WHERE ...` is invalid SQL, missing the
  `FROM` keyword (must be `DELETE FROM contributions WHERE ...`); also
  drop the `LIKE` on `provider` (exact match, use `=`) since it's an
  unindexed wildcard scan for what should be an exact key lookup.
- [x] **`Contribution` entity.** Small immutable value object
  (`src/Entity/Contribution.php`) wrapping one row: `provider` (string),
  `date` (unix timestamp int, or `\DateTimeImmutable` — pick one and
  use it consistently everywhere, including `add()`/`all()`), `count`
  (int). Gives `ContributionStore::all()` and the aggregator something
  typed to pass around instead of raw arrays/tuples.
- [x] **`ContributionCollection`.** Typed collection
  (`src/Entity/ContributionCollection.php`) wrapping
  `array<Contribution>` — implement `IteratorAggregate` + `Countable`
  at minimum ([`IteratorAggregate`](https://www.php.net/manual/en/class.iteratoraggregate.php),
  [`Countable`](https://www.php.net/manual/en/class.countable.php)) so
  it can be `foreach`'d and `count()`'d like a normal array. This is
  what `ContributionStore::all()` should return instead of a bare
  `date => count` array.
- [x] `latestDate(string $provider): ?int` — `SELECT MAX(date) WHERE provider = ?`
  (returns a unix timestamp, not a string, per the schema above).
- [x] `merge(string $provider, array $dateCounts): void` — upsert via
  `INSERT ... ON CONFLICT(provider, date) DO UPDATE SET count = excluded.count`;
  `$dateCounts` keyed by unix timestamp.
- [x] `all(string $provider, ?int $sinceDays = null): ContributionCollection` —
  fetch all rows for a provider, or since a given range. `null` returns
  full history (no arbitrary cutoff), a value filters to rows where
  `date >= (now - sinceDays * 86400)`. **Bug:** current stub in
  `ContributionStore.php:58` has invalid PHP (`$provider == null` instead
  of `?string $provider = null` — this won't parse) and returns `void`
  instead of `ContributionCollection`; fix the signature when implementing.
- [x] `prune(): void` — `DELETE FROM contributions WHERE date < ?` using
  the configured retention window (a unix timestamp cutoff); no-ops if
  retention is unset/0.
- [x] Constructor takes `?int $retentionDays` bound from new env var
  `CONTRIBUTIONS_RETENTION_DAYS` (empty/default = keep forever). *(constructor
  param wired; the env binding itself is step 6's job.)*
- [x] Tests: `tests/Unit/Service/ContributionStoreTest.php` — store &
  retrieve, upsert overwrites existing date, `sinceDays` filtering,
  `prune()` no-ops when retention unset, `prune()` deletes rows older
  than the window when set.
- [x] Tests: `tests/Unit/Entity/ContributionTest.php` and
  `ContributionCollectionTest.php` — construction, iteration, `count()`.

## 4. Wire `$since` through providers

- [ ] `ProviderInterface::fetch()` → `fetch(?\DateTimeImmutable $since = null): array`.
- [ ] `GitHubProvider::fetch()` — use `$since ?? new \DateTimeImmutable('-365 days')`
  for the GraphQL `from` param.
- [ ] `GitLabProvider::fetch()` — same, feeds the `after` query param
  (this is what actually shrinks the pagination loop).
- [ ] `GiteaProvider::fetch()` — same, feeds the `$cutoff` timestamp filter.
- [ ] Update `GitHubProviderTest.php` (drop `GraphQLApiClientRegistryInterface`
  stub setup entirely per step 1), `GitLabProviderTest.php`,
  `GiteaProviderTest.php` — add a case asserting a passed `$since` narrows
  the request window.

## 5. Wire `ContributionStore` into `ContributionAggregator`

- [ ] Inject `ContributionStore` into `ContributionAggregator`.
- [ ] Per configured provider: `$since = $store->latestDate($name)` → if
  set, `(new \DateTimeImmutable($latest))->modify('-3 days')` (3-day
  overlap for late corrections), else `null` (first run).
- [ ] `$fresh = $provider->fetch($since)`, `$store->merge($name, $fresh)`,
  then read back `$store->all($name, sinceDays: 371)` for the render
  window (53 weeks × 7 days) — a `ContributionCollection` — and merge
  its contributions into the returned array.
- [ ] Call `$store->prune()` once per `aggregate()` call, after all
  providers have merged.
- [ ] Keep the existing try/catch-and-log-per-provider behavior — a
  provider failure leaves its DB history stale, doesn't break the render.
- [ ] Update `ContributionAggregatorTest.php` with store-interaction and
  prune-call cases.

## 6. Docker / env

- [ ] `docker-compose.yml` — add a `data` named volume mounted at
  `/app/var/data` (same pattern as `cache`/`logs`), and pass through
  `CONTRIBUTIONS_RETENTION_DAYS: "${CONTRIBUTIONS_RETENTION_DAYS:-}"`.
- [ ] `Dockerfile` — add `var/data` to the `mkdir -p` in the `final` stage
  alongside `var/cache/prod/pools var/log`, owned by `app`.
- [ ] `.env` — document `CONTRIBUTIONS_RETENTION_DAYS` (empty by default),
  same style as the existing `ALLOWED_HOSTS` comment.

## 7. PHPStan

- [ ] `composer require --dev phpstan/phpstan` (plain PHPStan — no
  Symfony extension needed for this app's size).
- [ ] Add `phpstan.neon`: `paths: [src, tests]`, `level: 8`.
- [ ] Add composer script `"phpstan": "phpstan analyse"`.
- [ ] Fix whatever level-8 flags on first run.

## 8. `CLAUDE.md` update

- [ ] Architecture section: add the `ContributionStore` (SQLite) tier
  between providers and the renderer; note the two-tier cache (1h SVG
  cache → SQLite raw-data store → provider APIs).
- [ ] Environment variables table: add `CONTRIBUTIONS_RETENTION_DAYS`.
- [ ] Development section: add `composer phpstan` next to the existing
  `vendor/bin/phpunit` commands.
- [ ] Remove any remaining mentions of the two deleted bundles.

## Verification

- `vendor/bin/phpunit --testdox` green after every step.
- `composer phpstan` clean at level 8.
- `composer install` succeeds with no dangling references to the removed bundles.
- `docker compose up -d --build`; clear the FS cache
  (`docker compose exec graph rm -rf var/cache/*`); hit
  `/graph.svg?theme=dark` twice; check `docker compose logs -f graph` shows
  a narrower `since` window on the second fetch.
- Set `CONTRIBUTIONS_RETENTION_DAYS=30`; confirm rows older than 30 days
  are gone after the next refresh
  (`sqlite3 var/data/contributions.db "SELECT date FROM contributions ORDER BY date LIMIT 1"`).
- `curl localhost:8080/health` still reports all configured providers healthy.