tree-sitter-hledger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Patrick Timoney
+
+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.

package/README.md

@@ -0,0 +1,154 @@
+# tree-sitter-hledger
+
+A [tree-sitter](https://tree-sitter.github.io/) grammar for [hledger](https://hledger.org/) journal files.
+
+## About
+
+This is a standalone tree-sitter parser for hledger's plain text accounting format. It provides fast, incremental syntax parsing suitable for:
+
+- Syntax highlighting in editors (Neovim, Zed, Helix, etc.)
+- Code folding and structural navigation
+- Building editor integrations
+- Analysis and tooling
+
+This parser complements the existing [hledger-lsp](../hledger-lsp) language server by providing syntax-level parsing that can be used independently or integrated into editors that support tree-sitter.
+
+## Features
+
+**Transactions:**
+- Dates with flexible formats (`2024-01-15`, `2024.1.5`, `01/15`, `1-5`)
+- Status markers (`*` cleared, `!` pending)
+- Transaction codes (`(#123)`)
+- Descriptions
+- Inline comments with tags (`; category:food, project:home`)
+
+**Postings:**
+- Account names (including spaces)
+- Amounts with various formats:
+  - Symbol on left: `$100`, `-$50`, `$-25`
+  - Symbol on right: `100 USD`, `-50 EUR`
+  - No symbol: `100`, `-50.00`
+- Cost notation: `@ $1.50` (unit cost), `@@ $150` (total cost)
+- Balance assertions: `= $1000`
+- Inline comments with tags
+
+**Commodities:**
+- Currency symbols: `$`, `€`, `£`, `¥`, etc.
+- Alphabetic codes: `USD`, `EUR`, `BTC`
+- Quoted symbols: `"AAPL US Equity"`
+
+**Directives:**
+- `account` - Account declarations
+- `commodity` - Commodity declarations
+- `include` - File includes
+- `payee` - Payee declarations
+- `tag` - Tag declarations
+
+**Comments:**
+- Line comments: `;` or `#`
+- Block comments: `comment` ... `end comment`
+- Inline comments with tag parsing
+
+**Structure:**
+- Indentation-based posting blocks
+- Code folding support
+- Syntax highlighting queries
+
+## Future Enhancements
+- Automated transaction rules (`=`)
+- Periodic transactions (`~`)
+- Additional directives (alias, apply account, etc.)
+- Multi-line commodity format blocks
+
+## Usage
+
+### Parse a Journal File
+
+```bash
+npx tree-sitter parse examples/simple.journal
+```
+
+### Test the Grammar
+
+```bash
+npm test
+```
+
+### Development
+
+```bash
+# Generate parser from grammar
+npm run build
+
+# Test parser
+npm test
+```
+
+## Grammar Overview
+
+**Transactions:**
+```hledger
+2024-01-05 * Groceries  ; category:food
+    Expenses:Food:Groceries    $50.00
+    Assets:Checking           -$50.00  ; cleared:yes
+```
+
+**Costs and Assertions:**
+```hledger
+2024-01-10 * Currency Exchange
+    Assets:EUR    100 EUR @ $1.10
+    Assets:USD   -$110.00 = $500.00
+```
+
+**Directives:**
+```hledger
+account Assets:Checking
+commodity $1000.00
+payee Whole Foods
+include expenses.journal
+```
+
+**Comments:**
+```hledger
+; Line comment
+# Another style
+
+comment
+This is a block comment.
+Multiple lines are supported.
+end comment
+```
+
+## Syntax Highlighting
+
+The parser includes syntax highlighting queries in `queries/highlights.scm`:
+
+| Element | Highlight Group |
+|---------|----------------|
+| Dates | `@keyword.date` |
+| Status markers (`*`, `!`) | `@keyword.modifier` |
+| Account names | `@type` |
+| Quantities | `@number` |
+| Commodities | `@constant` |
+| Directives | `@keyword.directive` |
+| Comments | `@comment` |
+| Tags | `@tag` / `@property` |
+| Operators (`@`, `=`) | `@operator` |
+
+## Related Projects
+
+- [hledger-lsp](../hledger-lsp) - Language Server Protocol implementation for hledger
+- [hledger-vscode](../hledger-vscode) - VS Code extension
+- [hledger-nvim](../hledger-nvim) - Neovim plugin
+
+## Development
+
+See [CLAUDE.md](CLAUDE.md) for detailed development guidance.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.

package/binding.gyp

@@ -0,0 +1,19 @@
+{
+  "targets": [
+    {
+      "target_name": "tree_sitter_hledger_binding",
+      "include_dirs": [
+        "<!(node -e \"require('nan')\")",
+        "src"
+      ],
+      "sources": [
+        "bindings/node/binding.cc",
+        "src/parser.c",
+        "src/scanner.c"
+      ],
+      "cflags_c": [
+        "-std=c99"
+      ]
+    }
+  ]
+}

package/bindings/node/binding.cc

@@ -0,0 +1,28 @@
+#include "tree_sitter/parser.h"
+#include <node.h>
+#include "nan.h"
+
+using namespace v8;
+
+extern "C" TSLanguage * tree_sitter_hledger();
+
+namespace {
+
+NAN_METHOD(New) {}
+
+void Init(Local<Object> exports, Local<Object> module) {
+  Local<FunctionTemplate> tpl = Nan::New<FunctionTemplate>(New);
+  tpl->SetClassName(Nan::New("Language").ToLocalChecked());
+  tpl->InstanceTemplate()->SetInternalFieldCount(1);
+
+  Local<Function> constructor = Nan::GetFunction(tpl).ToLocalChecked();
+  Local<Object> instance = constructor->NewInstance(Nan::GetCurrentContext()).ToLocalChecked();
+  Nan::SetInternalFieldPointer(instance, 0, tree_sitter_hledger());
+
+  Nan::Set(instance, Nan::New("name").ToLocalChecked(), Nan::New("hledger").ToLocalChecked());
+  Nan::Set(module, Nan::New("exports").ToLocalChecked(), instance);
+}
+
+NODE_MODULE(tree_sitter_hledger_binding, Init)
+
+}  // namespace

package/bindings/node/index.js

@@ -0,0 +1,19 @@
+try {
+  module.exports = require("../../build/Release/tree_sitter_hledger_binding");
+} catch (error1) {
+  if (error1.code !== 'MODULE_NOT_FOUND') {
+    throw error1;
+  }
+  try {
+    module.exports = require("../../build/Debug/tree_sitter_hledger_binding");
+  } catch (error2) {
+    if (error2.code !== 'MODULE_NOT_FOUND') {
+      throw error2;
+    }
+    throw error1
+  }
+}
+
+try {
+  module.exports.nodeTypeInfo = require("../../src/node-types.json");
+} catch (_) {}

package/grammar.js

@@ -0,0 +1,236 @@
+module.exports = grammar({
+  name: 'hledger',
+
+  externals: $ => [
+    $.indent,
+    $.dedent,
+    $._newline,
+  ],
+
+  extras: _ => [
+    /[ \t]/,  // Allow spaces and tabs as whitespace, but NOT newlines
+  ],
+
+  rules: {
+    source_file: $ => repeat($._item),
+
+    _item: $ => choice(
+      $._blank_line,
+      $._comment,
+      $.transaction,
+      $._directive,
+    ),
+
+    // Blank line (just newline)
+    _blank_line: $ => $._newline,
+
+    // Comments
+    _comment: $ => choice(
+      $.line_comment,
+      $.block_comment,
+    ),
+
+    line_comment: $ => seq(
+      /[;#][^\n]*/,
+      $._newline,
+    ),
+
+    block_comment: $ => seq(
+      'comment',
+      $._newline,
+      repeat(
+        seq(/[^\n]*/, $._newline)
+      ),
+      'end comment',
+      $._newline,
+    ),
+
+    inline_comment: $ => seq(
+      ';',
+      repeat(
+        choice(
+          $.tag,
+          ',',
+          $._word,  // Non-tag words
+          'comment',     // Allow block_comment keyword as text
+          'end',         // Allow 'end' keyword as text
+          /:[,\s\n]/,    // Colon followed by separator (not part of a tag)
+        )
+      )
+    ),
+
+    // Word token shared between tag_name and regular comment text
+    _word: _ => /[^,:\s\n]+/,
+
+    tag: $ => seq(
+      alias($._word, $.tag_name),
+      token.immediate(':'),
+      alias(token.immediate(/[^,\s\n]+/), $.tag_value),
+    ),
+
+    tag_name: _ => /[^\s:,\n]+/,
+    tag_value: _ => /[^,\s\n]+/,
+
+    // Transaction: header followed by indented postings/comments
+    transaction: $ => seq(
+      $.transaction_header,
+      $.indent,
+      repeat1(
+        choice(
+          $.posting,
+          $.line_comment,
+        )
+      ),
+      $.dedent,
+    ),
+
+    transaction_header: $ => seq(
+      field('date', $.date),
+      optional(field('status', $.status)),
+      optional(field('code', $.code)),
+      field('description', $.description),
+      optional($.inline_comment),
+      $._newline,
+    ),
+
+    // Posting: account name with optional amount and comment
+    posting: $ => seq(
+      optional(field('status', $.status)),
+      field('account', $.account),
+      optional(field('amount', $.amount)),
+      optional(field('cost', $.cost)),
+      optional(field('assertion', $.assertion)),
+      optional($.inline_comment),
+      $._newline,
+    ),
+
+    cost: $ => seq(
+      choice(
+        '@',
+        '@@',
+      ),
+      $.amount,
+    ),
+
+    assertion: $ => seq(
+      '=',
+      $.amount,
+    ),
+
+    // Directives
+    _directive: $ => seq(
+      choice(
+        $.account_directive,
+        $.commodity_directive,
+        $.include_directive,
+        $.payee_directive,
+        $.tag_directive,
+      ),
+      optional($.inline_comment),
+      $._newline,
+    ),
+
+    account_directive: $ => seq(
+      'account',
+      field('name', $.account),
+    ),
+
+    commodity_directive: $ => seq(
+      'commodity',
+      choice(
+        seq(
+          field('symbol', $.commodity),
+          optional(/[ \t]+/),
+          optional(field('quantity', $.quantity)),
+        ),
+        seq(
+          field('symbol', $.quantity),
+          optional(/[ \t]+/),
+          field('commodity', $.commodity),
+        ),
+      ),
+    ),
+
+    include_directive: $ => seq(
+      'include',
+      field('path', $.file_path),
+    ),
+
+    payee_directive: $ => seq(
+      'payee',
+      field('name', $.payee_name),
+    ),
+
+    tag_directive: $ => seq(
+      'tag',
+      field('name', $.tag_name),
+    ),
+
+    // Basic tokens
+    date: _ => choice(
+      /\d{4}[-\/.]\d{1,2}[-\/.]\d{1,2}/,
+      /\d{1,2}[-\/.]\d{1,2}/,
+    ),
+
+    status: _ => token(prec(1, choice('*', '!'))),
+
+    sign: _ => token(choice('+', '-')),
+
+    code: _ => prec(1, seq('(', /[^)]+/, ')')),
+
+    // Description: Cannot start with status (*, !), code start parenthesis '(', 
+    // effective date equals '=', or be empty/semicolon.
+    // This allows the optional fields (status, code, effective_date) to match first.
+    description: _ => /[^*!=(;\s][^;\n]*/,
+
+
+    account: _ => /([^\s;#\n]+([ \t][^;\s\n#]+)*?)/,
+
+    // Amount: quantity with optional commodity
+    amount: $ => choice(
+      // Symbol on left, negative before symbol: $100, -$100, $ 100
+      seq(
+        optional(field('sign', $.sign)),
+        field('commodity', $.commodity),
+        optional(/\s+/),
+        field('quantity', $.quantity),
+      ),
+      // Symbol on left, negative after symbol: $-100, $+100,
+      seq(
+        field('commodity', $.commodity),
+        optional(field('sign', $.sign)),
+        optional(/\s+/),
+        field('quantity', $.quantity),
+      ),
+      // Symbol on right: 100 USD, -100 EUR
+      seq(
+        optional(field('sign', $.sign)),
+        field('quantity', $.quantity),
+        optional(/\s+/),
+        field('commodity', $.commodity),
+      ),
+      // No symbol: 100, -100.50
+      seq(
+        optional(field('sign', $.sign)),
+        field('quantity', $.quantity),
+      ),
+    ),
+
+    // Commodity symbols - excludes digits, whitespace, and special characters
+    // Also excludes +- so they can be parsed as signs
+    commodity: _ => choice(
+      /[^!"%(){}:;'~<>,.\/\\0-9\s\-+]+/,
+      /"[^\n]+"/,
+    ),
+
+
+    quantity: _ => /\d[\d., \t]*/,      // Number with optional separators (no newlines)
+
+    // File path for include directive
+    file_path: _ => /[^\s;#\n]+/,
+
+    // Payee name
+    payee_name: _ => /[^;\n]+/,
+
+  }
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "tree-sitter-hledger",
+  "version": "0.1.0",
+  "description": "Tree-sitter grammar for hledger journal files",
+  "main": "bindings/node",
+  "types": "bindings/node",
+  "keywords": [
+    "tree-sitter",
+    "parser",
+    "hledger",
+    "accounting",
+    "plaintext-accounting",
+    "ledger",
+    "finance"
+  ],
+  "author": "Patrick Timoney",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ptimoney/tree-sitter-hledger"
+  },
+  "bugs": {
+    "url": "https://github.com/ptimoney/tree-sitter-hledger/issues"
+  },
+  "homepage": "https://github.com/ptimoney/tree-sitter-hledger#readme",
+  "files": [
+    "grammar.js",
+    "binding.gyp",
+    "prebuilds/**",
+    "bindings/node/*",
+    "queries/**",
+    "src/**",
+    "*.wasm"
+  ],
+  "scripts": {
+    "build": "tree-sitter generate && node-gyp rebuild",
+    "test": "tree-sitter test",
+    "parse": "tree-sitter parse",
+    "watch": "tree-sitter generate --watch"
+  },
+  "dependencies": {
+    "nan": "^2.17.0"
+  },
+  "devDependencies": {
+    "tree-sitter-cli": "^0.20.8"
+  },
+  "tree-sitter": [
+    {
+      "scope": "source.hledger",
+      "file-types": [
+        "journal",
+        "hledger"
+      ],
+      "highlights": "queries/highlights.scm",
+      "folds": "queries/folds.scm"
+    }
+  ]
+}

package/queries/folds.scm

@@ -0,0 +1,9 @@
+; Fold transactions at the posting level
+(transaction) @fold
+
+; Fold block comments (multi-line)
+(block_comment) @fold
+
+; Fold consecutive line comments
+((line_comment)+ @fold)
+

package/queries/highlights.scm

@@ -0,0 +1,48 @@
+; Transaction dates
+(date) @keyword.date
+
+; Status markers
+(status) @keyword.modifier
+
+; Transaction codes
+(code) @string.special
+
+; Descriptions
+(description) @string
+
+; Account names
+(account) @type
+
+; Amounts - quantities and commodities
+(quantity) @number
+(commodity) @constant
+
+; Amount signs
+(sign) @operator
+
+; Directives
+"account" @keyword.directive
+"commodity" @keyword.directive
+"include" @keyword.import
+"payee" @keyword.directive
+"tag" @keyword.directive
+
+; Directive values
+(payee_name) @string
+(file_path) @string.special
+
+; Comments
+(line_comment) @comment
+(block_comment) @comment
+(inline_comment) @comment
+
+; Operators and punctuation
+"=" @operator
+"@" @operator
+"@@" @operator
+"(" @punctuation.bracket
+")" @punctuation.bracket
+
+; Tags
+(tag_name) @tag
+(tag_value) @property