flutter-pro-skills 0.0.0-stage → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (234) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE.md +26 -0
  3. package/README.ar.md +122 -0
  4. package/README.md +268 -2
  5. package/install.sh +86 -0
  6. package/package.json +39 -4
  7. package/skills/dart-flutter-best-practices/SKILL.md +242 -0
  8. package/skills/dart-flutter-best-practices/assets/AGENTS-snippet.md +24 -0
  9. package/skills/dart-flutter-best-practices/assets/analysis_options.yaml +86 -0
  10. package/skills/dart-flutter-best-practices/references/effective-dart.md +338 -0
  11. package/skills/dart-flutter-best-practices/scripts/format-dart-hook.sh +48 -0
  12. package/skills/dart-flutter-review/SKILL.md +342 -0
  13. package/skills/dart-flutter-review/references/ci.md +212 -0
  14. package/skills/dart-flutter-review/references/finding-format.md +238 -0
  15. package/skills/dart-flutter-review/references/review-guide.md +217 -0
  16. package/skills/dart-flutter-review/references/reviewer-prompts.md +1456 -0
  17. package/skills/dart-flutter-review/scripts/ci_action.sh +81 -0
  18. package/skills/dart-flutter-review/scripts/heuristics.py +1135 -0
  19. package/skills/dart-flutter-review/scripts/review.sh +440 -0
  20. package/skills/dart-naming/SKILL.md +208 -0
  21. package/skills/dart-naming/references/naming.md +522 -0
  22. package/skills/flutter-accessibility/SKILL.md +211 -0
  23. package/skills/flutter-accessibility/references/placement-by-architecture.md +185 -0
  24. package/skills/flutter-accessibility/references/review.md +92 -0
  25. package/skills/flutter-accessibility/references/rules.md +306 -0
  26. package/skills/flutter-accessibility/references/semantics-and-labels.md +187 -0
  27. package/skills/flutter-accessibility/references/testing-accessibility.md +152 -0
  28. package/skills/flutter-accessibility/references/visual-and-input.md +148 -0
  29. package/skills/flutter-accessibility/scripts/check_accessibility.py +1411 -0
  30. package/skills/flutter-adaptive-layout/SKILL.md +239 -0
  31. package/skills/flutter-adaptive-layout/references/input-and-platform.md +221 -0
  32. package/skills/flutter-adaptive-layout/references/placement-by-architecture.md +86 -0
  33. package/skills/flutter-adaptive-layout/references/review.md +98 -0
  34. package/skills/flutter-adaptive-layout/references/rules.md +502 -0
  35. package/skills/flutter-adaptive-layout/references/size-classes-and-layout.md +326 -0
  36. package/skills/flutter-adaptive-layout/references/testing-adaptive-layouts.md +158 -0
  37. package/skills/flutter-adaptive-layout/scripts/check_adaptive.py +1743 -0
  38. package/skills/flutter-architecture/SKILL.md +276 -0
  39. package/skills/flutter-architecture/references/anti-patterns/data-and-repositories.md +264 -0
  40. package/skills/flutter-architecture/references/anti-patterns/dependency-rule.md +314 -0
  41. package/skills/flutter-architecture/references/anti-patterns/di-and-globals.md +105 -0
  42. package/skills/flutter-architecture/references/anti-patterns/over-engineering.md +140 -0
  43. package/skills/flutter-architecture/references/anti-patterns/pattern-specific.md +473 -0
  44. package/skills/flutter-architecture/references/anti-patterns/presentation.md +411 -0
  45. package/skills/flutter-architecture/references/anti-patterns/state.md +348 -0
  46. package/skills/flutter-architecture/references/anti-patterns.md +195 -0
  47. package/skills/flutter-architecture/references/bloc.md +339 -0
  48. package/skills/flutter-architecture/references/clean-architecture.md +270 -0
  49. package/skills/flutter-architecture/references/detect.md +310 -0
  50. package/skills/flutter-architecture/references/mvc.md +249 -0
  51. package/skills/flutter-architecture/references/mvn.md +377 -0
  52. package/skills/flutter-architecture/references/mvvm.md +319 -0
  53. package/skills/flutter-architecture/references/repository-pattern.md +215 -0
  54. package/skills/flutter-architecture/references/state-management.md +190 -0
  55. package/skills/flutter-architecture/scripts/arch_check.py +2546 -0
  56. package/skills/flutter-design-system/SKILL.md +208 -0
  57. package/skills/flutter-design-system/references/components-and-placement.md +240 -0
  58. package/skills/flutter-design-system/references/review.md +92 -0
  59. package/skills/flutter-design-system/references/rules.md +438 -0
  60. package/skills/flutter-design-system/references/tokens-and-theming.md +338 -0
  61. package/skills/flutter-design-system/scripts/check_design_system.py +1517 -0
  62. package/skills/flutter-error-handling/SKILL.md +190 -0
  63. package/skills/flutter-error-handling/references/error-flow-by-architecture.md +646 -0
  64. package/skills/flutter-error-handling/references/global-handlers.md +246 -0
  65. package/skills/flutter-error-handling/references/result-vs-exceptions.md +302 -0
  66. package/skills/flutter-error-handling/references/review.md +85 -0
  67. package/skills/flutter-error-handling/references/rules.md +823 -0
  68. package/skills/flutter-error-handling/scripts/check_errors.py +2005 -0
  69. package/skills/flutter-feature-scaffold/SKILL.md +219 -0
  70. package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc.dart.tmpl +44 -0
  71. package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc_test.dart.tmpl +41 -0
  72. package/skills/flutter-feature-scaffold/assets/templates/bloc/event.dart.tmpl +19 -0
  73. package/skills/flutter-feature-scaffold/assets/templates/bloc/state.dart.tmpl +37 -0
  74. package/skills/flutter-feature-scaffold/assets/templates/bloc/view.dart.tmpl +55 -0
  75. package/skills/flutter-feature-scaffold/assets/templates/bloc/view_test.dart.tmpl +29 -0
  76. package/skills/flutter-feature-scaffold/assets/templates/clean/data_source.dart.tmpl +28 -0
  77. package/skills/flutter-feature-scaffold/assets/templates/clean/dto.dart.tmpl +24 -0
  78. package/skills/flutter-feature-scaffold/assets/templates/clean/entity.dart.tmpl +18 -0
  79. package/skills/flutter-feature-scaffold/assets/templates/clean/repository.dart.tmpl +6 -0
  80. package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl.dart.tmpl +26 -0
  81. package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl_test.dart.tmpl +60 -0
  82. package/skills/flutter-feature-scaffold/assets/templates/clean/usecase.dart.tmpl +13 -0
  83. package/skills/flutter-feature-scaffold/assets/templates/clean/usecase_test.dart.tmpl +21 -0
  84. package/skills/flutter-feature-scaffold/assets/templates/core/failure.dart.tmpl +24 -0
  85. package/skills/flutter-feature-scaffold/assets/templates/core/http_client.dart.tmpl +35 -0
  86. package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit.dart.tmpl +29 -0
  87. package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit_test.dart.tmpl +41 -0
  88. package/skills/flutter-feature-scaffold/assets/templates/cubit/view.dart.tmpl +52 -0
  89. package/skills/flutter-feature-scaffold/assets/templates/getx/api_client.dart.tmpl +21 -0
  90. package/skills/flutter-feature-scaffold/assets/templates/getx/binding.dart.tmpl +19 -0
  91. package/skills/flutter-feature-scaffold/assets/templates/getx/controller.dart.tmpl +34 -0
  92. package/skills/flutter-feature-scaffold/assets/templates/getx/controller_test.dart.tmpl +42 -0
  93. package/skills/flutter-feature-scaffold/assets/templates/getx/state.dart.tmpl +31 -0
  94. package/skills/flutter-feature-scaffold/assets/templates/getx/view.dart.tmpl +38 -0
  95. package/skills/flutter-feature-scaffold/assets/templates/mvn/entity.dart.tmpl +9 -0
  96. package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier.dart.tmpl +25 -0
  97. package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier_test.dart.tmpl +56 -0
  98. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository.dart.tmpl +5 -0
  99. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl.dart.tmpl +32 -0
  100. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl_test.dart.tmpl +58 -0
  101. package/skills/flutter-feature-scaffold/assets/templates/mvn/request.dart.tmpl +10 -0
  102. package/skills/flutter-feature-scaffold/assets/templates/mvn/response.dart.tmpl +20 -0
  103. package/skills/flutter-feature-scaffold/assets/templates/mvn/source.dart.tmpl +32 -0
  104. package/skills/flutter-feature-scaffold/assets/templates/mvn/state.dart.tmpl +28 -0
  105. package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase.dart.tmpl +19 -0
  106. package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase_test.dart.tmpl +21 -0
  107. package/skills/flutter-feature-scaffold/assets/templates/mvn/view.dart.tmpl +52 -0
  108. package/skills/flutter-feature-scaffold/assets/templates/mvn/view_test.dart.tmpl +34 -0
  109. package/skills/flutter-feature-scaffold/assets/templates/mvn/widget.dart.tmpl +19 -0
  110. package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_client.dart.tmpl +31 -0
  111. package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_model.dart.tmpl +20 -0
  112. package/skills/flutter-feature-scaffold/assets/templates/mvvm/command.dart.tmpl +66 -0
  113. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository.dart.tmpl +7 -0
  114. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl.dart.tmpl +23 -0
  115. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl_test.dart.tmpl +54 -0
  116. package/skills/flutter-feature-scaffold/assets/templates/mvvm/result.dart.tmpl +33 -0
  117. package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase.dart.tmpl +15 -0
  118. package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase_test.dart.tmpl +22 -0
  119. package/skills/flutter-feature-scaffold/assets/templates/mvvm/view.dart.tmpl +47 -0
  120. package/skills/flutter-feature-scaffold/assets/templates/mvvm/view_test.dart.tmpl +27 -0
  121. package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel.dart.tmpl +32 -0
  122. package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel_test.dart.tmpl +64 -0
  123. package/skills/flutter-feature-scaffold/assets/templates/provider/notifier.dart.tmpl +41 -0
  124. package/skills/flutter-feature-scaffold/assets/templates/provider/notifier_test.dart.tmpl +44 -0
  125. package/skills/flutter-feature-scaffold/assets/templates/provider/state.dart.tmpl +31 -0
  126. package/skills/flutter-feature-scaffold/assets/templates/provider/view.dart.tmpl +39 -0
  127. package/skills/flutter-feature-scaffold/assets/templates/provider/view_test.dart.tmpl +30 -0
  128. package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier.dart.tmpl +23 -0
  129. package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier_test.dart.tmpl +55 -0
  130. package/skills/flutter-feature-scaffold/assets/templates/riverpod/providers.dart.tmpl +24 -0
  131. package/skills/flutter-feature-scaffold/assets/templates/riverpod/view.dart.tmpl +45 -0
  132. package/skills/flutter-feature-scaffold/assets/templates/riverpod/view_test.dart.tmpl +31 -0
  133. package/skills/flutter-feature-scaffold/assets/templates/shared/list.dart.tmpl +21 -0
  134. package/skills/flutter-feature-scaffold/assets/templates/shared/model.dart.tmpl +27 -0
  135. package/skills/flutter-feature-scaffold/assets/templates/shared/repository.dart.tmpl +6 -0
  136. package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl.dart.tmpl +25 -0
  137. package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl_test.dart.tmpl +59 -0
  138. package/skills/flutter-feature-scaffold/assets/templates/shared/source.dart.tmpl +28 -0
  139. package/skills/flutter-feature-scaffold/references/profiles.md +145 -0
  140. package/skills/flutter-feature-scaffold/scripts/scaffold.py +1069 -0
  141. package/skills/flutter-firebase/SKILL.md +256 -0
  142. package/skills/flutter-firebase/references/firestore-data.md +178 -0
  143. package/skills/flutter-firebase/references/placement-by-architecture.md +309 -0
  144. package/skills/flutter-firebase/references/review.md +109 -0
  145. package/skills/flutter-firebase/references/rules.md +636 -0
  146. package/skills/flutter-firebase/references/security-rules-and-app-check.md +226 -0
  147. package/skills/flutter-firebase/references/setup-messaging-config.md +169 -0
  148. package/skills/flutter-firebase/references/testing-firebase.md +157 -0
  149. package/skills/flutter-firebase/scripts/check_firebase.py +2155 -0
  150. package/skills/flutter-forms/SKILL.md +191 -0
  151. package/skills/flutter-forms/references/multi-step-and-dirty-state.md +190 -0
  152. package/skills/flutter-forms/references/placement-by-architecture.md +326 -0
  153. package/skills/flutter-forms/references/review.md +88 -0
  154. package/skills/flutter-forms/references/rules.md +238 -0
  155. package/skills/flutter-forms/references/secure-inputs.md +256 -0
  156. package/skills/flutter-forms/references/validation-patterns.md +285 -0
  157. package/skills/flutter-forms/scripts/check_forms.py +1278 -0
  158. package/skills/flutter-i18n/SKILL.md +241 -0
  159. package/skills/flutter-i18n/references/formatting.md +174 -0
  160. package/skills/flutter-i18n/references/gen-l10n-and-arb.md +315 -0
  161. package/skills/flutter-i18n/references/placement-by-architecture.md +460 -0
  162. package/skills/flutter-i18n/references/review.md +93 -0
  163. package/skills/flutter-i18n/references/rtl-and-arabic.md +367 -0
  164. package/skills/flutter-i18n/scripts/check_i18n.py +1805 -0
  165. package/skills/flutter-navigation/SKILL.md +199 -0
  166. package/skills/flutter-navigation/references/deep-links-and-security.md +242 -0
  167. package/skills/flutter-navigation/references/go-router-patterns.md +361 -0
  168. package/skills/flutter-navigation/references/placement-by-architecture.md +414 -0
  169. package/skills/flutter-navigation/references/review.md +102 -0
  170. package/skills/flutter-navigation/references/rules.md +256 -0
  171. package/skills/flutter-navigation/scripts/check_navigation.py +1424 -0
  172. package/skills/flutter-networking/SKILL.md +202 -0
  173. package/skills/flutter-networking/references/client-setup.md +180 -0
  174. package/skills/flutter-networking/references/dtos-and-json.md +114 -0
  175. package/skills/flutter-networking/references/placement-by-architecture.md +147 -0
  176. package/skills/flutter-networking/references/requests.md +160 -0
  177. package/skills/flutter-networking/references/review.md +94 -0
  178. package/skills/flutter-networking/references/rules.md +487 -0
  179. package/skills/flutter-networking/references/testing-with-fakes.md +137 -0
  180. package/skills/flutter-networking/scripts/check_networking.py +1607 -0
  181. package/skills/flutter-performance/SKILL.md +219 -0
  182. package/skills/flutter-performance/references/diagnosing-jank.md +134 -0
  183. package/skills/flutter-performance/references/isolates.md +105 -0
  184. package/skills/flutter-performance/references/lists-images-painting.md +116 -0
  185. package/skills/flutter-performance/references/rebuild-scope.md +154 -0
  186. package/skills/flutter-performance/references/review.md +93 -0
  187. package/skills/flutter-performance/references/rules.md +400 -0
  188. package/skills/flutter-performance/scripts/check_performance.py +1360 -0
  189. package/skills/flutter-persistence/SKILL.md +198 -0
  190. package/skills/flutter-persistence/references/caching-and-offline.md +169 -0
  191. package/skills/flutter-persistence/references/choosing-storage.md +188 -0
  192. package/skills/flutter-persistence/references/migrations.md +201 -0
  193. package/skills/flutter-persistence/references/placement-by-architecture.md +232 -0
  194. package/skills/flutter-persistence/references/review.md +93 -0
  195. package/skills/flutter-persistence/references/rules.md +405 -0
  196. package/skills/flutter-persistence/scripts/check_persistence.py +1690 -0
  197. package/skills/flutter-platform-integration/SKILL.md +219 -0
  198. package/skills/flutter-platform-integration/references/channels-and-pigeon.md +194 -0
  199. package/skills/flutter-platform-integration/references/ffi.md +147 -0
  200. package/skills/flutter-platform-integration/references/permissions-and-isolates.md +124 -0
  201. package/skills/flutter-platform-integration/references/placement-by-architecture.md +102 -0
  202. package/skills/flutter-platform-integration/references/plugins-and-platform-views.md +129 -0
  203. package/skills/flutter-platform-integration/references/review.md +94 -0
  204. package/skills/flutter-platform-integration/references/rules.md +557 -0
  205. package/skills/flutter-platform-integration/references/testing-platform-code.md +125 -0
  206. package/skills/flutter-platform-integration/scripts/check_platform.py +1824 -0
  207. package/skills/flutter-release/SKILL.md +219 -0
  208. package/skills/flutter-release/references/ci-cd.md +156 -0
  209. package/skills/flutter-release/references/flavors-and-environments.md +127 -0
  210. package/skills/flutter-release/references/release-checklist.md +79 -0
  211. package/skills/flutter-release/references/review.md +91 -0
  212. package/skills/flutter-release/references/rules.md +417 -0
  213. package/skills/flutter-release/references/signing-and-versioning.md +113 -0
  214. package/skills/flutter-release/references/store-requirements.md +61 -0
  215. package/skills/flutter-release/scripts/check_release.py +1930 -0
  216. package/skills/flutter-secure-defaults/SKILL.md +270 -0
  217. package/skills/flutter-secure-defaults/references/network-and-auth.md +203 -0
  218. package/skills/flutter-secure-defaults/references/review.md +103 -0
  219. package/skills/flutter-secure-defaults/references/rules.md +452 -0
  220. package/skills/flutter-secure-defaults/references/secrets-and-config.md +136 -0
  221. package/skills/flutter-secure-defaults/references/secure-defaults-by-layer.md +474 -0
  222. package/skills/flutter-secure-defaults/references/secure-scaffold-checklist.md +147 -0
  223. package/skills/flutter-secure-defaults/references/storage-and-privacy.md +161 -0
  224. package/skills/flutter-secure-defaults/references/webview-and-links.md +153 -0
  225. package/skills/flutter-secure-defaults/scripts/check_secure_defaults.py +1571 -0
  226. package/skills/flutter-testing/SKILL.md +197 -0
  227. package/skills/flutter-testing/references/review.md +71 -0
  228. package/skills/flutter-testing/references/strategy-by-architecture.md +491 -0
  229. package/skills/flutter-testing/references/test-smells.md +475 -0
  230. package/skills/flutter-testing/references/widget-and-golden.md +337 -0
  231. package/skills/flutter-testing/scripts/test_gaps.py +1268 -0
  232. package/skills/flutter-ui-practices/SKILL.md +158 -0
  233. package/skills/flutter-ui-practices/references/flutter-ui.md +282 -0
  234. package/skills/flutter-ui-practices/references/review.md +89 -0
@@ -0,0 +1,338 @@
1
+ # Effective Dart — complete guideline checklist
2
+
3
+ Generated from the source of https://dart.dev/effective-dart (dart-lang/site-www,
4
+ `src/content/effective-dart/*.md`), 149 guidelines. Every heading is verbatim.
5
+
6
+ **Enforced by** column:
7
+ - `lint_name` (set) — the analyzer rule that checks it, and where it's on by default:
8
+ `core` / `recommended` (package:lints), `flutter` (package:flutter_lints, which
9
+ includes recommended), or `opt-in` (must be enabled in `analysis_options.yaml`;
10
+ `assets/analysis_options.yaml` enables the useful ones).
11
+ - **judgment** — no lint; you have to read the code. 76 of 149 guidelines.
12
+ These are where an agent adds value over `dart analyze`, so check them deliberately.
13
+
14
+ Strength: **DO/DON'T** ≈ always · **PREFER/AVOID** = unless good reason ·
15
+ **CONSIDER** = context-dependent. Report findings at the strength of the rule.
16
+
17
+ Overarching themes: **be consistent** (code that looks different should *be*
18
+ different) and **be brief** (economical, not dense).
19
+
20
+ ## Contents
21
+
22
+ - Style
23
+ - Identifiers
24
+ - Ordering
25
+ - Formatting
26
+ - Documentation
27
+ - Comments
28
+ - Doc comments
29
+ - Markdown
30
+ - Writing
31
+ - Usage
32
+ - Libraries
33
+ - Null
34
+ - Strings
35
+ - Collections
36
+ - Functions
37
+ - Variables
38
+ - Members
39
+ - Constructors
40
+ - Error handling
41
+ - Asynchrony
42
+ - Design
43
+ - Names
44
+ - Libraries
45
+ - Classes and mixins
46
+ - Constructors
47
+ - Members
48
+ - Types
49
+ - Parameters
50
+ - Equality
51
+
52
+ Grep for a keyword (`late`, `FutureOr`, `catch`, `getter`) instead of reading every row.
53
+
54
+ ## Style
55
+
56
+
57
+ ### Identifiers
58
+
59
+ | Guideline | Enforced by | Note |
60
+ |---|---|---|
61
+ | DO name types using `UpperCamelCase` | `camel_case_types` (core) | |
62
+ | DO name extensions using `UpperCamelCase` | `camel_case_extensions` (core) | |
63
+ | DO name packages, directories, and source files using `lowercase_with_underscores` | `file_names` (core), `package_names` (recommended) | |
64
+ | DO name import prefixes using `lowercase_with_underscores` | `library_prefixes` (recommended) | |
65
+ | DO name other identifiers using `lowerCamelCase` | `non_constant_identifier_names` (core) | |
66
+ | PREFER using `lowerCamelCase` for constant names | `constant_identifier_names` (recommended) | |
67
+ | DO capitalize acronyms and abbreviations longer than two letters like words | **judgment** | |
68
+ | PREFER using wildcards for unused callback parameters | `unnecessary_underscores` (recommended) | |
69
+ | DON'T use a leading underscore for identifiers that aren't private | `no_leading_underscores_for_local_identifiers` (recommended) | |
70
+ | DON'T use prefix letters | **judgment** | |
71
+ | DON'T explicitly name libraries | `unnecessary_library_name` (recommended) | `library;` or nothing. |
72
+
73
+ ### Ordering
74
+
75
+ | Guideline | Enforced by | Note |
76
+ |---|---|---|
77
+ | DO place `dart:` imports before other imports | `directives_ordering` (opt-in) | |
78
+ | DO place `package:` imports before relative imports | `directives_ordering` (opt-in) | |
79
+ | DO specify exports in a separate section after all imports | `directives_ordering` (opt-in) | |
80
+ | DO sort sections alphabetically | `directives_ordering` (opt-in) | |
81
+
82
+ ### Formatting
83
+
84
+ | Guideline | Enforced by | Note |
85
+ |---|---|---|
86
+ | DO format your code using `dart format` | **judgment** | |
87
+ | CONSIDER changing your code to make it more formatter-friendly | **judgment** | Long expressions/nested closures the formatter can't lay out well are a signal to extract a variable or function. |
88
+ | PREFER lines 80 characters or fewer | `lines_longer_than_80_chars` (opt-in) | |
89
+ | DO use curly braces for all flow control statements | `curly_braces_in_flow_control_structures` (core) | |
90
+
91
+ ## Documentation
92
+
93
+
94
+ ### Comments
95
+
96
+ | Guideline | Enforced by | Note |
97
+ |---|---|---|
98
+ | DO format comments like sentences | **judgment** | Capitalised, ends with a period (unless it's an identifier or a fragment like `// TODO`). |
99
+ | DON'T use block comments for documentation | **judgment** | Use `//` / `///`; `/* */` only to comment out code temporarily. |
100
+
101
+ ### Doc comments
102
+
103
+ | Guideline | Enforced by | Note |
104
+ |---|---|---|
105
+ | DO use `///` doc comments to document members and types | `slash_for_doc_comments` (recommended) | |
106
+ | PREFER writing doc comments for public APIs | `public_member_api_docs` (opt-in) | |
107
+ | CONSIDER writing a library-level doc comment | **judgment** | `///` before `library;` at the top of the library entry file. |
108
+ | CONSIDER writing doc comments for private APIs | **judgment** | |
109
+ | DO start doc comments with a single-sentence summary | **judgment** | First sentence is the summary dartdoc shows in lists; make it stand alone. |
110
+ | DO separate the first sentence of a doc comment into its own paragraph | **judgment** | Blank `///` line after the summary. |
111
+ | AVOID redundancy with the surrounding context | **judgment** | Don't restate the class name, param types, or what the signature already says. |
112
+ | PREFER starting comments of a function or method with third-person verbs if its main purpose is a side effect | **judgment** | `/// Connects to the server…`, `/// Starts the stopwatch…` |
113
+ | PREFER starting a non-boolean variable or property comment with a noun phrase | **judgment** | `/// The current day of the week…` |
114
+ | PREFER starting a boolean variable or property comment with "Whether" followed by a noun or gerund phrase | **judgment** | `/// Whether the modal is currently displayed…` (not "Returns true if"). |
115
+ | PREFER a noun phrase or non-imperative verb phrase for a function or method if returning a value is its primary purpose | **judgment** | Docs: `/// The [index]th element…` / `/// Returns the…` is also accepted. |
116
+ | DON'T write documentation for both the getter and setter of a property | **judgment** | Doc the getter only; dartdoc merges them. |
117
+ | PREFER starting library or type comments with noun phrases | **judgment** | `/// A chunk of non-breaking output text…` |
118
+ | CONSIDER including code samples in doc comments | **judgment** | Fenced ```dart``` blocks. |
119
+ | DO use square brackets in doc comments to refer to in-scope identifiers | `comment_references` (opt-in) | |
120
+ | DO use prose to explain parameters, return values, and exceptions | **judgment** | No `@param`/`@returns` Javadoc tags; weave `[param]` references into sentences. |
121
+ | DO put doc comments before metadata annotations | **judgment** | `/// Doc` then `@override`/`@Deprecated`, not the reverse. |
122
+
123
+ ### Markdown
124
+
125
+ | Guideline | Enforced by | Note |
126
+ |---|---|---|
127
+ | AVOID using markdown excessively | **judgment** | |
128
+ | AVOID using HTML for formatting | `unintended_html_in_doc_comment` (core) | `unintended_html_in_doc_comment` (core) catches accidental `<T>` in prose — wrap in backticks. |
129
+ | PREFER backtick fences for code blocks | **judgment** | Not 4-space indented blocks. |
130
+
131
+ ### Writing
132
+
133
+ | Guideline | Enforced by | Note |
134
+ |---|---|---|
135
+ | PREFER brevity | **judgment** | |
136
+ | AVOID abbreviations and acronyms unless they are obvious | **judgment** | |
137
+ | PREFER using "this" instead of "the" to refer to a member's instance | **judgment** | `/// True if this box has no contents.` |
138
+
139
+ ## Usage
140
+
141
+
142
+ ### Libraries
143
+
144
+ | Guideline | Enforced by | Note |
145
+ |---|---|---|
146
+ | DO use strings in `part of` directives | `use_string_in_part_of_directives` (core) | |
147
+ | DON'T import libraries that are inside the `src` directory of another package | `implementation_imports` (recommended) | |
148
+ | DON'T allow an import path to reach into or out of `lib` | `avoid_relative_lib_imports` (core) | |
149
+ | PREFER relative import paths | `prefer_relative_imports` (opt-in) | |
150
+
151
+ ### Null
152
+
153
+ | Guideline | Enforced by | Note |
154
+ |---|---|---|
155
+ | DON'T explicitly initialize variables to `null` | `avoid_init_to_null` (recommended) | |
156
+ | DON'T use an explicit default value of `null` | `avoid_init_to_null` (recommended) | |
157
+ | DON'T use `true` or `false` in equality operations | **judgment** | `if (nonNullable)` not `== true`. For nullable bools `== true` / `?? false` is fine. |
158
+ | AVOID `late` variables if you need to check whether they are initialized | **judgment** | There's no way to ask a `late` field whether it's set; use a nullable field instead. |
159
+ | CONSIDER type promotion or null-check patterns for using nullable types | **judgment** | Copy a nullable field to a local (`final user = _user; if (user != null)…`) or use `if (_user case final user?)`. Avoid scattering `!`. |
160
+
161
+ ### Strings
162
+
163
+ | Guideline | Enforced by | Note |
164
+ |---|---|---|
165
+ | DO use adjacent strings to concatenate string literals | `prefer_adjacent_string_concatenation` (recommended) | |
166
+ | PREFER using interpolation to compose strings and values | `prefer_interpolation_to_compose_strings` (recommended) | |
167
+ | AVOID using curly braces in interpolation when not needed | `unnecessary_brace_in_string_interps` (recommended) | |
168
+
169
+ ### Collections
170
+
171
+ | Guideline | Enforced by | Note |
172
+ |---|---|---|
173
+ | DO use collection literals when possible | `prefer_collection_literals` (recommended) | |
174
+ | DON'T use `.length` to see if a collection is empty | `prefer_is_empty` (core), `prefer_is_not_empty` (core) | |
175
+ | AVOID using `Iterable.forEach()` with a function literal | `avoid_function_literals_in_foreach_calls` (recommended) | |
176
+ | DON'T use `List.from()` unless you intend to change the type of the result | **judgment** | Use `.toList()` / `[...x]`; `List<int>.from(numbers)` only to downcast. |
177
+ | DO use `whereType()` to filter a collection by type | `prefer_iterable_whereType` (core) | |
178
+ | DON'T use `cast()` when a nearby operation will do | **judgment** | e.g. `List<int>.from(x)` / `map<int>()` / `whereType<int>()`. |
179
+ | AVOID using `cast()` | **judgment** | Create the collection with the right type, or cast each element on access. |
180
+
181
+ ### Functions
182
+
183
+ | Guideline | Enforced by | Note |
184
+ |---|---|---|
185
+ | DO use a function declaration to bind a function to a name | `prefer_function_declarations_over_variables` (recommended) | |
186
+ | DON'T create a lambda when a tear-off will do | `unnecessary_lambdas` (opt-in) | |
187
+
188
+ ### Variables
189
+
190
+ | Guideline | Enforced by | Note |
191
+ |---|---|---|
192
+ | DO follow a consistent rule for `var` and `final` on local variables | `prefer_final_locals` (opt-in) | Either `final` for non-reassigned + `var` for reassigned, or `var` everywhere. Match the project. (`prefer_final_locals` enforces the first.) |
193
+ | AVOID storing what you can calculate | **judgment** | Compute in a getter instead of a field you must keep in sync (cache only when measured). |
194
+
195
+ ### Members
196
+
197
+ | Guideline | Enforced by | Note |
198
+ |---|---|---|
199
+ | DON'T wrap a field in a getter and setter unnecessarily | `unnecessary_getters_setters` (recommended) | |
200
+ | PREFER using a `final` field to make a read-only property | **judgment** | `final` public field, not private field + getter. |
201
+ | CONSIDER using `=>` for simple members | `prefer_expression_function_bodies` (opt-in) | |
202
+ | DON'T use `this.` except to redirect to a named constructor or to avoid shadowing | `unnecessary_this` (recommended) | |
203
+ | DO initialize fields at their declaration when possible | **judgment** | When the value doesn't depend on constructor params. |
204
+
205
+ ### Constructors
206
+
207
+ | Guideline | Enforced by | Note |
208
+ |---|---|---|
209
+ | DO use initializing formals when possible | `prefer_initializing_formals` (recommended) | |
210
+ | DON'T use `late` when a constructor initializer list will do | **judgment** | |
211
+ | DO use `;` instead of `{}` for empty constructor bodies | `empty_constructor_bodies` (recommended) | |
212
+ | PREFER using concise constructor syntax | `unnecessary_type_name_in_constructor` (opt-in) | |
213
+ | DON'T use `new` | `unnecessary_new` (recommended) | |
214
+ | DON'T use `const` redundantly | `unnecessary_const` (recommended) | |
215
+
216
+ ### Error handling
217
+
218
+ | Guideline | Enforced by | Note |
219
+ |---|---|---|
220
+ | AVOID catches without `on` clauses | `avoid_catches_without_on_clauses` (opt-in) | |
221
+ | DON'T discard errors from catches without `on` clauses | **judgment** | If you catch everything, log/report/rethrow — never silently drop. |
222
+ | DO throw objects that implement `Error` only for programmatic errors | `only_throw_errors` (opt-in) | `ArgumentError`, `StateError` = caller bug. Runtime/IO failures → `Exception` (`only_throw_errors` stops throwing strings). |
223
+ | DON'T explicitly catch `Error` or types that implement it | `avoid_catching_errors` (opt-in) | |
224
+ | DO use `rethrow` to rethrow a caught exception | `use_rethrow_when_possible` (recommended) | |
225
+
226
+ ### Asynchrony
227
+
228
+ | Guideline | Enforced by | Note |
229
+ |---|---|---|
230
+ | PREFER async/await over using raw futures | **judgment** | Linear code; `try/catch` works; easier to read. |
231
+ | DON'T use `async` when it has no useful effect | **judgment** | A function that just returns another future doesn't need `async`. Keep it when you `await`, need errors as futures, or return `Future<void>` from sync work. |
232
+ | CONSIDER using higher-order methods to transform a stream | **judgment** | `map`, `where`, `asyncMap`, `expand` before reaching for a StreamController. |
233
+ | AVOID using Completer directly | **judgment** | Only to wrap callback-based APIs; otherwise `async`/`then`. |
234
+ | DO test for `Future<T>` when disambiguating a `FutureOr<T>` whose type argument could be `Object` | **judgment** | `if (value is Future<T>)` first, else `T` — testing `is T` first is wrong when T is Object. |
235
+
236
+ ## Design
237
+
238
+
239
+ ### Names
240
+
241
+ | Guideline | Enforced by | Note |
242
+ |---|---|---|
243
+ | DO use terms consistently | **judgment** | See naming.md §3. |
244
+ | AVOID abbreviations | **judgment** | See naming.md §3. |
245
+ | PREFER putting the most descriptive noun last | **judgment** | `pageCount` not `numPages`. |
246
+ | CONSIDER making the code read like a sentence | **judgment** | |
247
+ | PREFER a noun phrase for a non-boolean property or variable | **judgment** | |
248
+ | PREFER a non-imperative verb phrase for a boolean property or variable | **judgment** | `isEnabled`, `hasElements`, `canClose`. |
249
+ | CONSIDER omitting the verb for a named boolean *parameter* | **judgment** | `growable: true`, `enabled: false`. |
250
+ | PREFER the "positive" name for a boolean property or variable | **judgment** | `isConnected` over `isDisconnected`. |
251
+ | PREFER an imperative verb phrase for a function or method whose main purpose is a side effect | **judgment** | |
252
+ | PREFER a noun phrase or non-imperative verb phrase for a function or method if returning a value is its primary purpose | **judgment** | Docs: `/// The [index]th element…` / `/// Returns the…` is also accepted. |
253
+ | CONSIDER an imperative verb phrase for a function or method if you want to draw attention to the work it performs | **judgment** | `fetchUser()`, `downloadData()`. |
254
+ | AVOID starting a function or method name with `get` | **judgment** | Getter if cheap; otherwise name the work (`fetch`, `calculate`, `load`). |
255
+ | PREFER naming a method `to___()` if it copies the object's state to a new object | `use_to_and_as_if_applicable` (opt-in) | |
256
+ | PREFER naming a method `as___()` if it returns a different representation backed by the original object | `use_to_and_as_if_applicable` (opt-in) | |
257
+ | AVOID describing the parameters in the function's or method's name | **judgment** | `list.add(element)` not `addElement`. |
258
+ | DO follow existing mnemonic conventions when naming type parameters | **judgment** | `E`, `K`/`V`, `R`, `T`/`S`/`U`. |
259
+
260
+ ### Libraries
261
+
262
+ | Guideline | Enforced by | Note |
263
+ |---|---|---|
264
+ | PREFER making declarations private | **judgment** | Public = maintained forever; start private, widen when needed. |
265
+ | CONSIDER declaring multiple classes in the same library | **judgment** | Dart privacy is per-library; small cooperating classes may share a file. |
266
+
267
+ ### Classes and mixins
268
+
269
+ | Guideline | Enforced by | Note |
270
+ |---|---|---|
271
+ | AVOID defining a one-member abstract class when a simple function will do | `one_member_abstracts` (opt-in, deprecated) | |
272
+ | AVOID defining a class that contains only static members | `avoid_classes_with_only_static_members` (opt-in) | |
273
+ | AVOID extending a class that isn't intended to be subclassed | **judgment** | |
274
+ | DO use class modifiers to control if your class can be extended | **judgment** | `final`, `base`, `interface`, `sealed`; document intent. |
275
+ | AVOID implementing a class that isn't intended to be an interface | **judgment** | |
276
+ | DO use class modifiers to control if your class can be an interface | **judgment** | |
277
+ | PREFER defining a pure `mixin` or pure `class` to a `mixin class` | `prefer_mixin` (opt-in) | |
278
+
279
+ ### Constructors
280
+
281
+ | Guideline | Enforced by | Note |
282
+ |---|---|---|
283
+ | CONSIDER making your constructor `const` if the class supports it | **judgment** | All fields final + no body logic. Note: making it const is a public promise you can't easily take back. |
284
+
285
+ ### Members
286
+
287
+ | Guideline | Enforced by | Note |
288
+ |---|---|---|
289
+ | PREFER making fields and top-level variables `final` | `prefer_final_fields` (recommended) | |
290
+ | DO use getters for operations that conceptually access properties | **judgment** | No args, returns result, no visible side effects, idempotent, fast. |
291
+ | DO use setters for operations that conceptually change properties | `use_setters_to_change_properties` (opt-in) | |
292
+ | DON'T define a setter without a corresponding getter | `avoid_setters_without_getters` (opt-in) | |
293
+ | AVOID using runtime type tests to fake overloading | **judgment** | Separate named methods instead of `if (x is A) … else if (x is B)`. (Exhaustive `switch` on a `sealed` type is fine.) |
294
+ | AVOID public `late final` fields without initializers | **judgment** | They expose an implicit setter that throws on second write. |
295
+ | AVOID returning nullable `Future`, `Stream`, and collection types | **judgment** | Return empty collection / completed future instead of `null`. |
296
+ | AVOID returning `this` from methods just to enable a fluent interface | `avoid_returning_this` (opt-in) | Dart has cascades `..`. |
297
+
298
+ ### Types
299
+
300
+ | Guideline | Enforced by | Note |
301
+ |---|---|---|
302
+ | DO type annotate variables without initializers | `prefer_typing_uninitialized_variables` (core) | |
303
+ | DO type annotate fields and top-level variables if the type isn't obvious | `type_annotate_public_apis` (opt-in) | |
304
+ | DON'T redundantly type annotate initialized local variables | `omit_local_variable_types` (opt-in) | |
305
+ | DO annotate return types on function declarations | `always_declare_return_types` (opt-in) | (`always_declare_return_types`) |
306
+ | DO annotate parameter types on function declarations | **judgment** | |
307
+ | DON'T annotate inferred parameter types on function expressions | `avoid_types_on_closure_parameters` (opt-in) | |
308
+ | DON'T type annotate initializing formals | `type_init_formals` (recommended) | |
309
+ | DO write type arguments on generic invocations that aren't inferred | **judgment** | `<int>[]`, `Future<String>.value(...)` when context doesn't infer. |
310
+ | DON'T write type arguments on generic invocations that are inferred | **judgment** | |
311
+ | AVOID writing incomplete generic types | **judgment** | `List<num>` not raw `List` (→ `List<dynamic>`). |
312
+ | DO annotate with `dynamic` instead of letting inference fail | `strict_top_level_inference` (core) | Make the intent explicit; `strict_top_level_inference` (core) catches top-level cases. |
313
+ | PREFER signatures in function type annotations | **judgment** | `bool Function(Item)` not bare `Function`. |
314
+ | DON'T specify a return type for a setter | `avoid_return_types_on_setters` (recommended) | |
315
+ | DON'T use the legacy typedef syntax | `prefer_generic_function_type_aliases` (core) | |
316
+ | PREFER inline function types over typedefs | `avoid_private_typedef_functions` (opt-in, deprecated) | |
317
+ | PREFER using function type syntax for parameters | `use_function_type_syntax_for_parameters` (recommended) | |
318
+ | AVOID using `dynamic` unless you want to disable static checking | `avoid_dynamic_calls` (opt-in) | Use `Object?` for 'any value'. (`avoid_dynamic_calls` catches calls through dynamic.) |
319
+ | DO use `Future<void>` as the return type of asynchronous members that do not produce values | `avoid_void_async` (opt-in) | Not `void` (`avoid_void_async`) and not `Future` raw. |
320
+ | AVOID using `FutureOr<T>` as a return type | **judgment** | Return `Future<T>` — callers then always `await`. `FutureOr` is for parameters. |
321
+
322
+ ### Parameters
323
+
324
+ | Guideline | Enforced by | Note |
325
+ |---|---|---|
326
+ | AVOID positional boolean parameters | `avoid_positional_boolean_parameters` (opt-in) | |
327
+ | AVOID optional positional parameters if the user may want to omit earlier parameters | **judgment** | Use named params. |
328
+ | AVOID mandatory parameters that accept a special "no argument" value | **judgment** | Make it optional / nullable named instead of passing `-1` or `null` to mean 'none'. |
329
+ | DO use inclusive start and exclusive end parameters to accept a range | **judgment** | Like `substring(start, end)`. |
330
+
331
+ ### Equality
332
+
333
+ | Guideline | Enforced by | Note |
334
+ |---|---|---|
335
+ | DO override `hashCode` if you override `==` | `hash_and_equals` (core) | |
336
+ | DO make your `==` operator obey the mathematical rules of equality | **judgment** | Reflexive, symmetric, transitive, consistent; and `hashCode` agrees. |
337
+ | AVOID defining custom equality for mutable classes | `avoid_equals_and_hash_code_on_mutable_classes` (opt-in) | |
338
+ | DON'T make the parameter to `==` nullable | `avoid_null_checks_in_equality_operators` (opt-in, deprecated) | |
@@ -0,0 +1,48 @@
1
+ #!/usr/bin/env bash
2
+ # Optional "format on write" hook: runs `dart format` on the .dart file(s) an
3
+ # agent (or a person) just wrote, so formatting never depends on anyone
4
+ # remembering. Skips generated code. Never blocks: always exits 0.
5
+ #
6
+ # Input, either of:
7
+ # format-dart-hook.sh <file.dart> [more files...] # a path as $1 (any hook system, git hooks, scripts)
8
+ # echo '{"tool_input":{"file_path":"lib/a.dart"}}' | format-dart-hook.sh
9
+ # # hook JSON on stdin (Claude Code style)
10
+ # Non-.dart paths, generated files, missing files and a missing `dart` are ignored.
11
+ #
12
+ # --- Claude Code (post-edit hook) ----------------------------------------------
13
+ # In ~/.claude/settings.json or a project's .claude/settings.json:
14
+ # "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
15
+ # "hooks": [ { "type": "command",
16
+ # "command": "bash ~/.claude/skills/dart-flutter-best-practices/scripts/format-dart-hook.sh" } ] } ] }
17
+ # (adjust the path to wherever the suite is installed). Claude Code sends the
18
+ # hook JSON on stdin, and this script reads `tool_input.file_path` from it.
19
+ #
20
+ # --- Any other agent or hook system that can pass a path ------------------------
21
+ # Configure it to run this command after a file is written or edited:
22
+ # bash <suite>/dart-flutter-best-practices/scripts/format-dart-hook.sh "<edited file path>"
23
+ # If your agent's hook sends JSON on stdin in a different shape, extract the path
24
+ # and pass it as $1. Only the Claude Code shape above is parsed from stdin.
25
+ #
26
+ # --- git pre-commit (.git/hooks/pre-commit, chmod +x) ---------------------------
27
+ # #!/bin/sh
28
+ # git diff --cached --name-only --diff-filter=ACMR -- '*.dart' | while IFS= read -r f; do
29
+ # bash path/to/format-dart-hook.sh "$f" && git add -- "$f"
30
+ # done
31
+ # Caveat: `git add` restages the whole file. If you commit partial hunks, use a
32
+ # check-only hook instead: `dart format --output=none --set-exit-if-changed <files>`.
33
+
34
+ format_one() {
35
+ case "$1" in
36
+ *.g.dart|*.freezed.dart|*.gr.dart|*.mocks.dart|*.config.dart|*/generated/*) return 0 ;;
37
+ *.dart) [ -f "$1" ] && command -v dart >/dev/null 2>&1 && dart format "$1" >/dev/null 2>&1 ;;
38
+ esac
39
+ return 0
40
+ }
41
+
42
+ if [ "$#" -gt 0 ]; then
43
+ for f in "$@"; do format_one "$f"; done
44
+ elif [ ! -t 0 ]; then
45
+ f="$(python3 -I -c 'import json,sys; print((json.load(sys.stdin).get("tool_input") or {}).get("file_path",""))' 2>/dev/null)"
46
+ [ -n "$f" ] && format_one "$f"
47
+ fi
48
+ exit 0