Reorganize test suite by functionality (orthogonal to source structure)

[ocots]

Summary

This PR completes the full three-phase test suite overhaul for CTModels.jl, bringing all files into conformance with the testing standards, filling targeted coverage gaps, and adding contract/LSP tests.

---

Phase 1 — Uniform cleanup (all files, low risk) ✅

1a — Structural reorganization

Reorganizes test/suite/ from a source-aligned structure to a functionality-aligned one.

Directory	Content
suite/components/	Shared types, aliases, accessors, time-dependence traits
suite/models/	Immutable Model type, readers, user-facing predicates
suite/building/	PreModel, mutators, validation, defaults, build
suite/solutions/	Solution, time grids, dual model, interpolation
suite/init/	Initial guess construction, validation, API
suite/serialization/	Import/export to disk (JLD2, JSON)
suite/display/	Pretty-printing of models and solutions
suite/extensions/	Weak-dependency extension tests (e.g. Plots)
suite/integration/	End-to-end tests spanning multiple modules
suite/meta/	Aqua.jl code-quality checks, export verification, type hierarchy

• Removed empty shells: suite/ocp/, suite/exceptions/, suite/initial_guess/
• Renamed 40 test files to match the new structure
• Updated module names and entry functions in 4 files: test_components.jl, test_model_types.jl, test_solution_types.jl, test_building_exceptions.jl
• Updated test/README.md with new directory structure and examples

1b — Submodule-qualified imports and calls

• Imports replaced with explicit submodule imports (import CTModels.Building: Building, etc.) across all 44 files
• All call sites converted from CTModels.foo to Submodule.foo following the canonical symbol-to-submodule map
• Removed 36 empty placeholder testsets "Abstract Types" (noise)
• test_plot.jl: kept import CTModels: CTModels (needed for Base.get_extension)
• Project.toml / docs/Project.toml: widened CTBase compat to "0.18, 0.19"

---

Phase 2 — Coverage gaps + quality tests ✅

File	What was added
building/test_dedup.jl (new)	6 direct testsets on Building._dedup_box_constraints! + build(ConstraintsDictType) unknown-type error path
components/test_components.jl	Empty sentinels (EmptyControlModel, EmptyVariableModel, EmptyDefinition), StateModelSolution/ControlModelSolution accessors, time accessors, has_mayer_cost/has_lagrange_cost
models/test_model.jl	is_autonomous/has_variable traits, free-time branches (scalar and vector), mayer/lagrange error stubs, get_build_examodel, missing label, @inferred and @allocated quality assertions
solutions/test_dual_model.jl	Label :nonexistent → IncorrectArgument error path
init/test_initial_guess_validation.jl	Scalar variable on vdim=0, :variable block on problem without variable

---

Phase 3 — Contract/LSP tests, export verification, retro-compat ✅

File	What was added
components/test_contracts.jl (new)	Top-level fakes for AbstractStateModel, AbstractControlModel, AbstractVariableModel, AbstractModel; generic LSP contract checkers; mayer/lagrange/initial_time/final_time stubs on AbstractModel → PreconditionError
meta/test_CTModels.jl	Verify CTModels top-level exports only :CTModels (tenet #1); full list of symbols announced by Components
serialization/test_multi_grids.jl	Retro-compat: JSON with legacy key time_grid_dual imported correctly as time_grid_path
display/test_print.jl	Smoke tests show(Model) autonomous and with optimisation variable

---

Test results

• ✅ 3614 + 237 = 3851 tests pass across all three phases — zero regressions
• ✅ Test organization is orthogonal to the source file structure
• ✅ All imports and call sites are submodule-qualified throughout the suite
• ✅ Coverage gaps on Building, Solutions, Models, Init addressed
• ✅ Quality assertions (@inferred, @allocated) added
• ✅ Contract/LSP coverage for all abstract types
• ✅ Export invariants verified

---

Rationale

The previous structure mirrored the source layout (suite/ocp/ for src/OCP/) and used bare CTModels.foo calls, both in violation of the testing standards. This PR brings the full test suite into conformance:

• Orthogonality: tests grouped by functionality, not by source file
• Qualified imports: every call site uses Submodule.symbol, making intent explicit and namespace ownership clear
• Completeness: targeted gaps on risky branches, internal functions, and abstract-type contracts are now covered

[ocots]

Refactor docstrings for Solutions module

This commit completes the docstring refactoring for the Solutions module, following the same standards applied to Models and Serialization modules.

Changes:

• Added # Returns and # Arguments sections to all accessors in build_solution.jl (20 functions: state, control, variable, costate, times, dimensions)
• Added # Returns and See also: to dual accessors in dual_model.jl (8 functions)
• Added See also: to interpolation helpers in interpolation_helpers.jl (3 functions)
• Enriched Solutions.jl module docstring with # Public API, # Dependencies, # See also sections
• Ensured all cross-references use full paths (CTModels.Solutions., CTModels.Models.)

Conformity:

• All docstrings now conform to project standards with active descriptions and complete sections
• Consistent with Models and Serialization modules
• All tests pass (3734 tests)