diff --git a/rules/S7111/dart/metadata.json b/rules/S7111/dart/metadata.json new file mode 100644 index 0000000000..5dcdd5ea60 --- /dev/null +++ b/rules/S7111/dart/metadata.json @@ -0,0 +1,24 @@ +{ + "title": "\"part of\" directives should be used with strings", + "type": "CODE_SMELL", + "status": "ready", + "remediation": { + "func": "Constant\/Issue", + "constantCost": "2min" + }, + "tags": [ + "convention" + ], + "defaultSeverity": "Minor", + "ruleSpecification": "RSPEC-7111", + "sqKey": "S7111", + "scope": "All", + "defaultQualityProfiles": ["Sonar way"], + "quickfix": "unknown", + "code": { + "impacts": { + "MAINTAINABILITY": "LOW" + }, + "attribute": "CLEAR" + } +} diff --git a/rules/S7111/dart/rule.adoc b/rules/S7111/dart/rule.adoc new file mode 100644 index 0000000000..9eb5288d2b --- /dev/null +++ b/rules/S7111/dart/rule.adoc @@ -0,0 +1,62 @@ +`part of` directives should be used with strings, rather than with `library` names. + +== Why is this an issue? + +Often Dart libraries are small enough to be entirely contained in a single file. + +However, when the file becomes too large and it's not possible to split the library into smaller libraries (as adviced by the Dart team in the note https://dart.dev/guides/libraries/create-packages#organizing-a-package[here]), Dart defines a +`part of` directive, which allows developers to split the library into multiple smaller chunks. + +When a library is split into multiple files, each part has to refer the library it belongs to, and it can do so with two similar but alternative syntaxes: + +* by name identifier: `part of my_library;` +* by a URI string: `part of 'my_library.dart';` + +The second syntax is more precise and flexible, because it explicitely identifies the file that contains the main body of the library, whereas a reference by identifier needs to be resolved to a URI by the Dart compiler. + +=== What is the potential impact? + +If the `part of` directive is used with a library name, the Dart compiler may resolve the library incorrectly, if multiple libraries with the same name but different paths exist in the package. + +== How to fix it + +Convert the name identifier into a string, append the `.dart` extension, and prepend the relative path. + +=== Code examples + +==== Noncompliant code example + +[source,dart,diff-id=1,diff-type=noncompliant] +---- +part of my_library; +---- + +==== Compliant solution + +[source,dart,diff-id=1,diff-type=compliant] +---- +part of '../my_library.dart'; +---- + +== Resources + +=== Documentation + +* Dart Docs - https://dart.dev/tools/linter-rules/use_string_in_part_of_directives[Dart Linter rule - use_string_in_part_of_directives] +* Dart Docs - https://dart.dev/guides/libraries/create-packages#organizing-a-package[Packages - Organizing a package] + +ifdef::env-github,rspecator-view[] + +''' +== Implementation Specification +(visible only on this page) + +=== Message + +The part-of directive uses a library name. + +=== Highlighting + +The entire `part of` directive statement, including the semicolon: e.g. `part of my_library;`. + +endif::env-github,rspecator-view[] diff --git a/rules/S7111/metadata.json b/rules/S7111/metadata.json new file mode 100644 index 0000000000..2c63c08510 --- /dev/null +++ b/rules/S7111/metadata.json @@ -0,0 +1,2 @@ +{ +}