@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

package/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/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/framework/standards/data/vector-search/azure-ai-search.md

@@ -1,121 +0,0 @@
-# Data Standard: Azure AI Search (Vector Search)
-
-## Overview
-Azure AI Search provides vector and hybrid search for RAG (Retrieval-Augmented Generation) patterns.
-
-## Index Design
-```csharp
-// Define index with vector field
-var index = new SearchIndex("documents-index")
-{
-    Fields =
-    [
-        new SimpleField("id", SearchFieldDataType.String) { IsKey = true },
-        new SearchableField("content") { AnalyzerName = "pt.microsoft" },
-        new SearchableField("title") { AnalyzerName = "pt.microsoft" },
-        new SimpleField("sourceUrl", SearchFieldDataType.String) { IsFilterable = true },
-        new SimpleField("category", SearchFieldDataType.String) { IsFilterable = true, IsFacetable = true },
-        new VectorSearchField("contentVector", dimensions: 1536, vectorSearchProfileName: "hnsw-profile")
-    ],
-    VectorSearch = new VectorSearch
-    {
-        Profiles = { new VectorSearchProfile("hnsw-profile", "hnsw-config") },
-        Algorithms = { new HnswAlgorithmConfiguration("hnsw-config") }
-    }
-};
-await indexClient.CreateOrUpdateIndexAsync(index);
-```
-
-## Embedding Generation
-```csharp
-public class EmbeddingService : IEmbeddingService
-{
-    private readonly OpenAIClient _client;
-    private const string EmbeddingModel = "text-embedding-ada-002"; // 1536 dimensions
-
-    public async Task<float[]> GenerateEmbeddingAsync(string text)
-    {
-        // Truncate to model limit
-        var truncated = text.Length > 8192 ? text[..8192] : text;
-
-        var response = await _client.GetEmbeddingsAsync(
-            new EmbeddingsOptions(EmbeddingModel, [truncated]));
-
-        return response.Value.Data[0].Embedding.ToArray();
-    }
-
-    public async Task<IReadOnlyList<float[]>> GenerateBatchEmbeddingsAsync(IReadOnlyList<string> texts)
-    {
-        var response = await _client.GetEmbeddingsAsync(
-            new EmbeddingsOptions(EmbeddingModel, texts));
-        return response.Value.Data.Select(d => d.Embedding.ToArray()).ToList();
-    }
-}
-```
-
-## Document Indexing
-```csharp
-public class DocumentIndexer
-{
-    public async Task IndexDocumentAsync(Document doc)
-    {
-        var embedding = await _embeddingService.GenerateEmbeddingAsync(doc.Content);
-
-        var searchDoc = new SearchDocument
-        {
-            ["id"] = doc.Id.ToString(),
-            ["content"] = doc.Content,
-            ["title"] = doc.Title,
-            ["sourceUrl"] = doc.SourceUrl,
-            ["category"] = doc.Category,
-            ["contentVector"] = embedding
-        };
-
-        await _searchClient.MergeOrUploadDocumentsAsync([searchDoc]);
-    }
-}
-```
-
-## Hybrid Search (Vector + Keyword)
-```csharp
-public async Task<IReadOnlyList<SearchResult>> SearchAsync(string query, string? category = null)
-{
-    var queryEmbedding = await _embeddingService.GenerateEmbeddingAsync(query);
-
-    var options = new SearchOptions
-    {
-        Filter = category != null ? $"category eq '{category}'" : null,
-        Size = 10,
-        VectorSearch = new VectorSearchOptions
-        {
-            Queries =
-            {
-                new VectorizedQuery(queryEmbedding)
-                {
-                    Fields = { "contentVector" },
-                    KNearestNeighborsCount = 50
-                }
-            }
-        },
-        QueryType = SearchQueryType.Semantic,
-        SemanticSearch = new SemanticSearchOptions
-        {
-            SemanticConfigurationName = "my-semantic-config",
-            QueryCaption = new QueryCaption(QueryCaptionType.Extractive)
-        }
-    };
-
-    var response = await _searchClient.SearchAsync<SearchDocument>(query, options);
-    return await response.Value.GetResultsAsync().Select(r => new SearchResult(
-        r.Document["id"].ToString()!,
-        r.Document["content"].ToString()!,
-        r.Score ?? 0
-    )).ToListAsync();
-}
-```
-
-## Cost Optimization
-- Index only necessary fields (cost per GB/month)
-- Use semantic ranking sparingly (higher cost per query)
-- Cache frequent query embeddings (embeddings are stable for same text)
-- Batch indexing for large document sets (avoid per-document API calls)