Skip to content

docs: document cronstrue/croniter divergence guard in components AGENTS.md#22422

Draft
github-actions[bot] wants to merge 1 commit into
mainfrom
claude/update-agents-md-b97b6a5
Draft

docs: document cronstrue/croniter divergence guard in components AGENTS.md#22422
github-actions[bot] wants to merge 1 commit into
mainfrom
claude/update-agents-md-b97b6a5

Conversation

@github-actions

@github-actions github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Automated AGENTS.md update triggered by commit b97b6a5.

This PR was generated by Claude Code analyzing the diff from the latest push to main and updating any stale AGENTS.md files.

Why this belongs in AGENTS.md
Path: ui-v2/src/components/AGENTS.md

Proposed text:
## Cron Expression Divergence

`cronstrue.toString()` can successfully describe cron expressions that behave differently on the server, which schedules on `croniter` (e.g., slash-steps starting at a field's max value like `23/6 * * *`, equal low/high ranges, or 6-field crons). Guard any cron string from user input or the API with `divergesFromServerCron()` from `@/components/ui/cron-input` before trusting `cronstrue` output — reject on input forms, but fall back to rendering the raw cron string when displaying an already-saved schedule.

Non-obvious evidence: `cronstrue` is a third-party parser with looser semantics than the server's `croniter`-based executor. A form could accept and humanize a cron string (e.g. `0 23/6 * * *`) that `cronstrue` describes plausibly but that the server actually executes on a different cadence than described. This mismatch is not visible from reading any single file — it only appears when comparing `cronstrue`'s parsing rules against the server's croniter semantics, which the new `divergesFromServerCron()` helper encodes.

Cross-cutting scope: The helper is already consumed by three independent call sites across two component subtrees (`components/ui/cron-input`, `components/deployments/deployment-schedules/get-schedule-title.ts`, `components/ui/schedule-badge`) with two different usage patterns (reject on input vs. fall back to raw text on display). Any future component that renders or validates a cron string sourced from user input or the API needs to apply the same guard, making this a recurring cross-file contract rather than a one-off fix.

Why not code comment/docstring: The invariant spans three separate files/directories that don't import each other directly (input form, title formatter, badge). A comment in `utils.ts` (which already has one) only reaches a reader who happens to open that file; it doesn't warn a future contributor adding a fourth cron-rendering call site elsewhere in `components/` before they've discovered the helper exists.

Durability: The underlying gap between `cronstrue`'s parser and the server's `croniter` scheduler is a permanent characteristic of the two libraries, not tied to this specific PR's fix. The guidance remains correct and actionable for any future cron-display code, long after the triggering diff is old.

Counter-evidence checked: Read `utils.ts` (has a short block comment describing the guard mechanics, but not the "why guard at all" cross-file contract), `cron-input.tsx`, `get-schedule-title.ts`, and `schedule-badge/index.tsx` to confirm the two distinct usage patterns (reject vs. fallback-to-raw). Checked existing `ui-v2/src/components/AGENTS.md` and `ui-v2/AGENTS.md` for any prior mention of cron handling — none existed.

Changed files in triggering push
ui-v2/src/components/deployments/deployment-schedules/deployment-schedule-dialog/cron-schedule-form.test.tsx
ui-v2/src/components/deployments/deployment-schedules/deployment-schedule-dialog/cron-schedule-form.tsx
ui-v2/src/components/deployments/deployment-schedules/get-schedule-title.test.ts
ui-v2/src/components/deployments/deployment-schedules/get-schedule-title.ts
ui-v2/src/components/ui/cron-input/cron-input.test.tsx
ui-v2/src/components/ui/cron-input/cron-input.tsx
ui-v2/src/components/ui/cron-input/index.ts
ui-v2/src/components/ui/cron-input/utils.ts
ui-v2/src/components/ui/schedule-badge/index.tsx
ui-v2/src/components/ui/schedule-badge/schedule-badge.test.tsx

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

0 participants