sdd-full 4.8.0 → 4.8.1

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

@@ -1,158 +0,0 @@
----
-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

@@ -1,168 +0,0 @@
----
-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

@@ -1,87 +0,0 @@
----
-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

@@ -1,101 +0,0 @@
----
-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

@@ -1,136 +0,0 @@
----
-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