Skip to content

docs(surface): hide impl-detail re-exports + clarify schema_version + dogfood note#124

Merged
luofang34 merged 1 commit intomainfrom
pr/0.1.5-public-surface-trim
May 2, 2026
Merged

docs(surface): hide impl-detail re-exports + clarify schema_version + dogfood note#124
luofang34 merged 1 commit intomainfrom
pr/0.1.5-public-surface-trim

Conversation

@luofang34
Copy link
Copy Markdown
Owner

@luofang34 luofang34 commented May 2, 2026

Summary

Three shrink-and-document moves toward a leaner pre-1.0 public surface, no code-behavior change:

  • evidence-core lib.rs: re-exports split into a curated public surface (~36 items, grouped by external use case) and a #[doc(hidden)] implementation-detail block (~38 leaf items: BoundaryViolation, BranchCoverage, FixHint, sha256, rules_json, TraceMeta, etc.). Hidden items stay reachable via their owning module path for workspace callers and contract tests; they drop off rustdoc.
  • schema_versions.rs + README "Project Status": spell out that the on-disk schema_version field is informational during pre-1.0 — pinned at 0.0.1 across breaking shape changes, not a compatibility contract. Consumers should pin a cargo-evidence workspace version (read engine_crate_version in index.json) instead of pattern-matching the literal.
  • CONTRIBUTING.md: new "Dogfooding doctor / hint / MCP behavior changes" section. The installed binary on $PATH is the wrong test target when iterating on user-facing output. Use cargo run --bin cargo-evidence -- evidence doctor for direct CLI work; cargo install --path crates/cargo-evidence --path crates/evidence-mcp --force before re-invoking the MCP wrapper. MCP_VERSION_SKEW catches binary-vs-binary drift but not workspace-vs-binary drift.

This is the first of two planned pre-1.0-honesty PRs. The follow-up (separate) renames the HMAC envelope away from "signature" terminology (sign_bundlecompute_bundle_mac, BUNDLE.sigBUNDLE.mac, SYS-001 wording) so the project stops calling a shared-secret MAC a digital signature. That PR will trip the cross-time determinism gate and will use the Override-Deterministic-Baseline: protocol; this one does not.

Test plan

  • cargo fmt --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace --all-targets (all green; floors_equal_current_no_slack passes)
  • RUSTDOCFLAGS='-D missing_docs -D rustdoc::broken_intra_doc_links' cargo doc --workspace --no-deps
  • cargo evidence trace --validateTRACE_OK
  • cargo evidence floors --format=jsonlFLOORS_OK
  • cargo evidence doctor → no DOCTOR_FLOORS_SLACK, all checks [✓]
  • CI green on push (cross-host + Nix flavors)

🤖 Generated with Claude Code

… dogfood note

Three shrink-and-document moves toward a leaner pre-1.0 public surface:

- evidence-core lib.rs splits re-exports into a curated public surface
  and a #[doc(hidden)] implementation-detail block. ~38 leaf items
  (BoundaryViolation, BranchCoverage, FixHint, sha256, rules_json,
  TraceMeta, etc.) drop off rustdoc but stay reachable for workspace
  callers and contract tests via their owning module path. Curated
  surface is now ~36 items grouped by external use case (verify,
  build, compliance, trace, rules, coverage thresholds).

- schema_versions.rs and README "Project Status" spell out that the
  on-disk `schema_version` field is informational during pre-1.0:
  pinned at 0.0.1 across breaking shape changes, not a compatibility
  contract. Consumers should pin a `cargo-evidence` workspace version
  (read `engine_crate_version` in index.json) instead of pattern-
  matching the literal.

- CONTRIBUTING gains a "Dogfooding doctor / hint / MCP behavior
  changes" section: the installed binary on $PATH is the wrong test
  target when iterating on user-facing output. Use
  `cargo run --bin cargo-evidence -- evidence doctor` for direct
  CLI changes; `cargo install --path crates/cargo-evidence --path
  crates/evidence-mcp --force` before re-invoking the MCP wrapper.
  MCP_VERSION_SKEW only catches binary-vs-binary drift, not workspace-
  vs-binary drift.

No code-behavior change; rustdoc-only and docs-only edits. Local
fmt/clippy/doc/test/trace/floors all green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@luofang34 luofang34 merged commit a5cec5b into main May 2, 2026
15 checks passed
@luofang34 luofang34 deleted the pr/0.1.5-public-surface-trim branch May 2, 2026 05:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants