@diffpal/diffpal 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +224 -156
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,82 +1,103 @@
1
1
  # DiffPal
2
2
 
3
- DiffPal reviews pull request diffs and publishes policy-aware feedback back to
4
- your CI system.
3
+ [![ci](https://github.com/diffpal/diffpal/actions/workflows/ci.yml/badge.svg)](https://github.com/diffpal/diffpal/actions/workflows/ci.yml)
4
+ [![diffpal-dev review](https://github.com/diffpal/diffpal/actions/workflows/diffpal-dev-review.yml/badge.svg)](https://github.com/diffpal/diffpal/actions/workflows/diffpal-dev-review.yml)
5
+ [![npm](https://img.shields.io/npm/v/@diffpal/diffpal?label=npm)](https://www.npmjs.com/package/@diffpal/diffpal)
6
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
7
 
6
- It is built for teams that want AI review output that is easy to scan:
8
+ **Diff-first AI review for pull requests.**
7
9
 
8
- - PR summaries that explain what changed
9
- - inline comments only for actionable findings
10
- - merge gates through checks/statuses, not bot approvals
11
- - one config file that works across GitHub, GitLab, and Azure DevOps
10
+ DiffPal turns changed code into structured findings, clear PR summaries, inline
11
+ comments, and merge gates across GitHub, GitLab, and Azure DevOps. Bring the
12
+ review agent your team already trusts: Codex, Copilot, OpenCode, Gemini, Claude
13
+ Code, a hosted provider, or any ACP-compatible CLI.
12
14
 
13
- ## Quick Start
15
+ | Works with | Publishes | Gates on |
16
+ | --- | --- | --- |
17
+ | GitHub Actions, GitLab CI, Azure Pipelines | summaries, inline comments, checks/statuses, SARIF, Code Quality | policy thresholds through native CI checks and PR statuses |
14
18
 
15
- Add a DiffPal config, add a provider secret, then choose the CI example for your
16
- platform.
19
+ [Quickstart](docs/quickstart.md) · [CI examples](docs/ci-examples.md) · [Config reference](docs/config-reference.md) · [Provider recipes](examples/README.md)
17
20
 
18
- The examples use npm `@latest` for quick onboarding. For production, pin
19
- `@diffpal/diffpal`, `diffpal-version`, `@openai/codex`, and
20
- `@normahq/codex-acp-bridge` to versions you have tested.
21
+ ## How DiffPal Works
21
22
 
22
- ## Config
23
+ ```text
24
+ pull request diff
25
+ -> DiffPal config and policy
26
+ -> selected ACP or hosted provider
27
+ -> structured findings bundle
28
+ -> platform publisher and CI artifacts
29
+ ```
23
30
 
24
- Commit `.config/diffpal/config.yaml`:
31
+ DiffPal owns the diff collection, finding schema, gating, and platform publish
32
+ logic. Your provider owns the model, tool loop, account, and credentials. That
33
+ split keeps CI setup predictable while still letting you choose the agent stack
34
+ your team already trusts.
25
35
 
26
- ```yaml
27
- version: v1
36
+ ## Quick Start: GitHub Actions
28
37
 
29
- runtime:
30
- providers:
31
- codex-acp:
32
- type: codex_acp
33
- codex_acp:
34
- reasoning_effort: low
38
+ This is the fastest production-shaped setup: DiffPal installs itself through the
39
+ GitHub Action, Codex is used as the review provider, and `OPENAI_API_KEY` stays
40
+ in GitHub Secrets.
35
41
 
36
- diffpal:
37
- provider: codex-acp
38
- gate:
39
- block_on: high
40
- review:
41
- language: en
42
- instructions: |
43
- Prefer actionable findings that are directly supported by the diff.
44
- checks:
45
- - security
46
- - bugs
47
- - performance
48
- # - best-practices
42
+ 1. Add the config:
43
+
44
+ ```bash
45
+ mkdir -p .config/diffpal
46
+ cp examples/configs/codex-api-key/config.yaml .config/diffpal/config.yaml
49
47
  ```
50
48
 
51
- Add `OPENAI_API_KEY` as a CI secret so the Codex CLI can act as the
52
- review provider. Platform publish tokens are CI-specific:
49
+ 2. Add a repository secret:
53
50
 
54
- | Platform | Publish token |
51
+ | Secret | Purpose |
55
52
  | --- | --- |
56
- | GitHub Actions | built-in `GITHUB_TOKEN` |
57
- | GitLab CI | built-in `CI_JOB_TOKEN` or `GITLAB_TOKEN` |
58
- | Azure Pipelines | built-in `SYSTEM_ACCESSTOKEN` |
53
+ | `OPENAI_API_KEY` | Authenticates Codex for the review provider. |
54
+
55
+ 3. Add the workflow:
56
+
57
+ ```bash
58
+ mkdir -p .github/workflows
59
+ cp examples/ci/github-actions/codex-api-key.yml .github/workflows/diffpal.yml
60
+ ```
61
+
62
+ 4. Open a same-repository pull request.
63
+
64
+ Expected result:
65
+
66
+ - a `diffpal-checks` check run
67
+ - a `DiffPal Review Summary` PR comment with an overview of the change
68
+ - inline comments only for actionable findings
69
+ - `.artifacts/diffpal/findings.json` in the job workspace
70
+ - a failed job only when `gate: true` and blocking findings exist, or when setup
71
+ or publishing fails
72
+
73
+ The examples pin package versions for repeatable credentialed CI. After your
74
+ first successful run, bump `@diffpal/diffpal`, provider CLIs, and bridge
75
+ packages intentionally.
59
76
 
60
- ## GitHub Actions
77
+ ## Supported CI Systems
61
78
 
62
- Create `.github/workflows/diffpal-review.yml`.
79
+ Use the same `.config/diffpal/config.yaml` shape in every CI system. The host
80
+ workflow only changes how it checks out code, installs the provider, passes the
81
+ platform token, and runs DiffPal.
63
82
 
64
- The action installs the DiffPal CLI. The workflow installs only the Codex
65
- provider command.
83
+ | CI system | Examples | Output surfaces |
84
+ | --- | --- | --- |
85
+ | GitHub Actions | [`examples/ci/github-actions`](examples/ci/github-actions) | check run, PR summary, review comments, SARIF |
86
+ | GitLab CI | [`examples/ci/gitlab`](examples/ci/gitlab) | MR summary, discussions, Code Quality, SARIF |
87
+ | Azure Pipelines | [`examples/ci/azure-pipelines`](examples/ci/azure-pipelines) | PR summary thread, PR threads, PR status |
88
+
89
+ GitHub Actions can use the root action directly:
66
90
 
67
91
  ```yaml
68
- name: diffpal-review
92
+ name: diffpal
69
93
 
70
94
  on:
71
95
  pull_request:
72
96
  types: [opened, synchronize, reopened, ready_for_review]
73
97
 
74
- concurrency:
75
- group: diffpal-review-${{ github.event.pull_request.number }}
76
- cancel-in-progress: true
77
-
78
98
  jobs:
79
99
  review:
100
+ name: review
80
101
  if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }}
81
102
  runs-on: ubuntu-latest
82
103
  permissions:
@@ -84,161 +105,208 @@ jobs:
84
105
  pull-requests: write
85
106
  checks: write
86
107
  steps:
87
- - uses: actions/checkout@v4
108
+ - uses: actions/checkout@v6
88
109
  with:
89
110
  fetch-depth: 0
90
111
 
91
- - uses: actions/setup-node@v4
112
+ - uses: actions/setup-node@v6
92
113
  with:
93
114
  node-version: 22
94
115
 
95
116
  - name: Install Codex provider
96
- run: npm install --global @openai/codex@latest @normahq/codex-acp-bridge@latest
117
+ run: npm install --global @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3
97
118
 
98
119
  - name: Authenticate Codex
99
120
  run: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
100
121
  env:
101
122
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
102
123
 
103
- - name: Review pull request
104
- uses: diffpal/diffpal@v0.1.2
124
+ - uses: diffpal/diffpal@v0.1.7
105
125
  with:
106
- diffpal-version: latest
126
+ diffpal-version: 0.1.7
107
127
  base: ${{ github.event.pull_request.base.sha }}
108
128
  head: ${{ github.event.pull_request.head.sha }}
109
- repo: ${{ github.repository }}
110
- review-id: github-pr-${{ github.event.pull_request.number }}
111
- feedback: balanced
129
+ profile: ci
112
130
  gate: true
131
+ feedback: balanced
113
132
  env:
114
- OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
115
133
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
116
134
  ```
117
135
 
118
- The same-repository PR guard keeps provider secrets out of untrusted fork
119
- workflows. Remove or change that guard only after designing a fork-safe release
120
- flow.
136
+ For full copy-paste files and host-specific notes, read
137
+ [`docs/ci-examples.md`](docs/ci-examples.md).
121
138
 
122
- ## GitLab CI
139
+ ## Config You Commit
123
140
 
124
- Add this job to `.gitlab-ci.yml`.
141
+ DiffPal uses the current profile-based config shape. There is no legacy
142
+ `defaults` block.
125
143
 
126
144
  ```yaml
127
- stages:
128
- - review
129
-
130
- diffpal-review:
131
- stage: review
132
- image: node:22
133
- rules:
134
- - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
135
- resource_group: "diffpal:$CI_MERGE_REQUEST_IID"
136
- before_script:
137
- - npm install --global @diffpal/diffpal@latest @openai/codex@latest @normahq/codex-acp-bridge@latest
138
- - printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
139
- script:
140
- - >-
141
- diffpal review gitlab
142
- --base "$CI_MERGE_REQUEST_DIFF_BASE_SHA"
143
- --head "$CI_COMMIT_SHA"
144
- --repo "$CI_PROJECT_PATH"
145
- --review-id "gitlab-mr-$CI_MERGE_REQUEST_IID"
146
- --language en
147
- --review-checks security,bugs,performance,best-practices
148
- --feedback balanced
149
- --gate
150
- variables:
151
- GIT_DEPTH: "0"
152
- artifacts:
153
- when: always
154
- paths:
155
- - .artifacts/diffpal/
156
- reports:
157
- codequality: .artifacts/diffpal/codequality.json
158
- sarif: .artifacts/diffpal/diffpal.sarif
145
+ version: v1
146
+
147
+ runtime:
148
+ providers:
149
+ codex-acp:
150
+ type: codex_acp
151
+ codex_acp:
152
+ reasoning_effort: low
153
+
154
+ diffpal:
155
+ provider: codex-acp
156
+ gate:
157
+ block_on: high
158
+ review:
159
+ language: en
160
+ instructions: |
161
+ Prefer actionable findings that are directly supported by the diff.
162
+ checks:
163
+ - security
164
+ - bugs
165
+ - performance
166
+ - best-practices
167
+ platforms:
168
+ github: {}
169
+ gitlab: {}
170
+ azure: {}
171
+
172
+ profiles:
173
+ ci:
174
+ diffpal:
175
+ gate:
176
+ block_on: high
159
177
  ```
160
178
 
161
- Set `OPENAI_API_KEY` as a protected/masked CI variable. Use the built-in
162
- `CI_JOB_TOKEN` when your GitLab instance allows it, or set `GITLAB_TOKEN` for a
163
- dedicated API token.
179
+ Review checks are intentionally simple. They ask the agent what to focus on;
180
+ DiffPal does not hardcode individual signal slugs:
181
+
182
+ | Check | Finding categories the agent may return |
183
+ | --- | --- |
184
+ | `security` | security |
185
+ | `bugs` | correctness, reliability |
186
+ | `performance` | performance |
187
+ | `best-practices` | maintainability, testing, style |
164
188
 
165
- ## Azure Pipelines
189
+ Use `diffpal.review.instructions`, the `instructions` action input, or
190
+ `--instructions-file` for repository-specific review guidance.
166
191
 
167
- Enable **Allow scripts to access the OAuth token**, then add this to
168
- `azure-pipelines.yml`.
192
+ ## Bring Your Own Agent
193
+
194
+ DiffPal is not a single-provider product. It delegates review to
195
+ `diffpal.provider`, which points at a provider under `runtime.providers`.
196
+
197
+ Ready-made config recipes:
198
+
199
+ | Setup | Config | Secret |
200
+ | --- | --- | --- |
201
+ | Generic ACP CLI | [`examples/configs/generic-acp/config.yaml`](examples/configs/generic-acp/config.yaml) | provider-specific |
202
+ | Codex API key | [`examples/configs/codex-api-key/config.yaml`](examples/configs/codex-api-key/config.yaml) | `OPENAI_API_KEY` |
203
+ | Codex subscription auth | [`examples/configs/codex-subscription/config.yaml`](examples/configs/codex-subscription/config.yaml) | `CODEX_AUTH_JSON_B64` |
204
+ | Copilot fine-grained PAT | [`examples/configs/copilot-github-token/config.yaml`](examples/configs/copilot-github-token/config.yaml) | `COPILOT_GITHUB_TOKEN` |
205
+ | OpenCode ACP | [`examples/configs/opencode-acp/config.yaml`](examples/configs/opencode-acp/config.yaml) | OpenCode-specific |
206
+
207
+ Use `generic_acp` for any CLI that can start an ACP stdio server:
169
208
 
170
209
  ```yaml
171
- trigger: none
172
- pr:
173
- - main
174
-
175
- pool:
176
- vmImage: ubuntu-latest
177
-
178
- steps:
179
- - checkout: self
180
- fetchDepth: 0
181
-
182
- - task: NodeTool@0
183
- inputs:
184
- versionSpec: "22.x"
185
-
186
- - script: npm install --global @openai/codex@latest @normahq/codex-acp-bridge@latest
187
- displayName: Install Codex provider
188
-
189
- - script: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
190
- displayName: Authenticate Codex
191
- env:
192
- OPENAI_API_KEY: $(OPENAI_API_KEY)
193
-
194
- - task: DiffPalReview@1
195
- displayName: DiffPal review
196
- inputs:
197
- diffpalVersion: latest
198
- language: en
199
- reviewChecks: security,bugs,performance,best-practices
200
- feedback: balanced
201
- gate: true
202
- env:
203
- OPENAI_API_KEY: $(OPENAI_API_KEY)
204
- SYSTEM_ACCESSTOKEN: $(System.AccessToken)
210
+ runtime:
211
+ providers:
212
+ my-review-agent:
213
+ type: generic_acp
214
+ generic_acp:
215
+ cmd: ["your-acp-cli", "acp", "--stdio"]
216
+
217
+ diffpal:
218
+ provider: my-review-agent
205
219
  ```
206
220
 
207
- The Azure task installs the DiffPal CLI by default. Set `install: false` to use
208
- a preinstalled binary from `PATH`, or set `diffpalPath` to a custom binary path.
221
+ Common provider aliases are available when the CLI is already installed and
222
+ authenticated:
209
223
 
210
- ## What You Should See
224
+ | Type | Runtime command |
225
+ | --- | --- |
226
+ | `codex_acp` | Codex ACP via the configured Codex bridge |
227
+ | `copilot_acp` | Copilot ACP |
228
+ | `opencode_acp` | `opencode acp` |
229
+ | `gemini_acp` | Gemini ACP |
230
+ | `claude_code_acp` | Claude Code ACP |
231
+ | `generic_acp` | Your explicit command |
232
+ | `openai`, `aistudio` | Hosted API providers |
233
+ | `pool` | Ordered provider failover |
234
+
235
+ ## MCP Servers
211
236
 
212
- On pull requests, DiffPal can publish:
237
+ DiffPal can pass MCP servers through the Norma runtime to providers that support
238
+ them. Declare servers once, then attach them to the provider:
213
239
 
214
- - a review summary with a semantic overview of the change
215
- - a check/status for merge gating
216
- - inline comments or threads for actionable findings
217
- - JSON, SARIF, and CI artifacts for later inspection
240
+ ```yaml
241
+ runtime:
242
+ mcp_servers:
243
+ repo-docs:
244
+ type: stdio
245
+ cmd: ["your-docs-mcp-server"]
246
+ args: ["--root", "."]
247
+ env:
248
+ DOCS_TOKEN: "${DOCS_TOKEN}"
249
+ policy-api:
250
+ type: http
251
+ url: "https://policy.example.com/mcp"
252
+ headers:
253
+ Authorization: "Bearer ${POLICY_MCP_TOKEN}"
254
+ providers:
255
+ opencode-acp:
256
+ type: opencode_acp
257
+ mcp_servers:
258
+ - repo-docs
259
+ - policy-api
260
+ opencode_acp:
261
+ model: opencode/big-pickle
262
+
263
+ diffpal:
264
+ provider: opencode-acp
265
+ ```
266
+
267
+ Keep MCP credentials in CI secrets. Use envsubst placeholders only for values
268
+ that are guaranteed to exist in that job.
269
+
270
+ ## Feedback Modes
271
+
272
+ Use `feedback` for the normal user-facing shape:
273
+
274
+ | Mode | Behavior |
275
+ | --- | --- |
276
+ | `summary` | One PR/MR summary plus check/status, no inline comments. |
277
+ | `balanced` | Summary plus actionable high-confidence inline feedback. |
278
+ | `inline` | Summary plus a more permissive inline threshold. |
279
+
280
+ Use `summary-overview: false` or `--summary-overview=false` if you do not want
281
+ the semantic change overview in the summary.
282
+
283
+ If two DiffPal workflows run on the same PR, give them separate channels:
284
+
285
+ ```yaml
286
+ with:
287
+ review-channel: diffpal-dev
288
+ review-id: github-pr-${{ github.event.pull_request.number }}-diffpal-dev
289
+ ```
218
290
 
219
- The default review checks are `security`, `bugs`, `performance`, and
220
- `best-practices`. The default review language is English. Checks, language, and
221
- custom review instructions are configurable in `.config/diffpal/config.yaml` or
222
- by CLI flags such as `--review-checks`, `--instructions`, and
223
- `--instructions-file`.
291
+ That produces a separate `diffpal-dev-checks` check run and separate summary
292
+ comment.
224
293
 
225
294
  ## Local Debugging
226
295
 
227
- Local commands are useful for setup checks and debugging, but they are not the
228
- main CI setup path.
296
+ CI is the main path, but local checks help when wiring a provider:
229
297
 
230
298
  ```bash
231
- npm install --global @diffpal/diffpal@latest @openai/codex@latest @normahq/codex-acp-bridge@latest
299
+ npm install --global @diffpal/diffpal@latest @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3
232
300
  printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
233
- diffpal init
234
301
  diffpal doctor --mode github
235
- diffpal review local --base origin/main --head HEAD
302
+ diffpal review local --base origin/main --head HEAD --profile ci
236
303
  ```
237
304
 
238
305
  ## Documentation
239
306
 
240
307
  - [Quickstart](docs/quickstart.md)
241
308
  - [CI setup guide](docs/ci-examples.md)
309
+ - [Examples](examples/README.md)
242
310
  - [Config reference](docs/config-reference.md)
243
311
  - [Findings schema](docs/findings-schema.md)
244
312
  - [GitLab adapter reference](docs/platform-gitlab.md)
package/package.json CHANGED
@@ -14,11 +14,11 @@
14
14
  "license": "SEE LICENSE IN LICENSE",
15
15
  "name": "@diffpal/diffpal",
16
16
  "optionalDependencies": {
17
- "@diffpal/diffpal-darwin-arm64": "0.1.5",
18
- "@diffpal/diffpal-darwin-x64": "0.1.5",
19
- "@diffpal/diffpal-linux-arm64": "0.1.5",
20
- "@diffpal/diffpal-linux-x64": "0.1.5",
21
- "@diffpal/diffpal-win32-x64": "0.1.5"
17
+ "@diffpal/diffpal-darwin-arm64": "0.1.7",
18
+ "@diffpal/diffpal-darwin-x64": "0.1.7",
19
+ "@diffpal/diffpal-linux-arm64": "0.1.7",
20
+ "@diffpal/diffpal-linux-x64": "0.1.7",
21
+ "@diffpal/diffpal-win32-x64": "0.1.7"
22
22
  },
23
- "version": "0.1.5"
23
+ "version": "0.1.7"
24
24
  }