recipe-tmlanguage 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaj Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# recipe-tmlanguage
+
+[![NPM](https://img.shields.io/npm/v/recipe-tmlanguage?logo=npm&labelColor=CB3837&color=black)][npm]
+[![JSR](https://img.shields.io/jsr/v/@kjanat/recipe-tmlanguage?logoColor=083344&logo=jsr&logoSize=auto&label=&labelColor=f7df1e&color=black)][jsr]
+
+TextMate grammar for the [recipe] pharmacological notation language,
+**generated** from the same JavaScript vocabulary modules that drive
+`tree-sitter-recipe`'s parser.
+
+Ships as `dist/recipe.tmLanguage.json` for consumption by Shiki, VS Code,
+Sublime Text, Atom, `vscode-textmate`, and anything else that speaks
+TextMate.
+
+## Why generate, not author
+
+The parser's vocabulary (`FREQUENCY`, `TIMING`, `ROUTE`, …, `UNITS`) lives in
+plain `readonly string[]` modules under
+`tree-sitter-recipe/grammar/`. Authoring a parallel TextMate grammar by hand
+would mean copying those lists into regex alternations and re-copying them
+every time the parser is touched. Drift guaranteed.
+
+Instead, `src/grammar.ts` imports those exact modules through
+`tree-sitter-recipe`'s package `exports` map, escapes metachars, sorts
+alternatives longest-first (TextMate is first-match, not longest-match like
+tree-sitter), and emits a ready-to-ship JSON grammar. One source of truth,
+no sync burden.
+
+## Scope map
+
+Captures from `tree-sitter-recipe/queries/highlights.scm` are mapped to
+**standard** TextMate scopes (`keyword.control.…`, `support.function.…`,
+`invalid.illegal.…`, …) with a trailing `.recipe` namespace. Every mainstream
+theme already paints these — no custom theme needs to be shipped with the
+grammar.
+
+| highlights.scm capture   | TextMate scope                                         |
+| ------------------------ | ------------------------------------------------------ |
+| `@keyword.directive`     | `keyword.control.directive.{rx,dispense,signa}.recipe` |
+| `@keyword.repeat`        | `keyword.other.frequency.recipe`                       |
+| `@keyword` (timing)      | `keyword.other.timing.recipe`                          |
+| `@function.macro`        | `support.function.route.recipe`                        |
+| `@attribute`             | `entity.other.attribute-name.recipe`                   |
+| `@keyword.error`         | `invalid.illegal.warning.recipe`                       |
+| `@type` (form)           | `storage.type.form.recipe`                             |
+| `@keyword.operator`      | `keyword.operator.{compounding,fill,dtd}.recipe`       |
+| `@keyword.conditional`   | `keyword.control.conditional.recipe`                   |
+| `@number`                | `constant.numeric.recipe`                              |
+| `@type.builtin` (unit)   | `support.type.unit.recipe`                             |
+| `@variable` (ingredient) | `variable.other.ingredient.recipe`                     |
+| `@string` (signa)        | `string.unquoted.signa.recipe`                         |
+| `@comment`               | `comment.{line.number-sign,block}.recipe`              |
+| `@comment.documentation` | `comment.{line,block}.documentation.recipe`            |
+| `@punctuation.delimiter` | `punctuation.separator.recipe`                         |
+
+## Layout
+
+```text
+recipe-tmlanguage/
+├── cli.ts              # DreamCLI entry — `recipe-tmlang generate|verify`
+├── src/
+│   ├── grammar.ts      # pure: vocab → TextMate grammar object
+│   └── verifier.ts     # pure: tokenize fixtures, check scope assertions
+└── dist/
+    └── recipe.tmLanguage.json
+```
+
+## Setup
+
+`tree-sitter-recipe` is pulled in via Bun's link mechanism. Run once in the
+sibling repo, then link here:
+
+```sh
+cd ../tree-sitter-recipe && bun link
+cd ../recipe-tmlanguage && bun link tree-sitter-recipe && bun install
+```
+
+## CLI
+
+Powered by [DreamCLI][dreamcli] — no hand-rolled argparse.
+
+```sh
+bun cli.ts --help
+```
+
+### `generate`
+
+```sh
+bun cli.ts generate                       # → dist/recipe.tmLanguage.json
+bun cli.ts generate --out foo.json        # custom path
+bun cli.ts generate --indent 2 --quiet    # 2-space indent, silent
+bun cli.ts generate --json                # machine-readable result on stdout
+```
+
+### `verify`
+
+Tokenizes every fixture in `tree-sitter-recipe/test/highlight/` with
+`vscode-textmate` + `vscode-oniguruma` (the same engine Shiki wraps) and
+asserts the scope at each caret marker matches the tree-sitter capture.
+Fixtures and the Oniguruma WASM are located via package `exports` — no
+relative paths to maintain.
+
+```sh
+bun cli.ts verify
+bun cli.ts verify --json                  # { pass, total, failures[] }
+bun cli.ts verify --max-failures 0        # print every failure
+```
+
+Current status: **148 / 149** fixture assertions pass. The single failing
+assertion (`expanded.recipe:22:23`) points one column past the end of a
+23-character source line — a fixture off-by-one, not a grammar defect.
+
+### Drop into Shiki
+
+```ts
+import grammar from "recipe-tmlanguage/dist/recipe.tmLanguage.json";
+import { createHighlighter } from "shiki";
+
+const shiki = await createHighlighter({
+	themes: ["github-dark"],
+	langs: [grammar],
+});
+
+const html = shiki.codeToHtml(source, {
+	lang: "recipe",
+	theme: "github-dark",
+});
+```
+
+The scope names are standard TextMate, so any Shiki theme paints recipe
+blocks immediately.
+
+## License
+
+[MIT][License] © Kaj Kowalski
+
+[License]: LICENSE
+[dreamcli]: https://npm.im/@kjanat/dreamcli
+[jsr]: https://jsr.io/@kjanat/recipe-tmlanguage
+[npm]: https://npm.im/recipe-tmlanguage
+[recipe]: https://github.com/kjanat/tree-sitter-recipe
+
+<!-- markdownlint-disable-file no-hard-tabs -->

package/bin/recipe-tmlang.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * recipe-tmlang — TextMate grammar generator & verifier for recipe-tmlanguage.
+ *
+ * Subcommands
+ * - generate:   Build dist/recipe.tmLanguage.json from the tree-sitter-recipe vocab.
+ * - verify:     Tokenize tree-sitter-recipe's highlight fixtures and assert scopes.
+ *
+ * Zero manual argparse — argument parsing, help, and completions all come from
+ * {@link https://github.com/kjanat/dreamcli | DreamCLI}. `--json` is a DreamCLI built-in;
+ * we branch on {@linkcode Out.jsonMode}.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { cwd, exit } from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { cli, command, flag } from "dreamcli";
+import type { Out } from "dreamcli";
+
+import { buildGrammar, serializeGrammar } from "#grammar";
+import { verify } from "#verifier";
+
+import pkg from "#pkg" with { type: "json" };
+
+const { homepage, repository, version } = pkg;
+const DEFAULT_OUT = `${resolve(import.meta.dirname, "..")}/recipe.tmLanguage.json`;
+
+const TS_RX_DIR = resolve(dirname(fileURLToPath(import.meta.resolve("tree-sitter-recipe/package.json"))));
+const DEFAULT_FIXTURES_DIR = resolve(TS_RX_DIR, "test/highlight");
+const DEFAULT_ONIG_WASM = fileURLToPath(import.meta.resolve("vscode-oniguruma/release/onig.wasm"));
+
+const indentOf = (raw: string): "tab" | number => (raw === "tab" ? "tab" : Number(raw));
+
+const generate = command("generate")
+	.description("Build the TextMate grammar from the tree-sitter-recipe vocabulary")
+	.flag("out", flag.string().alias("o").default(DEFAULT_OUT).describe("Output JSON path"))
+	.flag("indent", flag.enum(["tab", "2", "4"]).default("tab").describe("JSON indent"))
+	.flag("quiet", flag.boolean().alias("q").default(false).describe("Suppress stats on success"))
+	.action(({ flags, out }) => {
+		const { grammar, stats } = buildGrammar();
+		const serialized = serializeGrammar(grammar, indentOf(flags.indent));
+		const outAbs = resolve(cwd(), flags.out);
+		mkdirSync(dirname(outAbs), { recursive: true });
+		writeFileSync(outAbs, serialized);
+		if (out.jsonMode) {
+			out.json({ ok: true, outPath: outAbs, bytes: serialized.length, stats });
+			return;
+		}
+		if (flags.quiet) return;
+
+		out.log(`wrote ${outAbs}`);
+		out.log(`  ${stats.topLevelPatterns} top-level patterns · ${serialized.length} bytes`);
+		const v = stats.vocab;
+		out.log(
+			`  vocab: ${v.frequency} frequency · ${v.timing.single}+${v.timing.multi} timing · ${v.route.single}+${v.route.multi} route · ${v.dispensing.single}+${v.dispensing.multi} dispensing · ${v.forms.single}+${v.forms.multi} forms · ${v.compounding.single}+${v.compounding.multi} compounding · ${v.conditional.single}+${v.conditional.multi} conditional · ${v.warning} warning · ${v.units} units`,
+		);
+	});
+
+const verifyCmd = command("verify")
+	.description("Tokenize tree-sitter-recipe highlight fixtures and assert scope matches")
+	.flag("grammar", flag.string().alias("g").default(DEFAULT_OUT).describe("Path to .tmLanguage.json"))
+	.flag("fixtures", flag.string().alias("f").default(DEFAULT_FIXTURES_DIR).describe("Directory of .recipe fixtures"))
+	.flag("onig-wasm", flag.string().default(DEFAULT_ONIG_WASM).describe("Path to oniguruma WASM"))
+	.flag("max-failures", flag.number().default(40).describe("Max failures to print (0 = all)"))
+	.action(async ({ flags, out }) => {
+		const result = await verify({
+			grammarPath: resolve(cwd(), flags.grammar),
+			fixturesDir: resolve(cwd(), flags.fixtures),
+			onigWasmPath: resolve(cwd(), flags["onig-wasm"]),
+		});
+		const failuresLen = result.failures.length;
+
+		if (out.jsonMode) {
+			out.json(result);
+			if (failuresLen > 0) {
+				out.setExitCode(1);
+				exit();
+			}
+			return;
+		}
+
+		out.log(`${result.pass} / ${result.total} assertions pass`);
+		if (failuresLen === 0) return;
+
+		out.log("");
+		out.log("── failures ──");
+		const limit = flags["max-failures"] === 0 ? failuresLen : flags["max-failures"];
+		for (const f of result.failures.slice(0, limit)) {
+			const gotStr = f.got
+				? f.got.filter((s) => s !== "source.recipe").join(" · ") || "(root only)"
+				: "(no token)";
+			out.log(`  ${f.fixture}:${f.line}:${f.col}  expected ${f.capture}  got [${gotStr}]`);
+		}
+		if (failuresLen > limit) {
+			out.log(`  … +${failuresLen - limit} more`);
+		}
+		out.setExitCode(1);
+	});
+
+export const app = cli("recipe-tmlang").packageJson({ repository, homepage, version }).links()
+	.description("TextMate grammar generator & verifier for the recipe DSL")
+	.command(generate)
+	.command(verifyCmd)
+	.completions();
+
+if (import.meta.main) app.run();

package/package.json

@@ -0,0 +1,82 @@
+{
+	"name": "recipe-tmlanguage",
+	"version": "0.3.0",
+	"description": "TextMate grammar for the recipe (.recipe) pharmacological notation language.",
+	"keywords": [
+		"dreamcli",
+		"recipe",
+		"textmate",
+		"grammar"
+	],
+	"homepage": "https://github.com/kjanat/recipe-tmlanguage#recipe-tmlanguage",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kjanat/recipe-tmlanguage.git"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "Kaj Kowalski",
+		"email": "info@kajkowalski.nl",
+		"url": "https://github.com/kjanat"
+	},
+	"type": "module",
+	"imports": {
+		"#pkg": "./package.json",
+		"#grammar": "./src/grammar.ts",
+		"#verifier": "./src/verifier.ts"
+	},
+	"exports": {
+		".": "./recipe.tmLanguage.json",
+		"./dist/*": "./dist/*",
+		"./package.json": "./package.json"
+	},
+	"main": "./recipe.tmLanguage.json",
+	"module": "./recipe.tmLanguage.json",
+	"bin": {
+		"recipe-tmlang": "bin/recipe-tmlang.ts"
+	},
+	"directories": {
+		"lib": "/src",
+		"bin": "/bin"
+	},
+	"files": [
+		"/bin/",
+		"/src/",
+		"/recipe.tmLanguage.json",
+		"/recipe.tmLanguage.ts",
+		"/README.md",
+		"/LICENSE"
+	],
+	"scripts": {
+		"check": "biome check",
+		"cli": "run recipe-tmlang",
+		"fmt": "dprint fmt",
+		"generate": "run recipe-tmlang generate",
+		"lint": "biome lint",
+		"prepack": "bun generate",
+		"recipe-tmlang": "bun bin/recipe-tmlang.ts",
+		"typecheck": "tsc --noEmit",
+		"verify": "run recipe-tmlang verify"
+	},
+	"dependencies": {
+		"dreamcli": "npm:@kjanat/dreamcli@^2.4.0",
+		"tree-sitter-recipe": "0.3.0",
+		"vscode-oniguruma": "^2.0.1",
+		"vscode-textmate": "^9.2.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.1",
+		"@types/bun": "^1.3.14",
+		"dprint": "^0.54.0",
+		"runner-run": "^0.14.3",
+		"typescript": "^6.0.3"
+	},
+	"packageManager": "bun@1.3.14",
+	"engines": {
+		"bun": ">=1.3",
+		"node": ">=22.22.2"
+	},
+	"trustedDependencies": [
+		"tree-sitter-recipe"
+	]
+}