sneak/pixa
1
0
Fork 0
Code Issues 20 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

Markdown is never formatted: script/fmt covers only Go, and no prettier config exists #100

New Issue
Closed
opened 2026-08-09 07:04:41 +02:00 by clawbot · 3 comments
clawbot commented 2026-08-09 07:04:41 +02:00
Collaborator
Copy Link
Copy Source

From the audit against the canonical REPO_POLICIES.md, verified against main at 61f42e6.

The policy states:

> Use platform-standard formatters: black for Python, prettier for JS/CSS/Markdown/HTML, go fmt for Go. Always use default configuration with two exceptions: four-space indents (except Go), and proseWrap: always for Markdown (hard-wrap at 80 columns).

script/fmt:11 runs gofmt -w over Go files and script/fmt-check:11 runs gofmt -l . — Go only. There is no .prettierrc or .prettierignore in the repo. The markdown demonstrably is not prettier output: README.md prose is hard-wrapped at roughly 66-70 columns (e.g. lines 3-8) where proseWrap: always at prettier's default printWidth: 80 would reflow to ~78; TODO.md maxes at 72.

Practical consequence: markdown formatting is currently whatever each author happened to do, and make check cannot catch drift. The repo also serves HTML templates (internal/templates/*.html) which are likewise unformatted and unchecked.

Stated honestly — partly ambiguous. The same policy scopes the config files narrowly ("Documentation and writing repos (Markdown, HTML, CSS) should also have .prettierrc and .prettierignore") and lists only go.mod, go.sum, .golangci.yml as the Go-repo minimum. So whether a Go repo must carry prettier config is genuinely unclear. That markdown should be prettier-formatted with proseWrap: always is not ambiguous. Filing at low severity; close as wontfix if the narrow reading is intended.

Definition of done

  1. .prettierrc (four-space tabs, proseWrap: always) and .prettierignore added.
  2. .prettierignore must exclude REPO_POLICIES.md — it is currently byte-identical to canonical (sha256 117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775) and reformatting it would break that property, which is the whole point of vendoring it verbatim. Same for CONVENTIONS.md if it survives #97.
  3. script/fmt and script/fmt-check extended to run prettier over *.md (and decide whether to include the HTML templates — Go template syntax and prettier do not always agree, so verify rather than assume).
  4. The resulting reflow committed as a standalone formatting-only commit, per EXISTING_REPO_CHECKLIST.md: "Formatting diffs can be large and should not be mixed with functional changes."
  5. make check green, and running make fmt twice is idempotent.

Coordination

The reflow touches README.md and TODO.md, both modified by both open PRs. Do last, after #55 and #54 have merged — a repo-wide markdown reflow landing before them would conflict with everything.

From the audit against the canonical `REPO_POLICIES.md`, verified against `main` at `61f42e6`. The policy states: > Use platform-standard formatters: `black` for Python, `prettier` for JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with two exceptions: four-space indents (except Go), and `proseWrap: always` for Markdown (hard-wrap at 80 columns). `script/fmt:11` runs `gofmt -w` over Go files and `script/fmt-check:11` runs `gofmt -l .` — Go only. There is no `.prettierrc` or `.prettierignore` in the repo. The markdown demonstrably is not prettier output: `README.md` prose is hard-wrapped at roughly 66-70 columns (e.g. lines 3-8) where `proseWrap: always` at prettier's default `printWidth: 80` would reflow to ~78; `TODO.md` maxes at 72. Practical consequence: markdown formatting is currently whatever each author happened to do, and `make check` cannot catch drift. The repo also serves HTML templates (`internal/templates/*.html`) which are likewise unformatted and unchecked. **Stated honestly — partly ambiguous.** The same policy scopes the config files narrowly ("Documentation and writing repos (Markdown, HTML, CSS) should also have `.prettierrc` and `.prettierignore`") and lists only `go.mod`, `go.sum`, `.golangci.yml` as the Go-repo minimum. So whether a **Go** repo must carry prettier config is genuinely unclear. That markdown should be prettier-formatted with `proseWrap: always` is not ambiguous. Filing at low severity; close as wontfix if the narrow reading is intended. ## Definition of done 1. `.prettierrc` (four-space tabs, `proseWrap: always`) and `.prettierignore` added. 2. `.prettierignore` **must** exclude `REPO_POLICIES.md` — it is currently byte-identical to canonical (sha256 `117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775`) and reformatting it would break that property, which is the whole point of vendoring it verbatim. Same for `CONVENTIONS.md` if it survives #97. 3. `script/fmt` and `script/fmt-check` extended to run prettier over `*.md` (and decide whether to include the HTML templates — Go template syntax and prettier do not always agree, so verify rather than assume). 4. The resulting reflow committed as a **standalone formatting-only commit**, per `EXISTING_REPO_CHECKLIST.md`: "Formatting diffs can be large and should not be mixed with functional changes." 5. `make check` green, and running `make fmt` twice is idempotent. ## Coordination The reflow touches `README.md` and `TODO.md`, both modified by both open PRs. Do **last**, after #55 and #54 have merged — a repo-wide markdown reflow landing before them would conflict with everything.
clawbot added this to the 1.0.0 milestone 2026-08-09 07:04:41 +02:00
clawbot commented 2026-10-04 19:26:29 +02:00
Author
Collaborator
Copy Link
Copy Source

Plan, checked against next at 233a9c0. The issue's open question (must a Go repo carry prettier?) is settled by the owner's standing rule that all his repos format markdown with prettier, four-space tabs and proseWrap: always. sneak/upaas already does this for a Go repo; follow its pattern rather than inventing one.

  • .prettierrc identical to sneak/prompts' (tabWidth 4, proseWrap always) and a .prettierignore that keeps prettier off REPO_POLICIES.md (vendored byte-for-byte), CONVENTIONS.md (until #97 decides its fate), vendor/, and anything generated.
  • prettier pinned in package.json with a yarn.lock, and Node and Yarn installed by script/bootstrap at pinned versions verified by hash, the way sneak/upaas does it (read its script/bootstrap, script/fmt and script/fmt-check). script/fmt and script/fmt-check run prettier on *.md after the Go formatters. HTML templates stay out unless prettier leaves the Go template syntax intact (check, and say which in the PR).
  • The Dockerfile lint stage gets what script/bootstrap now installs, so make fmt-check in the build checks the markdown.
  • Commits: first the tooling, then one formatting-only commit that reflows the markdown (EXISTING_REPO_CHECKLIST.md: formatting diffs are not mixed with other changes). make fmt run twice changes nothing the second time.
  • Keep the build lean: note in the PR how much the lint image and the gate time grew.

Model: opus-5-5

Plan, checked against `next` at `233a9c0`. The issue's open question (must a Go repo carry prettier?) is settled by the owner's standing rule that all his repos format markdown with prettier, four-space tabs and `proseWrap: always`. `sneak/upaas` already does this for a Go repo; follow its pattern rather than inventing one. - `.prettierrc` identical to `sneak/prompts`' (`tabWidth` 4, `proseWrap` always) and a `.prettierignore` that keeps prettier off `REPO_POLICIES.md` (vendored byte-for-byte), `CONVENTIONS.md` (until https://git.eeqj.de/sneak/pixa/issues/97 decides its fate), `vendor/`, and anything generated. - prettier pinned in `package.json` with a `yarn.lock`, and Node and Yarn installed by `script/bootstrap` at pinned versions verified by hash, the way `sneak/upaas` does it (read its `script/bootstrap`, `script/fmt` and `script/fmt-check`). `script/fmt` and `script/fmt-check` run prettier on `*.md` after the Go formatters. HTML templates stay out unless prettier leaves the Go template syntax intact (check, and say which in the PR). - The `Dockerfile` lint stage gets what `script/bootstrap` now installs, so `make fmt-check` in the build checks the markdown. - Commits: first the tooling, then one formatting-only commit that reflows the markdown (`EXISTING_REPO_CHECKLIST.md`: formatting diffs are not mixed with other changes). `make fmt` run twice changes nothing the second time. - Keep the build lean: note in the PR how much the lint image and the gate time grew. Model: opus-5-5
clawbot commented 2026-10-05 03:42:27 +02:00
Author
Collaborator
Copy Link
Copy Source

Updated plan, replacing #100 (comment), now that #202 has landed (canonical scripts; the format check runs on the host in script/check; script/fmt and script/fmt-check were kept as gofmt-only because pixa had no Node).

  • .prettierrc identical to sneak/prompts' and a .prettierignore keeping prettier off REPO_POLICIES.md (vendored byte for byte), vendor/ and anything generated.
  • package.json and yarn.lock pinning prettier as sneak/prompts does (prettier 3.8.1 at the time of writing), and script/bootstrap gaining the Node, nvm and Yarn part of the canonical script/bootstrap (pinned versions, hash-verified nvm, never curl | sh), copied as it is there.
  • script/fmt and script/fmt-check run gofmt as now, then prettier on **/*.md exactly as the canonical ones do (same run_yarn and arguments). Say in the PR how they differ from canonical (only the added gofmt step).
  • One formatting-only commit after the tooling that reflows the markdown; make fmt run twice changes nothing the second time.
  • WARNING for whoever does this on the shared host: do not let script/bootstrap install Yarn or anything else globally into the host's shared Node (~/.nvm), nor packages into the shared nix profile. Check what bootstrap would do first; run it, script/fmt and script/fmt-check inside a container (for example the Docker test phase image or a plain Debian image) where installs are throwaway, and remove the container. If the canonical bootstrap cannot avoid a global install on a host that already has Node, say so on this issue.

Model: opus-5-5

Updated plan, replacing https://git.eeqj.de/sneak/pixa/issues/100#issuecomment-124919, now that https://git.eeqj.de/sneak/pixa/issues/202 has landed (canonical scripts; the format check runs on the host in `script/check`; `script/fmt` and `script/fmt-check` were kept as `gofmt`-only because pixa had no Node). - `.prettierrc` identical to `sneak/prompts`' and a `.prettierignore` keeping prettier off `REPO_POLICIES.md` (vendored byte for byte), `vendor/` and anything generated. - `package.json` and `yarn.lock` pinning prettier as `sneak/prompts` does (`prettier` 3.8.1 at the time of writing), and `script/bootstrap` gaining the Node, nvm and Yarn part of the canonical `script/bootstrap` (pinned versions, hash-verified nvm, never `curl | sh`), copied as it is there. - `script/fmt` and `script/fmt-check` run `gofmt` as now, then prettier on `**/*.md` exactly as the canonical ones do (same `run_yarn` and arguments). Say in the PR how they differ from canonical (only the added `gofmt` step). - One formatting-only commit after the tooling that reflows the markdown; `make fmt` run twice changes nothing the second time. - WARNING for whoever does this on the shared host: do not let `script/bootstrap` install Yarn or anything else globally into the host's shared Node (`~/.nvm`), nor packages into the shared nix profile. Check what bootstrap would do first; run it, `script/fmt` and `script/fmt-check` inside a container (for example the Docker `test` phase image or a plain Debian image) where installs are throwaway, and remove the container. If the canonical bootstrap cannot avoid a global install on a host that already has Node, say so on this issue. Model: opus-5-5
clawbot commented 2026-10-05 04:04:19 +02:00
Author
Collaborator
Copy Link
Copy Source

Implemented in #219.

As the plan asked: on a host that has Node but no Yarn, the bootstrap copied from sneak/prompts installs Yarn globally into that Node (corepack enable, or npm install -g), and nothing in it avoids that. On this shared host both are already installed, so it installs only prettier, into the clone.

Model: opus-5-5

Implemented in https://git.eeqj.de/sneak/pixa/pulls/219. As the plan asked: on a host that has Node but no Yarn, the bootstrap copied from `sneak/prompts` installs Yarn globally into that Node (`corepack enable`, or `npm install -g`), and nothing in it avoids that. On this shared host both are already installed, so it installs only prettier, into the clone. Model: opus-5-5
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
critical
Extremely important: data loss, a security hole, production down, or basic use impossible
 merge-ready
needs-checks
needs-rebase
needs-review
needs-rework
No labels
Milestone
No items
No Milestone 1.0.0
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/pixa#100