@oakoss/oakum 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.5.0 (2026-10-05)
+
+### Changed
+
+`oakum version` no longer loses bump files when it is killed or fails while consuming them. It used to delete each consumed bump file and hold the only copy in memory, so a signal, an OOM kill or a cancelled CI job in that window removed files with nothing on stderr, and a later failure could leave some unrestorable. Consumed files are now moved aside to `.<name>.oakum-consume.*` names and removed only after every write has landed, and a failure moves them back. While it writes and consumes, `version` also holds a `.version.oakum-consume.*` marker in `.changeset/`. A run killed partway leaves these files behind. The next `check` names them and exits 2, where it used to pass. The next `version` and `ci version-pr` refuse (exit 1) rather than apply the bump files left beside them a second time. The refusal says whether the writes landed and how to recover. If a set-aside file cannot be moved back, `version` names it and the move that restores it. If every write landed but a set-aside file cannot be removed, `version` prints what it wrote, then names the file and why, and exits 1.
+
+`oakum release` now tags the first version `oakum version` writes, whether `0.1.0` or `0.0.x`. An untagged package was owed a tag only above `0.1.0`, so the `0.1.0` or `0.0.1` that `oakum version` writes from `0.0.0` read as an untouched starting version: `check` passed and `release` printed `nothing to release`. Now, with no reachable tag, only a manifest at `0.0.0` or `0.1.0` whose `CHANGELOG.md` has no section for that version is a starting version. Every other untagged version is owed a tag: `release` cuts it, and `check` refuses (exit 1) until it does. That includes a hand-set `0.0.5`, which `check` used to pass. A version with a changelog section is named as waiting for `oakum release`; one without still says to tag the version you meant. To release a `cargo init` crate at `0.1.0` as-is, add a `## 0.1.0` section to its changelog. When an untagged `0.0.0` or `0.1.0` has a changelog oakum cannot read, a dangling symlink included, the tags look reports it `unverified` (exit 2) and `release` refuses rather than skipping it; the other packages' findings still print. Above those versions an unreadable changelog only changes the wording.
+
+`oakum version` no longer bumps past a version someone set by hand. When the plan would bump a package, cascades included, whose manifest version has no tag and no changelog section, such as a `0.1.1` or `0.0.5` someone typed, `version` and `ci version-pr` exit 1 before writing anything and name every such package. The fix is to tag the version you meant, or to run `git fetch --tags` if its tag exists on a remote; `check` now gives that second option too. A hand-set version the plan leaves alone does not stop the run; `check` still reports it. A placeholder `0.0.0` or `0.1.0` is still bumped from, and an untagged version that has its changelog section (one `version` wrote and `release` has not tagged yet) is still stacked on. When the changelog or the tags cannot be read for such a package, `version` exits 2 rather than guess, so a shallow or no-tags clone now stops it whenever a package it bumps has no changelog section for its current version.
+
+`oakum add`, `generate` and `plan-intent` now refuse an `include` or `exclude` entry that names no package in the workspace, as `status`, `check`, `version` and `release` already did. They used to accept it, so `add` and `generate` wrote a bump file that every later step then rejected. The refusal, from every command, now names `.changeset/_config.toml` and lists the workspace packages to choose from (the first 20).
+
+Commits now count only toward packages the config versions, both in `generate` and when commits are the plan's intent: a package `include`/`exclude` leaves out, or a private package without `private-packages.version = true`, is skipped. A commit touching only such a package no longer makes `version` refuse in commits-only mode, and `generate` writes no bump file for it, naming the packages it skipped and the setting to change; a commit touching several packages names only the versioned ones.
+
+A changelog `template` must now render a heading oakum can read back. `check` and `release` find a version by its changelog heading, and a template that wrote, for example, `## demo@0.1.0` left the first `0.1.0` looking like an untouched placeholder, so `release` never tagged it. Headings of the form `## <name>@<version>` are now read for the package they name, alongside `## <version>`, `## [<version>]` and `## v<version>`. `version` exits 1 before writing anything when the template renders any other heading, such as `### {{ version }}` or `## Version {{ version }}`, and names the shapes that work. It also exits 1 when the template renders nothing for a bumped version, such as a cascade whose template writes only when there are notes; that version would otherwise have no section. Whatever the template, `version` exits 1 when a new entry leaves a code fence open, for example a bump file note that ends inside one, or when a fence the existing changelog leaves open would hide a new heading; either would hide headings from `check` and `release`.
+
+### Fixed
+
+The workflow `oakum init` and `oakum migrate` print for a Cargo repository now installs oakum with `taiki-e/install-action` (`tool: oakum@<tool-version>`), pinned to a release oakum ships with. The step it replaces, `run: cargo binstall --no-confirm oakum@<tool-version>`, cannot run on `ubuntu-latest`, which does not ship `cargo-binstall`. For the same reason `migrate` no longer tells a Cargo repository without a pin to add `cargo binstall` to it; the printed workflow is the pin it offers. `check`'s refusal for a repository with no pin names the install-action step as its example instead of `cargo binstall`. oakum is not in install-action's own tool list, so the action installs `cargo-binstall` and uses it; `cargo-binstall` 1.24.0 resolves `oakum@0.4.0` for `x86_64-unknown-linux-gnu` from the GitHub release (dry run). `oakum check` reads the new step as the install pin, as it read the old one. npm workspaces are unchanged.
+
+Oakum notices sooner that a git child has finished: the wait polled every 5 ms, so each child cost up to a poll's worth of idle time after git had already exited, and a command can run many of them. It now polls every 1 ms. Measured on macOS, `oakum check` in this repository dropped from 185 ms to 153 ms (fastest of 15 alternating runs). Output is unchanged.
+
+`oakum check`, `oakum release` and the other commands that verify the install pin no longer hang when a pin file is a FIFO. The look opened `package.json`, `.mise.toml`, `mise.toml` and `.github/actions/*/action.yml` with a blocking open, so a FIFO nobody wrote to stalled the command forever. It now opens them non-blocking, as oakum's other file readers do, and refuses as `unverified` (exit 2), naming the file that is not a regular file. A missing file and a dangling symlink still read as no pin there. A `cargo` or `pnpm` reached through a mise shim reads `mise.toml` itself, so on such a PATH a FIFO there can still block before oakum looks.
+
+When this binary is older than the repository's `tool-version`, the refusal no longer tells you to run `oakum upgrade`. Following that advice rewrote `tool-version` down to the older binary and exited 0, so a contributor with a stale local install downgraded the repository by doing what the error said. The refusal now names the pinned version to install and says `upgrade` would downgrade the repository. A binary newer than the pin still names `oakum upgrade`. Stderr only; the exit code is unchanged.
+
+An exported `GIT_LITERAL_PATHSPECS`, `GIT_GLOB_PATHSPECS`, `GIT_NOGLOB_PATHSPECS` or `GIT_ICASE_PATHSPECS` no longer changes what oakum asks git. Oakum writes its pathspecs for git's defaults, and under `GIT_LITERAL_PATHSPECS=1` the exclusions in `oakum migrate`'s gate look became literal file names: the look searched nothing, and a repository whose hook names `.bumpy/` was told no file names the old bump-file directory. Under `GIT_ICASE_PATHSPECS=1`, `oakum release` refused before tagging, because git rejects the `:(literal)` pathspec it reads the changelog through. Oakum now clears these variables for every git child it runs, as it already clears git's trace variables.
+
+Under pnpm 12, discovery no longer writes `pnpm-lock.yaml` into a pnpm workspace, or rewrites the one it has. Every pnpm call oakum makes (`pnpm list`, `pnpm root -w`, and the `pnpm --version` that `oakum init` runs) created a lockfile, mode 0600, in a lock-free workspace that declares its package manager, so `oakum status`, and any other command that discovers packages, left an untracked file behind; under an array-form `devEngines.packageManager`, `init` also rewrote an existing lockfile. Oakum now passes `--config.lockfile=false` on each call. Measured on pnpm 8.15.9, 9.15.9, 10.34.5, 11.25.0, 12.5.1 and 12.6.0: each accepts the flag and prints the same output with it. pnpm 11 still writes one under a `devEngines.packageManager` declaration or a `packageManager` naming pnpm 12; the flag does not stop it there. Output and exit codes are unchanged.
+
+## 0.4.0 (2026-09-21)
+
+### Added
+
+`oakum check --json` prints a versioned `CheckReport` instead of the prose report: every look the run could perform, what each established, and which refusal decided. A caller that must see both outcomes of a mixed run now has somewhere to read the second — ADR-0035 ranked a finding above a look that did not happen and named the cost: the unverified outcome survives only in the `also` prose. A look nobody asked for reports `not-asked`, and one that said something without refusing reports `reported`, so neither can read as a look that happened and found nothing. A look that raised several refusals carries every one of them with its own evidence, rather than the first alone. The document also carries what the run covered — the packages selected, the base it diffed from or why that could not be named, and whether coverage gated — which the prose report says on stdout and `--json` replaces. Refusals still reach stderr and the exit code is unchanged, so one run yields a document and a human-readable failure.
+
+### Changed
+
+A bump file whose note is a heading with nothing under it renders no changelog section, so `oakum version` consumed the file and the release said nothing about what its author wrote, with no warning anywhere. `oakum add` now refuses to write such a note, naming `--none` for a change that is deliberately releaseless. `oakum check` reports one always and refuses under `--strict`, the shape its coverage look already uses, so a repository green today stays green until it opts in. `version` itself still says nothing when it consumes one, so a repository that never runs `check` still loses the note at release time. Three shapes that render nothing on purpose are untouched: a coverage-only (`none`) entry, a bump file with no note, and a note that is only whitespace. A file that drops only one of several headings is not reported either. Breaking for a repository that has such a file and runs `check --strict`, or an `add` whose message is a bare heading; both exited 0 before and exit 1 now.
+
+### Fixed
+
+When `oakum version` fails partway and cannot restore a bump file it already deleted, the failure now names that file and prints the opening lines of what it held. The file is gone at this point, so a later run cannot see it: it consumes whatever is left and reports success at a version nobody asked for. Measured on a real run — a failed `version` destroyed a `minor` bump file, and the next run shipped `0.1.1` where `0.2.0` was intended, at exit 0. The message says a file git has a copy of, committed or staged, comes back with `git checkout`, and shows the text for one that was never committed. The excerpt is bounded by lines, by columns and by file count, and the entry list above it by file count, each saying what it elided. Everything user-supplied in this message — the cause, each path, each error and each excerpt line — is escaped, since a bump file and the path naming it can arrive from a pull request and this is the one path to a raw terminal; script joiners and combining text still render. Exit codes are unchanged; a delete oakum could not undo is a finding it measured, so it still exits 1 (ADR-0037).
+
+The `check --json` scope field `gating_coverage` is now `gating`, and carries the names of the looks `--strict` decides rather than a yes or no. `--strict` gates two looks as of this release — coverage, and the notes look that refuses a bump file note reaching no changelog — so a consumer that could only ask about coverage could not tell which of them refused; the names match `looks[].look`, so the two can be joined. The field says what `--strict` decided, not what the looks then managed: a look that could not run is still named, and reports `unverified` in its own row. An empty list means `--strict` was not asked for. A `patch` rather than a renamed field under the breaking row, and no `schema_version` bump: `check --json` has not appeared in a release — it was added after the v0.3.2 tag and its note is still pending — so no consumer can be holding the old name (ADR-0016 on a field that has never shipped).
+
+`oakum migrate` no longer reads a `git grep` that exited 0 without naming a file as a search that found nothing. Real git cannot answer that way — a match prints the path, and both no-match and an empty index exit 1 in silence (measured on git 2.55.0 and Apple Git 2.54.0) — so the shape only ever comes from a wrapper that failed to look, and the gate find it produced was a look nobody completed. Such a run now refuses as `unverified` and exits 2 where it printed that no file names the old bump-file directory and exited 0. No repository running real git changes behavior.
+
 ## 0.3.2 (2026-09-17)
 
 ### Fixed
@@ -220,4 +268,4 @@ Release workflow checks out the homebrew tap in a subdirectory so the composite
 
 Self-host release CI uploads cargo-dist artifacts into the GitHub Release oakum already created, instead of calling create again.
 
-Generated by oakum 0.3.1.
+Generated by oakum 0.4.0.

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@oakoss/oakum",
-      "version": "0.3.2"
+      "version": "0.5.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.3.2"
+  "version": "0.5.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/oakoss/oakum/releases/download/v0.3.2"
+    "https://github.com/oakoss/oakum/releases/download/v0.5.0"
   ],
   "author": "Jace Babin",
   "bin": {
@@ -105,7 +105,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.3.2",
+  "version": "0.5.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"