diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..a4e0491 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,5 @@ +* @metalagman + +/.github/ @metalagman +/docs/.vitepress/ @metalagman +/scripts/ @metalagman diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..3d1959d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,23 @@ +name: Documentation or site bug +description: Report incorrect documentation, broken links, or site behavior +title: "docs: " +labels: [bug] +body: + - type: input + id: page + attributes: + label: Page URL + validations: + required: true + - type: textarea + id: problem + attributes: + label: Problem + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected content or behavior + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..5bfc33f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Security or privacy report + url: https://github.com/diffpal/diffpal.github.io/security/advisories/new + about: Report sensitive issues privately. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..12dbeed --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,9 @@ +## Summary + + + +## Validation + +- [ ] Documentation synchronization and production build pass. +- [ ] Privacy checks pass and analytics consent behavior is unchanged or documented. +- [ ] Links and user-facing version references are current. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 772a199..61e95b4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,10 +14,23 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + + - name: Resolve canonical docs source + id: docs-source + run: | + ref=$(node -p "require('./docs-source.json').ref") + echo "ref=$ref" >> "$GITHUB_OUTPUT" + + - name: Checkout canonical DiffPal docs + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + repository: diffpal/diffpal + ref: ${{ steps.docs-source.outputs.ref }} + path: .source/diffpal - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 with: node-version: 22 cache: npm @@ -26,4 +39,4 @@ jobs: run: npm ci - name: Build - run: npm run docs:build + run: npm run check diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 0d949a0..ebe4379 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -20,16 +20,29 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + + - name: Resolve canonical docs source + id: docs-source + run: | + ref=$(node -p "require('./docs-source.json').ref") + echo "ref=$ref" >> "$GITHUB_OUTPUT" + + - name: Checkout canonical DiffPal docs + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + repository: diffpal/diffpal + ref: ${{ steps.docs-source.outputs.ref }} + path: .source/diffpal - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 with: node-version: 22 cache: npm - name: Configure Pages - uses: actions/configure-pages@v4 + uses: actions/configure-pages@1f0c5cde4bc74cd7e1254d0cb4de8d49e9068c7d # v4 - name: Install dependencies run: npm ci @@ -38,7 +51,7 @@ jobs: run: npm run docs:build - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3 with: path: .vitepress/dist @@ -51,4 +64,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 diff --git a/.gitignore b/.gitignore index c37add9..a9bdfbf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,7 @@ node_modules/ +.generated/ +.generated-rewrites.json +.source/ .vitepress/cache/ .vitepress/dist/ .DS_Store diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 1d39913..c7514d0 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -1,40 +1,28 @@ import { defineConfig } from 'vitepress' +import fs from 'node:fs' const siteTitle = 'DiffPal' const siteDescription = 'Open-source AI PR review you control.' const mainRepo = 'https://github.com/diffpal/diffpal' const examplesBase = `${mainRepo}/tree/main/examples` const changelog = `${mainRepo}/blob/main/CHANGELOG.md` -const googleAnalyticsId = 'G-B8G6D7K9SQ' +const docsSource = JSON.parse(fs.readFileSync('docs-source.json', 'utf8')) +const rewrites = JSON.parse(fs.readFileSync('.generated-rewrites.json', 'utf8')) export default defineConfig({ lang: 'en-US', title: siteTitle, description: siteDescription, base: '/', + srcDir: '.generated', + rewrites, cleanUrls: true, lastUpdated: true, - srcExclude: ['README.md', 'AGENTS.md'], sitemap: { hostname: 'https://diffpal.github.io' }, head: [ ['link', { rel: 'icon', type: 'image/png', href: '/logo-mark.png' }], - [ - 'script', - { - async: '', - src: `https://www.googletagmanager.com/gtag/js?id=${googleAnalyticsId}` - } - ], - [ - 'script', - {}, - `window.dataLayer = window.dataLayer || []; -function gtag(){dataLayer.push(arguments);} -gtag('js', new Date()); -gtag('config', '${googleAnalyticsId}');` - ], ['meta', { name: 'theme-color', content: '#2563eb' }], ['meta', { property: 'og:type', content: 'website' }], ['meta', { property: 'og:title', content: siteTitle }], @@ -50,7 +38,7 @@ gtag('config', '${googleAnalyticsId}');` provider: 'local' }, editLink: { - pattern: 'https://github.com/diffpal/diffpal.github.io/edit/main/:path', + pattern: `${mainRepo}/edit/${docsSource.ref}/docs/:path`, text: 'Edit this page on GitHub' }, socialLinks: [ @@ -61,6 +49,7 @@ gtag('config', '${googleAnalyticsId}');` { text: 'Docs', link: '/docs' }, { text: 'Examples', link: examplesBase }, { text: 'Security', link: '/security' }, + { text: 'Privacy', link: '/privacy' }, { text: 'Changelog', link: changelog }, { text: 'GitHub', link: mainRepo } ], @@ -113,6 +102,7 @@ gtag('config', '${googleAnalyticsId}');` { text: 'Verify first review', link: '/verify-first-review' }, { text: 'Next steps', link: '/next-steps' }, { text: 'Secrets and fork PRs', link: '/secrets-and-fork-prs' }, + { text: 'Migrate to v1', link: '/migrate-to-v1' }, { text: 'Examples gallery', link: examplesBase } ] }, diff --git a/.vitepress/theme/ConsentAnalytics.vue b/.vitepress/theme/ConsentAnalytics.vue new file mode 100644 index 0000000..d6204a3 --- /dev/null +++ b/.vitepress/theme/ConsentAnalytics.vue @@ -0,0 +1,63 @@ + + + + + diff --git a/.vitepress/theme/Layout.vue b/.vitepress/theme/Layout.vue new file mode 100644 index 0000000..a515337 --- /dev/null +++ b/.vitepress/theme/Layout.vue @@ -0,0 +1,12 @@ + + + diff --git a/.vitepress/theme/custom.css b/.vitepress/theme/custom.css index 65b8448..8efbdb8 100644 --- a/.vitepress/theme/custom.css +++ b/.vitepress/theme/custom.css @@ -34,6 +34,57 @@ max-width: 680px; } +.privacy-consent { + position: fixed; + z-index: 100; + right: 1rem; + bottom: 1rem; + max-width: 34rem; + padding: 1rem; + border: 1px solid var(--vp-c-divider); + border-radius: 0.75rem; + background: var(--vp-c-bg-soft); + box-shadow: var(--vp-shadow-3); +} + +.privacy-consent p { + margin: 0 0 0.75rem; +} + +.privacy-consent div { + display: flex; + justify-content: flex-end; + gap: 0.5rem; +} + +.privacy-consent button, +.privacy-choice-button { + padding: 0.45rem 0.75rem; + border: 1px solid var(--vp-c-divider); + border-radius: 0.5rem; + cursor: pointer; +} + +.privacy-consent .accept { + color: white; + border-color: var(--vp-c-brand-1); + background: var(--vp-c-brand-1); +} + +.privacy-consent .decline, +.privacy-choice-button { + color: var(--vp-c-text-1); + background: var(--vp-c-bg); +} + +.privacy-choice-button { + position: fixed; + z-index: 90; + right: 1rem; + bottom: 1rem; + font-size: 0.8rem; +} + @media (max-width: 640px) { .vp-doc table { display: block; diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts index 42fe9a9..094cbe0 100644 --- a/.vitepress/theme/index.ts +++ b/.vitepress/theme/index.ts @@ -1,4 +1,8 @@ import DefaultTheme from 'vitepress/theme' +import Layout from './Layout.vue' import './custom.css' -export default DefaultTheme +export default { + extends: DefaultTheme, + Layout +} diff --git a/README.md b/README.md index 0ec59a8..0c9fa51 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,11 @@ This repository contains the public documentation website for DiffPal. Production site: https://diffpal.github.io/ -Public documentation Markdown lives at the repository root so the organization-level GitHub Pages site publishes at `/`, not under a project path. +Canonical public documentation lives in the main +[`diffpal/diffpal`](https://github.com/diffpal/diffpal/tree/main/docs) +repository. This site records an immutable source commit in `docs-source.json` +and generates its documentation pages into `.generated/` before each build. +Only the homepage, theme, privacy policy, and site metadata are maintained here. ## Local Development @@ -14,6 +18,13 @@ Install dependencies: npm ci ``` +Check out the locked canonical documentation source: + +```bash +git clone https://github.com/diffpal/diffpal.git .source/diffpal +git -C .source/diffpal checkout "$(node -p "require('./docs-source.json').ref")" +``` + Start the local VitePress server: ```bash @@ -28,6 +39,12 @@ Build the static site: npm run docs:build ``` +Run the complete build, privacy, and synchronization checks with: + +```bash +npm run check +``` + Preview the generated site: ```bash diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..c226038 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,10 @@ +# Security Policy + +Do not open a public issue for a suspected vulnerability or privacy flaw. +Report it through +[GitHub private vulnerability reporting](https://github.com/diffpal/diffpal.github.io/security/advisories/new) +with reproduction steps and impact. We aim to acknowledge reports within three +business days and coordinate remediation and disclosure with the reporter. + +Issues in the DiffPal product should be reported to the +[core repository](https://github.com/diffpal/diffpal/security/advisories/new). diff --git a/artifacts.md b/artifacts.md deleted file mode 100644 index 2eda91a..0000000 --- a/artifacts.md +++ /dev/null @@ -1,69 +0,0 @@ -# Artifacts Reference - -DiffPal writes artifacts under `.artifacts/diffpal/` by default. - -## Artifact Table - -| Path | Created when | Format | Intended consumer | -| --- | --- | --- | --- | -| `.artifacts/diffpal/findings.json` | Every successful provider-backed review and `debug prompt` unless `--out` changes it. | DiffPal findings JSON | CI automation, audit logs, downstream converters. | -| `.artifacts/diffpal/summary.md` | Non-dry-run host review commands when the `summary` surface is enabled; custom CI examples may capture local stdout here. | Markdown | Humans, CI job summaries, retained review record. | -| `.artifacts/diffpal/diffpal.sarif` | Non-dry-run GitHub and GitLab host review commands; `diffpal sarif`; any file-publishing run that enables the SARIF surface. | SARIF 2.1.0 JSON | Code scanning or SARIF upload consumers. | -| `.artifacts/diffpal/codequality.json` | GitLab host review commands. | GitLab Code Quality JSON | GitLab Code Quality report ingestion. | -| `.artifacts/diffpal/github-comments.json` | GitHub file-output publishing plan when GitHub comment surface is emitted to files. | JSON | Debugging or API publishing handoff. | -| `.artifacts/diffpal/gitlab-discussions.json` | GitLab file-output publishing plan for discussions. | JSON | Debugging or API publishing handoff. | -| `.artifacts/diffpal/gitlab-status.json` | GitLab status file output. | JSON | Debugging or API publishing handoff. | -| `.artifacts/diffpal/azure-threads.json` | Azure file-output publishing plan for PR threads. | JSON | Debugging or API publishing handoff. | -| `.artifacts/diffpal/azure-status.json` | Azure status file output. | JSON | Debugging or API publishing handoff. | - -## Canonical Versus Host-Specific - -`findings.json` is the canonical DiffPal artifact. It contains validated -structured findings and metadata independent of a code host. - -Host-specific artifacts are derived from the canonical bundle: - -- SARIF is derived for SARIF consumers. -- GitLab Code Quality is derived for GitLab report ingestion. -- Comments, discussions, threads, and status JSON files are publishing plans or - status payloads for host integrations. - -## Creation Conditions - -`diffpal review local`: - -- writes `findings.json` or the `--out` path; -- prints Markdown to stdout; -- does not automatically create `summary.md`. - -Non-dry-run `diffpal review github`: - -- writes `findings.json`; -- creates `summary.md` and `diffpal.sarif`; -- creates GitHub comment artifacts when `feedback=review` file outputs are - generated. - -Non-dry-run `diffpal review gitlab`: - -- writes `findings.json`; -- creates `summary.md`, `diffpal.sarif`, `codequality.json`, - `gitlab-status.json`; -- creates `gitlab-discussions.json` when `feedback=review` file outputs are - generated. - -Non-dry-run `diffpal review ado`: - -- writes `findings.json`; -- creates `summary.md` and `azure-status.json`; -- creates `azure-threads.json` when `feedback=review` file outputs are - generated. - -`diffpal debug prompt` writes a mock findings bundle to `--out`. -`diffpal sarif` reads a findings bundle and writes SARIF to `--out`. - -## Retention Advice - -Upload `.artifacts/diffpal/` from CI when you need audit records, downstream -automation, or report ingestion after the job completes. Retain at least -`findings.json` for machine processing and `summary.md` for human review -history when host summaries are not enough. diff --git a/azure-pipelines.md b/azure-pipelines.md deleted file mode 100644 index 4253810..0000000 --- a/azure-pipelines.md +++ /dev/null @@ -1,148 +0,0 @@ -# Azure Pipelines - -Use this page to run DiffPal in Azure Pipelines pull request validation. - -## Supported Outputs - -- Azure PR summary thread. -- File-bound PR threads for actionable findings. -- Azure PR status named `DiffPal Review`. - -## Prerequisites - -- An Azure Repos project with PR validation. -- The DiffPal Review extension installed, or `diffpal` available in the job. -- A committed DiffPal config at `.config/diffpal/config.yaml`. -- A provider secret such as `OPENAI_API_KEY`. -- Pipeline access to `System.AccessToken`. - -See [Shared Setup](/integrations#shared-setup) and -[Providers](/providers). - -## Required Checkout Behavior - -Use full checkout history: - -```yaml -- checkout: self - fetchDepth: 0 -``` - -When `base` and `head` are omitted, `DiffPalReview@1` uses PR metadata and the -target branch to compute the merge base. - -## Required Token And Minimum Permissions - -Enable **Allow scripts to access the OAuth token** and pass -`SYSTEM_ACCESSTOKEN` to the review task: - -```yaml -env: - SYSTEM_ACCESSTOKEN: $(System.AccessToken) -``` - -Use `SYSTEM_ACCESSTOKEN` for pipeline-scoped access. Use -`AZURE_DEVOPS_EXT_PAT` only when your organization requires a dedicated PAT. -Keep host tokens separate from provider credentials such as `OPENAI_API_KEY`. - -## Provider Installation And Authentication - -Install and authenticate the selected provider before the DiffPal step. Use -[Providers](/providers) for Codex, Copilot, OpenCode, and custom -ACP-compatible CLI setup. - -Provider credentials allow the selected third-party provider to process the -review input. Store them as secret variables and keep credentialed review steps -behind trusted-source conditions. See -[Secrets and fork PRs](/secrets-and-fork-prs). - -## Minimal Pipeline - -```yaml -trigger: none -pr: - - main - -pool: - vmImage: ubuntu-latest - -steps: - - checkout: self - fetchDepth: 0 - - - task: UseNode@1 - inputs: - version: "22.x" - - - script: npm install --global @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3 - displayName: Install Codex provider - - - script: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key - displayName: Authenticate Codex - condition: and(succeeded(), ne(variables['System.PullRequest.IsFork'], 'True')) - env: - OPENAI_API_KEY: $(OPENAI_API_KEY) - - - task: DiffPalReview@1 - displayName: DiffPal review - condition: and(succeeded(), ne(variables['System.PullRequest.IsFork'], 'True')) - inputs: - diffpalVersion: latest - profile: ci - feedback: review - gate: true - env: - OPENAI_API_KEY: $(OPENAI_API_KEY) - SYSTEM_ACCESSTOKEN: $(System.AccessToken) -``` - -## Feedback Modes - -Use `feedback: review` for status, summary thread, and PR threads. Use -`feedback: summary` for status and summary thread without file-bound PR -threads. - -See [Feedback Modes](/integrations#feedback-modes). - -## Merge-Gate Setup - -Set `gate: true` on `DiffPalReview@1`. Blocking findings fail the task and set -the Azure PR status to failed. - -See [Merge Gates](/integrations#merge-gates). - -## Fork Or Untrusted-Contribution Behavior - -Keep credentialed review steps behind: - -```yaml -condition: and(succeeded(), ne(variables['System.PullRequest.IsFork'], 'True')) -``` - -Use stricter organization-specific trusted-source conditions when needed. See -[Secrets and fork PRs](/secrets-and-fork-prs). - -## Expected Results - -- Azure PR threads for actionable findings when feedback is `review`. -- A PR summary thread headed `DiffPal Review Summary`. -- An Azure PR status named `DiffPal Review`. -- Failed task only for blocking gated findings or incomplete review setup. - -## Common Failures - -- `fetchDepth: 0` is missing. -- **Allow scripts to access the OAuth token** is disabled. -- `SYSTEM_ACCESSTOKEN` is not passed to the review task. -- Provider variables are unavailable in fork PR validation. - -See [Common Failures](/integrations#common-failures). - -## Related Examples - -- [Codex API key](https://github.com/diffpal/diffpal/blob/main/examples/ci/azure-pipelines/codex-api-key.yml) -- [Codex subscription auth](https://github.com/diffpal/diffpal/blob/main/examples/ci/azure-pipelines/codex-subscription.yml) -- [Copilot token](https://github.com/diffpal/diffpal/blob/main/examples/ci/azure-pipelines/copilot-github-token.yml) - -Next step: use [Verify First Review](/verify-first-review) -after the first Azure Pipelines run completes. diff --git a/cli.md b/cli.md deleted file mode 100644 index 315c8e9..0000000 --- a/cli.md +++ /dev/null @@ -1,242 +0,0 @@ -# CLI Reference - -The public CLI entrypoint is `diffpal`. - -## Installation - -Verified distribution paths in this repository: - -| Method | Command or entrypoint | Notes | -| --- | --- | --- | -| npm one-shot | `npx -y @diffpal/diffpal@latest ` | Used by the quickstart. | -| npm global | `npm install --global @diffpal/diffpal@latest` | Provides the `diffpal` executable. | -| GitHub Action | `diffpal/action@v1` | Wraps DiffPal for GitHub Actions. See [GitHub Actions](/github-actions). | -| Azure extension | `DiffPalReview@1` | Wraps DiffPal for Azure Pipelines. See [Azure Pipelines](/azure-pipelines). | - -Release builds are produced by Omnidist for npm packages and platform binaries. -The npm meta-package is `@diffpal/diffpal`. - -## Global Flags - -| Flag | Default | Purpose | -| --- | --- | --- | -| `--config-dir` | empty | Extra config root directory searched before `.config/diffpal/config.yaml`. | -| `--debug` | `false` | Enable debug logging. | -| `--profile` | empty | Config profile name. | - -## Command Overview - -| Command | Purpose | -| --- | --- | -| `diffpal init` | Generate starter workspace configuration. | -| `diffpal review local` | Run provider-backed local review and print Markdown. | -| `diffpal review github` | Run review and publish/emit GitHub outputs. | -| `diffpal review gitlab` | Run review and publish/emit GitLab outputs. | -| `diffpal review ado` | Run review and publish/emit Azure DevOps outputs. Alias: `azure`. | -| `diffpal doctor` | Validate runtime, provider, workspace, and platform auth. | -| `diffpal debug prompt` | Render prompts and task snapshots without a provider call. | -| `diffpal sarif` | Convert a findings bundle to SARIF. | -| `diffpal version` | Print version metadata. | -| `diffpal completion` | Generate shell completion scripts. | - -All public commands take flags only; there are no positional arguments in the -commands documented below. - -## `diffpal init` - -Generates `.config/diffpal/config.yaml`, `.config/diffpal/.gitignore`, -`.config/diffpal/templates/*`, `.config/diffpal/state/`, and `.diffpalignore`. - -| Flag | Default | Allowed values | -| --- | --- | --- | -| `--wizard` | `false` | boolean | -| `--setup` | `codex-api-key` | `codex-api-key`, `codex-subscription`, `copilot-github-token`, `opencode-acp`, `generic-acp` | -| `--platform` | `auto` | `auto`, `github`, `gitlab`, `azure`, `none` | -| `--profile` | `ci` | letters, numbers, `.`, `_`, `-` | -| `--block-on` | `high` | `low`, `medium`, `high`, `critical` | -| `--config` | `.config/diffpal/config.yaml` | path | -| `--state` | `.config/diffpal/state` | path | -| `--force` | `false` | overwrite existing files | - -Example: - -```bash -npx -y @diffpal/diffpal@latest init --wizard --setup codex-api-key --platform github -``` - -## Review Commands - -Shared review flags: - -| Flag | Default | Purpose | -| --- | --- | --- | -| `--base` | empty | Base revision. Host commands can also resolve this from CI metadata. | -| `--head` | empty | Head revision. Host commands can also resolve this from CI metadata. | -| `--repo` | `local` | Repository ID used in deterministic fingerprints and links. | -| `--review-id` | command-specific | Review identifier used in deterministic output. | -| `--out` | `.artifacts/diffpal/findings.json` | Findings bundle output path. | -| `--language` | config value | Language for findings and summaries. | -| `--instructions` | config value | Replace config review instructions for this run. | -| `--instructions-file` | empty | Append instructions from a file. | -| `--block-on` | config value or `high` | Minimum blocking severity. | -| `--feedback` | `review` | `summary` or `review`. | -| `--gate` | `false` | Return non-zero when blocking findings exist. | - -### `diffpal review local` - -Outputs: - -- writes the findings bundle to `--out`; -- prints Markdown summary or review output to stdout. - -Example: - -```bash -diffpal --profile ci review local \ - --base origin/main \ - --head HEAD \ - --feedback summary \ - --out .artifacts/diffpal/findings.json -``` - -### `diffpal review github` - -Additional flags: - -| Flag | Default | Purpose | -| --- | --- | --- | -| `--review-channel` | `diffpal` | GitHub publishing channel for PR reviews. | -| `--summary-overview` | `true` | Include semantic change overview in summaries. | -| `--dry-run` | `false` | Print host review Markdown without publishing. Supported for GitHub only. | - -Environment inputs: - -- `GITHUB_TOKEN` for publishing unless config auth supplies a token; -- `GITHUB_REPOSITORY`, `GITHUB_EVENT_PATH`, `GITHUB_EVENT_NAME` from GitHub - Actions; -- `GITHUB_BASE_SHA` and `GITHUB_HEAD_SHA` as fallback base/head inputs; -- `DIFFPAL_GITHUB_API_URL` for tests or GitHub Enterprise API override. - -Default surfaces: - -- `summary`: SARIF and summary; -- `review`: PR review comments, SARIF, and summary. - -Example: - -```bash -diffpal --profile ci review github \ - --base "$BASE_SHA" \ - --head "$HEAD_SHA" \ - --repo "$GITHUB_REPOSITORY" \ - --review-id "github-pr-${PR_NUMBER}" \ - --feedback review \ - --gate -``` - -### `diffpal review gitlab` - -`--dry-run` appears in the shared host help, but GitLab review rejects it. - -Environment inputs: - -- `GITLAB_TOKEN` or `CI_JOB_TOKEN` for publishing unless config auth supplies a - token; -- `CI_PROJECT_PATH`, `CI_MERGE_REQUEST_IID`, - `CI_MERGE_REQUEST_DIFF_BASE_SHA`, `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`, - `CI_COMMIT_SHA`, `CI_COMMIT_SHORT_SHA`; -- `GITLAB_EVENT_PATH` or `CI_MERGE_REQUEST_EVENT_PATH` as payload fallback; -- `CI_JOB_URL` for status target URL; -- `DIFFPAL_GITLAB_API_URL` for tests or self-managed GitLab API override. - -Default surfaces: - -- `summary`: Code Quality, SARIF, status, and summary; -- `review`: Code Quality, discussions, status, SARIF, and summary. - -### `diffpal review ado` - -Alias: `diffpal review azure`. - -`--dry-run` appears in the shared host help, but Azure review rejects it. - -Environment inputs: - -- `SYSTEM_ACCESSTOKEN` or `AZURE_DEVOPS_EXT_PAT` for publishing unless config - auth supplies a token; -- `SYSTEM_COLLECTIONURI`, `SYSTEM_TEAMPROJECT`, `BUILD_REPOSITORY_NAME`, - `BUILD_REPOSITORY_ID`, `BUILD_REPOSITORY_URI`, `BUILD_BUILDID`; -- `SYSTEM_PULLREQUEST_PULLREQUESTID`, `SYSTEM_PULLREQUEST_SOURCEBRANCH`, - `SYSTEM_PULLREQUEST_TARGETBRANCH`, `SYSTEM_PULLREQUEST_SOURCECOMMITID`, - `SYSTEM_PULLREQUEST_TARGETCOMMITID`; -- `BUILD_SOURCEVERSION` as a head/base fallback; -- `SYSTEM_PULLREQUEST_EVENT_PAYLOAD` as payload fallback. - -Default surfaces: - -- `summary`: status and summary; -- `review`: PR threads, status, and summary. - -## `diffpal doctor` - -Validates local runtime and environment. - -| Flag | Default | Allowed values | -| --- | --- | --- | -| `--mode` | `local` | `local`, `github`, `gitlab`, `ado` | - -Outputs diagnostic lines to stdout. Missing selected-provider auth is a warning -in local mode and an error in host modes. Platform auth is checked for host -modes. - -```bash -diffpal --profile ci doctor --mode github -``` - -## `diffpal debug prompt` - -Renders the system prompt, task snapshot, and a mock findings bundle without a -provider call. It still loads config and resolves the review scope. - -Additional flags: - -| Flag | Default | Allowed values | -| --- | --- | --- | -| `--format` | `text` | `text`, `json` | -| `--dry-run` | `true` | suppress normal review summary output | - -It also accepts the shared review analysis and policy flags. - -```bash -diffpal --profile ci debug prompt --base origin/main --head HEAD --format text -``` - -## `diffpal sarif` - -Converts a findings bundle to SARIF. - -| Flag | Default | Purpose | -| --- | --- | --- | -| `--input` | `.artifacts/diffpal/findings.json` | Input findings bundle. | -| `--out` | `.artifacts/diffpal/diffpal.sarif` | Output SARIF report. | - -Output line: - -```text -sarif= findings= version= -``` - -## `diffpal version` - -Prints: - -```text -diffpal + () -``` - -Development builds use `0.0.0-dev+unknown (unknown)`. - -## `diffpal completion` - -Generates Cobra shell completion scripts. Use `diffpal completion --help` for -the shell-specific subcommands generated by the CLI framework. diff --git a/codex.md b/codex.md deleted file mode 100644 index fa54774..0000000 --- a/codex.md +++ /dev/null @@ -1,114 +0,0 @@ -# Codex Provider - -## When To Use This Provider - -Use Codex when you want the default DiffPal onboarding path, a copy-paste Codex -API-key setup, or trusted CI that restores an existing Codex auth file. - -## Prerequisites - -- A DiffPal config committed at `.config/diffpal/config.yaml`. -- Node.js available in the CI job. -- Either an `OPENAI_API_KEY` CI secret or a trusted `CODEX_AUTH_JSON_B64` CI - secret generated from your own Codex login. - -## Installation - -Install the Codex CLI and ACP bridge in CI: - -```bash -npm install --global @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3 -``` - -## Authentication In CI - -For API-key auth, store `OPENAI_API_KEY` as a protected CI secret and run: - -Do not expose `OPENAI_API_KEY` to untrusted fork jobs. Keep the credentialed -review job limited to trusted branches, same-repository pull requests, or -maintainer-approved jobs that do not execute fork-controlled code. - -```bash -printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key -``` - -For subscription auth, generate `CODEX_AUTH_JSON_B64` with the recipe in -[`examples/README.md`](https://github.com/diffpal/diffpal/blob/main/examples/README.md#generate-codex_auth_json_b64), -then restore it only in trusted CI: - -Do not expose restored Codex auth files to untrusted fork jobs. - -```bash -mkdir -p "$HOME/.codex" -printf '%s' "$CODEX_AUTH_JSON_B64" | base64 --decode > "$HOME/.codex/auth.json" -chmod 600 "$HOME/.codex/auth.json" -``` - -## Minimal Verified Configuration - -Use [`examples/configs/codex-api-key/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/codex-api-key/config.yaml) -for API-key auth or -[`examples/configs/codex-subscription/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/codex-subscription/config.yaml) -for subscription auth. - -The provider selection is: - -```yaml -runtime: - providers: - codex-acp: - type: codex_acp - codex_acp: - reasoning_effort: low - -diffpal: - provider: codex-acp -``` - -## How To Test Provider Connectivity - -Validate the local runtime first: - -```bash -diffpal doctor --profile ci --mode local -``` - -Then run a provider-backed smoke review on a trusted branch: - -```bash -diffpal --profile ci review local \ - --base origin/main \ - --head HEAD \ - --feedback summary \ - --out .artifacts/diffpal/findings.json -``` - -## Expected Result - -The smoke review should complete, write -`.artifacts/diffpal/findings.json`, and print a Markdown summary to stdout. - -## Security Considerations - -Do not expose `OPENAI_API_KEY` or restored Codex auth files to untrusted fork -jobs. Keep Codex credentials in protected CI secrets and run secret-backed -review only in trusted branches, same-repository pull requests, or -maintainer-approved jobs that do not execute untrusted code with secrets. - -## Common Failures - -- The Codex CLI or ACP bridge is not installed before DiffPal runs. -- `OPENAI_API_KEY` or `CODEX_AUTH_JSON_B64` is missing from the trusted CI job. -- Subscription auth was generated from an expired or invalid local login. -- The selected `diffpal.provider` does not match the `codex-acp` provider entry. - -## Links To Complete CI Examples - -- [GitHub Actions with Codex API key](https://github.com/diffpal/diffpal/blob/main/examples/ci/github-actions/codex-api-key.yml) -- [GitHub Actions with Codex subscription auth](https://github.com/diffpal/diffpal/blob/main/examples/ci/github-actions/codex-subscription.yml) -- [GitLab CI with Codex API key](https://github.com/diffpal/diffpal/blob/main/examples/ci/gitlab/codex-api-key.yml) -- [GitLab CI with Codex subscription auth](https://github.com/diffpal/diffpal/blob/main/examples/ci/gitlab/codex-subscription.yml) -- [Azure Pipelines with Codex API key](https://github.com/diffpal/diffpal/blob/main/examples/ci/azure-pipelines/codex-api-key.yml) -- [Azure Pipelines with Codex subscription auth](https://github.com/diffpal/diffpal/blob/main/examples/ci/azure-pipelines/codex-subscription.yml) - -Next step: choose the host-specific CI example that matches your code host. diff --git a/comparison.md b/comparison.md deleted file mode 100644 index c3d0771..0000000 --- a/comparison.md +++ /dev/null @@ -1,39 +0,0 @@ -# Comparison Guide - -DiffPal is best understood as an open-source control plane for AI pull request -review. It does not try to be the model, the hosted review platform, or a -general lint result router. - -## DiffPal Vs Hosted AI Reviewers - -Use DiffPal when you want: - -- provider choice through `runtime.providers` -- review config, instructions, artifacts, and gate policy committed with the - repository -- CI-native execution without a mandatory hosted DiffPal review service -- consistent outputs across GitHub, GitLab, and Azure DevOps - -Hosted reviewers can be a better fit when your team wants a fully managed -product experience, centralized account management, or provider decisions made -for you. - -## DiffPal Vs Lint Publishers - -Lint publishers take existing tool output and annotate pull requests. DiffPal -resolves the review scope, asks a selected AI provider for review findings, -validates the structured output, and publishes both human feedback and -machine-readable artifacts. - -Use both together when you want deterministic linters plus policy-aware AI -review in the same CI workflow. - -## DiffPal Vs CI Convention Bots - -CI convention bots are good at enforcing explicit repository rules. DiffPal is -for review feedback that needs model reasoning over a pull request diff while -still producing auditable findings and merge gates. - -Use DiffPal when the important choice is not "which hosted reviewer do we buy?" -but "how do we standardize AI review while keeping control of provider, -workflow, and artifacts?" diff --git a/concepts.md b/concepts.md deleted file mode 100644 index 18025f0..0000000 --- a/concepts.md +++ /dev/null @@ -1,17 +0,0 @@ -# Concepts - -Use this section to understand DiffPal's product model before configuring CI. - -- [How DiffPal works](/how-diffpal-works) explains DiffPal's product, - provider, publisher, and configuration boundaries. -- [Review lifecycle](/review-lifecycle) explains the flow from review scope - resolution to provider review, validation, publishing, artifacts, and optional - gates. -- [Providers and agents](/providers-and-agents) explains the provider versus - agent distinction and who owns authentication. -- [Findings, feedback, and gates](/findings-feedback-and-gates) explains the - concepts behind summaries, inline feedback, artifacts, and merge blocking. -- [Glossary](/glossary) defines the short terms used across guides and - reference pages. -- [Comparison guide](/comparison) explains how DiffPal differs from hosted AI - reviewers, lint publishers, and CI convention bots. diff --git a/configuration.md b/configuration.md deleted file mode 100644 index 04aed78..0000000 --- a/configuration.md +++ /dev/null @@ -1,261 +0,0 @@ -# Configuration Reference - -DiffPal reads repository configuration from `.config/diffpal/config.yaml`. -The file is YAML, uses top-level `version: v1`, and keeps review policy with -the repository. - -Task-oriented setup lives in [Getting Started](/getting-started), -[Providers](/providers), and [Integrations](/integrations). - -## Loading And Overrides - -Default config root: - -- `.config/diffpal/config.yaml` - -When `--config-dir ` is set, DiffPal searches: - -1. `/diffpal/config.yaml` -2. `/config.yaml` -3. `.config/diffpal/config.yaml` - -Profiles are selected by `--profile` or `DIFFPAL_PROFILE`. Environment -overrides are applied after config loading and before validation. - -## Complete Hierarchy - -```yaml -version: v1 - -runtime: - providers: - : - type: - mcp_servers: [] - system_instructions: "" - : {} - mcp_servers: - : - type: stdio - -diffpal: - provider: - gate: - block_on: high - review: - language: en - instructions: "" - timeout: 5m - platforms: - github: - auth: - token: "" - gitlab: - auth: - job_token: "" - api_token: "" - azure: - auth: - system_access_token: "" - pat: "" - -profiles: - ci: - runtime: {} - diffpal: {} -``` - -## Required Fields - -| Field | Required | Default | Allowed values | -| --- | --- | --- | --- | -| `version` | Optional | `v1` from defaults | empty or `v1` | -| `runtime.providers` | Required for review | empty | map of provider IDs | -| `runtime.providers..type` | Required | none | `generic_acp`, `gemini_acp`, `codex_acp`, `opencode_acp`, `copilot_acp`, `claude_code_acp`, `openai`, `aistudio`, `pool` | -| `diffpal.provider` | Required | empty | provider ID present in `runtime.providers` | -| `diffpal.gate.block_on` | Optional | `high` | `low`, `medium`, `high`, `critical` | -| `diffpal.review.language` | Optional | `en` | any single-line language value | -| `diffpal.review.instructions` | Optional | empty | string | -| `diffpal.review.timeout` | Optional | `5m` | positive Go duration such as `180s`, `5m`, `10m` | - -`diffpal.provider` must match one key in `runtime.providers`. - -## Runtime Providers - -Each provider is discriminated by `type`; the matching block contains -type-specific settings. - -```yaml -runtime: - providers: - codex-acp: - type: codex_acp - codex_acp: - reasoning_effort: low - -diffpal: - provider: codex-acp -``` - -Common provider fields: - -| Field | Applies to | Purpose | -| --- | --- | --- | -| `mcp_servers` | all providers | IDs from `runtime.mcp_servers` attached to this provider. | -| `system_instructions` | all providers | Provider-level instructions applied by the runtime. | -| `generic_acp`, `gemini_acp`, `codex_acp`, `opencode_acp`, `copilot_acp`, `claude_code_acp` | ACP providers | ACP runtime block. | -| `openai`, `aistudio` | hosted API providers | Hosted API runtime block. | -| `pool` | pool provider | Ordered failover member list. | - -ACP runtime block fields: - -| Field | Required | Default | Allowed values | -| --- | --- | --- | --- | -| `cmd` | Optional | provider alias default, or required for custom `generic_acp` use | string list | -| `extra_args` | Optional | empty | string list | -| `model` | Optional | provider-specific | non-blank string | -| `reasoning_effort` | Optional | provider-specific | `minimal`, `low`, `medium`, `high`, `xhigh` | -| `mode` | Optional | provider-specific | non-blank string | - -Hosted API block fields: - -| Field | Required | Default | Notes | -| --- | --- | --- | --- | -| `api_key` | Required for hosted review unless supplied by env | empty | `OPENAI_API_KEY` for `openai`, `GEMINI_API_KEY` for `aistudio`. | -| `model` | Required for hosted review | empty | Can be overridden for `openai` by `DIFFPAL_OPENAI_MODEL`. | - -Pool block fields: - -| Field | Required | Default | Notes | -| --- | --- | --- | --- | -| `members` | Optional | empty | Provider IDs in ordered failover order. | - -Provider installation and authentication are documented in -[Providers](/providers). - -## MCP Servers - -MCP servers are declared once and referenced by provider ID: - -```yaml -runtime: - mcp_servers: - repo-docs: - type: stdio - cmd: ["your-docs-mcp-server"] - args: ["--root", "."] - env: - DOCS_TOKEN: "${DOCS_TOKEN}" - providers: - codex-acp: - type: codex_acp - mcp_servers: [repo-docs] - codex_acp: - reasoning_effort: low -``` - -MCP server fields: - -| Field | Required | Applies to | Purpose | -| --- | --- | --- | --- | -| `type` | Required | all | `stdio`, `http`, or `sse`. | -| `cmd` | Optional | `stdio` | Executable argv prefix. | -| `args` | Optional | `stdio` | Arguments appended after `cmd`. | -| `env` | Optional | `stdio` | Environment variables for the server process. | -| `working_dir` | Optional | `stdio` | Server working directory. | -| `url` | Optional | `http`, `sse` | Server endpoint. | -| `headers` | Optional | `http`, `sse` | Request headers. | - -Keep MCP credentials in CI secrets. - -## Review Settings - -| Field | Default | Notes | -| --- | --- | --- | -| `diffpal.review.language` | `en` | Used for finding text and summaries. Must be one line. | -| `diffpal.review.instructions` | empty | Appended to the review prompt as repository-owned tuning. | -| `diffpal.review.timeout` | `5m` | Per-attempt provider review timeout. | - -`--language`, `--instructions`, and `--instructions-file` can override or -append instructions for one CLI run. See [CLI](/cli). - -## Review Contract And Severity Matrix - -DiffPal asks providers to report only discrete issues the pull request author -would likely fix before merging, only when the issue is introduced or made -worse by the patch. Providers must use the DiffPal finding taxonomy, prefer -high signal over high recall, use the smallest useful changed-line range, and -may return `review_result` when they can summarize the outcome. - -Severity is based on concrete impact, not confidence or preference. - -- critical: changed code can directly cause severe compromise, destructive data loss, privilege bypass, total outage, or unrecoverable corruption. -- high: changed code can cause an exploitable security flaw, user-visible data corruption, frequent crash, major outage risk, or severe performance regression on a common path. -- medium: changed code can cause an edge-case correctness failure, intermittent reliability issue, meaningful performance cost, confusing maintainability risk, or missing coverage for important behavior. -- low: changed code has a localized maintainability, testing, or style issue with clear evidence and a concrete improvement, but no immediate user-visible failure. -- security: use critical for direct compromise, credential exposure, destructive access, or privilege bypass; high for exploitable vulnerabilities with meaningful impact; medium for plausible weaknesses requiring extra conditions; low for hardening gaps with limited direct exploitability. -- correctness: use critical for unrecoverable corruption or system-wide wrong behavior; high for common-path wrong results or data corruption; medium for plausible edge-case failures; low for small inconsistencies with bounded impact. -- reliability: use critical for total outage, deadlock, or unrecoverable resource exhaustion; high for frequent crashes, leaks, or retry storms; medium for intermittent failure modes; low for localized resilience or observability gaps. -- performance: use critical for regressions that can make the service unavailable or explode cost; high for severe common-path latency, memory, or query regressions; medium for measurable inefficient behavior; low for small avoidable inefficiencies with clear evidence. -- maintainability: use critical only when the change creates an immediate operational hazard; high when the change makes future safe modification very risky; medium for confusing structure likely to cause defects; low for localized clarity or consistency issues. -- testing: use critical only when missing validation can allow severe unsafe behavior to ship; high for untested high-risk behavior; medium for missing meaningful coverage of new behavior; low for small missing edge-case coverage. -- style: use critical, high, or medium only when the issue has a non-style impact and should usually be reclassified; use low for repo-enforced style/readability issues that are actionable. - -## Gate - -```yaml -diffpal: - gate: - block_on: high -``` - -`block_on` sets the minimum severity that counts as blocking. The allowed values -are `low`, `medium`, `high`, and `critical`. Use `--gate` in CI to make -blocking findings fail the process. See [Exit behavior](/exit-behavior). - -## Platform Auth - -Platform auth can live in config, but standard CI environment variables are -preferred. - -| Platform | Config field | Preferred env | -| --- | --- | --- | -| GitHub | `diffpal.platforms.github.auth.token` | `GITHUB_TOKEN` | -| GitLab | `diffpal.platforms.gitlab.auth.job_token` | `CI_JOB_TOKEN` | -| GitLab | `diffpal.platforms.gitlab.auth.api_token` | `GITLAB_TOKEN` | -| Azure DevOps | `diffpal.platforms.azure.auth.system_access_token` | `SYSTEM_ACCESSTOKEN` | -| Azure DevOps | `diffpal.platforms.azure.auth.pat` | `AZURE_DEVOPS_EXT_PAT` | - -Blank auth values fail validation. Missing optional config values are allowed -when the matching environment variable will be present in CI. - -## Profiles - -Profiles override the same root sections: - -```yaml -profiles: - ci: - diffpal: - gate: - block_on: high - review: - language: en -``` - -Select a profile with `--profile ci` or `DIFFPAL_PROFILE=ci`. - -## Environment Overrides - -| Variable | Overrides | -| --- | --- | -| `DIFFPAL_PROFILE` | selected profile when `--profile` is not set | -| `DIFFPAL_PROVIDER` | `diffpal.provider` | -| `DIFFPAL_BLOCK_ON` | `diffpal.gate.block_on` | -| `DIFFPAL_OPENAI_MODEL` | `runtime.providers.*.openai.model` | -| `DIFFPAL_REVIEW_LANGUAGE` | `diffpal.review.language` | -| `DIFFPAL_REVIEW_INSTRUCTIONS` | `diffpal.review.instructions` | -| `DIFFPAL_REVIEW_TIMEOUT` | `diffpal.review.timeout` | - -Config loading also expands `$VAR` and `${VAR}` placeholders before YAML -parsing. Missing placeholder variables fail config loading. diff --git a/copilot.md b/copilot.md deleted file mode 100644 index 3657566..0000000 --- a/copilot.md +++ /dev/null @@ -1,96 +0,0 @@ -# Copilot Provider - -## When To Use This Provider - -Use Copilot when your organization already uses Copilot and can provide a -supported Copilot token to the CI job that runs DiffPal. - -## Prerequisites - -- A DiffPal config committed at `.config/diffpal/config.yaml`. -- Node.js available in the CI job. -- A `COPILOT_GITHUB_TOKEN` CI secret for the Copilot CLI. - -## Installation - -Install the Copilot CLI in CI: - -```bash -npm install --global @github/copilot@1.0.61 -``` - -## Authentication In CI - -Store `COPILOT_GITHUB_TOKEN` as a protected CI secret. The Copilot CLI reads -`COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, then `GITHUB_TOKEN`; use -`COPILOT_GITHUB_TOKEN` for DiffPal so the provider token stays separate from -the platform publishing token. - -Do not expose `COPILOT_GITHUB_TOKEN` to untrusted fork jobs. Keep the -credentialed review job limited to trusted branches, same-repository pull -requests, or maintainer-approved jobs that do not execute fork-controlled code. - -## Minimal Verified Configuration - -Use [`examples/configs/copilot-github-token/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/copilot-github-token/config.yaml). - -The provider selection is: - -```yaml -runtime: - providers: - copilot-acp: - type: copilot_acp - copilot_acp: - model: auto - -diffpal: - provider: copilot-acp -``` - -## How To Test Provider Connectivity - -Validate the local runtime first: - -```bash -diffpal doctor --profile ci --mode local -``` - -Then run a provider-backed smoke review on a trusted branch: - -```bash -diffpal --profile ci review local \ - --base origin/main \ - --head HEAD \ - --feedback summary \ - --out .artifacts/diffpal/findings.json -``` - -## Expected Result - -The smoke review should complete, write -`.artifacts/diffpal/findings.json`, and print a Markdown summary to stdout. - -## Security Considerations - -Do not reuse the platform publishing token as the Copilot provider token. Keep -`COPILOT_GITHUB_TOKEN` in protected CI secrets and run secret-backed review only -in trusted branches, same-repository pull requests, or maintainer-approved jobs -that do not execute untrusted code with secrets. - -## Common Failures - -- The Copilot CLI is not installed before DiffPal runs. -- `COPILOT_GITHUB_TOKEN` is missing from the trusted CI job. -- The token lacks the Copilot Requests permission required by the Copilot CLI. -- A classic PAT is used where the Copilot CLI requires a fine-grained token. -- The selected `diffpal.provider` does not match the `copilot-acp` provider - entry. - -## Links To Complete CI Examples - -- [GitHub Actions with Copilot token](https://github.com/diffpal/diffpal/blob/main/examples/ci/github-actions/copilot-github-token.yml) -- [GitLab CI with Copilot token](https://github.com/diffpal/diffpal/blob/main/examples/ci/gitlab/copilot-github-token.yml) -- [Azure Pipelines with Copilot token](https://github.com/diffpal/diffpal/blob/main/examples/ci/azure-pipelines/copilot-github-token.yml) - -Next step: choose the host-specific CI example that matches your code host. diff --git a/custom-acp.md b/custom-acp.md deleted file mode 100644 index 76a146b..0000000 --- a/custom-acp.md +++ /dev/null @@ -1,94 +0,0 @@ -# Custom ACP-Compatible CLI - -## When To Use This Provider - -Use a custom ACP-compatible CLI when you have another agent process that can -start an ACP stdio server and you want DiffPal to keep the same review, -artifact, publishing, and gate workflow. - -## Prerequisites - -- A DiffPal config committed at `.config/diffpal/config.yaml`. -- A CLI that can start an ACP stdio server. -- Provider-specific credentials configured in trusted CI. - -## Installation - -Install your ACP-compatible CLI before running DiffPal. Pin the package, -container image, or source revision in CI so review behavior is repeatable. - -## Authentication In CI - -Authenticate the CLI with its own supported mechanism before running DiffPal. -Store provider credentials in protected CI secrets and do not commit them to the -DiffPal config. - -Do not expose provider credentials to untrusted fork jobs. Keep the -credentialed review job limited to trusted branches, same-repository pull -requests, or maintainer-approved jobs that do not execute fork-controlled code. - -## Minimal Verified Configuration - -Use [`examples/configs/generic-acp/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/generic-acp/config.yaml) -as the starting point and replace `generic_acp.cmd` with the command that -starts your provider's ACP stdio server: - -```yaml -runtime: - providers: - my-review-agent: - type: generic_acp - generic_acp: - cmd: ["your-acp-cli", "acp", "--stdio"] - -diffpal: - provider: my-review-agent -``` - -## How To Test Provider Connectivity - -Validate the local runtime first: - -```bash -diffpal doctor --profile ci --mode local -``` - -Then run a provider-backed smoke review on a trusted branch: - -```bash -diffpal --profile ci review local \ - --base origin/main \ - --head HEAD \ - --feedback summary \ - --out .artifacts/diffpal/findings.json -``` - -## Expected Result - -The smoke review should complete, write -`.artifacts/diffpal/findings.json`, and print a Markdown summary to stdout. - -## Security Considerations - -DiffPal delegates provider-specific model, account, tool, sandbox, and approval -policy to the ACP CLI you configure. Keep credentials in protected CI secrets -and run secret-backed review only in trusted branches, same-repository pull -requests, or maintainer-approved jobs that do not execute untrusted code with -secrets. - -## Common Failures - -- `generic_acp.cmd` does not start an ACP stdio server. -- The CLI is not installed in the CI job. -- Required provider-specific credentials are missing. -- The configured command requires interactive input in CI. -- The selected `diffpal.provider` does not match the provider ID under - `runtime.providers`. - -## Links To Complete CI Examples - -- [Generic ACP config](https://github.com/diffpal/diffpal/blob/main/examples/configs/generic-acp/config.yaml) -- [Custom CI/CD guide](/custom-ci) - -Next step: replace `generic_acp.cmd` with your ACP command, then run the -portable [Custom CI/CD](/custom-ci) flow. diff --git a/custom-ci.md b/custom-ci.md deleted file mode 100644 index eb853bc..0000000 --- a/custom-ci.md +++ /dev/null @@ -1,187 +0,0 @@ -# Custom CI/CD - -Use this page to run DiffPal from Jenkins, Buildkite, CircleCI, Bitbucket -Pipelines, an internal runner, or any other CI system. This is a portable -integration contract, not native product support for those CI systems. - -## Integration Modes - -| Mode | What DiffPal does | -| --- | --- | -| Artifact-only review | Runs review, writes artifacts, and prints Markdown output without publishing to a code host. | -| Review plus publishing | Runs review and publishes feedback to GitHub, GitLab, or Azure DevOps when the job has host credentials. | -| Review with a blocking gate | Runs review and returns a non-zero result when blocking findings meet the configured threshold. | - -Native publishers exist for GitHub, GitLab, and Azure DevOps. Other code hosts -can still receive artifact-only output from `diffpal review local`, but DiffPal -does not publish native comments or statuses to unsupported hosts. - -## Required Inputs - -Your CI job must provide: - -- repository working tree; -- full git history for the reviewed range; -- base and head revisions; -- DiffPal configuration at `.config/diffpal/config.yaml`; -- provider executable and credentials; -- host credentials when publishing to GitHub, GitLab, or Azure DevOps. - -## Generic Execution Lifecycle - -1. Checkout the repository. -2. Fetch enough git history to resolve base and head. -3. Install the provider executable. -4. Authenticate the provider. -5. Install DiffPal. -6. Validate required environment variables and revisions. -7. Execute review. -8. Publish output when using a native host publisher. -9. Upload `.artifacts/diffpal/`. -10. Enforce the process exit result. - -## Base And Head Resolution - -DiffPal needs two revisions: - -| Value | Meaning | -| --- | --- | -| `base` | The target branch revision or merge-base used as the comparison start. | -| `head` | The pull request, merge request, or candidate commit being reviewed. | - -Your CI system must supply these values from pull-request metadata or from its -own build variables. Shallow clones, missing target branches, and deleted base -refs break review scope resolution because DiffPal cannot compute the reviewed -change range. Fetch full history or explicitly fetch the target branch before -running DiffPal. - -## Portable Example - -This vendor-neutral shell example performs an artifact-only review. It uses the -current CLI command and flags for `diffpal review local`. The provider setup -shown is the Codex API-key path; use [Providers](/providers) to -replace those install and authentication commands for another provider. - -```bash -set -eu - -: "${DIFFPAL_BASE_REV:?set DIFFPAL_BASE_REV to the target/base revision}" -: "${DIFFPAL_HEAD_REV:?set DIFFPAL_HEAD_REV to the reviewed/head revision}" -: "${DIFFPAL_REPO_ID:?set DIFFPAL_REPO_ID to a stable repository id}" -: "${OPENAI_API_KEY:?set OPENAI_API_KEY for the Codex provider}" -``` - -`OPENAI_API_KEY` is a provider credential. Do not expose it to untrusted fork -builds or jobs that execute fork-controlled code. - -```bash -git fetch --tags --prune -git rev-parse --verify "$DIFFPAL_BASE_REV^{commit}" -git rev-parse --verify "$DIFFPAL_HEAD_REV^{commit}" - -npm install --global @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3 -printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key -npm install --global @diffpal/diffpal@latest -mkdir -p .artifacts/diffpal - -diffpal --profile ci review local \ - --base "$DIFFPAL_BASE_REV" \ - --head "$DIFFPAL_HEAD_REV" \ - --repo "$DIFFPAL_REPO_ID" \ - --review-id "custom-ci-${DIFFPAL_HEAD_REV}" \ - --feedback review \ - --out .artifacts/diffpal/findings.json \ - > .artifacts/diffpal/summary.md -``` - -To publish to a native host, use the matching command and host credentials: - -- `diffpal review github` -- `diffpal review gitlab` -- `diffpal review ado` - -Pass `--gate` when blocking findings should fail the CI job. - -## CI Concept Mapping - -| CI concept | Capability to configure | -| --- | --- | -| Checkout | Clone the repository and fetch the target/base revision plus the reviewed/head revision. | -| Protected secrets | Expose provider credentials, and host credentials when publishing, only to trusted jobs. | -| Pull-request metadata | Provide stable base revision, head revision, repository id, and review id. | -| Artifact upload | Persist the files created by the selected review command. | -| Required check/gate | Use the DiffPal process exit result as the CI job result when `--gate` is enabled. | - -## Outputs - -Verified local artifact paths for the portable `review local` example: - -| Path | Purpose | -| --- | --- | -| `.artifacts/diffpal/findings.json` | Canonical structured findings bundle. | -| `.artifacts/diffpal/summary.md` | Human-readable review summary captured from stdout. | - -Native host publishers can create additional platform artifacts: - -| Path | Purpose | -| --- | --- | -| `.artifacts/diffpal/diffpal.sarif` | SARIF report when enabled by the platform output. | -| `.artifacts/diffpal/codequality.json` | GitLab Code Quality report. | - -Publishing is available only through the native GitHub, GitLab, and Azure -commands. `feedback` controls what DiffPal tries to publish or print: -`summary` omits file-level findings, while `review` includes file-level -feedback where the selected mode supports it. - -Gating is separate from feedback. `--gate` controls whether blocking findings -make the process return non-zero. Feedback can still show blocking findings -when the gate is disabled. - -## Expected Results - -The portable artifact-only example should create -`.artifacts/diffpal/findings.json` and a captured -`.artifacts/diffpal/summary.md`. Native host commands should additionally -publish the feedback surfaces listed in the -[support matrix](/support-matrix). - -## Security - -Do not expose provider or host secrets to untrusted fork builds. Run -secret-backed review only for trusted branches, same-repository pull requests, -or maintainer-approved jobs that do not execute untrusted code with secrets. - -For untrusted contributions, run no-secret CI checks only, or require a -maintainer-controlled rerun after reviewing the submitted workflow changes. -Artifact-only review still runs a provider-backed review, so it must not receive -provider credentials in a job that executes untrusted fork code. - -Use [Secrets and fork PRs](/secrets-and-fork-prs) for the full -credential and fork PR guide. - -## Failure Handling - -DiffPal returns success when the review completes and no enabled gate blocks the -job. With `--gate`, blocking findings return a non-zero process result. -Configuration, provider authentication, review scope resolution, and publishing -failures also return non-zero because the review result is incomplete. - -Treat the process exit result as the stable public contract. Do not depend on -specific numeric exit codes unless they are documented as stable for the -command you are using. - -## Boundaries - -DiffPal has native publishers for: - -- GitHub; -- GitLab; -- Azure DevOps. - -When running against another code host, DiffPal can still produce local -Markdown and artifacts, including `findings.json`, but it does not create -native comments, discussions, threads, checks, statuses, or branch-policy -signals for that host. - -Next step: upload `.artifacts/diffpal/` from your CI job and verify the first -run with [Verify First Review](/verify-first-review). diff --git a/docs-source.json b/docs-source.json new file mode 100644 index 0000000..1ffb718 --- /dev/null +++ b/docs-source.json @@ -0,0 +1,4 @@ +{ + "repository": "diffpal/diffpal", + "ref": "78c6b3e9fdc60366e60c3d7b02574364c9c5bfd5" +} diff --git a/docs.md b/docs.md deleted file mode 100644 index 2aeef6c..0000000 --- a/docs.md +++ /dev/null @@ -1,76 +0,0 @@ -# DiffPal Docs - -Choose the section that matches what you want to do. - -## Getting Started - -Use [Getting Started](/getting-started) for the first successful -review path. Start with the -[GitHub quickstart](/github-quickstart), then verify the -expected summary, comments, artifacts, and gate behavior with -[Verify First Review](/verify-first-review). Continue with -[Next Steps](/next-steps) after the first run works. - -## Concepts - -Use [Concepts](/concepts) to understand how DiffPal turns pull request -diffs into structured findings and host-native feedback. The section also -includes the [comparison guide](/comparison). - -- [How DiffPal works](/how-diffpal-works) -- [Review lifecycle](/review-lifecycle) -- [Providers and agents](/providers-and-agents) -- [Findings, feedback, and gates](/findings-feedback-and-gates) -- [Glossary](/glossary) - -## Integrations - -Use [Integrations](/integrations) for CI setup and host-specific -requirements: - -- [GitHub Actions](/github-actions) -- [GitLab CI](/gitlab-ci) -- [Azure Pipelines](/azure-pipelines) -- [Custom CI/CD](/custom-ci) - -## Providers - -Use [Providers](/providers) to choose Codex, Copilot, OpenCode, or a -custom ACP-compatible CLI: - -- [Codex](/codex) -- [Copilot](/copilot) -- [OpenCode](/opencode) -- [Custom ACP-compatible CLI](/custom-acp) - -## Guides - -Use [Guides](/guides) for operational guidance that spans setup and -reference material: - -- [Secrets and fork PRs](/secrets-and-fork-prs) -- [Security controls](/security) - -## Reference - -Use [Reference](/reference) for stable contracts: - -- [Configuration](/configuration) -- [CLI](/cli) -- [Findings schema](/findings-schema) -- [Artifacts](/artifacts) -- [Exit behavior](/exit-behavior) -- [Versioning](/versioning) -- [Support matrix](/support-matrix) - -## Help - -Use [Help](/help) for operational fixes, including -[troubleshooting](/troubleshooting) for missing comments, token failures, -fork PRs, and incomplete diffs. Use the [FAQ](/faq) for short answers -to common product, provider, CI, and artifact questions. - -## Examples - -Use the [examples gallery](https://github.com/diffpal/diffpal/blob/main/examples/README.md) for copy-paste configs and CI -files. diff --git a/exit-behavior.md b/exit-behavior.md deleted file mode 100644 index 34e9965..0000000 --- a/exit-behavior.md +++ /dev/null @@ -1,59 +0,0 @@ -# Exit Behavior - -DiffPal uses process exit status to distinguish completed review, blocked -review, setup problems, provider problems, publishing problems, and internal -tooling failures. - -| Code | Meaning | -| --- | --- | -| `0` | Command completed successfully. Review may still contain findings when gate is disabled. | -| `2` | Configuration, profile, provider validation, CLI flag, platform auth, or diff context/setup failure. | -| `3` | Transient provider failure such as provider timeout or retryable provider error. | -| `4` | Publishing or conversion failure, including platform API publishing and SARIF conversion. | -| `5` | Internal tooling or local file/output failure. | -| `10` | Blocking findings detected and `--gate` was enabled. | -| `130` | Interrupted or cancelled by the process environment. | - -## Success - -Without `--gate`, a review command returns `0` when review, artifact writing, -and any requested publishing complete. Findings can still be present and can -still be marked `blocking` in artifacts and summaries. - -## Blocking Findings - -With `--gate`, DiffPal counts findings whose severity meets -`diffpal.gate.block_on` or `--block-on`. If any are blocking, the command -returns exit code `10` after review output is written and publishing has been -attempted. - -## Setup Failure - -Exit code `2` covers invalid config, missing config, invalid feedback mode, -invalid review channel, invalid instructions file, missing platform token, and -missing host context such as base/head/repository metadata. - -Review scope resolution failures are setup/context failures and also return `2`. - -## Provider Failure - -Provider validation failures return `2`. Transient provider runtime failures -return `3`. Other provider/runtime failures return `5`. - -## Publishing Failure - -Host publishing failures return `4`. This includes platform API failures and -publishing file conversion errors. The `diffpal sarif` command also returns `4` -for failed input reading, SARIF conversion, or SARIF output writing. - -## Behavior With And Without Gating - -| Gate enabled | Blocking findings exist | Exit code | Feedback/artifacts | -| --- | --- | --- | --- | -| no | no | `0` | written/published | -| no | yes | `0` | written/published, may report blocking status in output | -| yes | no | `0` | written/published | -| yes | yes | `10` | written/published before the gate error | - -Tooling failures return their failure code regardless of gate setting because -the review result is incomplete. diff --git a/faq.md b/faq.md deleted file mode 100644 index 73b6efb..0000000 --- a/faq.md +++ /dev/null @@ -1,81 +0,0 @@ -# FAQ - -## Is A Hosted DiffPal Service Required? - -No. DiffPal runs in your CI. It can publish to supported code hosts from that -CI job when you provide host credentials. - -See [How DiffPal works](/how-diffpal-works). - -## Can Existing Agents Be Used? - -Yes, when they are exposed through a supported provider type or an -ACP-compatible CLI. DiffPal selects the provider from `diffpal.provider` and -`runtime.providers`. - -See [Providers](/providers) and -[Providers and agents](/providers-and-agents). - -## Which Hosts Are Supported? - -DiffPal has native publishers for GitHub pull requests, GitLab merge requests, -and Azure DevOps pull requests. Unsupported code hosts can still use local -Markdown and artifacts through custom CI. - -See the [support matrix](/support-matrix). - -## Is Custom CI Supported? - -Yes. Jenkins, Buildkite, CircleCI, Bitbucket Pipelines, internal runners, and -other CI systems can run DiffPal through the stable custom CI contract. That -does not imply native support for those CI products. - -See [Custom CI/CD](/custom-ci). - -## How Are Provider Costs And Accounts Handled? - -DiffPal does not own, create, bill, or manage third-party provider accounts. -Provider credentials, quotas, billing, and model access belong to the provider -account you configure in CI. - -See [Providers](/providers) and -[Secrets and fork PRs](/secrets-and-fork-prs). - -## What Happens When No Findings Exist? - -A completed review can legitimately produce no findings. The summary and -artifacts should still show that the review ran. With no blocking findings, an -enabled gate passes. - -See [Verify First Review](/verify-first-review) and -[Exit behavior](/exit-behavior). - -## Can Comments And Gates Be Configured Independently? - -Yes. `feedback` controls summary versus inline feedback. `--gate` or -`gate: true` controls whether blocking findings fail the job. A run can publish -feedback without blocking merges, or block based on findings after output is -written. - -See [Findings, feedback, and gates](/findings-feedback-and-gates) -and [Merge gates](/integrations#merge-gates). - -## How Are Fork PRs Handled? - -Secret-backed DiffPal review should run only for trusted branches, -same-repository pull requests, or maintainer-approved jobs that do not execute -fork-controlled code with secrets. Fork PRs should run no-secret CI unless a -maintainer uses a safe trusted workflow. - -See [Secrets and fork PRs](/secrets-and-fork-prs). - -## Where Are Artifacts Written? - -DiffPal writes artifacts under `.artifacts/diffpal/` by default. The canonical -findings bundle is `.artifacts/diffpal/findings.json`. Host commands can also -write `summary.md`, SARIF, Code Quality, and host-specific publishing payloads. - -See [Artifacts](/artifacts). - -Next step: use [Getting Started](/getting-started) when you are -ready to configure the first review. diff --git a/findings-feedback-and-gates.md b/findings-feedback-and-gates.md deleted file mode 100644 index 0f45b5a..0000000 --- a/findings-feedback-and-gates.md +++ /dev/null @@ -1,55 +0,0 @@ -# Findings, Feedback, And Gates - -DiffPal separates the review result from where it is shown and whether it -blocks a merge. - -## Finding - -A finding is one concrete issue returned by the provider and validated by -DiffPal. It includes a category, severity, message, impact, and changed-file -location when the issue can be anchored inline. - -## Severity - -Severity describes concrete impact, not confidence or preference. DiffPal uses -severity to decide which findings are advisory and which meet the configured -blocking threshold. - -## Summary - -The summary is the top-level human-readable review output. It explains the -reviewed change and the review result even when there are no actionable -findings. - -## Inline Feedback - -Inline feedback is file-level feedback on changed lines, such as GitHub review -comments, GitLab discussions, or Azure PR threads. Inline feedback depends on -the selected host publisher and feedback mode. - -## Output Artifact - -An output artifact is a file written by DiffPal, such as -`.artifacts/diffpal/findings.json`, `summary.md`, SARIF, or GitLab Code Quality -JSON. Artifacts let CI retain the review result even when no inline comments -are published. - -## Blocking Threshold - -The blocking threshold is the minimum severity that counts as blocking. A -repository might start with `high` so only high and critical findings block the -gate. - -## Feedback And Merge Blocking Are Separate - -Feedback visibility answers "what should users see?" Merge blocking answers -"should this CI job fail?" Keeping them separate lets teams roll out DiffPal -safely: - -- publish summaries and artifacts without inline comments; -- show inline feedback without failing merges; -- enable a gate only after the team agrees on the blocking threshold; -- lower the threshold later without changing provider setup. - -Use [Integrations](/integrations) for host feedback modes and -[Configuration](/configuration#gate) for the gate field. diff --git a/findings-schema.md b/findings-schema.md deleted file mode 100644 index 1896095..0000000 --- a/findings-schema.md +++ /dev/null @@ -1,132 +0,0 @@ -# Findings Schema - -The canonical review artifact is -`.artifacts/diffpal/findings.json`, a JSON serialization of DiffPal's findings -bundle. New review writes use `version: "v3"` unless a bundle version is -already set by the caller. - -## Canonical Bundle - -| Field | Required | Meaning | -| --- | --- | --- | -| `version` | yes | Bundle version. New writes use `v3`; readers accept `v1`, `v2`, and `v3`. | -| `review_id` | yes | Stable review identifier. | -| `base_sha` | yes | Base revision used for the review. | -| `head_sha` | yes | Head revision used for the review. | -| `language` | no | Language requested for generated text. | -| `prompt` | no | Prompt metadata. | -| `inspection` | no | Provider inspection metadata. | -| `change_summary` | no | Human-readable summary bullets. | -| `review_result` | no | Human-readable review outcome sentence. | -| `files` | no | Reviewed files. | -| `findings` | yes | Finding array. May be empty. | - -Prompt metadata fields: - -| Field | Meaning | -| --- | --- | -| `prompt_id` | Prompt identifier, currently `diffpal.review` for review output. | -| `prompt_version` | Prompt version used for the review. | -| `purpose` | Prompt purpose. | -| `schema_version` | Prompt output schema version, currently `findings.v3`. | - -Inspection metadata fields: - -| Field | Meaning | -| --- | --- | -| `provider_type` | Runtime provider type when available. | -| `required` | Whether inspection metadata was required by the runtime. | -| `tool_calls` | Tool call names when available. | -| `diff_inspected` | Whether the provider reported diff inspection. | -| `context_inspected` | Whether the provider reported context inspection. | - -## Finding Fields - -| Field | Required | Meaning | -| --- | --- | --- | -| `id` | written by DiffPal | Deterministic fingerprint. | -| `review_id` | written by DiffPal when missing | Review identifier copied from the bundle. | -| `category` | yes | Finding category. | -| `severity` | yes | `low`, `medium`, `high`, or `critical`. | -| `confidence` | yes | Number from `0` to `1`. | -| `path` | yes | File path for the finding. | -| `start_line` | yes | Positive start line. | -| `end_line` | yes | Positive end line, greater than or equal to `start_line`. | -| `changed_span` | yes for v2/v3 | Changed-line span that anchors the finding. | -| `supporting_span` | no | Additional context span. | -| `title` | yes | Short finding title. | -| `message` | yes | Finding explanation. | -| `evidence` | yes | Structured evidence for v2/v3. | -| `impact` | yes | Structured impact for v2/v3. | -| `suggestion` | no | Suggested fix. | -| `blocking` | written by DiffPal | Whether the finding meets the active threshold. | -| `provider` | no | Provider ID that produced the finding. | - -Line span representation: - -```json -{ - "path": "internal/session.go", - "start_line": 12, - "end_line": 14 -} -``` - -Evidence representation: - -```json -{ - "anchor": "changed lines call exec with request input", - "reasoning_basis": "the command arguments now include unsanitized user data", - "source": "changed_line" -} -``` - -Impact representation: - -```json -{ - "summary": "users can execute unintended shell commands", - "scope": "request handling path" -} -``` - -## Severity And Location - -Allowed severities are `low`, `medium`, `high`, and `critical`. -DiffPal normalizes severity to lowercase. - -Location is represented twice for compatibility: - -- `path`, `start_line`, and `end_line` are the primary line fields; -- `changed_span` carries the same changed-line anchor in structured form. - -For v2/v3, `changed_span.path`, `changed_span.start_line`, and -`changed_span.end_line` are required and must be positive. - -## Compatibility - -DiffPal readers accept: - -- `v1` bundles where `evidence` and `impact` may be legacy strings; -- `v2` bundles with structured evidence and impact; -- `v3` bundles with optional `review_result`. - -New writes use `v3`. Consumers should ignore unknown fields and treat -`findings[]` as the canonical machine-readable issue list. - -## Consumer Example - -Fail a CI step when the canonical bundle contains blocking findings: - -```bash -jq -e '[.findings[] | select(.blocking == true)] | length == 0' \ - .artifacts/diffpal/findings.json -``` - -Count high and critical findings regardless of whether the gate was enabled: - -```bash -jq '[.findings[] | select(.severity == "high" or .severity == "critical")] | length' \ - .artifacts/diffpal/findings.json -``` diff --git a/getting-started.md b/getting-started.md deleted file mode 100644 index 5af2f94..0000000 --- a/getting-started.md +++ /dev/null @@ -1,54 +0,0 @@ -# Getting Started - -Use this section to choose the shortest path to your first useful DiffPal -review. - -## Prerequisites - -Before you start, have: - -- a repository on GitHub, GitLab, or Azure DevOps; -- permission to add CI configuration and repository secrets; -- one supported review provider or ACP-compatible agent; -- a pull request or merge request you can use for a trusted first test. - -If the terms are new, read [How DiffPal works](/how-diffpal-works) -and the [Glossary](/glossary) first. -Before adding provider secrets, read -[Secrets and fork PRs](/secrets-and-fork-prs). - -## Choose Code Host - -| Host | Start here | -| --- | --- | -| GitHub Actions | [GitHub quickstart](/github-quickstart) | -| GitLab CI | [GitLab CI guide](/gitlab-ci) | -| Azure Pipelines | [Azure Pipelines guide](/azure-pipelines) | -| Custom CI/CD | [Custom CI/CD guide](/custom-ci) | - -## Choose Provider - -The fastest GitHub path uses the Codex API-key recipe because it is ready to -copy. Codex is not the product boundary: the same DiffPal workflow works with -other supported providers and ACP-compatible agents. - -| Provider path | Start here | -| --- | --- | -| Codex API key | [GitHub quickstart](/github-quickstart) | -| Codex subscription auth, Copilot, OpenCode, or generic ACP | [Providers](/providers) | - -## Choose Feedback Mode - -| Mode | Use when | -| --- | --- | -| `summary` | You want a PR/MR summary and non-file artifacts without inline review comments. | -| `review` | You want the summary plus file-level comments, discussions, or PR threads. | - -The GitHub quickstart uses `review` so the first run shows the full review -surface. - -## Start - -Use [GitHub quickstart](/github-quickstart) to install DiffPal in a new GitHub -repository, then use [Verify First Review](/verify-first-review) to confirm -the first run worked. After that, continue with [Next Steps](/next-steps). diff --git a/github-actions.md b/github-actions.md deleted file mode 100644 index c89190d..0000000 --- a/github-actions.md +++ /dev/null @@ -1,156 +0,0 @@ -# GitHub Actions - -Use this page to run DiffPal in GitHub Actions. For the shortest first setup, -start with the [GitHub quickstart](/github-quickstart). - -## Supported Outputs - -- Pull request review summary. -- File-level review comments on changed lines. -- SARIF upload output when enabled by the workflow. -- CI check result from the `diffpal` workflow. - -## Prerequisites - -- A GitHub repository with Actions enabled. -- Permission to add repository secrets and workflows. -- A committed DiffPal config at `.config/diffpal/config.yaml`. -- A provider secret such as `OPENAI_API_KEY`. - -See [Shared Setup](/integrations#shared-setup) and -[Providers](/providers). - -## Required Checkout Behavior - -Use a full checkout so DiffPal can compare the pull request base and head: - -```yaml -- uses: actions/checkout@v4 - with: - fetch-depth: 0 -``` - -## Required Token And Minimum Permissions - -GitHub provides `GITHUB_TOKEN`. Grant the workflow only the permissions DiffPal -needs to read code and publish PR feedback: - -```yaml -permissions: - contents: read - pull-requests: write -``` - -`GITHUB_TOKEN` is the host publishing credential. Keep it separate from provider -credentials such as `OPENAI_API_KEY`. - -## Provider Installation And Authentication - -Install and authenticate the selected provider before the DiffPal step. Use -[Providers](/providers) for Codex, Copilot, OpenCode, and custom -ACP-compatible CLI setup. - -Provider credentials allow the selected third-party provider to process the -review input. Store them as GitHub secrets and keep the credentialed review job -restricted to trusted pull requests. See -[Secrets and fork PRs](/secrets-and-fork-prs). - -## Minimal Pipeline - -```yaml -name: diffpal - -on: - pull_request: - types: [opened, synchronize, reopened, ready_for_review] - -jobs: - review: - if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }} - runs-on: ubuntu-latest - permissions: - contents: read - pull-requests: write - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - uses: actions/setup-node@v4 - with: - node-version: 22 - - - name: Install Codex provider - run: npm install --global @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3 - - - name: Authenticate Codex - run: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key - env: - OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} - - - name: Review pull request - uses: diffpal/action@v1 - with: - profile: ci - base: ${{ github.event.pull_request.base.sha }} - head: ${{ github.event.pull_request.head.sha }} - repo: ${{ github.repository }} - review-id: github-pr-${{ github.event.pull_request.number }} - feedback: review - gate: true - env: - OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - -## Feedback Modes - -Use `feedback: review` for a PR summary plus file-level comments. Use -`feedback: summary` for the summary and non-file artifacts only. - -See [Feedback Modes](/integrations#feedback-modes). - -## Merge-Gate Setup - -Set `gate: true` on `diffpal/action@v1`. Blocking findings fail the workflow -when they meet `diffpal.gate.block_on`. - -See [Merge Gates](/integrations#merge-gates). - -## Fork Or Untrusted-Contribution Behavior - -Keep provider credentials out of fork PR code. The minimal pipeline restricts -secret-backed review to same-repository PRs with: - -```yaml -if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }} -``` - -See [Secrets and fork PRs](/secrets-and-fork-prs). - -## Expected Results - -- A PR review headed `DiffPal Review Summary`. -- Inline review comments when actionable findings exist and feedback is - `review`. -- `.artifacts/diffpal/findings.json` in the workflow workspace. -- A failed workflow only for blocking gated findings or incomplete review setup. - -## Common Failures - -- `pull-requests: write` is missing. -- `fetch-depth: 0` is missing. -- `OPENAI_API_KEY` is missing or invalid. -- The PR is from a fork, so the same-repository guard skipped secret-backed - review. - -See [Common Failures](/integrations#common-failures). - -## Related Examples - -- [Codex API key](https://github.com/diffpal/diffpal/blob/main/examples/ci/github-actions/codex-api-key.yml) -- [Codex subscription auth](https://github.com/diffpal/diffpal/blob/main/examples/ci/github-actions/codex-subscription.yml) -- [Copilot token](https://github.com/diffpal/diffpal/blob/main/examples/ci/github-actions/copilot-github-token.yml) - -Next step: use [Verify First Review](/verify-first-review) -after the first GitHub Actions run completes. diff --git a/github-quickstart.md b/github-quickstart.md deleted file mode 100644 index 84f4534..0000000 --- a/github-quickstart.md +++ /dev/null @@ -1,107 +0,0 @@ -# GitHub Quickstart - -Use this page to add DiffPal to a new GitHub repository and see the first PR -review. - -This path uses the Codex API-key recipe because it is a complete copy-paste -GitHub Actions setup. Codex is not the product boundary; other supported -providers and ACP agents can use the same DiffPal workflow. -See [Codex Provider](/codex) for provider-specific setup -details. - -## 1. Create A Setup Branch - -Run this from the repository root: - -```bash -git switch -c diffpal-onboarding -``` - -## 2. Add The Provider Secret - -Add this repository secret in GitHub: - -| Secret | Purpose | -| --- | --- | -| `OPENAI_API_KEY` | Lets the Codex CLI act as the review provider. | - -DiffPal runs in your CI and sends review input to the provider you configure. -For this setup, `OPENAI_API_KEY` belongs to the Codex provider, not to GitHub. -Store it as a repository secret and do not expose it to untrusted fork PR code. - -With GitHub CLI: - -```bash -gh secret set OPENAI_API_KEY -``` - -Keep secret-backed DiffPal review limited to same-repository pull requests and -let forks run no-secret CI only. See -[Secrets and fork PRs](/secrets-and-fork-prs) for the security -rationale. - -## 3. Initialize Config - -Run this from the repository root: - -```bash -npx -y @diffpal/diffpal@latest init --wizard --setup codex-api-key --platform github -``` - -This creates `.config/diffpal/config.yaml` with Codex ACP as the provider, -`block_on: high`, a `ci` profile, and a GitHub platform block. Existing files -are preserved unless you pass `--force`. - -Commit the generated config: - -```bash -git add .config/diffpal/config.yaml .config/diffpal/.gitignore -git commit -m "chore: add diffpal config" -``` - -## 4. Install Workflow - -Copy the GitHub Actions example: - -```bash -mkdir -p .github/workflows -cp examples/ci/github-actions/codex-api-key.yml .github/workflows/diffpal.yml -``` - -Commit the workflow: - -```bash -git add .github/workflows/diffpal.yml -git commit -m "ci: add diffpal review" -``` - -The workflow performs a full checkout, installs the Codex provider command, -authenticates with `OPENAI_API_KEY`, runs `diffpal/action@v1`, publishes review -feedback, and enables the gate. - -## 5. Test A Trusted Pull Request - -Push the branch and open a pull request from a branch in the same repository: - -```bash -git push -u origin HEAD -``` - -Use a same-repository pull request for the first test so the provider secret is -available to the workflow. - -## Expected Result - -After the workflow completes, the pull request should show: - -- a `DiffPal Review Summary` review; -- inline review comments when actionable findings exist; -- a `diffpal` workflow check; -- `.artifacts/diffpal/findings.json` in the workflow workspace. - -If the run has no actionable findings, the review summary and artifacts should -still appear. If setup, authentication, review scope resolution, or publishing -fails, the workflow should fail because the review is incomplete. - -Use [Verify First Review](/verify-first-review) to check the first run, then -continue with [Next Steps](/next-steps). diff --git a/gitlab-ci.md b/gitlab-ci.md deleted file mode 100644 index 2a7c55e..0000000 --- a/gitlab-ci.md +++ /dev/null @@ -1,148 +0,0 @@ -# GitLab CI - -Use this page to run DiffPal in GitLab merge request pipelines. - -## Supported Outputs - -- Merge request summary discussion. -- File-level discussions for actionable findings. -- Code Quality report. -- SARIF report. -- Commit status named `DiffPal Review`. - -## Prerequisites - -- A GitLab project with merge request pipelines. -- A committed DiffPal config at `.config/diffpal/config.yaml`. -- A provider secret such as `OPENAI_API_KEY`. -- A platform token path that can publish MR feedback. - -See [Shared Setup](/integrations#shared-setup) and -[Providers](/providers). - -## Required Checkout Behavior - -Set full git depth so DiffPal can compare base and head: - -```yaml -variables: - GIT_DEPTH: "0" -``` - -Pass `--base "$CI_MERGE_REQUEST_DIFF_BASE_SHA"` and -`--head "$CI_COMMIT_SHA"` when running `diffpal review gitlab`. - -## Required Token And Minimum Permissions - -DiffPal can publish with: - -| Token | Use when | -| --- | --- | -| `CI_JOB_TOKEN` | Your instance allows MR API publishing with the built-in job token. | -| `GITLAB_TOKEN` | You need a dedicated API token for MR discussions/status publishing. | - -Use protected/masked variables for provider tokens. Prefer the least-privilege -token that can create MR discussions, publish commit status, and upload reports. -Keep host tokens separate from provider credentials such as `OPENAI_API_KEY`. - -## Provider Installation And Authentication - -Install and authenticate the selected provider before the DiffPal step. Use -[Providers](/providers) for Codex, Copilot, OpenCode, and custom -ACP-compatible CLI setup. - -Provider credentials allow the selected third-party provider to process the -review input. Store them as protected and masked variables, and expose them only -to trusted pipelines. See -[Secrets and fork PRs](/secrets-and-fork-prs). - -## Minimal Pipeline - -```yaml -stages: - - review - -diffpal-review: - stage: review - image: node:22 - rules: - - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_PATH == $CI_PROJECT_PATH && $DIFFPAL_TRUSTED_REVIEW == "true"' - when: manual - allow_failure: false - - when: never - resource_group: "diffpal:$CI_MERGE_REQUEST_IID" - before_script: - - npm install --global @diffpal/diffpal@latest @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3 - - printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key - script: - - >- - diffpal --profile ci review gitlab - --base "$CI_MERGE_REQUEST_DIFF_BASE_SHA" - --head "$CI_COMMIT_SHA" - --repo "$CI_PROJECT_PATH" - --review-id "gitlab-mr-$CI_MERGE_REQUEST_IID" - --feedback review - --gate - variables: - GIT_DEPTH: "0" - artifacts: - when: always - paths: - - .artifacts/diffpal/ - reports: - codequality: .artifacts/diffpal/codequality.json - sarif: .artifacts/diffpal/diffpal.sarif -``` - -## Feedback Modes - -Use `--feedback review` for a summary discussion plus file-level discussions. -Use `--feedback summary` for summary, status, Code Quality, and SARIF without -file-level discussions. - -See [Feedback Modes](/integrations#feedback-modes). - -## Merge-Gate Setup - -Pass `--gate`. Blocking findings return exit code `10` after publishing -succeeds and are represented by unresolved blocker discussions plus the -`DiffPal Review` status. - -See [Merge Gates](/integrations#merge-gates) and -[Exit behavior](/exit-behavior). - -## Fork Or Untrusted-Contribution Behavior - -Keep provider credentials available only to trusted pipelines. For fork merge -requests, use no-secret CI or a maintainer-approved manual job. The minimal -pipeline and examples use same-project conditions, a manual -`DIFFPAL_TRUSTED_REVIEW` guard, and protected variables for secret-backed -review. - -See [Secrets and fork PRs](/secrets-and-fork-prs). - -## Expected Results - -- GitLab discussions for actionable findings when feedback is `review`. -- A merge request summary discussion. -- Code Quality and SARIF artifacts. -- A commit status named `DiffPal Review`. -- `.artifacts/diffpal/summary.md` in job artifacts. - -## Common Failures - -- `GIT_DEPTH: "0"` is missing. -- `CI_JOB_TOKEN` lacks MR API permissions; use `GITLAB_TOKEN`. -- Provider variables are not protected/masked or are unavailable to the job. -- The pipeline is not a merge request pipeline, so MR context is missing. - -See [Common Failures](/integrations#common-failures). - -## Related Examples - -- [Codex API key](https://github.com/diffpal/diffpal/blob/main/examples/ci/gitlab/codex-api-key.yml) -- [Codex subscription auth](https://github.com/diffpal/diffpal/blob/main/examples/ci/gitlab/codex-subscription.yml) -- [Copilot token](https://github.com/diffpal/diffpal/blob/main/examples/ci/gitlab/copilot-github-token.yml) - -Next step: use [Verify First Review](/verify-first-review) -after the first GitLab pipeline completes. diff --git a/glossary.md b/glossary.md deleted file mode 100644 index 38ebde6..0000000 --- a/glossary.md +++ /dev/null @@ -1,61 +0,0 @@ -# Glossary - -## PR/MR - -Pull request or merge request. DiffPal uses the term for a proposed code change -that can be reviewed before merge. - -## Provider - -The configured runtime entry selected by `diffpal.provider` from -`runtime.providers`. - -## ACP - -Agent Client Protocol. DiffPal can run ACP-compatible CLIs as review agents. - -## Finding - -A structured review issue with severity, category, impact, message, and -location metadata. - -## Publisher - -The DiffPal component that turns validated review output into host-native -feedback such as comments, discussions, statuses, SARIF, or Code Quality -reports. - -## Feedback - -The visible review output users see in a host or local report, such as a -summary, inline comment, discussion, or thread. - -## Gate - -The optional CI behavior that returns a failing result when findings meet or -exceed the configured blocking threshold. - -## Profile - -A named config override selected for a run, commonly `ci`, that adjusts the -base repository config without changing the whole file. - -## Artifact - -A file written by DiffPal, usually under `.artifacts/diffpal/`, that records -the review result for CI uploads, auditing, or downstream processing. - -## Base - -The revision used as the comparison start. In PR/MR review, it is usually the -target branch revision or a merge base. - -## Head - -The revision being reviewed. In PR/MR review, it is usually the source branch -commit. - -## Merge Base - -The common ancestor used to compare a source branch against a target branch -when the host or CI system does not provide an exact base commit. diff --git a/guides.md b/guides.md deleted file mode 100644 index 4da1b31..0000000 --- a/guides.md +++ /dev/null @@ -1,11 +0,0 @@ -# Guides - -Use this section for operational guidance that spans getting started, -integrations, providers, and reference pages. - -- [Secrets and fork PRs](/secrets-and-fork-prs): credentials, trusted - pipelines, fork pull request safety, artifact retention, and security - reporting. - -Next step: read [Secrets and fork PRs](/secrets-and-fork-prs) before adding -or changing provider credentials. diff --git a/help.md b/help.md deleted file mode 100644 index 19ecaa3..0000000 --- a/help.md +++ /dev/null @@ -1,12 +0,0 @@ -# Help - -Use this section when a DiffPal run does not produce the expected host feedback -or artifacts, or when you need a short factual answer before choosing a guide. - -- [Troubleshooting](/troubleshooting) starts from observable symptoms such as - missing jobs, auth failures, missing summaries, artifact gaps, and gate - surprises. -- [FAQ](/faq) answers common product, provider, host, CI, fork PR, gate, and - artifact questions. -- [Secrets and fork PRs](/secrets-and-fork-prs) covers credential - handling and untrusted contribution safety. diff --git a/how-diffpal-works.md b/how-diffpal-works.md deleted file mode 100644 index 543d276..0000000 --- a/how-diffpal-works.md +++ /dev/null @@ -1,67 +0,0 @@ -# How DiffPal Works - -DiffPal is an open-source pull request and merge request review engine that -runs in your CI workflow. It standardizes how a repository asks an AI provider -for review, validates the response, publishes feedback, writes artifacts, and -optionally blocks a merge. - -## Product Boundary - -DiffPal owns the review workflow around the provider: - -- resolving the requested base/head range and review scope; -- building the review request; -- validating provider output against changed files and lines; -- rendering summaries, findings, and artifacts; -- publishing to supported code hosts; -- applying the configured gate. - -DiffPal is not the model, the provider account, or a mandatory hosted review -service. - -When a remote provider is configured, DiffPal sends review input to that -provider from the CI job. Use -[Security controls](/security) before enabling secret-backed review. - -## Provider Boundary - -The selected provider or ACP-compatible CLI owns model reasoning, model access, -provider-specific tools, credentials, sandboxing, and account management. -DiffPal chooses a provider through `diffpal.provider`, sends the review task, -and expects structured review output back. - -Use [Providers and agents](/providers-and-agents) for the provider model and -[Providers](/providers) for setup pages. - -## Publisher Boundary - -DiffPal publishers turn validated findings into host-native feedback. GitHub, -GitLab, and Azure DevOps have native publishers. Custom CI can still produce -local artifacts, and can publish through a supported code host when the job has -the required host metadata and credentials. - -Use the [support matrix](/support-matrix) for supported host -outputs. - -## Repository-Owned Configuration - -DiffPal reads `.config/diffpal/config.yaml` from the repository. That file owns -the selected provider, review settings, platform publishing settings, profiles, -and gate threshold. CI files install/authenticate the provider and pass host -context, but the review policy stays with the repository. - -```mermaid -flowchart LR - A[PR or MR event] --> B[CI job] - B --> C[Repository DiffPal config] - C --> D[DiffPal review engine] - D --> E[Selected provider or ACP agent] - E --> F[Structured findings] - F --> G[Publisher] - F --> H[Artifacts] - F --> I[Optional gate] -``` - -For the first setup path, start with the -[GitHub quickstart](/github-quickstart). For supported -hosts and outputs, see the [support matrix](/support-matrix). diff --git a/index.md b/index.md index bf97596..7bfec64 100644 --- a/index.md +++ b/index.md @@ -1,5 +1,6 @@ --- layout: home +editLink: false hero: name: DiffPal diff --git a/integrations.md b/integrations.md deleted file mode 100644 index 7a8436e..0000000 --- a/integrations.md +++ /dev/null @@ -1,89 +0,0 @@ -# Integrations - -Use this section to run DiffPal in CI and publish review feedback to your code -host. Host-specific pages all follow the same shape: - -For the review flow behind these CI steps, see -[Review lifecycle](/review-lifecycle). - -- [GitHub Actions](/github-actions) -- [GitLab CI](/gitlab-ci) -- [Azure Pipelines](/azure-pipelines) -- [Custom CI/CD](/custom-ci) - -Copy-paste configs and pipelines live in [`examples/`](https://github.com/diffpal/diffpal/blob/main/examples/README.md). -Use the [GitHub quickstart](/github-quickstart) when you -want the shortest first setup path. -Use [Providers](/providers) to choose Codex, Copilot, OpenCode, or -a custom ACP-compatible CLI. - -## Shared Setup - -Every host needs: - -1. Full git history for the reviewed pull request or merge request. -2. A DiffPal config committed at `.config/diffpal/config.yaml`. -3. The provider CLI runtime required by the selected - [provider](/providers). -4. A provider auth secret. -5. A platform token with permission to publish review feedback. - -DiffPal runs in your CI and sends review input to the provider you configure. -Protect provider credentials before enabling secret-backed review. See -[Secrets and fork PRs](/secrets-and-fork-prs). - -For Jenkins, Buildkite, CircleCI, Bitbucket Pipelines, internal runners, or any -other CI system, use the [Custom CI/CD guide](/custom-ci). - -## Feedback Modes - -Use `feedback` for normal setup: - -| Feedback | Behavior | -| --- | --- | -| `summary` | PR/MR summary plus non-file artifacts such as status, SARIF, or Code Quality. No file-level findings are published. | -| `review` | Summary plus file-level comments, threads, or discussions for the platform. Non-blocking findings remain visible without becoming merge blockers. | - -Default review publish surfaces: - -| Platform | Default surfaces | -| --- | --- | -| GitHub | `comments,sarif,summary` | -| GitLab | `code-quality,discussions,status,sarif,summary` | -| Azure | `threads,status,summary` | - -Common artifacts are listed in the [artifacts reference](/artifacts). - -## Merge Gates - -Enable `gate` when blocking findings should fail the CI job. Start with -`block_on: high`; lower the threshold only after tuning review policy. See the -[configuration gate reference](/configuration#gate) and -[exit behavior](/exit-behavior). - -Tooling failures such as setup, provider auth, review scope resolution, or -publishing fail the job because the review result is incomplete, even when the -merge gate is disabled. - -## Untrusted Contributions - -Keep provider credentials out of untrusted fork pipelines. Run secret-backed -DiffPal review only for trusted branches, same-repository pull requests, or -maintainer-approved workflows that do not execute untrusted code with secrets. - -See [Secrets and fork PRs](/secrets-and-fork-prs). - -## Common Failures - -Most integration failures come from: - -- shallow checkout; -- missing provider secret; -- provider CLI not installed or authenticated; -- platform token missing write permission; -- running secret-backed review on an untrusted fork PR. - -Use the [troubleshooting guide](/troubleshooting) for fixes. - -Next step: open the host-specific integration page for the CI system that will -run DiffPal. diff --git a/next-steps.md b/next-steps.md deleted file mode 100644 index 3af9bbd..0000000 --- a/next-steps.md +++ /dev/null @@ -1,45 +0,0 @@ -# Next Steps - -Use this page after your first DiffPal review is working. - -## Change Provider - -Switch providers by changing the selected `runtime.providers` entry and the -matching CI install/authentication step. Start with the -[Providers](/providers) section or use -[Custom ACP-Compatible CLI](/custom-acp) for a custom agent. - -## Enable Review Comments - -Set feedback mode to `review` when you want file-level comments, discussions, or -PR threads. Use `summary` when you only want the summary and non-file artifacts. -See [Feedback Modes](/integrations#feedback-modes). - -## Configure Policy - -Tune review language, repository instructions, profiles, MCP servers, and -severity policy in `.config/diffpal/config.yaml`. See the -[configuration reference](/configuration). - -## Enable A Merge Gate - -Enable the gate in CI when blocking findings should fail the job. Start with -`block_on: high`; lower the threshold only after your team has tuned the review -policy. See [Gate](/configuration#gate). - -## Retain Artifacts - -Upload `.artifacts/diffpal/` from CI when you need audit records, SARIF, Code -Quality reports, or the canonical findings bundle after the job completes. See -the [artifacts reference](/artifacts). - -## Move To Another Host Or CI - -Use the same DiffPal config shape and change the CI host setup: - -- [GitLab CI](/gitlab-ci) -- [Azure Pipelines](/azure-pipelines) -- [Custom CI/CD](/custom-ci) - -Next step: choose the integration page for the CI system that will run the next -DiffPal review. diff --git a/opencode.md b/opencode.md deleted file mode 100644 index 0a8248b..0000000 --- a/opencode.md +++ /dev/null @@ -1,92 +0,0 @@ -# OpenCode Provider - -## When To Use This Provider - -Use OpenCode when your CI environment already installs and authenticates an -OpenCode CLI that can run as the selected DiffPal provider. - -## Prerequisites - -- A DiffPal config committed at `.config/diffpal/config.yaml`. -- An OpenCode CLI available in the CI job. -- Provider credentials configured with OpenCode's own authentication flow. - -## Installation - -Install OpenCode in CI using the installation method you use for OpenCode in -that environment. Pin the OpenCode package or source revision in your CI setup -the same way you pin other provider CLIs. - -## Authentication In CI - -Authenticate OpenCode before running DiffPal. Store any OpenCode credentials in -protected CI secrets and pass them to the OpenCode CLI using its supported -authentication mechanism. - -Do not expose OpenCode credentials to untrusted fork jobs. Keep the -credentialed review job limited to trusted branches, same-repository pull -requests, or maintainer-approved jobs that do not execute fork-controlled code. - -## Minimal Verified Configuration - -Use [`examples/configs/opencode-acp/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/opencode-acp/config.yaml). - -The provider selection is: - -```yaml -runtime: - providers: - opencode-acp: - type: opencode_acp - opencode_acp: - model: opencode/big-pickle - -diffpal: - provider: opencode-acp -``` - -## How To Test Provider Connectivity - -Validate the local runtime first: - -```bash -diffpal doctor --profile ci --mode local -``` - -Then run a provider-backed smoke review on a trusted branch: - -```bash -diffpal --profile ci review local \ - --base origin/main \ - --head HEAD \ - --feedback summary \ - --out .artifacts/diffpal/findings.json -``` - -## Expected Result - -The smoke review should complete, write -`.artifacts/diffpal/findings.json`, and print a Markdown summary to stdout. - -## Security Considerations - -DiffPal does not manage OpenCode accounts, credentials, models, or sandbox -settings. Keep OpenCode credentials in protected CI secrets and run -secret-backed review only in trusted branches, same-repository pull requests, or -maintainer-approved jobs that do not execute untrusted code with secrets. - -## Common Failures - -- The OpenCode CLI is not installed before DiffPal runs. -- OpenCode authentication is missing from the trusted CI job. -- The configured model is not available to the authenticated OpenCode account. -- The selected `diffpal.provider` does not match the `opencode-acp` provider - entry. - -## Links To Complete CI Examples - -- [OpenCode ACP config](https://github.com/diffpal/diffpal/blob/main/examples/configs/opencode-acp/config.yaml) -- [Integration guides](/integrations) - -Next step: adapt the OpenCode config, then choose the integration page for your -CI host. diff --git a/package-lock.json b/package-lock.json index 040cac4..55bec97 100644 --- a/package-lock.json +++ b/package-lock.json @@ -369,9 +369,9 @@ } }, "node_modules/@esbuild/aix-ppc64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz", - "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", + "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==", "cpu": [ "ppc64" ], @@ -382,13 +382,13 @@ "aix" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/android-arm": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz", - "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz", + "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==", "cpu": [ "arm" ], @@ -399,13 +399,13 @@ "android" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/android-arm64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz", - "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz", + "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==", "cpu": [ "arm64" ], @@ -416,13 +416,13 @@ "android" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/android-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz", - "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz", + "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==", "cpu": [ "x64" ], @@ -433,13 +433,13 @@ "android" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/darwin-arm64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz", - "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz", + "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==", "cpu": [ "arm64" ], @@ -450,13 +450,13 @@ "darwin" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/darwin-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz", - "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz", + "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==", "cpu": [ "x64" ], @@ -467,13 +467,13 @@ "darwin" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/freebsd-arm64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz", - "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz", + "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==", "cpu": [ "arm64" ], @@ -484,13 +484,13 @@ "freebsd" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/freebsd-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz", - "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz", + "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==", "cpu": [ "x64" ], @@ -501,13 +501,13 @@ "freebsd" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-arm": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz", - "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz", + "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==", "cpu": [ "arm" ], @@ -518,13 +518,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-arm64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz", - "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz", + "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==", "cpu": [ "arm64" ], @@ -535,13 +535,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-ia32": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz", - "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz", + "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==", "cpu": [ "ia32" ], @@ -552,13 +552,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-loong64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz", - "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz", + "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==", "cpu": [ "loong64" ], @@ -569,13 +569,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-mips64el": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz", - "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz", + "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==", "cpu": [ "mips64el" ], @@ -586,13 +586,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-ppc64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz", - "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz", + "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==", "cpu": [ "ppc64" ], @@ -603,13 +603,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-riscv64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz", - "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz", + "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==", "cpu": [ "riscv64" ], @@ -620,13 +620,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-s390x": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz", - "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz", + "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==", "cpu": [ "s390x" ], @@ -637,13 +637,13 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/linux-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz", - "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz", + "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==", "cpu": [ "x64" ], @@ -654,13 +654,30 @@ "linux" ], "engines": { - "node": ">=12" + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz", + "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" } }, "node_modules/@esbuild/netbsd-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz", - "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz", + "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==", "cpu": [ "x64" ], @@ -671,13 +688,30 @@ "netbsd" ], "engines": { - "node": ">=12" + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz", + "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" } }, "node_modules/@esbuild/openbsd-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz", - "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz", + "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==", "cpu": [ "x64" ], @@ -688,13 +722,30 @@ "openbsd" ], "engines": { - "node": ">=12" + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz", + "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" } }, "node_modules/@esbuild/sunos-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz", - "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz", + "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==", "cpu": [ "x64" ], @@ -705,13 +756,13 @@ "sunos" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/win32-arm64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz", - "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz", + "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==", "cpu": [ "arm64" ], @@ -722,13 +773,13 @@ "win32" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/win32-ia32": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz", - "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz", + "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==", "cpu": [ "ia32" ], @@ -739,13 +790,13 @@ "win32" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@esbuild/win32-x64": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz", - "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz", + "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==", "cpu": [ "x64" ], @@ -756,7 +807,7 @@ "win32" ], "engines": { - "node": ">=12" + "node": ">=18" } }, "node_modules/@iconify-json/simple-icons": { @@ -1706,9 +1757,9 @@ } }, "node_modules/esbuild": { - "version": "0.21.5", - "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", - "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==", + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz", + "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==", "dev": true, "hasInstallScript": true, "license": "MIT", @@ -1716,32 +1767,35 @@ "esbuild": "bin/esbuild" }, "engines": { - "node": ">=12" + "node": ">=18" }, "optionalDependencies": { - "@esbuild/aix-ppc64": "0.21.5", - "@esbuild/android-arm": "0.21.5", - "@esbuild/android-arm64": "0.21.5", - "@esbuild/android-x64": "0.21.5", - "@esbuild/darwin-arm64": "0.21.5", - "@esbuild/darwin-x64": "0.21.5", - "@esbuild/freebsd-arm64": "0.21.5", - "@esbuild/freebsd-x64": "0.21.5", - "@esbuild/linux-arm": "0.21.5", - "@esbuild/linux-arm64": "0.21.5", - "@esbuild/linux-ia32": "0.21.5", - "@esbuild/linux-loong64": "0.21.5", - "@esbuild/linux-mips64el": "0.21.5", - "@esbuild/linux-ppc64": "0.21.5", - "@esbuild/linux-riscv64": "0.21.5", - "@esbuild/linux-s390x": "0.21.5", - "@esbuild/linux-x64": "0.21.5", - "@esbuild/netbsd-x64": "0.21.5", - "@esbuild/openbsd-x64": "0.21.5", - "@esbuild/sunos-x64": "0.21.5", - "@esbuild/win32-arm64": "0.21.5", - "@esbuild/win32-ia32": "0.21.5", - "@esbuild/win32-x64": "0.21.5" + "@esbuild/aix-ppc64": "0.25.12", + "@esbuild/android-arm": "0.25.12", + "@esbuild/android-arm64": "0.25.12", + "@esbuild/android-x64": "0.25.12", + "@esbuild/darwin-arm64": "0.25.12", + "@esbuild/darwin-x64": "0.25.12", + "@esbuild/freebsd-arm64": "0.25.12", + "@esbuild/freebsd-x64": "0.25.12", + "@esbuild/linux-arm": "0.25.12", + "@esbuild/linux-arm64": "0.25.12", + "@esbuild/linux-ia32": "0.25.12", + "@esbuild/linux-loong64": "0.25.12", + "@esbuild/linux-mips64el": "0.25.12", + "@esbuild/linux-ppc64": "0.25.12", + "@esbuild/linux-riscv64": "0.25.12", + "@esbuild/linux-s390x": "0.25.12", + "@esbuild/linux-x64": "0.25.12", + "@esbuild/netbsd-arm64": "0.25.12", + "@esbuild/netbsd-x64": "0.25.12", + "@esbuild/openbsd-arm64": "0.25.12", + "@esbuild/openbsd-x64": "0.25.12", + "@esbuild/openharmony-arm64": "0.25.12", + "@esbuild/sunos-x64": "0.25.12", + "@esbuild/win32-arm64": "0.25.12", + "@esbuild/win32-ia32": "0.25.12", + "@esbuild/win32-x64": "0.25.12" } }, "node_modules/estree-walker": { @@ -1751,6 +1805,24 @@ "dev": true, "license": "MIT" }, + "node_modules/fdir": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", + "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12.0.0" + }, + "peerDependencies": { + "picomatch": "^3 || ^4" + }, + "peerDependenciesMeta": { + "picomatch": { + "optional": true + } + } + }, "node_modules/focus-trap": { "version": "7.8.0", "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.8.0.tgz", @@ -2037,6 +2109,19 @@ "dev": true, "license": "ISC" }, + "node_modules/picomatch": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz", + "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, "node_modules/postcss": { "version": "8.5.15", "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz", @@ -2258,6 +2343,23 @@ "dev": true, "license": "MIT" }, + "node_modules/tinyglobby": { + "version": "0.2.17", + "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz", + "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fdir": "^6.5.0", + "picomatch": "^4.0.4" + }, + "engines": { + "node": ">=12.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/SuperchupuDev" + } + }, "node_modules/trim-lines": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", @@ -2373,21 +2475,24 @@ } }, "node_modules/vite": { - "version": "5.4.21", - "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz", - "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==", + "version": "6.4.3", + "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz", + "integrity": "sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==", "dev": true, "license": "MIT", "dependencies": { - "esbuild": "^0.21.3", - "postcss": "^8.4.43", - "rollup": "^4.20.0" + "esbuild": "^0.25.0", + "fdir": "^6.4.4", + "picomatch": "^4.0.2", + "postcss": "^8.5.3", + "rollup": "^4.34.9", + "tinyglobby": "^0.2.13" }, "bin": { "vite": "bin/vite.js" }, "engines": { - "node": "^18.0.0 || >=20.0.0" + "node": "^18.0.0 || ^20.0.0 || >=22.0.0" }, "funding": { "url": "https://github.com/vitejs/vite?sponsor=1" @@ -2396,19 +2501,25 @@ "fsevents": "~2.3.3" }, "peerDependencies": { - "@types/node": "^18.0.0 || >=20.0.0", + "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0", + "jiti": ">=1.21.0", "less": "*", "lightningcss": "^1.21.0", "sass": "*", "sass-embedded": "*", "stylus": "*", "sugarss": "*", - "terser": "^5.4.0" + "terser": "^5.16.0", + "tsx": "^4.8.1", + "yaml": "^2.4.2" }, "peerDependenciesMeta": { "@types/node": { "optional": true }, + "jiti": { + "optional": true + }, "less": { "optional": true }, @@ -2429,6 +2540,12 @@ }, "terser": { "optional": true + }, + "tsx": { + "optional": true + }, + "yaml": { + "optional": true } } }, diff --git a/package.json b/package.json index 5393595..879c8b7 100644 --- a/package.json +++ b/package.json @@ -3,10 +3,14 @@ "private": true, "type": "module", "scripts": { - "docs:dev": "vitepress .", - "docs:build": "vitepress build .", + "docs:sync": "node scripts/sync-docs.mjs", + "docs:dev": "npm run docs:sync && vitepress .", + "docs:build": "npm run docs:sync && vitepress build .", "docs:preview": "vitepress preview .", - "check": "npm run docs:build" + "check": "npm run docs:build && node scripts/check-privacy.mjs" + }, + "overrides": { + "vite": "6.4.3" }, "devDependencies": { "vitepress": "1.6.4" diff --git a/privacy.md b/privacy.md new file mode 100644 index 0000000..12f7549 --- /dev/null +++ b/privacy.md @@ -0,0 +1,23 @@ +--- +editLink: false +--- + +# Privacy + +DiffPal's documentation site uses Google Analytics only after you choose +**Accept analytics**. No analytics script or request is loaded before consent. + +When enabled, analytics helps the DiffPal maintainers understand aggregate page +usage, navigation, device category, and approximate region. DiffPal does not use +the site analytics integration for advertising or sell analytics data. Google +processes analytics data under its own terms and privacy controls. + +Your choice is stored in your browser's local storage. Use the **Privacy +choices** control at the bottom of any page to change or withdraw that choice. +Withdrawing consent prevents future analytics collection from this browser; it +does not retroactively delete aggregate data already processed. + +For questions about this site or its privacy practices, contact the DiffPal +maintainers through the [DiffPal GitHub organization](https://github.com/diffpal). + +Last updated: July 10, 2026. diff --git a/providers-and-agents.md b/providers-and-agents.md deleted file mode 100644 index c7e0042..0000000 --- a/providers-and-agents.md +++ /dev/null @@ -1,44 +0,0 @@ -# Providers And Agents - -DiffPal separates provider selection from CI and code host setup. - -## Provider Versus Agent - -A provider is the configured runtime entry under `runtime.providers`. It tells -DiffPal which review runtime to use and which provider-specific settings belong -to that runtime. - -An agent is the actual process that performs model-backed review work. For -ACP-based providers, the agent is a CLI process that starts an ACP stdio server. -For hosted provider types, the runtime talks to the hosted API described by the -provider config. - -DiffPal sends the review task and validates the response. The provider or agent -owns model behavior, account access, provider tools, sandbox behavior, and -credentials. - -## Built-In Provider Type Versus Generic ACP - -Built-in provider types encode the known config shape for supported runtimes, -such as Codex ACP, Copilot ACP, and OpenCode ACP. They keep common setup -predictable and let generated configs use stable provider IDs. - -`generic_acp` is the escape hatch for any CLI that can start an ACP stdio -server. DiffPal does not need provider-specific behavior for that path; it only -needs the command that starts the ACP-compatible agent. - -Use [Providers](/providers) for setup pages and -[Configuration](/configuration) for the exhaustive config -contract. - -## Authentication Ownership - -DiffPal does not create, license, or manage third-party provider accounts. -Provider authentication belongs to the provider and to your CI secret -management. Install and authenticate the selected provider before the DiffPal -review step, keep provider credentials out of untrusted fork jobs, and avoid -committing secrets to `.config/diffpal/config.yaml`. - -Platform publishing credentials are separate from provider credentials. A CI -job may need both: one credential lets the provider perform review reasoning, -and another lets DiffPal publish feedback to GitHub, GitLab, or Azure DevOps. diff --git a/providers.md b/providers.md deleted file mode 100644 index 30f0bfa..0000000 --- a/providers.md +++ /dev/null @@ -1,65 +0,0 @@ -# Providers - -Use this section to choose and configure the review provider that DiffPal runs -inside your CI job. - -DiffPal does not own or manage third-party provider accounts. Create, license, -authenticate, and secure the provider account or CLI with that provider's own -tools. - -For the conceptual difference between providers and agents, see -[Providers and agents](/providers-and-agents). - -## Concepts - -| Term | Meaning | -| --- | --- | -| Code host | The system that owns pull requests or merge requests, such as GitHub, GitLab, or Azure DevOps. | -| CI system | The runner that checks out the repository and executes DiffPal, such as GitHub Actions, GitLab CI, Azure Pipelines, or a custom runner. | -| Provider | The configured runtime entry that DiffPal asks to perform review reasoning. | -| Agent | The provider-backed CLI or ACP-compatible process that inspects the requested change or repository context and returns structured review output. | - -The code host decides where feedback is published. The CI system decides how -commands and secrets run. The provider or agent decides which model, account, -tools, sandbox, and credentials are used for review. - -## Provider Selection - -DiffPal selects one provider by matching `diffpal.provider` to an entry under -`runtime.providers`: - -```yaml -runtime: - providers: - codex-acp: - type: codex_acp - codex_acp: - reasoning_effort: low - -diffpal: - provider: codex-acp -``` - -The selected provider ID must exist in `runtime.providers`. Profiles and the -`DIFFPAL_PROVIDER` environment variable can override the selected provider for a -specific CI job. - -## Choose A Provider - -| Provider path | Use when | Setup name | Config example | -| --- | --- | --- | --- | -| [Codex](/codex) | You want the default copy-paste onboarding path or an existing Codex auth file in trusted CI. | `codex-api-key` or `codex-subscription` | [`examples/configs/codex-api-key/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/codex-api-key/config.yaml) | -| [Copilot](/copilot) | Your organization already uses Copilot and can provide a supported Copilot token to CI. | `copilot-github-token` | [`examples/configs/copilot-github-token/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/copilot-github-token/config.yaml) | -| [OpenCode](/opencode) | You want DiffPal to run through an OpenCode ACP provider already installed and authenticated in CI. | `opencode-acp` | [`examples/configs/opencode-acp/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/opencode-acp/config.yaml) | -| [Custom ACP CLI](/custom-acp) | You have another CLI that can start an ACP stdio server. | `generic-acp` | [`examples/configs/generic-acp/config.yaml`](https://github.com/diffpal/diffpal/blob/main/examples/configs/generic-acp/config.yaml) | - -These setup names are accepted by: - -```bash -diffpal init --wizard --setup --platform github -``` - -Use the provider page for install and authentication, then use the -[Integrations](/integrations) section for host-specific CI syntax. - -Next step: open the setup page for the provider you plan to authenticate in CI. diff --git a/public/llms.txt b/public/llms.txt index d255209..3a67bdc 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -50,6 +50,8 @@ - [FAQ](/faq): Short answers for product, provider, CI, and artifact questions. - [Security Controls](/security): Trust boundaries, credentials, and artifact handling. - [Secrets And Fork Pull Requests](/secrets-and-fork-prs): Safe patterns for secret-backed review. +- [Migrate To v1](/migrate-to-v1): Remove obsolete local state and verify host reconciliation. +- [Privacy](/privacy): Consent-first analytics and privacy choices. ## Optional diff --git a/reference.md b/reference.md deleted file mode 100644 index 275551c..0000000 --- a/reference.md +++ /dev/null @@ -1,17 +0,0 @@ -# Reference - -Use this section for stable user-facing contracts. - -- [Configuration](/configuration): config hierarchy, defaults, required - fields, allowed values, profiles, platform auth, and environment overrides. -- [CLI](/cli): installation, commands, flags, environment inputs, outputs, and - examples. -- [Findings schema](/findings-schema): canonical findings bundle and - compatibility expectations. -- [Artifacts](/artifacts): public output paths, formats, creation conditions, - consumers, and retention advice. -- [Exit behavior](/exit-behavior): success, blocking, setup, provider, diff, - publishing, and gate behavior. -- [Versioning](/versioning): CLI/package, config, and artifact compatibility. -- [Support matrix](/support-matrix): supported hosts, publishers, feedback - surfaces, provider types, and stability. diff --git a/review-lifecycle.md b/review-lifecycle.md deleted file mode 100644 index 8c5fce6..0000000 --- a/review-lifecycle.md +++ /dev/null @@ -1,57 +0,0 @@ -# Review Lifecycle - -DiffPal review is a CI job lifecycle. Each stage has a distinct role so -failures are clear and artifacts are consistent. - -## Review Scope Resolution - -DiffPal resolves the base and head revisions for the pull request, merge -request, or candidate commit. It records changed files, changed line ranges, -and related metadata that define the review scope. - -Shallow clones, missing target branches, or incorrect base/head values usually -break this stage. Host-specific setup pages describe the required checkout -behavior. - -## Review Request - -DiffPal combines the review scope metadata, repository configuration, review -instructions, language, and gate threshold into a provider request. The selected -provider or ACP-compatible agent inspects the requested `base..head` change with -its available tools. - -## Structured Findings - -The provider returns structured review output: a change summary and zero or -more findings. A finding describes a concrete issue, its severity, category, -impact, and the changed lines it applies to. - -## Validation - -DiffPal validates and normalizes provider output before publishing it. Findings -must map back to the reviewed change and the configured schema. Invalid or -unanchored output is not treated as publishable inline feedback. - -## Publishing - -When a native publisher is selected, DiffPal turns validated output into host -feedback such as a pull request summary, merge request discussion, file-level -comment, status, SARIF, or Code Quality report. The exact surfaces depend on -the code host and feedback mode. - -## Artifact Generation - -DiffPal writes machine-readable and human-readable artifacts under -`.artifacts/diffpal/`. These artifacts are useful for audit trails, downstream -CI steps, and supported report surfaces. - -## Optional Gate - -The gate is separate from feedback. When enabled, DiffPal compares findings to -the configured blocking threshold and returns a failing CI result if blocking -findings exist. When disabled, feedback and artifacts can still show blocking -findings without failing the merge check. - -For exact config fields and exit behavior, use -[Configuration](/configuration) and -[Exit behavior](/exit-behavior). diff --git a/scripts/check-privacy.mjs b/scripts/check-privacy.mjs new file mode 100644 index 0000000..f87ff02 --- /dev/null +++ b/scripts/check-privacy.mjs @@ -0,0 +1,12 @@ +import fs from 'node:fs' +import path from 'node:path' + +const dist = path.resolve('.vitepress/dist') +const index = fs.readFileSync(path.join(dist, 'index.html'), 'utf8') +if (index.includes('googletagmanager.com') || index.includes('G-B8G6D7K9SQ')) { + throw new Error('analytics must not be embedded in the initial HTML response') +} +if (!fs.existsSync(path.join(dist, 'privacy.html'))) { + throw new Error('privacy page was not generated') +} +console.log('consent-first analytics checks passed') diff --git a/scripts/sync-docs.mjs b/scripts/sync-docs.mjs new file mode 100644 index 0000000..22fb8e1 --- /dev/null +++ b/scripts/sync-docs.mjs @@ -0,0 +1,87 @@ +import fs from 'node:fs' +import path from 'node:path' + +const root = process.cwd() +const lock = JSON.parse(fs.readFileSync(path.join(root, 'docs-source.json'), 'utf8')) +const sourceDir = path.resolve(root, process.env.DIFFPAL_DOCS_DIR || '.source/diffpal/docs') +const repositoryRoot = path.dirname(sourceDir) +const generatedDir = path.join(root, '.generated') + +if (!fs.existsSync(sourceDir)) { + throw new Error(`canonical docs directory not found: ${sourceDir}`) +} + +function markdownFiles(dir) { + return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const fullPath = path.join(dir, entry.name) + if (entry.isDirectory()) return markdownFiles(fullPath) + return entry.isFile() && entry.name.endsWith('.md') ? [fullPath] : [] + }) +} + +function destinationFor(relativePath) { + const normalized = relativePath.split(path.sep).join('/') + if (normalized === 'README.md') return 'docs.md' + if (path.posix.basename(normalized) === 'README.md') { + return `${path.posix.basename(path.posix.dirname(normalized))}.md` + } + return path.posix.basename(normalized) +} + +const sources = markdownFiles(sourceDir) +const destinations = new Map() +const sourceByAbsolutePath = new Map() +for (const source of sources) { + const relative = path.relative(sourceDir, source).split(path.sep).join('/') + const destination = destinationFor(relative) + if (destinations.has(destination)) { + throw new Error(`duplicate flattened docs destination ${destination}`) + } + destinations.set(destination, relative) + sourceByAbsolutePath.set(path.resolve(source), destination) +} + +function rewriteTarget(target, source) { + if (/^(?:[a-z]+:|#|\/)/i.test(target)) return target + const match = target.match(/^([^#?]+)([?#].*)?$/) + if (!match) return target + const resolved = path.resolve(path.dirname(source), match[1]) + const suffix = match[2] || '' + const destination = sourceByAbsolutePath.get(resolved) + if (destination) return `/${destination.replace(/\.md$/, '')}${suffix}` + if (!resolved.startsWith(repositoryRoot + path.sep)) return target + + const relative = path.relative(repositoryRoot, resolved).split(path.sep).join('/') + const kind = fs.existsSync(resolved) && fs.statSync(resolved).isDirectory() ? 'tree' : 'blob' + return `https://github.com/${lock.repository}/${kind}/${lock.ref}/${relative}${suffix}` +} + +function rewriteMarkdown(content, source) { + return content.replace(/(!?\[[^\]]*\]\()([^\s)]+)([^)]*\))/g, (_match, prefix, target, suffix) => { + return `${prefix}${rewriteTarget(target, source)}${suffix}` + }) +} + +fs.rmSync(generatedDir, { recursive: true, force: true }) +fs.mkdirSync(generatedDir, { recursive: true }) + +const rewrites = {} +for (const [destination, relative] of destinations) { + const source = path.join(sourceDir, relative) + const output = path.join(generatedDir, relative) + fs.mkdirSync(path.dirname(output), { recursive: true }) + fs.writeFileSync(output, rewriteMarkdown(fs.readFileSync(source, 'utf8'), source)) + const stat = fs.statSync(source) + fs.utimesSync(output, stat.atime, stat.mtime) + rewrites[relative] = destination +} + +for (const sitePage of ['index.md', 'privacy.md']) { + const output = path.join(generatedDir, 'site', sitePage) + fs.mkdirSync(path.dirname(output), { recursive: true }) + fs.copyFileSync(path.join(root, sitePage), output) + rewrites[`site/${sitePage}`] = sitePage +} + +fs.writeFileSync(path.join(root, '.generated-rewrites.json'), `${JSON.stringify(rewrites, null, 2)}\n`) +console.log(`generated ${destinations.size} canonical docs pages from ${lock.repository}@${lock.ref}`) diff --git a/secrets-and-fork-prs.md b/secrets-and-fork-prs.md deleted file mode 100644 index 86ee0ea..0000000 --- a/secrets-and-fork-prs.md +++ /dev/null @@ -1,140 +0,0 @@ -# Secrets And Fork Pull Requests - -Use this guide when you add provider credentials, host publishing tokens, or -fork pull request handling to a DiffPal workflow. - -DiffPal runs in your CI and sends review input to the provider you configure. -When you use a remote provider, the reviewed diff and review instructions can -leave the CI job and be processed by that third-party provider. - -## What Receives Repository Content - -The CI job checks out the repository working tree and runs DiffPal in that -workspace. DiffPal resolves the configured base/head review scope, reads -repository-owned configuration, and applies review instructions. - -The selected provider or ACP-compatible agent receives the review request that -DiffPal builds for that scope. For remote providers, that request is sent outside -the CI runner according to the provider's own service terms and account settings, -and the provider or agent may inspect source context according to its -configuration. - -Host publishers receive validated review output. GitHub, GitLab, and Azure -DevOps receive summaries, comments, discussions, threads, statuses, or reports -only when you run a publishing command or action with host credentials. - -## Credential Types - -Provider credentials authenticate the AI provider or agent. Examples include: - -| Credential | Belongs to | -| --- | --- | -| `OPENAI_API_KEY` | Codex API-key provider authentication | -| `CODEX_AUTH_JSON_B64` | Codex subscription auth restored inside CI | -| `COPILOT_GITHUB_TOKEN` | Copilot CLI provider authentication | -| Custom provider secrets | The ACP-compatible CLI or provider you configure | - -Host credentials authenticate the code host publisher. Examples include: - -| Credential | Belongs to | -| --- | --- | -| `GITHUB_TOKEN` | GitHub pull request review and comments | -| `CI_JOB_TOKEN` or `GITLAB_TOKEN` | GitLab merge request discussions, status, and reports | -| `SYSTEM_ACCESSTOKEN` or `AZURE_DEVOPS_EXT_PAT` | Azure DevOps PR threads and status | - -Keep provider credentials separate from host credentials so each secret can use -the least privilege needed for its own system. - -## Minimum Host Permissions - -Use the smallest host permission set that supports the configured feedback -mode. - -| Host | Minimum verified permissions | -| --- | --- | -| GitHub | `contents: read` and `pull-requests: write` for PR summaries and review comments. | -| GitLab | A job token or API token that can read the project, create merge request discussions, and publish commit status. Code Quality and SARIF reports are uploaded by the CI artifacts mechanism. | -| Azure DevOps | Pipeline OAuth access through `System.AccessToken` for PR threads and status, or a dedicated PAT with equivalent PR thread/status permission when required by the organization. | - -Artifact-only `diffpal review local` does not need a host publishing token, but -it still needs provider credentials when the configured provider is remote. - -## Protected And Masked Secrets - -Store provider and host credentials as CI secrets or protected variables. Mark -them masked when the CI system supports masking, and restrict them to trusted -branches, protected environments, same-repository pull requests, or -maintainer-approved jobs. - -Do not commit provider credentials to `.config/diffpal/config.yaml`, workflow -files, examples, artifacts, or issue comments. - -## Fork Pull Request Safety - -Untrusted fork pipelines must not receive provider credentials. A fork author -can change workflow files, package scripts, build hooks, provider commands, or -test code in ways that run before or during the review job. - -Safe patterns for external contributions: - -- Run normal no-secret CI on fork pull requests. -- Run DiffPal with provider credentials only on same-repository pull requests. -- Use a maintainer-approved job that does not execute fork-controlled code with - secrets. -- Review workflow changes before manually re-running any credentialed job. -- Keep `pull_request_target` jobs away from PR-head checkout, package installs, - build scripts, hooks, provider CLIs, and other fork-controlled execution. - -GitHub Actions workflows should keep a same-repository guard next to the -credentialed review job: - -```yaml -if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }} -``` - -GitLab CI can combine same-project merge request conditions, protected -variables, and a manual maintainer gate such as `DIFFPAL_TRUSTED_REVIEW`. - -Azure Pipelines can skip credentialed review for fork validation with: - -```yaml -condition: and(succeeded(), ne(variables['System.PullRequest.IsFork'], 'True')) -``` - -## Artifact Retention - -DiffPal artifacts can contain file paths, line numbers, findings, summaries, -and snippets or descriptions derived from reviewed code. Treat -`.artifacts/diffpal/` as repository-sensitive output. - -Retain artifacts long enough for audit, debugging, SARIF ingestion, or Code -Quality ingestion. Avoid uploading them to public storage from private -repositories, and apply the same retention rules you use for CI logs and test -reports. - -## Log Redaction - -CI systems usually mask exact secret values, but masking is not a complete -redaction boundary. Avoid `set -x`, do not echo tokens, and do not print -restored provider auth files. Be careful with derived values, encoded secrets, -provider debug logs, and command-line arguments because they may not match the -secret value the CI system knows how to mask. - -If you need provider debugging, use the provider's own safe logging controls -and remove sensitive logs from retained artifacts. - -## Report A Security Issue - -This repository does not currently include a `SECURITY.md` policy file. If the -GitHub repository exposes **Report a vulnerability** on the Security tab, use -that private channel. Otherwise, open a GitHub issue with only a minimal, -non-sensitive description and ask maintainers for a private reporting channel. - -Do not paste secrets, exploit details, private code, provider responses, or -private artifacts into a public issue. - -See the public [Security controls](/security) page for the shorter control -summary. - -Next step: apply the trusted-source guard from your host integration page before -enabling provider credentials in CI. diff --git a/security.md b/security.md deleted file mode 100644 index 160c778..0000000 --- a/security.md +++ /dev/null @@ -1,58 +0,0 @@ -# Security Controls - -DiffPal runs in your CI and sends review input to the provider you configure. -This page summarizes the public security controls users should understand -before enabling provider-backed review. - -## Boundaries - -- The CI runner receives the repository checkout, DiffPal configuration, and - provider credentials made available to the job. -- DiffPal resolves the configured base/head review scope and sends review input - to the selected provider or ACP-compatible agent. -- The provider owns model execution, provider account security, and provider - credentials. -- GitHub, GitLab, and Azure DevOps publishers receive review output only when a - publishing command or action runs with host credentials. - -## Credential Controls - -Keep provider credentials and host credentials separate. - -Provider credentials include values such as `OPENAI_API_KEY`, -`CODEX_AUTH_JSON_B64`, `COPILOT_GITHUB_TOKEN`, and custom ACP provider tokens. -Host credentials include `GITHUB_TOKEN`, `CI_JOB_TOKEN`, `GITLAB_TOKEN`, -`SYSTEM_ACCESSTOKEN`, and `AZURE_DEVOPS_EXT_PAT`. - -Store credentials as protected and masked CI secrets. Give host tokens only the -minimum permission needed to publish the selected feedback mode. - -## Fork Pull Requests - -Do not expose provider or host credentials to untrusted fork code. Run -secret-backed DiffPal review only for same-repository pull requests, trusted -branches, or maintainer-approved jobs that do not execute fork-controlled code -with secrets. - -Use [Secrets and fork PRs](/secrets-and-fork-prs) for host-specific -guards and safe external contribution patterns. - -## Artifacts And Logs - -DiffPal artifacts and logs can contain repository-sensitive review output. -Retain `.artifacts/diffpal/` only where you need audit records, SARIF or Code -Quality ingestion, or troubleshooting. Do not rely on CI masking as the only -protection for debug logs or restored provider auth files. - -## Reporting Security Issues - -This repository does not currently include a `SECURITY.md` policy file. If the -GitHub repository exposes **Report a vulnerability** on the Security tab, use -that private channel. Otherwise, open a GitHub issue with a minimal, -non-sensitive description and ask maintainers for a private reporting channel. - -Do not include secrets, exploit details, private code, provider responses, or -private artifacts in a public issue. - -Next step: read [Secrets and fork PRs](/secrets-and-fork-prs) before -enabling provider credentials in CI. diff --git a/support-matrix.md b/support-matrix.md deleted file mode 100644 index 0ac0e7c..0000000 --- a/support-matrix.md +++ /dev/null @@ -1,50 +0,0 @@ -# Support Matrix - -This page lists the supported public surface confirmed by the repository. - -## Code Hosts And Publishers - -| Host / mode | Native publisher | Stable status | Guide | -| --- | --- | --- | --- | -| GitHub pull requests | GitHub publisher | Stable public surface | [GitHub Actions](/github-actions) | -| GitLab merge requests | GitLab publisher | Stable public surface | [GitLab CI](/gitlab-ci) | -| Azure DevOps pull requests | Azure DevOps publisher | Stable public surface | [Azure Pipelines](/azure-pipelines) | -| Custom CI/CD with unsupported code host | No native publisher | Artifact-only support | [Custom CI/CD](/custom-ci) | - -## Feedback Surfaces - -| Host | `summary` feedback | `review` feedback | -| --- | --- | --- | -| GitHub | Summary and SARIF | Summary, file-level PR review comments, SARIF | -| GitLab | Summary, status, SARIF, Code Quality | Summary, discussions, status, SARIF, Code Quality | -| Azure DevOps | Summary and status | Summary, PR threads, status | -| Custom CI/CD unsupported host | Local Markdown and artifacts | Local Markdown and artifacts | - -## Artifact Surfaces - -| Surface | GitHub | GitLab | Azure | Local/custom | -| --- | --- | --- | --- | --- | -| Findings bundle | yes | yes | yes | yes | -| Summary Markdown | yes | yes | yes | stdout unless captured | -| SARIF | yes | yes | no native surface | via `diffpal sarif` | -| GitLab Code Quality | no | yes | no | no | -| Host status | GitHub check/workflow status | GitLab commit status | Azure PR status | CI job status | - -## Provider Types - -Supported runtime provider types: - -| Type | Status | Notes | -| --- | --- | --- | -| `codex_acp` | Stable public setup | Default onboarding provider type. | -| `copilot_acp` | Stable public setup | Documented provider page and examples. | -| `opencode_acp` | Stable public setup | Documented provider page and config example. | -| `generic_acp` | Stable public setup | Bring your own ACP-compatible CLI. | -| `openai` | Supported config type | Hosted API config type; use when explicitly configured. | -| `aistudio` | Supported config type | Hosted API config type; use when explicitly configured. | -| `gemini_acp` | Supported runtime type | No dedicated public setup page in this docs set. | -| `claude_code_acp` | Supported runtime type | No dedicated public setup page in this docs set. | -| `pool` | Supported runtime type | Ordered provider failover config. | - -No provider account is managed by DiffPal. Provider authentication belongs to -the selected provider and CI secret management. diff --git a/troubleshooting.md b/troubleshooting.md deleted file mode 100644 index f52242e..0000000 --- a/troubleshooting.md +++ /dev/null @@ -1,331 +0,0 @@ -# Troubleshooting - -Use this page when a DiffPal run does not produce the expected host feedback, -artifacts, or gate result. Each entry starts from what you can observe in CI or -on the pull request. - -## Job Does Not Start - -**Symptom:** The DiffPal workflow, job, or task is not created for the pull -request or merge request. - -**Likely causes:** The CI trigger does not include PR/MR events, the PR is a -draft, a same-repository or trusted-review guard skipped the job, the workflow -file is not on the default branch, or the CI system is disabled for the -repository. - -**Diagnostic:** Check the CI event and guard expression first. For GitHub -Actions, confirm the workflow has a `pull_request` trigger and inspect whether -the job condition matches the PR: - -```yaml -if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }} -``` - -**Fix:** Enable the PR/MR trigger for the selected CI system. Keep fork-safety -guards in place, but test the first run with a same-repository, non-draft pull -request. - -**Related:** [GitHub quickstart](/github-quickstart), -[GitHub Actions](/github-actions), and -[Secrets and fork PRs](/secrets-and-fork-prs). - -## Provider Authentication Fails - -**Symptom:** The job starts, but provider login or provider validation fails -before review output is produced. - -**Likely causes:** The provider CLI is not installed, the selected -`diffpal.provider` entry does not match an installed/authenticated provider, -the provider secret is missing in the trusted job, or the secret belongs to a -different provider account. - -**Diagnostic:** Run the host-specific doctor after provider installation and -authentication: - -```bash -diffpal --profile ci doctor --mode github -``` - -Use `--mode gitlab`, `--mode ado`, or `--mode local` for other runs. - -**Fix:** Install the provider command before DiffPal runs, expose the provider -secret only to trusted jobs, and follow the selected provider page for the -exact authentication command. - -**Related:** [Providers](/providers), -[CLI doctor](/cli#diffpal-doctor), and -[Secrets and fork PRs](/secrets-and-fork-prs). - -## DiffPal Cannot Find The Base Or Head Revision - -**Symptom:** The review fails during review scope resolution with missing, -ambiguous, or invalid base/head revisions. - -**Likely causes:** The checkout is shallow, the target branch was not fetched, -CI metadata is unavailable, `--base` or `--head` is empty, or the job is not -running in a PR/MR context. - -**Diagnostic:** Verify the revisions in the CI workspace: - -```bash -git rev-parse --verify "$BASE_SHA^{commit}" -git rev-parse --verify "$HEAD_SHA^{commit}" -git merge-base "$BASE_SHA" "$HEAD_SHA" -``` - -**Fix:** Use full checkout history. In GitHub Actions set `fetch-depth: 0`; in -GitLab CI set `GIT_DEPTH: "0"`; in Azure Pipelines set `fetchDepth: 0`. For -custom CI, explicitly fetch the target branch and pass stable `--base` and -`--head` values. - -**Related:** [GitHub Actions checkout](/github-actions#required-checkout-behavior), -[GitLab checkout](/gitlab-ci#required-checkout-behavior), -[Azure checkout](/azure-pipelines#required-checkout-behavior), -and [Custom CI base/head resolution](/custom-ci#base-and-head-resolution). - -## Review Completes But No Summary Appears - -**Symptom:** The provider-backed review finishes, but the PR/MR does not show a -DiffPal summary. - -**Likely causes:** Host publishing was denied, the wrong host command was used, -`diffpal review local` printed Markdown to stdout without publishing, GitHub -`--dry-run` was used, or `summary.md` was not retained from artifacts. - -**Diagnostic:** Check whether the command wrote a summary artifact: - -```bash -test -s .artifacts/diffpal/summary.md -``` - -For local review, check the redirected stdout file if your CI captures one. - -**Fix:** Use the matching host command or action for GitHub, GitLab, or Azure -DevOps. Ensure the host token is present with write permission and upload -`.artifacts/diffpal/` for retained summaries. - -**Related:** [Artifacts reference](/artifacts), -[Support matrix](/support-matrix), and -[Integrations](/integrations). - -## Summary Appears But Inline Findings Do Not - -**Symptom:** The PR/MR has a DiffPal summary, but no file-level comments, -discussions, or threads appear. - -**Likely causes:** `feedback` is set to `summary`, the host does not support -inline feedback for the selected mode, findings could not be anchored to -changed lines, or the provider returned no actionable file-level findings. - -**Diagnostic:** Confirm the run used review feedback: - -```bash -diffpal --profile ci review local --base origin/main --head HEAD --feedback review -``` - -Inspect `.artifacts/diffpal/findings.json` to see whether findings have changed -file locations. - -**Fix:** Set `feedback: review` or pass `--feedback review`. If findings exist -without changed-line locations, review the provider output and diff range; only -changed-file locations can become inline host feedback. - -**Related:** [Feedback modes](/integrations#feedback-modes), -[Findings, feedback, and gates](/findings-feedback-and-gates), -and [Findings schema](/findings-schema). - -## No Findings Were Produced - -**Symptom:** The review summary says no actionable findings were found, or the -findings bundle contains an empty findings list. - -**Likely causes:** The change has no issues that meet the review contract, the -diff range is too small or wrong, provider instructions are too narrow, or the -provider returned a valid no-findings result. - -**Diagnostic:** Confirm that the reviewed diff is the expected range: - -```bash -git diff --stat "$BASE_SHA" "$HEAD_SHA" -``` - -Then inspect `.artifacts/diffpal/findings.json`. - -**Fix:** If the diff range is wrong, fix base/head resolution. If the diff is -right, treat no findings as a completed review and tune repository instructions -only when the provider is consistently missing issues your team expects. - -**Related:** [Verify First Review](/verify-first-review), -[Review lifecycle](/review-lifecycle), and -[Configuration review settings](/configuration#review-settings). - -## Publishing Is Denied - -**Symptom:** Review generation succeeds, but publishing comments, discussions, -threads, statuses, SARIF, or reports fails. - -**Likely causes:** The host token is missing, read-only, scoped to the wrong -repository/project, unavailable to the job, or the host API URL is wrong for an -enterprise/self-managed instance. - -**Diagnostic:** Run doctor in the host mode: - -```bash -diffpal --profile ci doctor --mode gitlab -``` - -Use `github` or `ado` for the other native publishers. - -**Fix:** Provide the host credential documented for the selected platform and -grant the minimum write permission needed for the selected feedback surface. -Keep host credentials separate from provider credentials. - -**Related:** [Secrets and fork PRs](/secrets-and-fork-prs), -[GitHub token permissions](/github-actions#required-token-and-minimum-permissions), -[GitLab tokens](/gitlab-ci#required-token-and-minimum-permissions), -and [Azure token setup](/azure-pipelines#required-token-and-minimum-permissions). - -## Fork PRs Are Skipped - -**Symptom:** DiffPal does not run, or only no-secret CI runs, for a fork pull -request. - -**Likely causes:** The workflow intentionally protects provider and host -credentials from untrusted fork code. GitHub, GitLab, or Azure guards can skip -credentialed review for fork contributions. - -**Diagnostic:** Inspect the CI condition or rules. GitHub examples use: - -```yaml -if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }} -``` - -Azure examples use `System.PullRequest.IsFork`; GitLab examples use -same-project MR conditions and a maintainer-controlled trusted-review guard. - -**Fix:** Keep the skip for untrusted fork code. For external contributions, run -no-secret CI or use a maintainer-approved workflow that does not execute -fork-controlled code with secrets. - -**Related:** [Secrets and fork PRs](/secrets-and-fork-prs), -[GitHub Actions fork behavior](/github-actions#fork-or-untrusted-contribution-behavior), -[GitLab fork behavior](/gitlab-ci#fork-or-untrusted-contribution-behavior), -and [Azure fork behavior](/azure-pipelines#fork-or-untrusted-contribution-behavior). - -## Expected Artifacts Are Missing - -**Symptom:** The CI job finishes, but `.artifacts/diffpal/findings.json`, -`summary.md`, or host-specific artifacts are not available after the job. - -**Likely causes:** The command failed before writing artifacts, `--out` changed -the findings path, `diffpal review local` printed Markdown to stdout instead -of creating `summary.md`, CI did not upload `.artifacts/diffpal/`, or a dry-run -did not create host artifacts. - -**Diagnostic:** List the artifact directory inside the job: - -```bash -find .artifacts/diffpal -maxdepth 1 -type f -print -``` - -**Fix:** Upload `.artifacts/diffpal/` from CI. For local review, redirect -stdout to `.artifacts/diffpal/summary.md` when you want a retained summary. -Check `--out` if `findings.json` was intentionally moved. - -**Related:** [Artifacts reference](/artifacts) and -[Custom CI outputs](/custom-ci#outputs). - -## SARIF Or Code Quality Output Is Missing - -**Symptom:** The review completes, but `.artifacts/diffpal/diffpal.sarif` or -`.artifacts/diffpal/codequality.json` is absent. - -**Likely causes:** SARIF is not a native Azure surface, Code Quality is a -GitLab-specific output, the run used `review local`, GitHub dry-run was used, -or the file was not uploaded as a CI artifact/report. - -**Diagnostic:** Check the selected host and command against the artifact table. -To create SARIF from a findings bundle manually, run: - -```bash -diffpal sarif --input .artifacts/diffpal/findings.json --out .artifacts/diffpal/diffpal.sarif -``` - -**Fix:** Use GitHub or GitLab host review when you expect SARIF from a native -run. Use GitLab CI report configuration for Code Quality. For custom CI or -Azure, convert findings to SARIF explicitly when needed. - -**Related:** [Artifacts reference](/artifacts), -[Support matrix](/support-matrix), and -[CLI SARIF command](/cli#diffpal-sarif). - -## Gate Blocks Unexpectedly - -**Symptom:** The job fails with blocking findings even though publishing and -artifacts completed. - -**Likely causes:** `--gate` or `gate: true` is enabled, and at least one -finding severity meets `diffpal.gate.block_on` or `--block-on`. - -**Diagnostic:** Check the process exit code and configured threshold. Blocking -findings with an enabled gate return exit code `10`. - -**Fix:** Inspect `findings.json` and the review summary. If the finding should -not block, raise `diffpal.gate.block_on` to a higher severity or improve review -instructions. If it should block, fix the code. - -**Related:** [Exit behavior](/exit-behavior), -[Configuration gate](/configuration#gate), and -[Findings, feedback, and gates](/findings-feedback-and-gates). - -## Gate Does Not Block - -**Symptom:** Findings appear in the summary or comments, but the CI job still -passes. - -**Likely causes:** The gate is disabled, findings are below the blocking -threshold, the command did not pass `--gate`, or the CI wrapper is not using the -DiffPal process result as the job result. - -**Diagnostic:** Confirm the run enables the gate and check the threshold: - -```bash -diffpal --profile ci review local --base origin/main --head HEAD --gate -``` - -**Fix:** Enable `gate: true` in the action/task or pass `--gate` to the CLI. -Set `diffpal.gate.block_on` to the minimum severity that should fail the job. - -**Related:** [Merge gates](/integrations#merge-gates), -[Exit behavior](/exit-behavior), and -[Configuration gate](/configuration#gate). - -## Local Execution Works But CI Execution Fails - -**Symptom:** `diffpal review local` works on a developer machine, but the same -repository fails in CI. - -**Likely causes:** CI has a shallow checkout, missing provider installation, -missing or protected secrets, different profile selection, missing host -metadata, a different working directory, or no artifact upload step. - -**Diagnostic:** Compare local and CI environments with doctor and version: - -```bash -diffpal version -diffpal --profile ci doctor --mode local -``` - -In host CI, use the matching host mode. - -**Fix:** Pin the same provider install path in CI, use full checkout history, -make the intended profile explicit, expose secrets only to trusted jobs, and -pass host metadata or base/head values from CI variables. - -**Related:** [CLI reference](/cli), -[Custom CI lifecycle](/custom-ci#generic-execution-lifecycle), -and [Providers](/providers). - -Next step: after applying the fix, rerun `diffpal doctor` in the same CI mode -that failed. diff --git a/verify-first-review.md b/verify-first-review.md deleted file mode 100644 index f982824..0000000 --- a/verify-first-review.md +++ /dev/null @@ -1,70 +0,0 @@ -# Verify First Review - -Use this page to confirm that the first DiffPal run produced a complete review, -even when it found no issues. - -## Pull Request Signals - -The PR or MR must show: - -- a `DiffPal Review Summary` review, discussion, or thread; -- inline comments, discussions, or PR threads when actionable findings exist; -- a check, commit status, or PR status for the DiffPal review job. - -## Required Artifacts - -The CI workspace must contain: - -| Path | Purpose | -| --- | --- | -| `.artifacts/diffpal/findings.json` | Canonical structured findings bundle. | -| `.artifacts/diffpal/summary.md` | Human-readable review summary. | - -Depending on the host and feedback mode, the run may also write: - -| Path | Purpose | -| --- | --- | -| `.artifacts/diffpal/diffpal.sarif` | SARIF report when enabled by the platform output. | -| `.artifacts/diffpal/codequality.json` | GitLab Code Quality report. | - -## No Findings Vs Broken Review - -`No findings` is healthy when: - -- the review summary appears; -- `findings.json` exists and is valid JSON; -- the CI job succeeds unless a configured gate blocks it; -- logs show DiffPal resolved the review scope and completed publishing. - -A broken review usually has one of these symptoms: - -- no summary appears in the PR/MR; -- `findings.json` is missing; -- provider authentication failed; -- the workflow used a shallow checkout and could not compare base and head; -- the platform token could not publish feedback. - -## Gate Behavior - -When gating is enabled, DiffPal fails the CI job if at least one finding meets -`diffpal.gate.block_on`. Setup, authentication, review scope resolution, and -publishing failures also fail the job because the review result is incomplete. - -When gating is disabled, blocking findings can still be published as review -feedback, but they do not fail the CI job. Tooling failures still fail because -DiffPal did not produce a complete review. - -## Troubleshooting - -- Missing summary or inline comments: - [Review Completes But No Summary Appears](/troubleshooting#review-completes-but-no-summary-appears) -- Missing or incomplete diff: - [DiffPal Cannot Find The Base Or Head Revision](/troubleshooting#diffpal-cannot-find-the-base-or-head-revision) -- Provider auth failures: - [Provider Authentication Fails](/troubleshooting#provider-authentication-fails) -- Gate failures: - [Gate Blocks Unexpectedly](/troubleshooting#gate-blocks-unexpectedly) -- Fork PR secrets: - [Secrets and fork PRs](/secrets-and-fork-prs) - -After the first run is healthy, continue with [Next Steps](/next-steps). diff --git a/versioning.md b/versioning.md deleted file mode 100644 index 0f7ee06..0000000 --- a/versioning.md +++ /dev/null @@ -1,57 +0,0 @@ -# Versioning - -DiffPal uses SemVer for user-facing releases. - -## CLI And Package Versions - -The CLI version is built into release binaries with Omnidist ldflags: - -- `Version` -- `GitCommit` -- `BuildDate` - -`diffpal version` prints: - -```text -diffpal + () -``` - -The npm package `@diffpal/diffpal` is the public CLI package. Omnidist also -builds platform-specific packages and release binaries from the same version. -Consumers should pin exact versions in credentialed CI jobs when repeatability -matters. - -GitHub Action users can use the stable major tag, for example -`diffpal/action@v1`, or pin a more specific release. Azure users can use the -published DiffPal extension task version. - -## Configuration Schema Compatibility - -Configuration files use `version: v1`. DiffPal accepts an empty version or -`v1`; any other config version is rejected. - -Minor releases should preserve `v1` compatibility. New optional fields may be -added without requiring existing configs to change. - -## Artifact And Schema Compatibility - -New findings writes use bundle `version: v3`. DiffPal readers accept `v1`, -`v2`, and `v3` findings bundles. - -Consumers should: - -- treat `findings.json` as the canonical artifact; -- ignore unknown fields; -- use `version` and `prompt.schema_version` when they need compatibility - branching; -- avoid depending on host-specific publishing plan files unless they are part of - the selected integration. - -## Upgrade Guidance - -1. Pin the DiffPal CLI, provider CLI, and CI wrapper versions in credentialed - jobs. -2. Upgrade in a branch and run `diffpal doctor --mode `. -3. Run a same-repository PR/MR review before enabling gates on the new version. -4. Keep uploaded artifacts for the first upgraded runs so schema or publisher - differences are easy to inspect.