feat: add FSharp.Azure.Cosmos.Sql, a syntax tree, printer, validator and function catalog for Cosmos DB SQL

.github/copilot-instructions.md

@@ -12,6 +12,18 @@
 
 ```text
 /
+├── src/Cosmos.Sql/      – Cosmos DB SQL model (FSharp.Azure.Cosmos.Sql)
+│   ├── EquatableArray.fs – immutable array with structural equality
+│   ├── ImmutableArrayPatterns.fs – active patterns that match an `ImmutableArray` by its length
+│   ├── Syntax.fs        – syntax tree of the query language
+│   ├── Keywords.fs      – reserved words and the identifier rule
+│   ├── FunctionSpec.fs  – specification of a built-in function
+│   ├── CatalogData.fs   – one row per built-in function
+│   ├── Catalog.fs       – lookup of built-in functions
+│   ├── ValidationError.fs – validation errors and options
+│   ├── Inline.fs        – replacement of parameters by literals
+│   ├── Printer.fs       – printer of the query text
+│   └── Validator.fs     – rules of the query language that the grammar cannot express
 ├── src/Cosmos/          – main library (FSharp.Azure.Cosmos)
 │   ├── SubStatusCodes.fs – documented Cosmos DB sub-status codes
 │   ├── Cosmos.fs        – core types and container extensions
@@ -28,6 +40,7 @@
 ├── src/Shared/          – source files that every F# project under src and tests compiles
 │   └── ValueCollections.fs – `Seq`, `List` and `Array` functions that return `voption` and struct tuples
 ├── tests/Cosmos.Tests/  – MSTest integration test project
+├── tests/Cosmos.Sql.Tests/ – MSTest unit tests of FSharp.Azure.Cosmos.Sql, no emulator needed
 ├── tests/Cosmos.Tests.Infrastructure/ – shared test fixtures, emulator settings and assertion helpers
 ├── build/               – FAKE build scripts
 └── docsSrc/             – FSharp.Formatting documentation source

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+* `FSharp.Azure.Cosmos.Sql` package: an immutable syntax tree of the Azure Cosmos DB NoSQL query language that mirrors the grammar of the .NET SDK, a deterministic printer with a parameterized and an inline mode, a validator for the rules the grammar cannot express and the catalog of the built-in functions as data, without a dependency on the Azure Cosmos DB SDK
+
 ### Changed
 * BREAKING: the package targets `net10.0` only and no longer supports `net8.0`, which makes this a major release
 * BREAKING: `Microsoft.Azure.Cosmos` updated from 3.60.0 to 3.62.0, which becomes the minimum version for consumers. Its release notes list a breaking change of their own: thin client mode is enabled by default and does not support resource-token authentication (opt out with `AZURE_COSMOS_THIN_CLIENT_ENABLED=false`)

FSharp.Azure.Cosmos.slnf

@@ -2,7 +2,9 @@
   "solution": {
     "path": "FSharp.Azure.Cosmos.slnx",
     "projects": [
+      "src\\Cosmos.Sql\\FSharp.Azure.Cosmos.Sql.fsproj",
       "src\\Cosmos\\FSharp.Azure.Cosmos.fsproj",
+      "tests\\Cosmos.Sql.Tests\\FSharp.Azure.Cosmos.Sql.Tests.fsproj",
       "tests\\Cosmos.Tests.Infrastructure\\FSharp.Azure.Cosmos.Tests.Infrastructure.fsproj",
       "tests\\Cosmos.Tests\\FSharp.Azure.Cosmos.Tests.fsproj"
     ]

FSharp.Azure.Cosmos.slnx

@@ -8,9 +8,12 @@
     <File Path="Directory.Packages.props" />
     <File Path="global.json" />
     <File Path="README.md" />
+    <File Path="THIRD-PARTY-NOTICES.md" />
   </Folder>
   <Project Path="build/build.fsproj" />
+  <Project Path="src/Cosmos.Sql/FSharp.Azure.Cosmos.Sql.fsproj" />
   <Project Path="src/Cosmos/FSharp.Azure.Cosmos.fsproj" />
+  <Project Path="tests/Cosmos.Sql.Tests/FSharp.Azure.Cosmos.Sql.Tests.fsproj" />
   <Project Path="tests/Cosmos.Tests.Infrastructure/FSharp.Azure.Cosmos.Tests.Infrastructure.fsproj" />
   <Project Path="tests/Cosmos.Tests/FSharp.Azure.Cosmos.Tests.fsproj" />
 </Solution>

THIRD-PARTY-NOTICES.md

@@ -0,0 +1,42 @@
+# Third-party notices
+
+This repository and the packages built from it include material from the third-party projects listed below. The
+original copyright notices and licences are reproduced here.
+
+## Azure Cosmos DB .NET SDK v3
+
+* Source: <https://github.com/Azure/azure-cosmos-dotnet-v3>, tag `3.62.0` (commit `fe16fe00617e962dbab246244813d605871c086d`)
+* Licence: MIT
+* Used in `FSharp.Azure.Cosmos.Sql` (`src/Cosmos.Sql`) and its tests (`tests/Cosmos.Sql.Tests`):
+  * the node inventory of the syntax tree, after the classes in `Microsoft.Azure.Cosmos/src/SqlObjects` and the
+    grammar `Microsoft.Azure.Cosmos/src/Query/Core/Parser/sql.g4`;
+  * the printing rules, after `Microsoft.Azure.Cosmos/src/SqlObjects/Visitors/SqlObjectTextSerializer.cs`;
+  * the names of the built-in functions in the catalog, from `SqlFunctionCallScalarExpression.Names` in
+    `Microsoft.Azure.Cosmos/src/SqlObjects/SqlFunctionCallScalarExpression.cs`;
+  * expected query texts in the tests, from the baselines in
+    `Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/BaselineTest/TestBaseline` and
+    `Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.EmulatorTests/BaselineTest/TestBaseline`.
+
+```text
+MIT License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE
+```

src/Cosmos.Sql/AssemblyInfo.fs

@@ -0,0 +1,23 @@
+// Auto-Generated by FAKE; do not edit
+namespace System
+open System.Reflection
+
+[<assembly: AssemblyTitleAttribute("FSharp.Azure.Cosmos.Sql")>]
+[<assembly: AssemblyProductAttribute("FSharp.Azure.Cosmos")>]
+[<assembly: AssemblyVersionAttribute("1.2.0")>]
+[<assembly: AssemblyMetadataAttribute("ReleaseDate","2026-10-01T00:00:00.0000000+02:00")>]
+[<assembly: AssemblyFileVersionAttribute("1.2.0")>]
+[<assembly: AssemblyInformationalVersionAttribute("1.2.0")>]
+[<assembly: AssemblyMetadataAttribute("ReleaseChannel","release")>]
+[<assembly: AssemblyMetadataAttribute("GitHash","210cf041a0ce44fcc5a5df369550a77a1f75d436")>]
+do ()
+
+module internal AssemblyVersionInformation =
+    let [<Literal>] AssemblyTitle = "FSharp.Azure.Cosmos.Sql"
+    let [<Literal>] AssemblyProduct = "FSharp.Azure.Cosmos"
+    let [<Literal>] AssemblyVersion = "1.2.0"
+    let [<Literal>] AssemblyMetadata_ReleaseDate = "2026-10-01T00:00:00.0000000+02:00"
+    let [<Literal>] AssemblyFileVersion = "1.2.0"
+    let [<Literal>] AssemblyInformationalVersion = "1.2.0"
+    let [<Literal>] AssemblyMetadata_ReleaseChannel = "release"
+    let [<Literal>] AssemblyMetadata_GitHash = "210cf041a0ce44fcc5a5df369550a77a1f75d436"

src/Cosmos.Sql/Catalog.fs

@@ -0,0 +1,68 @@
+/// <summary>
+/// The built-in functions of the query language as data: one <see cref="T:FSharp.Azure.Cosmos.Sql.FunctionSpec"/> per
+/// name, which the translator, the validator, the interpreter, the emulator capability gating and the generated
+/// function coverage page share.
+/// <para>
+/// The catalog holds every name the SDK lists, except its internal names, and every name Microsoft Learn documents.
+/// Entries the translator does not need yet are marked unsupported in their
+/// <see cref="P:FSharp.Azure.Cosmos.Sql.FunctionSpec.Status"/>, with the reason.
+/// </para>
+/// </summary>
+[<RequireQualifiedAccess>]
+module FSharp.Azure.Cosmos.Sql.Catalog
+
+open System
+open System.Collections.Frozen
+open System.Collections.Immutable
+
+/// Every built-in function, grouped like the function index on Microsoft Learn.
+let all : ImmutableArray<FunctionSpec> = CatalogData.functions
+
+/// <summary>
+/// Every built-in function by name. Function names are case-insensitive in the query language, so the lookup uses
+/// <see cref="P:System.StringComparer.OrdinalIgnoreCase"/>.
+/// </summary>
+let byName : FrozenDictionary<string, FunctionSpec> =
+    all.ToFrozenDictionary (_.Name, StringComparer.OrdinalIgnoreCase)
+
+/// <summary>
+/// Looks up the function named <paramref name="name"/>, in any letter case.
+/// </summary>
+/// <param name="name">The name of the function.</param>
+let tryFind (name : string) =
+    // The byref overload, because matching on the tuple form allocates a reference tuple per lookup
+    let mutable spec = Unchecked.defaultof<FunctionSpec>
+    if byName.TryGetValue (name, &spec) then
+        ValueSome spec
+    else
+        ValueNone
+
+/// <summary>
+/// Builds a call of the built-in function named <paramref name="name"/> with <paramref name="arguments"/>, after
+/// checking that the catalog knows the function, specifies it and accepts the number of arguments.
+/// <para>
+/// The call uses the catalog's spelling of the name, so the printed text does not depend on how the caller spelled it.
+/// Where a call may appear, such as a scoring function only in <c>ORDER BY RANK</c>, is checked by
+/// <see cref="M:FSharp.Azure.Cosmos.Sql.SqlQueryModule.validate(FSharp.Azure.Cosmos.Sql.SqlQuery)"/>.
+/// </para>
+/// </summary>
+/// <param name="name">The name of the function, in any letter case.</param>
+/// <param name="arguments">The arguments of the call.</param>
+/// <returns>
+/// The call, or the <see cref="T:FSharp.Azure.Cosmos.Sql.CatalogError"/> that says why it cannot be built: the name is
+/// unknown, the entry is not specified, or <see cref="P:FSharp.Azure.Cosmos.Sql.FunctionSpec.Arity"/> does not accept
+/// the number of arguments.
+/// </returns>
+let call (name : string) (arguments : ImmutableArray<ScalarExpression>) : Result<ScalarExpression, CatalogError> =
+    match tryFind name with
+    | ValueNone -> Error (CatalogError.UnknownFunction name)
+    | ValueSome spec ->
+        match spec.Status with
+        | FunctionStatus.Unsupported reason -> Error (CatalogError.Unsupported (spec.Name, reason))
+        | FunctionStatus.Supported ->
+            let count = if arguments.IsDefault then 0 else arguments.Length
+
+            if spec.Arity.Accepts count then
+                Ok (ScalarExpression.FunctionCall (FunctionRef.BuiltIn spec.Name, EquatableArray arguments))
+            else
+                Error (CatalogError.ArityMismatch (spec.Name, spec.Arity, count))