@polymorphism-tech/morph-spec 4.3.0 → 4.3.2

package/stacks/blazor-azure/.morph/standards/core/testing.md

@@ -0,0 +1,295 @@
+# Testing Standards
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** test, testing, unit, integration, xunit, nunit
+> **Load When:** always
+
+Test patterns and best practices for MORPH-SPEC projects
+
+---
+
+## Test Pyramid
+
+```
+        /\
+       /  \  E2E Tests (10%)
+      /____\
+     /      \
+    / Integration  Tests (30%)
+   /________________\
+  /                  \
+ /   Unit Tests (60%)  \
+/_______________________\
+```
+
+### Distribution
+
+- **Unit Tests (60%)**: Fast, isolated, test single units
+- **Integration Tests (30%)**: Test component interactions
+- **E2E Tests (10%)**: Full user workflows
+
+---
+
+## Naming Conventions
+
+### Format
+
+```
+MethodName_Scenario_ExpectedBehavior
+```
+
+### Examples
+
+```csharp
+// .NET (xUnit)
+[Fact]
+public void Login_ValidCredentials_ReturnsAuthToken() { }
+
+[Fact]
+public void Login_InvalidPassword_ThrowsUnauthorizedException() { }
+
+[Theory]
+[InlineData("user@example.com", "password123")]
+public void Register_ValidInput_CreatesUser(string email, string password) { }
+```
+
+```typescript
+// JavaScript (Jest/Vitest)
+describe('UserService', () => {
+  it('should return auth token for valid credentials', () => {})
+
+  it('should throw error for invalid password', () => {})
+
+  it.each([
+    ['user@example.com', 'password123'],
+    ['admin@test.com', 'admin456']
+  ])('should create user for %s', (email, password) => {})
+})
+```
+
+---
+
+## Unit Testing Best Practices
+
+### Arrange-Act-Assert (AAA)
+
+```csharp
+[Fact]
+public void CalculateTotal_WithDiscount_AppliesCorrectPercentage()
+{
+    // Arrange
+    var cart = new ShoppingCart();
+    cart.AddItem(new Item { Price = 100 });
+    var discountService = new DiscountService();
+
+    // Act
+    var total = discountService.CalculateTotal(cart, discountPercent: 10);
+
+    // Assert
+    Assert.Equal(90, total);
+}
+```
+
+### Mocking Dependencies
+
+```csharp
+[Fact]
+public async Task GetUser_ValidId_ReturnsUser()
+{
+    // Arrange
+    var mockRepo = new Mock<IUserRepository>();
+    mockRepo.Setup(r => r.GetByIdAsync(1))
+            .ReturnsAsync(new User { Id = 1, Name = "John" });
+
+    var service = new UserService(mockRepo.Object);
+
+    // Act
+    var user = await service.GetUserAsync(1);
+
+    // Assert
+    Assert.NotNull(user);
+    Assert.Equal("John", user.Name);
+}
+```
+
+---
+
+## Integration Testing
+
+### Database Tests
+
+```csharp
+public class UserRepositoryTests : IClassFixture<DatabaseFixture>
+{
+    private readonly AppDbContext _context;
+
+    public UserRepositoryTests(DatabaseFixture fixture)
+    {
+        _context = fixture.CreateContext();
+    }
+
+    [Fact]
+    public async Task CreateUser_ValidData_SavesToDatabase()
+    {
+        // Arrange
+        var repo = new UserRepository(_context);
+        var user = new User { Email = "test@example.com" };
+
+        // Act
+        await repo.CreateAsync(user);
+        await _context.SaveChangesAsync();
+
+        // Assert
+        var saved = await _context.Users.FirstOrDefaultAsync(u => u.Email == "test@example.com");
+        Assert.NotNull(saved);
+    }
+}
+```
+
+### API Tests
+
+```csharp
+public class AuthControllerTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+
+    public AuthControllerTests(WebApplicationFactory<Program> factory)
+    {
+        _client = factory.CreateClient();
+    }
+
+    [Fact]
+    public async Task Login_ValidCredentials_Returns200AndToken()
+    {
+        // Arrange
+        var request = new LoginRequest { Email = "user@test.com", Password = "password" };
+
+        // Act
+        var response = await _client.PostAsJsonAsync("/api/auth/login", request);
+
+        // Assert
+        response.EnsureSuccessStatusCode();
+        var result = await response.Content.ReadFromJsonAsync<AuthResponse>();
+        Assert.NotNull(result?.Token);
+    }
+}
+```
+
+---
+
+## E2E Testing
+
+### Playwright Example
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('user can login and access dashboard', async ({ page }) => {
+  // Navigate to login
+  await page.goto('/login');
+
+  // Fill credentials
+  await page.fill('input[name="email"]', 'user@example.com');
+  await page.fill('input[name="password"]', 'password123');
+
+  // Submit
+  await page.click('button[type="submit"]');
+
+  // Verify redirect to dashboard
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+});
+```
+
+---
+
+## Test Coverage
+
+### Targets
+
+- **Statements**: ≥ 80%
+- **Branches**: ≥ 70%
+- **Functions**: ≥ 80%
+- **Lines**: ≥ 80%
+
+### Running Coverage
+
+```bash
+# .NET
+dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover
+
+# JavaScript
+npm run test:coverage
+```
+
+---
+
+## Best Practices
+
+### DO
+
+✅ Write tests before or with code (TDD)
+✅ Test edge cases (null, empty, invalid input)
+✅ Use descriptive test names
+✅ Keep tests fast (< 1s per unit test)
+✅ Mock external dependencies
+✅ Test one thing per test
+
+### DON'T
+
+❌ Test implementation details (test behavior)
+❌ Rely on test execution order
+❌ Use real databases in unit tests
+❌ Hardcode magic values (use constants)
+❌ Skip tests (fix or remove)
+❌ Write tests that depend on external services
+
+---
+
+## Test Fixtures and Cleanup
+
+### xUnit
+
+```csharp
+public class DatabaseFixture : IDisposable
+{
+    public AppDbContext CreateContext()
+    {
+        var options = new DbContextOptionsBuilder<AppDbContext>()
+            .UseInMemoryDatabase($"TestDb_{Guid.NewGuid()}")
+            .Options;
+
+        return new AppDbContext(options);
+    }
+
+    public void Dispose()
+    {
+        // Cleanup
+    }
+}
+```
+
+### Jest
+
+```typescript
+beforeEach(() => {
+  // Setup before each test
+});
+
+afterEach(() => {
+  // Cleanup after each test
+});
+
+beforeAll(() => {
+  // Setup once before all tests
+});
+
+afterAll(() => {
+  // Cleanup once after all tests
+});
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/blazor-azure/.morph/standards/data/nosql/blob-storage.md

@@ -0,0 +1,102 @@
+# Data Standard: Azure Blob Storage
+
+## Overview
+Object storage for files, images, documents, and large binary data.
+
+## Setup
+```xml
+<PackageReference Include="Azure.Storage.Blobs" Version="12.*" />
+```
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton(new BlobServiceClient(
+    new Uri(config["Storage:AccountUrl"]),
+    new DefaultAzureCredential())); // Managed Identity — no connection string
+```
+
+## Service Pattern
+```csharp
+public class BlobStorageService : IFileStorageService
+{
+    private readonly BlobContainerClient _container;
+
+    public BlobStorageService(BlobServiceClient client, IConfiguration config)
+    {
+        _container = client.GetBlobContainerClient(config["Storage:ContainerName"]);
+    }
+
+    public async Task<string> UploadAsync(Stream content, string fileName, string contentType)
+    {
+        var blobName = $"{DateTime.UtcNow:yyyy/MM/dd}/{Guid.NewGuid()}/{fileName}";
+        var blob = _container.GetBlobClient(blobName);
+
+        await blob.UploadAsync(content, new BlobHttpHeaders { ContentType = contentType });
+        return blobName; // Return blob path, not URL
+    }
+
+    public async Task<Stream> DownloadAsync(string blobName)
+    {
+        var blob = _container.GetBlobClient(blobName);
+        var response = await blob.DownloadAsync();
+        return response.Value.Content;
+    }
+
+    public async Task DeleteAsync(string blobName)
+    {
+        var blob = _container.GetBlobClient(blobName);
+        await blob.DeleteIfExistsAsync();
+    }
+
+    public Uri GenerateSasUrl(string blobName, TimeSpan expiry)
+    {
+        var blob = _container.GetBlobClient(blobName);
+        return blob.GenerateSasUri(BlobSasPermissions.Read, DateTimeOffset.UtcNow.Add(expiry));
+    }
+}
+```
+
+## Security Requirements
+
+### Always Use Managed Identity
+```csharp
+// ✅ Managed Identity — no secrets
+new BlobServiceClient(storageUri, new DefaultAzureCredential())
+
+// ❌ Connection string — avoid
+new BlobServiceClient(connectionString)
+```
+
+### SAS Tokens for Client Access
+```csharp
+// Generate short-lived SAS for client-side uploads
+var sasUri = blob.GenerateSasUri(BlobSasPermissions.Write, DateTimeOffset.UtcNow.AddMinutes(15));
+// Send SAS URL to client — they upload directly
+```
+
+### Container Access Levels
+- `Private`: No public access (default for user documents)
+- `Blob`: Public read for specific blobs (CDN-served images)
+- `Container`: Public read for all blobs (avoid in most cases)
+
+## Content Types + Validation
+```csharp
+private static readonly HashSet<string> AllowedTypes = ["image/jpeg", "image/png", "application/pdf"];
+private const long MaxFileSizeBytes = 10 * 1024 * 1024; // 10 MB
+
+public async Task<string> UploadValidatedAsync(IFormFile file)
+{
+    if (!AllowedTypes.Contains(file.ContentType))
+        throw new ValidationException($"File type {file.ContentType} not allowed");
+    if (file.Length > MaxFileSizeBytes)
+        throw new ValidationException("File exceeds 10 MB limit");
+
+    return await UploadAsync(file.OpenReadStream(), file.FileName, file.ContentType);
+}
+```
+
+## Blob Lifecycle (Cost Management)
+- Move to Cool tier after 30 days
+- Move to Archive tier after 90 days
+- Delete after 365 days (unless legal hold)
+- Configure via Storage Account Lifecycle Management rules (Bicep)

package/stacks/blazor-azure/.morph/standards/data/nosql/cache/redis.md

@@ -0,0 +1,97 @@
+# Data Standard: Redis Cache (Azure Cache for Redis)
+
+## Overview
+Distributed cache for session data, rate limiting, and frequently-read data.
+
+## Setup
+```xml
+<PackageReference Include="StackExchange.Redis" Version="2.*" />
+<PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="9.*" />
+```
+
+```csharp
+// Program.cs
+builder.Services.AddStackExchangeRedisCache(opts =>
+{
+    opts.Configuration = config["Redis:ConnectionString"]; // from Key Vault
+    opts.InstanceName = "myapp:"; // Prefix to avoid key collisions
+});
+```
+
+## Cache-Aside Pattern
+```csharp
+public class CachedProductService : IProductService
+{
+    private readonly IDistributedCache _cache;
+    private readonly IProductRepository _repository;
+
+    public async Task<Product?> GetAsync(Guid id, CancellationToken ct = default)
+    {
+        var cacheKey = $"product:{id}";
+
+        // Try cache first
+        var cached = await _cache.GetStringAsync(cacheKey, ct);
+        if (cached != null)
+            return JsonSerializer.Deserialize<Product>(cached);
+
+        // Cache miss → read from DB
+        var product = await _repository.GetAsync(id, ct);
+        if (product == null) return null;
+
+        // Cache with TTL
+        await _cache.SetStringAsync(cacheKey,
+            JsonSerializer.Serialize(product),
+            new DistributedCacheEntryOptions
+            {
+                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(15),
+                SlidingExpiration = TimeSpan.FromMinutes(5)
+            }, ct);
+
+        return product;
+    }
+
+    public async Task InvalidateAsync(Guid id, CancellationToken ct = default)
+        => await _cache.RemoveAsync($"product:{id}", ct);
+}
+```
+
+## TTL Strategy
+| Data Type | TTL | Rationale |
+|-----------|-----|-----------|
+| User session | 30 min sliding | Active session window |
+| Product catalog | 15 min absolute | Inventory changes |
+| Rate limit counters | 1 min | Per-minute limiting |
+| Computed aggregates | 1 hour | Expensive query results |
+| Reference data | 24 hours | Config rarely changes |
+
+## Key Naming Convention
+```
+{service}:{entity}:{id}
+{service}:{entity}:list:{filter}
+{service}:ratelimit:{userId}:{endpoint}
+
+Examples:
+  product:detail:550e8400-e29b-41d4-a716
+  product:list:category:electronics
+  auth:ratelimit:user123:login
+```
+
+## Rate Limiting Pattern
+```csharp
+public async Task<bool> IsRateLimitedAsync(string userId, string action, int maxPerMinute)
+{
+    var key = $"ratelimit:{action}:{userId}:{DateTime.UtcNow:yyyyMMddHHmm}";
+    var db = _redis.GetDatabase();
+
+    var count = await db.StringIncrementAsync(key);
+    if (count == 1) await db.KeyExpireAsync(key, TimeSpan.FromMinutes(1));
+
+    return count > maxPerMinute;
+}
+```
+
+## Anti-Patterns
+- Never cache sensitive data (passwords, tokens, PII) without encryption
+- Never use Redis as primary store — it's a cache, not a database
+- Never omit TTL — unbounded keys fill memory
+- Never catch RedisException silently — degrade gracefully to DB

package/stacks/blazor-azure/.morph/standards/data/nosql/cosmos-db.md

@@ -0,0 +1,118 @@
+# Data Standard: Azure Cosmos DB
+
+## Overview
+NoSQL document database — use for high-throughput, globally distributed, or schema-flexible data.
+
+## When to Use Cosmos DB
+✅ Event store (append-only, high write throughput)
+✅ User activity/session data (variable schema)
+✅ Multi-region writes required
+✅ JSON documents with flexible schema
+❌ Relational data with complex joins (use Azure SQL)
+❌ Small datasets (cost inefficient)
+
+## Container Design
+```json
+{
+  "partitionKey": "/tenantId",
+  "indexingPolicy": {
+    "includedPaths": [{ "path": "/*" }],
+    "excludedPaths": [
+      { "path": "/largePayload/*" },
+      { "path": "/_etag/?" }
+    ]
+  }
+}
+```
+
+### Partition Key Strategy
+- High cardinality: userId, tenantId, orderId
+- Even distribution: avoid hot partitions (e.g., /status = "active" for 90% of docs)
+- Query alignment: partition key should appear in most queries
+
+## SDK Setup
+```csharp
+// Program.cs
+builder.Services.AddSingleton(sp =>
+    new CosmosClient(
+        config["CosmosDb:ConnectionString"],
+        new CosmosClientOptions
+        {
+            SerializerOptions = new CosmosSerializationOptions
+            {
+                PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
+            },
+            ApplicationName = "MyApp"
+        }));
+
+builder.Services.AddSingleton<ICosmosRepository<Order>>(sp =>
+    new CosmosRepository<Order>(
+        sp.GetRequiredService<CosmosClient>(),
+        config["CosmosDb:DatabaseId"],
+        "orders"));
+```
+
+## Repository Pattern
+```csharp
+public class CosmosRepository<T> where T : CosmosDocument
+{
+    private readonly Container _container;
+
+    public async Task<T?> GetAsync(string id, string partitionKey)
+    {
+        try
+        {
+            var response = await _container.ReadItemAsync<T>(id, new PartitionKey(partitionKey));
+            return response.Resource;
+        }
+        catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
+        {
+            return null;
+        }
+    }
+
+    public async Task<IReadOnlyList<T>> QueryAsync(string sql, Dictionary<string, object>? parameters = null)
+    {
+        var query = new QueryDefinition(sql);
+        if (parameters != null)
+            foreach (var (k, v) in parameters) query = query.WithParameter(k, v);
+
+        var results = new List<T>();
+        using var feed = _container.GetItemQueryIterator<T>(query);
+        while (feed.HasMoreResults)
+        {
+            var page = await feed.ReadNextAsync();
+            results.AddRange(page);
+        }
+        return results;
+    }
+
+    public async Task UpsertAsync(T document)
+        => await _container.UpsertItemAsync(document, new PartitionKey(document.PartitionKey));
+}
+```
+
+## Document Base Class
+```csharp
+public abstract class CosmosDocument
+{
+    [JsonPropertyName("id")]
+    public string Id { get; set; } = Guid.NewGuid().ToString();
+
+    [JsonPropertyName("_partitionKey")]
+    public abstract string PartitionKey { get; }
+
+    [JsonPropertyName("type")]
+    public string Type => GetType().Name;
+
+    [JsonPropertyName("createdAt")]
+    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
+}
+```
+
+## Cost Optimization
+- Enable TTL on transient data (session, temp tokens)
+- Use serverless mode for dev/test environments
+- Index only queried paths (exclude large blobs)
+- Batch operations with TransactionalBatch for same partition
+- Use bulk execution for large imports