@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/.morph/framework/standards/core/testing.md

@@ -1,295 +0,0 @@
-# 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/.morph/framework/standards/data/nosql/blob-storage.md

@@ -1,102 +0,0 @@
-# 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/.morph/framework/standards/data/nosql/cache/redis.md

@@ -1,97 +0,0 @@
-# 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/.morph/framework/standards/data/nosql/cosmos-db.md

@@ -1,118 +0,0 @@
-# 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