@critiq/cli 0.0.2 → 0.1.0

package/README.md

@@ -53,12 +53,60 @@ Run Critiq against a diff:
 npx critiq check . --base origin/main --head HEAD
 ```
 
+## GitHub Actions
+
+To run the same checks on **pull requests** in GitHub Actions—with optional **inline PR review comments** and severity-based merge gates—use the official composite action **[critiq-dev/critiq-action](https://github.com/critiq-dev/critiq-action)** ([README](https://github.com/critiq-dev/critiq-action/blob/main/README.md)). The action wraps `critiq check`, honors `.critiq/config.yaml`, and can install published `@critiq/cli` / `@critiq/rules` when they are not already declared on the repository root `package.json`.
+
+Example `.github/workflows/critiq.yml`:
+
+```yaml
+name: Critiq
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  critiq:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Critiq
+        uses: critiq-dev/critiq-action@v1
+        with:
+          fail-on-severity: off
+```
+
+Use a **major tag** (`@v1`) or pin a **commit SHA** for supply-chain control. More options (inputs, outputs, monorepos, reusable workflow) are in the [action README](https://github.com/critiq-dev/critiq-action/blob/main/README.md).
+
 ## Public Commands
 
+`critiq check` also runs an **advisory** built-in secret scan (same scope as the rule engine, plus optional `--staged` for index-only staging review) and prints a short summary before rule results. That scan does **not** change the `critiq check` exit code; use `critiq audit secrets` for full output and for gating in CI.
+
+**What "staged review" means**
+
+- "Staged" means Git index content (what `git add` has queued), not all local edits.
+- Critiq reads staged content the same way Git does for commit previews (`git diff --cached`).
+- Use this when you want pre-commit checks to match exactly what will be committed.
+
 | Command | What it does |
 | --- | --- |
 | `critiq check [target]` | Runs deterministic checks against a codebase, directory, or single file. |
 | `critiq check . --base origin/main --head HEAD` | Limits scanning to changed files and changed ranges in a diff. |
+| `critiq check . --staged` | Rule scan unchanged; the advisory secret scan reads only what is staged in Git index (`git diff --cached`). |
+| `critiq check . --format sarif` | Exports findings as SARIF 2.1.0 for code scanning and security platforms. |
+| `critiq check . --format html` | Exports a shareable HTML report for human review and audit handoff. |
+| `critiq audit secrets [target]` | Runs the dedicated secret-pattern scanner (exit non-zero when matches are found). |
+| `critiq audit secrets . --base origin/main --head HEAD` | Secret scan over changed files only (includes non-code paths such as `.env`). |
+| `critiq audit secrets . --staged` | Secret scan over staged paths/blobs from Git index (`git diff --cached`) (pre-commit friendly). |
+| `critiq audit` / `critiq audit --help` | Lists audit subcommands. |
 | `critiq rules validate <glob>` | Validates rule YAML files and returns diagnostics. |
 | `critiq rules test [glob]` | Runs fixture-backed `RuleSpec` files end to end. |
 | `critiq rules normalize <file>` | Prints the canonical normalized form of one rule. |
@@ -84,6 +132,12 @@ severityOverrides: {}
 
 Supported presets are `recommended`, `strict`, `security`, and `experimental`.
 
+Optional `secretsScan` in the same file merges extra `ignorePaths` (in addition to top-level `ignorePaths`), disables individual detectors by id (match the `detectorId` field in JSON output; published ids are exported as `SECRETS_SCAN_DETECTOR_IDS` from `@critiq/check-runner`), and drops findings listed under `suppressFingerprints` (64 lowercase hex characters from JSON `fingerprint`).
+
+## Git hooks
+
+Sample scripts ship under `scripts/hooks/` in this package (for example `pre-commit.sample.sh` runs `critiq audit secrets . --staged`; `pre-push.sample.sh` runs a diff against `origin/main` or `CRITIQ_PRE_PUSH_BASE`). Copy one to `.git/hooks/` and mark it executable, or wire the same commands into Husky.
+
 ## Default OSS Rule Catalog
 
 The default open source catalog in [`@critiq/rules`](https://www.npmjs.com/package/@critiq/rules) currently includes `112` rules across `10` categories.
@@ -123,6 +177,7 @@ The default open source catalog in [`@critiq/rules`](https://www.npmjs.com/packa
 - [Getting started](https://github.com/critiq-dev/critiq-core/blob/main/docs/guides/getting-started.md)
 - [CLI reference](https://github.com/critiq-dev/critiq-core/blob/main/docs/reference/cli.md)
 - [`@critiq/rules` package](https://www.npmjs.com/package/@critiq/rules)
+- [Critiq GitHub Action](https://github.com/critiq-dev/critiq-action/blob/main/README.md) (CI and PR comments)
 
 ## License