null_safety_percentage

command-line tool to provide null-safety percentage info of a project. track your migration progress on mixed-version programs that execute with unsound null safety.

important links

• read the source code and star the repo on github
• open an issue on github
• see package on pub.dev
• read the docs on pub.dev
• dart null safety
  • migrating to null safety
  • unsound null safety
• dart “pub run”

motivation

a dart program can contain some libraries that are null safe and some that aren’t. these mixed-version programs execute with unsound null safety. – dart: unsound null safety

for smaller projects, migrating to null safety can be done in a matter of minutes.
unfortunately, if you are not satisfied with the automatically migrated code and you want to do the migration on your own, the migration of large code-bases can take a while.

this command-line tool lets you track your progress of your null-safety migration.

installation

install the null_safety_percentage command-line tool either globally or as a dev dependency.

global installation

if you install null_safety_percentage globally, you can execute it simply by typing null_safety_percentage lib test.

# install globally
dart pub global activate null_safety_percentage
# or: flutter pub global activate null_safety_percentage

# verify installation was successful
null_safety_percentage --help

as dev dependency

you can run dart scripts from your dependencies using the dart run or flutter run command.

flutter project

1. add null_safety_percentage to your dev_dependencies: flutter pub add -d null_safety_percentage.
2. run the script flutter run null_safety_percentage lib test. see more example in the “usage” section below.

dart project

1. add null_safety_percentage to your dev_dependencies: dart pub add -d null_safety_percentage.
2. run the script dart run null_safety_percentage lib test. see more example in the “usage” section below.

usage

keep in mind that how you invoke the null_safety_percentage depends on how you installed it and whether you are using it from a flutter or dart project.
the usage examples below assume you installed the package globally.

# see usage and other info about the package
null_safety_percentage --help
null_safety_percentage -h

# one folder
null_safety_percentage lib

# multiple folders
null_safety_percentage lib test

# custom output format: json
null_safety_percentage --output-format=json lib test
null_safety_percentage --output-format json lib test

# custom output format: ascii (perfect with unix/shell tools)
null_safety_percentage --output-format ascii lib test

# get version info
null_safety_percentage --version

the tool supports multiple output formats, so for example if you want to add a check in your ci/cd tool to ensure that your “null-safety coverage percentage” metrics are not getting worse, you can use the “ascii” format, then take the metric you are interested in.

caveats

the tool is in its early phases and is written so that it runs correctly on the projects i am working on.

currently, the way the tool decides whether a file counts as migrated or not is pretty rudimentary.
i assume there must be better ways to get this information, but this approach worked well enough for me.
improvements, recommendations are welcome.

the tool is not going to work on totally unmigrated libraries. i didn’t want to add safe-guards against that, so please make sure that the “input” project is at least partially migrated.

example

don’t forget the project’s example folder for a project where you can test the command-line tool.