Continue on python 3.15 integration: Update dependencies, and fix CI matrix, format gate and venv, fix makefile drift

.github/workflows/ci.yml

@@ -50,12 +50,12 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ['3.12', '3.13', '3.14', '3.15.0rc1']
+        python-version: ['3.12', '3.13', '3.14', '3.15']
         exclude:
         - os: windows-latest
           python-version: '3.13'
         - os: windows-latest
-          python-version: '3.15.0rc1'
+          python-version: '3.15'
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.os }} check (py ${{ matrix.python-version }})
 
@@ -66,14 +66,24 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python
+        id: setup-python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
 
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
-          version: "0.12.1"
+          version: "0.12.2"
+
+      # Without this, 'uv sync' downloads a managed Python of its own choosing
+      # and the python-version matrix has no effect at all.
+      - name: Point uv at the matrix interpreter
+        shell: bash
+        env:
+          PYTHON_PATH: ${{ steps.setup-python.outputs.python-path }}
+        run: echo "UV_PYTHON=$PYTHON_PATH" >> "$GITHUB_ENV"
 
       - name: Run Check (Linux)
         if: runner.os == 'Linux'
@@ -91,14 +101,14 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ['3.12', '3.13', '3.14', '3.15.0rc1']
+        python-version: ['3.12', '3.13', '3.14', '3.15']
         exclude:
         - os: windows-latest
           python-version: '3.13'
         - os: windows-latest
           python-version: '3.14'
         - os: windows-latest
-          python-version: '3.15.0rc1'
+          python-version: '3.15'
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.os }} format (py ${{ matrix.python-version }})
 
@@ -109,37 +119,51 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python
+        id: setup-python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
 
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
-          version: "0.12.1"
+          version: "0.12.2"
+
+      # Without this, 'uv sync' downloads a managed Python of its own choosing
+      # and the python-version matrix has no effect at all.
+      - name: Point uv at the matrix interpreter
+        shell: bash
+        env:
+          PYTHON_PATH: ${{ steps.setup-python.outputs.python-path }}
+        run: echo "UV_PYTHON=$PYTHON_PATH" >> "$GITHUB_ENV"
 
+      # --check makes this fail on unformatted code instead of silently
+      # reformatting the checkout and passing.
       - name: Run Format (Linux)
         if: runner.os == 'Linux'
         shell: bash
         run: |
-            make format
+            make format FLAGS=--check
 
       - name: Run Format (Windows)
         if: runner.os == 'Windows'
         run: |
-            ./make.bat format
+            ./make.bat format --check
 
   offline-test:
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ['3.12', '3.13', '3.14', '3.15.0rc1']
+        python-version: ['3.12', '3.13', '3.14', '3.15']
+        # Same reduced Windows coverage as the 'check' job: oldest and newest
+        # stable, no 3.13 and no pre-release.
         exclude:
         - os: windows-latest
           python-version: '3.13'
         - os: windows-latest
-          python-version: '3.14'
+          python-version: '3.15'
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.os }} (py ${{ matrix.python-version }})
 
@@ -150,14 +174,24 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python
+        id: setup-python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
 
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
-          version: "0.12.1"
+          version: "0.12.2"
+
+      # Without this, 'uv sync' downloads a managed Python of its own choosing
+      # and the python-version matrix has no effect at all.
+      - name: Point uv at the matrix interpreter
+        shell: bash
+        env:
+          PYTHON_PATH: ${{ steps.setup-python.outputs.python-path }}
+        run: echo "UV_PYTHON=$PYTHON_PATH" >> "$GITHUB_ENV"
 
       - name: Run Test (Linux)
         if: runner.os == 'Linux'
@@ -170,6 +204,40 @@ jobs:
         run: |
             ./make.bat test
 
+  # 'make all' ends in 'make build'; without this the packaging step is
+  # never exercised in CI.
+  build:
+    runs-on: ubuntu-latest
+    name: build (py 3.14)
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.ref }}
+          persist-credentials: false
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.12.2"
+
+      - name: Point uv at the matrix interpreter
+        shell: bash
+        env:
+          PYTHON_PATH: ${{ steps.setup-python.outputs.python-path }}
+        run: echo "UV_PYTHON=$PYTHON_PATH" >> "$GITHUB_ENV"
+
+      - name: Run Build
+        shell: bash
+        run: |
+            make build
+
   # online-test:
   #   needs: permissions-check
   #   environment:

AGENTS.md

@@ -55,6 +55,15 @@ AGENTS.md. In all cases show what you added to AGENTS.md.
 - **Do NOT** manually edit `pyproject.toml` dependency versions after running uv commands
 - uv maintains consistency between `pyproject.toml`, `uv.lock`, and installed packages
 - Trust uv's automatic version resolution and file management
+- **Never raise the lower bounds in `[project.dependencies]` or `[project.optional-dependencies]`
+  as part of a dependency update.** Those bounds ship in the wheel metadata and constrain every
+  project that depends on typeagent; a high floor on a shared dependency is a common cause of
+  unsolvable resolutions for downstream users. Raise a floor only when our code actually needs
+  the newer version, and add an upper bound only for a known incompatibility (with a comment
+  saying what breaks and what it would take to lift the cap).
+- Bumping versions in `[dependency-groups] dev` is fine -- that only selects which versions the
+  dev tools run with here and in CI, and never reaches the published wheel. Same for `uv.lock`,
+  which is where routine "get the latest versions" updates belong.
 
 **IMPORTANT! YOU ARE NOT DONE UNTIL `make format check test` PASSES**
 

Makefile

@@ -11,10 +11,12 @@ format: venv
 	uv run isort src tests tools examples $(FLAGS)
 	uv run black -tpy312 src tests tools examples $(FLAGS)
 
+# intentionally running pyright only for the lowest and the highest version 
+# running it for all versions takes too much time and doesn't add enough diagnostic power
 .PHONY: check
 check: venv
 	uv run pyright --pythonversion 3.12 src tests tools examples
-	uv run pyright --pythonversion 3.14 src tests tools examples
+	uv run pyright --pythonversion 3.15 src tests tools examples
 
 .PHONY: test
 test: venv
@@ -64,13 +66,17 @@ release: venv
 .PHONY: venv
 venv: .venv
 
-.venv:
+# Re-sync when the dependencies change, not just when .venv/ is missing.
+# The final 'touch' is needed because 'uv sync' leaves .venv/'s own timestamp
+# alone, which would make this target look perpetually out of date.
+.venv: pyproject.toml uv.lock
 	@echo "(If 'uv' fails with 'No such file or directory', try 'make install-uv')"
-	uv sync -q $(FLAGS)
+	uv sync -q
 	uv run black --version
 	@echo "(If 'pyright' fails with 'error while loading shared libraries: libatomic.so.1:', try 'make install-libatomic')"
 	uv run pyright --version
 	uv run pytest --version
+	@touch .venv
 
 .PHONY: sync
 sync:

make.bat

@@ -8,40 +8,61 @@
 :: use `set-alias make ".\make.bat"` in PowerShell.
 
 @echo off
+setlocal
 if "%~1"=="" goto help
 
-if /I "%~1"=="format" goto format
-if /I "%~1"=="check" goto check
-if /I "%~1"=="test" goto test
-if /I "%~1"=="coverage" goto coverage
-if /I "%~1"=="demo" goto demo
-if /I "%~1"=="build" goto build
-if /I "%~1"=="venv" goto venv
-if /I "%~1"=="sync" goto sync
-if /I "%~1"=="install-uv" goto install-uv
-if /I "%~1"=="clean" goto clean
-if /I "%~1"=="help" goto help
-
-echo Unknown command: %~1
+:: Remember the command, then collect every remaining argument into ARGS.
+:: (The all-args variable can't be used here: 'shift' doesn't affect it.)
+set "CMD=%~1"
+set "ARGS="
+:collect
+shift
+if "%~1"=="" goto collected
+set "ARGS=%ARGS% %1"
+goto collect
+
+:collected
+:: Drop the leading space left by the loop above.
+if defined ARGS set "ARGS=%ARGS:~1%"
+
+:dispatch
+if /I "%CMD%"=="format" goto format
+if /I "%CMD%"=="check" goto check
+if /I "%CMD%"=="test" goto test
+if /I "%CMD%"=="coverage" goto coverage
+if /I "%CMD%"=="demo" goto demo
+if /I "%CMD%"=="build" goto build
+if /I "%CMD%"=="venv" goto venv
+if /I "%CMD%"=="sync" goto sync
+if /I "%CMD%"=="install-uv" goto install-uv
+if /I "%CMD%"=="clean" goto clean
+if /I "%CMD%"=="help" goto help
+
+echo Unknown command: %CMD%
 goto help
 
+:: Extra arguments are passed on to the tools, e.g. '.\make format --check --diff'.
 :format
 if not exist ".venv\" call make.bat venv
 echo Formatting code...
-uv run isort src tests tools examples
-uv run black -tpy312 src tests tools examples
+uv run isort src tests tools examples %ARGS% || exit /b 1
+uv run black -tpy312 src tests tools examples %ARGS% || exit /b 1
 goto end
 
+:: intentionally running pyright only for the lowest and the highest version 
+:: running it for all versions takes too much time and doesn't add enough diagnostic power
+:: Keep the checked versions in sync with the 'check' target in the Makefile.
 :check
 if not exist ".venv\" call make.bat venv
 echo Running type checks...
-uv run pyright src tests tools examples
+uv run pyright --pythonversion 3.12 src tests tools examples || exit /b 1
+uv run pyright --pythonversion 3.15 src tests tools examples || exit /b 1
 goto end
 
 :test
 if not exist ".venv\" call make.bat venv
 echo Running unit tests...
-uv run pytest
+uv run pytest %ARGS%
 goto end
 
 :coverage
@@ -50,7 +71,7 @@ if not exist ".venv\" call make.bat venv
 echo Running test coverage...
 uv run coverage erase
 set "COVERAGE_PROCESS_START=.coveragerc"
-uv run coverage run -m pytest
+uv run coverage run -m pytest %ARGS%
 uv run coverage combine
 uv run coverage report
 endlocal
@@ -60,7 +81,7 @@ goto end
 :demo
 if not exist ".venv\" call make.bat venv
 echo Running query tool...
-uv run python -m tools.query
+uv run python -m tools.query %ARGS%
 goto end
 
 :build
@@ -79,7 +100,7 @@ uv run pytest --version
 goto end
 
 :sync
-uv sync
+uv sync %ARGS%
 goto end
 
 :install-uv