Workiva's Shared Dart Analysis Options #
This is our take on the Dart team's
pedantic package and is used
in all Workiva Dart packages.
This package (
package:workiva_analysis_options) publicly exports
analysis_options.yaml files that can be included in a project's own
# pubspec.yaml dev_dependencies: workiva_analysis_options: ^1.0.0
# analysis_options.yaml include: package:workiva_analysis_options/v1.yaml
Because most packages don't commit a
pubspec.lock, CI may fail if updates to
analysis_options.yaml files in this package are automatically consumed. To
avoid this, all of these files include a version in the filename, and changes
that could cause new analyzer failures will only ever be introduced in separate,
For example, in the next release of this library, the existing
v1 files will
And changes to the analysis options will only be included in new
This enables consumers to depend on this package with a version range like
^1.0.0 while being able to manage their analysis options upgrade separately.
How lints and analyzer rules are evaluated #
Periodically, Workiva's Client Platform team will evaluate the available lints and rules and attempt to categorize them into one of the following:
- Should provide enough value that it is worth requiring them for all Workiva Dart projects.
- Should not contradict any other required rules.
- Usually help identify problematic code or protect against patterns that can be confusing or incorrect.
- May enforce stylistic/subjective patterns that are nearly universally agreed upon within the organization.
- Should be valuable to most projects.
- Should not contradict any required rules or other recommended rules.
- May have certain exceptions or caveats that prevent them from being required.
- May be used for rules that could be required, but are not currently worth the investment due to the # of infractions that would need to be fixed in order to adopt.
- May be used for rules that are intended to be upgraded to required in the future but are either new or were not previously required.
- Should not contradict any required or recommended rules.
- May have incompatibilities with common patterns or libraries used at Workiva.
- Often times stylistic or subjective.
- May be used for rules that could be recommended, but are not currently worth the investment due to the # of infractions that would need to be fixed in order to adopt.
- May be used for rules that are intended to be upgraded to recommended in the future but are either new or were not previously required.
- May contradict one or more required or recommended rules.
- May be targeted towards domains that Workiva Dart development does not (yet) overlap with (e.g. flutter).
- May be experimental or very new.
- May have an unclear long-term impact that should be avoided until more investigation/experimentation can be done.
We will use feedback from the Dart developers at Workiva, other similar
resources (like the
pedantic package), and the number of existing
infractions across Workiva Dart projects (collected automatically) to inform our
decisions. Each lint has its own issue in this repo that can be used to discuss
changes and will serve as documentation of context and reasons that influenced
Opting in to recommended rules #
analysis_options.yaml files only enable the required rules,
but this package also provides a separate version that also enables the
# analysis_options.yaml # Enables all required AND recommended rules. include: package:workiva_analysis_options/v1.recommended.yaml
Note: there is also a version provided by this library that includes the optional rules, but it is only intended for use in an automated fashion for the purpose of gathering data on the number of infractions in Workiva packages.
Ensuring adoption of the latest shared options #
An automated tool will be integrated into a CI check to verify that Workiva Dart
projects depend on this package at a specific version (or later) and include the
shared config in
Ensuring that analyzer infractions get fixed #
All required analyzer lints and infos/hints/lints will have their severities upgraded to "warning", e.g.:
# package:workiva_analysis_options/v1.yaml analyzer: errors: avoid_empty_else: warning
It is then expected (and enforced internally at Workiva) that CI and developers run analysis in a way that results in a non-zero exit code when errors or warnings are present.
dartanalyzer, this means using
tuneup, this is
enforced by default.
Latest Analysis Options Designations #
- Add ignore for uri_has_not_been_generated errors
- Setup Travis CI
- Initial release
Use this package as a library
1. Depend on it
Add this to your package's pubspec.yaml file:
dependencies: workiva_analysis_options: ^1.1.0
2. Install it
You can install packages from the command line:
$ pub get
Alternatively, your editor might support
Check the docs for your editor to learn more.
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
We analyzed this package on Apr 7, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
- Dart: 2.7.1
- pana: 0.13.6
Maintenance issues and suggestions
No valid SDK. (-20 points)
The analysis could not detect a valid SDK that can use this package.
dartdoc successfully runs on your package's source files. (-10 points)
exitCode: 255 stdout: parsing /dart-sdk/lib/async/async.dart... parsing /dart-sdk/lib/collection/collection.dart... parsing /dart-sdk/lib/internal/internal.dart... parsing /dart-sdk/lib/convert/convert.dart... parsing /dart-sdk/lib/typed_data/typed_data.dart... parsing /dart-sdk/lib/core/core.dart... parsing /dart-sdk/lib/math/math.dart... parsing /dart-sdk/lib/developer/developer.dart... parsing /dart-sdk/lib/isolate/isolate.dart... parsing /dart-sdk/lib/ffi/ffi.dart... parsing /dart-sdk/lib/html/dart2js/html_dart2js.dart... parsing /dart-sdk/lib/html/html_common/html_common_dart2js.dart... parsing /dart-sdk/lib/web_gl/dart2js/web_gl_dart2js.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/native_typed_data.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/interceptors.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/shared/embedded_names.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/js_helper.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/foreign_helper.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/js_names.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/rti.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/shared/recipe_syntax.dart... parsing /dart-sdk/lib/js_util/dart2js/js_util_dart2js.dart... parsing /dart-sdk/lib/html/html_common/metadata.dart... parsing /dart-sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart... parsing /dart-sdk/lib/svg/dart2js/svg_dart2js.dart... parsing /dart-sdk/lib/web_audio/dart2js/web_audio_dart2js.dart... parsing /dart-sdk/lib/web_sql/dart2js/web_sql_dart2js.dart... parsing /dart-sdk/lib/_http/http.dart... parsing /dart-sdk/lib/io/io.dart... parsing /dart-sdk/lib/js/dart2js/js_dart2js.dart... parsing /dart-sdk/lib/js/_js.dart... parsing /dart-sdk/lib/mirrors/mirrors.dart... parsing /dart-sdk/lib/html/dartium/nativewrappers.dart... parsing /dart-sdk/lib/cli/cli.dart... parsing /dart-sdk/lib/wasm/wasm.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/js_primitives.dart... parsing /dart-sdk/lib/_internal/js_runtime/lib/shared/async_await_error_codes.dart... Initialized dartdoc with 37 libraries in 30.3 seconds documenting workiva_analysis_options Validating docs... no issues found Documented 0 public libraries in 1.6 seconds stderr: Documenting workiva_analysis_options... Unhandled exception: dartdoc could not find any libraries to document #0 Dartdoc.generateDocs (package:dartdoc/dartdoc.dart:196:7)
The package description is too short. (-19 points)
Add more detail to the
description field of
pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.