blob: 180f80517b19c1d07e78e997432890694b40264f [file]
// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
import 'package:collection/collection.dart';
import 'api_declaration.dart';
import 'extensions.dart';
extension ApiLibraryIterableExtension on Iterable<ApiLibrary> {
List<ApiLibrary> sortedByUri(String packageName) => sortedBy(
(library) => UriSortKey(
Uri.parse(library.uri),
packageName,
isExperimental: library.isExperimental,
),
);
}
/// URI categorization used by [UriSortKey].
enum UriCategory {
primaryPublicEntryPoint,
stablePublicEntryPoint,
experimentalPublicEntryPoint,
nonPublicInPackage,
notInPackage,
}
/// Sort key used to sort libraries in the output.
///
/// Libraries in the specified package will be output first:
/// 1. The primary public entry point (`package:<pkg>/<pkg>.dart`, when not
/// `@experimental`)
/// 2. Other stable public entry points (`package:<pkg>/...` outside `src/`)
/// 3. Experimental public entry points (`@experimental`)
/// 4. Non-public libraries in the package (`package:<pkg>/src/...`)
/// 5. Libraries not in the package (`dart:*` and external `package:*`)
final class UriSortKey implements Comparable<UriSortKey> {
final UriCategory _category;
final String _uriString;
UriSortKey(Uri uri, String pkgName, {bool isExperimental = false})
: _category = _categorize(uri, pkgName, isExperimental: isExperimental),
_uriString = uri.toString();
static UriCategory _categorize(
Uri uri,
String pkgName, {
required bool isExperimental,
}) {
if (!uri.isIn(pkgName)) return .notInPackage;
if (!uri.isInPublicLibOf(pkgName)) return .nonPublicInPackage;
if (isExperimental) return .experimentalPublicEntryPoint;
if (uri.isPrimaryPublicLibOf(pkgName)) return .primaryPublicEntryPoint;
return .stablePublicEntryPoint;
}
@override
int compareTo(UriSortKey other) {
if (_category.index.compareTo(other._category.index) case final value
when value != 0) {
return value;
}
return _uriString.compareTo(other._uriString);
}
}