feat: improve customization and public contracts - #9
Merged
Conversation
Why: the deleted snapshots repeated coverage already provided by the end-to-end config editing tests and turned unrelated metadata changes into hundreds of lines of review noise. Keeping only the observable path-editing assertions makes this consumer scenario easier to understand and maintain. Signed-off-by: tison <wander4096@gmail.com>
Why: full Debug snapshots locked the derive tests to incidental field ordering and formatting while hiding which Serde contract each test protected. Focused assertions make regressions in names, defaults, tagging, bounds, and recursion visible without penalizing unrelated metadata additions. Signed-off-by: tison <wander4096@gmail.com>
Why: Serde serializes Cow through its borrowed target but deserializes into its owned target. Delegating both directions to one side reports the wrong shape and can require a Shape bound that Serde itself does not require, so each direction must follow the corresponding Serde contract. Signed-off-by: tison <wander4096@gmail.com>
Why: the wire representation of Serde from, try_from, and into containers is already defined by the conversion type. Treating it as opaque discards exact information that documentation and configuration consumers need, so the derive now reuses the proxy type shape directly. Signed-off-by: tison <wander4096@gmail.com>
Why: custom Serde functions and foreign types are necessarily opaque to the derive, and downstream crates cannot add Shape implementations to foreign types because of orphan rules. Directional serde_shape overrides give callers a local, explicit way to state the real representation without moving consumer policy into serde-shape. Signed-off-by: tison <wander4096@gmail.com>
Why: the no_std snapshots tested Debug output rather than the properties that matter on alloc-only targets. Direct assertions retain coverage for derive expansion, nested containers, and recursive definitions while removing the final snapshot-only dependency from the workspace. Signed-off-by: tison <wander4096@gmail.com>
Why: configuration references, CLI help, and diagnostics need the same user-facing descriptions that already live beside Rust fields and variants. Carrying doc comments in shape metadata avoids a second description registry and keeps generated documentation synchronized with the source type. Signed-off-by: tison <wander4096@gmail.com>
Why: callers could mutate roots and definition lists or forge arbitrary ShapeId values, producing dangling graph references that failed only during later traversal. Read-only accessors and graph-issued identifiers make invalid states harder to construct while preserving zero-copy inspection. Signed-off-by: tison <wander4096@gmail.com>
Why: the previous compile-time wording implied that complete graphs were constants and carried no runtime construction cost. Derive generates metadata code at compile time, but graph allocation happens when a shape method is called, so the package description must set the correct performance and ownership expectations. Signed-off-by: tison <wander4096@gmail.com>
Why: users otherwise risk persisting graph-local IDs and Debug output as a schema format or assuming unions are specialized for one serializer. Stating the persistence, format-mode, and description contracts up front prevents consumers from building on guarantees the crate does not provide. Signed-off-by: tison <wander4096@gmail.com>
Why: this series contains intentional API migrations alongside fixes and additions, and reviewers or early adopters need one place to identify required call-site changes. The changelog records user-visible impact without mixing test and implementation detail into release notes. Signed-off-by: tison <wander4096@gmail.com>
Why: the repository has distinct behavior boundaries for core, derive, integration, and no_std tests, but contributors had no guidance on where a regression belongs or which cargo x commands define success. A short guide keeps new tests focused and discourages another accumulation of broad snapshots and speculative abstractions. Signed-off-by: tison <wander4096@gmail.com>
Why: documentation is part of this library public API, yet broken intra-doc links and docsrs-only warnings were discoverable only after publishing. Running rustdoc with warnings denied inside cargo x lint makes the normal local and CI workflow catch those failures before release. Signed-off-by: tison <wander4096@gmail.com>
Why: Cargo copies the workspace README into each crate package but does not include the repository-level license and contributor files beside it. Absolute repository links keep those references working when the README is rendered from a crates.io package. Signed-off-by: tison <wander4096@gmail.com>
tisonkun
force-pushed
the
codex/improve-library-usability
branch
from
August 29, 2026 12:56
459a0e2 to
eded2c0
Compare
Why: most derive tests care about the metadata inside a named root, but each one repeated the same graph navigation and missing-definition failure handling. Shared directional helpers keep those tests focused on their Serde contract, while recursion tests continue to inspect ShapeId values explicitly because graph identity is the behavior under test. Signed-off-by: tison <wander4096@gmail.com>
Why: type-only overrides make a convenience form the extension boundary and force callers to invent proxy types for representations that do not correspond to one Rust type. Function hooks can build arbitrary ShapeRef values or delegate to existing Shape implementations while composing through the active graph context. Signed-off-by: tison <wander4096@gmail.com>
Why: the badge should point to the canonical Apache 2.0 license page instead of a branch-relative repository file, which can move with repository layout or default-branch changes. Signed-off-by: tison <wander4096@gmail.com>
Why: repository-internal documentation links should follow the checked-out branch and work in forks and local renderers instead of hard-coding one GitHub default-branch URL. Signed-off-by: tison <wander4096@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is structured for commit-by-commit review. Every commit message contains a
Why:paragraph explaining the user problem, the design boundary, and why that change belongs inserde-shape; the PR description is intentionally not a second design document.ScopeQL-specific traversal and configuration policy remain outside this library. The commits add only the reusable shape information and escape hatches that such consumers need.
Validation completed before the history rewrite (the rewritten tree is identical):
cargo x build --lockedcargo x testcargo x lintthumbv7em-none-eabihfno-std checkscargo package --lockedfor both published crates