@gram-data/tree-sitter-gram 0.2.7 → 0.3.4

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/zed/README.md

@@ -115,27 +115,44 @@ To work on this extension:
 
 ```
 editors/zed/
-├── extension.toml           # Extension metadata
-├── grammars/
-│   └── tree-sitter-gram/   # Grammar files
-│       ├── grammar.js      # Tree-sitter grammar definition
-│       └── src/            # Generated parser source
+├── extension.toml          # Extension metadata; points at grammar repo (repository + rev)
 ├── languages/
 │   └── gram/
-│       ├── config.toml     # Language configuration
-│       └── queries/        # Syntax highlighting queries
-│           └── highlights.scm
-└── example.gram            # Example file for testing
+│       ├── config.toml     # Zed language config (brackets, suffixes, etc.)
+│       ├── highlights.scm # → ../../../../queries/ (symlink; edit queries/ in repo root)
+│       ├── indents.scm
+│       ├── locals.scm
+│       └── injections.scm
+├── test.gram               # Example file for testing
+└── .gitignore              # Ignores grammars/ (populated by Zed from extension.toml)
 ```
 
+Query files (`.scm`) in `languages/gram/` are symlinks to the canonical `queries/` directory at the repo root. Edit `queries/*.scm` there; do not edit the copies under `editors/zed` directly. Running `scripts/prepare-zed-extension.sh` copies `queries/*.scm` into this directory (e.g. for distribution) and updates extension version/rev.
+
+The `grammars/` directory is created by Zed when it loads the extension (it clones the grammar from the URL in `extension.toml`). It is gitignored. If you see a nested `editors/zed/grammars/gram/...` path, that is the cloned repo inside Zed’s cache; you can ignore or delete `editors/zed/grammars/` locally.
+
+### Keeping the grammar revision in sync
+
+The extension pins the tree-sitter-gram grammar with `repository` and `rev` in `extension.toml`. Zed uses that to fetch and build the parser. To keep it aligned with the latest version:
+
+| Goal | Command | What it does |
+|------|---------|---------------|
+| **Local testing** | `npm run zed:dev` | Sets `repository = "file://<repo-root>"` and `rev = HEAD`. Zed uses your local clone at the current commit, so you can test grammar/query changes without pushing. |
+| **Prepare for publish** | `npm run zed:publish` | Sets `repository` to the public GitHub URL (from `package.json`) and `rev = HEAD`. Run this before committing a release so the published extension points at the correct commit on GitHub. |
+
+After either command, `extension.toml` is updated in place. For local dev you typically don’t commit that change (so the repo keeps a rev that matches the last release). For a release, run `zed:publish`, then commit and push so the extension and the tagged release stay aligned.
+
+**If Zed shows an old version (e.g. 0.1.11) after installing the dev extension:** Zed may be using a cached clone of the grammar (at an old rev) or an older copy of the extension. Try: (1) Uninstall the Gram extension from Zed’s Extensions panel. (2) Delete the grammar cache: remove `editors/zed/grammars/` if it exists (Zed recreates it when needed). (3) Run `npm run zed:dev` again so `extension.toml` has the current version and rev. (4) In Zed, run “Install Dev Extension” and select `editors/zed` again. Restart Zed and recheck the extension version.
+
 ## Contributing
 
 Contributions are welcome! Please see the main [repository](https://github.com/gram-data/tree-sitter-gram) for contribution guidelines.
 
-To improve syntax highlighting:
-1. Edit `languages/gram/queries/highlights.scm`
-2. Test with various Gram files
-3. Submit a pull request
+To improve syntax highlighting and editor behavior:
+
+1. Edit the canonical query files under `queries/` at the repo root (e.g. `queries/highlights.scm`).
+2. The extension uses those via symlinks in `languages/gram/`; run `scripts/prepare-zed-extension.sh` if you need to copy them for distribution.
+3. Test with various Gram files, then submit a pull request.
 
 ## License
 

package/editors/zed/extension.toml

@@ -1,11 +1,11 @@
 id = "gram"
 name = "Gram Language Support"
-version = "0.2.7"
+version = "0.3.4"
 schema_version = 1
 authors = ["Gram Data Contributors"]
-description = "Support for Gram notation - a subject-oriented notation for structured data"
+description = "Support for Gram notation - composable data patterns"
 
 # path = "grammars/tree-sitter-gram"
 [grammars.gram]
 repository = "https://github.com/gram-data/tree-sitter-gram"
-rev = "a702c249d589daca07380db66c54bcf497d71a38"
+rev = "7aee4c203a5c6ea48660ae6d8af849ed90317bed"

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

@@ -12,7 +12,38 @@
 ; Boolean literals
 (boolean_literal) @boolean
 
-; Symbols and identifiers
+; Comment (FR-003)
+(comment) @comment
+
+; Tagged-string tag distinct from content (FR-002)
+(tagged_string tag: (symbol) @attribute)
+
+; Reference identifier: pattern_reference (FR-001)
+(pattern_reference identifier: (_) @variable)
+
+; Definition-like identifiers (FR-001): @type
+; subject/node subject is _subject (use wildcard _ as it may be hidden in some runtimes)
+(subject_pattern subject: (_ identifier: (_) @type))
+(subject_pattern subject: (_ labels: (labels (symbol) @type)))
+(node_pattern subject: (_ identifier: (_) @type))
+(node_pattern subject: (_ labels: (labels (symbol) @type)))
+(relationship_pattern left: (node_pattern subject: (_ identifier: (_) @type)))
+(relationship_pattern left: (node_pattern subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern right: (node_pattern subject: (_ identifier: (_) @type)))
+(relationship_pattern right: (node_pattern subject: (_ labels: (labels (symbol) @type))))
+; Arrow kind: subject is inside optional brackets on the arrow
+(relationship_pattern kind: (right_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (right_arrow subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern kind: (left_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (left_arrow subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern kind: (undirected_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (undirected_arrow subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ labels: (labels (symbol) @type))))
+(identified_annotation identifier: (_) @type)
+(identified_annotation labels: (labels (symbol) @type))
+
+; Symbols and identifiers (generic; definition/reference/tag captured above)
 (symbol) @variable
 
 ; Keywords and operators
@@ -46,14 +77,8 @@
 (map_entry key: (string_literal) @property)
 (map_entry key: (integer) @property)
 
-; Annotation keys
-(annotation key: (symbol) @attribute)
-
-; Subject Pattern notation (special highlighting)
-(subject_pattern) @type
-
-; Node with labels
-(node_pattern (labels (symbol) @type))
+; Annotation keys (property-style) and headers (identified/label-style)
+(property_annotation key: (symbol) @attribute)
 
 ; Relationship arrows (special highlighting for graph syntax)
 (relationship_pattern) @keyword

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

@@ -0,0 +1,14 @@
+; Indentation: 2 spaces per level for brackets and multi-line structures
+; FR-007 — specs/004-editor-improvements/contracts/indents.md
+
+; Record {}
+"{" @indent
+"}" @indent.end
+
+; Subject pattern []
+"[" @indent
+"]" @indent.end
+
+; Node pattern ()
+"(" @indent
+")" @indent.end

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

@@ -0,0 +1,29 @@
+; Language injection for tagged strings: tag`content` and ```tag\ncontent\n```
+;
+; The tag symbol is used as the injection language so that downstream and editors
+; can support arbitrary tags without changing the grammar. Well-known tags (md, ts,
+; date, datetime, time, sql, json, html, etc.) are documented in docs/tagged-strings-and-injections.md.
+;
+; Overrides below map tags that do not match common parser names. The final
+; rule uses the tag's text as the language name for all other tags (e.g. "sql",
+; "json", "html" often match parser names).
+
+; md -> markdown
+(tagged_string
+  tag: (symbol) @_tag
+  content: (string_content) @injection.content)
+(#eq? @_tag "md")
+(#set! injection.language "markdown")
+
+; ts -> typescript
+(tagged_string
+  tag: (symbol) @_tag
+  content: (string_content) @injection.content)
+(#eq? @_tag "ts")
+(#set! injection.language "typescript")
+
+; Dynamic: use tag text as language name for all other tags (sql, json, html, etc.)
+; Editors may map additional tags (e.g. date, datetime, time) to parsers or leave as plain.
+(tagged_string
+  tag: (symbol) @injection.language
+  content: (string_content) @injection.content)

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

@@ -0,0 +1,28 @@
+; Locals: go to definition and highlight references (file scope)
+; FR-005, FR-006 — specs/004-editor-improvements/contracts/locals.md
+
+; File scope: all definitions and references in one scope
+(gram_pattern) @local.scope
+
+; Definitions: identifiers that define a pattern or annotation
+(subject_pattern subject: (_ identifier: (_) @local.definition))
+(subject_pattern subject: (_ labels: (labels (symbol) @local.definition)))
+(node_pattern subject: (_ identifier: (_) @local.definition))
+(node_pattern subject: (_ labels: (labels (symbol) @local.definition)))
+(relationship_pattern left: (node_pattern subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern left: (node_pattern subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern right: (node_pattern subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern right: (node_pattern subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (right_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (right_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (left_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (left_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (undirected_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (undirected_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(identified_annotation identifier: (_) @local.definition)
+(identified_annotation labels: (labels (symbol) @local.definition))
+
+; References: pattern_reference identifier
+(pattern_reference identifier: (_) @local.reference)

package/grammar.js

@@ -13,11 +13,9 @@ module.exports = grammar({
 
     annotated_pattern: ($) =>
       seq(
-        // field("annotations", optional($.annotations)),
         field("annotations", $.annotations),
         field("elements", choice($.subject_pattern, $._path_pattern)),
       ),
-    // _annotated_pattern_element: ($) => choice($.subject_pattern, $._path_pattern),
 
     subject_pattern: ($) =>
       seq(
@@ -31,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.7",
+  "version": "0.3.4",
   "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

@@ -12,7 +12,38 @@
 ; Boolean literals
 (boolean_literal) @boolean
 
-; Symbols and identifiers
+; Comment (FR-003)
+(comment) @comment
+
+; Tagged-string tag distinct from content (FR-002)
+(tagged_string tag: (symbol) @attribute)
+
+; Reference identifier: pattern_reference (FR-001)
+(pattern_reference identifier: (_) @variable)
+
+; Definition-like identifiers (FR-001): @type
+; subject/node subject is _subject (use wildcard _ as it may be hidden in some runtimes)
+(subject_pattern subject: (_ identifier: (_) @type))
+(subject_pattern subject: (_ labels: (labels (symbol) @type)))
+(node_pattern subject: (_ identifier: (_) @type))
+(node_pattern subject: (_ labels: (labels (symbol) @type)))
+(relationship_pattern left: (node_pattern subject: (_ identifier: (_) @type)))
+(relationship_pattern left: (node_pattern subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern right: (node_pattern subject: (_ identifier: (_) @type)))
+(relationship_pattern right: (node_pattern subject: (_ labels: (labels (symbol) @type))))
+; Arrow kind: subject is inside optional brackets on the arrow
+(relationship_pattern kind: (right_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (right_arrow subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern kind: (left_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (left_arrow subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern kind: (undirected_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (undirected_arrow subject: (_ labels: (labels (symbol) @type))))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ identifier: (_) @type)))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ labels: (labels (symbol) @type))))
+(identified_annotation identifier: (_) @type)
+(identified_annotation labels: (labels (symbol) @type))
+
+; Symbols and identifiers (generic; definition/reference/tag captured above)
 (symbol) @variable
 
 ; Keywords and operators
@@ -46,14 +77,8 @@
 (map_entry key: (string_literal) @property)
 (map_entry key: (integer) @property)
 
-; Annotation keys
-(annotation key: (symbol) @attribute)
-
-; Subject Pattern notation (special highlighting)
-(subject_pattern) @type
-
-; Node with labels
-(node_pattern (labels (symbol) @type))
+; Annotation keys (property-style) and headers (identified/label-style)
+(property_annotation key: (symbol) @attribute)
 
 ; Relationship arrows (special highlighting for graph syntax)
 (relationship_pattern) @keyword

package/queries/indents.scm

@@ -0,0 +1,14 @@
+; Indentation: 2 spaces per level for brackets and multi-line structures
+; FR-007 — specs/004-editor-improvements/contracts/indents.md
+
+; Record {}
+"{" @indent
+"}" @indent.end
+
+; Subject pattern []
+"[" @indent
+"]" @indent.end
+
+; Node pattern ()
+"(" @indent
+")" @indent.end

package/queries/injections.scm

@@ -0,0 +1,29 @@
+; Language injection for tagged strings: tag`content` and ```tag\ncontent\n```
+;
+; The tag symbol is used as the injection language so that downstream and editors
+; can support arbitrary tags without changing the grammar. Well-known tags (md, ts,
+; date, datetime, time, sql, json, html, etc.) are documented in docs/tagged-strings-and-injections.md.
+;
+; Overrides below map tags that do not match common parser names. The final
+; rule uses the tag's text as the language name for all other tags (e.g. "sql",
+; "json", "html" often match parser names).
+
+; md -> markdown
+(tagged_string
+  tag: (symbol) @_tag
+  content: (string_content) @injection.content)
+(#eq? @_tag "md")
+(#set! injection.language "markdown")
+
+; ts -> typescript
+(tagged_string
+  tag: (symbol) @_tag
+  content: (string_content) @injection.content)
+(#eq? @_tag "ts")
+(#set! injection.language "typescript")
+
+; Dynamic: use tag text as language name for all other tags (sql, json, html, etc.)
+; Editors may map additional tags (e.g. date, datetime, time) to parsers or leave as plain.
+(tagged_string
+  tag: (symbol) @injection.language
+  content: (string_content) @injection.content)

package/queries/locals.scm

@@ -0,0 +1,28 @@
+; Locals: go to definition and highlight references (file scope)
+; FR-005, FR-006 — specs/004-editor-improvements/contracts/locals.md
+
+; File scope: all definitions and references in one scope
+(gram_pattern) @local.scope
+
+; Definitions: identifiers that define a pattern or annotation
+(subject_pattern subject: (_ identifier: (_) @local.definition))
+(subject_pattern subject: (_ labels: (labels (symbol) @local.definition)))
+(node_pattern subject: (_ identifier: (_) @local.definition))
+(node_pattern subject: (_ labels: (labels (symbol) @local.definition)))
+(relationship_pattern left: (node_pattern subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern left: (node_pattern subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern right: (node_pattern subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern right: (node_pattern subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (right_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (right_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (left_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (left_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (undirected_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (undirected_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ identifier: (_) @local.definition)))
+(relationship_pattern kind: (bidirectional_arrow subject: (_ labels: (labels (symbol) @local.definition))))
+(identified_annotation identifier: (_) @local.definition)
+(identified_annotation labels: (labels (symbol) @local.definition))
+
+; References: pattern_reference identifier
+(pattern_reference identifier: (_) @local.reference)

package/src/grammar.json

@@ -178,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": [
         {
@@ -217,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": [