Repository navigation
Add oxfmt, format the repo, fix the showcase typecheck - #1
Merged
Merged
Conversation
Neither Markdown nor TypeScript had a formatter. Prose wrapping in the docs ranged from roughly 70 to 90 columns and was maintained by hand, and the frontend under web/ and showcase/ had only typecheck and tests. oxfmt covers both from one pinned binary. Its Markdown output was compared against Prettier 3 with the equivalent settings on README.md and came back byte-identical, including the cases a naive reflow gets wrong, such as breaking inside an inline code span. The version is pinned exactly in magefiles/fmt.go and in the workflow, and invoked through `pnpm dlx` rather than a root package.json, which this repository does not have, or the go.mod tool block, which would pull the formatter's archive-handling dependency tree into the module graph. The targets are explicit globs rather than a tree walk, so a new file type cannot start being rewritten without someone adding it here. Excluded in .oxfmtrc.json: the generated MDX reference pages that mage docs:cli and docs:crd own, the skill definitions under toolkits/ and **/SKILL.md that skillmd parses, testdata, the built bundles under webassets/dist, and CLAUDE.md, which is a symlink to AGENTS.md. This commit adds the tooling only. The reformat it produces follows.
Mechanical, produced by `mage fmt:all`. 179 files: prose rewrapped at 80 columns, table cells padded, emphasis markers normalized to underscores, blockquotes rewrapped. No prose was changed. Verified by normalizing whitespace, table separator runs, and emphasis markers out of every changed file and comparing against HEAD, and separately by extracting every fenced code block before and after: zero code blocks differ. Skill definitions, generated MDX, and testdata are excluded by .oxfmtrc.json, so nothing a parser or a digest depends on is touched.
Mechanical, produced by `mage fmt:all`. 146 of 160 .ts/.tsx files under web/
and showcase/, which had no formatter before this.
One source change has a compiled consequence. In agentlink.tsx the formatter
broke a long JSX line and, to preserve the significant space before the link,
emitted an explicit {" "}. The rendered DOM is unchanged; the compiled chunk
represents that space as its own child instead of a trailing space on the
preceding text node, which changes the chunk's content hash. The rebuilt
bundle and manifest are committed here so `mage web:check` stays green.
Verified: web typecheck passes, and 1532 tests across 148 files pass.
showcase typecheck fails, but it fails identically at the previous commit —
pre-existing breakage in demos/slacksim that CI does not catch, because the
frontend job runs typecheck only in web/.
`pnpm typecheck` in showcase/ failed with five errors, all from one cause. slacksim and consolesim each carried their own `declare global` for window.__showcase and window.__showcaseStory, typed to that demo's own richer interfaces. A `declare global` is program-wide, so under tsconfig.json — which includes both demos — those are two declarations of one property with two types (TS2717), and the four other errors are what follows once TypeScript resolves each property to the other demo's type. Nothing broke at runtime, where exactly one demo loads per page. The globals now live once in demos/showcase-globals.d.ts, typed as the contract the capture engine actually uses: set a caption, move the pointer, run a beat. Both demos' OverlayControl and Rect were already byte-identical, so nothing is lost. `run` and `playTo` are declared as returning `Promise<void> | void`, which both demos satisfy — slacksim's beats are immediate store mutations, consolesim's type into a terminal over time — and awaiting either still works. slacksim's bindControl now returns the ShowcaseControl it binds, so main.tsx uses that value instead of reading window.__showcase! back out and asserting a narrower type than the global carries. That also removes an excess-property error on the object literal. Verified: showcase typecheck passes, as do tsconfig.slacksim.json and tsconfig.consolesim.json on their own, 41 tests across 6 files, both demo builds, docs:check, mage fmt:check, mage web:check, and go build. Note: nothing in CI runs showcase typecheck. The frontend job runs typecheck only in web/, which is why these errors were able to accumulate.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Four commits, reviewable in order:
3e4877f— tooling:.oxfmtrc.json,mage fmt:all/fmt:check, a CIformatjob, a CONTRIBUTING section8a54b7b— Markdown reformat, 179 files02d2b61— TypeScript reformat, 146 files, plus the rebuilt web bundlesb802a07— declare the capture-engine globals once instead of per demoDecisions
One style for all web code.
showcase/was written without semicolons and with single quotes;web/with both. This applies one config to both, so showcase gains roughly 1,550 semicolons and 1,380 quote flips. A nestedshowcase/.oxfmtrc.jsoncould have preserved its style; we chose consistency.Prose wraps at 80 columns, matching what the docs already did by hand.
oxfmt is pinned at 0.70.0 and run through
pnpm dlx, so there is no rootpackage.jsonand nothing added to thego.modtool block.Targets are explicit globs. Excluded: generated MDX,
toolkits/and**/SKILL.md(parsed byskillmd),testdata,webassets/dist, andCLAUDE.md.Implications
Formatting is now a blocking CI check. Run
mage fmt:allbefore opening a PR, and run it untilfmt:checkis clean — oxfmt occasionally needs a second pass.Read
02d2b61by behavior, not by diff. Nothing in it was hand-written;mage fmt:allon its parent reproduces it exactly. One line has a real consequence: the formatter added an explicit{" "}inagentlink.tsxto preserve a space in JSX, which changed a bundle's content hash, so the rebuilt bundle and manifest are committed with it.showcasetypecheck passes again, but nothing in CI runs it — the frontend job coversweb/only. That gap is why the five errors accumulated, and it is not closed here.Verification
mage fmt:check,mage web:check,go build ./..., web typecheck and 1532 tests, showcase typecheck and 41 tests, both demo builds,docs:check.🤖 Generated with Claude Code