feat(plugins): add background document-indexer API (#1021)

Plugin API 1.2 gains an optional document-indexer export (plugin-indexing world). A plugin returns per document the keys it defines and refers to, aliases between key prefixes and gutter markers; the host indexes a trusted project in cancellable background batches, keeps the project-wide graph, and answers Go to Declaration / Ctrl-click and multi-target gutter markers from memory without calling the plugin again. Edits and file changes invalidate the affected entries; reload, disable or a failing runtime drops the plugin's graph.

The interface is limited to cross-file associations: icons chosen by file content and embedded-language regions are separate concerns for later interfaces. The plugin navigation choosers' titles are translated.

Co-authored-by: qjlqyf <[email protected]>

docs/plugins/indexing.md

@@ -0,0 +1,54 @@
+# Background document indexers (API 1.2)
+
+Use `contributes.providers` for interactive definition, completion and line-marker
+requests about one document. A document indexer is for cross-file associations
+that need the whole project: it publishes keys once per document, and the host
+resolves clicks and gutter markers from memory, without scanning files or
+calling the plugin.
+
+```toml
+[[contributes.documentIndexers]]
+extensions = ["java", "xml"]
+```
+
+Implement `openidea_plugin::indexing::DocumentIndexer` and register with
+`register_plugin!(Plugin, indexing)` (or `register_plugin!(Plugin, providers, indexing)`
+when the plugin also has interactive providers). Components built with other
+tools target the `plugin-indexing` world. Indexers require `project.read` and run
+only in trusted projects.
+
+`index` gets the document's text (the editor's while it is open) and the symbols
+the host's syntax support found in it, and returns:
+
+- `definitions`: where keys are declared;
+- `references`: ranges that go to the definitions of their key on Go to
+  Declaration and Ctrl/⌘-click. Elsewhere the language server answers as usual;
+- `aliases`: a `prefix#` whose keys also resolve under `target#`, for inherited
+  members. Chains are followed with bounded depth and candidates;
+- `markers`: gutter icons that go to the definitions of their key.
+
+Keys are the plugin's own strings and ranges are UTF-16. When a key has
+definitions in the same detected module, other modules' definitions are left
+out. Several targets open a chooser.
+
+Initial discovery reuses the host's project index. The editor schedules
+cancellable batches of at most 16 files; edits and file changes invalidate the
+affected entries before they are indexed again. Reloading, disabling or a
+failing runtime drops the plugin's graph, and nothing is answered from a
+document version older than the editor's.
+
+Limits: 2 MiB per document, 20,000 files per graph, 4,096 definitions and
+references and 4,096 markers per document, 256 aliases, 200,000 entries per
+graph, 16 project/window graphs and 256 candidates per lookup. A document over
+a limit is not indexed; editing is never blocked.
+
+## Minimal fixture
+
+`crates/ide-plugin/tests/fixtures/indexer` uses a tiny line-oriented `.idx`
+language to exercise definitions, references, aliases, markers and host syntax
+symbols without framework-specific parsing. Run
+`cargo test -p ide-host --test plugin_indexing` for the real-component contract
+checks.
+
+Framework plugins (MyBatis mappers, Rails routes) belong in their authors'
+repositories and are listed through the registry; see `plugins/README.md`.