[libgraphql-core-v1] Task 16.6e: Hygiene, from_str family, Schema::resolve_span

[jeffmo]

Summary

Task 16.6e (fifth of six schema-hardening PRs): the hygiene sweep + the two small public APIs the Task 16.5 audit found claimed-but-missing.

What & why

• SchemaBuilder::from_str — named by the API-Disposition ledger but never implemented (only load_str/build_from_str existed). Inherent method mirroring the other string entry points (FromStr deliberately avoided — it would force a trait import for a builder convenience); build_from_str now delegates through it. Error type mirrors load_str's load-phase shape, documented on the method.
• Source labels for multi-source schemas — v1 hardcoded SchemaSourceMap::from_source(source, None), so diagnostics from multi-document schemas couldn't name their source (a silent v0 regression: v0's load_str took Option<&Path>). New from_str_with_label / load_str_with_label / build_from_str_with_label variants (impl AsRef<Path>) thread the label into SchemaSourceMap.file_path; unlabeled entry points keep their clean signatures; all share a private load_str_impl. Task 19's operation builders copy this shape.
• Schema::resolve_span(Span) -> Option<LineCol> — AD18 lists it as public API but nothing implemented it. Indexes the schema's source maps by the span's source_map_id (None out of range); rustdoc states the schema-originated-span-only domain per AD18's cross-artifact rule, the 0-based LineCol semantics, the byte-offset column approximation (source maps store line_starts only), and builtin→0:0.
• Hygiene: stale "build() is currently todo!()" rustdoc in validators/mod.rs replaced with accurate module docs; the completed TODO(Task 16) in union_type_validator.rs removed; the dead #[allow(dead_code)] mutation_type_name() builder accessor deleted (the field remains; build() reads it directly — removal verified reference-free).
• schema_def test coverage — the typed query API had zero dedicated tests; new schema_def_tests.rs covers typed lookups (incl. kind-mismatch → None), typed iterators, types_implementing(), root-op accessors, and resolve_span with hand-computed positions on a multi-line schema.
• Zeroed 9 pre-existing cargo doc warnings (broken/wrong-crate intra-doc links, private-item links) — semantic fixes, not silencing.

Tests

17 new tests + 2 running doctests (v1 crate 295 → 310 + 10 doctests). Highlights: two-source label-threading test asserting per-source file_path, per-document source_map_id, and cross-document line resolution; hand-verified resolve_span positions; out-of-range → None; builtin → 0:0.

Verification

• cargo test --workspace — 1417 green; cargo clippy --workspace --tests -- -Dwarnings — clean; cargo doc --no-deps -p libgraphql-core-v1 — 0 warnings
• Opus sub-agent review: no blockers; independently re-derived the resolve_span test's line_starts/position math, confirmed the build_from_str delegation is behaviorally identical on error paths, verified all three spot-checked doc-link fixes are semantic, and confirmed the label-threading test exercises real cross-document resolution. Its one worthwhile nit (error-type rationale in rustdoc) applied as the follow-up commit.
• Plan doc updated with [x] boxes + Completion Notes per the Execution Protocol

🤖 Generated with Claude Code

https://claude.ai/code/session_01TipQtpvuLuHjHmRsVEgwJw

---

Generated by Claude Code

[Copilot]

Pull request overview

Implements Task 16.6e for libgraphql-core-v1 by hardening schema-building ergonomics and diagnostics: adds the missing SchemaBuilder::from_str API family (including label-threading variants), implements Schema::resolve_span, and performs hygiene/doc fixes with expanded schema_def test coverage.

Changes:

• Added SchemaBuilder::from_str plus _with_label variants across the load_str / from_str / build_from_str family, threading labels into SchemaSourceMap::file_path.
• Implemented Schema::resolve_span(Span) -> Option<LineCol> using the schema’s stored source maps.
• Cleaned up stale docs/dead code and added new schema_def tests covering typed lookups/iterators, root-op accessors, and span resolution.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
libgraphql-core-v1-plan.md	Marks Task 16.6e complete and documents the API/design outcomes.
crates/libgraphql-core-v1/src/validators/union_type_validator.rs	Updates validator docs to reflect current build wiring.
crates/libgraphql-core-v1/src/validators/mod.rs	Converts stale item docs to accurate module-level docs with correct link.
crates/libgraphql-core-v1/src/types/field_definition.rs	Adjusts rustdoc to avoid broken intra-doc link (but introduces internal-task wording).
crates/libgraphql-core-v1/src/span.rs	Fixes rustdoc link for ByteSpan.
crates/libgraphql-core-v1/src/schema/tests/schema_def_tests.rs	Adds dedicated typed schema API + resolve_span tests.
crates/libgraphql-core-v1/src/schema/tests/schema_builder_tests.rs	Adds tests for from_str and label threading across multi-source schemas.
crates/libgraphql-core-v1/src/schema/tests/mod.rs	Wires in the new schema_def_tests module.
crates/libgraphql-core-v1/src/schema/schema_def.rs	Adds Schema::resolve_span public API implementation + rustdoc.
crates/libgraphql-core-v1/src/schema/schema_builder.rs	Adds from_str and label variants; refactors shared load_str_impl; threads labels into SchemaSourceMap.
crates/libgraphql-core-v1/src/schema_source_map.rs	Clarifies docs and links Schema explicitly.
crates/libgraphql-core-v1/src/error_note.rs	Fixes intra-doc links and span type reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.