feat!: introduce parser introspection via the repo's Semantic Version baked in

lib/binding_rust/bindings.rs

@@ -1,7 +1,7 @@
 /* automatically generated by rust-bindgen 0.69.4 */
 
-pub const TREE_SITTER_LANGUAGE_VERSION: u32 = 14;
-pub const TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION: u32 = 13;
+pub const TREE_SITTER_LANGUAGE_VERSION: u32 = 15;
+pub const TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION: u32 = 15;
 pub type TSStateId = u16;
 pub type TSSymbol = u16;
 pub type TSFieldId = u16;
@@ -721,7 +721,11 @@ extern "C" {
 }
 extern "C" {
     #[doc = " Get the ABI version number for this language. This version number is used\n to ensure that languages were generated by a compatible version of\n Tree-sitter.\n\n See also [`ts_parser_set_language`]."]
-    pub fn ts_language_version(self_: *const TSLanguage) -> u32;
+    pub fn ts_language_abi_version(self_: *const TSLanguage) -> u32;
+}
+extern "C" {
+    #[doc = " Get the [Semantic Version](https://semver.org/) for this language. This\n version number is used to signal if a given parser might be incompatible\n with existing queries when upgraded between major versions.\n\n The Semantic Version is encoded as an unsigned 32-bit integer, where the\n major, minor, and patch version numbers are encoded in the 24 least significant\n bits of the integer, using 8 bits for each number.\n\n Layout of the returned integer:\n\n MSB                               LSB\n +--------+--------+--------+--------+\n |00000000|  Major |  Minor |  Patch |\n +--------+--------+--------+--------+\n 31      24 23    16 15     8 7      0\n"]
+    pub fn ts_language_semantic_version(self_: *const TSLanguage) -> u32;
 }
 extern "C" {
     #[doc = " Get the next parse state. Combine this with lookahead iterators to generate\n completion suggestions or valid symbols in error nodes. Use\n [`ts_node_grammar_symbol`] for valid symbols."]

lib/binding_rust/lib.rs

@@ -282,10 +282,31 @@ pub struct LossyUtf8<'a> {
 impl Language {
     /// Get the ABI version number that indicates which version of the Tree-sitter CLI
     /// that was used to generate this [`Language`].
-    #[doc(alias = "ts_language_version")]
+    #[doc(alias = "ts_language_abi_version")]
     #[must_use]
-    pub fn version(&self) -> usize {
-        unsafe { ffi::ts_language_version(self.0) as usize }
+    pub fn abi_version(&self) -> usize {
+        unsafe { ffi::ts_language_abi_version(self.0) as usize }
+    }
+
+    /// Get the [Semantic Version](https://semver.org/) for this language. This
+    /// version number is used to signal if a given parser might be incompatible
+    /// with existing queries when upgraded between major versions.
+    ///
+    /// The Semantic Version is encoded as an unsigned 32-bit integer, where the
+    /// major, minor, and patch version numbers are encoded in the 24 least significant
+    /// bits of the integer, using 8 bits for each number.
+    ///
+    /// Layout of the returned integer:
+    ///
+    /// MSB                               LSB
+    /// +--------+--------+--------+--------+
+    /// |00000000|  Major |  Minor |  Patch |
+    /// +--------+--------+--------+--------+
+    /// 31      24 23    16 15     8 7      0
+    #[doc(alias = "ts_language_semantic_version")]
+    #[must_use]
+    pub fn semantic_version(&self) -> usize {
+        unsafe { ffi::ts_language_semantic_version(self.0) as usize }
     }
 
     /// Get the number of distinct node types in this language.
@@ -448,7 +469,7 @@ impl Parser {
     /// [`MIN_COMPATIBLE_LANGUAGE_VERSION`](MIN_COMPATIBLE_LANGUAGE_VERSION) constants.
     #[doc(alias = "ts_parser_set_language")]
     pub fn set_language(&mut self, language: &Language) -> Result<(), LanguageError> {
-        let version = language.version();
+        let version = language.abi_version();
         if (MIN_COMPATIBLE_LANGUAGE_VERSION..=LANGUAGE_VERSION).contains(&version) {
             unsafe {
                 ffi::ts_parser_set_language(self.0.as_ptr(), language.0);
@@ -1728,7 +1749,7 @@ impl Query {
                     column: 0,
                     offset: 0,
                     message: LanguageError {
-                        version: language.version(),
+                        version: language.abi_version(),
                     }
                     .to_string(),
                     kind: QueryErrorKind::Language,

lib/binding_web/binding.js

@@ -48,10 +48,10 @@ class ParserImpl {
       language = null;
     } else if (language.constructor === Language) {
       address = language[0];
-      const version = C._ts_language_version(address);
+      const version = C._ts_language_abi_version(address);
       if (version < MIN_COMPATIBLE_VERSION || VERSION < version) {
         throw new Error(
-          `Incompatible language version ${version}. ` +
+          `Incompatible language abi version ${version}. ` +
           `Compatibility range ${MIN_COMPATIBLE_VERSION} through ${VERSION}.`,
         );
       }
@@ -680,8 +680,12 @@ class Language {
     }
   }
 
-  get version() {
-    return C._ts_language_version(this[0]);
+  get abiVersion() {
+    return C._ts_language_abi_version(this[0]);
+  }
+
+  get semanticVersion() {
+    return C._ts_language_semantic_version(this[0]);
   }
 
   get fieldCount() {

lib/include/tree_sitter/api.h

@@ -9,9 +9,9 @@
 extern "C" {
 #endif
 
-#include <stdlib.h>
-#include <stdint.h>
 #include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
 
 /****************************/
 /* Section - ABI Versioning */
@@ -24,13 +24,13 @@ extern "C" {
  * The Tree-sitter library is generally backwards-compatible with languages
  * generated using older CLI versions, but is not forwards-compatible.
  */
-#define TREE_SITTER_LANGUAGE_VERSION 14
+#define TREE_SITTER_LANGUAGE_VERSION 15
 
 /**
  * The earliest ABI version that is supported by the current version of the
  * library.
  */
-#define TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION 13
+#define TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION 15
 
 /*******************/
 /* Section - Types */
@@ -1079,7 +1079,27 @@ TSSymbolType ts_language_symbol_type(const TSLanguage *self, TSSymbol symbol);
  *
  * See also [`ts_parser_set_language`].
  */
-uint32_t ts_language_version(const TSLanguage *self);
+uint32_t ts_language_abi_version(const TSLanguage *self);
+
+/**
+ * Get the [Semantic Version](https://semver.org/) for this language. This
+ * version number is used to signal if a given parser might be incompatible
+ * with existing queries when upgraded between major versions.
+ *
+ * The Semantic Version is encoded as an unsigned 32-bit integer, where the
+ * major, minor, and patch version numbers are encoded in the 24 least significant
+ * bits of the integer, using 8 bits for each number.
+ *
+ * Layout of the returned integer:
+ *
+ * MSB                               LSB
+ * +--------+--------+--------+--------+
+ * |00000000|  Major |  Minor |  Patch |
+ * +--------+--------+--------+--------+
+ * 31      24 23    16 15     8 7      0
+ *
+ */
+uint32_t ts_language_semantic_version(const TSLanguage *self);
 
 /**
  * Get the next parse state. Combine this with lookahead iterators to generate

lib/src/language.c

@@ -24,8 +24,12 @@ uint32_t ts_language_state_count(const TSLanguage *self) {
   return self->state_count;
 }
 
-uint32_t ts_language_version(const TSLanguage *self) {
-  return self->version;
+uint32_t ts_language_abi_version(const TSLanguage *self) {
+  return self->abi_version;
+}
+
+uint32_t ts_language_semantic_version(const TSLanguage *self) {
+    return self->major_version << 16 | self->minor_version << 8 | self->patch_version;
 }
 
 uint32_t ts_language_field_count(const TSLanguage *self) {

lib/src/language.h

@@ -186,7 +186,7 @@ static inline bool ts_language_state_is_primary(
   const TSLanguage *self,
   TSStateId state
 ) {
-  if (self->version >= 14) {
+  if (self->abi_version >= 14) {
     return state == self->primary_state_ids[state];
   } else {
     return true;

lib/src/parser.c

@@ -1875,8 +1875,8 @@ bool ts_parser_set_language(TSParser *self, const TSLanguage *language) {
 
   if (language) {
     if (
-      language->version > TREE_SITTER_LANGUAGE_VERSION ||
-      language->version < TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION
+      language->abi_version > TREE_SITTER_LANGUAGE_VERSION ||
+      language->abi_version < TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION
     ) return false;
 
     if (ts_language_is_wasm(language)) {

lib/src/parser.h

@@ -110,7 +110,7 @@ typedef union {
 } TSParseActionEntry;
 
 struct TSLanguage {
-  uint32_t version;
+  uint32_t abi_version;
   uint32_t symbol_count;
   uint32_t alias_count;
   uint32_t token_count;
@@ -146,6 +146,9 @@ struct TSLanguage {
     void (*deserialize)(void *, const char *, unsigned);
   } external_scanner;
   const TSStateId *primary_state_ids;
+  uint32_t major_version;
+  uint32_t minor_version;
+  uint32_t patch_version;
 };
 
 /*

lib/src/query.c

@@ -2677,8 +2677,8 @@ TSQuery *ts_query_new(
 ) {
   if (
     !language ||
-    language->version > TREE_SITTER_LANGUAGE_VERSION ||
-    language->version < TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION
+    language->abi_version > TREE_SITTER_LANGUAGE_VERSION ||
+    language->abi_version < TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION
   ) {
     *error_type = TSQueryErrorLanguage;
     return NULL;

lib/src/wasm.c

@@ -1188,7 +1188,7 @@ const TSLanguage *ts_wasm_store_load_language(
     );
   }
 
-  if (language->version >= 14) {
+  if (language->abi_version >= 14) {
     language->primary_state_ids = copy(
       &memory[wasm_language.primary_state_ids],
       wasm_language.state_count * sizeof(TSStateId)