Merge branch 'main' into repo-assist/fix-issue-924-watch-root-override-c4e35a7b2fb520aa

Author: dsyme

RELEASE_NOTES.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## 22.0.0-alpha.2 - 2026-03-13
+
 ### Added
 * Add `--root` option to `fsdocs watch` to override the root URL for generated pages. Useful for serving docs via GitHub Codespaces, reverse proxies, or other remote hosting where `localhost` URLs are inaccessible. E.g. `fsdocs watch --root /` or `fsdocs watch --root https://example.com/docs/`. When not set, defaults to `http://localhost:<port>/` as before. [#924](https://github.com/fsprojects/FSharp.Formatting/issues/924)
 * Fix `fsdocs watch` hot-reload WebSocket to connect using the page's actual host (`window.location.host`) instead of a hardcoded `localhost:<port>`, so hot-reload works correctly in GitHub Codespaces, behind reverse proxies, and over HTTPS. [#924](https://github.com/fsprojects/FSharp.Formatting/issues/924)
@@ -10,12 +12,18 @@
 * `fsdocs convert` now accepts the input file as a positional argument (e.g. `fsdocs convert notebook.ipynb -o notebook.html`). [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 * `fsdocs convert` infers the output format from the output file extension when `--outputformat` is not specified (e.g. `-o out.md` implies `--outputformat markdown`). [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 * `fsdocs convert` now accepts `-o` as a shorthand for `--output`. [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
+* Added full XML doc comments (`<summary>`, `<param>`) to `Literate.ParseAndCheckScriptFile` and `Literate.ParseScriptString` to match the documentation style of the other `Literate.Parse*` methods.
+
+### Fixed
+* `Literate.ParseScriptString` and `Literate.ParsePynbString` used a hardcoded Windows path (`C:\script.fsx`) as the fallback script filename when neither `path` nor `rootInputFolder` is supplied. The fallback is now a simple platform-neutral `script.fsx`.
+* Add regression tests for cross-assembly tooltip resolution (issue [#1085](https://github.com/fsprojects/FSharp.Formatting/issues/1085)): verify that hover tooltips for types whose fields reference types from other assemblies show the correct type names (not `obj`) when `#r` paths resolve correctly.
 
 ### Changed
 * Tooltip elements (`div.fsdocs-tip`) now use the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) (Baseline 2024: Chrome 114+, Firefox 125+, Safari 17+). Tooltips are placed in the browser's top layer — no `z-index` needed, always above all other content. Fixes a positioning bug where tooltips appeared offset when the page was scrolled. The previous `display`-toggle fallback has been removed. Tooltips also fade in with a subtle animation. [#422](https://github.com/fsprojects/FSharp.Formatting/issues/422), [#1061](https://github.com/fsprojects/FSharp.Formatting/pull/1061)
 * Generated code tokens no longer use inline `onmouseover`/`onmouseout` event handlers. Tooltips are now triggered via `data-fsdocs-tip` / `data-fsdocs-tip-unique` attributes and a delegated event listener in `fsdocs-tips.js`. The `popover` attribute is also added to API-doc tooltip divs so they use the same top-layer path. [#1061](https://github.com/fsprojects/FSharp.Formatting/pull/1061)
 * Changed `range` fields in `MarkdownSpan` and `MarkdownParagraph` DU cases from `MarkdownRange option` to `MarkdownRange`, using `MarkdownRange.zero` as the default/placeholder value instead of `None`.
 * When no template is provided (e.g. `fsdocs convert` without `--template`), `fsdocs-tip` tooltip divs are no longer included in the output. Tooltips require JavaScript/CSS from a template to function, so omitting them produces cleaner raw output. [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
+* Use [`scrollbar-gutter: stable`](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-gutter) (Baseline 2024) on scroll containers (`main`, `#fsdocs-main-menu`, mobile menu, search dialog) to reserve scrollbar space and prevent layout shifts when content changes height. Also adds the missing `overflow-y: auto` to `main` so pages that exceed the viewport height are independently scrollable. [#1087](https://github.com/fsprojects/FSharp.Formatting/issues/1087), [#1088](https://github.com/fsprojects/FSharp.Formatting/pull/1088)
 
 ## 22.0.0-alpha.1 - 2026-03-03
 

docs/content/fsdocs-default.css

@@ -239,6 +239,7 @@ header {
                 list-style: none;
                 padding: var(--spacing-300);
                 overflow-y: auto;
+                scrollbar-gutter: stable;
             }
 
             & input:checked + .menu {
@@ -310,6 +311,8 @@ aside {
 
 main {
     height: calc(100dvh - var(--header-height));
+    overflow-y: auto;
+    scrollbar-gutter: stable;
 }
 
 #content {
@@ -469,6 +472,7 @@ main {
         grid-row: var(--main-menu-grid-row);
         grid-column: var(--main-menu-grid-column);
         overflow-y: auto;
+        scrollbar-gutter: stable;
     }
 
     main {
@@ -1269,6 +1273,7 @@ dialog {
 
     & ul {
         overflow-y: auto;
+        scrollbar-gutter: stable;
         max-height: calc(50vh - var(--spacing-700) - var(--spacing-700));
         list-style: none;
         padding: 0;

src/FSharp.Formatting.Literate/Literate.fs

@@ -98,7 +98,18 @@ type Literate private () =
 
             doc.With(paragraphs = pars)
 
-    /// Parse F# Script file to LiterateDocument
+    /// <summary>
+    /// Parse an F# script file (<c>.fsx</c>) to a <see cref="T:FSharp.Formatting.Literate.LiterateDocument"/>,
+    /// type-checking it via the F# Compiler Service.
+    /// </summary>
+    /// <param name="path">The path to the <c>.fsx</c> script file to parse.</param>
+    /// <param name="fscOptions">Additional F# compiler options (e.g. extra <c>-r:</c> references).</param>
+    /// <param name="definedSymbols">Conditional-compilation symbols to define.</param>
+    /// <param name="references">A map of reference labels to URLs, used to resolve Markdown-style links.</param>
+    /// <param name="fsiEvaluator">An optional FSI evaluator; when supplied, code snippets are executed and their output included.</param>
+    /// <param name="parseOptions">Markdown parse options. Defaults to <see cref="F:FSharp.Formatting.Markdown.MarkdownParseOptions.AllowYamlFrontMatter"/>.</param>
+    /// <param name="rootInputFolder">The root folder used to resolve relative paths within the script. Defaults to the directory containing <paramref name="path"/>.</param>
+    /// <param name="onError">A callback invoked with each error/warning message encountered during parsing or type-checking. Defaults to <c>ignore</c>.</param>
     static member ParseAndCheckScriptFile
         (
             path: string,
@@ -120,7 +131,20 @@ type Literate private () =
         |> Transformations.formatCodeSnippets path ctx
         |> Transformations.evaluateCodeSnippets ctx
 
-    /// Parse string as F# Script to LiterateDocument
+    /// <summary>
+    /// Parse a string containing F# script source code (<c>.fsx</c> syntax) to a
+    /// <see cref="T:FSharp.Formatting.Literate.LiterateDocument"/>,
+    /// type-checking it via the F# Compiler Service.
+    /// </summary>
+    /// <param name="content">The F# script source code to parse.</param>
+    /// <param name="path">An optional file path used in diagnostics and to resolve relative references. When not supplied, defaults to <c>script.fsx</c> in <paramref name="rootInputFolder"/> (or just <c>script.fsx</c>).</param>
+    /// <param name="fscOptions">Additional F# compiler options (e.g. extra <c>-r:</c> references).</param>
+    /// <param name="definedSymbols">Conditional-compilation symbols to define.</param>
+    /// <param name="references">A map of reference labels to URLs, used to resolve Markdown-style links.</param>
+    /// <param name="fsiEvaluator">An optional FSI evaluator; when supplied, code snippets are executed and their output included.</param>
+    /// <param name="parseOptions">Markdown parse options. Defaults to <see cref="F:FSharp.Formatting.Markdown.MarkdownParseOptions.AllowYamlFrontMatter"/>.</param>
+    /// <param name="rootInputFolder">The root folder used to resolve relative paths within the script.</param>
+    /// <param name="onError">A callback invoked with each error/warning message encountered during parsing or type-checking. Defaults to <c>ignore</c>.</param>
     static member ParseScriptString
         (
             content,
@@ -141,7 +165,7 @@ type Literate private () =
             | Some s -> s
             | None ->
                 match rootInputFolder with
-                | None -> "C:\\script.fsx"
+                | None -> "script.fsx"
                 | Some r -> Path.Combine(r, "script.fsx")
 
         ParseScript(parseOptions, ctx).ParseAndCheckScriptFile(filePath, content, rootInputFolder, onError)
@@ -242,7 +266,7 @@ type Literate private () =
             | Some s -> s
             | None ->
                 match rootInputFolder with
-                | None -> "C:\\script.fsx"
+                | None -> "script.fsx"
                 | Some r -> Path.Combine(r, "script.fsx")
 
         let content = ParsePynb.pynbStringToFsx content

tests/FSharp.CodeFormat.Tests/CodeFormatTests.fs

@@ -479,3 +479,152 @@ c.Method()
     // Attribute annotations should not appear in rendered tooltips
     tooltip |> shouldNotContainText "[<Optional"
     tooltip |> shouldNotContainText "[<DefaultParameterValue"
+
+// --------------------------------------------------------------------------------------
+// Tests for cross-assembly type resolution in tooltips (issue #1085)
+// --------------------------------------------------------------------------------------
+
+/// Find the directory where the currently executing test assembly lives.
+/// Both CrossAssemblyA.dll and CrossAssemblyB.dll are copied there as project references.
+let private testBinDir = System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().Location)
+
+/// Return the tooltip text for the first token named `tokenText` that carries a tip.
+let private tipForToken (tokenText: string) (snips: Snippet[]) =
+    snips
+    |> Seq.tryPick (fun (Snippet(_, lines)) ->
+        lines
+        |> Seq.tryPick (fun (Line(_, spans)) ->
+            spans
+            |> Seq.tryPick (function
+                | TokenSpan.Token(_, t, Some tips) when t = tokenText -> Some tips
+                | _ -> None)))
+
+/// Render tooltip spans to a single concatenated string for easy assertion.
+let private renderTips (spans: ToolTipSpans) =
+    spans
+    |> List.map (function
+        | Literal s -> s
+        | Emphasis inner ->
+            inner
+            |> List.map (function
+                | Literal s -> s
+                | _ -> "")
+            |> String.concat ""
+        | HardLineBreak -> "\n")
+    |> String.concat ""
+
+[<Test>]
+let ``Cross-assembly DU field type is shown as actual type name not obj in tooltip`` () =
+    // Reproduce issue #1085: `Subject.Account of Did` should show `Did`, not `obj`
+    // Use forward slashes so the paths are valid F# string literal content on Windows too.
+    let assemblyAPath = System.IO.Path.Combine(testBinDir, "CrossAssemblyA.dll").Replace('\\', '/')
+    let assemblyBPath = System.IO.Path.Combine(testBinDir, "CrossAssemblyB.dll").Replace('\\', '/')
+
+    let source =
+        $"""#r "{assemblyAPath}"
+#r "{assemblyBPath}"
+open CrossAssemblyA
+open CrossAssemblyB
+
+let subject = Subject.Account (CrossAssemblyA.Did.create "test")
+"""
+
+    let snips, errors = CodeFormatter.ParseAndCheckSource("/somewhere/test.fsx", source.Trim(), None, None, ignore)
+
+    errors |> shouldEqual [||]
+
+    // Find the tooltip for the `Subject` identifier and check its text
+    let subjectTip =
+        snips
+        |> tipForToken "Subject"
+        |> Option.map renderTips
+        |> Option.defaultValue ""
+
+    subjectTip |> shouldNotEqual ""
+
+    // The tooltip for Subject should show the actual DU case type, not `obj`
+    subjectTip |> shouldNotContainText "obj"
+    subjectTip |> shouldContainText "Did"
+
+[<Test>]
+let ``Cross-assembly record field types are shown as actual type names not obj in tooltip`` () =
+    // Reproduce issue #1085: `TeamMember` record fields referencing types from another
+    // assembly should show the correct type names (`Did`, `DateTimeOffset option`)
+    // rather than `obj`.
+    // Use forward slashes so the paths are valid F# string literal content on Windows too.
+    let assemblyAPath = System.IO.Path.Combine(testBinDir, "CrossAssemblyA.dll").Replace('\\', '/')
+    let assemblyBPath = System.IO.Path.Combine(testBinDir, "CrossAssemblyB.dll").Replace('\\', '/')
+
+    let source =
+        $"""#r "{assemblyAPath}"
+#r "{assemblyBPath}"
+open CrossAssemblyB
+
+let m : TeamMember = Unchecked.defaultof<TeamMember>
+"""
+
+    let snips, errors = CodeFormatter.ParseAndCheckSource("/somewhere/test.fsx", source.Trim(), None, None, ignore)
+
+    errors |> shouldEqual [||]
+
+    let teamMemberTip =
+        snips
+        |> tipForToken "TeamMember"
+        |> Option.map renderTips
+        |> Option.defaultValue ""
+
+    teamMemberTip |> shouldNotEqual ""
+
+    // Record field types from a different assembly should not appear as `obj`
+    teamMemberTip |> shouldContainText "Did"
+    teamMemberTip |> shouldContainText "DateTimeOffset"
+
+[<Test>]
+let ``Cross-assembly DU field types are correct when using relative hash-r references`` () =
+    // Reproduce the user scenario from issue #1085: using relative #r paths where the
+    // script file is in the same directory as the referenced assemblies.
+    // Set up a temporary directory containing the DLLs and a script path pointing there.
+    let tempDir = System.IO.Path.Combine(System.IO.Path.GetTempPath(), "fsharp-formatting-issue1085")
+    System.IO.Directory.CreateDirectory(tempDir) |> ignore
+
+    try
+        // Copy the test assemblies to the temp directory so relative #r can resolve them.
+        let srcA = System.IO.Path.Combine(testBinDir, "CrossAssemblyA.dll")
+        let srcB = System.IO.Path.Combine(testBinDir, "CrossAssemblyB.dll")
+        System.IO.File.Copy(srcA, System.IO.Path.Combine(tempDir, "CrossAssemblyA.dll"), overwrite = true)
+        System.IO.File.Copy(srcB, System.IO.Path.Combine(tempDir, "CrossAssemblyB.dll"), overwrite = true)
+
+        // Script path is inside the temp dir; FCS uses this to resolve relative #r paths.
+        let scriptPath = System.IO.Path.Combine(tempDir, "test.fsx")
+
+        let source =
+            """#r "CrossAssemblyA.dll"
+#r "CrossAssemblyB.dll"
+open CrossAssemblyA
+open CrossAssemblyB
+
+let subject = Subject.Account (CrossAssemblyA.Did.create "test")
+"""
+
+        let snips, errors = CodeFormatter.ParseAndCheckSource(scriptPath, source.Trim(), None, None, ignore)
+
+        errors |> shouldEqual [||]
+
+        let subjectTip =
+            snips
+            |> tipForToken "Subject"
+            |> Option.map renderTips
+            |> Option.defaultValue ""
+
+        subjectTip |> shouldNotEqual ""
+
+        // With correctly-resolved relative paths the tooltip should show Did, not obj.
+        subjectTip |> shouldNotContainText "of obj"
+        subjectTip |> shouldContainText "Did"
+
+    finally
+        // Clean up
+        try
+            System.IO.Directory.Delete(tempDir, recursive = true)
+        with _ ->
+            ()

tests/FSharp.CodeFormat.Tests/FSharp.CodeFormat.Tests.fsproj

@@ -10,6 +10,8 @@
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\src\FSharp.Formatting.CodeFormat\FSharp.Formatting.CodeFormat.fsproj" />
+    <ProjectReference Include="files\CrossAssemblyA\CrossAssemblyA.fsproj" />
+    <ProjectReference Include="files\CrossAssemblyB\CrossAssemblyB.fsproj" />
   </ItemGroup>
   <ItemGroup>
     <PackageReference Include="FSharp.Core" />

tests/FSharp.CodeFormat.Tests/files/CrossAssemblyA/CrossAssemblyA.fsproj

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>netstandard2.1</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="Library.fs" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="FSharp.Core" />
+  </ItemGroup>
+</Project>

tests/FSharp.CodeFormat.Tests/files/CrossAssemblyA/Library.fs

@@ -0,0 +1,9 @@
+namespace CrossAssemblyA
+
+/// A simple single-case discriminated union that is defined in Assembly A.
+/// It is referenced from Assembly B to test cross-assembly tooltip resolution (issue #1085).
+type Did = private Did of string
+
+module Did =
+    /// Construct a Did value.
+    let create (s: string) = Did s

tests/FSharp.CodeFormat.Tests/files/CrossAssemblyB/CrossAssemblyB.fsproj

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>netstandard2.1</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="Library.fs" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="FSharp.Core" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\CrossAssemblyA\CrossAssemblyA.fsproj" />
+  </ItemGroup>
+</Project>

tests/FSharp.CodeFormat.Tests/files/CrossAssemblyB/Library.fs

@@ -0,0 +1,19 @@
+namespace CrossAssemblyB
+
+open CrossAssemblyA
+
+/// A discriminated union in Assembly B whose Account case holds a Did value
+/// from Assembly A.  Used to test cross-assembly tooltip rendering (issue #1085).
+[<RequireQualifiedAccess>]
+type Subject =
+    | Account of Did
+    | Record of string
+
+/// A record in Assembly B whose fields mix types from Assembly A (Did),
+/// primitive types, and generic wrapper types from the BCL.
+/// Used to test cross-assembly tooltip rendering (issue #1085).
+type TeamMember =
+    { Did: Did
+      Name: string
+      Active: bool
+      JoinedAt: System.DateTimeOffset option }