Author SHA1 Message Date
clawbot 9cc6d43c68 CODE_STYLEGUIDE_GO: propose naming rules (closes #174)
check / check (push) Successful in 29s
Adds a Naming section to the Go style guide: ten rules for package
names, fourteen for exported names as the caller reads them, and three
for local names. Each is one rule with its reason.

The sentence that banned `util` now points to the section, which bans
it along with `model`, `common`, `types`, `helpers`, `api` and the
like, and says what to name the package instead.

The guide's error example now uses an `Err` name, as the new rule on
error values asks.

This is a proposal. Nothing is renamed in any repo until sneak
approves or amends the rules.

Model: fable-5-2 (proposal); opus-5-5 (rework)
2026-11-16 07:26:13 +00:00
16 changed files with 1086 additions and 1450 deletions

No files matched your search

+13 -11
View File
@@ -2,14 +2,18 @@
# lint` or `script/lint`, which are themselves a docker build and would
# recurse into a daemon that does not exist in a build step.
#
# node and yarn come from the distribution, which is trusted, so they
# need no version and no hash. That yarn only starts the release file in
# .yarn/releases/, so every stage copies that file and .yarnrc.yml
# before it runs script/bootstrap.
# In every stage, ARG CACHEBUST comes right after the step that installs
# system packages. script/ passes a new value on every build. That value
# reruns every RUN step below the ARG line, and the install step keeps
# its layer. node and yarn come from the distribution, which is trusted,
# so they need no version and no hash. That yarn only starts the release
# file in .yarn/releases/, so every stage copies that file and
# .yarnrc.yml before it runs script/bootstrap.
#
# alpine 3.24.3, 2026-11-04
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
RUN apk add --no-cache git make nodejs-current yarn
ARG CACHEBUST
WORKDIR /app
@@ -22,15 +26,12 @@ COPY . .
RUN yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
# Test phase, same shape and for the same reason. coreutils makes cp GNU
# cp, which writes into an existing file, as cp does on most hosts.
# busybox cp makes a new file, so test/commit-upstream-policy-files.sh
# would pass even if script/write-upstream-policy-files copied straight
# over the running script/commit-upstream-policy-files.
# Test phase, same shape and for the same reason.
#
# alpine 3.24.3, 2026-11-04
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
RUN apk add --no-cache coreutils git make nodejs-current yarn
RUN apk add --no-cache git make nodejs-current yarn
ARG CACHEBUST
WORKDIR /app
@@ -41,7 +42,7 @@ RUN script/bootstrap
COPY . .
RUN test/commit-upstream-policy-files.sh
RUN timeout 90 test/update-policy.sh
# Development environment, and the last stage: a plain `docker build .`
# names no target and so builds this one. Nothing is wanted from the two
@@ -52,6 +53,7 @@ RUN test/commit-upstream-policy-files.sh
# alpine 3.24.3, 2026-11-04
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
RUN apk add --no-cache git make nodejs-current yarn
ARG CACHEBUST
WORKDIR /app
+3 -6
View File
@@ -1,4 +1,4 @@
.PHONY: bootstrap setup test lint fmt fmt-check check docker hooks write-upstream-policy-files commit-upstream-policy-files
.PHONY: bootstrap setup test lint fmt fmt-check check docker hooks update-policy
# Makefile targets are thin shims; the implementations live in script/
# per the scripts-to-rule-them-all pattern (see the Entrypoints section
@@ -31,8 +31,5 @@ docker:
hooks:
@script/install-precommit
write-upstream-policy-files:
@script/write-upstream-policy-files
commit-upstream-policy-files:
@script/commit-upstream-policy-files
update-policy:
@script/update-policy
+29 -18
View File
@@ -116,10 +116,12 @@ alpine. We provide:
`script/bootstrap`, then `script/install-precommit`
- `script/projectname` — output the project name (our own extension); used by
`script/docker` for the image tag
- `script/test` — `docker build --target test --output type=cacheonly .`,
- `script/test` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
building the `test` phase of the `Dockerfile`, which runs
`test/commit-upstream-policy-files.sh`, without writing an image
- `script/lint` — `docker build --target lint --output type=cacheonly .`,
`test/update-policy.sh`, without writing an image
- `script/lint` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
building the `lint` phase, which runs prettier over the markdown files,
without writing an image
- `script/fmt` — format all markdown files with prettier (writes; native, not in
@@ -127,31 +129,40 @@ alpine. We provide:
- `script/fmt-check` — check formatting (read-only; native)
- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
extension); builds no image of its own
- `script/docker` — `docker build --build-arg VERSION="$version" -t prompts .`,
- `script/docker` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`,
the tag coming from `script/projectname` (byte-identical across repos)
- `script/cibuild` — cd to the repo root, run `script/bootstrap`, run
`script/check`, compute `version` from `git describe`, then
`docker build --build-arg VERSION="$version" -t prompts .` (what CI runs; it
bootstraps because CI checks out and runs this alone while `script/fmt-check`
is native)
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`
(what CI runs; it bootstraps because CI checks out and runs this alone while
`script/fmt-check` is native)
- `script/precommit` — run by the git pre-commit hook (our own extension); calls
`script/check`
- `script/install-precommit` — installs the git pre-commit hook (our own
extension); `make hooks` shims to it
- `script/write-upstream-policy-files` — fetch the vendored policy files from
this repo over HTTP and write them into a repo (our own extension). It writes
into the repo given as its argument, or its own repo with no argument. It
stops when its target is this repo.
- `script/commit-upstream-policy-files` — fetch the current
`script/write-upstream-policy-files`, run it on its own repo and commit the
result without pushing (our own extension). It is for the repos that vendor
the policy files. It stops when run here.
- `script/update-policy` — fetch the vendored policy files from this repo,
commit them and push (our own extension); it is for the repos that vendor them
and stops when run here
`make hooks` installs the pre-commit hook that runs `script/precommit`.
The builds use Docker's normal cache: a step runs again only when its inputs
change. This repo's own `Dockerfile` installs git, make, node and yarn right
after `FROM` in every stage, so a change to `script/` keeps that layer.
In every stage of a `Dockerfile`, every step that lints, tests or compiles comes
after `ARG CACHEBUST`. `ARG CACHEBUST` comes right after these steps:
- the steps that install system packages
- the steps that download Go's modules
- the step that runs `script/bootstrap` to install a Python `test` phase's
packages from `Pipfile.lock`
A stage with none of these steps declares `ARG CACHEBUST` right after `FROM`.
The `script/` builds pass a new `CACHEBUST` value on every build, which reruns
every `RUN` step after that line and leaves the layers above it and the cache
mounts in place; `--no-cache` would build those layers again and empty the
mounts. This repo's own `Dockerfile` installs git, make, node and yarn right
after `FROM` in every stage, above `ARG CACHEBUST`. `script/bootstrap` installs
the node packages below that line, because check builds keep system packages but
not node packages.
## Rationale
+7 -1
View File
@@ -113,7 +113,13 @@ last_modified: 2026-11-16
1. Write a `Dockerfile` for every repo, even if it only runs the tests and
linting. It carries the lint and test phases, and the final stage depends on
both, so a build makes sure the code is in an able-to-be-compiled state,
linted, and its tests run.
linted, and its tests run. Go through `script/cibuild` or `script/docker`
rather than a bare `docker build .`: they pass a new `CACHEBUST` value on
every build, which reruns every step that lints, tests or compiles and keeps
the system packages, Go's modules and build cache, and golangci-lint's
cache; `--no-cache` would throw all of them away. Without a new value an
unchanged tree serves the gate layers from cache and the build reports a
green it never ran.
1. Every repo must have a `Makefile`. See
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
+52 -39
View File
@@ -1,6 +1,6 @@
---
title: Existing Repo Checklist
last_modified: 2026-11-16
last_modified: 2026-11-09
---
Use this checklist when beginning work in a repo that may not yet conform to our
@@ -49,11 +49,23 @@ with your task.
`--target` names it, so a lost `COPY --from=` edge leaves `docker build .`
passing while the gate never runs. Confirm by planting a violation, not by
reading the file.
- [ ] No `docker build` in `script/` passes `--no-cache` or a cache-busting
build argument such as `CACHEBUST`, and no `Dockerfile` stage declares
`ARG CACHEBUST`.
- [ ] In every stage, every step that lints, tests or compiles comes after
`ARG CACHEBUST`. `ARG CACHEBUST` comes right after these steps:
- the steps that install system packages
- the steps that download Go's modules
- the step that runs `script/bootstrap` to install a Python `test` phase's
packages from `Pipfile.lock`
- [ ] A stage with none of these steps declares `ARG CACHEBUST` right after
`FROM`. A step that also installs anything else comes after
`ARG CACHEBUST` too. A `script/bootstrap` that also installs node packages
is one. The `script/` builds pass a new `CACHEBUST` value on every build,
which reruns every `RUN` step after that line and leaves the layers above
it and the cache mounts in place; `--no-cache` would build those layers
again and empty the mounts. A stage without the `ARG` line is served from
cache on an unchanged tree, so the scripts and the `ARG` lines are
re-vendored in one commit.
- [ ] Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
`RUN go mod download`) before `COPY . .`; the steps that compile
`RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
(`golangci-lint run`, `go test`, `go build`) mount Go's build cache
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
also mounts golangci-lint's
@@ -62,7 +74,7 @@ with your task.
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
`REPO_POLICIES.md`
- [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
it before `COPY . .`, with `COPY script/ script/`,
it above `ARG CACHEBUST`, with `COPY script/ script/`,
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
`script/bootstrap` runs in that step, it installs nothing beyond these:
- system packages
@@ -79,8 +91,9 @@ with your task.
a package with no wheel for the image stops the install. In that step it
installs no Python, because a step above it already did. `Pipfile` names no
`python_version`, because `--deploy` stops when the distribution's Python
differs from it. The tests run after `COPY . .`, as in the Python `test`
phase example in `REPO_POLICIES.md`
differs from it. The tests run after `ARG CACHEBUST`, and every other stage
installs its Python packages after it, as in the Python `test` phase example
in `REPO_POLICIES.md`
- [ ] The gate phases invoke their tools directly, never through `make lint` or
`script/test` — those are themselves a `docker build` and would recurse
@@ -192,48 +205,41 @@ with your task.
- [ ] `Makefile` exists in root — reference
`https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`
- [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
`hooks`, `commit-upstream-policy-files`
`hooks`, `update-policy`
- [ ] Target implementations live in `script/` (scripts-to-rule-them-all);
Makefile targets are thin shims calling them — model scripts at
`https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`
- [ ] `script/precommit` exists and the pre-commit hook (installed by
`script/install-precommit`, shimmed by `make hooks`) runs it
- [ ] `script/write-upstream-policy-files` and
`script/commit-upstream-policy-files` exist, identical to the model
scripts, and `make commit-upstream-policy-files` shims to
`script/commit-upstream-policy-files`. `make commit-upstream-policy-files`
commits without pushing, so a person reviews and pushes the commit. A
`.gitignore` or `.dockerignore` without the comment that ends the
canonical file needs no preparation. The script moves each line the
canonical file has never held to below the canonical content. Blank lines
and comments are dropped. Before its first use, add that comment to an
`.editorconfig` that has lines of its own, and put those lines below it.
Otherwise the script stops before it writes anything, naming the file and
each line. In a file that has the comment, an entry above it which the
canonical file has never held also stops the script. It stops the same way
on a line in `.golangci.yml` that the canonical file has never held, apart
from comments and the repo's entries in the `deny` list of the
`test-support` rule. It also stops on a repo's own
`script/write-upstream-policy-files` or
`script/commit-upstream-policy-files`.
- [ ] `script/update-policy` exists, identical to the model script, and
`make update-policy` shims to it. Before its first use, the repo's own
entries in `.gitignore`, `.editorconfig` and `.dockerignore` go below the
comment that ends each canonical file. An entry above that comment which
the canonical file has never held makes the script stop before it writes
anything, naming the file and the entry. It stops the same way on a line
in `.golangci.yml` that the canonical file has never held, apart from
comments and the repo's entries in the `deny` list of the `test-support`
rule.
- [ ] README has an **Entrypoints** section documenting the `script/`
entrypoints and linking the standard
- [ ] `script/lint` and `script/test` each run
`docker build --target <phase> --output type=cacheonly .`, which builds
their phase by name and writes no image, and no host invocation anywhere
in the repo can produce a lint verdict — grep for the linter's own name
across `script/`, the `Makefile` and CI config, not just `script/lint`. A
second path is likeliest here: a `make lint-fast`, an older
host-versus-container branch, or a CI step calling the binary directly.
`script/fmt` and `script/fmt-check` are expected hits and stay on the
host.
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target <phase> --output type=cacheonly .`,
which builds their phase by name and writes no image, and no host
invocation anywhere in the repo can produce a lint verdict — grep for the
linter's own name across `script/`, the `Makefile` and CI config, not just
`script/lint`. A second path is likeliest here: a `make lint-fast`, an
older host-versus-container branch, or a CI step calling the binary
directly. `script/fmt` and `script/fmt-check` are expected hits and stay
on the host.
- [ ] No `docker build` in `script/` leaves a dangling image behind:
`script/lint` and `script/test` write no image, and `script/docker` and
`script/cibuild` tag theirs. A build that writes an untagged image leaves
one behind on every run, on every host and CI runner.
- [ ] `script/cibuild` runs `script/bootstrap` before `script/check`. Without
the bootstrap the CI run dies in `script/fmt-check`, which runs the
formatter on the host and finds nothing installed.
- [ ] `script/cibuild` runs `script/bootstrap` before `script/check`, and builds
the image with a new `CACHEBUST` value on every build, like every
`docker build` in `script/`. Without the bootstrap the CI run dies in
`script/fmt-check`, which runs the formatter on the host and finds nothing
installed.
- [ ] `script/bootstrap` installs node, yarn and the node packages only when
`yarn.lock` is in the tree. node and yarn come from the distribution when
they are missing. It installs the node packages with
@@ -321,7 +327,14 @@ with your task.
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
That host is the runner image
`docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
node 24. Take any yarn off `PATH` first.
node 24. Take any yarn off `PATH` first. The run must show that the checks
executed. A sub-second build means nothing ran. So does `CACHED` on a step
that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
that line, these steps are expected to show `CACHED`:
- the steps that install system packages
- the steps that download Go's modules
- the step that runs `script/bootstrap` to install a Python `test` phase's
packages from `Pipfile.lock`
- [ ] A planted lint violation fails both `make lint` and a plain
`docker build .`; revert it afterwards
- [ ] Commit and merge fixes before starting your actual task
+44 -23
View File
@@ -1,6 +1,6 @@
---
title: New Repo Checklist
last_modified: 2026-11-16
last_modified: 2026-11-09
---
Use this checklist when creating a new repository from scratch. Follow the steps
@@ -118,8 +118,23 @@ Template files can be fetched from:
stage carries a `COPY --from=` of a harmless file from each so the image
cannot be built unless both passed. Keep the final stage last: a stage
nothing depends on is built only when `--target` names it.
- In every stage, every step that lints, tests or compiles comes after
`ARG CACHEBUST`. `ARG CACHEBUST` comes right after these steps:
- the steps that install system packages
- the steps that download Go's modules
- the step that runs `script/bootstrap` to install a Python `test`
phase's packages from `Pipfile.lock`
- A stage with none of these steps declares `ARG CACHEBUST` right after
`FROM`. A step that also installs anything else comes after
`ARG CACHEBUST` too. A `script/bootstrap` that also installs node packages
is one. The `script/` builds pass a new `CACHEBUST` value on every build,
which reruns every `RUN` step after that line and leaves the layers above
it and the cache mounts in place; `--no-cache` would build those layers
again and empty the mounts. A stage without the `ARG` line is served from
cache on an unchanged tree, so the scripts and every stage's
`ARG CACHEBUST` line are added in the same commit.
- Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
`RUN go mod download`) before `COPY . .`; the steps that compile
`RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
(`golangci-lint run`, `go test`, `go build`) mount Go's build cache
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
also mounts golangci-lint's
@@ -128,7 +143,7 @@ Template files can be fetched from:
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
`REPO_POLICIES.md`
- Python: a `test` phase that installs its packages from `Pipfile.lock` does
it before `COPY . .`, with `COPY script/ script/`,
it above `ARG CACHEBUST`, with `COPY script/ script/`,
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
`script/bootstrap` runs in that step, it installs nothing beyond these:
- system packages
@@ -146,7 +161,8 @@ Template files can be fetched from:
for the image stops the install. In that step it installs no Python,
because a step above it already did. `Pipfile` names no
`python_version`, because `--deploy` stops when the distribution's
Python differs from it. The tests run after `COPY . .`, as in the Python
Python differs from it. The tests run after `ARG CACHEBUST`, and every
other stage installs its Python packages after it, as in the Python
`test` phase example in `REPO_POLICIES.md`
- Server: the final stage builds and runs the application
@@ -211,12 +227,13 @@ are thin shims calling them. Model scripts:
- [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
then `install-precommit`, plus repo-specific init
- [ ] `script/test` / `make test` —
`docker build --target test --output type=cacheonly .`, which writes no
image; the phase runs real tests, not a no-op (90-second timeout,
60-second hard cap on wall time)
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
which writes no image; the phase runs real tests, not a no-op (90-second
timeout, 60-second hard cap on wall time)
- [ ] `script/lint` / `make lint` —
`docker build --target lint --output type=cacheonly .`, which writes no
image. No lint verdict may come from a host invocation of the linter.
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
which writes no image. No lint verdict may come from a host invocation of
the linter.
- [ ] `script/fmt` / `make fmt` — formats code (writes; native, never in a
container). Go code gets `gofmt`, then `golines -m 77`.
- [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only;
@@ -228,15 +245,16 @@ are thin shims calling them. Model scripts:
- [ ] `script/projectname` — outputs the project name (used by `script/docker`
for the image tag)
- [ ] `script/docker` / `make docker` — builds Docker image, tagged via
`script/projectname` (byte-identical across repos), with the version as a
build arg
`script/projectname` (byte-identical across repos); a new `CACHEBUST`
value on every build, plus the version as a build arg
- [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run
`script/check`, then
`docker build --build-arg VERSION="$version" -t "$tag" .` (what CI runs),
with `$version` from `git describe --tags --always --dirty` (`unknown` if
empty) and `$tag` from `script/projectname`, each assigned on its own line
before the build. The bootstrap is required: CI checks out and runs this
alone, and `script/fmt-check` runs the formatter on the host.
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t "$tag" .`
(what CI runs), with `$version` from
`git describe --tags --always --dirty` (`unknown` if empty) and `$tag`
from `script/projectname`, each assigned on its own line before the build.
The bootstrap is required: CI checks out and runs this alone, and
`script/fmt-check` runs the formatter on the host.
- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
@@ -248,13 +266,9 @@ are thin shims calling them. Model scripts:
- [ ] `script/install-precommit` — installs the pre-commit hook that runs
`script/precommit`
- [ ] `make hooks` — shims to `script/install-precommit`
- [ ] `script/write-upstream-policy-files` — fetches the vendored policy files
from the `prompts` repo over HTTP and writes them into the repo; identical
- [ ] `script/update-policy` / `make update-policy` — fetches the vendored
policy files from the `prompts` repo, commits them and pushes; identical
across repos
- [ ] `script/commit-upstream-policy-files` /
`make commit-upstream-policy-files` — fetches the current
`script/write-upstream-policy-files`, runs it on the repo and commits the
result without pushing; identical across repos
- [ ] README **Entrypoints** section documents the scripts and links the
standard
@@ -265,7 +279,14 @@ are thin shims calling them. Model scripts:
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
That host is the runner image
`docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
node 24. Take any yarn off `PATH` first.
node 24. Take any yarn off `PATH` first. The run must show that the checks
executed. A sub-second build means nothing ran. So does `CACHED` on a step
that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
that line, these steps are expected to show `CACHED`:
- the steps that install system packages
- the steps that download Go's modules
- the step that runs `script/bootstrap` to install a Python `test` phase's
packages from `Pipfile.lock`
- [ ] Plant a lint violation and confirm both `make lint` and a plain
`docker build .` fail on it; revert. A plain build that passes proves the
final stage is missing its `COPY --from=` edge to the gate phases.
+110 -76
View File
@@ -1,6 +1,6 @@
---
title: Repository Policies
last_modified: 2026-11-16
last_modified: 2026-11-09
---
This document covers repository structure, tooling, and workflow standards. Code
@@ -93,8 +93,8 @@ style conventions are in separate documents:
- `make check` (runs `test`, `lint`, `fmt-check`)
- `make docker`
- `make hooks` (installs pre-commit hook)
- `make commit-upstream-policy-files` (brings the repo up to standards and
commits)
- `make update-policy` (fetches the vendored policy files, commits and
pushes)
A model Makefile is at
`https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
@@ -111,8 +111,7 @@ style conventions are in separate documents:
- `script/fmt-check`
- `script/check`
- `script/docker`
- `script/write-upstream-policy-files`
- `script/commit-upstream-policy-files`
- `script/update-policy`
The scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they
run in minimal containers; alpine images, for example, have no bash. Locate
@@ -186,19 +185,15 @@ style conventions are in separate documents:
host. On a pristine checkout with nothing installed, the run dies there,
after the containerised gates have passed.
Six further scripts are our own extensions to the standard:
Five further scripts are our own extensions to the standard:
- `script/check` runs `script/test`, `script/lint` and `script/fmt-check`.
- `script/precommit` is what the git pre-commit hook runs, and it calls
`script/check`.
- `script/install-precommit` installs the git pre-commit hook. The
`make hooks` target shims to it.
- `script/write-upstream-policy-files` fetches the vendored policy files
from the `prompts` repo over HTTP and writes them into the repo it is
given, or its own repo with no argument.
- `script/commit-upstream-policy-files` fetches the current
`script/write-upstream-policy-files` from the `prompts` repo, runs it on
its own repo and commits the result. It does not push. The
`make commit-upstream-policy-files` target shims to it.
- `script/update-policy` fetches the vendored policy files from the
`prompts` repo, commits them and pushes. The `make update-policy` target
shims to it.
- `script/projectname` (literally that filename) simply outputs the
project's name.
@@ -259,8 +254,10 @@ style conventions are in separate documents:
phase and nothing else:
```sh
docker build --target lint --output type=cacheonly .
docker build --target test --output type=cacheonly .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target lint --output type=cacheonly .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target test --output type=cacheonly .
```
**A stage that is not the last one in the file is built only when the final
@@ -278,8 +275,7 @@ style conventions are in separate documents:
CI runner. `script/cibuild` and `script/docker` build the image that ships
and tag it, so each build replaces the previous image. Each script assigns
the tag on its own line before the build, so `set -e` stops it where
`script/projectname` fails. `script/check` runs the two gate phases and
`script/fmt-check`, and builds no image of its own.
`script/projectname` fails.
Inside a phase the tool is invoked directly: `golangci-lint`, `go test`,
`eslint`, `prettier`. The tool is never invoked through `make lint` or
@@ -302,16 +298,48 @@ style conventions are in separate documents:
- the settings
- the golangci-lint version
- **Check builds use Docker's normal cache.** On an unchanged tree Docker reuses
each step's stored result, and it stores a result only for a step that
succeeded. A step runs again when one of these changes:
- the base image
- its own line or a line above it
- the files copied before it
- **Any build that runs checks is given a new `CACHEBUST` value.** Docker
invalidates a `COPY` layer only when the copied content changes. On an
unchanged tree the check `RUN` is therefore served from cache, nothing
executes, and the build still exits 0. Every `docker build` in `script/`
therefore passes `--build-arg CACHEBUST="$(date +%s)-$$"`, the time and the
script's process id. So no two builds share a value, not even the three in one
`script/cibuild`. Four scripts do this, and there is no fifth:
- `script/lint`
- `script/test`
- `script/cibuild`
- `script/docker`
Nothing needs to run again on an unchanged tree. Never prune the build cache
(`docker builder prune` and the like): it is shared with every other build
on the host. When a check is added or changed, prove it works:
`script/check` runs the two gate phases and `script/fmt-check`, and builds
no image of its own. In every stage of the `Dockerfile`, every step that
lints, tests or compiles comes after `ARG CACHEBUST`. `ARG CACHEBUST` comes
right after these steps:
- the steps that install system packages
- the steps that download Go's modules
- the step that runs `script/bootstrap` to install a Python `test` phase's
packages from `Pipfile.lock`
A stage with none of these steps declares `ARG CACHEBUST` right after
`FROM`. A step that also installs anything else comes after `ARG CACHEBUST`
too. A `script/bootstrap` that also installs node packages is one. A new
value reruns every `RUN` step after that line; `COPY` steps are compared by
content and need nothing. Docker keeps the layers above the line until one
of these changes:
- the base image
- their own lines
- the files they copy
A stage without the `ARG` line is served from cache on an unchanged tree, so
a repository re-vendors the scripts and adds the `ARG` lines in one commit.
The scripts do not pass `--no-cache`. That flag reruns every step too, but
it also builds the layers above the line again and empties every cache
mount. Go's build cache and golangci-lint's would then start empty every
time; the canonical Go `Dockerfile` below mounts them so that they survive
between check builds. A bare `docker build .` is not evidence that anything
ran: a sub-second build reporting success is a cache hit, not a result.
Never invalidate by pruning: `docker builder prune` and friends destroy a
build cache shared with every other build on the host. When a check is added
or changed, prove it works:
- plant a defect it must catch
- watch the run fail on it
- revert the defect
@@ -326,8 +354,12 @@ style conventions are in separate documents:
`Dockerfile`:
```dockerfile
# The steps that install system packages and download Go's modules
# come before COPY . ., so a change to the code keeps their layers.
# In every stage ARG CACHEBUST comes right after the steps that install
# system packages and download Go's modules, or right after FROM in a
# stage with neither, and every step that lints, tests or compiles
# comes after it. script/ passes a new value on every build, which
# reruns every RUN step after it. Docker keeps the layers above it
# until the base image, their own lines or go.mod and go.sum change.
# The steps that compile mount Go's build cache, and golangci-lint run
# also mounts golangci-lint's; both survive from build to build.
@@ -337,6 +369,7 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
--mount=type=cache,target=/root/.cache/golangci-lint \
@@ -352,6 +385,7 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
status=0; \
@@ -376,6 +410,7 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
COPY --from=lint /src/go.sum /dev/null
COPY --from=test /src/go.sum /dev/null
# A tar-stream context keeps the sender's file owners, which git refuses.
@@ -401,6 +436,7 @@ style conventions are in separate documents:
# Runtime stage, and the last one
FROM alpine@sha256:...
ARG CACHEBUST
COPY --from=builder /app /usr/local/bin/app
ENTRYPOINT ["app"]
```
@@ -416,15 +452,15 @@ style conventions are in separate documents:
two copies. A plain `docker build .` builds the last stage's chain and
nothing else.
- Check builds keep these, and none of them can hand back a stale result:
- The layers of the system packages and Go's modules. Docker installs
the packages again when the base image or the install line changes.
Docker downloads the modules again when `go.mod` or `go.sum` changes.
Go checks every module against `go.sum` as it downloads it, and no
later build can change a kept layer. The modules are kept in a layer
rather than a cache mount. A cache mount is shared by every build on
the host, and Go builds from whatever files the mount holds without
checking them again (only `go mod verify` does). A file changed there
would go unnoticed.
- The layers above `ARG CACHEBUST`: the system packages and Go's
modules. Docker installs the packages again when the base image or the
install line changes. Docker downloads the modules again when `go.mod`
or `go.sum` changes. Go checks every module against `go.sum` as it
downloads it, and no later build can change a kept layer. The modules
are kept in a layer rather than a cache mount. A cache mount is shared
by every build on the host, and Go builds from whatever files the
mount holds without checking them again (only `go mod verify` does). A
file changed there would go unnoticed.
- Go's build cache (`/root/.cache/go-build`, where Go keeps it for
root), mounted on the steps that compile: `golangci-lint run`, both
`go test` runs and `go build`. Go reuses a compiled package only when
@@ -451,8 +487,8 @@ style conventions are in separate documents:
(`libvips-dev`, where alpine says `vips-dev`), and delete the package
lists in the same `RUN`, so the layer does not keep them. The test phase,
on the Debian Go image, installs the libraries its tests need the same
way. Either install goes right after `FROM`, so Docker keeps it until the
base image or the install line changes:
way. Either install goes right after `FROM`, above `ARG CACHEBUST`, so
Docker keeps it until the base image or the install line changes:
```dockerfile
FROM golangci/golangci-lint@sha256:... AS lint
@@ -462,6 +498,7 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
```
- `.dockerignore` lets `.git` into the build context. It keeps out every git
@@ -502,19 +539,21 @@ style conventions are in separate documents:
already do.
- **A Python `test` phase that installs its packages from `Pipfile.lock` does it
before `COPY . .`, so check builds keep them.** The steps are:
above `ARG CACHEBUST`, so check builds keep them.** The steps are:
- `COPY script/ script/`
- `COPY Pipfile Pipfile.lock ./`
- `RUN script/bootstrap`
Docker keeps what that `RUN` installed until one of these changes:
`ARG CACHEBUST` comes right after them. Docker keeps what that `RUN`
installed until one of these changes:
- the base image
- `script/`
- `Pipfile`
- `Pipfile.lock`
- a line up to and including the `RUN`
The tests run after `COPY . .`.
The tests run after `ARG CACHEBUST`, on every check build. In every other
stage, a step that installs Python packages comes after `ARG CACHEBUST`.
- When `script/bootstrap` runs in that step, it installs nothing beyond
these:
- system packages
@@ -522,7 +561,8 @@ style conventions are in separate documents:
- the packages from `Pipfile.lock`
`script/bootstrap` installs no Python there: the tests use the
distribution's Python, which a step above it installs.
distribution's Python, which a step above it installs. If it installs
anything else there, the step goes after `ARG CACHEBUST`.
- Debian's Python refuses a system-wide `pip install`, so pipenv goes in a
virtual environment at `$HOME/.pipenv`. `script/bootstrap` creates it with
@@ -604,6 +644,7 @@ style conventions are in separate documents:
COPY script/ script/
COPY Pipfile Pipfile.lock ./
RUN script/bootstrap
ARG CACHEBUST
COPY . .
RUN timeout 90 sh -c 'pipenv run pytest || { \
echo "--- Rerunning with -v for details ---"; \
@@ -622,17 +663,20 @@ style conventions are in separate documents:
A new push then cancels the older run on the same branch, queued or running,
and no other: runs for replaced commits do not hold up the shared runner.
`script/cibuild` bootstraps, runs the gate phases, and then builds the image,
so a successful run means every check passed. The image build reuses the gate
phases that the check has just built. The `check` job sets
`timeout-minutes: 20`, so a hung build frees the shared runner after 20
minutes. That allows for the three Docker builds described above, each held to
the 5-minute Docker build limit below, plus the bootstrap. Those builds are
the test phase, the lint phase, then the image. A separate workflow limited to
`main` by a `branches` list under `on: push` cannot be checked by review. To
try a change to it, add the feature branch to that list and push, then remove
the branch from the list again before merging. Keep any job in it that
publishes behind `if: github.ref_name == 'main'`, so the run from the feature
branch publishes nothing.
so a successful run means every check passed. A bare `docker build .` does not
carry the same guarantee, because its gate phases may come from the cache. The
image build gets a `CACHEBUST` value of its own and so runs the gate phases a
second time. That is the price of the rule above, and it is worth paying. The
image that ships is built from a run of its own gates rather than from a cache
entry. The `check` job sets `timeout-minutes: 20`, so a hung build frees the
shared runner after 20 minutes. That allows for the three Docker builds
described above, each held to the 5-minute Docker build limit below, plus the
bootstrap. Those builds are the test phase, the lint phase, then the image. A
separate workflow limited to `main` by a `branches` list under `on: push`
cannot be checked by review. To try a change to it, add the feature branch to
that list and push, then remove the branch from the list again before merging.
Keep any job in it that publishes behind `if: github.ref_name == 'main'`, so
the run from the feature branch publishes nothing.
- Use platform-standard formatters:
- `black` for Python
@@ -743,7 +787,8 @@ style conventions are in separate documents:
running them. The directory lasts from one run to the next on a developer's
machine, where this target runs. The directory also lasts in the `test`
phase of the `Dockerfile`, which mounts it to keep compiled packages between
check builds, so the phase's `go test` runs carry `-count=1` too.
check builds, so the phase's `go test` runs carry `-count=1` too. A new
`CACHEBUST` value (above) is what makes that step run on an unchanged tree.
Python example:
@@ -846,7 +891,9 @@ style conventions are in separate documents:
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
[ -n "$version" ] || version="unknown"
tag="$(script/projectname)"
docker build --build-arg VERSION="$version" -t "$tag" .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--build-arg VERSION="$version" \
-t "$tag" .
```
`--always` makes an untagged repo yield an abbreviated commit hash rather
@@ -886,26 +933,14 @@ style conventions are in separate documents:
- Make all changes on a feature branch. You can do whatever you want on a
feature branch.
- One command brings a repo up to standards:
`make commit-upstream-policy-files`. It runs
`script/commit-upstream-policy-files`, which fetches the current
`script/write-upstream-policy-files` from the head of `main` in the `prompts`
repo and runs it on the repo. It then commits the files that changed and does
not push, so a person reviews and pushes the commit.
`script/write-upstream-policy-files` fetches each vendored file from
`prompts` over HTTP and writes it into the repo. It skips a language's files
when git tracks no source file of that language. A file the repo lacks is
written whole. A `prompts/NAME.md` goes to `docs/NAME.md`, unless the repo
keeps it at `NAME.md`. It also writes `script/write-upstream-policy-files`
and `script/commit-upstream-policy-files` into the repo, so a repo updated
once can update itself. The list of vendored files is at the top of
`script/write-upstream-policy-files`. The script replaces each file and
keeps only the repo's own entries:
- A repo updates its policy files with one command: `make update-policy`. It
runs `script/update-policy`, which fetches each vendored file the repo carries
from the `prompts` repo, commits them and pushes. It uses the head of `main`,
or the commit given by a full hash: `script/update-policy <hash>`. The list of
vendored files is at the top of that script. The script replaces each file and
keeps only the repo's own entries:
- in `.gitignore`, `.editorconfig` and `.dockerignore`: the lines below the
comment that ends the canonical file
- in a `.gitignore` or `.dockerignore` lacking that comment: every entry the
canonical file has never held
- in `.golangci.yml`: the entries the repo added to the `deny` list of the
`test-support` depguard rule
@@ -1134,8 +1169,7 @@ style conventions are in separate documents:
- `Makefile`
- `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
`lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
`install-precommit`, `write-upstream-policy-files`,
`commit-upstream-policy-files`)
`install-precommit`, `update-policy`)
- `Dockerfile`, `.dockerignore`
- `.gitea/workflows/check.yml`
- Go: `go.mod`, `go.sum`, `.golangci.yml`
+9 -1
View File
@@ -2,6 +2,12 @@
# script/cibuild: run the CI build. It bootstraps first: a CI runner
# checks out and runs this and nothing else, and script/fmt-check runs
# the formatter on the host, which a pristine checkout cannot do.
# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
# line, since a cached gate phase is a check that did not run; unlike
# --no-cache, it keeps the layers above that line and the cache mounts.
# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
# before every step that lints, tests or compiles; a stage without that
# line is served from cache on an unchanged tree, with no warning.
set -eu
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -19,7 +25,9 @@ main() {
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
[ -n "$version" ] || version="unknown"
tag="$("$SCRIPT_DIR/projectname")"
docker build --build-arg VERSION="$version" -t "$tag" .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--build-arg VERSION="$version" \
-t "$tag" .
}
main "$@"
-45
View File
@@ -1,45 +0,0 @@
#!/bin/sh
# script/commit-upstream-policy-files: bring this repo up to standards.
# It fetches the current script/write-upstream-policy-files from the
# prompts repo over HTTP, runs it on this repo and commits the files it
# wrote. It does not push. Identical in all repos. Our own extension to
# scripts-to-rule-them-all.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
WRITE_UPSTREAM_POLICY_FILES_URL="https://git.eeqj.de/sneak/prompts/raw/branch/main/script/write-upstream-policy-files"
die() {
echo "commit-upstream-policy-files: $*" >&2
exit 1
}
main() {
[ "$#" -eq 0 ] || die "usage: script/commit-upstream-policy-files"
cd "$ROOT"
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
curl --fail --silent --show-error --max-time 60 \
--output "$tmp/write-upstream-policy-files" \
"$WRITE_UPSTREAM_POLICY_FILES_URL" ||
die "cannot fetch $WRITE_UPSTREAM_POLICY_FILES_URL"
sh "$tmp/write-upstream-policy-files" "$ROOT" > "$tmp/written"
commit="$(head -n 1 "$tmp/written")"
paths="$(tail -n +2 "$tmp/written")"
for path in $paths; do
git add -- "$path"
done
if git diff --cached --quiet -- $paths; then
echo "commit-upstream-policy-files: already at prompts $commit, nothing to commit"
else
git commit -m "Update policy files from prompts $commit" -- $paths
fi
}
main "$@"
+9 -1
View File
@@ -1,6 +1,12 @@
#!/bin/sh
# script/docker: build the Docker image tagged with the project name.
# Identical in all repos; the tag comes from script/projectname.
# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
# line, since a cached gate phase is a check that did not run; unlike
# --no-cache, it keeps the layers above that line and the cache mounts.
# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
# before every step that lints, tests or compiles; a stage without that
# line is served from cache on an unchanged tree, with no warning.
set -eu
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -16,7 +22,9 @@ main() {
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
[ -n "$version" ] || version="unknown"
tag="$("$SCRIPT_DIR/projectname")"
docker build --build-arg VERSION="$version" -t "$tag" .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--build-arg VERSION="$version" \
-t "$tag" .
}
main "$@"
+11 -2
View File
@@ -5,7 +5,14 @@
# make its answer untrustworthy.
#
# --target builds the lint phase and the stages it depends on, nothing
# else. --output type=cacheonly writes no image, since nothing uses one.
# else. A new CACHEBUST value reruns every RUN step after
# the ARG CACHEBUST line, since a cached lint layer is a lint that did
# not run; unlike --no-cache, it keeps the layers above that line and
# the cache mounts. This relies on every stage of the Dockerfile
# declaring ARG CACHEBUST before every step that lints, tests or
# compiles; a stage without that line is served from cache on an
# unchanged tree, with no warning.
# --output type=cacheonly writes no image, since nothing uses one.
set -eu
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -13,7 +20,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
main() {
cd "$ROOT"
docker build --target lint --output type=cacheonly .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target lint \
--output type=cacheonly .
}
main "$@"
+10 -3
View File
@@ -2,8 +2,13 @@
# script/test: run the test suite. Testing is a phase of the Dockerfile
# and this builds that phase, on the same terms as script/lint:
# --target so that only the test phase and the stages it depends on are
# built, and --output type=cacheonly so that no image is written, since
# nothing uses one.
# built, and a new CACHEBUST value because a cached test layer is a test
# that did not run; unlike --no-cache, it keeps the layers above the ARG
# CACHEBUST line and the cache mounts. This relies on every stage of the
# Dockerfile declaring ARG CACHEBUST before every step that lints, tests
# or compiles; a stage without that line is served from cache on an
# unchanged tree, with no warning. --output type=cacheonly writes no
# image, since nothing uses one.
set -eu
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -11,7 +16,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
main() {
cd "$ROOT"
docker build --target test --output type=cacheonly .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target test \
--output type=cacheonly .
}
main "$@"
+222
View File
@@ -0,0 +1,222 @@
#!/bin/sh
# script/update-policy: replace this repo's vendored policy files with
# the canonical ones from the prompts repo, commit them and push.
# Identical in all repos. Our own extension to
# scripts-to-rule-them-all.
#
# Usage: script/update-policy [full commit hash of prompts]
# Without a hash it uses the head of the prompts main branch.
#
# The script writes nothing until every file has been fetched and
# merged. A repo's own entries are kept:
# - .gitignore, .editorconfig, .dockerignore: the lines below the
# canonical file's last line. An entry above that line which the
# canonical file has never held stops the script.
# - .golangci.yml: the entries the repo added to the deny list of the
# test-support rule. Any other line the canonical file has never
# held stops the script, unless it is blank or a comment.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
PROMPTS_URL="https://git.eeqj.de/sneak/prompts"
# Paths in the prompts repo. A file this repo does not carry is skipped.
VENDORED_FILES="
.dockerignore
.editorconfig
.gitea/workflows/check.yml
.gitignore
.golangci.yml
.prettierrc
prompts/API_POLICIES.md
prompts/CODE_STYLEGUIDE.md
prompts/CODE_STYLEGUIDE_GO.md
prompts/CODE_STYLEGUIDE_JS.md
prompts/CODE_STYLEGUIDE_PYTHON.md
prompts/EXISTING_REPO_CHECKLIST.md
prompts/GO_HTTP_SERVER_CONVENTIONS.md
prompts/LLM_PROSE_TELLS.md
prompts/NEW_REPO_CHECKLIST.md
prompts/REPO_POLICIES.md
"
die() {
echo "update-policy: $*" >&2
exit 1
}
# local_path <path in prompts>: print where this repo keeps the file, or
# nothing if git does not track it here. A prompts/NAME.md lands at
# docs/NAME.md or NAME.md.
local_path() {
name="${1#prompts/}"
if [ "$name" != "$1" ] && [ -n "$(git ls-files -- "docs/$name")" ]; then
echo "docs/$name"
elif [ -n "$(git ls-files -- "$name")" ]; then
echo "$name"
fi
}
# local_only_lines <fetched> <local> [end]: print each line of the local
# file, above line end if given, that the canonical file has never held:
# not in the fetched file or in <fetched>.former, the lines earlier
# commits removed from it. Blank lines and comments do not count.
local_only_lines() {
cat "$1" "$1.former" | awk -v end="${3:-}" '
NR == FNR { held[$0]; next }
(end == "" || FNR < end) && !/^[ \t]*(#|$)/ && !($0 in held)
' - "$2"
}
# keep_lines_below_last <fetched> <local>: append to the fetched file
# whatever follows its last line in the local file. Stop if the canonical
# file has never held a line above that one, unless it is blank or a
# comment: replacing the file would delete it.
keep_lines_below_last() {
last="$(tail -n 1 "$1")"
number="$(grep -n -F -x -- "$last" "$2" | head -n 1 | cut -d: -f1)"
if [ -z "$last" ] || [ -z "$number" ]; then
die "$2 lacks this line; add it and put the repo's own entries below it: $last"
fi
own="$(local_only_lines "$1" "$2" "$number")"
if [ -n "$own" ]; then
die "$2 has entries above its last canonical line that the canonical file lacks; move each below that line to keep it, or delete it:
$own"
fi
tail -n "+$((number + 1))" "$2" >> "$1"
}
# keep_deny_entries <fetched> <local>: add to the deny list of the
# test-support rule in the fetched file the entries only the local file
# has. An entry is a "- pkg:" line, the lines under it and any comment
# above it. Stop if the local file still has a line that neither the
# result nor the canonical file has ever held, unless it is blank or a
# comment: replacing the file would delete it.
keep_deny_entries() {
awk '
function indent(line) { return match(line, /[^ ]/) - 1 }
function print_local_entries(i) {
for (i = 1; i <= count; i++)
if (!(pkg[i] in fetched_pkg))
printf "%s", entry[i]
}
FNR == 1 { in_rule = 0; in_list = 0 }
in_list && /[^ ]/ && indent($0) <= list_indent {
in_list = 0
if (FILENAME == ARGV[2]) print_local_entries()
}
in_list {
is_entry = ($1 == "-" && $2 == "pkg:")
if (FILENAME == ARGV[2]) {
if (is_entry) fetched_pkg[$3]
print
} else if (is_entry) {
count++
pkg[count] = $3
entry[count] = comment $0 "\n"
comment = ""
} else if (/^ *#/) {
comment = comment $0 "\n"
} else if (count) {
entry[count] = entry[count] $0 "\n"
}
next
}
in_rule && /^ *[^ #]/ && indent($0) <= rule_indent { in_rule = 0 }
/^ *test-support:/ { in_rule = 1; rule_indent = indent($0) }
in_rule && /^ *deny:/ {
in_rule = 0
in_list = 1
list_indent = indent($0)
if (FILENAME == ARGV[2]) found = 1
}
FILENAME == ARGV[2] { print }
END {
if (in_list) print_local_entries()
exit !found
}
' "$2" "$1" > "$1.merged" ||
die "the fetched $2 has no deny list in its test-support rule"
mv "$1.merged" "$1"
own="$(local_only_lines "$1" "$2")"
if [ -n "$own" ]; then
die "$2 has lines the canonical file has never held; only the deny list of the test-support rule may differ from canonical:
$own"
fi
}
main() {
cd "$ROOT"
[ "$#" -le 1 ] || die "usage: script/update-policy [full commit hash]"
project="$(script/projectname)"
if [ "$project" = "prompts" ]; then
die "this repo is the source of the policy files"
fi
commit="${1:-}"
if [ -z "$commit" ]; then
head_line="$(git ls-remote "$PROMPTS_URL.git" refs/heads/main)"
commit="${head_line%%[[:space:]]*}"
fi
printf '%s\n' "$commit" | grep -Eqx '[0-9a-f]{40}' ||
die "not a full commit hash: '$commit'"
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
git clone --quiet --bare "$PROMPTS_URL.git" "$tmp/prompts.git" ||
die "cannot clone $PROMPTS_URL.git"
carried=""
for file in $VENDORED_FILES; do
path="$(local_path "$file")"
[ -n "$path" ] || continue
if [ -n "$(git status --porcelain -- "$path")" ]; then
die "$path has uncommitted changes"
fi
mkdir -p "$tmp/$(dirname "$path")"
curl --fail --silent --show-error --max-time 60 \
--output "$tmp/$path" \
"$PROMPTS_URL/raw/commit/$commit/$file" ||
die "cannot fetch $file at $commit"
git -C "$tmp/prompts.git" log -p --format= "$commit" -- "$file" |
sed -n 's/^-//p' > "$tmp/$path.former"
carried="$carried $path"
done
[ -n "$carried" ] || die "this repo carries none of the vendored files"
for path in $carried; do
case "$path" in
.gitignore | .editorconfig | .dockerignore)
keep_lines_below_last "$tmp/$path" "$path"
;;
.golangci.yml)
keep_deny_entries "$tmp/$path" "$path"
;;
esac
done
for path in $carried; do
cp "$tmp/$path" "$path"
git add -- "$path"
done
if git diff --cached --quiet -- $carried; then
echo "update-policy: already at prompts $commit, nothing to commit"
else
git commit -m "Update policy files from prompts $commit" -- $carried
fi
# Also pushes when there was nothing to commit, so a run after a
# failed push delivers the commit that push left behind.
git push origin HEAD || die "push failed; fix that and run this again"
}
main "$@"
-302
View File
@@ -1,302 +0,0 @@
#!/bin/sh
# script/write-upstream-policy-files: write the current policy files
# from the prompts repo into a repo clone, over HTTP. It commits
# nothing; script/commit-upstream-policy-files does that. Identical in
# all repos. Our own extension to scripts-to-rule-them-all.
#
# Usage: script/write-upstream-policy-files [path of a repo clone]
# Without a path it updates the repo this script sits in.
#
# Standard output is the full hash of the prompts commit, then each path
# written, one per line. Messages go to standard error.
#
# The script writes nothing until every file has been fetched and
# merged. A repo's own entries are kept:
# - .gitignore, .editorconfig, .dockerignore: the lines below the
# canonical file's last line. An entry above that line which the
# canonical file has never held stops the script.
# - .gitignore, .dockerignore lacking that last line: each line the
# canonical file has never held, unless it is blank or a comment,
# goes below the canonical content.
# - .editorconfig lacking that last line: it is replaced if it has no
# such line. Otherwise the script stops, because a setting means
# nothing away from its section.
# - .golangci.yml: the entries the repo added to the deny list of the
# test-support rule. Any other line the canonical file has never
# held stops the script, unless it is blank or a comment.
set -eu
PROMPTS_URL="https://git.eeqj.de/sneak/prompts"
PROMPTS_API_URL="https://git.eeqj.de/api/v1/repos/sneak/prompts"
PROMPTS_FIRST_COMMIT="af257bef63f162a681bddc80d9b941c47a44b748"
# Paths in the prompts repo. Every repo gets each file, written whole if
# the repo lacks it. A language's files are skipped when git tracks no
# source file of that language.
VENDORED_FILES="
.dockerignore
.editorconfig
.gitea/workflows/check.yml
.gitignore
.golangci.yml
.prettierrc
prompts/API_POLICIES.md
prompts/CODE_STYLEGUIDE.md
prompts/CODE_STYLEGUIDE_GO.md
prompts/CODE_STYLEGUIDE_JS.md
prompts/CODE_STYLEGUIDE_PYTHON.md
prompts/EXISTING_REPO_CHECKLIST.md
prompts/GO_HTTP_SERVER_CONVENTIONS.md
prompts/LLM_PROSE_TELLS.md
prompts/NEW_REPO_CHECKLIST.md
prompts/REPO_POLICIES.md
script/write-upstream-policy-files
script/commit-upstream-policy-files
"
die() {
echo "write-upstream-policy-files: $*" >&2
exit 1
}
# fetch <url> <output file>
fetch() {
curl --fail --silent --show-error --max-time 60 --output "$2" "$1" ||
die "cannot fetch $1"
}
# file_applies <path in prompts>: fail if the file is for a language of
# which git tracks no source file in the target repo.
file_applies() {
case "$1" in
.golangci.yml | prompts/CODE_STYLEGUIDE_GO.md | \
prompts/GO_HTTP_SERVER_CONVENTIONS.md)
[ -n "$(git ls-files -- '*.go')" ]
;;
prompts/CODE_STYLEGUIDE_JS.md)
[ -n "$(git ls-files -- '*.js' '*.mjs' '*.ts')" ]
;;
prompts/CODE_STYLEGUIDE_PYTHON.md)
[ -n "$(git ls-files -- '*.py')" ]
;;
esac
}
# local_path <path in prompts>: print where the file goes in the target
# repo. A prompts/NAME.md stays at NAME.md if git tracks it there and not
# at docs/NAME.md; otherwise it goes to docs/NAME.md. Any other file goes
# to its own path.
local_path() {
name="${1#prompts/}"
if [ "$name" = "$1" ]; then
echo "$1"
elif [ -z "$(git ls-files -- "docs/$name")" ] &&
[ -n "$(git ls-files -- "$name")" ]; then
echo "$name"
else
echo "docs/$name"
fi
}
# former_lines <patch> <path in prompts>: print the lines earlier commits
# removed from the file. The file's section of the patch ends at the
# next diff or the next commit.
former_lines() {
awk -v header="diff --git a/$2 b/$2" '
/^diff --git / { inside = ($0 == header); next }
/^From / { inside = 0; next }
inside && /^-/ { print substr($0, 2) }
' "$1"
}
# local_only_lines <fetched> <local> [end]: print each line of the local
# file, above line end if given, that the canonical file has never held:
# not in the fetched file or in <fetched>.former, the lines earlier
# commits removed from it. Blank lines and comments do not count.
local_only_lines() {
cat "$1" "$1.former" | awk -v end="${3:-}" '
NR == FNR { held[$0]; next }
(end == "" || FNR < end) && !/^[ \t]*(#|$)/ && !($0 in held)
' - "$2"
}
# keep_lines_below_last <fetched> <local>: append to the fetched file
# whatever follows its last line in the local file. Stop if the canonical
# file has never held a line above that one, unless it is blank or a
# comment: replacing the file would delete it. If the local file lacks
# that last line, append each line the canonical file has never held,
# unless it is blank or a comment. An .editorconfig with such a line
# stops the script instead, because a setting means nothing away from
# its section.
keep_lines_below_last() {
last="$(tail -n 1 "$1")"
number="$(grep -n -F -x -- "$last" "$2" | head -n 1 | cut -d: -f1)"
if [ -z "$last" ] || [ -z "$number" ]; then
own="$(local_only_lines "$1" "$2")"
[ -n "$own" ] || return 0
if [ "$2" = .editorconfig ]; then
die "$2 lacks this line and has lines the canonical file has never held; add it and put those lines below it: $last
$own"
fi
printf '%s\n' "$own" >> "$1"
return 0
fi
own="$(local_only_lines "$1" "$2" "$number")"
if [ -n "$own" ]; then
die "$2 has entries above its last canonical line that the canonical file lacks; move each below that line to keep it, or delete it:
$own"
fi
tail -n "+$((number + 1))" "$2" >> "$1"
}
# keep_deny_entries <fetched> <local>: add to the deny list of the
# test-support rule in the fetched file the entries only the local file
# has. An entry is a "- pkg:" line, the lines under it and any comment
# above it. Stop if the local file still has a line that neither the
# result nor the canonical file has ever held, unless it is blank or a
# comment: replacing the file would delete it.
keep_deny_entries() {
awk '
function indent(line) { return match(line, /[^ ]/) - 1 }
function print_local_entries(i) {
for (i = 1; i <= count; i++)
if (!(pkg[i] in fetched_pkg))
printf "%s", entry[i]
}
FNR == 1 { in_rule = 0; in_list = 0 }
in_list && /[^ ]/ && indent($0) <= list_indent {
in_list = 0
if (FILENAME == ARGV[2]) print_local_entries()
}
in_list {
is_entry = ($1 == "-" && $2 == "pkg:")
if (FILENAME == ARGV[2]) {
if (is_entry) fetched_pkg[$3]
print
} else if (is_entry) {
count++
pkg[count] = $3
entry[count] = comment $0 "\n"
comment = ""
} else if (/^ *#/) {
comment = comment $0 "\n"
} else if (count) {
entry[count] = entry[count] $0 "\n"
}
next
}
in_rule && /^ *[^ #]/ && indent($0) <= rule_indent { in_rule = 0 }
/^ *test-support:/ { in_rule = 1; rule_indent = indent($0) }
in_rule && /^ *deny:/ {
in_rule = 0
in_list = 1
list_indent = indent($0)
if (FILENAME == ARGV[2]) found = 1
}
FILENAME == ARGV[2] { print }
END {
if (in_list) print_local_entries()
exit !found
}
' "$2" "$1" > "$1.merged" ||
die "the fetched $2 has no deny list in its test-support rule"
mv "$1.merged" "$1"
own="$(local_only_lines "$1" "$2")"
if [ -n "$own" ]; then
die "$2 has lines the canonical file has never held; only the deny list of the test-support rule may differ from canonical:
$own"
fi
}
# stop_on_own_script <fetched> <local>: stop if the local script has a
# line the canonical file has never held, unless it is blank or a
# comment: the repo wrote that script itself, and replacing it would
# delete it.
stop_on_own_script() {
own="$(local_only_lines "$1" "$2")"
if [ -n "$own" ]; then
die "$2 has lines the canonical file has never held; rename the repo's own script to keep it:
$own"
fi
}
main() {
[ "$#" -le 1 ] ||
die "usage: script/write-upstream-policy-files [path of a repo clone]"
target="${1:-$(dirname "$0")/..}"
cd "$target" || die "no such directory: $target"
if [ "$(git rev-parse --show-toplevel 2> /dev/null)" != "$(pwd -P)" ]; then
die "not the top of a git clone: $target"
fi
if [ -e prompts/REPO_POLICIES.md ]; then
die "this repo is the source of the policy files"
fi
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
fetch "$PROMPTS_API_URL/branches/main" "$tmp/branch.json"
commit="$(grep -Eo '"id":"[0-9a-f]{40}"' "$tmp/branch.json" |
head -n 1 | cut -d'"' -f4)"
[ -n "$commit" ] || die "no commit hash in $PROMPTS_API_URL/branches/main"
fetch "$PROMPTS_URL/compare/$PROMPTS_FIRST_COMMIT...$commit.patch" \
"$tmp/history.patch"
to_write=""
for file in $VENDORED_FILES; do
file_applies "$file" || continue
path="$(local_path "$file")"
if git check-ignore -q -- "$path"; then
die "$path is ignored by git; stop ignoring it"
fi
if [ -n "$(git status --porcelain -- "$path")" ]; then
die "$path has uncommitted changes"
fi
mkdir -p "$tmp/$(dirname "$path")"
fetch "$PROMPTS_URL/raw/commit/$commit/$file" "$tmp/$path"
former_lines "$tmp/history.patch" "$file" > "$tmp/$path.former"
to_write="$to_write $path"
done
for path in $to_write; do
[ -e "$path" ] || continue
case "$path" in
.gitignore | .editorconfig | .dockerignore)
keep_lines_below_last "$tmp/$path" "$path"
;;
.golangci.yml)
keep_deny_entries "$tmp/$path" "$path"
;;
script/*)
stop_on_own_script "$tmp/$path" "$path"
;;
esac
done
echo "$commit"
for path in $to_write; do
mkdir -p "$(dirname "$path")"
case "$path" in
script/*)
# A new name and mv, because the script running may be
# script/commit-upstream-policy-files.
cp "$tmp/$path" "$path.new"
chmod 755 "$path.new"
mv "$path.new" "$path"
;;
*)
cp "$tmp/$path" "$path"
;;
esac
echo "$path"
done
}
main "$@"
-922
View File
@@ -1,922 +0,0 @@
#!/bin/sh
# test/commit-upstream-policy-files.sh: test
# script/write-upstream-policy-files and script/commit-upstream-policy-files
# on throwaway repos. Each scenario gets one temp directory holding a
# repo, its local bare origin, a local git repository of the canonical
# files in place of prompts, and a stub curl that serves them, so nothing
# touches the network.
set -eu
SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd -P)/script"
WRITE_UPSTREAM_POLICY_FILES="$SCRIPT_DIR/write-upstream-policy-files"
COMMIT_UPSTREAM_POLICY_FILES="$SCRIPT_DIR/commit-upstream-policy-files"
dir=""
trap 'rm -rf "$dir"' EXIT
fail() {
echo "FAIL: $scenario: $*" >&2
cat "$dir/output" >&2
exit 1
}
# The stub stops with curl's HTTP error status on any URL containing
# FAIL_URL, and answers with no commit hash when BAD_BRANCH_JSON is set.
write_stub_curl() {
mkdir "$dir/bin"
cat > "$dir/bin/curl" << 'EOF'
#!/bin/sh
previous=""
fail_flag=""
for argument in "$@"; do
[ "$previous" = "--output" ] && output="$argument"
[ "$argument" = "--fail" ] && fail_flag=yes
previous="$argument"
done
url="$previous"
canonical="$(dirname "$0")/../canonical"
site="https://git.eeqj.de/sneak/prompts"
first="af257bef63f162a681bddc80d9b941c47a44b748"
not_found() {
[ -n "$fail_flag" ] && exit 22
echo "404 page not found" > "$output"
exit 0
}
serve_file() {
[ -f "$canonical/$1" ] || not_found
cat "$canonical/$1" > "$output"
}
case "$url" in
*"${FAIL_URL:-no url contains this}"*)
not_found
;;
"https://git.eeqj.de/api/v1/repos/sneak/prompts/branches/main")
if [ -n "${BAD_BRANCH_JSON:-}" ]; then
echo '{"message":"no such branch"}' > "$output"
else
printf '{"name":"main","commit":{"id":"%s"},"x":{"id":"%s"}}\n' \
"$HASH" 0000000000000000000000000000000000000000 > "$output"
fi
;;
"$site/raw/branch/main/script/write-upstream-policy-files")
serve_file script/write-upstream-policy-files
;;
"$site/compare/$first...$HASH.patch")
git -C "$canonical" format-patch --stdout --root "$HASH" > "$output"
;;
"$site/raw/commit/$HASH/"*)
serve_file "${url#"$site/raw/commit/$HASH/"}"
;;
*)
not_found
;;
esac
EOF
chmod +x "$dir/bin/curl"
}
write_canonical_files() {
mkdir -p "$dir/canonical/prompts" "$dir/canonical/script"
cp "$WRITE_UPSTREAM_POLICY_FILES" "$COMMIT_UPSTREAM_POLICY_FILES" \
"$dir/canonical/script/"
cat > "$dir/canonical/.gitignore" << 'EOF'
*.log
*.tmp
# Own entries go below this comment.
EOF
cat > "$dir/canonical/.dockerignore" << 'EOF'
**/*.log
**/*.tmp
# Own entries go below this comment.
EOF
cat > "$dir/canonical/.editorconfig" << 'EOF'
root = true
[*]
indent_size = 4
# Own sections go below this comment.
EOF
cat > "$dir/canonical/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
- pkg: net/http/cgi
desc: added canonically
other:
deny:
- pkg: example.com/other
EOF
echo '{ "tabWidth": 4 }' > "$dir/canonical/.prettierrc"
echo "new policy" > "$dir/canonical/prompts/REPO_POLICIES.md"
echo "new api policy" > "$dir/canonical/prompts/API_POLICIES.md"
for name in CODE_STYLEGUIDE CODE_STYLEGUIDE_GO CODE_STYLEGUIDE_JS \
CODE_STYLEGUIDE_PYTHON EXISTING_REPO_CHECKLIST \
GO_HTTP_SERVER_CONVENTIONS LLM_PROSE_TELLS NEW_REPO_CHECKLIST; do
echo "new $name" > "$dir/canonical/prompts/$name.md"
done
mkdir -p "$dir/canonical/.gitea/workflows"
echo "name: check" > "$dir/canonical/.gitea/workflows/check.yml"
}
# commit_canonical: commit the canonical files as they stand. The stub
# curl serves only the newest commit; every other commit gets a 404.
commit_canonical() {
git -C "$dir/canonical" add .gitignore .dockerignore .editorconfig \
.golangci.yml .prettierrc .gitea prompts script
git -C "$dir/canonical" commit -q -m "Canonical"
HASH="$(git -C "$dir/canonical" rev-parse HEAD)"
}
# write_outdated_files: this repo's files, one canonical version behind,
# with the repo's own entries in the places the script keeps them. The
# comment above the closing comment in .gitignore is replaced, not kept.
write_outdated_files() {
cat > "$dir/repo/.gitignore" << 'EOF'
*.log
# An outdated comment.
# Own entries go below this comment.
/myapp
EOF
cat > "$dir/repo/.dockerignore" << 'EOF'
**/*.log
# Own entries go below this comment.
/myapp
EOF
cat > "$dir/repo/.editorconfig" << 'EOF'
root = true
[*]
# Own sections go below this comment.
[*.py]
indent_size = 2
EOF
cat > "$dir/repo/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
# Our own test helpers.
- pkg: example.com/app/internal/apptest
desc: own entry
other:
deny:
- pkg: example.com/other
EOF
echo '{ "tabWidth": 2 }' > "$dir/repo/.prettierrc"
echo "old policy" > "$dir/repo/REPO_POLICIES.md"
}
# start_scenario <name>: make a new temp directory holding a repo with
# a Go source file and the outdated files, not yet committed, and an
# empty origin.
start_scenario() {
scenario="$1"
rm -rf "$dir"
dir="$(mktemp -d)"
: > "$dir/output"
mkdir "$dir/tmp"
write_stub_curl
write_canonical_files
export GIT_CONFIG_GLOBAL="$dir/gitconfig"
git config --global user.name "Test"
git config --global user.email "test@example.com"
export FAIL_URL=""
export BAD_BRANCH_JSON=""
git init -q -b main "$dir/canonical"
export HASH
commit_canonical
git init -q --bare -b main "$dir/origin.git"
git init -q -b main "$dir/repo"
git -C "$dir/repo" remote add origin "$dir/origin.git"
mkdir "$dir/repo/script"
cp "$WRITE_UPSTREAM_POLICY_FILES" "$COMMIT_UPSTREAM_POLICY_FILES" \
"$dir/repo/script/"
printf '#!/bin/sh\necho example\n' > "$dir/repo/script/projectname"
chmod +x "$dir/repo/script/projectname"
mkdir -p "$dir/repo/cmd/app"
echo "package main" > "$dir/repo/cmd/app/main.go"
write_outdated_files
}
# commit_and_push_fixture <paths...>: commit those paths as they stand
# and every other shared file as the canonical file has it, so the
# script changes only those paths. Record the commit as $before.
commit_and_push_fixture() {
(
cd "$dir/repo"
git add script cmd "$@"
git clean -q -f -x
for file in $(git -C "$dir/canonical" ls-files); do
case "$file" in
script/*) continue ;;
prompts/REPO_POLICIES.md) path="REPO_POLICIES.md" ;;
prompts/*) path="docs/${file#prompts/}" ;;
*) path="$file" ;;
esac
if [ -z "$(git ls-files -- "$path")" ]; then
mkdir -p "$(dirname "$path")"
cp "$dir/canonical/$file" "$path"
git add "$path"
fi
done
git commit -q -m "Fixture"
git push -q origin HEAD
)
before="$(git -C "$dir/repo" rev-parse HEAD)"
}
# remove_from_fixture <paths...>: delete those paths from the repo and
# its origin, and record the commit as $before.
remove_from_fixture() {
(
cd "$dir/repo"
git rm -q -r "$@"
git commit -q -m "Remove from fixture"
git push -q origin HEAD
)
before="$(git -C "$dir/repo" rev-parse HEAD)"
}
run_commit_upstream_policy_files() {
status=0
(cd "$dir/repo" && PATH="$dir/bin:$PATH" TMPDIR="$dir/tmp" \
script/commit-upstream-policy-files "$@") > "$dir/output" 2>&1 ||
status=$?
}
# run_write_upstream_policy_files <arguments>: run the script in this
# source tree, from outside the repo it updates.
run_write_upstream_policy_files() {
status=0
(cd "$dir" && PATH="$dir/bin:$PATH" TMPDIR="$dir/tmp" \
"$WRITE_UPSTREAM_POLICY_FILES" "$@") > "$dir/output" 2>&1 ||
status=$?
}
head_of_repo() {
git -C "$dir/repo" rev-parse HEAD
}
head_of_origin() {
git -C "$dir/origin.git" rev-parse refs/heads/main
}
files_in_commit() {
git -C "$dir/repo" show --name-only --format= HEAD | tr '\n' ' '
}
expect_success() {
[ "$status" -eq 0 ] || fail "exited $status"
}
expect_failure() {
[ "$status" -ne 0 ] || fail "exited 0"
}
expect_output() {
grep -q -F -e "$1" "$dir/output" || fail "output lacks: $1"
}
expect_output_without() {
if grep -q -F -e "$1" "$dir/output"; then
fail "output has: $1"
fi
}
# expect_file <path>: the file must equal standard input.
expect_file() {
cat > "$dir/expected"
diff "$dir/expected" "$dir/repo/$1" >&2 || fail "$1 is wrong"
}
expect_same_as_canonical() {
diff "$dir/canonical/$1" "$dir/repo/$1" >&2 || fail "$1 is not canonical"
}
expect_absent() {
[ ! -e "$dir/repo/$1" ] || fail "$1 exists"
}
expect_executable() {
[ "$(stat -c %a "$dir/repo/$1")" = 755 ] || fail "$1 is not mode 755"
}
expect_committed_executable() {
git -C "$dir/repo" ls-files -s -- "$1" | grep -q '^100755 ' ||
fail "$1 is not committed as executable"
}
expect_new_commit_not_pushed() {
[ "$(head_of_repo)" != "$before" ] || fail "no commit was made"
[ "$(head_of_origin)" = "$before" ] || fail "the commit was pushed"
}
expect_no_commit() {
[ "$(head_of_repo)" = "$before" ] || fail "the repo has a new commit"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
}
expect_nothing_written() {
[ -z "$(git -C "$dir/repo" status --porcelain)" ] ||
fail "the working tree changed"
expect_no_commit
}
test_own_entries_kept() {
start_scenario "own entries kept in all four files"
commit_and_push_fixture .gitignore .dockerignore .editorconfig \
.golangci.yml .prettierrc REPO_POLICIES.md
run_commit_upstream_policy_files
expect_success
expect_file .gitignore << 'EOF'
*.log
*.tmp
# Own entries go below this comment.
/myapp
EOF
expect_file .dockerignore << 'EOF'
**/*.log
**/*.tmp
# Own entries go below this comment.
/myapp
EOF
expect_file .editorconfig << 'EOF'
root = true
[*]
indent_size = 4
# Own sections go below this comment.
[*.py]
indent_size = 2
EOF
expect_file .golangci.yml << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
- pkg: net/http/cgi
desc: added canonically
# Our own test helpers.
- pkg: example.com/app/internal/apptest
desc: own entry
other:
deny:
- pkg: example.com/other
EOF
expect_file .prettierrc << 'EOF'
{ "tabWidth": 4 }
EOF
expect_file REPO_POLICIES.md << 'EOF'
new policy
EOF
expect_new_commit_not_pushed
git -C "$dir/repo" log -1 --format=%s | grep -q -F -e "$HASH" ||
fail "the commit message does not name the head of main"
[ "$(files_in_commit)" = ".dockerignore .editorconfig .gitignore .golangci.yml .prettierrc REPO_POLICIES.md " ] ||
fail "the commit holds other files: $(files_in_commit)"
[ -z "$(ls -A "$dir/tmp")" ] || fail "a temporary directory is left"
}
test_files_the_repo_lacks_are_written_whole() {
start_scenario "files the repo lacks are written whole"
mkdir "$dir/repo/docs"
mv "$dir/repo/REPO_POLICIES.md" "$dir/repo/docs/REPO_POLICIES.md"
echo "print()" > "$dir/repo/tool.py"
echo "export {}" > "$dir/repo/web.ts"
commit_and_push_fixture docs/REPO_POLICIES.md tool.py web.ts
remove_from_fixture REPO_POLICIES.md .gitignore .golangci.yml .gitea \
docs/API_POLICIES.md docs/CODE_STYLEGUIDE_GO.md \
docs/CODE_STYLEGUIDE_JS.md docs/CODE_STYLEGUIDE_PYTHON.md
run_commit_upstream_policy_files
expect_success
expect_same_as_canonical .gitignore
expect_same_as_canonical .golangci.yml
expect_same_as_canonical .gitea/workflows/check.yml
expect_file docs/REPO_POLICIES.md << 'EOF'
new policy
EOF
expect_absent REPO_POLICIES.md
expect_file docs/API_POLICIES.md << 'EOF'
new api policy
EOF
expect_absent API_POLICIES.md
expect_file docs/CODE_STYLEGUIDE_GO.md << 'EOF'
new CODE_STYLEGUIDE_GO
EOF
expect_file docs/CODE_STYLEGUIDE_JS.md << 'EOF'
new CODE_STYLEGUIDE_JS
EOF
expect_file docs/CODE_STYLEGUIDE_PYTHON.md << 'EOF'
new CODE_STYLEGUIDE_PYTHON
EOF
expect_new_commit_not_pushed
}
test_language_files_need_a_source_file() {
start_scenario "a repo with no source file of a language gets none of its files"
commit_and_push_fixture .prettierrc
remove_from_fixture cmd .golangci.yml docs/CODE_STYLEGUIDE_GO.md \
docs/GO_HTTP_SERVER_CONVENTIONS.md docs/CODE_STYLEGUIDE_JS.md \
docs/CODE_STYLEGUIDE_PYTHON.md
run_commit_upstream_policy_files
expect_success
expect_absent .golangci.yml
expect_absent docs/CODE_STYLEGUIDE_GO.md
expect_absent docs/GO_HTTP_SERVER_CONVENTIONS.md
expect_absent docs/CODE_STYLEGUIDE_JS.md
expect_absent docs/CODE_STYLEGUIDE_PYTHON.md
expect_new_commit_not_pushed
}
test_javascript_source_brings_its_styleguide() {
for extension in js mjs; do
start_scenario "a repo whose only JavaScript source is a .$extension file gets the JavaScript style guide"
echo "export {}" > "$dir/repo/web.$extension"
commit_and_push_fixture "web.$extension"
remove_from_fixture docs/CODE_STYLEGUIDE_JS.md
run_commit_upstream_policy_files
expect_success
expect_file docs/CODE_STYLEGUIDE_JS.md << 'EOF'
new CODE_STYLEGUIDE_JS
EOF
expect_new_commit_not_pushed
done
}
test_nothing_changed() {
start_scenario "nothing changed"
cp "$dir/canonical/.prettierrc" "$dir/repo/.prettierrc"
commit_and_push_fixture .prettierrc
run_commit_upstream_policy_files
expect_success
expect_output "nothing to commit"
expect_nothing_written
}
test_target_lacking_write_upstream_policy_files_gets_both_scripts() {
start_scenario "a repo lacking script/write-upstream-policy-files gets it, and the current script/commit-upstream-policy-files, in the commit"
rm "$dir/repo/script/write-upstream-policy-files"
echo "# An older version." >> "$dir/repo/script/commit-upstream-policy-files"
commit_and_push_fixture .prettierrc
run_commit_upstream_policy_files
expect_success
expect_same_as_canonical script/write-upstream-policy-files
expect_same_as_canonical script/commit-upstream-policy-files
expect_committed_executable script/write-upstream-policy-files
expect_committed_executable script/commit-upstream-policy-files
expect_new_commit_not_pushed
[ "$(files_in_commit)" = ".prettierrc script/commit-upstream-policy-files script/write-upstream-policy-files " ] ||
fail "the commit holds other files: $(files_in_commit)"
}
# The shell reads a script in blocks, so the padding makes it read the
# last line only after main has returned. It finds that line only if
# script/write-upstream-policy-files left the old file in place under a
# new name. The old file is an earlier canonical version, so
# script/write-upstream-policy-files replaces it.
test_commit_upstream_policy_files_replaces_itself() {
start_scenario "script/commit-upstream-policy-files replaces its own file and still exits 0"
{
cat "$dir/repo/script/commit-upstream-policy-files"
i=0
while [ "$i" -lt 2000 ]; do
echo "# Padding."
i=$((i + 1))
done
echo "echo 'the old file ran to its end'"
} > "$dir/merged"
cp "$dir/merged" "$dir/canonical/script/commit-upstream-policy-files"
commit_canonical
cp "$COMMIT_UPSTREAM_POLICY_FILES" \
"$dir/canonical/script/commit-upstream-policy-files"
commit_canonical
mv "$dir/merged" "$dir/repo/script/commit-upstream-policy-files"
chmod 755 "$dir/repo/script/commit-upstream-policy-files"
commit_and_push_fixture
run_commit_upstream_policy_files
expect_success
expect_output "the old file ran to its end"
expect_same_as_canonical script/commit-upstream-policy-files
expect_executable script/commit-upstream-policy-files
expect_new_commit_not_pushed
}
test_write_upstream_policy_files_with_path_commits_nothing() {
start_scenario "script/write-upstream-policy-files with a path writes into that clone and commits nothing"
rm "$dir/repo/script/write-upstream-policy-files" \
"$dir/repo/script/commit-upstream-policy-files"
commit_and_push_fixture .prettierrc
run_write_upstream_policy_files "$dir/repo"
expect_success
expect_file .prettierrc << 'EOF'
{ "tabWidth": 4 }
EOF
expect_same_as_canonical script/write-upstream-policy-files
expect_same_as_canonical script/commit-upstream-policy-files
expect_executable script/write-upstream-policy-files
expect_executable script/commit-upstream-policy-files
expect_no_commit
[ "$(head -n 1 "$dir/output")" = "$HASH" ] ||
fail "the first line of output is not the hash"
expect_output "script/write-upstream-policy-files"
[ -z "$(ls -A "$dir/tmp")" ] || fail "a temporary directory is left"
}
test_write_upstream_policy_files_without_script_directory() {
start_scenario "script/write-upstream-policy-files with a path writes both scripts into a clone with no script directory"
commit_and_push_fixture .prettierrc
remove_from_fixture script
run_write_upstream_policy_files "$dir/repo"
expect_success
expect_same_as_canonical script/write-upstream-policy-files
expect_same_as_canonical script/commit-upstream-policy-files
expect_executable script/write-upstream-policy-files
expect_executable script/commit-upstream-policy-files
expect_no_commit
}
test_write_upstream_policy_files_without_argument_updates_own_repo() {
start_scenario "script/write-upstream-policy-files with no argument updates the repo it sits in"
commit_and_push_fixture .prettierrc
status=0
(cd "$dir" && PATH="$dir/bin:$PATH" \
repo/script/write-upstream-policy-files) \
> "$dir/output" 2>&1 || status=$?
expect_success
expect_file .prettierrc << 'EOF'
{ "tabWidth": 4 }
EOF
expect_no_commit
}
test_write_upstream_policy_files_bad_target() {
start_scenario "script/write-upstream-policy-files refuses a path that is not the top of a clone"
commit_and_push_fixture .prettierrc
run_write_upstream_policy_files "$dir/repo/script"
expect_failure
expect_output "not the top of a git clone"
run_write_upstream_policy_files "$dir/bin"
expect_failure
expect_output "not the top of a git clone"
run_write_upstream_policy_files "$dir/no-such-directory"
expect_failure
expect_output "no such directory"
run_write_upstream_policy_files "$dir/repo" extra
expect_failure
expect_output "usage:"
expect_nothing_written
}
test_failed_fetch_stops() {
for url in \
"/api/v1/repos/sneak/prompts/branches/main" \
"/raw/branch/main/script/write-upstream-policy-files" \
"/compare/" \
"/raw/commit/"; do
start_scenario "a failed fetch of $url stops with nothing written"
commit_and_push_fixture .gitignore .prettierrc REPO_POLICIES.md
FAIL_URL="$url"
run_commit_upstream_policy_files
expect_failure
expect_output "cannot fetch"
expect_nothing_written
done
}
test_one_missing_file_stops_all() {
start_scenario "one file missing from prompts stops before any file is written"
rm "$dir/canonical/prompts/REPO_POLICIES.md"
commit_and_push_fixture .prettierrc REPO_POLICIES.md
run_commit_upstream_policy_files
expect_failure
expect_output "cannot fetch"
expect_nothing_written
}
test_branch_response_without_hash_stops() {
start_scenario "a branch response with no commit hash stops"
commit_and_push_fixture .prettierrc
BAD_BRANCH_JSON=yes
run_commit_upstream_policy_files
expect_failure
expect_output "no commit hash"
expect_nothing_written
}
# Each of these files, with the repo's own entries above the closing
# comment. The comment added with them must not be named.
test_own_entry_above_closing_comment() {
for file in .gitignore .dockerignore .editorconfig; do
start_scenario "own entries above the closing comment of $file stop"
{
printf '/myapp\n/.tool/\n\n# A comment of our own.\n'
cat "$dir/repo/$file"
} > "$dir/merged"
mv "$dir/merged" "$dir/repo/$file"
commit_and_push_fixture .gitignore .dockerignore .editorconfig \
.prettierrc REPO_POLICIES.md
run_commit_upstream_policy_files
expect_failure
expect_output "$file has entries"
expect_output "/myapp"
expect_output "/.tool/"
expect_output_without "A comment of our own."
expect_nothing_written
done
}
test_uncommitted_change_stops() {
start_scenario "a carried file with uncommitted changes stops"
commit_and_push_fixture .prettierrc REPO_POLICIES.md
echo "uncommitted" >> "$dir/repo/REPO_POLICIES.md"
run_commit_upstream_policy_files
expect_failure
expect_output "REPO_POLICIES.md has uncommitted changes"
expect_file REPO_POLICIES.md << 'EOF'
old policy
uncommitted
EOF
expect_no_commit
}
test_untracked_script_stops() {
start_scenario "an untracked script/write-upstream-policy-files is not overwritten"
rm "$dir/repo/script/write-upstream-policy-files"
commit_and_push_fixture .prettierrc
echo "our own script" > "$dir/repo/script/write-upstream-policy-files"
run_write_upstream_policy_files "$dir/repo"
expect_failure
expect_output "script/write-upstream-policy-files has uncommitted changes"
expect_file script/write-upstream-policy-files << 'EOF'
our own script
EOF
expect_no_commit
}
test_ignored_file_stops() {
start_scenario "an ignored file at a listed path is not overwritten"
commit_and_push_fixture .prettierrc
remove_from_fixture docs/API_POLICIES.md
echo "docs/API_POLICIES.md" >> "$dir/repo/.git/info/exclude"
echo "our own notes" > "$dir/repo/docs/API_POLICIES.md"
run_write_upstream_policy_files "$dir/repo"
expect_failure
expect_output "docs/API_POLICIES.md is ignored by git"
expect_file docs/API_POLICIES.md << 'EOF'
our own notes
EOF
expect_no_commit
}
test_own_script_stops() {
for script in script/write-upstream-policy-files \
script/commit-upstream-policy-files; do
start_scenario "a tracked $script with a line the canonical file has never held stops"
echo "echo our own script" >> "$dir/repo/$script"
commit_and_push_fixture .prettierrc
run_commit_upstream_policy_files
expect_failure
expect_output "$script has lines"
expect_output "echo our own script"
expect_nothing_written
done
}
test_gitignore_lacks_canonical_last_line() {
start_scenario ".gitignore lacking the canonical last line keeps the repo's own line below the canonical content"
printf '*.log\n\n# A comment of our own.\n/myapp\n' > "$dir/repo/.gitignore"
commit_and_push_fixture .gitignore .prettierrc
run_commit_upstream_policy_files
expect_success
expect_file .gitignore << 'EOF'
*.log
*.tmp
# Own entries go below this comment.
/myapp
EOF
expect_new_commit_not_pushed
}
test_dockerignore_lacks_canonical_last_line() {
start_scenario ".dockerignore lacking the canonical last line drops a line an earlier canonical commit held"
echo "**/*.log" > "$dir/repo/.dockerignore"
expect_former_canonical_line_replaced .dockerignore ".git"
expect_same_as_canonical .dockerignore
}
test_editorconfig_lacks_canonical_last_line() {
start_scenario ".editorconfig lacking the canonical last line with a line of its own stops"
printf 'root = true\n[*.py]\nindent_size = 2\n' > "$dir/repo/.editorconfig"
commit_and_push_fixture .editorconfig .prettierrc
run_commit_upstream_policy_files
expect_failure
expect_output ".editorconfig lacks this line"
expect_output "[*.py]"
expect_output "indent_size = 2"
expect_nothing_written
}
test_editorconfig_lacks_canonical_last_line_no_own_line() {
start_scenario ".editorconfig lacking the canonical last line with no line of its own is replaced"
printf 'root = true\n[*]\n' > "$dir/repo/.editorconfig"
expect_former_canonical_line_replaced .editorconfig "indent_size = 8"
expect_same_as_canonical .editorconfig
}
test_fetched_golangci_without_deny_list() {
start_scenario "a fetched .golangci.yml with no deny list stops"
cat > "$dir/canonical/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
files:
- "**/*.go"
other:
deny:
- pkg: example.com/other
EOF
commit_and_push_fixture .golangci.yml .prettierrc
run_commit_upstream_policy_files
expect_failure
expect_output "no deny list in its test-support rule"
expect_nothing_written
}
test_own_golangci_setting_stops() {
start_scenario "a .golangci.yml setting the canonical file lacks stops"
cat >> "$dir/repo/.golangci.yml" << 'EOF'
# A comment of our own.
forbidigo:
forbid:
- pattern: model.Operator
EOF
commit_and_push_fixture .golangci.yml .prettierrc
run_commit_upstream_policy_files
expect_failure
expect_output ".golangci.yml has lines"
expect_output "forbidigo:"
expect_output "- pattern: model.Operator"
expect_output_without "A comment of our own."
expect_nothing_written
}
test_source_repo_stops() {
start_scenario "the repo the policy files come from stops"
mkdir "$dir/repo/prompts"
echo "policy" > "$dir/repo/prompts/REPO_POLICIES.md"
commit_and_push_fixture .prettierrc prompts/REPO_POLICIES.md
run_commit_upstream_policy_files
expect_failure
expect_output "this repo is the source of the policy files"
expect_nothing_written
}
test_staged_file_stays_out_of_commit() {
start_scenario "a file staged before the script starts stays out of its commit"
commit_and_push_fixture .prettierrc
echo "notes" > "$dir/repo/notes.txt"
git -C "$dir/repo" add notes.txt
run_commit_upstream_policy_files
expect_success
[ "$(files_in_commit)" = ".prettierrc " ] ||
fail "the commit holds more than the policy file"
[ "$(git -C "$dir/repo" diff --cached --name-only)" = "notes.txt" ] ||
fail "notes.txt is no longer staged"
}
test_commit_upstream_policy_files_takes_no_argument() {
start_scenario "script/commit-upstream-policy-files refuses an argument"
commit_and_push_fixture .prettierrc
run_commit_upstream_policy_files "$HASH"
expect_failure
expect_output "usage:"
expect_nothing_written
}
# expect_former_canonical_line_replaced <file> <line>: an earlier
# canonical commit held the line and the newest does not. This repo's
# file still has it, and the script replaces it.
expect_former_canonical_line_replaced() {
cp "$dir/canonical/$1" "$dir/newest"
{ echo "$2"; cat "$dir/newest"; } > "$dir/canonical/$1"
commit_canonical
cp "$dir/newest" "$dir/canonical/$1"
commit_canonical
{ echo "$2"; cat "$dir/repo/$1"; } > "$dir/merged"
mv "$dir/merged" "$dir/repo/$1"
commit_and_push_fixture "$1" .prettierrc
run_commit_upstream_policy_files
expect_success
if grep -q -F -x -e "$2" "$dir/repo/$1"; then
fail "$1 still has: $2"
fi
expect_new_commit_not_pushed
}
test_former_canonical_golangci_line_replaced() {
start_scenario "a .golangci.yml line an earlier canonical commit held is replaced"
expect_former_canonical_line_replaced .golangci.yml "version: 1"
}
test_former_canonical_gitignore_line_replaced() {
start_scenario "a .gitignore line above the closing comment that an earlier canonical commit held is replaced"
expect_former_canonical_line_replaced .gitignore "*.old"
}
test_former_canonical_script_line_replaced() {
start_scenario "a script/write-upstream-policy-files line an earlier canonical commit held is replaced"
expect_former_canonical_line_replaced \
script/write-upstream-policy-files "echo an older version"
expect_same_as_canonical script/write-upstream-policy-files
}
# A line another file's history removed does not count as held by this
# one.
test_line_removed_from_another_file_still_stops() {
start_scenario "a line only another canonical file once held stops"
{ echo "*.old"; cat "$dir/canonical/.dockerignore"; } > "$dir/merged"
cp "$dir/merged" "$dir/canonical/.dockerignore"
commit_canonical
tail -n +2 "$dir/merged" > "$dir/canonical/.dockerignore"
commit_canonical
{ echo "*.old"; cat "$dir/repo/.gitignore"; } > "$dir/merged"
mv "$dir/merged" "$dir/repo/.gitignore"
commit_and_push_fixture .gitignore .prettierrc
run_commit_upstream_policy_files
expect_failure
expect_output ".gitignore has entries"
expect_output "*.old"
expect_nothing_written
}
main() {
test_own_entries_kept
test_files_the_repo_lacks_are_written_whole
test_language_files_need_a_source_file
test_javascript_source_brings_its_styleguide
test_nothing_changed
test_target_lacking_write_upstream_policy_files_gets_both_scripts
test_commit_upstream_policy_files_replaces_itself
test_write_upstream_policy_files_with_path_commits_nothing
test_write_upstream_policy_files_without_script_directory
test_write_upstream_policy_files_without_argument_updates_own_repo
test_write_upstream_policy_files_bad_target
test_failed_fetch_stops
test_one_missing_file_stops_all
test_branch_response_without_hash_stops
test_own_entry_above_closing_comment
test_uncommitted_change_stops
test_untracked_script_stops
test_ignored_file_stops
test_own_script_stops
test_gitignore_lacks_canonical_last_line
test_dockerignore_lacks_canonical_last_line
test_editorconfig_lacks_canonical_last_line
test_editorconfig_lacks_canonical_last_line_no_own_line
test_fetched_golangci_without_deny_list
test_own_golangci_setting_stops
test_source_repo_stops
test_staged_file_stays_out_of_commit
test_commit_upstream_policy_files_takes_no_argument
test_former_canonical_golangci_line_replaced
test_former_canonical_gitignore_line_replaced
test_former_canonical_script_line_replaced
test_line_removed_from_another_file_still_stops
echo "commit-upstream-policy-files tests passed"
}
main "$@"
+567
View File
@@ -0,0 +1,567 @@
#!/bin/sh
# test/update-policy.sh: test script/update-policy on throwaway repos.
# Each scenario gets one temp directory holding a repo, its local bare
# origin, a local git repository of the canonical files in place of
# prompts, and a stub curl that serves them, so nothing touches the
# network.
set -eu
UPDATE_POLICY="$(cd "$(dirname "$0")/.." && pwd -P)/script/update-policy"
dir=""
trap 'rm -rf "$dir"' EXIT
fail() {
echo "FAIL: $scenario: $*" >&2
cat "$dir/output" >&2
exit 1
}
write_stub_curl() {
mkdir "$dir/bin"
cat > "$dir/bin/curl" << 'EOF'
#!/bin/sh
previous=""
fail_flag=""
for argument in "$@"; do
[ "$previous" = "--output" ] && output="$argument"
[ "$argument" = "--fail" ] && fail_flag=yes
previous="$argument"
done
url="$previous"
base="https://git.eeqj.de/sneak/prompts/raw/commit/$HASH/"
path="${url#"$base"}"
source="$(dirname "$0")/../canonical/$path"
if [ "$path" = "$url" ] || [ ! -f "$source" ]; then
[ -n "$fail_flag" ] && exit 22
echo "404 page not found" > "$output"
exit 0
fi
cp "$source" "$output"
EOF
chmod +x "$dir/bin/curl"
}
write_canonical_files() {
mkdir -p "$dir/canonical/prompts"
cat > "$dir/canonical/.gitignore" << 'EOF'
*.log
*.tmp
# Own entries go below this comment.
EOF
cat > "$dir/canonical/.dockerignore" << 'EOF'
**/*.log
**/*.tmp
# Own entries go below this comment.
EOF
cat > "$dir/canonical/.editorconfig" << 'EOF'
root = true
[*]
indent_size = 4
# Own sections go below this comment.
EOF
cat > "$dir/canonical/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
- pkg: net/http/cgi
desc: added canonically
other:
deny:
- pkg: example.com/other
EOF
echo '{ "tabWidth": 4 }' > "$dir/canonical/.prettierrc"
echo "new policy" > "$dir/canonical/prompts/REPO_POLICIES.md"
echo "new api policy" > "$dir/canonical/prompts/API_POLICIES.md"
}
# commit_canonical: commit the canonical files as they stand. The stub
# curl serves only the newest commit; every other commit gets a 404.
commit_canonical() {
git -C "$dir/canonical" add .gitignore .dockerignore .editorconfig \
.golangci.yml .prettierrc prompts
git -C "$dir/canonical" commit -q -m "Canonical"
HASH="$(git -C "$dir/canonical" rev-parse HEAD)"
}
# write_outdated_files: this repo's files, one canonical version behind,
# with the repo's own entries in the places the script keeps them. The
# comment above the closing comment in .gitignore is replaced, not kept.
write_outdated_files() {
cat > "$dir/repo/.gitignore" << 'EOF'
*.log
# An outdated comment.
# Own entries go below this comment.
/myapp
EOF
cat > "$dir/repo/.dockerignore" << 'EOF'
**/*.log
# Own entries go below this comment.
/myapp
EOF
cat > "$dir/repo/.editorconfig" << 'EOF'
root = true
[*]
# Own sections go below this comment.
[*.py]
indent_size = 2
EOF
cat > "$dir/repo/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
# Our own test helpers.
- pkg: example.com/app/internal/apptest
desc: own entry
other:
deny:
- pkg: example.com/other
EOF
echo '{ "tabWidth": 2 }' > "$dir/repo/.prettierrc"
echo "old policy" > "$dir/repo/REPO_POLICIES.md"
}
# start_scenario <name>: make a new temp directory holding a repo with
# the outdated files, not yet committed, and an empty origin.
start_scenario() {
scenario="$1"
rm -rf "$dir"
dir="$(mktemp -d)"
: > "$dir/output"
write_stub_curl
write_canonical_files
# git clone reads no repo's own config, so the setting that points
# git at the local canonical repository has to be in this file.
export GIT_CONFIG_GLOBAL="$dir/gitconfig"
git config --global user.name "Test"
git config --global user.email "test@example.com"
git config --global "url.$dir/canonical.insteadOf" \
"https://git.eeqj.de/sneak/prompts.git"
git init -q -b main "$dir/canonical"
export HASH
commit_canonical
git init -q --bare -b main "$dir/origin.git"
git init -q -b main "$dir/repo"
git -C "$dir/repo" remote add origin "$dir/origin.git"
mkdir "$dir/repo/script"
cp "$UPDATE_POLICY" "$dir/repo/script/update-policy"
printf '#!/bin/sh\necho example\n' > "$dir/repo/script/projectname"
chmod +x "$dir/repo/script/projectname"
write_outdated_files
}
# commit_and_push_fixture <paths...>: commit those paths, remove the
# rest of the outdated files, and record the commit as $before.
commit_and_push_fixture() {
(
cd "$dir/repo"
git add script "$@"
git commit -q -m "Fixture"
git push -q origin HEAD
git clean -q -f -x
)
before="$(git -C "$dir/repo" rev-parse HEAD)"
}
run_update_policy() {
status=0
(cd "$dir/repo" && PATH="$dir/bin:$PATH" script/update-policy "$@") \
> "$dir/output" 2>&1 || status=$?
}
reject_pushes() {
printf '#!/bin/sh\nexit 1\n' > "$dir/origin.git/hooks/pre-receive"
chmod +x "$dir/origin.git/hooks/pre-receive"
}
accept_pushes() {
rm "$dir/origin.git/hooks/pre-receive"
}
head_of_repo() {
git -C "$dir/repo" rev-parse HEAD
}
head_of_origin() {
git -C "$dir/origin.git" rev-parse refs/heads/main
}
expect_success() {
[ "$status" -eq 0 ] || fail "exited $status"
}
expect_failure() {
[ "$status" -ne 0 ] || fail "exited 0"
}
expect_output() {
grep -q -F -e "$1" "$dir/output" || fail "output lacks: $1"
}
expect_output_without() {
if grep -q -F -e "$1" "$dir/output"; then
fail "output has: $1"
fi
}
# expect_file <path>: the file must equal standard input.
expect_file() {
cat > "$dir/expected"
diff "$dir/expected" "$dir/repo/$1" >&2 || fail "$1 is wrong"
}
expect_absent() {
[ ! -e "$dir/repo/$1" ] || fail "$1 exists"
}
expect_nothing_written() {
[ -z "$(git -C "$dir/repo" status --porcelain)" ] ||
fail "the working tree changed"
[ "$(head_of_repo)" = "$before" ] || fail "the repo has a new commit"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
}
test_own_entries_kept() {
start_scenario "own entries kept in all four files"
commit_and_push_fixture .gitignore .dockerignore .editorconfig \
.golangci.yml .prettierrc REPO_POLICIES.md
run_update_policy "$HASH"
expect_success
expect_file .gitignore << 'EOF'
*.log
*.tmp
# Own entries go below this comment.
/myapp
EOF
expect_file .dockerignore << 'EOF'
**/*.log
**/*.tmp
# Own entries go below this comment.
/myapp
EOF
expect_file .editorconfig << 'EOF'
root = true
[*]
indent_size = 4
# Own sections go below this comment.
[*.py]
indent_size = 2
EOF
expect_file .golangci.yml << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
- pkg: net/http/cgi
desc: added canonically
# Our own test helpers.
- pkg: example.com/app/internal/apptest
desc: own entry
other:
deny:
- pkg: example.com/other
EOF
expect_file .prettierrc << 'EOF'
{ "tabWidth": 4 }
EOF
expect_file REPO_POLICIES.md << 'EOF'
new policy
EOF
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
[ "$(head_of_repo)" != "$before" ] || fail "no commit was made"
git -C "$dir/repo" log -1 --format=%s | grep -q -F -e "$HASH" ||
fail "the commit message does not name the hash"
}
test_files_not_carried_are_skipped() {
start_scenario "files the repo does not carry skipped"
mkdir "$dir/repo/docs"
mv "$dir/repo/REPO_POLICIES.md" "$dir/repo/docs/REPO_POLICIES.md"
commit_and_push_fixture docs/REPO_POLICIES.md
run_update_policy "$HASH"
expect_success
expect_file docs/REPO_POLICIES.md << 'EOF'
new policy
EOF
expect_absent REPO_POLICIES.md
expect_absent API_POLICIES.md
expect_absent docs/API_POLICIES.md
expect_absent .gitignore
expect_absent .dockerignore
expect_absent .editorconfig
expect_absent .golangci.yml
expect_absent .prettierrc
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
}
test_nothing_changed() {
start_scenario "nothing changed"
cp "$dir/canonical/.prettierrc" "$dir/repo/.prettierrc"
commit_and_push_fixture .prettierrc
run_update_policy "$HASH"
expect_success
expect_output "nothing to commit"
expect_nothing_written
}
test_bad_commit_hash() {
for hash in not-a-hash 0000000000000000000000000000000000000000; do
start_scenario "bad commit hash $hash stops with nothing written"
commit_and_push_fixture .gitignore .prettierrc REPO_POLICIES.md
run_update_policy "$hash"
expect_failure
expect_nothing_written
done
# The last hash has the right form, so it is the one that reaches curl.
expect_output "cannot fetch"
}
test_push_failure() {
start_scenario "push failure exits non-zero"
commit_and_push_fixture .prettierrc
reject_pushes
run_update_policy "$HASH"
expect_failure
expect_output "push failed"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
}
# Each of these files, with the repo's own entries above the closing
# comment. The comment added with them must not be named.
test_own_entry_above_closing_comment() {
for file in .gitignore .dockerignore .editorconfig; do
start_scenario "own entries above the closing comment of $file stop"
{
printf '/myapp\n/.tool/\n\n# A comment of our own.\n'
cat "$dir/repo/$file"
} > "$dir/merged"
mv "$dir/merged" "$dir/repo/$file"
commit_and_push_fixture .gitignore .dockerignore .editorconfig \
.prettierrc REPO_POLICIES.md
run_update_policy "$HASH"
expect_failure
expect_output "$file has entries"
expect_output "/myapp"
expect_output "/.tool/"
expect_output_without "A comment of our own."
expect_nothing_written
done
}
test_retry_after_failed_push() {
start_scenario "a retry after a failed push delivers the commit"
commit_and_push_fixture .prettierrc
reject_pushes
run_update_policy "$HASH"
expect_failure
committed="$(head_of_repo)"
[ "$committed" != "$before" ] || fail "no commit was made"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
accept_pushes
run_update_policy "$HASH"
expect_success
[ "$(head_of_repo)" = "$committed" ] || fail "the retry made a new commit"
[ "$(head_of_origin)" = "$committed" ] ||
fail "the retry did not deliver the commit"
}
test_uncommitted_change_stops() {
start_scenario "a carried file with uncommitted changes stops"
commit_and_push_fixture .prettierrc REPO_POLICIES.md
echo "uncommitted" >> "$dir/repo/REPO_POLICIES.md"
run_update_policy "$HASH"
expect_failure
expect_output "REPO_POLICIES.md has uncommitted changes"
expect_file REPO_POLICIES.md << 'EOF'
old policy
uncommitted
EOF
[ "$(head_of_repo)" = "$before" ] || fail "the repo has a new commit"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
}
test_gitignore_lacks_canonical_last_line() {
start_scenario ".gitignore lacking the canonical last line stops"
printf '*.log\n/myapp\n' > "$dir/repo/.gitignore"
commit_and_push_fixture .gitignore .prettierrc
run_update_policy "$HASH"
expect_failure
expect_output ".gitignore lacks this line"
expect_nothing_written
}
test_fetched_golangci_without_deny_list() {
start_scenario "a fetched .golangci.yml with no deny list stops"
cat > "$dir/canonical/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
files:
- "**/*.go"
other:
deny:
- pkg: example.com/other
EOF
commit_and_push_fixture .golangci.yml .prettierrc
run_update_policy "$HASH"
expect_failure
expect_output "no deny list in its test-support rule"
expect_nothing_written
}
test_own_golangci_setting_stops() {
start_scenario "a .golangci.yml setting the canonical file lacks stops"
cat >> "$dir/repo/.golangci.yml" << 'EOF'
# A comment of our own.
forbidigo:
forbid:
- pattern: model.Operator
EOF
commit_and_push_fixture .golangci.yml .prettierrc
run_update_policy "$HASH"
expect_failure
expect_output ".golangci.yml has lines"
expect_output "forbidigo:"
expect_output "- pattern: model.Operator"
expect_output_without "A comment of our own."
expect_nothing_written
}
test_source_repo_stops() {
start_scenario "the repo the policy files come from stops"
printf '#!/bin/sh\necho prompts\n' > "$dir/repo/script/projectname"
commit_and_push_fixture .prettierrc REPO_POLICIES.md
run_update_policy "$HASH"
expect_failure
expect_output "this repo is the source of the policy files"
expect_nothing_written
}
test_staged_file_stays_out_of_commit() {
start_scenario "a file staged before the script starts stays out of its commit"
commit_and_push_fixture .prettierrc
echo "notes" > "$dir/repo/notes.txt"
git -C "$dir/repo" add notes.txt
run_update_policy "$HASH"
expect_success
[ "$(git -C "$dir/repo" show --name-only --format= HEAD)" = ".prettierrc" ] ||
fail "the commit holds more than the policy file"
[ "$(git -C "$dir/repo" diff --cached --name-only)" = "notes.txt" ] ||
fail "notes.txt is no longer staged"
}
test_short_commit_hash_refused() {
start_scenario "a hexadecimal hash shorter than 40 characters is refused"
commit_and_push_fixture .prettierrc
run_update_policy "${HASH%?}"
expect_failure
expect_output "not a full commit hash"
expect_nothing_written
}
# git asks the local canonical repository for the head of main, and the
# stub curl serves only that commit.
test_no_hash_uses_head_of_main() {
start_scenario "with no hash the script uses the head of main"
commit_and_push_fixture .prettierrc
run_update_policy
expect_success
expect_file .prettierrc << 'EOF'
{ "tabWidth": 4 }
EOF
git -C "$dir/repo" log -1 --format=%s | grep -q -F -e "$HASH" ||
fail "the commit message does not name the head of main"
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
}
# expect_former_canonical_line_replaced <file> <line>: an earlier
# canonical commit held the line and the newest does not. This repo's
# file still has it, and the script replaces it and pushes.
expect_former_canonical_line_replaced() {
cp "$dir/canonical/$1" "$dir/newest"
{ echo "$2"; cat "$dir/newest"; } > "$dir/canonical/$1"
commit_canonical
cp "$dir/newest" "$dir/canonical/$1"
commit_canonical
{ echo "$2"; cat "$dir/repo/$1"; } > "$dir/merged"
mv "$dir/merged" "$dir/repo/$1"
commit_and_push_fixture "$1" .prettierrc
run_update_policy "$HASH"
expect_success
if grep -q -F -x -e "$2" "$dir/repo/$1"; then
fail "$1 still has: $2"
fi
[ "$(head_of_repo)" != "$before" ] || fail "no commit was made"
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
}
test_former_canonical_golangci_line_replaced() {
start_scenario "a .golangci.yml line an earlier canonical commit held is replaced"
expect_former_canonical_line_replaced .golangci.yml "version: 1"
}
test_former_canonical_gitignore_line_replaced() {
start_scenario "a .gitignore line above the closing comment that an earlier canonical commit held is replaced"
expect_former_canonical_line_replaced .gitignore "*.old"
}
main() {
test_own_entries_kept
test_files_not_carried_are_skipped
test_nothing_changed
test_bad_commit_hash
test_push_failure
test_own_entry_above_closing_comment
test_retry_after_failed_push
test_uncommitted_change_stops
test_gitignore_lacks_canonical_last_line
test_fetched_golangci_without_deny_list
test_own_golangci_setting_stops
test_source_repo_stops
test_staged_file_stays_out_of_commit
test_short_commit_hash_refused
test_no_hash_uses_head_of_main
test_former_canonical_golangci_line_replaced
test_former_canonical_gitignore_line_replaced
echo "update-policy tests passed"
}
main "$@"