Merge pull request #3462 from hashicorp/f/data-api-differ

New Tool: Data API Differ

.github/workflows/automation-data-api-differ.yaml

@@ -0,0 +1,44 @@
+---
+name: Detect changes to the API Definitions
+on:
+  pull_request_target:
+    paths:
+      - 'api-definitions/**' # to detect changes when the API Definitions are updated
+      - 'tools/data-api/**' # to detect changes when the Data API is updated
+      - 'tools/data-api-differ/**' # to detect changes when the Data API Differ is updated
+      - 'tools/importer-rest-api-specs/**' # to detect changes when the Importer is updated
+    types: ['opened', 'edited']
+
+jobs:
+  detect-changes-to-the-api-definitions:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+        with:
+          go-version: '1.21.3'
+
+      - name: Detect Changes
+        run: |
+          ./scripts/automation-determine-changes-to-api-definitions.sh outputs/
+
+      - name: Post Comment containing Breaking Changes
+        uses: thollander/actions-comment-pull-request@1d3973dc4b8e1399c0620d3f2b1aa5e795465308
+        with:
+          filePath: outputs/breaking-changes.md
+
+      - name: Post Comment containing Changes
+        uses: thollander/actions-comment-pull-request@1d3973dc4b8e1399c0620d3f2b1aa5e795465308
+        with:
+          filePath: outputs/changes.md
+
+      - name: Post Comment with New Static Identifiers
+        uses: thollander/actions-comment-pull-request@1d3973dc4b8e1399c0620d3f2b1aa5e795465308
+        with:
+          filePath: outputs/static-identifiers.md

.github/workflows/unit-test-data-api-differ.yaml

@@ -0,0 +1,27 @@
+---
+name: Data API Differ (Unit Tests)
+on:
+  pull_request:
+    types: ['opened', 'synchronize']
+    paths:
+      - '.github/workflows/**'
+      - 'tools/data-api-differ/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+        with:
+          go-version: '1.21.3'
+
+      - name: run unit tests
+        run: |
+          cd ./tools/data-api-differ
+          make test

.gitignore

@@ -15,6 +15,9 @@ tools/version-bumper/version-bumper
 tools/wrapper-automation/wrapper-automation
 vendor/
 
+# Temp directories
+outputs/
+
 # .net binaries
 [Dd]ebug/
 [Rr]elease/

README.md

@@ -60,6 +60,7 @@ More information on [how to import a new Resource Manager Service/API Version fo
 - `./docs` - contains documentation.
 - `./submodules/msgraph-metadata` - contains the Git Submodule to [the `microsoftgraph/msgraph-metadata` repository](https://github.com/microsoftgraph/msgraph-metadata) - containing the OpenAPI/Swagger definitions for Microsoft Graph.
 - `./submodules/rest-api-specs` - contains the Git Submodule to [the `Azure/azure-rest-api-specs` repository](https://github.com/Azure/azure-rest-api-specs) - containing the OpenAPI/Swagger definitions for Azure Resource Manager.
+- `./tools/data-api-differ` - contains the Data API Differ which detects changes to the API Definitions.
 - `./tools/generator-go-sdk` - contains the Go SDK Generator, pulling information from the Data API.
 - `./tools/generator-terraform` - contains the Terraform Generator, pulling information from the Data API.
 - `./tools/importer-msgraph-metadata` - contains the Importer for the Microsoft Graph API Definitions.

scripts/automation-determine-changes-to-api-definitions.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+
+set -e
+
+DIR="$(cd "$(dirname "$0")" && pwd)/.."
+
+function buildAndInstallDependencies {
+  cd "${DIR}"
+
+  echo "Building and Installing the Data API onto the GOPATH"
+  cd ./tools/data-api
+  go install
+  cd "${DIR}"
+
+  echo "Building and Installing the Data API Differ onto the GOPATH"
+  cd ./tools/data-api-differ
+  go install
+  cd "${DIR}"
+}
+
+function checkoutAPIDefinitionsFromMainInto {
+  local workingDirectory="$1"
+  local existingPandoraDirectory="${DIR}"
+
+  cd "${DIR}"
+
+  echo "Removing any existing directory at ${workingDirectory}.."
+  rm -rf "$workingDirectory"
+
+  echo "Checking out a secondary copy of hashicorp/pandora from this repository.."
+  git clone --depth 1 --branch main "file://$existingPandoraDirectory" "$workingDirectory"
+  cd "$workingDirectory"
+
+  echo "Resetting the secondary working directory"
+  git reset --hard
+  git clean -xdf
+
+  echo "Checking out the 'main' branch in the copy"
+  git checkout main
+
+  echo "Returning to the original working directory.."
+  cd "${DIR}"
+}
+
+function ensureDirectoryExists {
+  local directory="$1"
+
+  echo "Removing any existing directory at ${directory}.."
+  rm -rf "$directory"
+
+  echo "Recreating the directory ${directory}"
+  mkdir -p "${directory}"
+}
+
+function runBreakingChangeDetector {
+  local initialApiDefinitionsDirectory="$1"
+  local updatedApiDefinitionsDirectory="$2"
+  local outputFilePath="$3"
+
+  echo "Detecting Breaking Changes between ${initialApiDefinitionsDirectory} and ${updatedApiDefinitionsDirectory}.."
+  data-api-differ detect-breaking-changes --initial-path="${initialApiDefinitionsDirectory}" --updated-path="${updatedApiDefinitionsDirectory}" --output-file-path="${outputFilePath}"
+}
+
+function runChangeDetector {
+  local initialApiDefinitionsDirectory="$1"
+  local updatedApiDefinitionsDirectory="$2"
+  local outputFilePath="$3"
+
+  echo "Detecting Changes between ${initialApiDefinitionsDirectory} and ${updatedApiDefinitionsDirectory}.."
+  data-api-differ detect-changes --initial-path="${initialApiDefinitionsDirectory}" --updated-path="${updatedApiDefinitionsDirectory}" --output-file-path="${outputFilePath}"
+}
+
+function runStaticIdentifierDetector {
+  local initialApiDefinitionsDirectory="$1"
+  local updatedApiDefinitionsDirectory="$2"
+  local outputFilePath="$3"
+
+  echo "Detecting any new Static Identifiers between ${initialApiDefinitionsDirectory} and ${updatedApiDefinitionsDirectory}.."
+  data-api-differ output-resource-id-segments --initial-path="${initialApiDefinitionsDirectory}" --updated-path="${updatedApiDefinitionsDirectory}" --output-file-path="${outputFilePath}"
+}
+
+function main {
+  local tempDirectory="${TMPDIR}/pandora-from-main"
+  local initialApiDefinitionsDirectory="${DIR}/api-definitions"
+  local updatedApiDefinitionsDirectory="${tempDirectory}/api-definitions"
+  local outputDirectory="$1"
+
+  buildAndInstallDependencies
+  checkoutAPIDefinitionsFromMainInto "$tempDirectory"
+  ensureDirectoryExists "$outputDirectory"
+
+  runBreakingChangeDetector "$initialApiDefinitionsDirectory" "$updatedApiDefinitionsDirectory" "${outputDirectory}/breaking-changes.md"
+  runChangeDetector "$initialApiDefinitionsDirectory" "$updatedApiDefinitionsDirectory" "${outputDirectory}/changes.md"
+  runStaticIdentifierDetector "$initialApiDefinitionsDirectory" "$updatedApiDefinitionsDirectory" "${outputDirectory}/static-identifiers.md"
+}
+
+main "$1"

tools/data-api-differ/.gitignore

@@ -0,0 +1,2 @@
+data-api-differ
+vendor/

tools/data-api-differ/GNUmakefile

@@ -0,0 +1,12 @@
+default: build
+
+build:
+	go build .
+
+fmt:
+	find . -name '*.go' | grep -v vendor | xargs gofmt -s -w
+
+test:
+	go test -v ./...
+
+.PHONY: build fmt test