feat(purge): add --include-locked flag to purge command (#479)

* feat: add --include-locked flag to annotate command

- Add --include-locked flag to annotate command to handle locked manifests/tags
- Skip locked manifests and tags when --include-locked is not set
- Display "x manifests/tags skipped as they are locked" messages
- Update function signatures to include includeLocked parameter and return skip counts
- Add comprehensive test coverage for new functionality
- Update documentation in README.md and CLAUDE.md

* feat: rename --force flag to --include-locked in purge command

- Rename --force flag to --include-locked across the entire codebase
- Update purge command help text and examples
- Update function signatures and parameter names throughout:
  - purgeParams.force -> purgeParams.includeLocked
  - force parameter -> includeLocked parameter
- Update all tests to use new flag name
- Maintain same functionality: unlock locked manifests/tags before deletion

* fix: improve dry run output messages in purge command

Change "Deleting" to "Would delete" in dry run mode to make output less scary and more accurate.

* docs: add warning to readme

Signed-off-by: Dávid Balatoni <[email protected]>

* refactor: change GetUntaggedManifests to return ManifestAttributesBase objects

Changes GetUntaggedManifests function signature from returning []string to
[]acr.ManifestAttributesBase to provide full manifest attributes to callers.
This enables optimization by avoiding extra API calls for manifest attributes
in downstream functions.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* feat: optimize PurgeManifests to use existing manifest attributes

Eliminates extra GetAcrManifestAttributes API call per manifest by using
the manifest attributes already provided by GetUntaggedManifests. This
significantly improves performance when purging many locked manifests
with the --include-locked flag.

Also improves error handling by continuing with deletion attempts even
when unlock operations fail.

* fix: update callers to handle new GetUntaggedManifests return type

Updates purge.go and annotate.go to handle the new ManifestAttributesBase
return type from GetUntaggedManifests. The annotate command converts the
manifest objects to digest strings for compatibility with the existing
Annotate method.

* test: update tests to reflect PurgeManifests optimization

Removes expectation for GetAcrManifestAttributes call in purge_test.go
since the optimization eliminates this API call. The test now correctly
validates that the function works with the manifest attributes already
provided by GetUntaggedManifests.

* test: add tests for --include-locked flag in annotate command

Adds comprehensive tests for the --include-locked flag functionality
in the annotate command, including:
- Test that locked tags are included when flag is set
- Test that locked tags are skipped when flag is not set
- Test that locked untagged manifests are included when flag is set
- Test dry run behavior with locked manifests

Note: Unlike the purge command, annotate does not currently unlock
manifests before annotating them. The tests document the current
behavior of filtering locked manifests.

* fix: uneccessary singleSkippedManifestsCount

* fix: handle HTTP 405 responses gracefully in purger deletion operations

* test: add functional test script

* refactor: move testing scripts to scripts/experimental

* fix: testing README

* test: improve test scripts with hyperfine

* test: faster image generation

* test: image generation fix

* test: use more images by default

* test: no warmups and only run everything once

* test: compare locked and unlocked

---------

Signed-off-by: Dávid Balatoni <[email protected]>
Co-authored-by: Claude <[email protected]>

Author: balcsida

README.md

@@ -208,6 +208,19 @@ acr purge \
     --repository-page-size 10
 ```
 
+#### Include-locked flag
+To delete locked manifests and tags (where deleteEnabled or writeEnabled is false), the `--include-locked` flag should be set. This will unlock them before deletion.
+
+**Warning:** The `--include-locked` flag will unlock and delete images that have been locked for protection. Use this flag with caution as it bypasses the image lock mechanism. For more information about image locking, see [Lock a container image in an Azure container registry](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-image-lock).
+
+```sh
+acr purge \
+    --registry <Registry Name> \
+    --filter <Repository Filter/Name>:<Regex Filter> \
+    --ago 30d \
+    --include-locked
+```
+
 ### Integration with ACR Tasks
 
 To run a locally built version of the ACR-CLI using ACR Tasks follow these steps:

cmd/acr/annotate.go

@@ -52,6 +52,7 @@ type annotateParameters struct {
 	untagged      bool
 	dryRun        bool
 	concurrency   int
+	includeLocked bool
 }
 
 // newAnnotateCmd defines the annotate command
@@ -93,6 +94,8 @@ func newAnnotateCmd(rootParams *rootParameters) *cobra.Command {
 			// In order to print a summary of the annotated tags/manifests, the counters get updated every time a repo is annotated.
 			annotatedTagsCount := 0
 			annotatedManifestsCount := 0
+			skippedTagsCount := 0
+			skippedManifestsCount := 0
 
 			poolSize := annotateParams.concurrency
 			if poolSize <= 0 {
@@ -103,15 +106,15 @@ func newAnnotateCmd(rootParams *rootParameters) *cobra.Command {
 				fmt.Printf("Specified concurrency value too large. Set to maximum value: %d \n", maxPoolSize)
 			}
 			for repoName, tagRegex := range tagFilters {
-				singleAnnotatedTagsCount, err := annotateTags(ctx, acrClient, orasClient, poolSize, loginURL, repoName, annotateParams.artifactType, annotateParams.annotations, tagRegex, annotateParams.filterTimeout, annotateParams.dryRun)
+				singleAnnotatedTagsCount, singleSkippedTagsCount, err := annotateTags(ctx, acrClient, orasClient, poolSize, loginURL, repoName, annotateParams.artifactType, annotateParams.annotations, tagRegex, annotateParams.filterTimeout, annotateParams.dryRun, annotateParams.includeLocked)
 				if err != nil {
 					return fmt.Errorf("failed to annotate tags: %w", err)
 				}
 
 				singleAnnotatedManifestsCount := 0
 				// If the untagged flag is set, then manifests with no tags are also annotated..
 				if annotateParams.untagged {
-					singleAnnotatedManifestsCount, err = annotateUntaggedManifests(ctx, acrClient, orasClient, poolSize, loginURL, repoName, annotateParams.artifactType, annotateParams.annotations, annotateParams.dryRun)
+					singleAnnotatedManifestsCount, err = annotateUntaggedManifests(ctx, acrClient, orasClient, poolSize, loginURL, repoName, annotateParams.artifactType, annotateParams.annotations, annotateParams.dryRun, annotateParams.includeLocked)
 					if err != nil {
 						return fmt.Errorf("failed to annotate manifests: %w", err)
 					}
@@ -120,6 +123,7 @@ func newAnnotateCmd(rootParams *rootParameters) *cobra.Command {
 				// After every repository is annotated, the counters are updated
 				annotatedTagsCount += singleAnnotatedTagsCount
 				annotatedManifestsCount += singleAnnotatedManifestsCount
+				skippedTagsCount += singleSkippedTagsCount
 			}
 
 			// After all repos have been annotated, the summary is printed
@@ -130,6 +134,12 @@ func newAnnotateCmd(rootParams *rootParameters) *cobra.Command {
 				fmt.Printf("\nNumber of annotated tags: %d", annotatedTagsCount)
 				fmt.Printf("\nNumber of annotated manifests: %d\n", annotatedManifestsCount)
 			}
+			if skippedTagsCount > 0 {
+				fmt.Printf("%d tags skipped as they are locked\n", skippedTagsCount)
+			}
+			if skippedManifestsCount > 0 {
+				fmt.Printf("%d manifests skipped as they are locked\n", skippedManifestsCount)
+			}
 			return nil
 		},
 	}
@@ -141,6 +151,7 @@ func newAnnotateCmd(rootParams *rootParameters) *cobra.Command {
 	cmd.Flags().StringSliceVarP(&annotateParams.annotations, "annotations", "a", []string{}, "The configurable annotation key value that can be specified one or more times")
 	cmd.Flags().BoolVar(&annotateParams.untagged, "untagged", false, "If the untagged flag is set, all the manifests that do not have any tags associated to them will also be annotated, except if they belong to a manifest list that contains at least one tag")
 	cmd.Flags().BoolVar(&annotateParams.dryRun, "dry-run", false, "If the dry-run flag is set, no manifest or tag will be annotated. The output would be the same as if they were annotated")
+	cmd.Flags().BoolVar(&annotateParams.includeLocked, "include-locked", false, "If the include-locked flag is set, locked manifests and tags (where writeEnabled is false) will be annotated")
 	cmd.Flags().IntVar(&annotateParams.concurrency, "concurrency", defaultPoolSize, annotatedConcurrencyDescription)
 	cmd.Flags().BoolP("help", "h", false, "Print usage")
 	cmd.MarkFlagRequired("filter")
@@ -160,7 +171,8 @@ func annotateTags(ctx context.Context,
 	annotations []string,
 	tagFilter string,
 	regexpMatchTimeoutSeconds int64,
-	dryRun bool) (int, error) {
+	dryRun bool,
+	includeLocked bool) (int, int, error) {
 
 	if !dryRun {
 		fmt.Printf("\nAnnotating tags for repository: %s\n", repoName)
@@ -170,35 +182,37 @@ func annotateTags(ctx context.Context,
 
 	tagRegex, err := common.BuildRegexFilter(tagFilter, regexpMatchTimeoutSeconds)
 	if err != nil {
-		return -1, err
+		return -1, 0, err
 	}
 
 	lastTag := ""
 	annotatedTagsCount := 0
+	totalSkippedCount := 0
 
 	var annotator *worker.Annotator
 	if !dryRun {
 		// In order to only have a limited amount of http requests, an annotator is used that will start goroutines to annotate tags.
 		annotator, err = worker.NewAnnotator(poolSize, orasClient, loginURL, repoName, artifactType, annotations)
 		if err != nil {
-			return -1, err
+			return -1, 0, err
 		}
 	}
 
 	for {
 		// GetTagsToAnnotate will return an empty lastTag when there are no more tags.
-		manifestsToAnnotate, newLastTag, err := getManifestsToAnnotate(ctx, acrClient, orasClient, loginURL, repoName, tagRegex, lastTag, artifactType, dryRun)
+		manifestsToAnnotate, newLastTag, skippedCount, err := getManifestsToAnnotate(ctx, acrClient, orasClient, loginURL, repoName, tagRegex, lastTag, artifactType, dryRun, includeLocked)
 		if err != nil {
-			return -1, err
+			return -1, 0, err
 		}
 		lastTag = newLastTag
 		count := len(manifestsToAnnotate)
+		totalSkippedCount += skippedCount
 		if count > 0 {
 			if !dryRun {
 				annotated, annotateErr := annotator.Annotate(ctx, manifestsToAnnotate)
 				if annotateErr != nil {
 					annotatedTagsCount += annotated
-					return annotatedTagsCount, annotateErr
+					return annotatedTagsCount, totalSkippedCount, annotateErr
 				}
 			}
 			annotatedTagsCount += count
@@ -207,7 +221,7 @@ func annotateTags(ctx context.Context,
 			break
 		}
 	}
-	return annotatedTagsCount, nil
+	return annotatedTagsCount, totalSkippedCount, nil
 }
 
 // getManifestsToAnnotate gets all manifests that should be annotated according to the filter flag.
@@ -220,38 +234,40 @@ func getManifestsToAnnotate(ctx context.Context,
 	loginURL string,
 	repoName string,
 	filter *regexp2.Regexp,
-	lastTag string, artifactType string, dryRun bool) ([]string, string, error) {
+	lastTag string, artifactType string, dryRun bool, includeLocked bool) ([]string, string, int, error) {
 
 	resultTags, err := acrClient.GetAcrTags(ctx, repoName, "timedesc", lastTag)
 	if err != nil {
 		if resultTags != nil && resultTags.Response.Response != nil && resultTags.StatusCode == http.StatusNotFound {
 			fmt.Printf("%s repository not found\n", repoName)
-			return nil, "", nil
+			return nil, "", 0, nil
 		}
-		return nil, "", err
+		return nil, "", 0, err
 	}
 
 	newLastTag := ""
 	if resultTags != nil && resultTags.TagsAttributes != nil && len(*resultTags.TagsAttributes) > 0 {
 		tags := *resultTags.TagsAttributes
 		manifestsToAnnotate := []string{}
+		skippedCount := 0
 		for _, tag := range tags {
 			matches, err := filter.MatchString(*tag.Name)
 			if err != nil {
 				// The only error that regexp2 will return is a timeout error
-				return nil, "", err
+				return nil, "", 0, err
 			}
 			if !matches {
 				// If a tag does not match the regex then it's not added to the list
 				continue
 			}
 
-			// If a tag is changable, then it is returned as a tag to annotate
-			if *tag.ChangeableAttributes.WriteEnabled {
+			// If a tag is changeable, then it is returned as a tag to annotate
+			// With --include-locked flag, locked tags are also eligible for annotation
+			if includeLocked || *tag.ChangeableAttributes.WriteEnabled {
 				ref := fmt.Sprintf("%s/%s:%s", loginURL, repoName, *tag.Name)
 				skip, err := orasClient.DiscoverLifecycleAnnotation(ctx, ref, artifactType)
 				if err != nil {
-					return nil, "", err
+					return nil, "", 0, err
 				}
 				if !skip {
 					// Only print what would be annotated during a dry-run. Successfully annotated manifests
@@ -261,13 +277,16 @@ func getManifestsToAnnotate(ctx context.Context,
 					}
 					manifestsToAnnotate = append(manifestsToAnnotate, *tag.Digest)
 				}
+			} else {
+				// Tag is locked and --include-locked is not set, skip it
+				skippedCount++
 			}
 		}
 
 		newLastTag = common.GetLastTagFromResponse(resultTags)
-		return manifestsToAnnotate, newLastTag, nil
+		return manifestsToAnnotate, newLastTag, skippedCount, nil
 	}
-	return nil, "", nil
+	return nil, "", 0, nil
 }
 
 // annotateUntaggedManifests annotates all manifests that do not have any tags associated with them except the ones
@@ -278,7 +297,7 @@ func annotateUntaggedManifests(ctx context.Context,
 	poolSize int, loginURL string,
 	repoName string, artifactType string,
 	annotations []string,
-	dryRun bool) (int, error) {
+	dryRun bool, includeLocked bool) (int, error) {
 	if !dryRun {
 		fmt.Printf("Annotating manifests for repository: %s\n", repoName)
 	} else {
@@ -288,7 +307,7 @@ func annotateUntaggedManifests(ctx context.Context,
 	// Contrary to getTagsToAnnotate, getManifests gets all the manifests at once.
 	// This was done because if there is a manifest that has no tag but is referenced by a multiarch manifest that has tags then it
 	// should not be annotated.
-	manifestsToAnnotate, err := common.GetUntaggedManifests(ctx, poolSize, acrClient, repoName, true, nil, dryRun)
+	manifestsToAnnotate, err := common.GetUntaggedManifests(ctx, poolSize, acrClient, repoName, true, nil, dryRun, includeLocked)
 	if err != nil {
 		return -1, err
 	}
@@ -301,14 +320,27 @@ func annotateUntaggedManifests(ctx context.Context,
 		if err != nil {
 			return -1, err
 		}
-		manifestsCount, annotateErr := annotator.Annotate(ctx, manifestsToAnnotate)
+		// Convert ManifestAttributesBase to digest strings for annotator
+		manifestDigests := make([]string, 0, len(manifestsToAnnotate))
+		for _, manifest := range manifestsToAnnotate {
+			if manifest.Digest != nil {
+				manifestDigests = append(manifestDigests, *manifest.Digest)
+			}
+		}
+		manifestsCount, annotateErr := annotator.Annotate(ctx, manifestDigests)
 		if annotateErr != nil {
 			annotatedManifestsCount += manifestsCount
 			return annotatedManifestsCount, annotateErr
 		}
 		annotatedManifestsCount += manifestsCount
 	} else {
 		annotatedManifestsCount = len(manifestsToAnnotate)
+		// In dry run mode, print which manifests would be annotated
+		for _, manifest := range manifestsToAnnotate {
+			if manifest.Digest != nil {
+				fmt.Printf("Would annotate: %s/%s@%s\n", loginURL, repoName, *manifest.Digest)
+			}
+		}
 	}
 
 	return annotatedManifestsCount, nil