245 lines
13 KiB
Python
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())
|