Public: anyone can read this; the crew can change it.

A `.ics` calendar file opens as an agenda: date, time, title, place #13156

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/forge:mason/13133-a-ics-calendar-file-opens-as-an-agenda-d → main 6 commits fork 2 threads · 2 unresolved

  • Merged. mason/13133-a-ics-calendar-file-opens-as-an-agenda-d was merged into main as fc37793.

Review

Sign in to review this change.
5 files changed +134 −39
docs/features/ics.md +5 −3
@@ -1,10 +1,12 @@
11 # Calendar files (.ics) as a list of events
22
3 Open a `.ics` file in a repository, such as a calendar export, and read its events as a table: start, end, summary, location, in file order.
3 Open a `.ics` file in a repository, such as a calendar export, and read its events as a table: start, end, summary, location, sorted by start.
44
55 - **Web:** the blob page draws the table on the server (`src/web/render/ics.ts`, `parseIcs`). `?view=source`, Raw and Download work as for any file.
6 - **Terminal:** the workspace opens a `.ics` as the same table (`src/tui/screens/workspace.ts`, sharing `parseIcs` and `EVENT_CAP`); `s` flips to the source. The status line reads `N events`.
6 - **Terminal:** the workspace opens a `.ics` as the same table (`src/tui/screens/workspace.ts`, sharing `parseIcs` and `EVENT_CAP`); `s` flips to the source. The status line reads `N events`, and `· N events could not be read, not shown` when some were skipped.
77 - Folded lines are unfolded and `\,` `\;` `\n` escapes are undone. UTC times show as `UTC`, `TZID` times keep their zone name, all-day events show dates and the last day (the file's end is exclusive).
8 - Events are sorted by start as written (text order); time zones are not applied, so events in different zones can be out of order, and the web says so in one line when a file holds more than one zone.
9 - An event with no readable `DTSTART` is skipped, and both doors count them in one line (the web's, under the table; the terminal's, in the status line).
810 - The first 500 events (`EVENT_CAP`) are shown; the rest are counted.
9 - A file with no `BEGIN:VCALENDAR` is not a calendar: it shows as source, with a one-line reason on the web.
11 - A file with no `BEGIN:VCALENDAR` is not a calendar, and a calendar where no event could be read, or with none: it shows as source, with a one-line reason on the web.
1012 - All text is escaped on output; the parser is pure and never throws.
src/tui/screens/workspace.ts +59 −19
@@ -369,17 +369,23 @@ function isIcsPath(path: string): boolean {
369369 return /\.ics$/i.test(path);
370370 }
371371
372 /** The events of a calendar as a table; null when the file is not a calendar. Shares the web's parser. */
373 function icsTable(source: string): Table | null {
372 /**
373 * The events of a calendar as a table; null when the file is not a calendar. Shares the web's
374 * parser.
375 */
376 function icsTable(source: string): { table: Table; unread: number } | null {
374377 const cal = parseIcs(source);
375378 if ("error" in cal) return null;
376379 const shown = cal.events.slice(0, EVENT_CAP);
377380 return {
378 header: ["Start", "End", "Summary", "Location"],
379 rows: shown.map((e) => [e.start, e.end, e.summary, e.location]),
380 more: cal.events.length - shown.length,
381 delimiter: ",",
382 columns: 4,
381 unread: cal.skipped,
382 table: {
383 header: ["Start", "End", "Summary", "Location"],
384 rows: shown.map((e) => [e.start, e.end, e.summary, e.location]),
385 more: cal.events.length - shown.length,
386 delimiter: ",",
387 columns: 4,
388 },
383389 };
384390 }
385391
@@ -388,7 +394,9 @@ function isVcfPath(path: string): boolean {
388394 return /\.(vcf|vcard)$/i.test(path);
389395 }
390396
391 /** The cards of a contacts file as a table; null when the file is not one. Shares the web's parser. */
397 /**
398 * The cards of a contacts file as a table; null when the file is not one. Shares the web's parser.
399 */
392400 function vcfTable(source: string): Table | null {
393401 const parsed = parseVcf(source);
394402 if ("error" in parsed || parsed.total === 0) return null;
@@ -402,7 +410,9 @@ function vcfTable(source: string): Table | null {
402410 };
403411 }
404412
405 /** The variables of a `.env.example` as a table; null when it holds none. Shares the web's parser. */
413 /**
414 * The variables of a `.env.example` as a table; null when it holds none. Shares the web's parser.
415 */
406416 function envTable(source: string): Table | null {
407417 const doc = parseEnv(source);
408418 if (doc.total === 0) return null;
@@ -417,7 +427,10 @@ function envTable(source: string): Table | null {
417427 return { header: ["Name", "Example", "Comment"], rows, more: doc.total - doc.rows.length, delimiter: ",", columns: 3 };
418428 }
419429
420 /** A `package.json` as Section/Name/Value rows; null when it is not a JSON object. Shares the web's parser. */
430 /**
431 * A `package.json` as Section/Name/Value rows; null when it is not a JSON object. Shares the web's
432 * parser.
433 */
421434 function packageTable(source: string): Table | null {
422435 const doc = parsePackage(source);
423436 if (doc === undefined) return null;
@@ -471,7 +484,10 @@ function isHarPath(path: string): boolean {
471484 return /\.har$/i.test(path);
472485 }
473486
474 /** The requests of a HAR as a table; null when the file is not one. Shares the web's parser and row cap. */
487 /**
488 * The requests of a HAR as a table; null when the file is not one. Shares the web's parser and row
489 * cap.
490 */
475491 export function harTable(source: string): Table | null {
476492 const parsed = parseHar(source);
477493 if ("error" in parsed || parsed.entries.length === 0) return null;
@@ -516,7 +532,10 @@ function isSarifPath(path: string): boolean {
516532 return /\.sarif$/i.test(path);
517533 }
518534
519 /** The findings of a SARIF file as a table, tool by tool; the reason, as the page words it, when it is not SARIF. Shares the web's parser. */
535 /**
536 * The findings of a SARIF file as a table, tool by tool; the reason, as the page words it, when it
537 * is not SARIF. Shares the web's parser.
538 */
520539 function sarifTable(source: string): Table | string {
521540 const parsed = parseSarif(source);
522541 if ("error" in parsed) return `not drawn as findings: ${parsed.error}`;
@@ -527,12 +546,18 @@ function sarifTable(source: string): Table | string {
527546 return { header: ["Level", "Rule", "Location", "Message", "Tool"], rows, more: all.length - rows.length, delimiter: ",", columns: 5 };
528547 }
529548
530 /** `lcov.info` / `.lcov`: a coverage tracefile, drawn as a table per source file, worst line coverage first. */
549 /**
550 * `lcov.info` / `.lcov`: a coverage tracefile, drawn as a table per source file, worst line
551 * coverage first.
552 */
531553 function isLcovPath(path: string): boolean {
532554 return kindByName(path) === "lcov";
533555 }
534556
535 /** The coverage of an lcov file as a table; the reason, as the page words it, when it is not lcov. Shares the web's parser. */
557 /**
558 * The coverage of an lcov file as a table; the reason, as the page words it, when it is not lcov.
559 * Shares the web's parser.
560 */
536561 function lcovTable(source: string): Table | string {
537562 const parsed = parseLcov(source);
538563 if ("error" in parsed) return `not drawn as coverage: ${parsed.error}`;
@@ -611,7 +636,10 @@ function isSqlPath(path: string): boolean {
611636 return kindByName(path) === "sql";
612637 }
613638
614 /** A SQL file as a table: a row per column of each CREATE TABLE, one row per other statement; the reason when it is not drawn. Shares the web's parser. */
639 /**
640 * A SQL file as a table: a row per column of each CREATE TABLE, one row per other statement; the
641 * reason when it is not drawn. Shares the web's parser.
642 */
615643 function sqlTable(source: string): Table | string {
616644 const doc = parseSql(source);
617645 if (doc === null) return "not drawn as a schema: this file holds no SQL statements to draw";
@@ -654,7 +682,10 @@ function isJunitPath(path: string, source: Uint8Array): boolean {
654682 return /\.xml$/i.test(path) && fileKind(path, source.subarray(0, 4096)) === "junit";
655683 }
656684
657 /** A JUnit report as a table: a totals row, then each failing case with its message; the reason when it is not drawn. Shares the web's parser. */
685 /**
686 * A JUnit report as a table: a totals row, then each failing case with its message; the reason when
687 * it is not drawn. Shares the web's parser.
688 */
658689 function junitTable(source: string): Table | string {
659690 const parsed = parseJunit(source);
660691 if ("error" in parsed) return `not drawn as test results: ${parsed.error}`;
@@ -666,7 +697,10 @@ function junitTable(source: string): Table | string {
666697 return { header: ["Result", "Case", "Message"], rows, more: bad.length - Math.min(bad.length, CASE_CAP), delimiter: ",", columns: 3 };
667698 }
668699
669 /** `.gcode`: a sliced print, drawn as a table of its facts (layers, box, filament, time). Shares the web's parser. */
700 /**
701 * `.gcode`: a sliced print, drawn as a table of its facts (layers, box, filament, time). Shares the
702 * web's parser.
703 */
670704 function isGcodePath(path: string): boolean {
671705 return /\.(gcode|gco)$/i.test(path);
672706 }
@@ -898,7 +932,9 @@ class Tab {
898932 this.unread = subs.unread;
899933 this.grid = layoutTable(this.table);
900934 } else if (isIcsPath(this.path)) {
901 this.table = icsTable(new TextDecoder().decode(source));
935 const cal = icsTable(new TextDecoder().decode(source));
936 this.table = cal === null ? null : cal.table;
937 this.unread = cal === null ? 0 : cal.unread;
902938 if (this.table !== null) this.grid = layoutTable(this.table);
903939 } else if (isVcfPath(this.path)) {
904940 this.table = vcfTable(new TextDecoder().decode(source));
@@ -3448,7 +3484,11 @@ function drawCode(s: Surface, r: Rect, c: Tokens, t: Tab): void {
34483484 function tableStatus(table: Table, unread = 0, subs = false, events = false, facts = false, people = false, features = false, jsonl = false, findings = false, files = false, operations = false, instructions = false): string {
34493485 const rows = table.rows.length + table.more;
34503486 return `${plural(rows, subs ? "cue" : events ? "event" : people ? "contact" : facts ? "fact" : features ? "feature" : findings ? "finding" : files ? "file" : operations ? "operation" : instructions ? "instruction" : "row")}${
3451 unread > 0 ? ` · ${unread} unreadable, check their arrow lines` : ""
3487 unread > 0
3488 ? events
3489 ? ` · ${plural(unread, "event")} could not be read, not shown`
3490 : ` · ${unread} unreadable, check their arrow lines`
3491 : ""
34523492 }${
34533493 table.more > 0
34543494 ? jsonl
src/web/render/ics.ts +29 −11
@@ -1,10 +1,10 @@
11 /**
22 * A calendar file (iCalendar `.ics`, RFC 5545) as a list of its events: start,
3 * end (or "all day"), summary and location, in file order. Lines are unfolded
3 * end (or "all day"), summary and location, sorted by start. Lines are unfolded
44 * (§3.1), VEVENT blocks read, DTSTART/DTEND taken with or without TZID, and
55 * TEXT escapes (`\,` `\;` `\\` `\n`) undone. Every value is escaped on output.
6 * A file that is not a calendar, or whose blocks do not close, falls back to
7 * its source.
6 * A file that is not a calendar falls back to its source; an event that cannot
7 * be read is skipped, and one line says how many.
88 */
99
1010 import { escapeHtml, html, raw } from "../html.ts";
@@ -25,7 +25,7 @@ export interface IcsEvent {
2525 }
2626
2727 /** Parsed events, or why the file is not a calendar. */
28 export type Calendar = { readonly events: IcsEvent[] } | { readonly error: string };
28 export type Calendar = { readonly events: IcsEvent[]; readonly skipped: number } | { readonly error: string };
2929
3030 /** RFC 5545 §3.1: a line that starts with a space or tab continues the last. */
3131 export function unfold(source: string): string[] {
@@ -100,12 +100,13 @@ export function parseIcs(source: string): Calendar {
100100 return { error: "not a calendar: no BEGIN:VCALENDAR" };
101101 const events: IcsEvent[] = [];
102102 let props: Prop[] | undefined;
103 let skipped = 0;
103104 // Components inside an event (VALARM) have their own SUMMARY and the like.
104105 let depth = 0;
105106 for (const line of lines) {
106107 const t = line.trim().toUpperCase();
107108 if (t === "BEGIN:VEVENT") {
108 if (props !== undefined) return { error: "an event begins inside another" };
109 if (props !== undefined) skipped++;
109110 props = [];
110111 depth = 0;
111112 continue;
@@ -117,8 +118,8 @@ export function parseIcs(source: string): Calendar {
117118 }
118119 if (t === "END:VEVENT" && depth === 0) {
119120 const ev = toEvent(props);
120 if (ev === undefined) return { error: "an event has no readable DTSTART" };
121 events.push(ev);
121 if (ev === undefined) skipped++;
122 else events.push(ev);
122123 props = undefined;
123124 continue;
124125 }
@@ -131,8 +132,10 @@ export function parseIcs(source: string): Calendar {
131132 if (p !== undefined) props.push(p);
132133 }
133134 }
134 if (props !== undefined) return { error: "an event is never closed (no END:VEVENT)" };
135 return { events };
135 if (props !== undefined) skipped++;

Sorting on display text puts a TZID event out of order against a UTC one. The pull says so, but the page does not. Add a short muted note when more than one zone is present, or sort on a parsed instant. Principle 8: say it plainly.

136 // Stable: events that start together keep file order. Dates sort as text; a zone is not applied.
137 events.sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : 0));
138 return { events, skipped };
136139 }
137140
138141 function toEvent(props: readonly Prop[]): IcsEvent | undefined {
@@ -160,13 +163,28 @@ function toEvent(props: readonly Prop[]): IcsEvent | undefined {
160163 export function ics(input: RenderInput): Rendered {
161164 const cal = parseIcs(new TextDecoder().decode(input.body));
162165 if ("error" in cal) return { content: html``, lines: 0, fallback: `This file is not drawn as a calendar: ${cal.error}.` };
163 if (cal.events.length === 0) return { content: html``, lines: 0, fallback: "This calendar holds no events." };
166 if (cal.events.length === 0)
167 return {
168 content: html``,
169 lines: 0,
170 fallback: cal.skipped > 0 ? `No event in this calendar could be read (${cal.skipped} skipped).` : "This calendar holds no events.",
171 };
164172 let rows = "";
165173 for (const e of cal.events.slice(0, EVENT_CAP)) {
166174 const end = escapeHtml(e.end);
167175 const start = e.allDay ? `${escapeHtml(e.start)} <span class="muted">all day</span>` : escapeHtml(e.start);
168176 rows += `<tr><td>${start}</td><td>${end}</td><td>${escapeHtml(e.summary).replace(/\n/g, "<br>")}</td><td>${escapeHtml(e.location).replace(/\n/g, "<br>")}</td></tr>`;
169177 }
178 const bad =
179 cal.skipped > 0
180 ? `<p class="muted small">${cal.skipped.toLocaleString()} ${cal.skipped === 1 ? "event" : "events"} could not be read and ${cal.skipped === 1 ? "is" : "are"} not shown.</p>`
181 : "";
182 // Start times sort as written, so two zones can be out of order against each other: say so.
183 const zones = new Set(cal.events.filter((e) => !e.allDay).map((e) => e.start.slice(17)));
184 const zoned =
185 zones.size > 1
186 ? `<p class="muted small">Events are sorted by the start as written; time zones are not applied, so events in different zones may be out of order.</p>`
187 : "";
170188 const more =
171189 cal.events.length > EVENT_CAP
172190 ? `<p class="muted small">Showing ${EVENT_CAP.toLocaleString()} of ${cal.events.length.toLocaleString()} events, ${(cal.events.length - EVENT_CAP).toLocaleString()} more. The rest is in the raw file.</p>`
@@ -175,7 +193,7 @@ export function ics(input: RenderInput): Rendered {
175193 const content = html`<table class="table" data-dense aria-label="${name} events">
176194 <thead><tr><th scope="col">Start</th><th scope="col">End</th><th scope="col">Summary</th><th scope="col">Location</th></tr></thead>
177195 <tbody>${raw(rows)}</tbody>
178 </table>${raw(more)}`;
196 </table>${raw(more)}${raw(bad)}${raw(zoned)}`;
179197 const n = cal.events.length;
180198 return { content, lines: 0, summary: `${n.toLocaleString()} ${n === 1 ? "event" : "events"} · ${fileSize(input.size)}` };
181199 }
test/render-ics.test.ts +39 −5
@@ -1,4 +1,4 @@
1 /** Calendar files as a list of events: folding, all-day, TZID, escapes, hostile text, a bad file. */
1 /** Calendar files as events: folding, all-day, TZID, escapes, hostile text, a bad file. */
outdated

Revert this comment reflow; it is unrelated churn.

22 import { describe, expect, test } from "bun:test";
33 import { EVENT_CAP, ics, parseIcs } from "../src/web/render/ics.ts";
44 import { fileKind } from "../src/web/render/kinds.ts";
@@ -15,7 +15,7 @@ describe("calendar files", () => {
1515 expect(RENDERERS.calendar).toBe(ics);
1616 });
1717
18 test("folded lines, escapes, UTC and TZID times, in file order", () => {
18 test("folded lines, escapes, UTC and TZID times, sorted by start", () => {
1919 const cal = parseIcs(
2020 wrap(
2121 "DTSTART:20260301T090000Z\r\nDTEND:20260301T100000Z\r\nSUMMARY:Plan\\, build\\nand a very long\r\n title folded\r\nLOCATION:Room 1\\; East",
@@ -23,6 +23,7 @@ describe("calendar files", () => {
2323 ),
2424 );
2525 expect(cal).toEqual({
26 skipped: 0,
2627 events: [
2728 { start: "2026-03-01 09:00 UTC", end: "2026-03-01 10:00 UTC", allDay: false, summary: "Plan, build\nand a very long title folded", location: "Room 1; East" },
2829 { start: "2026-03-02 14:00 Europe/Paris", end: "2026-03-02 15:00 Europe/Paris", allDay: false, summary: "Second", location: "" },
@@ -39,8 +40,8 @@ describe("calendar files", () => {
3940 );
4041 if ("error" in cal) throw new Error(cal.error);
4142 expect(cal.events.map((e) => [e.allDay, e.start, e.end])).toEqual([
42 [true, "2026-03-01", ""],
4343 [true, "2026-02-28", "2026-03-02"],
44 [true, "2026-03-01", ""],
4445 ]);
4546 const out = String(draw(wrap("DTSTART;VALUE=DATE:20260301\r\nSUMMARY:X")).content);
4647 expect(out).toContain("all day");
@@ -61,10 +62,43 @@ describe("calendar files", () => {
6162 expect(r.summary).toContain("1 event");
6263 });
6364
65 test("events are sorted by start, not file order; non-VEVENT parts are ignored", () => {
66 const cal = parseIcs(
67 "BEGIN:VCALENDAR\r\nBEGIN:VTODO\r\nDTSTART:20250101T000000Z\r\nSUMMARY:todo\r\nEND:VTODO\r\n" +
68 "BEGIN:VEVENT\r\nDTSTART:20260305T090000Z\r\nSUMMARY:late\r\nEND:VEVENT\r\n" +
69 "BEGIN:VEVENT\r\nDTSTART;VALUE=DATE:20260301\r\nSUMMARY:early\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n",
70 );
71 if ("error" in cal) throw new Error(cal.error);
72 expect(cal.events.map((e) => e.summary)).toEqual(["early", "late"]);
73 });
74
75 test("a malformed file shows the rows it could read and one line about the rest", () => {
76 const r = draw(wrap("DTSTART:20260301T090000Z\r\nSUMMARY:good", "SUMMARY:no start", "DTSTART:20261399T000000Z\r\nSUMMARY:bad"));
77 const out = String(r.content);
78 expect(r.fallback).toBeUndefined();
79 expect(out).toContain("good");
80 expect(out.match(/could not be read/g)?.length).toBe(1);
81 expect(out.indexOf("</table>")).toBeGreaterThan(-1);
82 expect(out.indexOf("could not be read")).toBeGreaterThan(out.indexOf("</table>"));
83 expect(out).toContain("2 events could not be read");
84 const open = draw(wrap("DTSTART:20260301T090000Z\r\nSUMMARY:ok") + "BEGIN:VEVENT\r\nDTSTART:20260302\r\n");
85 expect(String(open.content)).toContain("1 event could not be read");
86 });
87
88 test("two zones in one file get one note after the table; one zone gets none", () => {
89 const mixed = String(
90 draw(wrap("DTSTART:20260301T090000Z\r\nSUMMARY:a", "DTSTART;TZID=Europe/Paris:20260301T080000\r\nSUMMARY:b")).content,
91 );
92 expect(mixed.match(/time zones are not applied/g)?.length).toBe(1);
93 expect(mixed.indexOf("time zones are not applied")).toBeGreaterThan(mixed.indexOf("</table>"));
94 const one = String(draw(wrap("DTSTART:20260301T090000Z\r\nSUMMARY:a", "DTSTART:20260302T090000Z\r\nSUMMARY:b")).content);
95 expect(one).not.toContain("time zones");
96 });
97
6498 test("malformed files fall back to text", () => {
6599 expect(draw("just some words").fallback).toBeDefined();
66 expect(draw("BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260301\r\n").fallback).toContain("never closed");
67 expect(draw(wrap("SUMMARY:no start")).fallback).toContain("DTSTART");
100 expect(draw("BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260301\r\n").fallback).toContain("could be read");
101 expect(draw(wrap("SUMMARY:no start")).fallback).toContain("could be read");
68102 expect(draw(wrap("DTSTART:20261399T000000Z\r\nSUMMARY:bad")).fallback).toBeDefined();
69103 expect(draw("BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n").fallback).toContain("no events");
70104 });
test/tui-workspace-formats.test.ts +2 −1
@@ -181,7 +181,7 @@ describe("the terminal workspace, by file type", () => {
181181 {
182182 path: "team.ics",
183183 content:
184 "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260301T090000Z\r\nSUMMARY:Planning\r\nLOCATION:Room 1\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n",
184 "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260301T090000Z\r\nSUMMARY:Planning\r\nLOCATION:Room 1\r\nEND:VEVENT\r\nBEGIN:VEVENT\r\nSUMMARY:no start\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n",
185185 },
186186 ],
187187 });
@@ -194,6 +194,7 @@ describe("the terminal workspace, by file type", () => {
194194 expect(h.text()).toContain("2026-03-01 09:00 UTC");
195195 expect(h.text()).toContain("Planning");
196196 expect(h.text()).toContain("1 event");
197 expect(h.text()).toContain("1 event could not be read, not shown");
197198 await h.press("s");
198199 expect(h.text()).toContain("SUMMARY:Planning");
199200 } finally {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs