Lokalen iCal-Snapshotvergleich versionieren [skip ci]
This commit is contained in:
1 parent
bc3872c01f
commit
94df35e702
1 file changed
+244
@@ -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())
|
||||
Reference in new issue
Block a user