Establish the Koi Swagger parser release

Prepare the OpenAPI parser and Dart generator as a publishable Koi package with CLI entrypoint, docs, examples, tests, and pub.dev release metadata. Constraint: Initial GitHub import follows koi_blueprint_flutter identity mr.koi <i@mrkoi.is>. Rejected: Keep local runtime state in the initial repository | .dart_tool, .omx, and pubspec.lock are ignored for a reusable package source tree. Confidence: high Scope-risk: moderate Directive: Keep generated-output behavior covered by parser and generator tests before changing rendering rules. Tested: dart analyze; dart test; PUB_HOSTED_URL=https://pub.dev dart pub publish --dry-run Not-tested: End-to-end downstream build_runner compilation of generated Retrofit/Freezed output.
2026-06-02 22:00:13 +08:00
commit ea93f09154
24 changed files with 11355 additions and 0 deletions
@@ -0,0 +1,80 @@
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:koi_swagger_parser/koi_swagger_parser.dart';
+
+Future<void> main(List<String> arguments) async {
+  final parser = ArgParser()
+    ..addFlag('help', abbr: 'h', negatable: false, help: '显示帮助信息。');
+
+  final generateParser = ArgParser()
+    ..addFlag('all', abbr: 'a', negatable: false, help: '兼容旧命令格式，当前等价于生成全部资源。')
+    ..addOption('config', abbr: 'c', help: '配置文件路径。')
+    ..addOption('cwd', help: '工作目录。')
+    ..addFlag('dry-run', negatable: false, help: '只解析与渲染，不落盘。')
+    ..addFlag('verbose', abbr: 'v', negatable: false, help: '打印更多诊断信息。');
+  parser.addCommand('generate', generateParser);
+
+  late final ArgResults result;
+  try {
+    result = parser.parse(arguments);
+  } on FormatException catch (error) {
+    stderr.writeln(error.message);
+    stderr.writeln(parser.usage);
+    exitCode = 64;
+    return;
+  }
+
+  if ((result['help'] as bool?) ?? false) {
+    stdout.writeln(_usage(parser));
+    return;
+  }
+
+  final command = result.command;
+  if (command == null || command.name == 'generate') {
+    final commandArgs = command ?? result;
+    await _runGenerate(commandArgs, parser);
+    return;
+  }
+
+  stdout.writeln(_usage(parser));
+}
+
+Future<void> _runGenerate(ArgResults result, ArgParser parser) async {
+  final generator = const KoiSwaggerParser();
+  try {
+    final summary = await generator.generate(
+      configPath: result['config'] as String?,
+      workingDirectory: result['cwd'] as String?,
+      dryRun: result['dry-run'] as bool? ?? false,
+      verbose: result['verbose'] as bool? ?? false,
+    );
+
+    final mode = summary.dryRun ? 'dry-run' : 'written';
+    stdout.writeln(
+      '[koi_swagger_parser] $mode ${summary.writtenFiles.length} file(s), '
+      '${summary.operationsCount} operation(s), '
+      '${summary.modelsCount} model(s).',
+    );
+  } on Object catch (error, stackTrace) {
+    stderr.writeln('[koi_swagger_parser] generation failed: $error');
+    if ((result['verbose'] as bool?) ?? false) {
+      stderr.writeln(stackTrace);
+    } else {
+      stderr.writeln('使用 --verbose 可以查看详细堆栈。');
+    }
+    stderr.writeln(parser.usage);
+    exitCode = 1;
+  }
+}
+
+String _usage(ArgParser parser) {
+  return [
+    'koi_swagger_parser',
+    '',
+    '用法:',
+    '  dart run koi_swagger_parser generate --all',
+    '',
+    parser.usage,
+  ].join('\n');
+}