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

The guide lists every kind of file the viewer opens, generated from the same table the viewer reads #13891

Merged opened this

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

Merged

The "your apps" guide now has a "Which files open" section. It's a table of every file kind the viewer draws, with its names or extensions and its size cap. bun x tsc --noEmit, bun scripts/gate.ts and bun test test/kinds-guide.test.ts pass here.

Notes

shipped production is serving it deploy 8e1361f

opened this

The "your apps" guide now has a "Which files open" section. It's a table of every file kind the viewer draws, with its names or extensions and its size cap. bun x tsc --noEmit, bun scripts/gate.ts and bun test test/kinds-guide.test.ts pass here. I did not run scripts/design-lint.ts or the full suite.

  • Table: it sits between generated-section markers in docs/guide-your-apps.md. Run bun scripts/kinds-guide.ts to rewrite it. The script reads the caps (RENDER_CAP) and the extension tables from kinds.ts.
  • kinds.ts additions: this is slightly more than the "export only" in the issue.

- ALL_KINDS lists the kinds. - kindMatches(kind) gives each kind's extensions and other names, such as Makefile or .github/workflows/*.yml. - A small BY_NAME table holds the kinds that no extension names, such as .xml files recognised by their root element.

  • Labels: the human names live in the script as a Record<FileKind, string>, so a new kind without a label fails tsc.
  • Tests (test/kinds-guide.test.ts):

- The guide fails when its committed text differs from the generated table. The message says to run bun scripts/kinds-guide.ts. - Another test fails and names any kind with no entry in RENDERERS. text and binary are exempt, since they keep the source view or Download. - The remaining tests check that a stale table is caught and repaired, and spot-check a few kinds.

  • Left out: the table doesn't show which kinds can be sniffed by content, such as the executables sniffType names. It also doesn't show the 5 MB read ceiling that sits under some caps, such as SQLite and PSD.
  • Pre-push hook: it asked for a commit saying how to try the change. I added an empty "Try:" commit for that.

To try it, open the section in the guide and look at the SQLite row. It should read .db, .sqlite, .sqlite3 and 5 MB.

🤖 Generated with Claude Code

Closes #13869

Show 3 earlier items

7 earlier comments · 2 events
commented

<!-- look-pages 2db7199170eb --> Look pages for 2db7199, from the gate:

  • look pages (named): this pull changes src/web/render/kinds.ts; a commit names /docs
commented

I fixed the three failing feature-note tests and pushed. The other two failures I couldn't reproduce and left alone.

  • Cause: moving the table into docs/features/file-kinds.md left that note out of the features index. It also left the guide page with more than three direct links to feature notes, which test/feature-orphans.test.ts doesn't allow.
  • Index: docs/features/README.md now has a row for file-kinds.md under "Files in the browser".
  • Guide page: docs/guide-your-apps.md links the index instead of the note directly, which keeps it at 297 words.
  • Tests: test/feature-orphans.test.ts, test/guide.test.ts and test/kinds-guide.test.ts pass locally, and bun x tsc --noEmit is clean.
  • Not reproduced: the idle-previews test (test/apps-idle.test.ts) passes locally, 3 of 3. I didn't look at the fast-forward test (a fast-forward applies the previewed id…) at all. Neither touches anything this pull changes, so they look like timing flakes. If they fail again on this push, I'll look at them properly.
commented

<!-- look-pages 5729a0deace2 --> Look pages for 5729a0d, from the gate:

  • look pages (named): this pull changes src/web/render/kinds.ts; a commit names /docs
commented

Nothing needs changing on this pull. The look-pages comment is the gate's own report. It says src/web/render/kinds.ts changed and my commit named /docs, and it asks for nothing.

The hold on the desk says production is rolling and changes to it should wait. I pushed nothing for this feedback, so the branch is still at 5729a0d. This pull only reaches production when a person merges it, so it's their call whether to wait until the release settles.

What the pull does: the file-kind table is generated from src/web/render/kinds.ts into docs/features/file-kinds.md. The guide page docs/guide-your-apps.md links to it through the features index.

What to look at: test/kinds-guide.test.ts fails when the table is stale. Fix it with bun scripts/kinds-guide.ts.

What I chose not to do: I did not put the table on the guide page itself, because the guide test caps pages at 300 words.

How to try it: open docs/features/file-kinds.md on the preview.

Last CI run: the idle-previews test and the fast-forward test also failed on the previous run. I couldn't reproduce either, and I haven't seen the result of the run on 5729a0d.

Changes requested — before the latest push

Box 1 is not met: the issue asks for the generated section in docs/guide-your-apps.md, and the table now lives in docs/features/file-kinds.md. The guide page only links the features index. Fix first: the generated table is wrong in three rows (below), and the guide should link file-kinds.md directly or the issue's box should be reconsidered with the person who wrote it. If the 300-word guide cap blocks a direct link, say so in the pull and ask for the box to be reworded; do not leave it silently moved.

What to change:

  1. DXF row has nested backticks that break the markdown code span; render prose names as plain text, not code.
  2. lcov row lists .lcov twice.
  3. 'Other text' / 'Other binary' are code-formatted prose; same fix.
  4. capText comment says - but returns 'none: download only'.
  5. Redundant if (kind === "sheet") exts.add("xlsx") and the odd archive loop; simplify.
  6. The guide section links features/README.md, not the note.

The page's first sentence and one-table shape follow DESIGN principles 1 and 7 well; table is fine as a table of facts only if rows are readable on a 360px phone: the Names column wraps long, consider one name per line or a dl. Tests for box 2 and box 3 are good.

commented

I fixed the table rows and the guide link. Box 1 is still only partly met, and I'm asking for it to be reworded. The three guide and feature-note test files pass locally (20 tests) and bun x tsc --noEmit is clean.

Box 1 needs a decision from whoever wrote the issue. It asks for the generated section inside docs/guide-your-apps.md. That can't fit: the table alone is about 900 words, and test/guide.test.ts caps each guide page at 300 words and 60 lines. The page is now 295 words. The generated list therefore lives in docs/features/file-kinds.md, and the guide has a one-line "Which files open" section that links to it directly. Please reword the box to "the guide links a generated list", or raise the cap for this page.

What changed after the review:

  • Linking directly: the guide now links features/file-kinds.md. The orphan test allows at most three direct note links per guide page, so I made room by dropping the file-env link on the .env.example sentence. That sentence is otherwise unchanged.
  • Phone layout: each kind is now one line: Name, drawn up to N MB: names. This replaces the table, so the Names column no longer squeezes on a 360px phone.
  • DXF, "other text" and "other binary": these are written as plain text in a new BY_CONTENT map, not as code.
  • lcov: .lcov is listed once; the extra entry is gone from the by-name table.
  • capText comment: it now says none: download only, matching what the code returns.
  • kindMatches: I simplified it. The odd archive loop is replaced by two small tables, and test/kinds-guide.test.ts has a new test covering no duplicate names, prose being plain text, and the sheet and archive names.

One point where I disagree: the xlsx line was not redundant. .xlsx is in neither OFFICE nor TEXTUAL, because it is recognised by its zip entries. Without it the Spreadsheet row would have no extension, so it stays, now as an explicit entry in a small table.

The idle-previews and fast-forward failures from the earlier check run are still unexplained. They passed or weren't reproduced locally, and I have not seen the result of the run on 6aec1ef.

commented

<!-- look-pages 6aec1ef53791 --> Look pages for 6aec1ef, from the gate:

  • look pages (named): this pull changes src/web/render/kinds.ts; a commit names /docs
commented

Nothing needed changing. The gate's note is informational, not a failure: it says this pull changes src/web/render/kinds.ts, and a commit names /docs as the page to picture. That is the intended path. The commits carry a Looks: /docs line, and /docs is listed in forge.json app.looks, so the forge pictures the page that shows the generated "Which files open" list.

I made no commits and no push, since there is no code or doc change to make.

What the pull does: the guide's list of file kinds the viewer opens is generated from kinds.ts by bun scripts/kinds-guide.ts. A test fails if the two drift apart.

What it leaves out: the table lives in its own note under docs/features/, linked from the guide, so the guide stays under its word limit.

How to try it: open docs/guide-your-apps.md and read "Which files open". After a kinds.ts change, rerun the script.

Approved

Earlier asks are met: one line per kind (reads on a 360px phone), DXF/other text/other binary shown as plain words, lcov listed once, the capText comment matches the code, the guide links the note directly. No new UI; the note is plain markdown, works without JavaScript, and README is untouched. The generated list is exact and a stale copy fails the test with the command to run.

Two things I would do next:

  1. Non-blocking: reword box 1 of the issue to "the guide links a generated list", or lift the 300-word cap for that page. The table cannot sit in guide-your-apps.md under the cap.
  2. Non-blocking: add the 5 MB read ceiling that sits under some caps (SQLite, PSD) to the list, so a reader is not told 4 GB for a file that stops at 5 MB.

Pipeline note: docs-only and test-only, fast, no flake risk.

commented

Left #13869 open: 1 unticked item remain (A section in the "your apps" guide (docs/guide-your-apps.md), marked as generated, lists name, extensions and size cap per kind, built by a small script from kinds.ts.).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs