docs: add an EQL pin resolver so patch bumps stop relying on memory - #75
Merged
coderdan merged 1 commit intoJul 28, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
Reports whether a newer EQL release exists for the pinned minor, and with --apply rewrites the pin. The companion workflow calls this on a schedule and opens a PR, so a new EQL release surfaces as a reviewable PR instead of something someone has to remember to check. It deliberately does NOT float the pin. The drift check validates every schema-qualified symbol in the hand-written pages against the pinned release's manifest and FAILS THE BUILD on a mismatch, so an auto-following pin would turn an unrelated PR red with no commit of its author's to explain it — which is what eql-3.0.0-alpha.4 did when it replaced eql_v3.ore_cllw. Scope is the pinned minor, and even that goes through review: EQL patch releases are not additive-only ahead of Stack 1.0. Between 3.0.0 and 3.0.1 — a patch — eql_v3.contains went 15 occurrences to 0, eql_v3.matches 0 to 15, and eql_v3_json_search 0 to 162. A newer minor or major is reported but never proposed, since those carry migration work beyond a pin change. Prereleases and the sibling tags cut by the same release (eql-bindings-v3.0.3, @cipherstash/eql@3.0.3) are excluded by matching eql-X.Y.Z exactly and honouring the API's prerelease flag. Note the release bodies claim "Preview (prerelease)" on stable releases; that text is stale boilerplate and contradicts the flag, so the flag is what this trusts. Claude-Session: https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8
Copy link
Copy Markdown
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Sorry, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds scripts/check-eql-pin.ts: reports whether a newer EQL release exists for the pinned minor, and with --apply rewrites the pin. The companion workflow (#76, on main) runs it daily and opens a PR.
The goal is to stop remembering to bump the pin — not to stop reviewing it.
Why it proposes rather than follows
The pin exists because the drift check validates every schema-qualified symbol in the hand-written pages against the pinned release's manifest and fails the build on a mismatch. A floating pin means an upstream rename lands as a red build on whoever happens to have a PR open, with no commit of theirs to explain it — which is exactly what eql-3.0.0-alpha.4 did when it replaced eql_v3.ore_cllw.
So a bump arrives as a PR with the drift check already run, and the PR body says whether it is a rubber stamp or needs doc edits.
Why even patch bumps go through review
Ahead of Stack 1.0, EQL patch releases are not additive-only. Counting occurrences in the shipped cipherstash-encrypt.sql across what was a patch bump:
Auto-following would have swapped the entire fuzzy-match and encrypted-JSON surface underneath the docs silently. Once EQL semver tightens post-1.0, the natural next step is auto-merging these PRs when drift is clean — the workflow is shaped so that becomes a small change rather than a rewrite.
A newer minor or major is reported in the PR body but never proposed: that is migration work, not a pin change.
Details worth knowing
Verified
Run against this branch, which is pinned at eql-3.0.0:
--apply rewrites the pin to eql-3.0.3 and nothing else; Actions outputs (bump/from/to/newer_minor) emit correctly; biome check clean.
Note
Merge this before #76 — the workflow runs this script from the v2 checkout.
https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8