README
¶
gnopreview
Builds a static gnoweb snapshot of what a pull request changed, so a reviewer can
look at a realm instead of checking the branch out and running gnodev.
It is what .github/workflows/pr-preview.yml runs. Nothing here talks to a chain:
gnodev boots a fresh local node with only the selected packages loaded, the realms
render their post-init state, and the resulting HTML is crawled into a self-contained
directory tree.
What gets previewed
A pull request is previewed when it touches any of:
| Change | What is rendered |
|---|---|
a realm under examples/gno.land/r/** |
that realm |
a package under examples/gno.land/p/** |
every realm that transitively imports it |
gno.land/pkg/gnoweb/**, gno.land/cmd/gnoweb/**, contribs/gnodev/** |
a fixed sample of realms, plus screenshots |
Anything else produces no preview, no artifact and no pull request comment.
Deliberately excluded, because they cannot change what a realm renders:
*_test.gno, *_filetest.gno, filetests/, examples/quarantined/**, and packages
marked ignore = true. Realms under gno.land/r/tests/ are previewed when changed
directly but never pulled in as dependents — they are VM fixtures, and a change to a
widely imported package would otherwise crowd out the realms the PR is about.
At most 25 realms are rendered (-max-realms). Directly changed realms are rendered
first, so the cap only cuts one when a pull request changes more than 25; the comment
says how many were dropped and names a changed realm it cut without linking it.
Per-file $source pages are rendered only for the files the pull request touched.
They are the bulk of a wide preview — 133 of 243 pages and 13.3 MB of 22.2 MB on a change
to p/nt/avl/v0, which reaches the realm cap — and a reviewer wants the files that
changed, not all of them. A realm pulled in only because it imports a changed package gets
none; when gnoweb itself changed, every realm keeps two, because there the rendering of
a source file is the thing under review. Measured effect on that worst case:
22.2 MB / 243 pages → 8.8 MB / 110 pages.
Usage
# a matching gnodev — the released binary may be older than your tree
( cd contribs/gnodev && go build -o /tmp/gnodev . )
cd misc/gnopreview && go build -o /tmp/gnopreview .
# what would this branch preview?
git diff --name-only origin/master... | /tmp/gnopreview plan -changed -
# render it
git diff --name-only origin/master... > /tmp/changed.txt
GNODEV=/tmp/gnodev GNOROOT=$(git rev-parse --show-toplevel) \
/tmp/gnopreview render -changed /tmp/changed.txt -out _preview
( cd _preview && python3 -m http.server 8777 ) # http://localhost:8777/
Pass -base-root <checkout of the base> to get before/after screenshots of the
realms the pull request changed. Both passes run the head's gnodev and reference the
head's assets, so the pair differs by the realm change and nothing else; the two nodes are
given distinct RPC ports and keybases, because gnodev defaults both to fixed locations and
would otherwise collide.
render writes, next to the site:
preview.json— the plan that was executed, for the CI to readcomment.md— the sticky pull request comment body (absent when there is nothing to preview, which is what makes the CI skip silently)_shots/*.png— screenshots. A gnoweb change gets a fixed four-page sample; a realm change gets<realm>-before.png/<realm>-after.pngfor up to 2 changed realms. The two are alternatives, never both._before/— the changed realms as the base branch renders them, so a reviewer can click through to the before page and not just its screenshot
Publishing lives in a separate repository, gnolang/gno-previews —
see its README for why. This tool does not know about it: it writes a directory, and
pr-preview-publish.yml moves it there over a repo-scoped deploy key.
Output layout
_preview/
index.html # list of rendered realms
public/ # gnoweb css/js/fonts, copied from the repo
r/gnoland/home/index.html # the render view
r/gnoland/home/_t/source/index.html # $source
r/gnoland/home/_t/source-file-home.gno-7a0d5a89/index.html # $source&file=home.gno
r/gnoland/blog/_a/p-hello-13cc55eb/index.html # :p/hello render arguments
_shots/home.png
gnoweb puts the tab and the render arguments in the URL path ($source&file=x,
:p/about). Those spellings are slugged into _t/ and _a/ so no output path ever
contains $, : or & — characters a URL tolerates but a static host may not. A
segment that had to be rewritten carries the first 8 hex digits of its input's SHA-256,
so :p/a-b, :p/a/b and :p/a&b cannot collapse onto one file; source and help
are already safe and stay bare.
Because the site lives under _t/_a/_shots, a .nojekyll marker is mandatory
wherever it is published.
Every absolute URL is rewritten: to a relative path when the target was captured, to
https://gno.land/… when it was not, so a link that leaves the preview lands on the
live site rather than a 404. The same relativizing is applied inside the copied
assets — public/js/index.js builds its dynamic import() specifiers from a
hardcoded /public/js/controller- prefix, which would 404 from any mount point other
than the site root, taking every interactive control with it.
Bounds
The crawl follows links only within the selected realms, and skips URL shapes that enumerate rather than describe:
$state&oid=…/&tid=…— the state explorer walks the whole object graph, and gnoweb rate-limits it (HTTP 429) exactly as a crawler would trip it$state— ~1.3 MB of HTML per realm, describing a chain that only ever raninit()$help&func=X—$helpalready lists every exported function with its form$download&file=X— raw file bytes, not a page:args$source/:args$help— byte-identical to the argument-free tab
Render arguments get a per-realm cap of their own (-max-args, 10). They are the one
axis a realm can grow without limit: the files and the tabs are whatever the realm and
gnoweb have, but a realm may link one page per value it knows about, and each is a full
page of chrome. Nothing in examples/ comes close today (the busiest, r/gnoland/coins,
renders 5, and a p/nt/avl/v0 change produces 16 across 25 realms), so the cap changes
nothing about what is rendered now; what it buys is that a realm which starts enumerating
cannot exhaust -max-pages, which fails the whole render rather than trimming it.
A -max-pages cap (400) backstops the rest.
Search engines
Every captured page is a near-duplicate of a real gno.land page, so the snapshot must not be
indexed. gnoweb's own layout emits <meta name="robots" content="index, follow"> on every
page (components/layouts/head.html); the renderer replaces that tag with
noindex, nofollow rather than adding a second one, because two conflicting robots
directives leave the outcome to each crawler's precedence rules.
Deliberately not a robots.txt Disallow instead: a disallowed path can still be indexed
when something links to it, and being disallowed is precisely what stops a crawler from
fetching the page and reading the noindex. GitHub Pages cannot set an X-Robots-Tag
header, so the meta tag is the only authoritative mechanism available.
Known limits
- Transactions, the faucet, and search do not work: there is no signer and no chain behind the snapshot.
- Realms render their state right after
init(). A realm that is only interesting once it holds data will look empty. - Cross-realm navigation out of the previewed set goes to the live site, which may show a different version of the realm than the branch.
Documentation
¶
Overview ¶
Command gnopreview builds a static gnoweb snapshot of what a pull request changed, so the PR can link to a rendered page instead of asking reviewers to run gnodev themselves.
It has two modes, matching the two halves of the CI workflow:
gnopreview plan -changed <file> # what would be previewed, as JSON gnopreview render -changed <file> -out dir # boot gnodev, crawl, write the tree gnopreview comment -snapshot dir -base-url # the sticky PR comment, from a snapshot
`render` also writes <out>/preview.json and <out>/comment.md. The publishing job does not post that comment.md, which the pull request's own code wrote: it runs `comment` from the default branch over the snapshot's preview.json.