0.4.0

.githooks/commit-msg

@@ -0,0 +1,42 @@
+#!/bin/sh
+# Commit-message lint: the SAME tool CI runs — commitlint over
+# commitlint.config.mjs — executed through the docker compose `node` service,
+# so contributors need docker but no host Node toolchain.
+#
+# Installed by `composer install` via `git config core.hooksPath .githooks`.
+# The message is piped on stdin (comment lines stripped, as git would on
+# commit), so no path mapping into the container is needed and the hook works
+# from worktrees too. node_modules is (re)installed from the lockfile whenever
+# it's missing or stale, so the local commitlint always matches the pinned one.
+
+msg_file="$1"
+
+if ! command -v docker > /dev/null 2>&1; then
+    echo "commit-msg: docker is required to lint the commit message (compose service 'node')." >&2
+    echo "  rules: commitlint.config.mjs (Conventional Commits) — CI enforces the same check." >&2
+    exit 1
+fi
+
+# `command -v docker` isn't enough: this hook runs `docker compose run`, which
+# needs the Compose v2 plugin. Without it, Docker prints its own cryptic
+# "'compose' is not a docker command" — surface a useful message instead.
+if ! docker compose version > /dev/null 2>&1; then
+    echo "commit-msg: the Docker Compose v2 plugin is required ('docker compose' is unavailable)." >&2
+    echo "  rules: commitlint.config.mjs (Conventional Commits) — CI enforces the same check." >&2
+    exit 1
+fi
+
+top=$(git rev-parse --show-toplevel)
+
+# Reinstall when node_modules is absent OR the lockfile is newer than the
+# installed binary — a version bump a collaborator pulls in updates
+# package-lock.json but leaves node_modules untouched, and a stale local
+# commitlint would silently disagree with CI. `npm ci` is otherwise skipped so
+# the common case (already installed) stays fast.
+sed -e 's/\r$//' -e '/^#/d' "$msg_file" \
+    | docker compose --project-directory "$top" run --rm -T --no-deps node sh -c '
+        if [ ! -x node_modules/.bin/commitlint ] || [ package-lock.json -nt node_modules/.bin/commitlint ]; then
+            npm ci --no-audit --no-fund --loglevel=error
+        fi
+        exec node_modules/.bin/commitlint
+    '

.github/workflows/ci-core.yml

@@ -21,6 +21,27 @@ env:
   SHARD_TOTAL: 10
 
 jobs:
+  # Detect whether this PR/push touches code that mutation testing covers.
+  # Infection is expensive, so the `infection` job below runs only when src/
+  # or test/ changed — a docs-only or config-only change skips it.
+  changes:
+    name: Detect code changes
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            code:
+              - 'src/**'
+              - 'test/**'
+
   phpunit:
     # 8.4 is the supported/default runtime and runs the full suite minus the
     # `php85` group; a dedicated 8.5 container runs only that group, which
@@ -133,7 +154,10 @@ jobs:
   mutation-coverage:
     name: Mutation coverage (generate once)
     runs-on: ubuntu-latest
-    needs: phpunit
+    # Only after unit tests pass, and only when src/ or test/ changed
+    # (see the `changes` job) — mutation is skipped for docs/config-only work.
+    needs: [phpunit, changes]
+    if: needs.changes.outputs.code == 'true'
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/commitlint.yml

@@ -0,0 +1,38 @@
+name: Commitlint
+
+# Gate every PR on Conventional Commit messages. Same tool, same version, same
+# config as the local .githooks/commit-msg hook: commitlint pinned by
+# package-lock.json, rules in commitlint.config.mjs.
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  commitlint:
+    name: Conventional commit messages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # commitlint needs the full PR range, not a shallow tip.
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          # Keep in step with the compose `node` service image.
+          node-version: 24
+          cache: npm
+      - name: Install commitlint (lockfile-pinned)
+        run: npm ci --no-audit --no-fund
+      - name: Lint PR commit messages
+        run: >
+          npx --no-install commitlint
+          --from ${{ github.event.pull_request.base.sha }}
+          --to ${{ github.event.pull_request.head.sha }}
+          --verbose

.gitignore

@@ -13,3 +13,4 @@
 /core/.xphp-cache/
 docker-compose.override.yml
 .phpunit.result.cache
+node_modules/

CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to `xphp` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0]
+
+### Added
+
+- **Type aliases.** Give a type a reusable name, in two forms:
+  `type Name<A, B> = Body;` (generic) and `type Name = Body;` (non-generic). An
+  alias is a compile-time substitution — expanded into its body before
+  specialization, with no runtime existence, so the emitted PHP never mentions the
+  alias. Bodies may be a single
+  (possibly-generic) head, a **union** (`int|string`), or a **nullable** (`?Box`):
+  a single head expands in every type position (incl. as a generic argument,
+  `Bag<UserId>`), while a union/nullable expands as the whole type of a parameter,
+  property, return, or class-constant slot. Aliases compose (nested and
+  concrete-instantiation, `type UserMap = Pair<int, User>`); parameters carry
+  **defaults** (`type P<A, B = A>` — a use may omit trailing defaulted arguments)
+  and **bounds** (`type B<T : Named>` — an argument that violates the bound is a
+  compile error; the bound may itself name an alias), like a generic class. An alias
+  is **file-local** — visible only in the file that declares it, like a `use` alias.
+  A cyclic (`xphp.alias_cycle`), arity-mismatched (`xphp.alias_arity`),
+  class-colliding (`xphp.alias_class_collision`), duplicate (`xphp.alias_duplicate`),
+  unsupported-body (`xphp.alias_unsupported_body` — intersection / DNF / closure),
+  compound-in-non-slot (`xphp.alias_compound_in_non_slot`), or bound-violating
+  (`xphp.bound_violation`) alias is a loud error in both `xphp compile` and
+  `xphp check`. See [type aliases](docs/syntax/type-aliases.md).
+- **Type-argument inference (optional turbofish).** A generic call or `new` whose
+  type parameters are determined by the argument values no longer needs the `::<>`
+  turbofish: `identity(5)` infers `identity::<int>`, `new Box($product)` infers
+  `new Box::<Product>`, `$factory->make($p)` and `$box->put($this->item)` infer
+  from the argument's type. Works for free functions, static and instance methods,
+  and class instantiation. An inferred call compiles to exactly the specialization
+  the turbofish would have selected — the type arguments are unified from the
+  arguments' static types and dispatched through the identical path, so bounds,
+  variance, mangling, and check/compile parity are unchanged. Argument types are
+  read conservatively (literals, `new`, `$this` properties, and non-reassigned
+  typed parameters); where they don't determine the type — a type parameter only in
+  the return type, an unknown argument type, or conflicting arguments — the explicit
+  turbofish is still required and omitting it remains the same `xphp.missing_type_argument`
+  error. Generic closure calls (`$f($x)`) and `T[]`-typed parameters are not yet
+  inference sources. See [turbofish → inference](docs/syntax/turbofish.md#type-argument-inference).
+- **Method-generic turbofish grounded by an enclosing type parameter.** A turbofish
+  whose type argument is supplied by the enclosing generic scope now grounds **per
+  specialization** and runs, instead of being rejected by the emitted-marker backstop:
+  a named free-function forward (`identity::<T>($v)` inside `wrap<T>`), a static call
+  (`self::gen::<T>()`, `Maker::wrap::<T>()` inside `Box<T>` — the idiomatic "delegate
+  to a shared static generic helper" shape), and an instance call (`$this->dup::<T>()`,
+  `$m->dup::<T>()` on a non-generic receiver, including a target declared on a generic
+  base class). Freshly specialized bodies are re-grounded transitively, so multi-hop
+  forwards and mutually recursive generics converge; a member grounded onto the
+  program's classes is deduplicated per unique argument tuple, and an instantiation
+  that first appears inside a grounded body is discovered like any other. A bound that
+  only becomes provable after specialization (`gen<U : Stringable>` receiving the
+  class's `T`) is checked per instantiation, and a strictly-growing forward chain
+  (`grow<T>` calling `grow::<Box<T>>`) is rejected as non-convergent
+  (`xphp.unconverged_method_specialization`) instead of specializing forever. See
+  [turbofish](docs/syntax/turbofish.md) and the
+  [remaining caveats](docs/caveats.md#generic-turbofish-grounded-by-an-enclosing-type-parameter)
+  (closure turbofish in generic function bodies, cross-template targets, and the
+  late-bound `static::`/`parent::` spellings still fail loudly).
+
+### Fixed
+
+- **`xphp check` / `xphp compile` parity on enclosing-parameter turbofish.** `check`
+  previously reported nothing for the shapes only the compile-time emitted-marker
+  backstop rejected — a pipeline gating on `check` alone saw green on code `compile`
+  refused. The validate-only pass now grounds each specialization the same way
+  `compile` does and collects the same diagnostics (a violated grounded bound, a
+  non-convergent chain, a surviving marker), located at the template's real source
+  line.
+
 ## [0.3.0]
 
 ### Added
@@ -593,6 +662,7 @@ These are documented in full in the [caveats](docs/caveats.md):
 - Build-time hash-collision detection and a configurable
   `XPHP_HASH_LENGTH` (16–64).
 
+[0.4.0]: https://github.com/xphp-lang/xphp/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/xphp-lang/xphp/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/xphp-lang/xphp/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/xphp-lang/xphp/compare/v0.1.0...v0.2.0

CONTRIBUTING.md

@@ -1,5 +1,30 @@
 # Contributing
 
+## Commit messages
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org):
+
+```
+type(scope): lowercase subject
+```
+
+Types: `build` `chore` `ci` `docs` `feat` `fix` `perf` `refactor` `revert`
+`style` `test`. The scope is the component the change lives in
+(`monomorphize`, `specializer`, `parser`, `cli`, ...); bare `type:` is fine
+for cross-cutting changes. Examples from the history:
+
+```
+feat(monomorphize): ground enclosing-param method turbofish per class specialization
+fix(cli): locate Composer autoloader when installed as a dependency
+docs: refresh docs/ tree with syntax tour, caveats, errors
+```
+
+CI rejects a PR whose commits don't conform: `commitlint` (pinned by
+`package-lock.json`) over `commitlint.config.mjs`. Locally, `composer
+install` wires up a `commit-msg` hook (`.githooks/`) that runs the **same
+tool** through the docker compose `node` service at commit time — docker is
+required, a host Node toolchain is not.
+
 ## Test
 
 ```bash

README.md

@@ -85,10 +85,10 @@ genuinely [hard work](https://thephp.foundation/blog/2024/08/19/state-of-generic
 The object model that's served the ecosystem for two decades doesn't bend
 easily.
 
-Supporting generics proves that the compile-to-vanilla model handles non-trivial
-type-system additions. The remaining features are on
+Supporting generics — and now type aliases — proves that the compile-to-vanilla
+model handles non-trivial type-system additions. Further features are on
 the [roadmap](docs/roadmap.md):
-type aliases, literal types, mapped and conditional types to name a few.
+literal types, mapped and conditional types to name a few.
 
 ## Quick start
 

commitlint.config.mjs

@@ -0,0 +1,15 @@
+// Commit-message rules: Conventional Commits (https://www.conventionalcommits.org).
+// One rule set, one tool, two entry points:
+//   - locally:  .githooks/commit-msg runs commitlint through the docker compose
+//               `node` service (installed by `composer install`)
+//   - in CI:    .github/workflows/commitlint.yml runs the same lockfile-pinned
+//               commitlint over every PR commit
+//
+// The stock preset already matches this repo's history:
+//   type(scope): lowercase subject
+// with types build/chore/ci/docs/feat/fix/perf/refactor/revert/style/test, an
+// optional free-form scope (monomorphize, specializer, parser, cli, ...), a
+// 100-char header cap, and merge/revert/fixup subjects ignored.
+export default {
+    extends: ['@commitlint/config-conventional'],
+};

composer.json

@@ -51,5 +51,13 @@
         "allow-plugins": {
             "infection/extension-installer": true
         }
+    },
+    "scripts": {
+        "post-install-cmd": "@git:hooks",
+        "post-update-cmd": "@git:hooks",
+        "git:hooks": "git rev-parse --git-dir > /dev/null 2>&1 && git config core.hooksPath .githooks || true"
+    },
+    "scripts-descriptions": {
+        "git:hooks": "Point git at the tracked .githooks/ directory (commit-msg lint); no-op outside a git checkout."
     }
 }

docker-compose.yml

@@ -22,5 +22,20 @@ services:
       service: php
     entrypoint: [ "/opt/app/bin/xphp" ]
 
+  # Node runtime for commit-message linting: the .githooks/commit-msg hook runs
+  # commitlint through this service, so contributors need docker but no host
+  # Node toolchain — and local linting uses the exact tool CI runs. One-shot:
+  #   docker compose run --rm node npx commitlint --help
+  # Runs commitlint for the commit-msg hook and CI. Behind a profile so a bare
+  # `docker compose up` doesn't start it; the hook targets it explicitly with
+  # `docker compose run node`, which starts a profiled service on demand and
+  # supplies its own command (no keepalive needed).
+  node:
+    image: node:24-alpine
+    working_dir: /opt/app
+    volumes:
+      - ./:/opt/app
+    profiles: [ "commitlint" ]
+
 volumes:
   composer_cache: ~