canopus 0.4.0 → 0.5.0

data/docs/lsp.md

@@ -21,11 +21,142 @@ An absent or `null` entry auto-detects the language's default executable; it doe
 not disable the server. If no executable is found, Canopus leaves that language
 without a server. Invalid settings keep the previous working connection.
 
+Configure multiple ordered servers with option objects and explicit feature
+routing. The first matching server handles single-result features such as
+formatting and definition; completion, diagnostics, and code actions are merged
+from every matching server:
+
+```json
+{
+  "language_servers": {
+    "ruby": [
+      {"command": ["ruby-lsp"], "features": ["completion", "definition", "hover", "formatting"]},
+      {"command": ["rubocop", "--lsp"], "features": ["diagnostics", "codeAction"]}
+    ]
+  }
+}
+```
+
+Omit `features` to route from negotiated server capabilities. The legacy
+argument array (`"ruby": ["ruby-lsp"]`) remains a single-server command. The
+status bar shows each connection, and `language.restart_server` restarts one
+selected server without disturbing the others.
+
 Changes to the command, environment, or initialization options restart the
 connection and reopen its documents. A configuration-only change sends
 `workspace/didChangeConfiguration` without restarting. Resource-changing server
 requests require confirmation as described in [workspace edits](workspace_edits.md).
 
+Save-time actions are opt-in and run before the file write. Formatting runs
+first, followed by the first enabled action returned for each configured kind:
+
+```json
+{
+  "format_on_save": true,
+  "code_actions_on_save": ["source.organizeImports", "source.fixAll"],
+  "format_on_save_timeout": 2000
+}
+```
+
+The timeout covers the complete sequence. A timeout, stale or invalid edit, or
+server failure is reported without preventing the save; edits to the saved
+document accepted before a later failure remain grouped as one undo step.
+Server edits use the normal version-checked workspace-edit path. Resource
+operations are rejected during an automatic save action. An untitled document
+establishes its URI on the first Save As, so its save-time actions begin with
+the next save.
+
+Published diagnostics are shown as severity-colored wave underlines. The most
+severe message on each line is also shown at line end by default. Configure this
+with `diagnostics.inline`, `diagnostics.inline_max_length`, and the minimum
+`diagnostics.severity` (`error`, `warning`, `information`, or `hint`).
+
+The Problems panel groups validated local-file diagnostics by file and also
+accepts task and test sources through the diagnostics registry. Selecting a
+problem opens its exact source position. `problems.filter` filters the tree by
+free text and optional terms such as `severity:warning` and `source:task`; the
+status bar shows current error and warning totals.
+
+Task and test integrations publish the same validated LSP-shaped records with
+`workspace.diagnostics.publish(:task, uri, diagnostics)` or `:test`. Publishing
+an empty array removes that source's records for the URI.
+
+Inlay hints are fetched for the visible source lines plus 50 lines of context and
+shown inline. Label parts with a server-provided location are clickable. Configure
+type and parameter-name hints, or their display limit, with `inlay_hints.types`,
+`inlay_hints.parameter_names`, and `inlay_hints.max_length`; set
+`inlay_hints.enabled` to `false` to disable requests.
+
+Code lenses are cached for each document version and shown above their source
+line. Unresolved lenses are resolved only as they enter the viewport; click a
+lens to execute its server command. Set `code_lens.enabled` to `false` to
+disable requests and hide cached lenses.
+
+When supported, `textDocument/documentHighlight` automatically marks reads,
+writes, and textual occurrences at each visible editor's caret. Results are
+kept per split and caret, and are discarded when the caret or document changes,
+the tab closes, or the language server is replaced.
+
+`textDocument/documentLink` results are underlined and clickable in each visible
+editor. Links without a target are resolved only when clicked. Canopus opens
+HTTP(S) targets through the platform and local `file` targets in an editor;
+remote file URIs and executable or custom URI schemes are rejected. Cached links
+and pending resolutions are discarded after edits, hidden tabs, document close,
+settings changes, or server replacement.
+
+`editor.fold` prefers cached `textDocument/foldingRange` results and folds the
+smallest range containing the caret's source line. Servers without folding
+support, null or failed responses, and unconfigured languages fall back to
+asynchronous Antares structure analysis; the UI thread never waits for either
+source.
+
+`Alt-Up` expands every selection through its nested
+`textDocument/selectionRange` chain and `Alt-Down` restores the exact previous
+selection. Unsupported, null, failed, or invalid responses fall back to
+asynchronous Antares structure analysis. Move-line shortcuts use
+`Alt-Shift-Up` and `Alt-Shift-Down`.
+
+`F2` asks servers advertising rename preparation to validate the exact document
+version and caret before opening the rename dialog. The prepared range,
+placeholder, or client-side identifier pre-fills the dialog; edits, caret moves,
+hidden tabs, server replacement, and settings reload cancel the snapshot. Servers
+without preparation support, and unconfigured languages, keep the regular rename
+dialog.
+
+Run `language.linked_editing` from the command palette to request
+`textDocument/linkedEditingRange`. Canopus maps the current primary selection's
+relative anchor and caret to every validated, non-overlapping linked range and
+creates multiple selections. The request is cancelled when the selection,
+document, visible tab, settings, or server changes. Continuous linked editing
+is intentionally left to the editor's normal multi-selection behavior. If no
+server is available, or the server does not support the request, returns null,
+fails, or times out, HTML and XML use a bounded fallback for unambiguous matching
+opening and closing tag names. HTML names are ASCII case-insensitive; XML names
+are exact and may contain Unicode. Self-closing and HTML void elements are not
+linked.
+
+Run `language.call_hierarchy` or `language.type_hierarchy` from the command
+palette to prepare a hierarchy at the caret. If the server returns more than
+one root, choose one from the palette. The right-side Hierarchy panel loads
+incoming and outgoing calls, or supertypes and subtypes, only as branches are
+expanded. Selecting an item opens its local file and source range; remote file
+URIs are rejected.
+
+Press Cmd-T on macOS or Ctrl-T elsewhere, or run
+`language.workspace_symbols`, and enter a query. Canopus requests
+`workspace/symbol` from every active server routed to `workspaceSymbol` under
+one ten-second deadline, keeps configuration order while removing duplicate
+results, and uses Spica to refine the returned locations. Selecting a result
+opens its local file and range. If no routed server is running, or every routed
+provider fails, a background Alkaid content search supplies bounded local-file
+matches using the project's ignore rules. Queries are limited to 256 bytes and
+results to 10,000 entries.
+
+Sticky scroll prefers `textDocument/documentSymbol` when the server advertises
+it and uses cached Antares structure regions otherwise. Requests and normalized
+symbol trees are tied to the current buffer version and discarded after edits,
+document close, or server retirement; painting never waits for either source.
+
 Editor positions use UTF-8 byte offsets internally and are converted to LSP
 UTF-16 positions. Servers selecting another position encoding are rejected.
 Messages are limited to 32 MiB, crashes fail pending requests, and a connection

data/docs/performance.md

@@ -29,8 +29,17 @@ private directory with appropriate ACLs.
 
 Developers can produce current, reproducible measurements with:
 
+```sh
+BUDGET=1 ruby bench/require.rb
+```
+
+The require-only budget is 300 ms in a fresh Ruby process. It covers the
+library load, not window creation or the first rendered frame; those remain
+measured by the startup benchmark below.
+
 ```sh
 ruby --yjit bench/frame_profile.rb --frames 120 --output /tmp/frames.json
+ruby --yjit bench/minimap.rb
 ruby bench/startup.rb --runs 3
 ruby --yjit tools/native_check.rb --idle /tmp/native-check.png
 ```
@@ -38,3 +47,12 @@ ruby --yjit tools/native_check.rb --idle /tmp/native-check.png
 Compare results only when the platform, renderer, viewport, Ruby/JIT mode,
 warmup, and diagnostic options match. Headless software rendering is a regression
 check, not a hardware-GPU performance result.
+
+Bracket colors and indentation guides are requested and cached by visible source
+rows. Structural analysis stays in the bounded language worker; files on the
+large read-only path skip these decorations instead of scanning on the UI thread.
+
+`bench/minimap.rb` renders a 10,000-line file through the real headless renderer.
+It asserts the per-frame cold-generation bound, texture reuse while scrolling,
+one-row regeneration after an edit, and warm p95 against a same-run minimap-off
+baseline. Compare raw timings only on the same Ruby, font, scale factor, and renderer.

data/docs/providers.md

@@ -0,0 +1,36 @@
+# Completion providers
+
+`workspace.providers` combines completion sources without coupling the editor to
+a particular language server. Canopus registers LSP completion itself; plugins
+and embedders can add sources with `register_completion`:
+
+```ruby
+workspace.providers.register_completion(:project_terms, priority: 20) do |buffer, offset, context|
+  [Canopus::Provider::Completion.new(
+    "ProjectName", "ProjectName", :constant, "Project term", nil,
+    nil, nil, [], :project_terms
+  )]
+end
+```
+
+The block runs away from the UI thread and receives the current buffer, UTF-8
+byte offset, and a context hash whose `:query` is the word prefix. It returns an
+array of `Completion` records, or an awaitable with `await(timeout:)`. Results
+are fuzzy-ranked with Spica; higher source priority is the stable tie-break. Duplicate
+label/insertion pairs keep the higher-ranked source. Invalid, oversized, or
+failed sources are omitted without hiding results from healthy sources. All
+sources share a ten-second completion deadline, rather than multiplying that
+deadline by the number of registered providers.
+
+Use source `:snippet` (or kind `:snippet`) when `insert_text` contains LSP/
+TextMate snippet syntax. Additional edits are `[Range, String]` pairs and are
+preflighted with the main insertion before editing.
+
+Ghost-text integrations can register a block with
+`register_inline_completion(source)`. `inline_completion(buffer, offset)` uses
+the first registered provider that returns a valid non-nil string. Canopus only
+provides this boundary today; AI, word, and path providers belong to their
+respective later features or plugins.
+
+At most 64 providers of each kind, 10,000 combined completion records, 1,000
+additional edits per record, and 64 KiB per string are accepted.

data/docs/release-log.md

@@ -2,4 +2,16 @@
 
 | Date | Repository | Version | Canopus follow-up | Reason |
 | --- | --- | --- | --- | --- |
+| 2026-09-18 | kochab | 0.2.0 | 2026-09-18 | Settings schema metadata and safe layer merge API |
+| 2026-09-18 | tarazed | 0.2.4 | 2026-09-18 | Explicit command-history clearing for terminal consumers |
+| 2026-09-18 | tarazed | 0.2.3 | 2026-09-18 | Shell executable detection for argument-bearing and Windows commands |
+| 2026-09-17 | thuban | 0.6.0 | 2026-09-17 | Transactional merge-conflict snapshots and resolution |
+| 2026-09-17 | thuban | 0.5.0 | 2026-09-17 | Atomic partial staging and managed Git transfers |
+| 2026-09-17 | thuban | 0.4.1 | 2026-09-17 | Lazy remote provider loading for headless startup |
+| 2026-09-17 | tarazed | 0.2.2 | 2026-09-17 | Drain final Windows ConPTY output after process exit |
+| 2026-09-16 | megrez | 0.1.1 | 2026-09-16 | Debug Adapter Protocol session lifecycle |
+| 2026-09-16 | antares | 0.2.1 | 2026-09-16 | CRLF-safe selection range columns |
+| 2026-09-16 | denebola | 0.2.1 | 2026-09-16 | Deterministic same-offset edit and anchor mapping |
+| 2026-09-15 | thuban | 0.4.0 | 2026-09-17 | Git write, commit, history, stash, and remote APIs |
+| 2026-09-15 | porrima | 0.2.0 | 2026-09-17 | Structured three-way merge conflict resolution |
 | 2026-09-14 | thuban | 0.2.0 | 2026-09-14 | Public `IgnoreMatcher` API |

data/docs/tasks.md

@@ -0,0 +1,64 @@
+# Tasks
+
+Project tasks live in `.canopus/tasks.jsonc`. Open **Run Task** from the command
+palette or press Cmd-Shift-B on macOS / Ctrl-Shift-B on Linux and Windows.
+
+```jsonc
+{
+  "problem_matchers": {
+    "ruby": {
+      "owner": "ruby",
+      "file_location": ["relative", "${workspaceFolder}"],
+      "pattern": {
+        "regexp": "^(.+):(\\d+):(?:(\\d+):)?\\s*(warning|error):\\s*(.+)$",
+        "file": 1, "line": 2, "column": 3, "severity": 4, "message": 5,
+      },
+    },
+  },
+  "tasks": [
+    {
+      "label": "rake test",
+      "command": ["bundle", "exec", "rake", "test"],
+      "cwd": "${workspaceFolder}",
+      "problem_matcher": "ruby",
+      "presentation": { "panel": "output", "reveal": "always" },
+    },
+  ],
+}
+```
+
+Commands are argument arrays and are passed directly to `Tarazed::PTY`; Canopus
+does not interpolate a shell command string. Each task has one Output tab.
+Running the same label again replaces its previous process and tab. Select a
+tab and run **Stop Task** (Ctrl-C while its output is focused) to stop only that
+task. Output supports terminal colors and interactive input.
+
+The available variables are `${workspaceFolder}`, `${file}`,
+`${lineNumber}`, `${selectedText}`, and `${env:NAME}`. Missing variables are
+errors. `cwd` and file variables must stay inside the canonical workspace;
+symlink escapes are rejected.
+
+`presentation.panel` is currently `output`. `reveal` accepts `always` (show at
+start), `silent` (show only after a failing exit), or `never`.
+
+A problem matcher can use one `pattern` object or an array of up to eight
+patterns for a multi-line diagnostic. Captures are 1-based and may specify
+`file`, `line`, `column`, `end_line`, `end_column`, `severity`, and `message`;
+`file`, `line`, and `message` are required across the sequence. Matching files
+must already exist inside the canonical workspace. Matches are published with
+source `task`, so they appear in editor diagnostics and the Problems panel.
+
+Long-running tasks can add `background` with `begins_pattern`, `ends_pattern`,
+and optional `active_on_start`. A begin match starts a fresh cycle and clears
+the previous cycle's diagnostics; an end match pauses matching until the next
+begin marker. `active_on_start` defaults to `false`.
+
+Task files and expansion are limited to 1 MiB, 128 definitions, and 32 retained
+Output tabs. Each PTY uses the configured terminal scrollback and queue limits,
+and all output parsing remains frame-budgeted. Matcher lines and unfinished
+input are limited to 64 KiB, each matcher retains at most 1,000 diagnostics,
+and regular expressions use a timeout. A matcher that times out is disabled for
+the rest of that task run while its already-published diagnostics are retained.
+On Ruby 3.1, one timeout on a complete line is deferred to the next frame before
+disabling, which avoids dropping a matcher after a transient scheduler delay;
+an unterminated final line is disabled on its first timeout.

data/docs/testing.md

@@ -0,0 +1,49 @@
+# Test explorer
+
+Open the **Tests** panel with `panel.test`. Canopus discovers tests in the
+background the first time the panel opens. Run `test.refresh` after changing
+test declarations; filesystem changes also refresh an explorer that has
+already been opened.
+
+Discovery uses Alkaid's workspace walker and the same Git and project ignore
+rules as project search. Ruby files in `test/`, ending in `_test.rb`, or named
+`test_*.rb` use the Minitest adapter; files in `spec/` or ending in `_spec.rb`
+use the RSpec adapter. An explicit `_test.rb` or `_spec.rb` suffix takes
+precedence over a containing directory name.
+Prism parses each candidate and adapters inspect its AST; comments, strings,
+and syntactically invalid files are not treated as tests.
+
+The Minitest adapter recognizes `test_` methods in classes, `test` blocks, and
+Minitest spec-style `describe` / `context` groups with `it` or `specify`
+examples. The RSpec adapter recognizes nested `describe`, `context`, and
+`feature` groups plus their focused and skipped aliases, and `it`, `specify`,
+`example`, and `scenario` examples. Test nodes retain only their framework,
+workspace-relative path, static name, group path, source position, and bounded
+framework selector.
+Selecting a test opens its current source line after rechecking that the file
+is still a regular file inside the canonical workspace. Each discovered test
+also has a gutter button. The marker changes from run to running, passed,
+failed, or skipped; clicking it starts that one static test through the shared
+Task Output runner. Multiple declarations on one line run together.
+
+Minitest runs use an exact suite/method filter. RSpec combines the discovered
+source line with an exact full-description filter. Commands are fixed argument
+arrays rather than shell strings. A regular workspace `Gemfile` is run with
+`bundle exec`; inherited editor bundle state is
+removed before the child starts. Output remains available in the bounded
+Output panel and stopping or closing its tab cancels the run.
+
+Failed runs publish a `test` diagnostic and retain a 256 KiB tail of output to
+locate the test frame. Selecting a failed test, or its Problems entry, opens
+that failure line. If no safe frame is present, Canopus falls back to the
+discovered declaration.
+
+Discovery does not follow symlinks. It scans at most 50,000 workspace files,
+2,000 candidate test files, and 10,000 tests, with a maximum traversal depth of
+64. Candidate files are limited to 1 MiB, names to 4 KiB, and adapter AST walks
+to 100,000 nodes per file. Invalid UTF-8, NUL-containing, inaccessible,
+oversized, and escaped paths are skipped. Refresh cancels stale work and keeps
+at most one discovery worker active; closing the workspace cancels and joins
+that worker.
+
+Generating a debug launch remains a separate feature.

data/docs/vim.md

@@ -22,3 +22,6 @@ Vimscript, arbitrary shell commands, and user mappings are not interpreted.
 Clipboard registers `+` and `*` are in-memory registers rather than OS clipboard
 integrations. Counts are capped at 10,000; macro playback allows 10 nested calls
 and 10,000 keys.
+
+Insert and Replace modes follow Vim's literal insertion behavior and do not
+apply the editor's `auto_pairs` setting.

data/exe/canopus

@@ -13,7 +13,10 @@ unless RUBY_PLATFORM.match?(/mswin|mingw/) || RbConfig::CONFIG["YJIT_SUPPORT"] !
   exec(RbConfig.ruby, *flags, __FILE__, *ARGV)
 end
 ENV.delete("CANOPUS_YJIT_REEXEC")
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+canopus_root = File.expand_path("..", __dir__)
+Gem::Specification.find_all_by_name("canopus")
+  .find { |specification| File.expand_path(specification.full_gem_path) == canopus_root }&.activate
+$LOAD_PATH.unshift(File.join(canopus_root, "lib"))
 require "canopus"
 require "canopus/cli"
 exit Canopus::CLI.main(ARGV)