@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/flutter/testing/references/widget-testing.md

@@ -0,0 +1,120 @@
+# Widget Testing Strategies
+
+Widget tests verify the UI and interaction of valid widgets in a simulated environment (headless).
+
+## Core Rules
+
+1. **Wrapper**: Always wrap widgets in `MaterialApp`/`CupertinoApp` to provide Theme/Navigator context.
+2. **Pump**:
+   - `pump()`: Triggers a frame.
+   - `pumpAndSettle()`: Wait for all animations to complete.
+3. **Finders**: Use semantic finders (`find.text`, `find.byKey`, `find.byType`) to locate elements.
+
+## Advanced: The Robot Pattern
+
+For complex screens, avoid scattering `find.by...` references throughout your tests. Use a **Robot** to encapsulate UI interactions.
+
+Reference: [Robot Pattern Implementation](./robot-pattern.md)
+
+### Updated Example: Testing a Login Screen
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutter_bloc/flutter_bloc.dart';
+import 'package:mocktail/mocktail.dart';
+import 'robots/login_robot.dart'; // Import your robot
+
+void main() {
+  late MockAuthBloc mockAuthBloc;
+
+  setUp(() {
+    mockAuthBloc = MockAuthBloc();
+    when(() => mockAuthBloc.state).thenReturn(AuthInitial());
+  });
+
+  Widget createWidget() {
+    return MaterialApp(
+      home: BlocProvider<AuthBloc>.value(
+        value: mockAuthBloc,
+        child: LoginScreen(),
+      ),
+    );
+  }
+
+  testWidgets('shows loading indicator when state is Loading', (tester) async {
+    // ARRANGE
+    when(() => mockAuthBloc.state).thenReturn(AuthLoading());
+    final robot = LoginRobot(tester);
+
+    // ACT
+    await tester.pumpWidget(createWidget());
+
+    // ASSERT
+    robot.expectLoadingVisible();
+  });
+
+  testWidgets('triggers login event on button tap', (tester) async {
+    // ARRANGE
+    final robot = LoginRobot(tester);
+    await tester.pumpWidget(createWidget());
+
+    // ACT
+    await robot.enterEmail('test@example.com');
+    await robot.enterPassword('password123');
+    await robot.tapLogin();
+
+    // ASSERT
+    verify(() => mockAuthBloc.add(LoginSubmitted(
+      email: 'test@example.com',
+      password: 'password123'
+    ))).called(1);
+  });
+}
+```
+
+## Handling Screen Variability
+
+One of the most common mistakes is testing only on the default 800x600 surface.
+
+### 1. Multi-Screen Golden Tests
+
+Use `golden_toolkit` to verify responsive layouts across multiple devices.
+
+```dart
+testGoldens('Login Screen responsive layout', (tester) async {
+  final builder = DeviceBuilder()
+    ..overrideDevicesForAllScenarios(devices: [
+      Device.phone,
+      Device.iphone11,
+      Device.tabletPortrait,
+      Device.tabletLandscape,
+    ])
+    ..addScenario(
+      widget: LoginScreen(),
+      name: 'Default State',
+    );
+
+  await tester.pumpDeviceBuilder(builder);
+  await screenMatchesGolden(tester, 'login_screen_responsive');
+});
+```
+
+### 2. Manual Screen Resizing
+
+If not using goldens, explicitly force screen sizes to test overflows.
+
+```dart
+testWidgets('Login on small screen', (tester) async {
+  // Set Surface Size to a small phone
+  tester.binding.window.physicalSizeTestValue = Size(320, 480);
+  tester.binding.window.devicePixelRatioTestValue = 1.0;
+  addTearDown(tester.binding.window.clearPhysicalSizeTestValue);
+
+  await tester.pumpWidget(createWidget());
+
+  // Verify no overflow errors
+  expect(tester.takeException(), isNull);
+  // Using a custom finder to check if something is visible only on scroll
+  await tester.scrollUntilVisible(find.text('Login'), 50);
+});
+```

package/rules/flutter/widgets/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: Flutter UI Widgets
+description: Principles for maintainable UI components.
+metadata:
+  labels: [ui, widgets]
+  triggers:
+    files: ['**_page.dart', '**_screen.dart', '**/widgets/**']
+    keywords: [StatelessWidget, const, Theme, ListView]
+---
+
+# UI & Widgets (P1)
+
+- **State**: Use `StatelessWidget` by default. `StatefulWidget` only for local state/controllers.
+- **Composition**: Extract UI into small, atomic `const` widgets.
+- **Theming**: Use `Theme.of(context)`. No hardcoded colors.
+- **Layout**: Use `Flex` + `Gap/SizedBox`.
+- **Specialized**:
+  - `SelectionArea`: For multi-widget text selection.
+  - `InteractiveViewer`: For zoom/pan.
+  - `ListWheelScrollView`: For pickers.
+  - `IntrinsicWidth/Height`: Avoid unless strictly required.
+- **Large Lists**: Always use `ListView.builder`.
+
+```dart
+class AppButton extends StatelessWidget {
+  final String label;
+  final VoidCallback onPressed;
+  const AppButton({super.key, required this.label, required this.onPressed});
+
+  @override
+  Widget build(BuildContext context) => ElevatedButton(onPressed: onPressed, child: Text(label));
+}
+```
+
+## Related Topics
+
+performance | testing

package/rules/golang/chi-router/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: Chi Router
+description: Lightweight, composable Go HTTP router built on net/http.
+metadata:
+  labels: [golang, chi, router, http]
+  triggers:
+    files: ['**/main.go', '**/routes.go']
+    keywords: [chi, chi.NewRouter, chi.Router, r.Route]
+---
+
+# Chi Router Standards
+
+## Router Setup
+
+```go
+package main
+
+import (
+    "net/http"
+    "github.com/go-chi/chi/v5"
+    "github.com/go-chi/chi/v5/middleware"
+)
+
+func main() {
+    r := chi.NewRouter()
+
+    // Middleware
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+    r.Use(middleware.RequestID)
+    r.Use(middleware.RealIP)
+
+    // Routes
+    r.Get("/", homeHandler)
+    r.Get("/users/{id}", getUser)
+    r.Post("/users", createUser)
+
+    // Sub-routers
+    r.Route("/api/v1", func(r chi.Router) {
+        r.Get("/items", listItems)
+        r.Post("/items", createItem)
+    })
+
+    http.ListenAndServe(":8080", r)
+}
+```
+
+## Handlers
+
+```go
+// Path parameters
+func getUser(w http.ResponseWriter, r *http.Request) {
+    id := chi.URLParam(r, "id")
+    user, err := findUser(id)
+    if err != nil {
+        http.Error(w, "Not found", http.StatusNotFound)
+        return
+    }
+    json.NewEncoder(w).Encode(user)
+}
+
+// Query parameters
+func listUsers(w http.ResponseWriter, r *http.Request) {
+    page := r.URL.Query().Get("page")
+    limit := r.URL.Query().Get("limit")
+    users := fetchUsers(page, limit)
+    json.NewEncoder(w).Encode(users)
+}
+
+// JSON body
+func createUser(w http.ResponseWriter, r *http.Request) {
+    var req CreateUserRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        http.Error(w, err.Error(), http.StatusBadRequest)
+        return
+    }
+    user := insertUser(req)
+    w.WriteHeader(http.StatusCreated)
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+## Middleware
+
+```go
+// Built-in middleware
+r.Use(middleware.Logger)          // Logs requests
+r.Use(middleware.Recoverer)       // Panic recovery
+r.Use(middleware.RequestID)       // Request ID header
+r.Use(middleware.RealIP)          // Real IP from headers
+r.Use(middleware.Compress(5))     // Gzip compression
+r.Use(middleware.Timeout(60 * time.Second))
+
+// Custom middleware
+func authMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        token := r.Header.Get("Authorization")
+        if token == "" {
+            http.Error(w, "Unauthorized", http.StatusUnauthorized)
+            return
+        }
+
+        user, err := validateToken(token)
+        if err != nil {
+            http.Error(w, "Invalid token", http.StatusUnauthorized)
+            return
+        }
+
+        ctx := context.WithValue(r.Context(), "user", user)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Apply to group
+r.Route("/api", func(r chi.Router) {
+    r.Use(authMiddleware)
+    r.Get("/protected", protectedHandler)
+})
+```
+
+## Route Groups & Nesting
+
+```go
+r.Route("/api/v1", func(r chi.Router) {
+    // All routes here prefixed with /api/v1
+
+    r.Route("/users", func(r chi.Router) {
+        r.Get("/", listUsers)
+        r.Post("/", createUser)
+
+        r.Route("/{id}", func(r chi.Router) {
+            r.Get("/", getUser)
+            r.Put("/", updateUser)
+            r.Delete("/", deleteUser)
+        })
+    })
+
+    r.Route("/items", func(r chi.Router) {
+        r.Get("/", listItems)
+    })
+})
+```
+
+## Mount Sub-Routers
+
+```go
+func main() {
+    r := chi.NewRouter()
+    r.Mount("/api/v1", apiRouter())
+    r.Mount("/admin", adminRouter())
+    http.ListenAndServe(":8080", r)
+}
+
+func apiRouter() chi.Router {
+    r := chi.NewRouter()
+    r.Get("/users", listUsers)
+    r.Post("/users", createUser)
+    return r
+}
+
+func adminRouter() chi.Router {
+    r := chi.NewRouter()
+    r.Use(adminAuthMiddleware)
+    r.Get("/stats", getStats)
+    return r
+}
+```
+
+## Context Values
+
+```go
+// Set in middleware
+ctx := context.WithValue(r.Context(), "user", user)
+next.ServeHTTP(w, r.WithContext(ctx))
+
+// Get in handler
+user := r.Context().Value("user").(*User)
+
+// Type-safe context keys
+type contextKey string
+const userKey contextKey = "user"
+
+ctx := context.WithValue(r.Context(), userKey, user)
+user := r.Context().Value(userKey).(*User)
+```
+
+## Response Helpers
+
+```go
+import "github.com/go-chi/render"
+
+type UserResponse struct {
+    ID    int    `json:"id"`
+    Name  string `json:"name"`
+}
+
+func (u *UserResponse) Render(w http.ResponseWriter, r *http.Request) error {
+    return nil
+}
+
+func getUser(w http.ResponseWriter, r *http.Request) {
+    user := &UserResponse{ID: 1, Name: "John"}
+    render.Render(w, r, user)
+}
+
+// Error response
+func ErrNotFound(w http.ResponseWriter, r *http.Request, err error) {
+    render.Status(r, http.StatusNotFound)
+    render.JSON(w, r, map[string]string{"error": err.Error()})
+}
+```
+
+## Best Practices
+
+1. **Standard library**: Chi uses net/http, fully compatible with standard handlers
+2. **Composition**: Use `r.Route()` for grouping, `r.Mount()` for sub-routers
+3. **Middleware order**: Apply in order of execution (outer to inner)
+4. **Context**: Use typed keys for context values
+5. **Testing**: Use `httptest` - Chi handlers are standard `http.Handler`

package/rules/golang/chi-router/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Chi Router References
+
+## References
+
+- [**Routing Patterns**](routing-patterns.md) - Routes, middleware, subrouters
+
+## Quick Checks
+
+- [ ] Lightweight, idiomatic Go router
+- [ ] Middleware chain pattern
+- [ ] URL parameters via chi.URLParam
+- [ ] Subrouters for modular code
+- [ ] Compatible with net/http

package/rules/golang/chi-router/references/routing-patterns.md

@@ -0,0 +1,205 @@
+# Chi Routing Patterns
+
+## Basic Setup
+
+```go
+import (
+    "net/http"
+    "github.com/go-chi/chi/v5"
+    "github.com/go-chi/chi/v5/middleware"
+)
+
+func main() {
+    r := chi.NewRouter()
+
+    // Built-in middleware
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+    r.Use(middleware.RequestID)
+
+    // Routes
+    r.Get("/", func(w http.ResponseWriter, r *http.Request) {
+        w.Write([]byte("Hello World!"))
+    })
+
+    r.Get("/users/{id}", getUser)
+    r.Post("/users", createUser)
+
+    http.ListenAndServe(":3000", r)
+}
+```
+
+## Handlers
+
+```go
+import (
+    "encoding/json"
+    "net/http"
+    "github.com/go-chi/chi/v5"
+)
+
+func getUser(w http.ResponseWriter, r *http.Request) {
+    id := chi.URLParam(r, "id")
+    
+    user := User{ID: id, Name: "John"}
+    
+    w.Header().Set("Content-Type", "application/json")
+    json.NewEncoder(w).Encode(user)
+}
+
+func createUser(w http.ResponseWriter, r *http.Request) {
+    var user User
+    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
+        http.Error(w, err.Error(), http.StatusBadRequest)
+        return
+    }
+    
+    w.WriteHeader(http.StatusCreated)
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+## Route Groups
+
+```go
+func main() {
+    r := chi.NewRouter()
+
+    // API routes
+    r.Route("/api", func(r chi.Router) {
+        r.Use(apiMiddleware)
+        
+        r.Route("/v1", func(r chi.Router) {
+            r.Get("/users", listUsersV1)
+            r.Post("/users", createUserV1)
+            
+            r.Route("/users/{id}", func(r chi.Router) {
+                r.Get("/", getUser)
+                r.Put("/", updateUser)
+                r.Delete("/", deleteUser)
+            })
+        })
+    })
+
+    // Admin routes with auth
+    r.Group(func(r chi.Router) {
+        r.Use(authMiddleware)
+        r.Get("/admin/stats", getStats)
+    })
+}
+```
+
+## Subrouters
+
+```go
+// users.go
+func UsersRouter() chi.Router {
+    r := chi.NewRouter()
+    
+    r.Get("/", listUsers)
+    r.Post("/", createUser)
+    r.Get("/{id}", getUser)
+    r.Put("/{id}", updateUser)
+    r.Delete("/{id}", deleteUser)
+    
+    return r
+}
+
+// orders.go
+func OrdersRouter() chi.Router {
+    r := chi.NewRouter()
+    r.Get("/", listOrders)
+    r.Post("/", createOrder)
+    return r
+}
+
+// main.go
+func main() {
+    r := chi.NewRouter()
+    
+    r.Mount("/users", UsersRouter())
+    r.Mount("/orders", OrdersRouter())
+    
+    http.ListenAndServe(":3000", r)
+}
+```
+
+## Middleware
+
+```go
+// Custom middleware
+func AuthMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        token := r.Header.Get("Authorization")
+        if token == "" {
+            http.Error(w, "Unauthorized", http.StatusUnauthorized)
+            return
+        }
+        
+        // Validate token, add user to context
+        ctx := context.WithValue(r.Context(), "user", userID)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Request-scoped middleware
+func UserCtx(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        id := chi.URLParam(r, "id")
+        user, err := findUser(id)
+        if err != nil {
+            http.Error(w, "Not Found", http.StatusNotFound)
+            return
+        }
+        ctx := context.WithValue(r.Context(), "user", user)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Usage
+r.Route("/users/{id}", func(r chi.Router) {
+    r.Use(UserCtx)
+    r.Get("/", getUser)    // User available in context
+    r.Put("/", updateUser)
+})
+```
+
+## Built-in Middleware
+
+```go
+import "github.com/go-chi/chi/v5/middleware"
+
+r.Use(middleware.RequestID)       // X-Request-ID header
+r.Use(middleware.RealIP)          // X-Real-IP, X-Forwarded-For
+r.Use(middleware.Logger)          // Request logging
+r.Use(middleware.Recoverer)       // Panic recovery
+r.Use(middleware.Timeout(60 * time.Second))
+r.Use(middleware.Throttle(100))   // Rate limiting
+r.Use(middleware.Compress(5))     // Gzip compression
+r.Use(middleware.AllowContentType("application/json"))
+```
+
+## Pattern Matching
+
+```go
+// Basic pattern
+r.Get("/users/{id}", handler)
+
+// Regex constraint
+r.Get("/articles/{date:\\d{4}-\\d{2}-\\d{2}}", handler)
+
+// Catch-all
+r.Get("/files/*", handler) // r.URL.Path contains full path
+
+// Not found handler
+r.NotFound(func(w http.ResponseWriter, r *http.Request) {
+    w.WriteHeader(http.StatusNotFound)
+    w.Write([]byte("Not found"))
+})
+
+// Method not allowed
+r.MethodNotAllowed(func(w http.ResponseWriter, r *http.Request) {
+    w.WriteHeader(http.StatusMethodNotAllowed)
+    w.Write([]byte("Method not allowed"))
+})
+```