rigortype 0.2.1 → 0.2.2

data/docs/manual/08-skills.md

@@ -0,0 +1,143 @@
+# Provided skills
+
+Rigor bundles a set of **Agent Skills** — structured workflows an AI
+coding agent (Claude Code and compatible tools) can run on your behalf.
+They live in [`skills/`](../../skills/) and are auto-discovered when an
+agent works inside a project that has Rigor available.
+
+Skills are optional. Everything they do, you can do by hand with the
+commands in this manual; a skill drives the workflow end to end.
+
+## Start here — two skills to remember
+
+You only ever need to remember two skills; the rest are reached through
+them.
+
+- **`rigor-next-steps`** — *"what should we do next?"* The single entry
+  point: hand it to an agent and it resolves the `rigor` command
+  (installing it if missing), onboards an unconfigured project, then asks
+  `rigor skill describe` what to do next and routes to the matching skill
+  in the catalogue below. The end-to-end workflow it drives is
+  [Driving project improvement with `rigor-next-steps`](17-driving-improvement.md).
+- **`rigor-ask`** — *"answer this about Rigor."* Ask anything in plain
+  language — why a diagnostic fired or whether it's a false positive, how
+  narrowing / refinements / shapes work, what a flag or config key does,
+  how Rigor compares to Sorbet / Steep / mypy / PHPStan, whether it
+  handles a given gem or framework, or how to type a method. Rigor is
+  niche and version-specific, so instead of answering from memory the
+  agent **investigates**: it reads the bundled handbook and manual
+  **offline** via [`rigor docs`](02-cli-reference.md#rigor-docs) (plus
+  `rigor explain` for a diagnostic id) *and*, for a question about your
+  code, runs `rigor check` / `annotate` / `type-of` — then answers from
+  the page or the inferred type. You never have to remember the command,
+  just the question. Available at any point.
+
+If you do not know which skill you need, start with `rigor-next-steps`.
+
+## The catalogue
+
+Every skill below is a destination `rigor-next-steps` (via
+`rigor skill describe`) can route you to. (`rigor-ask`, above, is the
+always-available question skill rather than a routed destination, so it
+is not repeated here.)
+
+### Onboarding and foundation
+
+- **`rigor-project-init`** — onboards a project from a cold start. It
+  detects the stack (Rails, RSpec, dry-rb, …), proposes the matching
+  [plugins](07-plugins.md), picks an adoption mode — a
+  [baseline](06-baseline.md) snapshot for an existing codebase or a
+  zero-diagnostic gate for a clean one — writes a `.rigor.dist.yml`, and
+  generates the first baseline. Reach for it when setting Rigor up for
+  the first time.
+- **`rigor-rbs-setup`** — installs community RBS for your gems
+  (`rbs collection install`) so RBS-less dependencies stop typing as
+  `Dynamic`. Rigor auto-detects the resulting `rbs_collection.lock.yaml`.
+- **`rigor-plugin-tune`** — re-matches `Gemfile.lock` to the bundled
+  plugin catalogue and enables the plugins for your current stack
+  (verifying with `rigor plugins --strict`). Reach for it after adding a
+  gem, or for a Rails app whose Rails plugins are not yet enabled.
+
+### Improving and reducing
+
+- **`rigor-protection-uplift`** — closes the type-protection holes
+  `rigor coverage --protection` surfaces: sig-gen first, then the
+  minimal hand-RBS residual, under a double gate (the site becomes
+  protected *and* `rigor check` gains no new diagnostic). See
+  [Type-protection coverage](15-type-protection-coverage.md).
+- **`rigor-baseline-reduce`** — works an existing `.rigor-baseline.yml`
+  down rule by rule. It prioritises with `rigor triage`, classifies each
+  site as a real bug / safe stylistic finding / false positive, and
+  regenerates the baseline. Reach for it to chip away at the backlog.
+- **`rigor-monkeypatch-resolve`** — resolves an `undefined-method`
+  cluster that is really your project's own monkey-patches by wiring the
+  defining files into `pre_eval:`.
+
+### Integration and operations
+
+- **`rigor-ci-setup`** — wires Rigor into CI with inline PR/MR
+  diagnostics (SARIF / GitHub Actions / GitLab Code Quality / reviewdog).
+  See [Running Rigor in CI](11-ci.md).
+- **`rigor-editor-setup`** — wires the bundled `rigor lsp` language
+  server into your editor (Neovim, VS Code, Helix, Emacs). See
+  [Editor integration](09-editor-integration.md).
+- **`rigor-mcp-setup`** — wires the bundled `rigor mcp` server into an
+  AI coding agent (Claude Code, Cursor, Cline, …). See
+  [MCP server](10-mcp-server.md).
+
+### Maintenance and authoring
+
+- **`rigor-upgrade`** — adopts a new Rigor version cleanly: diff against
+  the baseline, sort genuine new catches from sig-quality false
+  positives, regenerate.
+- **`rigor-doctor`** — validates that the setup is healthy (config
+  resolves, plugins load, the baseline is fresh, the RBS environment is
+  not broken). See [Troubleshooting](13-troubleshooting.md).
+- **`rigor-plugin-author`** — scaffolds a new Rigor plugin in your own
+  repository to teach Rigor an application DSL or metaprogramming
+  pattern it cannot infer. Reach for it when no bundled plugin covers a
+  framework or DSL your project depends on.
+
+## Discovering skills from the CLI
+
+The skills ship inside the `rigortype` gem, so they are reachable even
+when Rigor is installed via `mise` / `gem install` with no project-side
+source checkout. The `rigor skill` command surfaces them:
+
+```sh
+rigor skill describe        # probe the project + recommend the next skill (alias: rigor describe)
+rigor skill --list          # name + absolute path for each bundled skill
+rigor skill <name>          # print the SKILL.md body (with a references/ header)
+rigor skill --path <name>   # one-line absolute SKILL.md path, for a file-reading tool
+```
+
+`rigor skill describe` is the recommendation engine driven by
+`rigor-next-steps`; `rigor skill rigor-project-init` is the
+canonical way to hand an agent the onboarding workflow without pointing
+it at the repository. The `list` / `print` / `path` verb spellings are
+deprecated (removed in v0.3.0). See [CLI reference](02-cli-reference.md#rigor-skill).
+
+## Installing skills into a project
+
+In addition to the gem, the user-facing skills are installable via
+[vercel-labs/skills](https://github.com/vercel-labs/skills) — useful for
+dropping the entry point into a project *before* Rigor is installed:
+
+```sh
+# Just the entry point (recommended):
+npx skills add https://github.com/rigortype/rigor/tree/master/skills/rigor-next-steps
+# Or the whole user-facing set:
+npx skills add rigortype/rigor
+```
+
+(The contributor-only skills under `.claude/skills/` are marked internal
+and are not installed by a bulk `npx skills add`.)
+
+## Running a skill
+
+In an agent that supports Agent Skills, invoke the skill by name (in
+Claude Code, `/rigor-next-steps`). The agent reads the skill definition
+(from `skills/` in a source checkout, or via `rigor skill <name>`
+otherwise) and follows it. If your tool does not support skills, each
+skill's `SKILL.md` still reads as a plain checklist you can follow
+yourself.

data/docs/manual/09-editor-integration.md

@@ -0,0 +1,245 @@
+# Rigor LSP — Editor Integration
+
+`rigor lsp` is the in-process Language Server bundled with the
+`rigortype` gem. It speaks the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
+over stdio and exposes Rigor's analyzer as a live editor experience —
+diagnostics on every keystroke, hover-to-type, outline view, and
+type-aware completion.
+
+This page is the entry point for wiring it into your editor. The
+design + capability matrix lives in
+[`docs/design/20260517-language-server.md`](../design/20260517-language-server.md)
+(v1) and
+[`docs/design/20260517-lsp-hover-completion.md`](../design/20260517-lsp-hover-completion.md)
+(v2). Packaging rationale is in
+[`docs/adr/19-language-server-packaging.md`](../adr/19-language-server-packaging.md).
+
+## Features at a glance
+
+| LSP method | Behaviour |
+|---|---|
+| `textDocument/publishDiagnostics` | Pushed on every `didChange`, 200ms debounced. Severity / rule / source map directly to Rigor's diagnostic taxonomy. |
+| `textDocument/hover` | Type-aware markdown. Per-node-class dispatch surfaces receiver type + RBS signature for method calls, FQN + singleton type + defined-in path for constants, narrowed type + bound-at for locals, canonical refinement names (`non-empty-string`, …) for `Refined` / `Difference` carriers. |
+| `textDocument/completion` | Method completion after `.` (driven by inferred receiver type), constant-path completion after `::`. Composite receivers (Union → intersection of methods, Tuple / HashShape → ancestor nominal, Refined → underlying nominal) handled. Parse-recovery sentinel makes mid-edit `obj.` / `Foo::` buffers work. |
+| `textDocument/documentSymbol` | Outline tree from Prism AST: `class` / `module` / `def` with nesting. |
+| `workspace/didChangeWatchedFiles` | Invalidates the per-session `Environment` + `Cache::Store` cache so saved files repropagate. |
+| `workspace/didChangeConfiguration` | Same — re-reads `.rigor.yml` / `Gemfile.lock` etc. |
+
+## Prerequisites
+
+The single prerequisite is **`rigor` on your `PATH`** — the same
+executable `rigor check` and `rigor type-of` already use. Any of the
+install channels in [Installing Rigor](01-installation.md) provide it;
+`mise` is the recommended one because its shims make `rigor` available
+to GUI-launched editors that do not inherit your shell environment.
+
+Do **not** add `rigortype` to your project's `Gemfile`. Rigor is a
+tool, not a library — installing it standalone keeps its Ruby version
+and its dependencies out of your application's resolution. See
+[Installing Rigor § Recommended — a runtime version manager](01-installation.md#recommended--a-runtime-version-manager).
+
+The LSP server runs as `rigor lsp`, using the same binary as
+`rigor check` / `rigor type-of`. There is no separate gem and no
+addon registration.
+
+## CLI
+
+```sh
+rigor lsp [--transport=stdio] [--log=PATH] [--config=PATH]
+```
+
+- `--transport=stdio` — default; only value accepted in v1. TCP /
+  Unix-socket transports are queued.
+- `--log=PATH` — wire log + server debug to a file. Without it,
+  server-side logs go to stderr.
+- `--config=PATH` — mirrors `rigor check --config=PATH`. Without
+  it, `Configuration.discover` walks `.rigor.yml` / `.rigor.dist.yml`
+  from the project root.
+
+## Editor wiring
+
+Every snippet below invokes `rigor lsp` directly, which works as soon
+as `rigor` is on the editor's `PATH` (the `mise` shim path, an
+`asdf` shim, or whatever your install channel set up — see
+[Installing Rigor](01-installation.md)).
+
+If you have an older, project-local install that puts `rigortype` in
+the project's `Gemfile`, swap `rigor lsp` for `bundle exec rigor lsp`
+(and add `cwd` / `BUNDLE_GEMFILE` as your editor requires). This is
+a legacy fallback; new installs should not need it.
+
+### Neovim — nvim-lspconfig
+
+Add a custom server entry. `nvim-lspconfig` doesn't ship a built-in
+preset for Rigor yet, so register it manually:
+
+```lua
+local configs = require('lspconfig.configs')
+local lspconfig = require('lspconfig')
+
+if not configs.rigor then
+  configs.rigor = {
+    default_config = {
+      cmd = { 'rigor', 'lsp' },
+      filetypes = { 'ruby' },
+      root_dir = lspconfig.util.root_pattern('.rigor.yml', '.rigor.dist.yml', 'Gemfile', '.git'),
+      single_file_support = false,
+    },
+  }
+end
+
+lspconfig.rigor.setup({})
+```
+
+Place this in your `init.lua` (or under `lua/plugins/`). Restart
+Neovim and open a Ruby file inside a Rigor-configured project; you
+should see diagnostics appear on save and hover work via `K`. For a
+legacy bundler-based install, set `cmd = { 'bundle', 'exec', 'rigor', 'lsp' }`.
+
+### VS Code — generic LSP client
+
+There's no first-party VS Code extension yet. Use a generic
+LSP-client wrapper extension, or write a minimal extension that
+registers the server:
+
+```ts
+// extension.ts (minimal example)
+import { workspace, ExtensionContext } from 'vscode';
+import { LanguageClient, ServerOptions, TransportKind } from 'vscode-languageclient/node';
+
+let client: LanguageClient;
+
+export function activate(context: ExtensionContext) {
+  const serverOptions: ServerOptions = {
+    command: 'rigor',
+    args: ['lsp'],
+    transport: TransportKind.stdio,
+  };
+  client = new LanguageClient(
+    'rigor',
+    'Rigor Language Server',
+    serverOptions,
+    { documentSelector: [{ scheme: 'file', language: 'ruby' }] }
+  );
+  client.start();
+}
+
+export function deactivate() { return client?.stop(); }
+```
+
+For a legacy bundler-based install, set `command: 'bundle', args: ['exec', 'rigor', 'lsp']`.
+
+Publish as a private extension or run via `--extensionDevelopmentPath`.
+A community-maintained marketplace extension may surface later;
+contributions welcome.
+
+### Helix
+
+Add to `~/.config/helix/languages.toml`:
+
+```toml
+[language-server.rigor]
+command = "rigor"
+args = ["lsp"]
+
+[[language]]
+name = "ruby"
+language-servers = ["rigor"]
+```
+
+Helix auto-detects `.rigor.yml` via its project-root walk. If you
+also use Solargraph / ruby-lsp, list them alongside `rigor` —
+Helix runs multiple servers per language. For a legacy bundler-based
+install, use `command = "bundle"` and `args = ["exec", "rigor", "lsp"]`.
+
+### Emacs — Eglot
+
+```elisp
+(require 'eglot)
+(add-to-list 'eglot-server-programs
+             '(ruby-mode . ("rigor" "lsp")))
+;; Or for ruby-ts-mode (Emacs 30+):
+(add-to-list 'eglot-server-programs
+             '(ruby-ts-mode . ("rigor" "lsp")))
+```
+
+`M-x eglot` in a Ruby buffer to attach. For a legacy bundler-based
+install, replace `("rigor" "lsp")` with `("bundle" "exec" "rigor" "lsp")`.
+
+### Emacs — lsp-mode
+
+```elisp
+(with-eval-after-load 'lsp-mode
+  (lsp-register-client
+   (make-lsp-client
+    :new-connection (lsp-stdio-connection '("rigor" "lsp"))
+    :activation-fn (lsp-activate-on "ruby")
+    :server-id 'rigor)))
+```
+
+For a legacy bundler-based install, swap the connection list to
+`'("bundle" "exec" "rigor" "lsp")`.
+
+## Troubleshooting
+
+**The server starts but no diagnostics appear.**
+
+- Confirm your project has a `.rigor.yml` or `.rigor.dist.yml` (or
+  the LSP root walk finds one). The LSP uses
+  `Configuration.discover` — same logic as `rigor check`.
+- Check the LSP log (`--log=/tmp/rigor-lsp.log`) for plugin-load
+  errors or RBS-env build failures.
+- Run `rigor check <path>` from the same project root; if it works
+  there, the LSP should too. If `rigor check` fails, fix that
+  first.
+
+**Completion popup is empty.**
+
+- Completion only fires on a node with a known type. Receivers
+  whose type collapses to `Dynamic[top]` produce no completions.
+  Look at `rigor type-of <file>:<line>:<col>` to see what type the
+  analyzer assigns the receiver.
+- Mid-edit buffer support is best-effort. If parse fails AND the
+  cursor isn't right after `.` / `::`, the v1 LSP returns no
+  completions; deeper recovery is queued (see ROADMAP §
+  "Editor / IDE integration").
+
+**Hover shows `untyped` everywhere.**
+
+- The analyzer hasn't loaded your project's RBS. Verify `.rigor.yml`
+  has the right `signature_paths:` and `libraries:`. Check the
+  LSP log for `RBS::DuplicatedDeclarationError` or similar.
+
+**Concurrent LSP sessions conflict.**
+
+- They shouldn't — the LSP uses a read-only `Cache::Store` so
+  multiple processes against the same project don't race on the
+  on-disk cache. If you see corruption, file a bug with the log.
+
+## Performance expectations
+
+Per LSP v1's design targets (warm session, 5K-file project,
+current laptop):
+
+- Cold start (`initialize` → first publish): < 3s.
+- `didChange` → `publishDiagnostics`: p50 < 250ms, p95 < 500ms.
+- `hover`: p95 < 100ms.
+- `documentSymbol`: p95 < 50ms.
+- Memory steady-state: < 600 MB.
+
+Cold start is dominated by RBS environment build; warm starts
+(`rigor check`-warmed `.rigor/cache`) land sub-1.5s.
+
+## Status + roadmap
+
+LSP v1 + v2 landed in v0.1.6 and ship in the `0.1.x` line. Queued
+follow-ups (`textDocument/signatureHelp`, hash-key completion,
+`textDocument/definition`, incremental `didChange` sync, Ractor
+pool dispatch, codeAction / rename / semanticTokens / inlayHint)
+are demand-driven; see ROADMAP § "Editor / IDE integration" for
+the current queue.
+
+To request a queued feature or report an LSP issue, open a GitHub
+issue with: the editor + version, the Rigor version
+(`rigor version`), the LSP log (`--log=PATH`), and a minimal
+reproduction.