An omitted argument reads a constant table under the key its own default

names

Author: AJenbo

docs/CHANGELOG.md

@@ -125,6 +125,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **An array literal keeps the values it was written with.** `[1, 1.5, '123']` says exactly what it holds, but the values were widened to `int|float|string` the moment they were stored, so reading an entry back could not be proven to be anything the individual values were. Handing `$values[$key]` to a parameter or return type of `numeric` was reported, even though every entry of the array is numeric on its own, and the same held for a literal key: `$values[2]` read as `string` rather than as the numeric `'123'` written at that position. The values a literal names now survive into its type, so a read off it, a `foreach` over it, and an inferred `@return` all see them, and a key that is only known at runtime resolves to the set of entries the array actually has. Widening now happens where the array is changed instead: a push or a keyed write says the array is being built up rather than written out, so the value arriving there stands in for however many more follow. An alternative already covered by a broader sibling is folded away, so a list mixing a plain `string` with two string literals stays `list<string>`, and a literal naming more distinct values than a set of alternatives is worth reasoning about falls back to the base types.
 - **A constant table constrains a plain signature too.** `@param key-of<ID_TABLE>` says a parameter takes one of the table's keys, and `@return value-of<ID_TABLE>` says the result is one of its values. PHPantom only looked behind the constant's name while working out a call's `@template` bindings, which a function that declares no `@template` never does, so both tags widened to whatever a key or a value could be in general: `acceptsKey('nope')` went unreported, and a return that can only ever be `int|string` was read as `mixed`. The constant is now read wherever a declared parameter or return type names one, so an untemplated function or method is held to the table's own keys and hands back the table's own values. The declaration reads the same way from inside the body: the parameter holds the keys the table has, so hover names them and passing one on is judged against them, and a `@return` naming the table is held to what the table holds, so returning a key the table does not have is reported where it is written. The `Class::TABLE` and `self::TABLE` spellings read the same way, and a constant that cannot be reached, or whose value is not an array literal, still widens rather than being guessed at.
 - **A lookup into a constant table reads as the entry its key names.** A constant holding an array literal is the ordinary way to write a table of settings, and a function that reads one out of it can say so: `@template T of key-of<ID_TABLE>` with `@return ID_TABLE[T]` names the value under whichever key the caller passed. PHPantom read neither tag, because the docblock only ever sees the constant's *name* and nothing looked behind it, so the declaration's own `int|string` stood for every call and `takesInt(lookUp('immutable'))` was reported for passing a `string`. The constant's initializer is now read where a type operator asks for it, so each call resolves to its own entry: hover names it, argument checks judge against it, and a key the table does not hold is still rejected. The `Class::TABLE` spelling reads the same way, and a constant whose value is not an array literal is left alone rather than guessed at.
+- **An omitted argument reads a constant table under the key its own default names.** `@template T of key-of<ID_TABLE>` with `@return ID_TABLE[T]` resolves to a single entry at every call site that writes the key out, but a parameter carrying its own default (`function lookUp(string $type = 'immutable')`) bound nothing when the caller left the argument off, so `lookUp()` fell back to the whole table's value union and `takesInt(lookUp())` was reported for passing a string the call can never return. A default value is as known at the declaration site as an argument is at the call site, so it now binds the template the same way: `lookUp()` resolves exactly as `lookUp('immutable')` does, for a method as much as for a function.
 - **A `for` loop's update clause carries its type into the next iteration.** `for ($node = $head; $node !== null; $node = $node->next)` is how a linked list is walked by hand, and the reassignment in the update clause counted for nothing. The clause was read far enough to hover and navigate the variables in it, but the type it produced was never fed back into the loop, so the body saw whatever the initialiser bound on the first trip through on every trip, and the variable kept that type after the loop as well, even where the update clause was the only thing that could have changed it. The clause now runs where PHP runs it, after the body and before the condition is checked again: the body sees the type the update produces alongside the one the initialiser bound, and a walk that ends because it ran out of nodes leaves the cursor holding `null` rather than the node it started from. The initialisers stay the one-time seed they are, so a variable the update clause retypes is no longer reset to its starting type.
 - **Arithmetic on a refined `int` no longer widens to `int|float`.** `int + int` is `int`, and that held for the bare spelling, but `strlen()`, `count()`, and most of the standard library's counting functions are declared with a refinement like `int<0,max>` rather than plain `int`, and accumulating one of those (`$length += strlen($text);`) read as an unrecognised operand and fell back to the conservative `int|float`, reported several lines away at the function's `return` rather than at the addition that caused it. Every `int` refinement (`positive-int`, `non-negative-int`, `int<min,max>`, and the rest) is now classified as `int` for arithmetic, and the same holds for `float`'s own refinements.
 - **A generic type argument is no longer coerced away.** A file that does not `declare(strict_types=1)` lets PHP convert a `'7'` handed to an `int` parameter, and that leniency was applied to type arguments as well, so a `Box<string>` where a `Box<int>` was required came back compatible and the class-hierarchy check that had the last word compared the two by name and called it a `Box`. Nothing is converted inside a value that is passed on whole, so the arguments are now compared without the juggling rules whatever the file declares, on arguments, returns, and property assignments alike. A class with type arguments that cannot be reconciled with the declared ones is also settled on those arguments rather than on its name, so a future reader of the type engine's own subtype check gets the same answer the diagnostics do. What we cannot prove still passes, unchanged: an argument our inference had to widen, one a `@template-contravariant` declaration means to be wider, a class named without its type arguments, and a name that could be the same class written unqualified.

docs/todo.md

@@ -102,7 +102,6 @@ unlikely to move the needle for most users.
 | D5  | [External tool diagnostic suppression actions](todo/diagnostics.md#d5-external-tool-diagnostic-suppression-actions)                                                         | Low         | Low         |
 | D15 | [Unused parameter diagnostic](todo/diagnostics.md#d15-unused-parameter-diagnostic)                                                                                          | Low         | Low         |
 |     | **[Bug Fixes](todo/bugs.md)**                                                                                                                                               |             |             |
-| B97 | [`CONSTANT[T]` reads as the whole table when `T` comes from a parameter's default value](todo/bugs.md#b97-constantt-reads-as-the-whole-table-when-t-comes-from-a-parameters-default-value) | Low-Medium  | Medium      |
 | B96 | [A docblock `@param` type narrower than its native nullable type hint is not flagged](todo/bugs.md#b96-a-docblock-param-type-narrower-than-its-native-nullable-type-hint-is-not-flagged) | Low         | Medium      |
 |     | **[Code Actions](todo/actions.md)**                                                                                                                                         |             |             |
 | A40 | [Generate method from call](todo/actions.md#a40-generate-method-from-call)                                                                                                  | Medium-High | Medium      |

docs/todo/bugs.md

@@ -40,35 +40,3 @@ or an array type. Only Qodana flags either case in
 documented parameter/return type against its native type hint for
 compatibility, most likely reusing the existing type-compatibility check
 rather than a new one.
-
-### B97. `CONSTANT[T]` reads as the whole table when `T` comes from a parameter's default value
-
-**Impact: Low-Medium · Effort: Medium**
-
-```php
-const ID_TABLE = ['immutable' => 1, 'mutable' => 'two'];
-
-/**
- * @template T of key-of<ID_TABLE>
- * @param T $type
- * @return ID_TABLE[T]
- */
-function lookUp(string $type = 'immutable'): int|string {
-    return ID_TABLE[$type];
-}
-
-takesInt(lookUp('immutable')); // passes: correctly reads as int
-takesInt(lookUp());            // reported: got 1|'two' — should also read as int
-```
-
-Per-key resolution of `CONSTANT[T]` (a template bound to `key-of<CONSTANT>`)
-now works correctly when the call site passes the key as an explicit literal
-argument, but falls back to the whole table's value union specifically when
-the caller omits the argument and the template binds from the parameter's
-*default* value instead. The default value (`'immutable'`) is known at
-the declaration site the same way an explicit argument is known at the call
-site, so `lookUp()` should resolve identically to `lookUp('immutable')`.
-
-**Fix:** wherever the explicit-argument case resolves `T` to the literal
-passed at the call site, apply the same resolution when the argument is
-omitted and a literal default value is available.

examples/demo.php

@@ -965,6 +965,11 @@ public function demo(): void
         $ink = scaffoldingToolDefault('ink');      // TOOL_DEFAULTS['ink'] → 'black'
         var_dump(strtoupper($ink));
 
+        // An omitted argument binds the template from the parameter's own
+        // default, which is as known here as a key written at the call site.
+        $fallback = scaffoldingDefaultToolSetting();  // TOOL_DEFAULTS['ink'] → 'black'
+        var_dump(strtoupper($fallback));
+
         // The class-constant spelling reads the same way.
         $retries = ScaffoldingLimits::lookUp('retries');
         var_dump($retries + 1);                    // LIMITS['retries'] → 3
@@ -3150,7 +3155,7 @@ public function returnType(): GtdResult { return new GtdResult(); }
      * @return GtdResult                           Ctrl+Click GtdResult
      * @throws GtdNotFoundException                Ctrl+Click GtdNotFoundException
      */
-    public function docblockTypes($items) { return $items; }
+    public function docblockTypes($items) { return new GtdResult(); }
 
     /**
      * Callable types in docblocks. Ctrl+Click on any class name inside the
@@ -6691,6 +6696,16 @@ function scaffoldingToolDefault(string $setting): int|string
     return TOOL_DEFAULTS[$setting];
 }
 
+/**
+ * @template T of key-of<TOOL_DEFAULTS>
+ * @param T $setting
+ * @return TOOL_DEFAULTS[T]
+ */
+function scaffoldingDefaultToolSetting(string $setting = 'ink'): int|string
+{
+    return TOOL_DEFAULTS[$setting];
+}
+
 /** @param key-of<TOOL_DEFAULTS> $setting */
 function scaffoldingToolSettingName(string $setting): string
 {
@@ -7653,6 +7668,7 @@ function runDemoAssertions(): void
     // ── Constant table read through a type operator ─────────────────────
     assert(scaffoldingToolDefault('width') === 2, "TOOL_DEFAULTS['width'] really is the int 2");
     assert(scaffoldingToolDefault('ink') === 'black', "TOOL_DEFAULTS['ink'] really is the string 'black'");
+    assert(scaffoldingDefaultToolSetting() === 'black', "an omitted argument really reads the entry its default names");
     assert(ScaffoldingLimits::lookUp('retries') === 3, "LIMITS['retries'] really is the int 3");
     assert(ScaffoldingLimits::lookUp('label') === 'off', "LIMITS['label'] really is the string 'off'");
     assert(scaffoldingToolSettingName('ink') === 'ink', "'ink' really is one of TOOL_DEFAULTS' keys");

src/type_engine/call_resolution/template_subs.rs

@@ -82,37 +82,50 @@ impl Backend {
                 .and_then(|p| p.type_hint.as_ref());
             let binding_mode = classify_template_binding(tpl_name, param_hint);
 
+            let tpl_bound = method.template_param_bounds.get(&atom(tpl_name));
+
             let arg_text = match bound.get(param_idx).and_then(|o| o.as_deref()) {
                 Some(text) => text,
                 None => {
                     let default_value = method
                         .parameters
                         .get(param_idx)
                         .and_then(|p| p.default_value.as_deref());
-                    match &binding_mode {
-                        TemplateBindingMode::ClassStringInner => match default_value {
-                            Some(d) if !subs.contains_key(tpl_name.as_str()) => d,
-                            None => continue,
-                            _ => continue,
-                        },
-                        TemplateBindingMode::Direct => match default_value {
-                            Some(d)
-                                if !subs.contains_key(tpl_name.as_str())
-                                    && (d == "null" || d.ends_with("::class")) =>
-                            {
-                                d
-                            }
+                    // A template bounded by a type operator resolves
+                    // against the one literal it binds to, and an omitted
+                    // argument has such a literal whenever the parameter
+                    // declares a scalar default — known at the declaration
+                    // site exactly as an explicit argument is known at the
+                    // call site.
+                    match default_value {
+                        Some(d)
+                            if !subs.contains_key(tpl_name.as_str())
+                                && type_operator_bound_literal(tpl_bound, d).is_some() =>
+                        {
+                            d
+                        }
+                        _ => match &binding_mode {
+                            TemplateBindingMode::ClassStringInner => match default_value {
+                                Some(d) if !subs.contains_key(tpl_name.as_str()) => d,
+                                None => continue,
+                                _ => continue,
+                            },
+                            TemplateBindingMode::Direct => match default_value {
+                                Some(d)
+                                    if !subs.contains_key(tpl_name.as_str())
+                                        && (d == "null" || d.ends_with("::class")) =>
+                                {
+                                    d
+                                }
+                                _ => continue,
+                            },
                             _ => continue,
                         },
-                        _ => continue,
                     }
                 }
             };
 
-            if let Some(literal) = type_operator_bound_literal(
-                method.template_param_bounds.get(&atom(tpl_name)),
-                arg_text,
-            ) {
+            if let Some(literal) = type_operator_bound_literal(tpl_bound, arg_text) {
                 crate::type_engine::variable::rhs_resolution::insert_or_union(
                     &mut subs,
                     tpl_name.to_string(),

src/type_engine/variable/rhs_resolution/calls.rs

@@ -86,27 +86,42 @@ pub(crate) fn build_function_template_subs(
             .parameters
             .get(param_idx)
             .and_then(|p| p.default_value.as_deref());
+        let tpl_bound = func_info
+            .template_param_bounds
+            .get(&crate::atom::atom(tpl_name));
         let arg_text: &str = match provided_arg {
             Some(text) => text,
-            None => match &binding_mode {
-                TemplateBindingMode::ClassStringInner => match default_value {
-                    Some(d) => d,
-                    None => continue,
-                },
-                TemplateBindingMode::Direct => match default_value {
-                    Some(d) if d.ends_with("::class") => d,
+            // A template bounded by a type operator resolves against the
+            // one literal it binds to, and an omitted argument has such a
+            // literal whenever the parameter declares a scalar default —
+            // known at the declaration site exactly as an explicit
+            // argument is known at the call site.
+            None => match default_value {
+                Some(d)
+                    if crate::type_engine::call_resolution::type_operator_bound_literal(
+                        tpl_bound, d,
+                    )
+                    .is_some() =>
+                {
+                    d
+                }
+                _ => match &binding_mode {
+                    TemplateBindingMode::ClassStringInner => match default_value {
+                        Some(d) => d,
+                        None => continue,
+                    },
+                    TemplateBindingMode::Direct => match default_value {
+                        Some(d) if d.ends_with("::class") => d,
+                        _ => continue,
+                    },
                     _ => continue,
                 },
-                _ => continue,
             },
         };
 
-        if let Some(literal) = crate::type_engine::call_resolution::type_operator_bound_literal(
-            func_info
-                .template_param_bounds
-                .get(&crate::atom::atom(tpl_name)),
-            arg_text,
-        ) {
+        if let Some(literal) =
+            crate::type_engine::call_resolution::type_operator_bound_literal(tpl_bound, arg_text)
+        {
             insert_or_union(&mut subs, tpl_name.to_string(), literal);
             continue;
         }