Integrate todo items in prd

yevhen · yevhen · commit 54bcb9daab30 · 2025-10-12T20:46:23.000+03:00
diff --git a/TODO.md b/TODO.md
@@ -1,58 +0,0 @@
-- Move all tests to integration tests and test only via front door (Assert)
-- Expose Assert(() => x => y) overload method in Sharp class to delegate to included PowerAssert directly
-- Review dynamic support - make sure that dynamic = {...} objects are properly formatted
-- Custom formatters
-- Custom comparisons
-
-----
-
-Dynamic - only implement (general/binary). Need to be tested/extended to work properly with objects/collections/expando
-```csharp
-dynamic json = JsonSerializer.Deserialize<dynamic>(jsonString);
-Console.WriteLine(json.user.name);
-```
-
-```csharp
-dynamic person = new ExpandoObject();
-person.Name = "Yevhen";
-person.Age = 42;
-Console.WriteLine($"{person.Name} ({person.Age})");
-```
-
-----
-
-**External diff viewers** - this is important to implement.
-- Need proper research. In pycharm when pytest assert fails it shows nice diff right inside ide using native means.
-- It would be cool impl similar for large multiline strings, or maps, etc. Need to think where this could be useful.
-
-----
-
-**Debugging the Rewriter** - not sure what value this will bring and what changes these requires.
-To facilitate debugging, the rewrite task will support a diagnostic MSBuild property:
-
-```xml
-<PropertyGroup>
-  <SharpAssertEmitRewriteInfo>true</SharpAssertEmitRewriteInfo>
-</PropertyGroup>
-```
-
-When enabled, the rewriter will output detailed logs of its analysis and decisions. This is crucial for troubleshooting unexpected rewrite behavior.
-
-----
-
-**Dependencies**
-- PowerAssert (current) — is not used anymore as automatic fallback for unsupported features (need to find all references to this fact and update)
-- DiffPlex — string & sequence diffs
-- Compare‑Net‑Objects — deep object diffs
-- Verify.*  — external diff tooling
-
-All these packages need to be properly attributed in README.md
-
-----
-
-**Rewriter Robustness & Fallback - pending**
-
-- Wrap rewriter logic in try-catch
-- If analysis fails, leave original Assert call
-- Add diagnostic logging controlled by MSBuild property - this looks like 4.3
-- Test with edge cases and invalid code 
diff --git a/prd.md b/prd.md
@@ -8,16 +8,107 @@
 
 **See [CONSTITUTION.md](CONSTITUTION.md)** for the immutable architectural principles and core philosophy.
 
+Key invariants:
+- Hybrid architecture: minimal rewriter, rich runtime
+- Never break the build (graceful fallback)
+- Single evaluation, single materialization
+- Simple API, rich diagnostics
+- Pay-on-failure performance
+
+---
+
+## Implementation Roadmap
+
+### High Priority (Polish & Correctness)
+
+#### 1. Move All Tests to Integration Tests (Front Door Only)
+**Goal:** Test only via public API `Assert()`, not internal methods.
+
+**Why:** Ensures we're testing user-facing behavior, catches integration issues.
+
+**Tasks:**
+- Move unit tests from `SharpInternal.*` direct calls to `Sharp.Assert()` calls
+- Keep tests focused on behavior, not implementation
+- Verify all edge cases still covered
+
 ---
 
-## Remaining Work
+#### 2. Enhanced Dynamic Support (Objects/Collections/ExpandoObject)
+**Goal:** Make dynamic object comparisons work with proper formatting.
+
+**Current State:** Basic dynamic binary/general implemented but needs extension.
 
-### Verify.* Integration (External Diff Viewers)
-**Status:** Not Started
-**Goal:** When string/object diffs are large, write `.received`/`.verified` files and open configured diff tool.
+**Test Cases:**
+```csharp
+// JSON deserialization
+dynamic json = JsonSerializer.Deserialize<dynamic>(jsonString);
+Assert(json.user.name == "expected");
+
+// ExpandoObject
+dynamic person = new ExpandoObject();
+person.Name = "Yevhen";
+person.Age = 42;
+Assert(person.Age > 40);
+
+// Dynamic collections
+dynamic obj = new { Items = new[] { 1, 2, 3 } };
+Assert(obj.Items.Contains(5));  // Should show collection contents
+```
+
+**Tasks:**
+- Test dynamic objects with nested properties
+- Test dynamic with collections (arrays, lists)
+- Test ExpandoObject scenarios
+- Ensure proper formatting for dynamic objects in diagnostics
+
+---
+
+#### 3. Rewriter Diagnostic Logging (`SharpAssertEmitRewriteInfo`)
+**Goal:** Support MSBuild property for troubleshooting rewriter behavior.
 
 **Implementation:**
-- Integrate Verify.* packages (Verify.Xunit, Verify.NUnit, Verify.MSTest).
+```xml
+<PropertyGroup>
+  <SharpAssertEmitRewriteInfo>true</SharpAssertEmitRewriteInfo>
+</PropertyGroup>
+```
+
+**Tasks:**
+- Add logging infrastructure to rewriter task
+- Log: detected await/dynamic, chosen rewrite path, fallback reasons
+- Write logs to MSBuild diagnostic output
+- Document in README/troubleshooting guide
+
+---
+
+#### 4. Documentation: Dependency Attribution
+**Goal:** Properly credit all third-party dependencies in README.md.
+
+**Dependencies to attribute:**
+- **DiffPlex** — string & sequence diffs
+- **Compare-Net-Objects** — deep object diffs
+- **PowerAssert** — optional alternative/fallback mode (clarify current usage)
+
+**Tasks:**
+- Add "Credits" or "Dependencies" section to README.md
+- Link to each package's repository
+- Clarify PowerAssert relationship (optional vs. fallback vs. not used)
+- Review all references to PowerAssert fallback behavior
+
+---
+
+### Medium Priority (New Features)
+
+#### 5. External Diff Viewers (Verify.* Integration)
+**Goal:** For large diffs, write `.received`/`.verified` files and open configured diff tool.
+
+**Research Needed:**
+- How PyCharm/pytest shows inline diffs in IDE
+- What triggers "large diff" threshold
+- Best UI/UX for .NET developers
+
+**Implementation:**
+- Integrate Verify.* packages (Verify.Xunit, Verify.NUnit, Verify.MSTest)
 - Write assertion failure artifacts to `.received`/`.verified` files
 - Open configured diff tool (VS Code, Beyond Compare, etc.)
 - For NUnit/MSTest: attach files via `TestContext.AddTestAttachment` / `AddResultFile`
@@ -29,22 +120,66 @@ dotnet add package Verify.Xunit  # or NUnit/MSTest variants
 
 ---
 
-### Custom Formatter Registry
-**Status:** Not Started
+#### 6. Expose Direct PowerAssert Integration
+**Goal:** Allow users to call PowerAssert directly via `Sharp.Assert(() => ...)` overload.
+
+**API:**
+```csharp
+// Current: Sharp.Assert(bool condition)
+// New: Sharp.Assert(Expression<Func<bool>> condition)  // delegates to PowerAssert
+```
+
+**Why:** Gives users escape hatch if they prefer PowerAssert diagnostics for specific assertions.
+
+**Tasks:**
+- Add overload that accepts `Expression<Func<bool>>`
+- Delegate directly to PowerAssert.PAssert.IsTrue
+- Document when to use this overload
+- Test that it works alongside rewritten assertions
+
+---
+
+#### 7. Custom Formatters Registry
 **Goal:** Allow users to register custom formatters for domain types.
 
-**Example API:**
+**API:**
 ```csharp
 SharpConfig.RegisterFormatter<MyType>((value, context) =>
 {
     return $"MyType({value.Id}, {value.Name})";
 });
 ```
 
+**Tasks:**
+- Design formatter API (signature, context object)
+- Implement formatter registry (thread-safe)
+- Integrate into diagnostic pipeline
+- Document with examples
+
+---
+
+#### 8. Custom Comparers
+**Goal:** Allow users to register custom equality comparers for types.
+
+**API:**
+```csharp
+SharpConfig.RegisterComparer<MyType>((left, right) =>
+{
+    return left.Id == right.Id;  // Custom equality logic
+});
+```
+
+**Tasks:**
+- Design comparer API
+- Implement comparer registry (thread-safe)
+- Integrate into comparison logic
+- Document with examples
+
 ---
 
-### HTML Diff Emitter
-**Status:** Not Started
+### Low Priority (Nice-to-Have)
+
+#### 9. HTML Diff Emitter
 **Goal:** Generate HTML diff artifacts for CI/CD pipelines.
 
 **Implementation:**
@@ -54,8 +189,7 @@ SharpConfig.RegisterFormatter<MyType>((value, context) =>
 
 ---
 
-### SourceLink-based Expression Embedding
-**Status:** Not Started
+#### 10. SourceLink-based Expression Embedding
 **Goal:** Use SourceLink to embed original expression text without CallerArgumentExpression.
 
 **Rationale:**
@@ -66,6 +200,21 @@ SharpConfig.RegisterFormatter<MyType>((value, context) =>
 
 ## Reference Documentation
 
+### Current Implementation Status
+
+All core features are **✅ COMPLETED**:
+- Basic assertions with CallerArgumentExpression
+- Expression tree runtime with binary/logical operators
+- MSBuild rewriter with PowerAssert fallback
+- String diffs (DiffPlex)
+- Collection comparisons
+- Object deep diffs (Compare-Net-Objects)
+- LINQ operations (Contains/Any/All/SequenceEqual)
+- Async/await support
+- Dynamic type support (basic)
+- Nullable type support
+- Graceful rewriter fallback
+
 ### API Reference
 
 **Public API:**
@@ -125,11 +274,21 @@ public static class SharpInternal
 - CompareNETObjects (object deep diffs)
 
 **Optional:**
-- PowerAssert (alternative mode)
+- PowerAssert (alternative mode via explicit overload - future)
 - Verify.* (external diff viewers - future)
 
 ---
 
+## Non-Goals
+
+- Full AST explanation for async/dynamic beyond thunks
+- Expression trees for await/dynamic (C# limitation)
+- Rewriting outside test projects
+- IDE integration/plugins
+- Performance profiling tools
+
+---
+
 ## Testing Commands
 
 **Fast development cycle:**
