tsrs 0.0.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ee10f94d6ca3fbfc6853d594cff2d247e6d6e2b410f8a84d2606f022d88701
-  data.tar.gz: 1e2bcd3b06704772693909327579d75559aae0326c94ba9a85cbacf0a4229d2c
+  metadata.gz: a87e1838e8352dbcb61cde9ed300cb2eca9f7b14006b6bb9f2aabe5f2565e16f
+  data.tar.gz: c14fe5ae5cb01af608eb90bff51ec4626530f7f8b1e47e80eb0482c539edede0
 SHA512:
-  metadata.gz: 141215b9b49c1efb0760fba4a89d5265f0c895afa10e6b2911ea175476240d1ed4df8699dc0d0e37c3e37739ed5e075d92df0c321b0c6eea0f26b6023da92519
-  data.tar.gz: e4c0fcc7d219893985c4bb7a3146827373c58105c6e1cc956238a0e74fbcb65492a093fbf2c20c48867dc5b41186d552f173d4b89ce28b1f1f4eb4889d6a495d
+  metadata.gz: 89c7cdc9f86f30d75517d16b45aeda776edc21fce6b466a8fa014f0d0c47fc0c6e376fbc44b4f8764187b147aceae99f831c0c30d55e097a9ecd900cc9b082f9
+  data.tar.gz: 8d21641227464c5ec4f33bff52da3a610c0ecc6b07bff8136cfda261426c663886c7b51e055c4ab84c91820e18ac130a4347591d3675982e6064536d0214d1c8

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Marco Roth
+
+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

@@ -1,5 +1,177 @@
-# tsrs
+<h2 align="center">🦀 tsrs for Ruby</h2>
 
-This release only reserves the gem name. It contains no code.
+<h4 align="center">A drop-in replacement for the TypeScript 7 compiler and language server, written in Rust.</h4>
 
-The gem is Ruby bindings for [tsrs](https://github.com/oxc-project/tsrs), the Rust port of the TypeScript 7 compiler, developed at https://github.com/marcoroth/tsrs-ruby.
+<div align="center">Ruby bindings for <a href="https://github.com/oxc-project/tsrs">tsrs</a>, the Rust port of the TypeScript 7 type checker.</div><br/>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/tsrs"><img alt="Gem Version" src="https://img.shields.io/gem/v/tsrs"></a>
+  <a href="https://github.com/oxc-project/tsrs"><img alt="Documentation" src="https://img.shields.io/badge/oxc--project%2Ftsrs-documentation-green"></a>
+  <a href="https://github.com/marcoroth/tsrs-ruby/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/github/license/marcoroth/tsrs-ruby"></a>
+  <a href="https://github.com/marcoroth/tsrs-ruby/issues"><img alt="Issues" src="https://img.shields.io/github/issues/marcoroth/tsrs-ruby"></a>
+</p>
+
+<br/>
+
+### What is tsrs for Ruby?
+
+Ruby bindings for [tsrs](https://github.com/oxc-project/tsrs), a drop-in replacement for the TypeScript 7 compiler and language server, written in Rust. Type check, compile and transpile TypeScript from Ruby, without the need for a JavaScript runtime.
+
+Everything here is tsrs doing the work. For what the options mean and what it can do, the [TypeScript documentation](https://www.typescriptlang.org/tsconfig/) is the reference.
+
+### Installation
+
+```bash
+bundle add tsrs
+```
+
+Anywhere a precompiled gem is not published, the gem builds from source and needs the [Rust toolchain](https://rustup.rs). tsrs needs a recent Rust, 1.99.1 at the moment. `rust/rust-toolchain.toml` pins it, so rustup installs it for the build.
+
+tsrs only runs on 64-bit platforms, so the gem doesn't support 32-bit ARM or x86.
+
+### Versioning
+
+The gem carries the version of tsrs it packages. Gem v0.18.0 bundles tsrs v0.18.0. `Tsrs.tsrs_version` reports what a given build was compiled against, and `Tsrs.typescript_version` reports the TypeScript version that tsrs release is a port of.
+
+So the version tracks tsrs, not the Ruby API here. If the gem needs releasing again for the same tsrs version, that release adds a fourth digit, as in v0.18.0.1.
+
+### Usage
+
+#### Type checking
+
+```ruby
+require "tsrs"
+
+result = Tsrs.check(cwd: "app/javascript")
+# => #<Tsrs::CheckResult status=2 errors=1 diagnostics=1>
+
+result.success?
+# => false
+
+puts result
+# app/javascript/src/index.ts:1:7 - error TS2322: Type 'string' is not assignable to type 'number'.
+
+result.errors.first.code
+# => 2322
+```
+
+Without arguments, tsc finds the `tsconfig.json` in `cwd`. You can also point it at a project, or at files:
+
+```ruby
+Tsrs.check(project: "app/javascript/tsconfig.json")
+Tsrs.check("app/javascript/index.ts", strict: true)
+```
+
+`Tsrs.check` never writes anything, as with `tsc --noEmit`. `validate!` raises `Tsrs::TypeError` if there were errors, so a rake task can fail on them:
+
+```ruby
+task :typecheck do
+  Tsrs.check(cwd: "app/javascript").validate!
+end
+```
+
+#### Checking again and again
+
+`Tsrs.check` runs tsc's command line, which is built to check once and exit, so a check's memory stays with the process. For anything long-lived, like a web server, a file watcher or a test suite that checks often, use a session instead:
+
+```ruby
+session = Tsrs::Session.new(cwd: "app/javascript")
+
+session.check.validate!                      # tsconfig.json in cwd
+session.check("admin/tsconfig.json").errors  # or any other project
+
+session.close
+```
+
+`Tsrs::Session.open(cwd: ...) { |session| ... }` closes the session when the block returns. A session is tsrs's API server, the same one behind tsrs's Node API. Each check builds the program in a snapshot and releases it afterwards, so memory levels off instead of growing by about 38 MB a check. Checks report the same diagnostics as `Tsrs.check`. They pick up what changed on disk since the last check, including the `tsconfig.json`, and can run from several threads at once.
+
+The project's `tsconfig.json` decides the compiler options: a session check takes none of its own. It never writes anything, and raises `Tsrs::CheckError` when there is no project to load.
+
+#### Compiling
+
+`Tsrs.compile` runs tsc and writes its outputs, the way `tsc` does:
+
+```ruby
+Tsrs.compile(project: "tsconfig.json", declaration: true)
+```
+
+`Tsrs.tsc` takes command-line arguments exactly as `tsc` would:
+
+```ruby
+Tsrs.tsc("--listFilesOnly", cwd: "app/javascript").output
+```
+
+#### Transpiling one file
+
+`Tsrs.transpile` turns one TypeScript source into JavaScript without type checking it, like TypeScript's `transpileModule`. It doesn't look at the file system:
+
+```ruby
+Tsrs.transpile("export const answer: number = 42;", target: "es2020").code
+# => "export const answer = 42;\n"
+
+result = Tsrs.transpile(source, file_name: "app.tsx", jsx: "react-jsx", source_map: true)
+result.code
+result.map
+```
+
+`Tsrs.transpile_declaration` emits the `.d.ts` for a source written for `isolatedDeclarations`:
+
+```ruby
+Tsrs.transpile_declaration("export function greet(name: string): string { return name; }").code
+# => "export declare function greet(name: string): string;\n"
+```
+
+A source that doesn't parse raises `Tsrs::SyntaxError`, which carries the diagnostics.
+
+#### Compiler options
+
+Compiler options are tsc's, written in snake case or as tsc spells them. They are passed to tsc as command-line flags, so tsc reads them the way it always does:
+
+| Ruby | tsc |
+| --- | --- |
+| `strict: true` | `--strict` |
+| `no_emit: false` | `--noEmit false` |
+| `target: "es2022"` | `--target es2022` |
+| `lib: ["es2022", "dom"]` | `--lib es2022,dom` |
+| `"esModuleInterop" => true` | `--esModuleInterop` |
+
+Options that only make sense in a terminal, like `watch`, `build`, `init` and `help`, raise `Tsrs::OptionError`. So does a hash, which tsc's command line can't express. Put options like `paths` in a `tsconfig.json`.
+
+#### Diagnostics
+
+Each `Tsrs::Diagnostic` has a `code`, a `category` (`:error`, `:warning`, `:suggestion` or `:message`), a `message`, a `file`, and a 1-based `line` and `column`. `start` and `finish` are offsets in UTF-16 code units, the unit TypeScript counts in. `message_chain` and `related_information` hold the elaborations tsc attaches, and `to_s` prints a diagnostic the way tsc does.
+
+#### Threads and memory
+
+Every call releases the GVL, so other Ruby threads keep running and several checks can run at once. The work runs on a few long-lived native threads with large stacks, since type checking recurses deeply.
+
+Transpiling gives back all the memory it used, and so does checking with a `Tsrs::Session`. `Tsrs.check`, `Tsrs.compile` and `Tsrs.tsc` don't: tsrs runs them like `tsc`, a process that checks once and exits, so much of what they allocate stays with the process. That's fine for a rake task or CI. In a long-lived process, check with a session instead.
+
+### Development
+
+The gem is a C extension over a Rust crate. `rust/` builds a static library and generates the C header with [cbindgen](https://github.com/mozilla/cbindgen), `ext/tsrs/` wraps it, and `lib/` is the Ruby API over that.
+
+tsrs doesn't publish its crates, so `rust/Cargo.toml` takes them from the release tag on GitHub. `rust/.cargo/config.toml` stamps the TypeScript version the way tsrs's own release builds do. The upstream workflow keeps the tag, that version, and the Rust toolchain in step with each tsrs release.
+
+```bash
+bin/setup
+bundle exec rake
+```
+
+`sig/` is generated from the `#:` annotations next to the code. Regenerate it with `rake rbs` after changing a signature, and CI checks that it matches.
+
+### Acknowledgements
+
+[tsrs](https://github.com/oxc-project/tsrs) is maintained at [oxc-project/tsrs](https://github.com/oxc-project/tsrs), and is a port of [TypeScript](https://github.com/microsoft/TypeScript). This gem only calls into it. Thank you for building these tools!
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/tsrs-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/marcoroth/tsrs-ruby/blob/main/CODE_OF_CONDUCT.md).
+
+Issues with type checking or emit belong [upstream](https://github.com/oxc-project/tsrs/issues), with a minimal reproduction, since this gem does none of that itself. Issues with the Ruby API, the build, or the bindings belong here.
+
+### License
+
+The Ruby, C, and Rust code in this gem is available under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+It builds against [tsrs](https://github.com/oxc-project/tsrs), which is Apache-2.0 licensed and a derivative of TypeScript. Its native extension embeds TypeScript's `lib.*.d.ts` files. tsrs's license and NOTICE travel with the gem in [`licenses/`](licenses).

data/ext/tsrs/extconf.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "fileutils"
+
+ext_dir = __dir__
+root_dir = File.expand_path("../..", ext_dir)
+
+rust_dir = File.join(root_dir, "rust")
+
+unless File.exist?(File.join(rust_dir, "Cargo.toml"))
+  abort <<~MESSAGE
+
+    ERROR: Rust sources not found at #{rust_dir}.
+
+  MESSAGE
+end
+
+unless system("cargo --version > /dev/null 2>&1")
+  abort <<~MESSAGE
+
+    ERROR: Rust toolchain not found.
+
+    tsrs requires the Rust toolchain to compile from source.
+
+    Install Rust: https://rustup.rs
+
+  MESSAGE
+end
+
+RUST_TARGETS = {
+  "aarch64-linux-gnu" => "aarch64-unknown-linux-gnu",
+  "aarch64-linux-musl" => "aarch64-unknown-linux-musl",
+  "arm64-darwin" => "aarch64-apple-darwin",
+  "x86_64-darwin" => "x86_64-apple-darwin",
+  "x86_64-linux-gnu" => "x86_64-unknown-linux-gnu",
+  "x86_64-linux-musl" => "x86_64-unknown-linux-musl",
+}.freeze
+
+cross_compiling = ENV.key?("RUBY_CC_VERSION")
+target_platform = ENV.fetch("CARGO_BUILD_TARGET", nil)
+
+if cross_compiling && target_platform.nil?
+  rcd_platform = ENV.fetch("RCD_PLATFORM", "")
+  target_platform = RUST_TARGETS[rcd_platform]
+
+  if target_platform.nil?
+    ruby_platform = RbConfig::CONFIG["arch"]
+    target_platform = RUST_TARGETS.values.find { |target| ruby_platform.include?(target.split("-").first) }
+  end
+end
+
+header_path = File.join(ext_dir, "include", "tsrs.h")
+
+FileUtils.mkdir_p(File.dirname(header_path))
+
+target_dir = File.join(rust_dir, "target")
+
+if target_platform
+  puts "tsrs: Cross-compiling Rust for target: #{target_platform}"
+
+  system("cd #{rust_dir} && rustup target add #{target_platform}") || warn("tsrs: Failed to add Rust target #{target_platform}")
+
+  cargo_args = "--release --locked --target #{target_platform}"
+  lib_dir = File.join(target_dir, target_platform, "release")
+else
+  puts "tsrs: Compiling Rust library for native platform..."
+
+  cargo_args = "--release --locked"
+  lib_dir = File.join(target_dir, "release")
+end
+
+unless system("cd #{rust_dir} && cargo build #{cargo_args}")
+  abort "ERROR: Failed to compile tsrs from Rust source."
+end
+
+unless File.exist?(header_path)
+  abort "ERROR: cbindgen did not generate #{header_path}. Try `cargo clean` in #{rust_dir} and reinstall."
+end
+
+static_lib = File.join(lib_dir, "libtsrs_ffi.a")
+developing = File.exist?(File.join(root_dir, ".git"))
+
+if File.exist?(static_lib) && !developing
+  vendored = File.join(ext_dir, "libtsrs_ffi.a")
+
+  FileUtils.cp(static_lib, vendored)
+  FileUtils.rm_rf(target_dir)
+
+  puts "tsrs: Static library vendored at #{vendored}, Rust build directory removed"
+
+  $LDFLAGS << " #{vendored}"
+elsif File.exist?(static_lib)
+  puts "tsrs: Static library found at #{static_lib}"
+
+  $LDFLAGS << " #{static_lib}"
+else
+  host_os = target_platform || RbConfig::CONFIG["host_os"]
+
+  lib_name = case host_os
+             when /darwin/
+               "libtsrs_ffi.dylib"
+             when /mingw|mswin|windows/
+               "tsrs_ffi.dll"
+             else
+               "libtsrs_ffi.so"
+             end
+
+  lib_path = File.join(lib_dir, lib_name)
+
+  abort "ERROR: Shared library not found at #{lib_path}" unless File.exist?(lib_path)
+
+  puts "tsrs: Shared library found at #{lib_path} (dynamic)"
+
+  $LDFLAGS << " -L#{lib_dir} -ltsrs_ffi"
+  $LDFLAGS << " -Wl,-rpath,#{lib_dir}" if RbConfig::CONFIG["host_os"].match?(/darwin|linux/)
+end
+
+$CFLAGS << " -I#{ext_dir}"
+
+create_makefile("tsrs/tsrs")

data/ext/tsrs/include/tsrs.h

@@ -0,0 +1,113 @@
+/* Generated by cbindgen, do not edit manually */
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stddef.h>
+
+#ifndef TSRS_H
+#define TSRS_H
+
+typedef enum TsrsErrorCode {
+  TSRS_ERROR_CODE_NONE = 0,
+  TSRS_ERROR_CODE_OPTION,
+  TSRS_ERROR_CODE_ENCODING,
+  TSRS_ERROR_CODE_TRANSPILE,
+  TSRS_ERROR_CODE_CHECK,
+  TSRS_ERROR_CODE_INTERNAL,
+  TSRS_ERROR_CODE_PANIC,
+} TsrsErrorCode;
+
+typedef struct TsrsSession TsrsSession;
+
+typedef struct TsrsResult {
+  char *value;
+  uintptr_t value_len;
+  char *error;
+  enum TsrsErrorCode code;
+} TsrsResult;
+
+/**
+ * # Safety
+ *
+ * `source` and `options_json` must be valid, nul-terminated UTF-8 strings.
+ */
+struct TsrsResult tsrs_transpile(const char *source, const char *options_json);
+
+/**
+ * # Safety
+ *
+ * `source` and `options_json` must be valid, nul-terminated UTF-8 strings.
+ */
+struct TsrsResult tsrs_transpile_declaration(const char *source, const char *options_json);
+
+/**
+ * # Safety
+ *
+ * `options_json` must be a valid, nul-terminated UTF-8 string.
+ */
+struct TsrsResult tsrs_check(const char *options_json);
+
+/**
+ * # Safety
+ *
+ * `cwd` must be a valid, nul-terminated UTF-8 string.
+ */
+struct TsrsSession *tsrs_session_new(const char *cwd);
+
+/**
+ * Taken before a check that runs without the GVL, so that freeing the original meanwhile cannot free the session.
+ *
+ * # Safety
+ *
+ * `session` must be a live pointer from `tsrs_session_new` or `tsrs_session_retain`.
+ */
+struct TsrsSession *tsrs_session_retain(const struct TsrsSession *session);
+
+/**
+ * # Safety
+ *
+ * `session` must be a live pointer from `tsrs_session_new` or `tsrs_session_retain`, and `options_json` a valid,
+ * nul-terminated UTF-8 string.
+ */
+struct TsrsResult tsrs_session_check(const struct TsrsSession *session,
+                                     const char *options_json);
+
+/**
+ * The pointer stays valid until `tsrs_session_free`.
+ *
+ * # Safety
+ *
+ * `session` must be a live pointer from `tsrs_session_new` or `tsrs_session_retain`, or null.
+ */
+void tsrs_session_close(const struct TsrsSession *session);
+
+/**
+ * # Safety
+ *
+ * `session` must be a pointer from `tsrs_session_new` or `tsrs_session_retain` that is not used afterwards, or null.
+ */
+void tsrs_session_free(struct TsrsSession *session);
+
+char *tsrs_version(void);
+
+char *tsrs_tsrs_version(void);
+
+char *tsrs_typescript_version(void);
+
+/**
+ * # Safety
+ *
+ * `value` must be a pointer this library returned, and must not be used afterwards.
+ */
+void tsrs_string_free(char *value);
+
+/**
+ * # Safety
+ *
+ * `result` must be one this library returned, and must not be used afterwards.
+ */
+void tsrs_result_free(struct TsrsResult result);
+
+struct TsrsResult tsrs_panic_for_test(void);
+
+#endif  /* TSRS_H */