mirror of
https://github.com/Myriad-Dreamin/tinymist.git
synced 2025-07-19 10:45:02 +00:00
122 lines
3.5 KiB
Markdown
122 lines
3.5 KiB
Markdown
|
|
# `tinymist-query` analyzer library
|
|
|
|
## Documentation
|
|
|
|
The documentation can be generated locally by running:
|
|
|
|
```bash
|
|
yarn docs:rs --open # You can also copy-run the command if you don't have a yarn.
|
|
```
|
|
|
|
## Name Convention
|
|
|
|
The names of analyzers are all have suffix `Worker`. To get a full list of analyzers, please search "struct: tinymist_query worker" in Cargo Docs.
|
|
|
|
```rust
|
|
tinymist_query::analysis::bib::BibWorker
|
|
tinymist_query::syntax::expr::ExprWorker
|
|
tinymist_query::syntax::index::IndexWorker
|
|
tinymist_query::analysis::link_expr::LinkStrWorker
|
|
tinymist_query::analysis::OnEnterWorker
|
|
tinymist_query::analysis::color_expr::ColorExprWorker
|
|
tinymist_query::analysis::InlayHintWorker
|
|
...
|
|
```
|
|
|
|
## Testing analyzers
|
|
|
|
To run analyzer tests for tinymist:
|
|
|
|
```bash
|
|
cargo insta test -p tinymist-query --accept
|
|
```
|
|
|
|
> [!Tip]
|
|
> Check [Cargo Insta](https://insta.rs/docs/cli/) to learn and install the `insta` command.
|
|
|
|
To add a test, for example for the [`textDocument/completion`](/crates/tinymist-query/src/completion.rs) function, please follow the steps:
|
|
|
|
1. Check the first argument of `snapshot_testing` function calls in the source file. We know that it uses fixtures from [`fixtures/completion/`](/crates/tinymist-query/src/fixtures/completion/).
|
|
2. Add a typst file in the [`fixtures/completion/`](/crates/tinymist-query/src/fixtures/completion/) directory.
|
|
3. Rerun the `cargo insta` command to update snapshot.
|
|
|
|
At the step 2, we have special syntax to write the typst file.
|
|
|
|
1. Cursor range to request completion: `/* range -1..0 */` or `/* range after 1..2 */` that relative to the comment node.
|
|
|
|
Example:
|
|
|
|
```typ
|
|
$: /* range -1..0 */$
|
|
```
|
|
|
|
It test completion when the cursor is after a colon in the equation context.
|
|
2. Completion result filter: `/// contains: comma separated list`
|
|
|
|
Example:
|
|
|
|
```typ
|
|
/// contains: body, fill
|
|
#set text(/* range 0..1 */ )
|
|
```
|
|
|
|
Description: The snapshot result **must** contains `fill` and **must not** contains `body`, so we add both of them to the `contains` list.
|
|
|
|
3. Fixture of some multiple-files project: `/// path: file name`
|
|
|
|
Example:
|
|
|
|
```typ
|
|
/// path: base.typ
|
|
#let table-prefix() = 1;
|
|
|
|
-----
|
|
/// contains: base,table,table-prefix
|
|
#import "base.typ": table/* range -1..1 */
|
|
```
|
|
|
|
Description: the files are separated by `-----`, and the first file is named `base.typ`. The snapshot result **must not** contain `base`, `table`, and **must** contain `table-prefix`, so we add them to the `contains` list.
|
|
|
|
4. Whether to compile the file: `/// compile: true`
|
|
|
|
Example:
|
|
|
|
```typ
|
|
/// compile: true
|
|
|
|
#let test1(body) = figure(body)
|
|
#test1([Test1]) <fig:test1>
|
|
/* position after */ @fig:test1
|
|
```
|
|
|
|
Description: The file will be compiled before the test, to get the content reference by `typst::trace` for completion.
|
|
|
|
4. Compile which the file: `/// compile: base.typ`
|
|
|
|
Example:
|
|
|
|
```typ
|
|
/// compile: true
|
|
|
|
/// path: base.typ
|
|
#set heading(numbering: "1.1")
|
|
|
|
= H <t>
|
|
|
|
== H2 <test>
|
|
|
|
aba aba
|
|
|
|
-----
|
|
/// contains: test
|
|
/// compile: base.typ
|
|
|
|
#<t /* range -2..-1 */
|
|
```
|
|
|
|
Description: Another file named `base.typ` will be compiled before the test, since a half-editing file causes the completion to fail.
|
|
|
|
## Analyzer playground
|
|
|
|
A special fixture folder [`playground`](/crates/tinymist-query/src/fixtures/playground/) is provided for testing analyzers. You can change argument of the `snapshot_testing` to `"playground"` or `""` to use the playground fixtures.
|