@gram-data/tree-sitter-gram 0.2.6 → 0.3.3

package/README.md

@@ -3,34 +3,93 @@
 A [tree-sitter](https://tree-sitter.github.io/tree-sitter/) grammar 
 for [gram](https://gram-data.github.io) notation.
 
-Gram is a subject-based notation for structured data.
+## About Gram
 
-If this is an object:
-```
-{
-  "name":"Andreas",
-  "roles":["author"]
+Gram is a pattern-based notation for structured data.
+
+### Patterns and Subjects
+
+A **pattern** is a generic data structure with a value and nested elements:
+
+```ts
+interface Pattern<V> {
+  value: V;
+  elements: Pattern<V>[];
 }
 ```
 
-Implicitly the object is a person. To become a subject, the implicit
-information can be explicit.
+Gram patterns are always `Pattern<Subject>` — patterns where values are **subjects**.
+A **subject** is content combining an optional identifier, labels, and/or a record of properties.
+
+### Pattern Elements
+
+The `gram_pattern` (top-level structure) consists of a sequence of patterns. Syntactically, `subject_pattern`, `node_pattern`, `relationship_pattern`, and `annotated_pattern` are peers.
 
-As a subject:
+They correlate to the underlying data structure based on the number of elements:
+
+- **Node Pattern** `()`: A pattern with **0 elements**.
+- **Annotated Pattern** `@a (b)`: A pattern with **1 element**.
+- **Relationship Pattern** `(a)-->(b)`: A pattern with **2 elements**.
+- **Subject Pattern** `[ s | ... ]`: A pattern with an **arbitrary number of elements**.
+
+#### Path Flattening
+
+A path is a flattened tree of relationships. For example:
+
+```gram
+(a)-[r1]->(b)-[r2]->(c) 
+// is equivalent to:
+[ | [r1 | (a), (b)], [r2 | (b),(c)] ]
 ```
-(:Person {
-  name: "Andreas",
-  roles: ["author"]
-})
+
+#### Subject Pattern Notation
+
+The subject pattern notation uses `[ subject | elements ]` to explicitly show pattern structure:
+
+```gram
+// A team with members as elements
+[devrel:Team {name: "Developer Relations"} | abk, adam, alex]
+
+// A simple atomic pattern (no elements)
+[:Person {name: "Andreas", roles: ["author"]}]
 ```
 
-Gram files support comments using `//` syntax for line-based and end-of-line comments:
+#### Node Notation (Syntactic Sugar)
+
+Parentheses `( subject )` provide familiar graph node syntax:
+
+```gram
+()                           // Empty node
+(a)                          // Node with identifier
+(a:Person)                   // Node with identifier and label
+(a:Person {name: "Alice"})   // Node with identifier, label, and properties
 ```
+
+#### Relationship Notation (Syntactic Sugar)
+
+Arrows connect nodes to express graph relationships:
+
+```gram
+// Path notation for graph relationships
+(a:Person)-[:KNOWS]->(b:Person)
+
+// Subject Pattern notation can contain path patterns
+[social:Graph | 
+  (a:Person {name: "Alice"}),
+  (b:Person {name: "Bob"}),
+  (a)-[:KNOWS]->(b)
+]
+```
+
+### Comments
+
+Gram files support comments using `//` syntax:
+```gram
 // This is a line comment
 (hello)-->(world)  // End-of-line comment
 ```
 
-Learn more about `gram` at the [gram-data github org](https://github.com/gram-data) notation.
+Learn more about `gram` at the [gram-data github org](https://github.com/gram-data).
 
 ## Editor Support
 

package/bindings/node/binding_test.js

@@ -7,3 +7,31 @@ test("can load grammar", () => {
   const parser = new (require("tree-sitter"))();
   assert.doesNotThrow(() => parser.setLanguage(require(".")));
 });
+
+test("annotation node kinds: identified_annotation and property_annotation", () => {
+  const Parser = require("tree-sitter");
+  const GramLang = require(".");
+  const parser = new Parser();
+  parser.setLanguage(GramLang);
+
+  const annotated = (root) => root.child(0) ?? null;
+
+  const withIdentified = parser.parse("@@p (a)");
+  const ap1 = annotated(withIdentified.rootNode);
+  assert(ap1?.type === "annotated_pattern", "root should have annotated_pattern child");
+  const annotations1 = ap1.childForFieldName("annotations");
+  assert(annotations1, "annotations node should exist");
+  const first1 = annotations1.child(0);
+  assert.strictEqual(first1?.type, "identified_annotation", "@@ form should be identified_annotation");
+  assert(first1?.childForFieldName("identifier"), "identified_annotation should have identifier field");
+
+  const withProperty = parser.parse("@x(1) ()");
+  const ap2 = annotated(withProperty.rootNode);
+  assert(ap2?.type === "annotated_pattern", "root should have annotated_pattern child");
+  const annotations2 = ap2.childForFieldName("annotations");
+  assert(annotations2, "annotations node should exist");
+  const first2 = annotations2.child(0);
+  assert.strictEqual(first2?.type, "property_annotation", "@ form should be property_annotation");
+  assert(first2?.childForFieldName("key"), "property_annotation should have key field");
+  assert(first2?.childForFieldName("value"), "property_annotation should have value field");
+});

package/editors/README.md

@@ -25,7 +25,7 @@ The Zed integration provides full syntax highlighting and language support for G
 
 **Features:**
 - Syntax highlighting for all Gram constructs
-- Bracket matching for `()`, `[]`, and `{}`
+- Subject Pattern matching for `()`, `[]`, and `{}`
 - Automatic file type detection for `.gram` files
 - Proper indentation handling
 

package/editors/zed/README.md

@@ -5,7 +5,7 @@ A [Zed](https://zed.dev) extension providing syntax highlighting and language su
 ## Features
 
 - **Syntax Highlighting**: Full syntax highlighting for all Gram constructs including subjects, nodes, relationships, and data types
-- **Bracket Matching**: Automatic matching for `()`, `[]`, and `{}`
+- **Subject Pattern Matching**: Automatic matching for `()`, `[]`, and `{}`
 - **File Type Detection**: Automatic recognition of `.gram` files
 - **Smart Indentation**: Proper indentation handling for nested structures
 
@@ -53,7 +53,7 @@ Once installed, the extension automatically provides syntax highlighting for any
 })
 
 // Relationships between nodes
-(alice:Person {name: "Alice"})->(bob:Person {name: "Bob"})
+(alice:Person {name: "Alice"})-->(bob:Person {name: "Bob"})
 
 // Complex subject with annotations
 @type("Employee")
@@ -80,7 +80,7 @@ Once installed, the extension automatically provides syntax highlighting for any
 
 The extension provides highlighting for:
 
-- **Brackets**: `[...]` and `[:type ...]` bracket notation (containing subjects)
+- **Subject Patterns**: `[...]` and `[:type ...]` subject pattern notation (containing subjects)
 - **Nodes**: `(...)` parentheses
 - **Relationships**: `->`, `--`, `<-`, `<-->`, etc.
 - **Strings**: Single, double, and backtick quoted strings

package/editors/zed/extension.toml

@@ -1,6 +1,6 @@
 id = "gram"
 name = "Gram Language Support"
-version = "0.2.6"
+version = "0.3.3"
 schema_version = 1
 authors = ["Gram Data Contributors"]
 description = "Support for Gram notation - a subject-oriented notation for structured data"
@@ -8,4 +8,4 @@ description = "Support for Gram notation - a subject-oriented notation for struc
 # path = "grammars/tree-sitter-gram"
 [grammars.gram]
 repository = "https://github.com/gram-data/tree-sitter-gram"
-rev = "7385463cf814f2e880e99c3e1372b4c0765820ad"
+rev = "78fba591ce4e3ca86ae77c871cfc9e87205c8e2b"

package/editors/zed/languages/gram/highlights.scm

@@ -23,7 +23,7 @@
     "::"
 ] @operator
 
-; Brackets and delimiters
+; Subject Patterns and delimiters
 [
     "["
     "]"
@@ -46,10 +46,12 @@
 (map_entry key: (string_literal) @property)
 (map_entry key: (integer) @property)
 
-; Annotation keys
-(annotation key: (symbol) @attribute)
+; Annotation keys (property-style) and headers (identified/label-style)
+(property_annotation key: (symbol) @attribute)
+(identified_annotation identifier: (_) @attribute)
+(identified_annotation labels: (_) @attribute)
 
-; Bracket notation (special highlighting)
+; Subject Pattern notation (special highlighting)
 (subject_pattern) @type
 
 ; Node with labels

package/grammar.js

@@ -7,16 +7,15 @@ module.exports = grammar({
   ],
 
   rules: {
-    // top-level rule, forming an outer pattern shaped like `[ record | sequence-of-top-level-elements ]`
-    gram: ($) => seq(field("root", optional($.record)), repeat($.annotated_pattern)),
+    gram_pattern: ($) => seq(field("root", optional($.record)), repeat($._top_level_pattern)),
+
+    _top_level_pattern: ($) => choice($.annotated_pattern, $.subject_pattern,$.node_pattern, $.relationship_pattern),
 
-    // top-level elements are annotated patterns shaped like `[annotation-record | pattern-elements]`
     annotated_pattern: ($) =>
       seq(
-        field("annotations", optional($.annotations)),
-        field("elements", commaSep1($._annotated_pattern_element)),
+        field("annotations", $.annotations),
+        field("elements", choice($.subject_pattern, $._path_pattern)),
       ),
-    _annotated_pattern_element: ($) => choice($.subject_pattern, $._path_pattern),
 
     subject_pattern: ($) =>
       seq(
@@ -30,11 +29,28 @@ module.exports = grammar({
 
     _subject_pattern_element: ($) => choice($.subject_pattern, $._path_pattern, $.pattern_reference),
 
-    annotations: ($) => repeat1($.annotation),
+    annotations: ($) =>
+      choice(
+        seq($.identified_annotation, repeat($.property_annotation)),
+        repeat1($.property_annotation),
+      ),
 
-    annotation: ($) =>
+    property_annotation: ($) =>
       seq("@", field("key", $.symbol), "(", field("value", $._value), ")"),
 
+    identified_annotation: ($) =>
+      seq(
+        "@@",
+        choice(
+          field("identifier", $._identifier),
+          field("labels", $.labels),
+          seq(
+            field("identifier", $._identifier),
+            field("labels", $.labels),
+          ),
+        ),
+      ),
+
     _path_pattern: ($) => choice($.relationship_pattern, $.node_pattern),
 
     node_pattern: ($) =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gram-data/tree-sitter-gram",
-  "version": "0.2.6",
+  "version": "0.3.3",
   "description": "subject-oriented notation for structured data",
   "homepage": "https://gram-data.github.io",
   "repository": {
@@ -12,6 +12,7 @@
   "scripts": {
     "install": "node-gyp-build",
     "prestart": "tree-sitter build --wasm",
+    "build": "tree-sitter build --wasm",
     "start": "tree-sitter playground",
     "test": "node --test bindings/node/*_test.js",
     "zed:dev": "ZED_REPO_MODE=dev bash scripts/prepare-zed-extension.sh",
@@ -28,12 +29,14 @@
   ],
   "files": [
     "grammar.js",
+    "tree-sitter.json",
     "binding.gyp",
     "prebuilds/**",
     "bindings/node/*",
     "queries/*",
     "src/**",
-    "editors/**"
+    "editors/**",
+    "*.wasm"
   ],
   "author": "",
   "license": "ISC",
@@ -51,8 +54,8 @@
   },
   "devDependencies": {
     "eslint": "^9.37.0",
-    "node-gyp": "^11.4.2",
     "prebuildify": "^6.0.1",
-    "tree-sitter-cli": "^0.25.10"
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-cli": "^0.26.5"
   }
 }

package/queries/highlights.scm

@@ -23,7 +23,7 @@
     "::"
 ] @operator
 
-; Brackets and delimiters
+; Subject Patterns and delimiters
 [
     "["
     "]"
@@ -46,10 +46,12 @@
 (map_entry key: (string_literal) @property)
 (map_entry key: (integer) @property)
 
-; Annotation keys
-(annotation key: (symbol) @attribute)
+; Annotation keys (property-style) and headers (identified/label-style)
+(property_annotation key: (symbol) @attribute)
+(identified_annotation identifier: (_) @attribute)
+(identified_annotation labels: (_) @attribute)
 
-; Bracket notation (special highlighting)
+; Subject Pattern notation (special highlighting)
 (subject_pattern) @type
 
 ; Node with labels

package/src/grammar.json

@@ -2,7 +2,7 @@
   "$schema": "https://tree-sitter.github.io/tree-sitter/assets/schemas/grammar.schema.json",
   "name": "gram",
   "rules": {
-    "gram": {
+    "gram_pattern": {
       "type": "SEQ",
       "members": [
         {
@@ -25,11 +25,32 @@
           "type": "REPEAT",
           "content": {
             "type": "SYMBOL",
-            "name": "annotated_pattern"
+            "name": "_top_level_pattern"
           }
         }
       ]
     },
+    "_top_level_pattern": {
+      "type": "CHOICE",
+      "members": [
+        {
+          "type": "SYMBOL",
+          "name": "annotated_pattern"
+        },
+        {
+          "type": "SYMBOL",
+          "name": "subject_pattern"
+        },
+        {
+          "type": "SYMBOL",
+          "name": "node_pattern"
+        },
+        {
+          "type": "SYMBOL",
+          "name": "relationship_pattern"
+        }
+      ]
+    },
     "annotated_pattern": {
       "type": "SEQ",
       "members": [
@@ -37,62 +58,29 @@
           "type": "FIELD",
           "name": "annotations",
           "content": {
-            "type": "CHOICE",
-            "members": [
-              {
-                "type": "SYMBOL",
-                "name": "annotations"
-              },
-              {
-                "type": "BLANK"
-              }
-            ]
+            "type": "SYMBOL",
+            "name": "annotations"
           }
         },
         {
           "type": "FIELD",
           "name": "elements",
           "content": {
-            "type": "SEQ",
+            "type": "CHOICE",
             "members": [
               {
                 "type": "SYMBOL",
-                "name": "_annotated_pattern_element"
+                "name": "subject_pattern"
               },
               {
-                "type": "REPEAT",
-                "content": {
-                  "type": "SEQ",
-                  "members": [
-                    {
-                      "type": "STRING",
-                      "value": ","
-                    },
-                    {
-                      "type": "SYMBOL",
-                      "name": "_annotated_pattern_element"
-                    }
-                  ]
-                }
+                "type": "SYMBOL",
+                "name": "_path_pattern"
               }
             ]
           }
         }
       ]
     },
-    "_annotated_pattern_element": {
-      "type": "CHOICE",
-      "members": [
-        {
-          "type": "SYMBOL",
-          "name": "subject_pattern"
-        },
-        {
-          "type": "SYMBOL",
-          "name": "_path_pattern"
-        }
-      ]
-    },
     "subject_pattern": {
       "type": "SEQ",
       "members": [
@@ -190,13 +178,34 @@
       ]
     },
     "annotations": {
-      "type": "REPEAT1",
-      "content": {
-        "type": "SYMBOL",
-        "name": "annotation"
-      }
+      "type": "CHOICE",
+      "members": [
+        {
+          "type": "SEQ",
+          "members": [
+            {
+              "type": "SYMBOL",
+              "name": "identified_annotation"
+            },
+            {
+              "type": "REPEAT",
+              "content": {
+                "type": "SYMBOL",
+                "name": "property_annotation"
+              }
+            }
+          ]
+        },
+        {
+          "type": "REPEAT1",
+          "content": {
+            "type": "SYMBOL",
+            "name": "property_annotation"
+          }
+        }
+      ]
     },
-    "annotation": {
+    "property_annotation": {
       "type": "SEQ",
       "members": [
         {
@@ -229,6 +238,57 @@
         }
       ]
     },
+    "identified_annotation": {
+      "type": "SEQ",
+      "members": [
+        {
+          "type": "STRING",
+          "value": "@@"
+        },
+        {
+          "type": "CHOICE",
+          "members": [
+            {
+              "type": "FIELD",
+              "name": "identifier",
+              "content": {
+                "type": "SYMBOL",
+                "name": "_identifier"
+              }
+            },
+            {
+              "type": "FIELD",
+              "name": "labels",
+              "content": {
+                "type": "SYMBOL",
+                "name": "labels"
+              }
+            },
+            {
+              "type": "SEQ",
+              "members": [
+                {
+                  "type": "FIELD",
+                  "name": "identifier",
+                  "content": {
+                    "type": "SYMBOL",
+                    "name": "_identifier"
+                  }
+                },
+                {
+                  "type": "FIELD",
+                  "name": "labels",
+                  "content": {
+                    "type": "SYMBOL",
+                    "name": "labels"
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
     "_path_pattern": {
       "type": "CHOICE",
       "members": [