Skip to content

Commit b2ec0d5

Browse files
authored
[infra] Agent skill: Apply dot shorthands (dart-lang#3164)
1 parent ae6ca24 commit b2ec0d5

1 file changed

Lines changed: 170 additions & 0 deletions

File tree

  • .agents/skills/refactor-dart-dot-shorthands
Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
name: refactor-dart-dot-shorthands
3+
description: Refactor Dart code to use modern language features, specifically dot shorthands (member access shorthands) introduced in Dart 3.7. Use this when you want to make code more concise by removing redundant type names in enum or static member access when the context type is known.
4+
---
5+
6+
# Refactor Dart Dot Shorthands
7+
8+
Apply Dart 3.7+ dot shorthands (member access shorthands) to simplify code where the context type is already known.
9+
10+
## Constraints
11+
12+
* **Single Package Focus**: Only apply changes to a single package in `pkgs/` at a time. Do not spread changes across multiple packages in a single operation.
13+
* **CI Usage**: Only run `dart tool/ci.dart --all --fast` if changes are made to packages that are part of the top-level pub workspace (as defined in the root `pubspec.yaml`). If the package is not in the workspace, use local validation (`dart analyze`, `dart test`) within that package's directory.
14+
* **No `.new` Shorthand**: Do not use `.new` as a shorthand for constructors (e.g., keep `MyClass()` or `MyClass.new()` if explicit, but do not refactor to just `.new()`).
15+
* **Immediate Clarity**: Only use dot shorthands if the type is immediately clear from the line itself (e.g., in a typed variable declaration, a switch on a variable with a clear type, or a collection with an explicit type argument). Do not use them if identifying the type requires scrolling or searching elsewhere in the file.
16+
* **No Explicit Typing for Shorthands**: DO NOT add explicit type arguments to collections (e.g., changing `const x = [...]` to `const x = <Type>[...]`) or explicit types to variables just to enable the use of dot shorthands. Shorthands should only be used where the context type is already explicitly defined in the existing code.
17+
* **Variable/Parameter Naming**: Only use shorthands if the variable or parameter name contains the type name (or a very clear abbreviation). Avoid renaming variables or parameters solely to enable shorthands, especially if they are part of a public API or used in many locations.
18+
* **Avoid Complex Contexts**: Avoid using shorthands in complex contexts where inference might be brittle, such as inside nested tuples in switch statements, unless the analysis tool confirms it's valid.
19+
* **Maintain Formatting**: When refactoring lists or collections, preserve the original formatting (e.g., multiline lists with trailing commas). Do not squash them into a single line.
20+
* **No Redundant Shorthands**: Do not use dot shorthands if the member is already accessible without any qualifier (e.g., inside the class where the static member is defined). Prefer `member` over `.member` if both work.
21+
* **Iterative Progress Tracking**: You MUST update `SHORTHAND_PROGRESS.md` after processing each file (or a small batch of no more than 3 files). This ensures progress is visible and prevents losing work if the session is interrupted. Do not wait until the end of the package to update the progress file.
22+
23+
## Workflow
24+
25+
1. **Select Target Package**: Choose a single package in `pkgs/` to refactor.
26+
2. **Initialize Progress**:
27+
* Recursively list all `.dart` files in the package.
28+
* Create a temporary markdown file (e.g., `SHORTHAND_PROGRESS.md`) containing a checklist of all files.
29+
3. **Iterative Refactoring**: Work through the files in small batches (1-3 files):
30+
* **Identify**: Search for shorthand opportunities within the files that meet the **Constraints**.
31+
* **Apply**: Replace `TypeName.memberName` with `.memberName`.
32+
* **Validate**: Run `dart analyze` on the affected files/package.
33+
* **Record**: Immediately update the checklist in `SHORTHAND_PROGRESS.md` to mark the processed files as completed. **Do not skip this step.**
34+
4. **Final Verification**:
35+
* Once all files are processed, perform the final validation step as described in the **Verification** section.
36+
5. **Cleanup**: Delete the temporary progress file.
37+
38+
## Examples
39+
40+
### Arguments and named parameter default values
41+
42+
```dart
43+
// Before
44+
super.language = Language.c,
45+
```
46+
47+
```dart
48+
// After
49+
super.language = .c,
50+
```
51+
52+
Only do the refactoring if the receiver or parameter name contains the type modulo spacing.
53+
54+
```dart
55+
// Before
56+
super(type: OutputType.library);
57+
```
58+
59+
```dart
60+
// After, bad. (Type not clear from 'type' parameter)
61+
super(type: .library);
62+
```
63+
64+
If not part of the public API, consider renaming the named parameter to match the type name.
65+
66+
```dart
67+
// After
68+
super(outputType: .library);
69+
```
70+
71+
However, only do this if the code quality doesn't suffer.
72+
73+
### Collections and Lists
74+
75+
Maintain multiline formatting for better readability.
76+
77+
```dart
78+
// Before
79+
const targets = [
80+
Architecture.arm,
81+
Architecture.arm64,
82+
Architecture.ia32,
83+
Architecture.x64,
84+
];
85+
```
86+
87+
```dart
88+
// After
89+
const targets = <Architecture>[
90+
.arm,
91+
.arm64,
92+
.ia32,
93+
.x64,
94+
];
95+
```
96+
97+
### Variable assignments and function calls
98+
99+
```dart
100+
// Before
101+
logger.level = Level.INFO;
102+
```
103+
104+
```dart
105+
// After
106+
logger.level = .INFO;
107+
```
108+
109+
If the type is contained in the name it is fine:
110+
111+
```dart
112+
// Before
113+
hostOS = hostOS ?? OS.current,
114+
```
115+
116+
```dart
117+
// After
118+
hostOS = hostOS ?? .current,
119+
```
120+
121+
Avoid shorthands if the context is lost:
122+
123+
```dart
124+
// Before
125+
await expectMachineArchitecture(libUri, target, OS.android);
126+
```
127+
128+
```dart
129+
// After, bad. (What is .android? Architecture? OS?)
130+
await expectMachineArchitecture(libUri, target, .android);
131+
```
132+
133+
### Equality checks
134+
135+
```dart
136+
// Before
137+
'/INCLUDE:${targetArch == Architecture.ia32 ? '_' : ''}$symbol'
138+
```
139+
140+
```dart
141+
// After, not great
142+
'/INCLUDE:${targetArch == .ia32 ? '_' : ''}$symbol'
143+
```
144+
145+
If variable names are not part of the public API, refactor variable name to match the type name.
146+
147+
```dart
148+
// After
149+
'/INCLUDE:${targetArchitecture == .ia32 ? '_' : ''}$symbol'
150+
```
151+
152+
However only do this if it keeps the code understandable.
153+
154+
**Note**: Shorthands are most effective for enums and static constants used as values.
155+
156+
## Verification
157+
158+
After applying changes, run the following in the package directory:
159+
```bash
160+
dart analyze
161+
```
162+
163+
If the package is part of the top-level workspace, run from the project root:
164+
```bash
165+
dart tool/ci.dart --all --fast
166+
```
167+
Otherwise, run tests locally in the package directory:
168+
```bash
169+
dart test
170+
```

0 commit comments

Comments
 (0)