Merge pull request #1180 from lcarva/EC-109

Add rego-antora-extension

.github/dependabot.yml

@@ -67,6 +67,16 @@ updates:
       all:
         patterns:
           - "*"
+  - package-ecosystem: "npm"
+    directory: "/rego-antora-extension/"
+    schedule:
+      interval: weekly
+      time: '15:00'
+      timezone: Etc/UTC
+    groups:
+      all:
+        patterns:
+          - "*"
   - package-ecosystem: "gomod"
     directory: "/tools/"
     schedule:

.github/workflows/release-antora-extension.yaml

@@ -24,6 +24,7 @@ name: Release Antora extensions
     paths:
       - 'reference-antora-extension/**'
       - 'tekton-task-antora-extension/**'
+      - 'rego-antora-extension/**'
   workflow_dispatch:
 
 permissions:
@@ -38,6 +39,8 @@ jobs:
           if: startsWith(github.event.head_commit.modified, "reference-antora-extension/**")
         - path: 'tekton-task-antora-extension'
           if: startsWith(github.event.head_commit.modified, "tekton-task-antora-extension/**")
+        - path: 'rego-antora-extension'
+          if: startsWith(github.event.head_commit.modified, "rego-antora-extension/**")
 
     runs-on: ubuntu-latest
 

Makefile

@@ -65,6 +65,15 @@ reference-docs: ## Generate reference documentation input YAML files
 # Make sure docs for experimental commands are generated.
 	@EC_EXPERIMENTAL=1 go run internal/documentation/documentation.go -yaml dist/cli-reference
 
+.PHONY: rego-docs
+rego-docs: ## Generate rego documentation input YAML files
+	@mkdir -p dist
+	@rm -rf dist/rego-reference
+	go run internal/evaluator/documentation/documentation.go -yaml dist/rego-reference
+
+.PHONY: generate-docs
+generate-docs: rego-docs reference-docs
+
 .PHONY: clean
 clean: ## Delete build output
 	@rm dist/*

docs/antora.yml

@@ -23,6 +23,6 @@ nav:
 ext:
   collector:
     run:
-      command: make reference-docs
+      command: make generate-docs
     scan:
-      dir: dist/cli-reference
+      dir: dist

docs/modules/ROOT/nav.adoc

@@ -1,3 +1,4 @@
 include::partial$main_nav.adoc[]
 include::partial$cli_nav.adoc[]
-include::partial$tasks_nav.adoc[]
+include::partial$tasks_nav.adoc[]
+include::partial$rego_nav.adoc[]

docs/modules/ROOT/pages/rego.adoc

@@ -0,0 +1,6 @@
+= ec rego functions reference documentation
+
+The EC CLI provides custom rego builtin functions in addition to the
+https://www.openpolicyagent.org/docs/latest/policy-reference/#built-in-functions[default ones].
+
+Use the navigation bar to view the documenation for each function.

docs/modules/ROOT/partials/rego_nav.adoc

@@ -0,0 +1,4 @@
+* xref:rego.adoc[Rego Reference]
+{{#each reference}}
+** xref:{{ path }}[{{ name }}]
+{{/each}}

docs/template/rego.hbs

@@ -0,0 +1,24 @@
+= {{ name }}
+
+{{{ description}}}
+
+== Usage
+
+  {{ decl.result.name }} = {{ name }}({{pluck decl.args 'name' ', '}})
+
+== Parameters
+
+{{#each decl.args}}
+* ``{{ name }}`` (``{{ type }}``): {{ description }}
+{{/each}}
+
+== Return
+
+``{{ decl.result.name }}`` (``{{ decl.result.type }}``): {{ decl.result.description }}
+
+{{#if decl.result.static}}
+The object contains the following attributes:
+
+{{{ describe decl.result 1 }}}
+
+{{/if}}

go.mod

@@ -18,6 +18,7 @@ require (
 	github.com/leanovate/gopter v0.2.9
 	github.com/open-policy-agent/conftest v0.46.0
 	github.com/open-policy-agent/opa v0.58.0
+	github.com/package-url/packageurl-go v0.1.2
 	github.com/qri-io/jsonpointer v0.1.1
 	github.com/qri-io/jsonschema v0.2.1
 	github.com/redhat-appstudio/application-api v0.0.0-20231026192857-89515ad2504f
@@ -33,10 +34,13 @@ require (
 	github.com/tektoncd/pipeline v0.51.0
 	golang.org/x/exp v0.0.0-20231006140011-7918f672742d
 	golang.org/x/net v0.18.0
+	k8s.io/api v0.28.3
+	k8s.io/apiextensions-apiserver v0.28.3
 	k8s.io/apimachinery v0.28.4
 	k8s.io/client-go v0.28.3
 	k8s.io/klog/v2 v2.110.1
 	k8s.io/kube-openapi v0.0.0-20231010175941-2dd684a91f00
+	sigs.k8s.io/controller-runtime v0.16.3
 	sigs.k8s.io/yaml v1.4.0
 )
 
@@ -227,7 +231,6 @@ require (
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.0-rc5 // indirect
 	github.com/opentracing/opentracing-go v1.2.0 // indirect
-	github.com/package-url/packageurl-go v0.1.2 // indirect
 	github.com/pelletier/go-toml/v2 v2.1.0 // indirect
 	github.com/peterh/liner v1.2.2 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
@@ -314,14 +317,11 @@ require (
 	gopkg.in/square/go-jose.v2 v2.6.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/api v0.28.3 // indirect
-	k8s.io/apiextensions-apiserver v0.28.3 // indirect
 	k8s.io/utils v0.0.0-20230726121419-3b25d923346b // indirect
 	knative.dev/pkg v0.0.0-20230718152110-aef227e72ead // indirect
 	muzzammil.xyz/jsonc v1.0.0 // indirect
 	olympos.io/encoding/edn v0.0.0-20201019073823-d3554ca0b0a3 // indirect
 	oras.land/oras-go/v2 v2.3.1 // indirect
-	sigs.k8s.io/controller-runtime v0.16.3 // indirect
 	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
 	sigs.k8s.io/release-utils v0.7.6 // indirect
 	sigs.k8s.io/structured-merge-diff/v4 v4.3.0 // indirect

internal/evaluator/documentation/__snapshots__/documentation_test.snap

@@ -0,0 +1,77 @@
+
+[TestWriteBuiltinsToYAML - 1]
+decl:
+  args:
+  - description: OCI blob reference
+    name: ref
+    type: string
+  result:
+    description: the OCI blob
+    name: blob
+    type: string
+  type: function
+description: Fetch a blob from an OCI registry.
+name: ec.oci.blob
+nondeterministic: true
+
+---
+
+[TestWriteBuiltinsToYAML - 2]
+decl:
+  args:
+  - description: the PURL
+    name: purl
+    type: string
+  result:
+    description: PURL validity
+    name: result
+    type: string
+  type: function
+description: Determine whether or not a given PURL is valid.
+name: ec.purl.is_valid
+
+---
+
+[TestWriteBuiltinsToYAML - 3]
+decl:
+  args:
+  - description: the PURL
+    name: purl
+    type: string
+  result:
+    description: the parsed PURL object
+    name: object
+    static:
+    - key: name
+      value:
+        type: string
+    - key: namespace
+      value:
+        type: string
+    - key: qualifiers
+      value:
+        dynamic:
+          static:
+          - key: key
+            value:
+              type: string
+          - key: value
+            value:
+              type: string
+          type: object
+        type: array
+    - key: subpath
+      value:
+        type: string
+    - key: type
+      value:
+        type: string
+    - key: version
+      value:
+        type: string
+    type: object
+  type: function
+description: Parse a valid PURL into an object.
+name: ec.purl.parse
+
+---

internal/evaluator/documentation/documentation.go

@@ -0,0 +1,71 @@
+// Copyright The Enterprise Contract Contributors
+//
+// 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 (
+	"flag"
+	"fmt"
+	"os"
+	"path"
+	"strings"
+
+	"github.com/open-policy-agent/opa/ast"
+	"sigs.k8s.io/yaml"
+
+	_ "github.com/enterprise-contract/ec-cli/internal/evaluator" // imports EC OPA builtins
+)
+
+const directoryPermissions = 0755
+const filePermissions = 0644
+
+var yamlDir = flag.String("yaml", "", "Location of the generated YAML files")
+
+func main() {
+	flag.Parse()
+
+	if err := writeBultinsToYAML(*yamlDir); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
+
+func writeBultinsToYAML(dir string) error {
+	if (dir) == "" {
+		dir = "rego-docs"
+	}
+
+	if err := os.MkdirAll(dir, directoryPermissions); err != nil {
+		return err
+	}
+
+	for _, builtin := range ast.Builtins {
+		// We only care about the builtins provided by EC.
+		if !strings.HasPrefix(builtin.Name, "ec.") {
+			continue
+		}
+		data, err := yaml.Marshal(builtin)
+		if err != nil {
+			return err
+		}
+
+		filename := path.Join(dir, fmt.Sprintf("%s.yaml", builtin.Name))
+		if err := os.WriteFile(filename, data, filePermissions); err != nil {
+			return err
+		}
+	}
+	return nil
+}

internal/evaluator/documentation/documentation_test.go

@@ -0,0 +1,46 @@
+// Copyright The Enterprise Contract Contributors
+//
+// 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
+
+//go:build unit
+
+package main
+
+import (
+	"io/fs"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/gkampitakis/go-snaps/snaps"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWriteBuiltinsToYAML(t *testing.T) {
+	dir := t.TempDir()
+	err := writeBultinsToYAML(dir)
+	require.NoError(t, err)
+	err = filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		require.NoError(t, err)
+		if d.IsDir() {
+			return nil
+		}
+		contents, err := os.ReadFile(path)
+		require.NoError(t, err)
+		snaps.MatchSnapshot(t, string(contents))
+		return nil
+	})
+	require.NoError(t, err)
+}

internal/evaluator/rego.go

@@ -59,6 +59,15 @@ func registerOCIBlob() {
 	}
 
 	rego.RegisterBuiltin1(&decl, ociBlob)
+	// Due to https://github.com/open-policy-agent/opa/issues/6449, we cannot set a description for
+	// the custom function through the call above. As a workaround we re-register the function with
+	// a declaration that does include the description.
+	ast.RegisterBuiltin(&ast.Builtin{
+		Name:             decl.Name,
+		Description:      "Fetch a blob from an OCI registry.",
+		Decl:             decl.Decl,
+		Nondeterministic: decl.Nondeterministic,
+	})
 }
 
 func registerPURLIsValid() {
@@ -77,6 +86,15 @@ func registerPURLIsValid() {
 	}
 
 	rego.RegisterBuiltin1(&decl, purlIsValid)
+	// Due to https://github.com/open-policy-agent/opa/issues/6449, we cannot set a description for
+	// the custom function through the call above. As a workaround we re-register the function with
+	// a declaration that does include the description.
+	ast.RegisterBuiltin(&ast.Builtin{
+		Name:             decl.Name,
+		Description:      "Determine whether or not a given PURL is valid.",
+		Decl:             decl.Decl,
+		Nondeterministic: decl.Nondeterministic,
+	})
 }
 
 func registerPURLParse() {
@@ -115,6 +133,15 @@ func registerPURLParse() {
 	}
 
 	rego.RegisterBuiltin1(&decl, purlParse)
+	// Due to https://github.com/open-policy-agent/opa/issues/6449, we cannot set a description for
+	// the custom function through the call above. As a workaround we re-register the function with
+	// a declaration that does include the description.
+	ast.RegisterBuiltin(&ast.Builtin{
+		Name:             decl.Name,
+		Description:      "Parse a valid PURL into an object.",
+		Decl:             decl.Decl,
+		Nondeterministic: decl.Nondeterministic,
+	})
 }
 
 const maxBytes = 10 * 1024 * 1024 // 10 MB

rego-antora-extension/.npmrc

@@ -0,0 +1 @@
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}