Merge pull request #276 from wttech/docs-and-hardening

Frontmatter in code metadata + mermaid graphs

Author: krystian-panek-vmltech

README.md

@@ -59,6 +59,7 @@ It works seamlessly across AEM on-premise, AMS, and AEMaaCS environments.
     - [Console](#console)
     - [Content scripts](#content-scripts)
       - [Minimal example](#minimal-example)
+      - [Conditions](#conditions)
       - [Inputs example](#inputs-example)
       - [Outputs example](#outputs-example)
       - [Console \& logging](#console--logging)
@@ -303,6 +304,43 @@ The `doRun()` method contains the actual code to be executed.
 Notice that the script on their own decide when to run without a need to specify any additional metadata. In that way the-sky-is-the-limit. You can run the script once, periodically, or at an exact date and time.
 There are many built-in, ready-to-use conditions available in the `conditions` [service](https://github.com/wttech/acm/blob/main/core/src/main/java/dev/vml/es/acm/core/code/Conditions.java).
 
+#### Conditions
+
+Conditions determine when automatic scripts should execute. The `conditions` [service](https://github.com/wttech/acm/blob/main/core/src/main/java/dev/vml/es/acm/core/code/Conditions.java) provides many useful methods:
+
+- `conditions.always()` - Always execute on every trigger. Most commonly used in console and manual scripts where execution is triggered directly by users.
+- `conditions.never()` - Never execute. Useful for temporarily disabling scripts.
+- `conditions.changed()` - Execute when script content changed or when instance changed after a failure. Automatically retries failed executions after deployments, making it more suitable for production scenarios than `once()`.
+- `conditions.contentChanged()` - Execute when script content changed or when never executed before. Does not consider instance state changes.
+- `conditions.instanceChanged()` - Execute when instance state changed (OSGi bundle checksums changed or ACM bundle restarted). Useful for detecting deployments or restarts.
+- `conditions.retryIfInstanceChanged()` - Execute when instance state changed and previous execution failed. Combines instance change detection with failure retry logic.
+- `conditions.once()` - Execute only once, when never executed before. Does not automatically retry after failures. Works well for initialization scripts that should not be repeated.
+- `conditions.notSucceeded()` - Execute if previous execution wasn't successful. Retries execution until it succeeds, ignoring script content and instance state changes.
+- `conditions.isInstanceAuthor()` / `conditions.isInstancePublish()` - Execute only on specific instance types (author or publish).
+- `conditions.isInstanceRunMode("dev")` - Execute only when instance has specific run mode.
+- `conditions.isInstanceOnPrem()` - Execute only on on-premise AEM instances.
+- `conditions.isInstanceCloud()` - Execute only on cloud-based AEM instances (AEMaaCS).
+- `conditions.isInstanceCloudSdk()` - Execute only on AEM Cloud SDK (local development environment).
+- `conditions.isInstanceCloudContainer()` - Execute only on AEM Cloud Service containers (non-SDK cloud instances).
+
+**Example usage:**
+
+```groovy
+boolean canRun() {
+    return conditions.once()
+}
+
+void doRun() {
+    out.info "Removing deprecated properties from pages..."
+    repo.get("/content/acme").query("n.[sling:resourceType=acme/component/page]").each { page ->
+        page.removeProperty("deprecatedProperty")
+    }
+    out.success "Removed deprecated properties successfully."
+}
+```
+
+For the complete list of available conditions and their behavior, see the [Conditions.java source code](https://github.com/wttech/acm/blob/main/core/src/main/java/dev/vml/es/acm/core/code/Conditions.java).
+
 #### Inputs example
 
 Scripts could accept inputs, which are passed to the script when it is executed.

core/src/main/java/dev/vml/es/acm/core/code/CodeMetadata.java

@@ -1,10 +1,10 @@
 package dev.vml.es.acm.core.code;
 
 import com.fasterxml.jackson.annotation.JsonAnyGetter;
+import dev.vml.es.acm.core.AcmException;
+import dev.vml.es.acm.core.util.YamlUtils;
 import java.io.Serializable;
-import java.util.ArrayList;
 import java.util.LinkedHashMap;
-import java.util.List;
 import java.util.Map;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -18,16 +18,15 @@ public class CodeMetadata implements Serializable {
 
     private static final Logger LOG = LoggerFactory.getLogger(CodeMetadata.class);
 
-    private static final Pattern DOC_COMMENT_PATTERN = Pattern.compile("/\\*\\*([^*]|\\*(?!/))*\\*/", Pattern.DOTALL);
-    private static final Pattern TAG_PATTERN =
-            Pattern.compile("(?m)^\\s*\\*?\\s*@(\\w+)\\s+(.+?)(?=(?m)^\\s*\\*?\\s*@\\w+|\\*/|$)", Pattern.DOTALL);
+    private static final Pattern BLOCK_COMMENT_PATTERN =
+            Pattern.compile("/\\*(?!\\*)([^*]|\\*(?!/))*\\*/", Pattern.DOTALL);
+    private static final Pattern FRONTMATTER_PATTERN =
+            Pattern.compile("^---\\s*\\n(.+?)^---\\s*\\n", Pattern.DOTALL | Pattern.MULTILINE);
     private static final Pattern NEWLINE_AFTER_COMMENT = Pattern.compile("^\\s*\\n[\\s\\S]*");
     private static final Pattern BLANK_LINE_AFTER_COMMENT = Pattern.compile("^\\s*\\n\\s*\\n[\\s\\S]*");
     private static final Pattern IMPORT_OR_PACKAGE_BEFORE =
             Pattern.compile("[\\s\\S]*(import|package)[\\s\\S]*\\n\\s*\\n\\s*$");
-    private static final Pattern FIRST_TAG_PATTERN = Pattern.compile("(?m)^\\s*\\*?\\s*@\\w+");
-    private static final Pattern LEADING_ASTERISK = Pattern.compile("(?m)^\\s*\\*\\s?");
-    private static final Pattern DOC_MARKERS = Pattern.compile("^/\\*\\*|\\*/$");
+    private static final Pattern COMMENT_MARKERS = Pattern.compile("^/\\*|\\*/$");
 
     private Map<String, Object> values;
 
@@ -46,20 +45,21 @@ public static CodeMetadata of(Executable executable) {
 
     public static CodeMetadata parse(String code) {
         if (StringUtils.isNotBlank(code)) {
-            String docComment = findFirstDocComment(code);
-            if (docComment != null) {
-                return new CodeMetadata(parseDocComment(docComment));
+            String blockComment = findFirstBlockComment(code);
+            if (blockComment != null) {
+                return new CodeMetadata(parseBlockComment(blockComment));
             }
         }
         return EMPTY;
     }
 
     /**
-     * Finds first JavaDoc/GroovyDoc comment that's properly separated with blank lines,
-     * or directly attached to describeRun() method.
+     * Finds first block comment that's properly separated with blank lines.
+     * Must be followed by a blank line (not directly attached to code).
+     * Can appear at the start of the file or after import/package statements.
      */
-    private static String findFirstDocComment(String code) {
-        Matcher matcher = DOC_COMMENT_PATTERN.matcher(code);
+    private static String findFirstBlockComment(String code) {
+        Matcher matcher = BLOCK_COMMENT_PATTERN.matcher(code);
 
         while (matcher.find()) {
             String comment = matcher.group();
@@ -72,12 +72,6 @@ private static String findFirstDocComment(String code) {
                 continue;
             }
 
-            String trimmedAfter = afterComment.trim();
-
-            if (trimmedAfter.startsWith("void describeRun()")) {
-                return comment;
-            }
-
             if (!BLANK_LINE_AFTER_COMMENT.matcher(afterComment).matches()) {
                 continue;
             }
@@ -98,63 +92,46 @@ private static String findFirstDocComment(String code) {
     }
 
     /**
-     * Extracts description and @tags from doc comment. Supports multiple values per tag.
+     * Extracts frontmatter (YAML between triple dashes) and description from block comment.
      */
-    private static Map<String, Object> parseDocComment(String docComment) {
+    private static Map<String, Object> parseBlockComment(String blockComment) {
         Map<String, Object> result = new LinkedHashMap<>();
+        if (StringUtils.isBlank(blockComment)) {
+            return result;
+        }
 
-        String content = DOC_MARKERS.matcher(docComment).replaceAll("");
+        String content = COMMENT_MARKERS.matcher(blockComment).replaceAll("").trim();
 
-        // @ at line start (not in email addresses)
-        Matcher firstTagMatcher = FIRST_TAG_PATTERN.matcher(content);
+        Matcher frontmatterMatcher = FRONTMATTER_PATTERN.matcher(content);
+        String description = content;
 
-        if (firstTagMatcher.find()) {
-            int firstTagIndex = firstTagMatcher.start();
-            String description = LEADING_ASTERISK
-                    .matcher(content.substring(0, firstTagIndex))
-                    .replaceAll("")
-                    .trim();
-            if (!description.isEmpty()) {
-                result.put("description", description);
-            }
-        } else {
-            String description =
-                    LEADING_ASTERISK.matcher(content).replaceAll("").trim();
-            if (!description.isEmpty()) {
-                result.put("description", description);
+        if (frontmatterMatcher.find()) {
+            String frontmatter = frontmatterMatcher.group(1);
+            if (frontmatter != null) {
+                result.putAll(parseFrontmatter(frontmatter));
             }
+            description = content.substring(frontmatterMatcher.end());
         }
 
-        Matcher tagMatcher = TAG_PATTERN.matcher(content);
-
-        while (tagMatcher.find()) {
-            String tagName = tagMatcher.group(1);
-            String tagValue = tagMatcher.group(2);
-
-            if (tagValue != null && !tagValue.isEmpty()) {
-                tagValue = LEADING_ASTERISK.matcher(tagValue).replaceAll("").trim();
-
-                if (!tagValue.isEmpty()) {
-                    Object existing = result.get(tagName);
-
-                    if (existing == null) {
-                        result.put(tagName, tagValue);
-                    } else if (existing instanceof List) {
-                        @SuppressWarnings("unchecked")
-                        List<String> list = (List<String>) existing;
-                        list.add(tagValue);
-                    } else {
-                        List<String> list = new ArrayList<>();
-                        list.add((String) existing);
-                        list.add(tagValue);
-                        result.put(tagName, list);
-                    }
-                }
-            }
+        description = description.trim();
+
+        if (!description.isEmpty()) {
+            result.put("description", description);
         }
+
         return result;
     }
 
+    private static Map<String, Object> parseFrontmatter(String frontmatter) {
+        try {
+            @SuppressWarnings("unchecked")
+            Map<String, Object> yamlData = YamlUtils.readFromString(frontmatter, Map.class);
+            return yamlData != null ? yamlData : new LinkedHashMap<>();
+        } catch (Exception e) {
+            throw new AcmException(String.format("Cannot parse frontmatter!\n%s\n", frontmatter), e);
+        }
+    }
+
     @JsonAnyGetter
     public Map<String, Object> getValues() {
         return values;

core/src/test/java/dev/vml/es/acm/core/code/CodeMetadataTest.java

@@ -67,18 +67,25 @@ void shouldParsePageThumbnailScript() throws IOException {
     }
 
     @Test
-    void shouldParseScriptWithoutDocComment() throws IOException {
+    void shouldParseScriptWithoutFrontmatter() throws IOException {
         String code = readScript("automatic/example/ACME-20_once.groovy");
         CodeMetadata metadata = CodeMetadata.parse(code);
 
-        assertTrue(metadata.getValues().isEmpty());
+        assertFalse(metadata.getValues().isEmpty());
+        assertNotNull(metadata.getValues().get("description"));
+        String description = (String) metadata.getValues().get("description");
+        assertTrue(description.contains("conditions.once()"));
     }
 
     @Test
     void shouldParseMultipleAuthors() {
-        String code = "/**\n" + " * @author John Doe\n"
-                + " * @author Jane Smith\n"
-                + " */\n"
+        String code = "/*\n" + "---\n"
+                + "author:\n"
+                + "  - John Doe\n"
+                + "  - Jane Smith\n"
+                + "---\n"
+                + "Multi-author script\n"
+                + "*/\n"
                 + "\n"
                 + "void doRun() {\n"
                 + "    println \"Hello\"\n"
@@ -96,11 +103,13 @@ void shouldParseMultipleAuthors() {
 
     @Test
     void shouldParseCustomTags() {
-        String code = "/**\n" + " * @description Custom script with metadata\n"
-                + " * @version 1.0.0\n"
-                + " * @since 2025-01-01\n"
-                + " * @category migration\n"
-                + " */\n"
+        String code = "/*\n" + "---\n"
+                + "version: 1.0.0\n"
+                + "since: 2025-01-01\n"
+                + "category: migration\n"
+                + "---\n"
+                + "Custom script with metadata\n"
+                + "*/\n"
                 + "\n"
                 + "void doRun() {\n"
                 + "    println \"Hello\"\n"

ui.content.example/src/main/content/jcr_root/conf/acm/settings/script/automatic/example/ACME-100_acl.groovy

@@ -1,9 +1,21 @@
-/**
-  * This script creates content author groups for each tenant-country-language combination.
-  * 
-  * The groups are named in the format: `{tenant}-{country}-{language}-content-authors`.
-  * Each group is granted read, write, and replicate permissions on the corresponding content and DAM paths.
-  */
+/*
+---
+tags: ['security', 'acl']
+schedule: Every hour at 10 minutes past the hour
+---
+Creates content author groups for each tenant-country-language combination.
+
+The groups are named in the format: `{tenant}-{country}-{language}-content-authors`.
+Each group is granted read, write, and replicate permissions on the corresponding content and DAM paths.
+
+```mermaid
+graph LR
+    A[Scan Tenants] --> B[Find Countries]
+    B --> C[Find Languages]
+    C --> D[Create Author Groups]
+    D --> E[Grant Permissions]
+```
+*/
 
 def scheduleRun() {
   return schedules.cron("0 10 * ? * * *") // every hour at minute 10
@@ -14,7 +26,11 @@ boolean canRun() {
 } 
 
 void doRun() {
+  out.info "ACL setup started"
+  
   def tenantPaths = ["/content/acme", "/content/wknd", "/content/we-retail"]
+  def groupsCreated = 0
+  
   for (def tenantRoot : tenantPaths.collect { repo.get(it) }.findAll { it.exists() }) {
     def tenant = tenantRoot.name
     for (def countryRoot : tenantRoot.children().findAll { isRoot(it) }) {
@@ -27,9 +43,12 @@ void doRun() {
           allow { path = "/content/${tenant}/${country}/${language}"; permissions = ["jcr:read", "rep:write", "crx:replicate"] }
           allow { path = "/content/dam/${tenant}/${country}/${language}"; permissions = ["jcr:read", "rep:write", "crx:replicate"] }
         }
+        groupsCreated++
       }
     }
   }
+  
+  out.success "ACL setup completed. Processed ${groupsCreated} content author group(s)."
 }
 
 def isRoot(root) {

ui.content.example/src/main/content/jcr_root/conf/acm/settings/script/automatic/example/ACME-20_once.groovy

@@ -1,7 +1,16 @@
+/*
+A simple demonstration script that executes only once.
+ 
+This script uses `conditions.once()` to ensure it runs exactly one time in the instance's lifetime.
+Useful for one-time initialization tasks that should never be repeated even if failed.
+*/
+
 boolean canRun() {
     return conditions.once()
 }
 
 void doRun() {
+    out.info "One-time task started"
     println("I should run only once!")
+    out.success "One-time task completed"
 }

ui.content.example/src/main/content/jcr_root/conf/acm/settings/script/automatic/example/ACME-21_changed.groovy

@@ -0,0 +1,24 @@
+/*
+---
+version: '1.0'
+---
+A script that executes when content changes or after deployment failures.
+ 
+This script uses `conditions.changed()` to run when:
+- The script content has been modified since last execution, OR
+- The script has never been executed before, OR
+- The instance state changed (deployment/restart) and previous execution failed
+
+This makes it ideal for deployment scenarios where you want to automatically
+retry failed executions after deployments or configuration changes.
+*/
+
+boolean canRun() {
+    return conditions.changed()
+}
+
+void doRun() {
+    out.info "Content update task started"
+    println("I should run when content changes or after failed deployment!")
+    out.success "Content update task completed"
+}

ui.content.example/src/main/content/jcr_root/conf/acm/settings/script/automatic/example/ACME-32_every-day.groovy

@@ -1,3 +1,10 @@
+/*
+A scheduled script that runs daily at 08:00.
+ 
+This script demonstrates cron-based scheduling with `schedules.cron()` and uses
+`conditions.always()` to execute on every scheduled trigger.
+*/
+
 def scheduleRun() {
     return schedules.cron("0 0 8 ? * * *") // at 08:00 every day
 }
@@ -7,5 +14,7 @@ boolean canRun() {
 }
 
 void doRun() {
+    out.info "Daily task started"
     println("I should run every day!")
+    out.success "Daily task completed"
 }