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
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ argtyper add-types [project-path] [--dry] [--literals] [--objects]

`project-path` defaults to `.`. `--dry` prints the diff without writing.
`--literals` only adds string types with a `@param 'a'|'b'` literal docblock.
`--objects` only adds object types, including unions made only of objects.
`--objects` only adds object types.
Both can be combined.

Dev tasks via `Makefile`:
Expand Down
22 changes: 9 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,25 +91,22 @@ $this->setLocale(null);
}
```

**Union types** when two or more different types reach the same parameter -
instead of guessing or giving up, it writes them all:
**No union types** - when two or more different types reach the same
parameter, it is ambiguous and left untyped. Only a single type, or a single
type plus `null` (nullable), is added:

```php
$this->handle(1); // int
$this->handle("text"); // string
```

```diff
-public function handle($value)
+public function handle(int|string $value)
public function handle($value)
{
}
```

There is no cap on the number of union members, and they are sorted
alphabetically. A nullable union is written with a trailing `|null` (since `?`
only works for a single type). The one type it will not accept is `callable`
(a closure or arrow function) - that poisons the parameter and it is left
A `callable` argument (a closure or arrow function) also leaves the parameter
untyped.

**Default values** are typed too, even without a call site:
Expand Down Expand Up @@ -201,9 +198,8 @@ Only add the string literal docblocks, and no other types, with `--literals`:
argtyper add-types . --literals
```

Only add object types with `--objects` - a single class, a nullable one, or a
union made only of classes (`\Foo|\Bar`). A union with a scalar, like
`int|\Money`, is skipped. Both options can be combined:
Only add object types with `--objects` - a single class or a nullable one.
Both options can be combined:

```bash
argtyper add-types . --objects
Expand All @@ -219,8 +215,8 @@ argtyper add-types . --literals --objects
objects, `Foo::class`, enum cases, constants, and a few built-in function
returns.
2. **Resolve** - it groups the recorded types per parameter position. A single
type is used directly; two or more distinct types become a union; `null`
becomes the nullable flag rather than a union member.
type is used directly; two or more distinct types are ambiguous and skipped;
`null` becomes the nullable flag.
3. **Apply** - it adds each resolved type to the definitions that are still
missing one, removes any now-redundant `@param` docblock, and reprints the
file. Unchanged code keeps its exact formatting.
Expand Down
11 changes: 6 additions & 5 deletions internal/aggregate/aggregate.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ import (
)

// Resolved is the final type decision for one parameter position. Two or more
// types observed for the same parameter become a union.
// types observed for the same parameter are ambiguous and left unresolved.
type Resolved struct {
Types []valuetype.Type // one or more types, never Null
Types []valuetype.Type // exactly one type, never Null
Nullable bool
Literals []string // sorted string literal values, set only for a plain string type, see literalValues
}
Expand Down Expand Up @@ -54,8 +54,8 @@ func (t Types) Function(name string, position int) (Resolved, bool) {
return resolved, ok
}

// Resolve groups records per parameter into a resolved type: the observed types
// as a union, with null captured as nullability rather than a member.
// Resolve groups records per parameter into a resolved type: a single observed
// type, with null captured as nullability. Unions are skipped.
func Resolve(records []collect.Record) Types {
methodTypes := map[string]*group{}
functionTypes := map[string]*group{}
Expand Down Expand Up @@ -95,7 +95,8 @@ func resolveGroups(groups map[string]*group) map[string]Resolved {

nullable := contains(types, valuetype.Null)
members := without(types, valuetype.Null)
if len(members) == 0 {
// only a single type is added, unions are left untyped
if len(members) != 1 {
continue
}
resolved[key] = Resolved{Types: members, Nullable: nullable, Literals: literalValues(members, group)}
Expand Down
11 changes: 4 additions & 7 deletions internal/aggregate/aggregate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -34,24 +34,21 @@ func TestResolveMethod(t *testing.T) {
wantFound: true,
},
{
name: "two real types become a union",
name: "two real types are skipped",
records: []collect.Record{
{Class: "A", Name: "m", Type: "int"},
{Class: "A", Name: "m", Type: "string"},
},
wantType: "int|string",
wantFound: true,
wantFound: false,
},
{
name: "union with null",
name: "two real types with null are skipped",
records: []collect.Record{
{Class: "A", Name: "m", Type: "int"},
{Class: "A", Name: "m", Type: "string"},
{Class: "A", Name: "m", Type: "null"},
},
wantType: "int|string",
wantNullable: true,
wantFound: true,
wantFound: false,
},
{
name: "unresolved argument keeps the resolved type",
Expand Down
2 changes: 1 addition & 1 deletion internal/apply/apply.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ func Source(src []byte, types aggregate.Types, table *symbols.Table, inheritance
// added; with one or more set, only the chosen kinds are.
type Options struct {
Literals bool // string types that get a `'a'|'b'` literal doc type
Objects bool // object types, including unions made only of objects
Objects bool // object types
}

// allows reports whether a resolved type passes the options; docType is its
Expand Down
16 changes: 8 additions & 8 deletions internal/apply/apply_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -130,19 +130,19 @@ func TestApply(t *testing.T) {
want: "<?php\nfinal class A {\n /**\n * @param string $v the value\n */\n public function set(string $v) {}\n public function go() { $this->set(\"x\"); }\n}",
},
{
name: "unions multiple observed types",
name: "skips multiple observed types",
target: "<?php\nfinal class A {\n public function set($v) {}\n public function go() { $this->set(1); $this->set(\"x\"); }\n}",
want: "<?php\nfinal class A {\n public function set(int|string $v) {}\n public function go() { $this->set(1); $this->set(\"x\"); }\n}",
want: "<?php\nfinal class A {\n public function set($v) {}\n public function go() { $this->set(1); $this->set(\"x\"); }\n}",
},
{
name: "unions multiple types with null as a member",
name: "skips multiple types with null",
target: "<?php\nfinal class A {\n public function set($v) {}\n public function go() { $this->set(1); $this->set(\"x\"); $this->set(null); }\n}",
want: "<?php\nfinal class A {\n public function set(int|string|null $v) {}\n public function go() { $this->set(1); $this->set(\"x\"); $this->set(null); }\n}",
want: "<?php\nfinal class A {\n public function set($v) {}\n public function go() { $this->set(1); $this->set(\"x\"); $this->set(null); }\n}",
},
{
name: "unions object and scalar types",
name: "skips object and scalar types",
target: "<?php\nfinal class A {\n public function set($v) {}\n public function go() { $this->set(new Money()); $this->set(1); }\n}",
want: "<?php\nfinal class A {\n public function set(int|\\Money $v) {}\n public function go() { $this->set(new Money()); $this->set(1); }\n}",
want: "<?php\nfinal class A {\n public function set($v) {}\n public function go() { $this->set(new Money()); $this->set(1); }\n}",
},
{
name: "skips magic method",
Expand Down Expand Up @@ -502,8 +502,8 @@ func TestObjectsOnly(t *testing.T) {

output, added, _ := apply.Source([]byte(src), types, table, inherit.New(), apply.Options{Objects: true})

want := "<?php\nfunction save(?\\User $user, \\Item|\\Order $item, $count, $mixed, \\Status $status = Status::Active) {}\nenum Status {\n case Active;\n}\nsave(new User(), new Item(), 1, new Money());\nsave(null, new Order(), 2, 5);"
if output != want || len(added) != 3 {
want := "<?php\nfunction save(?\\User $user, $item, $count, $mixed, \\Status $status = Status::Active) {}\nenum Status {\n case Active;\n}\nsave(new User(), new Item(), 1, new Money());\nsave(null, new Order(), 2, 5);"
if output != want || len(added) != 2 {
t.Errorf("\n got: %q (%d added)\nwant: %q", output, len(added), want)
}
}
Expand Down
2 changes: 1 addition & 1 deletion main.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ parameter type declarations. Defaults to the current directory.

--dry Print the diff of the types that would be added, without writing.
--literals Only add string types with a @param 'a'|'b' literal docblock.
--objects Only add object types, including unions made only of objects.
--objects Only add object types.

--literals and --objects can be combined.`

Expand Down
Loading