2c8f3827ff3f15f11a20885adb09b481111f0c04
6 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
clawbot
|
25b6c0a9de |
Run the lint inside Docker via Dockerfile.lint (closes #38)
All checks were successful
check / check (push) Successful in 1m23s
Add a root Dockerfile.lint that runs `hugo --minify --printPathWarnings`
as a build step, so a successful build IS a clean lint, and reduce
script/lint to building that file. There is no host lint path and
deliberately no "am I already inside a container?" branch, which would
be a host lint path in disguise.
The containerisation boundary is lint only, per the owner ruling on the
issue: formatting is not a lint, so script/fmt and script/fmt-check stay
on the host, unchanged in version, scope and flags. That also removes
the forced duplication of prettier's settings between a script and a
Dockerfile, and with it the keep-in-sync notes that duplication needed.
Dockerfile.lint has exactly one stage on purpose. A whole-file
`docker build -f Dockerfile.lint .` builds only the file's last stage,
and sibling stages off a shared base carry no ordering edge, so a second
stage beside the lint would be silently skipped by exactly the
invocation the canonical org-wide script/lint uses -- a green that
linted nothing, which the per-stage CHECK_EPOCH guard cannot catch
because the stage that did run satisfies it. With one stage there is
nothing to skip and script/lint needs no --target. A comment in the file
says that any second check added here must be chained or carry an
explicit ordering edge, never left as a sibling.
Its first four instructions are byte-identical to the main Dockerfile's
and in the same order, so the expensive `RUN script/bootstrap` layer
that compiles the pinned Hugo from source is shared between the two
images rather than paid twice.
Resolve the recursion by direction, not detection. `make check` calls
script/lint, and script/lint is now a `docker build`, so `RUN make
check` in an image would attempt a docker build inside a build step
where there is no daemon. The main Dockerfile therefore runs the
individual non-lint checks -- script/test and script/fmt-check, as
separate RUN lines under the CHECK_EPOCH guard -- matching the canonical
shape, and only the lint is absent from it. script/cibuild runs
script/lint first, for fail-fast feedback: on a runner with no cached
bootstrap layer a lint failure should not wait behind a Hugo build from
source. CI coverage is therefore unchanged, and it runs the same scripts
a developer runs.
Caching is waived for the lint in the shape this repo already settled:
ARG CHECK_EPOCH with no default, guarded with
`[ -n "$CHECK_EPOCH" ] || exit 1`, and the value expanded into the
linted command as well as the guard, so invalidation never rests on
BuildKit's treatment of an unreferenced ARG. Every image-building
entrypoint generates and passes it -- script/cibuild, script/docker,
script/lint -- each as a whole assignment rather than inline, for the
`set -e` reason script/cibuild documents.
script/lint builds with `--output type=cacheonly`: the build is run for
its exit status, not for an image, and because the lint layer is
cache-busted on every invocation an exporting build leaves one dangling
image per lint run. On a host shared with other work that accumulates.
The build cache is unaffected, so script/bootstrap still hits, and
failures still propagate.
Two divergences from REPO_POLICIES.md, stated rather than buried:
- REPO_POLICIES.md:92, "all Dockerfiles must run `make check`". That
rule and "every lint run happens in Docker" cannot both hold once
`make check` contains the lint.
- REPO_POLICIES.md:102-168, which requires a separate lint stage whose
result the build stage depends on through
`COPY --from=lint /src/go.sum /dev/null`, on the stated grounds that
without the edge "the build stage would not wait for lint to finish
and a lint failure might not fail the overall build". No such edge
exists here: the lint is its own file and its own build, sequenced
by script/cibuild rather than by BuildKit. Both sections are
superseded upstream by 12e8db8 in sneak/prompts, which deletes the
Go multistage lint stage and its ordering trick for the same reason
-- that stage ran `make lint`, which is now a docker build.
Verified: two consecutive script/lint runs on an unchanged tree both
executed hugo for real, distinct epochs echoed, script/bootstrap CACHED,
second run 0.85s; a whole-file `docker build -f Dockerfile.lint .` with
the argument and no --target ran the lint for real; a bare build with no
argument failed closed on the guard; a planted template error failed the
lint with hugo's own render error and made script/cibuild exit non-zero
in 0.6s with the main image build never starting; a planted over-long
line failed the host script/fmt-check; both reverted and re-run clean;
`make check`, script/docker and script/cibuild all green with every
check layer observed executing rather than served from cache, and the
bootstrap layer CACHED in both images. The deploy path is byte-identical
to main: .gitea/, script/bootstrap, script/test and .dockerignore are
untouched.
|
||
| 3e0694e6e0 |
Widen the prettier gate to markdown and CSS everywhere (closes #12)
All checks were successful
check / check (push) Successful in 59s
REPO_POLICIES.md scopes prettier to JS/CSS/Markdown/HTML, but script/fmt
and script/fmt-check covered only '*.md' - top-level markdown. The
canonical scripts use '**/*.md'. Both now run over '**/*.md' and
'**/*.css', and both header comments, which still described the old
top-level-only scope, were rewritten.
That brings themes/loravega/static/css/style.css into the gate. It is
inlined into every page by baseof.html via readFile, and its formatting
is whitespace-only: the minified <style> block in the built
public/index.html is byte-identical across the reformat, which is the
preceding commit.
Two paths are excluded, each with the reason recorded in
.prettierignore so the exclusion reads as a decision rather than an
oversight:
themes/loravega/layouts/ - these are not HTML. They are Go templates
carrying {{ define }}, {{ block }}, {{ .Content }} and
{{ readFile ... | safeCSS }}, and prettier has no Go-template parser; it
would fail or reflow the delimiters into markup Hugo cannot parse.
Covering them needs an out-of-tree plugin and therefore a package.json,
which this repo deliberately does not have.
content/ - excluded on measurement, not on the earlier assumption. With
content/ in scope, prettier re-wrapped one list item in
content/_index.md, and the rendered public/index.html changed with it:
the wrap landed as a literal newline between "7 PM at" and the following
<a> tag. HTML collapses that newline to a space, so the page looks the
same, but the published bytes do not match, and this content carries raw
div/span/br blocks that goldmark passes through verbatim because
hugo.toml sets markup.goldmark.renderer.unsafe = true. A formatter that
can silently change a published page is not worth the consistency.
archetypes/ stays covered - it is a template for new content, not
published output, and prettier leaves it unchanged.
Verified by extracting public/ from the built image before and after.
With the final scope, index.html, index.xml and sitemap.xml are
byte-identical; only the verbatim-copied public/css/style.css differs,
in whitespace. Each commit on this branch passes make check on its own -
the reformat lands first, under the old narrow glob that does not look
at CSS, so the widening commit arrives on an already-clean tree and no
merge commit is required to land it.
|
|||
| 223c520110 |
Cache-bust the make check layer via CHECK_EPOCH (closes #23)
All checks were successful
check / check (push) Successful in 56s
script/cibuild was a bare `docker build .`, and the Dockerfile did
`COPY . .` then `RUN make check`. COPY is keyed on content, so on an
unchanged tree Docker served the check layer from cache: the checks
never executed, no Hugo or prettier output appeared, and the build still
exited 0. A gate that reports success without running is worse than no
gate, because it is trusted -- three separate reviewers in this repo
have been fooled by it.
The Dockerfile now declares `ARG CHECK_EPOCH` immediately below
`COPY . .`, guards it, and expands it into the check command:
ARG CHECK_EPOCH
RUN [ -n "$CHECK_EPOCH" ] || exit 1
RUN echo "check epoch: ${CHECK_EPOCH}" && make check
script/cibuild and script/docker both generate the value identically and
pass it. Every element is load-bearing:
- No default value. A default is a constant, and a constant is a stable
cache key -- the defect unchanged.
- Placed below `COPY . .`. Everything above keeps caching, so the
script/bootstrap layer, which compiles Hugo from source, is not
rebuilt. Whole-build `--no-cache` would have discarded it and blown
the five-minute budget for no benefit.
- The guard. An unset ARG is the empty string, which is also a stable
cache key, so without it a bare `docker build .` still collects the
false green. Failed steps are never cached, so it fails on every such
invocation rather than only the first. This is why script/docker had
to be updated too: the guard makes passing the argument mandatory for
every entrypoint that builds the image.
- The value expanded into the RUN. Hardening rather than the fix: the
bare unreferenced-ARG form does work, but expansion makes the cache
miss contractual rather than dependent on BuildKit's handling of an
unreferenced ARG, and puts the epoch in the build log. The guard also
references the value, so there are two independent invalidation
points, not one.
- `epoch="$(date +%s%N)$$"` on its own line rather than inlined into the
argument list. A command substitution that fails inside an argument
does not trip `set -e`, so the inline form would quietly pass an empty
string and restore the cached false green. `%N` keeps concurrent
invocations distinct; `$$` covers busybox date, which drops `%N`
silently and still exits 0.
ARG is stage-scoped and must be redeclared in every stage that runs
checks. This image is single-stage, so one declaration is complete.
This is the shape settled upstream in the prompts repo, where it has not
merged to main yet, so it may need re-syncing later.
Verified: two consecutive script/cibuild runs on an unchanged tree both
executed the checks (two Hugo builds and the prettier line in each,
15s then 6s) with `RUN script/bootstrap` and `COPY . .` both CACHED in
the second -- the validity control that rules out a cache eviction
between them. A constant-epoch counterfactual restored the cached false
green, confirming the varying value is what does the work. A bare
`docker build .` now fails on the guard, and fails again on immediate
repeat. A planted prettier failure failed the build with exit 1. `make
docker` and `make check` both pass.
|
|||
| 4720c40cfa |
Install Hugo at a deliberate, hash-verified version (closes #26)
script/bootstrap did `pkg_install hugo hugo hugo hugo`, so the tool that produces the published artifact was whatever the base image's package repo happened to serve: alpine 3.21 gives hugo 0.139.0, about two years behind upstream, chosen by nobody, and liable to change silently on any base image digest bump. Hugo's version is a property of the site's output, not of the build environment, so it now gets pinned like every other external reference in this repo. It is installed with `go install github.com/gohugoio/hugo@v0.164.0`, which verifies the module against the sum.golang.org checksum database. That is genuine hash verification rather than bare version pinning, it is the mechanism REPO_POLICIES.md already names for Go, and it needs no hand-maintained sha256. It also keeps a single pinned base image: a digest-pinned Hugo container would have reintroduced the second base image that #7 deliberately removed. Two constants carry the decision, each with the canonical `# name version, YYYY-MM-DD` comment: - HUGO_VERSION=v0.164.0, the current stable release. - HUGO_GOTOOLCHAIN=go1.26.5. hugo v0.164.0's go.mod requires go >= 1.26.0 and alpine 3.21's go package is 1.23.9 built with GOTOOLCHAIN=local, so a bare `go install` refuses to run at all. Naming the toolchain makes Go fetch it through the module proxy and verify it against sum.golang.org like any other module, so the chain stays hash-verified end to end and the compiler is deliberate too. CGO_ENABLED=0 is deliberate: standard Hugo, not extended. Verified that this site uses nothing extended provides - no .scss/.sass, no resources.ToCSS, no PostCSS, and no image processing; the CSS is plain and inlined by readFile in baseof.html. The `+extended` on the apk build this replaces was incidental, and the script says so, so a later change does not assume extended is required. The binary is placed in /usr/local/bin rather than left in a GOPATH bin directory, because it has to be on the default PATH of a *fresh* shell: the Dockerfile's `RUN make check` and deploy.yml's `script/test` step each start their own shell. The location is overridable via HUGO_BIN_DIR for unprivileged installs, and `go install` itself runs as the invoking user so a workstation's module cache is not populated as root. The idempotency guard is version-aware instead of `missing hugo`: an older hugo already on PATH must be replaced, not accepted, or the pin means nothing. A same-version build that happens to be `+extended` is accepted, since it renders this site identically. After installing, the script re-checks what `hugo` on PATH actually resolves to and fails loudly if something else shadows it. Rendered output was compared three ways in a container carrying both binaries - apk 0.139.0 against 0.164.0 on identical sources. Across the whole public/ tree the only byte that differs is the generator meta tag's version string, which is the change describing itself. The RSS <language> element and the html lang attribute are unchanged. Cold `script/cibuild` is 2m36s, within the five-minute budget: 52.6s of it is the bootstrap layer (apk go, toolchain fetch, compile) and 100s is image export. The check image grows to 683 MB because the Go toolchain and module cache stay in the bootstrap layer; that image is only ever built to run checks, never published or deployed. |
|||
|
clawbot
|
bcb90e74b4 |
Run script/lint from script/check (closes #9)
All checks were successful
check / check (push) Successful in 14s
script/check ran only fmt-check then test, so script/lint was never invoked anywhere in the gate: make check shims to script/check, the Dockerfile runs make check, script/cibuild builds the Dockerfile, and the pre-commit hook calls script/check. The script was dead code that the README advertised as part of the gate. It now runs test, lint, fmt-check in the canonical order. script/lint is hugo --minify --printPathWarnings, which reports render-target collisions that the plain hugo --minify in script/test does not; that signal was being discarded. The gate still modifies no tracked files. script/test and script/lint both write to public/, which is gitignored and was already written by script/test before this change. Corrects the two documents that enumerated the old two-step gate: the README Entrypoints line for script/check, and the Dockerfile header comment above the RUN make check that executes it. |
||
| 7cad989724 |
Add scripts-to-rule-them-all scaffold (closes #4)
Adopt the Scripts to Rule Them All standard for this Hugo site: - script/ POSIX-sh entrypoints (bootstrap, setup, projectname, test, lint, fmt, fmt-check, check, docker, cibuild, precommit, install-precommit). The correctness check (test/lint) is a clean `hugo --minify` production build; fmt/fmt-check run prettier over the repo's own top-level markdown only, leaving content/ untouched. - Makefile targets reduced to thin shims that call script/NAME, plus a convenience serve target for `hugo server`. - Dockerfile on a sha256-pinned alpine base that installs deps via script/bootstrap and runs `make check`, so the image build fails on any formatting or Hugo build error; .dockerignore added. - .gitea/workflows/check.yml runs script/cibuild on push. - README Entrypoints section documenting the scripts. |
