Merge pull request #3215 from nojaf/skills

Add scripts to debug writer events and full format.

Author: nojaf

.claude/commands/ast.md

@@ -0,0 +1,20 @@
+---
+description: Parse F# source code to untyped AST
+allowed-tools: Bash(dotnet fsi:*), Bash(echo:*)
+---
+
+First build the project: `dotnet build src/Fantomas.Core/Fantomas.Core.fsproj`
+
+Then run the AST script. Write the source code to a temp file and pass it as argument:
+
+```
+dotnet fsi scripts/ast.fsx <file>
+```
+
+Or pipe inline source via stdin:
+
+```
+echo '<source>' | dotnet fsi scripts/ast.fsx [--signature]
+```
+
+$ARGUMENTS

.claude/commands/format.md

@@ -0,0 +1,20 @@
+---
+description: Format F# source code using the locally built Fantomas
+allowed-tools: Bash(dotnet fsi:*), Bash(echo:*), Bash(dotnet build:*)
+---
+
+First build the project: `dotnet build src/Fantomas/Fantomas.fsproj`
+
+Then run the format script. Pass a file path as argument:
+
+```
+dotnet fsi scripts/format.fsx [--editorconfig <content>] <file>
+```
+
+Or pipe inline source via stdin:
+
+```
+echo '<source>' | dotnet fsi scripts/format.fsx [--editorconfig <content>] [--signature]
+```
+
+$ARGUMENTS

.claude/commands/oak.md

@@ -0,0 +1,20 @@
+---
+description: Parse F# source code to Oak (Fantomas intermediate representation)
+allowed-tools: Bash(dotnet fsi:*), Bash(echo:*), Bash(dotnet build:*)
+---
+
+First build the project: `dotnet build src/Fantomas.Core/Fantomas.Core.fsproj`
+
+Then run the Oak script. Pass a file path as argument:
+
+```
+dotnet fsi scripts/oak.fsx <file>
+```
+
+Or pipe inline source via stdin:
+
+```
+echo '<source>' | dotnet fsi scripts/oak.fsx [--signature]
+```
+
+$ARGUMENTS

.claude/commands/writer-events.md

@@ -0,0 +1,20 @@
+---
+description: Show writer events produced during formatting of F# source code
+allowed-tools: Bash(dotnet fsi:*), Bash(echo:*), Bash(dotnet build:*)
+---
+
+First build the project: `dotnet build src/Fantomas/Fantomas.fsproj`
+
+Then run the writer-events script. Pass a file path as argument:
+
+```
+dotnet fsi scripts/writer-events.fsx [--editorconfig <content>] <file>
+```
+
+Or pipe inline source via stdin:
+
+```
+echo '<source>' | dotnet fsi scripts/writer-events.fsx [--editorconfig <content>] [--signature]
+```
+
+$ARGUMENTS

.gitignore

@@ -202,4 +202,7 @@ tests/.repositories/**
 *.sarif
 
 # vscode history plugin
-.history/
+.history/
+
+# LLM stuff
+.claude/settings.local.json

AGENTS.md

@@ -0,0 +1,39 @@
+# Fantomas
+
+F# source code formatter. Parses F# to an untyped AST (via vendored FCS), transforms it to an intermediate representation called Oak (`SyntaxOak.fs`), then prints it back via writer events (`CodePrinter.fs` + `Context.fs`).
+
+## Build & Test
+
+```bash
+dotnet build fantomas.sln
+dotnet test src/Fantomas.Core.Tests/
+```
+
+## Diagnostic Scripts
+
+All scripts accept a file path or stdin, with optional `--signature` and `--editorconfig <content>` flags.
+
+- `scripts/ast.fsx` — untyped AST
+- `scripts/oak.fsx` — Oak tree
+- `scripts/format.fsx` — format with local build
+- `scripts/writer-events.fsx` — writer events produced during formatting
+
+Scripts require a debug build first (`dotnet build src/Fantomas/Fantomas.fsproj`).
+
+## Post-task Steps
+
+Run these after completing a task, not during iterative development — analyzers can be slow.
+
+### Format
+
+```bash
+dotnet fantomas src docs build.fsx
+```
+
+### Analyzers
+
+```bash
+dotnet fsi build.fsx -- -p Analyze
+```
+
+Output goes to `analysis.sarif` in the repo root.

scripts/ast.fsx

@@ -1,20 +1,24 @@
-#r "../artifacts/bin/Fantomas.FCS/debug/Fantomas.FCS.dll"
+#load "shared.fsx"
 
 open System.IO
+open Shared
+
+let parseAst (input: string) (isSignature: bool) =
+    try
+        let ast =
+            Fantomas.FCS.Parse.parseFile isSignature (Fantomas.FCS.Text.SourceText.ofString input) []
+            |> fst
+
+        $"%A{ast}"
+    with ex ->
+        $"Error while parsing AST: %A{ex}"
 
 match Array.tryHead fsi.CommandLineArgs with
 | Some scriptPath ->
     let scriptFile = FileInfo(scriptPath)
     let sourceFile = FileInfo(Path.Combine(__SOURCE_DIRECTORY__, __SOURCE_FILE__))
 
     if scriptFile.FullName = sourceFile.FullName then
-        let inputPath = fsi.CommandLineArgs.[fsi.CommandLineArgs.Length - 1]
-        let sample = File.ReadAllText(inputPath)
-        let isSignature = inputPath.EndsWith(".fsi")
-
-        let ast =
-            Fantomas.FCS.Parse.parseFile isSignature (Fantomas.FCS.Text.SourceText.ofString sample) []
-            |> fst
-
-        ast |> printfn "%A"
-| _ -> printfn "Usage: dotnet fsi ast.fsx <input file>"
+        let sample, isSignature, _ = parseArgs fsi.CommandLineArgs.[1..]
+        parseAst sample isSignature |> printfn "%s"
+| _ -> printfn "Usage: dotnet fsi ast.fsx [--signature] <input file>"

scripts/format.fsx

@@ -0,0 +1,24 @@
+#load "shared.fsx"
+
+open System.IO
+open Fantomas.Core
+open Shared
+
+let format (input: string) (isSignature: bool) (config: FormatConfig) =
+    async {
+        try
+            let! result = CodeFormatter.FormatDocumentAsync(isSignature, input, config)
+            return result.Code
+        with ex ->
+            return $"Error while formatting: %A{ex}"
+    }
+
+match Array.tryHead fsi.CommandLineArgs with
+| Some scriptPath ->
+    let scriptFile = FileInfo(scriptPath)
+    let sourceFile = FileInfo(Path.Combine(__SOURCE_DIRECTORY__, __SOURCE_FILE__))
+
+    if scriptFile.FullName = sourceFile.FullName then
+        let sample, isSignature, config = parseArgs fsi.CommandLineArgs.[1..]
+        format sample isSignature config |> Async.RunSynchronously |> printfn "%s"
+| _ -> printfn "Usage: dotnet fsi format.fsx [--editorconfig <content>] <input file>"

scripts/oak.fsx

@@ -1,36 +1,27 @@
-#r "../artifacts/bin/Fantomas.FCS/debug/Fantomas.FCS.dll"
-#r "../artifacts/bin/Fantomas.Core/debug/Fantomas.Core.dll"
+#load "shared.fsx"
 
-open System.Threading.Tasks
+open System.IO
 open Fantomas.Core
+open Shared
 
-let parseOak (input: string) (isSignature: bool) : Task<string> =
-    task {
+let parseOak (input: string) (isSignature: bool) =
+    async {
         try
             let! oaks = CodeFormatter.ParseOakAsync(isSignature, input)
 
             match Array.tryHead oaks with
             | None -> return "No Oak found in input"
             | Some(oak, _) -> return (string oak)
-
         with ex ->
             return $"Error while parsing to Oak: %A{ex}"
     }
 
-open System.IO
-
 match Array.tryHead fsi.CommandLineArgs with
 | Some scriptPath ->
     let scriptFile = FileInfo(scriptPath)
     let sourceFile = FileInfo(Path.Combine(__SOURCE_DIRECTORY__, __SOURCE_FILE__))
 
     if scriptFile.FullName = sourceFile.FullName then
-        let inputPath = fsi.CommandLineArgs.[fsi.CommandLineArgs.Length - 1]
-        let sample = File.ReadAllText(inputPath)
-        let isSignature = inputPath.EndsWith(".fsi")
-
-        parseOak sample isSignature
-        |> Async.AwaitTask
-        |> Async.RunSynchronously
-        |> printfn "%s"
-| _ -> printfn "Usage: dotnet fsi oak.fsx <input file>"
+        let sample, isSignature, _ = parseArgs fsi.CommandLineArgs.[1..]
+        parseOak sample isSignature |> Async.RunSynchronously |> printfn "%s"
+| _ -> printfn "Usage: dotnet fsi oak.fsx [--signature] <input file>"

scripts/shared.fsx

@@ -0,0 +1,61 @@
+#r "../artifacts/bin/Fantomas.FCS/debug/Fantomas.FCS.dll"
+#r "../artifacts/bin/Fantomas.Core/debug/Fantomas.Core.dll"
+#r "nuget: editorconfig"
+
+#load "../src/Fantomas/EditorConfig.fs"
+
+open System.IO
+open Fantomas.Core
+open Fantomas.EditorConfig
+
+let parseEditorConfigContent (content: string) : FormatConfig =
+    let tempDir = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName())
+    Directory.CreateDirectory(tempDir) |> ignore
+    let editorConfigPath = Path.Combine(tempDir, ".editorconfig")
+    let fsharpFile = Path.Combine(tempDir, "temp.fs")
+    File.WriteAllText(editorConfigPath, $"root = true\n\n[*.fs]\n%s{content}")
+    File.WriteAllText(fsharpFile, "")
+
+    try
+        readConfiguration fsharpFile
+    finally
+        Directory.Delete(tempDir, true)
+
+/// Parses args and returns (source, isSignature, config).
+/// Accepts either a file path as last arg, or source code via stdin.
+/// Optional flags: --editorconfig <content>, --signature
+let parseArgs (args: string array) =
+    let editorConfigIdx = args |> Array.tryFindIndex (fun a -> a = "--editorconfig")
+    let hasSignatureFlag = args |> Array.exists (fun a -> a = "--signature")
+
+    let config =
+        match editorConfigIdx with
+        | Some idx -> parseEditorConfigContent args.[idx + 1]
+        | None -> FormatConfig.Default
+
+    // Collect flag indices to determine which arg (if any) is the input file
+    let flagIndices =
+        [| match editorConfigIdx with
+           | Some idx ->
+               yield idx
+               yield idx + 1
+           | None -> ()
+           yield!
+               args
+               |> Array.indexed
+               |> Array.choose (fun (i, a) -> if a = "--signature" then Some i else None) |]
+
+    let positionalArgs =
+        args
+        |> Array.indexed
+        |> Array.filter (fun (i, _) -> not (Array.contains i flagIndices))
+        |> Array.map snd
+
+    match Array.tryLast positionalArgs with
+    | Some path when File.Exists(path) ->
+        let sample = File.ReadAllText(path)
+        let isSignature = hasSignatureFlag || path.EndsWith(".fsi")
+        sample, isSignature, config
+    | _ ->
+        let sample = stdin.ReadToEnd()
+        sample, hasSignatureFlag, config