feat(#1512): remove abandoned generated documentation files

docs/modules/ROOT/pages/collect-keyless-params.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = collect-keyless-params
 
 Version: 0.1

docs/modules/ROOT/pages/ec.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec
 
 Conforma CLI

docs/modules/ROOT/pages/ec_compare.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec compare
 
 Compare two Conforma Policy specs for equivalence

docs/modules/ROOT/pages/ec_fetch.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec fetch
 
 Fetch remote resources

docs/modules/ROOT/pages/ec_fetch_policy.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec fetch policy
 
 Fetch policy rules from a git repository or other source

docs/modules/ROOT/pages/ec_init.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec init
 
 Initialize a directory for use

docs/modules/ROOT/pages/ec_init_policies.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec init policies
 
 Initialize a directory with minimal EC scaffolding

docs/modules/ROOT/pages/ec_inspect.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec inspect
 
 Inspect policy rules

docs/modules/ROOT/pages/ec_inspect_policy-data.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec inspect policy-data
 
 Read policy data from source urls and displays the data

docs/modules/ROOT/pages/ec_inspect_policy.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec inspect policy
 
 Read policies from source urls and show information about the rules inside them

docs/modules/ROOT/pages/ec_oci_blob.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.blob
 
 Fetch a blob from an OCI registry.

docs/modules/ROOT/pages/ec_oci_blob_files.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.blob_files
 
 Fetch structured files (YAML or JSON) from within a blob tar archive.

docs/modules/ROOT/pages/ec_oci_descriptor.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.descriptor
 
 Fetch a raw Image from an OCI registry.

docs/modules/ROOT/pages/ec_oci_image_files.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.image_files
 
 Fetch structured files (YAML or JSON) from within an image.

docs/modules/ROOT/pages/ec_oci_image_index.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.image_index
 
 Fetch an Image Index from an OCI registry.

docs/modules/ROOT/pages/ec_oci_image_manifest.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.image_manifest
 
 Fetch an Image Manifest from an OCI registry.

docs/modules/ROOT/pages/ec_oci_image_manifests.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.image_manifests
 
 Fetch Image Manifests from an OCI registry in parallel.

docs/modules/ROOT/pages/ec_oci_image_referrers.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.image_referrers
 
 Discover artifacts attached to an image via OCI Referrers API.

docs/modules/ROOT/pages/ec_oci_image_tag_refs.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.image_tag_refs
 
 Discover artifacts attached to an image via legacy tag-based discovery (cosign .sig, .att, .sbom suffixes).

docs/modules/ROOT/pages/ec_oci_parsed_blob.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.oci.parsed_blob
 
 Fetch a blob from an OCI registry and return the parsed JSON value. Results are cached per component.

docs/modules/ROOT/pages/ec_opa.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa
 
 Open Policy Agent (OPA) (embedded)

docs/modules/ROOT/pages/ec_opa_bench.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa bench
 
 Benchmark a Rego query

docs/modules/ROOT/pages/ec_opa_build.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa build
 
 Build an OPA bundle

docs/modules/ROOT/pages/ec_opa_capabilities.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa capabilities
 
 Print the capabilities of OPA

docs/modules/ROOT/pages/ec_opa_check.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa check
 
 Check Rego source files

docs/modules/ROOT/pages/ec_opa_deps.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa deps
 
 Analyze Rego query dependencies

docs/modules/ROOT/pages/ec_opa_eval.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa eval
 
 Evaluate a Rego query

docs/modules/ROOT/pages/ec_opa_exec.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa exec
 
 Execute against input files

docs/modules/ROOT/pages/ec_opa_fmt.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa fmt
 
 Format Rego source files

docs/modules/ROOT/pages/ec_opa_inspect.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa inspect
 
 Inspect OPA bundle(s)

docs/modules/ROOT/pages/ec_opa_parse.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa parse
 
 Parse Rego source file

docs/modules/ROOT/pages/ec_opa_run.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa run
 
 Start OPA in interactive or server mode

docs/modules/ROOT/pages/ec_opa_sign.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa sign
 
 Generate an OPA bundle signature

docs/modules/ROOT/pages/ec_opa_test.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa test
 
 Execute Rego test cases

docs/modules/ROOT/pages/ec_opa_version.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec opa version
 
 Print the version of OPA

docs/modules/ROOT/pages/ec_purl_is_valid.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.purl.is_valid
 
 Determine whether or not a given PURL is valid.

docs/modules/ROOT/pages/ec_purl_parse.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.purl.parse
 
 Parse a valid PURL into an object.

docs/modules/ROOT/pages/ec_sigstore.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec sigstore
 
 Perform certain sigstore operations

docs/modules/ROOT/pages/ec_sigstore_initialize.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec sigstore initialize
 
 Initializes Sigstore root to retrieve trusted certificate and key targets for verification

docs/modules/ROOT/pages/ec_sigstore_verify_attestation.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.sigstore.verify_attestation
 
 Use sigstore to verify the attestation of an image.

docs/modules/ROOT/pages/ec_sigstore_verify_image.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec.sigstore.verify_image
 
 Use sigstore to verify the signature of an image.

docs/modules/ROOT/pages/ec_test.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec test
 
 Test your configuration files using Open Policy Agent

docs/modules/ROOT/pages/ec_track.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec track
 
 Record resource references for tracking purposes

docs/modules/ROOT/pages/ec_track_bundle.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec track bundle
 
 Record tracking information about Tekton bundles

docs/modules/ROOT/pages/ec_validate.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec validate
 
 Validate conformance with the provided policies

docs/modules/ROOT/pages/ec_validate_image.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec validate image
 
 Validate conformance of container images with the provided policies

docs/modules/ROOT/pages/ec_validate_input.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec validate input
 
 Validate arbitrary JSON or yaml file input conformance with the provided policies

docs/modules/ROOT/pages/ec_validate_policy.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec validate policy
 
 Validate the provided EnterpriseContractPolicy spec

docs/modules/ROOT/pages/ec_validate_vsa.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec validate vsa
 
 Validate VSA (Verification Summary Attestation)

docs/modules/ROOT/pages/ec_version.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec version
 
 Print version information

docs/modules/ROOT/pages/rego_builtins.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec rego functions reference documentation
 
 The EC CLI provides custom rego builtin functions in addition to the

docs/modules/ROOT/pages/verify-conforma-konflux-ta.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = verify-conforma-konflux-ta
 
 Version: 0.1

docs/modules/ROOT/pages/verify-enterprise-contract.adoc

@@ -1,3 +1,4 @@
+// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = verify-enterprise-contract
 
 Version: 0.1

internal/documentation/asciidoc/asciidoc.go

@@ -17,25 +17,105 @@
 package asciidoc
 
 import (
-	_ "embed"
+	"bufio"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
 
 	"github.com/conforma/cli/internal/documentation/asciidoc/cli"
 	"github.com/conforma/cli/internal/documentation/asciidoc/rego"
 	"github.com/conforma/cli/internal/documentation/asciidoc/tekton"
 )
 
+// GeneratedMarker is the comment placed at the top of generated Asciidoc files
+// to distinguish them from handwritten documentation.
+const GeneratedMarker = "// Generated by conforma CLI documentation tooling. DO NOT EDIT."
+
 func GenerateAsciidoc(module string) error {
-	if err := cli.GenerateCommandLineDocumentation(module); err != nil {
+	var generated []string
+
+	cliGenerated, err := cli.GenerateCommandLineDocumentation(module)
+	if err != nil {
+		return err
+	}
+	generated = append(generated, cliGenerated...)
+
+	regoGenerated, err := rego.GenerateRegoReference(module)
+	if err != nil {
 		return err
 	}
+	generated = append(generated, regoGenerated...)
 
-	if err := rego.GenerateRegoReference(module); err != nil {
+	tektonGenerated, err := tekton.GenerateTektonDocumentation(module)
+	if err != nil {
 		return err
 	}
+	generated = append(generated, tektonGenerated...)
 
-	if err := tekton.GenerateTektonDocumentation(module); err != nil {
+	if err := removeAbandonedPages(module, generated); err != nil {
 		return err
 	}
 
 	return nil
 }
+
+// removeAbandonedPages removes generated Asciidoc page files that were not
+// produced in the current generation run. A file is considered generated if its
+// first line matches the GeneratedMarker. Handwritten files are left untouched.
+func removeAbandonedPages(module string, generated []string) error {
+	generatedSet := make(map[string]struct{}, len(generated))
+	for _, p := range generated {
+		generatedSet[p] = struct{}{}
+	}
+
+	pagesDir := filepath.Join(module, "pages")
+	entries, err := os.ReadDir(pagesDir)
+	if err != nil {
+		return fmt.Errorf("reading pages directory %q: %w", pagesDir, err)
+	}
+
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".adoc") {
+			continue
+		}
+
+		path := filepath.Join(pagesDir, entry.Name())
+		if _, ok := generatedSet[path]; ok {
+			// File was just generated, keep it.
+			continue
+		}
+
+		isGenerated, err := hasGeneratedMarker(path)
+		if err != nil {
+			return fmt.Errorf("checking generated marker in %q: %w", path, err)
+		}
+		if !isGenerated {
+			// Handwritten file, leave it alone.
+			continue
+		}
+
+		if err := os.Remove(path); err != nil {
+			return fmt.Errorf("removing abandoned file %q: %w", path, err)
+		}
+	}
+
+	return nil
+}
+
+// hasGeneratedMarker reports whether the first line of the file matches
+// GeneratedMarker.
+func hasGeneratedMarker(path string) (bool, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return false, err
+	}
+	defer f.Close()
+
+	scanner := bufio.NewScanner(f)
+	if scanner.Scan() {
+		return scanner.Text() == GeneratedMarker, nil
+	}
+
+	return false, scanner.Err()
+}