scrybe-check 0.1.0

Add inline annotations to check that files are self-consistent

Scrybe

A script to help keep your README up-to-date.

---

Scrybe is a Python script originally developed specifically to help me manage the releases of my Typst packages ([1], [2], [3]). The features it implements make it in theory applicable to other similar processes unrelated to Typst. The process of releasing a new package involves a lot of

• checking that README examples are up-to-date and compile,
• updating links in the README to point to static snapshots,
• changing version numbers in typst.toml, imports, etc.

scrybe can't do that automatically, but it can make the process less error-prone and less stressful by validating that it has been done correctly.

scrybe works by scanning the input file(s) to look for annotations (usually written in comments).

Examples

Validating links and versions

Let's say you have a link in your README, and it looks like this:

See the [documentation](docs/main.pdf).

Upon release of version 0.1.0, you want the link to now point to the snapshot for the appropriate version.

We can add the following annotation:

<!-- @scrybe(if publish; grep https; grep {{version}}) -->
See the [documentation](docs/main.pdf).

i.e. this means: if the execution mode is publish, the line that follows must contain the text "https" and it must contain the current version number.

Then invoke the command

scrybe README.md --publish --version=0.1.0

If you forgot to update the link you will get the following output:

Flags:
  publish	
  version	0.1.0

Reading README.md
  Checking command group at line 37
    Guarded by publish (sat)		 proceed
    Searching for pattern: https
      ERROR: No match!
    Searching for pattern: 0.1.0
      ERROR: No match!

Update the link and now the annotation will pass

<!-- @scrybe(if publish; grep https; grep {{version}}) -->
See the [documentation](https://github.com/user/repo/tree/v0.1.0/docs.pdf).

Flags:
  publish	
  version	0.1.0

Reading README.md
  Checking command group at line 63
    Guarded by publish (sat)		 proceed
    Searching for pattern: https		 ok
    Searching for pattern: 0.1.0		 ok

Ensuring that examples compile

Consider now that your README contains the following example:

```typ
#import "@local/mypkg:0.1.0"

#mypkg.magic()
```

On release we want to ensure that

• it compiles
• it imports the published package
• it uses the latest version

Additionally outside of a release we want the import to point to @local as that is where the dev version of the package would be copied.

Here are annotations that will check exactly that:

<!-- @scrybe(if publish; jump import; grep preview; grep {{version}}) -->
<!-- @scrybe(not publish; jump import; grep local; grep {{version}}) -->
<!-- @scrybe(jump import; until ```; diff examples/demo.typ) -->
```typ
#import "@local/mypkg:0.1.0"

#mypkg.magic()
```

The output is one of the following:

$ scrybe README.md --version=0.1.0

Flags:
  version	0.1.0

Reading README.md
  Checking command group at line 97
    Guarded by publish (unsat)		 skip

  Checking command group at line 98
    Guarded by not publish (unsat)		 proceed
    Start cursor forward until import		 selected: 101-101
    Searching for pattern: local		 ok
    Searching for pattern: 0.1.0		 ok

  Checking command group at line 99
    Start cursor forward until import		 selected: 101-101
    End cursor forward until ```		 selected: 101-103
    Diff to examples/demo.typ
      < #import "/src/lib.typ" as mypkg
      > #import "@local/mypkg:0.1.0

$ scrybe README.md --publish --version=0.1.0

Flags:
  publish	
  version	0.1.0

Reading README.md
  Checking command group at line 101
    Guarded by publish (sat)		 proceed
    Start cursor forward until import		 selected: 105-105
    Searching for pattern: preview
      ERROR: No match!
    Searching for pattern: 0.1.0		 ok

  Checking command group at line 102
    Guarded by not publish (sat)		 skip

  Checking command group at line 103
    Start cursor forward until import		 selected: 105-105
    End cursor forward until ```		 selected: 105-107
    Diff to examples/demo.typ
      < #import "/src/lib.typ" as mypkg
      > #import "@local/mypkg:0.1.0"

In other words, in non-publish mode all looks good, and before the package can be published the @local needs to be changed to @preview.

Final tip

I recommend adding a version check to your typst.toml, which is very easy:

[package]
name = "mypkg"
# @scrybe(not version; panic Please specify a version number)
# @scrybe(grep {{version}})
version = "0.1.0"
entrypoint = "src/lib.typ"