feature: Documentation command

.gitignore

@@ -12,3 +12,8 @@ site
 node_modules/
 package.json
 package-lock.json
+
+# ignore generated doc in tests
+/tests/document/*.md
+# ignore prospective golden files
+/document/testdata/doc/*.golden

docs/documentation.md

@@ -0,0 +1,74 @@
+# Generate Policy Documentations
+
+## Document your policies
+
+OPA has introduced a standard way to document policies called [Metadata](https://www.openpolicyagent.org/docs/latest/policy-language/#metadata). 
+This format allows for structured in code documentation of policies.
+
+```opa
+# METADATA
+# title: My rule
+# description: A rule that determines if x is allowed.
+# authors:
+# - John Doe <[email protected]>
+# entrypoint: true
+allow if {
+  ...
+}
+```
+
+For the generated documentation to make sense your `packages` should be documented with at least the `title` field 
+and `rules` should have both `title` and `description`. This will ensure that no section is empty in your 
+documentations.
+
+## Generate the documentation
+
+In code documentation is great but what we often want it to later generated an actual static reference documentation.
+The `doc` command will retrieve all annotation of a targeted module and generate a markdown documentation for it.
+
+```bash
+conftest doc path/to/policy
+```
+
+## Use your own template
+
+You can override the [default template](../document/resources/document.md) with your own template
+
+```aiignore
+conftest -t template.md path/tp/policies
+```
+
+All annotation are returned as a sorted list of all annotations, grouped by the path and location of their targeted 
+package or rule. For instance using this template
+
+```bash
+{{ range . -}}
+{{ .Path }} has annotations {{ .Annotations }}
+{{ end -}}
+```
+
+for the following module
+
+```yaml
+# METADATA
+# scope: subpackages
+# organizations:
+# - Acme Corp.
+package foo
+---
+# METADATA
+# description: A couple of useful rules
+package foo.bar
+
+# METADATA
+# title: My Rule P
+p := 7
+```
+
+You will obtain the following rendered documentation:
+
+```bash
+data.foo has annotations {"organizations":["Acme Corp."],"scope":"subpackages"}
+data.foo.bar has annotations {"description":"A couple of useful rules","scope":"package"}
+data.foo.bar.p has annotations {"scope":"rule","title":"My Rule P"}
+```

document/document.go

@@ -0,0 +1,34 @@
+package document
+
+import (
+	"fmt"
+	"io"
+)
+
+// GenerateDocument generate a documentation file for a given module
+// A single page is generated for the module located in the indicated directory this includes all package, subpackages
+// and rules of the provided path.
+func GenerateDocument(dir string, tpl string, out io.Writer) error {
+
+	as, err := ParseRegoWithAnnotations(dir)
+	if err != nil {
+		return fmt.Errorf("parse rego annotations: %w", err)
+	}
+
+	sec, err := ConvertAnnotationsToSections(as)
+	if err != nil {
+		return fmt.Errorf("validating annotations: %w", err)
+	}
+
+	var opt []RenderDocumentOption
+	if tpl != "" {
+		opt = append(opt, ExternalTemplate(tpl))
+	}
+
+	err = RenderDocument(out, sec, opt...)
+	if err != nil {
+		return fmt.Errorf("rendering document: %w", err)
+	}
+
+	return nil
+}

document/metadata.go

@@ -0,0 +1,121 @@
+package document
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/open-policy-agent/opa/ast"
+	"github.com/open-policy-agent/opa/loader"
+)
+
+var (
+	ErrNoAnnotations = errors.New("no annotations found")
+)
+
+// ParseRegoWithAnnotations parse the rego in the indicated directory
+func ParseRegoWithAnnotations(directory string) (ast.FlatAnnotationsRefSet, error) {
+	// Recursively find all rego files (ignoring test files), starting at the given directory.
+	result, err := loader.NewFileLoader().
+		WithProcessAnnotation(true).
+		Filtered([]string{directory}, func(_ string, info os.FileInfo, _ int) bool {
+			if strings.HasSuffix(info.Name(), "_test.rego") {
+				return true
+			}
+
+			if !info.IsDir() && filepath.Ext(info.Name()) != ".rego" {
+				return true
+			}
+
+			return false
+		})
+
+	if err != nil {
+		return nil, fmt.Errorf("load rego files: %w", err)
+	}
+
+	compiler, err := result.Compiler()
+	if err != nil {
+		return nil, fmt.Errorf("compile: %w", err)
+	}
+	as := compiler.GetAnnotationSet().Flatten()
+
+	if len(as) == 0 {
+		return nil, ErrNoAnnotations
+	}
+
+	return as, nil
+}
+
+// Document represent a page of the documentation
+type Document []Section
+
+// Section is a sequential piece of documentation comprised of ast.Annotations and some pre-processed fields
+// This struct exist because some fields of ast.Annotations are not easy to manipulate in go-template
+type Section struct {
+	// RegoPackageName is the string representation of ast.Annotations.Path
+	RegoPackageName string
+	// Depth represent title depth for this section (h1, h2, h3, etc.). This values is derived from len(ast.Annotations.RegoPackageName)
+	// and smoothed such that subsequent section only defer by +/- 1
+	Depth int
+	// MarkdownHeading represent the markdown title symbol #, ##, ###, etc. (produced by strings.Repeat("#", depth))
+	MarkdownHeading string
+	// Annotations is the raw metada provided by OPA compiler
+	Annotations *ast.Annotations
+}
+
+// Equal is only relevant for tests and assert that two sections are partially Equal
+func (s Section) Equal(s2 Section) bool {
+	if s.MarkdownHeading == s2.MarkdownHeading &&
+		s.RegoPackageName == s2.RegoPackageName &&
+		s.Annotations.Title == s2.Annotations.Title {
+		return true
+	}
+
+	return false
+}
+
+// ConvertAnnotationsToSections generates a more convenient struct that can be used to generate the doc
+// First concern is to build a coherent title structure; the ideal case is that each package and each rule has a doc,
+// but this is not guaranteed. I couldn't find a way to call `strings.Repeat` inside go-template; thus, the title symbol is
+// directly provided as markdown (#, ##, ###, etc.)
+// Second, the attribute RegoPackageName of ast.Annotations are not easy to use on go-template; thus, we extract it as a string
+func ConvertAnnotationsToSections(as ast.FlatAnnotationsRefSet) (Document, error) {
+
+	var d Document
+	var currentDepth = 0
+	var offset = 1
+
+	for i, entry := range as {
+		// offset at least by one because all path starts with `data.`
+		depth := len(entry.Path) - offset
+
+		// If the user is targeting a submodule we need to adjust the depth an offset base on the first annotation found
+		if i == 0 && depth > 1 {
+			offset = depth
+		}
+
+		// We need to compensate for unexpected jump in depth
+		// otherwise we would start at h3 if no package documentation is present
+		// or jump form h2 to h4 unexpectedly in subpackages
+		if (depth - currentDepth) > 1 {
+			depth = currentDepth + 1
+		}
+
+		currentDepth = depth
+
+		h := strings.Repeat("#", depth)
+		path := strings.TrimPrefix(entry.Path.String(), "data.")
+
+		d = append(d, Section{
+			Depth:           depth,
+			MarkdownHeading: h,
+			RegoPackageName: path,
+			Annotations:     entry.Annotations,
+		})
+	}
+
+	return d, nil
+}