diff --git a/.agents/skills/convert-dot-shorthand/SKILL.md b/.agents/skills/convert-dot-shorthand/SKILL.md new file mode 100644 index 0000000000..e66269791d --- /dev/null +++ b/.agents/skills/convert-dot-shorthand/SKILL.md @@ -0,0 +1,48 @@ +--- +name: convert-dot-shorthand +description: Auto-converts standard enums and statics (like Colors.red, EdgeInsets.all) to Dart 3.10 dot shorthands. Use when updating Flutter code samples to modern syntax. +--- + +# Convert to Dot Shorthand + +Use this skill when you need to migrate an existing Flutter example or Dart file to use the new Dart 3.10 dot shorthand feature. + +This skill enforces a hybrid approach to ensure maximum safety and readability: a script first replaces all possible candidates, and then YOU (the AI) must manually evaluate each change using rules defined below. + +## Workflow Instructions + +1. **Execute the brute-force script:** + Run `scripts/apply_all.sh `. + This script will unconditionally search and replace all known safe classes (e.g., `Colors`, `EdgeInsets`, `Alignment`) with their dot shorthand equivalents. + +2. **Evaluate the Diff (The Human/AI check):** + Run `git diff` to view all changes the script just made. You must evaluate every single substitution against the [Readability Heuristics](#readability-heuristics) below. + +3. **Revert bad candidates:** + If a change is deemed "bad" based on the heuristics, you must manually undo that specific change (e.g., by checking out that line or manually re-typing the class name). + +4. **Generate a Concise Rejection Report:** + Before finishing, you must print a short terminal/agent output report to the user summarizing ONLY the items you rejected. Format it like this: + ``` + Reverted Changes Report: + example_file.dart:L42 - Kept `FontWeight.w600` + Reason: Numeric font weights lose context without the class name. + + example_file.dart:L80 - Kept `MainAxisSize.min` + Reason: The property name does not provide enough context for `.min`. + ``` + +5. **Finalize:** + Format the remaining code with `dart format `, run `dart analyze`, and run `flutter test` (if tests exist) to ensure the good shorthands don't break anything. + +## Readability Heuristics + +When evaluating a diff, ask yourself if the removed class name hurts readability. We are trying to find the heuristic balance. + +**Known "Good" Shorthands (Usually Keep):** +* `Colors.*` -> `.*` (It's almost always obvious a color is a color). +* `EdgeInsets.all` / `EdgeInsets.symmetric` -> `.all` / `.symmetric` (Context is extremely strong inside a `padding` or `margin` property). +* `Alignment.*` -> `.*` (Very clear inside an `alignment` property). + +**Known "Bad" Shorthands (Always Revert):** +* *Please document rules here as we discover them during manual evaluation.* diff --git a/.agents/skills/convert-dot-shorthand/scripts/apply_all.sh b/.agents/skills/convert-dot-shorthand/scripts/apply_all.sh new file mode 100755 index 0000000000..866eb61b26 --- /dev/null +++ b/.agents/skills/convert-dot-shorthand/scripts/apply_all.sh @@ -0,0 +1,35 @@ +#!/bin/bash +# scripts/apply_all.sh +# Unconditionally converts all potential Shorthands. +# It is the AI Agent's job to revert bad conversions using git diff. + +TARGET_DIR="$1" + +if [ -z "$TARGET_DIR" ]; then + echo "Usage: ./apply_all.sh " + exit 1 +fi + +echo "Applying overly-aggressive shorthands to $TARGET_DIR..." + +find "$TARGET_DIR" -type f -name "*.dart" -print0 | while IFS= read -r -d '' file; do + # Colors.black26 -> .black26 + sed -i -E 's/Colors\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # EdgeInsets.all(...) -> .all(...) + sed -i -E 's/EdgeInsets\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # BorderRadius.* -> .* + sed -i -E 's/BorderRadius\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # Alignment.* -> .* + sed -i -E 's/Alignment\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # MainAxisAlignment.* -> .* + sed -i -E 's/MainAxisAlignment\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # CrossAxisAlignment.* -> .* + sed -i -E 's/CrossAxisAlignment\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # BoxFit.* -> .* + sed -i -E 's/BoxFit\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # FontWeight.* -> .* + sed -i -E 's/FontWeight\.([a-zA-Z0-9_]+)/\.\1/g' "$file" + # Expanded -> No shorthand for widget types, but keeping here for future rules. +done + +echo "Done applying regex. PLEASE RUN 'dart format' and 'git diff' to review heuristics." diff --git a/temp_shorthand_skill_test_runs/data-and-backend_rejection_report.txt b/temp_shorthand_skill_test_runs/data-and-backend_rejection_report.txt new file mode 100644 index 0000000000..590b2e76ca --- /dev/null +++ b/temp_shorthand_skill_test_runs/data-and-backend_rejection_report.txt @@ -0,0 +1,3 @@ +REJECTED SHORTHANDS REPORT FOR: data-and-backend + +None. No shorthands were converted by the script (0 prefixes stripped) so no heuristics failed. diff --git a/temp_shorthand_skill_test_runs/get-started_rejection_report.txt b/temp_shorthand_skill_test_runs/get-started_rejection_report.txt new file mode 100644 index 0000000000..e3ee10cdc8 --- /dev/null +++ b/temp_shorthand_skill_test_runs/get-started_rejection_report.txt @@ -0,0 +1,13 @@ +REJECTED SHORTHANDS REPORT FOR: get-started + +flutter-for/react_native_devs/lib/examples.dart:L100 - Kept `FontWeight.w600` +Reason: Numeric font weights lose meaning without the class name prefix. + +flutter-for/web_devs/lib/main.dart:L424 - Kept `FontWeight.w900` +Reason: Numeric font weights lose meaning without the class name prefix. + +flutter-for/web_devs/lib/main.dart:L461 - Kept `FontWeight.w300` +Reason: Numeric font weights lose meaning without the class name prefix. + +All Colors.* shorthands (e.g. Colors.red, Colors.blue) - Reverted ~90 instances. +Reason: The Colors class does not have the same static members as Color, causing 'dot_shorthand_undefined_member' or resolving to deprecated instance getters. MUST REVERT to fix compilation. diff --git a/temp_shorthand_skill_test_runs/googleapis_rejection_report.txt b/temp_shorthand_skill_test_runs/googleapis_rejection_report.txt new file mode 100644 index 0000000000..391a34d8df --- /dev/null +++ b/temp_shorthand_skill_test_runs/googleapis_rejection_report.txt @@ -0,0 +1,4 @@ +REJECTED SHORTHANDS REPORT FOR: googleapis + +lib/main.dart:L120 - Kept `Colors.red` +Reason: The Colors class does not have the same static members as Color, causing 'dot_shorthand_undefined_member' or resolving to deprecated instance getters. MUST REVERT to fix compilation. diff --git a/temp_shorthand_skill_test_runs/state_mgmt_rejection_report.txt b/temp_shorthand_skill_test_runs/state_mgmt_rejection_report.txt new file mode 100644 index 0000000000..00242c6684 --- /dev/null +++ b/temp_shorthand_skill_test_runs/state_mgmt_rejection_report.txt @@ -0,0 +1,4 @@ +REJECTED SHORTHANDS REPORT FOR: state_mgmt + +simple/lib/src/performance.dart:L124 - Kept `Colors.yellow` +Reason: The Colors class does not have the same static members as Color, causing 'dot_shorthand_undefined_member' or resolving to deprecated instance getters. MUST REVERT to fix compilation. diff --git a/temp_shorthand_skill_test_runs/visual_debugging_rejection_report.txt b/temp_shorthand_skill_test_runs/visual_debugging_rejection_report.txt new file mode 100644 index 0000000000..5f4ea7e778 --- /dev/null +++ b/temp_shorthand_skill_test_runs/visual_debugging_rejection_report.txt @@ -0,0 +1,3 @@ +REJECTED SHORTHANDS REPORT FOR: visual_debugging + +None. No shorthands were converted by the script (0 prefixes stripped) so no heuristics failed.