gmat-script 0.1.0__tar.gz

gmat_script-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+*.dylib
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.whl
+
+# Environments
+.venv/
+venv/
+env/
+.env
+
+# uv
+.uv-cache/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Docs build
+site/
+.cache/
+
+# Node / tree-sitter (the generated parser under tree-sitter-gmat/src/ IS committed)
+node_modules/
+tree-sitter-gmat/build/
+*.wasm
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+.DS_Store

gmat_script-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to gmat-script are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-07
+
+Initial release: a tree-sitter grammar for GMAT mission scripts and an install-free Python parser
+built on it.
+
+### Added
+
+- **Tree-sitter grammar** for GMAT `.script` and GmatFunction (`.gmf`) files — one grammar for both,
+  a deliberately permissive superset: `Create <Type> <name>` accepts any resource type and unknown
+  commands parse as generic command nodes, so a new resource or command never needs a grammar
+  change. Every input re-emits **byte-for-byte**, comments and layout included. The acceptance bar is
+  concrete: all 162 `.script` and 9 `.gmf` files shipped with NASA GMAT R2026a parse with zero
+  `ERROR` nodes and round-trip exactly (#2, #4, #5, #8).
+- **`parse()` API** — `parse(text)` returns a `Tree` that never raises on malformed input; syntax
+  problems surface as `ERROR` / `MISSING` nodes localised through `tree.errors`, alongside
+  `tree.has_errors` and a byte-exact `tree.to_source()` (#6, #9).
+- **`gmat-script parse` CLI** — a fast, install-free syntax gate: it prints the syntax tree and exits
+  non-zero on a syntax error, with a machine-readable `--json` `{file, ok, errors}` report (#7).
+- **Packaging** — `pip install gmat-script` ships a precompiled grammar in a stable-ABI wheel for
+  Python 3.10–3.12 on Linux, macOS, and Windows; the only runtime dependency is `tree-sitter`, and no
+  C or Node toolchain — and never a GMAT install — is required (#3).
+- **Documentation** — getting-started, the grammar-surface reference, the `parse` CLI and
+  error-reporting guides, and the API reference, published to GitHub Pages (#3, #10).

gmat_script-0.1.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: "If you use gmat-script in academic work, please cite it using the metadata below."
+title: gmat-script
+abstract: >-
+  gmat-script is a permissively-licensed Python library and tree-sitter grammar for GMAT mission
+  scripts. It parses GMAT .script and GmatFunction (.gmf) files into a concrete syntax tree that
+  re-emits byte-for-byte, and layers a typed AST with a mutation API, a canonical formatter, a
+  linter, and editor tooling on top. The whole stack operates on script text and needs no GMAT
+  install.
+type: software
+authors:
+  - given-names: Dimitrije
+    family-names: Jankovic
+version: 0.1.0
+date-released: "2026-06-07"
+license: MIT
+repository-code: "https://github.com/astro-tools/gmat-script"
+url: "https://github.com/astro-tools/gmat-script"
+keywords:
+  - gmat
+  - tree-sitter
+  - parser
+  - astrodynamics
+  - mission-analysis

gmat_script-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 astro-tools
+
+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.

gmat_script-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: gmat-script
+Version: 0.1.0
+Summary: Parse, format, lint, and edit GMAT mission scripts from Python — a tree-sitter grammar and tooling.
+Project-URL: Homepage, https://github.com/astro-tools/gmat-script
+Project-URL: Repository, https://github.com/astro-tools/gmat-script
+Project-URL: Issues, https://github.com/astro-tools/gmat-script/issues
+Project-URL: Documentation, https://astro-tools.github.io/gmat-script/
+Project-URL: Changelog, https://github.com/astro-tools/gmat-script/blob/main/CHANGELOG.md
+Author: Dimitrije Jankovic
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astrodynamics,formatter,gmat,linter,mission-analysis,parser,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tree-sitter<0.26,>=0.25
+Description-Content-Type: text/markdown
+
+# gmat-script
+
+Parse, format, lint, and edit [GMAT](https://gmat.gsfc.nasa.gov/) `.script` mission files from
+Python — built on a [tree-sitter](https://tree-sitter.github.io/tree-sitter/) grammar. The whole
+stack operates on script **text**; nothing here requires a GMAT install.
+
+Today it ships the parser and the `gmat-script parse` command-line tool. The typed AST and mutation
+API, the canonical formatter, the linter, and the editor tooling build on top of the same tree as
+they land.
+
+## Install
+
+```bash
+pip install gmat-script
+```
+
+gmat-script supports Python 3.10, 3.11, and 3.12. The wheel bundles a precompiled grammar, so the
+install needs no C or Node toolchain — and never GMAT.
+
+## Quick start
+
+```python
+from gmat_script import parse
+
+tree = parse("Create Spacecraft Sat\nSat.SMA = 7000\n")
+
+tree.has_errors      # False — the script is well-formed
+tree.to_source()     # round-trips byte-for-byte to the input
+```
+
+`parse` never raises on malformed input: it returns a tree carrying `ERROR` / `MISSING` nodes
+localised to the broken construct, surfaced through `tree.errors`. The same engine drives the CLI,
+a fast, install-free syntax gate for CI:
+
+```console
+$ gmat-script parse mission.script        # prints the syntax tree; exits non-zero on a syntax error
+$ gmat-script parse --json mission.script  # machine-readable {file, ok, errors} report
+```
+
+## The grammar surface
+
+The tree-sitter grammar parses GMAT scripts (`.script`) and GmatFunctions (`.gmf`) — the same
+grammar for both — and re-emits any input **byte-for-byte**, comments and layout included. It is a
+deliberately permissive superset: `Create <Type> <name>` accepts any resource type and unknown
+command keywords parse as generic command nodes, so a new resource or command never needs a grammar
+change. The acceptance bar is concrete: every one of the 162 `.script` and 9 `.gmf` files shipped
+with NASA GMAT R2026a parses with zero errors and round-trips exactly.
+
+See the [grammar surface reference](https://astro-tools.github.io/gmat-script/grammar-surface/) for
+the node taxonomy and the covered / deferred constructs.
+
+## The GMAT-free guarantee
+
+Reading, checking, formatting, and transforming a script needs only this package — never a GMAT
+install. `pip install gmat-script` never pulls in, requires, or looks for GMAT or `gmatpy`; the only
+runtime dependency is `tree-sitter`. (GMAT is used at build time only, to generate the field
+catalogue that later semantic tooling will check against.)
+
+## GMAT version
+
+The grammar targets **GMAT R2026a**. Because it never enumerates resource types or command keywords,
+parsing is effectively version-independent — scripts from other releases parse too. Semantics that
+*do* vary by release (valid field names, enums, defaults) belong to the later linter and are scoped
+to R2026a.
+
+## What gmat-script is not
+
+- **Not a propagator or astrodynamics engine.** It reads and transforms script *text*; it computes
+  no orbits and models no physics.
+- **Not a mission runner.** Running a script is GMAT's job — gmat-script does no execution.
+- **Not an engine-dependent validator.** "Does it parse" is a structural question answered here;
+  "does it run / converge" is a different question that needs GMAT.
+
+## Documentation
+
+Full documentation — getting started, the grammar surface, the `parse` CLI, the error-reporting
+model, and the API reference — is at
+**[astro-tools.github.io/gmat-script](https://astro-tools.github.io/gmat-script/)**.
+
+## License
+
+[MIT](LICENSE) — part of the [astro-tools](https://github.com/astro-tools) organization.

gmat_script-0.1.0/README.md

@@ -0,0 +1,82 @@
+# gmat-script
+
+Parse, format, lint, and edit [GMAT](https://gmat.gsfc.nasa.gov/) `.script` mission files from
+Python — built on a [tree-sitter](https://tree-sitter.github.io/tree-sitter/) grammar. The whole
+stack operates on script **text**; nothing here requires a GMAT install.
+
+Today it ships the parser and the `gmat-script parse` command-line tool. The typed AST and mutation
+API, the canonical formatter, the linter, and the editor tooling build on top of the same tree as
+they land.
+
+## Install
+
+```bash
+pip install gmat-script
+```
+
+gmat-script supports Python 3.10, 3.11, and 3.12. The wheel bundles a precompiled grammar, so the
+install needs no C or Node toolchain — and never GMAT.
+
+## Quick start
+
+```python
+from gmat_script import parse
+
+tree = parse("Create Spacecraft Sat\nSat.SMA = 7000\n")
+
+tree.has_errors      # False — the script is well-formed
+tree.to_source()     # round-trips byte-for-byte to the input
+```
+
+`parse` never raises on malformed input: it returns a tree carrying `ERROR` / `MISSING` nodes
+localised to the broken construct, surfaced through `tree.errors`. The same engine drives the CLI,
+a fast, install-free syntax gate for CI:
+
+```console
+$ gmat-script parse mission.script        # prints the syntax tree; exits non-zero on a syntax error
+$ gmat-script parse --json mission.script  # machine-readable {file, ok, errors} report
+```
+
+## The grammar surface
+
+The tree-sitter grammar parses GMAT scripts (`.script`) and GmatFunctions (`.gmf`) — the same
+grammar for both — and re-emits any input **byte-for-byte**, comments and layout included. It is a
+deliberately permissive superset: `Create <Type> <name>` accepts any resource type and unknown
+command keywords parse as generic command nodes, so a new resource or command never needs a grammar
+change. The acceptance bar is concrete: every one of the 162 `.script` and 9 `.gmf` files shipped
+with NASA GMAT R2026a parses with zero errors and round-trips exactly.
+
+See the [grammar surface reference](https://astro-tools.github.io/gmat-script/grammar-surface/) for
+the node taxonomy and the covered / deferred constructs.
+
+## The GMAT-free guarantee
+
+Reading, checking, formatting, and transforming a script needs only this package — never a GMAT
+install. `pip install gmat-script` never pulls in, requires, or looks for GMAT or `gmatpy`; the only
+runtime dependency is `tree-sitter`. (GMAT is used at build time only, to generate the field
+catalogue that later semantic tooling will check against.)
+
+## GMAT version
+
+The grammar targets **GMAT R2026a**. Because it never enumerates resource types or command keywords,
+parsing is effectively version-independent — scripts from other releases parse too. Semantics that
+*do* vary by release (valid field names, enums, defaults) belong to the later linter and are scoped
+to R2026a.
+
+## What gmat-script is not
+
+- **Not a propagator or astrodynamics engine.** It reads and transforms script *text*; it computes
+  no orbits and models no physics.
+- **Not a mission runner.** Running a script is GMAT's job — gmat-script does no execution.
+- **Not an engine-dependent validator.** "Does it parse" is a structural question answered here;
+  "does it run / converge" is a different question that needs GMAT.
+
+## Documentation
+
+Full documentation — getting started, the grammar surface, the `parse` CLI, the error-reporting
+model, and the API reference — is at
+**[astro-tools.github.io/gmat-script](https://astro-tools.github.io/gmat-script/)**.
+
+## License
+
+[MIT](LICENSE) — part of the [astro-tools](https://github.com/astro-tools) organization.

gmat_script-0.1.0/docs/api.md

@@ -0,0 +1,11 @@
+# API reference
+
+The public surface of `gmat_script`. It is deliberately minimal and additive — today it is the
+`parse` entry point and the `Tree` it returns, plus the `ErrorNode` / `Position` records that
+describe syntax errors. Later layers (the typed AST, the formatter) are re-exported here as they
+land.
+
+For a worked introduction see [Getting started](getting-started.md); for the error model see
+[Error reporting](errors.md).
+
+::: gmat_script

gmat_script-0.1.0/docs/cli.md

@@ -0,0 +1,115 @@
+# The `parse` CLI
+
+Installing gmat-script puts a `gmat-script` console script on your `PATH`. Its `parse` subcommand is
+a fast, install-free syntax gate: it parses `.script` / `.gmf` files and reports their syntax trees,
+exiting non-zero when any input has a syntax error. It needs no GMAT, C, or Node toolchain at
+runtime.
+
+```console
+$ gmat-script parse --help
+usage: gmat-script parse [-h] [-q] [--json] FILE [FILE ...]
+
+Parse each FILE (or '-' for stdin) and print its syntax tree as an
+S-expression. Exits non-zero if any file has a syntax error.
+
+positional arguments:
+  FILE         Path to a .script or .gmf file, or '-' to read from stdin.
+
+options:
+  -h, --help   show this help message and exit
+  -q, --quiet  Suppress the syntax tree; print only error diagnostics.
+  --json       Emit a machine-readable JSON report instead of the
+               S-expression.
+```
+
+## Default output — the S-expression
+
+By default, `parse` prints each file's tree as a tree-sitter S-expression to stdout. Any
+`ERROR` / `MISSING` node is reported on stderr as `FILE:line:col: <message>` (positions are
+1-indexed).
+
+```console
+$ gmat-script parse mission.script
+(source_file (create_command type: (identifier) name: (identifier)) (assignment_command left: (member_expression object: (identifier) property: (identifier)) right: (number)))
+```
+
+Read from stdin by passing `-`:
+
+```console
+$ printf 'Create Spacecraft Sat\nSat.SMA = 7000\n' | gmat-script parse -
+(source_file (create_command type: (identifier) name: (identifier)) (assignment_command left: (member_expression object: (identifier) property: (identifier)) right: (number)))
+```
+
+With more than one file, each tree is prefixed by a `; <file>` header (an S-expression comment) so
+the trees stay attributable; a single file's tree is printed bare.
+
+## `--quiet` — diagnostics only
+
+`--quiet` suppresses the tree (and its header), leaving only the stderr diagnostics. This is the form
+you want in CI when you only care whether a file is well-formed:
+
+```console
+$ printf 'Sat.SMA = \n' | gmat-script parse --quiet -
+<stdin>:1:1: unexpected token
+```
+
+A clean file under `--quiet` prints nothing and exits 0.
+
+## `--json` — a machine-readable report
+
+`--json` emits a `{file, ok, errors}` report instead of the S-expression. `ok` mirrors the exit code
+(`true` ⇔ exit 0). Positions are 1-indexed for both line and column.
+
+```console
+$ printf 'Create Spacecraft Sat\nSat.SMA = \n' | gmat-script parse --json -
+{
+  "file": "<stdin>",
+  "ok": false,
+  "errors": [
+    {
+      "type": "ERROR",
+      "start": {
+        "line": 2,
+        "column": 1
+      },
+      "end": {
+        "line": 2,
+        "column": 10
+      },
+      "message": "unexpected token"
+    }
+  ]
+}
+```
+
+A clean file reports `"ok": true` with an empty `errors` list:
+
+```console
+$ printf 'Create Spacecraft Sat\n' | gmat-script parse --json -
+{
+  "file": "<stdin>",
+  "ok": true,
+  "errors": []
+}
+```
+
+For a single file the report is one JSON object; for several files it is a JSON array of reports.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | every file parsed with no `ERROR` / `MISSING` node |
+| `1`  | at least one file had a syntax error |
+| `2`  | a file could not be read (an operational error, distinct from a syntax error) |
+
+The `1` / `0` split is the CI contract: drop `gmat-script parse` into a pipeline and a syntax
+regression fails the build.
+
+## A note on output encoding
+
+Stdout stays ASCII — S-expressions are node-type names, and the JSON report is emitted with
+`ensure_ascii`, so non-ASCII source never reaches stdout. A Windows console under a legacy code page
+cannot choke on it.
+
+For the structure of the error records, see [Error reporting](errors.md).