Dart: إدارة حزم Dart — نظام pub البيئي والتبعية

dependencies:
  http: ^1.2.0       # متوافق مع 1.x، تحديثات طفيفة/إصلاحات آمنة
  args: ^2.4.2        # متوافق مع 2.x
  csv: ^6.0.0         # متوافق مع 6.x

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

name: datapipeline
description: A CLI tool for e-commerce data analytics processing million-level orders
version: 1.0.0
homepage: https://github.com/bob/datapipeline
repository: https://github.com/bob/datapipeline
documentation: https://datapipeline.dev/docs

environment:
  sdk: ^3.0.0

dependencies:
  # تحليل وسائط CLI
  args: ^2.4.2
  # عميل HTTP لاستدعاءات API
  http: ^1.2.0
  # تحليل ملف CSV
  csv: ^6.0.0
  # دعم قاعدة بيانات SQLite
  sqlite3: ^2.4.0
  # أدوات معالجة المسار
  path: ^1.9.0
  # إطار تسجيل
  logging: ^1.2.0
  # تحليل تكوين YAML
  yaml: ^3.1.2

dev_dependencies:
  # إطار الاختبار
  test: ^1.24.0
  # مشغل توليد الكود
  build_runner: ^2.4.0
  # تسلسل JSON
  json_serializable: ^6.7.0
  # قواعد الفحص
  lints: ^3.0.0

dependency_overrides:
  # مؤقت: حل تعارض الإصدار
  # transitive: ^1.0.0

executables:
  datapipeline: datapipeline

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

dependencies:
  # صياغة علامة الإقحام: ^1.2.3 = >=1.2.3 <2.0.0
  package_a: ^1.2.3

  # صياغة النطاق
  package_b: ">=1.2.3 <2.0.0"

  # الحد الأدنى للإصدار
  package_c: ">=1.2.3"

  # أي إصدار (خطير!)
  package_d: any

  # إصدار دقيق
  package_e: "1.2.3"

  # تبعية Git
  package_f:
    git:
      url: https://github.com/user/package_f.git
      ref: main

  # تبعية المسار (التطوير المحلي)
  package_g:
    path: ../package_g

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

# السيناريو: package_a يتطلب http ^0.13.0، package_b يتطلب http ^1.0.0
# هذا تعارض إصدار رئيسي - غير متوافق!

# الحل 1: تحديث package_a إلى إصدار يدعم http ^1.0.0
# الحل 2: استخدام dependency_overrides (ملاذ أخير)
dependencies:
  http: ^1.2.0

dependency_overrides:
  http: ^1.2.0  # فرض إصدار محدد

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

# معايير اختيار حزم خط أنابيب البيانات:
#
# args (نقاط pub: 140/140، إعجابات: 300+)
#   - حزمة فريق Dart الرسمية
#   - API مستقر، موثق جيداً
#   - مثالي لتحليل وسائط CLI
#
# http (نقاط pub: 140/140، إعجابات: 1000+)
#   - حزمة فريق Dart الرسمية
#   - عميل HTTP قياسي
#   - يدعم المعترضات والبث
#
# csv (نقاط pub: 130/140، إعجابات: 100+)
#   - حزمة مجتمعية
#   - يتعامل مع تحليل/كتابة CSV
#   - صيانة نشطة
#
# json_serializable (نقاط pub: 140/140، إعجابات: 500+)
#   - حزمة Google
#   - توليد كود لـ JSON
#   - آمن النوع، متوافق مع AOT

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

dependencies:
  # مستودع git عام
  custom_client:
    git:
      url: https://github.com/bob/custom_client.git
      ref: v1.0.0  # علامة أو فرع أو commit

  # مستودع git خاص (SSH)
  internal_sdk:
    git:
      url: git@github.com:bob/internal_sdk.git
      ref: main

  # مسار محدد داخل مستودع git
  shared_utils:
    git:
      url: https://github.com/bob/monorepo.git
      path: packages/shared_utils
      ref: stable

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

# للتطوير والاختبار المحلي
dependencies:
  core_lib:
    path: ../core_lib

  shared_models:
    path: ./packages/shared_models

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

name: datapipeline
description: E-commerce analytics CLI tool for processing million-level orders
version: 1.0.0

environment:
  sdk: ^3.0.0

dependencies:
  # إطار CLI
  args: ^2.4.2
  # تنسيق إخراج وحدة التحكم
  cli_util: ^0.4.1
  # عميل HTTP
  http: ^1.2.0
  # تحليل CSV
  csv: ^6.0.0
  # تسلسل JSON
  json_annotation: ^4.8.0
  # أدوات المسار
  path: ^1.9.0
  # التسجيل
  logging: ^1.2.0
  # تكوين YAML
  yaml: ^3.1.2

dev_dependencies:
  # الاختبار
  test: ^1.24.0
  # المحاكاة
  mockito: ^5.4.0
  # توليد الكود
  build_runner: ^2.4.0
  json_serializable: ^6.7.0
  # الفحص
  lints: ^3.0.0
  # التغطية
  coverage: ^1.6.0

// ============================================
// عرض إدارة تبعية خط أنابيب البيانات
// يوضح كيفية استخدام التبعيات الرئيسية
// ============================================

import 'package:args/args.dart';
import 'package:path/path.dart' as p;

const String version = '1.0.0';

class DataPipelineCli {
  final ArgParser parser;

  DataPipelineCli()
      : parser = ArgParser()
          ..addFlag('version', abbr: 'v', negatable: false, help: 'Show version')
          ..addFlag('help', abbr: 'h', negatable: false, help: 'Show help')
          ..addOption('input', abbr: 'i', help: 'Input data source')
          ..addOption('output', abbr: 'o', defaultsTo: 'report.json', help: 'Output path')
          ..addOption('format', allowed: ['json', 'csv', 'html'], defaultsTo: 'json')
          ..addFlag('verbose', abbr: 'V', help: 'Verbose logging')
          ..addOption('batch-size', defaultsTo: '10000', help: 'Records per batch');

  Future<void> run(List<String> arguments) async {
    try {
      final results = parser.parse(arguments);

      if (results['help'] as bool) {
        _printHelp();
        return;
      }

      if (results['version'] as bool) {
        print('DataPipeline v$version');
        return;
      }

      final input = results['input'] as String?;
      final output = results['output'] as String;
      final format = results['format'] as String;
      final verbose = results['verbose'] as bool;
      final batchSize = int.parse(results['batch-size'] as String);

      if (input == null) {
        print('Error: --input is required');
        _printHelp();
        return;
      }

      // استخدام حزمة path للمسارات متعددة المنصات
      final inputPath = p.normalize(input);
      final outputPath = p.normalize(output);
      final ext = p.extension(inputPath);

      print('=== DataPipeline v$version ===');
      if (verbose) {
        print('Input:      $inputPath (${ext.isEmpty ? "unknown" : ext})');
        print('Output:     $outputPath');
        print('Format:     $format');
        print('Batch size: $batchSize records');
        print('SDK:        ${_getSdkInfo()}');
      }

      print('Processing: $inputPath → $outputPath ($format)');
    } on FormatException catch (e) {
      print('Argument error: ${e.message}');
      print(parser.usage);
    }
  }

  void _printHelp() {
    print('DataPipeline - E-commerce analytics CLI tool');
    print('');
    print('Usage: datapipeline [options]');
    print(parser.usage);
  }

  String _getSdkInfo() {
    // في مشروع حقيقي، استخدم dart:io Platform
    return 'Dart 3.x';
  }
}

void main(List<String> arguments) async {
  final cli = DataPipelineCli();
  await cli.run(arguments);
}

> **الإخراج:** شغّل في DartPad محلي أو عبر `dart run`. جميع الأمثلة في دورة Dart هذه مبنية على Dart 3.x / Flutter 3.x. قد تختلف النتائج قليلاً حسب إصدار SDK.

=== DataPipeline v1.0.0 ===
Input:      orders.csv (.csv)
Output:     report.json
Format:     json
Batch size: 10000 records
SDK:        Dart 3.x
Processing: orders.csv → report.json (json)