From 8884090e9de1b21e6a69350dda89707461ca9d76 Mon Sep 17 00:00:00 2001 From: Will-thom <116388885+Will-thom@users.noreply.github.com> Date: Tue, 26 May 2026 18:59:59 -0300 Subject: [PATCH] Document native integration scope --- README.md | 4 ++++ ROADMAP.md | 1 + docs/ci.md | 2 ++ docs/integrations.md | 46 ++++++++++++++++++++++++++++++++++++++++++++ docs/usage.md | 6 ++++++ docs_test.go | 4 ++++ examples/README.md | 2 ++ 7 files changed, 65 insertions(+) create mode 100644 docs/integrations.md diff --git a/README.md b/README.md index 5b496f8..56eb22d 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ Stage 1 MVP. The current release line focuses on deterministic local analysis of Maven report artifacts. It does not require GitHub tokens, CI API access, AI providers, telemetry, or external services. +Stage 1 does not include a native GitHub or GitLab API adapter. GitHub is currently the only platform with first-party project automation and a copyable CI example, while the CLI itself remains provider-agnostic. See [Integrations](docs/integrations.md). + Target Maven baseline: - Maven 3.9.x. @@ -35,6 +37,7 @@ Apache's download page currently lists Maven 3.9.16 as the recommended release a - Emits human-readable text. - Emits stable JSON for CI and agent usage. - Provides a versioned demo project with Maven report fixtures. +- Provides GitHub Actions examples, without requiring GitHub API access at runtime. ## Install From Source @@ -174,6 +177,7 @@ This is useful for: - [Installation](docs/installation.md) - [Usage guide](docs/usage.md) - [Examples](examples/README.md) +- [Integrations](docs/integrations.md) - [Contributing](CONTRIBUTING.md) - [Permission posture](docs/permissions.md) - [Testing](docs/testing.md) diff --git a/ROADMAP.md b/ROADMAP.md index 02ca19c..69eea77 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -47,6 +47,7 @@ Acceptance criteria: - Release tags produce Linux, macOS, and Windows packages with checksums. - Security automation runs CodeQL, govulncheck, and dependency review. - No network or external service is required for core functionality. +- GitHub is the only first-party platform with project automation and usage examples; no native provider API adapter ships in Stage 1. - Stage 2 and Stage 3 issues exist in GitHub with contributor-friendly acceptance criteria. Expected confidence: high. diff --git a/docs/ci.md b/docs/ci.md index 8bd745a..3786006 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -4,6 +4,8 @@ PR Maven CLI uses a Stage 1 OSS-style GitHub pipeline. The pipeline is intentionally dependency-light. Core checks do not require Maven, Docker, private credentials, hosted services, or external test infrastructure. +This is project CI, not a runtime provider adapter. The Stage 1 CLI does not call GitHub APIs. Runtime/provider integration scope is documented in [integrations.md](integrations.md). + ## CI Workflow File: `.github/workflows/ci.yml` diff --git a/docs/integrations.md b/docs/integrations.md new file mode 100644 index 0000000..211c9c3 --- /dev/null +++ b/docs/integrations.md @@ -0,0 +1,46 @@ +# Integrations + +PR Maven CLI is local-first in Stage 1. + +The core analyzer does not call GitHub, GitLab, CI APIs, hosted services, or AI providers. It reads Maven report artifacts from the local filesystem and emits text or JSON. + +## Stage 1 Integration Scope + +Current first-party integration surface: + +- GitHub repository automation for the project itself. +- GitHub Actions CI/CD workflows for this repository. +- A copyable GitHub Actions usage example for Maven failure triage. + +Current product/runtime integration scope: + +- No native GitHub API adapter yet. +- No native GitLab API adapter yet. +- No required provider token. +- No required network access for Maven report analysis. + +This means GitHub is the only platform with official project automation and example coverage today, but the CLI itself remains provider-agnostic in Stage 1. + +## Planned Native Adapters + +Native PR and CI context adapters are planned for Stage 3. + +Planned order: + +1. GitHub adapter for changed files and check runs. +2. GitHub-oriented PR summary and CI workspace output. +3. GitLab merge request support investigation. + +Adapters must stay optional. Local Maven report parsing should continue to work without GitHub or GitLab tokens. + +## Contributor Guidance + +Before adding a provider integration: + +- Keep the provider client behind an interface. +- Avoid making network access part of core tests. +- Add fixtures or mocks for provider responses. +- Preserve the local analyzer contract. +- Document required tokens and permissions. +- Keep provider-specific behavior out of parser packages. + diff --git a/docs/usage.md b/docs/usage.md index 55558e9..c00d79b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -65,6 +65,12 @@ go run ./cmd/prmaven why -project demo/multi-module-failure -format json The JSON contract is designed for CI systems, bots, and coding agents. It includes `summary`, `modules`, and `findings`. +## Provider Integrations + +Stage 1 has no native GitHub or GitLab API adapter. The CLI does not need provider tokens and does not call remote PR, check-run, issue, or merge request APIs. + +GitHub is the only platform with first-party project automation and a copyable CI example today. For the full integration scope and planned native adapters, read [integrations.md](integrations.md). + ## Demo: No-Failure Fixture ```bash diff --git a/docs_test.go b/docs_test.go index db34787..14b5b94 100644 --- a/docs_test.go +++ b/docs_test.go @@ -10,6 +10,7 @@ func TestDocumentationCoversInstallationUsageAndExamples(t *testing.T) { files := map[string]string{ "README.md": mustReadFile(t, "README.md"), "docs/installation.md": mustReadFile(t, "docs/installation.md"), + "docs/integrations.md": mustReadFile(t, "docs/integrations.md"), "docs/permissions.md": mustReadFile(t, "docs/permissions.md"), "docs/usage.md": mustReadFile(t, "docs/usage.md"), "examples/README.md": mustReadFile(t, "examples/README.md"), @@ -19,8 +20,11 @@ func TestDocumentationCoversInstallationUsageAndExamples(t *testing.T) { assertContains(t, files["README.md"], "[Installation](docs/installation.md)") assertContains(t, files["README.md"], "[Usage guide](docs/usage.md)") assertContains(t, files["README.md"], "[Examples](examples/README.md)") + assertContains(t, files["README.md"], "[Integrations](docs/integrations.md)") assertContains(t, files["README.md"], "[Permission posture](docs/permissions.md)") assertContains(t, files["docs/installation.md"], "go install ./cmd/prmaven") + assertContains(t, files["docs/integrations.md"], "No native GitHub API adapter yet.") + assertContains(t, files["docs/integrations.md"], "GitHub is the only platform with official project automation and example coverage today") assertContains(t, files["docs/permissions.md"], "Do not switch it to private if that would disable branch protection or repository rules.") assertContains(t, files["docs/permissions.md"], "All CI checks") assertContains(t, files["docs/installation.md"], "prmaven version") diff --git a/examples/README.md b/examples/README.md index acd8ba8..974e51d 100644 --- a/examples/README.md +++ b/examples/README.md @@ -54,3 +54,5 @@ The workflow example at [github-actions/triage-maven-failures.yml](github-action - upload JSON output as an artifact; - preserve the original Maven failure status. +GitHub Actions is the only first-party CI platform example today. The CLI itself does not call the GitHub API in Stage 1. +