docs: hand the landing-page role from the README to maka.apache.org

[Astro-Han]

Summary

Since #4660 the website is the landing page and the downloads path, but both READMEs still ran 290 lines as landing page, install guide and architecture summary, and opened with a different sentence from the site and the repository description.

• README.md, README.zh-CN.md and the .asf.yaml description carry the sentence settled in [DISCUSS] Rebuild the Maka website and project narrative #4307. The header is title, badges and hero; the hero carries the headline, so the sentence and lede appear once, as text opening "What Maka is". That section replaces "Why Maka", "Surfaces" and "Current capabilities" with the site's four claims (measured not claimed, the log is the runtime, your machine and your model, one Runtime Host) and a sentence linking the site and ARCHITECTURE.md. "Releases and downloads" becomes "Get Maka" with the same three labelled paths as the downloads page and links there instead of to GitHub Releases. Requirements, start and first run move under "Build from source". Website and Downloads are badges in the style of the row above them. The rest of the README is unchanged apart from a website/ line in the layout and a website link in Documentation. Both languages stay section-for-section identical.
• The hero is rendered from the website itself: website/scripts/readme-hero.mjs (run with npm --workspace @maka/website run readme-hero) builds the site and screenshots the homepage headline and RuntimeEvents scene per language and colour scheme into .github/assets/readme-hero.*.png, and the READMEs pick light or dark with a <picture> element. The two per-language illustrations that baked in the old tagline are removed, and docs/code-origin-audit.md now records that the heroes are renders of the site's own copy and styles rather than generated art.
• Every retained claim was checked against the repository. Three were stale and are corrected: Desktop Nightly has published macOS arm64 and x64, Windows x64 and Linux x64 and arm64 builds for some time, but the README and the website's three platform lines said Apple Silicon only with a Windows preview, so both now name the full matrix with Windows and Linux as unsigned previews; ARCHITECTURE.md links four deep dives, not six, so the README stops counting; and the repository layout gains native/, skills/, patches/ and experiments/.
• website/test/site.test.mjs asserts the two READMEs and the description carry the sentence, and the CI planner runs the website workspace for a README change so the check runs when it matters. .asf.yaml keeps its existing release-contract lane.
• Committing the first version of this branch showed that the pre-commit Biome check from feat(ci): add fast local validation hooks #4132 could not commit a binary or a Markdown file: it pipes every staged blob through git show and Biome with Node's default 1 MiB buffer, Biome rejects stdin that is not UTF-8, and for a language it parses without formatting it echoes nothing, which the hook read as unformatted. Binaries are now skipped by git's NUL-byte heuristic, an empty echo is treated as no handler, and the buffer limits are lifted, with a test for each.

Fixes #4684

Verification

• npm --workspace @maka/website run test:dist: 9/9, including the new cross-surface sentence test.
• npm --workspace @maka/website run readme-hero: writes the four PNGs above from the built site.
• node --test scripts/ci-test-plan.test.mjs scripts/ci-workflow-policy.test.mjs scripts/biome-staged-check.test.mjs: 80/80. The new planner test and the hook's binary and Markdown cases fail on main; the first two commit attempts of this branch failed on exactly those two hook paths.
• npm run format, npm run lint, npm run check:asf-headers: clean.
• Scripted check that every relative link and image path in both READMEs exists and the two in-page anchors match a heading; both files have the same 13 headings in the same order.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code set the section skeleton, wrote the render script, the tests, the planner and hook changes and this description; Gemini 3.8 Flash (Antigravity CLI) drafted the README prose from that skeleton, which I then corrected against the site copy and cut back to bullets. I reviewed every line of both READMEs.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[MicroGery]

The README handoff is directionally right; this is a maintainability concern about the new derived assets.

[MicroGery]

Could we give this generator a reproducible contract, or avoid committing the rendered derivatives? It launches Chromium, but neither npm ci nor the README-triggered website lane installs a Playwright browser, and CI neither runs this command nor checks that the four committed PNGs still match the site. A clean checkout therefore has no declared regeneration path, while later website changes can leave the README hero stale. Please either document/automate the browser-install and regeneration or drift check, or simplify/remove the generated-hero path.

[Astro-Han]

Good catch, thank you — you're right that a clean checkout has no declared way to regenerate these.

Two changes coming: the script installs its own Chromium when there isn't one, so npm --workspace @maka/website run readme-hero works straight after npm ci; and it writes a manifest of the text it bakes into the images, which the website test compares against the site copy, so a copy change that leaves the hero stale fails CI without a browser or a pixel diff.

Style-only drift stays uncaught — hashing the CSS would mean a Chromium download on every unrelated tweak. Say the word if you'd rather draw the line elsewhere.

[Astro-Han]

Done in 48f45f9fbf.

The script fetches a Chromium when there isn't one, so your reproduction now works: PLAYWRIGHT_BROWSERS_PATH=/tmp/empty npm --workspace @maka/website run readme-hero downloads the browser and writes the four images.

For drift it records the hero copy it screenshotted in .github/assets/readme-hero.json, and the site test recomputes that text from the built pages, failing with the command to run. Both sides use the same extractor, so it needs no browser and compares text, not pixels. Changing a hero string and rebuilding fails the test; regenerating passes it.

[jackwener]

I reviewed exact head a752b040df133acca4e93d18fc28fe52dbab6f7c. One P2 and one P3. No P0 or P1.

The documentation work checks out. I verified the three corrected claims against the repository rather than the description: the Nightly workflow really does publish macOS arm64 and x64, Windows x64 and Linux x64 and arm64, with macOS signed and notarised and the other two unsigned previews; ARCHITECTURE.md and its Chinese mirror link four deep dives, not six; and native/, skills/, patches/ and experiments/ all exist. Both READMEs keep the same thirteen sections in the same order, and their local links resolve. The .asf.yaml change is the description only, matching the site and README sentence verbatim.

Dropping the release wording from the top of the README worried me until I read where it went: "Get Maka" still states that no Apache release exists, that the signed source archive will be the official release and packages elsewhere are convenience artifacts, and it still links ASF_SOURCE_RELEASE.md. The Nightly line is now more explicit than what it replaced — it adds "not intended for production use" alongside the corrected platform matrix.

The hook fix also has teeth where it matters. On main, a 2 MiB PNG throws ENOBUFS and a Markdown file fails outright; on this head both pass. A 2 MiB unformatted JavaScript file with no NUL still reaches Biome and is still rejected.

P2 — the NUL heuristic lets a legitimate source file skip the formatter

scripts/biome-staged-check.mjs:45-53 scans the whole blob for 0x00 and skips the file before it looks at the path or the handler. That is broader than "binary".

Staging a valid but unformatted valid.js with a single NUL byte inside a string literal: node --check returns 0, Biome returns 0 and rewrites the 26 bytes into a different 33, so it is a formatter-owned source file that needs formatting. The old hook on main returns false for it. This head returns true — the file is skipped entirely.

A second shape reaches the same place: a UTF-16 encoded JavaScript file contains NUL bytes by construction, so it is skipped too. The opposite direction is fine — a NUL-free file with invalid UTF-8 still fails, because Biome rejects the stdin.

So the change delivers "binaries can be committed" for the common case of NUL-containing binaries, but it buys that by letting any file with a NUL byte past the gate. Hosted CI is still a backstop, which is why this is not a P1.

The new test does not cover it: it stages a zero-filled 2 MiB buffer, which is both large and NUL-bearing, so it exercises the intersection of the two fixes rather than either one alone. Neither "no NUL, over 1 MiB" nor "small, valid source containing a NUL" is tested.

Fix: make the NUL signal conditional on the path or handler, so a file the formatter owns is never skipped on that byte alone, and add a valid-source-with-NUL regression.

P3 — the buffer limit is now unbounded rather than raised

Both maxBuffer values are Number.POSITIVE_INFINITY, and git show reads the entire blob into memory before the NUL check runs. That replaces a hard failure over 1 MiB with no ceiling at all. This is a local developer path and recoverable, so it does not rise higher — but "lift the limit" and "remove the limit" are different fixes, and only the second one is what landed.

On the hero images

There is an unresolved inline thread on this already, and I reproduced its substance independently, so I will not restate it as a finding: after npm ci, readme-hero only runs if a Chromium happens to be in the global cache — pointing PLAYWRIGHT_BROWSERS_PATH at an empty directory makes it fail asking for npx playwright install. A README-only change plans just the website tests, and CI neither runs readme-hero nor compares the four committed PNGs against a fresh render. So site copy or styles can change, everything stays green, and the committed heroes quietly go stale. Worth closing that thread one way or the other before merge.

Also worth a line

The Incubator disclaimer wording differs between surfaces: both READMEs say "sponsored by the Apache Incubator PMC", the website says "sponsored by the Apache Incubator". This is pre-existing on main, not introduced here — but this PR is already editing that block, so it is a cheap moment to make the two agree.

Checks

The required test job is red on a Desktop E2E case this PR does not touch (104 pass / 4 skip / 1 fail); main's latest test is green and that case passes on its own against this head, so it does not attribute here — but a red required check is still a hard gate. audit failed separately on an npm registry HTTP 503. The synthetic merge against current main is clean, and the 124 files main brings in have zero path overlap with this PR's 20.

简体中文

我审的是 a752b040df133acca4e93d18fc28fe52dbab6f7c。一条 P2、一条 P3,没有 P0/P1。

文档这部分是站得住的。那三条被修正的声明,我是对着仓库核的而不是对着描述:Nightly 工作流确实发布 macOS arm64 与 x64、Windows x64、Linux x64 与 arm64,其中 macOS 有签名并公证,另两个是无签名预览;ARCHITECTURE.md 及其中文镜像链接的是四篇深度文档,不是六篇;native/、skills/、patches/、experiments/ 都存在。中英两份 README 保持十三个同序章节,本地链接均可解析。.asf.yaml 只改了描述,与网站和 README 的那句逐字一致。

README 顶部那段发布声明被删,一度让我担心,直到我看清它去了哪里:「Get Maka」里仍然写明尚未发布 Apache release、签名源码包才是正式发布、别处分发的是便利产物,也仍然链接 ASF_SOURCE_RELEASE.md。而 Nightly 那一行比它替换掉的更明确——在修正过的平台矩阵之外,新增了「不适用于生产环境」。

hook 的修复在要紧处也确实有牙齿:在 main 上,2 MiB 的 PNG 会抛 ENOBUFS,Markdown 直接失败;在这个 head 上两者都能通过。而一个 2 MiB、不含 NUL、未格式化的 JavaScript 仍然会进入 Biome 并被拒绝。

P2:NUL 判据会让一个合法源文件跳过格式化检查

scripts/biome-staged-check.mjs:45-53 扫描整份 blob 找 0x00,并且在查看路径或 handler 之前就跳过该文件。这比「二进制」宽得多。

暂存一个合法但未格式化的 valid.js,在字符串字面量里放一个 NUL 字节:node --check 返回 0,Biome 返回 0 并把 26 字节重写成不同的 33 字节——所以它是一个归 formatter 管、且确实需要格式化的源文件。main 上的旧 hook 对它返回 false。这个 head 返回 true,文件被整个跳过。

还有第二种形态会落到同一处:UTF-16 编码的 JavaScript 天然含 NUL 字节,同样会被跳过。反方向是好的——不含 NUL 但 UTF-8 非法的文件仍然失败,因为 Biome 会拒绝该 stdin。

所以这个改动为「含 NUL 的常见二进制」实现了「二进制可以提交」,代价是让任何含 NUL 字节的文件都越过了这道门。托管 CI 仍是兜底,所以不定 P1。

新增的测试覆盖不到它:它暂存的是一个全 0 的 2 MiB 缓冲区,既大又含 NUL,所以练到的是两处修复的交集,而不是其中任何一处单独的行为。「无 NUL 且超过 1 MiB」和「小体积、合法、含 NUL 的源文件」都没有被测到。

修法:让 NUL 信号与路径/handler 判断合用,使 formatter 管辖的文件不会仅凭一个字节被跳过,并补一条「合法源文件含 NUL」的回归用例。

P3:缓冲上限不是被调高,而是被取消了

两处 maxBuffer 都是 Number.POSITIVE_INFINITY,而且 git show 在 NUL 检查运行之前就把整份 blob 读进了内存。这把「超过 1 MiB 硬失败」换成了完全没有上限。这是本地开发者路径且可恢复,所以不再往上定级——但**「放宽上限」和「取消上限」是两种不同的修法,落地的是后者**。

关于 hero 图

这上面已经有一条未解决的 inline 讨论,而且我独立复现了它的实质,所以不再把它作为一条 finding 重述:npm ci 之后,readme-hero 只有在全局缓存里恰好存在 Chromium 时才跑得起来——把 PLAYWRIGHT_BROWSERS_PATH 指向一个空目录,它就会失败并要求 npx playwright install。而仅改 README 的变更只会规划 website 测试,CI 既不运行 readme-hero,也不把已提交的四张 PNG 与新渲染做比较。于是网站文案或样式改动之后,一切照样全绿,而提交进来的 hero 悄悄过时。 合并前把那条讨论按某种方式了结掉是值得的。

另外值得一行

Incubator disclaimer 的措辞在不同位置不一致:两份 README 写的是「sponsored by the Apache Incubator PMC」,网站写的是「sponsored by the Apache Incubator」。这在 main 上就已存在,不是这次引入的——但这个 PR 本来就在改那一段,所以这是一个很省事的时机,把两者统一。

检查

必需的 test 任务红在一个本 PR 未触及的 Desktop E2E 用例上(104 通过 / 4 跳过 / 1 失败);main 最新的 test 是绿的,而且该用例在这个 head 上单独跑是通过的,所以归因不到这里——但一个红色的必需检查仍然是硬门禁。audit 是另外因为 npm registry 返回 HTTP 503 而失败。与当前 main 的合成合并树是干净的,main 带入的 124 个文件与本 PR 的 20 个文件路径零重叠。

---

Automated review notice: This comment was posted by an automated review agent operated by jackwener. It is not an independent human review and does not replace one.

[Astro-Han]

Both findings were right, and both are fixed in b837cae282.

P2. The NUL scan was the wrong predicate. Biome's actual limit is that it reads stdin as UTF-8 and errors on anything else, so the hook now skips a blob that does not decode as UTF-8 and leaves every file the formatter owns inside the check. valid.js with a NUL inside a string literal decodes, reaches Biome and is rejected, as it is on main. A UTF-16 file decodes too and fails on the comparison rather than being waved through.

P3. The limit is stated rather than removed: git cat-file -s gives the blob size first, a blob over 16 MiB is skipped without being read into memory, and the read is bounded by that same ceiling. Nothing Biome formats approaches it, and the hosted format and lint jobs still see those paths.

The coverage gap is closed too. Three tests now separate the two fixes instead of exercising their intersection:

• checks a staged source file that holds a NUL byte — small, valid, NUL-bearing; fails on the previous head, passes on main, passes here.
• skips a small staged binary Biome cannot decode — an 11-byte PNG header with no NUL at all; fails on both main and the previous head.
• checks a staged source file larger than the default child-process buffer — 2 MiB of source with no NUL; fails on main with ENOBUFS.

Against main the file now has four failing tests, and all seven pass here.

On the disclaimer wording. Taken, in 21c34f0718. The branding guide asks for the sponsor's name rather than a fixed string, so neither surface was wrong, but publishing two wordings of the same required paragraph is not worth keeping. The site now states it the way DISCLAIMER-WIP does, and website/test/site.test.mjs reads the paragraph out of that file instead of holding its own copy, so there is one place to change it.

On the hero images. Being answered on MicroGrey's thread, where the substance is.

On the checks. audit failed on an npm registry HTTP 503 and has been rerun. Agreed on the Desktop E2E case: it does not attribute here, but it is a required check, so it has to be green before this merges.

[Colafornia]

The latest update is moving in a better direction. The light/dark Runtime Event Timeline now feels much more coherent, and I don't think the timeline design itself needs another redesign in this PR.

There are still a few things around the hero structure that I think would make the first screen feel more coherent without changing the existing positioning or reducing useful information:

• Keep the existing positioning sentence unchanged, but move it out of the PNG and render it as real README text.
  I don't think the wording needs to change. This is mainly an implementation and hierarchy issue: the project's primary positioning should ideally be copyable, searchable, accessible, responsive, and independently localizable rather than baked into a raster asset.

• Keep the Runtime Event Timeline itself unchanged, but let the image contain only the timeline scene.
  The timeline content, cards, annotations, colors, etc. already work well. I would not redesign them. The only change here would be separating the positioning text from the timeline asset, so each has a clearer role.

• Use plain links for official navigation instead of badges.
  For example:
  官网 · 文档 · 下载 · English
  These are navigation actions rather than project metadata, so a lighter treatment would make the page easier to scan.

• Reduce the visual weight of metadata.
  Stars, license, and platform support are useful information, but they should feel secondary to the project identity and hero. Keeping the dynamic stars badge is reasonable, while license/platform support could potentially use a more neutral treatment.

• Move DeepWiki out of the primary hero metadata row.
  Explicitly labeling it as third-party documentation is already an improvement. I think it would fit even better under a Documentation / Resources section, so the first screen more clearly distinguishes official project entry points from third-party resources.

• Keep the color system restrained.
  The current light/dark treatment is already better. I would continue using Maka's existing brand blue as the main accent, while keeping navigation and metadata mostly neutral rather than having several badge colors compete with the logo and timeline.

So the overall structure could roughly become:

[M] Apache Maka (Incubating)

<existing positioning sentence, unchanged>

官网 · 文档 · 下载 · English

★ stars    Apache-2.0 · macOS · Windows · Linux

[existing Runtime Event Timeline scene]

The goal here is not to make the README minimal or redesign the hero from scratch. I think the current amount of information is useful. The main improvement would be to separate positioning, navigation, metadata, and the timeline into clearer visual roles.

To make the hierarchy suggestion more concrete, here's a quick local VS Code Markdown preview I used while exploring this direction.

This is only illustrative — VS Code's theme, typography, and Markdown rendering are not identical to GitHub, so I'm not suggesting these exact colors or spacing. The main point is the separation between the positioning text, navigation, metadata, and the Runtime Event Timeline scene.

中文

最新这一版已经是在往更好的方向走了。现在 light / dark 两套 Runtime Event Timeline 的整体感都明显更统一，我觉得这次 PR 里 timeline 本身的设计不需要再重新做一轮。

不过 Hero 的整体结构还有几个地方，我觉得可以在不修改现有 positioning、也不减少有效信息的情况下进一步整理：

• 保留现有 positioning 文案完全不动，但把它从 PNG 中拆出来，作为真实 README 文本呈现。
  我觉得文案本身不需要改。这个主要是实现方式和视觉层级的问题：项目最核心的定位文案最好是可复制、可搜索、可访问、可响应式排版、可独立本地化的真实文本，而不是烘焙在 raster asset 中。

• Runtime Event Timeline 本身保持现状，但图片只保留 timeline scene。
  Timeline 内部的卡片、文字、标注、颜色和结构我觉得现在已经可以了，不建议重新设计。这里只是把 positioning 文案和 timeline asset 拆开，让两者各自承担更明确的角色。

• 官方导航改成普通文本链接，而不是 badge。
  比如：
  官网 · 文档 · 下载 · English
  这些本质上是 navigation action，不是项目 metadata。用更轻的表现形式会更容易扫读。

• 降低 metadata 的视觉重量。
  Stars、license、platform support 都是有用的信息，但应该明显弱于项目 identity 和 Hero。动态 stars badge 可以保留，license / platform support 可以考虑使用更 neutral 的表现方式。

• DeepWiki 从首屏 metadata row 下放。
  现在明确标注“第三方 AI 文档”已经是一个进步。我觉得如果进一步放到 Documentation / Resources 一类的位置，会更容易让用户区分官方入口和第三方资源。

• 继续收敛配色。
  现在 light / dark 的处理已经比之前统一很多。建议继续把 Maka 现有 brand blue 作为主要 accent，而 navigation 和 metadata 尽量保持 neutral，避免多个 badge 颜色继续和 logo / timeline 竞争。

所以整体结构大概可以变成：

[M] Apache Maka (Incubating)

<现有 positioning 文案，完全不改>

官网 · 文档 · 下载 · English

★ stars    Apache-2.0 · macOS · Windows · Linux

[保持现有 Runtime Event Timeline scene]

这里的目标不是把 README 做得很极简，也不是重新设计整个 Hero。我觉得现在的信息量本身是有价值的，主要只是把 positioning、navigation、metadata 和 timeline 的视觉角色分得更清楚。

[Astro-Han]

Thank you — this is exactly the read I needed, and the first point especially. Baking the positioning sentence into a raster asset meant the one line that says what Maka is could not be copied, searched, translated or read as text, and I had no good answer for that.

All six are in, and your mock is what I built against:

• The sentence is a centred heading under the title, and the image is the timeline only. The render hides the headline now, so the scene is the whole asset.
• Website · Documentation · Download · 中文文档 are plain links.
• Stars, licence and platforms stay badges beside each other, secondary to the title and the sentence rather than removed. My first attempt dropped them to a line of small text and the first screen collapsed, which is a good illustration of your point about roles.
• DeepWiki moved to Documentation.
• The only colours left in the first screen are the brand blue and GitHub's own link colour.

One deliberate difference from the mock: the heading carries the full sentence, "Apache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.", rather than the shortened site headline. #4307 settled that one sentence for the README, the homepage and the repository description, and a test checks the three agree. Using the short form here would mean repeating the full one a few lines later in "What Maka is", which is the duplication this PR set out to remove.

The timeline itself is untouched, as you suggested.

[hqhq1025]

Reviewed exact head 883b525274039260ee1cd6ce4828514ecaa7017a.

No actionable findings. This revision is ready to merge.

The PR correctly addresses two related maintenance problems: it refreshes the README and website presentation around Maka's RuntimeEvents model, and it makes the staged Biome check tolerate binary and large blobs without allowing formatter-owned source to bypass validation. The implementation follows the actual ownership boundaries: README hero copy is derived through the website extractor and checked by the website test, while staged blobs are size-bounded and decoded before Biome receives source text.

The earlier review concerns are closed in the current code:

• formatter-owned source containing NUL bytes is still checked;
• large blobs are bounded at 16 MiB instead of using an unlimited child-process buffer;
• small binary and large source cases have separate regression coverage;
• the hero generator can provision Chromium from a clean install;
• the committed hero manifest is checked against current built-page copy.

I also inspected all four committed English/Chinese light/dark hero images. They render at 2400x768 with complete content and no visible clipping, overlap, or blank output.

The problem definition and solution are consistent with first principles and Occam's razor. I found no production code or tests that should be deleted, and no deeper refactor is warranted. The remaining accepted risk is that style-only hero drift is not detected automatically; copy drift is covered, and avoiding a browser-backed pixel regeneration in normal CI is a reasonable boundary for this documentation asset.

Local verification:

• node --test scripts/biome-staged-check.test.mjs scripts/ci-test-plan.test.mjs scripts/ci-workflow-policy.test.mjs — 83 passed
• npm --workspace @maka/website run test:dist — build succeeded, 10 passed
• targeted npx biome check on changed text files — passed
• git diff --check — passed
• GitHub checks — all completed successfully or skipped as intended

[jackwener]

Updating my earlier findings against the current head 883b525274039260ee1cd6ce4828514ecaa7017a. The NUL heuristic has since been replaced with a UTF-8 decode plus a 16 MiB ceiling, which changes both of them — one is closed, the other changed shape rather than going away.

The NUL bypass is closed for UTF-8 sources

Re-running the same probe: a valid, unformatted .js with a raw 0x00 inside a string literal is now rejected, where the previous head accepted it. The result flipped. 0x00 is valid UTF-8, so the file decodes and reaches Biome; Biome writes the NUL back as U+FFFD, the comparison fails, and the hook returns false — the same outcome as an unformatted file with no NUL. There is a test in the repository asserting that shape. A file that is already space-formatted but still holds a raw 0x00 is caught too, since Biome's echo can never equal the input.

That was the substance of the P2, and it is genuinely fixed.

What remains: two shapes still skip the gate silently

UTF-16 with a BOM. Without a BOM, a UTF-16 LE file decodes as UTF-8 (ASCII interleaved with 0x00), reaches Biome, is treated as mojibake and is rejected — fine. With a FF FE BOM the decode fails, if (!decodes) continue fires, and the hook returns true. It takes the same exit as an unreadable binary.

Anything over 16 MiB. biome-staged-check.mjs:66 is if (size > maxBlobBytes) continue. A 16 MiB + 1 ASCII file, and an unformatted .js padded past 16 MiB, both return true: the file never reaches Biome and never fails.

This is where my earlier P3 changed character rather than closing. I reported it as "the limit was removed rather than raised", a local memory concern. A ceiling now exists — but the far side of the ceiling is continue, not throw. So the fix traded an unbounded read for a silent skip, which puts it in the same family as the P2 above rather than in the resource-limit family it started in: an oversized file is not checked, and nothing says so.

"Add a limit" and "add a limit and fail when it is exceeded" are different fixes, and only the first one landed. For both shapes, failing closed — refusing the commit with a message naming the file and why it could not be checked — keeps the availability goal while leaving no silent hole. That reads to me as the same correction in both places: the escape hatch should be loud.

Neither rises to P0/P1: both need an unusual file to reach, and hosted CI still formats. But they are worth closing together, because they are now the only two ways a staged file leaves this gate unexamined without anyone being told.

Evidence boundary: these are runs of checkStagedWithBiome on this head, not a re-reading of the diff. The hero-image contract and the documentation claims are unchanged from my earlier comment.

简体中文

针对当前 head 883b525274039260ee1cd6ce4828514ecaa7017a 更新我先前的两条发现。NUL 判据此后已被换成 UTF-8 解码加 16 MiB 上限,这让两条都发生了变化——一条关闭了,另一条不是消失而是改变了形状。

NUL 绕过:对 UTF-8 源文件已经关闭

用同一个探针重跑:一个合法、未格式化、字符串字面量里带原始 0x00 的 .js,现在会被拒绝,而上一个 head 是放行的。结果翻转了。 0x00 是合法的 UTF-8,所以文件能解码并进入 Biome;Biome 把 NUL 回写成 U+FFFD,比较失败,hook 返回 false——与一个不含 NUL 的未格式化文件结果相同。仓库里有一条测试断言了这个形状。连「已经按空格格式化、但仍含原始 0x00」的文件也会被拦,因为 Biome 的回显永远不可能等于输入。

那正是那条 P2 的实质,它确实被修好了。

仍然存在的:两种形态依然会静默跳过这道门

带 BOM 的 UTF-16。 不带 BOM 时,UTF-16 LE 文件能按 UTF-8 解码(ASCII 与 0x00 交错),进入 Biome,被当作乱码拒绝——这没问题。但带 FF FE BOM 时解码失败,if (!decodes) continue 触发,hook 返回 true,走的是和「读不了的二进制」同一个出口。

任何超过 16 MiB 的文件。 biome-staged-check.mjs:66 是 if (size > maxBlobBytes) continue。一个 16 MiB + 1 的 ASCII 文件,以及一个用空格垫过 16 MiB 的未格式化 .js,都返回 true:文件根本不会进入 Biome,也永远不会失败。

这正是我先前那条 P3 改变性质、而非关闭的地方。 我当时报的是「上限不是被调高而是被取消了」,那是一个本地内存层面的担心。现在上限有了——但上限的另一侧是 continue,不是 throw。 所以这个修复把「无界读取」换成了「静默跳过」,这让它归入上面那条 P2 的同一族,而不再属于它起初所在的资源上限族:一个超大文件不会被检查,而且没有任何东西说出来。

「加一个上限」和「加一个上限并在超限时失败」是两种不同的修法,落地的只有前者。 对这两种形态,fail closed——拒绝提交,并给出一条指明文件和「为什么无法检查」的消息——既保住了可用性目标,又不留下静默的口子。在我看来这两处是同一个修正:逃生口应该是响的。

两者都到不了 P0/P1:都需要一个不寻常的文件才能触及,而且托管 CI 仍会格式化。但值得一并关掉,因为它们现在是「一个暂存文件不被检查、而且没人被告知」的仅有两条路径。

证据边界:这些是在这个 head 上对 checkStagedWithBiome 的实际运行,不是重读 diff。hero 图契约与文档声明部分,与我先前的评论相比没有变化。

---

Automated review notice: This comment was posted by an automated review agent operated by jackwener. It is not an independent human review and does not replace one.

[Astro-Han]

Taken on the ceiling, in f86e6d8d96. You are right that "add a limit" and "add a limit and fail when it is exceeded" are different fixes, and that the far side of mine was a silent continue.

It now asks git which staged blobs are binary — git diff --cached --numstat -z, one call, made only when something is actually over the ceiling — skips those, and refuses the commit for the rest with the path and the byte count. So an oversized asset still commits and an oversized source file stops the commit and says why. Two tests, one per side; the source one fails on the previous head.

I did not make the undecodable path fail closed, and I don't think it should. Every image commit takes that exit: a PNG is exactly a blob Biome cannot read. Refusing there brings back the bug this branch started from. To fail closed only for the files the formatter owns, the hook would have to carry its own table of formatter-owned extensions — a second copy of a decision Biome already makes from --stdin-file-path, and the sort of parallel authority I would rather not add for this.

On UTF-16 with a BOM specifically: git calls such a file binary, as it does a PNG — git diff --cached --numstat reports - for it. So the hook skipping it is not a hole it invented; it agrees with the repository's own view of what is text, and git diff would not show its contents either. If someone lands UTF-16 source here, the hosted format and lint jobs still see it.

[Astro-Han]

Reviewed current head f86e6d8d96f12a7078da32590bb45923db56843d (OPEN, MERGEABLE). NO-GO — one new P2 below; the docs-side facts checked on the previous head still hold and are not repeated here.

P2 (new regression) — oversized valid-UTF-8 sources containing NUL are silently skipped as binary

scripts/biome-staged-check.mjs:45-69,96-102: binaryStagedPaths() relies on git diff --numstat -z emitting -\t-, but git marks a .js source containing NUL as binary; a subsequent binary.has(path) then just continues. Reproduced on this head in a scratch repo: a 2071-byte valid UTF-8 huge.js containing const value = "\0" yields -\t-\thuge.js with maxBytes: 1024 and the function returns true (skipped); with the limit at 4096, Biome reports it unformatted (function returns false). This contradicts the contract already established in scripts/biome-staged-check.test.mjs:76-84 (NUL-bearing sources must be checked) and bypasses this change's own "stop oversized text at commit" protection.

Suggested fix: do not use git's NUL-binary heuristic as the sole source/asset authority for oversized files — classify Biome source extensions independently (or fail closed on oversized NUL-bearing files not explicitly allowed), and add a regression test with an oversized valid-UTF-8 NUL-bearing JS file.

What was checked on this head

Delta scope only (staged-check commits on top of the verified baseline): current staged-check plus CI planner tests 45/45, website test:dist 10/10, format:check over 1919 files, lint over 3213 files, git diff --check — all pass. What I could not judge: concurrent-write pressure during the check itself was not run.

---

Automated review notice: This comment was posted by an automated review agent operated by Astro-Han. It is not an independent human review and does not replace one.

简体中文

本条结论全部来自 @未开智选手 的审查。我自己没有读这份 diff；我核的是当前 head 有没有漂移、以及 exact-head 的 CI 状态。当前 head 是 f86e6d8，可合并。P2 是新增回归：含 NUL 的合法大源文件会被当二进制静默跳过。修好再合。