GitHub Action

The complexijs GitHub Action runs cognitive complexity analysis directly in your CI pipeline using the same Rust engine compiled to WebAssembly. No Rust toolchain or build step is required: the WASM artifact ships with the action.

Use in a pull request check

Copy the workflow below into .github/workflows/complexity.yml to add a complexity gate to every pull request and every push to main:

name: Complexity check

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  complexity:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: yonib05/complexijs@v0
        with:
          max-complexity-allowed: "15"

What you get with this workflow:

Inline error annotations appear on the PR diff for each function that exceeds the threshold.
A job summary table lists every violating function sorted by complexity descending.
The check fails (exit code 1) when any function exceeds the threshold, blocking merge when required status checks are enabled.

More recipes

(a) Report-only mode on pull requests

Collect the violation count without blocking the build by setting fail-on-complexity: "false":

steps:
  - uses: actions/checkout@v4

  - name: Check cognitive complexity
    id: complexity
    uses: yonib05/complexijs@v0
    with:
      fail-on-complexity: "false"

  - name: Summarize
    run: echo "Failed functions: ${{ steps.complexity.outputs['failed-functions'] }}" >> "$GITHUB_STEP_SUMMARY"

(b) Monorepo subset

Analyze only specific packages and exclude generated files by extension or by directory:

steps:
  - uses: actions/checkout@v4

  - uses: yonib05/complexijs@v0
    with:
      paths: packages/web packages/api
      exclude: "packages/web/dist/**,packages/api/dist/**,*.spec.ts"
      max-complexity-allowed: "15"

The exclude input accepts comma-separated patterns. Supported forms:

dir/** excludes an entire directory subtree. Patterns are matched against workspace-root-relative paths, so use the full path from the repository root (e.g. packages/web/dist/**), not just a bare directory name like dist/**, which would only prune a top-level dist/ directory.
*.ext excludes all files with that extension regardless of directory (e.g. *.spec.ts).
An exact relative path excludes a single file.

(c) Using outputs in a follow-up step

Read the action outputs after the step runs to feed downstream decisions or summaries:

steps:
  - uses: actions/checkout@v4

  - name: Check cognitive complexity
    id: complexity
    uses: yonib05/complexijs@v0
    with:
      fail-on-complexity: "false"

  - name: Post metrics
    run: |
      echo "Total functions: ${{ steps.complexity.outputs['total-functions'] }}" >> "$GITHUB_STEP_SUMMARY"
      echo "Failed functions: ${{ steps.complexity.outputs['failed-functions'] }}" >> "$GITHUB_STEP_SUMMARY"
      echo "Max complexity found: ${{ steps.complexity.outputs['max-complexity-found'] }}" >> "$GITHUB_STEP_SUMMARY"

Versioning

Pin a released tag in production workflows to avoid unexpected behavior from main-branch changes:

- uses: yonib05/complexijs@v0        # moving major tag, receives patch updates
- uses: yonib05/complexijs@v0.1.2    # pinned to an exact release

Use @main only in pre-release or experimental workflows.

Inputs

Input	Description	Default
`paths`	Space-separated paths (files or directories) to analyze, relative to the workspace	`.`
`max-complexity-allowed`	Maximum cognitive complexity a function may have	`15`
`exclude`	Comma-separated exclude patterns (`dir/*` prefixes or `.ext` suffixes); directory patterns are matched against workspace-root-relative paths	`""`
`fail-on-complexity`	Fail the step when any function exceeds the threshold	`true`
`annotations`	Emit inline error annotations for exceeding functions	`true`
`check-script`	Also score module-level code as `<module>`	`false`
`no-ignore`	Disregard `complexijs: ignore` comments	`false`

Outputs

Output	Description
`total-functions`	Number of functions analyzed
`failed-functions`	Number of functions exceeding the threshold
`max-complexity-found`	Highest complexity encountered

Annotations

When annotations: true (the default), each function that exceeds the threshold produces an inline GitHub error annotation pointing to the function definition. These appear as review comments in pull requests and as job annotations in the Actions UI.

Step summary

The action always appends a markdown summary to the workflow job summary when GITHUB_STEP_SUMMARY is set (which GitHub sets automatically). The summary lists the total function count and, when violations exist, a table of exceeding functions sorted by complexity descending.

Relationship to the CLI

The action and the CLI use the same engine: the Rust analyzer compiled to WASM. They produce identical results for the same inputs.

The action covers the common CI use case: analyze source files, annotate pull requests, and gate on a threshold. For more advanced scenarios, use the CLI in a workflow run step:

Gitignore-aware discovery (the action walker always skips node_modules and dotfiles but does not read .gitignore)
TOML configuration via complexijs.toml
Snapshot watermarks (--snapshot-create / default run)
Complexity diff against a base branch (--diff main)
Machine-readable output formats (--output-format json,csv,sarif)
SARIF upload to GitHub code scanning

Branch protection

After the workflow above is in place, go to repository Settings, Branches, and add the complexity job as a required status check on the main branch. Pull requests that introduce functions exceeding the threshold will be blocked from merging.