jsonata 2.2.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52797dede85591f15e5e3ad10670d556d3b4683471c5b5e00f0ff0602e147694
+  data.tar.gz: 0d235b9161ee1d2a45a1f492c813c5a2b04f438aa91af7707f9144c48e39724b
+SHA512:
+  metadata.gz: 945f2e2fca929e067dd684ce171edc66f8d233047e3bea1b6e3b1513022e662a05342b1d393f585d43e2ed0892cb824a77896df04a19cb56922fe5fb6fc7216a
+  data.tar.gz: 1d960e3b290979f87f8f71509fcd1bbbd76a95081a08a701df7a1d33c57270857fe4f3d908530796cdc56c747857b95b53d3d9b13616a739d343dabe942ffd80

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,4 @@
+inherit_gem:
+  manageiq-style: ".rubocop_base.yml"
+inherit_from:
+- ".rubocop_local.yml"

data/.rubocop_local.yml

@@ -0,0 +1,52 @@
+# The minimum supported Ruby version (see the gemspec); manageiq-style targets a newer one.
+AllCops:
+  TargetRubyVersion: 3.1
+
+# This is not a Rails project, and the suggested corrections (e.g. blank?) need ActiveSupport.
+Rails:
+  Enabled: false
+
+# lib/ is ported from jsonata-js and keeps the structure, names and comments of the JS code, so it stays
+# diffable with upstream (see AGENTS.md). These cops restructure the code or rename things away from the JS.
+Lint/DuplicateBranch:
+  Enabled: false
+Naming/MethodParameterName:
+  Enabled: false
+Naming/PredicateMethod:
+  Enabled: false
+Style/CaseLikeIf:
+  Enabled: false
+Style/CommentAnnotation:
+  Enabled: false
+Style/ConditionalAssignment:
+  Enabled: false
+Style/EmptyElse:
+  AllowComments: true
+Style/GuardClause:
+  Enabled: false
+Style/IdenticalConditionalBranches:
+  Enabled: false
+Style/IfUnlessModifier:
+  Enabled: false
+Style/ItAssignment:
+  Enabled: false
+Style/MultilineBlockChain:
+  Enabled: false
+Style/MultipleComparison:
+  Enabled: false
+Style/NegatedIfElseCondition:
+  Enabled: false
+Style/RedundantAssignment:
+  Enabled: false
+
+# Built-in function parameters are positional, as their arity (JS Function.length) is used when invoking them.
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+# Array#sum uses Kahan-Babuska summation, which gives different results from the JS loop (see AGENTS.md).
+Performance/Sum:
+  Enabled: false
+
+# Jsonata::Error is raised with a code and fields, e.g. raise Jsonata::Error.new('T0410', :index => 1).
+Style/RaiseArgs:
+  EnforcedStyle: compact

data/AGENTS.md

@@ -0,0 +1,171 @@
+# AGENTS.md
+
+Guidance for agents working on jsonata-rb. Read the README first; this file covers what the README does not:
+the decisions behind the port and how JavaScript semantics are emulated in Ruby.
+
+## Ground rules
+
+- **Port, don't invent.** Every change to `lib/` should correspond to code in `vendor/jsonata-js/src`. When a
+  test fails, find how jsonata-js does it and port that, rather than writing a new solution that happens to pass.
+- **Keep the structure diffable.** Ruby files mirror the JS files: same function order, same names (snake_case),
+  same comments (including the JSDoc text and TODOs). Ruby-only code is marked with a comment such as
+  `(Ruby specific)` or `(jsonata-js: <original construct>)`, so it is clear what is a deviation.
+- **Keep the upstream copyright headers.** Each ported file starts with the IBM copyright header of the JS file it
+  ports (in ASCII, `(c)` for the copyright sign), as required by the MIT license. Copy the header when porting a
+  new file, and update the years if upstream changes them.
+- **Tests come from upstream only.** Language behavior is tested exclusively by the jsonata-js test suite via
+  `spec/test_suite_spec.rb`. Do not add hand-written specs for language features. `spec/jsonata_spec.rb` is only
+  for the Ruby API (conversion of values, `assign`, `register_function`, errors, ...).
+- **Never edit `vendor/jsonata-js`.** It is a git submodule tracking jsonata-js master. Bump it with
+  `rake jsonata_js:update` and commit the submodule bump together with the ported `lib/` changes.
+- **ASCII only.** Code, comments and commit messages must not contain non-ASCII characters, including (but not
+  limited to) em-dashes and en-dashes, curly quotes, the section sign, Greek letters (e.g. lambda) and
+  mathematical symbols (e.g. less-than-or-equal). Use `"\uXXXX"` escapes in string literals that
+  need non-ASCII characters, and ASCII equivalents in comments.
+- **LF line endings.** Enforced by `.gitattributes`; never commit CRLF.
+- **Optimize within Ruby, not by changing the algorithm.** Performance work may change how the Ruby is written
+  (e.g. caching in the Ruby-only helpers in `utils.rb`), but must not change the logic ported from jsonata-js.
+  Algorithmic improvements should be proposed upstream first, and then ported.
+- **Ruby >= 3.1.** Do not use syntax or core methods newer than 3.1.
+- **Rubocop must pass.** The style is ManageIQ's (`manageiq-style` gem), with project overrides in
+  `.rubocop_local.yml`. Cops that would restructure ported code away from the JS are disabled there; prefer adding
+  to that list (with the reason) over rewriting ported code to satisfy a cop. Review unsafe autocorrections by
+  hand - some are wrong here (e.g. `Style/HashExcept` on `#parameters`, or `Style/BitwisePredicate`).
+
+## Porting workflow for jsonata-js changes
+
+The `jsonata-js sync` workflow (`.github/workflows/jsonata-js-sync.yaml`) runs these steps daily with Claude and
+opens a PR from the `jsonata-js-sync` branch; they also apply when porting by hand.
+
+1. `bundle exec rake jsonata_js:update` - moves the submodule to jsonata-js master and lists new commits.
+2. `bundle exec rake jsonata_js:diff` - shows the `src/` and `test/` changes since the commit recorded in this repo.
+3. Port each `src/` hunk to the corresponding Ruby file (see the mapping table in the README), at the same place
+   in the file.
+4. `bundle exec rspec` (or `GROUP=<group> bundle exec rspec` while iterating) and `bundle exec rubocop` until
+   everything passes.
+5. If `test/run-test-suite.js` changed, port that change to `spec/test_suite_spec.rb`.
+6. Changes to the JS-only mocha tests (`test/*.js` other than `run-test-suite.js`) are not run by this repo;
+   only port them if they reveal behavior worth covering in `spec/jsonata_spec.rb`.
+
+## JavaScript vs Ruby: decisions made
+
+### undefined and null
+
+- `nil` is JavaScript `undefined`. `Jsonata::NULL` (a frozen sentinel) is JSON `null`. This was chosen because
+  JS code tests for `undefined` far more often than `null`, and Ruby methods return `nil` implicitly.
+- Values are converted at the API boundary only: `Utils.from_ruby` (nested `nil` -> `NULL`, Symbol keys -> String
+  keys) on the way in, `Utils.to_ruby` (`NULL` -> `nil`, `JArray` -> `Array`) on the way out. A top-level `nil`
+  input or binding value means `undefined`.
+- `Expression#evaluate_raw` returns the internal representation; the test harness uses it to tell `null` from
+  `undefined`.
+
+### Truthiness and typeof
+
+- JS truthiness (`if (x)`, `!x`, `x || y`) on values must use `Utils.truthy?` - in Ruby `0`, `""` and `NULL` are
+  truthy. Only use plain Ruby truthiness where the JS value is known to be a boolean/object/undefined.
+- `typeof x` maps to `Utils.typeof(x)`. Remember `typeof null === 'object'` and arrays are objects in JS:
+  `Utils.keys` returns index strings for arrays, as `Object.keys` does (needed by the wildcard operator).
+
+### Objects, arrays and sequences
+
+- JSON objects are Hashes with String keys (insertion ordered, like JS objects).
+- jsonata-js attaches properties to arrays (`sequence`, `keepSingleton`, `tupleStream`, `cons`, `outerWrapper`).
+  These live on `Jsonata::JArray < Array`. Read them with `x.is_a?(JArray) && x.flag` (or `Utils.sequence?`),
+  because many arrays are plain `Array`s. Before setting a flag on an array that may be plain, wrap it in a
+  `JArray`.
+- In Ruby 3, `Array#+`, `#map`, `#select`, `#[]` with ranges etc. on a `JArray` return a plain `Array`. This
+  matches JS, where `concat`/`slice`/`map` do not copy the custom properties.
+- `createSequence` (with the `sequence` length limit) is `Frame#create_sequence` / `Focus#create_sequence`.
+  `create_sequence(nil)` pushes `nil` (as JS does with an explicit `undefined` argument), while
+  `create_sequence()` creates an empty sequence - keep the distinction.
+- Beware Ruby negative indexes: `arr[-1]` is the last element, whereas JS returns `undefined`. Guard indexes that
+  may be negative.
+
+### Numbers
+
+- JS numbers are doubles; here they are Integers when integral (and within +/-2^53) and Floats otherwise.
+- Do arithmetic in Float and pass results through `Utils.normalize_number`, so integer overflow/precision behaves
+  like JS and integral results come back as Integers.
+- Do not use `Array#sum` - it uses Kahan-Babuska summation and gives different results from JS's naive loop.
+- `Math.floor` on large values: use `Utils.js_floor`, which keeps the result a Float beyond 2^53.
+- Formatting: `Utils.number_to_s` (Number::toString), `Utils.to_fixed` (toFixed), `Utils.to_precision`
+  (toPrecision) are exact (via Rational), including JS's round-half-up tie breaking.
+- `Math.round` is `(x.to_r + 1/2).floor` (ties toward +infinity), not Ruby's `round`.
+- JS parsing helpers: `Utils.parse_int` (returns `nil` for NaN), `Utils.js_number` (`Number(str)`).
+
+### Strings
+
+- Ruby strings are indexed by code point, JS strings by UTF-16 code unit. The port uses code points throughout
+  (consistent within Ruby); this only matters for characters outside the BMP.
+- Ruby cannot hold UTF-16 surrogates. The tokenizer combines `\uD8xx\uDCxx` escape pairs into one character; a
+  lone surrogate is stored as invalid UTF-8 bytes (`Utils.from_char_code`), which `encode_uri` rejects and
+  `json_stringify` re-escapes as `\udxxx`.
+- JS string helpers with different Ruby semantics: `Utils.js_slice`, `Utils.js_split` (keeps empty strings),
+  `Utils.json_stringify` (JSON.stringify, including the replacer and indentation used by `$string`),
+  `Utils.encode_uri` / `Utils.decode_uri`.
+
+### Regular expressions
+
+- Regex literals are parsed into `Parser::RegexLiteral` (source + flags) and translated by `Utils.js_regexp`:
+  `^`/`$` become `\A`/`\z` unless the `m` flag is set, `[]` and `[^]` are rewritten, and `(?a)` is prepended so
+  `\w`, `\d`, `\b` are ASCII-only as in JS.
+- `RegExp.lastIndex` is emulated with a `last_index` variable captured by the matcher closure in
+  `evaluate_regex`.
+- The jsonata-js `RegexEngine` option is the `:regex_engine` option: a callable `(source, flags)` returning an
+  object that responds to `match(str, pos)`.
+
+### Functions
+
+- Function values: `Jsonata::Lambda` (`_jsonata_lambda`), `Jsonata::NativeFunction` (`_jsonata_function`), and
+  plain callables (`Proc`, `Method`, `Jsonata::Closure` - the JS function with an `arity` property).
+  `Utils.function?` covers all of them; `Utils.callable?` is `typeof x === 'function'`.
+- Built-in functions are instance methods of `Jsonata::Functions` and `Jsonata::DateTime`, which are included in
+  `Jsonata::Focus`. A `Focus` is the JS `this` (`environment`, `input`, `options`, `create_sequence`), so
+  `fn.lookup.call(focus, ...)` becomes `focus.lookup(...)`. Built-ins are registered with
+  `Focus.instance_method(:name)`.
+- `Utils.invoke` calls a Ruby callable with JS semantics: missing arguments become `nil` and extra arguments are
+  dropped. Within built-ins, call function arguments with `call_function`, which also handles `Lambda#apply`.
+- Arity (JS `Function.length`) is the number of *required* Ruby parameters. Declare built-in parameters as
+  required (no defaults) unless the JS function has a default (e.g. `string(arg, prettify = false)`), otherwise
+  higher-order functions like `$map` pass the wrong number of arguments.
+- Partial application of native functions reads parameter names from `#parameters` (JS parses
+  `func.toString()`).
+- `not` is a valid Ruby method name and is used for `$not`.
+- JS `async`/`await` is dropped; evaluation is synchronous. `Promise.all` loops run sequentially but still set
+  `environment.is_parallel_call`, which the evaluate entry/exit hooks rely on. `$sort`'s recursive merge is
+  iterative to avoid deep Ruby recursion.
+- The `Symbol.for('jsonata.__evaluate_entry')` style hook names are Ruby Symbols, e.g.
+  `:'jsonata.__evaluate_entry'`; `Expression#assign` keeps such Symbols as-is.
+
+### Errors
+
+- JS `throw { code: ... }` is `raise Jsonata::Error.new('CODE', field: ...)`; the fields use Ruby names
+  (`function_name` for `functionName`) and `Error#to_h` maps them back. Messages are filled in by
+  `Evaluator.populate_message` from `ERROR_CODES`.
+- JS `catch (err)` catches everything; the port rescues only `Jsonata::Error`, so Ruby bugs surface as Ruby
+  exceptions instead of being annotated as JSONata errors.
+- `SystemStackError` is reported as `D1011` (Ruby specific). Non-tail recursion in an expression overflows the
+  Ruby stack at roughly 600-1000 levels, as each JSONata call uses about a dozen Ruby frames; tail calls are
+  handled by the trampoline in `Evaluator.apply`.
+
+### Parser
+
+- AST nodes are Hashes with Symbol keys (`:keep_array` for `keepArray`, etc.). Symbol keys keep AST nodes
+  distinguishable from user data, which has String keys (e.g. the `?` placeholder check in partial application).
+- JS nodes inherit `nud`/`led`/`lbp`/`id` from the symbol table via the prototype chain; here a
+  `compare_by_identity` Hash maps each node to its `Sym`. `JSON.parse(JSON.stringify(node))` is `deep_clone`,
+  which drops that mapping just as the JS clone drops the prototype.
+- `nud`/`led` are blocks: use `next`, not `return`, to return early from them.
+
+### Dates
+
+- JS `Date` is a UTC Ruby `Time`. `DateTime.date_utc` reproduces `Date.UTC` (month overflow, truncation, years
+  0-99 mapping to 1900+), and `DateTime.date_parse` reproduces `Date.parse` for the ISO 8601 subset accepted by
+  `$toMillis`. Timestamps without an offset are treated as UTC.
+
+### Test harness
+
+- `spec/test_suite_spec.rb` mirrors `run-test-suite.js`. Results are compared with `evaluate_raw` against the
+  expected JSON converted with `Utils.from_ruby`, so `null` and `undefined` are distinguished.
+- Ruby's JSON parser rejects lone surrogates, so test files containing them are re-parsed with the surrogates
+  escaped; they reach the tokenizer as `\uXXXX` in `expr`, and are decoded with `Utils.from_char_code` elsewhere.

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and the version follows the jsonata-js version it is ported from (see [Versioning](README.md#versioning)).
+
+## [Unreleased]
+
+### Added
+- Ruby port of jsonata-js: parser, evaluator, function library, date/time functions and signature validation
+- The full JSONata language and function library
+- `Jsonata::Error` with the jsonata-js error codes and messages
+- `Expression#assign`, `#register_function`, `#ast`, `#errors` and `#evaluate_raw`
+- `recover`, `timeout`, `stack`, `sequence` and `regex_engine` options
+- The jsonata-js test suite, via a git submodule at `vendor/jsonata-js`
+- `rake jsonata_js:update` and `rake jsonata_js:diff` tasks for tracking jsonata-js

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2016-2018 IBM Corp.
+Copyright (c) 2026 jsonata-rb contributors
+
+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.

data/README.md

@@ -0,0 +1,189 @@
+# JSONata-RB
+
+A Ruby port of [jsonata-js](https://github.com/jsonata-js/jsonata), the reference implementation of
+[JSONata](http://jsonata.org/) - a lightweight query and transformation language for JSON data.
+
+This is a faithful, file-by-file port of the JavaScript implementation, and it is tested against the
+jsonata-js test suite itself (included as a git submodule), so it supports the full JSONata language and
+function library.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jsonata'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+```ruby
+require 'jsonata'
+
+data = {
+  example: [
+    { value: 4 },
+    { value: 7 },
+    { value: 13 }
+  ]
+}
+
+# Compile an expression, then evaluate it
+expression = Jsonata.expression('$sum(example.value)')
+expression.evaluate(data)  # => 24
+
+# Or use the convenience method
+Jsonata.evaluate('$sum(example.value)', data)  # => 24
+```
+
+See the [JSONata documentation](http://docs.jsonata.org/) for the language and function library.
+
+### Variable bindings
+
+```ruby
+Jsonata.evaluate('value > $threshold', { value: 150 }, { threshold: 100 })  # => true
+
+expr = Jsonata.expression('value > $threshold')
+expr.assign('threshold', 100)
+expr.evaluate({ value: 150 })  # => true
+```
+
+### Custom functions
+
+Any Ruby callable can be bound as a function, optionally with a
+[signature](http://docs.jsonata.org/embedding-extending#function-signature-syntax) to validate its arguments:
+
+```ruby
+expr = Jsonata.expression('$double(value)')
+expr.assign('double', ->(x) { x * 2 })
+expr.evaluate({ value: 21 })  # => 42
+
+expr = Jsonata.expression('$add(1, 2)')
+expr.register_function('add', ->(a, b) { a + b }, '<nn:n>')
+expr.evaluate  # => 3
+
+expr = Jsonata.expression('$greet("World")')
+expr.register_function('greet', '<s:s>') { |name| "Hello, #{name}" }
+expr.evaluate  # => "Hello, World"
+```
+
+### Errors
+
+Syntax and evaluation errors raise `Jsonata::Error`, which carries the same fields as the error objects
+thrown by jsonata-js (`code`, `position`, `token`, `value`, ...):
+
+```ruby
+begin
+  Jsonata.evaluate('1 +')
+rescue Jsonata::Error => e
+  e.code      # => "S0207"
+  e.position  # => 3
+  e.message   # => "Unexpected end of expression"
+end
+```
+
+### Options
+
+`Jsonata.expression(expr, options)` accepts the same options as jsonata-js:
+
+| Option          | Description                                                                         |
+|-----------------|-------------------------------------------------------------------------------------|
+| `:recover`      | Attempt to recover on parse errors (see `Expression#errors`)                        |
+| `:timeout`      | Evaluation timeout in milliseconds (error `D1012`)                                  |
+| `:stack`        | Maximum evaluation depth (error `D1011`)                                            |
+| `:sequence`     | Maximum sequence length (error `D2015`)                                             |
+| `:regex_engine` | A callable `(source, flags)` returning an object that responds to `match(str, pos)` |
+
+### Mapping between JSON and Ruby values
+
+* JSON objects are Hashes. Symbol keys in the input are converted to Strings; results always have String keys.
+* JSON `null` and JavaScript `undefined` are both returned as `nil`. In the input, a `nil` nested inside a Hash
+  or Array is JSON `null`, while a top-level `nil` input means there is no input (`undefined`).
+  `Expression#evaluate_raw` returns the internal representation, in which `null` is `Jsonata::NULL` and
+  `undefined` is `nil`.
+* Numbers are Integers when they are integral (and within the range of a JavaScript safe integer), and Floats
+  otherwise. Arithmetic follows JavaScript (IEEE 754 double) semantics.
+* Functions (lambdas defined in an expression, or built-in functions) are returned as `Jsonata::Lambda` and
+  `Jsonata::NativeFunction` objects.
+
+### Differences from jsonata-js
+
+* Evaluation is synchronous (jsonata-js `evaluate` returns a Promise).
+* Regular expressions use Ruby's regex engine. JavaScript regex syntax is translated where the two differ
+  (e.g. `^`/`$` anchors), but some exotic constructs may behave differently.
+* Strings are indexed by Unicode code point, so `$match` indexes differ from jsonata-js (which uses UTF-16 code
+  units) for strings containing characters outside the Basic Multilingual Plane.
+
+## Development
+
+The jsonata-js repository is included as a git submodule at `vendor/jsonata-js`, so clone with:
+
+```bash
+git clone --recurse-submodules <repo-url>
+# or, in an existing clone
+git submodule update --init
+```
+
+Then:
+
+```bash
+bundle install
+bundle exec rspec                         # run all tests
+GROUP=hof-map,regex bundle exec rspec     # run specific test-suite groups
+bundle exec rake console                  # interactive console
+bundle exec rubocop                       # lint
+```
+
+### Structure of the port
+
+Each Ruby file is a port of the corresponding jsonata-js source file, keeping the same structure, function
+names (in snake_case), and comments, so that upstream changes can be applied to the Ruby code directly.
+
+| jsonata-js            | jsonata-rb                                                      |
+|-----------------------|-----------------------------------------------------------------|
+| `src/jsonata.js`      | `lib/jsonata/evaluator.rb`                                      |
+| `src/parser.js`       | `lib/jsonata/parser.rb`                                         |
+| `src/functions.js`    | `lib/jsonata/functions.rb`                                      |
+| `src/datetime.js`     | `lib/jsonata/datetime.rb`                                       |
+| `src/signature.js`    | `lib/jsonata/signature.rb`                                      |
+| `src/utils.js`        | `lib/jsonata/utils.rb` (plus helpers emulating JavaScript)      |
+| `test/run-test-suite.js` | `spec/test_suite_spec.rb`                                    |
+
+### Tracking jsonata-js
+
+The tests come from the jsonata-js test suite (`vendor/jsonata-js/test/test-suite`). To pick up jsonata-js
+changes:
+
+```bash
+bundle exec rake jsonata_js:update  # move the submodule to the latest jsonata-js master, and list the new commits
+bundle exec rake jsonata_js:diff    # show the src/ and test/ changes to port
+bundle exec rspec                   # port the src/ changes until the tests pass
+git add vendor/jsonata-js lib       # commit the submodule bump together with the ported changes
+```
+
+The `jsonata-js sync` workflow (`.github/workflows/jsonata-js-sync.yaml`) does this daily: when jsonata-js
+master moves, it bumps the submodule, has Claude port any `src/` and `test/` changes, and opens (or updates) a
+pull request from the `jsonata-js-sync` branch. The PR is a draft if the tests or rubocop fail. The steps are in
+`bin/jsonata-js-sync`; `DRY_RUN=1 bin/jsonata-js-sync publish` shows the commit message and PR description
+for the current submodule checkout without pushing.
+
+## Versioning
+
+For consistency, the gem's version follows the jsonata-js version it is ported from, so `jsonata` 2.2.2
+implements the same language and passes the same test suite as jsonata-js 2.2.2. Releases that contain only
+Ruby-specific changes, between upstream releases, add a fourth segment (e.g. 2.2.2.1).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Acknowledgments
+
+This is a Ruby port of the [JSONata JavaScript library](https://github.com/jsonata-js/jsonata) created by
+Andrew Coleman and contributors.

data/Rakefile

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc 'Run RSpec tests'
+task :test => :spec
+
+desc 'Open an interactive console'
+task :console do
+  require 'irb'
+  require_relative 'lib/jsonata'
+  ARGV.clear
+  IRB.start
+end
+
+JSONATA_JS_DIR = 'vendor/jsonata-js'
+
+namespace :jsonata_js do
+  # The jsonata-js commit recorded in the superproject (HEAD, falling back to the index)
+  def recorded_jsonata_js_commit
+    commit = `git ls-tree HEAD #{JSONATA_JS_DIR} 2>/dev/null`.split[2]
+    commit || `git ls-files -s #{JSONATA_JS_DIR}`.split[1]
+  end
+
+  desc 'Update the jsonata-js submodule to the latest jsonata-js master'
+  task :update do
+    sh "git -C #{JSONATA_JS_DIR} fetch origin"
+    sh "git -C #{JSONATA_JS_DIR} checkout --quiet origin/master"
+    sh "git -C #{JSONATA_JS_DIR} log --oneline #{recorded_jsonata_js_commit}..HEAD -- src test"
+  end
+
+  desc 'Show the jsonata-js source and test changes that have not yet been committed to this repo'
+  task :diff do
+    sh "git -C #{JSONATA_JS_DIR} diff #{recorded_jsonata_js_commit} HEAD -- src test"
+  end
+end