tinymist/docs/dev-guide/tinymist-query.md

tinymist-query analyzer library

Documentation

The documentation can be generated locally by running:

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.

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:

cargo insta test -p tinymist-query --accept

Tip

Check Cargo Insta to learn and install the insta command.

To add a test, for example for the textDocument/completion 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/.
2. Add a typst file in the 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:

   $: /* 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:

   /// 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:

   /// 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:

   /// 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.

5. Compile which the file: /// compile: base.typ

   Example:

   /// 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 is provided for testing analyzers. You can change argument of the snapshot_testing to "playground" or "" to use the playground fixtures.