dart-lang/pana

Package ANAlysis for Dart

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

Reports are created in the following categories:

• Follow Dart conventions
• Provide documentation
• Support multiple platforms
• Pass static analysis
• Support up-to-date dependencies

Used by the Dart Package site.

Use as an executable

Installation

dart pub global activate pana

Usage

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

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

Options:
      --dart-sdk               The directory of the Dart SDK.
      --flutter-sdk            The directory of the Flutter SDK.
      --exit-code-threshold    The exit code will indicate if (max - granted points) > threshold.
  -j, --json                   Output log records and full report as JSON.
      --hosted-url             The server that hosts <package>.
                               (defaults to "https://pub.dev")
  -l, --line-length            The line length to use with dart format.
      --hosted                 Download and analyze a hosted package (from https://pub.dev).
      --[no-]dartdoc           Run dartdoc and score the package on documentation coverage.
                               (defaults to on)
      --dartdoc-version        The dartdoc version to use: `sdk`, `latest` (default) or `<version constraint>`.

pana's Issues

Remove 'ding' for being pre-v1

We don't want to encourage folks to push for a v1 before they're ready – just to get a perfect score, etc.

Only include "primary" libraries in summaries

For Dart files in lib/ only include files that are not in lib/src.

This will make the output smaller – and restrict it to only "official" libraries.

Mis-classifying flutter packages as working on server

See https://github.com/amirh/indux/blob/ff6ac4272fc2ea883778949e2ed31669b5969dce/pubspec.yaml#L10

https://pub.dartlang.org/packages/indux

Nit: detect if current version is mentioned in changelog

Let's remove LibraryScanner overrides

(1) The override in its current form is misleading, because it creates a dart:web_safe_io package which doesn't exists, but somebody may think it does. A dart-trusted:http would be a more adept name.

(2) I think having these overrides is a bad precedent, for the following reasons:

• We don't want to keep track all of the libraries that use dart:io in a web-safe way. Getting onto that list, changing it would require efforts on all sides.
• We may track a few, but forget about it. As the libraries, change, some of these information gets outdated, even in a breaking way, and provides misleading results.
• Tracking package_resolver's http use is an ever worse precedent: are we going to list everything there that has http as its dependency?

The correct solution: analyze the Dart sources and detect, whether the client is going to use any of the non-web-related dart:io code, and mark it as such. This a lot of effort, and probably not worth it at the moment.

The optimistic solution: let's assume that when both dart:html and dart:io is present, it is importing it in a web-safe-io way. We already have tests for this: https://github.com/dart-lang/pana/blob/master/test/platform_test.dart#L83

I'd go with optimistic solution, and remove the overrides altogether.

Rationalize INFO|HINT|STRONG_MODE_TOP_LEVEL_ with new top-level logic

In 1.24 and before, strong-mode issues with top-level inference were considered hints.

They will be reclassified in 1.25+. Need to make sure we handle that.

Consolidate naming and serialized structure

Some classes and fields are confusing, for example:

• Summary vs. PubSummary vs. Pubspec
• AnalyzerOutput (which should be SourceIssue) vs. AnalyzerIssue (which should be ToolIssue).
• PubspecPlatform vs. PlatformInfo

I think 0.4 should be released with the directory option to unblock pub site's cache issue, and these could go in the next release.

Do we only care about `StateError` when creating `LibraryScanner`?

pana/lib/src/package_analyzer.dart

Line 188 in 8ec236a

} on StateError catch (e, stack) {

Seems...bad...that we don't log any of the other possible issues here.

Tracking issues for flutter CLI support

Couple of things we need to decide:

• How to pick flutter and Android SDK versions for analysis?

  • Do we do that as part of the pana library, or is it assumed to be done externally?
  • Can/should flutter use the Dart SDK we specify, or are we fine with whatever version it downloads?
  • For how long can we reuse the downloaded stack?

• The third-party dependency involvement here seems to be huge, and we use very little of it. Is there an alternative way to "simulate" flutter's version of pub get, without the full flutter stack?

Ignore dev_dependencies before pub upgrade / analysis

Parse Dart SDK and provide it the same way as pana- and flutter-version.

Detect which version constraints cause issues

Document in the README how to run pana

New pub website says "Follow the suggestions on the analysis tab on the package page, or run pana manually to check these before publishing." but I can't see how to run it.

It doesn't add any binaries if I pub global activate it.

Stack overflow w/ angular_ast at 0.4.0-alpha+2

dart --checked bin/main.dart angular_ast 0.4.0-alpha+2

SEVERE     Error scanning direct librariers
           Stack Overflow
           #0      _HashMap.putIfAbsent (dart:collection-patch/dart:collection/collection_patch.dart:130)
           #1      CacheEntry.getResultData (package:analyzer/src/context/cache.dart:423:23)
           #2      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart:800:27)
           #3      CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #4      _HashFieldBase&_HashBase&_OperatorEqualsAndHashCode&SetMixin.forEach (dart:collection/set.dart:145)
           #5      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart:808:31)
           #6      CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #7      _HashFieldBase&_HashBase&_OperatorEqualsAndHashCode&SetMixin.forEach (dart:collection/set.dart:145)
           #8      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart:808:31)
           #9      CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #10     _HashFieldBase&_HashBase&_OperatorEqualsAndHashCode&SetMixin.forEach (dart:collection/set.dart:145)
           ...
           ...
           #13660  _RootZone.runUnary (dart:async/zone.dart:1379)
           #13661  _FutureListener.handleValue (dart:async/future_impl.dart:129)
           #13662  _Future._propagateToListeners.handleValueCallback (dart:async/future_impl.dart:635)
           #13663  _Future._propagateToListeners (dart:async/future_impl.dart:664)
           #13664  _Future._completeWithValue (dart:async/future_impl.dart:477)
           #13665  _Future._asyncComplete.<anonymous closure> (dart:async/future_impl.dart:509)
           #13666  _microtaskLoop (dart:async/schedule_microtask.dart:41)
           #13667  _startMicrotaskLoop (dart:async/schedule_microtask.dart:50)
           #13668  _runPendingImmediateCallback (dart:isolate-patch/dart:isolate/isolate_patch.dart:111)
           #13669  _RawReceivePortImpl._handleMessage (dart:isolate-patch/dart:isolate/isolate_patch.dart:164)
INFO       Scanning transitive dependencies...
SEVERE     Error scanning transitive librariers
           Stack Overflow
           #0      _HashMap.putIfAbsent (dart:collection-patch/dart:collection/collection_patch.dart:130)
           #1      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart:423:23)
           #2      CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #3      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart)
           #4      CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #5      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart)
           #6      CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #7      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart)
           #8      CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #9      CacheEntry._setErrorState (package:analyzer/src/context/cache.dart)
           #10     CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #11     CacheEntry._setErrorState (package:analyzer/src/context/cache.dart)
           #12     CacheEntry._setErrorState.<anonymous closure> (package:analyzer/src/context/cache.dart:813:17)
           #13     CacheEntry._setErrorState (package:analyzer/src/context/cache.dart)
           ...
           ...
           #9053   _RootZone.runUnary (dart:async/zone.dart:1379)
           #9054   _FutureListener.handleValue (dart:async/future_impl.dart:129)
           #9055   _Future._propagateToListeners.handleValueCallback (dart:async/future_impl.dart:635)
           #9056   _Future._propagateToListeners (dart:async/future_impl.dart:664)
           #9057   _Future._completeWithValue (dart:async/future_impl.dart:477)
           #9058   _Future._asyncComplete.<anonymous closure> (dart:async/future_impl.dart:509)
           #9059   _microtaskLoop (dart:async/schedule_microtask.dart:41)
           #9060   _startMicrotaskLoop (dart:async/schedule_microtask.dart:50)
           #9061   _runPendingImmediateCallback (dart:isolate-patch/dart:isolate/isolate_patch.dart:111)
           #9062   _RawReceivePortImpl._handleMessage (dart:isolate-patch/dart:isolate/isolate_patch.dart:164)
INFO       Analyzing package...

Detect real license file url and check its existence.

• E.g. github.com URLs have tree/master in them.
• Sometimes the package homepage is just a landing page for the project or company, and there is no license file in the relative path.

Classify crashes of tools differently

See #138

There should be a Suggestion.bug or similar that tells users to file an issue.

We need to be able to find these types of issues quickly and (hopefully) fix them.

Detect the use of native extensions

At minimum we shall detect the use of import 'dart-ext:something';
An example project is here: https://github.com/yolkhovyy/dht_dart

Use `flutter packages upgrade` instead of `pub upgrade` for flutter packages

Otherwise we blow up

Extend the scope of analyzer options with stagehand defaults?

If these are good defaults for stagehand, maybe they are good for pana too?

https://github.com/dart-lang/stagehand/blob/master/templates/package-simple/analysis_options.yaml

consider environment -> flutter in pubspec analysis?

https://www.dartlang.org/tools/pub/pubspec#flutter-sdk-constraints

To discuss.

Flag imports that point outside of the lib/ directory.

Detect too broad version constraint

Similar to any, a constraint with>= 0.0.0 is likely too broad.

Misclassification if one of the packages was not analyzed.

If I have a package that has two libraries, and one of them has a lot of unresolved package URIs (because the dependency is in dev_dependencies), we classify it as "works everywhere", instead of "works nowhere".

License detection: separate package?

License detection is a neat, easy-to-separate feature which could live in its own package (e.g. license). Contribution to it would be easier, it would be normal there to have all of the different license texts part of the tests, but it won't put much drag on the pana repo. Thoughts?

please publish new version

Timeout stuck downloads.

As the pub site is sporadically down, many of my tests were stuck in the download step.

Rationalize Platform + PlatformSummary w/ Summary

I'd like to take the output from bin/main.dart and/or bin/runner.dart and throw that into a Platform/PlatformSummary

Getting asked to maintain a changelog – but it seems that one exists

From @kevmoo on December 7, 2017 18:7

URL: https://pub.dartlang.org/packages/pen

Thoughts?

Copied from original issue: dart-lang/pub-dev#769

Add `description` to `Suggestion.bug` ctor

Populate it in the title field instead of the hard-wired. "'There is likely a bug in the analysis code or a dependency.'"

Then populate the details w/ creating LibraryScanner, scanning direct dependencies, etc. We should keep track of this info.

`pub upgrade` failed. STDERR exceeded 100000 lines.

Not much in the logs. It was for twit 0.0.4.

Nit: detect if changelog or readme is just the skeleton generated by stagehand.

fail gracefully when dartanalyzer's output is not in the expected format

for example run dart bin/main.dart glob

Analyzer returns dart:nativewrappers instead of dart-ext:package

This is probably a change in the bleeding edge analyzer we are using in the override.

store version in serialized format

Use `asset:` instead of `path:` - tis convention

asset:pkg_name/full/path/inside/package.dart

Move most of score calculation from pub site to pana

Detect multiple licenses

Examples:

• https://github.com/dart-lang/dart-samples/blob/master/LICENSE
• multiple license files at root
• Use https://spdx.org/licenses/ classifications.

flutter_built_redux should not be tagged server

https://pub.dartlang.org/packages/flutter_built_redux

Depends on package: flutter directly, yet is classified as "server" :)

I've seen other flutter packages tagged this way.

Handle packages without dart files better.

dartfmt log duplicates the chatter about files not being found. For example:

• bootstrap_sass 3.3.6

Use `flutter analyze` for analyzing flutter packages

Ensures the right set of lints are enabled, etc.

Blocked by flutter/flutter#10704

Backport AnalysisView.health metric to pana from pub site.

License detection doesn't work if license text has comment prefixes

A lot of flutter packages have 'unknown' license, e.g.:
https://pub.dartlang.org/experimental/packages/video_player

This seems to be happening when (for historical reasons) license files have each line start with // ?
https://github.com/flutter/plugins/blob/master/packages/video_player/LICENSE

Override analyzer_options.yaml?

Shall we do it? If somebody disables every warning, our report will display it as clean, while in reality it may be full of warnings or errors.

dobx_ds 0.1.0 parse failure

It looks like that parsing of dobx_ds 0.1.0 fails for several reasons. The following log is after the NPE of #55 was fixed.

dart bin/main.dart dobx_ds 0.1.0
INFO       SDK: Dart VM version: 1.24.2 (Thu Jun 22 08:42:17 2017) on "macos_x64"
INFO       Package: dobx_ds
INFO       Version: 0.1.0
FINE       Using .package-cache: /private/var/folders/fw/h4p8y9dx4y95nc0myyz75xvh0000gn/T/pana.1501251743113.uegBgf
INFO       Downloading package...
FINE       Package at /private/var/folders/fw/h4p8y9dx4y95nc0myyz75xvh0000gn/T/pana.1501251743113.uegBgf/hosted/pub.dartlang.org/dobx_ds-0.1.0
INFO       Counting files...
INFO       Checking formatting...
INFO       Checking pubspec.yaml...
INFO       Pub upgrade...
FINE       Running `/Users/syntern/work/google/pub/flutter/bin/flutter packages pub upgrade --verbosity io --no-precompile`...
INFO       Package version: 0.1.0
SEVERE     Could not create LibraryScanner
           Bad state: Could not determine package name for package at /private/var/folders/fw/h4p8y9dx4y95nc0myyz75xvh0000gn/T/pana.1501251743113.uegBgf/hosted/pub.dartlang.org/dobx_ds-0.1.0
           #0      new LibraryScanner (package:pana/src/library_scanner.dart:73:7)
           #1      PackageAnalyzer.inspectPackage (package:pana/pana.dart:153:17)
           <asynchronous suspension>
           #2      main (file:///Users/syntern/work/google/pub/pana.dart/bin/main.dart:83:36)
           <asynchronous suspension>
           #3      _startIsolate.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:263)
           #4      _RawReceivePortImpl._handleMessage (dart:isolate-patch/isolate_patch.dart:151)
INFO       Analyzing package...
FINE       Running `/Users/syntern/work/google/pub/flutter/bin/flutter --version --machine`...

Report license file location

Detect the use of 'any' as version constraint

Use direct downloads of packages instead of using `pub cache`

We should directly download the packages from the normal https://pub.dartlang.org/packages/<name>/versions/<version>.tar.gz urls. Doing so will avoid running into the memcache issue. Furthermore it seems not particularly nice using the internal caching of pub for other purposes.

Detect if dependency is in pubspec but not used in libraries.

should handle better when version cannot be resolved

e.g. in package:unittest, we get the following error:

ERR : Package test has no versions that match >=0.12.4 <0.12.5 derived from:
    | - unittest depends on version >=0.12.4 <0.12.5

Detect license