Fix crashes and silent misvalidation in object-implied compositions, reject non-representable ones

[wol-soft]

Summary

Gives the generator a principled way to decide whether a schema without an explicit
type: object is, statically, an object — and to fail generation loudly instead of silently
misbehaving when it isn't. Fixes the composition bugs originally reported against a FedEx OpenAPI
schema, plus several pre-existing defects found while verifying that work.

Fixed bugs

Issue	Bug	Symptom before
#72	Object-implied compositions were not recognised	Generation crashed with No nested schema for composed property, or the composed property was never instantiated (getCEO() returned a raw array despite a nested @return)
#182	A base-level $ref dropped the referenced schema's object-level constraints	additionalProperties, minProperties, propertyNames and any root composition were never validated; an object could be constructed in an invalid state and only fail later with a PHP TypeError from a typed getter
#183	A base-level $ref to a root anyOf/oneOf was always rejected	A referenced schema on base level must provide an object definition, even when every branch declared type: object. The same composition written inline worked — a $ref did not behave like the schema it points at
#184	A literal true composition branch never warned	{}, example-only and annotation-only branches warned; the most explicit "matches anything" spelling stayed silent

Fixes #72, fixes #182, fixes #183, fixes #184.

Not filed as issues because they were introduced and fixed inside this branch, so no release ever
contained them: wrong composition-element numbering in direct-exception mode, a target-side
generation failure being reported as Unresolved Reference, an unreachable guard in
withoutNestedCompositionValidation(), and the representability check pre-empting three precise
diagnostics (see Undecidable shapes below).

A later review pass on this branch found four more of the same kind, all fixed here:

• An allOf branch declaring a type list containing "object" was rejected as conflicting with
  an object-asserting sibling — so allOf: [<object>, {"type": ["object", "null"]}], the ordinary
  "referenced type, but nullable" shape, failed generation. The conflict check inferred "scalar
  branch" from the absence of a nested schema, which a multi-type branch also lacks.
• Two cross-file $ref shapes broke because the representability check ran before the schema was
  registered for deduplication, and its $ref peek re-enters processTopLevelSchema(): two files
  referencing each other recursed until the stack was exhausted, and a target referencing back built
  a duplicate render job (File X.php already exists).
• A composition keyword given as a JSON object instead of an array raised a raw
  TypeError: Unsupported operand types: string + int from the new 1-based branch numbering. It,
  and a branch that is not a schema at all, now raise a SchemaException naming the keyword and
  branch. (not and if/then/else crashed the same way on a scalar branch — pre-existing, but
  hardened alongside.)

How it works

ObjectShape and ObjectShapeResolver statically classify a schema by resolving $ref chains and
composition keywords. Wired into PropertyFactory::create() so that:

• An allOf whose branches jointly guarantee object-ness is routed through the real object path —
  a generated class, instantiated, validated with instanceof — even when no individual branch
  declares type: object.
• A schema carrying only object-constraining keywords with no type gets a guarded
  representation: object values are instantiated and validated, non-object values pass through
  unchanged per strict JSON Schema semantics, with a generation-time warning since this is easy to
  write by accident.
• allOf branches with contradictory types (an object-asserting branch alongside an explicit
  scalar-typed branch) are rejected at generation time instead of producing silently broken code.
• The vacuous-branch warning is driven by the Draft's own registered validator keywords rather than
  a hardcoded list, so it works for custom Drafts.

Class-defining compositions must resolve to a definite object

Excluding "vacuous" (e.g. example-only) branches from composition matching was rejected during
review as not spec-compliant — a schema that also matches non-object values genuinely cannot be
represented by the single class a file root, or a $ref target parsed as its own schema, produces.

SchemaProcessor::checkObjectRepresentability() closes that gap the spec-compliant way: a
class-defining composition that does not resolve to ObjectAsserting is rejected, unless
GeneratorConfiguration::setImplicitObjectComposition() is enabled (default false) as an opt-in
escape hatch for object-describing compositions. ObjectShapeResolver classifies if/then/else
for this too — an aggregate asserts object-ness only when both then and else do.

Undecidable shapes

The classifier separates "decidably not an object" from "object-ness cannot be determined here"
(an unresolvable or cyclic $ref, a filter-bearing schema). Only the former is rejected;
an undecidable shape is handed back to the pipeline so the subsystem that owns it — $ref
resolution, the filter machinery — reports its own precise, correctly-attributed error.

This matters because the representability check runs before any property processing, so without the
distinction it pre-empted the unresolved-reference and filter-compatibility diagnostics with a
generic message naming the wrong cause. A $ref to a boolean definition is deliberately not
undecidable: JsonSchema::$json is typed array, so the target is known and unrepresentable, and
routing it back to the pipeline would resurface the uncaught TypeError this branch replaced with
a clean SchemaException.

$ref siblings follow the draft

Since the $ref-sibling rework landed on master, whether keywords beside a $ref apply is decided
per draft: Draft 07 registers $ref as an ExclusiveProducer and ignores them, Draft 2019-09 and
later apply them alongside the reference. ObjectShapeResolver::classifyReference() reads the
draft's own $ref producer and follows it rather than restating the policy — a classifier that
merged siblings regardless would reject allOf: [{$ref: <object>, "type": "string"}] under Draft 07,
which the generator builds without complaint because the type is ignored there.

checkObjectRepresentability()'s $ref exemption covers sibling-bearing roots for the same reason:
the reference resolution that follows already implements whichever rule is in force.

Breaking changes

Release notes are composed separately for 1.0; these are the entries this PR contributes.

• A class-defining composition that only describes object shape now raises a SchemaException.
  This hits the common OpenAPI inheritance shape when the base omits type: object, and a schema
  root carrying properties plus if/then without else. Fix by adding "type": "object", or
  by enabling setImplicitObjectComposition(true). Two schemas in this repo's own test suite
  needed "type": "object" added.

• Three further root shapes that previously generated are now rejected. The opt-in flag provably
  cannot rescue any of them (it only widens acceptance from asserting to describing), so the message
  names declaring the type as the fix but deliberately does not offer the flag:

  • {"type": ["object", "null"], ...} — a multi-type root permits a non-object value the single
    generated class cannot represent. The generated constructor only ever took an array, so such a
    root previously produced a class that could not accept its own schema's null.
  • a composition containing a vacuous branch ({}, true, annotation-only), which matches every
    value.
  • an empty composition ({"allOf": []}, {"anyOf": []}), which constrains nothing at all.
    Previously a warning plus a class that accepted anything.

  Add "type": "object" (or remove the vacuous branch) to generate these. The suggestion is worded
  conditionally in the message, because unlike the object-describing case above these schemas really
  do accept non-object values — declaring the type changes what they accept rather than stating what
  they already mean, and only the author knows whether that was the intent.

• An array items schema carrying only object-constraining keywords with no type now gets a
  guarded representation class: object items are instantiated and validated, non-object items pass
  through unchanged per strict spec, and generation warns. Previously no item class was generated at
  all and the item constraints were silently dropped, so input that used to be accepted may now be
  correctly rejected.

• An allOf of $refs to object schemas no longer produces a _Merged_ class. Such a composition
  guarantees an object, so it is routed through the object path and the property is typed with a
  regular nested class instead (X_Merged_Ceo → X_Ceo), which also changes the accessor
  signatures from mixed to that class. This makes the $ref form behave like the inline form,
  which already generated a plain nested class. anyOf is unaffected and remains the only keyword
  that produces a merged property.

• An allOf-implied object property carrying an object default now fails generation, consistent
  with an explicit type: object property, which has always rejected object defaults.

• Composition error messages in direct-exception mode now enumerate every branch with its reason,
  matching collect-errors mode — except for a root composition generated with
  setImmutable(false), where both composition templates still gate the enumeration on
  isMutableBaseValidator. That gap is pinned by a test and tracked in the follow-up.

• Composition branch numbering in the vacuous-branch warning and in the filter-in-branch
  SchemaException is now 1-based, matching the runtime Composition element #N numbering.
  Previously both counted from zero.

• A base-level $ref now enforces the referenced schema's object-level constraints (A base-level $ref silently drops the referenced schema's object-level constraints #182), so
  input that was previously accepted may now be correctly rejected. Such a $ref to a root
  anyOf/oneOf now generates instead of being refused (A base-level $ref to a root anyOf/oneOf is always rejected, even when it is a definite object #183), and a failure inside the
  referenced schema reports that schema's own error rather than Unresolved Reference.

• A literal true composition branch now emits the vacuous-branch warning (A literal true composition branch never emits the vacuous-branch warning #184).

Known follow-up

#181, shipping in the
same release, so the two land as a single migration. Deliberately not auto-closed by this PR:

• The representability check and its flag currently affect the file root and cross-file $ref
  targets only; named properties, array items and dependencies targets bypass it. A root carrying
  only object keywords with no composition keyword is skipped entirely — no class, no message —
  under either setting of the flag.
• The composition branch type-inheritance mechanism (inheritPropertyType()) is largely redundant
  once representability is validated upfront, and actively corrupts a branch in two proven cases:
  an allOf branch with a scalar enum becomes an unsatisfiable {type: object, enum: [...]}
  (this PR warns about it; removing the injection is the fix), and the injected type suppresses the
  vacuous-branch warning for every non-boolean spelling.
• $ref to a boolean schema cannot be represented, because JsonSchema cannot carry a boolean.
  A reproduction of the named-property variant (which escapes as an uncaught TypeError, unlike the
  root variant's clean SchemaException) is recorded in the Follow-up: broaden object-representability checks and reconsider forced type inheritance in compositions #181 thread.
• Branch enumeration in direct-exception mode skips mutable base validators.

Filed separately, since it is independent of #181 and pre-existing on master:
#189 — {"type": ["object"]} is classified as an object by ObjectShapeResolver but cannot be routed as one, so
such a schema either fails with a misattributed No nested schema for composed property or is
skipped with no diagnostic at all. This branch makes the divergence visible rather than causing it:
the representability check now approves a root the pipeline then refuses to build.

Test plan

• Merged with master at 7cff736 (the $ref-sibling rework and the multi-draft infrastructure).
• Full suite green — 3230 tests, 8197 assertions, no failures — and phpcs clean on every file this
  branch touches. CI green on PHP 8.4 and 8.5.
• New/updated coverage: ObjectShapeResolverTest, ComposedObjectShapeValidationTest,
  ComposedAllOfTest, Issue72Test, ReferencePropertyTest, ComposedOneOfBranchDefaultTest.
• Every defect found in review has a regression test: the multi-type branch in both its inline and
  $ref spellings, the two cross-file recursion shapes, malformed composition keywords across
  allOf/anyOf/oneOf/not/then, the empty-composition roots, the bare object-describing array
  item, and the dependencies site's force-asserting asymmetry (which was recorded nowhere before).
• Two shapes found while probing are filed as issues rather than pinned as tests: a test asserting a
  TypeError or a misattributed message documents a bug as if it were a contract.
• Inline/$ref parity is asserted through a shared assertion helper covering both accepted
  branches and both rejection modes, so the two forms must behave identically rather than merely
  both generating.
• Each restored diagnostic is asserted against the owning subsystem's own message, not the
  representability message, so a regression surfaces as a named failure.
• The draft-dependent $ref sibling policy is pinned both as a unit matrix (Draft 07 vs 2019-09)
  and end to end.
• See docs/source/combinedSchemas/impliedObjects.rst and docs/source/gettingStarted.rst for the
  user-facing documentation, including setImplicitObjectComposition().
• mergedProperty.rst, allOf.rst and oneOf.rst were corrected against generated output rather
  than from reading the code: anyOf is the only keyword that produces a merged property
  (OneOfValidatorFactory never calls createMergedProperty() at all), and the page's headline
  allOf example had documented a _Merged_ class that is not generated. The allOf-inline and
  oneOf claims were already stale on master; only the $ref-based allOf form changed here.

[coveralls]

Coverage Report for CI Build 31640503194

Coverage increased (+0.07%) to 98.88%

Details

• Coverage increased (+0.07%) from the base build.
• Patch coverage: 4 uncovered changes across 3 files (453 of 457 lines covered, 99.12%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
src/SchemaProcessor/SchemaProcessor.php	76	74	97.37%
src/Model/Validator/Factory/Composition/AbstractCompositionValidatorFactory.php	175	174	99.43%
src/PropertyProcessor/ObjectShape/ObjectShapeResolver.php	90	89	98.89%
Total (15 files)	457	453	99.12%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	8037
Covered Lines:	7947
Line Coverage:	98.88%
Coverage Strength:	594.55 hits per line

---

💛 - Coveralls