tree-sitter-fsharp AGENTS.md

Improving the F# Tree-sitter Parser

This document explains how to add new language features to the F# parser.

Project Structure

This project contains two parsers:

1. fsharp/ - Parses .fs and .fsx files (F# source and script files)
2. fsharp_signature/ - Parses .fsi files (F# signature files)

These are not independent. fsharp_signature/grammar.js starts with grammar(require("../fsharp/grammar"), { ... }) — it extends the base grammar and overrides/adds a small number of rules. Consequences you must internalize:

• A change to fsharp/grammar.js changes the derived signature grammar too, even if you never open fsharp_signature/grammar.js.
• Both fsharp/src/parser.c and fsharp_signature/src/parser.c must be regenerated after any change to fsharp/grammar.js. Forgetting the second one will fail CI's "parser matches grammar" check.
• Use npm run generate (regenerates both) rather than a single tree-sitter generate invocation — see the workflow section below.

Each parser directory contains:

• grammar.js - The grammar definition (written in JavaScript)
• src/grammar.json - Generated grammar in JSON format
• src/parser.c - Generated C parser code (never edit this file directly)
• src/scanner.c - Thin per-parser shim that #includes the shared scanner

The real external scanner logic lives in a single shared header at common/scanner.h. Both fsharp/src/scanner.c and fsharp_signature/src/scanner.c are just three-function shims that delegate to functions defined in that header. If you need to change tokenization behavior (indent/dedent, keyword handling, string interpolation, etc.), edit common/scanner.h — never the per-parser scanner.c shim.

Running the CLI

The tree-sitter CLI is installed as a local devDependency (node_modules/.bin/tree-sitter), not globally. Invoke it with npx tree-sitter <command>, which resolves the local binary automatically. All examples in this document use npx tree-sitter ....