sdd-full 4.6.1 → 4.8.0

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

@@ -0,0 +1,158 @@
+---
+name: dart-checks-migration
+description: |-
+  Replace the usage of `expect` and similar functions from `package:matcher`
+  to `package:checks` equivalents.
+license: Apache-2.0
+---
+
+# Dart Checks Migration
+
+## When to use this skill
+Use this skill when:
+- Migrating existing test files from `package:matcher` to `package:checks`.
+- A user specifically asks for "modern checks" or similar.
+
+## The Workflow
+
+1.  **Analysis**:
+    - Use `grep` to identify files using `expect` or `package:matcher`.
+    - Review custom matchers; these may require manual migration.
+2.  **Tools & Dependencies**:
+    - Ensure `dev_dependencies` includes `checks`.
+    - Run `dart pub add --dev checks` if missing.
+3.  **Discovery**:
+    - Use the **Strategies for Discovery** below to find candidates.
+4.  **Replacement**:
+    - Add `import 'package:checks/checks.dart';`.
+    - Apply the **Common Patterns** below.
+    - **Final Step**: Replace `import 'package:test/test.dart';` with
+      `import 'package:test/scaffolding.dart';` ONLY after all `expect` calls
+      are replaced. This ensures incremental progress.
+5.  **Verification**:
+    - Ensure the code analyzes cleanly.
+    - Ensure tests pass.
+
+## Strategies for Discovery
+
+To find candidates for migration, use the following search strategies:
+
+### Files using Legacy Matchers
+Search for test files that import `package:test/test.dart` or use `expect`:
+- **Search Query**: `import 'package:test/test.dart';`
+- **Regex**: `expect\(`
+
+### Specific Matchers to Target
+Search for specific matchers that are easy to migrate:
+- **Regex**: `expect\(.*,\s*equals\(`
+- **Regex**: `expect\(.*,\s*isNull\)`
+- **Regex**: `expect\(.*,\s*isTrue\)`
+- **Regex**: `expect\(.*,\s*isFalse\)`
+- **Regex**: `expect\(.*,\s*throwsA`
+
+## Common Patterns
+
+| Legacy `expect` | Modern `check` |
+| :--- | :--- |
+| `expect(a, equals(b))` | `check(a).equals(b)` |
+| `expect(a, isTrue)` | `check(a).isTrue()` |
+| `expect(a, isFalse)` | `check(a).isFalse()` |
+| `expect(a, isNull)` | `check(a).isNull()` |
+| `expect(a, isNotNull)` | `check(a).isNotNull()` |
+| `expect(() => fn(), throwsA<T>())` | `check(() => fn()).throws<T>()` |
+| `expect(list, hasLength(n))` | `check(list).length.equals(n)` |
+| `expect(a, closeTo(b, delta))` | `check(a).isA<num>().isCloseTo(b, delta)` |
+| `expect(a, greaterThan(b))` | `check(a).isGreaterThan(b)` |
+| `expect(a, lessThan(b))` | `check(a).isLessThan(b)` |
+| `expect(list, isEmpty)` | `check(list).isEmpty()` |
+| `expect(list, isNotEmpty)` | `check(list).isNotEmpty()` |
+| `expect(list, contains(item))` | `check(list).contains(item)` |
+| `expect(map, equals(otherMap))` | `check(map).deepEquals(otherMap)` |
+| `expect(list, equals(otherList))` | `check(list).deepEquals(otherList)` |
+| `expect(future, completes)` | `await check(future).completes()` |
+| `expect(stream, emitsInOrder(...))` | `await check(stream).withQueue.inOrder(...)` |
+
+### Async & Futures (CRITICAL)
+
+- **Checking async functions:**
+  `check(() => asyncFunc()).throws<T>()` causes **FALSE POSITIVES** because the
+  closure returns a `Future`, which is a value, so it "completes normally"
+  (as a Future).
+  **Correct Usage:**
+  ```dart
+  await check(asyncFunc()).throws<T>();
+  ```
+
+- **Chaining on void returns:**
+  Many async check methods (like `throws`) return `Future<void>`. You cannot
+  chain directly on them. Use cascades or callbacks.
+  **Wrong:**
+  ```dart
+  await check(future)
+      .throws<Error>()
+      .has((e) => e.message, 'message')
+      .equals('foo');
+  ```
+  **Correct:**
+  ```dart
+  await check(future).throws<Error>(
+      (it) => it.has((e) => e.message, 'message').equals('foo'));
+  ```
+
+## Complex Examples
+
+*Deep Verification with `isA` and `having`:*
+
+**Legacy:**
+```dart
+expect(() => foo(), throwsA(isA<ArgumentError>()
+    .having((e) => e.message, 'message', contains('MSG'))));
+```
+
+**Modern:**
+```dart
+check(() => foo())
+    .throws<ArgumentError>()
+    .has((e) => e.message, 'message')
+    .contains('MSG');
+```
+
+*Property Extraction:*
+
+**Legacy:**
+```dart
+expect(obj.prop, equals(value)); // When checking multiple props
+```
+
+**Modern:**
+```dart
+check(obj)
+  ..has((e) => e.prop, 'prop').equals(value)
+  ..has((e) => e.other, 'other').equals(otherValue);
+```
+
+*One-line Cascades:*
+Since checks often return `void`, use cascades for multiple assertions on the
+same subject.
+```dart
+check(it)..isGreaterThan(10)..isLessThan(20);
+```
+
+## Constraints
+
+- **Scope**: Only modify files in `test/` (and `pubspec.yaml`).
+- **Correctness**: One failing test is unacceptable. If a test fails after
+  migration and you cannot fix it immediately, REVERT that specific change.
+- **Type Safety**: `package:checks` is stricter about types than `matcher`.
+  You may need to add explicit `as T` casts or `isA<T>()` checks in the chain.
+
+## Related Skills
+
+- **[dart-test-fundamentals]**: Core
+  concepts for structuring tests, lifecycles, and configuration.
+- **[dart-matcher-best-practices]**:
+  Best practices for the traditional `package:matcher` that is being migrated
+  away from.
+
+[dart-test-fundamentals]: https://github.com/kevmoo/dash_skills/blob/main/.agent/skills/dart-test-fundamentals/SKILL.md
+[dart-matcher-best-practices]: https://github.com/kevmoo/dash_skills/blob/main/.agent/skills/dart-matcher-best-practices/SKILL.md

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-cli-app-best-practices/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: dart-cli-app-best-practices
+description: |-
+  Best practices for creating high-quality, executable Dart CLI applications.
+  Covers entrypoint structure, exit code handling, and recommended packages.
+license: Apache-2.0
+---
+
+# Dart CLI Application Best Practices
+
+## 1. When to use this skill
+Use this skill when:
+-   Creating a new Dart CLI application.
+-   Refactoring an existing CLI entrypoint (`bin/`).
+-   Reviewing CLI code for quality and standards.
+-   Setting up executable scripts for Linux/Mac.
+
+## 2. Best Practices
+
+### Entrypoint Structure (`bin/`)
+Keep the contents of your entrypoint file (e.g., `bin/my_app.dart`) minimal.
+This improves testability by decoupling logic from the process runner.
+
+**DO:**
+```dart
+// bin/my_app.dart
+import 'package:my_app/src/entry_point.dart';
+
+Future<void> main(List<String> arguments) async {
+  await runApp(arguments);
+}
+```
+
+**DON'T:**
+-   Put complex logic directly in `bin/my_app.dart`.
+-   Define classes or heavy functions in the entrypoint.
+
+### Put an `executable` entry in `pubspec.yaml`
+
+List your executables in `pubspec.yaml` to make them available for global
+activation and clean invocation via `dart run`.
+
+**DO:**
+Add an `executables` section mapping the command name to the Dart file in
+`bin/` (excluding the `.dart` extension).
+
+```yaml
+executables:
+  my_app: # Maps to bin/my_app.dart
+  custom_name: main # Maps to bin/main.dart
+```
+
+Then run via `dart run my_app` or `dart run custom_name`.
+
+### CONSIDER `#!` for other scripts on *nix systems
+
+This is NOT a hard and fast rule, but it is something to consider.
+
+For CLI tools intended to be run directly on Linux and Mac, add a shebang and
+ensure the file is executable.
+
+**DO:**
+1.  Add `#!/usr/bin/env dart` to the first line.
+2.  Run `chmod +x bin/my_script.dart` to make it executable.
+
+```dart
+#!/usr/bin/env dart
+
+void main() => print('Ready to run!');
+```
+
+### Process Termination (`exitCode`)
+Properly handle process termination to allow for debugging and correct status
+reporting.
+
+**DO:**
+-   Use the `exitCode` setter to report failure.
+-   Allow `main` to complete naturally.
+-   Use standard exit codes (sysexits) for clarity (e.g., `64` for bad usage,
+    `78` for configuration errors).
+    -   See `package:io` `ExitCode` class or FreeBSD sysexits man page.
+
+```dart
+import 'dart:io';
+
+void main() {
+  if (someFailure) {
+    exitCode = 64; // DO!
+    return;
+  }
+}
+```
+
+**AVOID:**
+-   Calling `exit(code)` directly, as it terminates the VM immediately,
+    preventing "pause on exit" debugging and `finally` blocks from running.
+
+### Exception Handling
+Uncaught exceptions automatically set a non-zero exit code, but you should
+handle expected errors gracefully.
+
+**Example:**
+```dart
+Future<void> main(List<String> arguments) async {
+  try {
+    await runApp(arguments);
+  } catch (e, stack) {
+    print('App crashed!');
+    print(e);
+    print(stack);
+    exitCode = 1; // Explicitly fail
+  }
+}
+```
+
+### Cross-Platform Compatibility (Windows Support)
+When writing CLI applications and tests, ensure compatibility with Windows:
+- **Paths**: Avoid hardcoding path separators like `/` because Windows uses `\`.
+  Use `package:path`'s `p.join` or `p.normalize` to construct paths portably.
+- **File Permissions**: When testing file permission errors, remember that
+  `chmod` is not available on Windows. Use `icacls` on Windows or appropriate
+  mock libraries to simulate permission errors. Never skip tests on Windows
+  simply because of permission commands if a Windows equivalent exists.
+
+## Discovery
+
+To find areas to apply these best practices:
+
+### Heavy Entrypoints
+Inspect files in `bin/` to see if they contain logic that should be in `lib/`:
+- **Target**: Files matching `bin/*.dart`.
+
+### Direct Process Termination
+Search for calls to `exit()` instead of setting `exitCode`:
+- **Regex**: `\bexit\(`
+
+### Hardcoded Path Separators
+Search for hardcoded `/` in strings that appear to be file paths:
+- **Regex**: `['"][^'"]+/[^'"]+['"]` (Verify context as this may match URLs).
+
+## 3. Recommended Packages
+
+Use these community-standard packages owned by the [Dart team](https://dart.dev)
+to solve common CLI problems:
+
+| Category | Recommended Package | Usage |
+| :--- | :--- | :--- |
+| **Stack Traces** | [`package:stack_trace`](https://pub.dev/packages/stack_trace) | detailed, cleaner stack traces |
+| **Arg Parsing** | [`package:args`](https://pub.dev/packages/args) | standard flag/option parsing |
+| **Testing** | [`package:test_process`](https://pub.dev/packages/test_process) | integration testing for CLI apps |
+| **Testing** | [`package:test_descriptor`](https://pub.dev/packages/test_descriptor) | file system fixtures for tests |
+| **Networking** | [`package:http`](https://pub.dev/packages/http) | standard HTTP client (remember user-agent!) |
+| **ANSI Output** | [`package:io`](https://pub.dev/packages/io) | handling ANSI colors and styles |
+
+## 4. Interesting community packages
+
+| Category | Recommended Package | Usage |
+| :--- | :--- | :--- |
+| **Configuration** | [`package:json_serializable`](https://pub.dev/packages/json_serializable) | strongly typed config objects |
+| **CLI Generation** | [`package:build_cli`](https://pub.dev/packages/build_cli) | generate arg parsers from classes |
+| **Version Info** | [`package:build_version`](https://pub.dev/packages/build_version) | automatic version injection |
+| **Configuration** | [`package:checked_yaml`](https://pub.dev/packages/checked_yaml) | precise YAML parsing with line numbers |
+
+## 5. Conventions
+
+-   **File Caching**: Write cached files to `.dart_tool/[pkg_name]/`.
+-   **User-Agent**: Always set a User-Agent header in HTTP requests, including
+    version info.

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

@@ -0,0 +1,87 @@
+---
+name: dart-doc-validation
+description: |-
+  Best practices for validating Dart documentation comments.
+  Covers using `dart doc` to catch unresolved references and macros.
+license: Apache-2.0
+---
+
+# Dart Doc Validation
+
+## 1. When to use this skill
+
+Use this skill when:
+-   Writing or updating documentation comments (`///`) in Dart code.
+-   Checking for broken documentation links, references, or macros.
+-   Preparing a package for publishing to pub.dev.
+
+## Discovery
+
+To find documentation issues:
+
+### Missing Lint
+Verify if the `comment_references` lint is enabled:
+- **Target**: `analysis_options.yaml`
+- **Search Query**: `comment_references`
+
+### Automated Validation
+Run the documentation generator to surface warnings:
+- **Command**: `dart doc -o $(mktemp -d)`
+- **Keywords to look for**: `warning:`, `unresolved doc reference`,
+  `undefined macro`
+
+## 2. Best Practices
+
+### Enable the doc validation lint
+
+In your `analysis_options.yaml`, enable the `comment_references` lint.
+
+```yaml
+linter:
+  rules:
+    - comment_references
+```
+
+### Validating Documentation Locally
+
+Use the `dart doc` command with a temporary output directory to validate
+documentation comments without polluting the local project workspace.
+
+This command parses all documentation comments and reports warnings such as:
+-   `warning: unresolved doc reference`
+-   `warning: undefined macro`
+
+**Command to run:**
+
+```bash
+dart doc -o $(mktemp -d)
+```
+
+*This will work on Mac and Linux.*
+
+This ensures that the generated HTML files are stored in a temporary location
+and don't clutter the package directory, while still surfacing all validation
+warnings in the terminal output.
+
+**Browsing the docs:**
+
+Our docs use features designed to be run on a web server. If you want to browse
+the generated docs locally, install the `dhttpd` package.
+
+
+```shell
+pub global activate dhttpd
+TMP_DIR=$(mktemp -d) && dart doc -o "$TMP_DIR" &&  dhttpd --path "$TMP_DIR"
+```
+
+*(Or use another HTTP server, such as `python3 -m http.server`.)*
+
+
+### Fixing Common Warnings
+
+-   **Unresolved doc reference**: Ensure that any identifier wrapped in square
+    brackets (`[Identifier]`) correctly points to an existing class, method,
+    property, or parameter in the current scope or imported libraries.
+-   **Undefined macro**: If using `{@macro macro_name}`, ensure that the
+    template `{@template macro_name}` is defined in the same file or a file
+    that is imported and visible to the documentation generator.

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

@@ -0,0 +1,101 @@
+---
+name: dart-long-lines
+description: |-
+  Guidelines for handling long lines in Dart code to adhere to the 80-column
+  rule. The `lines_longer_than_80_chars` lint.
+license: Apache-2.0
+---
+
+# Dart Long Lines
+
+## 1. When to use this skill
+
+Use this skill when:
+-   Writing Dart code that might exceed the 80-column limit.
+-   Refactoring code to comply with the `lines_longer_than_80_chars` lint.
+    Reference: https://dart.dev/tools/linter-rules/lines_longer_than_80_chars
+
+## Discovery
+
+To find lines that exceed the limit:
+
+### Automated Analysis
+The most reliable way to find long lines is to use the Dart analyzer:
+- **Command**: `dart analyze`
+- **Lint**: `lines_longer_than_80_chars`
+
+### Manual Search
+To search for long lines using regex:
+- **Regex**: `^.{81,}$` (Matches any line with 81 or more characters).
+
+## 2. Guidelines
+
+### Format First
+Always run `dart format` before manually breaking long lines. The formatter
+often automatically fixes long lines, especially in generated code, and
+applies standard Dart styling rules.
+
+### Code Comments
+Break long code comments (`//`) cleanly at word boundaries to ensure lines do
+not exceed 80 characters. Maintain tight formatting and avoid unnecessary
+vertical space.
+
+### Documentation Comments (`///`)
+-   Apply the same line-breaking rules as for code comments.
+-   Avoid breaking markdown link blocks like `[name]` or
+    `[text](http://example.com)` across lines. Place them on their own line if
+    they exceed the limit.
+-   Start doc comments with a single summary sentence, followed by a blank line
+    before the rest of the comment. It is okay to break this first sentence
+    across multiple lines to fit the 80-column limit.
+-   Avoid unresolved references or dangling sentences.
+
+### Long Strings
+-   Use adjacent string literals (e.g., `'part 1 ' 'part 2'`) to break long
+    strings. Break at word boundaries.
+-   If a single-line string contains newline characters (`\n`) or if there are
+    consecutive `print` statements, consider migrating to a multi-line string
+    literal (`'''`).
+
+### Format and Analyze After Changes
+-   Run `dart format` and `dart analyze` after making changes.
+-   Be aware that splitting strings may trigger new lints (e.g.,
+    `prefer_single_quotes` if a double-quoted string is split into parts that
+    no longer contain single quotes).
+
+## 3. Examples
+
+### Documentation Comment Link
+**Avoid:**
+```dart
+/// This is a long doc comment that contains a link to [a very long
+/// URL](http://example.com/very/long/url/that/exceeds/eighty/chars).
+```
+
+**Prefer:**
+```dart
+/// This is a long doc comment that contains a link to [a very long URL][ref].
+///
+/// [ref]: http://example.com/very/long/url/that/exceeds/eighty/chars
+```
+
+### Adjacent String Literals
+**Prefer:**
+```dart
+final longString = 'This is a very long string that needs to be broken '
+    'across multiple lines to stay under the limit.';
+```
+
+### Multi-line String Migration
+**Avoid:**
+```dart
+print('This is line 1\nThis is line 2 that is also quite long\nThis is line 3 which makes the whole thing exceed eighty characters');
+```
+
+**Prefer:**
+```dart
+print('''This is line 1
+This is line 2 that is also quite long
+This is line 3 which makes the whole thing exceed eighty characters''');
+```
+

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-matcher-best-practices/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: dart-matcher-best-practices
+description: |-
+  Best practices for using `expect` and `package:matcher`.
+  Focuses on readable assertions, proper matcher selection, and avoiding
+  common pitfalls.
+license: Apache-2.0
+---
+
+# Dart Matcher Best Practices
+
+## When to use this skill
+
+Use this skill when:
+- Writing assertions using `expect` and `package:matcher`.
+- Migrating legacy manual checks to cleaner matchers.
+- Debugging confusing test failures.
+
+## Discovery
+
+To find candidates for improving matcher usage, search for suboptimal patterns:
+
+### Suboptimal Length Checks
+Search for length checks that should use `hasLength`:
+- **Regex**: `expect\([^,]+.length,\s*`
+
+### Suboptimal Boolean Checks
+Search for checks on boolean properties that have specific matchers:
+- **Regex**: `expect\([^,]+.isEmpty,\s*(true|equals\(true\))`
+- **Regex**: `expect\([^,]+.isNotEmpty,\s*(true|equals\(true\))`
+- **Regex**: `expect\([^,]+.contains\(.*\),\s*(true|equals\(true\))`
+
+### Suboptimal Map Lookups
+Search for manual map lookups instead of `containsPair`:
+- **Regex**: `expect\([^,]+\[.*\],\s*`
+
+## Core Matchers
+
+### 1. Collections (`hasLength`, `contains`, `isEmpty`, `unorderedEquals`, `containsPair`)
+
+- **`hasLength(n)`**:
+  - Prefer `expect(list, hasLength(n))` over `expect(list.length, n)`.
+  - Gives better error messages on failure (shows actual list content).
+
+- **`isEmpty` / `isNotEmpty`**:
+  - Prefer `expect(list, isEmpty)` over `expect(list.isEmpty, true)`.
+  - Prefer `expect(list, isNotEmpty)` over `expect(list.isNotEmpty, true)`.
+
+- **`contains(item)`**:
+  - Verify existence without manual iteration.
+  - Prefer over `expect(list.contains(item), true)`.
+
+- **`unorderedEquals(items)`**:
+  - Verify contents regardless of order.
+  - Prefer over `expect(list, containsAll(items))`.
+
+- **`containsPair(key, value)`**:
+  - Verify a map contains a specific key-value pair.
+  - Prefer over checking `expect(map[key], value)` or
+    `expect(map.containsKey(key), true)`.
+
+### 2. Type Checks (`isA<T>` and `TypeMatcher<T>`)
+
+- **`isA<T>()`**:
+  - Prefer for inline assertions: `expect(obj, isA<Type>())`.
+  - More concise and readable than `TypeMatcher<Type>()`.
+  - Allows chaining constraints using `.having()`.
+
+- **`TypeMatcher<T>`**:
+  - Prefer when defining top-level reusable matchers.
+  - **Use `const`**: `const isMyType = TypeMatcher<MyType>();`
+  - Chaining `.having()` works here too, but the resulting matcher is not `const`.
+
+### 3. Object Properties (`having`)
+
+Use `.having()` on `isA<T>()` or other TypeMatchers to check properties.
+
+- **Descriptive Names**: Use meaningful parameter names in the closure (e.g.,
+  `(e) => e.message`) instead of generic ones like `p0` to improve readability.
+
+```dart
+expect(person, isA<Person>()
+    .having((p) => p.name, 'name', 'Alice')
+    .having((p) => p.age, 'age', greaterThan(18)));
+```
+
+This provides detailed failure messages indicating exactly which property
+failed.
+
+### 4. Async Assertions
+
+- **`completion(matcher)`**:
+  - Wait for a future to complete and check its value.
+  - **Prefer `await expectLater(...)`** to ensure the future completes before
+    the test continues.
+  - `await expectLater(future, completion(equals(42)))`.
+
+- **`throwsA(matcher)`**:
+  - Check that a future or function throws an exception.
+  - `await expectLater(future, throwsA(isA<StateError>()))`.
+  - `expect(() => function(), throwsA(isA<ArgumentError>()))` (synchronous
+    function throwing is fine with `expect`).
+
+### 5. Using `expectLater`
+
+Use `await expectLater(...)` when testing async behavior to ensure proper
+sequencing.
+
+```dart
+// GOOD: Waits for future to complete before checking side effects
+await expectLater(future, completion(equals(42)));
+expect(sideEffectState, equals('done'));
+
+// BAD: Side effect check might run before future completes
+expect(future, completion(equals(42)));
+expect(sideEffectState, equals('done')); // Race condition!
+```
+
+## Principles
+
+1.  **Readable Failures**: Choose matchers that produce clear error messages.
+2.  **Avoid Manual Logic**: Don't use `if` statements or `for` loops for
+    assertions; let matchers handle it.
+3.  **Specific Matchers**: Use the most specific matcher available (e.g.,
+    `containsPair` for maps instead of checking keys manually).
+
+## Related Skills
+
+- **[dart-test-fundamentals]**: Core
+  concepts for structuring tests, lifecycles, and configuration.
+- **[dart-checks-migration]**: Use this
+  skill if you are migrating tests from `package:matcher` to modern
+  `package:checks`.
+
+[dart-test-fundamentals]: https://github.com/kevmoo/dash_skills/blob/main/.agent/skills/dart-test-fundamentals/SKILL.md
+[dart-checks-migration]: https://github.com/kevmoo/dash_skills/blob/main/.agent/skills/dart-checks-migration/SKILL.md