Improve cron schedule validation and diagnostics (#224)

workflow-parser/src/model/converter/cron.test.ts

@@ -1,4 +1,4 @@
-import {isValidCron, getCronDescription} from "./cron";
+import {isValidCron, getCronDescription, hasCronIntervalLessThan5Minutes} from "./cron";
 
 describe("cron", () => {
   describe("valid cron", () => {
@@ -66,14 +66,54 @@ describe("cron", () => {
 
   describe("getCronDescription", () => {
     it(`Produces a sentence for valid cron`, () => {
-      expect(getCronDescription("0 * * * *")).toEqual(
-        "Runs every hour\n\n" +
-          "Actions schedules run at most every 5 minutes. [Learn more](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#onschedule)"
-      );
+      expect(getCronDescription("0 * * * *")).toEqual("Runs every hour");
     });
 
     it(`Returns nothing for invalid cron`, () => {
       expect(getCronDescription("* * * * * *")).toBeUndefined();
     });
   });
+
+  describe("hasCronIntervalLessThan5Minutes", () => {
+    it("returns true for step expressions with interval < 5 min", () => {
+      expect(hasCronIntervalLessThan5Minutes("*/1 * * * *")).toBe(true);
+      expect(hasCronIntervalLessThan5Minutes("*/4 * * * *")).toBe(true);
+    });
+
+    it("returns false for step expressions with interval >= 5 min", () => {
+      expect(hasCronIntervalLessThan5Minutes("*/5 * * * *")).toBe(false);
+      expect(hasCronIntervalLessThan5Minutes("*/15 * * * *")).toBe(false);
+    });
+
+    it("returns true for comma-separated values with gap < 5 min", () => {
+      expect(hasCronIntervalLessThan5Minutes("0,2,4 * * * *")).toBe(true);
+      expect(hasCronIntervalLessThan5Minutes("0,10,12 * * * *")).toBe(true);
+    });
+
+    it("returns false for comma-separated values with gap >= 5 min", () => {
+      expect(hasCronIntervalLessThan5Minutes("0,10,20 * * * *")).toBe(false);
+      expect(hasCronIntervalLessThan5Minutes("0,30 * * * *")).toBe(false);
+    });
+
+    it("returns true for comma-separated values with wrap-around gap < 5 min", () => {
+      expect(hasCronIntervalLessThan5Minutes("0,58 * * * *")).toBe(true);
+      expect(hasCronIntervalLessThan5Minutes("2,59 * * * *")).toBe(true);
+    });
+
+    it("returns true for * (every minute)", () => {
+      expect(hasCronIntervalLessThan5Minutes("* * * * *")).toBe(true);
+    });
+
+    it("returns true for range expressions (runs every minute in range)", () => {
+      expect(hasCronIntervalLessThan5Minutes("0-4 * * * *")).toBe(true);
+    });
+
+    it("returns false for single value (hourly)", () => {
+      expect(hasCronIntervalLessThan5Minutes("0 * * * *")).toBe(false);
+    });
+
+    it("returns false for invalid cron", () => {
+      expect(hasCronIntervalLessThan5Minutes("invalid")).toBe(false);
+    });
+  });
 });

workflow-parser/src/model/converter/cron.ts

@@ -8,6 +8,78 @@ type Range = {
   names?: Record<string, number>;
 };
 
+/**
+ * Checks if a cron expression specifies an interval shorter than 5 minutes.
+ * GitHub Actions schedules run at most every 5 minutes, so intervals < 5 min won't work as expected.
+ */
+export function hasCronIntervalLessThan5Minutes(cron: string): boolean {
+  if (!isValidCron(cron)) {
+    return false;
+  }
+
+  const parts = cron.split(/ +/);
+  const minutePart = parts[0];
+
+  // Parse the minute field to determine the effective interval
+  return getMinuteInterval(minutePart) < 5;
+}
+
+/**
+ * Gets the minimum interval in minutes between cron executions based on the minute field.
+ * Returns 60 if there's only one execution per hour, otherwise returns the minimum gap.
+ */
+function getMinuteInterval(minutePart: string): number {
+  // Handle step expressions like */1, */3, 0-59/2
+  if (minutePart.includes("/")) {
+    const [, step] = minutePart.split("/");
+    const stepNum = parseInt(step, 10);
+    if (!isNaN(stepNum) && stepNum > 0) {
+      return stepNum;
+    }
+  }
+
+  // Handle comma-separated values like 0,2,4 or 0,1,5,10
+  if (minutePart.includes(",")) {
+    const values = minutePart
+      .split(",")
+      .map(v => parseInt(v, 10))
+      .filter(n => !isNaN(n))
+      .sort((a, b) => a - b);
+    if (values.length >= 2) {
+      let minGap = 60;
+      for (let i = 1; i < values.length; i++) {
+        const gap = values[i] - values[i - 1];
+        if (gap < minGap) {
+          minGap = gap;
+        }
+      }
+      // Check wrap-around gap from last minute to first minute of next hour
+      const wrapGap = values[0] + 60 - values[values.length - 1];
+      if (wrapGap < minGap) {
+        minGap = wrapGap;
+      }
+      return minGap;
+    }
+  }
+
+  // Handle range expressions like 0-4 (runs every minute from 0-4)
+  if (minutePart.includes("-") && !minutePart.includes("/")) {
+    const [start, end] = minutePart.split("-").map(v => parseInt(v, 10));
+    if (!isNaN(start) && !isNaN(end) && end > start) {
+      // A range without step means every minute in that range
+      return 1;
+    }
+  }
+
+  // * means every minute
+  if (minutePart === "*") {
+    return 1;
+  }
+
+  // Single value or unrecognized pattern - assume hourly (60 min interval)
+  return 60;
+}
+
 export function isValidCron(cron: string): boolean {
   // https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
 
@@ -46,11 +118,7 @@ export function getCronDescription(cronspec: string): string | undefined {
   }
 
   // Make first character lowercase
-  let result = "Runs " + desc.charAt(0).toLowerCase() + desc.slice(1);
-  result +=
-    "\n\nActions schedules run at most every 5 minutes." +
-    " [Learn more](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#onschedule)";
-  return result;
+  return "Runs " + desc.charAt(0).toLowerCase() + desc.slice(1);
 }
 
 function validateCronPart(value: string, range: Range, allowSeparators = true): boolean {

workflow-parser/src/model/converter/events.ts

@@ -158,7 +158,7 @@ function convertSchedule(context: TemplateContext, token: SequenceToken): Schedu
         const cron = schedule.value.assertString(`schedule cron`);
         // Validate the cron string
         if (!isValidCron(cron.value)) {
-          context.error(cron, "Invalid cron string");
+          context.error(cron, "Invalid cron expression. Expected format: '* * * * *' (minute hour day month weekday)");
         }
         result.push({cron: cron.value});
       } else {