felis-terminal/felis

Watch

Hide internal plumbing and drop the build-stamp scripts before publishing #190

Merged

natsukium merged 3 commits from api/hidden-internals into main

2026-10-19 14:15:11 +09:00

natsukium commented

2026-10-19 13:08:30 +09:00

Owner

Pre-publish refactor for #160. Each commit is one step:

grid, daemon, render-wgpu: #[doc(hidden)] on pub items that are pub only because another workspace crate reaches them. They stay usable, but they leave the rendered docs, and cargo-semver-checks stops treating them as public API.
- daemon: the embedder surface stays visible: serve_unix, SessionPool::new, ServeError, TERMINFO_SOURCE, serve::DaemonCaps, and the types its fields name (HandshakeDeadlines, IdlePolicy, ConnectionAdmission, Shutdown, AgentLink, UpgradeState).
- grid: keeps ClusterTable, LinkTable and LinkText visible, because visible signatures and sibling consumers name them. The *_CAP constants are hidden.
- Other crates: whatever the sibling repos import, or docs/reference/ names, stays visible.
shaping, render-core, transport: testing and test-util keep their names. The manifests state they are test-only and outside semver, and the items they gate are #[doc(hidden)].
cli, client, daemon: the three build.rs files and crates/build-common.rs are deleted. The build scripts include! a file outside every package, so no published tarball could build. Their git fallback would also stamp an unrelated repository's revision when the crate is built from the registry.
- Stamp: the binaries now read FELIS_GIT_HASH via option_env!. Nix and the Windows CI jobs already set it, so release artifacts are unchanged. A bare cargo build reports unknown.
- Bench provenance: tools/bench/envinfo.py now flags an unknown stamp as drift. Before, it credited the checkout's revision to the binary.

Verification:

just check passes.
nix build .#felis binaries report the real revision.
docs/reference/workspace.md (stamping paragraph), nix/package.nix and the cargo-env action comment are updated.

Pre-publish refactor for #160. Each commit is one step: - **grid, daemon, render-wgpu:** `#[doc(hidden)]` on pub items that are pub only because another workspace crate reaches them. They stay usable, but they leave the rendered docs, and cargo-semver-checks stops treating them as public API. - **daemon:** the embedder surface stays visible: `serve_unix`, `SessionPool::new`, `ServeError`, `TERMINFO_SOURCE`, `serve::DaemonCaps`, and the types its fields name (`HandshakeDeadlines`, `IdlePolicy`, `ConnectionAdmission`, `Shutdown`, `AgentLink`, `UpgradeState`). - **grid:** keeps `ClusterTable`, `LinkTable` and `LinkText` visible, because visible signatures and sibling consumers name them. The `*_CAP` constants are hidden. - **Other crates:** whatever the sibling repos import, or `docs/reference/` names, stays visible. - **shaping, render-core, transport:** `testing` and `test-util` keep their names. The manifests state they are test-only and outside semver, and the items they gate are `#[doc(hidden)]`. - **cli, client, daemon:** the three `build.rs` files and `crates/build-common.rs` are deleted. The build scripts `include!` a file outside every package, so no published tarball could build. Their git fallback would also stamp an unrelated repository's revision when the crate is built from the registry. - **Stamp:** the binaries now read `FELIS_GIT_HASH` via `option_env!`. Nix and the Windows CI jobs already set it, so release artifacts are unchanged. A bare `cargo build` reports `unknown`. - **Bench provenance:** `tools/bench/envinfo.py` now flags an `unknown` stamp as drift. Before, it credited the checkout's revision to the binary. Verification: - `just check` passes. - `nix build .#felis` binaries report the real revision. - `docs/reference/workspace.md` (stamping paragraph), `nix/package.nix` and the `cargo-env` action comment are updated.

natsukium added 3 commits

2026-10-19 13:08:30 +09:00

grid, daemon, render: hide internal plumbing from the public API ca45c48c5f

These items are pub only because another workspace crate reaches them,
and pub(crate) cannot express that. Before the first crates.io publish,
doc(hidden) takes them out of the rendered docs and out of what
cargo-semver-checks treats as public, so changing them does not force a
breaking bump. The daemon keeps the embedder surface (serve_unix,
SessionPool::new, DaemonCaps and the types its fields name,
TERMINFO_SOURCE); grid and render-wgpu keep what the sibling consumers
import. Doc links from visible items to hidden ones are unlinked.

shaping, render, transport: mark the test-support features unstable b3f4b6f381

The testing and test-util features stay under their names, since a
leading underscore would not stop a registry user enabling them
either. What a published crate can say is that they are test-only and
outside the semver contract: the manifest states it, and the items they
gate (and the pinned test-font family name) are doc(hidden) so
cargo-semver-checks does not hold them to the public API.

cli, client, daemon, docs: stamp the build from FELIS_GIT_HASH alone

fuzz / cargo fuzz nightly long-run (pull_request) Has been skipped

Details

darwin / detect relevant changes (pull_request) Successful in 8s

Details

darwin / darwin docs-only no-op (pull_request) Has been skipped

Details

windows / detect relevant changes (pull_request) Successful in 17s

Details

windows / windows docs-only no-op (pull_request) Has been skipped

Details

darwin / build felis (aarch64-darwin) (pull_request) Successful in 1m11s

Details

windows / cargo nextest (Windows) (pull_request) Successful in 2m53s

Details

windows / frontend smoke (Windows) (pull_request) Successful in 58s

Details

bench / instruction-count regression gate (pull_request) Successful in 2m5s

Details

fuzz / cargo fuzz smoke (per target) (pull_request) Successful in 1m21s

Details

pr / nix flake check (pull_request) Successful in 1m10s

Details

pr / cargo build / clippy / test / deny (pull_request) Successful in 2m28s

Details

pr / wire schema is compatible with the base (pull_request) Successful in 7s

Details

pr / frontend smoke (x86_64-linux) (pull_request) Successful in 1m5s

Details

windows / cargo clippy (Windows cross) (pull_request) Successful in 27s

Details

c988a51cc1

The three binary crates' build scripts include!d a file outside every
package, so none of them would build from a published tarball. Their
git fallback is also wrong for a registry build: it runs git from the
extracted source, so a CARGO_HOME inside some repository stamps that
repository's revision. The binaries now read FELIS_GIT_HASH through
option_env!, and BuildIdentity validates it as before; the abbreviated
--version line is derived from the parsed identity. Nix and the Windows
CI jobs set the variable, so the release gate sees the same stamps; a
bare cargo build reports unknown, which the bench provenance now flags.

natsukium merged commit 6cbc7a73fe into main

2026-10-19 14:15:11 +09:00

natsukium deleted branch api/hidden-internals

2026-10-19 14:15:11 +09:00

natsukium referenced this pull request from a commit

2026-10-19 14:15:13 +09:00

Merge pull request 'Hide internal plumbing and drop the build-stamp scripts before publishing' (#190) from api/hidden-internals into main