From 94df35e702110562162c4877d7420d3aac6f283f Mon Sep 17 00:00:00 2001 From: Lars Date: Thu, 29 Oct 2026 14:58:41 +0100 Subject: [PATCH] Lokalen iCal-Snapshotvergleich versionieren [skip ci] --- scripts/compare-ical.py | 244 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 scripts/compare-ical.py diff --git a/scripts/compare-ical.py b/scripts/compare-ical.py new file mode 100644 index 0000000..1ee0e21 --- /dev/null +++ b/scripts/compare-ical.py @@ -0,0 +1,244 @@ +"""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())