Skip to content

refactor(template): replace prek-autoupdate.sh with declarative update filters - #336

Merged
ichoosetoaccept merged 1 commit into
mainfrom
prek-declarative-update
Jul 29, 2026
Merged

ichoosetoaccept merged 1 commit into
mainfrom
prek-declarative-update

Conversation

@ichoosetoaccept

@ichoosetoaccept ichoosetoaccept commented Jul 29, 2026 •

Copy link
Copy Markdown
Owner

Summary

Deletes scripts/prek-autoupdate.sh and replaces it with a declarative [update.repos] tag filter in prek.toml, available since prek 0.4.10.

Why

lychee tags nightly as their GitHub "Latest" release, so prek update resolves it as the newest tag and rewrites the pinned rev to a mutable one that lychee's own hook then rejects (lycheeverse/lychee#1601). The template shipped a wrapper script passing --repo-exclude-tag to work around it.

The wrapper only protected the invocation that went through it. Verified against prek 0.4.11 in a throwaway repo:

config prek update result
no guard lychee-v0.24.0 → nightly
[update.repos."…/lychee"] exclude_tags = ["nightly"] lychee-v0.24.0 → lychee-v0.24.2

A bare prek update still flips the rev today. Habitual prek update, CI, an editor integration or an agent all bypassed the script. Moving the exclusion into the config makes it unconditional. The block also survives prek rewriting the file during the update.

minimum_prek_version is the load-bearing half

prek.toml is regenerated in full by migrations/sync_marked_sections.py (only extra-local-hooks is preserved), so minimum_prek_version = "0.4.10" reaches projects updating from an older template.

The pyproject floor does not: [dependency-groups] sits inside a template-preserve region, so an updating project keeps its own prek>=0.3.11. A too-old prek would ignore the [update] block entirely and silently reintroduce the bug. The config constraint fails loudly instead:

`prek` version `0.4.10` or newer is required, but version `0.4.9` is installed.
To update, run `brew update && brew upgrade prek`.

Structurally the same guard as the ruff required-version added in #333, for the same reason.

Migration

copier update never deletes files, so a _migrations entry removes the orphaned script from existing projects.

It refuses to delete a script the user edited. The guard is an exact SHA-256 against every version the template shipped, not a substring match — a #336 review finding, and correct in both directions:

  • A substring guard deletes a genuinely customised script as long as the matched line survives. That outcome is unrecoverable, so a heuristic is the wrong tool regardless of how accurate it is.
  • It also misses whole shipped versions. The pre-0.40.0 script used a --cooldown-days 7 second pass and contains no --repo-exclude-tag at all, so a marker-based guard flags every project generated before 0.40.0 as "customised" and leaves a pristine file behind with a warning.

Hashing is exact here rather than approximate because the script carries no .jinja suffix — copier copies it verbatim, so the bytes are identical in every generated project. Line endings are normalised first so a Windows checkout with core.autocrlf=true does not read as a customisation.

Migration command quoting

Both _migrations commands now quote the interpolated script path. copier/_main.py:405 sets shell=True for string-form commands and _copier_conf.src_path is whatever the user passed to copier copy, so an unquoted path containing a space splits into two arguments. The pre-existing 0.41.0 migration had the same latent bug and is fixed alongside.

migrations/** T201 exemption

Migrations run as bare python3 in the destination project, where the repo's logging setup does not exist and stdout is the only channel to the user. A migration that mutates files silently is worse than one that prints. Same category as the existing extensions.py exemption.

Test plan

  • Both directions verified empirically against prek 0.4.11, not inferred from the changelog.
  • minimum_prek_version enforcement confirmed to produce an actionable error naming both the required and installed versions.
  • Migration exercised on all five branches by hand and in tests: both shipped versions removed, a CRLF checkout removed, a customised script left in place with a warning, an absent file a silent no-op. It previously shipped with no test coverage at all, which is why neither direction of the old guard was ever exercised.
  • test_lychee_nightly_excluded_declaratively replaces test_prek_autoupdate_script_has_lychee_workaround, asserting the config and the minimum_prek_version premise it depends on.
  • The slow integration test now runs a bare prek update on a rendered project and asserts the resulting rev is still a versioned tag — the outcome, not just the configuration.
  • Full suite green on a clean tree including slow tests: 186 passed. ruff check, ruff format --check and ty check clean.

Not closed by this

DOT-504 tracks removing the workaround once lycheeverse/lychee#1601 is fixed upstream. Re-confirmed still unfixed on 2026-07-29 — only the remediation got smaller.

Closes DOT-616

@ichoosetoaccept

ichoosetoaccept commented Jul 29, 2026 •

Copy link
Copy Markdown
Owner Author

@linear-code

linear-code Bot commented Jul 29, 2026

Copy link
Copy Markdown

DOT-616

Comment thread copier.yml Resolved
@macroscopeapp

macroscopeapp Bot commented Jul 29, 2026 •

Copy link
Copy Markdown

Approvability

Verdict: Needs human review

2 blocking correctness issues found. This template refactor adds a migration that deletes files from user projects during copier update. While the implementation uses safe hash-based detection and the review comments appear to be addressed, runtime file modification behavior warrants human verification.

You can customize Macroscope's approvability policy. Learn more.

Base automatically changed from release-uv-env-guards to main July 29, 2026 08:21
…e filters

prek 0.4.10 added project-level and per-repository tag filters to the
`update` config (j178/prek#2354), which makes the shipped
scripts/prek-autoupdate.sh wrapper redundant.

The wrapper only ever protected the invocation that went through it.
Verified against prek 0.4.11 in a throwaway repo: a bare `prek update`
still rewrites lychee-v0.24.0 to `nightly` today, and lychee's own hook
then rejects that mutable rev. Habitual `prek update`, CI, an editor
integration or an agent all bypassed the script. Declaring the exclusion
in prek.toml makes it unconditional:

    [update.repos."https://github.com/lycheeverse/lychee"]
    exclude_tags = ["nightly"]

With the guard the same update resolves lychee-v0.24.2, and the block
survives prek rewriting the config file during the update.

minimum_prek_version rises to 0.4.10, and it is the load-bearing half.
prek.toml is regenerated in full by migrations/sync_marked_sections.py
(only extra-local-hooks is preserved), so it reaches projects updating
from an older template. The pyproject `prek>=` floor does not:
[dependency-groups] sits inside a template-preserve region, so an
updating project keeps its own prek>=0.3.11. A too-old prek would ignore
the [update] block entirely and silently reintroduce the bug, so the
config fails loudly instead -- the same shape as the ruff
required-version guard.

copier update never deletes files, so a _migrations entry removes the
orphaned script from existing projects. It refuses to delete a
customised one: a project that edited the script had a reason to, and
discarding that silently is worse than leaving an unreferenced file.

Migrations now carry a T201 per-file-ignore. They run as bare python3 in
the destination project, where the repo's logging setup does not exist
and stdout is the only channel to the user; a migration that mutates
files silently is worse than one that prints.

Tests assert the config and the minimum_prek_version premise it depends
on, replacing the assertions on the deleted script. The slow integration
test now runs a bare `prek update` on a rendered project and asserts the
resulting rev is still a versioned tag, so the outcome is covered and
not just the configuration.

DOT-504 stays open: lycheeverse/lychee#1601 is still unfixed as of
2026-07-29. Only the remediation got smaller.

Closes DOT-616
@ichoosetoaccept
ichoosetoaccept force-pushed the prek-declarative-update branch from 4a007b7 to 2affc71 Compare July 29, 2026 08:32
@ichoosetoaccept
ichoosetoaccept merged commit 903d007 into main Jul 29, 2026
7 checks passed
@ichoosetoaccept
ichoosetoaccept deleted the prek-declarative-update branch July 29, 2026 08:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant