rigortype 0.2.1 → 0.2.2

data/docs/manual/11-ci.md

@@ -0,0 +1,274 @@
+# Running Rigor in CI
+
+Rigor runs on Ruby 4.0 (see
+[Installing Rigor](01-installation.md)). In CI that
+has one consequence worth stating up front; the rest of this page
+follows from it.
+
+## Run Rigor in its own job
+
+Run Rigor in a **separate CI job** from your test suite — better
+still, a separate workflow file. The reason is concrete:
+`ruby/setup-ruby` sets the *job's* active Ruby. A test job
+provisions the Ruby your project runs (often a 3.x version, or a
+matrix of several); Rigor needs Ruby 4.0. The two cannot share a job
+without the second `setup-ruby` call clobbering the first.
+
+A separate job gives Rigor a clean runner where provisioning Ruby
+4.0 conflicts with nothing. A separate workflow file additionally
+gets its own triggers, concurrency group, and status badge — and
+keeps the analyser out of the test workflow, which is good practice
+regardless.
+
+## A minimal GitHub Actions workflow
+
+```yaml
+# .github/workflows/rigor.yml
+name: rigor
+on: [push, pull_request]
+jobs:
+  rigor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+      - run: gem install rigortype
+      - run: rigor check
+```
+
+Those four steps check out the project, provision Ruby 4.0, install
+Rigor, and run it. That workflow surfaces diagnostics only in the job
+log. To put them **inline on the changed code** (a PR annotation, a
+code-scanning alert, a merge-request widget) use one of the CI-native
+output formats below.
+
+## It already works on GitHub Actions (auto-detection)
+
+`rigor check` detects the CI it runs in and, on its default output, surfaces
+diagnostics the platform-native way **without any `--format`** — modelled on
+PHPStan's CI auto-detection. So the minimal workflow at the top of this page
+already produces inline PR annotations on GitHub Actions: the human log stays,
+and `::error` annotations are added on top.
+
+- **GitHub Actions** and **TeamCity** (first-class): native annotations are
+  emitted on top of the text output automatically.
+- **GitLab CI** (native, but artifact-based): a one-line hint reminds you to
+  run `--format gitlab` and publish the `codequality` artifact (below).
+- **Other CIs** (CircleCI, Jenkins, Travis, Azure, Bitbucket, Buildkite,
+  Drone, …): a one-line hint points you at the reviewdog or `--format junit`
+  path.
+
+Auto-detection only augments the default human output — an explicit
+`--format` is never touched. Turn it off with `--no-ci-detect` or
+`RIGOR_CI_DETECT=0`. The sections below are for when you want a *specific*
+surface (code scanning, the GitLab widget, review comments) rather than the
+auto default.
+
+## Surfacing diagnostics inline in the PR / MR
+
+`rigor check --format` renders the same diagnostics in a format your CI
+platform reads to annotate the diff directly, instead of leaving them in
+the job log ([ADR-51](../adr/51-ci-diagnostic-output-formats.md)). These
+layer on the generic `--format json` stream; they add no new diagnostics,
+only a platform-native rendering. Ready-to-copy template files live under
+[`ci-templates/`](ci-templates/).
+
+### GitHub — inline annotations (the default)
+
+`--format github` emits GitHub Actions workflow commands
+(`::error file=…,line=…::`) that the runner turns into inline annotations
+on the PR — no upload step, no code-scanning setup, no extra permissions.
+Because it works on **every** repository (public or private, no paid
+features), it is the recommended default for GitHub:
+
+```yaml
+      - run: gem install rigortype
+      - run: rigor check --format github
+```
+
+### GitHub — code scanning (SARIF)
+
+Upgrade to SARIF for the Security tab, deduped + persistent alerts, and
+richer PR alerts — **when code scanning is available**: a public repo
+(free), or a private repo with GitHub Advanced Security / Code Security
+enabled. (Without it, `upload-sarif` fails with *"GitHub Advanced Security
+must be enabled for this repository"* — use the annotations form above.)
+The check step uses `continue-on-error` (and the upload runs `if: always()`)
+so a non-zero Rigor exit still publishes the report:
+
+```yaml
+# .github/workflows/rigor.yml
+name: rigor
+on: [push, pull_request]
+permissions:
+  contents: read
+  security-events: write   # required by upload-sarif
+jobs:
+  rigor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+      - run: gem install rigortype
+      - run: rigor check --format sarif > rigor.sarif
+        continue-on-error: true
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: rigor.sarif
+```
+
+SARIF is the cross-platform option: the same report is consumed by any
+SARIF-aware tool, not only GitHub.
+
+### GitLab — Code Quality widget
+
+`--format gitlab` emits a GitLab Code Quality (CodeClimate-subset) report.
+Publish it as a `codequality` report artifact and GitLab renders the
+findings in the merge-request widget:
+
+```yaml
+# .gitlab-ci.yml
+rigor:
+  image: ruby:4.0
+  script:
+    - gem install rigortype
+    - rigor check --format gitlab > gl-code-quality-report.json
+  artifacts:
+    reports:
+      codequality: gl-code-quality-report.json
+    when: always
+```
+
+### Any platform — reviewdog
+
+[reviewdog](https://github.com/reviewdog/reviewdog) posts findings as PR/MR
+review comments on GitHub, GitLab, Gerrit, Bitbucket, and Gitea. It reads
+Rigor's `sarif` or `checkstyle` output, so one of those formats reaches
+*all* of its reporters. Install it with
+[`reviewdog/action-setup`](https://github.com/reviewdog/action-setup) and
+pipe Rigor into it:
+
+```yaml
+      - uses: reviewdog/action-setup@v1
+      - run: rigor check --format checkstyle | reviewdog -f=checkstyle -reporter=github-pr-review -fail-level=error
+        env:
+          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+`github-pr-review` needs `permissions: pull-requests: write`. The
+`rigor-ci-setup` skill (`rigor skill rigor-ci-setup`) walks through
+the reporter and `-fail-level` choices.
+
+### Other test-report CI — JUnit
+
+`--format junit` emits JUnit XML, which GitHub test reporting, GitLab,
+CircleCI, and Jenkins render. Every diagnostic becomes a `testcase` with a
+`failure` typed by its severity:
+
+```sh
+rigor check --format junit > rigor-junit.xml
+```
+
+### Severity mapping
+
+Rigor's severities map per format ([ADR-51](../adr/51-ci-diagnostic-output-formats.md) WD2):
+
+| Rigor | SARIF | GitHub | GitLab | Checkstyle | JUnit | TeamCity |
+| --- | --- | --- | --- | --- | --- | --- |
+| error | `error` | `::error` | `major` | `error` | `error` | `ERROR` |
+| warning | `warning` | `::warning` | `minor` | `warning` | `warning` | `WARNING` |
+| info | `note` | `::notice` | `info` | `info` | `info` | `INFO` |
+
+The exit code is unchanged by `--format` — `0` when there are no errors,
+`1` otherwise — so the job still gates the pipeline. `--format json`
+remains available for any other tool that wants the raw diagnostic stream.
+
+## Pinning Rigor's version
+
+The workflow above installs whatever `rigortype` is current at run
+time. To pin a version — and keep CI reproducible — choose one of the
+options below. While the `0.1.x` line is in preview the surface is
+still settling, so pinning is recommended; what Rigor commits to
+keeping stable (and from which release) is enumerated in
+[`docs/compatibility.md`](../compatibility.md).
+
+### A CI-only `Gemfile` (recommended)
+
+Commit a two-line `.github/rigor/Gemfile`:
+
+```ruby
+source "https://rubygems.org"
+gem "rigortype", "~> 0.1"
+```
+
+plus its `Gemfile.lock`, and point the Rigor job at it through
+`BUNDLE_GEMFILE`:
+
+```yaml
+jobs:
+  rigor:
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: .github/rigor/Gemfile
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+      - run: bundle exec rigor check
+```
+
+This `Gemfile` is read only by the Rigor job — it never enters your
+application's dependency resolution, and the committed lockfile
+pins Rigor and its dependencies for a reproducible run. Because it
+is an ordinary Bundler `Gemfile`, Dependabot can keep it current:
+add a `bundler` entry scoped to its directory in
+`.github/dependabot.yml`:
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: /.github/rigor
+    schedule:
+      interval: weekly
+```
+
+### A pinned `gem install`
+
+`gem install rigortype -v "0.1.15"` in the workflow. Simpler, with no
+extra files — but Dependabot does not see a version inside a `run:`
+step, so updates to the pin are manual.
+
+## Container image
+
+A standalone image is published to GHCR with Ruby 4.0 and Rigor
+baked in. It suits CI runners with no Ruby toolchain — mount the
+project on `/src`:
+
+```sh
+docker run --rm -v "$PWD:/src" ghcr.io/rigortype/rigor check
+```
+
+`rigor` is the image entrypoint, so subcommands and flags follow the
+image name. Pin a version with an explicit tag —
+`ghcr.io/rigortype/rigor:0.1.15`.
+
+## Nix
+
+For CI that already runs Nix, the flake exposes Rigor as a package
+with Ruby 4.0 in its closure — a fully hermetic run with nothing
+else on the runner:
+
+```sh
+nix run github:rigortype/rigor#rigor -- check
+```
+
+See [ADR-27](../adr/27-tool-distribution-model.md) for the
+distribution model behind this page.

data/docs/manual/12-caching.md

@@ -0,0 +1,116 @@
+# Caching
+
+Rigor caches expensive intermediate results — parsed RBS
+environments, per-file analysis products — so a second run
+over an unchanged project is fast. The cache is correct by
+construction: you should never need to clear it to fix a stale
+result. This page is for the times you are curious where it
+lives or want to reclaim the space.
+
+## Where it lives
+
+The cache is an on-disk directory, `.rigor/cache` by default,
+relative to the project root. Change it with the `cache.path`
+config key:
+
+```yaml
+cache:
+  path: tmp/rigor-cache
+```
+
+Add the cache directory to your `.gitignore`.
+
+## What invalidates an entry
+
+Each entry is keyed by a hash of everything its result depends
+on:
+
+- the **content** of the source and `.rbs` files that fed it,
+- the **gems** in play, by name and locked version,
+- the active **plugins**, by ID and version,
+- the relevant **configuration**.
+
+Change any of those and the dependent entries are recomputed
+automatically. A corrupt or unreadable entry is treated as a
+miss and overwritten — bad cache state cannot wedge a run.
+
+The cache is also schema-versioned: after a Rigor upgrade that
+changes the cache format, the stale cache is purged on the
+first writable run.
+
+## Controlling the cache
+
+| Flag | Effect |
+| --- | --- |
+| `rigor check --no-cache` | Run without reading or writing the persistent cache. |
+| `rigor check --clear-cache` | Delete the cache directory, then run. |
+| `rigor check --cache-stats` | Print the on-disk cache inventory when the run finishes. |
+| `rigor check --incremental` | Re-analyse only what changed; serve the rest from the incremental snapshot (see below). |
+
+There is no config key to disable caching permanently — the
+flags are per-run toggles. To run without a persistent cache
+habitually, point `cache.path` at a disposable directory.
+
+## Size and eviction
+
+A project's active cache set is small (around 2 MB). Entries
+are content-keyed, so events like a gem upgrade or an `.rbs`
+edit write fresh entries and leave the old ones *orphaned* —
+nothing references them, and no run would otherwise delete
+them. To reap those, Rigor evicts least-recently-used entries
+at the end of a run once the cache directory exceeds
+`cache.max_bytes` (default **256 MB** — far above any active
+set, so eviction only ever touches orphans):
+
+```yaml
+cache:
+  max_bytes: 67108864   # tighten the cap to 64 MB…
+```
+
+```yaml
+cache:
+  max_bytes: null       # …or disable eviction entirely
+```
+
+## Incremental analysis
+
+The cache above makes an *unchanged* project fast — a second
+run over the same files reuses the whole result. `rigor check
+--incremental` goes further: when you have edited a few files,
+it re-analyses **only those files plus the files that depend on
+them**, and serves every other file's diagnostics from a
+snapshot of the previous run. Editing a leaf controller
+re-checks one file; editing a model re-checks the model and its
+callers — not the whole project.
+
+The diagnostics are identical to a full run. Rigor records, per
+file, which other files its analysis read from, so it knows
+exactly which files an edit can affect. A continuous-integration
+gate, `rigor check --verify-incremental`, asserts this on every
+build: it runs the incremental analyzer and a full analysis and
+fails if they disagree on a single diagnostic.
+
+The snapshot lives under the cache directory (`.rigor/cache`)
+and is keyed by a fingerprint of your configuration, your locked
+gems, your project's own `sig/` RBS, and the Rigor version.
+Change any of those and the snapshot is dropped and the next run
+is a full one, so an incremental run can never serve a stale
+result. (The fingerprint keys on the analysis *roots* — e.g.
+`["lib"]` — not the expanded file list, so adding or removing a
+file *under* those roots does **not** drop the snapshot: the
+incremental session re-analyzes the added files and the
+dependents of removed ones.) As with the rest of the cache, a
+missing or corrupt snapshot is simply a full run; it can never
+wedge analysis.
+
+`--incremental` is most useful for fast local re-checks and CI
+on a changed branch. For a one-shot run on an unchanged project,
+the ordinary cache already serves the whole result in one step.
+
+## Concurrency
+
+The cache is safe to share. Parallel worker processes
+(`--workers=N`) and multiple editor LSP sessions against the
+same project coordinate through atomic, locked writes; the LSP
+opens the cache read-only, so it never races a `rigor check`
+running alongside it.

data/docs/manual/13-troubleshooting.md

@@ -0,0 +1,120 @@
+# Troubleshooting
+
+Common problems and their fixes. For editor-specific issues,
+see [Editor integration](09-editor-integration.md); for "why
+did this diagnostic (not) fire", see
+[handbook chapter 8](../handbook/08-understanding-errors.md).
+
+## `rigor: command not found`
+
+Rigor is installed but not on your `PATH`. With a version
+manager this usually means the shell is not activated — see
+[Installing Rigor](01-installation.md). As a stop-gap,
+`mise exec gem:rigortype -- rigor …` runs it explicitly.
+
+## `rigor check` analyses nothing
+
+Rigor checks the `paths:` from the configuration file when no
+paths are given on the command line. If `paths:` is wrong, or
+no config file was found, the run is empty. Confirm a
+`.rigor.yml` or `.rigor.dist.yml` exists at the project root,
+or pass paths explicitly: `rigor check lib app`.
+
+## Everything is `untyped` / `Dynamic[top]`
+
+Rigor has no type information for the code in question. The
+usual causes:
+
+- **A gem ships no RBS.** Install signatures with
+  `rbs collection install`, or opt into
+  `dependencies.source_inference` (see
+  [Configuration](03-configuration.md)).
+- **A framework needs a plugin.** Rails, RSpec, dry-rb and
+  others are only legible to Rigor through a
+  [plugin](07-plugins.md).
+- **A project monkey-patch is invisible.** List the patching
+  files under `pre_eval:` so Rigor walks them first.
+
+`rigor type-of FILE:LINE:COL` reports the exact type at a
+point, which narrows down where the information is lost.
+
+## Too many diagnostics to act on
+
+A first run on a large, untyped project can report hundreds of
+diagnostics. Do not start by suppressing them one by one:
+
+1. `rigor triage` — see which rules and files dominate, with
+   hints about likely causes.
+2. Fix the systemic causes triage points at — a missing
+   plugin, a missing RBS bundle.
+3. `rigor baseline generate` — snapshot the rest so CI tracks
+   only new diagnostics. See [Baselines](06-baseline.md).
+
+The [`rigor-project-init` skill](08-skills.md) automates this
+sequence.
+
+## A diagnostic is wrong (a false positive)
+
+Rigor aims never to flag working code, so a genuine false
+positive is a bug worth reporting. In the meantime, suppress
+the single site with a `# rigor:disable <rule>` comment (see
+[Diagnostics](04-diagnostics.md)) — prefer that over a
+project-wide `disable:`, which also hides real instances.
+
+Before reporting, rule out a missing RBS source. A burst of
+`call.undefined-method` on calls you know exist usually means
+Rigor never loaded their signatures. Check `rigor check`'s
+STDERR for a `rigor: …` config-validation warning — a typo'd
+or moved `signature_paths:` / `libraries:` entry (or an
+explicit `bundler` / `rbs_collection` path that no longer
+exists) loads zero signatures silently, and every call into
+the types it was meant to cover then fires at
+`evidence_tier: high`. Correct the configured value and the
+false positives clear. (The same warnings cover an inert
+`disable:` / `severity_overrides:` rule id — a typo there
+leaves the rule firing as if you never suppressed it.) See
+[Configuration § Config validation warnings](03-configuration.md#config-validation-warnings).
+
+If the diagnostic is *correct* but you are not ready to fix
+it, a [baseline](06-baseline.md) is the right tool.
+
+## A result looks stale
+
+It should not — cache entries are keyed by content and
+invalidate themselves (see [Caching](12-caching.md)). If you
+suspect the cache anyway, `rigor check --clear-cache` rules it
+out. A result that survives a cleared cache is real analyzer
+behaviour, not a caching artefact.
+
+## The run is slow
+
+- Let the cache warm up — the first run is the slow one.
+- Narrow `paths:` and widen `exclude:` so Rigor is not walking
+  generated or vendored code.
+- For a large project, `rigor check --workers=N` spreads
+  per-file analysis across parallel worker processes (or set
+  `RIGOR_RACTOR_WORKERS=N`).
+
+## Advanced diagnostics
+
+When a class infers worse than you expect, or a run uses more
+memory than you expect, three environment variables make Rigor
+report on *itself*. They print to stderr after `rigor check`
+finishes and are no-ops when unset. They are process-global
+counters, so run single-process (`--workers 0`) for meaningful
+numbers.
+
+| Variable | Reports |
+| --- | --- |
+| `RIGOR_BUDGET_TRACE=1` | How often inference hit a built-in cutoff (recursion guard, ancestor-walk limit, HKT fuel, …) and silently degraded to `Dynamic[top]`, plus the union-size distribution. The fastest way to see *where* inference gave up. |
+| `RIGOR_HEAP_PROFILE=1` | A live-heap breakdown by class after a forced GC, ranked by memory — what the resident heap is actually made of (type carriers, RBS objects, Prism nodes, …). Walking the whole heap is slow; use it as a probe, not on every run. |
+| `RIGOR_HEAP_TRACE=1` | The top String allocation sites by `file:line`. Very high overhead — run it on a small file subset only. |
+
+These are intended for diagnosing Rigor itself or filing a
+detailed bug report, not for day-to-day use.
+
+## Reporting a bug
+
+Open a GitHub issue with the Rigor version (`rigor version`),
+the command you ran, a minimal reproduction, and — for a
+suspected false positive — what you expected Rigor to infer.