VSCode Ledger Helper

• /vscode-ledger-helper
• 2024
• Typescript, PTA, ledger
• Repo

A solution to add tooling to VSCode based editors for .ledger files. Based on and inspired by features also found in

• mariosangiorgio/vscode-ledger
• ananthakumaran/paisa
• microsoft/vscode-extension-samples

Features include

• Autocomplete for account names & payees
• Inline diagnostics and error reporting
• File formatting
• --strict mode consistency checks
• Account balance preview on hover
• Language Snippets
• New transaction command (using ledger's xact)

The most interesting part

I found myself wanting to validate not just the currently open ledger file, but a "workspace" of them all at once. The Ledger CLI makes this easy by just including files in a "root" ledger file and treating them as one. To avoid having to prompt the user for what file was their "root", an optional feature was created: "Validate Root Include File".

This enables some extra behaivor. The extension will

1. keep track of all the ledger files that have been opened
2. check what files they include and are included by
3. upon a "validation" will "walk" up the includes to find the root ledger for a given file

For example

> open savings.ledger and hit "Ctrl-S"

The extension will validate & check only savings.ledger

> open main.ledger which includes savings.ledger
> switch back to savings.ledger and hit "Ctrl-S

The extension realizes that the main.ledger is what
needs to be validated, and in doing so, will get
savings.ledger because it's included

This may seem unnecessary, but it made keeping a workspace like the following much easier to work with. Also, it fixed the problem of random errors popping up because a given ledger was not being validated "in context".

• main.ledger
  • archived ledgers/
    • 2023.ledger
  • chart of accounts.ledger
  • recently imported.leger
  • verified transactions.ledger

What could be improved

Using the ledger-cli library from NPM left me with certain limitations that I solved by calling the binary directly with a child process. There are now two ways to interact with ledger files in the codebase. Some features use the NPM library and some direct use the binary.

Additionally, multiple file passes are being done to

• validate the ledger files for errors
• perform --strict account checking
• provide account/payee autocompletion
• provide data for the "preview balance on hover" feature

This could be made much more efficient by either updating the NPM library, possibly by doing everything with direct binary calls, or by implementing a new library to read and parse all relavent file data & errors in a single pass. For now, we can stick with the inefficient approach and let the ledger CLI do the heavy lifting.

A ledger file about 50,000 lines long can be validated, formatted, and syntax highlighted in less than a second.

Last thing

Did you know that basically every useful language feature boils down to a bunch of regex? Crazy.