cronphase 0.2.1__tar.gz

cronphase-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cronphase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cronphase-0.2.1/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: cronphase
+Version: 0.2.1
+Summary: Fleet-wide cron thundering-herd analyzer & deterministic phase-shift compiler
+Author: cronphase contributors
+License: MIT
+Keywords: cron,crontab,kubernetes,devops,sre,scheduler,thundering-herd
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# `cronphase` — Fleet-Wide Cron Thundering-Herd Oscilloscope & Phase-Shift Compiler
+
+> **Why does your database CPU spike to 100% at `00:00`, `:00`, and `:15` every day?**
+> Because humans write `0 * * * *`, `*/5 * * * *`, `*/15 * * * *`, and `0 0 * * *`. Across 20+ microservices, Kubernetes `CronJob` manifests, and GitHub Actions workflows, those schedules constructively interfere like acoustic waves—creating **The Midnight Stampede**.
+
+Existing tools (like `crontab.guru`) only translate a **single** cron line into English.
+**`cronphase`** analyzes your **entire fleet** as a 1,440-minute diurnal signal, pinpoints multi-job resource collisions (accounting for multi-minute execution durations and midnight wrap-around), and runs a **constrained minimax phase-shift solver** that rewrites cron expressions with deterministic offsets (`*/15 * * * *` → `7-59/15 * * * *`, `0 * * * *` → `23 * * * *`, `0 */4 * * *` → `19 1-23/4 * * *`) while strictly preserving every job's exact frequency, SLA window bounds, and pinned locks.
+
+## Key Capabilities
+
+1. **Multi-Format Fleet Ingestion**: Parses standard UNIX `/etc/crontab`, Kubernetes `batch/v1 CronJob` YAML manifests, and GitHub Actions `.github/workflows/*.yml` schedule blocks.
+2. **1,440-Minute Load Envelope & Crest Factor Simulator**: Models job execution duration (`@duration=8m`), resource weight (`@weight=7.5`), and target subsystem contention (`@resource=db-primary`), including jobs that start at `23:55` and spill across midnight into `00:05`.
+3. **Harmonic Resonance Spectrum**: Quantifies `:00`, `:15`, `:30`, `:45`, and `5m-grid` harmonic clustering across your fleet.
+4. **Constrained Minimax Phase-Shift Compiler**:
+   - **Coordinate Descent / Minimax (`--strategy anneal`)**: Minimizes $L_\infty$ peak resource load and $L_2$ load variance across the 1,440-minute ring.
+   - **Deterministic FNV-1a Hash Jitter (`--strategy fnv-hash`)**: Zero-coordination stateless phase assignment (compiles Jenkins `H/15 * * * *` semantics to standard POSIX/Vixie cron syntax).
+   - **Prime-Modulo Splay (`--strategy prime-splay`)**: Coprime stride distribution across periodic lattices.
+5. **Ready-to-Apply Unified Git Diff & CI Gate**: Generates a `git apply`-ready patch and supports `--max-crest-factor` for CI/CD pull request checks.
+
+## Quick Start (CLI)
+
+```bash
+# 1. Analyze a production crontab and print the 24h waveform + collision spikes
+python3 -m cronphase examples/prod.crontab
+
+# 2. Run the constrained phase-shift compiler and emit a unified git diff patch
+python3 -m cronphase examples/prod.crontab --optimize --diff
+
+# 3. Gate CI pipelines if peak-to-mean crest factor exceeds 2.5x
+python3 -m cronphase examples/k8s-cronjobs.yaml --optimize --max-crest-factor 2.5
+```

cronphase-0.2.1/README.md

@@ -0,0 +1,31 @@
+# `cronphase` — Fleet-Wide Cron Thundering-Herd Oscilloscope & Phase-Shift Compiler
+
+> **Why does your database CPU spike to 100% at `00:00`, `:00`, and `:15` every day?**
+> Because humans write `0 * * * *`, `*/5 * * * *`, `*/15 * * * *`, and `0 0 * * *`. Across 20+ microservices, Kubernetes `CronJob` manifests, and GitHub Actions workflows, those schedules constructively interfere like acoustic waves—creating **The Midnight Stampede**.
+
+Existing tools (like `crontab.guru`) only translate a **single** cron line into English.
+**`cronphase`** analyzes your **entire fleet** as a 1,440-minute diurnal signal, pinpoints multi-job resource collisions (accounting for multi-minute execution durations and midnight wrap-around), and runs a **constrained minimax phase-shift solver** that rewrites cron expressions with deterministic offsets (`*/15 * * * *` → `7-59/15 * * * *`, `0 * * * *` → `23 * * * *`, `0 */4 * * *` → `19 1-23/4 * * *`) while strictly preserving every job's exact frequency, SLA window bounds, and pinned locks.
+
+## Key Capabilities
+
+1. **Multi-Format Fleet Ingestion**: Parses standard UNIX `/etc/crontab`, Kubernetes `batch/v1 CronJob` YAML manifests, and GitHub Actions `.github/workflows/*.yml` schedule blocks.
+2. **1,440-Minute Load Envelope & Crest Factor Simulator**: Models job execution duration (`@duration=8m`), resource weight (`@weight=7.5`), and target subsystem contention (`@resource=db-primary`), including jobs that start at `23:55` and spill across midnight into `00:05`.
+3. **Harmonic Resonance Spectrum**: Quantifies `:00`, `:15`, `:30`, `:45`, and `5m-grid` harmonic clustering across your fleet.
+4. **Constrained Minimax Phase-Shift Compiler**:
+   - **Coordinate Descent / Minimax (`--strategy anneal`)**: Minimizes $L_\infty$ peak resource load and $L_2$ load variance across the 1,440-minute ring.
+   - **Deterministic FNV-1a Hash Jitter (`--strategy fnv-hash`)**: Zero-coordination stateless phase assignment (compiles Jenkins `H/15 * * * *` semantics to standard POSIX/Vixie cron syntax).
+   - **Prime-Modulo Splay (`--strategy prime-splay`)**: Coprime stride distribution across periodic lattices.
+5. **Ready-to-Apply Unified Git Diff & CI Gate**: Generates a `git apply`-ready patch and supports `--max-crest-factor` for CI/CD pull request checks.
+
+## Quick Start (CLI)
+
+```bash
+# 1. Analyze a production crontab and print the 24h waveform + collision spikes
+python3 -m cronphase examples/prod.crontab
+
+# 2. Run the constrained phase-shift compiler and emit a unified git diff patch
+python3 -m cronphase examples/prod.crontab --optimize --diff
+
+# 3. Gate CI pipelines if peak-to-mean crest factor exceeds 2.5x
+python3 -m cronphase examples/k8s-cronjobs.yaml --optimize --max-crest-factor 2.5
+```

cronphase-0.2.1/cronphase/__init__.py

@@ -0,0 +1,21 @@
+"""
+cronphase — Fleet-wide cron thundering-herd detector & deterministic phase-shift solver.
+"""
+
+from .parser import CronExpression, ScheduledJob, parse_manifest
+from .engine import SimulationResult, simulate_day
+from .solver import SolverConfig, optimize_fleet
+from .diff import generate_unified_diff, apply_rewrites
+
+__version__ = "0.2.1"
+__all__ = [
+    "CronExpression",
+    "ScheduledJob",
+    "parse_manifest",
+    "SimulationResult",
+    "simulate_day",
+    "SolverConfig",
+    "optimize_fleet",
+    "generate_unified_diff",
+    "apply_rewrites",
+]

cronphase-0.2.1/cronphase/__main__.py

@@ -0,0 +1,5 @@
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

cronphase-0.2.1/cronphase/cli.py

@@ -0,0 +1,136 @@
+"""
+Command-Line Interface for `cronphase`.
+Usage:
+  python3 -m cronphase examples/prod.crontab --optimize --diff
+"""
+
+from __future__ import annotations
+import argparse
+import json
+import sys
+from typing import List, Optional
+from .parser import parse_manifest
+from .engine import format_hhmm, simulate_day
+from .solver import SolverConfig, optimize_fleet
+from .diff import apply_rewrites, generate_unified_diff
+
+
+def _ascii_sparkline(values: List[float], width: int = 48) -> str:
+    blocks = " ▂▃▄▅▆▇█"
+    if not values:
+        return ""
+    step = max(1, len(values) // width)
+    bucketed = [max(values[i : i + step]) for i in range(0, len(values), step)][:width]
+    hi = max(bucketed) if bucketed else 1.0
+    if hi <= 0:
+        return blocks[0] * len(bucketed)
+    return "".join(blocks[min(len(blocks) - 1, int((v / hi) * (len(blocks) - 1)))] for v in bucketed)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cronphase",
+        description="Fleet-wide cron thundering-herd analyzer & deterministic phase-shift compiler.",
+    )
+    parser.add_argument("manifest", help="Path to crontab, Kubernetes CronJob YAML, or GitHub Actions YAML ('-' for stdin)")
+    parser.add_argument("--optimize", "-o", action="store_true", help="Run constrained phase-shift solver")
+    parser.add_argument(
+        "--strategy",
+        choices=["anneal", "prime-splay", "fnv-hash"],
+        default="anneal",
+        help="Phase-shift solver algorithm (default: anneal)",
+    )
+    parser.add_argument("--diff", "-d", action="store_true", help="Output unified git diff patch")
+    parser.add_argument("--json", action="store_true", help="Output machine-readable JSON report")
+    parser.add_argument(
+        "--max-crest-factor",
+        type=float,
+        default=None,
+        help="Exit with code 2 if Crest Factor (Peak/Mean load) exceeds threshold (for CI linting)",
+    )
+
+    args = parser.parse_args(argv)
+    if args.manifest == "-":
+        raw = sys.stdin.read()
+        fname = "stdin.crontab"
+    else:
+        with open(args.manifest, "r", encoding="utf-8") as f:
+            raw = f.read()
+        fname = args.manifest.rsplit("/", 1)[-1]
+
+    jobs = parse_manifest(raw)
+    if not jobs:
+        print("cronphase: no valid cron schedules found in input.", file=sys.stderr)
+        return 1
+
+    cfg = SolverConfig(strategy=args.strategy)
+    if args.optimize or args.diff:
+        opt_jobs, rewrites, before_sim, after_sim = optimize_fleet(jobs, cfg)
+    else:
+        before_sim = simulate_day(jobs)
+        opt_jobs, rewrites, after_sim = jobs, [], before_sim
+
+    if args.json:
+        payload = {
+            "job_count": len(jobs),
+            "before": {
+                "peak_concurrency": before_sim.peak_concurrency,
+                "peak_load": before_sim.peak_load,
+                "peak_time": format_hhmm(before_sim.peak_minute),
+                "mean_load": before_sim.mean_load,
+                "crest_factor": before_sim.crest_factor,
+                "collision_minutes": before_sim.collision_minutes_count,
+                "harmonics": before_sim.harmonic_buckets,
+            },
+            "after": {
+                "peak_concurrency": after_sim.peak_concurrency,
+                "peak_load": after_sim.peak_load,
+                "peak_time": format_hhmm(after_sim.peak_minute),
+                "mean_load": after_sim.mean_load,
+                "crest_factor": after_sim.crest_factor,
+                "collision_minutes": after_sim.collision_minutes_count,
+                "harmonics": after_sim.harmonic_buckets,
+            },
+            "rewrites": [
+                {
+                    "job_id": r.job_id,
+                    "job_name": r.job_name,
+                    "old_expr": r.old_expr,
+                    "new_expr": r.new_expr,
+                    "phase_shift_minutes": r.phase_shift_minutes,
+                }
+                for r in rewrites
+            ],
+        }
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"CRONPHASE // FLEET HARMONIC & COLLISION REPORT ({len(jobs)} jobs parsed)")
+        print("=" * 74)
+        b_loads = [s.load for s in before_sim.timeline]
+        print(
+            f"BASELINE   | Peak Load: {before_sim.peak_load:5.1f} ({before_sim.peak_concurrency} jobs @ {format_hhmm(before_sim.peak_minute)}) "
+            f"| Crest: {before_sim.crest_factor:4.2f}x | Collisions: {before_sim.collision_minutes_count}m"
+        )
+        print(f"WAVEFORM   | [{_ascii_sparkline(b_loads, 48)}] (00:00..23:59)")
+        if args.optimize or args.diff:
+            a_loads = [s.load for s in after_sim.timeline]
+            drop_pct = ((before_sim.peak_load - after_sim.peak_load) / before_sim.peak_load * 100.0) if before_sim.peak_load else 0.0
+            print(
+                f"OPTIMIZED  | Peak Load: {after_sim.peak_load:5.1f} ({after_sim.peak_concurrency} jobs @ {format_hhmm(after_sim.peak_minute)}) "
+                f"| Crest: {after_sim.crest_factor:4.2f}x | Peak Drop: -{drop_pct:.1f}%"
+            )
+            print(f"DE-PHASED  | [{_ascii_sparkline(a_loads, 48)}] ({len(rewrites)} schedules shifted)")
+
+        if args.diff and rewrites:
+            print("\n" + "-" * 74)
+            rewritten_text = apply_rewrites(raw, jobs, rewrites)
+            print(generate_unified_diff(raw, rewritten_text, filename=fname).rstrip())
+
+    active_sim = after_sim if (args.optimize or args.diff) else before_sim
+    if args.max_crest_factor is not None and active_sim.crest_factor > args.max_crest_factor:
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cronphase-0.2.1/cronphase/diff.py

@@ -0,0 +1,51 @@
+"""
+Unified Diff & Rewritten Manifest Generator for Crontab, Kubernetes YAML, and GitHub Actions.
+"""
+
+from __future__ import annotations
+import difflib
+from typing import Dict, List
+from .parser import ScheduledJob
+from .solver import JobRewrite
+
+
+def apply_rewrites(original_text: str, jobs: List[ScheduledJob], rewrites: List[JobRewrite]) -> str:
+    """Applies phase-shifted cron expressions back to the original manifest line-by-line."""
+    rewrite_by_id: Dict[str, JobRewrite] = {r.job_id: r for r in rewrites}
+    line_to_rewrite: Dict[int, JobRewrite] = {}
+    for j in jobs:
+        if j.id in rewrite_by_id and j.source_line > 0:
+            line_to_rewrite[j.source_line] = rewrite_by_id[j.id]
+
+    out_lines: List[str] = []
+    for idx, line in enumerate(original_text.splitlines(keepends=True), start=1):
+        rw = line_to_rewrite.get(idx)
+        if rw is not None:
+            # Replace only inside the schedule portion before any trailing comment
+            comment_idx = line.find(" #")
+            if comment_idx != -1:
+                head = line[:comment_idx].replace(rw.old_expr, rw.new_expr, 1)
+                replaced = head + line[comment_idx:]
+            else:
+                replaced = line.replace(rw.old_expr, rw.new_expr, 1)
+            out_lines.append(replaced)
+        else:
+            out_lines.append(line)
+    return "".join(out_lines)
+
+
+def generate_unified_diff(
+    original_text: str,
+    rewritten_text: str,
+    filename: str = "crontab",
+) -> str:
+    orig_lines = [ln if ln.endswith("\n") else ln + "\n" for ln in original_text.splitlines()]
+    new_lines = [ln if ln.endswith("\n") else ln + "\n" for ln in rewritten_text.splitlines()]
+    diff = difflib.unified_diff(
+        orig_lines,
+        new_lines,
+        fromfile=f"a/{filename}",
+        tofile=f"b/{filename}",
+        lineterm="\n",
+    )
+    return "".join(diff)

cronphase-0.2.1/cronphase/engine.py

@@ -0,0 +1,167 @@
+"""
+1,440-Minute Diurnal Concurrency, Resource Load & Harmonic Spectrum Simulator.
+Accurately models multi-minute job durations, midnight wrap-around spillover,
+crest factor (Peak / Mean), and pairwise job collision matrices.
+"""
+
+from __future__ import annotations
+import dataclasses
+import math
+from typing import Dict, List, Tuple
+from .parser import ScheduledJob
+
+
+@dataclasses.dataclass
+class MinuteSlice:
+    minute: int  # 0..1439
+    concurrency: int
+    load: float
+    active_job_ids: List[str]
+    resource_loads: Dict[str, float]
+
+
+@dataclasses.dataclass
+class CollisionSpike:
+    minute: int
+    time_label: str
+    concurrency: int
+    total_load: float
+    dominant_resource: str
+    job_names: List[str]
+
+
+@dataclasses.dataclass
+class SimulationResult:
+    timeline: List[MinuteSlice]
+    peak_concurrency: int
+    peak_load: float
+    peak_minute: int
+    mean_load: float
+    p95_load: float
+    l2_energy: float
+    crest_factor: float
+    collision_minutes_count: int
+    harmonic_buckets: Dict[str, int]
+    top_spikes: List[CollisionSpike]
+    pairwise_overlaps: Dict[Tuple[str, str], int]
+
+
+def format_hhmm(minute: int) -> str:
+    m = minute % 1440
+    return f"{m // 60:02d}:{m % 60:02d}"
+
+
+def simulate_day(jobs: List[ScheduledJob], collision_threshold: int = 3) -> SimulationResult:
+    timeline: List[MinuteSlice] = [
+        MinuteSlice(minute=m, concurrency=0, load=0.0, active_job_ids=[], resource_loads={})
+        for m in range(1440)
+    ]
+
+    harmonic_buckets: Dict[str, int] = {
+        ":00": 0,
+        ":15": 0,
+        ":30": 0,
+        ":45": 0,
+        "5m-grid": 0,
+        "prime/off-grid": 0,
+    }
+
+    for job in jobs:
+        starts = job.cron.firing_minutes_in_day()
+        dur = max(1, job.duration_min)
+        for start_min in starts:
+            mod_m = start_min % 60
+            if mod_m == 0:
+                harmonic_buckets[":00"] += 1
+            elif mod_m == 15:
+                harmonic_buckets[":15"] += 1
+            elif mod_m == 30:
+                harmonic_buckets[":30"] += 1
+            elif mod_m == 45:
+                harmonic_buckets[":45"] += 1
+            elif mod_m % 5 == 0:
+                harmonic_buckets["5m-grid"] += 1
+            else:
+                harmonic_buckets["prime/off-grid"] += 1
+
+            for offset in range(dur):
+                m_idx = (start_min + offset) % 1440
+                sl = timeline[m_idx]
+                if job.id not in sl.active_job_ids:
+                    sl.active_job_ids.append(job.id)
+                    sl.concurrency += 1
+                    sl.load = round(sl.load + job.weight, 4)
+                    sl.resource_loads[job.resource] = round(
+                        sl.resource_loads.get(job.resource, 0.0) + job.weight, 4
+                    )
+
+    job_map = {j.id: j for j in jobs}
+    loads = [sl.load for sl in timeline]
+    concurrencies = [sl.concurrency for sl in timeline]
+
+    peak_load = max(loads) if loads else 0.0
+    peak_concurrency = max(concurrencies) if concurrencies else 0
+    peak_minute = 0
+    for sl in timeline:
+        if sl.load == peak_load:
+            peak_minute = sl.minute
+            break
+
+    mean_load = sum(loads) / 1440.0 if loads else 0.0
+    sorted_loads = sorted(loads)
+    p95_load = sorted_loads[int(1440 * 0.95)] if sorted_loads else 0.0
+    l2_energy = math.sqrt(sum(x * x for x in loads) / 1440.0) if loads else 0.0
+    crest_factor = (peak_load / mean_load) if mean_load > 1e-6 else 1.0
+    collision_minutes_count = sum(1 for sl in timeline if sl.concurrency >= collision_threshold)
+
+    pairwise: Dict[Tuple[str, str], int] = {}
+    for sl in timeline:
+        active = sl.active_job_ids
+        n = len(active)
+        if n > 1:
+            for i in range(n):
+                for k in range(i + 1, n):
+                    pair = (active[i], active[k]) if active[i] < active[k] else (active[k], active[i])
+                    pairwise[pair] = pairwise.get(pair, 0) + 1
+
+    candidate_slices = sorted(
+        [sl for sl in timeline if sl.concurrency >= 2],
+        key=lambda s: (s.load, s.concurrency, -s.minute),
+        reverse=True,
+    )
+    top_spikes: List[CollisionSpike] = []
+    used_minutes: List[int] = []
+    for sl in candidate_slices:
+        if any(min((sl.minute - u) % 1440, (u - sl.minute) % 1440) < 5 for u in used_minutes):
+            continue
+        used_minutes.append(sl.minute)
+        dom_res = "none"
+        if sl.resource_loads:
+            dom_res = max(sl.resource_loads.items(), key=lambda kv: kv[1])[0]
+        top_spikes.append(
+            CollisionSpike(
+                minute=sl.minute,
+                time_label=format_hhmm(sl.minute),
+                concurrency=sl.concurrency,
+                total_load=round(sl.load, 2),
+                dominant_resource=dom_res,
+                job_names=[job_map[jid].name for jid in sl.active_job_ids],
+            )
+        )
+        if len(top_spikes) >= 8:
+            break
+
+    return SimulationResult(
+        timeline=timeline,
+        peak_concurrency=peak_concurrency,
+        peak_load=round(peak_load, 2),
+        peak_minute=peak_minute,
+        mean_load=round(mean_load, 2),
+        p95_load=round(p95_load, 2),
+        l2_energy=round(l2_energy, 2),
+        crest_factor=round(crest_factor, 2),
+        collision_minutes_count=collision_minutes_count,
+        harmonic_buckets=harmonic_buckets,
+        top_spikes=top_spikes,
+        pairwise_overlaps=pairwise,
+    )