sneak/quak
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

README: state the container-lint claim as what is actually true
All checks were successful
check / check (push) Successful in 1m14s
Details

Browse Source 
The Linting section this PR adds claimed "There is no host lint path" and
then, two paragraphs later, documented script/fmt-check as a host-side
formatting check. Both cannot be true, and the absolute one is the false one.

What is true is narrower: no lint path reachable from script/check or
script/precommit runs on the host, so every lint verdict those two produce
comes from the container. script/fmt-check stays as a standalone entrypoint,
now stated as the one host formatting path with nothing reaching it. The
"exactly one place" and "in the container only" phrasings elsewhere are
qualified the same way.
This commit is contained in:
user
2026-09-04 11:27:49 +00:00
parent 956870889f
commit bd88eced84
1 changed files with 20 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@@ -108,11 +108,14 @@ alpine. We provide:
### Linting ### Linting
Linting runs in a container, one way, everywhere. `script/lint` builds Linting runs in a container, one way, in every path that produces a lint verdict
`Dockerfile.lint`, which copies the repo into a digest-pinned node image and for `make check` or the pre-commit hook. `script/lint` builds `Dockerfile.lint`,
runs eslint and prettier as build steps, so a successful build is a clean lint. which copies the repo into a digest-pinned node image and runs eslint and
There is no host lint path: docker is required to lint, and that also works prettier as build steps, so a successful build is a clean lint. No lint path
where the docker daemon is remote and bind mounts are impossible. reachable from `script/check` or `script/precommit` runs on the host: every lint
verdict those two produce comes from the container. Docker is therefore required
to lint, and the container route also works where the docker daemon is remote
and bind mounts are impossible.
The formatting check is part of that, not a step beside it. `script/check` and The formatting check is part of that, not a step beside it. `script/check` and
`script/precommit` therefore call `script/lint` and stop; neither calls `script/precommit` therefore call `script/lint` and stop; neither calls
@@ -124,15 +127,17 @@ in each. `test/packaging/lint-once.test.ts` asserts that count by walking the
invocation graph, so a second pass cannot creep back in unnoticed. invocation graph, so a second pass cannot creep back in unnoticed.
`script/fmt-check` remains as a standalone entrypoint for asking the formatting `script/fmt-check` remains as a standalone entrypoint for asking the formatting
question on its own, without docker and without the rest of lint. Its verdict question on its own, without docker and without the rest of lint. It is the one
cannot drift from the container's: prettier is pinned to an exact version, formatting path that still runs on the host, and nothing reaches it: neither
installed from `yarn.lock` under `--frozen-lockfile` in both places, and reads `script/check` nor `script/precommit` calls it, so it never contributes to their
`.gitignore` as its default ignore file — which is why `.dockerignore` verdicts. Its own verdict cannot drift from the container's: prettier is pinned
deliberately keeps `.gitignore` in the build context. to an exact version, installed from `yarn.lock` under `--frozen-lockfile` in
both places, and reads `.gitignore` as its default ignore file — which is why
`.dockerignore` deliberately keeps `.gitignore` in the build context.
Lint happens in exactly one place, which constrains the rest of the build. Lint happens in exactly one place in that graph, which constrains the rest of
`script/check` calls `script/lint`, so `make check` cannot run inside a the build. `script/check` calls `script/lint`, so `make check` cannot run inside
container without asking for docker inside docker. The image built from a container without asking for docker inside docker. The image built from
`Dockerfile` therefore runs `make test` and `make build` and does not lint; `Dockerfile` therefore runs `make test` and `make build` and does not lint;
`script/cibuild` builds `Dockerfile.lint` first and that image second, so CI `script/cibuild` builds `Dockerfile.lint` first and that image second, so CI
gets both verdicts. gets both verdicts.
@@ -526,8 +531,8 @@ documents:
runs the tests) must pass before merging to `main`. `make fmt-check` is runs the tests) must pass before merging to `main`. `make fmt-check` is
available for a host-side formatting check on its own, but it is not a available for a host-side formatting check on its own, but it is not a
separate requirement: `make lint` already covers it, and running both would separate requirement: `make lint` already covers it, and running both would
check formatting twice. Never invoke eslint or prettier directly; linting runs check formatting twice. Never invoke eslint or prettier directly; every lint
in the container only. verdict `make check` and the pre-commit hook produce comes from the container.
- **Formatting:** prettier with 4-space indents and `proseWrap: always` for - **Formatting:** prettier with 4-space indents and `proseWrap: always` for
markdown. Use `make fmt` to format. Use `yarn` not `npm`. markdown. Use `make fmt` to format. Use `yarn` not `npm`.