Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 20 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,17 @@ The run in `main.go` is a three-stage pipeline over the project's PHP files:
reprint the file, leaving untouched code byte-for-byte.

Skip rules: parameters that already have a type; parameters with conflicting
types (ambiguous); parameters passed into a type check like `is_array($param)`
or `gettype($param)` in the body, as they accept more than one type; magic methods except `__construct`; methods that may override
a parent or interface (including vendor), unless private or a constructor.
types (ambiguous) or any unresolved argument (a variable); parameters seen only
from call sites in tests; a default value of another type; a wider `@param` doc
type; parameters type checked in the body (`is_array($param)`, `gettype()`,
`instanceof`, `=== false`), as they accept more than one type; magic methods
except `__construct`; methods that may override a parent, interface or trait
(including vendor), or that a child class overrides, unless private or a
constructor.

Setters (`set*`) of Doctrine entities, marked by `#[ORM\Entity]` or
`@ORM\Entity`, always get a nullable type, since forms and hydrators may pass
null.

## Packages (`internal/`)

Expand Down Expand Up @@ -80,9 +88,15 @@ Run the same command locally before pushing.
`valuetype.Object(fqcn)` checked with `IsObject()` and read with `Class()`.
`Null` becomes nullability, `Callable` (from a closure argument) poisons the
parameter so it is never typed. `apply.typeText` turns an object into `\X`.
- **Unresolved arguments** produce a record with an empty `Type`. It never adds
a type, but marks the group as not fully literal, which blocks the
`'a'|'b'` docblock (`aggregate.group.nonLiterals`).
- **Unresolved arguments** produce a record with an empty `Type`. It blocks
the parameter: `aggregate.Types` returns it found with no `Types`, so apply
skips it and does not fall back to the default value type either.
- **Unresolved receivers** (`$x->m(1)`, `parent::m(1)`) record by method name
only (empty `Class`). `aggregate.Types.Method` requires them to agree with
the class type, else the parameter is blocked.
- **Inherited calls** - `main.go` rewrites a record's class to the class that
declares the method (`inherit.DeclaringClass`), so `$this->m()` in a child
counts for the parent method.
- **Lookup keys use fully qualified, lowercased class names**
(`app\entity\foo`, via `phpast.ClassKey`): `collect` records carry the fully
qualified name, and `aggregate.Types` keys, `symbols` enums/class consts and
Expand Down
47 changes: 30 additions & 17 deletions internal/aggregate/aggregate.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@ import (
)

// Resolved is the final type decision for one parameter position. Two or more
// types observed for the same parameter are ambiguous and left unresolved, as is
// a parameter with any argument whose type could not be resolved.
// types, a callable or an unresolved argument leave Types empty: the parameter
// was seen at a call site but must stay untyped.
type Resolved struct {
Types []valuetype.Type // exactly one type, never Null
Types []valuetype.Type // exactly one type, never Null; empty when blocked
Nullable bool
Literals []string // sorted string literal values, set only for a plain string type, see literalValues
}
Expand All @@ -34,9 +34,12 @@ type group struct {
// set when a string other than a plain literal, or an unresolved value, was
// passed - the literals then no longer cover every argument
nonLiterals bool
// set when an argument type could not be resolved - it may be any type, so
// the parameter is left untyped
// set when an argument type could not be resolved, e.g. a variable - it may
// be anything, so the parameter must stay untyped
unresolved bool
// set when a call site lies outside tests; tests pass fixture values while
// production may call through a container, form or hydrator instead
production bool
}

// Types holds resolved parameter types keyed for fast lookup during apply.
Expand All @@ -46,10 +49,19 @@ type Types struct {
functions map[string]Resolved // function \x00 position
}

// Method returns the resolved type for a method/constructor parameter.
// Method returns the resolved type for a method/constructor parameter. Calls on
// an unresolved receiver, recorded by method name only, may target this method
// too, so they must agree with its type, else the parameter is blocked.
func (t Types) Method(class, method string, position int) (Resolved, bool) {
resolved, ok := t.methods[methodKey(class, method, position)]
return resolved, ok
byName, byNameOK := t.methods[methodKey("", method, position)]
if !byNameOK {
return resolved, ok
}
if !ok || len(resolved.Types) == 0 || len(byName.Types) == 0 || resolved.Types[0] != byName.Types[0] {
return Resolved{}, true
}
return Resolved{Types: resolved.Types, Nullable: resolved.Nullable || byName.Nullable}, true
}

// Function returns the resolved type for a function parameter.
Expand All @@ -60,7 +72,7 @@ func (t Types) Function(name string, position int) (Resolved, bool) {

// Resolve groups records per parameter into a resolved type: a single observed
// type, with null captured as nullability. Unions and parameters with an
// unresolved argument are skipped.
// unresolved argument are blocked.
func Resolve(records []collect.Record) Types {
methodTypes := map[string]*group{}
functionTypes := map[string]*group{}
Expand All @@ -85,35 +97,33 @@ func resolveGroups(groups map[string]*group) map[string]Resolved {
resolved := map[string]Resolved{}

for key, group := range groups {
// an unresolved argument may pass any type, narrowing to the literal
// ones seen elsewhere would break that call site
if group.unresolved {
continue
}

types := make([]valuetype.Type, 0, len(group.types))
for typeName := range group.types {
types = append(types, typeName)
}
slices.Sort(types)
types = dedupeClasses(types)

// a callable argument (a closure) leaves the parameter untyped, since a
// callable can take many shapes that must not be narrowed
if contains(types, valuetype.Callable) {
// an unresolved argument may be anything, a parameter seen only from
// tests may get other values in production, and a callable argument (a
// closure) can take many shapes - all leave the parameter untyped
if group.unresolved || !group.production || contains(types, valuetype.Callable) {
resolved[key] = Resolved{}
continue
}

// a DateTime argument leaves the parameter untyped, as it often accepts a
// string or any DateTimeInterface too
if slices.ContainsFunc(types, isDateTime) {
resolved[key] = Resolved{}
continue
}

nullable := contains(types, valuetype.Null)
members := without(types, valuetype.Null)
// only a single type is added, unions are left untyped
if len(members) != 1 {
resolved[key] = Resolved{}
continue
}
resolved[key] = Resolved{Types: members, Nullable: nullable, Literals: literalValues(members, group)}
Expand Down Expand Up @@ -144,6 +154,9 @@ func addRecord(groups map[string]*group, key string, record collect.Record) {
if groups[key] == nil {
groups[key] = &group{types: map[valuetype.Type]struct{}{}, literals: map[string]struct{}{}}
}
if !record.InTest {
groups[key].production = true
}
switch {
case record.Type == valuetype.Unknown:
groups[key].nonLiterals = true
Expand Down
41 changes: 28 additions & 13 deletions internal/aggregate/aggregate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ func TestResolveMethod(t *testing.T) {
records []collect.Record
wantType string // members joined by "|"
wantNullable bool
wantFound bool
wantFound bool // found with an empty wantType means blocked
}{
{
name: "single type",
Expand All @@ -39,7 +39,7 @@ func TestResolveMethod(t *testing.T) {
{Class: "A", Name: "m", Type: "int"},
{Class: "A", Name: "m", Type: "string"},
},
wantFound: false,
wantFound: true,
},
{
name: "two real types with null are skipped",
Expand All @@ -48,15 +48,15 @@ func TestResolveMethod(t *testing.T) {
{Class: "A", Name: "m", Type: "string"},
{Class: "A", Name: "m", Type: "null"},
},
wantFound: false,
wantFound: true,
},
{
name: "unresolved argument is skipped",
name: "unresolved argument blocks the type",
records: []collect.Record{
{Class: "A", Name: "m", Type: "int"},
{Class: "A", Name: "m"},
},
wantFound: false,
wantFound: true,
},
{
name: "class name differing in case shares the key",
Expand All @@ -74,27 +74,42 @@ func TestResolveMethod(t *testing.T) {
wantFound: true,
},
{
name: "DateTime is skipped",
name: "DateTime blocks the type",
records: []collect.Record{{Class: "A", Name: "m", Type: valuetype.Object("DateTime")}},
wantFound: false,
wantFound: true,
},
{
name: "DateTimeImmutable with null is skipped",
name: "DateTimeImmutable with null blocks the type",
records: []collect.Record{
{Class: "A", Name: "m", Type: valuetype.Object("DateTimeImmutable")},
{Class: "A", Name: "m", Type: "null"},
},
wantFound: false,
wantFound: true,
},
{
name: "only unresolved resolves to nothing",
name: "only unresolved blocks the type",
records: []collect.Record{{Class: "A", Name: "m"}},
wantFound: false,
wantFound: true,
},
{
name: "only test call sites block the type",
records: []collect.Record{{Class: "A", Name: "m", Type: "int", InTest: true}},
wantFound: true,
},
{
name: "only null resolves to nothing",
name: "test call site adds to a production one",
records: []collect.Record{
{Class: "A", Name: "m", Type: "int"},
{Class: "A", Name: "m", Type: "null", InTest: true},
},
wantType: "int",
wantNullable: true,
wantFound: true,
},
{
name: "only null blocks the type",
records: []collect.Record{{Class: "A", Name: "m", Type: "null"}},
wantFound: false,
wantFound: true,
},
}

Expand Down
Loading
Loading