npm - @critiq/cli - Versions diffs - 0.0.1 → 0.1.0 - Mend

@critiq/cli 0.0.1 → 0.1.0

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 (3) hide show

package/README.md CHANGED Viewed

@@ -1,305 +1,184 @@
-# critiq CLI
+<p align="center">
+  <img src="https://raw.githubusercontent.com/critiq-dev/critiq-core/main/docs/assets/banner-cli-simple-transparent.png" alt="critiq.dev" style="max-height:400px" />
+</p>
-`critiq` is the local developer interface for working with Critiq rules in your
-own repository.
+<h1 align="center">Critiq CLI</h1>
+<p align="center">
+  <strong>Open source deterministic static analysis for code review.<br/>Run high-signal checks on your codebase to identify security, performance, scaling issues before it goes to production</strong>
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@critiq/cli"><img src="https://img.shields.io/npm/v/%40critiq%2Fcli" alt="npm version" /></a>
+  <a href="https://github.com/critiq-dev/critiq-core/tree/main/apps/cli"><img src="https://img.shields.io/badge/source-GitHub-181717?logo=github" alt="Source" /></a>
+  <a href="https://github.com/critiq-dev/critiq-core/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License" /></a>
+</p>
-Install it with the default OSS catalog:
-```bash
-npm install -D @critiq/cli @critiq/rules
-npx critiq check .
-```
-It is designed for two equally important modes:
-- manual invocation while a developer is authoring, debugging, or reviewing a rule
-- automated invocation in CI to increase confidence in a PR or run a broader repository scan
-Use it when you want to:
-- run rules against real repository code or a PR diff
-- validate authored rules before committing them
-- explain how a rule is interpreted
-- normalize a rule into the canonical internal form
-- run fixture-based `RuleSpec` tests for a rule pack
-- use the same deterministic checks locally and in automation
-The CLI now has two modes:
-- `critiq check` is catalog-first and loads rules from `.critiq/config.yaml`
-- `critiq rules ...` commands remain path-based for pack authors and maintainers
-If you want to run the built CLI from `dist/`, use:
-```bash
-npm run build:release-cli
-node dist/publish/cli/main.js --help
-```
-`dist/publish/cli` is the self-contained npm release artifact for
-`@critiq/cli`.
-## Recommended Project Layout
-A common consumer setup is:
-```text
-.critiq/
-  config.yaml
-```
-with:
-```yaml
-apiVersion: critiq.dev/v1alpha1
-kind: CritiqConfig
-catalog:
-  package: "@critiq/rules"
-preset: recommended
-disableRules: []
-disableCategories: []
-disableLanguages: []
-includeTests: false
-ignorePaths: []
-severityOverrides: {}
-```
-If you are authoring your own rules, a common convention is:
-```text
-.critiq/
-  rules/
-    no-console.rule.yaml
-    no-console.spec.yaml
-  fixtures/
-    no-console/
-      valid.ts
-      invalid.ts
-```
-This is only a convention. Authoring commands work with any file path or glob
-you give them, so you can also:
-- keep rules in another local folder
-- vendor a shared rule pack into your repo
-- install a rule pack and reference it from `.critiq/config.yaml`
-## Commands
-- `critiq check [target]`
-- `critiq rules validate <glob>`
-- `critiq rules test [glob]`
-- `critiq rules normalize <file>`
-- `critiq rules explain <file>`
-## What Each Command Is For
-### `check`
-Use this to run the configured catalog against real source files in a
-repository.
-This is the runtime/CI entrypoint when you want Critiq to inspect application
-code rather than validate or test the rule pack itself. `check` reads
-`.critiq/config.yaml`, resolves the configured catalog package, applies preset
-selection and subtractive overrides, auto-detects repository languages from
-supported source files, and evaluates the active rules.
-Today that means:
-- deepest support for TypeScript and JavaScript
-- early phase-1 adapter coverage for Go, Java, PHP, Python, Ruby, and Rust
-- tests excluded from `check` by default unless `includeTests: true`
-Examples:
-```bash
-critiq check
-critiq check . --format json
-critiq check . --base origin/main --head HEAD --format json
-```
+Think of Critiq as an extra code reviewer that scans your project for bugs, security issues, performance problems, and risky changes before they turn into production incidents. Instead of only checking style, it focuses on the kinds of problems that usually slip through review and cause real trouble later. You run it locally or in CI, and it gives you deterministic findings you can act on before merging code.
-Migration:
-```bash
-# old
-critiq check ".critiq/rules/*.rule.yaml" .
+It does this by parsing your code, matching it against a curated catalog of explicit rules, and reporting findings with concrete evidence tied to the code that triggered them. That means the output is based on repeatable checks for things like unsafe SQL, missing authorization, repeated IO in loops, and untested critical logic changes, not vague heuristics or style-only linting.
-# new
-critiq check .
-```
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/critiq-dev/critiq-core/main/docs/assets/cli-architecture-transparent.png"
+    alt="Cli Architecture"
+  />
+</p>
-### `validate`
+`@critiq/cli` runs Critiq checks against real code and exposes the public rule-pack commands for validation, testing, normalization, and explanation. By default it uses [`@critiq/rules`](https://www.npmjs.com/package/@critiq/rules) as the open source catalog with recommended rules. You can configure this by adding a `.critiq/config.yaml` configuration file.
-Use this while authoring rules.
+<br/>
+<p align="left">
+  <img
+    src="https://raw.githubusercontent.com/critiq-dev/critiq-core/main/docs/assets/languages.png"
+    alt="TypeScript, JavaScript, Node.js, Go, Java, Python, PHP, Ruby and Rust support"
+  />
+</p>
-It loads the YAML, validates the public contract, runs semantic validation, and
-returns diagnostics only.
+`@critiq/cli` is capable of scanning codebases written in TypeScript, JavaScript, Node.js, Go, Java, Python, PHP, Ruby, and Rust.
-This is the command you would commonly use in a PR-focused workflow to make
-sure authored rules are valid before the rules are executed elsewhere.
+## Start In 60 Seconds
-Examples:
+Run Critiq on your project:
 ```bash
-critiq rules validate ".critiq/rules/*.rule.yaml"
-critiq rules validate "packages/my-pack/rules/*.rule.yaml"
+npm install -D @critiq/cli @critiq/rules
+npx critiq check .
 ```
-### `test`
-Use this to run `RuleSpec` fixtures and prove rule behavior end to end.
-This is the command that gives you confidence that a rule pack behaves the way
-you expect before using it in an automated PR check or a repository scan.
-If you omit the glob, it defaults to `**/*.spec.yaml` from the current working
-directory.
-Examples:
+Run Critiq against a diff:
 ```bash
-critiq rules test
-critiq rules test ".critiq/rules/*.spec.yaml"
+npx critiq check . --base origin/main --head HEAD
 ```
-### `normalize`
-Use this when you want to inspect the canonical normalized IR for one rule.
-Example:
+## GitHub Actions
-```bash
-critiq rules normalize .critiq/rules/no-console.rule.yaml --format json
-```
+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`.
-### `explain`
+Example `.github/workflows/critiq.yml`:
-Use this when you want a readable breakdown of:
+```yaml
+name: Critiq
-- parsed rule metadata
-- validation status
-- normalized rule content
-- inferred template variables
+on:
+  pull_request:
-Example:
+permissions:
+  contents: read
+  pull-requests: write
-```bash
-critiq rules explain .critiq/rules/no-console.rule.yaml
+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
 ```
-## Flags
+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).
-- `--format pretty|json`
-- `--help`
+## Public Commands
-`pretty` is the default.
+`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.
-## Exit Codes
+**What "staged review" means**
-- `0`: success
-- `1`: findings or non-internal command failures
-- `2`: internal/runtime errors
+- "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.
-## Typical Developer Workflow
+| 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. |
+| `critiq rules explain <file>` | Shows a readable breakdown of how one rule is interpreted. |
-Authoring a new rule:
+## Runtime Config
-```bash
-npm run nx -- run cli:prune
-critiq rules validate ".critiq/rules/*.rule.yaml"
-critiq rules explain .critiq/rules/no-console.rule.yaml
-critiq rules test ".critiq/rules/*.spec.yaml"
-```
-Working from the separate `critiq-rules` repo:
-```bash
-npm run nx -- run cli:prune
-critiq rules validate "../critiq-rules/examples/starter-pack/rules/*.rule.yaml"
-critiq rules explain ../critiq-rules/examples/starter-pack/rules/ts.logging.no-console-log.rule.yaml
-critiq rules test "../critiq-rules/examples/starter-pack/rules/*.spec.yaml"
-```
-Running in automation:
-```bash
-npm run nx -- run cli:prune
-critiq check . --format json
-critiq rules validate ".critiq/rules/*.rule.yaml" --format json
-critiq rules test ".critiq/rules/*.spec.yaml" --format json
-```
-### Reusable GitHub Workflow
-Consumer repositories can call the reusable workflow published from this repo
-instead of copying the CLI setup into every workflow file.
-Example:
+`critiq check` is catalog-first. When `.critiq/config.yaml` is present, it controls the catalog package, preset, and filters used for the run.
 ```yaml
-jobs:
-  critiq:
-    uses: critiq-dev/critiq-core/.github/workflows/run-critiq-cli.yml@ref
-    with:
-      critiq-version: x.y.z
-      run-check: true
-      check-target: .
-      check-base: origin/main
-      check-head: HEAD
-      validate-glob: .critiq/rules/*.rule.yaml
-      test-glob: .critiq/rules/*.spec.yaml
+apiVersion: critiq.dev/v1alpha1
+kind: CritiqConfig
+catalog:
+  package: "@critiq/rules"
+preset: recommended
+disableRules: []
+disableCategories: []
+disableLanguages: []
+includeTests: false
+ignorePaths: []
+severityOverrides: {}
 ```
-The workflow:
-- checks out the consumer repository
-- installs Node.js
-- installs the requested `@critiq/cli` package version
-- optionally runs `check`, `validate`, and `test` with JSON output
-- uploads the JSON results as workflow artifacts
-For production use, pin both the workflow ref and `critiq-version`.
-## JSON Output
+Supported presets are `recommended`, `strict`, `security`, and `experimental`.
-All commands support `--format json`.
+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`).
-That makes the CLI usable as:
+## Git hooks
-- a terminal tool for humans
-- a machine-readable step in CI
-- a building block for custom wrappers
+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.
-That means the same CLI can sit behind:
+## Default OSS Rule Catalog
-- a developer manually checking a rule before commit
-- a repository or PR gate that emits findings from real source files
-- a PR workflow that wants confidence before merge
-- a scheduled or on-demand full repository scan
+The default open source catalog in [`@critiq/rules`](https://www.npmjs.com/package/@critiq/rules) currently includes `112` rules across `10` categories.
-See [docs/reference/cli.md](../../docs/reference/cli.md) for the envelope
-shapes.
+| Category | Rules | What it looks after |
+| --- | ---: | --- |
+| Security | 70 | Injection, auth and session gaps, unsafe transport, sensitive data exposure, unsafe file and HTML handling |
+| Correctness | 15 | Async bugs, null access, control-flow mistakes, missing fallbacks, race conditions |
+| Performance | 10 | Repeated IO, wasted async sequencing, hot-path loops, large retained objects, render churn |
+| Quality | 10 | Error handling gaps, oversized functions, coupling, duplicated logic, and weak test coverage |
+| Logging | 2 | Console usage and unsafe logging patterns |
+| Config | 1 | Configuration access boundaries |
+| Next | 1 | Server and client boundary leaks |
+| Random | 1 | Unsafe randomness in core logic |
+| React | 1 | Cascaded effect fetch patterns |
+| Runtime | 1 | Debug-only statements left in shipped code |
-## Relationship To The Rest Of The Repo
+## High-Value Rules In The Default Catalog
-The CLI is intentionally thin. It composes the OSS packages rather than
-re-implementing their logic.
+| Rule title | Description |
+| --- | --- |
+| `Hardcoded API keys or credentials` | Source files should not embed credential-like string literals. |
+| `Avoid raw or interpolated SQL`| Database query sinks must not receive request-driven or dynamically interpolated SQL text. |
+| `Path traversal via user input` | File access calls must not use request-controlled paths directly. |
+| `Protect deserialization trust boundaries`| Deserializers should not consume untrusted payloads directly across a trust boundary. |
+| `Server-side request forgery` (`ts.security.ssrf`) | Outbound requests should not use attacker-controlled targets or private hosts. |
+| `Open redirect via request-controlled target`| Redirect and navigation sinks should not use request-controlled destinations without validation. |
+| `Missing authorization before sensitive action` | Sensitive backend actions should be guarded by an authorization or permission check. |
+| `Use authenticated encryption for secrets and tokens` | Session, cookie, and token encryption should provide integrity protection in the same helper. |
+| `Missing await on async call` | Async functions should not drop direct async calls without awaiting them. |
+| `Repeated IO call inside loop` | Database or network calls inside loops can multiply latency and load. |
+| `Logic change without corresponding test updates` | Diffs that change critical logic should usually update the matching tests in the same change. |
+| `Avoid server/client boundary leaks in Next.js` | Server components should not use browser-only APIs or client-only hooks without an explicit client boundary. |
-- repository scanning comes from `@critiq/check-runner`
-- adapter-backed source analysis comes from `@critiq/adapter-typescript`
-- rule loading and validation come from `@critiq/core-rules-dsl`
-- normalization comes from `@critiq/core-ir`
-- diagnostics rendering comes from `@critiq/core-diagnostics`
-- fixture-based testing comes from `@critiq/testing-harness`
+## Reference
-That means you can use the CLI directly, or use the underlying packages inside
-your own tooling if you need more control.
+- [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)
-## Development Commands
+## License
-- `npm run nx -- build cli`
-- `npm run nx -- run cli:prune`
-- `npm run nx -- test cli`
-- `npm run nx -- lint cli`
-- `npm run nx -- typecheck cli`
+`@critiq/cli` is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). See the source [LICENSE](https://github.com/critiq-dev/critiq-core/blob/main/LICENSE).