Files
fewo-stommer/scripts/compare-ical.py

245 lines
13 KiB
Python

"""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())