Scrybe

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

---

Introduction

Scrybe reads one or more files, looks for annotations of the form @scrybe(...), and checks that they are consistent. This has immediate applications to e.g. checking that a README is properly updated with the latest version number, links, and examples. See a demo below.

Scrybe is read-only: it does not and never will modify the input file, its job is only to check that the updates have been correctly performed.

Installation

Assuming that you have Python 3 and pip:

$ pip install scrybe-check

will make scrybe available as a command.

Background

Scrybe was originally developed specifically to help me manage the releases of my Typst packages ([1], [2], [3]). 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. During all of that it is very easy to forget one on the steps, so Scrybe implements features to help detect mistakes. These are in theory applicable to other similar processes unrelated to Typst. Scrybe has a current track record of enabling me to release 8 consecutive package updates without inconsistencies in links or version numbers.

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"