v0.13.0

lockrot 0.13.0 writes several reports from one run, keeps self-update within its major version, and writes the decisions behind each verdict, priority and exit code into the report as typed fields. Read Before you upgrade if you: run lockrot in CI, set COMPOSER or LOCKROT_*, publish reports, validate them with Ajv strict or a vendored schema, run self-update in CI, or use lockrot's PHP classes.

No verdict or priority rule changed. Documents written by earlier releases still validate.

Before you upgrade

If you…	What changes	What to do
allow exit 1 in CI (e.g. GitLab allow_failure: exit_codes: [1])	A command line lockrot cannot read (unknown option, missing value) exits 2, not 1. An unknown command name is still 1	Fix the command line (exit codes)
set LOCKROT_FAIL_ON or LOCKROT_TARGET_PHP	An invalid value is a configuration error (exit 2), even when the matching option overrides it	Fix or unset the variable
set COMPOSER=alt.json	lockrot reads extra.lockrot from alt.json and analyses alt.lock, as Composer does, so verdicts can differ; annotations name alt.lock	Keep extra.lockrot and the baseline with that manifest (environment overrides)
publish reports	json and html carry run.root_package, composer.json's name, whatever extra.lockrot.project says	Remove the name before publishing if it must stay private
published reports from earlier releases	Earlier releases could print logins, URL tokens and machine paths. 0.13.0 quotes none (SARIF's %SRCROOT% aside)	Check old published reports; rotate any token you find (what a report reveals)
validate reports with Ajv strict, or keep a copy of the schema	Sets that grow (signal ids, reasons, note codes, formats…) are open strings with x-known-values. The schema URLs serve the newest release's files, so this applies even if you stay on 0.12	Declare x-known-values or set strict: false; refresh a vendored copy (open sets)
run self-update in CI	A 0.13 archive installs only within its major (--allow-major moves one), skips releases needing a newer PHP or a key it lacks, and reads lockrot.phar.meta.json from github.com. --check exits 1 only when an update would install; --force can exit 2	Allow github.com where only api.github.com was allowed; let a --force job accept exit 2 (self-update exit codes)
reviewed lockrot or set an egress allowlist from 0.12.0's SECURITY.md	That page left out GitLab, Bitbucket, GitHub's release downloads and the GitLab token variables, which earlier releases used too	Recheck against what lockrot does and does not do
use lockrot's PHP classes	Everything under src/ is @internal; Lockrot\Extension\ is reserved	Depend on the CLI and the json report
cut the JSON out of an html page	That recipe wrote an empty file when the page did not match	Write both from one run: --output=json:lockrot.json (the JSON beside the page)

What's new

• Several reports from one run. Repeat --output=<format>:<path>; --format still decides stdout, and every file shares one analysis:

  php lockrot.phar --format=github \
    --output=sarif:lockrot.sarif --output=html:lockrot.html --output=json:lockrot.json

• The report states what lockrot decided. Instead of rebuilding it from prose or lockrot's rules, read it from the json report:

  • gate: whether the run fails and why, and per finding whether it reaches --fail-on or is exempt by the baseline;
  • priority_basis and no_fix_expected: how each priority was reached, and which advisories expect no fix;
  • origin, from_composer_repository and replacement_url: where each lock entry came from, and links lockrot can vouch for;
  • note_details: every run note typed, with a link to its section;
  • libyears_unmeasured, exposure_rule with unattributed, S6's release facts, and which release branches the project's PHP can take.

  All are listed in schema.md. The html page (lockrot-report 0.13.0) reads them.

• A warning for a mistyped key. An extra.lockrot key lockrot does not read gets one line on stderr, with the likely key: lockrot: unknown key extra.lockrot.install-tme ignored (did you mean install-time?).

• A safer self-update. It stays within its major version, checks the PHP floor and signing key a release declares, and moves to a new key through a transition release.

• A draft of the 1.0 promise. Compatibility says what 1.0 freezes, how verdicts may change between releases, and the deprecation policy.

Fixed

• Text from a package or an error message can no longer restyle the console, open a terminal link or end the run with exit 2.
• A key starting with a NUL byte no longer switches extra.lockrot or baseline validation off.
• LOCKROT_DISABLE=1 skips the run before the configuration is read.
• Report and baseline files are written through an exclusive temporary file and never follow a planted symlink.
• Several docs statements that gave wrong results when followed; each is in the changelog.

The full list, with a link from every entry to the page that explains it, is the 0.13.0 changelog.