DSL based Migrator API and a Updated Change Model (#6)

Author: bauer-andreas

.github/workflows/build.yml

@@ -20,5 +20,5 @@ jobs:
     uses: Apodini/.github/.github/workflows/build-and-test.yml@main
     with:
       packagename: ApodiniMigrator
-      usexcodebuild: false
+      supportsmacos11: true
       testdocc: false

.github/workflows/pull_request.yml

@@ -18,7 +18,7 @@ jobs:
     uses: Apodini/.github/.github/workflows/build-and-test.yml@main
     with:
       packagename: ApodiniMigrator
-      usexcodebuild: false
+      supportsmacos11: true
       testdocc: false
   reuse_action:
     name: REUSE Compliance Check

.gitignore

@@ -11,7 +11,6 @@
 .idea
 
 # Swift Package Manager
-Package.resolved
 *.xcodeproj
 .swiftpm
 .build/

.swiftlint.yml

@@ -325,17 +325,16 @@ only_rules:
 excluded: # paths to ignore during linting. Takes precedence over `included`.
   - .build
   - .swiftpm
-  - Tests
-  - Sources/ApodiniMigratorCompare/Change/ProviderSupport.swift
-  - Sources/ApodiniMigratorCompare/AnyCodableElement.swift
+  - Sources/RESTMigrator/Resources
+  - Tests/ApodiniMigratorTests/Resources
 
 closure_body_length: # Closure bodies should not span too many lines.
   - 35 # warning - default: 20
   - 35 # error - default: 100
 
 enum_case_associated_values_count: # Number of associated values in an enum case should be low
-  - 5 # warning - default: 5
-  - 5 # error - default: 6
+  - 8 # warning - default: 5
+  - 8 # error - default: 6
 
 file_length: # Files should not span too many lines.
   - 500 # warning - default: 400
@@ -351,18 +350,21 @@ function_parameter_count: # Number of function parameters should be low.
 
 identifier_name:
   excluded: # excluded names
+    - v1
+    - v2
     - id
     - ok
     - or
     - to
+    - at
 
 large_tuple: # Tuples shouldn't have too many members. Create a custom type instead.
   - 2 # warning - default: 2
   - 2 # error - default: 3
 
 line_length: # Lines should not span too many characters.
-  warning: 200 # default: 120
-  error: 200
+  warning: 150 # default: 120
+  error: 150
   ignores_comments: true # default: false
   ignores_urls: true # default: false
   ignores_function_declarations: false # default: false

Package.resolved

@@ -18,81 +18,113 @@ let package = Package(
         .iOS(.v13)
     ],
     products: [
-        // Products define the executables and libraries a package produces, and make them visible to other packages.
-        .library(name: "ApodiniMigratorCore", targets: ["ApodiniMigratorCore"]),
-        .library(name: "ApodiniMigrator", targets: ["ApodiniMigrator"]),
         .library(name: "ApodiniMigratorShared", targets: ["ApodiniMigratorShared"]),
+        .library(name: "ApodiniMigratorCore", targets: ["ApodiniMigratorCore"]),
         .library(name: "ApodiniMigratorClientSupport", targets: ["ApodiniMigratorClientSupport"]),
         .library(name: "ApodiniMigratorCompare", targets: ["ApodiniMigratorCompare"]),
+        .library(name: "ApodiniMigrator", targets: ["ApodiniMigrator"]),
+        .library(name: "RESTMigrator", targets: ["RESTMigrator"]),
         .executable(name: "migrator", targets: ["ApodiniMigratorCLI"])
     ],
     dependencies: [
-        // Dependencies declare other packages that this package depends on.
-        .package(url: "https://github.com/Apodini/ApodiniTypeInformation.git", .upToNextMinor(from: "0.2.0")),
+        .package(url: "https://github.com/Apodini/ApodiniTypeInformation.git", .upToNextMinor(from: "0.3.0")),
         .package(url: "https://github.com/kylef/PathKit.git", from: "1.0.1"),
         .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "0.4.0")),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"),
         .package(url: "https://github.com/omochi/FineJSON.git", from: "1.14.0"),
-        .package(url: "https://github.com/jpsim/Yams.git", from: "4.0.0")
+        .package(url: "https://github.com/jpsim/Yams.git", from: "4.0.0"),
+        .package(url: "https://github.com/apple/swift-collections.git", .upToNextMajor(from: "1.0.0")),
+
+        // testing runtime crashes
+        .package(url: "https://github.com/norio-nomura/XCTAssertCrash.git", from: "0.2.0")
     ],
     targets: [
-        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
-        // Targets can depend on other targets in this package, and on products in packages this package depends on.
+        // The lowest level ApodiniMigrator package providing common API used across several targets, including
+        // common file extensions, encoding and decoding strategies and output formatting
         .target(
-            name: "ApodiniMigratorCore",
+            name: "ApodiniMigratorShared",
             dependencies: [
-                .target(name: "ApodiniMigratorShared"),
-                .product(name: "ApodiniTypeInformation", package: "ApodiniTypeInformation"),
+                .product(name: "PathKit", package: "PathKit"),
+                .product(name: "FineJSON", package: "FineJSON"),
                 .product(name: "Yams", package: "Yams")
             ]
         ),
-        .executableTarget(
-            name: "ApodiniMigratorCLI",
+
+        // The core ApodiniMigrator package. It provides access to the TypeInformation framework and introduces
+        // the generalized API document.
+        .target(
+            name: "ApodiniMigratorCore",
             dependencies: [
-                .target(name: "ApodiniMigrator"),
-                .product(name: "ArgumentParser", package: "swift-argument-parser"),
-                .product(name: "Logging", package: "swift-log")
+                .target(name: "ApodiniMigratorShared"),
+                .product(name: "ApodiniTypeInformation", package: "ApodiniTypeInformation"),
+                .product(name: "Yams", package: "Yams"),
+                .product(name: "OrderedCollections", package: "swift-collections")
             ]
         ),
+
+        // This target provides any necessary interfaces for REST client libraries!
         .target(
             name: "ApodiniMigratorClientSupport",
             dependencies: [
                 .target(name: "ApodiniMigratorCore")
             ]
         ),
+
+        // The Compare target builds upon the Core package containing the generalized MigrationGuide
+        // and all the necessary utilities for the comparison algorithms.
+        .target(
+            name: "ApodiniMigratorCompare",
+            dependencies: [
+                .target(name: "ApodiniMigratorClientSupport")
+            ]
+        ),
+
+        // The Migrator package provides the Migrator Interface. So everything which is required
+        // to build your own Migrator. LibraryStructure generation, Source Code generation, ...
         .target(
             name: "ApodiniMigrator",
             dependencies: [
                 .target(name: "ApodiniMigratorCompare"),
-                .target(name: "ApodiniMigratorClientSupport"),
                 .product(name: "Logging", package: "swift-log")
-            ],
-            resources: [
-                .process("Templates")
             ]
         ),
+
+        // This target packages the REST client library generator and migrator.
+        // Further it contain the template files for the REST client library.
         .target(
-            name: "ApodiniMigratorShared",
+            name: "RESTMigrator",
             dependencies: [
-                .product(name: "PathKit", package: "PathKit"),
-                .product(name: "FineJSON", package: "FineJSON"),
-                .product(name: "Yams", package: "Yams")
+                .target(name: "ApodiniMigrator"),
+                .target(name: "ApodiniMigratorCompare"),
+                .target(name: "ApodiniMigratorClientSupport"),
+                .product(name: "Logging", package: "swift-log")
+            ],
+            resources: [
+                .process("Resources")
             ]
         ),
-        
-        .target(
-            name: "ApodiniMigratorCompare",
+
+        // This target implements the command line interface of the ApodiniMigrator utility.
+        // It offers command to generate and migrate client libraries and a sub command
+        // to compare API documents.
+        .executableTarget(
+            name: "ApodiniMigratorCLI",
             dependencies: [
-                .target(name: "ApodiniMigratorClientSupport")
+                .target(name: "RESTMigrator"),
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                .product(name: "Logging", package: "swift-log")
             ]
         ),
+
+        // The unified test target.
         .testTarget(
             name: "ApodiniMigratorTests",
             dependencies: [
                 "ApodiniMigratorCore",
-                "ApodiniMigrator",
+                "RESTMigrator",
                 "ApodiniMigratorCompare",
-                "ApodiniMigratorClientSupport"
+                "ApodiniMigratorClientSupport",
+                .product(name: "XCTAssertCrash", package: "XCTAssertCrash", condition: .when(platforms: [.macOS]))
             ],
             resources: [
                 .process("Resources")

Package.swift

@@ -20,7 +20,7 @@ SPDX-License-Identifier: MIT
 [![Build and Test](https://github.com/Apodini/ApodiniMigrator/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/Apodini/ApodiniMigrator/actions/workflows/build-and-test.yml)
 [![codecov](https://codecov.io/gh/Apodini/ApodiniMigrator/branch/develop/graph/badge.svg?token=5MMKMPO5NR)](https://codecov.io/gh/Apodini/ApodiniMigrator)
 
-`ApodiniMigrator` is a Swift package that performs several automated tasks, to migrate client applications after a Web Service publishes a new version that contains breaking changes. The tasks include automated generation of an intermediary client library that contains all required components to establish a client-server communication. Furthermore, `ApodiniMigrator` is able to automatically generate a machine-readable migration guide in either `json` or `yaml` format, that describes the changes between two subsequent Web API versions, and includes auxiliary migrating actions. By means of the migration guide, `ApodiniMigrator` can automatically migrate the intermadiary client library, ensuring therefore the compatibility with the new Web API version. It is part of [**Apodini**](https://github.com/Apodini/Apodini), a composable framework to build Web Services in using Swift.
+`ApodiniMigrator` is a Swift package that performs several automated tasks, to migrate client applications after a Web Service publishes a new version that contains breaking changes. The tasks include automated generation of an intermediary client library that contains all required components to establish a client-server communication. Furthermore, `ApodiniMigrator` is able to automatically generate a machine-readable migration guide in either `json` or `yaml` format, that describes the changes between two subsequent Web API versions, and includes auxiliary migrating actions. By means of the migration guide, `ApodiniMigrator` can automatically migrate the intermediary client library, ensuring therefore the compatibility with the new Web API version. It is part of [**Apodini**](https://github.com/Apodini/Apodini), a composable framework to build Web Services in using Swift.
 
 ## Requirements
 
@@ -168,7 +168,7 @@ info org.apodini.migrator : Starting generation of the migration guide...
 info org.apodini.migrator : Migration guide was generated successfully at /path/to/ApodiniMigrator/Resources/ExampleDocuments/migration_guide.json.
 ```
 
-Once the migration guide has been generate, use `migrate` argument to migrate the initial library:
+Once the migration guide has been generated, use `migrate` argument to migrate the initial library:
 
 ```console
 $ ./migrator migrate
@@ -185,7 +185,7 @@ info org.apodini.migrator : Package QONECTIQ was migrated successfully. You can
 ```
 
 ## Contributing
-Contributions to this projects are welcome. Please make sure to read the [contribution guidelines](https://github.com/Apodini/.github/blob/release/CONTRIBUTING.md) first.
+Contributions to the projects are welcome. Please make sure to read the [contribution guidelines](https://github.com/Apodini/.github/blob/release/CONTRIBUTING.md) first.
 
 ## License
 This project is licensed under the MIT License. See [License](https://github.com/Apodini/ApodiniMigrator/blob/develop/LICENSES) for more information.