Skip to content

docs: refresh README for self-containment + Track C wheels #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rafael5 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: refresh README for self-containment + Track C wheels #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 34 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ The grammar:
downstream tools can classify portability tier without re-parsing
(see `lib/stamp.js`),
- is **generated mechanically** from
[`m-standard`](../m-standard)'s curated data (specifically
`integrated/grammar-surface.json`) so it stays in sync with the
source documentation,
[`m-standard`](https://github.com/m-dev-tools/m-standard)'s curated data
(specifically `integrated/grammar-surface.json`) so it stays in sync
with the source documentation,
- handles M's structural quirks via a small external scanner
(`src/scanner.c`) — the two-space rule for argumentless commands,
trailing-whitespace-before-EOL, and `?N` tab-to-column in WRITE
Expand All @@ -61,9 +61,11 @@ compose with tree-sitter-m when a file mixes both. See

`tree-sitter-m` is a parser, not a compiler, formatter, or linter.

- **Standards enforcement** (pragmatic / SAC / operational) lives in
a sibling project (`tree-sitter-m-lint`) that consumes both
`tree-sitter-m`'s AST and `m-standard`'s tier classifications.
- **Standards enforcement** (pragmatic / SAC / operational) lives
downstream in [`m-cli`](https://github.com/m-dev-tools/m-cli)'s
`m lint`, which consumes both this grammar's AST and
[`m-standard`](https://github.com/m-dev-tools/m-standard)'s tier
classifications.
- **Cross-routine resolution**, **type inference**, and **semantic
analysis** belong in tooling layers above the parser.
- **InterSystems ObjectScript** is permanently out of scope (see
Expand All @@ -75,11 +77,12 @@ compose with tree-sitter-m when a file mixes both. See
m-standard → integrated/grammar-surface.json → tree-sitter-m
(data) (versioned data contract) (this project)

tree-sitter-m → bindings: Node / Rust / Python / Go → tree-sitter-m-lint
(this project) (npm, crates.io, go modules; Python: (sibling project)
clone-and-install — no PyPI publication)
→ editor plugins
→ AI agents
tree-sitter-m → bindings: Node / Rust / Python / Go → m-cli (m fmt / m lint /
(this project) (npm, crates.io, go modules; Python: m test / m coverage / m doc)
wheels attached to GitHub Releases)
→ tree-sitter-m-vscode
→ m-stdlib-vscode
→ AI agents / other tooling
```

`tree-sitter-m` is a strict downstream consumer of `m-standard` and
Expand All @@ -98,11 +101,12 @@ npm run generate
# run the corpus tests
npm test

# real-source smoke gate against the full VistA corpus
node tools/smoke-corpus.js ~/vista-meta/vista/vista-m-host/Packages
# real-source smoke gate against any M corpus (default for the m-dev-tools
# org is m-modern-corpus; maintainers also run against a VistA checkout)
node tools/smoke-corpus.js ~/projects/m-modern-corpus

# bucket remaining ERROR nodes by syntactic shape (triage tool)
node tools/error-buckets.js ~/vista-meta/vista/vista-m-host/Packages --sample 1000
node tools/error-buckets.js ~/projects/m-modern-corpus --sample 1000
```

## Bindings
Expand All @@ -117,14 +121,20 @@ cargo add tree-sitter-m tree-sitter # Rust
go get github.com/m-dev-tools/tree-sitter-m # Go
```

The Python binding is consumed via a local checkout — there is
no PyPI publication planned:
The Python binding ships as **prebuilt wheels attached to each GitHub
Release** (cibuildwheel-built; cp310-abi3, so one wheel covers Python
3.10+). No PyPI publication. Install by URL:

```bash
git clone https://github.com/m-dev-tools/tree-sitter-m
pip install ./tree-sitter-m tree-sitter # Python
pip install tree-sitter \
https://github.com/m-dev-tools/tree-sitter-m/releases/download/v0.1.1/tree_sitter_m-0.1.1-cp310-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
```

Wheels for all four platforms (linux x64/arm64, macos arm64, windows x64)
are attached to each release; pick the one matching your platform.
For uv's `[tool.uv.sources]` per-platform-marker template see
[`RELEASE.md`](RELEASE.md) §5.5.

**Node version requirement.** The Node binding requires
**Node 22 LTS**. Upstream `tree-sitter@0.25.0` (the JS runtime)
fails to compile against Node 24's V8 headers — install on Node 24
Expand All @@ -134,11 +144,12 @@ errors during `npm install` with a `node_object_wrap.h` /
Node 24-compatible release. Other bindings (Rust, Python, Go) have
no equivalent host-version constraint.

**Prebuilt binaries.** First-time consumers on a platform without a
prebuild fall back to `node-gyp` build at install time (works,
requires a C toolchain). Prebuilt binary distribution via
`prebuildify` is wired into `package.json` but not yet running in
CI; see [`RELEASE.md`](RELEASE.md) §3 for the rollout plan.
**Prebuilt binaries.** `.github/workflows/prebuilds.yml` runs on
every `v*` tag push and produces N-API binaries for linux x64/arm64,
macos arm64, and windows x64 via `prebuildify`. Each release ships
with both the Node prebuild tarballs and Python wheels attached
(see [`RELEASE.md`](RELEASE.md) §3). `node-gyp-build` consumes the
prebuilds at npm-install time so end users don't need a C toolchain.

## Documentation

Expand Down
Loading