Merge remote-tracking branch 'origin/master'

Author: wol-soft

CLAUDE.md

@@ -1,5 +1,23 @@
 # CLAUDE.md
 
+## Responding to review notes
+
+When working through a list of review notes, critically evaluate each note before acting on it:
+
+- **Is the note correct?** The reviewer may be mistaken about what the code does, or may be
+  operating on a false assumption. If the note is factually wrong, explain why and skip it.
+- **Is the proposed fix better than the current approach?** The reviewer's suggestion is a
+  starting point, not a mandate. If a different solution is clearly superior, propose it.
+- **Is there an even better solution?** Think beyond the note. If the reviewer flags a smell,
+  consider whether the right fix is the one they suggest or a deeper redesign.
+- **Document the reasoning.** For each note, produce a summary of what action was taken and why
+  — including why any note was rejected or handled differently than suggested.
+
+After tackling all notes, provide a summary table: one row per note, action taken, and brief
+reasoning.
+
+---
+
 ## Learning from reviews
 
 After completing a task that involved responding to code review feedback, scan the reviewer's

docs/source/combinedSchemas/mergedProperty.rst

@@ -102,3 +102,34 @@ This schema will generate three classes as no merged property is created. The ma
     public function setName(string $name): static
     public function getAge(): ?int
     public function setAge(int $age): static
+
+Branch-constraint isolation
+---------------------------
+
+When the same property name appears in multiple composition branches with different constraints
+(e.g. one ``oneOf`` branch requires an ``enum`` value while another allows a free-form string),
+the outer merged class does **not** inherit branch-specific constraints from any individual
+branch. Validation constraints such as ``enum``, ``minLength``, or ``pattern`` remain scoped to
+their respective branch and are enforced only when that branch is being validated.
+
+This means that the ``EnumPostProcessor`` and similar post-processors will correctly operate on
+the branch-level property — not on the outer merged property — so the generated merged class
+setter accepts the full union of allowed values from all branches rather than being narrowed to
+the constraints of a single branch.
+
+Attributes for shared properties
+---------------------------------
+
+When ``JSON_POINTER`` or ``JSON_SCHEMA`` attributes are enabled (see
+`Attributes <../gettingStarted.html#attributes>`__), properties that appear in more than one
+composition branch receive synthesised attributes:
+
+- **JSON_POINTER**: one ``#[JsonPointer]`` attribute is emitted per branch that defines the
+  property. When the property is also declared in the root ``properties`` block, the root
+  pointer is prepended.
+
+- **JSON_SCHEMA**: a single ``#[JsonSchema]`` attribute is emitted whose value is a synthesised
+  JSON object containing the composition keyword (``allOf``, ``anyOf``, ``oneOf``, or
+  ``if``/``then``/``else`` sub-objects) with only those branch sub-schemas that involve this
+  property. Root-level constraints are merged into the top-level object when the property is
+  also root-registered.

docs/source/gettingStarted.rst

@@ -320,6 +320,9 @@ The following attributes are available:
    * - JSON_POINTER
      - Classes & Properties
      - Adds a JSON Pointer with the path in the source Schema. This attribute can't be disabled.
+       For properties that appear in multiple composition branches (e.g. ``oneOf``, ``allOf``),
+       one ``#[JsonPointer]`` attribute is emitted per defining branch, plus one for the
+       root-level definition when the property is also declared in the top-level ``properties`` block.
      - Yes
    * - SCHEMA_NAME
      - Properties
@@ -331,7 +334,11 @@ The following attributes are available:
      - No
    * - JSON_SCHEMA
      - Classes & Properties
-     - Provides the full JSON Schema used to generate the class or the property
+     - Provides the full JSON Schema used to generate the class or the property.
+       For properties transferred from composition branches, the attribute value is
+       *synthesised*: it contains the composition keyword (e.g. ``oneOf``) with only the
+       branch-level sub-schemas that define this property, merged with any root-level
+       constraints when the property is also declared in the top-level ``properties`` block.
      - No
    * - REQUIRED
      - Properties

src/Model/Attributes/AttributesTrait.php

@@ -11,12 +11,20 @@ trait AttributesTrait
     /** @var PhpAttribute[] */
     private array $phpAttributes = [];
 
+    public function filterAttributes(callable $filter): static
+    {
+        $this->phpAttributes = array_values(array_filter($this->phpAttributes, $filter));
+
+        return $this;
+    }
+
     public function addAttribute(
         PhpAttribute $attribute,
         ?GeneratorConfiguration $generatorConfiguration = null,
         ?int $enablementFlag = null,
     ): static {
-        if ($generatorConfiguration
+        if (
+            $generatorConfiguration
             && $enablementFlag
             && ($generatorConfiguration->getEnabledAttributes() & $enablementFlag) === 0
         ) {

src/Model/Property/AbstractProperty.php

@@ -4,8 +4,10 @@
 
 namespace PHPModelGenerator\Model\Property;
 
+use PHPModelGenerator\Attributes\JsonPointer;
 use PHPModelGenerator\Exception\SchemaException;
 use PHPModelGenerator\Model\Attributes\AttributesTrait;
+use PHPModelGenerator\Model\Attributes\PhpAttribute;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchema;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchemaTrait;
 use PHPModelGenerator\Utils\NormalizedName;
@@ -36,6 +38,16 @@ public function __construct(protected string $name, JsonSchema $jsonSchema)
         $this->attribute = $this->processAttributeName($this->name);
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function setJsonSchema(JsonSchema $jsonSchema): static
+    {
+        $this->jsonSchema = $jsonSchema;
+
+        return $this;
+    }
+
     /**
      * @inheritdoc
      */
@@ -56,6 +68,18 @@ public function getAttribute(bool $variableName = false): string
         return ($this->isInternal() ? '_' : '') . $attribute;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function overrideJsonPointer(PhpAttribute $attribute): static
+    {
+        $this->filterAttributes(
+            static fn(PhpAttribute $existing): bool => $existing->getFqcn() !== JsonPointer::class,
+        );
+
+        return $this->addAttribute($attribute);
+    }
+
     /**
      * Convert a name of a JSON-field into a valid PHP variable name to be used as class attribute
      *

src/Model/Property/PropertyInterface.php

@@ -169,12 +169,23 @@ public function getNestedSchema(): ?Schema;
      */
     public function getJsonSchema(): JsonSchema;
 
+    public function setJsonSchema(JsonSchema $jsonSchema): static;
+
+    public function filterAttributes(callable $filter): static;
+
     public function addAttribute(
         PhpAttribute $attribute,
         ?GeneratorConfiguration $generatorConfiguration = null,
         ?int $enablementFlag = null,
     ): static;
 
+    /**
+     * Replace the JsonPointer attribute with one carrying the given pointer value.
+     * Used by processReference to set the reference site's pointer on a resolved property
+     * rather than the definition's pointer.
+     */
+    public function overrideJsonPointer(PhpAttribute $attribute): static;
+
     /**
      * @return PhpAttribute[]
      */

src/Model/Property/PropertyProxy.php

@@ -4,6 +4,8 @@
 
 namespace PHPModelGenerator\Model\Property;
 
+use PHPModelGenerator\Attributes\JsonPointer;
+use PHPModelGenerator\Attributes\SchemaName;
 use PHPModelGenerator\Exception\SchemaException;
 use PHPModelGenerator\Model\Attributes\PhpAttribute;
 use PHPModelGenerator\Model\GeneratorConfiguration;
@@ -21,6 +23,9 @@
  */
 class PropertyProxy extends AbstractProperty
 {
+    private ?JsonSchema $overrideJsonSchema = null;
+    private ?PhpAttribute $overrideJsonPointer = null;
+
     /**
      * PropertyProxy constructor.
      *
@@ -296,7 +301,20 @@ public function getNestedSchema(): ?Schema
      */
     public function getJsonSchema(): JsonSchema
     {
-        return $this->getProperty()->getJsonSchema();
+        return $this->overrideJsonSchema ?? $this->getProperty()->getJsonSchema();
+    }
+
+    /**
+     * @inheritdoc
+     *
+     * Stores a local override rather than delegating to the underlying property, preventing
+     * mutation of a shared $ref-resolved property when only this proxy's schema must change.
+     */
+    public function setJsonSchema(JsonSchema $jsonSchema): static
+    {
+        $this->overrideJsonSchema = $jsonSchema;
+
+        return $this;
     }
 
     /**
@@ -317,6 +335,16 @@ public function isInternal(): bool
         return $this->getProperty()->isInternal();
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function filterAttributes(callable $filter): static
+    {
+        $this->getProperty()->filterAttributes($filter);
+
+        return $this;
+    }
+
     /**
      * @inheritdoc
      */
@@ -330,11 +358,45 @@ public function addAttribute(
         return $this;
     }
 
+    /**
+     * Store the pointer attribute locally so this proxy can show a different JsonPointer from
+     * the shared underlying property (each reference site has its own pointer).
+     */
+    public function overrideJsonPointer(PhpAttribute $attribute): static
+    {
+        $this->overrideJsonPointer = $attribute;
+
+        return $this;
+    }
+
     /**
      * @inheritdoc
+     *
+     * Replaces the SchemaName attribute from the underlying shared property with one that
+     * carries the proxy's own name. Two proxies sharing the same $ref definition would
+     * otherwise both report the first property's name via the shared underlying attribute.
+     *
+     * When a JsonPointer override is set, all existing JsonPointer attributes (there may be
+     * multiple when the underlying property was synthesised from composition branches) are
+     * removed and replaced with a single attribute pointing to the reference site.
      */
     public function getAttributes(): array
     {
-        return $this->getProperty()->getAttributes();
+        $attributes = array_map(
+            fn(PhpAttribute $attribute): PhpAttribute => $attribute->getFqcn() === SchemaName::class
+                ? new PhpAttribute(SchemaName::class, [$this->name])
+                : $attribute,
+            $this->getProperty()->getAttributes(),
+        );
+
+        if ($this->overrideJsonPointer !== null) {
+            $attributes = array_values(array_filter(
+                $attributes,
+                static fn(PhpAttribute $attribute): bool => $attribute->getFqcn() !== JsonPointer::class,
+            ));
+            $attributes[] = $this->overrideJsonPointer;
+        }
+
+        return $attributes;
     }
 }

src/Model/Schema.php

@@ -63,6 +63,9 @@ class Schema
     /** @var callable[] */
     private array $onAllPropertiesResolvedCallbacks = [];
 
+    /** @var array<string, true> */
+    private array $rootRegisteredPropertyNames = [];
+
     /** @var string[] Maps normalized attribute → raw property name; used to detect property-vs-property collisions */
     private array $attributeIndex = [];
 
@@ -204,7 +207,7 @@ public function addProperty(PropertyInterface $property, ?string $compositionPro
             $this->properties[$property->getName()] = $property;
 
             if ($compositionProcessor === null) {
-                $this->propertyMerger->markRootRegistered($property->getName());
+                $this->rootRegisteredPropertyNames[$property->getName()] = true;
             }
 
             $property->onResolve(function (): void {
@@ -224,11 +227,22 @@ public function addProperty(PropertyInterface $property, ?string $compositionPro
             $this->properties[$property->getName()],
             $property,
             is_a($compositionProcessor, AllOfValidatorFactory::class, true),
+            $this->isRootRegistered($property->getName()),
         );
 
         return $this;
     }
 
+    public function isRootRegistered(string $name): bool
+    {
+        return isset($this->rootRegisteredPropertyNames[$name]);
+    }
+
+    public function getProperty(string $name): ?PropertyInterface
+    {
+        return $this->properties[$name] ?? null;
+    }
+
     /**
      * @return PropertyValidatorInterface[]
      */

src/Model/Validator/ConditionalPropertyValidator.php

@@ -4,6 +4,7 @@
 
 namespace PHPModelGenerator\Model\Validator;
 
+use LogicException;
 use PHPModelGenerator\Exception\ComposedValue\ConditionalException;
 use PHPModelGenerator\Model\GeneratorConfiguration;
 use PHPModelGenerator\Model\Property\CompositionPropertyDecorator;
@@ -20,6 +21,9 @@ class ConditionalPropertyValidator extends AbstractComposedPropertyValidator
     /** @var CompositionPropertyDecorator[] */
     private array $conditionBranches;
 
+    private ?CompositionPropertyDecorator $thenBranch;
+    private ?CompositionPropertyDecorator $elseBranch;
+
     public function __construct(
         GeneratorConfiguration $generatorConfiguration,
         PropertyInterface $property,
@@ -41,6 +45,8 @@ public function __construct(
         $this->compositionProcessor = IfValidatorFactory::class;
         $this->composedProperties = $composedProperties;
         $this->conditionBranches = $conditionBranches;
+        $this->thenBranch = $validatorVariables['thenProperty'] ?? null;
+        $this->elseBranch = $validatorVariables['elseProperty'] ?? null;
     }
 
     /**
@@ -53,6 +59,35 @@ public function getConditionBranches(): array
         return $this->conditionBranches;
     }
 
+    /**
+     * Returns the if-condition branch.
+     *
+     * The if branch is always present — ConditionalPropertyValidator cannot be constructed
+     * without a valid if schema (IfValidatorFactory throws SchemaException otherwise).
+     */
+    public function getIfBranch(): CompositionPropertyDecorator
+    {
+        foreach ($this->composedProperties as $composedProperty) {
+            if (!in_array($composedProperty, $this->conditionBranches, true)) {
+                return $composedProperty;
+            }
+        }
+
+        // @codeCoverageIgnoreStart
+        throw new LogicException('ConditionalPropertyValidator has no if branch — this is a bug.');
+        // @codeCoverageIgnoreEnd
+    }
+
+    public function getThenBranch(): ?CompositionPropertyDecorator
+    {
+        return $this->thenBranch;
+    }
+
+    public function getElseBranch(): ?CompositionPropertyDecorator
+    {
+        return $this->elseBranch;
+    }
+
     /**
      * Initialize variables required by the conditional validator.
      */