pana 0.12.21

Build Status

A library for analyzing Dart packages. It invokes executables from the Dart SDK (or from the Flutter SDK if the package uses Flutter).

  • Checks for outdated dependencies (calls pub upgrade or flutter pub upgrade).
  • Validates the code using Dart Analyzer.
  • Checks code formatting (dartfmt or flutter format).
  • Infers supported platforms: Flutter, web, and/or other (e.g console/server).
  • Creates suggestions to improve the package.

Used by the Dart Package site.

Use as an executable #

Installation #

> pub global activate pana

Usage #

You can specify either a package (+ version) or a local directory to analyze:

Usage: pana [<options>] <published package name> [<version>]
       pana [<options>] --source path <local directory>

Options:
      --flutter-sdk     The directory of the Flutter SDK.
  -j, --json            Output log items as JSON.
  -s, --source          The source where the package is located (hosted on https://pub.dev, or local directory path).
                        [hosted (default), path]
  
      --hosted-url      The server that hosts <package>.
                        (defaults to "https://pub.dev")
  
  -l, --line-length     The line length to use with dartfmt.
      --verbosity       Configure the details in the output.
                        [compact, normal (default), verbose]
  
      --[no-]scores     Include scores in the output JSON.
      --[no-]warning    Shows the warning message before potentially destructive operation.
                        (defaults to on)

Scoring #

Health score #

A package gets 0.0 if any major analyzer process fails (e.g. pub upgrade, dartanalyzer or dartfmt).

Otherwise the score starts with 1.0, and

  • analyzer errors reduce it by 25%
  • analyzer warnings reduce it by 5%
  • analyzer hints reduce it by 0.5%
  • platform conflicts reduce it by 0.25 points (absolute reduction)

health = 0.75^errors * 0.95^warnings * 0.995^hints - 0.25*conflicts

Pub site transforms this score into the [0 - 100] range.

Maintenance score #

A package starts with 100 points, and the following detected issues have point reductions:

  • unable to parse pubspec.yaml with strict parsing (100 points)
  • uses strong-mode: false in analysis_options.yaml (-50 points)
  • SDK constraint is missing from pubspec.yaml (-50 points)
  • using git dependencies (-100 points, -50 if using commit hashes)
  • unable to parse markdown content (-50 points)
  • readme.md missing (-30 points)
  • changelog.md missing (-20 points)
  • has platform conflicts (-20 points)
  • has unconstrained dependencies (-20 points)
  • does not allow latest stable SDK (-20 points)
  • description is too short (<60 characters) (-20 points)
  • description contains too many non-ASCII characters (-20 points)
  • homepage points to non-existent URL (-20 points)
  • homepage is not helpful (e.g. pointing to http://localhost/) (-10 points)
  • homepage is insecure (not using https) (-5 points)
  • documentation points to non-existent URL (-10 points)
  • documentation is not helpful (e.g. pointing to http://localhost/) (-10 points)
  • documentation is insecure (not using https) (-5 points)
  • repository points to non-existent URL (-10 points)
  • repository is not helpful (e.g. pointing to http://localhost/) (-10 points)
  • repository is insecure (not using https) (-5 points)
  • issue_tracker points to non-existent URL (-10 points)
  • issue_tracker is not helpful (e.g. pointing to http://localhost/) (-10 points)
  • issue_tracker is insecure (not using https) (-5 points)
  • description is too long (>180 characters) (-10 points)
  • does not support the latest version of its direct dependencies (-10 points)
  • package has no example file (-10 points)
  • uses old .analysis_options file (-10 points)
  • uses pre-v0.1 release versioning (0.0.*) (-10 points)
  • uses pre-release versioning (*.*.*-beta2) (-5 points)
  • image links in markdown content are insecure (not using https) (-2 points per link)
  • image links in markdown content are broken (unable to parse) (-1 point per link)
  • changelog.md, readme.md or example content is too large (-1 point per every 1kb above 128kb).
  • pubspec.yaml too large (-1 point per every 1kb above 32kb).

On top of that, pub site applies an age restriction:

  • outdated packages (age older than two years) are reduced to 0
  • old packages (age between 1 and 2 years) get linear reduction (1.5 years old get 50% reduction)

0.12.21 #

  • Upgraded dependencies: analyzer 0.38.2.

0.12.20 #

  • Updated suggestion for not supporting future stable SDKs.

  • Upgrade dependencies: analyzer to 0.37

  • Support the latest json_annotation.

  • Don't penalize outdated dependency when the package's constraint allows it, but a dependent package or SDK restricts it.

0.12.19 #

  • Fix: penalize outdated package constraints only for direct dependencies.

0.12.18 #

  • Penalize package constraints that does not support the latest published versions of their dependencies.

0.12.17 #

  • Recognize .markdown and .mdown files.
  • Recognize COPYING and UNLICENSE as license file names (or prefix).
  • Accept any extension for license files.

0.12.16 #

  • Fixed the use of pedantic rules following the new versioned pattern.

0.12.15 #

  • Fix: delete local temporary pedantic_analyis_options_[timestamp].g.yaml.

  • Upgrade dependencies: analyzer to 0.36

0.12.14 #

  • Penalty for too large readme, changelog or example.

  • Penalty for too large pubspec.yaml.

  • Display calculated health and maintenance scores when pana is called with --scores.

  • Ask for example only for packages with public libraries.

  • Deduplicate dartanalyzer output lines.

0.12.13+1 #

  • Support the latest package:analyzer.

0.12.13 #

  • Don't block platform classification on hints.

  • Apply pedantic rules without referencing package:pedantic in the inspected package's pubspec.yaml.

  • Warn about insecure (non-https) image URLs in markdown content (readme, changelog and example).

0.12.12 #

  • Link to package layout conventions in example-related suggestions.

  • Use package:pedantic as default package analysis ruleset.

  • Linear penalties for description.

  • Updated suggestion messages.

0.12.11 #

  • Maintenance score penalty for:
    • non-https URLs
    • git dependencies
    • strict parsing errors of pubspec.yaml

0.12.10 #

  • Support --line-length in command-line and in InspectOptions (pass-through to dartfmt).

  • Fix pub upgrade parsing.

  • Strict SDK constraint status:

    • sdk: any or sdk: is considered missing constraint
    • handling cases without upper bound (sdk: >1.0.0 is rejected by Dart2 latest)

0.12.9 #

  • Analysis options used in code health scoring updated:

    • removed stale options,
    • included latest Flutter-enabled lints,
    • included latest stagehand-enabled lints.
  • Upgraded to package:analyzer 0.34.1, which fixed a NPE.

  • Validating repository and issue_tracker URLs.

0.12.8 #

  • Code cleanup.

  • Reduce the amount of warning+ level log messages when tools fail.

  • Handle package with bad pubspec.yaml.

0.12.7 #

  • Reduce the amount of logging when dartfmt fails due to an issue in the package.

  • Display Dart SDK warning if package doesn't allow the latest Dart 2.X version.

0.12.6 #

  • Bulk processing and comparison.

  • Penalty for description using too many non-ASCII characters.

  • Use --dry-run on executing flutter format.

  • Retry the external process on downloading and listing packages.

  • Use Flutter's internal Dart SDK to run dartanalyzer on Flutter packages.

0.12.5 #

  • Increase the severity of missing SDK constraint.

  • Make example/readme.md the first-level example-file candidate.

  • Scores values should be consistently in the [0.0-1.0] range.

0.12.4 #

  • Documented how scoring works.

  • Estimate health score penalties.

0.12.3 #

  • Increased dartfmt timeout to 5 minutes.

  • Store basic stats in the analysis summary.

  • Detect example/readme.md (or similar pattern) as an alternative to single .dart example.

0.12.2 #

  • Bugfix: pre-v1 release should be pre-v0.1 instead.

0.12.1 #

  • Bugfix: packages without Dart files failed the health checks.

0.12.0 #

Breaking changes:

  • Named parameters in the following constructors: Summary, DartFileSummary, PkgDependency, CodeProblem.

  • Removed per-file and overall Fitness, using a top-level Health report instead. Follows the proposed changes that allow us to clearly communicate the scoring mechanism.

  • Removed Penalty and using the simpler to understand score in place of it.

Updates:

  • Use flutter format for Flutter packages.

  • Support relative local path with --source path.

  • Track tool failures and set health score to 0 if there is any.

0.11.8 #

  • Support Dart 2 gold release.

  • Remove strong-mode: true check and suggestion.

  • Do not check existence of non-external URLs.

  • API for external caching of URL existence checks.

0.11.7 #

  • Suggestions for SDK constraint and Dart 2 compatibility.

0.11.6 #

  • Updated report on dartanalyzer suggestions.

0.11.5 #

  • Less verbose logging.

  • Updated platform classification:

    • Library conflict rule is moved to the end of the evaluation.
    • Top file-related suggestions are directly exposed.
    • The bulk summary suggestion is more compact.
  • Updated suggestion messages.

0.11.4 #

  • Export libraries used by pub site.

  • Update minimum SDK to 2.0.0-dev.42.0

    • The SDK was effectively restricted to at least this version due to other dependencies.
  • Better expose platform conflict reasons.

0.11.3 #

  • Support changing part of the analysis result.

  • Fix dartdoc timeout when using pub global run.

0.11.2 #

  • dartdoc processing: do not exclude packages by default, as dartdoc 0.19 handles SDK links.

  • expose getAgeSuggestion method for pub site

  • Update analyzer dependency to ^0.32.0.

0.11.1 #

  • Upgrade CI to dev.54 and fix new deprecation warnings.

  • Bugfix: do not initialize dartdocSuccessful with a value.

  • Support --flutter-sdk in the pana binary.

0.11.0 #

Breaking changes:

  • DartSdk, FlutterSdk and PubEnvironment is replaced with ToolEnvironment.

  • ToolEnvironment.runAnalyzer returns the text output of the process.

  • Consolidating options in InspectOptions, changing PackageAnalyzer APIs.

  • Move all output-related data structure to src/model.dart:

    • CodeProblem.parse -> parseCodeProblem
    • Maintenance.getMaintenanceScore -> getMaintenanceScore
    • PkgResolution.create -> createPkgResolution
  • Move all runtime/version info into PanaRuntimeInfo (and use it in Summary).

  • Removed Fitness.suggestions (moved it to DartFileSummary)

Updates:

  • Run dartdoc (optional) and report if it was not able to complete successfully.

  • Added a top-level models.dart library exposing several of the data classes.

  • Check homepage and documentation properties to point to an existing and external web page.

  • --verbose command-line and Verbosity option to control the details in the analysis output.

0.10.6 #

  • Enable Dart 2 Preview in analyzer options (including non-Flutter packages).

  • Change platform classification of dart:isolate: no longer available on web.

  • Treat environment: keys as dependent SDKs (e.g. flutter).

  • Use LibraryElement.hasExtUri to detect dart-ext: imports.

  • Detailed suggestion messages when package has conflicting platforms.

0.10.5 #

  • Enable Dart 2 Preview in Flutter analyzer options.

0.10.4 #

  • Fix CI test

  • Flutter-specific suggestion messages for dartfmt and dartanalyzer.

0.10.3 #

  • Fix end-to-end test (package dependency changed).

  • Move pubspec stripping inside PubEnvironment.runUpgrade (dartdoc service will get it for free).

  • Handle more repository URLs (e.g. www.github.com).

  • Expose Flutter detection to clients, with better naming (isFlutter -> usesFlutter).

0.10.2 #

  • Fix issue of not using the PUB_CACHE directory when it was set.

  • Update analyzer to 0.31 and extends quiver version range.

  • Fix issue where we were not passing the proper package directory variable.

  • Expose all dartanalyzer and dartfmt problems as suggestions.

0.10.1 #

  • Include component list in platform classification reasons.

  • Do not report on unconstrained SDK dependencies.

  • New platform component: build.

  • Remove dependency_overrides from pubspec.yaml.

0.10.0 #

BREAKING CHANGES:

  • Removed DartPlatform.description and DartPlatform.descriptionAndReason because we don't use them elsewhere and complicates the PlatformNames with everywhere and undefined.

  • Removed PlatformNames.everywhere and PlatformNames.undefined, because we don't print these anywhere except in tests.

  • Removed PlatformNames.dartExtension, because we use it only internally.

  • Removed DartPlatform.restrictedTo, using the fields components and uses instead.

  • Removed PlatformNames.server (and its platform detection), using a wider other platform instead.

0.9.1 #

  • Use raw links for images in repository URLs.

  • Move unconstrained version penalty from health score to maintenance.

  • Move platform conflict penalty from health score to maintenance.

  • Sort maintenance suggestions in decreasing importance.

0.9.0+1 #

  • Fix NPE when dependency has no constraint (e.g. git repo).

0.9.0 #

  • Only direct unconstrained dependencies decrease the health score.

  • Removed superfluous pubspec.lock validation.

  • Recommend descriptions between 60 and 180 characters.

  • Detect another license format

  • Pass-through values of analyzer_options.yaml errors like uri_has_not_been_generated.

0.8.2 #

  • Unblock platform classification on a new class of errors.

  • Better messages in platform classification.

0.8.1 #

  • Use Flutter-recommended analysis options when analyzer Flutter packages.

  • BREAKING BEHAVIOR: Don't use PUB_HOSTED_URL for package downloads, as it has not worked out in practice. Instead, we've added a --hosted-url command line argument.

0.8.0 #

  • PackageAnalyzer.inspectPackage added a named argument deleteTemporaryDirectory. Setting this to false retains the directory and prints its location to the log. Useful for debugging.

  • Maintenance

    • BREAKING getMaintenanceScore now takes an optional age parameter replacing the previously required publishDate parameter.

    • Changed the meaning of version fields:

      • isExperimentalVersion now means pre-V1.
      • isPreReleaseVersion now means there is a pre-release flag like -beta, -alpha, etc.
    • BREAKING maintenance-related Suggestion entries as moved to Maintenance.suggestions

  • BREAKING Suggestion.file is now String instead of dynamic.

  • Detect the new format of native extensions.

  • Unblock platform classification on a new class of errors.

  • Use PUB_HOSTED_URL for package downloads.

0.7.3+1 #

  • Allow more versions of package:args.

0.7.3 #

  • Added pana as an executable. Enables pub global activate pana.

  • Improved license detection: commented license files are now recognized.

0.7.2 #

  • Handle more critical exceptions and report them with more details.

  • The Suggestion.bug constructor had a breaking change – a required argument was added, but this is not intended for invocation by end-users.

0.7.1 #

  • Add SuggestionLevel.bug and use it to record fatal errors with the tool.

0.7.0+1 #

  • Fixed issue where analyzer and/or formatter were run on directories with no Dart files.

0.7.0 #

  • Breaking changes

    • Summary.sdkVersion is now a Version instead of String.

    • new PackageAnalyzer(...) now takes a DartSdk instance instead of a String.

  • static Future<PackageAnalyzer> create(...) was added to PackageAnalyzer.

  • Added logger optional argument to PackageAnalyzer.inspectPackage.

0.6.2 #

  • Allow platform classification for a small class of analysis errors.

0.6.1 #

  • Don't count the absence of an analysis_options.yaml file against a package.

0.6.0 #

  • Breaking changes

    • Removed ToolProblem class.
    • Removed Summary.toolProblems, in favor of Summary.suggestions.
  • Detect and store maintenance-related data in summary.

    • Scoring of tool problems moved from Fitness to Maintenance.
  • Provide human-readable feedback and instructions on some of the issues we find during the analysis.

0.5.1 #

  • Use a consistent 2 minute timeout for all processes.

  • Classify platform as nowhere when part of analysis fails.

0.5.0 #

  • Breaking changes

    • License renamed to LicenseFile
    • Summary.license -> licenses: we'll return multiple licenses
    • Removed LicenseNames.missing: empty List will indicate no license file
  • Greatly expanded and improved license detection.

0.4.0 #

  • Breaking changes

    • Renamed AnalyzerIssue -> ToolProblem

      • Renamed Summary.issues -> toolProblems
      • Renamed AnalyzerIssue.scope -> tool
      • Renamed AnalyzerScopes -> ToolNames
    • Renamed AnalyzerOutput -> CodeProblem

      • Renamed Summary.analyzerItems and DartFileSummary.analyzerItems -> codeProblems
    • Refactored CodeProblem (previously AnalyzerOutput):

      • Split up type, new fields: severity, errorType, errorCode
      • Renamed error to description
    • Refactored Fitness:

      • Renamed total -> magnitude
      • Removed value, using shortcoming instead (value = magnitude - shortcoming;)
    • Refactored PubSummary, renamed to PkgResolution

      • Moved pubspec -> Summary
      • Moved pkgVersion -> Pubspec.version
      • Moved authors -> Pubspec.authors
      • Merged packageVersions and availableVersions into dependencies
      • Renamed Summary.pubSummary -> pkgResolution
    • Refactored platform:

      • Renamed PlatformFlags -> PlatformNames
      • Removed most of the platform-related classes, using DartPlatform instead

0.3.0 #

  • Removed PlatformSummary.package in favor of PlatformSummary.pubspec of (new) type PubspecPlatform.

  • Renamed KnownPlatforms to PlatformFlags. Also:

    • Removed mirrors, browser and standalone.
    • Renamed native to dartExtension.
  • PlatformInfo

    • Now store dart:* references directly in uses.
    • worksInStandalone renamed to worksOnServer.
    • Other .worksIn* renamed to worksOn*.
    • Added String get description which returns a simple String description of the supported platforms. Examples: everywhere, flutter, server, web, conflict.
    • Removed angular as a value in uses.

0.2.4 #

  • Detect native extensions.

  • Detect licenses.

0.2.3 #

  • Lot's of stability improvements.

  • Improvements to error handling.

0.2.2 #

  • Lot's of cleanup to JSON output.

  • Improved stability.

  • Platform detection basics.

0.2.1 #

  • Added support for flutter packages.

  • Expanded analysis to include transitive dependencies.

  • Added scoring library.

  • Moved the repo to dart-lang.

0.2.0 #

  • A lot of tweaks. Still under heavy development.

0.0.1 #

  • Initial version.

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate pana

2. Use it

The package has the following executables:


$ pana

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  pana: ^0.12.21

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:pana/pana.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
51
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
79
Overall:
Weighted score of the above. [more]
71
Learn more about scoring.

We analyzed this package on Sep 19, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, other

Primary library: package:pana/pana.dart with components: io, isolate.

Maintenance suggestions

The package description is too short. (-11 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.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and pana.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.3.0 <3.0.0
analyzer ^0.38.0 0.38.3
args >=0.13.7 <2.0.0 1.5.2
async >=1.13.3 <3.0.0 2.3.0
cli_util ^0.1.3 0.1.3+2
html >=0.13.3 <0.15.0 0.14.0+2
http >=0.11.3 <0.13.0 0.12.0+2
io ^0.3.3 0.3.3
json_annotation >=2.0.0 <4.0.0 3.0.0
logging ^0.11.3+1 0.11.3+2
markdown ^2.0.2 2.0.3
meta ^1.1.7 1.1.7
package_config >=0.1.5 <2.0.0 1.1.0
path ^1.6.2 1.6.4
pedantic ^1.4.0 1.8.0+1
pool ^1.3.6 1.4.0
pub_semver ^1.4.2 1.4.2
pubspec_parse ^0.1.4 0.1.5
quiver >=0.24.0 <3.0.0 2.0.5
resource ^2.1.5 2.1.6
yaml ^2.1.15 2.2.0
Transitive dependencies
charcode 1.1.2
checked_yaml 1.0.2
collection 1.14.12
convert 2.1.1
crypto 2.1.3
csslib 0.16.1
front_end 0.1.25
glob 1.1.7
http_parser 3.1.3
kernel 0.3.25
matcher 0.12.5
source_span 1.5.5
stack_trace 1.9.3
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
watcher 0.9.7+12
Dev dependencies
build ^1.1.0
build_config ^0.4.0
build_runner ^1.1.3
build_verify ^1.1.1
build_version ^2.0.0
json_serializable ^3.2.0
source_gen ^0.9.0
test ^1.5.2
test_descriptor ^1.1.1
test_process ^1.0.4