Clean-up and tweaks of the firehose project. (#117)

Cleaned up and reduced RegExp use.
Simplified some functions.
Upped SDK constraint to 3.0.0, to use `firstOrNull` from SDK.
Use a named parameter for optional boolean parameer.
Added documentation to remaining `RegExp`s.
(Always document what a RegExp matches in prose. They are *not* readable or self-explanatory.)

pkgs/firehose/CHANGELOG.md

@@ -1,6 +1,11 @@
+## 0.3.19
+- Clean-up and optimizations.
+- Stop depending on `package:collection` now that SDK 3.0.0 has `firstOrNull`.
+
 ## 0.3.18
 - Add Github workflow for PR health.
 - Refactorings to health workflow.
+- Require Dart `3.0.0`.
 
 ## 0.3.17
 

pkgs/firehose/lib/firehose.dart

@@ -288,18 +288,21 @@ class VerificationResults {
 
  bool get hasError => results.any((r) => r.severity == Severity.error);
 
- String describeAsMarkdown([bool withTag = true]) {
+ String describeAsMarkdown({bool withTag = true}) {
  results.sort((a, b) => Enum.compareByIndex(a.severity, b.severity));
 
  return results.map((r) {
  var sev = r.severity == Severity.error ? '(error) ' : '';
- var tag = r.gitTag == null ? '' : '`${r.gitTag}`';
- var publishReleaseUri = r.publishReleaseUri;
- if (publishReleaseUri != null) {
- tag = '[$tag]($publishReleaseUri)';
- }
+ var tagColumn = '';
+ if (withTag) {
+ var tag = r.gitTag == null ? '' : '`${r.gitTag}`';
+ var publishReleaseUri = r.publishReleaseUri;
+ if (publishReleaseUri != null) {
+ tag = '[$tag]($publishReleaseUri)';
+ }
 
- var tagColumn = withTag ? ' | $tag' : '';
+ tagColumn = ' | $tag';
+ }
  return '| package:${r.package.name} | ${r.package.version} | '
  '$sev${r.message}$tagColumn |';
  }).join('\n');

pkgs/firehose/lib/health.dart

@@ -70,7 +70,7 @@ class Health {
  var markdownTable = '''
 | Package | Version | Status |
 | :--- | ---: | :--- |
-${results.describeAsMarkdown(false)}
+${results.describeAsMarkdown(withTag: false)}
 
 Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.
  ''';

pkgs/firehose/lib/src/changelog.dart

@@ -4,69 +4,79 @@
 
 import 'dart:io';
 
-import 'package:collection/collection.dart';
-
 class Changelog {
+ static const _headerLinePrefix = '## ';
+
  final File file;
 
  Changelog(this.file);
 
  bool get exists => file.existsSync();
 
+ /// Pattern recognizing some SemVer formats.
+ ///
+ /// Accepts:
+ /// > digits '.' digits '.' digits
+ ///
+ /// optionally followed by `-` or `+` character
+ /// and one or more "word characters", which are
+ /// ASCII letters (`a`-`z`, `A`-`Z`), digits (`0`-`9`),
+ /// underscore (`_`) and dollar-sign (`$`).
+ ///
+ /// This is not all complete SemVer version strings,
+ /// since it doesn't allow `.` in the continuation,
+ /// or a `+...` sequence after a `-` sequence.
+ /// It should be enough for the user-cases we need it for
+ /// in this package.
+ static final _versionRegex = RegExp(r'\d+\.\d+\.\d+(?:[\-+]\w+)?');
+
  String? get latestVersion {
  var input = latestHeading;
 
- if (input == null) {
- return null;
+ if (input != null) {
+ var match = _versionRegex.firstMatch(input);
+ if (match != null) {
+ var version = match[0];
+ return version;
+ }
  }
 
- final versionRegex = RegExp(r'[0-9]+\.[0-9]+\.[0-9]+([-\+]\w+)?');
-
- var match = versionRegex.firstMatch(input);
-
- if (match != null) {
- var version = match.group(0);
- return version;
- }
  return null;
  }
 
  String? get latestHeading {
  var sections = _parseSections();
- // Remove all leading "#"
- return sections.firstOrNull?.title.replaceAll(RegExp(r'^#*'), '').trim();
+ var section = sections.firstOrNull;
+ if (section == null) return null;
+ // Remove the leading `_headerLinePrefix`, then trim left-over whitespace.
+ var title = section.title;
+ assert(title.startsWith(_headerLinePrefix));
+ return title.substring(_headerLinePrefix.length).trim();
  }
 
- List<String> get latestChangeEntries {
- var sections = _parseSections();
- return sections.isEmpty ? [] : sections.first.entries;
- }
+ List<String> get latestChangeEntries =>
+ _parseSections().firstOrNull?.entries ?? [];
 
  Iterable<_Section> _parseSections() sync* {
  if (!exists) return;
 
  _Section? section;
 
- for (var line in file.readAsLinesSync().where((line) => line.isNotEmpty)) {
- if (line.startsWith('## ')) {
+ for (var line in file.readAsLinesSync()) {
+ if (line.isEmpty) continue;
+ if (line.startsWith(_headerLinePrefix)) {
  if (section != null) yield section;
 
  section = _Section(line);
- } else if (section != null) {
- section.entries.add(line);
+ } else {
+ section?.entries.add(line);
  }
  }
 
  if (section != null) yield section;
  }
 
- String get describeLatestChanges {
- var buf = StringBuffer();
- for (var entry in latestChangeEntries) {
- buf.writeln(entry);
- }
- return buf.toString();
- }
+ String get describeLatestChanges => latestChangeEntries.join();
 }
 
 class _Section {

pkgs/firehose/lib/src/utils.dart

@@ -25,41 +25,62 @@ Future<int> runCommand(
 
  process.stdout
  .transform(utf8.decoder)
- .transform(LineSplitter())
- .listen((line) => stdout.writeln(' $line'));
+ .transform(const LineSplitter())
+ .listen((line) => stdout
+ ..write(' ')
+ ..writeln(line));
  process.stderr
  .transform(utf8.decoder)
- .transform(LineSplitter())
- .listen((line) => stderr.writeln(' $line'));
+ .transform(const LineSplitter())
+ .listen((line) => stderr
+ ..write(' ')
+ ..writeln(line));
 
  return process.exitCode;
 }
 
 class Tag {
+ /// RegExp matching a version tag at the start of a line.
+ ///
+ /// A version tag is an optional starting seqeuence
+ /// of non-whitespace, which is the package name,
+ /// followed by a `v` and a simplified SemVer version
+ /// number.
+ /// The version number accepted is
+ /// > digits '.' digits '.' digits
+ ///
+ /// and if followed by a `+`, then it includes the
+ /// rest of the line.
  static final RegExp packageVersionTag =
- RegExp(r'^(\S+)-v(\d+\.\d+\.\d+(\+.*)?)');
-
- static final RegExp versionTag = RegExp(r'^v(\d+\.\d+\.\d+(\+.*)?)');
+ RegExp(r'^(?:(\S+)-)?v(\d+\.\d+\.\d+(?:\+.*)?)');
 
+ /// A package version tag.
+ ///
+ /// Is expected to have the format:
+ /// > (package-name)? 'v' SemVer-version
+ ///
+ /// If not, the tag is not [valid], and the [package] and [version]
+ /// will both be `null`.
  final String tag;
 
  Tag(this.tag);
 
  bool get valid => version != null;
 
- String? get package {
- var match = packageVersionTag.firstMatch(tag);
- return match?.group(1);
- }
+ /// The package name before the `v` in the version [tag], if any.
+ ///
+ /// Is `null` if there is no package name before the `v`,
+ /// or if the tag is not [valid].
+ String? get package => packageVersionTag.firstMatch(tag)?[1];
 
- String? get version {
-  var match = packageVersionTag.firstMatch(tag);
-  if (match != null) {
-  return match.group(2);
-  }
-  match = versionTag.firstMatch(tag);
-  return match?.group(1);
- }
+ /// The SemVer version string of the version [tag], if any.
+ ///
+ /// This is the part after the `v` of the [tag] string,
+ /// of the form, which is a major/minor/patch version string
+ /// optionally followed by a `+` and more characters.
+ ///
+ /// Is `null` if the tag is not [valid].
+ String? get version => packageVersionTag.firstMatch(tag)?[2];
 
  @override
  String toString() => tag;

pkgs/firehose/pubspec.yaml

@@ -1,6 +1,6 @@
 name: firehose
 description: A tool to automate publishing of Pub packages from GitHub actions.
-version: 0.3.18
+version: 0.3.19
 repository: https://github.com/dart-lang/ecosystem/tree/main/pkgs/firehose
 
 environment:
@@ -11,7 +11,6 @@ executables:
 
 dependencies:
  args: ^2.3.0
- collection: ^1.17.0
  http: ^0.13.0
  path: ^1.8.0
  pub_semver: ^2.1.0