diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml new file mode 100644 index 0000000..f25ae75 --- /dev/null +++ b/.pre-commit-hooks.yaml @@ -0,0 +1,9 @@ +- id: agentskit-review + name: AgentsKit Code Review + description: Run provider-neutral, adversarial code review over the repository diff. + entry: agentskit-review + language: node + pass_filenames: false + always_run: true + require_serial: true + stages: [manual] diff --git a/README.md b/README.md index 0e485d0..828dcbe 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,29 @@ The current command runs directly from GitHub. After the first npm release, the npx @agentskit/code-review --provider codex-cli ``` +## Run through pre-commit + +The repository publishes a [`pre-commit`](https://pre-commit.com/) hook for teams that already use that framework. It is manual by default because a full adversarial review is slower and more expensive than a formatter or linter. + +Add this to `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: https://github.com/AgentsKit-io/code-review-cli + rev: main # pre-release; pin a release tag when one contains the hook + hooks: + - id: agentskit-review + args: [--provider, codex-cli, --no-fail, --max-files, "20"] +``` + +Then run it when a change is ready for review: + +```sh +pre-commit run --hook-stage manual agentskit-review +``` + +The hook reviews the repository diff against `origin/main`; it does not claim to review only staged files. Override `--base` when your integration branch differs. To run on every push, override the hook with `stages: [pre-push]` and install that hook type explicitly, but first choose cost, latency, provider, and blocking policies appropriate for the repository. + ## Use the GitHub Action Add `.github/workflows/code-review.yml` to any repository: diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index d7ad1a5..6f2bd24 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -15,6 +15,14 @@ Credential precedence is `--api-key`, `LLM_API_KEY`, then `_API_KEY`. Do not run hosted review on code whose policy forbids external processing. A local model reduces external disclosure but does not remove the need to secure the runner, logs, cache, and generated SARIF. +## pre-commit integration + +The root `.pre-commit-hooks.yaml` exposes `agentskit-review` as a Node hook. It uses `pass_filenames: false` because the CLI reviews a Git diff, explicit paths, a pull request, or stdin rather than interpreting positional filenames. It is confined to the `manual` stage by default so cloning the hook does not silently add model calls to every commit. + +Consumer configuration must select a provider through `args`. Keep credentials in the provider login or environment; never place API keys in `.pre-commit-config.yaml`. Before overriding the hook to `stages: [pre-push]`, decide whether findings are advisory, set a file budget, and confirm that provider latency and data handling are appropriate for every contributor. + +The default diff base remains `origin/main`. A pre-commit invocation does not mean the input is limited to the Git staging area. Set `--base` explicitly when the repository uses another integration branch. + ## GitHub Action permissions The copy-ready workflow in [`examples/pull-request.yml`](../examples/pull-request.yml) requires: diff --git a/llms-full.txt b/llms-full.txt index 1f27faf..818cb2e 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -84,6 +84,29 @@ The current command runs directly from GitHub. After the first npm release, the npx @agentskit/code-review --provider codex-cli ``` +## Run through pre-commit + +The repository publishes a [`pre-commit`](https://pre-commit.com/) hook for teams that already use that framework. It is manual by default because a full adversarial review is slower and more expensive than a formatter or linter. + +Add this to `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: https://github.com/AgentsKit-io/code-review-cli + rev: main # pre-release; pin a release tag when one contains the hook + hooks: + - id: agentskit-review + args: [--provider, codex-cli, --no-fail, --max-files, "20"] +``` + +Then run it when a change is ready for review: + +```sh +pre-commit run --hook-stage manual agentskit-review +``` + +The hook reviews the repository diff against `origin/main`; it does not claim to review only staged files. Override `--base` when your integration branch differs. To run on every push, override the hook with `stages: [pre-push]` and install that hook type explicitly, but first choose cost, latency, provider, and blocking policies appropriate for the repository. + ## Use the GitHub Action Add `.github/workflows/code-review.yml` to any repository: @@ -301,6 +324,14 @@ Credential precedence is `--api-key`, `LLM_API_KEY`, then `_API_KEY`. Do not run hosted review on code whose policy forbids external processing. A local model reduces external disclosure but does not remove the need to secure the runner, logs, cache, and generated SARIF. +## pre-commit integration + +The root `.pre-commit-hooks.yaml` exposes `agentskit-review` as a Node hook. It uses `pass_filenames: false` because the CLI reviews a Git diff, explicit paths, a pull request, or stdin rather than interpreting positional filenames. It is confined to the `manual` stage by default so cloning the hook does not silently add model calls to every commit. + +Consumer configuration must select a provider through `args`. Keep credentials in the provider login or environment; never place API keys in `.pre-commit-config.yaml`. Before overriding the hook to `stages: [pre-push]`, decide whether findings are advisory, set a file budget, and confirm that provider latency and data handling are appropriate for every contributor. + +The default diff base remains `origin/main`. A pre-commit invocation does not mean the input is limited to the Git staging area. Set `--base` explicitly when the repository uses another integration branch. + ## GitHub Action permissions The copy-ready workflow in [`examples/pull-request.yml`](https://github.com/AgentsKit-io/code-review-cli/blob/main/examples/pull-request.yml) requires: diff --git a/package.json b/package.json index d1d5ccb..b0c30c4 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "README.md", "LICENSE", "AGENTS.md", + ".pre-commit-hooks.yaml", "action.yml", "examples/pull-request.yml", "SECURITY.md", diff --git a/readme-standard-v1.json b/readme-standard-v1.json index a8a8293..b15c5e7 100644 --- a/readme-standard-v1.json +++ b/readme-standard-v1.json @@ -215,7 +215,7 @@ "docs/OPERATIONS.md", "test/cli-smoke.test.mjs" ], - "sourceHash": "sha256:df64583bb8d08a538138986bfe3604ee9fb821c7271a08527fe758229f6116d8" + "sourceHash": "sha256:9b6b6c25a9ccdde85eb1f5eb39b484a8b4ca726a783584d4c8606a3342baaa5c" }, "exceptions": [] } diff --git a/test/documentation.test.mjs b/test/documentation.test.mjs index 7538c56..7fe7c8e 100644 --- a/test/documentation.test.mjs +++ b/test/documentation.test.mjs @@ -20,11 +20,31 @@ test('README communicates pipeline, maturity, contribution, and ecosystem role', test('operations guide covers every required security and release topic', () => { const operations = read('docs/OPERATIONS.md') - for (const marker of ['## Provider and credential choices', '## GitHub Action permissions', '## Advisory and blocking behavior', '## Cost and latency controls', '## SARIF', '## Failure scenarios', '## Releases and maturity', '## Contribution and security', 'pull_request_target', 'security-events: write']) { + for (const marker of ['## Provider and credential choices', '## pre-commit integration', '## GitHub Action permissions', '## Advisory and blocking behavior', '## Cost and latency controls', '## SARIF', '## Failure scenarios', '## Releases and maturity', '## Contribution and security', 'pull_request_target', 'security-events: write']) { assert.ok(operations.includes(marker), `operations guide missing ${marker}`) } }) +test('pre-commit hook is manual, provider-neutral, and reviews the repository diff', () => { + const hook = read('.pre-commit-hooks.yaml') + const readme = read('README.md') + for (const marker of [ + 'id: agentskit-review', + 'entry: agentskit-review', + 'language: node', + 'pass_filenames: false', + 'always_run: true', + 'require_serial: true', + 'stages: [manual]', + ]) { + assert.ok(hook.includes(marker), `pre-commit hook missing ${marker}`) + } + assert.match(readme, /pre-commit run --hook-stage manual agentskit-review/) + assert.match(readme, /does not claim to review only staged files/) + assert.match(readme, /args: \[--provider, codex-cli, --no-fail/) + assert.doesNotMatch(hook, /api[_-]?key/i) +}) + test('the Action stays least-privilege, secret-safe, and advisory by default', () => { const action = read('action.yml') const workflow = read('examples/pull-request.yml') @@ -100,6 +120,7 @@ test('published package keeps documentation generators and freshness enforcement '.doc-bridge/index.json', '.doc-bridge/capabilities.json', 'action.yml', + '.pre-commit-hooks.yaml', 'examples/pull-request.yml', ]) { assert.ok(manifest.files.includes(input), `published documentation input missing: ${input}`)