Fixes

Author: MelbourneDeveloper

Agents.md

@@ -8,7 +8,7 @@
 
 ## Coding Rules
 
-- **NEVER THROW** - Return `Result<T>`. Wrap failures in try/catch
+- **NEVER THROW** - Return `Result<T,E>`. Wrap failures in try/catch
 - **No casting/!** - Pattern match on type only
 - **NO GIT** - Source control is illegal
 - **No suppressing warnings** - Illegal

CLAUDE.md

@@ -8,7 +8,7 @@
 
 ## Coding Rules
 
-- **NEVER THROW** - Return `Result<T>`. Wrap failures in try/catch
+- **NEVER THROW** - Return `Result<T,E>`. Wrap failures in try/catch
 - **No casting/!** - Pattern match on type only
 - **NO GIT** - Source control is illegal
 - **No suppressing warnings** - Illegal

DataProvider/DataProvider/DataProviderConfig.cs

@@ -3,6 +3,20 @@ namespace DataProvider;
 /// <summary>
 /// Configuration for DataProvider code generation
 /// </summary>
+/// <example>
+/// <code>
+/// // Configure tables for code generation
+/// var config = new DataProviderConfig
+/// {
+///     ConnectionString = "Data Source=app.db",
+///     Tables = new List&lt;TableConfig&gt;
+///     {
+///         new TableConfig { Schema = "main", Name = "users", GenerateDelete = true },
+///         new TableConfig { Schema = "main", Name = "orders" }
+///     }.AsReadOnly()
+/// };
+/// </code>
+/// </example>
 public sealed record DataProviderConfig
 {
     /// <summary>
@@ -19,6 +33,21 @@ public sealed record DataProviderConfig
 /// <summary>
 /// Configuration for a single table
 /// </summary>
+/// <example>
+/// <code>
+/// // Configure a table with custom settings
+/// var tableConfig = new TableConfig
+/// {
+///     Schema = "dbo",
+///     Name = "Patients",
+///     GenerateInsert = true,
+///     GenerateUpdate = true,
+///     GenerateDelete = false,
+///     ExcludeColumns = new List&lt;string&gt; { "computed_column" }.AsReadOnly(),
+///     PrimaryKeyColumns = new List&lt;string&gt; { "Id" }.AsReadOnly()
+/// };
+/// </code>
+/// </example>
 public sealed record TableConfig
 {
     /// <summary>

DataProvider/DataProvider/DbConnectionExtensions.cs

@@ -5,19 +5,52 @@
 namespace DataProvider;
 
 /// <summary>
-/// Static extension methods for IDbConnection following FP patterns
+/// Static extension methods for IDbConnection following FP patterns.
+/// All methods return Result types for explicit error handling.
 /// </summary>
+/// <example>
+/// <code>
+/// using var connection = new SqliteConnection("Data Source=:memory:");
+/// connection.Open();
+///
+/// // Execute a query with mapping
+/// var result = connection.Query&lt;Customer&gt;(
+///     sql: "SELECT Id, Name FROM Customers WHERE Active = 1",
+///     mapper: reader => new Customer(
+///         Id: reader.GetInt32(0),
+///         Name: reader.GetString(1)
+///     )
+/// );
+///
+/// // Pattern match on the result
+/// var customers = result switch
+/// {
+///     Result&lt;IReadOnlyList&lt;Customer&gt;, SqlError&gt;.Ok&lt;IReadOnlyList&lt;Customer&gt;, SqlError&gt; ok => ok.Value,
+///     Result&lt;IReadOnlyList&lt;Customer&gt;, SqlError&gt;.Error&lt;IReadOnlyList&lt;Customer&gt;, SqlError&gt; err => throw new Exception(err.Value.Message),
+///     _ => throw new InvalidOperationException()
+/// };
+/// </code>
+/// </example>
 public static class DbConnectionExtensions
 {
     /// <summary>
-    /// Execute a query and return results
+    /// Execute a query and return results.
     /// </summary>
     /// <typeparam name="T">The result type</typeparam>
     /// <param name="connection">The database connection</param>
     /// <param name="sql">The SQL query</param>
     /// <param name="parameters">Optional parameters</param>
     /// <param name="mapper">Function to map from IDataReader to T</param>
     /// <returns>Result with list of T or error</returns>
+    /// <example>
+    /// <code>
+    /// var result = connection.Query&lt;Product&gt;(
+    ///     sql: "SELECT * FROM Products WHERE Price > @minPrice",
+    ///     parameters: [new SqliteParameter("@minPrice", 10.00)],
+    ///     mapper: r => new Product(r.GetInt32(0), r.GetString(1), r.GetDecimal(2))
+    /// );
+    /// </code>
+    /// </example>
     public static Result<IReadOnlyList<T>, SqlError> Query<T>(
         this IDbConnection connection,
         string sql,
@@ -72,12 +105,26 @@ public static Result<IReadOnlyList<T>, SqlError> Query<T>(
     }
 
     /// <summary>
-    /// Execute a non-query command
+    /// Execute a non-query command (INSERT, UPDATE, DELETE).
     /// </summary>
     /// <param name="connection">The database connection</param>
     /// <param name="sql">The SQL command</param>
     /// <param name="parameters">Optional parameters</param>
     /// <returns>Result with rows affected or error</returns>
+    /// <example>
+    /// <code>
+    /// var result = connection.Execute(
+    ///     sql: "UPDATE Products SET Price = @price WHERE Id = @id",
+    ///     parameters: [
+    ///         new SqliteParameter("@price", 19.99),
+    ///         new SqliteParameter("@id", 42)
+    ///     ]
+    /// );
+    ///
+    /// if (result is Result&lt;int, SqlError&gt;.Ok&lt;int, SqlError&gt; ok)
+    ///     Console.WriteLine($"Updated {ok.Value} rows");
+    /// </code>
+    /// </example>
     public static Result<int, SqlError> Execute(
         this IDbConnection connection,
         string sql,

DataProvider/DataProvider/DbTransact.cs

@@ -7,6 +7,24 @@ namespace DataProvider;
 /// Provides transactional helpers as extension methods for <see cref="DbConnection"/>.
 /// Opens a transaction, executes the provided delegate, and commits or rolls back accordingly.
 /// </summary>
+/// <example>
+/// <code>
+/// // Execute multiple operations in a transaction
+/// await connection.Transact(async tx =>
+/// {
+///     await tx.InsertUserAsync(new User { Id = Guid.NewGuid(), Name = "John" });
+///     await tx.InsertOrderAsync(new Order { UserId = userId, Total = 99.99m });
+/// });
+///
+/// // Execute with a return value
+/// var userId = await connection.Transact(async tx =>
+/// {
+///     var user = new User { Id = Guid.NewGuid(), Name = "Jane" };
+///     await tx.InsertUserAsync(user);
+///     return user.Id;
+/// });
+/// </code>
+/// </example>
 public static class DbTransact
 {
     /// <summary>

DataProvider/DataProvider/SchemaTypes.cs

@@ -6,6 +6,31 @@ namespace DataProvider;
 /// <summary>
 /// Represents a database column with its metadata
 /// </summary>
+/// <example>
+/// <code>
+/// // Create a column definition
+/// var column = new DatabaseColumn
+/// {
+///     Name = "Id",
+///     SqlType = "uniqueidentifier",
+///     CSharpType = "Guid",
+///     IsNullable = false,
+///     IsPrimaryKey = true,
+///     IsIdentity = false,
+///     IsComputed = false
+/// };
+///
+/// // Create a string column with max length
+/// var nameColumn = new DatabaseColumn
+/// {
+///     Name = "Name",
+///     SqlType = "nvarchar(100)",
+///     CSharpType = "string",
+///     IsNullable = false,
+///     MaxLength = 100
+/// };
+/// </code>
+/// </example>
 public sealed record DatabaseColumn
 {
     /// <summary>
@@ -62,6 +87,27 @@ public sealed record DatabaseColumn
 /// <summary>
 /// Represents a database table with its columns
 /// </summary>
+/// <example>
+/// <code>
+/// // Create a table definition with columns
+/// var table = new DatabaseTable
+/// {
+///     Schema = "dbo",
+///     Name = "Patients",
+///     Columns = new List&lt;DatabaseColumn&gt;
+///     {
+///         new DatabaseColumn { Name = "Id", SqlType = "uniqueidentifier", IsPrimaryKey = true },
+///         new DatabaseColumn { Name = "Name", SqlType = "nvarchar(100)" },
+///         new DatabaseColumn { Name = "DateOfBirth", SqlType = "date", IsNullable = true }
+///     }.AsReadOnly()
+/// };
+///
+/// // Access computed column lists
+/// var pkColumns = table.PrimaryKeyColumns;
+/// var insertColumns = table.InsertableColumns;
+/// var updateColumns = table.UpdateableColumns;
+/// </code>
+/// </example>
 public sealed record DatabaseTable
 {
     /// <summary>

DataProvider/README.md

@@ -7,7 +7,7 @@ A .NET source generator that creates compile-time safe database extension method
 - **Compile-Time Safety** - SQL queries are validated during compilation, catching errors before runtime
 - **Auto-Generated Extensions** - Creates extension methods on `IDbConnection` and `IDbTransaction`
 - **Schema Inspection** - Automatically inspects database schema to generate appropriate types
-- **Result Type Pattern** - All operations return `Result<T>` types for explicit error handling
+- **Result Type Pattern** - All operations return `Result<T,E>` types for explicit error handling
 - **Multi-Database Support** - Currently supports SQLite and SQL Server
 - **LQL Integration** - Seamlessly works with Lambda Query Language files
 
@@ -244,7 +244,7 @@ For complex result sets with joins, configure grouping in a `.grouping.json` fil
 DataProvider follows functional programming principles:
 
 - **No Classes** - Uses records and static extension methods
-- **No Exceptions** - Returns `Result<T>` types for all operations
+- **No Exceptions** - Returns `Result<T,E>` types for all operations
 - **Pure Functions** - Static methods with no side effects
 - **Expression-Based** - Prefers expressions over statements
 
@@ -277,7 +277,7 @@ dotnet test DataProvider.Tests/DataProvider.Tests.csproj
 
 ## Error Handling
 
-All methods return `Result<T>` types:
+All methods return `Result<T,E>` types:
 
 ```csharp
 var result = await connection.ExecuteQueryAsync();

Migration/Migration/SchemaBuilder.cs

@@ -3,11 +3,29 @@ namespace Migration;
 /// <summary>
 /// Fluent builder for schema definitions.
 /// </summary>
+/// <example>
+/// <code>
+/// var schema = SchemaFactory.Define("MyDatabase")
+///     .Table("users", t => t
+///         .Column("id", PortableTypes.Uuid, c => c.PrimaryKey())
+///         .Column("email", PortableTypes.VarChar(255), c => c.NotNull())
+///         .Column("created_at", PortableTypes.DateTime, c => c.DefaultLql("now()"))
+///         .Index("idx_users_email", "email", unique: true))
+///     .Table("orders", t => t
+///         .Column("id", PortableTypes.Int, c => c.Identity().PrimaryKey())
+///         .Column("user_id", PortableTypes.Uuid, c => c.NotNull())
+///         .Column("total", PortableTypes.Decimal(10, 2))
+///         .ForeignKey("user_id", "users", "id", onDelete: ForeignKeyAction.Cascade))
+///     .Build();
+/// </code>
+/// </example>
 public static class SchemaFactory
 {
     /// <summary>
     /// Start defining a schema with the given name.
     /// </summary>
+    /// <param name="name">The name of the schema/database.</param>
+    /// <returns>A <see cref="SchemaBuilder"/> for fluent configuration.</returns>
     public static SchemaBuilder Define(string name) => new(name);
 }
 
@@ -28,8 +46,20 @@ public static class Schema
 }
 
 /// <summary>
-/// Builder for creating schema definitions.
+/// Builder for creating schema definitions with tables, columns, indexes, and constraints.
 /// </summary>
+/// <example>
+/// <code>
+/// var schema = Schema.Define("inventory")
+///     .Table("products", t => t
+///         .Column("id", PortableTypes.Int, c => c.Identity().PrimaryKey())
+///         .Column("name", PortableTypes.VarChar(100), c => c.NotNull())
+///         .Column("price", PortableTypes.Decimal(10, 2), c => c.NotNull().Check("price >= 0"))
+///         .Column("sku", PortableTypes.VarChar(50), c => c.NotNull())
+///         .Unique("uq_products_sku", "sku"))
+///     .Build();
+/// </code>
+/// </example>
 public sealed class SchemaBuilder
 {
     private readonly string _name;
@@ -66,8 +96,23 @@ public SchemaBuilder Table(string schema, string name, Action<TableBuilder> conf
 }
 
 /// <summary>
-/// Builder for creating table definitions.
+/// Builder for creating table definitions with columns, indexes, foreign keys, and constraints.
 /// </summary>
+/// <example>
+/// <code>
+/// // Define a table with various column types and constraints
+/// .Table("employees", t => t
+///     .Column("id", PortableTypes.Uuid, c => c.PrimaryKey().DefaultLql("gen_uuid()"))
+///     .Column("name", PortableTypes.VarChar(100), c => c.NotNull())
+///     .Column("email", PortableTypes.VarChar(255), c => c.NotNull())
+///     .Column("department_id", PortableTypes.Int)
+///     .Column("salary", PortableTypes.Decimal(12, 2))
+///     .Column("hired_at", PortableTypes.DateTime, c => c.DefaultLql("now()"))
+///     .Index("idx_employees_email", "email", unique: true)
+///     .Index("idx_employees_dept", "department_id")
+///     .ForeignKey("department_id", "departments", "id"))
+/// </code>
+/// </example>
 public sealed class TableBuilder
 {
     private readonly string _name;
@@ -279,8 +324,26 @@ internal TableDefinition Build() =>
 }
 
 /// <summary>
-/// Builder for creating column definitions.
+/// Builder for creating column definitions with type, nullability, defaults, and constraints.
 /// </summary>
+/// <example>
+/// <code>
+/// // UUID primary key with auto-generation
+/// .Column("id", PortableTypes.Uuid, c => c.PrimaryKey().DefaultLql("gen_uuid()"))
+///
+/// // Required string with max length
+/// .Column("name", PortableTypes.VarChar(100), c => c.NotNull())
+///
+/// // Auto-increment integer
+/// .Column("sequence", PortableTypes.Int, c => c.Identity())
+///
+/// // Decimal with precision and check constraint
+/// .Column("price", PortableTypes.Decimal(10, 2), c => c.NotNull().Check("price > 0"))
+///
+/// // DateTime with default to current timestamp
+/// .Column("created_at", PortableTypes.DateTime, c => c.DefaultLql("now()"))
+/// </code>
+/// </example>
 public sealed class ColumnBuilder
 {
     private readonly string _name;

Migration/Migration/SchemaDiff.cs

@@ -4,6 +4,33 @@ namespace Migration;
 /// Calculates the difference between two schema definitions.
 /// Produces a list of operations to transform current schema into desired schema.
 /// </summary>
+/// <example>
+/// <code>
+/// // Compare current database schema against desired schema
+/// var currentSchema = await schemaInspector.InspectAsync(connection);
+/// var desiredSchema = Schema.Define("mydb")
+///     .Table("users", t => t
+///         .Column("id", PortableTypes.Uuid, c => c.PrimaryKey())
+///         .Column("email", PortableTypes.VarChar(255), c => c.NotNull())
+///         .Column("name", PortableTypes.VarChar(100)))  // New column
+///     .Build();
+///
+/// // Calculate safe (additive-only) migration operations
+/// var result = SchemaDiff.Calculate(currentSchema, desiredSchema);
+/// if (result is OperationsResult.Ok&lt;IReadOnlyList&lt;SchemaOperation&gt;, MigrationError&gt; ok)
+/// {
+///     foreach (var op in ok.Value)
+///     {
+///         var ddl = ddlGenerator.Generate(op);
+///         await connection.ExecuteAsync(ddl);
+///     }
+/// }
+///
+/// // Or allow destructive changes (DROP operations)
+/// var destructiveResult = SchemaDiff.Calculate(
+///     currentSchema, desiredSchema, allowDestructive: true);
+/// </code>
+/// </example>
 public static class SchemaDiff
 {
     /// <summary>