@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/dotnet/blazor/references/REFERENCE.md

@@ -0,0 +1,392 @@
+# Blazor Reference
+
+Component lifecycle, state management, and advanced patterns.
+
+## References
+
+- [**Lifecycle**](lifecycle.md) - Component lifecycle methods.
+- [**State Management**](state-management.md) - Fluxor, cascading values.
+- [**JS Interop**](js-interop.md) - JavaScript interoperability.
+
+## Component Lifecycle
+
+```csharp
+@code {
+    // 1. Called when component is first initialized (before rendering)
+    protected override void OnInitialized()
+    {
+        // Sync initialization
+    }
+
+    // 1b. Async version (preferred for data loading)
+    protected override async Task OnInitializedAsync()
+    {
+        // Load initial data
+        _data = await DataService.GetAsync();
+    }
+
+    // 2. Called when parameters are set/changed
+    protected override void OnParametersSet()
+    {
+        // React to parameter changes
+    }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Async parameter processing
+    }
+
+    // 3. Called after component has rendered
+    protected override void OnAfterRender(bool firstRender)
+    {
+        if (firstRender)
+        {
+            // First render only - initialize JS libraries
+        }
+        // Every render - update DOM-dependent state
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JSRuntime.InvokeVoidAsync("initializeChart", _chartElement);
+        }
+    }
+
+    // 4. Optimize re-rendering
+    protected override bool ShouldRender()
+    {
+        // Return false to prevent re-rendering
+        return _hasChanged;
+    }
+
+    // 5. Cleanup when component is disposed
+    public void Dispose()
+    {
+        // Unsubscribe from events, dispose resources
+        _subscription?.Dispose();
+    }
+
+    // Async dispose (IAsyncDisposable)
+    public async ValueTask DisposeAsync()
+    {
+        await JSRuntime.InvokeVoidAsync("cleanup");
+    }
+}
+```
+
+## State Management Patterns
+
+```csharp
+// 1. Cascading Values - App-wide state
+// App.razor or Routes.razor
+<CascadingValue Value="@_themeState">
+    <CascadingValue Value="@_userState">
+        <Router AppAssembly="@typeof(App).Assembly">
+            ...
+        </Router>
+    </CascadingValue>
+</CascadingValue>
+
+@code {
+    private ThemeState _themeState = new();
+    private UserState _userState = new();
+}
+
+// Consuming component
+@code {
+    [CascadingParameter]
+    public ThemeState Theme { get; set; } = default!;
+
+    [CascadingParameter]
+    public UserState User { get; set; } = default!;
+}
+```
+
+```csharp
+// 2. State Container Service
+public class CartState
+{
+    private readonly List<CartItem> _items = [];
+
+    public IReadOnlyList<CartItem> Items => _items.AsReadOnly();
+    public decimal Total => _items.Sum(i => i.Price * i.Quantity);
+
+    public event Action? OnChange;
+
+    public void AddItem(CartItem item)
+    {
+        _items.Add(item);
+        NotifyStateChanged();
+    }
+
+    public void RemoveItem(int productId)
+    {
+        _items.RemoveAll(i => i.ProductId == productId);
+        NotifyStateChanged();
+    }
+
+    private void NotifyStateChanged() => OnChange?.Invoke();
+}
+
+// Registration
+builder.Services.AddScoped<CartState>();
+
+// Component usage
+@inject CartState Cart
+@implements IDisposable
+
+<div>Total: @Cart.Total.ToString("C")</div>
+
+@code {
+    protected override void OnInitialized()
+    {
+        Cart.OnChange += StateHasChanged;
+    }
+
+    public void Dispose()
+    {
+        Cart.OnChange -= StateHasChanged;
+    }
+}
+```
+
+```csharp
+// 3. Fluxor (Redux pattern)
+// State
+public record CounterState(int Count);
+
+public class CounterFeature : Feature<CounterState>
+{
+    public override string GetName() => "Counter";
+    protected override CounterState GetInitialState() => new(0);
+}
+
+// Actions
+public record IncrementAction();
+public record DecrementAction();
+public record SetCountAction(int Count);
+
+// Reducers
+public static class CounterReducers
+{
+    [ReducerMethod]
+    public static CounterState OnIncrement(CounterState state, IncrementAction _)
+        => state with { Count = state.Count + 1 };
+
+    [ReducerMethod]
+    public static CounterState OnDecrement(CounterState state, DecrementAction _)
+        => state with { Count = state.Count - 1 };
+
+    [ReducerMethod]
+    public static CounterState OnSetCount(CounterState state, SetCountAction action)
+        => state with { Count = action.Count };
+}
+
+// Component
+@inject IState<CounterState> CounterState
+@inject IDispatcher Dispatcher
+
+<p>Count: @CounterState.Value.Count</p>
+<button @onclick="Increment">+</button>
+<button @onclick="Decrement">-</button>
+
+@code {
+    private void Increment() => Dispatcher.Dispatch(new IncrementAction());
+    private void Decrement() => Dispatcher.Dispatch(new DecrementAction());
+}
+```
+
+## JS Interop
+
+```csharp
+// Calling JavaScript from C#
+@inject IJSRuntime JS
+
+@code {
+    private ElementReference _inputElement;
+
+    // Call JS function
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("initializeComponent", _inputElement);
+        }
+    }
+
+    // Call JS function with return value
+    private async Task<string> GetLocalStorage(string key)
+    {
+        return await JS.InvokeAsync<string>("localStorage.getItem", key);
+    }
+
+    // Focus element
+    private async Task FocusInput()
+    {
+        await _inputElement.FocusAsync();
+    }
+}
+```
+
+```javascript
+// wwwroot/js/interop.js
+window.initializeComponent = (element) => {
+    // Initialize third-party library
+    new SomeLibrary(element);
+};
+
+window.blazorInterop = {
+    showAlert: (message) => alert(message),
+    getWindowSize: () => ({ width: window.innerWidth, height: window.innerHeight })
+};
+```
+
+```csharp
+// Calling C# from JavaScript
+// In component
+@inject IJSRuntime JS
+
+@code {
+    private DotNetObjectReference<MyComponent>? _objRef;
+
+    protected override void OnInitialized()
+    {
+        _objRef = DotNetObjectReference.Create(this);
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("registerCallback", _objRef);
+        }
+    }
+
+    [JSInvokable]
+    public void HandleCallback(string data)
+    {
+        // Called from JavaScript
+        Console.WriteLine($"Received: {data}");
+        StateHasChanged();
+    }
+
+    public void Dispose()
+    {
+        _objRef?.Dispose();
+    }
+}
+```
+
+```javascript
+// JavaScript calling C#
+window.registerCallback = (dotNetRef) => {
+    window.myCallback = (data) => {
+        dotNetRef.invokeMethodAsync('HandleCallback', data);
+    };
+};
+
+// Later...
+myCallback('Some data from JS');
+```
+
+## Render Modes (.NET 8+)
+
+```razor
+@* Static Server Rendering (SSR) - Default *@
+@rendermode InteractiveServer
+@rendermode InteractiveWebAssembly
+@rendermode InteractiveAuto
+
+@* Per-component render mode *@
+<Counter @rendermode="InteractiveServer" />
+<Counter @rendermode="InteractiveWebAssembly" />
+
+@* Streaming rendering for slow data *@
+@attribute [StreamRendering]
+
+<h1>Dashboard</h1>
+
+@if (_data is null)
+{
+    <p>Loading dashboard data...</p>
+}
+else
+{
+    <DashboardContent Data="_data" />
+}
+
+@code {
+    private DashboardData? _data;
+
+    protected override async Task OnInitializedAsync()
+    {
+        // This data streams to the client as it loads
+        _data = await SlowDataService.GetDashboardAsync();
+    }
+}
+```
+
+## Error Handling
+
+```razor
+@* ErrorBoundary for graceful error handling *@
+<ErrorBoundary @ref="_errorBoundary">
+    <ChildContent>
+        <RiskyComponent />
+    </ChildContent>
+    <ErrorContent Context="exception">
+        <div class="alert alert-danger">
+            <h4>Something went wrong</h4>
+            <p>@exception.Message</p>
+            <button @onclick="Recover">Try Again</button>
+        </div>
+    </ErrorContent>
+</ErrorBoundary>
+
+@code {
+    private ErrorBoundary? _errorBoundary;
+
+    private void Recover()
+    {
+        _errorBoundary?.Recover();
+    }
+}
+```
+
+## Authentication in Blazor
+
+```razor
+@* Show content based on auth state *@
+<AuthorizeView>
+    <Authorized>
+        <p>Hello, @context.User.Identity?.Name!</p>
+        <a href="account/logout">Logout</a>
+    </Authorized>
+    <NotAuthorized>
+        <a href="account/login">Login</a>
+    </NotAuthorized>
+</AuthorizeView>
+
+@* Role-based content *@
+<AuthorizeView Roles="Admin,Manager">
+    <Authorized>
+        <AdminPanel />
+    </Authorized>
+    <NotAuthorized>
+        <p>Access denied</p>
+    </NotAuthorized>
+</AuthorizeView>
+
+@* Policy-based content *@
+<AuthorizeView Policy="CanEditOrders">
+    <button @onclick="EditOrder">Edit</button>
+</AuthorizeView>
+
+@* Protect entire page *@
+@page "/admin"
+@attribute [Authorize(Roles = "Admin")]
+
+<h1>Admin Dashboard</h1>
+```

package/rules/dotnet/language/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: C# Language Patterns
+description: Modern C# standards for type safety, performance, and maintainability.
+metadata:
+  labels: [csharp, dotnet, language, types, async]
+  triggers:
+    files: ['**/*.cs', '**/*.csproj']
+    keywords: [class, record, interface, async, await, linq, nullable, span]
+---
+
+# C# Language Patterns
+
+## **Priority: P0 (CRITICAL)**
+
+Modern C# standards for type-safe, performant, maintainable code.
+
+## Implementation Guidelines
+
+- **Nullable Reference Types**: Enable `<Nullable>enable</Nullable>`. Use `?` for nullable, avoid `!` except when compiler can't infer.
+- **Records**: `record` for immutable DTOs, `record struct` for stack-allocated value types.
+- **Pattern Matching**: `is` patterns, `switch` expressions, property/positional patterns.
+- **Async/Await**: Always use `CancellationToken`. `ValueTask` for hot paths. `ConfigureAwait(false)` in libraries.
+- **LINQ**: Prefer method syntax. Avoid multiple enumerations (`ToList()` once). Use `AsNoTracking()` for read-only EF queries.
+- **Generics**: Constraints (`where T : class, new()`), covariance (`out T`), contravariance (`in T`).
+- **Spans**: `Span<T>`, `ReadOnlySpan<T>` for zero-allocation slicing.
+- **Primary Constructors**: C# 12+ `class Foo(int x)` for concise DI.
+- **Collection Expressions**: C# 12+ `[1, 2, 3]` syntax.
+- **Raw String Literals**: `"""multi-line"""` for SQL, JSON templates.
+
+## Anti-Patterns
+
+- **No `async void`**: Use `async Task`. Exception: event handlers.
+- **No `Task.Result`/`.Wait()`**: Deadlock risk. Always `await`.
+- **No `DateTime.Now`**: Use `DateTimeOffset.UtcNow` for timezone safety.
+- **No string concat in loops**: Use `StringBuilder` or `string.Join`.
+- **No `!` abuse**: Prefer null checks or `??` over null-forgiving.
+
+## Code
+
+```csharp
+// Record with primary constructor
+public record UserDto(string Name, string Email);
+
+// Pattern matching with switch expression
+string GetStatus(Order order) => order switch
+{
+    { Status: OrderStatus.Pending } => "Waiting",
+    { Status: OrderStatus.Shipped, TrackingNumber: not null } => "In Transit",
+    { IsCancelled: true } => "Cancelled",
+    _ => "Unknown"
+};
+
+// Async with cancellation token
+async Task<User?> GetUserAsync(int id, CancellationToken ct = default)
+{
+    return await _db.Users
+        .AsNoTracking()
+        .FirstOrDefaultAsync(u => u.Id == id, ct);
+}
+
+// Span for zero-allocation parsing
+ReadOnlySpan<char> GetFirstWord(ReadOnlySpan<char> text)
+{
+    int idx = text.IndexOf(' ');
+    return idx < 0 ? text : text[..idx];
+}
+
+// Primary constructor (C# 12)
+public class UserService(IUserRepository repo, ILogger<UserService> logger)
+{
+    public async Task<User?> GetAsync(int id) => await repo.GetByIdAsync(id);
+}
+```
+
+## Reference & Examples
+
+For advanced patterns, spans, and nullable annotations:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+best-practices | security | tooling

package/rules/dotnet/language/references/REFERENCE.md

@@ -0,0 +1,222 @@
+# C# Language Patterns Reference
+
+Advanced type patterns, spans, and modern C# features.
+
+## References
+
+- [**Pattern Matching**](pattern-matching.md) - Switch expressions, property patterns.
+- [**Nullable Annotations**](nullable-annotations.md) - `[NotNull]`, `[MaybeNull]`, flow analysis.
+- [**Spans & Memory**](spans-memory.md) - Zero-allocation patterns.
+
+## Advanced Pattern Matching
+
+```csharp
+// List patterns (C# 11+)
+int[] numbers = [1, 2, 3, 4, 5];
+var result = numbers switch
+{
+    [1, 2, ..] => "Starts with 1, 2",
+    [_, _, 3, ..] => "Third element is 3",
+    { Length: > 10 } => "Long array",
+    [] => "Empty",
+    _ => "Other"
+};
+
+// Property patterns with nested matching
+string Describe(Person person) => person switch
+{
+    { Name: "Admin", Role: { Permissions: { IsAdmin: true } } } => "Full access",
+    { Age: >= 18, IsVerified: true } => "Verified adult",
+    { Age: < 18 } => "Minor",
+    _ => "Standard user"
+};
+
+// Relational patterns
+string GetTaxBracket(decimal income) => income switch
+{
+    <= 10_000m => "0%",
+    <= 50_000m => "10%",
+    <= 100_000m => "20%",
+    _ => "30%"
+};
+```
+
+## Nullable Reference Types
+
+```csharp
+// Nullable annotations
+public class UserService
+{
+    // Parameter never null after validation
+    public User GetUser([NotNull] string? id)
+    {
+        ArgumentNullException.ThrowIfNull(id);
+        return _repo.Find(id);
+    }
+
+    // Return may be null
+    [return: MaybeNull]
+    public T Find<T>(int id) where T : class
+    {
+        return _context.Set<T>().Find(id);
+    }
+
+    // Output parameter set if returns true
+    public bool TryGet(int id, [NotNullWhen(true)] out User? user)
+    {
+        user = _repo.Find(id);
+        return user is not null;
+    }
+}
+
+// Null-coalescing patterns
+string name = user?.Name ?? "Anonymous";
+int length = text?.Length ?? 0;
+
+// Null-conditional with assignment
+user?.Settings?.Theme = "dark"; // No-op if null
+```
+
+## Span and Memory Patterns
+
+```csharp
+// Zero-allocation string processing
+public static int CountWords(ReadOnlySpan<char> text)
+{
+    if (text.IsEmpty) return 0;
+
+    int count = 0;
+    bool inWord = false;
+
+    foreach (char c in text)
+    {
+        if (char.IsWhiteSpace(c))
+        {
+            inWord = false;
+        }
+        else if (!inWord)
+        {
+            inWord = true;
+            count++;
+        }
+    }
+    return count;
+}
+
+// Stackalloc for small buffers
+public static string FormatId(int id)
+{
+    Span<char> buffer = stackalloc char[16];
+    id.TryFormat(buffer, out int written);
+    return new string(buffer[..written]);
+}
+
+// Memory<T> for async scenarios
+public async Task ProcessAsync(Memory<byte> buffer)
+{
+    await _stream.ReadAsync(buffer);
+    // Process buffer...
+}
+```
+
+## Generics with Constraints
+
+```csharp
+// Multiple constraints
+public class Repository<T> where T : class, IEntity, new()
+{
+    public T Create() => new T();
+}
+
+// Covariance (out) - can return derived types
+public interface IReadOnlyRepository<out T>
+{
+    T? GetById(int id);
+    IEnumerable<T> GetAll();
+}
+
+// Contravariance (in) - can accept base types
+public interface IComparer<in T>
+{
+    int Compare(T x, T y);
+}
+
+// Static abstract members (C# 11+)
+public interface IParsable<TSelf> where TSelf : IParsable<TSelf>
+{
+    static abstract TSelf Parse(string s);
+    static abstract bool TryParse(string? s, out TSelf result);
+}
+```
+
+## C# 12+ Features
+
+```csharp
+// Collection expressions
+int[] numbers = [1, 2, 3, 4, 5];
+List<string> names = ["Alice", "Bob"];
+Span<int> span = [1, 2, 3];
+
+// Spread operator
+int[] combined = [..numbers, 6, 7, ..otherNumbers];
+
+// Primary constructors for classes
+public class OrderService(IOrderRepository repo, ILogger<OrderService> logger)
+{
+    public async Task<Order?> GetAsync(int id)
+    {
+        logger.LogDebug("Fetching order {OrderId}", id);
+        return await repo.GetByIdAsync(id);
+    }
+}
+
+// Alias any type
+using Point = (int X, int Y);
+using UserId = System.Int32;
+
+// Default lambda parameters
+var greet = (string name = "World") => $"Hello, {name}!";
+
+// Inline arrays (for high-performance scenarios)
+[InlineArray(16)]
+public struct Buffer16<T>
+{
+    private T _element0;
+}
+```
+
+## Async Patterns
+
+```csharp
+// ValueTask for hot paths
+public ValueTask<int> GetCachedCountAsync()
+{
+    if (_cache.TryGetValue("count", out int count))
+        return ValueTask.FromResult(count);
+
+    return new ValueTask<int>(LoadCountAsync());
+}
+
+// IAsyncEnumerable for streaming
+public async IAsyncEnumerable<User> GetUsersAsync(
+    [EnumeratorCancellation] CancellationToken ct = default)
+{
+    await foreach (var user in _db.Users.AsAsyncEnumerable().WithCancellation(ct))
+    {
+        yield return user;
+    }
+}
+
+// Parallel async with SemaphoreSlim
+public async Task ProcessAllAsync(IEnumerable<int> ids, int maxConcurrency = 10)
+{
+    using var semaphore = new SemaphoreSlim(maxConcurrency);
+    var tasks = ids.Select(async id =>
+    {
+        await semaphore.WaitAsync();
+        try { await ProcessAsync(id); }
+        finally { semaphore.Release(); }
+    });
+    await Task.WhenAll(tasks);
+}
+```