Bramble Parser

A parser for the .havenfs file format

Introduction

Bramble is a lightweight recursive descent parser that processes .havenfs files, returning a structured Json tree that can be used to construct an in-memory FS representation. The parser is based on line-based grammar, chunk headers, and metadata declarations.

.havenfs files describe the structure of a virtual file system with elements such as files, metadata, directories, references, and git history.

Example Input

A typical .havenfs input file would look like this:

#BRANCH base=main parent=b0011 head=b0012

#CHUNK files 0-999 @0
FILE f1a7e parent=92e1f name=logo.png size=20320 tags=branding,logo
META f1a7e modified=1723472381 created=1723472370 mimetype=image/png

#CHUNK files 1000-1999 @12010
FILE f1b88 parent=92e1f name=screenshot1.png size=50320 libs=a300
META f1b88 modified=1723472381 created=1723472370 mimetype=image/png

#CHUNK libraries @3000
LIB a300 info=b400,b401

#CHUNK tagmap @4500
TAG b401 branding:#8E44AD FR=f1a7e
TAG b402 logo:#1ABC9C FR=f1a7e
TAG b402 bin:#464646
TAG b402 favourite:#A6DB5A

#CHUNK directories @25000
DIR 92e1f parent=root name=images

#CHUNK refs @27000
REF f1a7e to=3d93e type=used-by context=thumbnail

#CHUNK history f1a7e
HIST f1a7e 20250625T1230 user=ellie action=created hash=abc123
HIST f1a7e 20250626T1010 user=ellie action=edited hash=def456

Output

Parsing the above file produces:

• A JSON structure describing all nodes (files, metadata, directories, etc).
• A readable debug printout displaying detailed per-node information.

How to Run

You need a package manager like npm, yarn or bun.

Development Script

bun run example

or

npm run example

This will read the example file located at:

fixtures/example.havenfs

Reading .havenfs flat config files from current folder

bun run bramble

or

npm run bramble

Running the Bramble Lexer

bun run lex

or

npm run lex

Parse and debug a .havenfs file located at:

fixtures/example.havenfs

Running Tests

bun test

Project Structure

• lexer.ts: Tokenizes .havenfs files into structured chunks
• parser.ts: Implements a predictive parser and builds the file system tree
• fixtures.ts: Example .havenfs input
• test.ts: Runs unit tests for lexer and parser