Expose more precise repository verification status in 'AnalysisResult'. (#1433)

Author: isoos

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 0.22.18-dev
 
 - Make example's `README.md` priority over any dart file in the examples directory.
+- Expose more precise repository verification status in `AnalysisResult`.
 
 ## 0.22.17
 

lib/src/internal_model.dart

@@ -214,11 +214,13 @@ class UrlStatus {
 
 @JsonSerializable(includeIfNull: false, explicitToJson: true)
 class VerifiedRepository {
+  final RepositoryStatus status;
   final Repository? repository;
   final String? contributingUrl;
   final String? verificationFailure;
 
   VerifiedRepository({
+    required this.status,
     this.repository,
     this.contributingUrl,
     this.verificationFailure,

lib/src/internal_model.g.dart

@@ -331,6 +331,7 @@ class AnalysisResult {
   final String? issueTrackerUrl;
   final String? documentationUrl;
   final List<String>? fundingUrls;
+  final RepositoryStatus? repositoryStatus;
   final Repository? repository;
   final String? contributingUrl;
   final List<License>? licenses;
@@ -343,6 +344,7 @@ class AnalysisResult {
     this.issueTrackerUrl,
     this.documentationUrl,
     this.fundingUrls,
+    this.repositoryStatus,
     this.repository,
     this.contributingUrl,
     this.licenses,
@@ -356,6 +358,36 @@ class AnalysisResult {
   Map<String, dynamic> toJson() => _$AnalysisResultToJson(this);
 }
 
+/// The status of the repository verification.
+enum RepositoryStatus {
+  /// The repository URL was not specified, empty, or we were not able to
+  /// infer it (e.g. from `homepage`).
+  ///
+  /// No verification was done.
+  unspecified,
+
+  /// The specified URL was not a valid or secure URL.
+  ///
+  /// No verification was done.
+  invalid,
+
+  /// There was no repository found on the specified URL.
+  /// The issue may be transient, a repeated access may find it.
+  ///
+  /// No verification was done.
+  missing,
+
+  /// The repository did not pass verification tests.
+  failed,
+
+  /// The repository passed verification tests.
+  verified,
+
+  /// The repository verification encountered a failure, result is
+  /// not conclusive.
+  inconclusive;
+}
+
 /// NOTE: the content of the class is experimental, clients should not rely on it yet.
 /// To get successful verification, the remote repository:
 ///   - must be a valid remote repository with public access,

lib/src/model.dart

@@ -258,7 +258,7 @@ Future<AnalysisResult> _createAnalysisResult(
     PackageContext context, Report report) async {
   final pubspecUrls = await context.pubspecUrlsWithIssues;
   final repoVerification = await context.repository;
-  final repository = repoVerification?.repository;
+  final repository = repoVerification.repository;
   final fundingUrls =
       pubspecUrls.funding.map((e) => e.verifiedUrl).nonNulls.toList();
   return AnalysisResult(
@@ -267,8 +267,9 @@ Future<AnalysisResult> _createAnalysisResult(
     issueTrackerUrl: pubspecUrls.issueTracker.verifiedUrl,
     documentationUrl: pubspecUrls.documentation.verifiedUrl,
     fundingUrls: fundingUrls.isEmpty ? null : fundingUrls,
+    repositoryStatus: repoVerification.status,
     repository: repository,
-    contributingUrl: repoVerification?.contributingUrl,
+    contributingUrl: repoVerification.contributingUrl,
     licenses: await context.licenses,
     grantedPoints: report.grantedPoints,
     maxPoints: report.maxPoints,

lib/src/model.g.dart

@@ -16,6 +16,7 @@ import 'internal_model.dart';
 import 'license.dart';
 import 'logging.dart';
 import 'messages.dart' as messages;
+import 'model.dart';
 import 'package_analyzer.dart' show InspectOptions;
 import 'pana_cache.dart';
 import 'pkg_resolution.dart';
@@ -61,12 +62,16 @@ class SharedAnalysisContext {
     return status;
   }
 
-  Future<VerifiedRepository?> verifyRepository(
+  Future<VerifiedRepository> verifyRepository(
     String package,
     String? repositoryOrHomepage,
   ) async {
-    if (repositoryOrHomepage == null) {
-      return null;
+    repositoryOrHomepage = repositoryOrHomepage?.trim();
+    if (repositoryOrHomepage == null || repositoryOrHomepage.isEmpty) {
+      return VerifiedRepository(
+        status: RepositoryStatus.unspecified,
+        verificationFailure: 'Repository URL is missing.',
+      );
     }
     final cacheType = 'repository';
     final cacheKey = '$package/$repositoryOrHomepage';
@@ -79,9 +84,7 @@ class SharedAnalysisContext {
       packageName: package,
       sourceUrl: repositoryOrHomepage,
     );
-    if (repository != null) {
-      await panaCache.writeData(cacheType, cacheKey, repository.toJson());
-    }
+    await panaCache.writeData(cacheType, cacheKey, repository.toJson());
     return repository;
   }
 }

lib/src/package_analyzer.dart

@@ -57,7 +57,8 @@ Future<PubspecUrlsWithIssues> checkPubspecUrls(PackageContext context) async {
   // Switch homepage and repository if only homepage is given,
   // and it can be verified as a valid repository.
   final verifiedRepository = await context.repository;
-  final isVerifiedRepository = verifiedRepository?.repository != null;
+  final status = verifiedRepository.status;
+  final isVerifiedRepository = status == RepositoryStatus.verified;
   // We should switch these values if the repository has been verified.
   if (isVerifiedRepository &&
       pubspec.homepage != null &&
@@ -69,7 +70,7 @@ Future<PubspecUrlsWithIssues> checkPubspecUrls(PackageContext context) async {
 
   // Set known issue tracker link in cases where it was not provided.
   if (pubspec.issueTracker == null && isVerifiedRepository) {
-    final vr = verifiedRepository!.repository!;
+    final vr = verifiedRepository.repository!;
     final repoSegments = vr.repository;
     if (RepositoryProvider.isGitHubCompatible(vr.provider) &&
         repoSegments != null) {

lib/src/package_context.dart

@@ -170,7 +170,8 @@ Future<ReportSection> followsTemplate(PackageContext context) async {
     issues.addAll(pubspecUrls.issues);
 
     final repository = await context.repository;
-    if (repository?.verificationFailure != null) {
+    final repositoryStatus = repository.status;
+    if (repositoryStatus == RepositoryStatus.failed) {
       issues.add(Issue('Failed to verify repository URL.',
           suggestion:
               'Please provide a valid [`repository`](https://dart.dev/tools/pub/pubspec#repository) URL in `pubspec.yaml`, such that:\n\n'
@@ -179,7 +180,7 @@ Future<ReportSection> followsTemplate(PackageContext context) async {
               '    * contains `name: ${pubspec.name}`,\n'
               '    * contains a `version` property, and,\n'
               '    * does not contain a `publish_to` property.\n\n'
-              '${repository!.verificationFailure}'));
+              '${repository.verificationFailure ?? 'status: `${repositoryStatus.name}`'}'));
     }
 
     final executableFiles = await context.executablesInBinDirectory;
@@ -202,7 +203,7 @@ Future<ReportSection> followsTemplate(PackageContext context) async {
             issues.every((issue) =>
                 (issue.suggestion ?? '').contains('was unreachable')) &&
             // repository verification succeeded
-            repository?.repository != null;
+            repository.repository != null;
 
     final status = issues.isEmpty
         ? ReportStatus.passed

lib/src/references/pubspec_urls.dart

@@ -18,23 +18,33 @@ import 'git_local_repository.dart';
 const _maxPubspecBytes = 256 * 1024;
 
 /// Returns the repository information for the current package.
-Future<VerifiedRepository?> checkRepository({
+Future<VerifiedRepository> checkRepository({
   required SharedAnalysisContext sharedContext,
   required String packageName,
   required String? sourceUrl,
 }) async {
-  if (sourceUrl == null) {
-    return null;
+  sourceUrl = sourceUrl?.trim();
+  if (sourceUrl == null || sourceUrl.isEmpty) {
+    return VerifiedRepository(
+      status: RepositoryStatus.missing,
+      verificationFailure: 'Repository URL is missing.',
+    );
   }
-  final parsedSourceUrl = Repository.tryParseUrl(sourceUrl);
-  if (parsedSourceUrl == null) {
-    return null;
+  late Repository parsedSourceUrl;
+  try {
+    parsedSourceUrl = Repository.parseUrl(sourceUrl);
+  } on Exception catch (e) {
+    return VerifiedRepository(
+      status: RepositoryStatus.invalid,
+      verificationFailure: e.toString(),
+    );
   }
   var branch = parsedSourceUrl.branch;
   var completed = false;
   String? verificationFailure;
   var localPath = parsedSourceUrl.path;
   String? contributingUrl;
+  RepositoryStatus? status;
 
   Repository repositoryWithPath(String? path) {
     if (path == '' || path == '.') {
@@ -52,18 +62,23 @@ Future<VerifiedRepository?> checkRepository({
   VerifiedRepository result() {
     if (completed && verificationFailure == null) {
       return VerifiedRepository(
+        status: RepositoryStatus.verified,
         repository: repositoryWithPath(localPath),
         contributingUrl: contributingUrl,
       );
     } else {
       return VerifiedRepository(
+        status: status ?? RepositoryStatus.inconclusive,
         verificationFailure: verificationFailure,
       );
     }
   }
 
   void failVerification(String message, [Object? error, StackTrace? st]) {
     verificationFailure = message;
+    if (error == null) {
+      status = RepositoryStatus.failed;
+    }
     log.info(message, error, st);
   }
 
@@ -81,6 +96,7 @@ Future<VerifiedRepository?> checkRepository({
         files.where((path) => p.basename(path) == 'pubspec.yaml').toList();
     if (pubspecFiles.isEmpty) {
       return VerifiedRepository(
+        status: RepositoryStatus.failed,
         verificationFailure:
             'Could not find any `pubspec.yaml` in the repository.',
       );

lib/src/report/template.dart

@@ -80,6 +80,7 @@
   "screenshots": [],
   "result": {
     "homepageUrl": "https://github.com/dart-lang/pub-dev",
+    "repositoryStatus": "failed",
     "licenses": [
       {
         "path": "LICENSE",

lib/src/repository/check_repository.dart

@@ -111,6 +111,7 @@
   "result": {
     "repositoryUrl": "https://github.com/dart-lang/async",
     "issueTrackerUrl": "https://github.com/dart-lang/async/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",

test/goldens/end2end/_dummy_pkg-1.0.0-null-safety.1.json

@@ -188,6 +188,7 @@
   "result": {
     "repositoryUrl": "https://github.com/ryanheise/audio_service/tree/minor/audio_service",
     "issueTrackerUrl": "https://github.com/ryanheise/audio_service/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",

test/goldens/end2end/async-2.11.0.json

@@ -82,6 +82,7 @@
   "result": {
     "repositoryUrl": "https://github.com/agilord/bulma_min",
     "issueTrackerUrl": "https://github.com/agilord/bulma_min/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",

test/goldens/end2end/audio_service-0.18.15.json

@@ -96,6 +96,7 @@
     "homepageUrl": "https://code.makery.ch/library/dart-drag-and-drop/",
     "repositoryUrl": "https://github.com/marcojakob/dart-dnd",
     "issueTrackerUrl": "https://github.com/marcojakob/dart-dnd/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",

test/goldens/end2end/bulma_min-0.7.4.json

@@ -171,6 +171,7 @@
   "result": {
     "repositoryUrl": "https://github.com/inlavigo/gg.git",
     "issueTrackerUrl": "https://github.com/inlavigo/gg/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",

test/goldens/end2end/dnd-2.0.1.json

@@ -116,6 +116,7 @@
   "result": {
     "repositoryUrl": "https://github.com/dart-lang/http",
     "issueTrackerUrl": "https://github.com/dart-lang/http/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",

test/goldens/end2end/gg-1.0.12.json

@@ -91,6 +91,7 @@
   },
   "screenshots": [],
   "result": {
+    "repositoryStatus": "unspecified",
     "licenses": [
       {
         "path": "LICENSE",

test/goldens/end2end/http-0.13.0.json

@@ -75,6 +75,7 @@
   "result": {
     "repositoryUrl": "https://github.com/mitsuoka/mime_type",
     "issueTrackerUrl": "https://github.com/mitsuoka/mime_type/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",

test/goldens/end2end/lints-1.0.0.json

@@ -111,6 +111,7 @@
   "result": {
     "repositoryUrl": "https://github.com/sebastianhaberey/nsd/tree/main/nsd_android",
     "issueTrackerUrl": "https://github.com/sebastianhaberey/nsd/issues",
+    "repositoryStatus": "verified",
     "repository": {
       "provider": "github",
       "host": "github.com",