From e9833e9498d99c3cddad4686ee794c01a839109e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 27 Mar 2026 23:34:02 +0000
Subject: [PATCH 1/2] Initial plan
From cda2b9f03cfe930533b244f4191a98aa08a0cdba Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 27 Mar 2026 23:36:54 +0000
Subject: [PATCH 2/2] Add .github/copilot-instructions.md for Copilot agent
onboarding
Agent-Logs-Url: https://github.com/TrinityWestern/Lasy/sessions/98a2c6ba-fec6-4bb2-a2e2-1f2de749ddd0
Co-authored-by: andrewmenary <1131938+andrewmenary@users.noreply.github.com>
---
.github/copilot-instructions.md | 184 ++++++++++++++++++++++++++++++++
1 file changed, 184 insertions(+)
create mode 100644 .github/copilot-instructions.md
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..09021ec
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,184 @@
+# Copilot Instructions for Lasy
+
+## Project Overview
+
+**Lasy** is a C# database abstraction library that provides a unified interface for multiple database backends. It targets **.NET Framework 4.0** and enables code to be written against clean interfaces (`IReadable`, `IWriteable`, `IReadWrite`) that can be backed by a real SQL Server database, an in-memory fake database, or a file-based database — making unit testing straightforward.
+
+---
+
+## Repository Structure
+
+```
+/
+├── .github/
+│ └── copilot-instructions.md # This file
+├── lib/
+│ └── nunit.framework.dll # NUnit 2.5.10 test runner (checked in)
+├── src/ # Main library source (~21 C# files)
+│ ├── Core Interfaces
+│ │ ├── IReadable.cs # Read operations contract
+│ │ ├── IWriteable.cs # Write operations contract
+│ │ ├── IReadWrite.cs # Combined read/write interface
+│ │ ├── ITransaction.cs # Transaction contract (Commit/Rollback)
+│ │ └── IDBAnalyzer.cs # Database metadata contract
+│ ├── SQL Server Implementation
+│ │ ├── RealDB.cs # SqlConnection-backed implementation
+│ │ ├── RealDBTransaction.cs # Wraps SqlTransaction
+│ │ ├── SQLAnalyzer.cs # Abstract base for SQL metadata
+│ │ ├── SQL2000DBAnalyzer.cs # SQL Server 2000 metadata queries
+│ │ └── SQL2005DBAnalyzer.cs # SQL Server 2005+ metadata queries
+│ ├── In-Memory Fake Implementation
+│ │ ├── FakeDB.cs # Dictionary-backed in-memory store
+│ │ ├── FakeDBTable.cs # Per-table storage and operations
+│ │ ├── FakeDBTransaction.cs # Simulated transaction
+│ │ └── FakeDBAnalyzer.cs # Metadata for fake database
+│ ├── File-Based Implementation
+│ │ └── FileDB.cs # Reads SQL Management Studio .rpt files
+│ ├── Utilities & Extensions
+│ │ ├── IReadableExtensions.cs
+│ │ ├── IWritableExtensions.cs
+│ │ ├── IReadWriteExtensions.cs
+│ │ ├── SqlExtensions.cs
+│ │ ├── SqlTypeConversion.cs
+│ │ └── LasyExceptions.cs # KeyNotSetException, ThisSadlyHappenedException
+│ ├── Lasy.csproj
+│ └── Properties/AssemblyInfo.cs
+└── test/ # NUnit test project (~8 C# files)
+ ├── FakeDBTests.cs
+ ├── FileDBTests.cs
+ ├── RealDBTests.cs # Requires live SQL Server connection
+ ├── FakeDBTableTests.cs
+ ├── IReadWriteExtensionTests.cs
+ ├── SqlTypeConversionTests.cs
+ ├── Person.cs # Test model
+ ├── Organization.cs # Test model
+ ├── FileDBData/ # .rpt test data files
+ │ ├── simple.rpt
+ │ ├── variableWidth.rpt
+ │ └── withNull.rpt
+ ├── Lasy.Tests.csproj
+ └── Properties/AssemblyInfo.cs
+```
+
+---
+
+## Tech Stack
+
+| Concern | Technology |
+|---------|-----------|
+| Language | C# |
+| Runtime | .NET Framework 4.0 |
+| Build | MSBuild (via .csproj files, ToolsVersion 4.0) |
+| Tests | NUnit 2.5.10 (DLL checked in at `lib/nunit.framework.dll`) |
+| SQL Backend | SQL Server (via `System.Data.SqlClient`) |
+| Key Dependency | **Nvelope** — expected at `../../Nvelope/src/Nvelope.csproj` |
+
+---
+
+## Building the Project
+
+```bash
+# Build main library
+msbuild src/Lasy.csproj /p:Configuration=Debug
+
+# Build test project
+msbuild test/Lasy.Tests.csproj /p:Configuration=Debug
+```
+
+Output assemblies are placed in `bin/Debug/` or `bin/Release/` relative to each project.
+
+**Important**: The project depends on **Nvelope**, a sibling repository that must be cloned at `../../Nvelope/` (relative to this repo root) before the build will succeed. If Nvelope is missing, you will see project reference resolution errors.
+
+---
+
+## Running Tests
+
+Tests use **NUnit 2.5.10**. After building the test project:
+
+```bash
+# Run with NUnit console runner (path to runner may vary)
+nunit-console test/bin/Debug/Lasy.Tests.dll
+
+# Or use the NUnit GUI runner against the compiled DLL
+```
+
+**Notes on test categories**:
+- `FakeDBTests`, `FakeDBTableTests`, `IReadWriteExtensionTests`, `SqlTypeConversionTests`, `FileDBTests` — run without any external dependencies.
+- `RealDBTests` — requires a live SQL Server instance with a connection string. These tests will fail or be skipped in environments without a database.
+
+---
+
+## Linting
+
+There is no dedicated linting tool configured. The build uses `4` so compiler warnings serve as the primary code-quality signal. Run the build and inspect compiler output for warnings.
+
+---
+
+## Core Design Patterns
+
+### 1. Interface-Based Abstraction
+All consumers code to `IReadable`, `IWriteable`, or `IReadWrite`. Swap implementations without changing consumer code:
+
+```csharp
+// Production
+IReadWrite db = new RealDB(connectionString, new SQL2005DBAnalyzer(connectionString));
+
+// Unit tests (no database required)
+IReadWrite db = new FakeDB();
+
+// Integration tests from snapshot data
+IReadable db = new FileDB("test/FileDBData");
+```
+
+### 2. Dictionary-Based Data Model
+There is no ORM or entity class generation. All rows are represented as `Dictionary` where keys are column names. This keeps the library flexible but means consumers must handle type conversions themselves (see `SqlTypeConversion`).
+
+### 3. Analyzer Pattern (Metadata Abstraction)
+The `IDBAnalyzer` interface decouples the library from the specific way each database exposes metadata (primary keys, auto-number columns, field lists). Each DB implementation pairs with an analyzer:
+- `RealDB` → `SQL2005DBAnalyzer` or `SQL2000DBAnalyzer`
+- `FakeDB` → `FakeDBAnalyzer`
+
+### 4. Extension Methods
+Heavy use of extension methods to add functionality without modifying core classes. When adding operations that apply across multiple implementations, prefer extension methods in the appropriate `I*Extensions.cs` file.
+
+### 5. Metadata Caching
+`SQLAnalyzer` uses Nvelope's `.Memoize()` to cache metadata lookups (primary keys, field lists) for 10 minutes. This avoids repeated round-trips to system tables at runtime.
+
+---
+
+## Key Conventions
+
+- **Private fields**: Underscore prefix (`_db`, `_conn`, `_dbAnalyzer`)
+- **Methods & Properties**: PascalCase
+- **Parameters & local variables**: camelCase
+- **Interfaces**: `I` prefix (`IReadable`, `IWriteable`)
+- **Test classes**: NUnit `[TestFixture]` attribute, test methods with `[Test]`
+- **No solution (.sln) file** — build each `.csproj` directly with MSBuild
+
+---
+
+## Known Issues & Workarounds
+
+1. **Nvelope dependency**: The project references Nvelope via a relative path (`../../Nvelope/src/Nvelope.csproj`). If this sibling repo is not present, the build fails with project reference errors. Clone Nvelope into the parent directory to resolve this.
+
+2. **No CI/CD pipeline**: There are no GitHub Actions workflows, no AppVeyor, and no other CI configuration. Tests must be run locally.
+
+3. **RealDB tests require SQL Server**: `RealDBTests.cs` will fail without a SQL Server instance. Skip or isolate these tests in environments without a database.
+
+4. **README is empty**: The `README` file at the repo root has no content. Refer to this file for onboarding information instead.
+
+5. **NUnit version**: The project uses NUnit 2.5.10 (very old). The DLL is checked in under `lib/`. Do not upgrade NUnit without updating all test attributes — NUnit 3.x has breaking API changes.
+
+6. **FileDB reads SQL Management Studio `.rpt` files**: These are fixed-width text exports. The parser in `FileDB.cs` is sensitive to column alignment; any `.rpt` files added to `test/FileDBData/` must preserve the fixed-width format.
+
+---
+
+## Adding New Features — Checklist
+
+When adding a new database operation:
+1. Add the method signature to the appropriate interface (`IReadable`, `IWriteable`, or `IReadWrite`).
+2. Implement the method in `RealDB` (SQL Server).
+3. Implement the method in `FakeDB` and `FakeDBTable` (in-memory).
+4. Add a convenience overload in the corresponding `I*Extensions.cs` file if needed.
+5. Add `FakeDBTests` coverage — these can run without a live database.
+6. Add `RealDBTests` coverage if the behavior differs from the fake (optional; requires SQL Server).