ci: add scripts to validate that public API has not changed (#152)

* ci: add scripts to validate that public API has not changed

* ci: install sourcekitten

* ci: setup ssh-agent

* ci: add more info on rememdy

* ci: add documentation + refactor

* ci: add support for ConfidenceProvider in API diff

.github/workflows/ci.yaml

@@ -9,6 +9,22 @@ on:
       - 'main'
 
 jobs:
+  API-diff:
+    strategy:
+      matrix:
+        module: ["ConfidenceProvider", "Confidence"]
+    runs-on: macOS-latest
+    steps:
+    - name: install sourcekitten
+      run: brew install sourcekitten
+    - uses: actions/checkout@v3
+    - name: webfactory/ssh-agent
+      uses: webfactory/[email protected]
+      with:
+        ssh-private-key: ${{ secrets.SDK_REPO_PRIVATE_KEY }}
+    - name: Run public API diff
+      run: scripts/api_diff.sh ${{ matrix.module }}
+
   Tests:
     runs-on: macOS-latest
     steps:

.gitignore

@@ -8,4 +8,5 @@ DerivedData/
 .netrc
 .build
 .mockingbird
-project.json
+project.json
+scripts/raw_api.json

CONTRIBUTING.md

@@ -1,8 +1,8 @@
-## Contributing
+# Contributing
 
 Open the project in Xcode and build by Product -> Build.
 
-### Linting code
+## Linting code
 
 Code is automatically linted during a build in Xcode. If you need to manually lint:
 
@@ -11,15 +11,25 @@ brew install swiftlint
 swiftlint
 ```
 
-### Formatting code
+## Formatting code
 
 You can automatically format your code using:
 
 ```shell
 ./scripts/swift-format
 ```
 
-### Running tests
+## API diffs
+We run a script to make sure that we don't make changes to the public API without intending to.
+The diff script and the script to generate a new "golden api file" uses a tool called [SourceKitten](https://github.com/jpsim/SourceKitten) which can be installed using homebrew (`brew install sourcekitten`).
+
+### The expected workflow is:
+* Write code (that may change the public API).
+* Optionally run `./scripts/api_diff.sh` to detect the api change.
+* Run `./scripts/generate_public_api.sh` -- this will update the file in `./api`.
+* Commit both code and the updated API file in the same commit. 
+
+## Running tests
 
 IT tests require a Confidence client token to reach remote servers. The token can be created on the Confidence portal. 
 The Confidence organization used for IT tests is named `confidence-test` (you may need to request access).

api/ConfidenceProvider_public_api.json

@@ -0,0 +1,43 @@
+[
+  {
+    "className": "ConfidenceFeatureProvider",
+    "apiFunctions": [
+      {
+        "name": "init(confidence:initializationStrategy:)",
+        "declaration": "public convenience init(confidence: Confidence, initializationStrategy: InitializationStrategy = .fetchAndActivate)"
+      },
+      {
+        "name": "initialize(initialContext:)",
+        "declaration": "public func initialize(initialContext: OpenFeature.EvaluationContext?)"
+      },
+      {
+        "name": "onContextSet(oldContext:newContext:)",
+        "declaration": "public func onContextSet(\n    oldContext: OpenFeature.EvaluationContext?,\n    newContext: OpenFeature.EvaluationContext\n)"
+      },
+      {
+        "name": "getBooleanEvaluation(key:defaultValue:context:)",
+        "declaration": "public func getBooleanEvaluation(key: String, defaultValue: Bool, context: EvaluationContext?) throws\n-> OpenFeature.ProviderEvaluation<Bool>"
+      },
+      {
+        "name": "getStringEvaluation(key:defaultValue:context:)",
+        "declaration": "public func getStringEvaluation(key: String, defaultValue: String, context: EvaluationContext?) throws\n-> OpenFeature.ProviderEvaluation<String>"
+      },
+      {
+        "name": "getIntegerEvaluation(key:defaultValue:context:)",
+        "declaration": "public func getIntegerEvaluation(key: String, defaultValue: Int64, context: EvaluationContext?) throws\n-> OpenFeature.ProviderEvaluation<Int64>"
+      },
+      {
+        "name": "getDoubleEvaluation(key:defaultValue:context:)",
+        "declaration": "public func getDoubleEvaluation(key: String, defaultValue: Double, context: EvaluationContext?) throws\n-> OpenFeature.ProviderEvaluation<Double>"
+      },
+      {
+        "name": "getObjectEvaluation(key:defaultValue:context:)",
+        "declaration": "public func getObjectEvaluation(key: String, defaultValue: OpenFeature.Value, context: EvaluationContext?)\nthrows -> OpenFeature.ProviderEvaluation<OpenFeature.Value>"
+      },
+      {
+        "name": "observe()",
+        "declaration": "public func observe() -> AnyPublisher<OpenFeature.ProviderEvent, Never>"
+      }
+    ]
+  }
+]