Merge pull request #4 from matanlurey/pkg-chore

Move pkg/chore into the monorepo.

.github/workflows/package_chore.yaml

@@ -0,0 +1,27 @@
+name: package/chore
+
+on:
+  # Post-submit.
+  push:
+    branches: [ main ]
+
+  # Pre-submit.
+  pull_request:
+    branches: [ main ]
+    paths:
+      - .github/workflows/package_chore.yaml
+      - packages/chore/**
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/chore
+    steps:
+      - uses: actions/[email protected]
+      - uses: dart-lang/[email protected]
+      - run: dart pub get
+      - run: dart format --output none --set-exit-if-changed .
+      - run: dart analyze
+      - run: dart test

README.md

@@ -10,6 +10,7 @@ A wide but independent collection of Dart packages and projects.
 
 | Project | Release | Description |
 |:--------|:--------|:------------|
+| [`chore`](./packages/chore) | [![Pub version for package/chore](https://img.shields.io/pub/v/chore?label=%20)](https://pub.dev/packages/chore) | Opinionated project management. |
 | [`iota`](./packages/iota) | [![Pub version for package/iota](https://img.shields.io/pub/v/iota?label=%20)](https://pub.dev/packages/iota) | Minimalist file system API. |
 | [`jsonut`](./packages/jsonut) | [![Pub version for package/jsonut](https://img.shields.io/pub/v/jsonut?label=%20)](https://pub.dev/packages/jsonut) | Minimal JSON utilities. |
 | [`lore`](./packages/lore) | [![Pub version for package/lore](https://img.shields.io/pub/v/lore?label=%20)](https://pub.dev/packages/lore) | Fast, structured, and idiomatic logging. |

dev/lib/src/generators/package_readme.dart

@@ -33,6 +33,7 @@ String generatePackageReadmeRegion(Package package) {
   // Maintenance status.
   buffer.write(' | ');
   buffer.write(_githubIssues(package.name));
+  buffer.write(' |');
 
   return buffer.toString();
 }

packages/chore/CHANGELOG.md

@@ -0,0 +1,9 @@
+<!-- #region(HEADER) -->
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- #endregion -->

packages/chore/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024 Matan Lurey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/chore/README.md

@@ -0,0 +1,9 @@
+<!-- #region(PACKAGE_README_HEADER) -->
+# `chore`
+
+Opinionated open source project management tools for Dart packages.
+
+| ✅ Health | 🚀 Release | 📝 Docs | ♻️ Maintenance |
+|:----------|:-----------|:--------|:--------------|
+| [![Build status for package/chore](https://github.com/matanlurey/pub.lurey.dev/actions/workflows/package_chore.yaml/badge.svg)](https://github.com/matanlurey/pub.lurey.dev/actions/workflows/package_chore.yaml) | [![Pub version for package/chore](https://img.shields.io/pub/v/chore)](https://pub.dev/packages/chore) | [![Dart documentation for package/chore](https://img.shields.io/badge/dartdoc-reference-blue.svg)](https://pub.dev/documentation/chore) | [![GitHub Issues for package/chore](https://img.shields.io/github/issues/matanlurey/pub.lurey.dev/pkg-chore?label=issues)](https://github.com/matanlurey/pub.lurey.dev/issues?q=is%3Aopen+is%3Aissue+label%3Apkg-chore) |
+<!-- #endregion -->

packages/chore/bin/chore.dart

@@ -0,0 +1,7 @@
+#!/usr/bin/env dart
+
+import 'package:chore/chore.dart';
+
+void main(List<String> args) async {
+  await Chore().run(args);
+}

packages/chore/dart_test.yaml

@@ -0,0 +1,16 @@
+# https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md
+
+presets:
+  # Runs VM-specific tests and captures coverage.
+  coverage:
+    reporter: github
+
+platforms:
+  - vm
+
+fold_stack_frames:
+  except:
+    - checks
+    - test
+    - test_api
+    - stream_channel

packages/chore/lib/chore.dart

@@ -0,0 +1,109 @@
+import 'dart:io' as io;
+
+import 'package:args/args.dart';
+import 'package:args/command_runner.dart';
+import 'package:async/async.dart';
+import 'package:chore/src/coverage.dart';
+import 'package:chore/src/dartdoc.dart';
+import 'package:path/path.dart' as p;
+
+export 'package:chore/src/coverage.dart';
+export 'package:chore/src/dartdoc.dart';
+
+/// A simple task runner.
+final class Chore extends CommandRunner<void> {
+  /// Creates a new instance of [Chore].
+  factory Chore({
+    StringSink? stdout,
+    StringSink? stderr,
+    bool? isCI,
+    Stream<void>? onTerminate,
+  }) {
+    final chore = Chore.withCommands(
+      stdout: stdout,
+      stderr: stderr,
+      isCI: isCI ?? io.Platform.environment['CI'] == 'true',
+      onTerminate: onTerminate,
+      commands: [Dartdoc.new, Coverage.new],
+    );
+    return chore;
+  }
+
+  /// Creates a new instance of [Chore] without any commands.
+  Chore.withCommands({
+    bool isCI = false,
+    StringSink? stdout,
+    StringSink? stderr,
+    Stream<void>? onTerminate,
+    List<Command<void> Function(Chore)> commands = const [],
+  })  : _commands = commands,
+        stdout = stdout ?? io.stdout,
+        stderr = stderr ?? io.stderr,
+        onTerminate = onTerminate ??
+            StreamGroup.merge([
+              io.ProcessSignal.sigint.watch(),
+              io.ProcessSignal.sigterm.watch(),
+            ]),
+        super('chore', 'A simple task runner') {
+    argParser
+      ..addOption(
+        'working-directory',
+        abbr: 'w',
+        help: ''
+            'The working directory for the command. Defaults to the first '
+            'directory containing a pubspec.yaml file, traversing up from the '
+            'current directory.',
+      )
+      ..addFlag(
+        'ci',
+        help: 'Whether the command is running in a CI environment',
+        defaultsTo: _isCI = isCI,
+      );
+  }
+
+  /// The standard output sink.
+  final StringSink stdout;
+
+  /// The standard error sink.
+  final StringSink stderr;
+
+  /// The working directory for the command runner.
+  String get workingDirectory => _workingDirectory;
+  late final String _workingDirectory;
+
+  /// Whether the command runner is running in a CI environment.
+  bool get isCI => _isCI;
+  late bool _isCI;
+
+  /// A stream that emits when the command runner should be terminated.
+  final Stream<void> onTerminate;
+
+  /// Commands to register with the command runner.
+  final List<Command<void> Function(Chore)> _commands;
+
+  @override
+  ArgResults parse(Iterable<String> args) {
+    // Do an initial parse to get required options.
+    final results = super.parse(args.takeWhile((arg) => arg.startsWith('-')));
+    final workingDir = results.option('working-directory');
+    _workingDirectory = p.normalize(workingDir ?? _findWorkingDir());
+    _isCI = results.flag('ci');
+
+    // Now add the commands.
+    for (final command in _commands) {
+      addCommand(command(this));
+    }
+    return super.parse(args);
+  }
+
+  static String _findWorkingDir() {
+    var dir = io.Directory.current;
+    while (!io.File(p.join(dir.path, 'pubspec.yaml')).existsSync()) {
+      if (dir.path == dir.parent.path) {
+        return io.Directory.current.path;
+      }
+      dir = dir.parent;
+    }
+    return dir.path;
+  }
+}

packages/chore/lib/src/coverage.dart

@@ -0,0 +1,99 @@
+import 'dart:io' as io;
+
+import 'package:args/command_runner.dart';
+import 'package:chore/chore.dart';
+import 'package:path/path.dart' as p;
+import 'package:shelf/shelf_io.dart' as shelf_io;
+import 'package:shelf_static/shelf_static.dart';
+
+/// A command to generate a coverage report.
+final class Coverage extends Command<void> {
+  final Chore _chore;
+
+  /// Creates a new coverage command.
+  Coverage(this._chore) {
+    argParser
+      ..addOption(
+        'output',
+        abbr: 'o',
+        help: 'The output directory for the coverage report',
+        defaultsTo: 'coverage',
+      )
+      ..addOption(
+        'format',
+        abbr: 'f',
+        help: 'The format of the coverage report',
+        allowed: ['lcov', 'html'],
+        defaultsTo: _chore.isCI ? 'lcov' : 'html',
+      )
+      ..addOption(
+        'port',
+        abbr: 'p',
+        help: 'Set to a port number to preview the HTML report',
+        defaultsTo: _chore.isCI ? null : '8080',
+      );
+  }
+
+  @override
+  String get name => 'coverage';
+
+  @override
+  String get description => 'Generates a coverage report';
+
+  @override
+  Future<void> run() async {
+    final argResults = this.argResults!;
+    final outputDir = p.join(
+      _chore.workingDirectory,
+      argResults.option('output'),
+    );
+
+    // Generate LCOV.
+    io.stderr.writeln('Generating LCOV in $outputDir...');
+    final testWithCoverage = await io.Process.run('dart', [
+      'run',
+      'coverage:test_with_coverage',
+      '--out=$outputDir',
+      if (argResults.rest.isNotEmpty) ...['--', ...argResults.rest],
+    ]);
+    if (testWithCoverage.exitCode != 0) {
+      _chore.stderr.writeln(testWithCoverage.stderr);
+      io.exitCode = 1;
+      return;
+    }
+
+    // Early exit if the format is LCOV.
+    if (argResults.option('format') != 'html') {
+      return;
+    }
+
+    // Generate HTML.
+    io.stderr.writeln('Generating HTML...');
+    final generateHtml = await io.Process.run('genhtml', [
+      p.join(outputDir, 'lcov.info'),
+      '-o',
+      p.join(outputDir, 'html'),
+    ]);
+    if (generateHtml.exitCode != 0) {
+      _chore.stderr.writeln(generateHtml.stderr);
+      io.exitCode = 1;
+      return;
+    }
+
+    // Preview the HTML report.
+    final handler = createStaticHandler(
+      p.join(outputDir, 'html'),
+      defaultDocument: 'index.html',
+    );
+    final port = int.parse(argResults.option('port')!);
+    final server = await shelf_io.serve(handler, 'localhost', port);
+    _chore.stdout.writeln(
+      'Serving coverage report on '
+      'http://${server.address.host}:${server.port}',
+    );
+
+    // Wait for the command runner to terminate.
+    await _chore.onTerminate.first;
+    await server.close(force: true);
+  }
+}

packages/chore/lib/src/dartdoc.dart

@@ -0,0 +1,75 @@
+import 'dart:io' as io;
+
+import 'package:args/command_runner.dart';
+import 'package:chore/chore.dart';
+import 'package:path/path.dart' as p;
+import 'package:shelf/shelf_io.dart' as shelf_io;
+import 'package:shelf_static/shelf_static.dart';
+
+/// A command to generate dart docs.
+final class Dartdoc extends Command<void> {
+  final Chore _chore;
+
+  /// Creates a new dartdoc command.
+  Dartdoc(this._chore) {
+    argParser
+      ..addOption(
+        'output',
+        abbr: 'o',
+        help: 'The output directory for the dart docs',
+        defaultsTo: p.join('doc', 'api'),
+      )
+      ..addOption(
+        'port',
+        abbr: 'p',
+        help: 'Set to a port number to preview the HTML report',
+        defaultsTo: _chore.isCI ? null : '8080',
+      );
+  }
+
+  @override
+  String get name => 'dartdoc';
+
+  @override
+  String get description => 'Generates dart docs';
+
+  @override
+  Future<void> run() async {
+    final argResults = this.argResults!;
+    final outputDir = p.join(
+      _chore.workingDirectory,
+      argResults.option('output'),
+    );
+
+    // Generate dart docs.
+    io.stderr.writeln('Generating dart docs in $outputDir...');
+    final dartdoc = await io.Process.run('dart', [
+      'doc',
+      '--output',
+      outputDir,
+      if (argResults.rest.isNotEmpty) ...['--', ...argResults.rest],
+    ]);
+    if (dartdoc.exitCode != 0) {
+      _chore.stderr.writeln(dartdoc.stderr);
+      io.exitCode = 1;
+      return;
+    }
+
+    if (argResults.option('port') case final String port) {
+      final handler = createStaticHandler(
+        outputDir,
+        defaultDocument: 'index.html',
+      );
+      final server = await shelf_io.serve(
+        handler,
+        'localhost',
+        int.parse(port),
+      );
+      _chore.stdout.writeln(
+        'Serving dart docs on http://localhost:${server.port}',
+      );
+      await _chore.onTerminate.first;
+      await server.close(force: true);
+    }
+  }
+}