@methiu/raigal 0.2.5 → 0.2.7

package/LICENSE

@@ -1 +1,6 @@
-PROPRIETARY. All rights reserved. Use is permitted only under a written agreement with Raigal.
+Copyright (c) 2026 Raigal. All rights reserved.
+
+PROPRIETARY. Use is permitted only under a written agreement with Raigal.
+
+This software includes third-party components licensed under their own terms.
+See THIRD_PARTY_NOTICES.md for those components and their licences.

package/README.md

@@ -5,11 +5,11 @@
 [![npm version](https://img.shields.io/npm/v/@methiu/raigal.svg)](https://www.npmjs.com/package/@methiu/raigal) [![npm downloads](https://img.shields.io/npm/dm/@methiu/raigal.svg)](https://www.npmjs.com/package/@methiu/raigal) [![CI](https://github.com/meethiu/raigal/actions/workflows/ci.yml/badge.svg)](https://github.com/meethiu/raigal/actions/workflows/ci.yml) [![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 The patterns Claude Code, Cursor, Codex, and OpenCode leave behind: narrative comments above self-explanatory code, swallowed exceptions, hidden fallbacks, `as any` casts, hallucinated imports, duplicated helpers, dead code, todo stubs, oversized functions. Tests pass. Lint passes. The code rots anyway.
 
-Raigal catches them. 50+ rules across 10 language targets (TypeScript, JavaScript, Expo / React Native, Python, Go, Rust, Ruby, PHP, C#, C/C++). Scores every change 0-100. Sub-second. Deterministic: no LLM in the runtime path, same code in, same score out.
+Raigal catches them. 50+ rules across 10 language targets (TypeScript, JavaScript, Expo / React Native, Python, Go, Rust, Ruby, PHP, C#, C/C++). Scores every change 0-100. No LLM in the scoring path: the same code and tool versions give the same score.
 
 ## Quick start
 
-Raigal is demo software licensed to organizations on an admin-managed allowlist. Runs require authentication via organization credentials (`raigal login` or `RAIGAL_TOKEN`).
+Raigal is licensed to organizations on an admin-managed allowlist. Runs require authentication via organization credentials (`raigal login` or `RAIGAL_TOKEN`).
 
 ```bash
 # 1. Sign in with your organization account
@@ -21,7 +21,7 @@ raigal scan
 
 In CI and automated workflows, provide your organization API key via the `RAIGAL_TOKEN` environment variable.
 
-Also available on npm, Yarn, Bun, and Homebrew:
+Install it with npm, pnpm, Yarn, or Bun:
 
 ```bash
 npm install -g @methiu/raigal
@@ -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)
@@ -53,7 +53,7 @@ raigal hook install --claude # per-edit hook
 
 ## Installation
 
-The same CLI is published to npm and Homebrew. Pick whichever fits your stack.
+The CLI is published to npm as `@methiu/raigal`. The unscoped `raigal` package is an official alias that installs the same CLI.
 
 **Node / npm**
 
@@ -79,23 +79,7 @@ npm install -g @methiu/raigal
 
 Package installation does not run dependency lifecycle scripts. After installing, run `raigal-tools` once if you want bundled Ruff and golangci-lint coverage; the core scanner works without it.
 
-**Homebrew** (macOS / Linux)
-
-```bash
-brew install meethiu/tap/raigal
-```
-
-Homebrew installs Node.js as a dependency if it isn't already present. Details: [homebrew-tap](https://github.com/meethiu/homebrew-tap).
-
-**Python / pipx**
-
-```bash
-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).
 
 ---
 
@@ -286,7 +270,7 @@ Expose Raigal as MCP tools for Claude Desktop, Cursor, Codex:
   "mcpServers": {
     "raigal": {
       "command": "npx",
-      "args": ["-y", "@methiu/raigal-mcp"]
+      "args": ["-y", "@methiu/raigal@latest", "mcp"]
     }
   }
 }
@@ -309,8 +293,8 @@ raigal ci --sarif          # SARIF output for code scanning
 
 ```bash
 raigal                         # interactive menu
-raigal init                    # create .raigal/config.yml
-raigal init --strict           # enterprise-grade gate: all engines, typecheck, failBelow 85
+raigal init                    # interactive setup: engines, threshold, and CI pipeline (GitHub, GitLab, Bitbucket)
+raigal init --strict           # strict gate: all engines, typecheck, failBelow 85
 raigal doctor                  # check which engines can run here
 raigal rules                   # list rules with severity, fixability, and score impact
 raigal rules --search          # searchable rule explorer
@@ -324,12 +308,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 +339,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 +364,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 +376,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 +441,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.
 
 ---
 
@@ -442,9 +469,20 @@ AI coding tools generate code that compiles and passes tests but ships with patt
 
 - **One score**: 0-100, enforced in CI. Weighted so sloppy patterns hit harder than style noise.
 - **Auto-fix first**: Clears formatters, unused imports, dead code mechanically. Hands off the rest to your agent with full context.
-- **Deterministic**: Regex + AST + standard tooling. No LLMs, no API calls. Same code in, same score out.
+- **No LLM in scoring**: Regex + AST + standard tooling. The same code and tool versions give the same score. See [Network access](#network-access) for the calls a run does make.
 - **Fast onboarding**: Runs with your organization session (`raigal login`) or CI token (`RAIGAL_TOKEN`). Add `.raigal/config.yml` to tune.
 
+## Network access
+
+Raigal scores code on your machine, but a run is not offline. It contacts:
+
+- **Raigal Cloud** (`app.raigal.dev`): sign-in, the organization licence check, and the upload of run results while you are signed in. In GitHub Actions it also requests an OIDC token from GitHub.
+- **Package registries**, through dependency audits (`npm audit`, `pnpm audit`, `bun audit`, `pip-audit` when installed). On by default; set `security.audit: false` to turn them off.
+- **npm registry**, to check for a newer CLI version. Turn off with `RAIGAL_NO_UPDATE_NOTIFIER=1`.
+- **Usage telemetry** (PostHog, EU host). Off in CI; turn off with `RAIGAL_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`.
+
+`raigal-tools` downloads Ruff and golangci-lint only when you run it.
+
 ## What it catches
 
 Six deterministic engines run in parallel:
@@ -458,21 +496,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
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,70 @@
+# Third-Party Software Notices and Information
+
+This product contains components subject to open source licenses.
+
+---
+
+## aislop
+
+Portions of this software are derived from aislop (https://github.com/scanaislop/aislop),
+used under the MIT License. Raigal's own code is not covered by this notice; see `LICENSE`.
+
+MIT License
+
+Copyright (c) 2025 heavykenny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## Third-Party Package Dependencies
+
+The following third-party packages may be bundled into or used by distributions of this software:
+
+- `@biomejs/biome` (MIT OR Apache-2.0) - https://github.com/biomejs/biome
+- `@clack/prompts` (MIT) - https://github.com/natemoo-re/clack
+- `@modelcontextprotocol/sdk` (MIT) - https://github.com/modelcontextprotocol/typescript-sdk
+- `adm-zip` (MIT) - https://github.com/cthackers/adm-zip
+- `commander` (MIT) - https://github.com/tj/commander.js
+- `expo-doctor` (MIT) - https://github.com/expo/expo
+- `ink` (MIT) - https://github.com/vadimdemedes/ink
+- `ink-select-input` (MIT) - https://github.com/vadimdemedes/ink-select-input
+- `knip` (ISC) - https://github.com/webpro-nl/knip
+- `micromatch` (MIT) - https://github.com/micromatch/micromatch
+- `oxlint` (MIT) - https://github.com/oxc-project/oxc
+- `picocolors` (ISC) - https://github.com/alexeyraspopov/picocolors
+- `react` (MIT) - https://github.com/facebook/react
+- `smol-toml` (BSD-3-Clause) - https://github.com/cyyynthia/smol-toml
+- `tar` (BlueOak-1.0.0 / ISC) - https://github.com/isaacs/node-tar
+- `typescript` (Apache-2.0) - https://github.com/microsoft/TypeScript
+- `wcwidth` (MIT) - https://github.com/timoxley/wcwidth
+- `yaml` (ISC) - https://github.com/eemeli/yaml
+- `zod` (MIT) - https://github.com/colinhacks/zod
+
+---
+
+## External Tools (Downloaded Standalone Binaries)
+
+The following external tools are downloaded separately as standalone binaries by `raigal-tools` and executed as separate child processes. They are NOT bundled or redistributed inside the Raigal JavaScript library:
+
+- `ruff` (MIT / Apache-2.0) - https://github.com/astral-sh/ruff
+- `golangci-lint` (GPL-3.0) - https://github.com/golangci/golangci-lint
+- `AsyncFixer` (Apache-2.0) - https://github.com/semihokur/AsyncFixer
+- `Meziantou.Analyzer` (MIT) - https://github.com/meziantou/Meziantou.Analyzer
+- `IDisposableAnalyzers` (MIT) - https://github.com/DotNetAnalyzers/IDisposableAnalyzers