feat!: drop v1 runtime, keep v1 -> v2 auto-migration (PR1 of plenary removal) by delphinus · Pull Request #341 · nvim-telescope/telescope-frecency.nvim

delphinus · 2026-05-09T06:42:34Z

Summary

PR 1 of the plenary.nvim removal effort.

Removes the v1 database runtime (entry score / table writes / DB write+sort+update paths) and its specs.
Flattens the v1 read path and the existing migrate_from / from_v1 logic into v2 so existing file_frecency.bin users upgrade transparently. The v1 binary is left on disk for rollback safety. The migration shim is scheduled for removal in a later 2.x minor release after a CHANGELOG notice (separate tracking issue to be filed).
Drops the db_version config option (only v2 exists now).
Updates query({ record = true }) to expose v2 native fields (num_accesses, last_accessed, half_life, reference_time) plus a count = num_accesses alias for backwards compatibility. The timestamps array is gone because v2 keeps only the most-recent access time, not history. order = "count" and order = "timestamps" are remapped to num_accesses / last_accessed internally so existing call sites keep working.
Bumps minimum Neovim to v0.11.7 by dropping v0.10.4 from the CI matrix (matches telescope.nvim).
Replaces v1-shape test assertions with v2 smoke tests; broader v2 coverage is deferred to follow-up PRs.
Documents the migration, the v0.11.7 requirement, and the new query() shape in :help and README.

Net diff: +615 / −1075 across 18 files (including the deleted v1/ directory).

Breaking changes

Minimum Neovim is now v0.11.7. Users on 0.10.x should lock to a release before 2.0.0.
db_version is removed (passing it to setup() becomes a no-op or validation error).
file_frecency.bin is migrated automatically on first launch with 2.0.0; the v1 file itself is left on disk for rollback safety. Internal score representation changes from v1 (count × static recency) to v2 (exponential decay), so initial rankings may shift after upgrade.
query({ record = true }) no longer returns a timestamps array; use reference_time + last_accessed to recover the most-recent access epoch (single value, not a list).

Test plan

bin/run-tests green locally on Neovim stable (Apple Silicon macOS).
- sorter_spec: 3 / database_spec: 1 / file_lock_spec: 11 / frecency_validate_database_spec: 4 / frecency_spec: 14 → 33 passed, 0 failed.
stylua clean on changed lua files.
CI: Linux / macOS / Windows × stable / nightly (this PR)
CI: luacheck (this PR)
CI: lua-typecheck-action (this PR)
Manual smoke on a real project: :Telescope frecency, register-on-open, :FrecencyDelete, :FrecencyValidate, workspace tag filtering.
Migration smoke: launch with an existing file_frecency.bin only, confirm file_frecency_v2.bin is created and entries are preserved (with re-decayed scores).

Follow-up PRs (tracking #340)

PR 2 — Replace the plenary.log facade with an in-tree logger.
PR 3 — Add lua/frecency/async/ and migrate plenary.path / plenary.async call sites to builtins / vendored async.
PR 4 — Vendor scandir.__make_gitignore, switch tests to plentest.nvim, drop FrecencyPlenary* types, finish README / :help cleanup.

🤖 Generated with Claude Code

PR 1 of the plenary.nvim removal effort (refs #340). - Remove the v1 database runtime (entry score / table writes / DB write+sort+update paths) and its specs. - Flatten the v1 read path and the existing migrate_from / from_v1 logic into v2 so `file_frecency.bin` users upgrade transparently. The v1 binary is left on disk for rollback safety. The migration shim is scheduled for removal in a later 2.x minor release after a CHANGELOG notice. - Drop the `db_version` config option (only v2 exists now). - Update `query()` to expose v2 fields (`num_accesses`, `last_accessed`, `half_life`, `reference_time`) plus a `count = num_accesses` alias for backwards compatibility. The `timestamps` array is gone because v2 keeps only the most-recent access time, not history. - Bump minimum Neovim to v0.11.7 by dropping v0.10.4 from the CI matrix (matches telescope.nvim). - Replace v1-shape test assertions with v2 smoke tests; broader v2 coverage is deferred to follow-up PRs. - Document the migration, the v0.11.7 requirement, and the query() shape change in `:help` and README. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@diagnostic

The protected `tbl` field and the V2-only `wait_ready` method need the same `---@diagnostic disable-next-line` annotation that the surrounding `tbl:set` line already has. Caught by the lua-typecheck-action CI step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@as

luacheck flagged 125 > 120; switch the inline `--[[@as ...]]` to a separate `---@cast` annotation on the next line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Long-time users who follow master without pinning to a tag may still be on the v1 database silently. Make the breaking change discoverable so they don't think the plugin is broken after pulling HEAD. - Add a hard error in lua/frecency/init.lua if Neovim < v0.11.7 (mirrors telescope.nvim's plugin/telescope.lua pattern). Failing loud beats cryptic errors from missing vim.fs APIs. - After a successful v1 -> v2 migration, schedule a one-time vim.notify (WARN level) explaining what happened, why rankings shift, and where the v1 file is preserved for rollback. The v2-file existence guard naturally serves as the once-flag, so subsequent launches stay quiet. - Add an "Upgrading to 2.0.0" section to README right after the existing versioning notice, listing the breaking changes and the ^1.0.0 pin recipe for users who want to stay on v1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CI ran (a) stylua, (b) lua-language-server (lua-typecheck-action), (c) luacheck (docker), (d) bin/run-tests. Last PR1 push had to be re-run twice because (b) and (c) were not exercised locally. This script bundles all four behind one entry point so the checks happen before push, not after. Notes on the trickier bits: - luacheck runs in the same `lunarmodules/luacheck:v1.2.0` docker image CI uses, so output is byte-identical. Falls back to the Mason luacheck only if it is actually runnable (the macOS Mason copy hard- codes /opt/homebrew/opt/lua/bin/lua5.4 which usually isn't there). - lua-language-server diagnostics are filtered to files changed vs --base (default origin/master) so pre-existing warnings in untouched code don't fail the check. Known luassert false positives (`assert.are.*`, `assert.is_*`, etc.) are also dropped because the Mason lua-language-server flags them while the CI version does not. - stylua is restricted to changed .lua files per the project's "format only what you changed" convention; CI doesn't run stylua at all so this is purely a local guard. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

TableV2:from_v1 was leaving record.last_accessed at the absolute v1 epoch, while every other code path stores it as a delta from reference_time (see EntryV2:update). Migrated entries therefore reported wildly different last_accessed values from freshly-registered ones, breaking: - query({ record = true }) consistency, - the documented "reference_time + last_accessed = absolute epoch" recovery path, - order = "timestamps" sort behaviour (migrated entries sorted as if they were ~50 years in the future). The inner fold's entry:update() already computes the correct delta on entry.last_accessed; just mirror it back onto record.last_accessed. The score path was already mirrored the same way. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

delphinus · 2026-05-09T23:59:13Z

Hi @clason — I dropped v0.10.4 from the CI matrix in this PR, but the main ruleset still requires three checks that no longer run:

Run tests (ubuntu-latest, v0.10.4)
Run tests (macos-latest, v0.10.4)
Run tests (windows-latest, v0.10.4)

They sit pending and block the merge button. Could you remove them from Settings → Rules → Rulesets → main → Required status checks when you have a moment? I don't have admin on the repo. Thanks!

clason · 2026-05-10T08:19:52Z

Sorry, removed them! (And bumped your privileges.)

Regarding your plan: My plan is to keep plenary.log and plenary.async in telescope for now, so you should be able to just rename the require to pull in the vendored version from telescope. (It doesn't make sense to drop them before vim.log and vim.async is shipped, but no need for every extension to duplicate them.)

scandir and path are definitely on the chopping block.

delphinus · 2026-05-10T11:05:09Z

@clason Thank you! It is really helpful that log and async are vendored in telescope itself. Then I will refactor frecency for the deprecation of other plenary.* modules.

delphinus added this to the Drop plenary.nvim dependency milestone May 9, 2026

delphinus and others added 5 commits May 9, 2026 20:42

style: split overlong cast comment in TableV2.new

803cc98

luacheck flagged 125 > 120; switch the inline `--[[@as ...]]` to a separate `---@cast` annotation on the next line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

delphinus enabled auto-merge (squash) May 9, 2026 15:31

clason approved these changes May 10, 2026

View reviewed changes

delphinus merged commit ab7b693 into master May 10, 2026
11 of 12 checks passed

delphinus deleted the feat/drop-plenary-pr1 branch May 10, 2026 08:20

delphinus mentioned this pull request May 21, 2026

Tracking: drop plenary.nvim dependency #340

Open

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat!: drop v1 runtime, keep v1 -> v2 auto-migration (PR1 of plenary removal) - #341

feat!: drop v1 runtime, keep v1 -> v2 auto-migration (PR1 of plenary removal)#341
delphinus merged 6 commits into
masterfrom
feat/drop-plenary-pr1

delphinus commented May 9, 2026 •

edited

Loading

Uh oh!

delphinus commented May 9, 2026

Uh oh!

clason commented May 10, 2026

Uh oh!

Uh oh!

delphinus commented May 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

delphinus commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking changes

Test plan

Follow-up PRs (tracking #340)

Uh oh!

delphinus commented May 9, 2026

Uh oh!

clason commented May 10, 2026

Uh oh!

Uh oh!

delphinus commented May 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

delphinus commented May 9, 2026 •

edited

Loading