opencode-skills-collection 3.0.49 → 3.0.51

package/bundled-skills/super-code/csharp/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: csharp
+description: "Language-specific super-code guidelines for csharp."
+risk: safe
+source: community
+date_added: "2026-06-16"
+---
+# C#: Idiomatic Efficiency Reference
+
+## Table of Contents
+1. [LINQ & Collections](#linq)
+2. [Null Handling](#nulls)
+3. [Async/Await](#async)
+4. [Records & Pattern Matching](#records)
+5. [Error Handling](#errors)
+6. [Resource Management](#resources)
+7. [Anti-patterns specific to C#](#antipatterns)
+
+---
+
+## 1. LINQ & Collections {#linq}
+
+```csharp
+// ❌ Imperative accumulation
+var result = new List<string>();
+foreach (var item in items) {
+    if (item.IsActive) result.Add(item.Name.ToUpper());
+}
+
+// ✅
+var result = items
+    .Where(i => i.IsActive)
+    .Select(i => i.Name.ToUpper())
+    .ToList();
+```
+
+```csharp
+// ❌ Manual grouping
+var grouped = new Dictionary<string, List<Item>>();
+foreach (var item in items) {
+    if (!grouped.ContainsKey(item.Category))
+        grouped[item.Category] = new List<Item>();
+    grouped[item.Category].Add(item);
+}
+
+// ✅
+var grouped = items.GroupBy(i => i.Category)
+    .ToDictionary(g => g.Key, g => g.ToList());
+```
+
+```csharp
+// ❌ Checking Any() then First()
+if (items.Any(i => i.IsValid)) {
+    var first = items.First(i => i.IsValid);
+}
+
+// ✅
+var first = items.FirstOrDefault(i => i.IsValid);
+if (first is not null) { ... }
+```
+
+**Prefer method syntax for chains of 2+ operations. Query syntax is fine for complex joins.**
+
+---
+
+## 2. Null Handling {#nulls}
+
+```csharp
+// ❌ Nested null checks
+string city = null;
+if (user != null && user.Address != null) {
+    city = user.Address.City;
+}
+
+// ✅
+var city = user?.Address?.City;
+```
+
+```csharp
+// ❌ Ternary for null fallback
+var name = user != null ? user.Name : "Unknown";
+
+// ✅
+var name = user?.Name ?? "Unknown";
+```
+
+```csharp
+// ❌ Null check before event invocation
+if (OnChanged != null) OnChanged(this, args);
+
+// ✅
+OnChanged?.Invoke(this, args);
+```
+
+```csharp
+// ❌ Throwing ArgumentNullException manually
+if (name == null) throw new ArgumentNullException(nameof(name));
+
+// ✅ (C# 10+)
+ArgumentNullException.ThrowIfNull(name);
+```
+
+**Enable nullable reference types (`<Nullable>enable</Nullable>`) project-wide.**
+
+---
+
+## 3. Async/Await {#async}
+
+```csharp
+// ❌ Blocking on async code
+var result = GetDataAsync().Result; // deadlock risk
+
+// ✅
+var result = await GetDataAsync();
+```
+
+```csharp
+// ❌ async void (exceptions are unobservable)
+async void OnButtonClick() { await DoWork(); }
+
+// ✅ — async Task; only async void for event handlers that truly require it
+async Task OnButtonClick() { await DoWork(); }
+```
+
+```csharp
+// ❌ Sequential awaits for independent work
+var a = await FetchA();
+var b = await FetchB();
+
+// ✅
+var (a, b) = (await Task.WhenAll(FetchA(), FetchB())) switch
+{
+    var r => (r[0], r[1])
+};
+// or cleaner with ValueTuple:
+var taskA = FetchA();
+var taskB = FetchB();
+var a = await taskA;
+var b = await taskB;
+```
+
+```csharp
+// ❌ Wrapping synchronous code in Task.Run inside a library
+public Task<int> GetValue() => Task.Run(() => ComputeSync());
+
+// ✅ — let the caller decide; expose sync method
+public int GetValue() => ComputeSync();
+```
+
+**Add `ConfigureAwait(false)` in library code. Omit in app/UI code.**
+
+---
+
+## 4. Records & Pattern Matching {#records}
+
+```csharp
+// ❌ Manual equality, ToString, Deconstruct for data types
+class Point {
+    public int X { get; init; }
+    public int Y { get; init; }
+    // + Equals, GetHashCode, ToString...
+}
+
+// ✅ (C# 9+)
+record Point(int X, int Y);
+```
+
+```csharp
+// ❌ if-else chain for type checking
+if (shape is Circle) {
+    var c = (Circle)shape;
+    return c.Radius * c.Radius * Math.PI;
+} else if (shape is Rectangle) { ... }
+
+// ✅
+return shape switch {
+    Circle { Radius: var r } => r * r * Math.PI,
+    Rectangle { Width: var w, Height: var h } => w * h,
+    _ => throw new ArgumentException($"Unknown shape: {shape}")
+};
+```
+
+```csharp
+// ❌ Range checking with && 
+if (score >= 0 && score <= 100) { ... }
+
+// ✅ (C# 9+)
+if (score is >= 0 and <= 100) { ... }
+```
+
+---
+
+## 5. Error Handling {#errors}
+
+```csharp
+// ❌ Catching Exception to log and swallow
+try { Process(); }
+catch (Exception ex) { logger.LogError(ex, "error"); }
+
+// ✅ — catch specific, rethrow if you can't handle
+try { Process(); }
+catch (HttpRequestException ex) {
+    throw new ServiceException("upstream failure", ex);
+}
+```
+
+```csharp
+// ❌ throw ex (resets stack trace)
+catch (Exception ex) { throw ex; }
+
+// ✅
+catch (Exception ex) { throw; } // preserves stack trace
+// or wrap: throw new AppException("context", ex);
+```
+
+```csharp
+// ❌ Exceptions for flow control
+try { return dict[key]; }
+catch (KeyNotFoundException) { return defaultValue; }
+
+// ✅
+return dict.TryGetValue(key, out var value) ? value : defaultValue;
+```
+
+---
+
+## 6. Resource Management {#resources}
+
+```csharp
+// ❌ Manual Dispose
+var conn = new SqlConnection(cs);
+conn.Open();
+// ... use conn ...
+conn.Dispose(); // missed on exception
+
+// ✅
+using var conn = new SqlConnection(cs);
+conn.Open();
+// disposed at end of scope
+```
+
+```csharp
+// ❌ Verbose using block
+using (var reader = new StreamReader(path)) {
+    return reader.ReadToEnd();
+}
+
+// ✅ (C# 8+)
+using var reader = new StreamReader(path);
+return reader.ReadToEnd();
+// or just: return File.ReadAllText(path);
+```
+
+---
+
+## 7. Anti-patterns specific to C# {#antipatterns}
+
+| Anti-pattern | Preferred |
+|---|---|
+| `string.Format("{0}", x)` | `$"{x}"` string interpolation |
+| `List<T>` as public API return | `IReadOnlyList<T>` or `IEnumerable<T>` |
+| `async void` | `async Task` |
+| `.Result` / `.Wait()` on Task | `await` |
+| `throw ex` | `throw` (preserves stack trace) |
+| Manual `IEquatable` on data types | `record` |
+| `object` parameters | generics with constraints |
+| `DateTime.Now` | `DateTime.UtcNow` or `DateTimeOffset` |
+| Mutable public fields | properties with `{ get; set; }` or `{ get; init; }` |
+| `catch (Exception) { }` (swallow all) | catch specific exceptions, rethrow unknown |
+| `IDisposable` without `using` | `using` declaration |
+
+
+
+## Limitations
+- These are language-specific guidelines and do not cover overall architectural decisions.
+- Over-compression might reduce readability; apply judgement.

package/bundled-skills/super-code/dart/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: dart
+description: "Language-specific super-code guidelines for dart."
+risk: safe
+source: community
+date_added: "2026-06-16"
+---
+# Dart: Idiomatic Efficiency Reference
+
+## Table of Contents
+1. [Null Safety](#nulls)
+2. [Collections & Iteration](#collections)
+3. [Classes & Records](#classes)
+4. [Async/Await & Streams](#async)
+5. [Error Handling](#errors)
+6. [Flutter-Specific Patterns](#flutter)
+7. [Anti-patterns specific to Dart](#antipatterns)
+
+---
+
+## 1. Null Safety {#nulls}
+
+```dart
+// ❌ Manual null check
+String display;
+if (user.name != null) {
+  display = user.name!;
+} else {
+  display = 'Unknown';
+}
+
+// ✅
+final display = user.name ?? 'Unknown';
+```
+
+```dart
+// ❌ Nested null checks
+if (user != null && user.address != null && user.address!.city != null) {
+  print(user.address!.city!);
+}
+
+// ✅
+final city = user?.address?.city;
+if (city != null) print(city);
+```
+
+```dart
+// ❌ Late field when nullable is correct
+late String name; // crashes if accessed before assignment
+
+// ✅ — use late only when you guarantee initialization before access
+String? name; // honestly nullable
+// late is fine for: late final _controller = TextEditingController();
+```
+
+```dart
+// ❌ Bang operator (!) everywhere
+final name = user.name!;
+final city = user.address!.city!;
+
+// ✅ — promote through null checks
+final name = user.name;
+if (name == null) return;
+// name is now non-null (promoted)
+```
+
+---
+
+## 2. Collections & Iteration {#collections}
+
+```dart
+// ❌ Imperative accumulation
+final result = <String>[];
+for (final item in items) {
+  if (item.isActive) result.add(item.name.toUpperCase());
+}
+
+// ✅
+final result = items
+    .where((i) => i.isActive)
+    .map((i) => i.name.toUpperCase())
+    .toList();
+```
+
+```dart
+// ❌ Manual map construction
+final map = <String, List<Item>>{};
+for (final item in items) {
+  map.putIfAbsent(item.category, () => []).add(item);
+}
+
+// ✅ (using collection-if/for in a different way — but groupBy isn't built-in)
+// The loop above is actually idiomatic Dart. Use package:collection for groupBy:
+import 'package:collection/collection.dart';
+final map = groupBy(items, (Item i) => i.category);
+```
+
+```dart
+// ❌ Building list with add() calls
+final widgets = <Widget>[];
+widgets.add(Header());
+if (showSubtitle) widgets.add(Subtitle());
+widgets.add(Body());
+
+// ✅ — collection-if
+final widgets = [
+  Header(),
+  if (showSubtitle) Subtitle(),
+  Body(),
+];
+```
+
+```dart
+// ❌ Spreading manually
+final all = <int>[];
+all.addAll(listA);
+all.addAll(listB);
+
+// ✅
+final all = [...listA, ...listB];
+```
+
+---
+
+## 3. Classes & Records {#classes}
+
+```dart
+// ❌ Manual data class boilerplate
+class Point {
+  final int x, y;
+  const Point(this.x, this.y);
+  @override bool operator ==(Object other) => ...
+  @override int get hashCode => ...
+  @override String toString() => 'Point($x, $y)';
+}
+
+// ✅ (Dart 3.0+)
+typedef Point = ({int x, int y});
+// or for named class semantics:
+class Point {
+  final int x, y;
+  const Point(this.x, this.y);
+}
+// Use package:equatable or Dart records for equality
+```
+
+```dart
+// ❌ Verbose constructor
+class User {
+  final String name;
+  final int age;
+  User(String name, int age) : name = name, age = age;
+}
+
+// ✅ — initializing formals
+class User {
+  final String name;
+  final int age;
+  const User(this.name, this.age);
+}
+```
+
+```dart
+// ❌ Mutable fields on an immutable object
+class Config {
+  String host;
+  int port;
+  Config(this.host, this.port);
+}
+
+// ✅
+class Config {
+  final String host;
+  final int port;
+  const Config(this.host, this.port);
+}
+```
+
+```dart
+// ❌ Switch on type with if-else chain
+if (shape is Circle) {
+  return (shape as Circle).radius * pi;
+} else if (shape is Rectangle) { ... }
+
+// ✅ (Dart 3.0+)
+return switch (shape) {
+  Circle(:final radius) => radius * radius * pi,
+  Rectangle(:final width, :final height) => width * height,
+};
+```
+
+---
+
+## 4. Async/Await & Streams {#async}
+
+```dart
+// ❌ .then() chains
+fetchUser()
+    .then((user) => fetchPosts(user))
+    .then((posts) => display(posts))
+    .catchError((e) => log(e));
+
+// ✅
+try {
+  final user = await fetchUser();
+  final posts = await fetchPosts(user);
+  display(posts);
+} catch (e) {
+  log(e);
+}
+```
+
+```dart
+// ❌ Sequential await for independent work
+final a = await fetchA();
+final b = await fetchB();
+
+// ✅
+final results = await Future.wait([fetchA(), fetchB()]);
+// or with typed destructuring:
+final (a, b) = await (fetchA(), fetchB()).wait; // Dart 3.0+ record
+```
+
+```dart
+// ❌ StreamBuilder doing too much in build
+StreamBuilder(
+  stream: stream,
+  builder: (ctx, snap) {
+    if (snap.hasError) return Error();
+    if (!snap.hasData) return Loading();
+    final data = snap.data!;
+    // 50 lines of widget tree...
+  },
+)
+
+// ✅ — extract widget, or use listen + setState for simple cases
+```
+
+---
+
+## 5. Error Handling {#errors}
+
+```dart
+// ❌ Catching Exception (too broad)
+try { process(); }
+on Exception catch (e) { print(e); }
+
+// ✅ — catch specific types
+try {
+  process();
+} on FormatException catch (e) {
+  throw AppException('Invalid format', cause: e);
+} on HttpException catch (e) {
+  throw AppException('Network error', cause: e);
+}
+```
+
+```dart
+// ❌ Returning null for errors
+Future<User?> fetchUser() async {
+  try { return await api.getUser(); }
+  catch (_) { return null; } // caller doesn't know why
+}
+
+// ✅ — let exceptions propagate, or use sealed Result type
+sealed class Result<T> {}
+class Success<T> extends Result<T> { final T value; Success(this.value); }
+class Failure<T> extends Result<T> { final Object error; Failure(this.error); }
+```
+
+---
+
+## 6. Flutter-Specific Patterns {#flutter}
+
+```dart
+// ❌ Rebuilding entire tree on state change
+setState(() {
+  // changes a single value, but the build() method builds 200 widgets
+});
+
+// ✅ — extract subtrees into separate widgets or use ValueListenableBuilder
+ValueListenableBuilder<int>(
+  valueListenable: counter,
+  builder: (_, value, __) => Text('$value'),
+)
+```
+
+```dart
+// ❌ const-able widget without const
+Container(color: Colors.blue)
+
+// ✅
+const ColoredBox(color: Colors.blue)
+// Mark constructors const when possible; use `const` keyword at call site
+```
+
+```dart
+// ❌ Navigator.push with MaterialPageRoute everywhere
+Navigator.push(context, MaterialPageRoute(builder: (_) => DetailPage()));
+
+// ✅ — named routes or GoRouter
+context.go('/detail');
+```
+
+---
+
+## 7. Anti-patterns specific to Dart {#antipatterns}
+
+| Anti-pattern | Preferred |
+|---|---|
+| `!` (bang) operator liberally | null checks and promotion |
+| `dynamic` everywhere | proper types |
+| `as` cast without check | pattern matching or `is` check |
+| Mutable fields on value objects | `final` fields |
+| `print()` for logging | `package:logging` or structured logger |
+| Manual `==`/`hashCode` | records, equatable, or code generation |
+| `setState` for complex state | Riverpod / Bloc / Provider |
+| Deep widget nesting | extract widgets into classes |
+| String-based routing | typed routing (GoRouter) |
+| `late` as escape hatch | nullable types or proper initialization |
+| `Future.delayed` for debounce | `Timer` or proper debounce utility |
+
+
+
+## Limitations
+- These are language-specific guidelines and do not cover overall architectural decisions.
+- Over-compression might reduce readability; apply judgement.