Define provider fixtures and mocks

.github/backlog/ISSUES.md

@@ -638,6 +638,8 @@ Issue: #85
 
 Depends on: #79 and #82.
 
+Status: completed by [Provider Fixtures And Mocks](../../docs/provider-fixtures-and-mocks.md).
+
 Labels: `stage: 3`, `area: architecture`, `area: test`, `help wanted`, `need help`, `agent-friendly`, `status: ready`
 
 Acceptance criteria:

docs/provider-context-plan.md

@@ -68,3 +68,4 @@ Every provider-context issue should keep:
 Ready design issues signal that contributors may start drafting contracts. Blocked implementation issues signal that the repo is still waiting for the prerequisite contract, fixture, or mock design.
 
 Detailed package-boundary guidance lives in [Provider Adapter Package Boundaries](provider-adapter-boundaries.md).
+Fixture and fake-client guidance lives in [Provider Fixtures And Mocks](provider-fixtures-and-mocks.md).

docs/provider-fixtures-and-mocks.md

@@ -0,0 +1,104 @@
+# Provider Fixtures And Mocks
+
+Stage 3 provider behavior must be testable without live GitHub, GitLab, CI provider, or hosted-service access.
+
+This document defines the fixture and fake-client contract for optional provider context.
+
+## Fixture Principles
+
+Provider fixtures should be:
+
+- sanitized and safe to publish;
+- stable across machines and CI workers;
+- small enough to review in pull requests;
+- close enough to provider payloads to preserve useful field names;
+- normalized where provider APIs include volatile IDs, timestamps, URLs, or actor metadata;
+- stored under a provider-specific `testdata` directory once implementation begins.
+
+Default tests must not call live provider APIs.
+
+## Suggested Fixture Shape
+
+Provider fixtures should use JSON unless a provider artifact is naturally another format.
+
+Recommended layout:
+
+```text
+pkg/prmaven/provider/testdata
+  github
+    changed-files
+      added-modified-renamed.json
+      deleted-files.json
+      nested-modules.json
+    check-runs
+      success.json
+      failure.json
+      skipped-cancelled-timed-out.json
+      pending.json
+    errors
+      missing-token.json
+      rate-limit.json
+      permission-denied.json
+      not-found.json
+  gitlab
+    merge-request-files
+    pipeline-jobs
+```
+
+Each fixture should include a short README or inline test name that explains:
+
+- the scenario being modeled;
+- the expected normalized provider-neutral result;
+- any fields intentionally omitted or redacted.
+
+## Fake Client Contract
+
+Provider fake clients should support deterministic responses for:
+
+- successful changed-file lookup;
+- successful check-run or pipeline summary lookup;
+- missing token;
+- insufficient permissions;
+- rate limit;
+- network failure;
+- not found;
+- unsupported provider state;
+- partial provider data.
+
+Fakes should not read environment variables unless a test explicitly validates token-resolution behavior. Tests that validate token behavior should set variables inside the test and restore them before returning.
+
+## Error Scenario Expectations
+
+Provider failures should degrade gracefully.
+
+Expected behavior:
+
+- missing token: provider context is unavailable, local Maven findings remain;
+- insufficient permissions: include a provider diagnostic, local Maven findings remain;
+- rate limit: include retry/context information when available, local Maven findings remain;
+- network failure: do not retry indefinitely in default tests, local Maven findings remain;
+- not found: treat provider context as unavailable for that target, local Maven findings remain;
+- unsupported state: report a bounded diagnostic rather than inventing findings.
+
+## Test Layers
+
+Recommended test layers:
+
+1. Provider-neutral unit tests over fake clients.
+2. Fixture parser/normalizer tests using sanitized provider payloads.
+3. CLI wiring tests that prove report-only mode still works without provider credentials.
+4. Optional live-provider checks that are skipped by default and never required for `go test ./...`.
+
+## Compatibility With Local-First Core
+
+Provider fixtures and mocks must not make provider context part of the core analyzer contract.
+
+The following must continue to work without provider fixtures, mocks, credentials, or network access:
+
+- Maven module discovery;
+- report parsing;
+- text output;
+- JSON output;
+- output-file writing;
+- module filtering;
+- no-failure behavior.

docs/testing.md

@@ -170,6 +170,8 @@ GitHub Actions runs:
 
 The CI workflow is intentionally dependency-light. Core tests do not require Maven, network services, GitHub tokens, Docker, or external APIs. The `pkg/prmaven` local-first guard fails if production core code starts importing network/provider clients or reading provider environment variables.
 
+Future provider-context tests should follow the [Provider Fixtures And Mocks](provider-fixtures-and-mocks.md) contract so default tests stay fixture-driven and credential-free.
+
 ## Contributor Expectations
 
 For parser changes: