"""Inspect and compare local iCalendar snapshots without network or application access.""" from __future__ import annotations import argparse from collections import defaultdict from datetime import datetime import hashlib import json from pathlib import Path import re import sys def split_unquoted(text: str, separator: str, limit: int = -1) -> list[str]: parts = [] quoted = False start = 0 for index, char in enumerate(text): if char == '"': quoted = not quoted if char == separator and not quoted and (limit < 0 or len(parts) < limit): parts.append(text[start:index]) start = index + 1 parts.append(text[start:]) return parts def content_line(line: str, number: int) -> tuple[str, str, str]: parts = split_unquoted(line, ":", 1) if len(parts) != 2: raise ValueError(f"Content line {number} has no unquoted colon") header, value = parts pieces = split_unquoted(header, ";") name = pieces[0].upper() if not re.fullmatch(r"[A-Z0-9-]+", name): raise ValueError(f"Content line {number} has an invalid property name") params = [] for piece in pieces[1:]: if "=" not in piece: raise ValueError(f"Content line {number} has an invalid parameter") key, parameter = piece.split("=", 1) params.append(key.upper() + "=" + parameter) return name, ";".join([name, *sorted(params)]), value def property_map(properties: list[dict]) -> dict[str, list[str]]: result = defaultdict(list) for item in properties: result[item["header"]].append(item["value"]) return {key: sorted(values) for key, values in sorted(result.items())} def named_values(properties: list[dict], name: str) -> list[str]: return [item["value"] for item in properties if item["name"] == name] def parse_calendar(raw: bytes) -> dict: physical = raw.splitlines() warnings = [] if not raw.endswith(b"\r\n") or b"\n" in raw.replace(b"\r\n", b""): warnings.append("Line endings differ from RFC 5545 CRLF content lines") long_lines = [index for index, line in enumerate(physical, 1) if len(line) > 75] if long_lines: warnings.append(f"Physical lines exceed the recommended 75 octets: {long_lines}") unfolded = re.sub(rb"\r?\n[ \t]", b"", raw).decode("utf-8-sig") stack = [] calendar_properties = [] events = [] current = None started = False finished = False for number, line in enumerate(unfolded.splitlines(), 1): if not line: if stack: raise ValueError(f"Empty content line {number} inside a component") continue name, header, value = content_line(line, number) if finished: raise ValueError("Content exists after END:VCALENDAR") if name == "BEGIN": component = value.upper() if not stack: if component != "VCALENDAR" or started: raise ValueError("Expected one VCALENDAR root component") started = True elif component == "VCALENDAR": raise ValueError("Nested VCALENDAR is not supported") if component == "VEVENT": if stack != ["VCALENDAR"]: raise ValueError("VEVENT must be a direct calendar component") current = {"properties": [], "nested_properties": []} elif current is not None: current["nested_properties"].append({"header": "/".join(stack[2:]) + "/BEGIN", "value": value}) stack.append(component) continue if not stack: raise ValueError("Content exists outside VCALENDAR") if name == "END": if stack[-1] != value.upper(): raise ValueError(f"Mismatched component ending on content line {number}") if stack[-1] == "VEVENT": events.append(current) current = None elif current is not None: current["nested_properties"].append({"header": "/".join(stack[2:]) + "/END", "value": value}) stack.pop() if not stack: finished = True continue item = {"name": name, "header": header, "value": value} if stack == ["VCALENDAR"]: calendar_properties.append(item) elif stack == ["VCALENDAR", "VEVENT"]: current["properties"].append(item) elif current is not None: current["nested_properties"].append({"header": "/".join(stack[2:]) + "/" + header, "value": value}) else: warnings.append(f"Non-VEVENT component present: {stack[1]}; recurrence/time-zone semantics are not expanded") if not started or not finished or stack: raise ValueError("Incomplete calendar or component; comparison stopped") errors = [] if named_values(calendar_properties, "VERSION") != ["2.0"]: errors.append("Exactly one VERSION:2.0 is expected") if len(named_values(calendar_properties, "PRODID")) != 1: errors.append("Exactly one PRODID is expected") for index, event in enumerate(events, 1): properties = event["properties"] for required in ["UID", "DTSTAMP"]: if len(named_values(properties, required)) != 1: errors.append(f"Event {index}: exactly one {required} is expected") stamps = named_values(properties, "DTSTAMP") if len(stamps) == 1: try: if not re.fullmatch(r"\d{8}T\d{6}Z", stamps[0]): raise ValueError datetime.strptime(stamps[0], "%Y%m%dT%H%M%SZ") except ValueError: errors.append(f"Event {index}: DTSTAMP must be a valid UTC date-time") starts = [p for p in properties if p["name"] == "DTSTART"] ends = [p for p in properties if p["name"] == "DTEND"] if len(starts) != 1: warnings.append(f"Event {index}: no single DTSTART; check scheduling/recurrence semantics separately") if len(starts) == len(ends) == 1 and ";VALUE=DATE" in starts[0]["header"]: try: if ";VALUE=DATE" not in ends[0]["header"]: raise ValueError for item in [starts[0], ends[0]]: if not re.fullmatch(r"\d{8}", item["value"]): raise ValueError start = datetime.strptime(starts[0]["value"], "%Y%m%d") end = datetime.strptime(ends[0]["value"], "%Y%m%d") if end <= start: raise ValueError except ValueError: errors.append(f"Event {index}: invalid all-day date interval or inconsistent value types") if named_values(properties, "RRULE") or named_values(properties, "RDATE"): warnings.append(f"Event {index}: recurrence properties retained, not expanded") event["uid"] = (named_values(properties, "UID") or [""])[0] event["recurrence_id"] = property_map([p for p in properties if p["name"] == "RECURRENCE-ID"]) event["period"] = property_map([p for p in properties if p["name"] in {"DTSTART", "DTEND", "DURATION"}]) event["attributes"] = property_map(properties + event.pop("nested_properties")) del event["properties"] identities = defaultdict(int) for event in events: identities[(event["uid"], json.dumps(event["recurrence_id"], sort_keys=True))] += 1 if any(count > 1 for count in identities.values()): warnings.append("Duplicate UID/RECURRENCE-ID combinations exist; ambiguous events are not paired") return {"sha256": hashlib.sha256(raw).hexdigest(), "bytes": len(raw), "calendar_attributes": property_map(calendar_properties), "events": events, "validation_errors": errors, "warnings": sorted(set(warnings)), "scope": "Structural checks for snapshot analysis; not a complete RFC 5545 validator or recurrence engine"} def attribute_changes(before: dict, after: dict) -> list[dict]: return [{"attribute": key, "before": before.get(key, []), "after": after.get(key, [])} for key in sorted(before.keys() | after.keys()) if before.get(key) != after.get(key)] def compare_calendars(before: dict, after: dict) -> dict: def group(events: list[dict]) -> dict: result = defaultdict(list) for event in events: result[(event["uid"], json.dumps(event["recurrence_id"], sort_keys=True))].append(event) return result left, right = group(before["events"]), group(after["events"]) removed = [event for key in sorted(left.keys() - right.keys()) for event in left[key]] added = [event for key in sorted(right.keys() - left.keys()) for event in right[key]] changed, ambiguous = [], [] unchanged = 0 for key in sorted(left.keys() & right.keys()): if len(left[key]) != 1 or len(right[key]) != 1: ambiguous.append({"uid": key[0], "before": left[key], "after": right[key]}) continue changes = attribute_changes(left[key][0]["attributes"], right[key][0]["attributes"]) if changes: changed.append({"uid": key[0], "recurrence_id": left[key][0]["recurrence_id"], "changes": changes}) else: unchanged += 1 candidates = [{"before_uid": old["uid"], "after_uid": new["uid"], "period": old["period"], "evidence": "Identical interval only; not proof of source identity"} for old in removed for new in added if old["period"] and old["period"] == new["period"]] return {"before": before, "after": after, "unchanged_events": unchanged, "changed_events": changed, "removed_events": removed, "added_events": added, "ambiguous_identities": ambiguous, "same_interval_new_uid_candidates": candidates, "explicit_cancellations_after": [event for event in after["events"] if "CANCELLED" in event["attributes"].get("STATUS", [])], "calendar_attribute_changes": attribute_changes(before["calendar_attributes"], after["calendar_attributes"]), "interpretation": "Missing VEVENT is an observed omission, not an explicit cancellation or proof of availability in a portal"} def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("before", type=Path, help="Local .ics snapshot to inspect") parser.add_argument("after", type=Path, nargs="?", help="Optional later snapshot to compare") parser.add_argument("--output", type=Path, help="Private local JSON report; may contain personal data and URLs") parser.add_argument("--own-uid-suffix", help="Report which UIDs the existing suffix filter would recognise") args = parser.parse_args() if args.output and args.output.resolve() in {path.resolve() for path in [args.before, args.after] if path}: parser.error("Output must not overwrite an input snapshot") if args.output and args.output.exists(): parser.error("Output already exists; choose a new report filename") try: before = parse_calendar(args.before.read_bytes()) after = parse_calendar(args.after.read_bytes()) if args.after else None report = compare_calendars(before, after) if after is not None else {"calendar": before} if args.own_uid_suffix: report["own_uid_suffix_analysis"] = { "suffix": args.own_uid_suffix, "before_matching_uids": [event["uid"] for event in before["events"] if event["uid"].endswith(args.own_uid_suffix)], "after_matching_uids": [event["uid"] for event in after["events"] if event["uid"].endswith(args.own_uid_suffix)] if after is not None else [], "interpretation": "Suffix match models only the existing UID echo filter; it is not a complete import simulation", } if args.output: with args.output.open("x", encoding="utf-8") as target: json.dump(report, target, ensure_ascii=False, indent=2) target.write("\n") summary = {"before_events": len(before["events"]), "validation_errors": len(before["validation_errors"]), "warnings": len(before["warnings"])} if after is not None: summary.update({"after_events": len(after["events"]), "validation_errors": summary["validation_errors"] + len(after["validation_errors"]), "warnings": summary["warnings"] + len(after["warnings"]), "unchanged_events": report["unchanged_events"], "changed_events": len(report["changed_events"]), "removed_events": len(report["removed_events"]), "added_events": len(report["added_events"]), "ambiguous_identities": len(report["ambiguous_identities"]), "same_interval_new_uid_candidates": len(report["same_interval_new_uid_candidates"]), "explicit_cancellations_after": len(report["explicit_cancellations_after"])}) print(json.dumps(summary, ensure_ascii=False)) return 2 if summary["validation_errors"] else 0 except (OSError, UnicodeError, ValueError) as error: print(json.dumps({"error": type(error).__name__, "message": str(error)}, ensure_ascii=False), file=sys.stderr) return 2 if __name__ == "__main__": raise SystemExit(main())