@kaisers-io/refs 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,140 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] - 2026-09-13
+
+### Upgrading
+
+**A repository declaring a workspace pattern like `packages/**` now reports every member behind
+it.** Those patterns were refused outright, which also stood the unregistered-package pass down for
+the whole ref — so a ref that reported nothing for months may suddenly name hundreds of packages.
+They are not new; they were invisible. `refs doctor` prints the first ten and a count of the rest,
+`refs doctor --json` carries all of them, and
+`refs edit --package=<name> --decline --path=<path> <ref>` records the ones you do not want so they
+stop coming back.
+
+### Added
+
+- **A workspace pattern that matches at more than one depth is expanded.** `packages/**/*` — the
+  most common pnpm spelling — was reported as `unsupported_pattern`, which also made the whole scan
+  unreliable and stood the unregistered-package pass down for that ref. A repository declaring it
+  got no answer at all, permanently.
+
+  Such a pattern is now walked from the deepest directory it names outright. Pruning is the
+  MATCHER's decision: minimatch answers "could anything below this directory still match?", so a
+  subtree no pattern can reach is never entered, a hidden directory is skipped where a wildcard
+  would not select it and walked where a pattern names it, and a package boundary does not stop
+  the walk — nested packages are ordinary, and both resolvers glob manifest paths rather than
+  stopping at one. Selection matches the manifest path for the same reason: `packages/core/**`
+  selects `packages/core` itself, because `**` matches zero segments before the manifest.
+  `node_modules` and `.git` are never walked under any pattern — a recursive pattern matches an
+  installed dependency's path as a string, and reporting those would be reporting a repository's
+  dependencies as its own packages.
+
+  The whole scan runs under one budget shared by every pattern — 32 levels deep, 20 000
+  directories, 200 000 entries — because patterns overlap, and a per-pattern budget would charge
+  the same tree once per declaration. Reaching a limit is not itself a failure; having to leave a
+  subtree that could still match unwalked is, and that is the only condition `scan_budget_exhausted`
+  is reported under. A directory the pattern names but the repository does not have stays silent,
+  which is ordinary: astro declares `smoke/**/*` and a fresh clone has no `smoke/`.
+
+  Measured against the resolvers themselves, on fresh clones: `withastro/astro` now detects 554
+  packages where pnpm's own workspace listing reports 554 and refs previously reported 37;
+  `vercel/next.js` detects 38 where pnpm reports 38; `payloadcms/payload` 53 where pnpm reports 53.
+  Pattern semantics were checked against `@npmcli/map-workspaces` over six pattern shapes.
+
+- **A ref with hundreds of findings no longer prints all of them.** The same repositories that
+  motivated the expansion can legitimately have hundreds of workspace members, so a ref tracking
+  three of them would print 551 repair commands into one `doctor` line. Ten are printed, followed
+  by a count of what was held back — act on those and run the check again for the next batch.
+  `refs doctor --json` carries every finding on the check itself, uncapped: a finding no command
+  can repair is never cleared by acting on the ones printed before it, so a capped list would put
+  it permanently out of reach.
+
+- **A drift finding you have decided against can be recorded, so it stops coming back.**
+  `refs doctor` reports every workspace member a checkout declares that the configuration does not
+  have. There was no way to say "I looked, and no": the finding returned on every run forever, so
+  `config-drift` sat on `warn` permanently and the next real finding arrived in a line already
+  being ignored. On a home tracking four monorepos, six of seven findings were decisions that had
+  already been made — a repository root, and four packages published nowhere.
+
+  `refs edit --package=<name> --decline --path=<path> <ref>` records the decision on the ref, as
+  the name AND the path. Neither identifies it alone: a name-only record would also silence a
+  different package that later takes the name, and a path-only one would silence whatever moves in.
+  The `unregistered` finding now prints this command beside the registration command, so both
+  answers are available where the question is asked.
+
+  What a decline does not do: it never touches a finding about a configured entry (`missing`,
+  `relocated`, `ambiguous`, `unverifiable`), never suppresses `discovery_incomplete`, and never
+  hides the other claimants of an ambiguous name. The package is reported again if it moves.
+  `--undecline` withdraws the decision; registering the package clears it in the same write.
+  `refs doctor` says how many decisions a run left unreported, so a quiet check is not a silent
+  one.
+
+## [0.13.1] - 2026-09-12
+
+### Upgrading
+
+**A repository declaring a workspace pattern like `crates/*/js` will suddenly report packages refs
+could not see before.** The pattern was classified as unsupported, which also made the whole scan
+unreliable and stood the unregistered-package pass down for that ref. `refs doctor` may therefore
+name members on a ref that reported nothing for months. They are not new; they were invisible.
+Register the ones worth routing to, and leave the rest.
+
+### Added
+
+- **Every drift finding that has a repair now prints it as a command.** `unregistered` has printed
+  a runnable `refs edit --create` since the probe shipped; `missing` and `relocated` described the
+  repair in prose and left the reader to construct it. The asymmetry was not deliberate — one of
+  the two repairs did not exist as a command at all. `refs doctor` now ends those findings with
+  `refs edit --package='<name>' --remove '<ref>'` and
+  `refs edit --package='<name>' '<ref>' 'path' '<new>'`, quoted for a shell like every other
+  command refs prints. A new path the configuration could not hold is still reported, without a command
+  that would only fail validation.
+
+  Every printed `refs edit` now attaches its option values with `=` and, where a positional would
+  otherwise begin with `-`, ends the options with `--`. Quoting gets a value past the shell; refs'
+  own parser reads it next, and `refs edit '<ref>' path '-new/pkg'` — a path `zPackagePath` accepts
+  — arrived correctly quoted and exited `2` with `unknown option '-new/pkg'`. The terminator is
+  printed only where it is needed, so appending `--json` to an ordinary printed line still works.
+
+- **`refs edit <ref> --package <name> --remove` unregisters a package.** The counterpart to
+  `--create`, and the repair the `missing` finding needed: a package that left a repository's
+  workspaces leaves an entry behind that `refs resolve` keeps answering with, pointing at a path no
+  checkout has. The only instruction refs could give was to hand-edit `config.toml`. Removal
+  touches configuration alone and never consults a checkout — it has to work while the checkout is
+  stale, absent, or still carrying the directory. Removing the last entry drops the `packages`
+  table rather than leaving an empty one, which `add` and the drift probe read differently.
+
+### Fixed
+
+- **A workspace pattern whose wildcard is not in its last segment is expanded.** `crates/*/js` —
+  the spelling a Rust/JS monorepo uses — was reported as `unsupported_pattern` and every package
+  beneath it went undetected. That pattern costs one `readdir` and a literal probe per child, the
+  same shape `packages/*` has, so the budget that refused it was measuring the wrong thing. Two
+  wildcards still mean two levels and `packages/*/nested/*` is still refused. Measured on a
+  repository declaring `crates/*/js` and `turbopack/crates/*/js`: 41 packages detected instead of
+  37, with no diagnostics; three other monorepos detect exactly what they did before.
+
+- **`tag_format` is detected from every tag, not from the top twenty of a refname sort.** Detection
+  counted formats among the first 20 tags of `git tag --sort=-version:refname`. That sort is
+  version-aware over the whole refname, so in a monorepo that tags per package it groups by prefix:
+  those twenty are one package's tags, not a sample of the repository's. Measured against two real
+  repositories, `refs add` proposed `create-astro@{version}` for a repository with 839
+  `astro@{version}` tags, and `keystatic@{version}` — a package whose last tag is `0.0.36` and whose
+  directory no longer exists — for one where `@keystatic/core@{version}` is the live package with 183 of
+  them. Both now resolve correctly, and the two repositories whose detection was already right are
+  unchanged.
+
+  A tag list that could not be read whole now yields no candidate at all rather than one derived
+  from whatever survived. `git tag` output is capped at the subprocess stream limit, and the note
+  saying so was written to stderr and never read — which did not matter while only twenty lines
+  were needed, and does once the count is a claim about all of them.
+
+  What this establishes is historical plurality, not which package is primary or still alive: a
+  retired package with a thousand tags still outvotes its replacement's hundred. The two-phase flow
+  shows the candidate for exactly that reason.
+
 ## [0.13.0] - 2026-09-12
 
 ### Upgrading