MacOS Lark fix

Author: debritto

CHANGELOG.md

@@ -5,6 +5,17 @@ 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 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.11] - 2026-03-06
+
+### Fixed
+- `transformer.py`: replaced `@v_args(meta=True)` with `@v_args(tree=True)` in all 10
+  Transformer methods to fix cross-platform incompatibility. Different Lark builds (e.g.
+  Homebrew on macOS vs pip on Windows) pass arguments to `_vargs_meta` in opposite orders
+  (`f(children, meta)` vs `f(meta, children)`). `@v_args(tree=True)` passes a single
+  `Tree` object whose `.meta` and `.children` attributes are always stable, eliminating the
+  build-dependent argument-order ambiguity that caused `'Meta' object is not subscriptable`
+  on macOS.
+
 ## [0.2.10] - 2026-02-24
 
 ### Fixed

bug-report-lark-vargs-meta.md

@@ -0,0 +1,148 @@
+# Bug Report: `'Meta' object is not subscriptable` ao compilar no macOS
+
+## Sumário
+
+O compilador Synesis falhava com `VisitError: 'Meta' object is not subscriptable` em qualquer
+tentativa de compilação (`synesis compile`), enquanto funcionava normalmente no Windows.
+A causa raiz foi uma **mudança backwards-incompatible na API do Lark** entre versões,
+que inverteu a ordem dos argumentos em métodos decorados com `@v_args(meta=True)`.
+
+---
+
+## Sintoma
+
+```
+erro: Falha inesperada durante compilacao: Error trying to process rule "include_stmt":
+'Meta' object is not subscriptable
+```
+
+Qualquer arquivo `.synp` falhava na compilação. O erro ocorria em `include_stmt`, mas
+todos os demais métodos com `@v_args(meta=True)` tinham o mesmo problema latente.
+
+---
+
+## Causa Raiz
+
+### A API do Lark mudou a ordem dos argumentos em `@v_args(meta=True)`
+
+O decorador `@v_args(meta=True)` instrui o Lark a passar o objeto `Meta` (com informações
+de posição — linha, coluna) para o método do Transformer além da lista `items`.
+
+O código do Synesis foi escrito assumindo a assinatura:
+
+```python
+@v_args(meta=True)
+def include_stmt(self, meta: Any, items: List[Any]) -> Any:
+    ...
+```
+
+Porém, no Lark **1.2.x e superior**, a função interna `_vargs_meta` chama o método com
+a ordem **invertida** — `items` primeiro, `meta` segundo:
+
+```python
+# lark/visitors.py — Lark 1.3.1
+def _vargs_meta(f, _data, children, meta):
+    return f(children, meta)   # TODO swap these for consistency? Backwards incompatible!
+```
+
+O próprio comentário no código-fonte do Lark (`# TODO swap these for consistency?
+Backwards incompatible!`) confirma que esta foi uma mudança intencional e quebrou a
+compatibilidade com código escrito para versões anteriores.
+
+### Por que funcionava no Windows?
+
+O ambiente Windows tinha uma versão **mais antiga do Lark** instalada (provavelmente
+`1.1.x`), onde a ordem era `f(meta, children)` — compatível com a assinatura original
+do Synesis. O macOS tinha o Lark **1.3.1** instalado, onde a ordem já é `f(children, meta)`.
+
+---
+
+## Versões Envolvidas
+
+| Ambiente | Lark    | Resultado       |
+|----------|---------|-----------------|
+| Windows  | ~1.1.x  | Compilava OK    |
+| macOS    | 1.3.1   | Falha com erro  |
+
+O `pyproject.toml` do Synesis especifica apenas `lark >= 1.1`, permitindo qualquer versão
+a partir de 1.1 — o que expõe o projeto à quebra silenciosa quando o Lark é atualizado.
+
+---
+
+## Correção Aplicada
+
+Todos os 10 métodos afetados em `synesis/parser/transformer.py` tiveram a ordem dos
+parâmetros corrigida de `(self, meta, items)` para `(self, items, meta)`:
+
+```python
+# ANTES (assinatura para Lark < ~1.2)
+@v_args(meta=True)
+def include_stmt(self, meta: Any, items: List[Any]) -> Any:
+
+# DEPOIS (assinatura correta para Lark 1.2+)
+@v_args(meta=True)
+def include_stmt(self, items: List[Any], meta: Any) -> Any:
+```
+
+### Métodos corrigidos
+
+1. `project_block`
+2. `include_stmt`
+3. `source_block`
+4. `item_block`
+5. `ontology_block`
+6. `template_header`
+7. `field_def_block`
+8. `value_entry`
+9. `field_entry`
+10. `chain_expr`
+
+---
+
+## Como Reproduzir / Testar no Windows
+
+### 1. Verificar a versão atual do Lark instalada
+
+```bash
+pip show lark
+```
+
+Se a versão for **menor que 1.2.x**, o bug não aparece com o código antigo — mas aparecerá
+assim que o Lark for atualizado.
+
+### 2. Reproduzir o bug (com o código original, antes da correção)
+
+```bash
+pip install "lark==1.3.1"
+synesis compile project.synp --stats
+# Esperado: erro 'Meta' object is not subscriptable
+```
+
+### 3. Verificar que a correção resolve
+
+```bash
+# Após aplicar o patch em transformer.py:
+synesis compile project.synp --stats
+# Esperado: Stats com sources, items, ontologies, etc.
+```
+
+### 4. Fixar a versão mínima do Lark no `pyproject.toml`
+
+Para evitar que o bug retorne, recomenda-se atualizar a restrição de dependência:
+
+```toml
+# pyproject.toml — ANTES
+"lark >= 1.1"
+
+# pyproject.toml — DEPOIS
+"lark >= 1.2"
+```
+
+---
+
+## Referência
+
+- Código afetado: `synesis/parser/transformer.py`
+- Função interna do Lark: `lark.visitors._vargs_meta`
+- Comportamento documentado (implicitamente) no comentário do código-fonte do Lark:
+  `# TODO swap these for consistency? Backwards incompatible!`

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "synesis"
-version = "0.2.10"
+version = "0.2.11"
 description = "The confluence of information into intelligence - A DSL compiler that transforms qualitative research annotations into canonical knowledge structures"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,7 +13,7 @@ authors = [
     {name = "De Britto, Christian Maciel", email = "chriseana@gmail.com"}
 ]
 maintainers = [
-    {name = "Synesis Language Organization", email = "synesis-lang@users.noreply.github.com"}
+    {name = "Synesis Language Organization", email = "chriseana@gmail.com"}
 ]
 keywords = [
     "qualitative-research",

synesis/parser/transformer.py

@@ -381,8 +381,10 @@ def KW_TOPIC(self, token: Token) -> str:  # noqa: N802
     def COMPARATOR(self, token: Token) -> str:  # noqa: N802
         return token.value
 
-    @v_args(meta=True)
-    def project_block(self, meta: Any, items: List[Any]) -> ProjectNode:
+    @v_args(tree=True)
+    def project_block(self, tree: Any) -> ProjectNode:
+        meta = tree.meta
+        items = tree.children
         name = items[1]
         template_path: Optional[Path] = None
         include_nodes: List[IncludeNode] = []
@@ -458,13 +460,15 @@ def includes(self, items: List[Any]) -> Tuple[Optional[Path], List[IncludeNode]]
 
         return (template_path, include_nodes)
 
-    @v_args(meta=True)
-    def include_stmt(self, meta: Any, items: List[Any]) -> Any:
+    @v_args(tree=True)
+    def include_stmt(self, tree: Any) -> Any:
         """
         Grammar: include_stmt: KW_TEMPLATE STRING NEWLINE | KW_INCLUDE include_type STRING NEWLINE
         For TEMPLATE: items = [KW_TEMPLATE, STRING, NEWLINE] = ["TEMPLATE", string, newline]
         For INCLUDE: items = [KW_INCLUDE, include_type, STRING, NEWLINE] = ["INCLUDE", type_str, string, newline]
         """
+        meta = tree.meta
+        items = tree.children
         if items[0] == "TEMPLATE":
             return ("TEMPLATE", _strip_quotes(items[1]), _source_location(self.file_path, meta))
         # items = ["INCLUDE", include_type_result, STRING]
@@ -525,8 +529,10 @@ def description(self, items: List[Any]) -> str:
     def description_lines(self, items: List[Any]) -> List[Any]:
         return items
 
-    @v_args(meta=True)
-    def source_block(self, meta: Any, items: List[Any]) -> SourceNode:
+    @v_args(tree=True)
+    def source_block(self, tree: Any) -> SourceNode:
+        meta = tree.meta
+        items = tree.children
         bibref = items[1]
         field_entries = items[2:-2]
         fields: Dict[str, Any] = {}
@@ -546,8 +552,10 @@ def source_block(self, meta: Any, items: List[Any]) -> SourceNode:
             location=_source_location(self.file_path, meta),
         )
 
-    @v_args(meta=True)
-    def item_block(self, meta: Any, items: List[Any]) -> ItemNode:
+    @v_args(tree=True)
+    def item_block(self, tree: Any) -> ItemNode:
+        meta = tree.meta
+        items = tree.children
         bibref = items[1]
         field_entries = items[2:-2]
         quote = ""
@@ -613,8 +621,10 @@ def item_block(self, meta: Any, items: List[Any]) -> ItemNode:
             location=_source_location(self.file_path, meta),
         )
 
-    @v_args(meta=True)
-    def ontology_block(self, meta: Any, items: List[Any]) -> OntologyNode:
+    @v_args(tree=True)
+    def ontology_block(self, tree: Any) -> OntologyNode:
+        meta = tree.meta
+        items = tree.children
         concept = items[1].strip()
         field_entries = items[2:-2]
         description = ""
@@ -653,8 +663,10 @@ def ontology_block(self, meta: Any, items: List[Any]) -> OntologyNode:
     def concept_name(self, items: List[Any]) -> str:
         return str(items[0]).strip()
 
-    @v_args(meta=True)
-    def template_header(self, meta: Any, items: List[Any]) -> Dict[str, Any]:
+    @v_args(tree=True)
+    def template_header(self, tree: Any) -> Dict[str, Any]:
+        meta = tree.meta
+        items = tree.children
         name = items[1]
         metadata: Dict[str, Any] = {}
         for item in items[2:]:
@@ -720,8 +732,10 @@ def field_names(self, items: List[Any]) -> List[str]:
     def field_key(self, items: List[Any]) -> str:
         return items[0]
 
-    @v_args(meta=True)
-    def field_def_block(self, meta: Any, items: List[Any]) -> FieldSpec:
+    @v_args(tree=True)
+    def field_def_block(self, tree: Any) -> FieldSpec:
+        meta = tree.meta
+        items = tree.children
         name = _normalize_field_name(items[1])
         type_spec = next(item for item in items if isinstance(item, FieldType))
         props = [item for item in items if isinstance(item, tuple)]
@@ -794,8 +808,10 @@ def value_list(self, items: List[Any]) -> List[OrderedValue]:
             if not (isinstance(item, Token) and item.type in {"NEWLINE", "_INDENT", "_DEDENT"})
         ]
 
-    @v_args(meta=True)
-    def value_entry(self, meta: Any, items: List[Any]) -> OrderedValue:
+    @v_args(tree=True)
+    def value_entry(self, tree: Any) -> OrderedValue:
+        meta = tree.meta
+        items = tree.children
         index = -1
         if len(items) == 3:
             index = int(items[0])
@@ -826,8 +842,10 @@ def relation_list(self, items: List[Any]) -> Dict[str, str]:
     def relation_entry(self, items: List[Any]) -> Tuple[str, str]:
         return items[0], items[1]
 
-    @v_args(meta=True)
-    def field_entry(self, meta: Any, items: List[Any]) -> Tuple[str, Any, SourceLocation]:
+    @v_args(tree=True)
+    def field_entry(self, tree: Any) -> Tuple[str, Any, SourceLocation]:
+        meta = tree.meta
+        items = tree.children
         name = _normalize_field_name(items[0])
         location = _source_location(self.file_path, meta)
         cleaned = [
@@ -937,8 +955,8 @@ def text_block(self, items: List[Any]) -> List[Any]:
             if not (isinstance(item, Token) and item.type == "NEWLINE")
         ]
 
-    @v_args(meta=True)
-    def chain_expr(self, meta: Any, items: List[Any]) -> ChainNode:
+    @v_args(tree=True)
+    def chain_expr(self, tree: Any) -> ChainNode:
         """
         Parseia chain_expr da gramatica.
 
@@ -952,6 +970,8 @@ def chain_expr(self, meta: Any, items: List[Any]) -> ChainNode:
         Por ora, armazenamos todos os elementos em nodes e deixamos relations vazio.
         O validator.validate_chain() faz a separacao correta.
         """
+        meta = tree.meta
+        items = tree.children
         elements: List[str] = []
         locations: List[SourceLocation] = []
         for item in items: