@methiu/raigal 0.2.4 → 0.2.6

package/README.md

@@ -33,7 +33,7 @@ See [Installation](#installation) for all options.
 
 Raigal supports TypeScript, JavaScript, Expo / React Native, Python, Go, Rust, Ruby, PHP, C#, and C/C++.
 
-Coverage includes formatting, linting, complexity, AI-slop detection, and security checks. Some checks use optional system tools; see [Installation](https://raigal.gitbook.io/raigal-docs/getting-started/installation).
+Coverage includes formatting, linting, complexity, AI-slop detection, and security checks. Some checks use optional system tools; see [Installation](https://docs.raigal.dev/getting-started/installation).
 
 ```bash
 raigal agent                 # repair with your coding agent (Codex/Claude/OpenCode)
@@ -95,7 +95,7 @@ pipx install raigal
 
 `pipx` keeps `raigal` in its own isolated environment. Needs Node.js on `PATH`.
 
-Full reference for every channel, optional bundled tooling, and external tools: [Installation Docs](https://raigal.gitbook.io/raigal-docs/getting-started/installation).
+Full reference for every channel, optional bundled tooling, and external tools: [Installation Docs](https://docs.raigal.dev/getting-started/installation).
 
 ---
 
@@ -309,7 +309,7 @@ raigal ci --sarif          # SARIF output for code scanning
 
 ```bash
 raigal                         # interactive menu
-raigal init                    # create .raigal/config.yml
+raigal init                    # interactive setup: engines, threshold, and CI pipeline (GitHub, GitLab, Bitbucket)
 raigal init --strict           # enterprise-grade gate: all engines, typecheck, failBelow 85
 raigal doctor                  # check which engines can run here
 raigal rules                   # list rules with severity, fixability, and score impact
@@ -324,12 +324,14 @@ raigal commands                # full command list
 
 **Score history**: a normal (full-project, interactive) `scan` appends a compact record to `.raigal/history.jsonl` (timestamp, score, error/warning counts, file count, CLI version). `raigal trend` and `raigal trends` read it and print a relative-time table plus an ASCII sparkline of recent scores. History is a local side effect only: it is never written for `--json`/`--sarif` output, in CI, or when `RAIGAL_NO_HISTORY=1` is set, so machine output stays clean.
 
-Docs: [Commands Reference](https://raigal.gitbook.io/raigal-docs/cli-reference/commands)
+Docs: [Commands Reference](https://docs.raigal.dev/cli-reference/commands)
 
 ---
 
 ## CI integration
 
+Running `raigal init` automatically inspects your repository, detects your CI provider (GitHub Actions, GitLab CI, or Bitbucket Pipelines), and scaffolds your CI workflow with zero guesswork.
+
 ### Pre-commit
 
 Run directly on staged files:
@@ -353,7 +355,7 @@ repos:
 
 ### GitHub Actions
 
-Add `.github/workflows/raigal.yml` to your repository. Provide your organization token via the `RAIGAL_TOKEN` secret. Setting `id-token: write` enables GitHub OIDC verification so the server can verify the repository owner:
+Scaffolded via `raigal init` as `.github/workflows/raigal.yml`. Setting `id-token: write` enables zero-token GitHub OIDC entitlement verification against your organization allowlist. Alternatively, pass an organization machine token via the `RAIGAL_TOKEN` secret:
 
 ```yaml
 name: raigal
@@ -378,6 +380,7 @@ jobs:
         run: npx --yes @methiu/raigal@latest ci
         env:
           RAIGAL_TOKEN: ${{ secrets.RAIGAL_TOKEN }}
+          # RAIGAL_ORG_ID: ${{ vars.RAIGAL_ORG_ID }} # Required only if repository owner belongs to multiple Raigal orgs
 ```
 
 **GitHub code scanning (SARIF)**: emit a SARIF 2.1.0 report and upload it so findings appear in the Security tab:
@@ -389,26 +392,61 @@ jobs:
     sarif_file: raigal.sarif
 ```
 
+### GitLab CI
+
+Scaffolded via `raigal init` as `.gitlab-ci.yml`. Gating merge requests on changed code and default branch pushes on full repository analysis:
+
+```yaml
+# .gitlab-ci.yml
+raigal_quality_gate:
+  image: node:24
+  stage: test
+  script:
+    - if [ -n "$CI_MERGE_REQUEST_IID" ]; then npx --yes @methiu/raigal@latest ci --changes --base "$CI_MERGE_REQUEST_DIFF_BASE_SHA"; else npx --yes @methiu/raigal@latest ci .; fi
+  variables:
+    RAIGAL_TOKEN: $RAIGAL_TOKEN
+    # RAIGAL_ORG_ID: $RAIGAL_ORG_ID # Required only if repository owner belongs to multiple Raigal orgs
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+Set `RAIGAL_TOKEN` under **Settings > CI/CD > Variables**.
+
 ### Bitbucket Pipelines
 
-Bitbucket clones shallow by default, so fetch the PR target branch and gate on only the changed files with `ci --changes --base`:
+Scaffolded via `raigal init` as `bitbucket-pipelines.yml`. Full clone is configured so branch diffs against the pull request destination branch resolve cleanly:
 
 ```yaml
 # bitbucket-pipelines.yml
 pipelines:
+  default:
+    - step:
+        name: raigal quality gate
+        image: node:24
+        script:
+          - npx --yes @methiu/raigal@latest ci .
+        secrets:
+          - RAIGAL_TOKEN
+          # - RAIGAL_ORG_ID
   pull-requests:
     "**":
       - step:
-          name: raigal gate
+          name: raigal quality gate
           image: node:24
           clone:
-            depth: full   # branch diffs need history
+            depth: full   # branch diffs need full history
           script:
             - git fetch origin "$BITBUCKET_PR_DESTINATION_BRANCH"
             - npx --yes @methiu/raigal@latest ci --changes --base FETCH_HEAD
+          secrets:
+            - RAIGAL_TOKEN
+            # - RAIGAL_ORG_ID
 ```
 
-`ci` applies the score gate and exit code, so no JSON parsing or hand-rolled threshold is needed. More providers: [CI/CD Documentation](https://raigal.gitbook.io/raigal-docs/automation-and-ci-cd/ci-cd).
+Set `RAIGAL_TOKEN` under **Repository settings > Repository variables**.
+
+`ci` applies the score gate and exit code, so no JSON parsing or hand-rolled threshold is needed. More providers: [CI/CD Documentation](https://docs.raigal.dev/automation-and-ci-cd/ci-cd).
 
 ### Quality gate
 
@@ -419,7 +457,12 @@ ci:
   failBelow: 70
 ```
 
-`raigal ci` exits 1 when score < threshold. Docs: [CI/CD Documentation](https://raigal.gitbook.io/raigal-docs/automation-and-ci-cd/ci-cd)
+`raigal ci` evaluates PRs with a calibrated 3-state verdict:
+- **`PASSED`**: Score $\ge$ threshold (default 70) and 0 blocker errors or warnings.
+- **`PASSED (WITH WARNINGS)`**: Score $\ge$ threshold and 0 blocker errors, but actionable warnings present. Merges proceed without blocking.
+- **`FAILED / BLOCKED`**: Score $<$ threshold, non-zero exit code, or blocker errors present. Merges are blocked.
+
+When using GitHub Actions OIDC in multi-tenant organizations, set `RAIGAL_ORG_ID: org_...` in your workflow environment if your repository owner is mapped across multiple organizations.
 
 ---
 
@@ -458,21 +501,21 @@ Six deterministic engines run in parallel:
 | **Security** | Vulnerabilities and risky code | eval, innerHTML, SQL/shell injection, dependency audits for JavaScript, Python, Rust, Go, and .NET |
 | **Architecture** | Structural rules (opt-in) | Custom import bans, layering rules, required patterns |
 
-See the full [Rules Reference](https://raigal.gitbook.io/raigal-docs/core-concepts/rules).
+See the full [Rules Reference](https://docs.raigal.dev/core-concepts/rules).
 
 ---
 
 ## Research
 
-Raigal rules are shaped by public scans and benchmark-derived failure modes, not only local fixtures. The [documentation](https://raigal.gitbook.io/raigal-docs) defines how to run repeatable open-source scans: pin the cohort, store raw JSON, classify findings, fix noisy rules with regression tests, and publish the limits.
+Raigal rules are shaped by public scans and benchmark-derived failure modes, not only local fixtures. The [documentation](https://docs.raigal.dev) defines how to run repeatable open-source scans: pin the cohort, store raw JSON, classify findings, fix noisy rules with regression tests, and publish the limits.
 
 ---
 
 ## Docs
 
-Read the complete documentation at [raigal.gitbook.io/raigal-docs](https://raigal.gitbook.io/raigal-docs):
+Read the complete documentation at [docs.raigal.dev](https://docs.raigal.dev):
 
-[Installation](https://raigal.gitbook.io/raigal-docs/getting-started/installation) · [Commands](https://raigal.gitbook.io/raigal-docs/cli-reference/commands) · [Rules](https://raigal.gitbook.io/raigal-docs/core-concepts/rules) · [Configuration](https://raigal.gitbook.io/raigal-docs/cli-reference/configuration) · [Scoring](https://raigal.gitbook.io/raigal-docs/core-concepts/scoring) · [CI/CD](https://raigal.gitbook.io/raigal-docs/automation-and-ci-cd/ci-cd) · [Pull Requests](https://raigal.gitbook.io/raigal-docs/automation-and-ci-cd/pull-requests) · [Agent Repairs](https://raigal.gitbook.io/raigal-docs/automation-and-ci-cd/agent-repairs)
+[Installation](https://docs.raigal.dev/getting-started/installation) · [Commands](https://docs.raigal.dev/cli-reference/commands) · [Rules](https://docs.raigal.dev/core-concepts/rules) · [Configuration](https://docs.raigal.dev/cli-reference/configuration) · [Scoring](https://docs.raigal.dev/core-concepts/scoring) · [CI/CD](https://docs.raigal.dev/automation-and-ci-cd/ci-cd) · [Pull Requests](https://docs.raigal.dev/automation-and-ci-cd/pull-requests) · [Agent Repairs](https://docs.raigal.dev/automation-and-ci-cd/agent-repairs)
 
 ## Community