feat(docs): ship the benchmarks and the schema in the doc package

[BryanFRD]

First half of FerrLabs/FerrFlow-Cloud#929: @ferrflow/doc now carries the benchmark numbers and the JSON schema alongside the pages, so one version bump moves all three together.

Today ferrflow.com assembles those three from three routes at three cadences, and they disagree: docs from @ferrflow/doc pinned at 7.17.0, benchmarks from a six-hourly sync at 7.18.0, and a schema copied from this repository's main, so the site can advertise config keys no published binary accepts.

Where the data is written. scripts/embed-release-data.js runs as part of postBump and writes docs/site/data/. It has to be a hook rather than a step before ferrflow: auto_stage_new_files diffs the dirty set around each hook, so anything already modified when ferrflow starts is invisible to it and never reaches the release commit. collect_dirty_files counts ?? entries, so files the hook creates are staged like modified ones.

Where the data comes from. The release job downloads hyperfine-baseline before running ferrflow and passes the path in FERRFLOW_BENCHMARK_JSON. That artifact already exists at that moment: release declares needs: [..., benchmark-aggregate], so the benchmark matrix for this exact commit has finished. The existing benchmark-release-summary download stays where it is, since it feeds the draft release notes rather than the package.

The download is continue-on-error and the step is gated on benchmark-aggregate having succeeded. A release without benchmark data keeps the previously published numbers rather than failing or shipping an empty file, and the script says which of the two happened.

The version in the embedded JSON is overwritten with FERRFLOW_NEW_VERSION, so it names the version being released rather than the one the benchmark run measured, which is the same commit but the older number.

docs/site/data/ is committed rather than generated-only, so the directory is tracked and the package is complete from the first publish. Both files are regenerated on every release; schema/ferrflow.json remains the source of truth and docs/site/data/schema.json is a copy of it.

The consuming half stays in FerrLabs/FerrFlow-Cloud and needs a release carrying this before it can land: sync-docs.mjs picks both files out of node_modules, sync-ferrflow.yml and its org-admin PAT go away, and the Schema parity job becomes unnecessary because the served copy stops being a copy.

Ref FerrLabs/FerrFlow-Cloud#929

[ferrfleet]

One blocking finding in the workflow change, plus a nit on the hook script.

Checked and fine: benchmark-aggregate is in release's needs, so the gate resolves; the hyperfine-baseline artifact does contain latest.json (FerrLabs/Benchmarks action.yml:406); docs/site/data/schema.json is byte-identical to schema/ferrflow.json at this SHA; postBump output is auto-staged (src/monorepo/run/mod.rs:621), so the generated files do reach the release commit; @ferrflow/doc has no files field, so data/ ships.

Worth noting rather than fixing: hyperfine-baseline is only uploaded on push to main (action.yml:403), so on a workflow_dispatch release the download fails, continue-on-error swallows it, and the committed numbers are published as-is. That matches the stated intent, but it means the dispatch path never refreshes benchmarks.

[github-actions]

SonarQube — 2 issue(s) introduite(s) par cette PR

• MINOR scripts/embed-release-data.js L1 — Prefer node:fs over fs. _{javascript:S7772}
• MINOR scripts/embed-release-data.js L2 — Prefer node:path over path. _{javascript:S7772}

_{Comparaison entre le projet bac à sable de cette PR et la branche par défaut : SonarQube Community n'analyse pas les PR, ce delta est calculé côté CI. Détail}

[BryanFRD]

Both taken, in aca7bad.

The duplicate env. Correct, and it would have taken the whole file down. I added a block above run: without noticing the step already had one below it. What makes this worth recording is that my validation said the file was fine: yaml.safe_load accepts duplicate keys and silently keeps the last, so FERRFLOW_BOT would have won and FERRFLOW_BENCHMARK_JSON would never have reached ferrflow. A green parse was not evidence of a valid workflow, exactly as with the mid-value >- earlier in this series.

I wrote a loader that rejects duplicates rather than trusting the default, which reproduces it and now passes:

.github/workflows/ci.yml: duplicate key 'env' at line 710
...
checked 8 file(s), 0 rejected

The unguarded JSON.parse. Also correct, and I confirmed the consequence rather than assuming it: with a truncated artifact the script exits 1, and since postBump runs after the version files are bumped and .ferrflow sets no onFailure, that aborts the release mid-flight. The three paths now behave as the description claims:

corrupt artifact -> benchmark artifact unusable (Unterminated string in JSON...)
                    no usable benchmark artifact, keeping the published numbers   exit=0
valid artifact   -> embedded benchmarks for ferrflow 9.9.9                        exit=0
no artifact      -> no usable benchmark artifact, keeping the published numbers   exit=0

On the dispatch path, which you raised without asking for a change: agreed, and I have made the comment say it rather than leave it implied. A workflow_dispatch release keeps the committed numbers because hyperfine-baseline only exists for push to main. That is the intended behaviour, since a dispatch release is not preceded by a benchmark run for that commit, but it was worth naming in the file rather than in a PR description nobody reads later.

[ferrfleet]

Both findings are fixed in aca7bad: the duplicate env: is merged into one block, and the parse is guarded so an unusable artifact logs and keeps the committed numbers instead of aborting postBump. Nothing new in the changed lines.