[libgraphql-core-v1] Task 16.6d: Spec notes on all build-level errors

[jeffmo]

Summary

Task 16.6d (fourth of the six schema-hardening PRs): complete the half-landed Task 13 rule — every build-level SchemaBuildError now carries an ErrorNote::spec linking the September 2025 rule it enforces. Before this, only the four type validators attached spec notes; 42 construction sites (30 across the type builders' new()/add_*()/from_ast() paths, 12 in SchemaBuilder) returned errors with empty notes.

What & why

• Every error now teaches: each site attaches the most precise September2025 anchor, verified against the spec source. Two anchors were actively corrected in the process: duplicate type/directive definitions (and builtin redefinition) now cite #sec-Schema's uniqueness rules, and InvalidEnumValueName cites the #sec-Enum-Value grammar production ("Name but not true/false/null") instead of the enum Type-Validation section, which only covers uniqueness.
• New crate-private spec_urls module holds URL consts for rules fired from multiple sites (Reserved-Names alone fires from 17), so the notes can't diverge; the literal URL stays in the // comment above each site per the plan's convention.
• Uniform notes() surface: the TypeValidation wrapper in build() now mirrors the inner TypeValidationError's notes onto the outer SchemaBuildError, so consumers get spec notes without reaching into the inner error (documented on the accessor to avoid double-reading).
• Two deliberate exceptions, inline-commented and recorded in the plan: ParseError (grammar-level; parser-supplied notes — including the parser's own spec notes — flow through verbatim) and SourceMapLimitExceeded (a u16 implementation limit, not a spec rule).

Tests (11 new; v1 crate 284 → 295)

Eight per-builder spec-note assertions, a NoQueryOperationTypeDefined note test, a TypeValidation note-propagation test, and the guard-rail: all_build_level_errors_carry_spec_notes — a kitchen-sink invalid schema triggering 22 distinct error kinds, asserting every returned error carries a Spec note except the two documented exceptions. (Caveat recorded in the plan: it guards the kinds its fixed source reaches, so new error kinds must extend the kitchen-sink alongside their own tests.)

Verification

• cargo test --workspace — 1400 green; cargo clippy --workspace --tests -- -Dwarnings — clean
• Opus sub-agent review pre-PR: no blockers; all 10 spot-checked anchors confirmed correct against the September2025 source (including the two corrections); the three doc-level findings (site-count off-by-one, "permanently locking" overstatement, mirrored-notes doc) fixed in the follow-up commit fb8f396
• Plan doc updated with [x] boxes + Completion Notes per the Execution Protocol

🤖 Generated with Claude Code

https://claude.ai/code/session_01TipQtpvuLuHjHmRsVEgwJw

[Copilot]

Pull request overview

This PR standardizes GraphQL spec-references across build-level schema construction errors in libgraphql-core-v1 by attaching ErrorNote::spec(...) notes (and keeping inline URL comments) everywhere SchemaBuildError is created, and by ensuring wrapped TypeValidation errors propagate their notes to the outer build error.

Changes:

• Introduces a crate-private spec_urls module to centralize spec URL constants used by multiple error sites.
• Adds ErrorNote::spec(...) notes to build-level error construction sites in type builders and SchemaBuilder.
• Adds/extends tests to assert spec-note presence and to verify note propagation for wrapped TypeValidation errors.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
libgraphql-core-v1-plan.md	Marks Task 16.6d complete and documents the scope/anchor decisions and tests added.
crates/libgraphql-core-v1/src/spec_urls.rs	New centralized spec URL constants for reuse across many error sites.
crates/libgraphql-core-v1/src/lib.rs	Exposes spec_urls as a crate-private module.
crates/libgraphql-core-v1/src/type_builders/object_type_builder.rs	Adds spec notes to reserved-name and type-validation build errors.
crates/libgraphql-core-v1/src/type_builders/interface_type_builder.rs	Adds spec notes to reserved-name and interface type-validation build errors.
crates/libgraphql-core-v1/src/type_builders/union_type_builder.rs	Adds spec notes to reserved-name and union type-validation build errors.
crates/libgraphql-core-v1/src/type_builders/scalar_type_builder.rs	Adds spec notes to reserved-name build errors.
crates/libgraphql-core-v1/src/type_builders/input_object_type_builder.rs	Adds spec notes to reserved-name and input-object type-validation build errors.
crates/libgraphql-core-v1/src/type_builders/field_def_builder.rs	Adds spec notes to reserved-name and duplicate-parameter build errors.
crates/libgraphql-core-v1/src/type_builders/enum_type_builder.rs	Adds spec notes and corrects anchor selection for invalid enum value names.
crates/libgraphql-core-v1/src/type_builders/tests/builder_validation_tests.rs	Adds per-builder tests asserting spec notes are present with expected anchors.
crates/libgraphql-core-v1/src/schema/schema_builder.rs	Adds spec notes for schema-build errors and propagates TypeValidationError notes to the wrapping SchemaBuildError.
crates/libgraphql-core-v1/src/schema/tests/schema_builder_tests.rs	Adds tests for root-op spec notes, note propagation, and a meta-test enforcing spec-note coverage (with documented exceptions).

---

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