sdd-full 4.6.2 → 4.8.0

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-modern-features/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: dart-modern-features
+description: |-
+  Guidelines for using modern Dart features (v3.0 - v3.10) such as Records,
+  Pattern Matching, Switch Expressions, Extension Types, Class Modifiers,
+  Wildcards, Null-Aware Elements, and Dot Shorthands.
+---
+
+# Dart Modern Features
+
+## 1. When to use this skill
+
+Use this skill when:
+- Writing or reviewing Dart code targeting Dart 3.0 or later.
+- Refactoring legacy Dart code to use modern, concise, and safe features.
+- Looking for idiomatic ways to handle multiple return values, deep data
+  extraction, or exhaustive checking.
+
+## Discovery
+
+To find candidates for modernization:
+
+### Switch Expressions
+Search for switch statements where every case assigns to the same variable
+or returns:
+- **Regex**: `switch\s*\([^)]+\)\s*\{\s*case`
+
+### Pattern Matching Candidates
+Search for manual map or JSON property extraction and type checking:
+- **Regex**: `containsKey\(['"][^'"]+['"]\)`
+- **Regex**: `json\[['"][^'"]+['"]\]\s+is\s+`
+
+### Null-Aware Elements
+Search for collection `if` statements checking for null:
+- **Regex**: `if\s*\(\w+\s*!=\s*null\)\s*\w+`
+
+### Digit Separators
+Search for long numbers without separators:
+- **Regex**: `\b\d{6,}\b` (Matches numbers with 6 or more digits).
+
+## 2. Features
+
+### Records
+Use records as anonymous, immutable, aggregate structures to bundle multiple
+objects without defining a custom class. Prefer them for returning multiple
+values from a function or grouping related data temporarily.
+
+**Avoid:**
+Creating a dedicated class for simple multiple-value returns.
+```dart
+class UserResult {
+  final String name;
+  final int age;
+  UserResult(this.name, this.age);
+}
+
+UserResult fetchUser() {
+  return UserResult('Alice', 42);
+}
+```
+
+**Prefer:**
+Using records to bundle types seamlessly on the fly.
+```dart
+(String, int) fetchUser() {
+  return ('Alice', 42);
+}
+
+void main() {
+  var user = fetchUser();
+  print(user.$1); // Alice
+}
+```
+
+### Patterns and Pattern Matching
+Use patterns to destructure complex data into local variables and match against
+specific shapes or values. Use them in `switch`, `if-case`, or variable
+declarations to unpack data directly.
+
+**Avoid:**
+Manually checking types, nulls, and keys for data extraction.
+```dart
+void processJson(Map<String, dynamic> json) {
+  if (json.containsKey('name') && json['name'] is String &&
+      json.containsKey('age') && json['age'] is int) {
+    String name = json['name'];
+    int age = json['age'];
+    print('$name is $age years old.');
+  }
+}
+```
+
+**Prefer:**
+Combining type-checking, validation, and assignment into a single statement.
+```dart
+void processJson(Map<String, dynamic> json) {
+  if (json case {'name': String name, 'age': int age}) {
+    print('$name is $age years old.');
+  }
+}
+```
+
+### Switch Expressions
+Use switch expressions to return a value directly, eliminating bulky `case` and
+`break` statements.
+
+**Avoid:**
+Using switch statements where every branch simply returns or assigns a value.
+```dart
+String describeStatus(int code) {
+  switch (code) {
+    case 200:
+      return 'Success';
+    case 404:
+      return 'Not Found';
+    default:
+      return 'Unknown';
+  }
+}
+```
+
+**Prefer:**
+Returning the evaluated expression directly using the `=>` syntax.
+```dart
+String describeStatus(int code) => switch (code) {
+  200 => 'Success',
+  404 => 'Not Found',
+  _ => 'Unknown',
+};
+```
+
+### Class Modifiers
+Use class modifiers (`sealed`, `final`, `base`, `interface`) to restrict how
+classes can be used outside their defines library. Prefer `sealed` for defining
+closed families of subtypes to enable exhaustive checking.
+
+**Avoid:**
+Using open `abstract` classes when the set of subclasses is known and fixed.
+```dart
+abstract class Result {}
+
+class Success extends Result {}
+class Failure extends Result {}
+
+String handle(Result r) {
+  if (r is Success) return 'OK';
+  if (r is Failure) return 'Error';
+  return 'Unknown';
+}
+```
+
+**Prefer:**
+Using `sealed` to guarantee to the compiler that all cases are covered.
+```dart
+sealed class Result {}
+
+class Success extends Result {}
+class Failure extends Result {}
+
+String handle(Result r) => switch(r) {
+  Success() => 'OK',
+  Failure() => 'Error',
+};
+```
+
+### Extension Types
+Use extension types for a zero-cost wrapper around an existing type. Use them to
+restrict operations or add custom behavior without runtime overhead.
+
+**Avoid:**
+Allocating new wrapper objects just for domain-specific logic or type safety.
+```dart
+class Id {
+  final int value;
+  Id(this.value);
+  bool get isValid => value > 0;
+}
+```
+
+**Prefer:**
+Using extension types which compile down to the underlying type at runtime.
+```dart
+extension type Id(int value) {
+  bool get isValid => value > 0;
+}
+```
+
+### Digit Separators
+Use underscores (`_`) in number literals strictly to improve visual readability
+of large numeric values.
+
+**Avoid:**
+Long number literals that are difficult to read at a glance.
+```dart
+const int oneMillion = 1000000;
+```
+
+**Prefer:**
+Using underscores to separate thousands or other groupings.
+```dart
+const int oneMillion = 1_000_000;
+```
+
+### Wildcard Variables
+Use wildcards (`_`) as non-binding variables or parameters to explicitly signal
+that a value is intentionally unused.
+
+**Avoid:**
+Inventing clunky, distinct variable names to avoid "unused variable" warnings.
+```dart
+void handleEvent(String ignoredName, int status) {
+  print('Status: $status');
+}
+```
+
+**Prefer:**
+Explicitly dropping the binding with an underscore.
+```dart
+void handleEvent(String _, int status) {
+  print('Status: $status');
+}
+```
+
+### Null-Aware Elements
+Use null-aware elements (`?`) inside collection literals to conditionally
+include items only if they evaluate to a non-null value.
+
+**Avoid:**
+Using collection `if` statements for simple null checks.
+```dart
+var names = [
+  'Alice',
+  if (optionalName != null) optionalName,
+  'Charlie'
+];
+```
+
+**Prefer:**
+Using the `?` prefix inline.
+```dart
+var names = ['Alice', ?optionalName, 'Charlie'];
+```
+
+### Dot Shorthands
+Use dot shorthands to omit the explicit type name when it can be confidently
+inferred from context, such as with enums or static fields.
+
+**Avoid:**
+Fully qualifying type names when the type is obvious from the context.
+```dart
+LogLevel currentLevel = LogLevel.info;
+```
+
+**Prefer:**
+Reducing visual noise with inferred shorthand.
+```dart
+LogLevel currentLevel = .info;
+```
+
+## Related Skills
+
+- **[dart-best-practices]**: General code
+  style and foundational Dart idioms that predate or complement the modern
+  syntax features.
+
+[dart-best-practices]: https://github.com/kevmoo/dash_skills/blob/main/.agent/skills/dart-best-practices/SKILL.md

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-package-maintenance/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: dart-package-maintenance
+description: |-
+  Guidelines for maintaining external Dart packages, covering versioning,
+  publishing workflows, and pull request management. Use when updating Dart
+  packages, preparing for a release, or managing collaborative changes in a
+  repository.
+---
+
+# Dart Package Maintenance
+
+Guidelines for maintaining Dart packages in alignment with Dart team best
+practices.
+
+## Discovery
+
+To find maintenance tasks or inconsistencies:
+
+### Consistency Checks
+Ensure the latest version in `CHANGELOG.md` matches `pubspec.yaml`:
+- Compare the top header in `CHANGELOG.md` with the `version:` field in
+  `pubspec.yaml`.
+
+## Versioning
+
+### Semantic Versioning
+- **Major**: Breaking changes.
+- **Minor**: New features (non-breaking API changes).
+- **Patch**: Bug fixes, documentation, or non-impacting changes.
+- **Unstable packages**: Use `0.major.minor+patch`.
+- **Recommendation**: Aim for `1.0.0` as soon as the package is stable.
+
+### Pre-Edit Verification
+- **Check Published Versions**: Before modifying `CHANGELOG.md` or
+  `pubspec.yaml`, ALWAYS check the currently released version (e.g., via
+  `git tag` or `pub.dev`).
+- **Do Not Amend Released Versions**: Never add new entries to a version header
+  that corresponds to a released tag.
+- **Increment for New Changes**: If the current version in `pubspec.yaml`
+  matches a released tag, increment the version (e.g., usually to `-wip`) and
+  create a new section in `CHANGELOG.md`.
+
+  - **Consistency**: The `CHANGELOG.md` header must match the new
+    `pubspec.yaml` version.
+
+  - **SemVer Guidelines**:
+    - **Breaking Changes**: Bump Major, reset Minor/Patch
+      (e.g., `2.0.0-wip`, `0.5.0-wip`).
+    - **New Features**: Bump Minor, reset Patch
+      (e.g., `1.1.0-wip`, `0.4.5-wip`).
+    - **Bug Fixes**: Bump Patch (e.g., `1.0.1-wip`).
+
+### Changelog Content
+- **Focus on User Impact**: Entries in `CHANGELOG.md` should focus on changes
+  visible to or impacting the end-user (e.g., new features, bug fixes,
+  breaking changes).
+- **Omit Internal Changes**: Do not include internal refactorings, test
+  changes, or other modifications that do not affect the package's behavior
+  or API for the user.
+
+### Work-in-Progress (WIP) Versions
+- Immediately after a publish, or on the first change after a publish, update
+  `pubspec.yaml` and `CHANGELOG.md` with a `-wip` suffix (e.g., `1.1.0-wip`).
+- This indicates the current state is not yet published.
+
+### Breaking Changes
+- Evaluate the impact on dependent packages and internal projects.
+- Consider running changes through internal presubmits if possible.
+- Prefer incremental rollouts (e.g., new behavior as opt-in) to minimize
+  downstream breakage.
+
+## Publishing Process
+
+1. **Preparation**: Remove the `-wip` suffix from `pubspec.yaml` and
+   `CHANGELOG.md` in a dedicated pull request.
+2. **Execution**: Run `dart pub publish` (or `flutter pub publish`) and resolve
+   all warnings and errors.
+3. **Tagging**: Create and push a git tag for the published version:
+   - For single-package repos: `v1.2.3`
+   - For monorepos: `package_name-v1.2.3`
+   - Example: `git tag v1.2.3 && git push --tags`
+
+## Pull Request Management
+
+- **Commits**: Each PR should generally correspond to a single squashed commit
+  upon merging.
+- **Shared History**: Once a PR is open, avoid force pushing to the branch.
+- **Conflict Resolution**: Prefer merging `main` into the PR branch rather than
+  rebasing to resolve conflicts. This preserves the review history and comments.
+- **Reviewing**: Add comments from the "Files changed" view to batch them.
+- **Local Inspection**: Use `gh pr checkout <number>` to inspect changes
+  locally in your IDE.

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-test-coverage/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: dart-test-coverage
+description: |-
+  Understand and improve test coverage in a Dart package.
+  Helps agents run coverage, interpret results, and identify missed lines.
+---
+
+# Dart Test Coverage
+
+Guidelines for running and interpreting test coverage in Dart packages.
+
+## When to use this skill
+- When asked to "check test coverage" or "improve coverage".
+- When you need to identify which parts of a library are untested.
+
+## Discovery
+
+To find areas lacking test coverage:
+
+### Run Coverage Analysis
+Follow the workflow to generate and interpret coverage data:
+1. **Run Tests with Coverage**: `dart test --coverage=.dart_tool/coverage`
+2. **Interpret Results**: Use the script or `format_coverage` as described in
+   the **Interpreting Results** section to identify specific files and missed
+   lines.
+
+## How to use this skill (The Workflow)
+1.  Ensure tests pass by running `dart test`.
+2.  Collect coverage by running `dart test --coverage=.dart_tool/coverage`.
+3.  Interpret the results using the provided script or standard tools.
+4.  Add tests to cover missed lines.
+
+## Running Coverage
+Run the following command to collect coverage in JSON format:
+```bash
+dart test --coverage=.dart_tool/coverage
+```
+
+> [!NOTE]
+> We use `.dart_tool/coverage` as the output directory because `.dart_tool`
+> is typically already ignored in `.gitignore` files.
+
+> [!TIP]
+> For projects with complex conditional logic, you can pass the
+> `--branch-coverage` flag to `dart test` to collect branch-level coverage.
+
+## Interpreting Results
+
+### Option 1: Use the custom interpreter script
+This repository includes a zero-dependency script that parses the raw JSON
+output and provides a summary of covered percentage and missed lines.
+
+Run it from the project root (adjust path to script as needed):
+```bash
+dart run .agent/skills/dart-test-coverage/scripts/interpret_coverage.dart .dart_tool/coverage <package_name>
+```
+Replace `<package_name>` with the name from `pubspec.yaml`.
+
+Example Output:
+```
+package:my_pkg/src/file.dart: 50.0% (2/4 lines)
+  Missed lines: 3, 4
+```
+
+### Option 2: Use package:coverage
+If `package:test` is installed, `package:coverage` is likely available as a
+transitive dependency. You can use its `format_coverage` tool.
+
+To get a human-readable "pretty print" of the coverage:
+```bash
+dart run coverage:format_coverage --in=.dart_tool/coverage --out=stdout --pretty-print --report-on=lib
+```
+This will output the file content with hit counts on the left (e.g., `0|` for
+missed lines).
+
+## Best Practices for Reporting Results
+When presenting coverage results to the user, follow these guidelines:
+1.  **State the high-level percentage first** to give immediate context.
+2.  **Identify specific files and missed lines** clearly.
+3.  **Translate line numbers to code**: Don't just say "lines 3-6 are missed".
+    Look at the source file and tell the user which functions or blocks are
+    untested (e.g., "The `divide` function is missing coverage").
+4.  **Propose concrete fixes**: Provide example test code that the user can
+    immediately apply to cover the missed lines.
+5.  **Use tables for multi-file summaries**: When reporting on multiple files,
+    use a markdown table with columns for File, Coverage %, and Missed Lines
+    to make the summary easy to scan.
+
+## Constraints
+- ALWAYS verify that tests pass before collecting coverage.
+- DO NOT commit the `.dart_tool/coverage` directory.
+- Focus coverage improvements on `lib/` files, not `test/` or generated files.

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-test-coverage/example/lib/src/calculator.dart

@@ -0,0 +1,7 @@
+int add(int a, int b) => a + b;
+int subtract(int a, int b) => a - b;
+int multiply(int a, int b) => a * b;
+int divide(int a, int b) {
+  if (b == 0) throw ArgumentError('Cannot divide by zero');
+  return a ~/ b;
+}

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-test-coverage/example/pubspec.yaml

@@ -0,0 +1,8 @@
+name: dummy_pkg
+publish_to: none
+
+environment:
+  sdk: ^3.9.0
+
+dev_dependencies:
+  test: ^1.24.0

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-test-coverage/example/test/calculator_test.dart

@@ -0,0 +1,11 @@
+import 'package:dummy_pkg/src/calculator.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('add', () {
+    expect(add(1, 2), 3);
+  });
+  test('subtract', () {
+    expect(subtract(2, 1), 1);
+  });
+}

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-test-coverage/scripts/interpret_coverage.dart

@@ -0,0 +1,95 @@
+#!/usr/bin/env dart
+
+import 'dart:convert';
+import 'dart:io';
+
+void main(List<String> args) {
+  if (args.isEmpty) {
+    print(
+      'Usage: dart interpret_coverage.dart <coverage_directory> [package_name]',
+    );
+    exitCode = 64; // Bad usage
+    return;
+  }
+  final dirPath = args[0];
+  final packageName = args.length > 1 ? args[1] : null;
+
+  final dir = Directory(dirPath);
+  if (!dir.existsSync()) {
+    print('Directory not found: $dirPath');
+    exitCode = 78; // Configuration error
+    return;
+  }
+
+  final files = dir
+      .listSync(recursive: true)
+      .whereType<File>()
+      .where((f) => f.path.endsWith('.vm.json'));
+
+  final coverageData = processCoverage(files, packageName);
+
+  if (coverageData.isEmpty) {
+    print('No coverage data found for the specified criteria.');
+    return;
+  }
+
+  // Print summary
+  coverageData.forEach((source, lineHits) {
+    final totalLines = lineHits.length;
+    final coveredLines = lineHits.values.where((hits) => hits > 0).length;
+    final percent = totalLines > 0
+        ? (coveredLines / totalLines * 100).toStringAsFixed(1)
+        : '100';
+
+    print('$source: $percent% ($coveredLines/$totalLines lines)');
+
+    // Show missed lines
+    final missed =
+        lineHits.entries.where((e) => e.value == 0).map((e) => e.key).toList()
+          ..sort();
+
+    if (missed.isNotEmpty) {
+      print('  Missed lines: ${missed.join(', ')}');
+    }
+  });
+}
+
+/// Processes a list of coverage files and returns a map of file paths to line hit counts.
+///
+/// The returned map structure is: `{ file_uri: { line_number: hit_count } }`.
+///
+/// If [packageName] is provided, only files starting with `package:$packageName/` are included.
+/// Files containing `/test/` are skipped.
+Map<String, Map<int, int>> processCoverage(
+  Iterable<File> files,
+  String? packageName,
+) {
+  final coverageData = <String, Map<int, int>>{}; // file -> (line -> hits)
+  for (final file in files) {
+    final content = file.readAsStringSync();
+    final json = jsonDecode(content) as Map<String, dynamic>;
+    final coverage = json['coverage'] as List<dynamic>;
+
+    for (final item in coverage) {
+      final source = item['source'] as String;
+
+      // Filter by package name if provided
+      if (packageName != null && !source.startsWith('package:$packageName/')) {
+        continue;
+      }
+
+      // Skip test files usually
+      if (source.contains('/test/')) continue;
+
+      final hits = item['hits'] as List<dynamic>;
+      final fileData = coverageData.putIfAbsent(source, () => <int, int>{});
+
+      for (var i = 0; i < hits.length; i += 2) {
+        final line = hits[i] as int;
+        final count = hits[i + 1] as int;
+        fileData[line] = (fileData[line] ?? 0) + count;
+      }
+    }
+  }
+  return coverageData;
+}

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-test-coverage/scripts/pubspec.yaml

@@ -0,0 +1,6 @@
+name: interpret_coverage
+environment:
+  sdk: '^3.9.0'
+
+dev_dependencies:
+  test: ^1.24.0

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-test-coverage/scripts/test/interpret_coverage_test.dart

@@ -0,0 +1,93 @@
+import 'dart:convert';
+import 'dart:io';
+import 'package:test/test.dart';
+import '../interpret_coverage.dart';
+
+void main() {
+  /// Helper to create a mock coverage file.
+  /// Takes a list of items where 'hits' is a Map<int, int> (line -> hits).
+  File createMockCoverageFile(
+    Directory dir,
+    String filename,
+    List<Map<String, dynamic>> coverageItems,
+  ) {
+    final file = File('${dir.path}/$filename');
+
+    final processedItems = coverageItems.map((item) {
+      final source = item['source'] as String;
+      final hitsMap = item['hits'] as Map<int, int>;
+      final flatHits = <int>[];
+      hitsMap.forEach((line, count) {
+        flatHits.add(line);
+        flatHits.add(count);
+      });
+      return {'source': source, 'hits': flatHits};
+    }).toList();
+
+    final json = {'coverage': processedItems};
+    file.writeAsStringSync(jsonEncode(json));
+    return file;
+  }
+
+  test('processCoverage extracts data correctly', () {
+    final tempDir = Directory.systemTemp.createTempSync('coverage_test');
+    final coverageFile = createMockCoverageFile(tempDir, 'test.vm.json', [
+      {
+        'source': 'package:foo/bar.dart',
+        'hits': {1: 1, 2: 0},
+      },
+    ]);
+
+    try {
+      final result = processCoverage([coverageFile], null);
+      expect(result, contains('package:foo/bar.dart'));
+      expect(result['package:foo/bar.dart'], {1: 1, 2: 0});
+    } finally {
+      tempDir.deleteSync(recursive: true);
+    }
+  });
+
+  test('processCoverage filters by package name', () {
+    final tempDir = Directory.systemTemp.createTempSync('coverage_test');
+    final coverageFile = createMockCoverageFile(tempDir, 'test.vm.json', [
+      {
+        'source': 'package:foo/bar.dart',
+        'hits': {1: 1},
+      },
+      {
+        'source': 'package:baz/qux.dart',
+        'hits': {1: 1},
+      },
+    ]);
+
+    try {
+      final result = processCoverage([coverageFile], 'foo');
+      expect(result, contains('package:foo/bar.dart'));
+      expect(result, isNot(contains('package:baz/qux.dart')));
+    } finally {
+      tempDir.deleteSync(recursive: true);
+    }
+  });
+
+  test('processCoverage skips test files', () {
+    final tempDir = Directory.systemTemp.createTempSync('coverage_test');
+    final coverageFile = createMockCoverageFile(tempDir, 'test.vm.json', [
+      {
+        'source': 'package:foo/test/bar_test.dart',
+        'hits': {1: 1},
+      },
+      {
+        'source': 'package:foo/bar.dart',
+        'hits': {1: 1},
+      },
+    ]);
+
+    try {
+      final result = processCoverage([coverageFile], 'foo');
+      expect(result, contains('package:foo/bar.dart'));
+      expect(result, isNot(contains('package:foo/test/bar_test.dart')));
+    } finally {
+      tempDir.deleteSync(recursive: true);
+    }
+  });
+}