Merge pull request #280 from robnester-rh/EC-80

EC-80 Document formal spec for EC policy.yaml

.github/workflows/publish-schema.yaml

@@ -0,0 +1,84 @@
+# Copyright 2022 Red Hat, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+---
+name: Publish schema to website
+
+"on":
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - "api/v1alpha1/enterprisecontractpolicy_types.go"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "schema-publish"
+  cancel-in-progress: false
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      - name: Setup Go 1.21.x
+        uses: actions/setup-go@v4
+        with:
+          # Semantic version range syntax or exact version of Go
+          go-version: "1.21.x"
+          cache-dependency-path: schema/go.mod
+
+      - name: Export Schema
+        run: make export-schema
+
+      - name: Upload schema artifact
+        uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
+        with:
+          name: dist
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+    steps:
+      - name: Download schema artifact
+        uses: actions/download-artifact@87c55149d96e628cc2ef7e6fc2aab372015aec85 # v4.1.3
+        with:
+          name: dist
+          path: "schema"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v.3.0.1
+        with:
+          path: "."
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@decdde0ac072f6dcbe43649d82d9c635fff5b4e4 # v4.0.4

.gitignore

@@ -11,6 +11,9 @@ testbin/*
 # Test binary, build with `go test -c`
 *.test
 
+# Dist directory for schema export
+dist/*
+
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
 

Makefile

@@ -8,7 +8,6 @@ ROOT = $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
 CONTROLLER_GEN = go run -modfile $(ROOT)tools/go.mod sigs.k8s.io/controller-tools/cmd/controller-gen
 KUSTOMIZE = go run -modfile $(ROOT)tools/go.mod sigs.k8s.io/kustomize/kustomize/v4
 ENVTEST = go run -modfile $(ROOT)tools/go.mod sigs.k8s.io/controller-runtime/tools/setup-envtest
-
 CRD_DEF = ./api/v1alpha1
 
 # Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
@@ -107,6 +106,9 @@ endif
 docker-push: ## Push docker image with the manager.
 	docker push ${IMG}
 
+.PHONY: export-schema
+export-schema: ## Export the CRD schema to the schema directory as a json-store.org schema.
+	go run -modfile $(ROOT)schema/go.mod schema/export.go $(ROOT)dist github.com/enterprise-contract/enterprise-contract-controller ./api/v1alpha1/
 ##@ Deployment
 
 ifndef ignore-not-found

schema/export.go

@@ -0,0 +1,86 @@
+// Copyright 2024 Red Hat, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path"
+
+	"github.com/enterprise-contract/enterprise-contract-controller/api/v1alpha1"
+	"github.com/invopop/jsonschema"
+	"github.com/spf13/afero"
+)
+
+func main() {
+	// Write the JSON schema to a file location provided
+	if len(os.Args) < 3 {
+		fmt.Printf(`
+Please ensure you've provided the following:
+  * A directory location to write the JSON schema to.
+    The file will be titled schema.json
+  * A repository for the Go source file containing the struct used in schema creation."
+  * The path to the directory containing the Go source file which contains the struct used for schema creation.
+    Example: go run schema/export.go /tmp/enterprise-contract-controller github.com/enterprise-contract/enterprise-contract-controller ./api/v1alpha1/
+
+`)
+		os.Exit(1)
+	}
+	schemaDir := os.Args[1]
+	repo := os.Args[2]
+	sourceFilePath := os.Args[3]
+	fileName := "policy_spec.json"
+	if len(os.Args) == 5 {
+		fileName = os.Args[4]
+	}
+	// Create a JSON schema from a Go type
+	schema, err := JsonSchemaFromPolicySpec(&v1alpha1.EnterpriseContractPolicySpec{}, repo, sourceFilePath)
+	if err != nil {
+		fmt.Println("Error creating JSON schema:", err)
+		os.Exit(1)
+	}
+	// Write the JSON schema to a file location provided
+	err = writeSchemaToFile(schemaDir, schema, fileName)
+	if err != nil {
+		fmt.Println("Error writing JSON schema to file:", err)
+		os.Exit(1)
+	}
+	fmt.Println("JSON schema written to", path.Join(schemaDir, fileName))
+}
+
+// Write the JSON schema to a directory location provided
+func writeSchemaToFile(schemaDir string, schema []byte, fileName string) error {
+	fs := afero.NewOsFs()
+	fs.MkdirAll(schemaDir, 0755)
+	return afero.WriteFile(fs, path.Join(schemaDir, fileName), schema, 0644)
+}
+
+// Create a JSON schema from a Go type, and return the JSON as a byte slice
+func JsonSchemaFromPolicySpec(ecp *v1alpha1.EnterpriseContractPolicySpec, repo, dir string) ([]byte, error) {
+	// Create a JSON schema from a Go type
+	r := new(jsonschema.Reflector)
+	if err := r.AddGoComments(repo, dir); err != nil {
+		return nil, err
+	}
+	schema := r.Reflect(ecp)
+	prettyJSON, err := json.MarshalIndent(schema, "", "  ")
+	if err != nil {
+		return nil, err
+	}
+	return prettyJSON, nil
+}

schema/go.mod

@@ -0,0 +1,34 @@
+module github.com/enterprise-contract/enterprise-contract-controller/schema
+
+go 1.21.4
+
+require (
+	github.com/enterprise-contract/enterprise-contract-controller/api v0.1.35
+	github.com/invopop/jsonschema v0.12.0
+)
+
+require (
+	github.com/bahlo/generic-list-go v0.2.0 // indirect
+	github.com/buger/jsonparser v1.1.1 // indirect
+	github.com/go-logr/logr v1.4.1 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/spf13/afero v1.11.0
+	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
+	golang.org/x/net v0.21.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/apiextensions-apiserver v0.29.2 // indirect
+	k8s.io/apimachinery v0.29.2 // indirect
+	k8s.io/klog/v2 v2.120.1 // indirect
+	k8s.io/utils v0.0.0-20240102154912-e7106e64919e // indirect
+	sigs.k8s.io/controller-runtime v0.17.2 // indirect
+	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
+)