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

An .opml or RSS/Atom file opens as its list of titles and links, with links shown as text #13410

Merged opened this

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

Merged

scout/forge:scout/13384-an-opml-or-rss-atom-file-opens-as-its-li → main 7 commits fork 2 threads · 2 unresolved

  • Merged. scout/13384-an-opml-or-rss-atom-file-opens-as-its-li was merged into main as 1f6fe82.

Review

Sign in to review this change.
9 files changed +306 −0
docs/features/README.md +1
@@ -221,6 +221,7 @@ Read with the guide page [Your apps](../guide-your-apps.md).
221221 - [App templates](app-templates.md)
222222 - [Archive listing](archive-listing.md)
223223 - [A binary file shows its size and type](binary-file.md)
224 - [An OPML or RSS/Atom file opens as its entries](feed-xml.md)
224225 - [Crawl budget](crawl-budget.md)
225226 - [Data browser (core)](data-browser.md)
226227 - [Database size](db-size.md)
docs/features/feed-xml.md added +14
@@ -0,0 +1,14 @@
1 # An OPML or RSS/Atom file opens as its entries
2
3 Open an `.opml`, `.rss` or `.atom` file, or an `.xml` file whose root is `<opml>`,
4 `<rss>`, `<feed>` or `<rdf:RDF>`, in a repository. The page shows one line of
5 text (`This is a feed called Blog: 12 entries.`) and a table of title, date and
6 link. A nested OPML outline is shown under its parent with `– ` before the title,
7 one per level. A link is clickable only when it is an `http:` or `https:` address;
8 any other (`javascript:`, `data:`) stays plain text. Nothing in the file is fetched.
9
10 At most 500 entries are drawn; a line says how many were left out. A file that
11 is not well formed, or that has a DOCTYPE, is shown as source with the reason.
12
13 The terminal's file view draws the same table (Title, Date, Link) and `s`
14 flips to the source. When the file is not drawn, the status line gives the reason.
src/tui/screens/workspace.ts +25
@@ -67,6 +67,7 @@ import { ROW_CAP as TIMELINE_ROW_CAP } from "../../web/render/timeline-table.ts"
6767 import { parseHar, ROW_CAP as HAR_ROW_CAP, duration as harDuration } from "../../web/render/har.ts";
6868 import { gpxFacts, parseGpx } from "../../web/render/gpx.ts";
6969 import { CASE_CAP, parseJunit } from "../../web/render/junit.ts";
70 import { nest, parseEntries } from "../../web/render/feed-xml.ts";
7071 import { parseOpenApi } from "../../web/render/openapi.ts";
7172 import { parseDockerfile } from "../../web/render/dockerfile.ts";
7273 import { parseWorkflow } from "../../web/render/workflow.ts";
@@ -704,6 +705,25 @@ function junitTable(source: string): Table | string {
704705 return { header: ["Result", "Case", "Message"], rows, more: bad.length - Math.min(bad.length, CASE_CAP), delimiter: ",", columns: 3 };
705706 }
706707
708 /**
709 * An OPML or RSS/Atom/RDF file, by the web's own rule (extension, or the root element of `.xml`).
710 */
711 function isFeedPath(path: string, source: Uint8Array): boolean {
712 const k = fileKind(path, source.subarray(0, 4096));
713 return k === "opml" || k === "feed";
714 }
715
716 /**
717 * A subscription list or feed as a table of title, date and link; the reason when it is not drawn.
718 * Shares the web's reader.
719 */
720 function feedTable(source: string): Table | string {
721 const doc = parseEntries(source);
722 if ("error" in doc) return `not drawn as a list of entries: ${doc.error}`;
723 const rows = doc.entries.map((e) => [nest(e.depth) + (e.title || "(untitled)"), e.date, e.link]);
724 return { header: ["Title", "Date", "Link"], rows, more: doc.total - doc.entries.length, delimiter: ",", columns: 3 };
725 }
726
707727 /**
708728 * `.gcode`: a sliced print, drawn as a table of its facts (layers, box, filament, time). Shares the
709729 * web's parser.
@@ -1035,6 +1055,11 @@ class Tab {
10351055 this.table = typeof results === "string" ? null : results;
10361056 this.fault = typeof results === "string" ? results : "";
10371057 if (this.table !== null) this.grid = layoutTable(this.table);
1058 } else if (isFeedPath(this.path, source)) {
1059 const feed = feedTable(new TextDecoder().decode(source));
1060 this.table = typeof feed === "string" ? null : feed;
1061 this.fault = typeof feed === "string" ? feed : "";
1062 if (this.table !== null) this.grid = layoutTable(this.table);
10381063 } else if (isGcodePath(this.path)) {
10391064 this.table = gcodeTable(new TextDecoder().decode(source));
10401065 if (this.table !== null) this.grid = layoutTable(this.table);
src/web/render/feed-xml.ts added +120
@@ -0,0 +1,120 @@
1 /**
2 * An OPML subscription list or an RSS/Atom/RDF feed as its entries: title, date, link. The XML is
3 * read by the same no-entity reader as the JUnit report (`parseXml`: a DOCTYPE is refused, so no
4 * entity expands), and nothing in the file is fetched: no image, no script, no stylesheet. A link
5 * is written out as text; it is made clickable only when it is an `http:` or `https:` address,
6 * so a `javascript:` or `data:` link stays inert text. At most `ENTRY_CAP` entries are drawn and
7 * a plain line says how many were left out. Every string is escaped.
8 */
9
10 import { escapeHtml, html, raw } from "../html.ts";
11 import { fileSize } from "../ui.ts";
12 import { parseXml, type XmlNode } from "./junit.ts";
13 import type { Rendered, RenderInput } from "./renderers.ts";
14
15 export const ENTRY_CAP = 500;
16 const MAX_TEXT = 500;
17
18 export interface Entry {
19 readonly depth: number;
20 readonly title: string;
21 readonly date: string;
22 readonly link: string;
23 }
24 export type Entries =
25 | { readonly what: string; readonly name: string; readonly entries: Entry[]; readonly total: number }
26 | { readonly error: string };
27
28 const clean = (s: string | undefined): string => (s ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_TEXT);
29 const child = (n: XmlNode, ...names: string[]): XmlNode | undefined => n.children.find((c) => names.includes(c.name));
30 const childText = (n: XmlNode, ...names: string[]): string => clean(child(n, ...names)?.text);
31
32 /** An Atom link: the `alternate` one (or the one with no `rel`), by its `href`. */
33 function atomLink(n: XmlNode): string {
34 const links = n.children.filter((c) => c.name === "link");
35 const pick = links.find((l) => (l.attrs.rel ?? "alternate") === "alternate") ?? links[0];
36 return clean(pick?.attrs.href);
37 }
38
39 /** Read an OPML or feed document's text. Pure; never throws. */
40 export function parseEntries(source: string, limit = ENTRY_CAP): Entries {
41 const xml = parseXml(source);
42 if ("error" in xml) return { error: xml.error };
43 const root = xml.root;
44 const entries: Entry[] = [];
45 let total = 0;
46 const add = (e: Entry): void => {
47 total++;
48 if (entries.length < limit) entries.push(e);
49 };
50 if (root.name === "opml") {
51 const body = child(root, "body");
52 const work: { n: XmlNode; depth: number }[] = (body?.children ?? []).filter((c) => c.name === "outline").map((n) => ({ n, depth: 0 })).reverse();
53 while (work.length > 0) {
54 const { n, depth } = work.pop()!;
55 add({
56 depth,
57 title: clean(n.attrs.text ?? n.attrs.title),
58 date: clean(n.attrs.created),
59 link: clean(n.attrs.xmlUrl ?? n.attrs.htmlUrl ?? n.attrs.url),
60 });
61 for (let k = n.children.length - 1; k >= 0; k--) if (n.children[k]!.name === "outline") work.push({ n: n.children[k]!, depth: depth + 1 });
62 }
63 return { what: "subscription list", name: childText(child(root, "head") ?? root, "title"), entries, total };
64 }
65 if (root.name === "rss") {
66 const channel = child(root, "channel");
67 for (const it of channel?.children.filter((c) => c.name === "item") ?? [])
68 add({ depth: 0, title: childText(it, "title"), date: childText(it, "pubDate", "dc:date"), link: childText(it, "link") });
69 return { what: "feed", name: channel === undefined ? "" : childText(channel, "title"), entries, total };
70 }
71 if (root.name === "feed") {
72 for (const e of root.children.filter((c) => c.name === "entry"))
73 add({ depth: 0, title: childText(e, "title"), date: childText(e, "updated", "published"), link: atomLink(e) });
74 return { what: "feed", name: childText(root, "title"), entries, total };
75 }
76 if (root.name === "rdf:RDF" || root.name === "RDF") {
77 for (const it of root.children.filter((c) => c.name === "item"))
78 add({ depth: 0, title: childText(it, "title"), date: childText(it, "dc:date"), link: childText(it, "link") });
79 return { what: "feed", name: childText(child(root, "channel") ?? root, "title"), entries, total };
80 }
81 return { error: "its root element is not <opml>, <rss>, <feed> or <rdf:RDF>" };
82 }
83
84 /**
85 * A nested outline's depth as a plain prefix ("– " per level, at most 8), so no style is needed.
86 */
87 export const nest = (depth: number): string => "– ".repeat(Math.min(depth, 8));
88
89 /** Only an http(s) address becomes a link. */
90 const isWeb = (s: string): boolean => /^https?:\/\/[^\s<>"']+$/i.test(s);
91
92 function linkCell(link: string): string {
93 if (link === "") return "";
94 const text = escapeHtml(link);
95 return isWeb(link) ? `<a href="${text}" rel="noopener noreferrer nofollow">${text}</a>` : text;
96 }
97
98 export function feedXml(input: RenderInput): Rendered {
99 const doc = parseEntries(new TextDecoder().decode(input.body));
100 if ("error" in doc) return { content: html``, lines: 0, fallback: `This file is not drawn as a list of entries: ${doc.error}.` };
101 const n = doc.total.toLocaleString();
102 const lead = `This is a ${doc.what}${doc.name === "" ? "" : ` called ${doc.name}`}: ${n} ${doc.total === 1 ? "entry" : "entries"}.`;
103 let body: string;
104 if (doc.entries.length === 0) body = `<p class="muted">It has no entries.</p>`;
outdated

Principles 3 and 4 and the tokens rule: a hand-written style="padding-left:...rem" is hand-rolled markup, not a token or named component, and it is not covered by a test. Express the indent with an existing spacing token or class, and add a test for the nesting depth.

105 else {
106 const rows = doc.entries
107 .map(
108 (e) =>
109 `<tr><td>${escapeHtml(nest(e.depth) + (e.title || "(untitled)"))}</td><td>${escapeHtml(e.date)}</td><td>${linkCell(e.link)}</td></tr>`,
110 )
111 .join("");
outdated

Principle 7 and the design docs: feed-xml-view is a new component class that is not in docs/design/areas/<area>.md. Document it there or remove it. Separately, this change has no terminal screen in src/tui/ and no docs/features/ how-to; both are required.

112 body = `<table class="table" data-dense aria-label="Entries"><thead><tr><th scope="col">Title</th><th scope="col">Date</th><th scope="col">Link</th></tr></thead><tbody>${rows}</tbody></table>`;
113 }
114 const cut = doc.total > doc.entries.length ? `<p class="muted small">Showing the first ${doc.entries.length.toLocaleString()} of ${n} entries; the rest is in the raw file.</p>` : "";
115 return {
116 content: html`<div><p>${lead}</p>${raw(body)}${raw(cut)}</div>`,
117 lines: 0,
118 summary: `${n} ${doc.total === 1 ? "entry" : "entries"} · ${fileSize(input.size)}`,
119 };
120 }
src/web/render/kinds.ts +18
@@ -55,6 +55,8 @@ export type FileKind =
5555 | "sarif"
5656 | "lcov"
5757 | "junit"
58 | "opml"
59 | "feed"
5860 | "env"
5961 | "openapi"
6062 | "package"
@@ -128,6 +130,8 @@ export const RENDER_CAP: Readonly<Record<FileKind, number>> = {
128130 sarif: 5 * MB,
129131 lcov: 5 * MB,
130132 junit: 5 * MB,
133 opml: 5 * MB,
134 feed: 5 * MB,
131135 env: 1 * MB,
132136 openapi: 1 * MB,
133137 package: 1 * MB,
@@ -273,6 +277,9 @@ const TEXTUAL: Readonly<Record<string, FileKind>> = {
273277 step: "step",
274278 stp: "step",
275279 sarif: "sarif",
280 opml: "opml",
281 rss: "feed",
282 atom: "feed",
276283 lcov: "lcov",
277284 sql: "sql",
278285 graphql: "graphql",
@@ -385,6 +392,15 @@ function isJunit(path: string, head: Uint8Array): boolean {
385392 return root?.[1] === "testsuites" || root?.[1] === "testsuite";
386393 }
387394
395 /** An `.xml` file whose root element (past the prolog and comments) is `<opml>` or a feed's. */
396 function xmlFeedKind(path: string, head: Uint8Array): "opml" | "feed" | undefined {
397 if (extension(path) !== "xml") return undefined;
398 const text = new TextDecoder().decode(head).replace(/^\uFEFF/, "").replace(/<\?[\s\S]*?\?>|<!--[\s\S]*?-->/g, "");
399 const root = /<([A-Za-z_][\w.:-]*)/.exec(text)?.[1];
400 if (root === "opml") return "opml";
401 return root === "rss" || root === "feed" || root === "rdf:RDF" ? "feed" : undefined;
402 }
403
388404 /** Git's own heuristic: a NUL in the first 8 KB means binary. */
389405 const looksBinary = (head: Uint8Array): boolean => head.subarray(0, 8000).includes(0);
390406
@@ -412,6 +428,8 @@ export function fileKind(path: string, head: Uint8Array): FileKind {
412428 if (isLcovName(path)) return "lcov";
413429 if (isEnvExample(path)) return "env";
414430 if (isJunit(path, head)) return "junit";
431 const xmlFeed = xmlFeedKind(path, head);
432 if (xmlFeed !== undefined) return xmlFeed;
415433 if (isOpenApiName(path)) return "openapi";
416434 if (isPackageName(path)) return "package";
417435 if (isMakefileName(path)) return "makefile";
src/web/render/renderers.ts +3
@@ -29,6 +29,7 @@ import { otio } from "./otio.ts";
2929 import { edl } from "./edl.ts";
3030 import { fcpxml } from "./fcpxml.ts";
3131 import { junit } from "./junit.ts";
32 import { feedXml } from "./feed-xml.ts";
3233 import { vcf } from "./vcf.ts";
3334 import { htmlPreview } from "./html_preview.ts";
3435 import { image } from "./image.ts";
@@ -145,6 +146,8 @@ export const RENDERERS: Partial<Readonly<Record<FileKind, Renderer>>> = {
145146 sarif,
146147 lcov,
147148 junit,
149 opml: feedXml,
150 feed: feedXml,
148151 env: envView,
149152 sql: sqlView,
150153 graphql,
test/render-feed-xml.test.ts added +102
@@ -0,0 +1,102 @@
1 /**
2 * OPML and RSS/Atom as entry lists: each format, a hostile title, link safety, the cap, an empty
3 * file.
4 */
5 import { describe, expect, test } from "bun:test";
6 import { ENTRY_CAP, feedXml, parseEntries } from "../src/web/render/feed-xml.ts";
7 import { fileKind } from "../src/web/render/kinds.ts";
8 import { RENDERERS } from "../src/web/render/renderers.ts";
9
10 const enc = (s: string): Uint8Array => new TextEncoder().encode(s);
11 const draw = (text: string, path = "a.opml") => feedXml({ path, size: text.length, body: enc(text), media: "/m", download: "/d" });
12
13 const OPML = `<?xml version="1.0"?><opml version="2.0"><head><title>My feeds</title></head><body>
14 <outline text="News"><outline text="Wire" xmlUrl="https://example.com/feed.xml" htmlUrl="https://example.com"/></outline>
15 <outline text="Odd" xmlUrl="javascript:alert(1)"/></body></opml>`;
16 const RSS = `<rss version="2.0"><channel><title>Blog</title><item><title>One &amp; two</title><pubDate>Mon, 01 Jan 2024 00:00:00 GMT</pubDate><link>https://e.com/1</link></item></channel></rss>`;
17 const ATOM = `<feed xmlns="http://www.w3.org/2005/Atom"><title>Atom</title><entry><title>Post</title><updated>2024-02-03T00:00:00Z</updated><link rel="self" href="https://e.com/self"/><link rel="alternate" href="https://e.com/post"/></entry></feed>`;
18
19 describe("feed-xml", () => {
20 test("the registry names each by extension and by root; other xml stays source", () => {
21 expect(fileKind("a.opml", enc("<opml/>"))).toBe("opml");
22 expect(fileKind("a.rss", enc("<rss/>"))).toBe("feed");
23 expect(fileKind("a.atom", enc("<feed/>"))).toBe("feed");
24 expect(fileKind("a.xml", enc('<?xml version="1.0"?><opml/>'))).toBe("opml");
25 expect(fileKind("a.xml", enc("<rss/>"))).toBe("feed");
26 expect(fileKind("a.xml", enc("<project/>"))).toBe("text");
27 expect(RENDERERS.opml).toBe(feedXml);
28 expect(RENDERERS.feed).toBe(feedXml);
29 });
30
31 test("opml: nested outlines, titles and links; only http(s) is clickable", () => {
32 const r = draw(OPML);
33 const h = String(r.content);
34 expect(h).toContain("This is a subscription list called My feeds: 3 entries.");
35 expect(h).toContain("Wire");
36 expect(h).toContain('<a href="https://example.com/feed.xml"');
37 expect(h).toContain("javascript:alert(1)");
38 expect(h).not.toContain('href="javascript');
39 });
40
41 test("rss and atom: title, date, link", () => {
42 const rss = String(draw(RSS, "a.rss").content);
43 expect(rss).toContain("One &amp; two");
44 expect(rss).toContain("Mon, 01 Jan 2024 00:00:00 GMT");
45 expect(rss).toContain("https://e.com/1");
46 const atom = String(draw(ATOM, "a.atom").content);
47 expect(atom).toContain("2024-02-03T00:00:00Z");
48 expect(atom).toContain("https://e.com/post");
49 expect(atom).not.toContain("https://e.com/self");
50 });
51
52 test("a hostile title is escaped and nothing loads", () => {
53 const h = String(draw(`<rss><channel><item><title>&lt;img src=x onerror=alert(1)&gt;&lt;script&gt;</title><link>data:text/html,&lt;b&gt;</link></item></channel></rss>`, "a.rss").content);
54 expect(h).not.toContain("<img");
55 expect(h).not.toContain("<script");
56 expect(h).toContain("&lt;img src=x");
57 expect(h).not.toContain('href="data');
58 });
59
60 test("a DOCTYPE is refused and falls back to source", () => {
61 expect(draw(`<!DOCTYPE x [<!ENTITY a "b">]><rss/>`, "a.rss").fallback).toContain("DOCTYPE");
62 });
63
64 test("more than the cap is cut with a plain line", () => {
65 const items = Array.from({ length: ENTRY_CAP + 5 }, (_, i) => `<item><title>t${i}</title></item>`).join("");
66 const r = draw(`<rss><channel>${items}</channel></rss>`, "a.rss");
67 const h = String(r.content);
68 expect(h).toContain(`Showing the first ${ENTRY_CAP} of 505 entries`);
69 expect(h).toContain(`t${ENTRY_CAP - 1}<`);
70 expect(h).not.toContain(`t${ENTRY_CAP}<`);
71 });
72
73 test("an empty file says so; a foreign root falls back", () => {
74 expect(String(draw(`<opml><body/></opml>`).content)).toContain("It has no entries.");
75 expect(parseEntries("<project/>")).toHaveProperty("error");
76 expect(draw("").fallback).toBeDefined();
77 });
78 });
79
80 describe("feed-xml: RDF, nesting, Atom link without rel", () => {
81 test("an RDF feed reads its items and dc:date", () => {
82 const doc = parseEntries(`<rdf:RDF><channel><title>Old</title></channel><item><title>I</title><dc:date>2020-01-01</dc:date><link>https://e.com/i</link></item></rdf:RDF>`);
83 if ("error" in doc) throw new Error(doc.error);
84 expect(doc.name).toBe("Old");
85 expect(doc.entries).toEqual([{ depth: 0, title: "I", date: "2020-01-01", link: "https://e.com/i" }]);
86 });
87 test("OPML nesting is kept as depth, drawn as a prefix with no inline style", () => {
88 const text = `<opml><body><outline text="A"><outline text="B"><outline text="C"/></outline></outline></body></opml>`;
89 const doc = parseEntries(text);
90 if ("error" in doc) throw new Error(doc.error);
91 expect(doc.entries.map((e) => e.depth)).toEqual([0, 1, 2]);
92 const out = String(draw(text).content);
93 expect(out).toContain("<td>– – C</td>");
94 expect(out).not.toContain("style=");
95 expect(out).not.toContain("feed-xml-view");
96 });
97 test("an Atom link with no rel is the entry's link", () => {
98 const doc = parseEntries(`<feed><entry><title>P</title><link href="https://e.com/p"/></entry></feed>`);
99 if ("error" in doc) throw new Error(doc.error);
100 expect(doc.entries[0]!.link).toBe("https://e.com/p");
101 });
102 });
test/render-kinds.test.ts +3
@@ -103,6 +103,9 @@ const SAMPLES: Record<string, [Uint8Array, FileKind, string]> = {
103103 graphql: [enc("type A { b: Int }\n"), "graphql", "application/octet-stream"],
104104 gql: [enc("type A { b: Int }\n"), "graphql", "application/octet-stream"],
105105 sarif: [enc('{"runs":[]}'), "sarif", "application/octet-stream"],
106 opml: [enc("<opml/>"), "opml", "application/octet-stream"],
107 rss: [enc("<rss/>"), "feed", "application/octet-stream"],
108 atom: [enc("<feed/>"), "feed", "application/octet-stream"],
106109 lcov: [enc("SF:a.ts\nend_of_record\n"), "lcov", "application/octet-stream"],
107110 };
108111
test/tui-workspace-formats.test.ts +20
@@ -568,6 +568,26 @@ describe("the terminal workspace, by file type", () => {
568568 }
569569 });
570570
571 test("an OPML file opens as its titles and links, sharing the web reader", async () => {
572 const made = await createRepo(forge, alice, { name: "opmlrepo", visibility: "public", description: "feeds" });
573 if (!made.ok) throw new Error("repo failed");
574 const opml = '<opml><body><outline text="News"><outline text="Wire" xmlUrl="https://e.com/f.xml"/></outline></body></opml>';
575 await commitToBranch(forge, alice, made.value, { message: "seed", files: [{ path: "feeds.opml", content: opml }, { path: "bad.rss", content: "<nope" }] });
576 const h = boot();
577 try {
578 await h.settle();
579 await open(h, "opmlrepo");
580 await openFile(h, "feeds.opml");
581 expect(h.text()).toContain("– Wire");
582 expect(h.text()).toContain("https://e.com/f.xml");
583 await h.press("s");
584 expect(h.text()).toContain("<outline text=");
585 await h.press("q");
586 } finally {
587 h.stop();
588 }
589 });
590
571591 test("a .env.example opens as a table with secrets masked, and s flips to the source", async () => {
572592 const made = await createRepo(forge, alice, { name: "envrepo", visibility: "public", description: "tests" });
573593 if (!made.ok) throw new Error("repo failed");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs