DOCS

Author: dg

AGENTS.md

@@ -19,7 +19,8 @@ subtler than it looks.
 inputs) through a fluent `Expect::` builder and a `Processor`.
 
 - **PHP Version**: 8.1 - 8.5
-- **Package**: `nette/schema` (dep: `nette/utils`)
+- **Package**: `nette/schema` (dep: `nette/utils`); `master` = 2.0-dev,
+  maintenance lives on `v1.x` branches
 
 ## Essential Commands
 
@@ -36,6 +37,7 @@ composer phpstan
 
 - Every file starts with `declare(strict_types=1);`; **tabs**; single quotes;
   `@internal` for implementation details, `@method` for `Expect`'s magic methods;
+  deprecations use the native `#[\Deprecated]` attribute, not phpDoc;
   Nette Coding Standard.
 - Tests are Nette Tester `.phpt` named `Expect.<feature>.phpt`; `checkValidationErrors()`
   asserts the expected error messages of a failing `process()`.

docs/internals.md

@@ -83,9 +83,8 @@ it** — and they do so in subtly different ways:
 
 This is the package's sharpest trap: a piece of control state travelling through
 the payload, replicated across five sites. Any new `Schema` element must reproduce
-the strip-and-honor dance or merging silently misbehaves. (There is a standing
-idea to replace it with a declarative `MergeMode::Replace`; DI carries its own
-parallel `PREVENT_MERGING` constant. See `docs/local/ideas/odstranit-prevent-merging.md`.)
+the strip-and-honor dance or merging silently misbehaves. (DI carries its own
+parallel `PREVENT_MERGING` constant.)
 
 ## One transform pipeline; `assert`/`castTo` are sugar over `transform`
 
@@ -181,13 +180,20 @@ by validating dynamics eagerly.
 
 ## `Expect::from()` mapping rules
 
-`Expect::from($object)` reflects **constructor parameters if `__construct`
-exists, otherwise properties** — a class with a constructor has its properties
-ignored entirely. Per item: uninitialized property / non-optional parameter →
-`required()`; a `null` default on a type that does not accept null → also
-`required()` (not "default null"); an **object** default recurses into a nested
-`from()`; anything else becomes `default($def)`. The type comes from
-`Helpers::getPropertyType` (native type, then `@var`), falling back to `mixed`.
+`Expect::from()` accepts an instance **or a class name** (since 2.0) and
+reflects **constructor parameters if `__construct` exists, otherwise
+properties** — a class with a constructor has its properties ignored entirely.
+Types come from **native declarations only** (`Nette\Utils\Type::fromReflection`,
+fallback `mixed`); phpDoc `@var` support was removed in 2.0. Per item:
+
+- a non-nullable class-typed item recurses into `from($thatClass)` **even
+  without a default** (beware: `class_exists` is also true for enums, which
+  then map badly);
+- no default (uninitialized property / non-optional parameter) → `required()`;
+- an **object** default recurses into a nested `from($default)` (instance-based);
+- any other default — including `null` — becomes `default($def)` (the 1.x rule
+  "null default on a non-nullable type → `required()`" is gone).
+
 The result is a `Structure` with `castTo($class)` **stacked after** the
 constructor's built-in `castTo('object')`, so a completed value travels
 array → `stdClass` → instance through the cast fork above.
@@ -207,4 +213,4 @@ array → `stdClass` → instance through the cast fork above.
 | DI / integration hook | `Processor::onNewContext`, `createContext` |
 | Error message rendering | `Message::toString`, `Message::*` code constants |
 | Key schemas, `isKey` | `Type::normalize`/`validateItems`, `Context::isKey` |
-| Object-to-schema mapping | `Expect::from`, `Helpers::getPropertyType` |
+| Object-to-schema mapping | `Expect::from` (native types only) |