@gmickel/gno 1.27.0 → 1.28.0

package/src/converters/adapters/ical/adapter.ts

@@ -0,0 +1,475 @@
+import type {
+  RecordAdapter,
+  RecordAdapterEvent,
+  RecordAdapterInput,
+  RecordAnchor,
+} from "../../types";
+
+import { summarizeRecurrence } from "./recurrence";
+
+const DATE_PATTERN = /^(\d{4})(\d{2})(\d{2})$/;
+const DATE_TIME_PATTERN = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z)?$/;
+const NUMERIC_OFFSET_PATTERN = /[+-]\d{4}$/;
+
+interface LogicalLine {
+  text: string;
+  startLine: number;
+  endLine: number;
+}
+
+interface IcalProperty {
+  name: string;
+  params: Map<string, string>;
+  value: string;
+}
+
+const failure = (
+  sourceLocator: string,
+  retryable = false
+): RecordAdapterEvent => ({
+  type: "failure",
+  failure: {
+    code: "MALFORMED_RECORD",
+    message: "Malformed iCalendar event.",
+    retryable,
+    sourceLocator,
+  },
+});
+
+async function* physicalLines(
+  input: RecordAdapterInput
+): AsyncGenerator<{ text: string; line: number }> {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let pending = "";
+  let line = 0;
+  for await (const chunk of input.open()) {
+    pending += decoder.decode(chunk, { stream: true });
+    while (true) {
+      const newline = pending.indexOf("\n");
+      if (newline < 0) break;
+      line += 1;
+      const raw = pending.slice(0, newline);
+      pending = pending.slice(newline + 1);
+      if (raw.length > input.limits.maxRecordChars) {
+        throw new Error("iCalendar physical line exceeded its limit.");
+      }
+      const withoutCarriageReturn = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+      yield {
+        text:
+          line === 1 && withoutCarriageReturn.startsWith("\uFEFF")
+            ? withoutCarriageReturn.slice(1)
+            : withoutCarriageReturn,
+        line,
+      };
+    }
+    if (pending.length > input.limits.maxRecordChars) {
+      throw new Error("iCalendar physical line exceeded its limit.");
+    }
+  }
+  pending += decoder.decode();
+  if (pending.length > 0) {
+    if (pending.length > input.limits.maxRecordChars) {
+      throw new Error("iCalendar physical line exceeded its limit.");
+    }
+    line += 1;
+    yield {
+      text: pending.endsWith("\r") ? pending.slice(0, -1) : pending,
+      line,
+    };
+  }
+}
+
+async function* logicalLines(
+  input: RecordAdapterInput
+): AsyncGenerator<LogicalLine> {
+  let pending: LogicalLine | undefined;
+  for await (const physical of physicalLines(input)) {
+    if (/^[ \t]/.test(physical.text) && pending) {
+      pending.text += physical.text.slice(1);
+      if (pending.text.length > input.limits.maxRecordChars) {
+        throw new Error("iCalendar unfolded line exceeded its limit.");
+      }
+      pending.endLine = physical.line;
+      continue;
+    }
+    if (pending) yield pending;
+    pending = {
+      text: physical.text,
+      startLine: physical.line,
+      endLine: physical.line,
+    };
+  }
+  if (pending) yield pending;
+}
+
+const parseProperty = (line: string): IcalProperty | undefined => {
+  const colon = line.indexOf(":");
+  if (colon <= 0) return undefined;
+  const [rawName, ...rawParams] = line.slice(0, colon).split(";");
+  const name = rawName?.trim().toUpperCase();
+  if (!name) return undefined;
+  const params = new Map<string, string>();
+  for (const rawParam of rawParams) {
+    const equals = rawParam.indexOf("=");
+    if (equals <= 0) continue;
+    const key = rawParam.slice(0, equals).trim().toUpperCase();
+    const value = rawParam
+      .slice(equals + 1)
+      .trim()
+      .replace(/^"|"$/g, "");
+    params.set(key, value);
+  }
+  return { name, params, value: line.slice(colon + 1).trim() };
+};
+
+const unescapeText = (value: string): string =>
+  value
+    .replace(/\\n/gi, "\n")
+    .replace(/\\,/g, ",")
+    .replace(/\\;/g, ";")
+    .replace(/\\\\/g, "\\")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replace(/([\\`*_[\]#!])/g, "\\$1");
+
+const validCalendarDate = (
+  year: number,
+  month: number,
+  day: number,
+  hour = 0,
+  minute = 0,
+  second = 0
+): boolean => {
+  const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+  return (
+    date.getUTCFullYear() === year &&
+    date.getUTCMonth() === month - 1 &&
+    date.getUTCDate() === day &&
+    date.getUTCHours() === hour &&
+    date.getUTCMinutes() === minute &&
+    date.getUTCSeconds() === second
+  );
+};
+
+const normalizeDate = (property: IcalProperty): string | undefined => {
+  if (NUMERIC_OFFSET_PATTERN.test(property.value)) return undefined;
+  const dateOnly = DATE_PATTERN.exec(property.value);
+  if (dateOnly) {
+    const [, year, month, day] = dateOnly;
+    if (!validCalendarDate(Number(year), Number(month), Number(day))) {
+      return undefined;
+    }
+    return `${year}-${month}-${day}`;
+  }
+  const dateTime = DATE_TIME_PATTERN.exec(property.value);
+  if (!dateTime) return undefined;
+  const [, year, month, day, hour, minute, second, utc] = dateTime;
+  if (
+    !validCalendarDate(
+      Number(year),
+      Number(month),
+      Number(day),
+      Number(hour),
+      Number(minute),
+      Number(second)
+    )
+  ) {
+    return undefined;
+  }
+  const iso = `${year}-${month}-${day}T${hour}:${minute}:${second}`;
+  if (utc) return `${iso}Z`;
+  const timezone = property.params.get("TZID");
+  return timezone ? `TZID=${timezone}:${iso}` : iso;
+};
+
+const participant = (property: IcalProperty): string => {
+  const address = property.value.replace(/^mailto:/i, "");
+  const name = property.params.get("CN");
+  return unescapeText(name ? `${name} <${address}>` : address);
+};
+
+const values = (properties: IcalProperty[], name: string): IcalProperty[] =>
+  properties.filter((property) => property.name === name);
+
+const first = (
+  properties: IcalProperty[],
+  name: string
+): IcalProperty | undefined => values(properties, name)[0];
+
+const convertEvent = (
+  properties: IcalProperty[],
+  startLine: number,
+  endLine: number
+): RecordAdapterEvent | undefined => {
+  const uid = first(properties, "UID")?.value.normalize("NFC").trim();
+  if (!uid) return undefined;
+  const startProperty = first(properties, "DTSTART");
+  const endProperty = first(properties, "DTEND");
+  const start = startProperty ? normalizeDate(startProperty) : undefined;
+  const end = endProperty ? normalizeDate(endProperty) : undefined;
+  if ((startProperty && !start) || (endProperty && !end)) return undefined;
+  const invalidRecurrenceDate = properties
+    .filter((property) =>
+      ["RECURRENCE-ID", "RDATE", "EXDATE"].includes(property.name)
+    )
+    .some((property) =>
+      property.value
+        .split(",")
+        .some((value) => !normalizeDate({ ...property, value }))
+    );
+  if (invalidRecurrenceDate) return undefined;
+  const recurrence = summarizeRecurrence(properties, startProperty?.value);
+  const recurrenceIdProperty = first(properties, "RECURRENCE-ID");
+  const recurrenceIdentity = recurrenceIdProperty
+    ? normalizeDate(recurrenceIdProperty)
+    : undefined;
+  if (recurrenceIdProperty && !recurrenceIdentity) return undefined;
+  const summary = unescapeText(first(properties, "SUMMARY")?.value ?? "Event");
+  const description = first(properties, "DESCRIPTION")?.value;
+  const location = first(properties, "LOCATION")?.value;
+  const organizerProperty = first(properties, "ORGANIZER");
+  const createdProperty = first(properties, "CREATED");
+  const updatedProperty = first(properties, "LAST-MODIFIED");
+  const attendees = values(properties, "ATTENDEE").map(participant);
+  const organizer = organizerProperty
+    ? participant(organizerProperty)
+    : undefined;
+  const categories = values(properties, "CATEGORIES")
+    .flatMap((property) => property.value.split(","))
+    .map(unescapeText)
+    .filter(Boolean);
+  const lines = [`# ${summary}`];
+  if (start) lines.push(`Start: ${start}`);
+  if (end) lines.push(`End: ${end}`);
+  if (location) lines.push(`Location: ${unescapeText(location)}`);
+  if (organizer) lines.push(`Organizer: ${organizer}`);
+  if (attendees.length > 0) lines.push(`Attendees: ${attendees.join(", ")}`);
+  if (description) lines.push("", unescapeText(description));
+  if (recurrence.rrule) {
+    lines.push("", `Recurrence: ${unescapeText(recurrence.rrule)}`);
+  }
+  if (recurrence.truncated) {
+    lines.push("Recurrence anchors: truncated to the bounded local horizon");
+  }
+  const stableId = recurrenceIdentity
+    ? `ical:${uid}::recurrence:${recurrenceIdentity}`
+    : `ical:${uid}`;
+  const anchors: RecordAnchor[] = [
+    { kind: "event", value: uid },
+    ...recurrence.occurrenceAnchors.map((value) => ({
+      kind: "timestamp" as const,
+      value,
+    })),
+  ];
+  return {
+    type: "record",
+    record: {
+      stableId,
+      sourceLocator: `lines:${startLine}-${endLine}`,
+      markdown: lines.join("\n"),
+      title: summary,
+      metadata: {
+        author: organizer,
+        participants: [
+          ...new Set([organizer, ...attendees].filter(Boolean)),
+        ] as string[],
+        categories,
+        dateFields: Object.fromEntries(
+          [
+            ["start", start],
+            ["end", end],
+            ["created", createdProperty && normalizeDate(createdProperty)],
+            ["updated", updatedProperty && normalizeDate(updatedProperty)],
+          ].filter((entry): entry is [string, string] => Boolean(entry[1]))
+        ),
+        eventId: uid,
+      },
+      anchors,
+    },
+  };
+};
+
+async function* parseCalendar(
+  input: RecordAdapterInput
+): AsyncGenerator<RecordAdapterEvent> {
+  let sawCalendar = false;
+  let calendarOpen = false;
+  let endedCalendar = false;
+  let eventStart = 0;
+  let eventChars = 0;
+  let eventProperties: IcalProperty[] | undefined;
+  const nestedComponents: string[] = [];
+  const calendarComponents: string[] = [];
+  let hadFailure = false;
+  try {
+    for await (const line of logicalLines(input)) {
+      if (line.text === "BEGIN:VCALENDAR") {
+        if (sawCalendar || calendarOpen || endedCalendar || eventProperties) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+          continue;
+        }
+        sawCalendar = true;
+        calendarOpen = true;
+        continue;
+      }
+      if (line.text === "END:VCALENDAR") {
+        if (
+          !calendarOpen ||
+          eventProperties ||
+          nestedComponents.length > 0 ||
+          calendarComponents.length > 0
+        ) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+          continue;
+        }
+        calendarOpen = false;
+        endedCalendar = true;
+        continue;
+      }
+      if (line.text === "BEGIN:VEVENT") {
+        if (
+          !calendarOpen ||
+          endedCalendar ||
+          eventProperties ||
+          calendarComponents.length > 0
+        ) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+          continue;
+        }
+        eventStart = line.startLine;
+        eventChars = 0;
+        nestedComponents.length = 0;
+        eventProperties = [];
+        continue;
+      }
+      if (line.text === "END:VEVENT") {
+        if (!eventProperties || nestedComponents.length > 0) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+          continue;
+        }
+        const converted = convertEvent(
+          eventProperties,
+          eventStart,
+          line.endLine
+        );
+        if (converted) yield converted;
+        else {
+          hadFailure = true;
+          yield failure(`lines:${eventStart}-${line.endLine}`);
+        }
+        eventProperties = undefined;
+        continue;
+      }
+      if (!eventProperties) {
+        if (!line.text.trim()) continue;
+        if (!calendarOpen || endedCalendar) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+          continue;
+        }
+        if (line.text.startsWith("BEGIN:")) {
+          const component = line.text.slice("BEGIN:".length).trim();
+          if (!component) {
+            hadFailure = true;
+            yield failure(`line:${line.startLine}`);
+          } else {
+            calendarComponents.push(component);
+          }
+          continue;
+        }
+        if (line.text.startsWith("END:")) {
+          const component = line.text.slice("END:".length).trim();
+          if (!component || calendarComponents.at(-1) !== component) {
+            hadFailure = true;
+            yield failure(`line:${line.startLine}`);
+          } else {
+            calendarComponents.pop();
+          }
+          continue;
+        }
+        if (!parseProperty(line.text)) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+        }
+        continue;
+      }
+      if (line.text.startsWith("BEGIN:")) {
+        const component = line.text.slice("BEGIN:".length).trim();
+        if (!component) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+        } else {
+          nestedComponents.push(component);
+        }
+        continue;
+      }
+      if (line.text.startsWith("END:") && nestedComponents.length > 0) {
+        const component = line.text.slice("END:".length).trim();
+        if (nestedComponents.at(-1) !== component) {
+          hadFailure = true;
+          yield failure(`line:${line.startLine}`);
+        } else {
+          nestedComponents.pop();
+        }
+        continue;
+      }
+      if (line.text.startsWith("END:")) {
+        hadFailure = true;
+        yield failure(`line:${line.startLine}`);
+        continue;
+      }
+      if (nestedComponents.length > 0) continue;
+      eventChars += line.text.length;
+      if (eventChars > input.limits.maxRecordChars) {
+        hadFailure = true;
+        yield {
+          type: "failure",
+          failure: {
+            code: "RECORD_TOO_LARGE",
+            message: "iCalendar event exceeded its record limit.",
+            retryable: false,
+            sourceLocator: `line:${eventStart}`,
+          },
+        };
+        eventProperties = undefined;
+        continue;
+      }
+      const property = parseProperty(line.text);
+      if (property) eventProperties.push(property);
+      else {
+        hadFailure = true;
+        yield failure(`line:${line.startLine}`);
+      }
+    }
+  } catch {
+    hadFailure = true;
+    yield failure("calendar", true);
+  }
+  if (eventProperties) {
+    hadFailure = true;
+    yield failure(`line:${eventStart}`, true);
+  }
+  if (calendarOpen || calendarComponents.length > 0) {
+    hadFailure = true;
+    yield failure("calendar", true);
+  }
+  const complete =
+    sawCalendar &&
+    endedCalendar &&
+    !calendarOpen &&
+    calendarComponents.length === 0 &&
+    !hadFailure;
+  yield { type: "snapshot", state: complete ? "complete" : "partial" };
+}
+
+export const icalAdapter: RecordAdapter = {
+  id: "adapter/ical-export",
+  version: "1.0.0",
+  canHandle: (mime, ext) => mime === "text/calendar" || ext === ".ics",
+  records: parseCalendar,
+};

package/src/converters/adapters/ical/recurrence.ts

@@ -0,0 +1,186 @@
+const BASIC_DATE_PATTERN = /^(\d{4})(\d{2})(\d{2})$/;
+const BASIC_DATE_TIME_PATTERN =
+  /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z)?$/;
+
+export const MAX_RECURRENCE_ANCHORS = 64;
+const MAX_RECURRENCE_HORIZON_DAYS = 366;
+
+export interface RecurrenceSummary {
+  recurrenceId?: string;
+  rrule?: string;
+  exdates: string[];
+  rdates: string[];
+  occurrenceAnchors: string[];
+  truncated: boolean;
+}
+
+export interface IcalPropertyLike {
+  name: string;
+  value: string;
+  params?: ReadonlyMap<string, string>;
+}
+
+interface BasicDateParts {
+  date: Date;
+  dateOnly: boolean;
+  utc: boolean;
+}
+
+const parseBasicDate = (value: string): BasicDateParts | undefined => {
+  const dateOnly = BASIC_DATE_PATTERN.exec(value);
+  if (dateOnly) {
+    const [, year, month, day] = dateOnly;
+    const date = new Date(
+      Date.UTC(Number(year), Number(month) - 1, Number(day), 0, 0, 0)
+    );
+    return { date, dateOnly: true, utc: false };
+  }
+  const dateTime = BASIC_DATE_TIME_PATTERN.exec(value);
+  if (!dateTime) return undefined;
+  const [, year, month, day, hour, minute, second, utc] = dateTime;
+  const date = new Date(
+    Date.UTC(
+      Number(year),
+      Number(month) - 1,
+      Number(day),
+      Number(hour),
+      Number(minute),
+      Number(second)
+    )
+  );
+  return { date, dateOnly: false, utc: Boolean(utc) };
+};
+
+const pad = (value: number): string => value.toString().padStart(2, "0");
+
+const formatBasicDate = (parts: BasicDateParts, date: Date): string => {
+  const datePart = `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}`;
+  if (parts.dateOnly) return datePart;
+  const timePart = `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}`;
+  return `${datePart}T${timePart}${parts.utc ? "Z" : ""}`;
+};
+
+const parseRule = (value: string): Map<string, string> | undefined => {
+  const rule = new Map<string, string>();
+  for (const part of value.split(";")) {
+    const equals = part.indexOf("=");
+    if (equals <= 0 || equals === part.length - 1) return undefined;
+    const key = part.slice(0, equals).toUpperCase();
+    const item = part.slice(equals + 1);
+    if (!/^[A-Z-]+$/.test(key) || rule.has(key)) return undefined;
+    rule.set(key, item);
+  }
+  return rule.size > 0 ? rule : undefined;
+};
+
+const recurrenceAnchor = (value: string, timezone?: string): string =>
+  timezone ? `TZID=${timezone}:${value}` : value;
+
+const expandSimpleRule = (
+  start: string,
+  ruleValue: string,
+  exclusions: Set<string>,
+  limit: number,
+  timezone?: string
+): { anchors: string[]; truncated: boolean } => {
+  const startParts = parseBasicDate(start);
+  if (!startParts) return { anchors: [], truncated: true };
+  const rule = parseRule(ruleValue);
+  if (!rule) return { anchors: [], truncated: true };
+  const supportedKeys = new Set(["FREQ", "COUNT", "INTERVAL"]);
+  if ([...rule.keys()].some((key) => !supportedKeys.has(key))) {
+    return { anchors: [], truncated: true };
+  }
+  const frequency = rule.get("FREQ");
+  if (frequency !== "DAILY" && frequency !== "WEEKLY") {
+    return { anchors: [], truncated: true };
+  }
+  const configuredCount = rule.get("COUNT");
+  const countValue = Number(configuredCount ?? limit);
+  const intervalValue = Number(rule.get("INTERVAL") ?? 1);
+  if (
+    !Number.isSafeInteger(countValue) ||
+    countValue < 1 ||
+    !Number.isSafeInteger(intervalValue) ||
+    intervalValue < 1
+  ) {
+    return { anchors: [], truncated: true };
+  }
+  const stepDays = frequency === "WEEKLY" ? intervalValue * 7 : intervalValue;
+  const requested = Math.min(countValue, limit + 1);
+  const anchors: string[] = [];
+  for (let index = 0; index < requested; index += 1) {
+    const elapsedDays = index * stepDays;
+    if (elapsedDays > MAX_RECURRENCE_HORIZON_DAYS) {
+      return { anchors, truncated: true };
+    }
+    const occurrence = new Date(startParts.date);
+    occurrence.setUTCDate(occurrence.getUTCDate() + elapsedDays);
+    const formatted = formatBasicDate(startParts, occurrence);
+    if (!exclusions.has(formatted)) {
+      anchors.push(recurrenceAnchor(formatted, timezone));
+    }
+  }
+  return {
+    anchors: anchors.slice(0, limit),
+    truncated:
+      configuredCount === undefined ||
+      countValue > limit ||
+      anchors.length > limit,
+  };
+};
+
+/**
+ * Expand only calendar-safe daily/weekly rules. Unsupported RRULE shapes remain
+ * source-visible and explicitly truncated instead of inventing DST semantics.
+ */
+export function summarizeRecurrence(
+  properties: readonly IcalPropertyLike[],
+  start: string | undefined,
+  limit = MAX_RECURRENCE_ANCHORS
+): RecurrenceSummary {
+  const property = (name: string): string | undefined =>
+    properties.find((item) => item.name === name)?.value;
+  const values = (name: string): string[] =>
+    properties
+      .filter((item) => item.name === name)
+      .flatMap((item) =>
+        item.value
+          .split(",")
+          .map((value) => recurrenceAnchor(value, item.params?.get("TZID")))
+      )
+      .map((item) => item.trim())
+      .filter(Boolean);
+
+  const recurrenceId = property("RECURRENCE-ID");
+  const rrule = property("RRULE");
+  const exdates = values("EXDATE").sort();
+  const rdates = values("RDATE").sort();
+  const explicit = rdates.filter((item) => !exdates.includes(item));
+  const startProperty = properties.find((item) => item.name === "DTSTART");
+  const startTimezone = startProperty?.params?.get("TZID");
+  const rawExdates = new Set(
+    properties
+      .filter((item) => item.name === "EXDATE")
+      .flatMap((item) => item.value.split(","))
+  );
+  const expanded =
+    rrule && start
+      ? expandSimpleRule(start, rrule, rawExdates, limit, startTimezone)
+      : {
+          anchors: start ? [recurrenceAnchor(start, startTimezone)] : [],
+          truncated: false,
+        };
+  const occurrenceAnchors = [...new Set([...expanded.anchors, ...explicit])]
+    .sort()
+    .slice(0, limit);
+  return {
+    recurrenceId,
+    rrule,
+    exdates,
+    rdates,
+    occurrenceAnchors,
+    truncated:
+      expanded.truncated || expanded.anchors.length + explicit.length > limit,
+  };
+}