monogram-jora

Syntax-highlighting artifacts for the Jora
query language, derived from a single grammar definition with
Monogram.

You write the grammar once in Monogram’s combinator API
(grammar/jora.ts); Monogram derives the TextMate grammar,
a VS Code language configuration, a Monaco Monarch tokenizer, and a tree-sitter
grammar from it.

Status: the grammar covers Jora’s full surface syntax — literals
(numbers, strings, templates, regexps), $-variables and the @/#/$/$$
references, all operators, is assertions, dot/bracket/slice access, maps
.( ) / filters .[ ] / recursive maps .., method calls, functions,
object/array literals with spreads, multi-key sort, and $x: definitions.
It is validated against Jora’s own language test suite: of the 288 valid
queries there, 287 parse (see test/grammar-corpus.test.ts).

Two known, deliberate divergences from Jora’s parser: an identifier whose
\uXXXX escape decodes to a non-identifier character (e.g. \u0020, a space)
is rejected rather than accepted, and a regexp with a duplicate flag
(/x/gg) is accepted syntactically rather than rejected. Neither affects
highlighting of real queries.

Layout

• monogram/ — the Monogram engine, pinned as a git submodule.
  Clone with git clone --recurse-submodules, or run
  git submodule update --init in an existing checkout.
• grammar/jora.ts — the Jora grammar definition (the
  source of truth). It imports Monogram’s API from the submodule.
• grammar/jora.tmLanguage.json, grammar/jora.language-configuration.json,
  grammar/jora.monarch.json, grammar/jora.cst-match.ts,
  grammar/tree-sitter/jora/* — generated artifacts, committed to the repo.

Regenerating

Requires Node 24+ (Monogram runs .ts directly).

pnpm run regen   # node monogram/src/cli.ts grammar/jora.ts

pnpm run build regenerates before building, and CI fails if the committed
artifacts drift from grammar/jora.ts. Edit the grammar, run regen, and
commit the resulting diff.

Usage

The generated files are re-exported from the package:

import { languageConfiguration, monarch, tmLanguage } from 'monogram-jora'

They’re also shipped as raw .json files, for tools that need an actual file
on disk rather than a bundled JS value (e.g. VS Code extensions, or
oniguruma/shiki-style highlighters that load a grammar by path):

import tmLanguage from 'monogram-jora/grammar/jora.tmLanguage.json' with { type: 'json' }
// or: require.resolve('monogram-jora/grammar/jora.tmLanguage.json')

• monogram-jora/grammar/jora.tmLanguage.json
• monogram-jora/grammar/jora.monarch.json
• monogram-jora/grammar/jora.language-configuration.json

Note for Developers

This package uses npm Trusted Publisher, where the release is done on CI to ensure the security of the packages.

To do so, you need to run pnpm publish manually for the very first time to create the package on npm, and then go to https://www.npmjs.com/package/monogram-jora/access to set the connection to your GitHub repo.

Then for the future releases, you can run pnpm run release to do the release and the GitHub Actions will take care of the release process.

Sponsors

License

MIT License © Anthony Fu