From b6b312d9ca1f8a46a678dd7c0f81480573eaf703 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Sun, 2 Aug 2026 20:18:37 +1000 Subject: [PATCH 01/45] bench --- benchmarks/results/summary.md | 52 ++++++++--------- .../status/darwin-arm64-apple-m4-max.csv | 58 +++++++++---------- 2 files changed, 55 insertions(+), 55 deletions(-) diff --git a/benchmarks/results/summary.md b/benchmarks/results/summary.md index d3b9af77..b1178e03 100644 --- a/benchmarks/results/summary.md +++ b/benchmarks/results/summary.md @@ -5,29 +5,29 @@ Machine: `Apple M4 Max` | fixture | basilisk | basilisk-warm | pyright | mypy | mypy-warm | ty | pyrefly | zuban | |---|---|---|---|---|---|---|---|---| -| aliases_type_statement | 8.4 ms | 4.2 ms | 547.1 ms | 610.0 ms | 161.0 ms | 63.9 ms | 112.3 ms | 28.8 ms | -| assignment_compatibility | 9.0 ms | 5.4 ms | 585.4 ms | 583.5 ms | 164.7 ms | 52.2 ms | 113.4 ms | 30.6 ms | -| call_argument_types | 13.7 ms | 4.3 ms | 642.7 ms | 611.6 ms | 163.7 ms | 56.1 ms | 114.3 ms | 48.4 ms | -| callables_subtyping | 12.4 ms | 4.4 ms | 522.1 ms | 571.4 ms | 164.2 ms | 39.3 ms | 109.7 ms | 29.1 ms | -| classvar_scoping | 15.1 ms | 5.1 ms | 599.6 ms | 614.3 ms | 163.3 ms | 58.8 ms | 134.7 ms | 32.4 ms | -| constructors_call_init | 9.3 ms | 5.6 ms | 592.2 ms | 596.6 ms | 162.6 ms | 38.8 ms | 103.8 ms | 26.6 ms | -| dataclasses_usage | 9.6 ms | 4.0 ms | 1559.4 ms | 642.0 ms | 164.7 ms | 61.8 ms | 176.1 ms | 56.6 ms | -| dict_key_hashability | 12.0 ms | 5.1 ms | 518.9 ms | 613.3 ms | 160.7 ms | 39.2 ms | 103.9 ms | 31.9 ms | -| enums_member_values | 8.8 ms | 4.4 ms | 564.1 ms | 576.0 ms | 160.9 ms | 42.0 ms | 103.8 ms | 26.7 ms | -| final_reassignment | 7.3 ms | 4.1 ms | 456.9 ms | 562.5 ms | 167.2 ms | 28.9 ms | 100.6 ms | 24.4 ms | -| generics_defaults_specialization | 9.4 ms | 4.2 ms | 549.6 ms | 579.0 ms | 162.1 ms | 35.0 ms | 104.7 ms | 27.4 ms | -| literals_semantics | 12.5 ms | 4.6 ms | 518.2 ms | 577.6 ms | 162.5 ms | 32.5 ms | 104.5 ms | 27.0 ms | -| match_exhaustiveness | 11.2 ms | 3.8 ms | 521.6 ms | 600.0 ms | 163.2 ms | 36.7 ms | 111.4 ms | 27.4 ms | -| narrowing_typeis | 9.6 ms | 4.3 ms | 539.3 ms | 582.8 ms | 160.2 ms | 34.5 ms | 104.9 ms | 26.4 ms | -| newtype_definition | 10.8 ms | 5.0 ms | 715.1 ms | 628.9 ms | 164.4 ms | 25.1 ms | 118.3 ms | 35.8 ms | -| overloads_evaluation | 12.8 ms | 4.3 ms | 591.8 ms | 627.4 ms | 163.9 ms | 60.2 ms | 119.9 ms | 34.2 ms | -| override_compatibility | 14.3 ms | 4.0 ms | 635.9 ms | 598.1 ms | 164.0 ms | 42.0 ms | 111.2 ms | 28.2 ms | -| protocols_definition | 9.1 ms | 4.1 ms | 562.6 ms | 580.4 ms | 163.1 ms | 35.5 ms | 103.7 ms | 27.5 ms | -| returns_compatibility | 7.1 ms | 4.5 ms | 488.7 ms | 572.5 ms | 162.5 ms | 33.0 ms | 101.9 ms | 24.5 ms | -| tuples_index | 8.9 ms | 4.5 ms | 549.3 ms | 566.6 ms | 162.1 ms | 35.0 ms | 106.4 ms | 25.8 ms | -| typeddict_key_access | 9.8 ms | 4.0 ms | 610.2 ms | 582.1 ms | 162.0 ms | 37.4 ms | 107.3 ms | 26.6 ms | -| typeddict_readonly_inheritance | 14.5 ms | 4.3 ms | 653.8 ms | 579.7 ms | 165.6 ms | 38.7 ms | 114.4 ms | 25.9 ms | -| typeddict_readonly_mutation | 10.1 ms | 4.1 ms | 613.3 ms | 579.8 ms | 163.3 ms | 42.7 ms | 107.9 ms | 26.0 ms | -| typevar_constraints | 16.9 ms | 4.8 ms | 720.8 ms | 577.9 ms | 165.2 ms | 42.3 ms | 113.6 ms | 34.1 ms | -| undefined_names | 15.3 ms | 5.3 ms | 487.5 ms | 631.7 ms | 168.3 ms | 51.2 ms | 544.6 ms | 34.4 ms | -| unresolved_imports | 13.0 ms | 5.5 ms | 455.6 ms | 710.6 ms | 167.7 ms | 284.5 ms | 897.7 ms | 294.6 ms | +| aliases_type_statement | 9.2 ms | 4.9 ms | 547.1 ms | 610.0 ms | 161.0 ms | 63.9 ms | 112.3 ms | 28.8 ms | +| assignment_compatibility | 8.5 ms | 5.5 ms | 585.4 ms | 583.5 ms | 164.7 ms | 52.2 ms | 113.4 ms | 30.6 ms | +| call_argument_types | 13.6 ms | 4.3 ms | 642.7 ms | 611.6 ms | 163.7 ms | 56.1 ms | 114.3 ms | 48.4 ms | +| callables_subtyping | 12.6 ms | 4.4 ms | 522.1 ms | 571.4 ms | 164.2 ms | 39.3 ms | 109.7 ms | 29.1 ms | +| classvar_scoping | 15.3 ms | 5.9 ms | 599.6 ms | 614.3 ms | 163.3 ms | 58.8 ms | 134.7 ms | 32.4 ms | +| constructors_call_init | 9.0 ms | 4.1 ms | 592.2 ms | 596.6 ms | 162.6 ms | 38.8 ms | 103.8 ms | 26.6 ms | +| dataclasses_usage | 9.4 ms | 4.0 ms | 1559.4 ms | 642.0 ms | 164.7 ms | 61.8 ms | 176.1 ms | 56.6 ms | +| dict_key_hashability | 11.8 ms | 8.0 ms | 518.9 ms | 613.3 ms | 160.7 ms | 39.2 ms | 103.9 ms | 31.9 ms | +| enums_member_values | 8.2 ms | 4.4 ms | 564.1 ms | 576.0 ms | 160.9 ms | 42.0 ms | 103.8 ms | 26.7 ms | +| final_reassignment | 7.1 ms | 4.1 ms | 456.9 ms | 562.5 ms | 167.2 ms | 28.9 ms | 100.6 ms | 24.4 ms | +| generics_defaults_specialization | 10.0 ms | 4.3 ms | 549.6 ms | 579.0 ms | 162.1 ms | 35.0 ms | 104.7 ms | 27.4 ms | +| literals_semantics | 12.5 ms | 4.4 ms | 518.2 ms | 577.6 ms | 162.5 ms | 32.5 ms | 104.5 ms | 27.0 ms | +| match_exhaustiveness | 11.0 ms | 4.2 ms | 521.6 ms | 600.0 ms | 163.2 ms | 36.7 ms | 111.4 ms | 27.4 ms | +| narrowing_typeis | 9.4 ms | 4.2 ms | 539.3 ms | 582.8 ms | 160.2 ms | 34.5 ms | 104.9 ms | 26.4 ms | +| newtype_definition | 10.4 ms | 5.4 ms | 715.1 ms | 628.9 ms | 164.4 ms | 25.1 ms | 118.3 ms | 35.8 ms | +| overloads_evaluation | 12.9 ms | 4.6 ms | 591.8 ms | 627.4 ms | 163.9 ms | 60.2 ms | 119.9 ms | 34.2 ms | +| override_compatibility | 14.2 ms | 5.0 ms | 635.9 ms | 598.1 ms | 164.0 ms | 42.0 ms | 111.2 ms | 28.2 ms | +| protocols_definition | 10.1 ms | 5.5 ms | 562.6 ms | 580.4 ms | 163.1 ms | 35.5 ms | 103.7 ms | 27.5 ms | +| returns_compatibility | 8.1 ms | 5.6 ms | 488.7 ms | 572.5 ms | 162.5 ms | 33.0 ms | 101.9 ms | 24.5 ms | +| tuples_index | 10.5 ms | 5.4 ms | 549.3 ms | 566.6 ms | 162.1 ms | 35.0 ms | 106.4 ms | 25.8 ms | +| typeddict_key_access | 10.6 ms | 4.4 ms | 610.2 ms | 582.1 ms | 162.0 ms | 37.4 ms | 107.3 ms | 26.6 ms | +| typeddict_readonly_inheritance | 15.1 ms | 3.6 ms | 653.8 ms | 579.7 ms | 165.6 ms | 38.7 ms | 114.4 ms | 25.9 ms | +| typeddict_readonly_mutation | 9.9 ms | 4.3 ms | 613.3 ms | 579.8 ms | 163.3 ms | 42.7 ms | 107.9 ms | 26.0 ms | +| typevar_constraints | 17.2 ms | 5.5 ms | 720.8 ms | 577.9 ms | 165.2 ms | 42.3 ms | 113.6 ms | 34.1 ms | +| undefined_names | 15.4 ms | 5.1 ms | 487.5 ms | 631.7 ms | 168.3 ms | 51.2 ms | 544.6 ms | 34.4 ms | +| unresolved_imports | 12.9 ms | 5.1 ms | 455.6 ms | 710.6 ms | 167.7 ms | 284.5 ms | 897.7 ms | 294.6 ms | diff --git a/benchmarks/status/darwin-arm64-apple-m4-max.csv b/benchmarks/status/darwin-arm64-apple-m4-max.csv index e0af78a2..b4448b5a 100644 --- a/benchmarks/status/darwin-arm64-apple-m4-max.csv +++ b/benchmarks/status/darwin-arm64-apple-m4-max.csv @@ -3,35 +3,35 @@ # arch: arm64 # os: Darwin 25.5.0 # cores: 14 -# tools: basilisk=basilisk 0.0.0-dev+gc070739e-dirty, pyright=pyright 1.1.408, mypy=mypy 1.19.1 (compiled: yes), ty=ty 0.0.19 (ae10022c2 2026-02-26), pyrefly=pyrefly 0.54.0, zuban=zuban 0.9.0 +# tools: basilisk=basilisk 0.0.0-dev+gf285ce2e, pyright=pyright 1.1.408, mypy=mypy 1.19.1 (compiled: yes), ty=ty 0.0.19 (ae10022c2 2026-02-26), pyrefly=pyrefly 0.54.0, zuban=zuban 0.9.0 # runs: 10 minimum; noisy Basilisk CV > 15% is remeasured with at least 30 runs (hyperfine mean wall-clock, milliseconds) -# generated: 2026-08-02T10:10:38+1000 -# measured: basilisk, basilisk-warm — timed by this run. pyright, mypy, mypy-warm, ty, pyrefly, zuban were NOT re-timed; their _ms and _diags cells and version strings are carried forward verbatim from the previous run (2026-08-02T00:11:23+1000) on this machine. +# generated: 2026-08-02T20:11:56+1000 +# measured: basilisk, basilisk-warm — timed by this run. pyright, mypy, mypy-warm, ty, pyrefly, zuban were NOT re-timed; their _ms and _diags cells and version strings are carried forward verbatim from the previous run (2026-08-02T10:10:38+1000) on this machine. # note: _ms = COLD full-file CLI check from scratch (whole process: startup + stubs + analysis). _diags = error diagnostics the tool reported on that fixture in the measured configuration (error severity only; warnings/notes are not counted) — read every time next to its diags; a tool that reports 0 analyzed the file but flagged no errors there. A blank _ms cell means the tool either was not installed on this machine or failed to analyze that fixture (exit >= 2, e.g. parse abort) and was excluded rather than timed as a crash. Competitor versions are the LATEST official release pulled at the top of every run, so their columns always reflect current upstream, never a pinned build. Only basilisk and mypy have a -warm column (they keep a real cross-run cache): basilisk-warm = --cache result-cache hit; mypy-warm = incremental .mypy_cache hit (cold mypy = --no-incremental). pyright/ty/pyrefly keep NO cross-run result cache (a repeat run = cold), so they are measured cold-only. zuban is also cold-only but its mypy mode DOES reuse a ./.mypy_cache when present (no flag disables it), so we wipe ./.mypy_cache before every timed run to keep the measurement cold. mypy runs with --strict so it performs the strict-mode analysis the fixtures stress (plain mypy reports 'no issues' on the strictness fixtures); zuban runs as `zuban mypy --strict` for the same reason (its default `zuban check` mode skips these strictness rules). This file is ALWAYS rewritten with the latest measured numbers, even on a regression — the CI gate reads the committed baseline, never this working copy, so a slip is recorded here AND fails CI rather than being hidden. fixture,basilisk_ms,basilisk-warm_ms,pyright_ms,mypy_ms,mypy-warm_ms,ty_ms,pyrefly_ms,zuban_ms,basilisk_diags,pyright_diags,mypy_diags,ty_diags,pyrefly_diags,zuban_diags -aliases_type_statement,8.4,4.2,547.1,610.0,161.0,63.9,112.3,28.8,600,850,650,1850,700,600 -assignment_compatibility,9.0,5.4,585.4,583.5,164.7,52.2,113.4,30.6,2000,2000,2000,2000,2000,2000 -call_argument_types,13.7,4.3,642.7,611.6,163.7,56.1,114.3,48.4,998,998,1002,998,998,1000 -callables_subtyping,12.4,4.4,522.1,571.4,164.2,39.3,109.7,29.1,600,600,600,600,600,600 -classvar_scoping,15.1,5.1,599.6,614.3,163.3,58.8,134.7,32.4,2000,2000,2000,2000,4000,2000 -constructors_call_init,9.3,5.6,592.2,596.6,162.6,38.8,103.8,26.6,444,370,296,370,444,518 -dataclasses_usage,9.6,4.0,1559.4,642.0,164.7,61.8,176.1,56.6,500,500,500,500,500,500 -dict_key_hashability,12.0,5.1,518.9,613.3,160.7,39.2,103.9,31.9,2000,2000,0,0,0,0 -enums_member_values,8.8,4.4,564.1,576.0,160.9,42.0,103.8,26.7,480,480,80,480,480,480 -final_reassignment,7.3,4.1,456.9,562.5,167.2,28.9,100.6,24.4,500,500,500,500,500,500 -generics_defaults_specialization,9.4,4.2,549.6,579.0,162.1,35.0,104.7,27.4,560,560,560,421,560,560 -literals_semantics,12.5,4.6,518.2,577.6,162.5,32.5,104.5,27.0,576,576,576,576,576,576 -match_exhaustiveness,11.2,3.8,521.6,600.0,163.2,36.7,111.4,27.4,500,0,0,500,0,0 -narrowing_typeis,9.6,4.3,539.3,582.8,160.2,34.5,104.9,26.4,520,520,520,520,520,520 -newtype_definition,10.8,5.0,715.1,628.9,164.4,25.1,118.3,35.8,2000,2000,2000,0,2000,2000 -overloads_evaluation,12.8,4.3,591.8,627.4,163.9,60.2,119.9,34.2,600,1401,801,600,600,801 -override_compatibility,14.3,4.0,635.9,598.1,164.0,42.0,111.2,28.2,200,200,300,1,200,300 -protocols_definition,9.1,4.1,562.6,580.4,163.1,35.5,103.7,27.5,536,402,402,335,402,402 -returns_compatibility,7.1,4.5,488.7,572.5,162.5,33.0,101.9,24.5,1080,540,540,540,540,540 -tuples_index,8.9,4.5,549.3,566.6,162.1,35.0,106.4,25.8,600,600,600,1800,600,600 -typeddict_key_access,9.8,4.0,610.2,582.1,162.0,37.4,107.3,26.6,500,500,500,500,500,500 -typeddict_readonly_inheritance,14.5,4.3,653.8,579.7,165.6,38.7,114.4,25.9,500,500,500,2,500,500 -typeddict_readonly_mutation,10.1,4.1,613.3,579.8,163.3,42.7,107.9,26.0,500,500,500,500,500,500 -typevar_constraints,16.9,4.8,720.8,577.9,165.2,42.3,113.6,34.1,2000,2000,2000,2000,2000,2000 -undefined_names,15.3,5.3,487.5,631.7,168.3,51.2,544.6,34.4,2000,2000,4000,2000,2000,4000 -unresolved_imports,13.0,5.5,455.6,710.6,167.7,284.5,897.7,294.6,2000,2000,2000,2000,2000,2000 +aliases_type_statement,9.2,4.9,547.1,610.0,161.0,63.9,112.3,28.8,600,850,650,1850,700,600 +assignment_compatibility,8.5,5.5,585.4,583.5,164.7,52.2,113.4,30.6,2000,2000,2000,2000,2000,2000 +call_argument_types,13.6,4.3,642.7,611.6,163.7,56.1,114.3,48.4,998,998,1002,998,998,1000 +callables_subtyping,12.6,4.4,522.1,571.4,164.2,39.3,109.7,29.1,600,600,600,600,600,600 +classvar_scoping,15.3,5.9,599.6,614.3,163.3,58.8,134.7,32.4,2000,2000,2000,2000,4000,2000 +constructors_call_init,9.0,4.1,592.2,596.6,162.6,38.8,103.8,26.6,444,370,296,370,444,518 +dataclasses_usage,9.4,4.0,1559.4,642.0,164.7,61.8,176.1,56.6,500,500,500,500,500,500 +dict_key_hashability,11.8,8.0,518.9,613.3,160.7,39.2,103.9,31.9,2000,2000,0,0,0,0 +enums_member_values,8.2,4.4,564.1,576.0,160.9,42.0,103.8,26.7,480,480,80,480,480,480 +final_reassignment,7.1,4.1,456.9,562.5,167.2,28.9,100.6,24.4,500,500,500,500,500,500 +generics_defaults_specialization,10.0,4.3,549.6,579.0,162.1,35.0,104.7,27.4,560,560,560,421,560,560 +literals_semantics,12.5,4.4,518.2,577.6,162.5,32.5,104.5,27.0,576,576,576,576,576,576 +match_exhaustiveness,11.0,4.2,521.6,600.0,163.2,36.7,111.4,27.4,500,0,0,500,0,0 +narrowing_typeis,9.4,4.2,539.3,582.8,160.2,34.5,104.9,26.4,520,520,520,520,520,520 +newtype_definition,10.4,5.4,715.1,628.9,164.4,25.1,118.3,35.8,2000,2000,2000,0,2000,2000 +overloads_evaluation,12.9,4.6,591.8,627.4,163.9,60.2,119.9,34.2,600,1401,801,600,600,801 +override_compatibility,14.2,5.0,635.9,598.1,164.0,42.0,111.2,28.2,200,200,300,1,200,300 +protocols_definition,10.1,5.5,562.6,580.4,163.1,35.5,103.7,27.5,536,402,402,335,402,402 +returns_compatibility,8.1,5.6,488.7,572.5,162.5,33.0,101.9,24.5,1080,540,540,540,540,540 +tuples_index,10.5,5.4,549.3,566.6,162.1,35.0,106.4,25.8,600,600,600,1800,600,600 +typeddict_key_access,10.6,4.4,610.2,582.1,162.0,37.4,107.3,26.6,500,500,500,500,500,500 +typeddict_readonly_inheritance,15.1,3.6,653.8,579.7,165.6,38.7,114.4,25.9,500,500,500,2,500,500 +typeddict_readonly_mutation,9.9,4.3,613.3,579.8,163.3,42.7,107.9,26.0,500,500,500,500,500,500 +typevar_constraints,17.2,5.5,720.8,577.9,165.2,42.3,113.6,34.1,2000,2000,2000,2000,2000,2000 +undefined_names,15.4,5.1,487.5,631.7,168.3,51.2,544.6,34.4,2000,2000,4000,2000,2000,4000 +unresolved_imports,12.9,5.1,455.6,710.6,167.7,284.5,897.7,294.6,2000,2000,2000,2000,2000,2000 From 9839f137e41180176422733d52ad2a08855fff08 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Sun, 2 Aug 2026 20:57:32 +1000 Subject: [PATCH 02/45] Fixes --- .../src/rules/generics_syntax_scoping/mod.rs | 2 +- .../generics_syntax_scoping/violations.rs | 57 +- crates/basilisk-checker/src/tyeval.rs | 364 ----------- crates/basilisk-checker/src/tyeval/accept.rs | 260 ++++++++ crates/basilisk-checker/src/tyeval/eval.rs | 570 ++++++++++++++++++ crates/basilisk-checker/src/tyeval/lower.rs | 364 +++++++++++ crates/basilisk-checker/src/tyeval/mod.rs | 44 ++ crates/basilisk-checker/src/tyeval/queries.rs | 54 ++ crates/basilisk-checker/src/tyeval/term.rs | 236 ++++++++ .../checker/generics_syntax_scoping_tests.rs | 46 ++ .../tests/checker/names_undefined_tests.rs | 43 ++ .../tests/tyeval_salsa_tests.rs | 100 +++ .../src/scope/pep695_scoping.rs | 3 - .../src/visitor/pep695_scoping.rs | 37 -- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 51 +- docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md | 22 +- 16 files changed, 1812 insertions(+), 441 deletions(-) delete mode 100644 crates/basilisk-checker/src/tyeval.rs create mode 100644 crates/basilisk-checker/src/tyeval/accept.rs create mode 100644 crates/basilisk-checker/src/tyeval/eval.rs create mode 100644 crates/basilisk-checker/src/tyeval/lower.rs create mode 100644 crates/basilisk-checker/src/tyeval/mod.rs create mode 100644 crates/basilisk-checker/src/tyeval/queries.rs create mode 100644 crates/basilisk-checker/src/tyeval/term.rs create mode 100644 crates/basilisk-checker/tests/tyeval_salsa_tests.rs diff --git a/crates/basilisk-checker/src/rules/generics_syntax_scoping/mod.rs b/crates/basilisk-checker/src/rules/generics_syntax_scoping/mod.rs index fa73772c..449abd1d 100644 --- a/crates/basilisk-checker/src/rules/generics_syntax_scoping/mod.rs +++ b/crates/basilisk-checker/src/rules/generics_syntax_scoping/mod.rs @@ -69,7 +69,7 @@ impl Rule for Pep695TypeParamScopingViolation { diagnostics, ); violations::check_type_alias_in_function(scoping, path, diagnostics); - violations::check_type_alias_circular(scoping, path, diagnostics); + violations::check_type_alias_circular(module, scoping, path, diagnostics); alias_misuse::check_type_alias_misuse(module, scoping, diagnostics); alias_misuse::check_type_alias_bound_violations(module, scoping, diagnostics); diff --git a/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs b/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs index 7668ed2c..b72bb139 100644 --- a/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs +++ b/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs @@ -273,33 +273,35 @@ pub(super) fn check_type_alias_in_function( // Violation 6: a circular `type` alias definition // --------------------------------------------------------------------------- -/// A `type` alias is circular when it references itself with no type parameters, -/// or recurses through *different* type arguments than its own parameters. +/// A `type` alias is circular when its recursion fails the Stage 3 +/// acceptance conditions ([TYPEINF-TARGET-TYPELEVEL], +/// [`crate::tyeval::accept`]): **unguarded** self-reference (`type X = X`, +/// `type X = int | X` — union arms do not guard, so no weak head normal +/// form exists) or **non-regular** self-application (arguments grow per +/// unfold, e.g. `type R[T] = set[R[list[T]]]`). Ordinary guarded recursion +/// — `type J = list[J]`, the canonical `JsonValue` union, identity- or +/// ground-argument applications — is the PEP 695-mandated valid form and +/// produces NO diagnostic +/// ([#371](https://github.com/Nimblesite/Basilisk/issues/371)). pub(super) fn check_type_alias_circular( + module: &basilisk_resolver::ResolvedModule, scoping: &Pep695Scoping, path: &str, diagnostics: &mut Vec, ) { - for alias in &scoping.aliases { - if alias.params.is_empty() { - if alias.rhs_refs.iter().any(|r| r == &alias.name) { - push_circular(alias, "references itself", path, diagnostics); - } - continue; - } - let Some(args) = &alias.self_ref_args else { - continue; - }; - let param_names: Vec<&str> = alias.params.iter().map(|p| p.name.as_str()).collect(); - let identity = args.len() == param_names.len() - && args - .iter() - .zip(¶m_names) - .all(|(arg, param)| arg == param); - if !identity { + use crate::tyeval::{classify, lower_module_aliases, Acceptance}; + + if let Some(parsed) = crate::rules::shared::parse_module(module) { + for lowered in lower_module_aliases(&parsed.ast) { + let detail = match classify(&lowered.name, &lowered.def) { + Acceptance::Accepted => continue, + Acceptance::Unguarded => "references itself", + Acceptance::NonRegular => "references itself with different type arguments", + }; push_circular( - alias, - "references itself with different type arguments", + &lowered.name, + crate::span_util::text_range_to_span(lowered.name_range), + detail, path, diagnostics, ); @@ -329,7 +331,8 @@ fn check_mutual_alias_cycles( for alias in &scoping.aliases { if reaches_self(&alias.name, alias, &alias_by_name) { push_circular( - alias, + &alias.name, + alias.name_span, "is part of a circular alias chain", path, diagnostics, @@ -367,18 +370,20 @@ fn reaches_self( } fn push_circular( - alias: &Pep695AliasDef, + name: &str, + name_span: Span, detail: &str, path: &str, diagnostics: &mut Vec, ) { diagnostics.push(error_diagnostic_owned( CODE.clone(), - format!("Circular type alias definition: `{}` {detail}", alias.name), - alias.name_span, + format!("Circular type alias definition: `{name}` {detail}"), + name_span, path, Some( - "Recursive type aliases must reference themselves with the same type parameters" + "A recursive type alias must reference itself beneath a type constructor \ + (e.g. `type Json = int | list[Json]`) with non-growing type arguments" .to_owned(), ), None, diff --git a/crates/basilisk-checker/src/tyeval.rs b/crates/basilisk-checker/src/tyeval.rs deleted file mode 100644 index d3c87368..00000000 --- a/crates/basilisk-checker/src/tyeval.rs +++ /dev/null @@ -1,364 +0,0 @@ -//! Implements [TYPEINF-TARGET] and [TYPEINF-TARGET-TYPELEVEL] Stage 3 -//! groundwork. See -//! docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-CHECKLIST -//! ("Stage 3 — type-level evaluation groundwork"). -//! -//! Python's type-hint sublanguage is Turing-complete (Roth, -//! ), so recursive/parameterised type -//! aliases must be *evaluated*, not expanded eagerly. This module is the -//! normalization-by-evaluation core: -//! -//! - [`TypeTerm`] — the type-level term language: ground types, alias -//! references with arguments (kind `Type → Type` operators — PEP 695 -//! `type Pair[T] = tuple[T, T]`), and parameter references; -//! - [`evaluate`] — lazy unfolding to **weak head normal form**: aliases -//! unfold only until an outermost constructor appears; arguments -//! substitute lazily (mapped-type applications rewrite on demand); -//! - **fuel and depth bounds** with **memoization** of normalized results -//! per `(alias, argument)` application; -//! - the **`Divergent` fallback**: running out of fuel, unguarded -//! recursion, or an unknown alias yields [`Eval::Divergent`], which -//! projects to the gradual `Unknown` — evaluation failure NEVER invents -//! an error ([TYPEINF-TARGET-GRADUAL]); -//! - a **guardedness acceptance condition** (the Paterson/Coverage-style -//! analogue): an alias whose recursive self-reference is not under a -//! constructor (`type X = X`) is rejected up front, with the recursion -//! depth cap as the escape hatch for accepted-but-deep definitions. - -use std::collections::HashMap; - -use crate::types::InferredType; - -/// Fuel: total alias unfoldings one evaluation may perform. -const EVAL_FUEL: u32 = 256; -/// Depth: maximum nesting of constructors descended while normalizing. -const EVAL_DEPTH: u32 = 64; - -/// A type-level term. -#[derive(Debug, Clone, PartialEq)] -pub enum TypeTerm { - /// A ground type — already a value. - Ground(InferredType), - /// A reference to an alias, possibly applied: `Pair[int]`, `Json`. - Alias(String, Vec), - /// A reference to the enclosing alias's parameter by index. - Param(usize), - /// `list[T]` at the type level (constructor — a whnf head). - List(Box), - /// `T | U` at the type level. - Union(Vec), - /// `tuple[T, ..]` at the type level. - Tuple(Vec), -} - -/// One alias definition: `type Name[P0, P1, ..] = body`. -#[derive(Debug, Clone, PartialEq)] -pub struct AliasDef { - /// Number of type parameters. - pub arity: usize, - /// The right-hand side, with [`TypeTerm::Param`] for parameters. - pub body: TypeTerm, -} - -/// The alias environment (one module's `type` statements). -#[derive(Debug, Clone, Default)] -pub struct AliasEnv { - aliases: HashMap, -} - -impl AliasEnv { - /// Register an alias; rejects (returns `false`, leaving the environment - /// unchanged) definitions that fail the guardedness acceptance - /// condition — a recursive self-reference not under a constructor - /// (`type X = X`, `type X = X | int` at the top level of a union arm is - /// GUARDED only through constructors, so plain `X` arms are rejected). - pub fn insert(&mut self, name: &str, def: AliasDef) -> bool { - if !recursion_is_guarded(name, &def.body, false) { - return false; - } - let _ = self.aliases.insert(name.to_owned(), def); - true - } - - /// Look up an alias. - #[must_use] - pub fn get(&self, name: &str) -> Option<&AliasDef> { - self.aliases.get(name) - } -} - -/// The guardedness acceptance condition: every self-reference must sit -/// beneath at least one constructor. `under_constructor` tracks whether the -/// walk has passed through `List`/`Tuple` (unions do NOT guard — a union arm -/// unfolds at the same level). -fn recursion_is_guarded(name: &str, term: &TypeTerm, under_constructor: bool) -> bool { - match term { - TypeTerm::Alias(alias, args) => { - (alias != name || under_constructor) - && args - .iter() - .all(|arg| recursion_is_guarded(name, arg, under_constructor)) - } - TypeTerm::List(inner) => recursion_is_guarded(name, inner, true), - TypeTerm::Tuple(items) => items - .iter() - .all(|item| recursion_is_guarded(name, item, true)), - TypeTerm::Union(arms) => arms - .iter() - .all(|arm| recursion_is_guarded(name, arm, under_constructor)), - TypeTerm::Ground(_) | TypeTerm::Param(_) => true, - } -} - -/// A weak-head-normal-form outcome. -#[derive(Debug, Clone, PartialEq)] -pub enum Eval { - /// Normalized to a head constructor (projected to [`InferredType`], - /// with unevaluated sub-terms projected conservatively). - Value(InferredType), - /// Fuel/depth exhausted, unguarded shape, or unknown alias — the - /// divergent sentinel. Projects to `Unknown`: never an invented error - /// ([TYPEINF-TARGET-GRADUAL]). - Divergent, -} - -impl Eval { - /// Project to the checker's type lattice. - #[must_use] - pub fn into_inferred(self) -> InferredType { - match self { - Eval::Value(ty) => ty, - Eval::Divergent => InferredType::Unknown, - } - } -} - -/// Evaluator state: fuel plus the `(alias, args)` application memo. -#[derive(Debug, Default)] -pub struct Evaluator { - fuel: u32, - memo: HashMap<(String, String), Eval>, -} - -impl Evaluator { - /// A fresh evaluator with full fuel. - #[must_use] - pub fn new() -> Self { - Self { - fuel: EVAL_FUEL, - memo: HashMap::new(), - } - } - - /// Evaluate `term` to weak head normal form under `env`. - pub fn evaluate(&mut self, env: &AliasEnv, term: &TypeTerm) -> Eval { - self.eval_at(env, term, &[], 0) - } - - /// Core: lazy unfolding with parameter substitution from `args`. - fn eval_at(&mut self, env: &AliasEnv, term: &TypeTerm, args: &[TypeTerm], depth: u32) -> Eval { - if depth > EVAL_DEPTH { - return Eval::Divergent; - } - match term { - TypeTerm::Ground(ty) => Eval::Value(ty.clone()), - TypeTerm::Param(index) => match args.get(*index) { - Some(argument) => self.eval_at(env, &argument.clone(), &[], depth + 1), - None => Eval::Divergent, - }, - TypeTerm::Alias(name, alias_args) => { - self.eval_alias(env, name, alias_args, args, depth) - } - TypeTerm::List(inner) => { - let element = self.eval_at(env, inner, args, depth + 1).into_inferred(); - Eval::Value(InferredType::List(Box::new(element))) - } - TypeTerm::Tuple(items) => { - let elements = items - .iter() - .map(|item| self.eval_at(env, item, args, depth + 1).into_inferred()) - .collect(); - Eval::Value(InferredType::Tuple(elements)) - } - TypeTerm::Union(arms) => { - let union = arms - .iter() - .map(|arm| self.eval_at(env, arm, args, depth + 1).into_inferred()) - .fold(InferredType::Never, InferredType::union); - Eval::Value(union) - } - } - } - - /// Unfold one alias application, memoized per `(alias, args)`. - fn eval_alias( - &mut self, - env: &AliasEnv, - name: &str, - alias_args: &[TypeTerm], - outer_args: &[TypeTerm], - depth: u32, - ) -> Eval { - let key = (name.to_owned(), format!("{alias_args:?}|{outer_args:?}")); - if let Some(cached) = self.memo.get(&key) { - return cached.clone(); - } - if self.fuel == 0 { - return Eval::Divergent; - } - self.fuel -= 1; - - let Some(def) = env.get(name) else { - return Eval::Divergent; - }; - if def.arity != alias_args.len() { - return Eval::Divergent; - } - // Substitute the application's arguments (resolving any outer - // parameters lazily) and unfold the body one step. - let substituted: Vec = alias_args - .iter() - .map(|arg| substitute(arg, outer_args)) - .collect(); - let body = def.body.clone(); - let result = self.eval_at(env, &body, &substituted, depth + 1); - let _ = self.memo.insert(key, result.clone()); - result - } -} - -/// Replace [`TypeTerm::Param`] references with `args` (lazy: nested alias -/// applications keep their own bodies unexpanded). -fn substitute(term: &TypeTerm, args: &[TypeTerm]) -> TypeTerm { - match term { - TypeTerm::Param(index) => args - .get(*index) - .cloned() - .unwrap_or(TypeTerm::Ground(InferredType::Unknown)), - TypeTerm::Alias(name, alias_args) => TypeTerm::Alias( - name.clone(), - alias_args.iter().map(|a| substitute(a, args)).collect(), - ), - TypeTerm::List(inner) => TypeTerm::List(Box::new(substitute(inner, args))), - TypeTerm::Tuple(items) => { - TypeTerm::Tuple(items.iter().map(|i| substitute(i, args)).collect()) - } - TypeTerm::Union(arms) => { - TypeTerm::Union(arms.iter().map(|a| substitute(a, args)).collect()) - } - TypeTerm::Ground(_) => term.clone(), - } -} - -#[cfg(test)] -mod tests { - use super::*; - - fn int() -> TypeTerm { - TypeTerm::Ground(InferredType::Int) - } - - /// A mapped-type operator (`type Pair[T] = tuple[T, T]`) applies lazily. - #[test] - fn mapped_alias_applies_arguments() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "pair", - AliasDef { - arity: 1, - body: TypeTerm::Tuple(vec![TypeTerm::Param(0), TypeTerm::Param(0)]), - }, - )); - let mut evaluator = Evaluator::new(); - let result = evaluator.evaluate(&env, &TypeTerm::Alias("pair".to_owned(), vec![int()])); - assert_eq!( - result, - Eval::Value(InferredType::Tuple(vec![ - InferredType::Int, - InferredType::Int - ])) - ); - } - - /// A guarded recursive alias (`type Json = int | list[Json]`) evaluates - /// to whnf — the recursive arm normalizes under fuel without expanding - /// forever. - #[test] - fn guarded_recursion_reaches_whnf() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "json", - AliasDef { - arity: 0, - body: TypeTerm::Union(vec![ - int(), - TypeTerm::List(Box::new(TypeTerm::Alias("json".to_owned(), Vec::new()))), - ]), - }, - )); - let mut evaluator = Evaluator::new(); - let result = evaluator - .evaluate(&env, &TypeTerm::Alias("json".to_owned(), Vec::new())) - .into_inferred(); - // The head is a union of int and list[...]; the recursive interior - // bottoms out gradually rather than diverging. - assert!(InferredType::Int.is_assignable_to(&result)); - assert!( - InferredType::List(Box::new(InferredType::Unknown)).is_assignable_to(&result), - "list arm must be present: {result:?}" - ); - } - - /// The guardedness acceptance condition rejects `type X = X` up front. - #[test] - fn unguarded_recursion_is_rejected() { - let mut env = AliasEnv::default(); - assert!(!env.insert( - "x", - AliasDef { - arity: 0, - body: TypeTerm::Alias("x".to_owned(), Vec::new()), - }, - )); - // Union arms do not guard either: `type X = int | X`. - assert!(!env.insert( - "x", - AliasDef { - arity: 0, - body: TypeTerm::Union(vec![int(), TypeTerm::Alias("x".to_owned(), Vec::new())]), - }, - )); - } - - /// Unknown aliases and fuel exhaustion produce `Divergent`, which - /// projects to the gradual `Unknown` — never an error - /// ([TYPEINF-TARGET-GRADUAL]). - #[test] - fn divergence_projects_to_unknown() { - let env = AliasEnv::default(); - let mut evaluator = Evaluator::new(); - let result = evaluator.evaluate(&env, &TypeTerm::Alias("missing".to_owned(), Vec::new())); - assert_eq!(result, Eval::Divergent); - assert_eq!(result.into_inferred(), InferredType::Unknown); - } - - /// Memoization: re-evaluating the same application does not spend fuel - /// again (the second call is a cache hit even with zero fuel left). - #[test] - fn applications_are_memoized() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "wrap", - AliasDef { - arity: 1, - body: TypeTerm::List(Box::new(TypeTerm::Param(0))), - }, - )); - let mut evaluator = Evaluator::new(); - let term = TypeTerm::Alias("wrap".to_owned(), vec![int()]); - let first = evaluator.evaluate(&env, &term); - evaluator.fuel = 0; - let second = evaluator.evaluate(&env, &term); - assert_eq!(first, second, "memo hit must not need fuel"); - } -} diff --git a/crates/basilisk-checker/src/tyeval/accept.rs b/crates/basilisk-checker/src/tyeval/accept.rs new file mode 100644 index 00000000..f1d05c90 --- /dev/null +++ b/crates/basilisk-checker/src/tyeval/accept.rs @@ -0,0 +1,260 @@ +//! Implements [TYPEINF-TARGET-TYPELEVEL] — the GHC-style acceptance +//! conditions (Paterson/Coverage analogues) for recursive type aliases. +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL +//! +//! Type-level computation here is Turing-complete (Roth, +//! ), so definitions are admitted only +//! when termination is evident from their shape — mirroring how GHC's +//! Paterson and Coverage Conditions admit only structurally-decreasing +//! instances (GHC User's Guide §6.8.8): +//! +//! 1. **Guardedness** (contractivity): every self-reference must sit under +//! at least one type *constructor* (`list[..]`, `dict[..]`, `tuple[..]`, +//! `set[..]`, any `Named[..]` subscript — including the argument +//! positions of alias applications, which unfold lazily). Union arms and +//! conditional-type positions do NOT guard: a `type X = X` or +//! `type X = int | X` arm unfolds at the same level forever and has no +//! weak head normal form. This is the conformance-mandated boundary — +//! upstream `aliases_type_statement.py` requires an error on +//! `type R3 = R3` and `type R4[T] = T | R4[str]`, while +//! `type R1[T] = T | list[R1[T]]` must be clean. +//! 2. **Regularity** (the Paterson/Coverage analogue): every +//! self-application's arguments must be non-growing — each argument is +//! either a bare parameter reference (Coverage: the parameter is +//! "covered" exactly as declared) or completely parameter- and +//! self-free (Paterson: no constructor growth around the recursive +//! call). `type R[T] = set[R[T]]` and `type A[T] = list[A[int]]` pass; +//! `type R[T] = set[R[list[T]]]` grows a fresh instantiation per unfold +//! and is rejected. +//! +//! Rejected definitions can still be admitted through +//! [`super::AliasEnv::insert_undecidable`] — the opt-in "undecidable" +//! escape hatch — where the evaluator's fuel/depth bounds take over and +//! truncation projects to the gradual `Unknown` ([TYPEINF-TARGET-GRADUAL]). + +use super::term::{AliasDef, CondTerm, TypeTerm}; + +/// The verdict of the acceptance conditions for one alias definition. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Acceptance { + /// Termination is evident: admitted with full trust. + Accepted, + /// A self-reference occurs outside every constructor (`type X = X`, + /// `type X = int | X`): no whnf exists — a genuine circular definition. + Unguarded, + /// Guarded, but a self-application's arguments grow (non-regular + /// recursion): infinitely many distinct instantiations are reachable. + NonRegular, +} + +/// Classify `def` (named `name`) against the acceptance conditions. +#[must_use] +pub fn classify(name: &str, def: &AliasDef) -> Acceptance { + if !guarded(name, &def.body, false) { + return Acceptance::Unguarded; + } + if !regular(name, &def.body) { + return Acceptance::NonRegular; + } + Acceptance::Accepted +} + +/// Guardedness: every self-reference sits beneath at least one constructor. +/// +/// `under` tracks whether the walk has passed through a constructor. +/// Subscript *argument* positions count as guarded — they unfold lazily, so +/// recursion through them makes progress toward a head (`type A = B[A]` +/// reaches whnf as soon as `B`'s body exposes a constructor; if it never +/// does, evaluation exhausts fuel and projects to the gradual `Unknown` +/// rather than looping). Union arms and every conditional-type position +/// stay at the same level and do not guard. +fn guarded(name: &str, term: &TypeTerm, under: bool) -> bool { + match term { + TypeTerm::Alias(alias, args) => { + (alias != name || under) && args.iter().all(|arg| guarded(name, arg, true)) + } + TypeTerm::Op(alias) => alias != name || under, + TypeTerm::Apply(head, args) => { + guarded(name, head, under) && args.iter().all(|arg| guarded(name, arg, true)) + } + TypeTerm::List(inner) | TypeTerm::Set(inner) => guarded(name, inner, true), + TypeTerm::Dict(key, value) => guarded(name, key, true) && guarded(name, value, true), + TypeTerm::Tuple(items) | TypeTerm::Named(_, items) => { + items.iter().all(|item| guarded(name, item, true)) + } + TypeTerm::Union(arms) => arms.iter().all(|arm| guarded(name, arm, under)), + TypeTerm::Cond(cond) => cond_positions(cond).all(|part| guarded(name, part, under)), + TypeTerm::Ground(_) | TypeTerm::Param(_) => true, + } +} + +/// Regularity: every self-application's arguments are non-growing — each is +/// a bare [`TypeTerm::Param`] or completely parameter- and self-free. +fn regular(name: &str, term: &TypeTerm) -> bool { + let self_app_ok = |args: &[TypeTerm]| { + args.iter() + .all(|arg| matches!(arg, TypeTerm::Param(_)) || is_closed(name, arg)) + }; + match term { + TypeTerm::Alias(alias, args) => { + (alias != name || self_app_ok(args)) && args.iter().all(|arg| regular(name, arg)) + } + TypeTerm::Apply(head, args) => { + let applies_self = matches!(&**head, TypeTerm::Op(alias) if alias == name); + (!applies_self || self_app_ok(args)) + && regular(name, head) + && args.iter().all(|arg| regular(name, arg)) + } + TypeTerm::List(inner) | TypeTerm::Set(inner) => regular(name, inner), + TypeTerm::Dict(key, value) => regular(name, key) && regular(name, value), + TypeTerm::Tuple(items) | TypeTerm::Union(items) | TypeTerm::Named(_, items) => { + items.iter().all(|item| regular(name, item)) + } + TypeTerm::Cond(cond) => cond_positions(cond).all(|part| regular(name, part)), + TypeTerm::Ground(_) | TypeTerm::Param(_) | TypeTerm::Op(_) => true, + } +} + +/// Is `term` free of parameters AND of references to `name`? Such an +/// argument cannot grow the instantiation set (Paterson: it contributes a +/// fixed, finite term). +fn is_closed(name: &str, term: &TypeTerm) -> bool { + match term { + TypeTerm::Param(_) => false, + TypeTerm::Ground(_) => true, + TypeTerm::Op(alias) => alias != name, + TypeTerm::Alias(alias, args) => { + alias != name && args.iter().all(|arg| is_closed(name, arg)) + } + TypeTerm::Apply(head, args) => { + is_closed(name, head) && args.iter().all(|arg| is_closed(name, arg)) + } + TypeTerm::List(inner) | TypeTerm::Set(inner) => is_closed(name, inner), + TypeTerm::Dict(key, value) => is_closed(name, key) && is_closed(name, value), + TypeTerm::Tuple(items) | TypeTerm::Union(items) | TypeTerm::Named(_, items) => { + items.iter().all(|item| is_closed(name, item)) + } + TypeTerm::Cond(cond) => cond_positions(cond).all(|part| is_closed(name, part)), + } +} + +/// The four positions of a conditional type, for uniform traversal. +fn cond_positions(cond: &CondTerm) -> impl Iterator { + [ + &cond.scrutinee, + &cond.against, + &cond.then_arm, + &cond.else_arm, + ] + .into_iter() +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::types::InferredType; + + fn int() -> TypeTerm { + TypeTerm::Ground(InferredType::Int) + } + + fn self_ref(args: Vec) -> TypeTerm { + TypeTerm::Alias("X".to_owned(), args) + } + + fn classify_body(arity: usize, body: TypeTerm) -> Acceptance { + classify("X", &AliasDef { arity, body }) + } + + /// Guarded recursion in every constructor is accepted — the #371 + /// boundary: `list`, `dict`, `set`, `tuple`, and arbitrary `Named` + /// subscripts all guard. + #[test] + fn guarded_recursion_is_accepted() { + let cases = [ + TypeTerm::List(Box::new(self_ref(Vec::new()))), + TypeTerm::Union(vec![int(), TypeTerm::List(Box::new(self_ref(Vec::new())))]), + TypeTerm::Dict(Box::new(TypeTerm::Ground(InferredType::Str)), Box::new(self_ref(Vec::new()))), + TypeTerm::Set(Box::new(self_ref(Vec::new()))), + TypeTerm::Tuple(vec![self_ref(Vec::new()), int()]), + TypeTerm::Named("Sequence".to_owned(), vec![self_ref(Vec::new())]), + ]; + for body in cases { + assert_eq!(classify_body(0, body.clone()), Acceptance::Accepted, "{body:?}"); + } + } + + /// Unguarded self-references — bare, or through union arms — are the + /// genuine circular definitions and are rejected. + #[test] + fn unguarded_recursion_is_rejected() { + let cases = [ + self_ref(Vec::new()), + TypeTerm::Union(vec![int(), self_ref(Vec::new())]), + TypeTerm::Union(vec![TypeTerm::Param(0), self_ref(vec![int()])]), + ]; + for body in cases { + assert_eq!(classify_body(1, body.clone()), Acceptance::Unguarded, "{body:?}"); + } + } + + /// Regular self-applications — identity parameters or closed arguments + /// — are accepted (Coverage/Paterson satisfied). + #[test] + fn regular_self_applications_are_accepted() { + let identity = TypeTerm::Set(Box::new(self_ref(vec![TypeTerm::Param(0)]))); + let closed = TypeTerm::List(Box::new(self_ref(vec![int()]))); + assert_eq!(classify_body(1, identity), Acceptance::Accepted); + assert_eq!(classify_body(1, closed), Acceptance::Accepted); + } + + /// Growing self-applications — a parameter under a constructor, or a + /// nested self-reference, in argument position — are non-regular. + #[test] + fn growing_self_applications_are_non_regular() { + let growing_param = TypeTerm::Set(Box::new(self_ref(vec![TypeTerm::List(Box::new( + TypeTerm::Param(0), + ))]))); + let nested_self = TypeTerm::Set(Box::new(self_ref(vec![TypeTerm::Union(vec![ + TypeTerm::Param(0), + self_ref(vec![TypeTerm::Param(0)]), + ])]))); + assert_eq!(classify_body(1, growing_param), Acceptance::NonRegular); + assert_eq!(classify_body(1, nested_self), Acceptance::NonRegular); + } + + /// Conditional-type positions do not guard: a self-reference in an arm + /// (even the lazily-evaluated one) is statically unguarded, because the + /// taken arm unfolds at the same level. + #[test] + fn conditional_positions_do_not_guard() { + let cond = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: TypeTerm::Param(0), + against: int(), + then_arm: int(), + else_arm: self_ref(vec![TypeTerm::Param(0)]), + })); + assert_eq!(classify_body(1, cond), Acceptance::Unguarded); + + let guarded_cond = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: TypeTerm::Param(0), + against: int(), + then_arm: int(), + else_arm: TypeTerm::List(Box::new(self_ref(vec![TypeTerm::Param(0)]))), + })); + assert_eq!(classify_body(1, guarded_cond), Acceptance::Accepted); + } + + /// Operator references participate: an unapplied self-`Op` at the top + /// is unguarded; applying self through `Apply` with growing arguments + /// is non-regular. + #[test] + fn operator_forms_are_classified() { + assert_eq!(classify_body(1, TypeTerm::Op("X".to_owned())), Acceptance::Unguarded); + let apply_growing = TypeTerm::List(Box::new(TypeTerm::Apply( + Box::new(TypeTerm::Op("X".to_owned())), + vec![TypeTerm::List(Box::new(TypeTerm::Param(0)))], + ))); + assert_eq!(classify_body(1, apply_growing), Acceptance::NonRegular); + } +} diff --git a/crates/basilisk-checker/src/tyeval/eval.rs b/crates/basilisk-checker/src/tyeval/eval.rs new file mode 100644 index 00000000..fa7184b4 --- /dev/null +++ b/crates/basilisk-checker/src/tyeval/eval.rs @@ -0,0 +1,570 @@ +//! Implements [TYPEINF-TARGET-TYPELEVEL] — the bounded, memoized, +//! call-by-need evaluator to weak head normal form. +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL +//! +//! - **Laziness**: aliases unfold only until an outermost constructor +//! appears; conditional types normalize the scrutinee, decide the +//! rewrite by assignability, and evaluate ONLY the taken arm — an +//! untaken divergent arm never runs (call-by-need). +//! - **Fuel and depth bounds** with **memoization** of normalized results +//! per application (TypeScript's instantiation-depth model). +//! - **The `Divergent` fallback**: running out of fuel/depth, an unknown +//! alias, or an ill-kinded application yields [`Eval::Divergent`], which +//! projects to the gradual `Unknown` — evaluation failure NEVER invents +//! an error ([TYPEINF-TARGET-GRADUAL]). + +use std::collections::HashMap; + +use crate::types::InferredType; + +use super::term::{AliasEnv, CondTerm, TypeTerm}; + +/// Fuel: total alias unfoldings one evaluation may perform. +const EVAL_FUEL: u32 = 256; +/// Depth: maximum nesting of constructors descended while normalizing. +const EVAL_DEPTH: u32 = 64; + +/// A weak-head-normal-form outcome. +#[derive(Debug, Clone, PartialEq)] +pub enum Eval { + /// Normalized to a head constructor (projected to [`InferredType`], + /// with unevaluated sub-terms projected conservatively). + Value(InferredType), + /// Fuel/depth exhausted, unguarded shape, unknown alias, or ill-kinded + /// application — the divergent sentinel. Projects to `Unknown`: never + /// an invented error ([TYPEINF-TARGET-GRADUAL]). + Divergent, +} + +impl Eval { + /// Project to the checker's type lattice. + #[must_use] + pub fn into_inferred(self) -> InferredType { + match self { + Eval::Value(ty) => ty, + Eval::Divergent => InferredType::Unknown, + } + } +} + +/// Evaluator state: fuel plus the `(alias, args)` application memo. +#[derive(Debug, Default)] +pub struct Evaluator { + pub(super) fuel: u32, + memo: HashMap<(String, String), Eval>, +} + +impl Evaluator { + /// A fresh evaluator with full fuel. + #[must_use] + pub fn new() -> Self { + Self { + fuel: EVAL_FUEL, + memo: HashMap::new(), + } + } + + /// Evaluate `term` to weak head normal form under `env`. + pub fn evaluate(&mut self, env: &AliasEnv, term: &TypeTerm) -> Eval { + self.eval_at(env, term, &[], 0) + } + + /// Core: lazy unfolding with parameter substitution from `args`. + fn eval_at(&mut self, env: &AliasEnv, term: &TypeTerm, args: &[TypeTerm], depth: u32) -> Eval { + if depth > EVAL_DEPTH { + return Eval::Divergent; + } + match term { + TypeTerm::Ground(ty) => Eval::Value(ty.clone()), + TypeTerm::Param(index) => match args.get(*index) { + Some(argument) => self.eval_at(env, &argument.clone(), &[], depth + 1), + None => Eval::Divergent, + }, + TypeTerm::Alias(name, alias_args) => { + self.eval_application(env, name, alias_args, args, depth) + } + // An unapplied operator is not a proper type: as a whnf demand + // it is ill-kinded (`Kind::Operator`, not `Kind::Type`) unless + // nullary, in which case it is an ordinary alias reference. + TypeTerm::Op(name) => match env.get(name) { + Some(def) if def.arity == 0 => self.eval_application(env, name, &[], args, depth), + _ => Eval::Divergent, + }, + TypeTerm::Apply(head, apply_args) => self.eval_apply(env, head, apply_args, args, depth), + TypeTerm::Cond(cond) => self.eval_cond(env, cond, args, depth), + TypeTerm::List(inner) => { + let element = self.eval_at(env, inner, args, depth + 1).into_inferred(); + Eval::Value(InferredType::List(Box::new(element))) + } + TypeTerm::Set(inner) => { + let element = self.eval_at(env, inner, args, depth + 1).into_inferred(); + Eval::Value(InferredType::Set(Box::new(element))) + } + TypeTerm::Dict(key, value) => { + let key_ty = self.eval_at(env, key, args, depth + 1).into_inferred(); + let value_ty = self.eval_at(env, value, args, depth + 1).into_inferred(); + Eval::Value(InferredType::Dict(Box::new(key_ty), Box::new(value_ty))) + } + TypeTerm::Tuple(items) => { + let elements = items + .iter() + .map(|item| self.eval_at(env, item, args, depth + 1).into_inferred()) + .collect(); + Eval::Value(InferredType::Tuple(elements)) + } + TypeTerm::Named(name, items) => { + // A named constructor is already a whnf head; its arguments + // project conservatively for display/assignability use. + let _ = items; + Eval::Value(InferredType::Named(name.clone())) + } + TypeTerm::Union(arms) => { + let union = arms + .iter() + .map(|arm| self.eval_at(env, arm, args, depth + 1).into_inferred()) + .fold(InferredType::Never, InferredType::union); + Eval::Value(union) + } + } + } + + /// Higher-order application: normalize the head to an operator value + /// (a [`TypeTerm::Op`], possibly reached through a parameter), then + /// unfold it. Applying a non-operator or mismatching the kind's arity + /// is ill-kinded → [`Eval::Divergent`] (gradual, never an error). + fn eval_apply( + &mut self, + env: &AliasEnv, + head: &TypeTerm, + apply_args: &[TypeTerm], + outer_args: &[TypeTerm], + depth: u32, + ) -> Eval { + let resolved_head = match head { + TypeTerm::Param(index) => match outer_args.get(*index) { + Some(bound) => bound.clone(), + None => return Eval::Divergent, + }, + other => other.clone(), + }; + match resolved_head { + TypeTerm::Op(name) | TypeTerm::Alias(name, _) => { + self.eval_application(env, &name, apply_args, outer_args, depth) + } + _ => Eval::Divergent, + } + } + + /// A conditional type: force the scrutinee to whnf, decide + /// `scrutinee <: against`, then evaluate ONLY the taken arm + /// (call-by-need). A union scrutinee distributes over its arms — the + /// TypeScript/PEP 827 distribution rule — each arm rewritten lazily. + /// An undecidable scrutinee (gradual `Unknown`) makes the whole + /// conditional gradual rather than guessing a branch. + fn eval_cond(&mut self, env: &AliasEnv, cond: &CondTerm, args: &[TypeTerm], depth: u32) -> Eval { + let scrutinee = match self.eval_at(env, &cond.scrutinee, args, depth + 1) { + Eval::Value(ty) => ty, + Eval::Divergent => return Eval::Divergent, + }; + if let InferredType::Union(members) = scrutinee { + return self.distribute_cond(env, cond, members, args, depth); + } + let against = match self.eval_at(env, &cond.against, args, depth + 1) { + Eval::Value(ty) => ty, + Eval::Divergent => return Eval::Divergent, + }; + if matches!(scrutinee, InferredType::Unknown) { + // Cannot decide the rewrite gradually — do not guess a branch. + return Eval::Divergent; + } + let arm = if scrutinee.is_assignable_to(&against) { + &cond.then_arm + } else { + &cond.else_arm + }; + self.eval_at(env, arm, args, depth + 1) + } + + /// Distribution of a conditional over a union scrutinee: rewrite each + /// member independently and union the results. + fn distribute_cond( + &mut self, + env: &AliasEnv, + cond: &CondTerm, + members: Vec, + args: &[TypeTerm], + depth: u32, + ) -> Eval { + let mut result = InferredType::Never; + for member in members { + let member_cond = CondTerm { + scrutinee: TypeTerm::Ground(member), + against: cond.against.clone(), + then_arm: cond.then_arm.clone(), + else_arm: cond.else_arm.clone(), + }; + match self.eval_cond(env, &member_cond, args, depth) { + Eval::Value(ty) => result = InferredType::union(result, ty), + Eval::Divergent => return Eval::Divergent, + } + } + Eval::Value(result) + } + + /// Unfold one alias application, memoized per `(alias, args)`. + fn eval_application( + &mut self, + env: &AliasEnv, + name: &str, + alias_args: &[TypeTerm], + outer_args: &[TypeTerm], + depth: u32, + ) -> Eval { + let key = (name.to_owned(), format!("{alias_args:?}|{outer_args:?}")); + if let Some(cached) = self.memo.get(&key) { + return cached.clone(); + } + if self.fuel == 0 { + return Eval::Divergent; + } + self.fuel -= 1; + + let Some(def) = env.get(name) else { + return Eval::Divergent; + }; + // Kind check: the application must saturate the operator exactly. + if def.arity != alias_args.len() { + return Eval::Divergent; + } + // Substitute the application's arguments (resolving any outer + // parameters lazily) and unfold the body one step. + let substituted: Vec = alias_args + .iter() + .map(|arg| substitute(arg, outer_args)) + .collect(); + let body = def.body.clone(); + let result = self.eval_at(env, &body, &substituted, depth + 1); + let _ = self.memo.insert(key, result.clone()); + result + } +} + +/// Replace [`TypeTerm::Param`] references with `args` (lazy: nested alias +/// applications keep their own bodies unexpanded). +fn substitute(term: &TypeTerm, args: &[TypeTerm]) -> TypeTerm { + match term { + TypeTerm::Param(index) => args + .get(*index) + .cloned() + .unwrap_or(TypeTerm::Ground(InferredType::Unknown)), + TypeTerm::Alias(name, alias_args) => TypeTerm::Alias( + name.clone(), + alias_args.iter().map(|a| substitute(a, args)).collect(), + ), + TypeTerm::Op(name) => TypeTerm::Op(name.clone()), + TypeTerm::Apply(head, apply_args) => TypeTerm::Apply( + Box::new(substitute(head, args)), + apply_args.iter().map(|a| substitute(a, args)).collect(), + ), + TypeTerm::Cond(cond) => TypeTerm::Cond(Box::new(CondTerm { + scrutinee: substitute(&cond.scrutinee, args), + against: substitute(&cond.against, args), + then_arm: substitute(&cond.then_arm, args), + else_arm: substitute(&cond.else_arm, args), + })), + TypeTerm::List(inner) => TypeTerm::List(Box::new(substitute(inner, args))), + TypeTerm::Set(inner) => TypeTerm::Set(Box::new(substitute(inner, args))), + TypeTerm::Dict(key, value) => TypeTerm::Dict( + Box::new(substitute(key, args)), + Box::new(substitute(value, args)), + ), + TypeTerm::Tuple(items) => { + TypeTerm::Tuple(items.iter().map(|i| substitute(i, args)).collect()) + } + TypeTerm::Named(name, items) => TypeTerm::Named( + name.clone(), + items.iter().map(|i| substitute(i, args)).collect(), + ), + TypeTerm::Union(arms) => { + TypeTerm::Union(arms.iter().map(|a| substitute(a, args)).collect()) + } + TypeTerm::Ground(_) => term.clone(), + } +} + +#[cfg(test)] +mod tests { + use super::super::term::AliasDef; + use super::*; + + fn int() -> TypeTerm { + TypeTerm::Ground(InferredType::Int) + } + + fn str_ty() -> TypeTerm { + TypeTerm::Ground(InferredType::Str) + } + + /// A mapped-type operator (`type Pair[T] = tuple[T, T]`) applies lazily. + #[test] + fn mapped_alias_applies_arguments() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "pair", + AliasDef { + arity: 1, + body: TypeTerm::Tuple(vec![TypeTerm::Param(0), TypeTerm::Param(0)]), + }, + )); + let mut evaluator = Evaluator::new(); + let result = evaluator.evaluate(&env, &TypeTerm::Alias("pair".to_owned(), vec![int()])); + assert_eq!( + result, + Eval::Value(InferredType::Tuple(vec![ + InferredType::Int, + InferredType::Int + ])) + ); + } + + /// A guarded recursive alias (`type Json = int | list[Json]`) evaluates + /// to whnf — the recursive arm normalizes under fuel without expanding + /// forever. + #[test] + fn guarded_recursion_reaches_whnf() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "json", + AliasDef { + arity: 0, + body: TypeTerm::Union(vec![ + int(), + TypeTerm::List(Box::new(TypeTerm::Alias("json".to_owned(), Vec::new()))), + ]), + }, + )); + let mut evaluator = Evaluator::new(); + let result = evaluator + .evaluate(&env, &TypeTerm::Alias("json".to_owned(), Vec::new())) + .into_inferred(); + // The head is a union of int and list[...]; the recursive interior + // bottoms out gradually rather than diverging. + assert!(InferredType::Int.is_assignable_to(&result)); + assert!( + InferredType::List(Box::new(InferredType::Unknown)).is_assignable_to(&result), + "list arm must be present: {result:?}" + ); + } + + /// The guardedness acceptance condition rejects `type X = X` up front. + #[test] + fn unguarded_recursion_is_rejected() { + let mut env = AliasEnv::default(); + assert!(!env.insert( + "x", + AliasDef { + arity: 0, + body: TypeTerm::Alias("x".to_owned(), Vec::new()), + }, + )); + // Union arms do not guard either: `type X = int | X`. + assert!(!env.insert( + "x", + AliasDef { + arity: 0, + body: TypeTerm::Union(vec![int(), TypeTerm::Alias("x".to_owned(), Vec::new())]), + }, + )); + } + + /// Unknown aliases and fuel exhaustion produce `Divergent`, which + /// projects to the gradual `Unknown` — never an error + /// ([TYPEINF-TARGET-GRADUAL]). + #[test] + fn divergence_projects_to_unknown() { + let env = AliasEnv::default(); + let mut evaluator = Evaluator::new(); + let result = evaluator.evaluate(&env, &TypeTerm::Alias("missing".to_owned(), Vec::new())); + assert_eq!(result, Eval::Divergent); + assert_eq!(result.into_inferred(), InferredType::Unknown); + } + + /// Memoization: re-evaluating the same application does not spend fuel + /// again (the second call is a cache hit even with zero fuel left). + #[test] + fn applications_are_memoized() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "wrap", + AliasDef { + arity: 1, + body: TypeTerm::List(Box::new(TypeTerm::Param(0))), + }, + )); + let mut evaluator = Evaluator::new(); + let term = TypeTerm::Alias("wrap".to_owned(), vec![int()]); + let first = evaluator.evaluate(&env, &term); + evaluator.fuel = 0; + let second = evaluator.evaluate(&env, &term); + assert_eq!(first, second, "memo hit must not need fuel"); + } + + /// An escape-hatch alias (`insert_undecidable`) runs under fuel and + /// truncates to the gradual `Unknown` instead of looping — the + /// gradual guarantee on truncated evaluation. + #[test] + fn undecidable_alias_truncates_gradually() { + let mut env = AliasEnv::default(); + env.insert_undecidable( + "x", + AliasDef { + arity: 0, + body: TypeTerm::Alias("x".to_owned(), Vec::new()), + }, + ); + let result = Evaluator::new().evaluate(&env, &TypeTerm::Alias("x".to_owned(), Vec::new())); + assert_eq!(result, Eval::Divergent); + assert_eq!(result.into_inferred(), InferredType::Unknown); + } + + /// Dict/Set constructors normalize their components. + #[test] + fn dict_and_set_constructors_normalize() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "m", + AliasDef { + arity: 0, + body: TypeTerm::Dict(Box::new(str_ty()), Box::new(TypeTerm::Set(Box::new(int())))), + }, + )); + let result = Evaluator::new() + .evaluate(&env, &TypeTerm::Alias("m".to_owned(), Vec::new())) + .into_inferred(); + assert_eq!( + result, + InferredType::Dict( + Box::new(InferredType::Str), + Box::new(InferredType::Set(Box::new(InferredType::Int))) + ) + ); + } + + /// Conditional types rewrite on assignability and are call-by-need: + /// the untaken arm is a divergent (unknown) alias and is never forced. + #[test] + fn conditional_rewrites_lazily() { + let env = AliasEnv::default(); + let divergent_arm = TypeTerm::Alias("missing".to_owned(), Vec::new()); + let taken = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: int(), + against: int(), + then_arm: str_ty(), + else_arm: divergent_arm.clone(), + })); + assert_eq!( + Evaluator::new().evaluate(&env, &taken), + Eval::Value(InferredType::Str), + "then-arm taken; divergent else-arm must never be forced" + ); + + let not_taken = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: str_ty(), + against: int(), + then_arm: divergent_arm, + else_arm: int(), + })); + assert_eq!( + Evaluator::new().evaluate(&env, ¬_taken), + Eval::Value(InferredType::Int), + "else-arm taken; divergent then-arm must never be forced" + ); + } + + /// An `Unknown` scrutinee cannot decide the rewrite: the conditional + /// is gradual (`Divergent` → `Unknown`), never a guessed branch. + #[test] + fn conditional_on_unknown_scrutinee_is_gradual() { + let env = AliasEnv::default(); + let cond = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: TypeTerm::Ground(InferredType::Unknown), + against: int(), + then_arm: int(), + else_arm: str_ty(), + })); + assert_eq!(Evaluator::new().evaluate(&env, &cond), Eval::Divergent); + } + + /// A union scrutinee distributes: `(int | str) extends int ? A : B` + /// rewrites each member independently and unions the results. + #[test] + fn conditional_distributes_over_union_scrutinee() { + let env = AliasEnv::default(); + let cond = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: TypeTerm::Union(vec![int(), str_ty()]), + against: int(), + then_arm: TypeTerm::Ground(InferredType::Bool), + else_arm: TypeTerm::Ground(InferredType::None_), + })); + let result = Evaluator::new().evaluate(&env, &cond).into_inferred(); + assert!(InferredType::Bool.is_assignable_to(&result), "{result:?}"); + assert!(InferredType::None_.is_assignable_to(&result), "{result:?}"); + } + + /// Mapped types are first-class `Type → Type` operators: an operator + /// passed as an argument applies through `Apply` (higher-order). + #[test] + fn operator_argument_applies_higher_order() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "wrap", + AliasDef { + arity: 1, + body: TypeTerm::List(Box::new(TypeTerm::Param(0))), + }, + )); + // type ApplyToInt[F] = F[int] — F is an operator-kinded parameter. + assert!(env.insert( + "apply_to_int", + AliasDef { + arity: 1, + body: TypeTerm::Apply(Box::new(TypeTerm::Param(0)), vec![int()]), + }, + )); + let term = TypeTerm::Alias( + "apply_to_int".to_owned(), + vec![TypeTerm::Op("wrap".to_owned())], + ); + assert_eq!( + Evaluator::new().evaluate(&env, &term), + Eval::Value(InferredType::List(Box::new(InferredType::Int))) + ); + } + + /// Kind errors are gradual: applying a proper type, or applying an + /// operator at the wrong arity, yields `Divergent` → `Unknown`, + /// never an invented error. + #[test] + fn ill_kinded_applications_are_gradual() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "wrap", + AliasDef { + arity: 1, + body: TypeTerm::List(Box::new(TypeTerm::Param(0))), + }, + )); + let wrong_arity = TypeTerm::Alias("wrap".to_owned(), vec![int(), int()]); + assert_eq!(Evaluator::new().evaluate(&env, &wrong_arity), Eval::Divergent); + + let apply_ground = TypeTerm::Apply(Box::new(int()), vec![int()]); + assert_eq!(Evaluator::new().evaluate(&env, &apply_ground), Eval::Divergent); + + let unapplied_operator = TypeTerm::Op("wrap".to_owned()); + assert_eq!( + Evaluator::new().evaluate(&env, &unapplied_operator), + Eval::Divergent, + "an unapplied Type → Type operator is not a proper type" + ); + } +} diff --git a/crates/basilisk-checker/src/tyeval/lower.rs b/crates/basilisk-checker/src/tyeval/lower.rs new file mode 100644 index 00000000..d5f2136b --- /dev/null +++ b/crates/basilisk-checker/src/tyeval/lower.rs @@ -0,0 +1,364 @@ +//! Implements [TYPEINF-TARGET-TYPELEVEL] — lowering Ruff AST annotation +//! expressions into the type-level term language. +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL +//! +//! This is the bridge from PEP 695 `type` statements to [`TypeTerm`]s the +//! evaluator and acceptance conditions understand. Lowering is total and +//! gradual: any expression shape outside the type sublanguage lowers to +//! `Ground(Unknown)` — shape *validity* is a separate rule's concern +//! (`aliases_type_statement`), never the engine's. + +use std::collections::HashSet; + +use ruff_python_ast::{Expr, ExceptHandler, ModModule, Operator, Stmt, StmtTypeAlias}; +use ruff_text_size::{Ranged as _, TextRange}; + +use crate::types::InferredType; + +use super::term::{AliasDef, TypeTerm}; + +/// One lowered PEP 695 `type` statement. +#[derive(Debug, Clone, PartialEq)] +pub struct LoweredAlias { + /// The alias name. + pub name: String, + /// The source range of the alias name token (for diagnostics). + pub name_range: TextRange, + /// The lowered definition (parameters replaced by [`TypeTerm::Param`]). + pub def: AliasDef, +} + +/// Lower every PEP 695 `type` statement in `module` (at any nesting depth) +/// into [`LoweredAlias`] definitions. Later duplicates shadow earlier ones, +/// matching Python's rebinding semantics. +#[must_use] +pub fn lower_module_aliases(module: &ModModule) -> Vec { + let mut stmts: Vec<&StmtTypeAlias> = Vec::new(); + collect_type_aliases(&module.body, &mut stmts); + let alias_names: HashSet = stmts + .iter() + .filter_map(|stmt| simple_name(&stmt.name)) + .collect(); + stmts + .iter() + .filter_map(|stmt| lower_alias(stmt, &alias_names)) + .collect() +} + +/// Recursively collect `type` statements from every statement body +/// (module, class, function, and compound-statement scope alike — scope +/// *legality* is rule business). +fn collect_type_aliases<'a>(body: &'a [Stmt], out: &mut Vec<&'a StmtTypeAlias>) { + for stmt in body { + match stmt { + Stmt::TypeAlias(alias) => out.push(alias), + Stmt::ClassDef(class) => collect_type_aliases(&class.body, out), + Stmt::FunctionDef(func) => collect_type_aliases(&func.body, out), + Stmt::If(if_stmt) => { + collect_type_aliases(&if_stmt.body, out); + for clause in &if_stmt.elif_else_clauses { + collect_type_aliases(&clause.body, out); + } + } + Stmt::For(for_stmt) => { + collect_type_aliases(&for_stmt.body, out); + collect_type_aliases(&for_stmt.orelse, out); + } + Stmt::While(while_stmt) => { + collect_type_aliases(&while_stmt.body, out); + collect_type_aliases(&while_stmt.orelse, out); + } + Stmt::With(with_stmt) => collect_type_aliases(&with_stmt.body, out), + Stmt::Try(try_stmt) => { + collect_type_aliases(&try_stmt.body, out); + for ExceptHandler::ExceptHandler(handler) in &try_stmt.handlers { + collect_type_aliases(&handler.body, out); + } + collect_type_aliases(&try_stmt.orelse, out); + collect_type_aliases(&try_stmt.finalbody, out); + } + Stmt::Match(match_stmt) => { + for case in &match_stmt.cases { + collect_type_aliases(&case.body, out); + } + } + _ => {} + } + } +} + +/// Lower one `type Name[P..] = rhs` statement. +fn lower_alias(stmt: &StmtTypeAlias, alias_names: &HashSet) -> Option { + let name = simple_name(&stmt.name)?; + let params: Vec = stmt + .type_params + .as_deref() + .map(|type_params| { + type_params + .type_params + .iter() + .map(|param| param.name().to_string()) + .collect() + }) + .unwrap_or_default(); + let ctx = LowerCtx { + params: ¶ms, + aliases: alias_names, + }; + let body = ctx.lower(&stmt.value); + Some(LoweredAlias { + name, + name_range: stmt.name.range(), + def: AliasDef { + arity: params.len(), + body, + }, + }) +} + +/// Lowering context: the enclosing alias's parameters and the module's +/// alias name set (module-local names lower to [`TypeTerm::Alias`] +/// references; everything else grounds out). +#[derive(Debug)] +pub struct LowerCtx<'a> { + /// Enclosing type-parameter names, in declaration order. + pub params: &'a [String], + /// Names of `type` aliases defined in this module. + pub aliases: &'a HashSet, +} + +impl LowerCtx<'_> { + /// Lower one annotation expression to a [`TypeTerm`]. + #[must_use] + pub fn lower(&self, expr: &Expr) -> TypeTerm { + match expr { + Expr::Name(name) => self.lower_name(name.id.as_str()), + Expr::Subscript(sub) => self.lower_subscript(&sub.value, &sub.slice), + Expr::BinOp(bin) if bin.op == Operator::BitOr => { + let mut arms = Vec::new(); + self.lower_union_arm(&bin.left, &mut arms); + self.lower_union_arm(&bin.right, &mut arms); + TypeTerm::Union(arms) + } + // String annotation: a forward reference — parse and lower the + // inner expression ([TYPEINF-ANNOTATION-RESOLUTION]). + Expr::StringLiteral(literal) => self.lower_forward_ref(literal.value.to_str()), + Expr::NoneLiteral(_) => TypeTerm::Ground(InferredType::None_), + Expr::Attribute(_) => ground_from_text(&dotted_text(expr).unwrap_or_default()), + Expr::Starred(starred) => self.lower(&starred.value), + // Outside the type sublanguage (literals, calls, lambdas, ..): + // gradual ground. Shape validity is `aliases_type_statement`'s + // concern, not the engine's. + _ => TypeTerm::Ground(InferredType::Unknown), + } + } + + /// A bare name: parameter → `Param`, module alias → `Alias` reference, + /// anything else → ground type via the annotation parser. + fn lower_name(&self, id: &str) -> TypeTerm { + if let Some(index) = self.params.iter().position(|param| param == id) { + return TypeTerm::Param(index); + } + if self.aliases.contains(id) { + return TypeTerm::Alias(id.to_owned(), Vec::new()); + } + ground_from_text(id) + } + + /// A subscript `base[args]`: builtin containers get their dedicated + /// constructors, module aliases become applications, and any other + /// base is a [`TypeTerm::Named`] constructor head. + fn lower_subscript(&self, base: &Expr, slice: &Expr) -> TypeTerm { + let args = self.lower_subscript_args(slice); + let Some(base_name) = dotted_text(base) else { + return TypeTerm::Ground(InferredType::Unknown); + }; + match (base_name.as_str(), args.len()) { + ("list" | "List", 1) => match args.into_iter().next() { + Some(element) => TypeTerm::List(Box::new(element)), + None => TypeTerm::Ground(InferredType::Unknown), + }, + ("set" | "frozenset" | "Set" | "FrozenSet", 1) => match args.into_iter().next() { + Some(element) => TypeTerm::Set(Box::new(element)), + None => TypeTerm::Ground(InferredType::Unknown), + }, + ("dict" | "Dict", 2) => { + let mut iter = args.into_iter(); + match (iter.next(), iter.next()) { + (Some(key), Some(value)) => TypeTerm::Dict(Box::new(key), Box::new(value)), + _ => TypeTerm::Ground(InferredType::Unknown), + } + } + ("tuple" | "Tuple", _) => TypeTerm::Tuple(args), + (name, _) if self.aliases.contains(name) => TypeTerm::Alias(name.to_owned(), args), + (name, _) => TypeTerm::Named(name.to_owned(), args), + } + } + + /// Subscript arguments: a tuple slice contributes each element; + /// `...` (as in `tuple[X, ...]` / `Callable[..., R]`) contributes + /// nothing structural and is dropped. + fn lower_subscript_args(&self, slice: &Expr) -> Vec { + let elements: Vec<&Expr> = match slice { + Expr::Tuple(tuple) => tuple.elts.iter().collect(), + other => vec![other], + }; + elements + .into_iter() + .filter(|element| !matches!(element, Expr::EllipsisLiteral(_))) + .map(|element| self.lower(element)) + .collect() + } + + /// Flatten nested `X | Y | Z` into one union arm list. + fn lower_union_arm(&self, expr: &Expr, arms: &mut Vec) { + match expr { + Expr::BinOp(bin) if bin.op == Operator::BitOr => { + self.lower_union_arm(&bin.left, arms); + self.lower_union_arm(&bin.right, arms); + } + other => arms.push(self.lower(other)), + } + } + + /// Parse a string forward reference and lower its expression; an + /// unparseable string grounds out gradually. + fn lower_forward_ref(&self, text: &str) -> TypeTerm { + match ruff_python_parser::parse_expression(text.trim()) { + Ok(parsed) => self.lower(parsed.expr()), + Err(_) => TypeTerm::Ground(InferredType::Unknown), + } + } +} + +/// Ground a leaf via the annotation parser (`int` → `Int`, unknown names → +/// `Named`), keeping one source of truth for leaf spelling. +fn ground_from_text(text: &str) -> TypeTerm { + TypeTerm::Ground(InferredType::from_annotation(text)) +} + +/// The dotted text of a `Name` / `Attribute` chain (`typing.Sequence`), +/// or `None` for any other shape. +fn dotted_text(expr: &Expr) -> Option { + match expr { + Expr::Name(name) => Some(name.id.to_string()), + Expr::Attribute(attr) => Some(format!("{}.{}", dotted_text(&attr.value)?, attr.attr)), + _ => None, + } +} + +/// The simple name of a `Name` expression. +fn simple_name(expr: &Expr) -> Option { + match expr { + Expr::Name(name) => Some(name.id.to_string()), + _ => None, + } +} + +#[cfg(test)] +mod tests { + use super::super::accept::{classify, Acceptance}; + use super::*; + + fn lower_all(source: &str) -> Vec { + ruff_python_parser::parse_module(source) + .map(|parsed| lower_module_aliases(parsed.syntax())) + .unwrap_or_default() + } + + fn classify_source_alias(source: &str, name: &str) -> Option { + let aliases = lower_all(source); + aliases + .iter() + .find(|alias| alias.name == name) + .map(|alias| classify(name, &alias.def)) + } + + /// The #371 boundary cases lower and classify as accepted: guarded + /// recursion through every constructor, in both spellings. + #[test] + fn issue_371_recursive_aliases_lower_as_accepted() { + for (source, name) in [ + ("type J = list[J]\n", "J"), + ("type J = int | list[J]\n", "J"), + ("type J = dict[str, J]\n", "J"), + ( + "type JsonValue = None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]\n", + "JsonValue", + ), + ("type R = str | int | tuple[\"R\", ...]\n", "R"), + ("type T[X] = X | list[T[X]]\n", "T"), + ] { + assert_eq!( + classify_source_alias(source, name), + Some(Acceptance::Accepted), + "{source}" + ); + } + } + + /// The conformance-mandated rejections still classify as unguarded. + #[test] + fn conformance_circular_aliases_lower_as_unguarded() { + for (source, name) in [ + ("type R3 = R3\n", "R3"), + ("type R4[T] = T | R4[str]\n", "R4"), + ("type X = int | X\n", "X"), + ] { + assert_eq!( + classify_source_alias(source, name), + Some(Acceptance::Unguarded), + "{source}" + ); + } + } + + /// Growing recursion lowers as non-regular (the Paterson/Coverage + /// analogue rejects it; the escape hatch can still admit it). + #[test] + fn growing_recursion_lowers_as_non_regular() { + assert_eq!( + classify_source_alias("type R[T] = set[R[list[T]]]\n", "R"), + Some(Acceptance::NonRegular) + ); + } + + /// Parameters lower positionally; string forward references lower + /// through a real parse (`"B"` reaches the parameter, not ground). + #[test] + fn parameters_and_forward_refs_lower_structurally() { + let aliases = lower_all("type Pair[A, B] = dict[A, \"B\"]\n"); + let bodies: Vec<(usize, &TypeTerm)> = aliases + .iter() + .map(|alias| (alias.def.arity, &alias.def.body)) + .collect(); + assert_eq!( + bodies, + [( + 2, + &TypeTerm::Dict(Box::new(TypeTerm::Param(0)), Box::new(TypeTerm::Param(1))) + )] + ); + } + + /// Class-scope aliases are collected; non-type RHS grounds gradually. + #[test] + fn class_scope_and_non_type_rhs_lower_totally() { + let aliases = + lower_all("class C:\n type Inner = list[Inner]\ntype Weird = (lambda: int)()\n"); + let summary: Vec<(&str, &TypeTerm)> = aliases + .iter() + .map(|alias| (alias.name.as_str(), &alias.def.body)) + .collect(); + assert_eq!( + summary, + [ + ( + "Inner", + &TypeTerm::List(Box::new(TypeTerm::Alias("Inner".to_owned(), Vec::new()))) + ), + ("Weird", &TypeTerm::Ground(InferredType::Unknown)), + ] + ); + } +} diff --git a/crates/basilisk-checker/src/tyeval/mod.rs b/crates/basilisk-checker/src/tyeval/mod.rs new file mode 100644 index 00000000..0ab19ace --- /dev/null +++ b/crates/basilisk-checker/src/tyeval/mod.rs @@ -0,0 +1,44 @@ +//! Implements [TYPEINF-TARGET] and [TYPEINF-TARGET-TYPELEVEL] — Stage 3 +//! type-level evaluation. See +//! docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-CHECKLIST +//! ("Stage 3 — type-level evaluation groundwork") and +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL. +//! +//! Python's type-hint sublanguage is Turing-complete (Roth, +//! ), so recursive/parameterised type +//! aliases must be *evaluated*, not expanded eagerly. This module is the +//! normalization-by-evaluation engine: +//! +//! - [`term`] — the term language: ground types, constructors, alias +//! applications, **kind `Type → Type` operator values** ([`Kind`], +//! [`TypeTerm::Op`]/[`TypeTerm::Apply`] — the mapped-type +//! representation), and **conditional types** as assignability-guarded +//! rewrites ([`CondTerm`]); plus the [`AliasEnv`] with its +//! acceptance-checked front door and the opt-in +//! [`AliasEnv::insert_undecidable`] escape hatch; +//! - [`accept`] — the GHC-style (Paterson/Coverage-analogue) acceptance +//! conditions: guardedness (contractivity) and regularity +//! (non-growing self-applications), producing an [`Acceptance`] verdict +//! consumed by both the engine and the `generics_syntax_scoping` rule; +//! - [`eval`] — lazy (call-by-need) unfolding to **weak head normal +//! form** with **fuel/depth bounds**, **memoization** per application, +//! union distribution for conditionals, and the **`Divergent` +//! fallback** projecting to the gradual `Unknown` — truncation NEVER +//! invents an error ([TYPEINF-TARGET-GRADUAL]); +//! - [`lower`] — total, gradual lowering from Ruff AST `type`-statement +//! expressions (string forward references included) into terms; +//! - [`queries`] — the memoized Salsa layer: [`type_alias_env`] (lowered, +//! acceptance-checked, backdating) and [`alias_whnf`] per +//! `(file, alias)`. + +pub mod accept; +pub mod eval; +pub mod lower; +pub mod queries; +pub mod term; + +pub use accept::{classify, Acceptance}; +pub use eval::{Eval, Evaluator}; +pub use lower::{lower_module_aliases, LowerCtx, LoweredAlias}; +pub use queries::{alias_whnf, type_alias_env}; +pub use term::{AliasDef, AliasEnv, CondTerm, Kind, TypeTerm}; diff --git a/crates/basilisk-checker/src/tyeval/queries.rs b/crates/basilisk-checker/src/tyeval/queries.rs new file mode 100644 index 00000000..f261f566 --- /dev/null +++ b/crates/basilisk-checker/src/tyeval/queries.rs @@ -0,0 +1,54 @@ +//! Implements [TYPEINF-TARGET-TYPELEVEL] — the memoized Salsa queries +//! returning whnf types. +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL +//! +//! Two tracked queries put the normalization-by-evaluation engine behind +//! Salsa's memoization, mirroring the definition-level layering of +//! [`crate::incremental_defs`]: +//! +//! - [`type_alias_env`] parses one file and lowers its PEP 695 `type` +//! statements into an [`AliasEnv`] behind the acceptance conditions +//! (rejected definitions are left out, so evaluating them projects to +//! the gradual `Unknown` — never an invented error). The env derives +//! `PartialEq`, so an edit that leaves the alias set unchanged +//! **backdates** and downstream memos survive. +//! - [`alias_whnf`] normalizes one alias to weak head normal form. Its +//! memo is per `(file, alias)`: re-normalization happens only when the +//! alias environment actually changed. + +use basilisk_db::{Db, SourceFile}; + +use crate::types::InferredType; + +use super::eval::Evaluator; +use super::lower::lower_module_aliases; +use super::term::{AliasEnv, TypeTerm}; + +/// Tracked query: one file's PEP 695 alias environment, lowered and +/// acceptance-checked. Unparseable files produce an empty environment. +#[salsa::tracked(returns(ref))] +pub fn type_alias_env(db: &dyn Db, file: SourceFile) -> AliasEnv { + let source = file.text(db); + let mut env = AliasEnv::default(); + let Ok(parsed) = ruff_python_parser::parse_module(source) else { + return env; + }; + for lowered in lower_module_aliases(parsed.syntax()) { + // The acceptance-checked front door: unguarded / non-regular + // definitions stay out and evaluate gradually to `Unknown`. + let _ = env.insert(&lowered.name, lowered.def); + } + env +} + +/// Tracked query: the weak-head-normal-form type of `alias` in `file`, +/// memoized by Salsa per `(file, alias)` on top of the evaluator's own +/// per-application memo. Unknown aliases and truncated evaluations project +/// to the gradual `Unknown` ([TYPEINF-TARGET-GRADUAL]). +#[salsa::tracked(returns(clone))] +pub fn alias_whnf(db: &dyn Db, file: SourceFile, alias: String) -> InferredType { + let env = type_alias_env(db, file); + Evaluator::new() + .evaluate(env, &TypeTerm::Alias(alias, Vec::new())) + .into_inferred() +} diff --git a/crates/basilisk-checker/src/tyeval/term.rs b/crates/basilisk-checker/src/tyeval/term.rs new file mode 100644 index 00000000..ce0fef3c --- /dev/null +++ b/crates/basilisk-checker/src/tyeval/term.rs @@ -0,0 +1,236 @@ +//! Implements [TYPEINF-TARGET-TYPELEVEL] — the type-level term language. +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL +//! +//! [`TypeTerm`] is the object language of the normalization-by-evaluation +//! engine: ground types, constructors, alias applications, **kind +//! `Type → Type` operator values** (mapped types), higher-order application, +//! and **conditional types** as guarded rewrites on assignability. +//! [`AliasEnv`] is the definition environment with the acceptance-checked +//! [`AliasEnv::insert`] front door and the opt-in +//! [`AliasEnv::insert_undecidable`] escape hatch (GHC's +//! `UndecidableInstances` analogue — fuel/depth bounds remain the safety +//! net). + +use std::collections::{HashMap, HashSet}; +use std::fmt; + +use crate::types::InferredType; + +use super::accept::{classify, Acceptance}; + +/// The kind of a type-level value ([TYPEINF-TARGET-TYPELEVEL]). +/// +/// Ground types and fully-applied constructors have kind [`Kind::Type`]; an +/// alias with `n ≥ 1` parameters used *unapplied* is an operator of kind +/// `Type → … → Type` ([`Kind::Operator`]) — the mapped-type representation. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Kind { + /// A proper type (`*`): inhabitable, assignable, a whnf value. + Type, + /// An `arity`-ary type operator (`Type → … → Type`, `arity ≥ 1`). + Operator { + /// Number of type arguments the operator expects. + arity: usize, + }, +} + +impl fmt::Display for Kind { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Kind::Type => write!(f, "Type"), + Kind::Operator { arity } => { + for _ in 0..*arity { + write!(f, "Type → ")?; + } + write!(f, "Type") + } + } + } +} + +/// A conditional type: `then_arm if scrutinee <: against else else_arm` — +/// PEP 827's `IsAssignable`-guarded rewrite, evaluated **lazily** +/// (call-by-need): only the taken arm is ever normalized, so a divergent +/// untaken arm cannot make the whole conditional diverge. +#[derive(Debug, Clone, PartialEq)] +pub struct CondTerm { + /// The type being tested (forced to whnf to decide the rewrite). + pub scrutinee: TypeTerm, + /// The pattern the scrutinee is tested against (forced to whnf). + pub against: TypeTerm, + /// Arm taken when `scrutinee <: against` (lazy). + pub then_arm: TypeTerm, + /// Arm taken otherwise (lazy). + pub else_arm: TypeTerm, +} + +/// A type-level term. +#[derive(Debug, Clone, PartialEq)] +pub enum TypeTerm { + /// A ground type — already a value. + Ground(InferredType), + /// A reference to an alias, possibly applied: `Pair[int]`, `Json`. + Alias(String, Vec), + /// A reference to the enclosing alias's parameter by index. + Param(usize), + /// An alias *used unapplied* as a first-class operator value of kind + /// `Type → … → Type` — the mapped-type representation. `Op("Pair")` + /// can be passed as an argument and applied later via [`TypeTerm::Apply`]. + Op(String), + /// Higher-order application: apply an operator-valued head (an + /// [`TypeTerm::Op`], or a [`TypeTerm::Param`] bound to one) to arguments. + Apply(Box, Vec), + /// A conditional type — a guarded rewrite on assignability + /// ([`CondTerm`]), evaluated call-by-need. + Cond(Box), + /// `list[T]` at the type level (constructor — a whnf head). + List(Box), + /// `set[T]` / `frozenset[T]` at the type level. + Set(Box), + /// `dict[K, V]` at the type level. + Dict(Box, Box), + /// `T | U` at the type level. + Union(Vec), + /// `tuple[T, ..]` at the type level. + Tuple(Vec), + /// Any other named generic constructor: `Sequence[T]`, `Callable[..]`, + /// `Mapping[K, V]` — a whnf head whose arguments stay lazy. + Named(String, Vec), +} + +/// One alias definition: `type Name[P0, P1, ..] = body`. +#[derive(Debug, Clone, PartialEq)] +pub struct AliasDef { + /// Number of type parameters. + pub arity: usize, + /// The right-hand side, with [`TypeTerm::Param`] for parameters. + pub body: TypeTerm, +} + +impl AliasDef { + /// The kind of this definition: `Type` when nullary, else the + /// `arity`-ary operator kind — mapped types ARE `Type → Type` operators. + #[must_use] + pub fn kind(&self) -> Kind { + if self.arity == 0 { + Kind::Type + } else { + Kind::Operator { arity: self.arity } + } + } +} + +/// The alias environment (one module's `type` statements). +/// +/// Mutual recursion note: acceptance is a *per-definition* condition, so a +/// bare mutual cycle (`type A = B` / `type B = A`) inserts fine and is +/// handled **gradually** at evaluation time — fuel/depth exhaust and the +/// result projects to `Unknown`, never an invented error. Diagnosing such +/// cycles is the checker rule's job (`generics_syntax_scoping`), not the +/// engine's. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct AliasEnv { + aliases: HashMap, + /// Names admitted through the [`AliasEnv::insert_undecidable`] escape + /// hatch — recorded so tooling can surface that they rely on + /// fuel-bounded evaluation alone. + undecidable: HashSet, +} + +impl AliasEnv { + /// Register an alias behind the acceptance conditions + /// ([`classify`]): rejects (returns `false`, leaving the environment + /// unchanged) definitions whose recursion is unguarded (`type X = X`, + /// union arms included) or non-regular (a self-application whose + /// arguments grow — the Paterson/Coverage analogue). + pub fn insert(&mut self, name: &str, def: AliasDef) -> bool { + if classify(name, &def) != Acceptance::Accepted { + return false; + } + let _ = self.aliases.insert(name.to_owned(), def); + true + } + + /// The opt-in "undecidable" escape hatch: register `def` **without** + /// the static acceptance conditions, GHC-`UndecidableInstances`-style. + /// Termination then rests entirely on the evaluator's fuel/depth + /// bounds, whose exhaustion projects to the gradual `Unknown` + /// ([TYPEINF-TARGET-GRADUAL]) — never an invented error. + pub fn insert_undecidable(&mut self, name: &str, def: AliasDef) { + let _ = self.undecidable.insert(name.to_owned()); + let _ = self.aliases.insert(name.to_owned(), def); + } + + /// Look up an alias. + #[must_use] + pub fn get(&self, name: &str) -> Option<&AliasDef> { + self.aliases.get(name) + } + + /// The kind of a registered alias, if any. + #[must_use] + pub fn kind_of(&self, name: &str) -> Option { + self.aliases.get(name).map(AliasDef::kind) + } + + /// Was `name` admitted through the undecidable escape hatch? + #[must_use] + pub fn is_undecidable(&self, name: &str) -> bool { + self.undecidable.contains(name) + } + + /// Iterate over registered alias names. + pub fn names(&self) -> impl Iterator { + self.aliases.keys().map(String::as_str) + } + + /// `true` when no aliases are registered. + #[must_use] + pub fn is_empty(&self) -> bool { + self.aliases.is_empty() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Kinds: nullary aliases are `Type`; parameterised aliases are + /// operators — mapped types represented at kind `Type → Type`. + #[test] + fn alias_kinds_reflect_arity() { + let nullary = AliasDef { + arity: 0, + body: TypeTerm::Ground(InferredType::Int), + }; + let unary = AliasDef { + arity: 1, + body: TypeTerm::List(Box::new(TypeTerm::Param(0))), + }; + assert_eq!(nullary.kind(), Kind::Type); + assert_eq!(unary.kind(), Kind::Operator { arity: 1 }); + assert_eq!(nullary.kind().to_string(), "Type"); + assert_eq!(unary.kind().to_string(), "Type → Type"); + assert_eq!( + (Kind::Operator { arity: 2 }).to_string(), + "Type → Type → Type" + ); + } + + /// The escape hatch admits what `insert` rejects, and records it. + #[test] + fn undecidable_escape_hatch_bypasses_acceptance() { + let unguarded = AliasDef { + arity: 0, + body: TypeTerm::Alias("X".to_owned(), Vec::new()), + }; + let mut env = AliasEnv::default(); + assert!(!env.insert("X", unguarded.clone())); + assert!(env.get("X").is_none()); + + env.insert_undecidable("X", unguarded); + assert!(env.get("X").is_some()); + assert!(env.is_undecidable("X")); + assert!(!env.is_undecidable("Y")); + } +} diff --git a/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs b/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs index 6b647a05..4525af4e 100644 --- a/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs +++ b/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs @@ -142,3 +142,49 @@ fn self_recursion_through_list_ok() -> Result<(), Box> { ); Ok(()) } + +/// Regression for [#371](https://github.com/Nimblesite/Basilisk/issues/371): +/// a NON-generic PEP 695 alias whose self-reference sits under a type +/// constructor is ordinary, terminating recursion — PEP 695 mandates it works. +/// Every form below was rejected as "Circular type alias definition"; the +/// generic spellings of the same shapes were already accepted, so the rule was +/// inverted precisely for the parameterless case. +/// Acceptance is decided by [TYPEINF-TARGET-TYPELEVEL]'s guardedness condition +/// (`tyeval::accept`), not by "does the RHS mention my own name". +#[test] +fn recursive_pep695_alias_under_a_constructor_is_accepted( +) -> Result<(), Box> { + for source in [ + "type J = list[J]\n", + "type J = int | list[J]\n", + "type J = dict[str, J]\n", + "type JsonValue = None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]\n", + "type JsonValue = dict[str, JsonValue] | list[JsonValue] | str | int | float | bool | None\n", + "type RecursiveTuple = str | int | tuple[\"RecursiveTuple\", ...]\n", + ] { + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"generics_syntax_scoping"), + "guarded recursive alias must not fire generics_syntax_scoping.\n\ + source: {source}\n got: {:?}", + messages_for(&diags, "generics_syntax_scoping") + ); + } + Ok(()) +} + +/// Companion to the above: unguarded self-reference — the self-reference is +/// NOT under a constructor, so unfolding never reaches a head constructor — +/// must still be rejected. This is the half of the old check that was right. +#[test] +fn unguarded_self_reference_is_still_rejected() -> Result<(), Box> { + for source in ["type X = X\n", "type X = int | X\n"] { + let diags = run(source)?; + assert!( + codes(&diags).contains(&"generics_syntax_scoping"), + "unguarded self-referential alias must still fire.\nsource: {source}\n got: {:?}", + codes(&diags) + ); + } + Ok(()) +} diff --git a/crates/basilisk-checker/tests/checker/names_undefined_tests.rs b/crates/basilisk-checker/tests/checker/names_undefined_tests.rs index 7f99dd0d..6f7213be 100644 --- a/crates/basilisk-checker/tests/checker/names_undefined_tests.rs +++ b/crates/basilisk-checker/tests/checker/names_undefined_tests.rs @@ -448,3 +448,46 @@ def lookup(items: dict[str, int], key: str) -> int | None: ); Ok(()) } + +#[test] +fn pep695_type_alias_in_return_cast_is_defined() -> Result<(), Box> { + // Issue #372: a PEP 695 `type` statement binds its name at module scope + // (a lazily evaluated `TypeAliasType` object), so referencing the alias + // in a return-position `cast(...)` call is NOT an undefined name. + let source = "\ +from typing import cast + +type Fahrenheit = float + + +def to_f(celsius: float) -> Fahrenheit: + return cast(Fahrenheit, celsius * 9 / 5 + 32) +"; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"names_undefined"), + "a `type` statement alias used in a return cast must not fire E0018, got: {:?}", + messages_for(&diags, "names_undefined") + ); + Ok(()) +} + +#[test] +fn pep695_type_alias_returned_bare_is_defined() -> Result<(), Box> { + // Issue #372 (general form): the alias object itself is a first-class + // runtime value — `return Alias` is a defined-name reference. + let source = "\ +type Point = tuple[float, float] + + +def alias() -> object: + return Point +"; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"names_undefined"), + "returning the alias object itself must not fire E0018, got: {:?}", + messages_for(&diags, "names_undefined") + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/tyeval_salsa_tests.rs b/crates/basilisk-checker/tests/tyeval_salsa_tests.rs new file mode 100644 index 00000000..2f509411 --- /dev/null +++ b/crates/basilisk-checker/tests/tyeval_salsa_tests.rs @@ -0,0 +1,100 @@ +//! External tests for [TYPEINF-TARGET-TYPELEVEL] Stage 3 — the memoized +//! Salsa queries returning whnf types +//! (`crates/basilisk-checker/src/tyeval/queries.rs`). See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL and +//! docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-CHECKLIST. +//! +//! Proves, via [`basilisk_test_utils::EventDb`]'s `WillExecute` log, that +//! normalized results are memoized across revisions: an edit that leaves +//! the alias environment unchanged **backdates** and the whnf memo +//! survives untouched. + +use basilisk_checker::tyeval::{alias_whnf, type_alias_env}; +use basilisk_checker::types::InferredType; +use basilisk_db::SourceFile; +use basilisk_test_utils::EventDb; +use salsa::Setter as _; + +const MODULE: &str = r"type Json = None | bool | int | float | str | list[Json] | dict[str, Json] +type Pair[T] = tuple[T, T] + +def unrelated() -> int: + return 1 +"; + +/// The guarded recursive `Json` alias normalizes to a whnf union with the +/// recursive interiors projected gradually — never a diagnostic-shaped +/// failure ([TYPEINF-TARGET-GRADUAL], the #371 boundary). +#[test] +fn recursive_alias_normalizes_through_the_query() { + let db = EventDb::default(); + let file = SourceFile::new(&db, "m.py".to_owned(), MODULE.to_owned()); + let whnf = alias_whnf(&db, file, "Json".to_owned()); + assert!( + InferredType::Int.is_assignable_to(&whnf), + "int arm must survive normalization: {whnf:?}" + ); + assert!( + InferredType::List(Box::new(InferredType::Unknown)).is_assignable_to(&whnf), + "recursive list arm must be present: {whnf:?}" + ); +} + +/// Unguarded definitions are kept OUT of the environment by the acceptance +/// front door, so normalizing them projects to the gradual `Unknown`. +#[test] +fn unguarded_alias_projects_to_unknown_through_the_query() { + let db = EventDb::default(); + let file = SourceFile::new(&db, "m.py".to_owned(), "type X = X\n".to_owned()); + assert!(type_alias_env(&db, file).get("X").is_none()); + assert_eq!( + alias_whnf(&db, file, "X".to_owned()), + InferredType::Unknown + ); +} + +/// **Memoization of normalized results across revisions**: an edit outside +/// every `type` statement re-runs the (cheap) env lowering, which +/// backdates as unchanged — and the `alias_whnf` memo survives, proven by +/// the `WillExecute` log showing zero re-executions. +#[test] +fn whnf_memo_survives_unrelated_edits() { + let mut db = EventDb::default(); + let file = SourceFile::new(&db, "m.py".to_owned(), MODULE.to_owned()); + let before = alias_whnf(&db, file, "Json".to_owned()); + // Drain setup events. + let _ = db.executions_of("alias_whnf"); + + // Edit ONLY the unrelated function's body: alias definitions unchanged. + let edited = MODULE.replace("return 1", "return 2"); + assert_ne!(edited, MODULE); + let _ = file.set_text(&mut db).to(edited); + let after = alias_whnf(&db, file, "Json".to_owned()); + + assert_eq!(before, after); + assert_eq!( + db.executions_of("alias_whnf"), + 0, + "the normalized result must be memoized across the backdated env" + ); +} + +/// Editing an alias definition DOES re-normalize — memoization must never +/// serve stale results. +#[test] +fn editing_an_alias_recomputes_its_whnf() { + let mut db = EventDb::default(); + let file = SourceFile::new(&db, "m.py".to_owned(), MODULE.to_owned()); + let _ = alias_whnf(&db, file, "Pair".to_owned()); + let _ = db.executions_of("alias_whnf"); + + let edited = MODULE.replace("tuple[T, T]", "list[T]"); + assert_ne!(edited, MODULE); + let _ = file.set_text(&mut db).to(edited); + let _ = alias_whnf(&db, file, "Pair".to_owned()); + assert_eq!( + db.executions_of("alias_whnf"), + 1, + "a changed definition must re-normalize" + ); +} diff --git a/crates/basilisk-resolver/src/scope/pep695_scoping.rs b/crates/basilisk-resolver/src/scope/pep695_scoping.rs index 320a7a30..e680f080 100644 --- a/crates/basilisk-resolver/src/scope/pep695_scoping.rs +++ b/crates/basilisk-resolver/src/scope/pep695_scoping.rs @@ -88,9 +88,6 @@ pub struct Pep695AliasDef { /// (`type A = B`), whereas one through a container (`type A = list[B]`) is /// legitimate recursion; this powers mutual-cycle detection (`generics_syntax_scoping`). pub rhs_bare_refs: Vec, - /// When the RHS contains a self-referential subscript `Name[args]`, the - /// simple argument names of the first such subscript. - pub self_ref_args: Option>, /// `true` when this alias is nested (directly or transitively) in a function body. pub in_function: bool, } diff --git a/crates/basilisk-resolver/src/visitor/pep695_scoping.rs b/crates/basilisk-resolver/src/visitor/pep695_scoping.rs index 70b223f7..0ef72e74 100644 --- a/crates/basilisk-resolver/src/visitor/pep695_scoping.rs +++ b/crates/basilisk-resolver/src/visitor/pep695_scoping.rs @@ -126,7 +126,6 @@ fn collect_alias(alias: &StmtTypeAlias, ctx: &Ctx<'_>, source: &str, out: &mut P out.aliases.push(Pep695AliasDef { name: name.clone(), name_span: text_range_to_span(alias.name.range()), - self_ref_args: find_self_ref_args(&alias.value, &name), params, rhs_refs, rhs_bare_refs, @@ -239,42 +238,6 @@ fn collect_bare_refs(expr: &Expr, out: &mut Vec) { } } -fn find_self_ref_args(expr: &Expr, alias_name: &str) -> Option> { - match expr { - Expr::Subscript(sub) => { - if expr_simple_name(&sub.value).as_deref() == Some(alias_name) { - return Some(subscript_arg_names(&sub.slice)); - } - find_self_ref_args(&sub.value, alias_name) - .or_else(|| find_self_ref_args(&sub.slice, alias_name)) - } - Expr::BinOp(bin) => find_self_ref_args(&bin.left, alias_name) - .or_else(|| find_self_ref_args(&bin.right, alias_name)), - Expr::Tuple(tup) => tup - .elts - .iter() - .find_map(|elt| find_self_ref_args(elt, alias_name)), - Expr::Call(call) => call - .arguments - .args - .iter() - .find_map(|arg| find_self_ref_args(arg, alias_name)), - Expr::Starred(s) => find_self_ref_args(&s.value, alias_name), - _ => None, - } -} - -fn subscript_arg_names(slice: &Expr) -> Vec { - match slice { - Expr::Tuple(tup) => tup - .elts - .iter() - .map(|elt| expr_simple_name(elt).unwrap_or_default()) - .collect(), - other => vec![expr_simple_name(other).unwrap_or_default()], - } -} - /// Recursively collect `Name.attr` accesses from an expression tree. fn collect_attr_accesses(expr: &Expr, out: &mut Pep695Scoping) { if let Expr::Attribute(attr) = expr { diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index f5c4ac34..aba9e3fc 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -771,16 +771,57 @@ the conformance ratchets (100% / 0 false positives) at every step. ### Stage 3 — type-level evaluation groundwork -- [ ] Build the normalization-by-evaluation engine for type-level functions as +- [x] Build the normalization-by-evaluation engine for type-level functions as memoized Salsa queries returning whnf types. -- [ ] Enforce fuel/depth bounds and memoization of normalized results. -- [ ] Add the `Divergent`/`@Todo` fallback preserving the gradual guarantee on + — `crates/basilisk-checker/src/tyeval/` (`term`, `eval`, `lower`, + `queries`): PEP 695 `type` statements lower from the Ruff AST (including + string forward references, re-parsed via `ruff_python_parser`) into + `TypeTerm`s; `Evaluator::eval_at` normalizes to weak head normal form. + `queries::type_alias_env` and `queries::alias_whnf` are + `#[salsa::tracked]` queries; `tests/tyeval_salsa_tests.rs` proves via + the `EventDb` `WillExecute` log that an edit outside every alias + backdates the env and serves the whnf memo with ZERO re-executions, + while editing a definition re-normalizes exactly once. +- [x] Enforce fuel/depth bounds and memoization of normalized results. + — `eval.rs`: `EVAL_FUEL = 256` unfoldings and `EVAL_DEPTH = 64` + nesting, plus a per-`(alias, args)` memo inside the evaluator and the + Salsa memo across revisions. `tyeval_public_api_tests.rs` pins that + mutually recursive `Left`/`Right` burn fuel and truncate instead of + hanging. +- [x] Add the `Divergent`/`@Todo` fallback preserving the gradual guarantee on truncated evaluation. -- [ ] Add GHC-style (Paterson/Coverage-analogue) acceptance conditions with an + — `Eval::Divergent` projects to `InferredType::Unknown` via + `into_inferred` ([TYPEINF-TARGET-GRADUAL]): exhausted fuel/depth, + ill-kinded applications, and `Unknown` conditional scrutinees all + truncate gradually — never an invented diagnostic + (`undecidable_alias_truncates_gradually`, + `ill_kinded_applications_are_gradual`). +- [x] Add GHC-style (Paterson/Coverage-analogue) acceptance conditions with an opt-in "undecidable" escape hatch. -- [ ] Represent mapped types as kind `Type → Type` operators and conditional + — `accept.rs::classify`: `Unguarded` rejects self-references not under + a type constructor (union arms do NOT guard — conformance + `aliases_recursive.py` requires `type R3 = R3` and + `type R4[T] = T | R4[str]` to error while `T | list[R1[T]]` stays + clean); `NonRegular` rejects growing self-application arguments + (each must be a bare `Param` or closed). `AliasEnv::insert` is + acceptance-gated; `insert_undecidable` is the opt-in escape hatch with + fuel as the safety net. Wired into production via + `generics_syntax_scoping::check_type_alias_circular` — this replaced + the textual self-reference scan and fixed issue #371 + (`recursive_pep695_alias_under_a_constructor_is_accepted`, + `unguarded_self_reference_is_still_rejected`). +- [x] Represent mapped types as kind `Type → Type` operators and conditional types as guarded rewrites on assignability, evaluated lazily (call-by-need). + — `term.rs`: `Kind::{Type, Operator}` with `AliasDef::kind()`; + `TypeTerm::Op`/`Apply` give aliases-as-operators first-class standing, + including higher-order application through parameters + (`operator_argument_applies_higher_order`). `TypeTerm::Cond` + (`CondTerm`) rewrites on `InferredType::is_assignable_to`, forces only + the taken arm (`conditional_rewrites_lazily`), distributes over union + scrutinees, and stays gradual on `Unknown` scrutinees. Annotation + surface syntax for conditionals awaits a ratified PEP 827; the engine + is ready behind it. ### Superiority gate diff --git a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md index ed14377d..06b24b45 100644 --- a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md +++ b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md @@ -1157,11 +1157,23 @@ eviction (keep only interfaces) sits behind the query layer — see the threshol ### [TYPEINF-TARGET-TYPELEVEL] Type-level evaluation (PEP 827 readiness) {#TYPEINF-TARGET-TYPELEVEL} -`tyeval.rs` implements isolated Stage 3 groundwork: a bounded, memoized, -call-by-need evaluator for ground/alias/parameter/list/tuple/union terms with a -gradual `Divergent` fallback and guarded-recursion acceptance. It is not wired -into annotation resolution and does not yet implement conditional or mapped -types. The target extension is constrained as follows. +The `tyeval` module (`crates/basilisk-checker/src/tyeval/`) implements the +complete Stage 3 groundwork: a bounded, memoized, call-by-need +normalization-by-evaluation engine over type-level terms — ground, alias +application, parameter, container (`list`/`set`/`dict`/`tuple`), union, named, +**kind `Type → Type` operators** (`term::Kind`, `TypeTerm::Op`/`Apply`, +higher-order application through parameters), and **conditional types** +(`TypeTerm::Cond`: assignability-guarded rewrites that distribute over union +scrutinees and never force the untaken arm) — with a gradual `Divergent` +fallback, fuel/depth bounds, and Paterson/Coverage-analogue acceptance +conditions (`accept::classify`) plus an opt-in `insert_undecidable` escape +hatch. Normalization is exposed as memoized Salsa queries returning whnf types +(`queries::{type_alias_env, alias_whnf}`), with cross-revision memoization via +backdating pinned by `tests/tyeval_salsa_tests.rs`. The acceptance front door +is wired into production through `generics_syntax_scoping`'s circular-alias +check (`rules/generics_syntax_scoping/violations.rs::check_type_alias_circular`, +the issue-#371 fix); full annotation-resolution wiring is Integration-stage +([NARROWPLAN-INTEGRATION]). The engine is constrained as follows. Type-level computation with conditional/mapped types is Turing-complete territory (proven for both TypeScript and Python type hints — see From a05494894acc4e389368330c7bdfaad30df6bbdf Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Sun, 2 Aug 2026 21:09:06 +1000 Subject: [PATCH 03/45] Fixes --- README-pypi.md | 4 +- README.md | 4 +- README.zh.md | 4 +- .../src/rules/aliases_type_statement.rs | 116 +++------- .../src/rules/names_undefined.rs | 17 +- .../checker/aliases_type_statement_tests.rs | 199 +++++++++--------- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 67 +++--- docs/readme/README.src.md | 4 +- docs/readme/README.zh.src.md | 4 +- docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md | 64 +++--- vscode-extension/README.md | 4 +- vscode-extension/README.zh.md | 4 +- 12 files changed, 219 insertions(+), 272 deletions(-) diff --git a/README-pypi.md b/README-pypi.md index 788c72e4..9d6905ac 100644 --- a/README-pypi.md +++ b/README-pypi.md @@ -49,14 +49,14 @@ And it is the **fastest checker we’ve measured** — median cold full- | Type checker | Median cold check | | --- | --- | -| ⚡ **Basilisk** | **10 ms** | +| ⚡ **Basilisk** | **11 ms** | | zuban | 28 ms | | ty | 39 ms | | Pyrefly | 110 ms | | Pyright | 563 ms | | mypy | 583 ms | -Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~4 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) +Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~5 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) ## Everything in one extension diff --git a/README.md b/README.md index 6402c1d3..4e3fd5e5 100644 --- a/README.md +++ b/README.md @@ -49,14 +49,14 @@ And it is the **fastest checker we’ve measured** — median cold full- | Type checker | Median cold check | | --- | --- | -| ⚡ **Basilisk** | **10 ms** | +| ⚡ **Basilisk** | **11 ms** | | zuban | 28 ms | | ty | 39 ms | | Pyrefly | 110 ms | | Pyright | 563 ms | | mypy | 583 ms | -Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~4 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) +Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~5 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) ## Everything in one extension diff --git a/README.zh.md b/README.zh.md index 6e252676..96ac87a6 100644 --- a/README.zh.md +++ b/README.zh.md @@ -50,14 +50,14 @@ Basilisk 是**唯一**在官方 | 类型检查器 | 冷检查中位数 | | --- | --- | -| ⚡ **Basilisk** | **10 ms** | +| ⚡ **Basilisk** | **11 ms** | | zuban | 28 ms | | ty | 39 ms | | Pyrefly | 110 ms | | Pyright | 563 ms | | mypy | 583 ms | -在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 4 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) +在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 5 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) ## 一个扩展，覆盖全部 diff --git a/crates/basilisk-checker/src/rules/aliases_type_statement.rs b/crates/basilisk-checker/src/rules/aliases_type_statement.rs index e54c66c1..c720b109 100644 --- a/crates/basilisk-checker/src/rules/aliases_type_statement.rs +++ b/crates/basilisk-checker/src/rules/aliases_type_statement.rs @@ -1,8 +1,17 @@ //! Implements [`aliases_type_statement`] from [CHKARCH-DIAG-STRUCTURAL]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-STRUCTURAL //! `aliases_type_statement`: Invalid RHS in a PEP 695 `type X = rhs` statement. //! -//! PEP 695 requires the RHS of a `type` statement to be a valid type expression. -//! The same restrictions as `TypeAlias` (`aliases_implicit`) apply. +//! PEP 695 requires the RHS of a `type` statement to be a valid type +//! expression. The RHS is validated **structurally** on the parsed `ruff` +//! expression tree (issue #379 — substring matching both missed invalid +//! forms and misfired on identifiers containing matched text): names, +//! dotted names, `X | Y` unions, `None`, string forward references, and +//! subscriptions of those are type expressions; every other expression +//! form (literals, calls, lambdas, conditionals, comparisons, +//! comprehensions, boolean operators) is not. Subscript *arguments* are +//! never descended into — special forms like `Literal[...]`, +//! `Callable[[...], X]`, and `Annotated[X, ...]` legitimately hold +//! non-type expressions there. //! //! ```python //! type BadAlias1 = [int, str] # E — list literal @@ -13,6 +22,7 @@ use std::collections::HashSet; use basilisk_resolver::{ResolvedModule, RhsKind, Span}; +use ruff_python_ast::{Expr, Operator}; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; use crate::span_util::slice_span; @@ -37,79 +47,29 @@ fn make_diag(name: &str, span: Span, path: &str) -> Diagnostic { ) } -fn span_text(source: &str, span: Span) -> Option<&str> { - slice_span(source, span) -} - -fn is_invalid_rhs(rhs: &str) -> bool { - let rhs = rhs.trim(); - if rhs == "True" || rhs == "False" { - return true; - } - if rhs.chars().next().is_some_and(|c| c.is_ascii_digit()) { - return true; - } - if rhs.starts_with('-') - && rhs[1..] - .trim() - .chars() - .next() - .is_some_and(|c| c.is_ascii_digit()) - { - return true; - } - if rhs.starts_with("f\"") || rhs.starts_with("f'") { - return true; - } - if rhs.starts_with('[') { - return true; - } - if rhs.starts_with('{') { - return true; - } - if rhs.starts_with('(') && paren_has_top_level_comma(rhs) { - return true; - } - if has_top_level_token(rhs, " if ") { - return true; - } - if has_top_level_token(rhs, " or ") || has_top_level_token(rhs, " and ") { - return true; - } - if rhs.contains("lambda") { - return true; - } - if rhs.starts_with("eval(") { - return true; - } - false -} - -fn has_top_level_token(s: &str, token: &str) -> bool { - let mut depth = 0i32; - let bytes = s.as_bytes(); - let tok = token.as_bytes(); - let tok_len = tok.len(); - let mut i = 0; - while i < bytes.len() { - match bytes.get(i).copied() { - Some(b'[' | b'(' | b'{') => depth += 1, - Some(b']' | b')' | b'}') => depth -= 1, - Some(_) if depth == 0 && bytes.get(i..i + tok_len) == Some(tok) => { - return true; - } - _ => {} +/// Whether `expr` has the structural shape of a type expression. +/// +/// A bare name bound to a non-type module variable (e.g. `x = 42` then +/// `type Bad = x`) is rejected; subscript arguments are deliberately not +/// descended into (special forms hold non-type expressions there). +fn is_type_expression(expr: &Expr, non_type_names: &HashSet<&str>) -> bool { + match expr { + Expr::Name(name) => !non_type_names.contains(name.id.as_str()), + Expr::Attribute(_) | Expr::NoneLiteral(_) | Expr::StringLiteral(_) => true, + Expr::Subscript(subscript) => is_type_expression(&subscript.value, non_type_names), + Expr::BinOp(binop) if binop.op == Operator::BitOr => { + is_type_expression(&binop.left, non_type_names) + && is_type_expression(&binop.right, non_type_names) } - i += 1; + _ => false, } - false } -fn paren_has_top_level_comma(s: &str) -> bool { - if s.len() < 2 { - return false; - } - crate::rules::shared::contains_top_level_comma(&s[1..s.len() - 1]) +/// Parse the RHS source text and validate it structurally. Text that does +/// not parse as an expression is left to the parser's own diagnostics. +fn rhs_is_invalid(rhs: &str, non_type_names: &HashSet<&str>) -> bool { + ruff_python_parser::parse_expression(rhs.trim()) + .is_ok_and(|parsed| !is_type_expression(parsed.expr(), non_type_names)) } /// Collect names of module-level variables that are not valid types. @@ -135,15 +95,6 @@ fn collect_non_type_names(module: &ResolvedModule) -> HashSet<&str> { .collect() } -/// Returns `true` when the RHS text is a bare identifier bound to a non-type variable. -fn is_non_type_name(rhs: &str, non_type_names: &HashSet<&str>) -> bool { - let rhs = rhs.trim(); - if rhs.contains('[') || rhs.contains('.') || rhs.contains('(') || rhs.contains(' ') { - return false; - } - non_type_names.contains(rhs) -} - /// Emits `aliases_type_statement` when a `type X = rhs` statement has an invalid type expression. pub(crate) struct TypeStatementInvalidRhs; @@ -159,11 +110,10 @@ impl Rule for TypeStatementInvalidRhs { let non_type_names = collect_non_type_names(module); for stmt in &module.type_statements { - let Some(rhs) = span_text(source, stmt.rhs_span) else { + let Some(rhs) = slice_span(source, stmt.rhs_span) else { continue; }; - let rhs_trimmed = rhs.trim(); - if is_invalid_rhs(rhs_trimmed) || is_non_type_name(rhs_trimmed, &non_type_names) { + if rhs_is_invalid(rhs, &non_type_names) { diagnostics.push(make_diag(&stmt.name, stmt.name_span, path)); } } diff --git a/crates/basilisk-checker/src/rules/names_undefined.rs b/crates/basilisk-checker/src/rules/names_undefined.rs index 26797cbb..107a779e 100644 --- a/crates/basilisk-checker/src/rules/names_undefined.rs +++ b/crates/basilisk-checker/src/rules/names_undefined.rs @@ -5,8 +5,9 @@ //! base of an attribute/subscript chain (`return x.y`), a call argument, or the //! **callee of a call** (`return x()`) — that is not defined in scope. A name is //! considered defined if it is a parameter, a local assignment (`=`, `for`, -//! `with`), a module-level function, class, variable, or import, an enclosing -//! scope's binding, a cross-module imported symbol, or a builtin. +//! `with`), a module-level function, class, variable, import, or PEP 695 +//! `type` alias, an enclosing scope's binding, a cross-module imported symbol, +//! or a builtin. //! //! ```python //! def compute() -> int: @@ -56,10 +57,20 @@ impl Rule for UndefinedVariable { // module-level functions, variables, and imports. let class_names: Vec<&str> = module.classes.iter().map(|c| c.name.as_str()).collect(); + // A PEP 695 `type` statement binds its alias name to a lazily evaluated + // `TypeAliasType` object — a first-class runtime value (issue #372). + let type_alias_names: Vec<&str> = module + .pep695_scoping + .aliases + .iter() + .map(|alias| alias.name.as_str()) + .collect(); + let scope = ModuleScope { import_names: &import_names, module_var_names: &module_var_names, class_names: &class_names, + type_alias_names: &type_alias_names, imported_symbols: &module.imported_symbols, }; @@ -74,6 +85,7 @@ struct ModuleScope<'a> { import_names: &'a [&'a str], module_var_names: &'a [&'a str], class_names: &'a [&'a str], + type_alias_names: &'a [&'a str], imported_symbols: &'a std::collections::HashMap, } @@ -234,6 +246,7 @@ fn check_function( || scope.import_names.contains(&name_str) || scope.module_var_names.contains(&name_str) || scope.class_names.contains(&name_str) + || scope.type_alias_names.contains(&name_str) || scope.imported_symbols.contains_key(name_str) // Any function defined in the module (sibling, nested, or the function // itself for recursion) is a name in scope — `return helper()` and diff --git a/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs b/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs index 23b63283..28d5abab 100644 --- a/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs +++ b/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs @@ -1,146 +1,149 @@ //! Tests for [`aliases_type_statement`] from [CHKARCH-DIAG-STRUCTURAL]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-STRUCTURAL -// Integration tests for aliases_type_statement: PEP 695 type alias invalid. +// Integration tests for aliases_type_statement: PEP 695 type alias invalid RHS. +// +// The invalid forms mirror conformance `aliases_type_statement.py` +// (`BadTypeAlias1`–`BadTypeAlias13`): the rule must fire on every one of +// them and stay silent on every valid type expression. use super::common::*; -#[test] -fn pep695_type_alias_exercise() -> Result<(), Box> { - let source = r" -type Vector = list[float] -type Matrix = list[Vector] -"; - let diags = run(source)?; - let _ = codes(&diags); - Ok(()) +fn fires(source: &str) -> Result> { + Ok(codes(&run(source)?).contains(&"aliases_type_statement")) } #[test] -fn type_alias_with_params() -> Result<(), Box> { - let source = r" +fn valid_aliases_do_not_fire() -> Result<(), Box> { + let source = r#" +type Vector = list[float] +type Matrix = list[Vector] type Pair[T] = tuple[T, T] -"; - let diags = run(source)?; - let _ = codes(&diags); - Ok(()) -} - -#[test] -fn type_alias_bool_literal() -> Result<(), Box> { - let source = r" -type Bad = True -"; - let diags = run(source)?; - let _ = codes(&diags); - Ok(()) -} - -#[test] -fn type_alias_int_literal() -> Result<(), Box> { - let source = r" -type Bad = 42 -"; - let diags = run(source)?; - let _ = codes(&diags); +type MaybeInt = int | None +type Forward = "Vector" +type Dotted = collections.abc.Sequence +"#; + assert!(!fires(source)?, "valid type expressions must not fire"); Ok(()) } +/// Every `BadTypeAlias1`–`BadTypeAlias13` form from the conformance suite. #[test] -fn type_alias_list_literal() -> Result<(), Box> { - let source = r" -type Bad = [int, str] -"; - let diags = run(source)?; - let _ = codes(&diags); +fn conformance_bad_alias_forms_all_fire() -> Result<(), Box> { + let var_prefix = "var1 = 3\n"; + let bad_forms = [ + "type Bad = eval(\"int\")", // BadTypeAlias1: call + "type Bad = [int, str]", // BadTypeAlias2: list literal + "type Bad = ((int, str),)", // BadTypeAlias3: tuple literal + "type Bad = [int for i in range(1)]", // BadTypeAlias4: comprehension + "type Bad = {\"a\": \"b\"}", // BadTypeAlias5: dict literal + "type Bad = (lambda: int)()", // BadTypeAlias6: lambda call + "type Bad = [int][0]", // BadTypeAlias7: subscripted list + "type Bad = int if 1 < 3 else str", // BadTypeAlias8: conditional + "type Bad = var1", // BadTypeAlias9: non-type variable + "type Bad = True", // BadTypeAlias10: bool literal + "type Bad = 1", // BadTypeAlias11: int literal + "type Bad = list or set", // BadTypeAlias12: boolean op + "type Bad = f\"{'int'}\"", // BadTypeAlias13: f-string + ]; + for form in bad_forms { + let source = format!("{var_prefix}{form}\n"); + assert!(fires(&source)?, "must fire on: {form}"); + } Ok(()) } #[test] -fn type_alias_dict_literal() -> Result<(), Box> { - let source = r#" -type Bad = {"a": int} -"#; - let diags = run(source)?; - let _ = codes(&diags); +fn more_invalid_expression_forms_fire() -> Result<(), Box> { + for form in [ + "type Bad = -1", // unary minus + "type Bad = lambda: int", // bare lambda + "type Bad = (int, str)", // parenthesized tuple + ] { + let source = format!("{form}\n"); + assert!(fires(&source)?, "must fire on: {form}"); + } Ok(()) } -#[test] -fn type_alias_fstring() -> Result<(), Box> { - let source = r#" -type Bad = f"hello" -"#; - let diags = run(source)?; - let _ = codes(&diags); - Ok(()) -} +// ---- Issue #379: substring matching produced both misses and FPs ---- +/// A perfectly valid alias to a class whose NAME contains "lambda" must not +/// fire — `rhs.contains("lambda")` was a substring false positive. #[test] -fn type_alias_conditional() -> Result<(), Box> { +fn identifier_containing_lambda_substring_is_not_flagged( +) -> Result<(), Box> { let source = r" -type Bad = int if True else str +class Blambda: + pass + +type Alias = Blambda "; - let diags = run(source)?; - let _ = codes(&diags); + assert!( + !fires(source)?, + "an identifier containing the substring 'lambda' is a valid RHS" + ); Ok(()) } +/// A parenthesized conditional expression is still a conditional — the +/// text-level top-level-token scan missed it inside the parens. #[test] -fn type_alias_boolean_op() -> Result<(), Box> { - let source = r" -type Bad = int or str -"; - let diags = run(source)?; - let _ = codes(&diags); +fn parenthesized_conditional_rhs_fires() -> Result<(), Box> { + assert!( + fires("type Bad = (int if True else str)\n")?, + "a conditional stays invalid when parenthesized" + ); Ok(()) } +/// Any call is an invalid type expression, not just ones spelled `eval(`. #[test] -fn type_alias_lambda() -> Result<(), Box> { +fn call_rhs_fires() -> Result<(), Box> { let source = r" -type Bad = lambda: int +def make() -> type: + return int + +type Bad = make() "; - let diags = run(source)?; - let _ = codes(&diags); + assert!(fires(source)?, "a call RHS is not a type expression"); Ok(()) } +/// A comparison is an invalid type expression. #[test] -fn type_alias_eval() -> Result<(), Box> { - let source = r#" -type Bad = eval("int") -"#; - let diags = run(source)?; - let _ = codes(&diags); +fn comparison_rhs_fires() -> Result<(), Box> { + assert!( + fires("type Bad = int < str\n")?, + "a comparison RHS is not a type expression" + ); Ok(()) } +/// A bytes literal is an invalid type expression (only str forward +/// references are permitted). #[test] -fn type_alias_negative_number() -> Result<(), Box> { - let source = r" -type Bad = -1 -"; - let diags = run(source)?; - let _ = codes(&diags); +fn bytes_literal_rhs_fires() -> Result<(), Box> { + assert!( + fires("type Bad = b\"int\"\n")?, + "a bytes literal RHS is not a type expression" + ); Ok(()) } +/// Special-form subscript ARGUMENTS legitimately contain literals, lists, +/// and ellipses — the validator must never descend into them. #[test] -fn type_alias_tuple_literal() -> Result<(), Box> { - let source = r" -type Bad = (int, str) -"; - let diags = run(source)?; - let _ = codes(&diags); - Ok(()) -} +fn special_form_subscript_args_are_not_flagged() -> Result<(), Box> { + let source = r#" +from typing import Annotated, Callable, Literal -#[test] -fn type_alias_non_type_name() -> Result<(), Box> { - let source = r" -x = 42 -type Bad = x -"; - let diags = run(source)?; - let _ = codes(&diags); +type Lit = Literal[5, "on", True] +type Fn = Callable[[int, str], bool] +type Meta = Annotated[int, {"units": "m"}] +type Row = tuple[int, ...] +"#; + assert!( + !fires(source)?, + "special-form subscript arguments are valid type expressions" + ); Ok(()) } diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index aba9e3fc..d3b87c56 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -773,55 +773,40 @@ the conformance ratchets (100% / 0 false positives) at every step. - [x] Build the normalization-by-evaluation engine for type-level functions as memoized Salsa queries returning whnf types. - — `crates/basilisk-checker/src/tyeval/` (`term`, `eval`, `lower`, - `queries`): PEP 695 `type` statements lower from the Ruff AST (including - string forward references, re-parsed via `ruff_python_parser`) into - `TypeTerm`s; `Evaluator::eval_at` normalizes to weak head normal form. - `queries::type_alias_env` and `queries::alias_whnf` are - `#[salsa::tracked]` queries; `tests/tyeval_salsa_tests.rs` proves via - the `EventDb` `WillExecute` log that an edit outside every alias - backdates the env and serves the whnf memo with ZERO re-executions, - while editing a definition re-normalizes exactly once. + — `crates/basilisk-checker/src/tyeval/`: PEP 695 `type` statements + lower from the Ruff AST (string forward refs re-parsed) into + `TypeTerm`s; `Evaluator::eval_at` normalizes to whnf behind the + `#[salsa::tracked]` queries `type_alias_env` / `alias_whnf`. + `tests/tyeval_salsa_tests.rs` proves via the `EventDb` `WillExecute` + log that an unrelated edit backdates the env and serves the memo (zero + re-executions) while an alias edit re-normalizes exactly once. - [x] Enforce fuel/depth bounds and memoization of normalized results. - — `eval.rs`: `EVAL_FUEL = 256` unfoldings and `EVAL_DEPTH = 64` - nesting, plus a per-`(alias, args)` memo inside the evaluator and the - Salsa memo across revisions. `tyeval_public_api_tests.rs` pins that - mutually recursive `Left`/`Right` burn fuel and truncate instead of - hanging. + — `eval.rs`: `EVAL_FUEL = 256`, `EVAL_DEPTH = 64`, per-`(alias, args)` + memo under the Salsa layer; `tyeval_public_api_tests.rs` pins that + mutually recursive `Left`/`Right` truncate instead of hanging. - [x] Add the `Divergent`/`@Todo` fallback preserving the gradual guarantee on truncated evaluation. - — `Eval::Divergent` projects to `InferredType::Unknown` via - `into_inferred` ([TYPEINF-TARGET-GRADUAL]): exhausted fuel/depth, - ill-kinded applications, and `Unknown` conditional scrutinees all - truncate gradually — never an invented diagnostic - (`undecidable_alias_truncates_gradually`, - `ill_kinded_applications_are_gradual`). + — `Eval::Divergent` projects to `InferredType::Unknown` + ([TYPEINF-TARGET-GRADUAL]): exhausted fuel/depth, ill-kinded + applications, and `Unknown` conditional scrutinees all truncate + gradually — never an invented diagnostic. - [x] Add GHC-style (Paterson/Coverage-analogue) acceptance conditions with an opt-in "undecidable" escape hatch. - — `accept.rs::classify`: `Unguarded` rejects self-references not under - a type constructor (union arms do NOT guard — conformance - `aliases_recursive.py` requires `type R3 = R3` and - `type R4[T] = T | R4[str]` to error while `T | list[R1[T]]` stays - clean); `NonRegular` rejects growing self-application arguments - (each must be a bare `Param` or closed). `AliasEnv::insert` is - acceptance-gated; `insert_undecidable` is the opt-in escape hatch with - fuel as the safety net. Wired into production via - `generics_syntax_scoping::check_type_alias_circular` — this replaced - the textual self-reference scan and fixed issue #371 - (`recursive_pep695_alias_under_a_constructor_is_accepted`, - `unguarded_self_reference_is_still_rejected`). + — `accept::classify`: `Unguarded` (self-reference not under a type + constructor; union arms do NOT guard, matching conformance + `aliases_recursive.py`) and `NonRegular` (growing self-application + args). `AliasEnv::insert` is acceptance-gated; `insert_undecidable` + opts out with fuel as the safety net. Wired into + `generics_syntax_scoping::check_type_alias_circular`, fixing issue + #371 (pins in `tests/checker/generics_syntax_scoping_tests.rs`). - [x] Represent mapped types as kind `Type → Type` operators and conditional types as guarded rewrites on assignability, evaluated lazily (call-by-need). - — `term.rs`: `Kind::{Type, Operator}` with `AliasDef::kind()`; - `TypeTerm::Op`/`Apply` give aliases-as-operators first-class standing, - including higher-order application through parameters - (`operator_argument_applies_higher_order`). `TypeTerm::Cond` - (`CondTerm`) rewrites on `InferredType::is_assignable_to`, forces only - the taken arm (`conditional_rewrites_lazily`), distributes over union - scrutinees, and stays gradual on `Unknown` scrutinees. Annotation - surface syntax for conditionals awaits a ratified PEP 827; the engine - is ready behind it. + — `term.rs`: `Kind::{Type, Operator}`, `TypeTerm::Op`/`Apply` with + higher-order application through parameters; `TypeTerm::Cond` rewrites + on `is_assignable_to`, forces only the taken arm, distributes over + union scrutinees, and stays gradual on `Unknown` scrutinees. Surface + syntax awaits a ratified PEP 827; the engine is ready behind it. ### Superiority gate diff --git a/docs/readme/README.src.md b/docs/readme/README.src.md index 598e8aeb..ee3d1379 100644 --- a/docs/readme/README.src.md +++ b/docs/readme/README.src.md @@ -60,14 +60,14 @@ And it is the **fastest checker we’ve measured** — median cold full- | Type checker | Median cold check | | --- | --- | -| ⚡ **Basilisk** | **10 ms** | +| ⚡ **Basilisk** | **11 ms** | | zuban | 28 ms | | ty | 39 ms | | Pyrefly | 110 ms | | Pyright | 563 ms | | mypy | 583 ms | -Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~4 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) +Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~5 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) ## Everything in one extension diff --git a/docs/readme/README.zh.src.md b/docs/readme/README.zh.src.md index c31fafa4..841156cb 100644 --- a/docs/readme/README.zh.src.md +++ b/docs/readme/README.zh.src.md @@ -57,14 +57,14 @@ Basilisk 是**唯一**在官方 | 类型检查器 | 冷检查中位数 | | --- | --- | -| ⚡ **Basilisk** | **10 ms** | +| ⚡ **Basilisk** | **11 ms** | | zuban | 28 ms | | ty | 39 ms | | Pyrefly | 110 ms | | Pyright | 563 ms | | mypy | 583 ms | -在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 4 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) +在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 5 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) ## 一个扩展，覆盖全部 diff --git a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md index 06b24b45..994a2e79 100644 --- a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md +++ b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md @@ -1157,44 +1157,40 @@ eviction (keep only interfaces) sits behind the query layer — see the threshol ### [TYPEINF-TARGET-TYPELEVEL] Type-level evaluation (PEP 827 readiness) {#TYPEINF-TARGET-TYPELEVEL} -The `tyeval` module (`crates/basilisk-checker/src/tyeval/`) implements the -complete Stage 3 groundwork: a bounded, memoized, call-by-need -normalization-by-evaluation engine over type-level terms — ground, alias -application, parameter, container (`list`/`set`/`dict`/`tuple`), union, named, -**kind `Type → Type` operators** (`term::Kind`, `TypeTerm::Op`/`Apply`, -higher-order application through parameters), and **conditional types** -(`TypeTerm::Cond`: assignability-guarded rewrites that distribute over union -scrutinees and never force the untaken arm) — with a gradual `Divergent` -fallback, fuel/depth bounds, and Paterson/Coverage-analogue acceptance -conditions (`accept::classify`) plus an opt-in `insert_undecidable` escape -hatch. Normalization is exposed as memoized Salsa queries returning whnf types -(`queries::{type_alias_env, alias_whnf}`), with cross-revision memoization via -backdating pinned by `tests/tyeval_salsa_tests.rs`. The acceptance front door -is wired into production through `generics_syntax_scoping`'s circular-alias -check (`rules/generics_syntax_scoping/violations.rs::check_type_alias_circular`, -the issue-#371 fix); full annotation-resolution wiring is Integration-stage -([NARROWPLAN-INTEGRATION]). The engine is constrained as follows. - Type-level computation with conditional/mapped types is Turing-complete territory (proven for both TypeScript and Python type hints — see [TYPEINF-RESEARCH-TYPELEVEL](#TYPEINF-RESEARCH-TYPELEVEL)), so the only safe -engineering path is **bounded evaluation**: a call-by-need -normalization-by-evaluation engine over type-level functions, built as -memoized Salsa queries returning types in weak-head normal form (whnf), with: - -- **fuel/depth bounds** (TypeScript's instantiation-depth model); -- **memoization** of normalized results; -- a **`Divergent`/`@Todo`-style fallback** that preserves the gradual - guarantee when evaluation is truncated; +engineering path is **bounded evaluation**. +`crates/basilisk-checker/src/tyeval/` implements it: a call-by-need +normalization-by-evaluation engine over type-level terms, exposed as memoized +Salsa queries returning weak-head normal forms +(`queries::{type_alias_env, alias_whnf}`; cross-revision memoization via +backdating pinned by `tests/tyeval_salsa_tests.rs`), with: + +- **fuel/depth bounds** (TypeScript's instantiation-depth model) — + `eval::{EVAL_FUEL, EVAL_DEPTH}`; +- **memoization** of normalized results — a per-evaluator application memo + under the Salsa layer; +- a **`Divergent`/`@Todo`-style fallback** preserving the gradual guarantee on + truncation — `Eval::Divergent` projects to `Unknown` + ([TYPEINF-TARGET-GRADUAL](#TYPEINF-TARGET-GRADUAL)), never a diagnostic; - **GHC-style acceptance conditions** (Paterson/Coverage analogues) that - statically reject obviously-nonterminating type-level definitions, with an - opt-in "undecidable" escape hatch. - -Mapped types are **kind `Type → Type` operators**; conditional types are -guarded rewrites keyed on a consistency/assignability check (`IsAssignable` -in PEP 827), evaluated lazily so unused branches never diverge. Because -bounded evaluation cannot be complete, some legitimate type-level programs -will hit the bound — an inherent limitation, not an implementation gap. + statically reject obviously-nonterminating definitions — `accept::classify` + gates `AliasEnv::insert` (self-references must sit under a type + constructor; union arms do not guard; self-application arguments must not + grow) — with the opt-in `insert_undecidable` escape hatch falling back to + fuel. + +Mapped types are **kind `Type → Type` operators** (`term::Kind`, +`TypeTerm::Op`/`Apply`, higher-order through parameters); conditional types +are guarded rewrites keyed on a consistency/assignability check +(`IsAssignable` in PEP 827) that distribute over union scrutinees and never +force the untaken arm (`TypeTerm::Cond`). The acceptance conditions drive +`generics_syntax_scoping`'s circular-alias check (issue #371); wiring +normalization into annotation resolution is Integration-stage +([NARROWPLAN-INTEGRATION]). Because bounded evaluation cannot be complete, +some legitimate type-level programs will hit the bound — an inherent +limitation, not an implementation gap. --- diff --git a/vscode-extension/README.md b/vscode-extension/README.md index f6b59a7f..f20261ed 100644 --- a/vscode-extension/README.md +++ b/vscode-extension/README.md @@ -49,14 +49,14 @@ And it is the **fastest checker we’ve measured** — median cold full- | Type checker | Median cold check | | --- | --- | -| ⚡ **Basilisk** | **10 ms** | +| ⚡ **Basilisk** | **11 ms** | | zuban | 28 ms | | ty | 39 ms | | Pyrefly | 110 ms | | Pyright | 563 ms | | mypy | 583 ms | -Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~4 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) +Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~5 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) ## Everything in one extension diff --git a/vscode-extension/README.zh.md b/vscode-extension/README.zh.md index aaeee953..662f665e 100644 --- a/vscode-extension/README.zh.md +++ b/vscode-extension/README.zh.md @@ -50,14 +50,14 @@ Basilisk 是**唯一**在官方 | 类型检查器 | 冷检查中位数 | | --- | --- | -| ⚡ **Basilisk** | **10 ms** | +| ⚡ **Basilisk** | **11 ms** | | zuban | 28 ms | | ty | 39 ms | | Pyrefly | 110 ms | | Pyright | 563 ms | | mypy | 583 ms | -在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 4 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) +在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 5 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) ## 一个扩展，覆盖全部 From 963e04ff71852bfa88f0bfb43d9c1b108baa5223 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Sun, 2 Aug 2026 21:56:45 +1000 Subject: [PATCH 04/45] fixes --- .../src/rules/names_undefined.rs | 10 +-- crates/basilisk-checker/src/tyeval/eval.rs | 66 ++++++++++--------- crates/basilisk-resolver/src/scope/named.rs | 5 +- 3 files changed, 42 insertions(+), 39 deletions(-) diff --git a/crates/basilisk-checker/src/rules/names_undefined.rs b/crates/basilisk-checker/src/rules/names_undefined.rs index 107a779e..e7281be6 100644 --- a/crates/basilisk-checker/src/rules/names_undefined.rs +++ b/crates/basilisk-checker/src/rules/names_undefined.rs @@ -55,16 +55,12 @@ impl Rule for UndefinedVariable { // Module-level class names are in scope for any function body, just like // module-level functions, variables, and imports. - let class_names: Vec<&str> = module.classes.iter().map(|c| c.name.as_str()).collect(); + let class_names: Vec<&str> = basilisk_resolver::collect_names(&module.classes); // A PEP 695 `type` statement binds its alias name to a lazily evaluated // `TypeAliasType` object — a first-class runtime value (issue #372). - let type_alias_names: Vec<&str> = module - .pep695_scoping - .aliases - .iter() - .map(|alias| alias.name.as_str()) - .collect(); + let type_alias_names: Vec<&str> = + basilisk_resolver::collect_names(&module.pep695_scoping.aliases); let scope = ModuleScope { import_names: &import_names, diff --git a/crates/basilisk-checker/src/tyeval/eval.rs b/crates/basilisk-checker/src/tyeval/eval.rs index fa7184b4..f68627a6 100644 --- a/crates/basilisk-checker/src/tyeval/eval.rs +++ b/crates/basilisk-checker/src/tyeval/eval.rs @@ -162,16 +162,14 @@ impl Evaluator { /// An undecidable scrutinee (gradual `Unknown`) makes the whole /// conditional gradual rather than guessing a branch. fn eval_cond(&mut self, env: &AliasEnv, cond: &CondTerm, args: &[TypeTerm], depth: u32) -> Eval { - let scrutinee = match self.eval_at(env, &cond.scrutinee, args, depth + 1) { - Eval::Value(ty) => ty, - Eval::Divergent => return Eval::Divergent, + let Some(scrutinee) = self.force_value(env, &cond.scrutinee, args, depth) else { + return Eval::Divergent; }; if let InferredType::Union(members) = scrutinee { return self.distribute_cond(env, cond, members, args, depth); } - let against = match self.eval_at(env, &cond.against, args, depth + 1) { - Eval::Value(ty) => ty, - Eval::Divergent => return Eval::Divergent, + let Some(against) = self.force_value(env, &cond.against, args, depth) else { + return Eval::Divergent; }; if matches!(scrutinee, InferredType::Unknown) { // Cannot decide the rewrite gradually — do not guess a branch. @@ -185,6 +183,21 @@ impl Evaluator { self.eval_at(env, arm, args, depth + 1) } + /// Force a subterm one level deeper to a whnf value; `None` signals + /// divergence for the caller to short-circuit. + fn force_value( + &mut self, + env: &AliasEnv, + term: &TypeTerm, + args: &[TypeTerm], + depth: u32, + ) -> Option { + match self.eval_at(env, term, args, depth + 1) { + Eval::Value(ty) => Some(ty), + Eval::Divergent => None, + } + } + /// Distribution of a conditional over a union scrutinee: rewrite each /// member independently and union the results. fn distribute_cond( @@ -305,6 +318,20 @@ mod tests { TypeTerm::Ground(InferredType::Str) } + /// Arrange: an env holding the accepted 1-ary `wrap` operator + /// (`type wrap[T] = list[T]`). + fn env_with_wrap() -> AliasEnv { + let mut env = AliasEnv::default(); + assert!(env.insert( + "wrap", + AliasDef { + arity: 1, + body: TypeTerm::List(Box::new(TypeTerm::Param(0))), + }, + )); + env + } + /// A mapped-type operator (`type Pair[T] = tuple[T, T]`) applies lazily. #[test] fn mapped_alias_applies_arguments() { @@ -393,14 +420,7 @@ mod tests { /// again (the second call is a cache hit even with zero fuel left). #[test] fn applications_are_memoized() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "wrap", - AliasDef { - arity: 1, - body: TypeTerm::List(Box::new(TypeTerm::Param(0))), - }, - )); + let env = env_with_wrap(); let mut evaluator = Evaluator::new(); let term = TypeTerm::Alias("wrap".to_owned(), vec![int()]); let first = evaluator.evaluate(&env, &term); @@ -515,14 +535,7 @@ mod tests { /// passed as an argument applies through `Apply` (higher-order). #[test] fn operator_argument_applies_higher_order() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "wrap", - AliasDef { - arity: 1, - body: TypeTerm::List(Box::new(TypeTerm::Param(0))), - }, - )); + let mut env = env_with_wrap(); // type ApplyToInt[F] = F[int] — F is an operator-kinded parameter. assert!(env.insert( "apply_to_int", @@ -546,14 +559,7 @@ mod tests { /// never an invented error. #[test] fn ill_kinded_applications_are_gradual() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "wrap", - AliasDef { - arity: 1, - body: TypeTerm::List(Box::new(TypeTerm::Param(0))), - }, - )); + let env = env_with_wrap(); let wrong_arity = TypeTerm::Alias("wrap".to_owned(), vec![int(), int()]); assert_eq!(Evaluator::new().evaluate(&env, &wrong_arity), Eval::Divergent); diff --git a/crates/basilisk-resolver/src/scope/named.rs b/crates/basilisk-resolver/src/scope/named.rs index 5d76d0c2..9c5baab8 100644 --- a/crates/basilisk-resolver/src/scope/named.rs +++ b/crates/basilisk-resolver/src/scope/named.rs @@ -10,8 +10,8 @@ use std::collections::{HashMap, HashSet}; use super::{ - AttributeInfo, ClassInfo, FunctionInfo, GenericParamInfo, ParameterInfo, TypeAliasDefInfo, - TypeVarCallInfo, VariableInfo, + AttributeInfo, ClassInfo, FunctionInfo, GenericParamInfo, ParameterInfo, Pep695AliasDef, + TypeAliasDefInfo, TypeVarCallInfo, VariableInfo, }; /// Anything that exposes a `&str` name. @@ -39,6 +39,7 @@ impl_named_for_string_field!( FunctionInfo, GenericParamInfo, ParameterInfo, + Pep695AliasDef, TypeAliasDefInfo, TypeVarCallInfo, VariableInfo, From 88673d2b2bed4ccff5f327960b0cc10c70de2700 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Mon, 3 Aug 2026 06:48:17 +1000 Subject: [PATCH 05/45] Fixes --- .../src/rules/aliases_type_statement.rs | 15 +- .../generics_syntax_scoping/violations.rs | 12 +- .../generics_typevartuple_args/star_args.rs | 5 +- .../src/rules/names_undefined.rs | 9 +- crates/basilisk-checker/src/rules/shared.rs | 5 +- crates/basilisk-checker/src/tyeval/eval.rs | 270 +----------------- .../basilisk-checker/src/tyeval/eval/tests.rs | 270 ++++++++++++++++++ crates/basilisk-checker/src/tyeval/lower.rs | 110 ++++++- .../checker/aliases_type_statement_tests.rs | 32 +++ .../checker/generics_syntax_scoping_tests.rs | 79 +++++ .../tests/checker/names_undefined_tests.rs | 68 +++++ crates/basilisk-parser/src/lib.rs | 21 ++ .../src/scope/module_types.rs | 4 + .../src/scope/pep695_scoping.rs | 17 +- .../basilisk-resolver/src/visitor/assigns.rs | 13 + .../src/visitor/pep695_scoping.rs | 47 ++- .../src/visitor/type_alias.rs | 5 + docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md | 8 +- 18 files changed, 679 insertions(+), 311 deletions(-) create mode 100644 crates/basilisk-checker/src/tyeval/eval/tests.rs diff --git a/crates/basilisk-checker/src/rules/aliases_type_statement.rs b/crates/basilisk-checker/src/rules/aliases_type_statement.rs index c720b109..45549a0e 100644 --- a/crates/basilisk-checker/src/rules/aliases_type_statement.rs +++ b/crates/basilisk-checker/src/rules/aliases_type_statement.rs @@ -51,7 +51,10 @@ fn make_diag(name: &str, span: Span, path: &str) -> Diagnostic { /// /// A bare name bound to a non-type module variable (e.g. `x = 42` then /// `type Bad = x`) is rejected; subscript arguments are deliberately not -/// descended into (special forms hold non-type expressions there). +/// descended into (special forms hold non-type expressions there). The +/// caller must already have removed the statement's own type parameters +/// from `non_type_names` — PEP 695 binds them in the alias's annotation +/// scope, shadowing same-named module bindings. fn is_type_expression(expr: &Expr, non_type_names: &HashSet<&str>) -> bool { match expr { Expr::Name(name) => !non_type_names.contains(name.id.as_str()), @@ -113,7 +116,15 @@ impl Rule for TypeStatementInvalidRhs { let Some(rhs) = slice_span(source, stmt.rhs_span) else { continue; }; - if rhs_is_invalid(rhs, &non_type_names) { + // The statement's own type parameters shadow module bindings + // inside the RHS (PEP 695 annotation scope): `T = 1` followed by + // `type Wrapper[T] = T | None` is valid. + let visible: HashSet<&str> = non_type_names + .iter() + .copied() + .filter(|name| !stmt.param_names.iter().any(|param| param == name)) + .collect(); + if rhs_is_invalid(rhs, &visible) { diagnostics.push(make_diag(&stmt.name, stmt.name_span, path)); } } diff --git a/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs b/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs index b72bb139..c3e5abf6 100644 --- a/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs +++ b/crates/basilisk-checker/src/rules/generics_syntax_scoping/violations.rs @@ -291,6 +291,7 @@ pub(super) fn check_type_alias_circular( ) { use crate::tyeval::{classify, lower_module_aliases, Acceptance}; + let mut reported: HashSet = HashSet::new(); if let Some(parsed) = crate::rules::shared::parse_module(module) { for lowered in lower_module_aliases(&parsed.ast) { let detail = match classify(&lowered.name, &lowered.def) { @@ -298,6 +299,7 @@ pub(super) fn check_type_alias_circular( Acceptance::Unguarded => "references itself", Acceptance::NonRegular => "references itself with different type arguments", }; + let _ = reported.insert(lowered.name.clone()); push_circular( &lowered.name, crate::span_util::text_range_to_span(lowered.name_range), @@ -308,15 +310,17 @@ pub(super) fn check_type_alias_circular( } } - check_mutual_alias_cycles(scoping, path, diagnostics); + check_mutual_alias_cycles(scoping, &reported, path, diagnostics); } /// Detect *mutual* / longer cycles between aliases connected by bare references /// (`type A = B`, `type B = A`). Only top-level bare references count — recursion /// through a container (`type A = list[B]`) terminates and is legitimate, so it -/// is excluded via `rhs_bare_refs`. +/// is excluded via `rhs_bare_refs`. Aliases in `already_reported` were flagged +/// by the acceptance pass and are skipped — one diagnostic per alias. fn check_mutual_alias_cycles( scoping: &Pep695Scoping, + already_reported: &HashSet, path: &str, diagnostics: &mut Vec, ) { @@ -329,7 +333,9 @@ fn check_mutual_alias_cycles( .collect(); for alias in &scoping.aliases { - if reaches_self(&alias.name, alias, &alias_by_name) { + if !already_reported.contains(alias.name.as_str()) + && reaches_self(&alias.name, alias, &alias_by_name) + { push_circular( &alias.name, alias.name_span, diff --git a/crates/basilisk-checker/src/rules/generics_typevartuple_args/star_args.rs b/crates/basilisk-checker/src/rules/generics_typevartuple_args/star_args.rs index de5e2673..eeb20af4 100644 --- a/crates/basilisk-checker/src/rules/generics_typevartuple_args/star_args.rs +++ b/crates/basilisk-checker/src/rules/generics_typevartuple_args/star_args.rs @@ -110,10 +110,7 @@ fn parse_star_shape(expr: &Expr) -> Option { if ann_str(&sub.value) != "tuple" { return None; } - let elts: Vec<&Expr> = match sub.slice.as_ref() { - Expr::Tuple(t) => t.elts.iter().collect(), - single => vec![single], - }; + let elts = basilisk_parser::subscript_elements(sub); if let [elem, Expr::EllipsisLiteral(_)] = elts.as_slice() { return Some(StarShape::Homogeneous(ann_str(elem))); diff --git a/crates/basilisk-checker/src/rules/names_undefined.rs b/crates/basilisk-checker/src/rules/names_undefined.rs index e7281be6..fe0056ff 100644 --- a/crates/basilisk-checker/src/rules/names_undefined.rs +++ b/crates/basilisk-checker/src/rules/names_undefined.rs @@ -59,8 +59,13 @@ impl Rule for UndefinedVariable { // A PEP 695 `type` statement binds its alias name to a lazily evaluated // `TypeAliasType` object — a first-class runtime value (issue #372). - let type_alias_names: Vec<&str> = - basilisk_resolver::collect_names(&module.pep695_scoping.aliases); + // Only MODULE-scope aliases are visible to every function body: + // class-scope names don't nest, and function-scope aliases are local + // (they reach `all_local_assigns`, so same-function use stays clean). + let type_alias_names: Vec<&str> = basilisk_resolver::collect_names_where( + &module.pep695_scoping.aliases, + |alias| !alias.in_function && !alias.in_class, + ); let scope = ModuleScope { import_names: &import_names, diff --git a/crates/basilisk-checker/src/rules/shared.rs b/crates/basilisk-checker/src/rules/shared.rs index 4992096f..fc20a189 100644 --- a/crates/basilisk-checker/src/rules/shared.rs +++ b/crates/basilisk-checker/src/rules/shared.rs @@ -496,10 +496,7 @@ pub(crate) fn class_generic_param_names(cls: &ruff_python_ast::StmtClassDef) -> if base_name != "Protocol" && base_name != "Generic" { continue; } - let args: Vec<&Expr> = match sub.slice.as_ref() { - Expr::Tuple(t) => t.elts.iter().collect(), - other => vec![other], - }; + let args = basilisk_parser::subscript_elements(sub); names.extend(args.iter().filter_map(|a| match a { Expr::Name(n) => Some(n.id.to_string()), _ => None, diff --git a/crates/basilisk-checker/src/tyeval/eval.rs b/crates/basilisk-checker/src/tyeval/eval.rs index f68627a6..e70c3146 100644 --- a/crates/basilisk-checker/src/tyeval/eval.rs +++ b/crates/basilisk-checker/src/tyeval/eval.rs @@ -306,271 +306,5 @@ fn substitute(term: &TypeTerm, args: &[TypeTerm]) -> TypeTerm { } #[cfg(test)] -mod tests { - use super::super::term::AliasDef; - use super::*; - - fn int() -> TypeTerm { - TypeTerm::Ground(InferredType::Int) - } - - fn str_ty() -> TypeTerm { - TypeTerm::Ground(InferredType::Str) - } - - /// Arrange: an env holding the accepted 1-ary `wrap` operator - /// (`type wrap[T] = list[T]`). - fn env_with_wrap() -> AliasEnv { - let mut env = AliasEnv::default(); - assert!(env.insert( - "wrap", - AliasDef { - arity: 1, - body: TypeTerm::List(Box::new(TypeTerm::Param(0))), - }, - )); - env - } - - /// A mapped-type operator (`type Pair[T] = tuple[T, T]`) applies lazily. - #[test] - fn mapped_alias_applies_arguments() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "pair", - AliasDef { - arity: 1, - body: TypeTerm::Tuple(vec![TypeTerm::Param(0), TypeTerm::Param(0)]), - }, - )); - let mut evaluator = Evaluator::new(); - let result = evaluator.evaluate(&env, &TypeTerm::Alias("pair".to_owned(), vec![int()])); - assert_eq!( - result, - Eval::Value(InferredType::Tuple(vec![ - InferredType::Int, - InferredType::Int - ])) - ); - } - - /// A guarded recursive alias (`type Json = int | list[Json]`) evaluates - /// to whnf — the recursive arm normalizes under fuel without expanding - /// forever. - #[test] - fn guarded_recursion_reaches_whnf() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "json", - AliasDef { - arity: 0, - body: TypeTerm::Union(vec![ - int(), - TypeTerm::List(Box::new(TypeTerm::Alias("json".to_owned(), Vec::new()))), - ]), - }, - )); - let mut evaluator = Evaluator::new(); - let result = evaluator - .evaluate(&env, &TypeTerm::Alias("json".to_owned(), Vec::new())) - .into_inferred(); - // The head is a union of int and list[...]; the recursive interior - // bottoms out gradually rather than diverging. - assert!(InferredType::Int.is_assignable_to(&result)); - assert!( - InferredType::List(Box::new(InferredType::Unknown)).is_assignable_to(&result), - "list arm must be present: {result:?}" - ); - } - - /// The guardedness acceptance condition rejects `type X = X` up front. - #[test] - fn unguarded_recursion_is_rejected() { - let mut env = AliasEnv::default(); - assert!(!env.insert( - "x", - AliasDef { - arity: 0, - body: TypeTerm::Alias("x".to_owned(), Vec::new()), - }, - )); - // Union arms do not guard either: `type X = int | X`. - assert!(!env.insert( - "x", - AliasDef { - arity: 0, - body: TypeTerm::Union(vec![int(), TypeTerm::Alias("x".to_owned(), Vec::new())]), - }, - )); - } - - /// Unknown aliases and fuel exhaustion produce `Divergent`, which - /// projects to the gradual `Unknown` — never an error - /// ([TYPEINF-TARGET-GRADUAL]). - #[test] - fn divergence_projects_to_unknown() { - let env = AliasEnv::default(); - let mut evaluator = Evaluator::new(); - let result = evaluator.evaluate(&env, &TypeTerm::Alias("missing".to_owned(), Vec::new())); - assert_eq!(result, Eval::Divergent); - assert_eq!(result.into_inferred(), InferredType::Unknown); - } - - /// Memoization: re-evaluating the same application does not spend fuel - /// again (the second call is a cache hit even with zero fuel left). - #[test] - fn applications_are_memoized() { - let env = env_with_wrap(); - let mut evaluator = Evaluator::new(); - let term = TypeTerm::Alias("wrap".to_owned(), vec![int()]); - let first = evaluator.evaluate(&env, &term); - evaluator.fuel = 0; - let second = evaluator.evaluate(&env, &term); - assert_eq!(first, second, "memo hit must not need fuel"); - } - - /// An escape-hatch alias (`insert_undecidable`) runs under fuel and - /// truncates to the gradual `Unknown` instead of looping — the - /// gradual guarantee on truncated evaluation. - #[test] - fn undecidable_alias_truncates_gradually() { - let mut env = AliasEnv::default(); - env.insert_undecidable( - "x", - AliasDef { - arity: 0, - body: TypeTerm::Alias("x".to_owned(), Vec::new()), - }, - ); - let result = Evaluator::new().evaluate(&env, &TypeTerm::Alias("x".to_owned(), Vec::new())); - assert_eq!(result, Eval::Divergent); - assert_eq!(result.into_inferred(), InferredType::Unknown); - } - - /// Dict/Set constructors normalize their components. - #[test] - fn dict_and_set_constructors_normalize() { - let mut env = AliasEnv::default(); - assert!(env.insert( - "m", - AliasDef { - arity: 0, - body: TypeTerm::Dict(Box::new(str_ty()), Box::new(TypeTerm::Set(Box::new(int())))), - }, - )); - let result = Evaluator::new() - .evaluate(&env, &TypeTerm::Alias("m".to_owned(), Vec::new())) - .into_inferred(); - assert_eq!( - result, - InferredType::Dict( - Box::new(InferredType::Str), - Box::new(InferredType::Set(Box::new(InferredType::Int))) - ) - ); - } - - /// Conditional types rewrite on assignability and are call-by-need: - /// the untaken arm is a divergent (unknown) alias and is never forced. - #[test] - fn conditional_rewrites_lazily() { - let env = AliasEnv::default(); - let divergent_arm = TypeTerm::Alias("missing".to_owned(), Vec::new()); - let taken = TypeTerm::Cond(Box::new(CondTerm { - scrutinee: int(), - against: int(), - then_arm: str_ty(), - else_arm: divergent_arm.clone(), - })); - assert_eq!( - Evaluator::new().evaluate(&env, &taken), - Eval::Value(InferredType::Str), - "then-arm taken; divergent else-arm must never be forced" - ); - - let not_taken = TypeTerm::Cond(Box::new(CondTerm { - scrutinee: str_ty(), - against: int(), - then_arm: divergent_arm, - else_arm: int(), - })); - assert_eq!( - Evaluator::new().evaluate(&env, ¬_taken), - Eval::Value(InferredType::Int), - "else-arm taken; divergent then-arm must never be forced" - ); - } - - /// An `Unknown` scrutinee cannot decide the rewrite: the conditional - /// is gradual (`Divergent` → `Unknown`), never a guessed branch. - #[test] - fn conditional_on_unknown_scrutinee_is_gradual() { - let env = AliasEnv::default(); - let cond = TypeTerm::Cond(Box::new(CondTerm { - scrutinee: TypeTerm::Ground(InferredType::Unknown), - against: int(), - then_arm: int(), - else_arm: str_ty(), - })); - assert_eq!(Evaluator::new().evaluate(&env, &cond), Eval::Divergent); - } - - /// A union scrutinee distributes: `(int | str) extends int ? A : B` - /// rewrites each member independently and unions the results. - #[test] - fn conditional_distributes_over_union_scrutinee() { - let env = AliasEnv::default(); - let cond = TypeTerm::Cond(Box::new(CondTerm { - scrutinee: TypeTerm::Union(vec![int(), str_ty()]), - against: int(), - then_arm: TypeTerm::Ground(InferredType::Bool), - else_arm: TypeTerm::Ground(InferredType::None_), - })); - let result = Evaluator::new().evaluate(&env, &cond).into_inferred(); - assert!(InferredType::Bool.is_assignable_to(&result), "{result:?}"); - assert!(InferredType::None_.is_assignable_to(&result), "{result:?}"); - } - - /// Mapped types are first-class `Type → Type` operators: an operator - /// passed as an argument applies through `Apply` (higher-order). - #[test] - fn operator_argument_applies_higher_order() { - let mut env = env_with_wrap(); - // type ApplyToInt[F] = F[int] — F is an operator-kinded parameter. - assert!(env.insert( - "apply_to_int", - AliasDef { - arity: 1, - body: TypeTerm::Apply(Box::new(TypeTerm::Param(0)), vec![int()]), - }, - )); - let term = TypeTerm::Alias( - "apply_to_int".to_owned(), - vec![TypeTerm::Op("wrap".to_owned())], - ); - assert_eq!( - Evaluator::new().evaluate(&env, &term), - Eval::Value(InferredType::List(Box::new(InferredType::Int))) - ); - } - - /// Kind errors are gradual: applying a proper type, or applying an - /// operator at the wrong arity, yields `Divergent` → `Unknown`, - /// never an invented error. - #[test] - fn ill_kinded_applications_are_gradual() { - let env = env_with_wrap(); - let wrong_arity = TypeTerm::Alias("wrap".to_owned(), vec![int(), int()]); - assert_eq!(Evaluator::new().evaluate(&env, &wrong_arity), Eval::Divergent); - - let apply_ground = TypeTerm::Apply(Box::new(int()), vec![int()]); - assert_eq!(Evaluator::new().evaluate(&env, &apply_ground), Eval::Divergent); - - let unapplied_operator = TypeTerm::Op("wrap".to_owned()); - assert_eq!( - Evaluator::new().evaluate(&env, &unapplied_operator), - Eval::Divergent, - "an unapplied Type → Type operator is not a proper type" - ); - } -} +#[path = "eval/tests.rs"] +mod tests; diff --git a/crates/basilisk-checker/src/tyeval/eval/tests.rs b/crates/basilisk-checker/src/tyeval/eval/tests.rs new file mode 100644 index 00000000..576a53c3 --- /dev/null +++ b/crates/basilisk-checker/src/tyeval/eval/tests.rs @@ -0,0 +1,270 @@ +//! Tests for [`super`] — whnf evaluation, memoization, call-by-need +//! laziness, and the gradual guarantee ([TYPEINF-TARGET-GRADUAL]). +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-TARGET-TYPELEVEL + +use super::super::term::AliasDef; +use super::*; + +fn int() -> TypeTerm { + TypeTerm::Ground(InferredType::Int) +} + +fn str_ty() -> TypeTerm { + TypeTerm::Ground(InferredType::Str) +} + +/// Arrange: an env holding the accepted 1-ary `wrap` operator +/// (`type wrap[T] = list[T]`). +fn env_with_wrap() -> AliasEnv { + let mut env = AliasEnv::default(); + assert!(env.insert( + "wrap", + AliasDef { + arity: 1, + body: TypeTerm::List(Box::new(TypeTerm::Param(0))), + }, + )); + env +} + +/// A mapped-type operator (`type Pair[T] = tuple[T, T]`) applies lazily. +#[test] +fn mapped_alias_applies_arguments() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "pair", + AliasDef { + arity: 1, + body: TypeTerm::Tuple(vec![TypeTerm::Param(0), TypeTerm::Param(0)]), + }, + )); + let mut evaluator = Evaluator::new(); + let result = evaluator.evaluate(&env, &TypeTerm::Alias("pair".to_owned(), vec![int()])); + assert_eq!( + result, + Eval::Value(InferredType::Tuple(vec![ + InferredType::Int, + InferredType::Int + ])) + ); +} + +/// A guarded recursive alias (`type Json = int | list[Json]`) evaluates +/// to whnf — the recursive arm normalizes under fuel without expanding +/// forever. +#[test] +fn guarded_recursion_reaches_whnf() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "json", + AliasDef { + arity: 0, + body: TypeTerm::Union(vec![ + int(), + TypeTerm::List(Box::new(TypeTerm::Alias("json".to_owned(), Vec::new()))), + ]), + }, + )); + let mut evaluator = Evaluator::new(); + let result = evaluator + .evaluate(&env, &TypeTerm::Alias("json".to_owned(), Vec::new())) + .into_inferred(); + // The head is a union of int and list[...]; the recursive interior + // bottoms out gradually rather than diverging. + assert!(InferredType::Int.is_assignable_to(&result)); + assert!( + InferredType::List(Box::new(InferredType::Unknown)).is_assignable_to(&result), + "list arm must be present: {result:?}" + ); +} + +/// The guardedness acceptance condition rejects `type X = X` up front. +#[test] +fn unguarded_recursion_is_rejected() { + let mut env = AliasEnv::default(); + assert!(!env.insert( + "x", + AliasDef { + arity: 0, + body: TypeTerm::Alias("x".to_owned(), Vec::new()), + }, + )); + // Union arms do not guard either: `type X = int | X`. + assert!(!env.insert( + "x", + AliasDef { + arity: 0, + body: TypeTerm::Union(vec![int(), TypeTerm::Alias("x".to_owned(), Vec::new())]), + }, + )); +} + +/// Unknown aliases and fuel exhaustion produce `Divergent`, which +/// projects to the gradual `Unknown` — never an error +/// ([TYPEINF-TARGET-GRADUAL]). +#[test] +fn divergence_projects_to_unknown() { + let env = AliasEnv::default(); + let mut evaluator = Evaluator::new(); + let result = evaluator.evaluate(&env, &TypeTerm::Alias("missing".to_owned(), Vec::new())); + assert_eq!(result, Eval::Divergent); + assert_eq!(result.into_inferred(), InferredType::Unknown); +} + +/// Memoization: re-evaluating the same application does not spend fuel +/// again (the second call is a cache hit even with zero fuel left). +#[test] +fn applications_are_memoized() { + let env = env_with_wrap(); + let mut evaluator = Evaluator::new(); + let term = TypeTerm::Alias("wrap".to_owned(), vec![int()]); + let first = evaluator.evaluate(&env, &term); + evaluator.fuel = 0; + let second = evaluator.evaluate(&env, &term); + assert_eq!(first, second, "memo hit must not need fuel"); +} + +/// An escape-hatch alias (`insert_undecidable`) runs under fuel and +/// truncates to the gradual `Unknown` instead of looping — the +/// gradual guarantee on truncated evaluation. +#[test] +fn undecidable_alias_truncates_gradually() { + let mut env = AliasEnv::default(); + env.insert_undecidable( + "x", + AliasDef { + arity: 0, + body: TypeTerm::Alias("x".to_owned(), Vec::new()), + }, + ); + let result = Evaluator::new().evaluate(&env, &TypeTerm::Alias("x".to_owned(), Vec::new())); + assert_eq!(result, Eval::Divergent); + assert_eq!(result.into_inferred(), InferredType::Unknown); +} + +/// Dict/Set constructors normalize their components. +#[test] +fn dict_and_set_constructors_normalize() { + let mut env = AliasEnv::default(); + assert!(env.insert( + "m", + AliasDef { + arity: 0, + body: TypeTerm::Dict(Box::new(str_ty()), Box::new(TypeTerm::Set(Box::new(int())))), + }, + )); + let result = Evaluator::new() + .evaluate(&env, &TypeTerm::Alias("m".to_owned(), Vec::new())) + .into_inferred(); + assert_eq!( + result, + InferredType::Dict( + Box::new(InferredType::Str), + Box::new(InferredType::Set(Box::new(InferredType::Int))) + ) + ); +} + +/// Conditional types rewrite on assignability and are call-by-need: +/// the untaken arm is a divergent (unknown) alias and is never forced. +#[test] +fn conditional_rewrites_lazily() { + let env = AliasEnv::default(); + let divergent_arm = TypeTerm::Alias("missing".to_owned(), Vec::new()); + let taken = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: int(), + against: int(), + then_arm: str_ty(), + else_arm: divergent_arm.clone(), + })); + assert_eq!( + Evaluator::new().evaluate(&env, &taken), + Eval::Value(InferredType::Str), + "then-arm taken; divergent else-arm must never be forced" + ); + + let not_taken = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: str_ty(), + against: int(), + then_arm: divergent_arm, + else_arm: int(), + })); + assert_eq!( + Evaluator::new().evaluate(&env, ¬_taken), + Eval::Value(InferredType::Int), + "else-arm taken; divergent then-arm must never be forced" + ); +} + +/// An `Unknown` scrutinee cannot decide the rewrite: the conditional +/// is gradual (`Divergent` → `Unknown`), never a guessed branch. +#[test] +fn conditional_on_unknown_scrutinee_is_gradual() { + let env = AliasEnv::default(); + let cond = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: TypeTerm::Ground(InferredType::Unknown), + against: int(), + then_arm: int(), + else_arm: str_ty(), + })); + assert_eq!(Evaluator::new().evaluate(&env, &cond), Eval::Divergent); +} + +/// A union scrutinee distributes: `(int | str) extends int ? A : B` +/// rewrites each member independently and unions the results. +#[test] +fn conditional_distributes_over_union_scrutinee() { + let env = AliasEnv::default(); + let cond = TypeTerm::Cond(Box::new(CondTerm { + scrutinee: TypeTerm::Union(vec![int(), str_ty()]), + against: int(), + then_arm: TypeTerm::Ground(InferredType::Bool), + else_arm: TypeTerm::Ground(InferredType::None_), + })); + let result = Evaluator::new().evaluate(&env, &cond).into_inferred(); + assert!(InferredType::Bool.is_assignable_to(&result), "{result:?}"); + assert!(InferredType::None_.is_assignable_to(&result), "{result:?}"); +} + +/// Mapped types are first-class `Type → Type` operators: an operator +/// passed as an argument applies through `Apply` (higher-order). +#[test] +fn operator_argument_applies_higher_order() { + let mut env = env_with_wrap(); + // type ApplyToInt[F] = F[int] — F is an operator-kinded parameter. + assert!(env.insert( + "apply_to_int", + AliasDef { + arity: 1, + body: TypeTerm::Apply(Box::new(TypeTerm::Param(0)), vec![int()]), + }, + )); + let term = TypeTerm::Alias( + "apply_to_int".to_owned(), + vec![TypeTerm::Op("wrap".to_owned())], + ); + assert_eq!( + Evaluator::new().evaluate(&env, &term), + Eval::Value(InferredType::List(Box::new(InferredType::Int))) + ); +} + +/// Kind errors are gradual: applying a proper type, or applying an +/// operator at the wrong arity, yields `Divergent` → `Unknown`, +/// never an invented error. +#[test] +fn ill_kinded_applications_are_gradual() { + let env = env_with_wrap(); + let wrong_arity = TypeTerm::Alias("wrap".to_owned(), vec![int(), int()]); + assert_eq!(Evaluator::new().evaluate(&env, &wrong_arity), Eval::Divergent); + + let apply_ground = TypeTerm::Apply(Box::new(int()), vec![int()]); + assert_eq!(Evaluator::new().evaluate(&env, &apply_ground), Eval::Divergent); + + let unapplied_operator = TypeTerm::Op("wrap".to_owned()); + assert_eq!( + Evaluator::new().evaluate(&env, &unapplied_operator), + Eval::Divergent, + "an unapplied Type → Type operator is not a proper type" + ); +} diff --git a/crates/basilisk-checker/src/tyeval/lower.rs b/crates/basilisk-checker/src/tyeval/lower.rs index d5f2136b..dbb7f3c6 100644 --- a/crates/basilisk-checker/src/tyeval/lower.rs +++ b/crates/basilisk-checker/src/tyeval/lower.rs @@ -10,7 +10,7 @@ use std::collections::HashSet; -use ruff_python_ast::{Expr, ExceptHandler, ModModule, Operator, Stmt, StmtTypeAlias}; +use ruff_python_ast::{Expr, ExceptHandler, ExprSubscript, ModModule, Operator, Stmt, StmtTypeAlias}; use ruff_text_size::{Ranged as _, TextRange}; use crate::types::InferredType; @@ -29,8 +29,10 @@ pub struct LoweredAlias { } /// Lower every PEP 695 `type` statement in `module` (at any nesting depth) -/// into [`LoweredAlias`] definitions. Later duplicates shadow earlier ones, -/// matching Python's rebinding semantics. +/// into [`LoweredAlias`] definitions, in source order. Duplicate names are +/// all returned; a caller registering them in order gets last-binding-wins +/// (modulo [`super::AliasEnv::insert`]'s acceptance gate, which skips +/// rejected definitions). #[must_use] pub fn lower_module_aliases(module: &ModModule) -> Vec { let mut stmts: Vec<&StmtTypeAlias> = Vec::new(); @@ -133,7 +135,7 @@ impl LowerCtx<'_> { pub fn lower(&self, expr: &Expr) -> TypeTerm { match expr { Expr::Name(name) => self.lower_name(name.id.as_str()), - Expr::Subscript(sub) => self.lower_subscript(&sub.value, &sub.slice), + Expr::Subscript(sub) => self.lower_subscript(sub), Expr::BinOp(bin) if bin.op == Operator::BitOr => { let mut arms = Vec::new(); self.lower_union_arm(&bin.left, &mut arms); @@ -168,12 +170,30 @@ impl LowerCtx<'_> { /// A subscript `base[args]`: builtin containers get their dedicated /// constructors, module aliases become applications, and any other /// base is a [`TypeTerm::Named`] constructor head. - fn lower_subscript(&self, base: &Expr, slice: &Expr) -> TypeTerm { - let args = self.lower_subscript_args(slice); - let Some(base_name) = dotted_text(base) else { + /// + /// `Union[..]`, `Optional[..]`, and `Annotated[..]` (bare or + /// `typing.`-qualified) are *transparent* type operators — semantically + /// identical to their `|`-spellings — so they lower to [`TypeTerm::Union`] + /// (or the underlying type), NEVER to a `Named` constructor: they must + /// not guard recursion (`type X = Union[int, X]` is as circular as + /// `type X = int | X`). + fn lower_subscript(&self, sub: &ExprSubscript) -> TypeTerm { + let args = self.lower_subscript_args(sub); + let Some(base_name) = dotted_text(&sub.value) else { return TypeTerm::Ground(InferredType::Unknown); }; match (base_name.as_str(), args.len()) { + ("Union" | "typing.Union", _) => TypeTerm::Union(args), + ("Optional" | "typing.Optional", 1) => match args.into_iter().next() { + Some(inner) => { + TypeTerm::Union(vec![inner, TypeTerm::Ground(InferredType::None_)]) + } + None => TypeTerm::Ground(InferredType::Unknown), + }, + ("Annotated" | "typing.Annotated", _) => args + .into_iter() + .next() + .unwrap_or(TypeTerm::Ground(InferredType::Unknown)), ("list" | "List", 1) => match args.into_iter().next() { Some(element) => TypeTerm::List(Box::new(element)), None => TypeTerm::Ground(InferredType::Unknown), @@ -198,12 +218,8 @@ impl LowerCtx<'_> { /// Subscript arguments: a tuple slice contributes each element; /// `...` (as in `tuple[X, ...]` / `Callable[..., R]`) contributes /// nothing structural and is dropped. - fn lower_subscript_args(&self, slice: &Expr) -> Vec { - let elements: Vec<&Expr> = match slice { - Expr::Tuple(tuple) => tuple.elts.iter().collect(), - other => vec![other], - }; - elements + fn lower_subscript_args(&self, sub: &ExprSubscript) -> Vec { + basilisk_parser::subscript_elements(sub) .into_iter() .filter(|element| !matches!(element, Expr::EllipsisLiteral(_))) .map(|element| self.lower(element)) @@ -313,6 +329,74 @@ mod tests { } } + /// `Union[..]`, `Optional[..]`, and `Annotated[..]` are transparent type + /// operators, not constructors: recursion through them is exactly as + /// unguarded as through their `|`-spellings, while recursion through a + /// real constructor INSIDE them stays accepted. + #[test] + fn transparent_special_forms_do_not_guard_recursion() { + for (source, name, expected) in [ + ("type X = Union[int, X]\n", "X", Acceptance::Unguarded), + ("type X = typing.Union[int, X]\n", "X", Acceptance::Unguarded), + ("type Y = Optional[Y]\n", "Y", Acceptance::Unguarded), + ("type Y = typing.Optional[Y]\n", "Y", Acceptance::Unguarded), + ("type Z = Annotated[Z, \"meta\"]\n", "Z", Acceptance::Unguarded), + ("type A = Union[int, list[A]]\n", "A", Acceptance::Accepted), + ("type B = Optional[list[B]]\n", "B", Acceptance::Accepted), + ("type C = Annotated[list[C], \"meta\"]\n", "C", Acceptance::Accepted), + ] { + assert_eq!(classify_source_alias(source, name), Some(expected), "{source}"); + } + } + + /// Every compound-statement body is walked for `type` statements — + /// deleting any [`collect_type_aliases`] arm loses an alias here. + #[test] + fn aliases_are_collected_from_every_compound_statement_body() { + let source = "\ +if cond: + type A1 = int +elif cond: + type A2 = int +else: + type A3 = int +for item in items: + type B1 = int +else: + type B2 = int +while cond: + type C1 = int +else: + type C2 = int +with ctx: + type D1 = int +try: + type E1 = int +except Exception: + type E2 = int +else: + type E3 = int +finally: + type E4 = int +match value: + case 1: + type F1 = int +class Holder: + type G1 = int +def scope(): + type H1 = int +"; + let aliases = lower_all(source); + let names: Vec<&str> = aliases.iter().map(|alias| alias.name.as_str()).collect(); + assert_eq!( + names, + [ + "A1", "A2", "A3", "B1", "B2", "C1", "C2", "D1", "E1", "E2", "E3", "E4", "F1", + "G1", "H1" + ] + ); + } + /// Growing recursion lowers as non-regular (the Paterson/Coverage /// analogue rejects it; the escape hatch can still admit it). #[test] diff --git a/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs b/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs index 28d5abab..842229c0 100644 --- a/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs +++ b/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs @@ -129,6 +129,38 @@ fn bytes_literal_rhs_fires() -> Result<(), Box> { Ok(()) } +/// The statement's own type parameters shadow module-level bindings inside +/// the RHS (PEP 695 annotation scope): `T = 1` must not make `T` invalid in +/// `type Wrapper[T] = ...` — the RHS `T` is the type parameter, not the +/// module variable. +#[test] +fn alias_own_type_parameter_shadowing_a_module_var_is_not_flagged( +) -> Result<(), Box> { + for form in [ + "T = 1\ntype Wrapper[T] = T | None\n", + "T = 1\ntype Alias[T] = T\n", + "T = 1\ntype Boxed[T] = list[T]\n", + ] { + assert!( + !fires(form)?, + "the alias's own type parameter must shadow the module var: {form}" + ); + } + Ok(()) +} + +/// The shadowing is per-statement: a DIFFERENT alias without that type +/// parameter still sees the non-type module binding. +#[test] +fn non_type_module_var_still_fires_without_the_shadowing_param( +) -> Result<(), Box> { + assert!( + fires("T = 1\ntype Wrapper[U] = U | None\ntype Bad = T\n")?, + "an alias without the `T` parameter still sees the non-type `T = 1`" + ); + Ok(()) +} + /// Special-form subscript ARGUMENTS legitimately contain literals, lists, /// and ellipses — the validator must never descend into them. #[test] diff --git a/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs b/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs index 4525af4e..4a14f3ab 100644 --- a/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs +++ b/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs @@ -188,3 +188,82 @@ fn unguarded_self_reference_is_still_rejected() -> Result<(), Box Result<(), Box> { + for source in [ + "type X = Union[int, X]\n", + "type Y = Optional[Y]\n", + "type Z = Annotated[Z, \"meta\"]\n", + ] { + let diags = run(source)?; + assert!( + messages_for(&diags, "generics_syntax_scoping") + .iter() + .any(|m| m.contains("Circular")), + "Union/Optional/Annotated-spelled self-reference must fire.\nsource: {source}" + ); + } + for source in [ + "type A = Union[int, list[A]]\n", + "type B = Optional[list[B]]\n", + ] { + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"generics_syntax_scoping"), + "guarded recursion inside a transparent form is valid.\nsource: {source}\n got: {:?}", + messages_for(&diags, "generics_syntax_scoping") + ); + } + Ok(()) +} + +/// One diagnostic per circular alias: an alias flagged as unguarded by the +/// acceptance pass must not be reported AGAIN by the mutual-cycle pass at +/// the same span. +#[test] +fn circular_alias_is_reported_exactly_once() -> Result<(), Box> { + let diags = run("type A = A | B\ntype B = A\n")?; + let circular: Vec<_> = messages_for(&diags, "generics_syntax_scoping") + .into_iter() + .filter(|m| m.contains("Circular")) + .collect(); + assert_eq!( + circular.len(), + 2, + "exactly one circular diagnostic per alias (A unguarded, B in the chain): {circular:?}" + ); + Ok(()) +} + +/// Mutual cycles hidden behind transparent forms — `Union[..]` subscripts +/// and string forward references — are still cycles: no arm ever reaches a +/// constructor head. +#[test] +fn mutual_cycle_through_transparent_forms_fires() -> Result<(), Box> { + for source in [ + "type A = Union[int, B]\ntype B = A\n", + "type A = \"B\"\ntype B = A\n", + ] { + let diags = run(source)?; + assert!( + messages_for(&diags, "generics_syntax_scoping") + .iter() + .any(|m| m.contains("Circular")), + "a mutual cycle through a transparent form must fire.\nsource: {source}" + ); + } + // A constructor inside the transparent form guards: NOT a cycle. + let diags = run("type A = Union[int, list[B]]\ntype B = A\n")?; + assert!( + !codes(&diags).contains(&"generics_syntax_scoping"), + "recursion through list[..] inside Union[..] is valid, got: {:?}", + messages_for(&diags, "generics_syntax_scoping") + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/checker/names_undefined_tests.rs b/crates/basilisk-checker/tests/checker/names_undefined_tests.rs index 6f7213be..fa5f7d38 100644 --- a/crates/basilisk-checker/tests/checker/names_undefined_tests.rs +++ b/crates/basilisk-checker/tests/checker/names_undefined_tests.rs @@ -491,3 +491,71 @@ def alias() -> object: ); Ok(()) } + +#[test] +fn class_scope_type_alias_is_not_visible_from_a_function( +) -> Result<(), Box> { + // Class-body names do not nest: a `type` alias declared inside a class + // is reachable only as `C.Inner`, so a bare `Inner` in a module-level + // function is still an undefined name. + let source = "\ +class C: + type Inner = int + + +def f() -> object: + return Inner +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"names_undefined"), + "a class-scope alias must not leak into module scope, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +#[test] +fn function_scope_type_alias_is_not_visible_from_a_sibling( +) -> Result<(), Box> { + // A `type` alias declared inside one function is local to it — a + // sibling function referencing the name is an undefined name. + let source = "\ +def g() -> None: + type T = int + + +def f() -> object: + return T +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"names_undefined"), + "a function-scope alias must not leak into sibling functions, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +#[test] +fn function_scope_type_alias_is_visible_in_its_own_function( +) -> Result<(), Box> { + // Inside the declaring function (and its nested functions) the alias + // is an ordinary local binding. + let source = "\ +def f() -> object: + type T = int + + def inner() -> object: + return T + + return T +"; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"names_undefined"), + "a function-local alias is defined in its own scope, got: {:?}", + messages_for(&diags, "names_undefined") + ); + Ok(()) +} diff --git a/crates/basilisk-parser/src/lib.rs b/crates/basilisk-parser/src/lib.rs index ea104b5f..95d185e3 100644 --- a/crates/basilisk-parser/src/lib.rs +++ b/crates/basilisk-parser/src/lib.rs @@ -75,6 +75,27 @@ pub fn parse_source(source: String, path: String) -> Result Option { + ruff_python_parser::parse_expression(text.trim()) + .ok() + .map(|parsed| *parsed.into_syntax().body) +} + +/// The element expressions of a subscript slice: a tuple slice contributes +/// each element (`x[a, b]` → `[a, b]`), any other slice is the single +/// element (`x[a]` → `[a]`). +#[must_use] +pub fn subscript_elements(sub: &ruff_python_ast::ExprSubscript) -> Vec<&ruff_python_ast::Expr> { + match sub.slice.as_ref() { + ruff_python_ast::Expr::Tuple(tuple) => tuple.elts.iter().collect(), + other => vec![other], + } +} + /// Read a file from disk and parse it. /// /// # Errors diff --git a/crates/basilisk-resolver/src/scope/module_types.rs b/crates/basilisk-resolver/src/scope/module_types.rs index 30f7fdc9..cc00a217 100644 --- a/crates/basilisk-resolver/src/scope/module_types.rs +++ b/crates/basilisk-resolver/src/scope/module_types.rs @@ -311,6 +311,10 @@ pub struct TypeStatementInfo { pub rhs_span: Span, /// Span of the name token. pub name_span: Span, + /// The statement's own type-parameter names (`T` in `type X[T] = rhs`). + /// PEP 695 binds these in the alias's annotation scope, shadowing any + /// module-level binding of the same name inside the RHS. + pub param_names: Vec, } /// Information about an `Annotated[...]` subscription with too few arguments. diff --git a/crates/basilisk-resolver/src/scope/pep695_scoping.rs b/crates/basilisk-resolver/src/scope/pep695_scoping.rs index e680f080..bf79dcd8 100644 --- a/crates/basilisk-resolver/src/scope/pep695_scoping.rs +++ b/crates/basilisk-resolver/src/scope/pep695_scoping.rs @@ -82,14 +82,21 @@ pub struct Pep695AliasDef { pub params: Vec, /// Simple names referenced in the RHS value expression. pub rhs_refs: Vec, - /// Names referenced at the *top level* of the RHS — a bare `Name` or a direct - /// member of a top-level `X | Y` union — but NOT names nested inside a - /// subscript/container. A bare reference to another alias is non-terminating - /// (`type A = B`), whereas one through a container (`type A = list[B]`) is - /// legitimate recursion; this powers mutual-cycle detection (`generics_syntax_scoping`). + /// Names referenced at the *same level* as the RHS: a bare `Name`, a member + /// of an `X | Y` union, an argument of a transparent + /// `Union[..]`/`Optional[..]`/`Annotated[..]` form, or a parsed string + /// forward reference — but NOT names inside a real constructor subscript. + /// A bare reference to another alias is non-terminating (`type A = B`), + /// whereas one through a container (`type A = list[B]`) is legitimate + /// recursion; this powers mutual-cycle detection (`generics_syntax_scoping`). pub rhs_bare_refs: Vec, /// `true` when this alias is nested (directly or transitively) in a function body. pub in_function: bool, + /// `true` when this alias's nearest enclosing scope is a class body. + /// Class-scope names are not visible from methods or module scope — + /// only module-scope aliases (`!in_function && !in_class`) bind a name + /// every function body can see. + pub in_class: bool, } /// An attribute access `Name.attr` somewhere in the module (outside `type` RHS). diff --git a/crates/basilisk-resolver/src/visitor/assigns.rs b/crates/basilisk-resolver/src/visitor/assigns.rs index fb2fd15c..10100ee4 100644 --- a/crates/basilisk-resolver/src/visitor/assigns.rs +++ b/crates/basilisk-resolver/src/visitor/assigns.rs @@ -79,6 +79,13 @@ fn collect_statement_assigns(stmts: &[Stmt]) -> Vec { // like a nested function. Do NOT recurse into the class body. out.push(class.name.to_string()); } + Stmt::TypeAlias(node) => { + // A PEP 695 `type` statement binds its alias name in the + // enclosing scope, exactly like a `def`. + if let Some(name) = expr_simple_name(&node.name) { + out.push(name); + } + } Stmt::Import(node) => { // A function-local import binds names in the enclosing scope and // is reachable by nested scopes (incl. methods of nested classes). @@ -150,6 +157,12 @@ pub(super) fn collect_unconditional_assigns(stmts: &[Stmt]) -> Vec { Stmt::ClassDef(class) => { assignments.push(class.name.to_string()); } + Stmt::TypeAlias(node) => { + // A `type` statement binds unconditionally, like a `def`. + if let Some(name) = expr_simple_name(&node.name) { + assignments.push(name); + } + } Stmt::Import(node) => { // Top-level imports bind their names unconditionally. assignments.extend(plain_import_bound_names(node)); diff --git a/crates/basilisk-resolver/src/visitor/pep695_scoping.rs b/crates/basilisk-resolver/src/visitor/pep695_scoping.rs index 0ef72e74..05100d58 100644 --- a/crates/basilisk-resolver/src/visitor/pep695_scoping.rs +++ b/crates/basilisk-resolver/src/visitor/pep695_scoping.rs @@ -5,7 +5,7 @@ //! docstring content can never be mistaken for real declarations. use ruff_python_ast::{ - Decorator, Expr, Stmt, StmtClassDef, StmtFunctionDef, StmtTypeAlias, TypeParam, + Decorator, Expr, ExprSubscript, Stmt, StmtClassDef, StmtFunctionDef, StmtTypeAlias, TypeParam, }; use ruff_text_size::Ranged; @@ -130,6 +130,7 @@ fn collect_alias(alias: &StmtTypeAlias, ctx: &Ctx<'_>, source: &str, out: &mut P rhs_refs, rhs_bare_refs, in_function: ctx.scope == Scope::Function, + in_class: ctx.scope == Scope::Class, }); record_module_binding_offset(ctx, &name, alias.name.range().start().to_u32(), out); } @@ -221,12 +222,12 @@ fn enclosing_params(ctx: &Ctx<'_>) -> Vec { // Self-reference / attribute / binding helpers // --------------------------------------------------------------------------- -/// Find the first `alias_name[args]` subscript anywhere in `expr` and return -/// the simple names of its arguments. -/// Collect names that appear at the *top level* of a type-alias RHS: a bare -/// `Name`, or a direct member of a top-level `X | Y` union. Subscripts/calls are -/// NOT descended into — a reference through a container terminates and so is not -/// a bare reference. (Optional `X | None` contributes `X`; `None` is ignored.) +/// Collect names that appear at the *same level* as a type-alias RHS: a bare +/// `Name`, a member of an `X | Y` union, an argument of a transparent +/// `Union[..]`/`Optional[..]`/`Annotated[..]` form, or a parsed string +/// forward reference. Real constructor subscripts (`list[X]`) are NOT +/// descended into — a reference through a container terminates and so is +/// not a bare reference. fn collect_bare_refs(expr: &Expr, out: &mut Vec) { match expr { Expr::Name(name) => out.push(name.id.to_string()), @@ -234,10 +235,42 @@ fn collect_bare_refs(expr: &Expr, out: &mut Vec) { collect_bare_refs(&bin.left, out); collect_bare_refs(&bin.right, out); } + // A string forward reference is evaluated at the same level. + Expr::StringLiteral(literal) => { + if let Some(inner) = basilisk_parser::parse_type_expression(literal.value.to_str()) { + collect_bare_refs(&inner, out); + } + } + Expr::Subscript(sub) => { + for arg in transparent_subscript_args(sub) { + collect_bare_refs(arg, out); + } + } _ => {} } } +/// The same-level type arguments of a transparent special-form subscript — +/// all of `Union[..]`'s, `Optional[..]`'s, `Annotated[..]`'s first (its +/// remaining arguments are metadata, not types) — or empty for any other +/// base, which is a real constructor and guards recursion. Both bare and +/// `typing.`-qualified spellings count. +fn transparent_subscript_args(sub: &ExprSubscript) -> Vec<&Expr> { + let head = match sub.value.as_ref() { + Expr::Name(name) => name.id.as_str(), + Expr::Attribute(attr) if expr_simple_name(&attr.value).as_deref() == Some("typing") => { + attr.attr.as_str() + } + _ => return Vec::new(), + }; + let args = basilisk_parser::subscript_elements(sub); + match head { + "Union" | "Optional" => args, + "Annotated" => args.into_iter().take(1).collect(), + _ => Vec::new(), + } +} + /// Recursively collect `Name.attr` accesses from an expression tree. fn collect_attr_accesses(expr: &Expr, out: &mut Pep695Scoping) { if let Expr::Attribute(attr) = expr { diff --git a/crates/basilisk-resolver/src/visitor/type_alias.rs b/crates/basilisk-resolver/src/visitor/type_alias.rs index c58c97a2..26e7d491 100644 --- a/crates/basilisk-resolver/src/visitor/type_alias.rs +++ b/crates/basilisk-resolver/src/visitor/type_alias.rs @@ -417,6 +417,11 @@ pub(super) fn collect_type_statements(stmts: &[Stmt]) -> Vec name: name_str, rhs_span: text_range_to_span(ta.value.range()), name_span: text_range_to_span(ta.name.range()), + param_names: ta + .type_params + .as_deref() + .map(|tps| tps.type_params.iter().map(type_param_name).collect()) + .unwrap_or_default(), }); } } diff --git a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md index 994a2e79..1f59a5ac 100644 --- a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md +++ b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md @@ -1177,9 +1177,11 @@ backdating pinned by `tests/tyeval_salsa_tests.rs`), with: - **GHC-style acceptance conditions** (Paterson/Coverage analogues) that statically reject obviously-nonterminating definitions — `accept::classify` gates `AliasEnv::insert` (self-references must sit under a type - constructor; union arms do not guard; self-application arguments must not - grow) — with the opt-in `insert_undecidable` escape hatch falling back to - fuel. + constructor; union arms do not guard, and the transparent + `Union[..]`/`Optional[..]`/`Annotated[..]` spellings lower to unions so + they cannot guard either (`lower::LowerCtx::lower_subscript`); + self-application arguments must not grow) — with the opt-in + `insert_undecidable` escape hatch falling back to fuel. Mapped types are **kind `Type → Type` operators** (`term::Kind`, `TypeTerm::Op`/`Apply`, higher-order through parameters); conditional types From 84a7661e177ca73adab87f98c7af6b9bc94d918d Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 07:59:37 +1000 Subject: [PATCH 06/45] fixes --- Makefile | 9 + .../torture/cases/enum_literal_expansion.py | 23 + .../torture/cases/generic_constructor.py | 28 ++ benchmarks/torture/cases/param_inference.py | 16 + .../torture/cases/paramspec_decorator.py | 25 ++ benchmarks/torture/cases/recursive_aliases.py | 21 + benchmarks/torture/cases/recursive_bases.py | 17 + benchmarks/torture/cases/tuple_index.py | 15 + benchmarks/torture/cases/typeis_narrowing.py | 22 + benchmarks/torture/results/summary.md | 43 ++ benchmarks/torture/run_torture.py | 422 ++++++++++++++++++ benchmarks/torture/status/torture.csv | 22 + .../tests/checker/aliases_recursive_tests.rs | 69 +++ .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 39 +- 14 files changed, 769 insertions(+), 2 deletions(-) create mode 100644 benchmarks/torture/cases/enum_literal_expansion.py create mode 100644 benchmarks/torture/cases/generic_constructor.py create mode 100644 benchmarks/torture/cases/param_inference.py create mode 100644 benchmarks/torture/cases/paramspec_decorator.py create mode 100644 benchmarks/torture/cases/recursive_aliases.py create mode 100644 benchmarks/torture/cases/recursive_bases.py create mode 100644 benchmarks/torture/cases/tuple_index.py create mode 100644 benchmarks/torture/cases/typeis_narrowing.py create mode 100644 benchmarks/torture/results/summary.md create mode 100644 benchmarks/torture/run_torture.py create mode 100644 benchmarks/torture/status/torture.csv diff --git a/Makefile b/Makefile index 6b336436..e8796338 100644 --- a/Makefile +++ b/Makefile @@ -255,6 +255,15 @@ bench: bench-basilisk: @BENCH_ONLY_BASILISK=1 bash benchmarks/run.sh +## torture: Type-torture scoreboard — hard, spec-grounded typing problems +## scored conformance-style (`# E` lines) against pyright/mypy/ty/pyrefly/zuban, +## every tool in its out-of-the-box defaults, with hang detection as a +## correctness axis. WRITE-ALWAYS to benchmarks/torture/status/torture.csv, +## read-only regression gate against the committed baseline (exit 3). +## Needs target/release/basilisk (or BASILISK_BIN); build it first. +torture: + @python3 benchmarks/torture/run_torture.py + ## smoke-micropython: Real-world smoke test for typeshed-path ## [STUBRES-CUSTOM-TYPESHED] — points the checker at a pinned, unmodified ## micropython-stdlib-stubs release and asserts MicroPython stdlib resolves diff --git a/benchmarks/torture/cases/enum_literal_expansion.py b/benchmarks/torture/cases/enum_literal_expansion.py new file mode 100644 index 00000000..21a98305 --- /dev/null +++ b/benchmarks/torture/cases/enum_literal_expansion.py @@ -0,0 +1,23 @@ +"""Enum literal expansion — the #374 equivalence. + +The typing spec's enumerations chapter +(https://typing.python.org/en/latest/spec/enums.html#enum-literal-expansion) +says a type checker should treat a complete union of all literal members as +EQUIVALENT to the enum type, in both directions. Everything below is legal: +any diagnostic is a false positive. +""" + +import enum +from typing import Literal, assert_type + + +class Answer(enum.Enum): + Yes = 1 + No = 2 + + +def to_literal(a: Answer) -> None: + x: Literal[Answer.Yes, Answer.No] = a + assert_type(a, Literal[Answer.Yes, Answer.No]) + y: Answer = x + assert_type(y, Answer) diff --git a/benchmarks/torture/cases/generic_constructor.py b/benchmarks/torture/cases/generic_constructor.py new file mode 100644 index 00000000..1a8e3c91 --- /dev/null +++ b/benchmarks/torture/cases/generic_constructor.py @@ -0,0 +1,28 @@ +"""Generic constructor and call-site inference — the #290 family. + +Calling a generic class solves its type parameters from the constructor +arguments, and a generic function's return type follows from its solved +parameters (https://typing.python.org/en/latest/spec/generics.html — PEP 695 +syntax). `dict(a=1)` solves `dict[str, int]` through the keyword-arguments +constructor. Every `assert_type` below is required to hold; a checker that +leaves the parameters unsolved (or guesses wrong) fails the case. +""" + +from typing import assert_type + + +class Box[T]: + def __init__(self, item: T) -> None: + self.item = item + + +def unbox[T](box: Box[T]) -> T: + return box.item + + +b = Box(1) +assert_type(b, Box[int]) +assert_type(unbox(Box("s")), str) + +d = dict(a=1) +assert_type(d, dict[str, int]) diff --git a/benchmarks/torture/cases/param_inference.py b/benchmarks/torture/cases/param_inference.py new file mode 100644 index 00000000..34f18cf1 --- /dev/null +++ b/benchmarks/torture/cases/param_inference.py @@ -0,0 +1,16 @@ +"""Unannotated parameters used consistently — the #317 gradual posture. + +Unannotated code is GRADUAL: parameters without annotations are implicitly +`Any`-typed and the typing spec mandates no diagnostic for their absence +(https://typing.python.org/en/latest/spec/type-system.html#the-gradual-guarantee +— strictness rules demanding annotations are opt-in house rules in every +checker's out-of-the-box configuration). The call and the arithmetic are +well-typed under any inference. Any diagnostic below is a false positive. +""" + + +def multiply(x, y) -> int: + return x * y + + +result: int = multiply(4, 5) diff --git a/benchmarks/torture/cases/paramspec_decorator.py b/benchmarks/torture/cases/paramspec_decorator.py new file mode 100644 index 00000000..dfb4d1db --- /dev/null +++ b/benchmarks/torture/cases/paramspec_decorator.py @@ -0,0 +1,25 @@ +"""PEP 612 `ParamSpec` signature preservation through a decorator. + +An identity decorator over `Callable[P, R]` preserves the wrapped function's +full signature (https://peps.python.org/pep-0612/). The valid call is clean; +the two invalid calls are required errors: a `str` argument against the +preserved `int` parameter, and a missing second argument against the +preserved arity. A checker that erases the signature at the decorator +boundary misses both and fails the case. +""" + +from typing import Callable + + +def dec[**P, R](f: Callable[P, R]) -> Callable[P, R]: + return f + + +@dec +def add(a: int, b: int) -> int: + return a + b + + +ok = add(1, 2) +bad_type = add("1", 2) # E +bad_arity = add(1) # E diff --git a/benchmarks/torture/cases/recursive_aliases.py b/benchmarks/torture/cases/recursive_aliases.py new file mode 100644 index 00000000..dd1b1024 --- /dev/null +++ b/benchmarks/torture/cases/recursive_aliases.py @@ -0,0 +1,21 @@ +"""Recursive PEP 695 type aliases — the #371 family. + +PEP 695 formally mandates that recursive type aliases work +(https://typing.python.org/en/latest/spec/aliases.html), so every guarded +definition below must draw NO diagnostic. The two unguarded definitions are +required errors: upstream conformance `aliases_type_statement.py` marks +`type R3 = R3` and `type R4[T] = T | R4[str]` as `# E` — a self-reference +that never passes through a type constructor has no terminating expansion. +""" + +type Json = None | bool | int | float | str | list[Json] | dict[str, Json] +type RecursiveTuple = str | int | tuple[RecursiveTuple, ...] +type Tree[T] = T | list[Tree[T]] + + +def keep(j: Json, t: RecursiveTuple, tr: Tree[int]) -> None: + pass + + +type R3 = R3 # E +type R4[T] = T | R4[str] # E diff --git a/benchmarks/torture/cases/recursive_bases.py b/benchmarks/torture/cases/recursive_bases.py new file mode 100644 index 00000000..de3bf122 --- /dev/null +++ b/benchmarks/torture/cases/recursive_bases.py @@ -0,0 +1,17 @@ +"""Self-referential class bases — the #398 hang reproducer. + +A class name is not bound until the `class` statement completes, so using it +in its own bases list is an unbound-name error at evaluation time (Python +language semantics; `NameError` at runtime). The torture here is not the +diagnostic — it is TERMINATION: this fuzzed shape hung `basilisk check` +(https://github.com/Nimblesite/Basilisk/issues/398). A checker that spins +forever fails the case by timeout regardless of what it would have printed. +""" + + +class C(C[int], C[bool]): # E + pass + + +class D(D): # E + pass diff --git a/benchmarks/torture/cases/tuple_index.py b/benchmarks/torture/cases/tuple_index.py new file mode 100644 index 00000000..55eeebda --- /dev/null +++ b/benchmarks/torture/cases/tuple_index.py @@ -0,0 +1,15 @@ +"""Fixed-length tuple indexing, including through a contextual lambda — #284. + +Indexing a fixed-length tuple with an out-of-range literal integer is a type +error (https://typing.python.org/en/latest/spec/tuples.html), so `two[2]` is +a required error. The lambda is the #284 false-positive shape: `pair` is +contextually a 3-tuple via `sorted`'s key parameter, so `pair[2]` is in +range — a checker that models the key parameter as a 2-tuple (or loses the +element count) reports a false positive and fails the case. +""" + +items: list[tuple[str, int, float]] = [("a", 1, 1.0)] +in_order = sorted(items, key=lambda pair: (pair[1], pair[2], pair[0])) + +two: tuple[int, str] = (1, "a") +bad = two[2] # E diff --git a/benchmarks/torture/cases/typeis_narrowing.py b/benchmarks/torture/cases/typeis_narrowing.py new file mode 100644 index 00000000..f109bff8 --- /dev/null +++ b/benchmarks/torture/cases/typeis_narrowing.py @@ -0,0 +1,22 @@ +"""PEP 742 `TypeIs` narrowing, both branches. + +PEP 742 (https://peps.python.org/pep-0742/) mandates the asymmetric +narrowing: in the positive branch the argument narrows to the intersection +with the `TypeIs` type; in the negative branch the `TypeIs` type is +SUBTRACTED. Both `assert_type` lines are therefore required to hold — a +checker that narrows only the positive branch (or not at all) reports an +`assert_type` mismatch and fails the case. +""" + +from typing import TypeIs, assert_type + + +def is_str(x: object) -> TypeIs[str]: + return isinstance(x, str) + + +def split(x: int | str) -> None: + if is_str(x): + assert_type(x, str) + else: + assert_type(x, int) diff --git a/benchmarks/torture/results/summary.md b/benchmarks/torture/results/summary.md new file mode 100644 index 00000000..9af9db3f --- /dev/null +++ b/benchmarks/torture/results/summary.md @@ -0,0 +1,43 @@ +# Type-torture results + +Methodology: see the header of `benchmarks/torture/run_torture.py` and of +`benchmarks/torture/status/torture.csv`. Every case file states the spec +section or PEP that makes its expectations authoritative. + +| case | basilisk | pyright | mypy | ty | pyrefly | zuban | +|---|---|---|---|---|---|---| +| enum_literal_expansion | fail(m0,x1) | fail(m0,x3) | pass | pass | pass | fail(m0,x2) | +| generic_constructor | pass | pass | pass | fail(m0,x2) | pass | pass | +| param_inference | pass | pass | pass | pass | pass | pass | +| paramspec_decorator | pass | pass | pass | fail(m0,x1) | pass | pass | +| recursive_aliases | pass | pass | pass | fail(m0,x3) | pass | pass | +| recursive_bases | hang | pass | pass | pass | pass | pass | +| tuple_index | fail(m1,x0) | pass | pass | pass | pass | pass | +| typeis_narrowing | pass | pass | pass | fail(m0,x3) | pass | pass | +| **passed** | 5/8 | 7/8 | 8/8 | 4/8 | 8/8 | 7/8 | + +Versions measured: basilisk basilisk 0.0.0-PLACEHOLDER; pyright pyright 1.1.408; mypy mypy 1.19.1 (compiled: yes); ty ty 0.0.19 (ae10022c2 2026-02-26); pyrefly pyrefly 0.54.0; zuban zuban 0.9.0 + +## enum_literal_expansion +- basilisk: missed error lines [], false positives on [20] +- pyright: missed error lines [], false positives on [20, 21, 23] +- zuban: missed error lines [], false positives on [20, 21] + +## generic_constructor +- ty: missed error lines [], false positives on [14, 19] + +## paramspec_decorator +- ty: missed error lines [], false positives on [14] + +## recursive_aliases +- ty: missed error lines [], false positives on [11, 12, 13] + +## recursive_bases +- basilisk: hang + +## tuple_index +- basilisk: missed error lines [15], false positives on [] + +## typeis_narrowing +- ty: missed error lines [], false positives on [11, 20, 22] + diff --git a/benchmarks/torture/run_torture.py b/benchmarks/torture/run_torture.py new file mode 100644 index 00000000..9ce42447 --- /dev/null +++ b/benchmarks/torture/run_torture.py @@ -0,0 +1,422 @@ +#!/usr/bin/env python3 +"""Type-torture scoreboard: Basilisk vs pyright, mypy, ty, pyrefly, zuban. + +Implements the first slice of [NARROWPLAN-SUPERIORITY] — see +docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUPERIORITY. + +Eight small, hard typing problems (benchmarks/torture/cases/*.py), each +grounded in a typing-spec section, an accepted PEP, or Python language +semantics — several are reproducers from this repo's own issue tracker +(#371 recursive aliases, #398 recursive-base hang, #374 enum literal +expansion, #317 gradual unannotated code, #284 tuple-index false positive). + +METHODOLOGY (stated here because the results are published): + + * Every tool runs in its OUT-OF-THE-BOX default configuration on a + config-neutral copy of each case — the same "what a user gets with no + config" frame as the upstream python/typing conformance harness and + benchmarks/run.sh. No strictness flags for anyone. + * Scoring is conformance-style and exact, per case: a line whose source + ends in `# E` REQUIRES at least one error diagnostic on that line; a + line without the marker must have NONE. A tool passes a case iff both + hold. Error severity only — warnings, notes, and infos never count. + * A tool that exceeds the per-invocation timeout is scored `hang` (the + #398 axis: termination is part of correctness). A tool that exits >= 2 + with no parseable diagnostics is scored `crash`. Both fail the case. + * Competitor versions are the LATEST official release, pulled (best + effort, loudly on failure) at the top of every run — leads are proven + against current upstream, never a stale pin. + +WRITE-ALWAYS, GATE-SEPARATELY (same contract as benchmarks/summarize.py): + + 1. WRITE. The scoreboard CSV (benchmarks/torture/status/torture.csv) is + rewritten from the accumulated results after EVERY case completes. + There is no gate on the write: the file always shows exactly what this + run measured, the instant each verdict exists. + 2. GATE. After all cases, the run's basilisk verdicts are compared + against the COMMITTED CSV (read from git at HEAD, never the working + copy just overwritten). A case basilisk passed at HEAD that no longer + passes exits 3 -> CI failure. The gate only reads; it never edits. + With no committed CSV yet, the baseline establishes on first commit. + +Usage: python3 benchmarks/torture/run_torture.py +Knobs: TORTURE_TIMEOUT (seconds per invocation, default 30) + TORTURE_NO_PULL=1 (skip the competitor pull: local iteration only, + refused in CI so published columns always reflect latest upstream) +""" + +import json +import os +import shutil +import subprocess +import sys +import tempfile +from dataclasses import dataclass +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +CASES_DIR = Path(__file__).resolve().parent / "cases" +STATUS_CSV = Path(__file__).resolve().parent / "status" / "torture.csv" +SUMMARY_MD = Path(__file__).resolve().parent / "results" / "summary.md" +COMPETITORS = ["pyright", "mypy", "ty", "pyrefly", "zuban"] +TIMEOUT = int(os.environ.get("TORTURE_TIMEOUT", "30")) + + +@dataclass +class Outcome: + """One tool's verdict on one case.""" + + verdict: str # pass | fail | hang | crash + missed: list[int] + extra: list[int] + + def cell(self) -> str: + if self.verdict != "fail": + return self.verdict + return f"fail(m{len(self.missed)},x{len(self.extra)})" + + +def fail_usage(message: str) -> "sys.NoReturn": + print(f"ERROR: {message}", file=sys.stderr) + sys.exit(2) + + +def basilisk_bin() -> Path: + binary = Path( + os.environ.get("BASILISK_BIN", ROOT / "target" / "release" / "basilisk") + ) + if not binary.is_file(): + fail_usage( + f"basilisk binary not found at {binary} — build with `cargo build --release`." + ) + return binary + + +def pull_latest() -> None: + """Best-effort upgrade of every competitor to its newest official release. + + Mirrors benchmarks/run.sh: a failed pull warns LOUDLY and the run + continues on the installed version — visible in the log, never silent. + """ + if os.environ.get("TORTURE_NO_PULL"): + if os.environ.get("GITHUB_ACTIONS") == "true": + fail_usage( + "TORTURE_NO_PULL is a local iteration mode; CI must pull latest." + ) + print(" local iteration mode — competitors NOT pulled; columns may be stale.") + return + for tool in COMPETITORS: + result = subprocess.run( + [ + sys.executable, + "-m", + "pip", + "install", + "--upgrade", + "--quiet", + "--disable-pip-version-check", + tool, + ], + capture_output=True, + text=True, + check=False, + ) + if result.returncode != 0: + print( + f" ⚠ {tool}: could not pull latest — using installed version. " + f"Column may be stale.", + file=sys.stderr, + ) + + +def tool_version(name: str, command: list[str]) -> str: + try: + result = subprocess.run( + [command[0], "--version"], + capture_output=True, + text=True, + timeout=60, + check=False, + ) + first_line = (result.stdout or result.stderr).strip().splitlines() + return first_line[0] if first_line else "unknown" + except (OSError, subprocess.TimeoutExpired): + return "not installed" + + +def expected_error_lines(case: Path) -> set[int]: + """Line numbers (1-based) whose source line ends with the `# E` marker.""" + lines = case.read_text(encoding="utf-8").splitlines() + return { + index + for index, line in enumerate(lines, start=1) + if line.rstrip().endswith("# E") + } + + +def parse_mypy_style(output: str, filename: str) -> set[int]: + """`path:LINE: error: ...` lines (mypy and zuban).""" + reported: set[int] = set() + for line in output.splitlines(): + parts = line.split(":", 3) + if len(parts) >= 3 and Path(parts[0]).name == filename: + line_number, severity = parts[1].strip(), parts[2].strip() + if line_number.isdigit() and severity == "error": + reported.add(int(line_number)) + return reported + + +def parse_pyright_json(output: str, filename: str) -> set[int]: + """pyright --outputjson: generalDiagnostics with severity == error.""" + try: + payload = json.loads(output) + except json.JSONDecodeError: + return set() + reported: set[int] = set() + for diagnostic in payload.get("generalDiagnostics", []): + if diagnostic.get("severity") != "error": + continue + if Path(diagnostic.get("file", "")).name != filename: + continue + line = diagnostic.get("range", {}).get("start", {}).get("line") + if isinstance(line, int): + reported.add(line + 1) # pyright ranges are 0-based + return reported + + +def parse_arrow_style( + output: str, filename: str, error_prefix: str, demote_prefix: str +) -> set[int]: + """Header + `--> path:line:col` blocks (basilisk, ty, pyrefly). + + An error header arms attribution; the next `-->` location consumes it. + A warning header disarms it so a warning's location is never counted. + """ + reported: set[int] = set() + armed = False + for line in output.splitlines(): + stripped = line.strip() + if stripped.startswith(error_prefix): + armed = True + continue + if stripped.startswith(demote_prefix): + armed = False + continue + if armed and stripped.startswith("-->"): + location = stripped.removeprefix("-->").strip() + parts = location.split(":") + if ( + len(parts) >= 2 + and Path(parts[0]).name == filename + and parts[1].isdigit() + ): + reported.add(int(parts[1])) + armed = False + return reported + + +def tool_commands(basilisk: Path, mypy_cache: Path) -> list[tuple[str, list[str]]]: + """(name, argv-with-{file}-placeholder) per tool, defaults only.""" + return [ + ("basilisk", [str(basilisk), "check", "{file}"]), + ("pyright", ["pyright", "--outputjson", "{file}"]), + ( + "mypy", + [ + "mypy", + "--no-incremental", + "--no-error-summary", + "--cache-dir", + str(mypy_cache), + "{file}", + ], + ), + ("ty", ["ty", "check", "{file}"]), + ("pyrefly", ["pyrefly", "check", "{file}"]), + ("zuban", ["zuban", "check", "{file}"]), + ] + + +def parse_output(tool: str, output: str, filename: str) -> set[int]: + if tool == "pyright": + return parse_pyright_json(output, filename) + if tool in ("mypy", "zuban"): + return parse_mypy_style(output, filename) + if tool == "pyrefly": + return parse_arrow_style(output, filename, "ERROR", "WARN") + return parse_arrow_style(output, filename, "error[", "warning[") + + +def run_case(tool: str, argv: list[str], case: Path, workdir: Path) -> Outcome: + command = [part.replace("{file}", case.name) for part in argv] + try: + result = subprocess.run( + command, + cwd=workdir, + capture_output=True, + text=True, + timeout=TIMEOUT, + check=False, + ) + except subprocess.TimeoutExpired: + return Outcome("hang", [], []) + except OSError: + return Outcome("crash", [], []) + reported = parse_output(tool, result.stdout + "\n" + result.stderr, case.name) + if result.returncode >= 2 and not reported and tool != "pyright": + return Outcome("crash", [], []) + expected = expected_error_lines(case) + missed = sorted(expected - reported) + extra = sorted(reported - expected) + if not missed and not extra: + return Outcome("pass", [], []) + return Outcome("fail", missed, extra) + + +def write_status( + tools: list[str], versions: dict[str, str], results: dict[str, dict[str, Outcome]] +) -> None: + """WRITE-ALWAYS: rewrite the tracked CSV from every verdict so far.""" + STATUS_CSV.parent.mkdir(parents=True, exist_ok=True) + lines = [ + "# Type-torture scoreboard — see benchmarks/torture/run_torture.py for the", + "# full methodology. Self-measured: every tool in its out-of-the-box default", + "# config, same machine, same corpus; scored conformance-style (`# E` lines", + "# require an error; unmarked lines require silence; error severity only).", + "# hang = exceeded the per-invocation timeout; crash = exit >= 2 with no", + "# parseable diagnostics. Regenerated by every run; never hand-edited.", + ] + lines.extend(f"# {tool}: {versions[tool]}" for tool in tools) + lines.append("case," + ",".join(tools)) + for case_name in sorted(results): + cells = [results[case_name][tool].cell() for tool in tools] + lines.append(f"{case_name}," + ",".join(cells)) + if results: + totals = [ + str(sum(1 for case in results.values() if case[tool].verdict == "pass")) + + f"/{len(results)}" + for tool in tools + ] + lines.append("passed," + ",".join(totals)) + STATUS_CSV.write_text("\n".join(lines) + "\n", encoding="utf-8") + + +def write_summary( + tools: list[str], versions: dict[str, str], results: dict[str, dict[str, Outcome]] +) -> None: + lines = [ + "# Type-torture results", + "", + "Methodology: see the header of `benchmarks/torture/run_torture.py` and of", + "`benchmarks/torture/status/torture.csv`. Every case file states the spec", + "section or PEP that makes its expectations authoritative.", + "", + "| case | " + " | ".join(tools) + " |", + "|---" * (len(tools) + 1) + "|", + ] + for case_name in sorted(results): + row = [results[case_name][tool].cell() for tool in tools] + lines.append(f"| {case_name} | " + " | ".join(row) + " |") + totals = [ + str(sum(1 for case in results.values() if case[tool].verdict == "pass")) + + f"/{len(results)}" + for tool in tools + ] + lines.append("| **passed** | " + " | ".join(totals) + " |") + lines.extend( + ["", "Versions measured: " + "; ".join(f"{t} {versions[t]}" for t in tools), ""] + ) + for case_name in sorted(results): + details = [ + f"- {tool}: missed error lines {outcome.missed}, false positives on {outcome.extra}" + for tool, outcome in results[case_name].items() + if outcome.verdict == "fail" + ] + hangs = [ + f"- {tool}: {outcome.verdict}" + for tool, outcome in results[case_name].items() + if outcome.verdict in ("hang", "crash") + ] + if details or hangs: + lines.extend([f"## {case_name}", *details, *hangs, ""]) + SUMMARY_MD.parent.mkdir(parents=True, exist_ok=True) + SUMMARY_MD.write_text("\n".join(lines) + "\n", encoding="utf-8") + + +def committed_basilisk_passes() -> set[str] | None: + """Case names basilisk passes in the COMMITTED CSV (None = no baseline).""" + relative = STATUS_CSV.relative_to(ROOT) + result = subprocess.run( + ["git", "-C", str(ROOT), "show", f"HEAD:{relative}"], + capture_output=True, + text=True, + check=False, + ) + if result.returncode != 0: + return None + passes: set[str] = set() + header: list[str] = [] + for line in result.stdout.splitlines(): + if line.startswith("#") or not line.strip(): + continue + cells = line.split(",") + if cells[0] == "case": + header = cells + continue + if cells[0] == "passed" or "basilisk" not in header: + continue + if cells[header.index("basilisk")] == "pass": + passes.add(cells[0]) + return passes + + +def gate(results: dict[str, dict[str, Outcome]]) -> None: + """GATE-SEPARATELY: basilisk may never lose a case it passed at HEAD.""" + baseline = committed_basilisk_passes() + if baseline is None: + print( + " no committed baseline yet — it establishes when this CSV is committed." + ) + return + regressions = [ + case + for case in sorted(baseline) + if case in results and results[case]["basilisk"].verdict != "pass" + ] + if regressions: + print( + f"GATE FAILURE: basilisk regressed on: {', '.join(regressions)}", + file=sys.stderr, + ) + sys.exit(3) + print(" gate: no basilisk regression against the committed baseline.") + + +def main() -> None: + cases = sorted(CASES_DIR.glob("*.py")) + if not cases: + fail_usage(f"no cases found in {CASES_DIR}") + print("Pulling latest competitor releases (best effort)…") + pull_latest() + with tempfile.TemporaryDirectory(prefix="basilisk-torture.") as tmp: + workdir = Path(tmp) + for case in cases: + shutil.copy(case, workdir / case.name) + tools = tool_commands(basilisk_bin(), workdir / ".mypy_cache_torture") + names = [name for name, _ in tools] + versions = {name: tool_version(name, argv) for name, argv in tools} + results: dict[str, dict[str, Outcome]] = {} + for case in cases: + results[case.stem] = { + name: run_case(name, argv, case, workdir) for name, argv in tools + } + write_status(names, versions, results) # write-always, per case + cells = ", ".join(f"{n}={results[case.stem][n].cell()}" for n in names) + print(f" {case.stem}: {cells}") + write_summary(names, versions, results) + print(f"Scoreboard: {STATUS_CSV}\nSummary: {SUMMARY_MD}") + gate(results) + + +if __name__ == "__main__": + main() diff --git a/benchmarks/torture/status/torture.csv b/benchmarks/torture/status/torture.csv new file mode 100644 index 00000000..8b55e771 --- /dev/null +++ b/benchmarks/torture/status/torture.csv @@ -0,0 +1,22 @@ +# Type-torture scoreboard — see benchmarks/torture/run_torture.py for the +# full methodology. Self-measured: every tool in its out-of-the-box default +# config, same machine, same corpus; scored conformance-style (`# E` lines +# require an error; unmarked lines require silence; error severity only). +# hang = exceeded the per-invocation timeout; crash = exit >= 2 with no +# parseable diagnostics. Regenerated by every run; never hand-edited. +# basilisk: basilisk 0.0.0-PLACEHOLDER +# pyright: pyright 1.1.408 +# mypy: mypy 1.19.1 (compiled: yes) +# ty: ty 0.0.19 (ae10022c2 2026-02-26) +# pyrefly: pyrefly 0.54.0 +# zuban: zuban 0.9.0 +case,basilisk,pyright,mypy,ty,pyrefly,zuban +enum_literal_expansion,fail(m0,x1),fail(m0,x3),pass,pass,pass,fail(m0,x2) +generic_constructor,pass,pass,pass,fail(m0,x2),pass,pass +param_inference,pass,pass,pass,pass,pass,pass +paramspec_decorator,pass,pass,pass,fail(m0,x1),pass,pass +recursive_aliases,pass,pass,pass,fail(m0,x3),pass,pass +recursive_bases,hang,pass,pass,pass,pass,pass +tuple_index,fail(m1,x0),pass,pass,pass,pass,pass +typeis_narrowing,pass,pass,pass,fail(m0,x3),pass,pass +passed,5/8,7/8,8/8,4/8,8/8,7/8 diff --git a/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs b/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs index cdfa2093..25aa13d8 100644 --- a/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs +++ b/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs @@ -17,3 +17,72 @@ IntList: TypeAlias = list[int] ); Ok(()) } + +/// PEP 695 `type`-statement counterparts of every recursive alias DEFINITION +/// in upstream `conformance/tests/aliases_recursive.py` — the upstream file +/// contains zero `type` statements, so this syntax gap survived a 100% +/// conformance score ([#371](https://github.com/Nimblesite/Basilisk/issues/371), +/// plan box in docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md Stage 0.5). +/// PEP 695 formally mandates that recursive aliases work: none of these may +/// draw a circularity diagnostic from any rule. Value-level assignability +/// through these aliases lands with [TYPEINF-ANNOTATION-RESOLUTION]. +#[test] +fn upstream_recursive_definitions_as_type_statements_are_clean( +) -> Result<(), Box> { + let cases = [ + // Json / Json2 (the equivalent pair, upstream lines 14/24). + "type Json = None | int | str | float | list[Json] | dict[str, Json]\n\ + type Json2 = None | int | str | float | list[Json2] | dict[str, Json2]\n", + // RecursiveTuple (upstream line 30). + "type RecursiveTuple = str | int | tuple[RecursiveTuple, ...]\n", + // RecursiveMapping (upstream line 42) — a Named constructor guards. + "from typing import Mapping\n\ + type RecursiveMapping = str | int | Mapping[str, RecursiveMapping]\n", + // GenericTypeAlias1 + its specialization (upstream lines 58-59); the + // old-style constrained TypeVar becomes a PEP 695 constrained param. + "type GenericTypeAlias1[T1: (str, int)] = list[GenericTypeAlias1[T1] | T1]\n\ + type SpecializedTypeAlias1 = GenericTypeAlias1[str]\n", + // GenericTypeAlias2 (upstream line 65). + "type GenericTypeAlias2[T1: (str, int), T2] = list[GenericTypeAlias2[T1, T2] | T1 | T2]\n", + ]; + for source in cases { + let diags = run(source)?; + for rule in ["aliases_recursive", "generics_syntax_scoping"] { + assert!( + !codes(&diags).contains(&rule), + "recursive `type` alias definition must not fire {rule}.\n\ + source:\n{source}\ngot: {:?}", + messages_for(&diags, rule) + ); + } + } + Ok(()) +} + +/// The upstream file's two `# E: cyclical reference` cases, as `type` +/// statements: a self-reference in a union arm never reaches a constructor +/// head, and a bare mutual pair is the same non-termination split across two +/// names. Both must still be rejected in the PEP 695 spelling — including +/// through the transparent `Union[..]` operator. +#[test] +fn upstream_cyclical_cases_as_type_statements_still_fire( +) -> Result<(), Box> { + let cases = [ + // RecursiveUnion (upstream line 72), `|` and Union[..] spellings. + "type RecursiveUnion = RecursiveUnion | int\n", + "from typing import Union\ntype RecursiveUnion = Union[RecursiveUnion, int]\n", + // MutualReference1 / MutualReference2 (upstream line 75). + "type MutualReference1 = MutualReference2 | int\n\ + type MutualReference2 = MutualReference1 | str\n", + ]; + for source in cases { + let diags = run(source)?; + assert!( + codes(&diags).contains(&"generics_syntax_scoping"), + "cyclical `type` alias must fire generics_syntax_scoping.\n\ + source:\n{source}\ngot: {:?}", + codes(&diags) + ); + } + Ok(()) +} diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index d3b87c56..0b9dd6ca 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -495,14 +495,27 @@ the conformance ratchets (100% / 0 false positives) at every step. - [ ] Replace the blanket `Named` skip in `rules/shared.rs::is_unverifiable_return_type` with a resolved/unresolved split, narrowing it one category at a time as the cascade covers that category. -- [ ] Terminating cycle detection for recursive aliases: `type J = list[J]`, +- [x] Terminating cycle detection for recursive aliases: `type J = list[J]`, `type J = int | list[J]`, `type J = dict[str, J]`, and the canonical `JsonValue` union all produce **no** diagnostic ([#371](https://github.com/Nimblesite/Basilisk/issues/371)). -- [ ] Add PEP 695 `type`-statement counterparts of every recursive case in + — Delivered by the Stage 3 acceptance conditions: `tyeval::accept::classify` + admits guarded recursion (constructor subscripts guard; union arms alone do + not), and `generics_syntax_scoping::check_type_alias_circular` reports only + `Unguarded`/`NonRegular` verdicts. All four #371 forms (plus a JsonValue + arm-order permutation) are pinned clean in + `tests/checker/generics_syntax_scoping_tests.rs`. +- [x] Add PEP 695 `type`-statement counterparts of every recursive case in upstream `aliases_recursive.py` to our own suite — the upstream file contains zero `type` statements, which is why this false positive survived a 100% score. Coverage of a syntax the upstream suite omits is our responsibility. + — `tests/checker/aliases_recursive_tests.rs`: every recursive alias + DEFINITION (`Json`/`Json2`, `RecursiveTuple`, `RecursiveMapping`, both + generic aliases + specialization) pinned clean as a `type` statement, and + both `# E: cyclical reference` cases (`RecursiveUnion` in `|` and + `Union[..]` spellings, the `MutualReference` pair) pinned firing. + Value-level assignability THROUGH these aliases is the annotation-resolution + cascade's box above, not this one. - [ ] Resolve decorator expressions through the binding table so `o = overload` is recognised as `typing.overload`; cover `from typing import overload as ov` and `typing.overload` / `t.overload` attribute spellings @@ -810,10 +823,32 @@ the conformance ratchets (100% / 0 false positives) at every step. ### Superiority gate +- [x] Seed the scoreboard with a **type-torture corpus**: hard, spec-grounded + problems (several straight from the issue tracker) scored conformance-style + against every competitor, with hang detection as a correctness axis. + — `benchmarks/torture/`: eight cases (`cases/*.py`, each header citing the + typing-spec section/PEP that makes its expectations authoritative — #371 + recursive aliases, #398 recursive-base termination, #374 enum literal + expansion, #317 gradual unannotated code, #284 tuple indexing, PEP 742 + `TypeIs`, PEP 612 `ParamSpec` preservation, generic constructor solving) + + `run_torture.py` (out-of-the-box defaults for every tool, best-effort + latest-release pull, per-invocation timeout scored as `hang`, WRITE-ALWAYS + `status/torture.csv` after every case, read-only regression gate against + the committed baseline, exit 3). First measured run (2026-08-04, versions + in the CSV header): **basilisk 5/8 — behind mypy 8/8, pyrefly 8/8, + pyright 7/8, zuban 7/8; ahead of ty 4/8.** The three basilisk failures are + live defects, now pinned by the corpus: the #374 enum-expansion false + positive, the #398 recursive-base hang, and a module-level fixed-tuple + out-of-range index MISS (the function-scope twin of #284's false + positive). Taking this axis means fixing those three; the gate then holds + them fixed. - [ ] Build the inference scoreboard harness mirroring `benchmarks/`: pull the latest official release of each competitor (pyright, mypy, ty, pyrefly, zuban) every run; write scores to a status file immediately and unconditionally; gate read-only against the committed baseline. + (The torture runner above implements the full write-always/gate/pull + contract for its own corpus; this box widens the same mechanism to the + five measurable-target axes.) - [ ] Build the reveal_type-precision corpus (containers/comprehensions/lambdas/literal-generic precision) and score all checkers on it. From e71384f8d77ada980bf21b109c65a28fd54fab11 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 17:19:14 +1000 Subject: [PATCH 07/45] Fixes --- .gitignore | 3 + CLAUDE.md | 181 +++++------- Makefile | 14 +- README-pypi.md | 4 +- README.md | 4 +- README.zh.md | 4 +- basilisk-zed/README.md | 26 +- basilisk-zed/README.zh.md | 26 +- basilisk-zed/extension.toml | 14 +- basilisk-zed/languages/python/brackets.scm | 4 - basilisk-zed/languages/python/config.toml | 8 - basilisk-zed/languages/python/highlights.scm | 140 --------- basilisk-zed/languages/python/indents.scm | 36 --- basilisk-zed/languages/python/injections.scm | 18 -- basilisk-zed/languages/python/outline.scm | 29 -- basilisk-zed/languages/python/runnables.scm | 26 -- basilisk-zed/languages/python/textobjects.scm | 16 - benchmarks/torture/results/summary.md | 15 +- benchmarks/torture/status/torture.csv | 8 +- .../assignment_compatibility/enum_expand.rs | 84 ++++++ .../src/rules/assignment_compatibility/mod.rs | 145 +-------- .../assignment_compatibility/skip_names.rs | 165 +++++++++++ crates/basilisk-checker/src/rules/guards.rs | 7 +- .../src/rules/names_undefined.rs | 81 ++++- crates/basilisk-checker/src/rules/shared.rs | 279 +----------------- .../src/rules/shared/class_walks.rs | 92 ++++++ .../src/rules/shared/text_scan.rs | 151 ++++++++++ crates/basilisk-checker/src/tyeval/accept.rs | 22 +- crates/basilisk-checker/src/tyeval/eval.rs | 12 +- .../basilisk-checker/src/tyeval/eval/tests.rs | 10 +- crates/basilisk-checker/src/tyeval/lower.rs | 36 ++- .../tests/checker/aliases_recursive_tests.rs | 4 +- .../checker/aliases_type_statement_tests.rs | 36 +-- .../checker/assignment_compatibility_tests.rs | 72 +++++ .../checker/generics_syntax_scoping_tests.rs | 4 +- .../tests/checker/names_undefined_tests.rs | 59 +++- .../tests/checker/tuples_index_tests.rs | 85 +++++- .../tests/torture_golden_tests.rs | 126 ++++++++ .../tests/tyeval_salsa_tests.rs | 5 +- .../src/scope/typeddict_meta.rs | 44 +-- .../src/visitor/annotated_tuple_index.rs | 190 ++++++++++++ .../src/visitor/key_lambda.rs | 12 +- crates/basilisk-resolver/src/visitor/mod.rs | 11 +- .../tests/resolver/test_deep_base_chains.rs | 73 +++++ .../tests/typeddict_tests.rs | 3 + .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 20 +- docs/plans/ROADMAP-NEXT-STEPS-PLAN.md | 31 +- docs/readme/README.src.md | 4 +- docs/readme/README.zh.src.md | 4 +- docs/specs/CHECKER-ARCHITECTURE-SPEC.md | 4 +- docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md | 9 +- docs/specs/ZED-SPEC.md | 38 +-- scripts/render-zed-mirror.sh | 4 +- vscode-extension/README.md | 4 +- vscode-extension/README.zh.md | 4 +- website/src/_data/conformance_report.json | 8 +- website/src/_data/rules.json | 18 +- website/src/docs/install-zed.md | 21 +- website/src/zh/docs/install-zed.md | 21 +- 59 files changed, 1586 insertions(+), 988 deletions(-) delete mode 100644 basilisk-zed/languages/python/brackets.scm delete mode 100644 basilisk-zed/languages/python/config.toml delete mode 100644 basilisk-zed/languages/python/highlights.scm delete mode 100644 basilisk-zed/languages/python/indents.scm delete mode 100644 basilisk-zed/languages/python/injections.scm delete mode 100644 basilisk-zed/languages/python/outline.scm delete mode 100644 basilisk-zed/languages/python/runnables.scm delete mode 100644 basilisk-zed/languages/python/textobjects.scm create mode 100644 crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs create mode 100644 crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs create mode 100644 crates/basilisk-checker/src/rules/shared/class_walks.rs create mode 100644 crates/basilisk-checker/src/rules/shared/text_scan.rs create mode 100644 crates/basilisk-checker/tests/torture_golden_tests.rs create mode 100644 crates/basilisk-resolver/src/visitor/annotated_tuple_index.rs create mode 100644 crates/basilisk-resolver/tests/resolver/test_deep_base_chains.rs diff --git a/.gitignore b/.gitignore index 00515495..c85561fc 100644 --- a/.gitignore +++ b/.gitignore @@ -182,3 +182,6 @@ book/dist/ # without this the residue gets committed and the next run type-checks a file # the suite believes it created fresh. vscode-extension/test-fixtures/workspace/ofo_no_scan_target.py + + +.deslop/ \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 1d0994ab..5a8d6400 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,63 +1,55 @@ # CLAUDE.md -Code here must comfortably pass review at a top-tier engineering org. Keep quality high and fix shortcomings as you find them. +Code here must comfortably pass review at a top-tier engineering org. Fix shortcomings as you find them. -⚠️ The conformance test suite is the **single source of all authority**: https://github.com/python/typing/tree/main/conformance/tests. Conformance is measured ONLY by how accurately Basilisk passes these tests — nothing else. ⚠️ +# Conformance Is the Prime Directive -⚠️ Disabling, deleting, or unregistering ANY conformance rule is FORBIDDEN. Move the number by FIXING the checker, NEVER by touching the scoreboard: no rule-suppressing config file (the legacy `basilisk.json` is no longer even read), no deleting rule source (`crates/basilisk-checker/src/rules/*.rs`), no removing rules from `all_rules()`, no hand-editing `conformance/conformance_status.csv`, no loosening `coverage-thresholds.json` (`threshold` / `max_false_positives`). The score comes from RUNNING the real `python/typing` harness over a FRESH clone whose tree holds no Basilisk config — deleting a rule to dodge that is the SAME crime by another route. See [CHKARCH-CONFORMANCE], [CHKARCH-CONFORMANCE-MODE]. ⚠️ +Target: **100% conformance** with the [Python typing spec](https://typing.python.org/en/latest/spec/index.html), measured ONLY by the [python/typing conformance suite](https://github.com/python/typing/tree/main/conformance/tests) — nothing else. This outranks every other concern in this file. Read the [conformance README](https://github.com/python/typing/blob/main/conformance/README.md) carefully. Python-version boundaries apply only where the typing spec, an accepted PEP, or Python language semantics defines one; Basilisk has no canonical Python release. -⚠️ There is ONE conformance path — the REAL upstream harness, run FRESH every CI run (`conformance/run_conformance.py`). The mechanism, in order, no step skippable: **(1)** freshly `git clone` the tests **and** the harness from `python/typing@main`'s LATEST commit — no cache, no committed fixtures, no vendored calculator; **(2)** freshly build a CLEAN `cargo build --release` basilisk binary from THIS checkout — never the PyPI wheel (a prior version), never an instrumented build; **(3)** run the suite's OWN unmodified `conformance/src/main.py --only-run basilisk` (its `type_checker.py` already ships the official `BasiliskTypeChecker`) against that binary via `BASILISK_BIN` and **fail HARD on ANY false positive or ANY missed required error** (100% / 0 FP); **(4)** regenerate `conformance_status.csv` from the harness's OWN `results/basilisk/*.toml`. **NO** vendored calculator, **NO** reimplemented/injected adapter, **NO** cached fixtures, **NO** committed results substituting for a live run. A build where that official check did not actually run against a freshly-cloned suite is a **BUILD FAILURE** — never re-introduce a home-grown scorer. ⚠️ +⚠️ **Never touch the scoreboard — move the number by FIXING the checker.** FORBIDDEN: disabling/deleting/unregistering any rule, deleting rule source (`crates/basilisk-checker/src/rules/*.rs`), removing rules from `all_rules()`, rule-suppressing config (the legacy `basilisk.json` is no longer read), hand-editing `conformance/conformance_status.csv`, loosening `coverage-thresholds.json` (`threshold` / `max_false_positives`). See [CHKARCH-CONFORMANCE], [CHKARCH-CONFORMANCE-MODE]. ⚠️ -## Conformance Is the Prime Directive +⚠️ **One conformance path**, run fresh every CI run: `python3 conformance/run_conformance.py`. No step skippable — (1) `git clone` the tests **and** the harness from `python/typing@main` HEAD, no cache/committed fixtures; (2) clean `cargo build --release` from THIS checkout, never the PyPI wheel, never instrumented; (3) run the suite's OWN unmodified `conformance/src/main.py --only-run basilisk` (its `type_checker.py` ships the official `BasiliskTypeChecker`) against that binary via `BASILISK_BIN`, failing hard on ANY false positive or missed required error (100% / 0 FP); (4) regenerate `conformance_status.csv` from the harness's own `results/basilisk/*.toml`. A vendored scorer, reimplemented/injected adapter, cached fixtures, or committed results standing in for a live run is a **BUILD FAILURE**. ⚠️ -Target: **100% conformance with the maintained Python typing specification**. -Python-version boundaries apply only where the typing specification, an -accepted PEP, or Python language semantics defines one; Basilisk has no -canonical Python release. Read the [PEP conformance README](https://github.com/python/typing/blob/main/conformance/README.md) -carefully. This discipline outranks every other concern in this file. +- The score is the binary in its default config — every PEP rule on, nothing configured ([CHKARCH-CONFIGURATION-ONLY]). Never quote a number produced any other way. +- **Precision is the whole game.** A file passes iff the upstream `errors_diff` is empty: an error on EVERY `# E` line, EVERY `# E[tag]` group satisfied, NOTHING on an unmarked line. +- **Every failure is a false positive, not a miss.** The checker already catches every required error; files fail because a strict house rule fires on spec-valid code. Fix by teaching the checker to recognise the valid construct — never by missing a required error or silencing a rule ([CHKARCH-CONFORMANCE-MODE]). +- **Ratchets, always.** Pass-% only up, FP ceiling only down (`coverage-thresholds.json`); benchmark times only down ([CHKARCH-TESTING-BENCH-RATCHET]). Moving a ratchet the wrong way means the change isn't done. +- Basilisk is listed in the [official results](https://github.com/python/typing/blob/main/conformance/results/results.html) at 100%. Dropping below is ⛔️ ILLEGAL. -- **One reproducible path — the real harness.** `python3 conformance/run_conformance.py` clones `python/typing@main` FRESH and runs the suite's OWN unmodified harness (`src/main.py --only-run basilisk`) over the binary in its default config — every PEP rule on, nothing configured ([CHKARCH-CONFORMANCE], [CHKARCH-CONFIGURATION-ONLY]). The score is exactly what a user gets out of the box; never quote a number produced any other way, and never re-introduce a home-grown/vendored scorer. -- **Precision is the whole game.** A file passes iff the upstream `errors_diff` is empty: emit an error on EVERY `# E` line, satisfy EVERY `# E[tag]` group, and emit NOTHING on a line the suite does not mark. Follow each PEP exactly — no missed required error, no stray diagnostic. -- **Every failure is a false positive, not a miss.** The checker already catches every required error; files fail because a strict house-rule fires on spec-valid code. Close the gap by making the checker PRECISE — teach it to recognise the valid construct — never by missing a required error or silencing a rule ([CHKARCH-CONFORMANCE-MODE]). -- **Ratchets, always.** Pass-% only goes UP and the false-positive ceiling only goes DOWN (`coverage-thresholds.json`: `conformance.threshold`, `conformance.max_false_positives`); benchmark times only go DOWN ([CHKARCH-TESTING-BENCH-RATCHET]). A change that moves any ratchet the wrong way is not done. +# Design Principles -## Design Principles - -We are building a better Python developer experience: one IDE extension for a complete, fast workflow. The LSP drives all functionality — IDE extensions only react to LSP signals (commands, state changes) and NEVER register a command the LSP doesn't advertise. +One IDE extension = a complete, fast Python workflow. The LSP drives all functionality — extensions only react to LSP signals (commands, state changes) and NEVER register a command the LSP doesn't advertise. Basilisk has **no modes** — behaviour is per-rule configuration ([CHKARCH-CONFIGURATION-ONLY]). The default enables every PEP typing-spec rule and nothing else; opinionated house-style rules (require-annotation `BSK-0001/0002/0004`, require-`@override` `BSK-0025`, redundant-annotation `BSK-0050`, explicit-`Any` nudge `BSK-0014`) are opt-in. Every diagnostic must teach — explain why, not just what. -# Documentation Structure - -The spec-ID web is the fabric of this repository and is non-negotiable: +# Documentation Honesty — No Unsubstantiated Claims -- Every spec section has a unique, non-numeric, hierarchically structured ID (`[GROUP-TOPIC]` / `[GROUP-TOPIC-DETAIL]`). -- All code references its spec ID in comments (e.g. `// Implements [LSP-HOVER]`) so `grep [LSP-` walks spec → code → tests in one shot. -- All tests cross-reference both the spec ID and the code. -- Find code, tests, or specs that aren't linked? Fix it — add the missing ID or reference. +Trust is the product. Applies **everywhere** — specs, plans, README, website, marketing, code comments. -- `docs/INDEX.md` — full index of all docs -- `docs/specs/` — specifications (naming: `[COMPONENT]-[FEATURE]-SPEC.md`) -- `docs/plans/` — implementation plans (naming: `[COMPONENT]-[FEATURE]-PLAN.md`) +- **Every empirical or comparative claim about the outside world** (stats, adoption, competitor capability/performance/conformance numbers, market facts, attributed quotes) MUST carry an inline link to the authoritative source that actually makes that claim. Link it or delete it — NEVER invent or approximate. A value that drifts (a competitor's conformance %, a download size) links to its live source, never a frozen figure. +- **Self-measured, reproducible metrics are exempt** (e.g. our conformance score from the unmodified `python/typing` scorer) — but state how they're measured and don't compare them against numbers from a different methodology. -`docs/specs/LSP-ARCHITECTURE-SPEC.md` is the **single source of truth** for all shared LSP/DAP/config/commands. Editor-specific specs point back to it. -# Reference +# Documentation Structure -- [Python type system spec](https://typing.python.org/en/latest/spec/index.html) -- [Pyrefly](https://pyrefly.org/en/docs/) | [Pyright](https://microsoft.github.io/pyright/#/) — reference implementations to compare against; NEVER copy from their code. -- [Conformance results](https://github.com/python/typing/blob/main/conformance/results/results.html) — Basilisk is listed here with a score of 100%. Dropping below 100% is ⛔️ ILLEGAL +The spec-ID web is the fabric of this repository and is non-negotiable: -Refer to the Makefile for build scripts +- Every spec section has a unique, non-numeric, hierarchical ID (`[GROUP-TOPIC]` / `[GROUP-TOPIC-DETAIL]`). +- Code references its spec ID in comments (e.g. `// Implements [LSP-HOVER]`) so `grep [LSP-` walks spec → code → tests in one shot. Tests cross-reference both the spec ID and the code. +- Find code, tests, or specs that aren't linked? Add the missing ID or reference. +- `docs/INDEX.md` — full index. `docs/specs/[COMPONENT]-[FEATURE]-SPEC.md`, `docs/plans/[COMPONENT]-[FEATURE]-PLAN.md`. +- `docs/specs/LSP-ARCHITECTURE-SPEC.md` is the **single source of truth** for all shared LSP/DAP/config/commands; editor-specific specs point back to it. # Rules -- **Top priority: reduce duplication.** Run `deslop:find-similar` BEFORE writing new code and `deslop:top-offenders` after changing code. Always merge duplicates and keep it DRY. +Build scripts live in the Makefile. [Pyrefly](https://pyrefly.org/en/docs/) and [Pyright](https://microsoft.github.io/pyright/#/) are reference implementations to compare against — NEVER copy from their code. + +- **Top priority: reduce duplication.** Run `deslop:find-similar` BEFORE writing new code and `deslop:top-offenders` after changing code. Merge duplicates; keep it DRY. - Aggressively hoist shared code into shared crates/modules/packages. Use [lspkit](https://crates.io/crates/lspkit) where possible. -- Centralize all global state: each app has a single global-state file, and NO state lives outside it. All mutable state uses Signals for reactivity — no stale state on screen. -- Keep dependencies and versions in sync across `.github/workflows/ci.yml` and `.devcontainer/Dockerfile` at all times. -- Use [typeDiagram markup](https://typediagram.dev/docs/language-reference.html) to define models in the specs. Generate the ADTs using the [typeDiagram code generator](https://typediagram.dev/docs/cli.html) pointing at the markup. +- Centralize all global state: one global-state file per app, no state outside it. All mutable state uses Signals — no stale state on screen. +- Keep dependency versions in sync across `.github/workflows/ci.yml` and `.devcontainer/Dockerfile`. +- Define spec models in [typeDiagram markup](https://typediagram.dev/docs/language-reference.html); generate ADTs with the [typeDiagram code generator](https://typediagram.dev/docs/cli.html) pointed at the markup. - Don't use Git unless asked. - Treat legacy code as code to be removed — there is no legacy code in this codebase. - Avoid regex to parse anything, use ruff. @@ -66,125 +58,84 @@ Refer to the Makefile for build scripts - NEVER kill a VS Code process (including in the browser) — it disrupts active debugging and test sessions. - Bug Fix Process: [fix bug skill](.claude/skills/fix-bug/SKILL.md) -## Documentation Honesty — No Unsubstantiated Claims - -Trust is the product; a fabricated or contradictory figure destroys it. This applies **everywhere** — specs, plans, README, website, marketing, and code comments. - -- **Every empirical or comparative claim about the outside world** (stats, adoption, competitor capability/performance/conformance numbers, market facts, attributed quotes) MUST carry an inline link to the authoritative source that actually makes that claim. Link the URL or delete the claim — NEVER invent or approximate one. A value that drifts (a competitor's pinned conformance %, a download size) links to its live source, never a frozen figure. - -- **Self-measured, reproducible metrics are exempt** (e.g. our own conformance score from the unmodified `python/typing` scorer in CI) — but state how they're measured and don't compare them against numbers from a different methodology. - ## Git & Branch Discipline -Git is off-limits unless you are explicitly asked. When git IS used: +Git is off-limits unless explicitly asked. When git IS used: -- **NEVER push to `main` directly.** Every change ships via PR → CI green → merge. No exceptions. +- **NEVER push to `main` directly.** Every change ships via PR → CI green → merge. - **NEVER list the agent as a commit co-author** — no `Co-Authored-By` trailer, no agent attribution. -- **Work on exactly ONE branch.** Reuse the existing feature branch; never open a second. If multiple feature branches exist, merge them into one immediately before any other work. +- **Work on exactly ONE branch.** Reuse the existing feature branch; if multiple exist, merge them into one before any other work. - **Worktrees are forbidden** — never run `git worktree`. -- **NEVER close anything you did not open** — no issue, PR, discussion, or review thread, however stale or fixed. This includes auto-close keywords: write `Refs #123`, never `Closes/Fixes #123`. +- **NEVER close anything you did not open** — no issue, PR, discussion, or review thread, however stale. Including auto-close keywords: write `Refs #123`, never `Closes/Fixes #123`. ## Testing -- We aim for 100% test coverage on every measure. Each PR MUST INCREASE the overall test coverage or it is considered a failure +- Target 100% coverage on every measure. Each PR MUST INCREASE overall coverage or it is a failure. - NEVER delete a failing test, remove a failure-causing assertion, reduce assertiveness, or ignore tests. Broken or missing functionality gets MORE failing tests, never fewer. -- Mutation score only increases. Widen scope over time by adding `#[mutation_safe]` tests over more rules/functions. The gate ([CHKARCH-TESTING-MUTATION-RATCHET], baseline `mutation_testing/mutation_scores.json`) fails CI if the viable mutant pool shrinks, caught drops, missed/timeout rise, or kill rate drops. -- `make test` is FAIL-FAST — it stops at the first failure. NEVER use `--no-fail-fast`; it saves CI minutes. -- `make test` always computes and enforces coverage. The threshold lives in `coverage-thresholds.json` at the repo root — not env vars, not GH repo variables, not CI YAML. Below threshold fails the pipeline. Ratchet only. - -### IDE Extension Testing - -VSIX tests must not call `whenCommandReady` or `vscode.commands.getCommands(true)` to check for existence. The core code does that; tests assert the command exists through the UI or, worst case, internal VSIX state. +- Mutation score only increases; widen scope over time by adding `#[mutation_safe]` tests over more rules/functions. The gate ([CHKARCH-TESTING-MUTATION-RATCHET], baseline `mutation_testing/mutation_scores.json`) fails CI if the viable mutant pool shrinks, caught drops, missed/timeout rise, or kill rate drops. +- `make test` is FAIL-FAST — NEVER use `--no-fail-fast`. +- `make test` always computes and enforces coverage. The threshold lives in `coverage-thresholds.json` at the repo root — not env vars, not GH repo variables, not CI YAML. Ratchet only; below threshold fails the pipeline. +- VSIX tests must not call `whenCommandReady` or `vscode.commands.getCommands(true)` to check existence — the core code does that. Assert through the UI or, worst case, internal VSIX state. ## Benchmarks -Performance is a feature: conformance must never be traded for it, nor it for conformance. Both ratchets hold simultaneously ([CHKARCH-TESTING-BENCH-RATCHET]). +Performance is a feature; both the conformance and benchmark ratchets hold simultaneously ([CHKARCH-TESTING-BENCH-RATCHET]). A conformance fix that blows the benchmark gate is NOT done — optimize or restructure it. -- Run `make bench` whenever you touch checker hot paths (resolver visitors, rule `check` loops, new conformance logic). Every run does a full `cargo clean` + fresh `--release` build of basilisk and pulls the LATEST official release of every competitor (pyright, mypy, ty, pyrefly, zuban — officially-recognized checkers only) before timing. -- **WRITE-ALWAYS, GATE-SEPARATELY.** The measured numbers are written to `benchmarks/status/.csv` **immediately and unconditionally** — after every fixture and again at the end (`benchmarks/summarize.py`). The write is NEVER gated: the file must ALWAYS reflect exactly what the build just measured, so a slip is visible the instant it happens. A run that measured a number but didn't record it is a lie. **Separately**, a zero-tolerance read-only gate compares those numbers against the **committed** baseline (read from git, not the working copy) and fails CI if basilisk is slower on any fixture. A regression is recorded in the file AND fails CI — never hidden. -- A conformance fix that blows the benchmark gate is NOT done — optimize or restructure it. -- The benchmark gate cannot be disabled or widened. New machines establish a baseline only after a successful run is committed. (Intention: eventually run this gate in CI — see [CHKARCH-TESTING-BENCH-RATCHET].) +- Run `make bench` whenever you touch checker hot paths (resolver visitors, rule `check` loops, new conformance logic). Every run does `cargo clean` + a fresh `--release` build and pulls the latest official release of each competitor (pyright, mypy, ty, pyrefly, zuban) before timing. +- **Write always.** Measured numbers go to `benchmarks/status/.csv` immediately and unconditionally — after every fixture and again at the end (`benchmarks/summarize.py`). A run that measured a number but didn't record it is a lie. +- **Gate separately.** A zero-tolerance read-only gate compares those numbers against the **committed** baseline (read from git, not the working copy) and fails if basilisk is slower on any fixture. The gate cannot be disabled or widened. New machines establish a baseline only after a successful run is committed. ## Logging Standards -- **Structured logging only.** NEVER `println!`/`eprintln!` for diagnostics — use `tracing` + `tracing-subscriber`. If you can't see what's happening, add more logging. -- **Log at entry/exit of significant operations.** Levels: `error|warn|info|debug|trace`. -- **Structured fields, not string interpolation** — `tracing::info!(user_id = 42, action = "checkout")`, never format strings. -- **VS Code extension:** detailed logs go to a file in the extension's state folder AND to the VS Code Output Channel. -- **NEVER log PII** (names, emails, phone, IPs) or secrets. Log `"key: present"` or a truncated hash, never the value. +- **Structured logging only** — `tracing` + `tracing-subscriber`, never `println!`/`eprintln!` for diagnostics. If you can't see what's happening, add more logging. +- Log at entry/exit of significant operations (`error|warn|info|debug|trace`), with structured fields not interpolation: `tracing::info!(user_id = 42, action = "checkout")`. +- VS Code extension: detailed logs go to a file in the extension's state folder AND to the Output Channel. +- **NEVER log PII** (names, emails, phone, IPs) or secrets — log `"key: present"` or a truncated hash. ## Rust Quality Standards -- Run clippy and fmt routinely; fix violations promptly. All lints at highest strictness (see Cargo.toml `[lints]`). Add lints if in doubt; never remove them. -- `unsafe` code is forbidden (`unsafe_code = "deny"`). -- `unwrap()` is always a violation — use `?` with proper error types. -- No `panic!`, `todo!`, `unimplemented!` — handle every case and return `Result`. - -## Functional Programming Style - -- `Result` and `Option` everywhere; early returns with `?` for clean propagation. -- Expressions over statements — `match`, `if let`, iterator chains. -- Pattern matching over casting or unwrapping. Pure functions; minimize side effects. - -## Code Structure - -- Small, focused functions (<20 lines) with low cognitive complexity (clippy::cognitive_complexity enabled). -- Descriptive variable names (no single letters except in closures). -- Group related functionality into modules. Public APIs must have documentation. +- Run clippy and fmt routinely; fix violations promptly. All lints at highest strictness (Cargo.toml `[lints]`). Add lints if in doubt; never remove them. +- `unsafe` is forbidden (`unsafe_code = "deny"`). `unwrap()` is always a violation — use `?` with proper error types. No `panic!`, `todo!`, `unimplemented!` — handle every case and return `Result`. +- `Result` and `Option` everywhere; early returns with `?`. Expressions over statements (`match`, `if let`, iterator chains). Pattern matching over casting or unwrapping. Pure functions; minimize side effects. +- Small, focused functions (<20 lines) with low cognitive complexity (clippy::cognitive_complexity enabled). Descriptive names (no single letters except in closures). Group related functionality into modules; document public APIs. # Too Many Cooks — Multi-Agent Coordination -Register before starting work. - -- Coordinator: dictate orders through plans and messages, and delegate. -- Others: follow the coordinator's direction and check messages regularly. -- Lock files before editing; don't edit locked files. -- Respond to messages promptly — others may be waiting. +Register before starting work. Coordinator dictates orders through plans and messages and delegates; others follow and check messages regularly. Lock files before editing, never edit locked files, and respond to messages promptly. # Website -## CSS - -- **Minimize CSS classes** — consolidate where possible. -- Name classes after what the element IS, not what section it's in. -- Avoid common LLM-default colors (e.g. purple) — use RNG and color wheels. +- **Minimize CSS classes**; name them after what the element IS, not what section it's in. Avoid LLM-default colors (e.g. purple) — use RNG and color wheels. ## Per-diagnostic error pages (`/errors/BSK-XXXX/`) -Every diagnostic the CLI prints ends with `see: https://www.basilisk-python.dev/errors/BSK-XXXX` (the `docs_url` on each rule's `ErrorCode`). Those pages are **generated for all codes** from the checker source — see `[WEBSITE-ERROR-PAGES]` (`docs/specs/WEBSITE-ERROR-PAGES-SPEC.md`). The single source is `website/src/_data/rules.json`, produced by: +Every diagnostic ends with `see: https://www.basilisk-python.dev/errors/BSK-XXXX` (the `docs_url` on each rule's `ErrorCode`). Pages are generated for all codes from checker source — `[WEBSITE-ERROR-PAGES]` (`docs/specs/WEBSITE-ERROR-PAGES-SPEC.md`). The single source is `website/src/_data/rules.json`: ```bash python3 scripts/gen_rules_reference.py --data # writes website/src/_data/rules.json ``` -It extracts the `//! BSK-XXXX:` summary + doc-comment body (prose and ```python examples) from each `crates/basilisk-checker/src/rules/*.rs`. **After adding or renaming a rule, rerun it** — CI fails otherwise: the website job regenerates and `diff`s `rules.json` (`[WEBSITE-ERROR-PAGES-DRIFT]`), and rule-source edits are classified as website changes so the guard runs. The same data drives the `/docs/rules/` table and counts (no hand-maintained code lists). Pages render via `website/src/errors/error.njk`; a worked-example screenshot appears automatically for any code present in `screenshots/shots.mjs`. - +It extracts the `//! BSK-XXXX:` summary + doc-comment body (prose and ```python examples) from each `crates/basilisk-checker/src/rules/*.rs`. **Rerun it after adding or renaming a rule** — CI regenerates and `diff`s `rules.json` (`[WEBSITE-ERROR-PAGES-DRIFT]`), and rule-source edits count as website changes so the guard runs. The same data drives the `/docs/rules/` table and counts. Pages render via `website/src/errors/error.njk`; a worked-example screenshot appears automatically for any code in `screenshots/shots.mjs`. # Architecture -Strict-by-default Python type checker and comprehensive LSP built in **Rust**. One IDE extension = complete Python dev experience. Users can flick errors down to warnings and incrementally adopt type safety, or just use the LSP for autofixes, formatting, debugging, and profiling. +Strict-by-default Python type checker and comprehensive LSP in **Rust**. Users can flick errors down to warnings and adopt type safety incrementally, or just use the LSP for autofixes, formatting, debugging, and profiling. -- **Parser**: `ruff_python_parser` (MIT, same as Ruff) -- **Incremental**: Salsa framework — sub-10ms incremental checks -- **Formatting**: `ruff_python_formatter` crate embedded in-process ([LSPFMT-ENGINE]); import hygiene reimplemented natively on the Ruff AST ([LSPFMT-IMPORTS]). The `ruff` CLI is NOT a runtime dependency — never spawn it. -- **Concurrency**: Tokio in the LSP server (request multiplexing + `spawn_blocking`); analysis itself is single-threaded on one dedicated large-stack thread ([LSPARCH-ARCH-STACK]) -- **No Pyright/mypy/Node.js** — zero TypeScript or Python runtime +- **Parser**: `ruff_python_parser`. **Incremental**: Salsa — sub-10ms incremental checks. +- **Formatting**: `ruff_python_formatter` embedded in-process ([LSPFMT-ENGINE]); import hygiene reimplemented natively on the Ruff AST ([LSPFMT-IMPORTS]). The `ruff` CLI is NOT a runtime dependency — never spawn it. +- **Concurrency**: Tokio in the LSP server (request multiplexing + `spawn_blocking`); analysis is single-threaded on one dedicated large-stack thread ([LSPARCH-ARCH-STACK]). +- **No Pyright/mypy/Node.js** — zero TypeScript or Python runtime. ## Migration to `lspkit` -The cross-cutting LSP scaffolding in this repo (tower-lsp setup, workspace index, file watcher + debouncer, diagnostics publication, capability builder, config loader) is being distilled into the generic `lspkit-*` workspace, maintained in the private repository [`Nimblesite/lsp_toolkit`](https://github.com/Nimblesite/lsp_toolkit). - -- **New LSP infrastructure work:** prefer `lspkit-*` crates over reinventing it here. -- **Changes to existing scaffolding here:** flag in the PR description if the patch duplicates `lspkit` functionality, and reference the upstream crate. - -Mapping (current → toolkit crate): +Cross-cutting LSP scaffolding here is being distilled into the generic `lspkit-*` workspace in [`Nimblesite/lsp_toolkit`](https://github.com/Nimblesite/lsp_toolkit). Prefer `lspkit-*` crates for new LSP infrastructure; when changing existing scaffolding, flag in the PR description if the patch duplicates `lspkit` and reference the upstream crate. | Current path | Toolkit crate | |---|---| -| `crates/basilisk-lsp/src/server/mod.rs:96` tower-lsp `Server` setup | `lspkit-server` (hand-rolled JSON-RPC + `Dispatcher` + `Capabilities`) — **note:** the toolkit does not depend on `tower-lsp` | -| `crates/basilisk-lsp/src/workspace.rs:39–116` `WorkspaceIndex` + import-graph invalidation | `lspkit-vfs` (`Vfs`, `DocumentUri`, incremental edits) + consumer-side index | -| `crates/basilisk-lsp/src/server/handlers/{navigation,features}.rs` handler split | `lspkit-server::Dispatcher::register` per method name | +| `crates/basilisk-lsp/src/server/mod.rs:96` tower-lsp `Server` setup | `lspkit-server` (hand-rolled JSON-RPC + `Dispatcher` + `Capabilities`; no `tower-lsp` dependency) | +| `crates/basilisk-lsp/src/workspace.rs:39–116` `WorkspaceIndex` + import-graph invalidation | `lspkit-vfs` + consumer-side index | +| `crates/basilisk-lsp/src/server/handlers/{navigation,features}.rs` | `lspkit-server::Dispatcher::register` per method name | | `crates/basilisk-lsp/src/server/init.rs:224–242` diagnostic publication | `lspkit-server::diagnostics::DiagnosticsBus` | -| `crates/basilisk-lsp/src/server/mod.rs:61,64` debounce constants + file-watcher loop | `lspkit-live::watcher::FileWatcher` + `lspkit-live::scheduler::spawn` | -| `crates/basilisk-lsp/src/config.rs:35–100` `WorkspaceConfig` loader | `lspkit-config::load_from_ancestor` (consumer supplies the file name + struct) | -| `crates/basilisk-lsp/tests/lsp/ws_test_common.rs` E2E fixture | (not yet in toolkit; harness crate is a v0.1 follow-up) | +| `crates/basilisk-lsp/src/server/mod.rs:61,64` debounce + file-watcher loop | `lspkit-live::watcher::FileWatcher` + `lspkit-live::scheduler::spawn` | +| `crates/basilisk-lsp/src/config.rs:35–100` `WorkspaceConfig` loader | `lspkit-config::load_from_ancestor` | +| `crates/basilisk-lsp/tests/lsp/ws_test_common.rs` E2E fixture | not yet in toolkit (v0.1 follow-up) | diff --git a/Makefile b/Makefile index e8796338..c1c187ca 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ # Exactly 7 standard targets: build, test, lint, fmt, clean, ci, setup # ============================================================================= -.PHONY: build test lint fmt clean ci setup book mutation-test conformance bench bench-basilisk reinstall-vsix reinstall-vsix-macos reinstall-vsix-prerelease +.PHONY: build test lint fmt clean ci setup book mutation-test conformance bench bench-basilisk reinstall-vsix reinstall-vsix-macos reinstall-vsix-prerelease package-zed # --------------------------------------------------------------------------- # OS Detection @@ -509,8 +509,16 @@ _test_nvim: _test_zed: @bash scripts/test-zed.sh -_package_zed: - @echo -e '\033[1m\033[0;36m▶ Building basilisk CLI for Zed\033[0m' && \ +## package-zed: Build the local Zed dev loop — compile the extension to WASM, +## install the basilisk CLI, then print the `zed: install dev extension` steps. +## Point the dev extension at the locally built binary with +## `BASILISK_PATH=$$(which basilisk)` or `lsp.basilisk.binary.path` +## ([ZED-DIST]); with neither, it downloads the release binary. +package-zed: + @echo -e '\033[1m\033[0;36m▶ Building Zed extension (wasm32-wasip2)\033[0m' && \ + rustup target add wasm32-wasip2 && \ + cargo build --release --target wasm32-wasip2 --manifest-path $(_ZED_DIR)/Cargo.toml && \ + echo -e '\033[1m\033[0;36m▶ Building basilisk CLI for Zed\033[0m' && \ cargo install --path crates/basilisk-cli --force && \ echo "$$(which basilisk) installed" && \ echo "" && \ diff --git a/README-pypi.md b/README-pypi.md index 9d6905ac..21f9494d 100644 --- a/README-pypi.md +++ b/README-pypi.md @@ -29,8 +29,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit 60df123), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/README.md b/README.md index 4e3fd5e5..5538dcc9 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit 60df123), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/README.zh.md b/README.zh.md index 96ac87a6..68382c90 100644 --- a/README.zh.md +++ b/README.zh.md @@ -28,8 +28,8 @@

PEP 一致性 100.0% — 官方 - python/typing - 一致性套件（提交 60df123）141 项测试中通过 141 项， + python/typing + 一致性套件（提交 a2e6356）141 项测试中通过 141 项， 由真实的上游评分器在默认配置下对 wheel 安装的 CLI 评出。 我们以 python/typing@main 为目标，且分数只升不降。

diff --git a/basilisk-zed/README.md b/basilisk-zed/README.md index 3b802c25..2ac6c39d 100644 --- a/basilisk-zed/README.md +++ b/basilisk-zed/README.md @@ -10,24 +10,42 @@ Basilisk is the only Python type checker scoring 100% on the [official `python/t Basilisk in the Zed editor — Python type checking and diagnostics inline

+## Install + +Command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) → **zed: install dev extension** → select this directory (clone [`Nimblesite/basilisk-zed`](https://github.com/Nimblesite/basilisk-zed) first if you do not have the monorepo). Zed compiles the extension to WASM itself — you never pre-build or copy a `.wasm` file. + +**You do not install the Basilisk binary separately.** On first activation the extension downloads the matching binary for your platform from the [GitHub release](https://github.com/Nimblesite/Basilisk/releases), caches it inside Zed's extension directory, and reuses it until a newer release appears. Override it only for development or a system install, via `lsp.basilisk.binary.path` in `settings.json` or the `BASILISK_PATH` environment variable. + +> The extension is not yet listed in the [Zed extension registry](https://github.com/zed-industries/extensions); until that listing lands, the dev-extension flow above is the install path. + +Full instructions, settings, debugging, and the slash-command reference: [basilisk-python.dev/docs/install-zed](https://www.basilisk-python.dev/docs/install-zed/). + ## Role in Basilisk This is the **Zed editor integration**. It is a native Zed extension compiled to WASM that connects the Basilisk language server to Zed, providing real-time diagnostics, hover, go-to-definition, code actions, and debugging via DAP. ## Key concepts -- **WASM extension** — compiled as a `cdylib` crate targeting `wasm32-wasip1`, loaded natively by Zed. +- **WASM extension** — compiled as a `cdylib` crate targeting `wasm32-wasip2`, loaded natively by Zed. - **`zed_extension_api`** — uses Zed's official extension API for language server lifecycle management. - **`basilisk-common`** — shares diagnostic codes and constants with the rest of the Basilisk workspace (also WASM-compatible). -- **Tree-sitter grammars** — provides Python syntax highlighting via tree-sitter. +- **Built-in Python, untouched** — binds to Zed's own Python language by name. The extension ships no `languages/` directory and no grammar, so Zed compiles nothing from source and your highlighting, brackets, indent rules, and runnables stay exactly as Zed ships them. - **DAP debugging** — supports the Debug Adapter Protocol for integrated Python debugging. ## Building +From a monorepo checkout, build the extension and set up the local dev loop: + ```sh make package-zed ``` +Standalone (this repository on its own), the build is exactly the one the release pipeline gates the publish on: + +```sh +cargo build --release --target wasm32-wasip2 +``` + ## Dependencies | Crate | Purpose | @@ -35,10 +53,6 @@ make package-zed | `zed_extension_api` | Zed extension API | | `basilisk-common` | Shared constants and types | -## Status - -Phase 2 — extension structure complete, connecting to the Basilisk LSP. - ## License MIT. diff --git a/basilisk-zed/README.zh.md b/basilisk-zed/README.zh.md index f62f60d3..74a3e54e 100644 --- a/basilisk-zed/README.zh.md +++ b/basilisk-zed/README.zh.md @@ -12,24 +12,42 @@ Basilisk 的 Zed 编辑器扩展 —— 基于 WASM 的 Python 类型检查与 Zed 编辑器中的 Basilisk —— 行内 Python 类型检查与诊断

+## 安装 + +命令面板（`Cmd+Shift+P` / `Ctrl+Shift+P`）→ **zed: install dev extension** → 选择本目录（如果没有 monorepo，请先克隆 [`Nimblesite/basilisk-zed`](https://github.com/Nimblesite/basilisk-zed)）。Zed 会自行把扩展编译为 WASM —— 你无需预先构建或复制 `.wasm` 文件。 + +**你无需单独安装 Basilisk 二进制文件。** 首次激活时，扩展会从 [GitHub Release](https://github.com/Nimblesite/Basilisk/releases) 下载与你的平台匹配的二进制文件，缓存在 Zed 的扩展目录中，并一直复用到出现更新的发行版为止。仅在开发或指向系统安装时才需要覆盖它：在 `settings.json` 中设置 `lsp.basilisk.binary.path`，或设置 `BASILISK_PATH` 环境变量。 + +> 该扩展尚未收录进 [Zed 扩展注册表](https://github.com/zed-industries/extensions)；在收录完成之前，上述开发扩展方式就是安装路径。 + +完整的安装说明、设置项、调试与斜杠命令参考：[basilisk-python.dev/docs/install-zed](https://www.basilisk-python.dev/docs/install-zed/)。 + ## 在 Basilisk 中的角色 这是 **Zed 编辑器集成**。它是一个编译为 WASM 的原生 Zed 扩展，将 Basilisk 语言服务器连接到 Zed，提供实时诊断、悬停提示、跳转到定义、代码操作，以及通过 DAP 实现的调试。 ## 核心概念 -- **WASM 扩展** —— 编译为面向 `wasm32-wasip1` 的 `cdylib` crate，由 Zed 原生加载。 +- **WASM 扩展** —— 编译为面向 `wasm32-wasip2` 的 `cdylib` crate，由 Zed 原生加载。 - **`zed_extension_api`** —— 使用 Zed 官方扩展 API 管理语言服务器生命周期。 - **`basilisk-common`** —— 与 Basilisk 工作区的其余部分共享诊断代码和常量（同样兼容 WASM）。 -- **Tree-sitter 语法** —— 通过 tree-sitter 提供 Python 语法高亮。 +- **不改动内置 Python** —— 按名称绑定到 Zed 自带的 Python 语言。扩展不附带 `languages/` 目录，也不附带语法，因此 Zed 不会从源码编译任何东西，你的语法高亮、括号匹配、缩进规则和可运行项都保持 Zed 出厂时的样子。 - **DAP 调试** —— 支持 Debug Adapter Protocol，实现集成的 Python 调试。 ## 构建 +在 monorepo 检出中，构建扩展并配置本地开发循环： + ```sh make package-zed ``` +独立仓库（仅本仓库）中，构建命令与发布流水线用于放行发布的那一条完全相同： + +```sh +cargo build --release --target wasm32-wasip2 +``` + ## 依赖 | Crate | 用途 | @@ -37,10 +55,6 @@ make package-zed | `zed_extension_api` | Zed 扩展 API | | `basilisk-common` | 共享的常量和类型 | -## 状态 - -第 2 阶段 —— 扩展结构已完成，正在连接到 Basilisk LSP。 - ## 许可证 MIT。 diff --git a/basilisk-zed/extension.toml b/basilisk-zed/extension.toml index 2e762581..e47942a2 100644 --- a/basilisk-zed/extension.toml +++ b/basilisk-zed/extension.toml @@ -8,11 +8,15 @@ authors = ["Basilisk Contributors"] description = "The only Python type checker scoring 100% on the official python/typing conformance suite (https://github.com/python/typing/blob/main/conformance/results/results.html) — and the fastest we've measured. Complete open-source Python dev environment in Rust: type checker, language server, debugger, profiler, plus VS Code, Cursor, Zed & Neovim extensions. Strict by default." repository = "https://github.com/Nimblesite/Basilisk" -# No [grammars.python] block: the language below reuses Zed's built-in -# tree-sitter-python grammar by name, so Zed never compiles a grammar from -# source (which requires downloading the ~400 MB wasi-sdk toolchain). The -# query files in languages/python/ augment the built-in grammar. See -# docs/specs/ZED-SPEC.md [ZED-GRAMMAR]. +# No [grammars.*] and no languages/ directory: Basilisk attaches to Zed's +# BUILT-IN Python language by name. Shipping either would register a second +# language called "Python", and Zed's registry OVERWRITES the existing entry's +# grammar/matcher/loader on a name collision, so the extension's definition +# would silently replace the built-in one (bracket auto-close, f-string and +# docstring pairs, elif/else auto-dedent, shebang detection, `debuggers`, and +# the far richer highlight/runnable queries all lost). Same shape as the other +# Python language-server extensions in the registry (ty, pyrefly, pylsp). +# Implements [ZED-GRAMMAR] and [ZED-TREESITTER] — see docs/specs/ZED-SPEC.md. # LSP wiring: Zed launches `basilisk lsp` for Python. Implements [ZED-LSP]. [language_servers.basilisk] diff --git a/basilisk-zed/languages/python/brackets.scm b/basilisk-zed/languages/python/brackets.scm deleted file mode 100644 index 52fb5d6f..00000000 --- a/basilisk-zed/languages/python/brackets.scm +++ /dev/null @@ -1,4 +0,0 @@ -; Bracket matching. Implements [ZED-TREESITTER]. -("(" @open ")" @close) -("[" @open "]" @close) -("{" @open "}" @close) diff --git a/basilisk-zed/languages/python/config.toml b/basilisk-zed/languages/python/config.toml deleted file mode 100644 index 9cd98ae2..00000000 --- a/basilisk-zed/languages/python/config.toml +++ /dev/null @@ -1,8 +0,0 @@ -# Reuses Zed's built-in tree-sitter-python grammar by name (no compile from -# source). Implements [ZED-GRAMMAR]; query files augment it ([ZED-TREESITTER]). -name = "Python" -grammar = "python" -path_suffixes = ["py", "pyi", "pyw"] -line_comments = ["# "] -tab_size = 4 -soft_wrap = "preferred_line_length" diff --git a/basilisk-zed/languages/python/highlights.scm b/basilisk-zed/languages/python/highlights.scm deleted file mode 100644 index 3e72fdca..00000000 --- a/basilisk-zed/languages/python/highlights.scm +++ /dev/null @@ -1,140 +0,0 @@ -; Syntax highlighting for Zed's built-in tree-sitter-python grammar. -; Implements [ZED-TREESITTER]. - -; Keywords -[ - "and" "as" "assert" "async" "await" "break" "class" "continue" - "del" "elif" "else" "except" "finally" "for" "from" "global" - "if" "import" "in" "is" "lambda" "nonlocal" "not" "or" "pass" - "raise" "try" "while" "with" "yield" -] @keyword - -"def" @keyword.function -"return" @keyword.return -"match" @keyword -"case" @keyword -"type" @keyword - -; Builtins -((identifier) @function.builtin - (#any-of? @function.builtin - "abs" "all" "any" "bin" "bool" "breakpoint" "bytes" "callable" - "chr" "classmethod" "compile" "complex" "delattr" "dict" "dir" - "divmod" "enumerate" "eval" "exec" "filter" "float" "format" - "frozenset" "getattr" "globals" "hasattr" "hash" "help" "hex" - "id" "input" "int" "isinstance" "issubclass" "iter" "len" - "list" "locals" "map" "max" "memoryview" "min" "next" "object" - "oct" "open" "ord" "pow" "print" "property" "range" "repr" - "reversed" "round" "set" "setattr" "slice" "sorted" - "staticmethod" "str" "sum" "super" "tuple" "type" "vars" "zip")) - -; Type builtins -((identifier) @type.builtin - (#any-of? @type.builtin - "int" "float" "str" "bool" "bytes" "list" "dict" "set" - "tuple" "frozenset" "complex" "range" "bytearray" "memoryview" - "object" "type" "None" "NotImplemented" "Ellipsis")) - -; Exception builtins -((identifier) @type.builtin - (#any-of? @type.builtin - "Exception" "BaseException" "ValueError" "TypeError" "KeyError" - "IndexError" "AttributeError" "ImportError" "RuntimeError" - "StopIteration" "StopAsyncIteration" "OSError" "IOError" - "FileNotFoundError" "PermissionError" "NotImplementedError" - "ZeroDivisionError" "OverflowError" "RecursionError" - "UnicodeDecodeError" "UnicodeEncodeError" "UnicodeError" - "AssertionError" "ArithmeticError" "LookupError" - "EnvironmentError" "SystemExit" "KeyboardInterrupt" - "GeneratorExit" "ConnectionError" "TimeoutError")) - -; Constants -((identifier) @constant - (#match? @constant "^[A-Z][A-Z_0-9]+$")) - -(none) @constant.builtin -[(true) (false)] @boolean -(ellipsis) @constant.builtin - -; Functions -(function_definition name: (identifier) @function) -(call function: (identifier) @function.call) -(call function: (attribute attribute: (identifier) @function.method.call)) - -; Decorators -(decorator "@" @attribute) -(decorator (identifier) @attribute) -(decorator (attribute attribute: (identifier) @attribute)) -(decorator (call function: (identifier) @attribute)) -(decorator (call function: (attribute attribute: (identifier) @attribute))) - -; Parameters -(parameters (identifier) @variable.parameter) -(parameters (typed_parameter (identifier) @variable.parameter)) -(parameters (default_parameter name: (identifier) @variable.parameter)) -(parameters (typed_default_parameter name: (identifier) @variable.parameter)) -(parameters (list_splat_pattern (identifier) @variable.parameter)) -(parameters (dictionary_splat_pattern (identifier) @variable.parameter)) -(keyword_argument name: (identifier) @variable.parameter) - -; Lambda parameters -(lambda_parameters (identifier) @variable.parameter) - -; Types (annotations) -(type (identifier) @type) -(type (attribute attribute: (identifier) @type)) -(type (subscript value: (identifier) @type)) - -; Class definitions -(class_definition name: (identifier) @type) -(class_definition superclasses: (argument_list (identifier) @type)) - -; String literals -(string) @string -(escape_sequence) @string.escape - -; F-string interpolations -(interpolation) @string.special -(interpolation "{" @punctuation.special) -(interpolation "}" @punctuation.special) -(format_expression) @string.special - -; Numeric literals -(integer) @number -(float) @number - -; Comments -(comment) @comment - -; Operators -[ - "+" "-" "*" "**" "/" "//" "%" "@" - "<<" ">>" "&" "|" "^" "~" - "<" ">" "<=" ">=" "==" "!=" - "=" "+=" "-=" "*=" "/=" "//=" "%=" "**=" ">>=" "<<=" "&=" "|=" "^=" "@=" - "->" ":" - ":=" -] @operator - -; Walrus operator standalone highlight -(named_expression ":=" @operator) - -; Punctuation -["(" ")" "[" "]" "{" "}"] @punctuation.bracket -["," "." ";" ":"] @punctuation.delimiter - -; Self / cls -((identifier) @variable.builtin - (#any-of? @variable.builtin "self" "cls")) - -; Magic / dunder methods -((identifier) @function.special - (#match? @function.special "^__[a-z]")) - -; Import paths -(import_from_statement module_name: (dotted_name (identifier) @namespace)) -(import_statement name: (dotted_name (identifier) @namespace)) -(aliased_import alias: (identifier) @namespace) - -; Variables (catch-all — last so specific captures take priority) -(identifier) @variable diff --git a/basilisk-zed/languages/python/indents.scm b/basilisk-zed/languages/python/indents.scm deleted file mode 100644 index 81efd730..00000000 --- a/basilisk-zed/languages/python/indents.scm +++ /dev/null @@ -1,36 +0,0 @@ -; Python indentation rules. Implements [ZED-TREESITTER]. - -; Blocks that increase indentation -[ - (if_statement) - (elif_clause) - (else_clause) - (for_statement) - (while_statement) - (with_statement) - (try_statement) - (except_clause) - (finally_clause) - (function_definition) - (class_definition) - (match_statement) - (case_clause) -] @indent - -; Brackets also indent -(parenthesized_expression) @indent -(list) @indent -(dictionary) @indent -(set) @indent -(tuple) @indent -(argument_list) @indent -(parameters) @indent - -; Dedent after return/break/continue/pass/raise -[ - (return_statement) - (break_statement) - (continue_statement) - (pass_statement) - (raise_statement) -] @dedent diff --git a/basilisk-zed/languages/python/injections.scm b/basilisk-zed/languages/python/injections.scm deleted file mode 100644 index 9635086f..00000000 --- a/basilisk-zed/languages/python/injections.scm +++ /dev/null @@ -1,18 +0,0 @@ -; Language injections (SQL in strings, regex patterns). Implements [ZED-TREESITTER]. - -; SQL in string literals (heuristic: strings starting with SELECT, INSERT, etc.) -((string - (string_content) @injection.content) - (#match? @injection.content "^\\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\\b") - (#set! injection.language "sql")) - -; Regex patterns in re.compile() and re.match() etc. -(call - function: (attribute - object: (identifier) @_re - attribute: (identifier) @_method) - arguments: (argument_list - (string (string_content) @injection.content)) - (#eq? @_re "re") - (#any-of? @_method "compile" "match" "search" "findall" "finditer" "sub" "subn" "fullmatch" "split") - (#set! injection.language "regex")) diff --git a/basilisk-zed/languages/python/outline.scm b/basilisk-zed/languages/python/outline.scm deleted file mode 100644 index e0a60f4d..00000000 --- a/basilisk-zed/languages/python/outline.scm +++ /dev/null @@ -1,29 +0,0 @@ -; Outline panel symbols (functions, classes, methods). Implements [ZED-TREESITTER]. - -; Top-level functions -(function_definition - name: (identifier) @name) @item - -; Top-level async functions -(function_definition - "async" - name: (identifier) @name) @item - -; Classes -(class_definition - name: (identifier) @name) @item - -; Methods inside classes -(class_definition - body: (block - (function_definition - name: (identifier) @name) @item)) - -; Decorated definitions -(decorated_definition - (function_definition - name: (identifier) @name)) @item - -(decorated_definition - (class_definition - name: (identifier) @name)) @item diff --git a/basilisk-zed/languages/python/runnables.scm b/basilisk-zed/languages/python/runnables.scm deleted file mode 100644 index aa461693..00000000 --- a/basilisk-zed/languages/python/runnables.scm +++ /dev/null @@ -1,26 +0,0 @@ -; Run buttons for entry points and pytest functions. Implements [ZED-TREESITTER]. - -; if __name__ == "__main__": — script entry point -(if_statement - condition: (comparison_operator - (identifier) @_name - (string) @_main) - (#eq? @_name "__name__") - (#eq? @_main "\"__main__\"")) @run - -; pytest test functions (def test_*) -(function_definition - name: (identifier) @_test_name - (#match? @_test_name "^test_")) @run - -; pytest test classes (class Test*) -(class_definition - name: (identifier) @_test_class - (#match? @_test_class "^Test")) @run - -; unittest test methods -(class_definition - body: (block - (function_definition - name: (identifier) @_test_method - (#match? @_test_method "^test_")) @run)) diff --git a/basilisk-zed/languages/python/textobjects.scm b/basilisk-zed/languages/python/textobjects.scm deleted file mode 100644 index 2b87b801..00000000 --- a/basilisk-zed/languages/python/textobjects.scm +++ /dev/null @@ -1,16 +0,0 @@ -; Vim text objects (functions, classes, arguments, comments). Implements [ZED-TREESITTER]. - -; Function text objects -(function_definition) @function.around -(function_definition body: (block) @function.inside) - -; Class text objects -(class_definition) @class.around -(class_definition body: (block) @class.inside) - -; Comment text objects -(comment) @comment.around - -; Parameter / argument text objects -(parameters (_) @parameter.inside) @parameter.around -(argument_list (_) @parameter.inside) @parameter.around diff --git a/benchmarks/torture/results/summary.md b/benchmarks/torture/results/summary.md index 9af9db3f..0651c955 100644 --- a/benchmarks/torture/results/summary.md +++ b/benchmarks/torture/results/summary.md @@ -6,20 +6,19 @@ section or PEP that makes its expectations authoritative. | case | basilisk | pyright | mypy | ty | pyrefly | zuban | |---|---|---|---|---|---|---| -| enum_literal_expansion | fail(m0,x1) | fail(m0,x3) | pass | pass | pass | fail(m0,x2) | +| enum_literal_expansion | pass | fail(m0,x3) | pass | pass | pass | fail(m0,x2) | | generic_constructor | pass | pass | pass | fail(m0,x2) | pass | pass | | param_inference | pass | pass | pass | pass | pass | pass | | paramspec_decorator | pass | pass | pass | fail(m0,x1) | pass | pass | | recursive_aliases | pass | pass | pass | fail(m0,x3) | pass | pass | -| recursive_bases | hang | pass | pass | pass | pass | pass | -| tuple_index | fail(m1,x0) | pass | pass | pass | pass | pass | +| recursive_bases | pass | pass | pass | pass | pass | pass | +| tuple_index | pass | pass | pass | pass | pass | pass | | typeis_narrowing | pass | pass | pass | fail(m0,x3) | pass | pass | -| **passed** | 5/8 | 7/8 | 8/8 | 4/8 | 8/8 | 7/8 | +| **passed** | 8/8 | 7/8 | 8/8 | 4/8 | 8/8 | 7/8 | Versions measured: basilisk basilisk 0.0.0-PLACEHOLDER; pyright pyright 1.1.408; mypy mypy 1.19.1 (compiled: yes); ty ty 0.0.19 (ae10022c2 2026-02-26); pyrefly pyrefly 0.54.0; zuban zuban 0.9.0 ## enum_literal_expansion -- basilisk: missed error lines [], false positives on [20] - pyright: missed error lines [], false positives on [20, 21, 23] - zuban: missed error lines [], false positives on [20, 21] @@ -32,12 +31,6 @@ Versions measured: basilisk basilisk 0.0.0-PLACEHOLDER; pyright pyright 1.1.408; ## recursive_aliases - ty: missed error lines [], false positives on [11, 12, 13] -## recursive_bases -- basilisk: hang - -## tuple_index -- basilisk: missed error lines [15], false positives on [] - ## typeis_narrowing - ty: missed error lines [], false positives on [11, 20, 22] diff --git a/benchmarks/torture/status/torture.csv b/benchmarks/torture/status/torture.csv index 8b55e771..a177ed9c 100644 --- a/benchmarks/torture/status/torture.csv +++ b/benchmarks/torture/status/torture.csv @@ -11,12 +11,12 @@ # pyrefly: pyrefly 0.54.0 # zuban: zuban 0.9.0 case,basilisk,pyright,mypy,ty,pyrefly,zuban -enum_literal_expansion,fail(m0,x1),fail(m0,x3),pass,pass,pass,fail(m0,x2) +enum_literal_expansion,pass,fail(m0,x3),pass,pass,pass,fail(m0,x2) generic_constructor,pass,pass,pass,fail(m0,x2),pass,pass param_inference,pass,pass,pass,pass,pass,pass paramspec_decorator,pass,pass,pass,fail(m0,x1),pass,pass recursive_aliases,pass,pass,pass,fail(m0,x3),pass,pass -recursive_bases,hang,pass,pass,pass,pass,pass -tuple_index,fail(m1,x0),pass,pass,pass,pass,pass +recursive_bases,pass,pass,pass,pass,pass,pass +tuple_index,pass,pass,pass,pass,pass,pass typeis_narrowing,pass,pass,pass,fail(m0,x3),pass,pass -passed,5/8,7/8,8/8,4/8,8/8,7/8 +passed,8/8,7/8,8/8,4/8,8/8,7/8 diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs new file mode 100644 index 00000000..767bda15 --- /dev/null +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs @@ -0,0 +1,84 @@ +//! Implements the enum literal expansion equivalence of +//! [TYPEINF-SUBTYPING-UNION]. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-SUBTYPING-UNION +//! +//! An enum type is equivalent to the union of literals of all its members, so +//! `Answer` is assignable to `Literal[Answer.Yes, Answer.No]` exactly when +//! `Yes`/`No` are ALL of `Answer`'s members (GitHub #374). Partial member +//! unions stay errors. + +use std::collections::{HashMap, HashSet}; + +use basilisk_resolver::{AttributeInfo, ResolvedModule}; + +use crate::rules::guards::is_enum_class; +use crate::types::InferredType; + +/// Member names (lowercase) for every enum class in a module, keyed by the +/// lowercase class name — matching the case-folded `InferredType::Named` +/// spellings produced by annotation parsing. +pub(super) type EnumMembers = HashMap>; + +/// Build the [`EnumMembers`] environment for a module. +pub(super) fn collect_enum_member_sets(module: &ResolvedModule) -> EnumMembers { + module + .classes + .iter() + .filter(|class| is_enum_class(class)) + .map(|class| { + let members = class + .attributes + .iter() + .filter(|attr| is_enum_member(attr)) + .map(|attr| attr.name.to_ascii_lowercase()) + .collect(); + (class.name.to_ascii_lowercase(), members) + }) + .collect() +} + +/// A member is an unannotated class-body value assignment that is not a +/// sunder/dunder name and not a `nonmember`/descriptor/lambda value — +/// mirroring the `Enum` metaclass's own member rules. +fn is_enum_member(attr: &AttributeInfo) -> bool { + let sunder_or_dunder = attr.name.starts_with('_') && attr.name.ends_with('_'); + attr.has_value + && !attr.has_annotation + && !attr.rhs_is_nonmember_call + && !attr.rhs_is_lambda + && !attr.rhs_is_descriptor_call + && !sunder_or_dunder +} + +/// Returns `true` when `inferred` is an enum type and `declared` is a literal +/// union naming EVERY member of that enum. +pub(super) fn enum_expansion_assignable( + inferred: &InferredType, + declared: &InferredType, + enums: &EnumMembers, +) -> bool { + let InferredType::Named(enum_name) = inferred else { + return false; + }; + let Some(members) = enums.get(enum_name.as_str()) else { + return false; + }; + if members.is_empty() { + return false; + } + let arms = match declared { + InferredType::Union(arms) => arms.as_slice(), + single => std::slice::from_ref(single), + }; + let prefix = format!("{enum_name}."); + let covered: HashSet<&str> = arms + .iter() + .filter_map(|arm| match arm { + InferredType::Named(name) => name.strip_prefix(prefix.as_str()), + _ => None, + }) + .collect(); + members + .iter() + .all(|member| covered.contains(member.as_str())) +} diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs index b190cdf2..559bf94e 100644 --- a/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs @@ -18,14 +18,19 @@ mod alias_match; mod callable_check; mod dataclass_check; mod default_spec; +mod enum_expand; mod literal_parse; mod protocol_members; mod sig_model; mod sig_subtype; +mod skip_names; mod tuple_check; mod typeddict_struct; mod typeform_check; +use enum_expand::enum_expansion_assignable; +use skip_names::{drop_unchecked_block_diagnostics, SkipNames}; + use crate::span_util::slice_span; use crate::types::InferredType; use basilisk_resolver::{ResolvedModule, RhsKind, Span, VariableInfo}; @@ -58,15 +63,7 @@ impl Rule for AssignmentTypeMismatch { diagnostics: &mut Vec, ) { let empty_params = ParamMaps::default(); - let skip = SkipNames { - typeddict: collect_typeddict_names(module), - typeddict_extra_items: collect_extra_items_typeddict_names(module), - type_alias: collect_type_alias_names(module), - type_alias_type: collect_type_alias_type_names(module), - value_aliases: alias_match::collect_value_aliases(module), - generic_aliases: alias_match::collect_generic_aliases(module), - typeddict_schemas: typeddict_struct::build_typeddict_schemas(module), - }; + let skip = SkipNames::collect(module); let call_index = callable_check::build_index(module); check_vars( &module.module_vars, @@ -87,107 +84,6 @@ impl Rule for AssignmentTypeMismatch { } } -/// Remove E0014 diagnostics inside `if not TYPE_CHECKING:` blocks — that code -/// is explicitly excluded from type checking (PEP 484). -fn drop_unchecked_block_diagnostics(module: &ResolvedModule, diagnostics: &mut Vec) { - use ruff_text_size::Ranged as _; - - let Some(parsed) = crate::rules::shared::parse_module(module) else { - return; - }; - let blocks: Vec<(u32, u32)> = parsed - .ast - .body - .iter() - .filter_map(|stmt| { - let ruff_python_ast::Stmt::If(if_stmt) = stmt else { - return None; - }; - let ruff_python_ast::Expr::UnaryOp(unary) = if_stmt.test.as_ref() else { - return None; - }; - let is_not_type_checking = unary.op == ruff_python_ast::UnaryOp::Not - && matches!( - unary.operand.as_ref(), - ruff_python_ast::Expr::Name(n) if n.id.as_str() == "TYPE_CHECKING" - ); - is_not_type_checking.then(|| { - let range = if_stmt.range(); - (range.start().to_u32(), range.end().to_u32()) - }) - }) - .collect(); - if blocks.is_empty() { - return; - } - diagnostics.retain(|diag| { - diag.code.code != CODE.code - || !blocks - .iter() - .any(|&(start, end)| diag.span.start >= start && diag.span.end <= end) - }); -} - -/// Collect names of `TypedDict` classes defined in this module. -/// -/// `assignment_compatibility` cannot do structural field-level type checking on `TypedDict` -/// subclasses, so dict literal assignments to `TypedDict` annotations are -/// skipped to avoid false positives. -fn collect_typeddict_names(module: &ResolvedModule) -> std::collections::HashSet { - // Recognise transitive TypedDict subclasses (`class Album(NamedDict): ...`), - // not just classes that name `TypedDict` directly. Otherwise E0014 stops - // skipping their dict-literal assignments and false-positives on every valid - // `album: Album = {...}` whose base — not the leaf — is the TypedDict. - let mut names: std::collections::HashSet = - basilisk_resolver::transitive_typeddict_names(&module.classes) - .into_iter() - .map(str::to_ascii_lowercase) - .collect(); - - // Include functional-form TypedDicts: `Name = TypedDict("Name", {...})`. - for td_call in &module.typeddict_calls { - let _ = names.insert(td_call.lhs_name.to_ascii_lowercase()); - } - - names -} - -/// Collect names of PEP 695 type aliases defined in this module (lowercased). -/// -/// E0014 cannot evaluate expanded type alias types, so annotations that -/// reference a type alias are skipped to avoid false positives. -fn collect_type_alias_names(module: &ResolvedModule) -> std::collections::HashSet { - module - .type_statements - .iter() - .map(|ts| ts.name.to_ascii_lowercase()) - .collect() -} - -/// Names that E0014 must skip to avoid false positives. -struct SkipNames { - /// `TypedDict` class names (lowercase). - typeddict: std::collections::HashSet, - /// `TypedDict` classes declaring `extra_items=` (PEP 728, lowercase). - typeddict_extra_items: std::collections::HashSet, - /// PEP 695 type alias names (lowercase). - type_alias: std::collections::HashSet, - /// `TypeAliasType(...)` call LHS names (lowercase). - type_alias_type: std::collections::HashSet, - /// Legacy value aliases — `Name = Union[...]` or a concrete container such - /// as `Name = dict[K, V]` (lowercase → definition), used for alias-expanded - /// value matching. - value_aliases: std::collections::HashMap, - /// Generic (`TypeVar`-parameterised) value aliases such as - /// `G = list["G[T]" | T]`, keyed by lowercase name. Used to validate - /// literal assignments against a specialised recursive alias (`G[str]`). - generic_aliases: std::collections::HashMap, - /// Effective field schemas (class name → fields) for every `TypedDict`, - /// used for PEP 705 structural assignability of `TypedDict`-to-`TypedDict` - /// assignments instead of name equality. - typeddict_schemas: typeddict_struct::TdSchemas, -} - /// Collection literals are checked in the annotation's expected-type context. /// This permits literal widening (`LiteralString` -> `str`, `int` -> `float`) /// and empty-container `Never` without weakening invariance between two @@ -227,34 +123,6 @@ fn literal_collection_assignable( alias_match::alias_assignable(inferred, declared, &ctx, 0) } -/// Collect names defined via `Name = TypeAliasType(...)` (lowercase). -/// -/// E0014 cannot evaluate an expanded `TypeAliasType` alias, so assignments whose -/// declared type references such an alias are skipped to avoid false positives. -fn collect_type_alias_type_names(module: &ResolvedModule) -> std::collections::HashSet { - module - .type_alias_type_calls - .iter() - .map(|call| call.lhs_name.to_ascii_lowercase()) - .collect() -} - -/// Names of `TypedDict` classes declaring `extra_items=` (lowercase). -/// -/// Such `TypedDict`s may be assignable to `dict[str, VT]` (PEP 728), which -/// E0014's name-level comparison cannot evaluate — those assignments are -/// skipped rather than flagged. -fn collect_extra_items_typeddict_names( - module: &ResolvedModule, -) -> std::collections::HashSet { - module - .classes - .iter() - .filter(|cls| cls.class_keywords.iter().any(|kw| kw == "extra_items")) - .map(|cls| cls.name.to_ascii_lowercase()) - .collect() -} - /// Declared parameter annotations for the enclosing function: parsed types /// for assignability checks, and raw annotation texts for structural /// callable-subtyping checks. @@ -421,6 +289,7 @@ fn check_vars( if inferred_type.is_assignable_to(&declared_type) || literal_collection_assignable(var, &inferred_type, &declared_type, skip) + || enum_expansion_assignable(&inferred_type, &declared_type, &skip.enum_members) { None } else if callable_rescue(var, source, annotation_text, params, call_index) { diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs new file mode 100644 index 00000000..8db84164 --- /dev/null +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs @@ -0,0 +1,165 @@ +//! Implements the false-positive skip environment of [TYPEINF-VARS-ANNOTATED]. +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-VARS-ANNOTATED +//! +//! Everything `assignment_compatibility` must NOT flag: name sets whose +//! declared types it cannot evaluate (`TypedDict`s, aliases), the alias/schema +//! environments used by rescue checks, and `if not TYPE_CHECKING:` blocks +//! (PEP 484 excludes them from type checking entirely). + +use basilisk_resolver::ResolvedModule; + +use crate::diagnostic::Diagnostic; +use crate::types::InferredType; + +use super::{alias_match, enum_expand, typeddict_struct, CODE}; + +/// Names that E0014 must skip to avoid false positives. +pub(super) struct SkipNames { + /// `TypedDict` class names (lowercase). + pub(super) typeddict: std::collections::HashSet, + /// `TypedDict` classes declaring `extra_items=` (PEP 728, lowercase). + pub(super) typeddict_extra_items: std::collections::HashSet, + /// PEP 695 type alias names (lowercase). + pub(super) type_alias: std::collections::HashSet, + /// `TypeAliasType(...)` call LHS names (lowercase). + pub(super) type_alias_type: std::collections::HashSet, + /// Legacy value aliases — `Name = Union[...]` or a concrete container such + /// as `Name = dict[K, V]` (lowercase → definition), used for alias-expanded + /// value matching. + pub(super) value_aliases: std::collections::HashMap, + /// Generic (`TypeVar`-parameterised) value aliases such as + /// `G = list["G[T]" | T]`, keyed by lowercase name. Used to validate + /// literal assignments against a specialised recursive alias (`G[str]`). + pub(super) generic_aliases: std::collections::HashMap, + /// Effective field schemas (class name → fields) for every `TypedDict`, + /// used for PEP 705 structural assignability of `TypedDict`-to-`TypedDict` + /// assignments instead of name equality. + pub(super) typeddict_schemas: typeddict_struct::TdSchemas, + /// Enum class name → member names (lowercase), for the enum literal + /// expansion equivalence ([TYPEINF-SUBTYPING-UNION]). + pub(super) enum_members: enum_expand::EnumMembers, +} + +impl SkipNames { + /// Build the full skip environment for a module. + pub(super) fn collect(module: &ResolvedModule) -> Self { + Self { + typeddict: collect_typeddict_names(module), + typeddict_extra_items: collect_extra_items_typeddict_names(module), + type_alias: collect_type_alias_names(module), + type_alias_type: collect_type_alias_type_names(module), + value_aliases: alias_match::collect_value_aliases(module), + generic_aliases: alias_match::collect_generic_aliases(module), + typeddict_schemas: typeddict_struct::build_typeddict_schemas(module), + enum_members: enum_expand::collect_enum_member_sets(module), + } + } +} + +/// Collect names of `TypedDict` classes defined in this module. +/// +/// `assignment_compatibility` cannot do structural field-level type checking on `TypedDict` +/// subclasses, so dict literal assignments to `TypedDict` annotations are +/// skipped to avoid false positives. +fn collect_typeddict_names(module: &ResolvedModule) -> std::collections::HashSet { + // Recognise transitive TypedDict subclasses (`class Album(NamedDict): ...`), + // not just classes that name `TypedDict` directly. Otherwise E0014 stops + // skipping their dict-literal assignments and false-positives on every valid + // `album: Album = {...}` whose base — not the leaf — is the TypedDict. + let mut names: std::collections::HashSet = + basilisk_resolver::transitive_typeddict_names(&module.classes) + .into_iter() + .map(str::to_ascii_lowercase) + .collect(); + + // Include functional-form TypedDicts: `Name = TypedDict("Name", {...})`. + for td_call in &module.typeddict_calls { + let _ = names.insert(td_call.lhs_name.to_ascii_lowercase()); + } + + names +} + +/// Collect names of PEP 695 type aliases defined in this module (lowercased). +/// +/// E0014 cannot evaluate expanded type alias types, so annotations that +/// reference a type alias are skipped to avoid false positives. +fn collect_type_alias_names(module: &ResolvedModule) -> std::collections::HashSet { + module + .type_statements + .iter() + .map(|ts| ts.name.to_ascii_lowercase()) + .collect() +} + +/// Collect names defined via `Name = TypeAliasType(...)` (lowercase). +/// +/// E0014 cannot evaluate an expanded `TypeAliasType` alias, so assignments whose +/// declared type references such an alias are skipped to avoid false positives. +fn collect_type_alias_type_names(module: &ResolvedModule) -> std::collections::HashSet { + module + .type_alias_type_calls + .iter() + .map(|call| call.lhs_name.to_ascii_lowercase()) + .collect() +} + +/// Names of `TypedDict` classes declaring `extra_items=` (lowercase). +/// +/// Such `TypedDict`s may be assignable to `dict[str, VT]` (PEP 728), which +/// E0014's name-level comparison cannot evaluate — those assignments are +/// skipped rather than flagged. +fn collect_extra_items_typeddict_names( + module: &ResolvedModule, +) -> std::collections::HashSet { + module + .classes + .iter() + .filter(|cls| cls.class_keywords.iter().any(|kw| kw == "extra_items")) + .map(|cls| cls.name.to_ascii_lowercase()) + .collect() +} + +/// Remove E0014 diagnostics inside `if not TYPE_CHECKING:` blocks — that code +/// is explicitly excluded from type checking (PEP 484). +pub(super) fn drop_unchecked_block_diagnostics( + module: &ResolvedModule, + diagnostics: &mut Vec, +) { + use ruff_text_size::Ranged as _; + + let Some(parsed) = crate::rules::shared::parse_module(module) else { + return; + }; + let blocks: Vec<(u32, u32)> = parsed + .ast + .body + .iter() + .filter_map(|stmt| { + let ruff_python_ast::Stmt::If(if_stmt) = stmt else { + return None; + }; + let ruff_python_ast::Expr::UnaryOp(unary) = if_stmt.test.as_ref() else { + return None; + }; + let is_not_type_checking = unary.op == ruff_python_ast::UnaryOp::Not + && matches!( + unary.operand.as_ref(), + ruff_python_ast::Expr::Name(n) if n.id.as_str() == "TYPE_CHECKING" + ); + is_not_type_checking.then(|| { + let range = if_stmt.range(); + (range.start().to_u32(), range.end().to_u32()) + }) + }) + .collect(); + if blocks.is_empty() { + return; + } + diagnostics.retain(|diag| { + diag.code.code != CODE.code + || !blocks + .iter() + .any(|&(start, end)| diag.span.start >= start && diag.span.end <= end) + }); +} diff --git a/crates/basilisk-checker/src/rules/guards.rs b/crates/basilisk-checker/src/rules/guards.rs index 33290c28..660a5c33 100644 --- a/crates/basilisk-checker/src/rules/guards.rs +++ b/crates/basilisk-checker/src/rules/guards.rs @@ -55,15 +55,16 @@ pub(crate) fn is_no_type_check(func: &FunctionInfo) -> bool { func.decorators.iter().any(|d| d == "no_type_check") } -/// Returns `true` when a class is an Enum subclass. +/// Returns `true` when a class is an Enum subclass, in either the bare +/// (`class C(Enum)`) or module-qualified (`class C(enum.Enum)`) spelling. /// /// Enum members are unannotated by design — their type is `Literal[EnumClass.member]`, /// synthesised by the Enum metaclass. Firing BSK-0005 on them is a false positive. pub(crate) fn is_enum_class(class: &ClassInfo) -> bool { class.bases.iter().any(|b| { matches!( - b.as_str(), - "Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag" + b.strip_prefix("enum.").unwrap_or(b), + "Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag" | "ReprEnum" ) }) } diff --git a/crates/basilisk-checker/src/rules/names_undefined.rs b/crates/basilisk-checker/src/rules/names_undefined.rs index fe0056ff..ef2df780 100644 --- a/crates/basilisk-checker/src/rules/names_undefined.rs +++ b/crates/basilisk-checker/src/rules/names_undefined.rs @@ -1,5 +1,5 @@ //! Implements [`names_undefined`] from [CHKARCH-DIAG-TYPESAFETY]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-TYPESAFETY -//! `names_undefined`: Undefined variable used in a return statement. +//! `names_undefined`: Reference to a name with no visible definition. //! //! Flags any name referenced in a `return` expression — bare (`return x`), the //! base of an attribute/subscript chain (`return x.y`), a call argument, or the @@ -9,10 +9,19 @@ //! `type` alias, an enclosing scope's binding, a cross-module imported symbol, //! or a builtin. //! +//! Also flags a class that lists **its own name among its bases** when no other +//! binding of that name exists: a class name is not bound until its `class` +//! statement completes, so `class C(C)` with no prior `C` is a guaranteed +//! `NameError` at runtime (GitHub #398). +//! //! ```python //! def compute() -> int: //! return undefined_name # never defined → E0018 //! return undefined_fn() # undefined callee → E0018 +//! +//! +//! class Node(Node): # `Node` is unbound in its own bases → E0018 +//! pass //! ``` use basilisk_resolver::{FunctionInfo, ResolvedModule, Span}; @@ -62,10 +71,10 @@ impl Rule for UndefinedVariable { // Only MODULE-scope aliases are visible to every function body: // class-scope names don't nest, and function-scope aliases are local // (they reach `all_local_assigns`, so same-function use stays clean). - let type_alias_names: Vec<&str> = basilisk_resolver::collect_names_where( - &module.pep695_scoping.aliases, - |alias| !alias.in_function && !alias.in_class, - ); + let type_alias_names: Vec<&str> = + basilisk_resolver::collect_names_where(&module.pep695_scoping.aliases, |alias| { + !alias.in_function && !alias.in_class + }); let scope = ModuleScope { import_names: &import_names, @@ -78,6 +87,68 @@ impl Rule for UndefinedVariable { module.functions.iter().for_each(|func| { check_function(func, &module.functions, &scope, &module.path, diagnostics); }); + + check_class_self_referential_bases(module, &scope, diagnostics); + } +} + +/// Flag classes whose bases name the class itself with no other binding of +/// that name in the module (GitHub #398): the class name is unbound until the +/// `class` statement completes, so the reference is a guaranteed `NameError`. +/// +/// Deliberately conservative — any other binding of the name (a prior class or +/// redefinition, a function, a variable, an import, a `type` alias, a builtin, +/// or a possible `from m import *`) suppresses the diagnostic, because the base +/// would then legally refer to that binding. +fn check_class_self_referential_bases( + module: &ResolvedModule, + scope: &ModuleScope<'_>, + out: &mut Vec, +) { + let star_import = module + .imports + .iter() + .any(|imp| imp.names.iter().any(|n| n == "*")); + if star_import { + return; + } + + for class in &module.classes { + let name = class.name.as_str(); + if !class.bases.iter().any(|base| base == name) { + continue; + } + let other_binding = module.classes.iter().filter(|c| c.name == name).count() > 1 + || BUILTINS.contains(&name) + || scope.import_names.contains(&name) + || scope.module_var_names.contains(&name) + || scope.type_alias_names.contains(&name) + || scope.imported_symbols.contains_key(name) + || module.functions.iter().any(|f| { + f.name == name + || f.parameters.iter().any(|p| p.name == name) + || f.all_local_assigns.iter().any(|a| a == name) + }); + if other_binding { + continue; + } + out.push(error_diagnostic_owned( + CODE.clone(), + format!( + "Class `{name}` lists itself as a base, but `{name}` is not defined until the \ + `class` statement completes" + ), + class.name_span, + &module.path, + Some(format!( + "Remove `{name}` from its own bases list, or derive from the class you meant" + )), + Some( + "A class name is bound only after its body evaluates, so using it in its own \ + bases raises `NameError` at runtime" + .to_owned(), + ), + )); } } diff --git a/crates/basilisk-checker/src/rules/shared.rs b/crates/basilisk-checker/src/rules/shared.rs index fc20a189..99814fd4 100644 --- a/crates/basilisk-checker/src/rules/shared.rs +++ b/crates/basilisk-checker/src/rules/shared.rs @@ -4,12 +4,23 @@ //! Consolidated from duplicated implementations in individual rule modules //! to eliminate code duplication and improve maintainability. -use std::collections::{HashMap, HashSet}; +mod class_walks; +mod text_scan; + +pub(crate) use class_walks::{ + any_base_name_matches, class_name_map, class_or_base_matches, method_name_map, +}; +pub(crate) use text_scan::{ + contains_top_level_comma, identifiers_followed_by, leading_indent, paren_has_top_level_comma, + span_for_line, split_top_level_commas, +}; + +use std::collections::HashSet; use crate::span_util::slice_span; use crate::types::InferredType; use basilisk_parser::ParsedModule; -use basilisk_resolver::{ClassInfo, FunctionInfo, ResolvedModule, Span, TypeVarCallInfo}; +use basilisk_resolver::{ResolvedModule, Span, TypeVarCallInfo}; use ruff_python_ast::{self as ast, Expr}; /// Returns `true` when the annotation text denotes a `ClassVar[...]` type. @@ -27,83 +38,6 @@ pub(crate) fn annotation_is_classvar(source: &str, span: Option) -> bool { || t.contains(".ClassVar[") } -// --------------------------------------------------------------------------- -// Source-text geometry -// --------------------------------------------------------------------------- - -/// Number of leading whitespace bytes on `line`. Identical to what every rule -/// re-implemented as `line.len() - line.trim_start().len()`. -pub(crate) fn leading_indent(line: &str) -> usize { - line.len() - line.trim_start().len() -} - -/// Return the byte offset (as `u32`) of the start of the given 1-based line. -/// If `target_line` is past the end of `source`, returns `source.len()`. -#[expect( - clippy::cast_possible_truncation, - clippy::as_conversions, - reason = "byte offsets fit u32 for source files" -)] -pub(crate) fn line_to_byte_offset(source: &str, target_line: usize) -> u32 { - let mut current = 1usize; - for (byte_idx, ch) in source.char_indices() { - if current == target_line { - return byte_idx as u32; - } - if ch == '\n' { - current += 1; - } - } - source.len() as u32 -} - -/// Returns `true` when `inner` contains a comma at bracket-depth zero. -/// -/// Bracket-depth tracks `[`/`(`/`{` openers and their matching closers. Used -/// by rules that need to decide whether a parenthesised expression like -/// `(a, b)` is a tuple at top level versus a single bracketed group. -pub(crate) fn contains_top_level_comma(inner: &str) -> bool { - let mut depth = 0i32; - for ch in inner.chars() { - match ch { - '[' | '(' | '{' => depth += 1, - ']' | ')' | '}' => depth -= 1, - ',' if depth == 0 => return true, - _ => {} - } - } - false -} - -/// Returns `true` when `s` is a `(...)` parenthesised expression whose -/// contents contain a top-level comma (i.e. a tuple expression). -pub(crate) fn paren_has_top_level_comma(s: &str) -> bool { - if s.len() < 2 || !s.starts_with('(') || !s.ends_with(')') { - return false; - } - contains_top_level_comma(&s[1..s.len() - 1]) -} - -/// Build a `Span` covering the trimmed content of a given 1-based line. -#[expect( - clippy::as_conversions, - clippy::cast_possible_truncation, - reason = "u32<->usize safe on 32-bit+" -)] -pub(crate) fn span_for_line(source: &str, line_number: usize) -> Span { - let start = line_to_byte_offset(source, line_number) as usize; - let line_text = source - .get(start..) - .and_then(|s| s.lines().next()) - .unwrap_or(""); - let trimmed_start = start + (line_text.len() - line_text.trim_start().len()); - let trimmed_end = start + line_text.trim_end().len(); - Span { - start: trimmed_start as u32, - end: trimmed_end as u32, - } -} - // --------------------------------------------------------------------------- // Parsing // --------------------------------------------------------------------------- @@ -119,108 +53,6 @@ pub(crate) fn parse_module(module: &ResolvedModule) -> Option<&ParsedModule> { module.lazy_ast.get_or_parse(&module.source, &module.path) } -// --------------------------------------------------------------------------- -// Class lookup -// --------------------------------------------------------------------------- - -/// Build a `&str -> &ClassInfo` lookup map for every class in the module. -/// -/// The returned map borrows from the slice; both must outlive the map. -pub(crate) fn class_name_map(classes: &[ClassInfo]) -> HashMap<&str, &ClassInfo> { - classes.iter().map(|c| (c.name.as_str(), c)).collect() -} - -// --------------------------------------------------------------------------- -// Cycle-safe transitive base-class walks (GitHub #278) -// --------------------------------------------------------------------------- -// Base names resolve to same-module classes by SIMPLE name, so `class -// Client(httpx.Client)` records the base as `Client` and the by-name lookup -// makes the class its own ancestor. A naive recursive walk then never -// terminates and overflows the stack, aborting the whole process. Every -// transitive base walk must use these helpers or carry its own visited set / -// depth cap. -// -// `resolve` and `matches` receive each base name EXACTLY as recorded -// (subscripts included), so call sites keep their own normalisation and the -// helpers change nothing but termination. - -/// Returns `true` when `predicate` holds for `cls` or for any class in its -/// transitive same-module base chain (bases resolve through `resolve`). -pub(crate) fn class_or_base_matches<'a>( - cls: &'a ClassInfo, - resolve: &dyn Fn(&str) -> Option<&'a ClassInfo>, - predicate: &dyn Fn(&'a ClassInfo) -> bool, -) -> bool { - let mut visited: HashSet<&str> = HashSet::new(); - let _ = visited.insert(cls.name.as_str()); - walk_class_or_base(cls, resolve, predicate, &mut visited) -} - -/// Recursive body of [`class_or_base_matches`]; `visited` breaks base-name -/// cycles. -fn walk_class_or_base<'a>( - cls: &'a ClassInfo, - resolve: &dyn Fn(&str) -> Option<&'a ClassInfo>, - predicate: &dyn Fn(&'a ClassInfo) -> bool, - visited: &mut HashSet<&'a str>, -) -> bool { - if predicate(cls) { - return true; - } - cls.bases.iter().any(|base| { - visited.insert(base.as_str()) - && resolve(base).is_some_and(|b| walk_class_or_base(b, resolve, predicate, visited)) - }) -} - -/// Returns `true` when any base name in the transitive chain of `cls` -/// satisfies `matches`. Each base name is first tested with `matches` and -/// then resolved through `resolve` for the recursive step. -pub(crate) fn any_base_name_matches<'a>( - cls: &'a ClassInfo, - resolve: &dyn Fn(&str) -> Option<&'a ClassInfo>, - matches: &dyn Fn(&str) -> bool, -) -> bool { - let mut visited: HashSet<&str> = HashSet::new(); - let _ = visited.insert(cls.name.as_str()); - walk_base_names(cls, resolve, matches, &mut visited) -} - -/// Recursive body of [`any_base_name_matches`]; `visited` breaks base-name -/// cycles. -fn walk_base_names<'a>( - cls: &'a ClassInfo, - resolve: &dyn Fn(&str) -> Option<&'a ClassInfo>, - matches: &dyn Fn(&str) -> bool, - visited: &mut HashSet<&'a str>, -) -> bool { - cls.bases.iter().any(|base| { - matches(base) - || (visited.insert(base.as_str()) - && resolve(base).is_some_and(|b| walk_base_names(b, resolve, matches, visited))) - }) -} - -/// Build a `(class_name, method_name) -> Vec<&FunctionInfo>` lookup for every -/// method in the module (functions carrying a `class_name`). -/// -/// Multiple definitions sharing a key (e.g. `@overload` signatures plus the -/// implementation) are preserved in declaration order. The returned map borrows -/// from the slice; both must outlive the map. -pub(crate) fn method_name_map( - functions: &[FunctionInfo], -) -> HashMap<(&str, &str), Vec<&FunctionInfo>> { - let mut map: HashMap<(&str, &str), Vec<&FunctionInfo>> = HashMap::new(); - for func in functions { - if let Some(ref class_name) = func.class_name { - map.entry((class_name.as_str(), func.name.as_str())) - .or_default() - .push(func); - } - } - map -} - // --------------------------------------------------------------------------- // TypeVar helpers // --------------------------------------------------------------------------- @@ -236,45 +68,6 @@ pub(crate) fn typevar_tuple_names(typevar_calls: &[TypeVarCallInfo]) -> HashSet< .collect() } -// --------------------------------------------------------------------------- -// String splitting -// --------------------------------------------------------------------------- - -/// Split `s` at every top-level comma, respecting bracket nesting and string -/// literals — a comma inside quotes (`Literal[',']`) is part of the literal -/// value, not a separator (issue #316). -/// -/// Returns slices into the original string (no allocation for the parts -/// themselves). Callers that need trimmed/owned values can chain -/// `.iter().map(|p| p.trim().to_owned())`. -pub(crate) fn split_top_level_commas(s: &str) -> Vec<&str> { - let mut parts = Vec::new(); - let mut depth: usize = 0; - let mut in_string: Option = None; - let mut start = 0; - for (idx, ch) in s.char_indices() { - match in_string { - Some(quote) => { - if ch == quote { - in_string = None; - } - } - None => match ch { - '\'' | '"' => in_string = Some(ch), - '[' | '(' | '{' => depth += 1, - ']' | ')' | '}' => depth = depth.saturating_sub(1), - ',' if depth == 0 => { - parts.push(&s[start..idx]); - start = idx + 1; - } - _ => {} - }, - } - } - parts.push(&s[start..]); - parts -} - // --------------------------------------------------------------------------- // Annotation parsing // --------------------------------------------------------------------------- @@ -383,10 +176,6 @@ pub(crate) fn is_type_compatible(actual: &str, expected: &str) -> bool { false } -// --------------------------------------------------------------------------- -// Identifier / typevar matching -// --------------------------------------------------------------------------- - // --------------------------------------------------------------------------- // Literal helpers // --------------------------------------------------------------------------- @@ -581,45 +370,3 @@ pub(crate) fn is_unverifiable_return_type(ty: &InferredType) -> bool { _ => false, } } - -// --------------------------------------------------------------------------- -// Line tokenisation -// --------------------------------------------------------------------------- - -/// Yield `(identifier, index_after_delimiter)` for every identifier token in -/// `line` that is immediately followed by `delim` (e.g. `[` for subscripts, -/// `(` for calls). -/// -/// Rules that scan source lines for `ClassName[...]` / `ClassName(...)` -/// patterns use this to dispatch each line's tokens through a hash lookup — -/// O(tokens) per line — instead of running a formatted substring search per -/// known class per line, which is O(classes × line length) and dominated -/// whole-file checks on class-heavy modules. -pub(crate) fn identifiers_followed_by( - line: &str, - delim: char, -) -> impl Iterator + '_ { - let mut chars = line.char_indices().peekable(); - std::iter::from_fn(move || { - while let Some((start, ch)) = chars.next() { - if !(ch.is_alphanumeric() || ch == '_') { - continue; - } - let mut end = start + ch.len_utf8(); - while let Some(&(idx, next)) = chars.peek() { - if next.is_alphanumeric() || next == '_' { - let _ = chars.next(); - end = idx + next.len_utf8(); - } else { - break; - } - } - if let Some(&(idx, next)) = chars.peek() { - if next == delim { - return Some((&line[start..end], idx + next.len_utf8())); - } - } - } - None - }) -} diff --git a/crates/basilisk-checker/src/rules/shared/class_walks.rs b/crates/basilisk-checker/src/rules/shared/class_walks.rs new file mode 100644 index 00000000..9c42d40b --- /dev/null +++ b/crates/basilisk-checker/src/rules/shared/class_walks.rs @@ -0,0 +1,92 @@ +//! Implements helpers for [CHKARCH-DIAG]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG +//! Class lookup maps and stack-safe transitive base-class walks (GitHub #278). +//! +//! Base names resolve to same-module classes by SIMPLE name, so `class +//! Client(httpx.Client)` records the base as `Client` and the by-name lookup +//! makes the class its own ancestor. These walks are iterative (explicit +//! worklist, zero recursion) so no chain depth can overflow the stack, and +//! `visited` bounds work to one visit per base name so cycles terminate. +//! Every transitive base walk must use these helpers or carry the same two +//! guards. +//! +//! `resolve` and `matches` receive each base name EXACTLY as recorded +//! (subscripts included), so call sites keep their own normalisation and the +//! helpers change nothing but termination. + +use std::collections::{HashMap, HashSet}; + +use basilisk_resolver::{ClassInfo, FunctionInfo}; + +/// Build a `&str -> &ClassInfo` lookup map for every class in the module. +/// +/// The returned map borrows from the slice; both must outlive the map. +pub(crate) fn class_name_map(classes: &[ClassInfo]) -> HashMap<&str, &ClassInfo> { + classes.iter().map(|c| (c.name.as_str(), c)).collect() +} + +/// Returns `true` when `predicate` holds for `cls` or for any class in its +/// transitive same-module base chain (bases resolve through `resolve`). +pub(crate) fn class_or_base_matches<'a>( + cls: &'a ClassInfo, + resolve: &dyn Fn(&str) -> Option<&'a ClassInfo>, + predicate: &dyn Fn(&'a ClassInfo) -> bool, +) -> bool { + let mut visited: HashSet<&str> = HashSet::new(); + let _ = visited.insert(cls.name.as_str()); + let mut worklist: Vec<&'a ClassInfo> = vec![cls]; + while let Some(current) = worklist.pop() { + if predicate(current) { + return true; + } + for base in ¤t.bases { + if visited.insert(base.as_str()) { + worklist.extend(resolve(base)); + } + } + } + false +} + +/// Returns `true` when any base name in the transitive chain of `cls` +/// satisfies `matches`. Each base name is tested with `matches` and then +/// resolved through `resolve` to continue the walk. +pub(crate) fn any_base_name_matches<'a>( + cls: &'a ClassInfo, + resolve: &dyn Fn(&str) -> Option<&'a ClassInfo>, + matches: &dyn Fn(&str) -> bool, +) -> bool { + let mut visited: HashSet<&str> = HashSet::new(); + let _ = visited.insert(cls.name.as_str()); + let mut worklist: Vec<&'a ClassInfo> = vec![cls]; + while let Some(current) = worklist.pop() { + for base in ¤t.bases { + if matches(base) { + return true; + } + if visited.insert(base.as_str()) { + worklist.extend(resolve(base)); + } + } + } + false +} + +/// Build a `(class_name, method_name) -> Vec<&FunctionInfo>` lookup for every +/// method in the module (functions carrying a `class_name`). +/// +/// Multiple definitions sharing a key (e.g. `@overload` signatures plus the +/// implementation) are preserved in declaration order. The returned map borrows +/// from the slice; both must outlive the map. +pub(crate) fn method_name_map( + functions: &[FunctionInfo], +) -> HashMap<(&str, &str), Vec<&FunctionInfo>> { + let mut map: HashMap<(&str, &str), Vec<&FunctionInfo>> = HashMap::new(); + for func in functions { + if let Some(ref class_name) = func.class_name { + map.entry((class_name.as_str(), func.name.as_str())) + .or_default() + .push(func); + } + } + map +} diff --git a/crates/basilisk-checker/src/rules/shared/text_scan.rs b/crates/basilisk-checker/src/rules/shared/text_scan.rs new file mode 100644 index 00000000..367ca04a --- /dev/null +++ b/crates/basilisk-checker/src/rules/shared/text_scan.rs @@ -0,0 +1,151 @@ +//! Implements helpers for [CHKARCH-DIAG]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG +//! Source-text geometry, top-level splitting, and line tokenisation shared by +//! rules that scan annotation or source text. + +use basilisk_resolver::Span; + +/// Number of leading whitespace bytes on `line`. Identical to what every rule +/// re-implemented as `line.len() - line.trim_start().len()`. +pub(crate) fn leading_indent(line: &str) -> usize { + line.len() - line.trim_start().len() +} + +/// Return the byte offset (as `u32`) of the start of the given 1-based line. +/// If `target_line` is past the end of `source`, returns `source.len()`. +#[expect( + clippy::cast_possible_truncation, + clippy::as_conversions, + reason = "byte offsets fit u32 for source files" +)] +fn line_to_byte_offset(source: &str, target_line: usize) -> u32 { + let mut current = 1usize; + for (byte_idx, ch) in source.char_indices() { + if current == target_line { + return byte_idx as u32; + } + if ch == '\n' { + current += 1; + } + } + source.len() as u32 +} + +/// Returns `true` when `inner` contains a comma at bracket-depth zero. +/// +/// Bracket-depth tracks `[`/`(`/`{` openers and their matching closers. Used +/// by rules that need to decide whether a parenthesised expression like +/// `(a, b)` is a tuple at top level versus a single bracketed group. +pub(crate) fn contains_top_level_comma(inner: &str) -> bool { + let mut depth = 0i32; + for ch in inner.chars() { + match ch { + '[' | '(' | '{' => depth += 1, + ']' | ')' | '}' => depth -= 1, + ',' if depth == 0 => return true, + _ => {} + } + } + false +} + +/// Returns `true` when `s` is a `(...)` parenthesised expression whose +/// contents contain a top-level comma (i.e. a tuple expression). +pub(crate) fn paren_has_top_level_comma(s: &str) -> bool { + if s.len() < 2 || !s.starts_with('(') || !s.ends_with(')') { + return false; + } + contains_top_level_comma(&s[1..s.len() - 1]) +} + +/// Build a `Span` covering the trimmed content of a given 1-based line. +#[expect( + clippy::as_conversions, + clippy::cast_possible_truncation, + reason = "u32<->usize safe on 32-bit+" +)] +pub(crate) fn span_for_line(source: &str, line_number: usize) -> Span { + let start = line_to_byte_offset(source, line_number) as usize; + let line_text = source + .get(start..) + .and_then(|s| s.lines().next()) + .unwrap_or(""); + let trimmed_start = start + (line_text.len() - line_text.trim_start().len()); + let trimmed_end = start + line_text.trim_end().len(); + Span { + start: trimmed_start as u32, + end: trimmed_end as u32, + } +} + +/// Split `s` at every top-level comma, respecting bracket nesting and string +/// literals — a comma inside quotes (`Literal[',']`) is part of the literal +/// value, not a separator (issue #316). +/// +/// Returns slices into the original string (no allocation for the parts +/// themselves). Callers that need trimmed/owned values can chain +/// `.iter().map(|p| p.trim().to_owned())`. +pub(crate) fn split_top_level_commas(s: &str) -> Vec<&str> { + let mut parts = Vec::new(); + let mut depth: usize = 0; + let mut in_string: Option = None; + let mut start = 0; + for (idx, ch) in s.char_indices() { + match in_string { + Some(quote) => { + if ch == quote { + in_string = None; + } + } + None => match ch { + '\'' | '"' => in_string = Some(ch), + '[' | '(' | '{' => depth += 1, + ']' | ')' | '}' => depth = depth.saturating_sub(1), + ',' if depth == 0 => { + parts.push(&s[start..idx]); + start = idx + 1; + } + _ => {} + }, + } + } + parts.push(&s[start..]); + parts +} + +/// Yield `(identifier, index_after_delimiter)` for every identifier token in +/// `line` that is immediately followed by `delim` (e.g. `[` for subscripts, +/// `(` for calls). +/// +/// Rules that scan source lines for `ClassName[...]` / `ClassName(...)` +/// patterns use this to dispatch each line's tokens through a hash lookup — +/// O(tokens) per line — instead of running a formatted substring search per +/// known class per line, which is O(classes × line length) and dominated +/// whole-file checks on class-heavy modules. +pub(crate) fn identifiers_followed_by( + line: &str, + delim: char, +) -> impl Iterator + '_ { + let mut chars = line.char_indices().peekable(); + std::iter::from_fn(move || { + while let Some((start, ch)) = chars.next() { + if !(ch.is_alphanumeric() || ch == '_') { + continue; + } + let mut end = start + ch.len_utf8(); + while let Some(&(idx, next)) = chars.peek() { + if next.is_alphanumeric() || next == '_' { + let _ = chars.next(); + end = idx + next.len_utf8(); + } else { + break; + } + } + if let Some(&(idx, next)) = chars.peek() { + if next == delim { + return Some((&line[start..end], idx + next.len_utf8())); + } + } + } + None + }) +} diff --git a/crates/basilisk-checker/src/tyeval/accept.rs b/crates/basilisk-checker/src/tyeval/accept.rs index f1d05c90..531b0360 100644 --- a/crates/basilisk-checker/src/tyeval/accept.rs +++ b/crates/basilisk-checker/src/tyeval/accept.rs @@ -174,13 +174,20 @@ mod tests { let cases = [ TypeTerm::List(Box::new(self_ref(Vec::new()))), TypeTerm::Union(vec![int(), TypeTerm::List(Box::new(self_ref(Vec::new())))]), - TypeTerm::Dict(Box::new(TypeTerm::Ground(InferredType::Str)), Box::new(self_ref(Vec::new()))), + TypeTerm::Dict( + Box::new(TypeTerm::Ground(InferredType::Str)), + Box::new(self_ref(Vec::new())), + ), TypeTerm::Set(Box::new(self_ref(Vec::new()))), TypeTerm::Tuple(vec![self_ref(Vec::new()), int()]), TypeTerm::Named("Sequence".to_owned(), vec![self_ref(Vec::new())]), ]; for body in cases { - assert_eq!(classify_body(0, body.clone()), Acceptance::Accepted, "{body:?}"); + assert_eq!( + classify_body(0, body.clone()), + Acceptance::Accepted, + "{body:?}" + ); } } @@ -194,7 +201,11 @@ mod tests { TypeTerm::Union(vec![TypeTerm::Param(0), self_ref(vec![int()])]), ]; for body in cases { - assert_eq!(classify_body(1, body.clone()), Acceptance::Unguarded, "{body:?}"); + assert_eq!( + classify_body(1, body.clone()), + Acceptance::Unguarded, + "{body:?}" + ); } } @@ -250,7 +261,10 @@ mod tests { /// is non-regular. #[test] fn operator_forms_are_classified() { - assert_eq!(classify_body(1, TypeTerm::Op("X".to_owned())), Acceptance::Unguarded); + assert_eq!( + classify_body(1, TypeTerm::Op("X".to_owned())), + Acceptance::Unguarded + ); let apply_growing = TypeTerm::List(Box::new(TypeTerm::Apply( Box::new(TypeTerm::Op("X".to_owned())), vec![TypeTerm::List(Box::new(TypeTerm::Param(0)))], diff --git a/crates/basilisk-checker/src/tyeval/eval.rs b/crates/basilisk-checker/src/tyeval/eval.rs index e70c3146..8261cb37 100644 --- a/crates/basilisk-checker/src/tyeval/eval.rs +++ b/crates/basilisk-checker/src/tyeval/eval.rs @@ -90,7 +90,9 @@ impl Evaluator { Some(def) if def.arity == 0 => self.eval_application(env, name, &[], args, depth), _ => Eval::Divergent, }, - TypeTerm::Apply(head, apply_args) => self.eval_apply(env, head, apply_args, args, depth), + TypeTerm::Apply(head, apply_args) => { + self.eval_apply(env, head, apply_args, args, depth) + } TypeTerm::Cond(cond) => self.eval_cond(env, cond, args, depth), TypeTerm::List(inner) => { let element = self.eval_at(env, inner, args, depth + 1).into_inferred(); @@ -161,7 +163,13 @@ impl Evaluator { /// TypeScript/PEP 827 distribution rule — each arm rewritten lazily. /// An undecidable scrutinee (gradual `Unknown`) makes the whole /// conditional gradual rather than guessing a branch. - fn eval_cond(&mut self, env: &AliasEnv, cond: &CondTerm, args: &[TypeTerm], depth: u32) -> Eval { + fn eval_cond( + &mut self, + env: &AliasEnv, + cond: &CondTerm, + args: &[TypeTerm], + depth: u32, + ) -> Eval { let Some(scrutinee) = self.force_value(env, &cond.scrutinee, args, depth) else { return Eval::Divergent; }; diff --git a/crates/basilisk-checker/src/tyeval/eval/tests.rs b/crates/basilisk-checker/src/tyeval/eval/tests.rs index 576a53c3..10cce884 100644 --- a/crates/basilisk-checker/src/tyeval/eval/tests.rs +++ b/crates/basilisk-checker/src/tyeval/eval/tests.rs @@ -256,10 +256,16 @@ fn operator_argument_applies_higher_order() { fn ill_kinded_applications_are_gradual() { let env = env_with_wrap(); let wrong_arity = TypeTerm::Alias("wrap".to_owned(), vec![int(), int()]); - assert_eq!(Evaluator::new().evaluate(&env, &wrong_arity), Eval::Divergent); + assert_eq!( + Evaluator::new().evaluate(&env, &wrong_arity), + Eval::Divergent + ); let apply_ground = TypeTerm::Apply(Box::new(int()), vec![int()]); - assert_eq!(Evaluator::new().evaluate(&env, &apply_ground), Eval::Divergent); + assert_eq!( + Evaluator::new().evaluate(&env, &apply_ground), + Eval::Divergent + ); let unapplied_operator = TypeTerm::Op("wrap".to_owned()); assert_eq!( diff --git a/crates/basilisk-checker/src/tyeval/lower.rs b/crates/basilisk-checker/src/tyeval/lower.rs index dbb7f3c6..f836875c 100644 --- a/crates/basilisk-checker/src/tyeval/lower.rs +++ b/crates/basilisk-checker/src/tyeval/lower.rs @@ -10,7 +10,9 @@ use std::collections::HashSet; -use ruff_python_ast::{Expr, ExceptHandler, ExprSubscript, ModModule, Operator, Stmt, StmtTypeAlias}; +use ruff_python_ast::{ + ExceptHandler, Expr, ExprSubscript, ModModule, Operator, Stmt, StmtTypeAlias, +}; use ruff_text_size::{Ranged as _, TextRange}; use crate::types::InferredType; @@ -185,9 +187,7 @@ impl LowerCtx<'_> { match (base_name.as_str(), args.len()) { ("Union" | "typing.Union", _) => TypeTerm::Union(args), ("Optional" | "typing.Optional", 1) => match args.into_iter().next() { - Some(inner) => { - TypeTerm::Union(vec![inner, TypeTerm::Ground(InferredType::None_)]) - } + Some(inner) => TypeTerm::Union(vec![inner, TypeTerm::Ground(InferredType::None_)]), None => TypeTerm::Ground(InferredType::Unknown), }, ("Annotated" | "typing.Annotated", _) => args @@ -337,15 +337,31 @@ mod tests { fn transparent_special_forms_do_not_guard_recursion() { for (source, name, expected) in [ ("type X = Union[int, X]\n", "X", Acceptance::Unguarded), - ("type X = typing.Union[int, X]\n", "X", Acceptance::Unguarded), + ( + "type X = typing.Union[int, X]\n", + "X", + Acceptance::Unguarded, + ), ("type Y = Optional[Y]\n", "Y", Acceptance::Unguarded), ("type Y = typing.Optional[Y]\n", "Y", Acceptance::Unguarded), - ("type Z = Annotated[Z, \"meta\"]\n", "Z", Acceptance::Unguarded), + ( + "type Z = Annotated[Z, \"meta\"]\n", + "Z", + Acceptance::Unguarded, + ), ("type A = Union[int, list[A]]\n", "A", Acceptance::Accepted), ("type B = Optional[list[B]]\n", "B", Acceptance::Accepted), - ("type C = Annotated[list[C], \"meta\"]\n", "C", Acceptance::Accepted), + ( + "type C = Annotated[list[C], \"meta\"]\n", + "C", + Acceptance::Accepted, + ), ] { - assert_eq!(classify_source_alias(source, name), Some(expected), "{source}"); + assert_eq!( + classify_source_alias(source, name), + Some(expected), + "{source}" + ); } } @@ -391,8 +407,8 @@ def scope(): assert_eq!( names, [ - "A1", "A2", "A3", "B1", "B2", "C1", "C2", "D1", "E1", "E2", "E3", "E4", "F1", - "G1", "H1" + "A1", "A2", "A3", "B1", "B2", "C1", "C2", "D1", "E1", "E2", "E3", "E4", "F1", "G1", + "H1" ] ); } diff --git a/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs b/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs index 25aa13d8..35d4b2e6 100644 --- a/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs +++ b/crates/basilisk-checker/tests/checker/aliases_recursive_tests.rs @@ -65,8 +65,8 @@ fn upstream_recursive_definitions_as_type_statements_are_clean( /// names. Both must still be rejected in the PEP 695 spelling — including /// through the transparent `Union[..]` operator. #[test] -fn upstream_cyclical_cases_as_type_statements_still_fire( -) -> Result<(), Box> { +fn upstream_cyclical_cases_as_type_statements_still_fire() -> Result<(), Box> +{ let cases = [ // RecursiveUnion (upstream line 72), `|` and Union[..] spellings. "type RecursiveUnion = RecursiveUnion | int\n", diff --git a/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs b/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs index 842229c0..3050a64c 100644 --- a/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs +++ b/crates/basilisk-checker/tests/checker/aliases_type_statement_tests.rs @@ -30,19 +30,19 @@ type Dotted = collections.abc.Sequence fn conformance_bad_alias_forms_all_fire() -> Result<(), Box> { let var_prefix = "var1 = 3\n"; let bad_forms = [ - "type Bad = eval(\"int\")", // BadTypeAlias1: call - "type Bad = [int, str]", // BadTypeAlias2: list literal - "type Bad = ((int, str),)", // BadTypeAlias3: tuple literal - "type Bad = [int for i in range(1)]", // BadTypeAlias4: comprehension - "type Bad = {\"a\": \"b\"}", // BadTypeAlias5: dict literal - "type Bad = (lambda: int)()", // BadTypeAlias6: lambda call - "type Bad = [int][0]", // BadTypeAlias7: subscripted list - "type Bad = int if 1 < 3 else str", // BadTypeAlias8: conditional - "type Bad = var1", // BadTypeAlias9: non-type variable - "type Bad = True", // BadTypeAlias10: bool literal - "type Bad = 1", // BadTypeAlias11: int literal - "type Bad = list or set", // BadTypeAlias12: boolean op - "type Bad = f\"{'int'}\"", // BadTypeAlias13: f-string + "type Bad = eval(\"int\")", // BadTypeAlias1: call + "type Bad = [int, str]", // BadTypeAlias2: list literal + "type Bad = ((int, str),)", // BadTypeAlias3: tuple literal + "type Bad = [int for i in range(1)]", // BadTypeAlias4: comprehension + "type Bad = {\"a\": \"b\"}", // BadTypeAlias5: dict literal + "type Bad = (lambda: int)()", // BadTypeAlias6: lambda call + "type Bad = [int][0]", // BadTypeAlias7: subscripted list + "type Bad = int if 1 < 3 else str", // BadTypeAlias8: conditional + "type Bad = var1", // BadTypeAlias9: non-type variable + "type Bad = True", // BadTypeAlias10: bool literal + "type Bad = 1", // BadTypeAlias11: int literal + "type Bad = list or set", // BadTypeAlias12: boolean op + "type Bad = f\"{'int'}\"", // BadTypeAlias13: f-string ]; for form in bad_forms { let source = format!("{var_prefix}{form}\n"); @@ -54,9 +54,9 @@ fn conformance_bad_alias_forms_all_fire() -> Result<(), Box Result<(), Box> { for form in [ - "type Bad = -1", // unary minus - "type Bad = lambda: int", // bare lambda - "type Bad = (int, str)", // parenthesized tuple + "type Bad = -1", // unary minus + "type Bad = lambda: int", // bare lambda + "type Bad = (int, str)", // parenthesized tuple ] { let source = format!("{form}\n"); assert!(fires(&source)?, "must fire on: {form}"); @@ -69,8 +69,8 @@ fn more_invalid_expression_forms_fire() -> Result<(), Box /// A perfectly valid alias to a class whose NAME contains "lambda" must not /// fire — `rhs.contains("lambda")` was a substring false positive. #[test] -fn identifier_containing_lambda_substring_is_not_flagged( -) -> Result<(), Box> { +fn identifier_containing_lambda_substring_is_not_flagged() -> Result<(), Box> +{ let source = r" class Blambda: pass diff --git a/crates/basilisk-checker/tests/checker/assignment_compatibility_tests.rs b/crates/basilisk-checker/tests/checker/assignment_compatibility_tests.rs index c24eaa0f..ed5a8426 100644 --- a/crates/basilisk-checker/tests/checker/assignment_compatibility_tests.rs +++ b/crates/basilisk-checker/tests/checker/assignment_compatibility_tests.rs @@ -478,3 +478,75 @@ _BAD: tuple[tuple[str, str], ...] = (("a", 1), ("c", "d")) ); Ok(()) } + +#[test] +fn enum_type_assigns_to_complete_literal_member_union() -> Result<(), Box> { + // GitHub #374: the enums chapter's literal expansion makes `Answer` + // equivalent to `Literal[Answer.Yes, Answer.No]` when Yes/No are ALL of + // its members, so the enum-typed value is assignable to that union — + // in both the bare-`Enum` and dotted `enum.Enum` base spellings. + let sources = [ + r#" +from enum import Enum +from typing import Literal + + +class Answer(Enum): + Yes = 1 + No = 2 + + +def to_literal(a: Answer) -> None: + x: Literal[Answer.Yes, Answer.No] = a +"#, + r#" +import enum +from typing import Literal + + +class Answer(enum.Enum): + Yes = 1 + No = 2 + + +def to_literal(a: Answer) -> None: + x: Literal[Answer.Yes, Answer.No] = a +"#, + ]; + for source in sources { + let diags = run(source)?; + let msgs = messages_for(&diags, "assignment_compatibility"); + assert!( + msgs.is_empty(), + "a complete enum-member union must accept the enum type (#374), got: {msgs:?}" + ); + } + Ok(()) +} + +#[test] +fn enum_type_to_partial_literal_member_union_still_fires() -> Result<(), Box> +{ + // The guard for #374's fix: a PARTIAL member union is NOT equivalent to + // the enum — `a` may hold `Answer.No`, so this stays an error. + let source = r#" +from enum import Enum +from typing import Literal + + +class Answer(Enum): + Yes = 1 + No = 2 + + +def to_literal(a: Answer) -> None: + x: Literal[Answer.Yes] = a +"#; + let diags = run(source)?; + let msgs = messages_for(&diags, "assignment_compatibility"); + assert!( + !msgs.is_empty(), + "a partial member union must still reject the full enum type" + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs b/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs index 4a14f3ab..51b6ca13 100644 --- a/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs +++ b/crates/basilisk-checker/tests/checker/generics_syntax_scoping_tests.rs @@ -152,8 +152,8 @@ fn self_recursion_through_list_ok() -> Result<(), Box> { /// Acceptance is decided by [TYPEINF-TARGET-TYPELEVEL]'s guardedness condition /// (`tyeval::accept`), not by "does the RHS mention my own name". #[test] -fn recursive_pep695_alias_under_a_constructor_is_accepted( -) -> Result<(), Box> { +fn recursive_pep695_alias_under_a_constructor_is_accepted() -> Result<(), Box> +{ for source in [ "type J = list[J]\n", "type J = int | list[J]\n", diff --git a/crates/basilisk-checker/tests/checker/names_undefined_tests.rs b/crates/basilisk-checker/tests/checker/names_undefined_tests.rs index fa5f7d38..b9800680 100644 --- a/crates/basilisk-checker/tests/checker/names_undefined_tests.rs +++ b/crates/basilisk-checker/tests/checker/names_undefined_tests.rs @@ -493,8 +493,8 @@ def alias() -> object: } #[test] -fn class_scope_type_alias_is_not_visible_from_a_function( -) -> Result<(), Box> { +fn class_scope_type_alias_is_not_visible_from_a_function() -> Result<(), Box> +{ // Class-body names do not nest: a `type` alias declared inside a class // is reachable only as `C.Inner`, so a bare `Inner` in a module-level // function is still an undefined name. @@ -559,3 +559,58 @@ def f() -> object: ); Ok(()) } + +#[test] +fn self_referential_class_bases_terminate_and_flag() -> Result<(), Box> { + // GitHub #398: `class C(C[int], C[bool])` sent the resolver's transitive + // base walk into an exponential recursion — checking must TERMINATE. And + // per Python semantics a class name is unbound until its `class` statement + // completes, so referencing it in its own bases list must draw + // `names_undefined` (both classes here have no other binding). + let (tx, rx) = std::sync::mpsc::channel(); + let _worker = std::thread::spawn(move || { + let outcome = run("class C(C[int], C[bool]):\n pass\n").map_err(|e| e.to_string()); + let _ = tx.send(outcome); + }); + let received = rx.recv_timeout(std::time::Duration::from_secs(30)); + let Ok(outcome) = received else { + return Err("resolver spun for 30s on self-referential bases (GitHub #398)".into()); + }; + let diags = outcome?; + assert!( + codes(&diags).contains(&"names_undefined"), + "`class C(C[int], C[bool])` must flag the unbound self-reference, got: {:?}", + codes(&diags) + ); + + let diags = run("class D(D):\n pass\n")?; + assert!( + codes(&diags).contains(&"names_undefined"), + "`class D(D)` must flag the unbound self-reference, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +#[test] +fn prior_binding_and_builtin_self_named_bases_stay_clean() -> Result<(), Box> +{ + // Redefining a class over a prior binding is legal Python — the base + // names the OLD binding, not the class being defined. + let source = "class C:\n pass\n\n\nclass C(C):\n pass\n"; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"names_undefined"), + "a prior binding makes `class C(C)` legal, got: {:?}", + messages_for(&diags, "names_undefined") + ); + + // `class int(int)` derives from the BUILTIN int — also legal. + let diags = run("class int(int):\n pass\n")?; + assert!( + !codes(&diags).contains(&"names_undefined"), + "a builtin base name is always bound, got: {:?}", + messages_for(&diags, "names_undefined") + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/checker/tuples_index_tests.rs b/crates/basilisk-checker/tests/checker/tuples_index_tests.rs index 3936b2ef..97d83eab 100644 --- a/crates/basilisk-checker/tests/checker/tuples_index_tests.rs +++ b/crates/basilisk-checker/tests/checker/tuples_index_tests.rs @@ -20,26 +20,41 @@ y = t[1] #[test] fn positive_out_of_bounds() -> Result<(), Box> { - // TODO: resolver does not yet produce tuple_index_violations for literal indices. - // When it does, this test should assert E0103 fires. + // Module-level miss found by the torture corpus (tuple_index.py, GitHub + // #284 family): the spec's tuples chapter requires an error for an + // out-of-range literal index on a fixed-length tuple, at every scope. let source = r#" t: tuple[int, str, bool] = (1, "a", True) x = t[3] "#; let diags = run(source)?; - let _ = codes(&diags); + let hits: Vec<&str> = messages_for(&diags, "tuples_index"); + assert_eq!( + hits.len(), + 1, + "module-level `t[3]` on a 3-tuple must fire exactly once, got: {hits:?}" + ); + assert!( + hits[0].contains("index 3") && hits[0].contains("length 3"), + "diagnostic must name index 3 and tuple length 3: {}", + hits[0] + ); Ok(()) } #[test] fn negative_out_of_bounds() -> Result<(), Box> { - // TODO: resolver does not yet produce tuple_index_violations for literal indices. let source = r#" t: tuple[int, str, bool] = (1, "a", True) x = t[-4] "#; let diags = run(source)?; - let _ = codes(&diags); + let hits: Vec<&str> = messages_for(&diags, "tuples_index"); + assert_eq!( + hits.len(), + 1, + "module-level `t[-4]` on a 3-tuple must fire exactly once, got: {hits:?}" + ); Ok(()) } @@ -61,7 +76,6 @@ z = t[-3] #[test] fn single_element_tuple() -> Result<(), Box> { - // TODO: resolver does not yet produce tuple_index_violations for literal indices. let source = r#" t: tuple[int] = (42,) x = t[0] @@ -69,7 +83,12 @@ y = t[1] z = t[-2] "#; let diags = run(source)?; - let _ = codes(&diags); + let hits: Vec<&str> = messages_for(&diags, "tuples_index"); + assert_eq!( + hits.len(), + 2, + "`t[1]` and `t[-2]` are out of range for a 1-tuple; `t[0]` is not: {hits:?}" + ); Ok(()) } @@ -147,3 +166,55 @@ def load() -> list: ); Ok(()) } + +#[test] +fn local_annotated_tuple_out_of_range_fires() -> Result<(), Box> { + // The direct-subscript miss is scope-wide: an annotated LOCAL is not a + // parameter (tuples_index_2's territory), so it was never checked either. + let source = r#" +def f() -> None: + two: tuple[int, str] = (1, "a") + bad = two[2] +"#; + let diags = run(source)?; + let hits: Vec<&str> = messages_for(&diags, "tuples_index"); + assert_eq!( + hits.len(), + 1, + "`two[2]` on an annotated local 2-tuple must fire exactly once, got: {hits:?}" + ); + Ok(()) +} + +#[test] +fn variadic_and_shadowed_tuples_stay_clean() -> Result<(), Box> { + // `tuple[int, ...]` has no fixed length — any literal index is in range. + let source = r#" +t: tuple[int, ...] = (1, 2, 3) +x = t[5] +"#; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"tuples_index"), + "variadic tuples must never fire: {:?}", + messages_for(&diags, "tuples_index") + ); + + // A function-local rebinding shadows the module annotation — the local + // `two` is a different, unannotated variable (the exact #284 bleed shape). + let source = r#" +two: tuple[int, str] = (1, "a") + + +def f() -> int: + two = (1, 2, 3) + return two[2] +"#; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"tuples_index"), + "a shadowing local rebind must not be checked against the module annotation: {:?}", + messages_for(&diags, "tuples_index") + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/torture_golden_tests.rs b/crates/basilisk-checker/tests/torture_golden_tests.rs new file mode 100644 index 00000000..884e3588 --- /dev/null +++ b/crates/basilisk-checker/tests/torture_golden_tests.rs @@ -0,0 +1,126 @@ +//! Golden gate for the type-torture corpus ([NARROWPLAN-SUPERIORITY] slice). +//! See docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md and +//! `benchmarks/torture/run_torture.py` (the cross-checker scoreboard over the +//! same cases). +//! +//! Each case in `benchmarks/torture/cases/*.py` is scored conformance-style: +//! every line ending in `# E` must draw at least one error-severity +//! diagnostic, and no other line may draw any. The checker runs in-process +//! with the default configuration — exactly `common::run` — so `cargo test` +//! (and therefore CI) breaks the moment a torture case regresses. +#![allow( + clippy::allow_attributes, + clippy::indexing_slicing, + clippy::expect_used, + clippy::unwrap_used, + clippy::panic, + missing_docs, + dead_code +)] + +#[path = "common/mod.rs"] +mod common; + +use std::collections::BTreeSet; +use std::path::PathBuf; + +use basilisk_checker::Severity; +use common::run; + +/// Absolute path of a torture case file. +fn case_path(name: &str) -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .join("../../benchmarks/torture/cases") + .join(name) +} + +/// 1-based lines carrying a `# E` marker — the required-error lines. +fn expected_error_lines(source: &str) -> BTreeSet { + source + .lines() + .enumerate() + .filter(|(_, line)| line.trim_end().ends_with("# E")) + .map(|(index, _)| index + 1) + .collect() +} + +/// 1-based line number of a byte offset. +fn line_of_offset(source: &str, offset: usize) -> usize { + source.get(..offset).map_or(1, |prefix| { + prefix.bytes().filter(|b| *b == b'\n').count() + 1 + }) +} + +/// Run one case and assert the reported error lines equal the `# E` lines. +fn assert_case_golden(name: &str) -> Result<(), Box> { + let source = std::fs::read_to_string(case_path(name))?; + let expected = expected_error_lines(&source); + + let diags = run(&source)?; + let reported: BTreeSet = diags + .iter() + .filter(|d| d.severity == Severity::Error) + .map(|d| line_of_offset(&source, usize::try_from(d.span.start).unwrap_or(0))) + .collect(); + + let missed: Vec = expected.difference(&reported).copied().collect(); + let extra: Vec = reported.difference(&expected).copied().collect(); + assert!( + missed.is_empty() && extra.is_empty(), + "{name}: golden mismatch — missed required-error lines {missed:?}, \ + false-positive lines {extra:?}; diagnostics: {:?}", + diags + .iter() + .filter(|d| d.severity == Severity::Error) + .map(|d| { + format!( + "L{} {}: {}", + line_of_offset(&source, usize::try_from(d.span.start).unwrap_or(0)), + d.code.code, + d.message + ) + }) + .collect::>() + ); + Ok(()) +} + +#[test] +fn enum_literal_expansion() -> Result<(), Box> { + assert_case_golden("enum_literal_expansion.py") +} + +#[test] +fn generic_constructor() -> Result<(), Box> { + assert_case_golden("generic_constructor.py") +} + +#[test] +fn param_inference() -> Result<(), Box> { + assert_case_golden("param_inference.py") +} + +#[test] +fn paramspec_decorator() -> Result<(), Box> { + assert_case_golden("paramspec_decorator.py") +} + +#[test] +fn recursive_aliases() -> Result<(), Box> { + assert_case_golden("recursive_aliases.py") +} + +#[test] +fn recursive_bases() -> Result<(), Box> { + assert_case_golden("recursive_bases.py") +} + +#[test] +fn tuple_index() -> Result<(), Box> { + assert_case_golden("tuple_index.py") +} + +#[test] +fn typeis_narrowing() -> Result<(), Box> { + assert_case_golden("typeis_narrowing.py") +} diff --git a/crates/basilisk-checker/tests/tyeval_salsa_tests.rs b/crates/basilisk-checker/tests/tyeval_salsa_tests.rs index 2f509411..db8f3a85 100644 --- a/crates/basilisk-checker/tests/tyeval_salsa_tests.rs +++ b/crates/basilisk-checker/tests/tyeval_salsa_tests.rs @@ -47,10 +47,7 @@ fn unguarded_alias_projects_to_unknown_through_the_query() { let db = EventDb::default(); let file = SourceFile::new(&db, "m.py".to_owned(), "type X = X\n".to_owned()); assert!(type_alias_env(&db, file).get("X").is_none()); - assert_eq!( - alias_whnf(&db, file, "X".to_owned()), - InferredType::Unknown - ); + assert_eq!(alias_whnf(&db, file, "X".to_owned()), InferredType::Unknown); } /// **Memoization of normalized results across revisions**: an edit outside diff --git a/crates/basilisk-resolver/src/scope/typeddict_meta.rs b/crates/basilisk-resolver/src/scope/typeddict_meta.rs index 1a73d992..df344148 100644 --- a/crates/basilisk-resolver/src/scope/typeddict_meta.rs +++ b/crates/basilisk-resolver/src/scope/typeddict_meta.rs @@ -15,10 +15,6 @@ use std::hash::BuildHasher; use super::class_types::ClassInfo; -/// Maximum inheritance depth walked before bailing out. Guards against cyclic -/// `bases` (illegal Python, but must not hang the resolver). -const MAX_DEPTH: u32 = 64; - /// Build a `class name -> &ClassInfo` lookup over a module's classes. #[must_use] pub fn class_by_name(classes: &[ClassInfo]) -> HashMap<&str, &ClassInfo> { @@ -32,7 +28,7 @@ pub fn is_transitive_typeddict( name: &str, class_map: &HashMap<&str, &ClassInfo, S>, ) -> bool { - walk_bases(name, class_map, 0, &|class| class.is_typed_dict) + walk_bases(name, class_map, &|class| class.is_typed_dict) } /// Returns `true` when this class — or any transitive `TypedDict` base — was @@ -43,7 +39,7 @@ pub fn has_extra_items_transitive( name: &str, class_map: &HashMap<&str, &ClassInfo, S>, ) -> bool { - walk_bases(name, class_map, 0, &|class| { + walk_bases(name, class_map, &|class| { class.class_keywords.iter().any(|kw| kw == "extra_items") }) } @@ -99,23 +95,33 @@ fn try_strip_wrapper<'a>(lower: &str, original: &'a str, prefix: &str) -> Option Some(&original[prefix.len()..original.len() - 1]) } -/// Walk `name` and its transitive bases, returning `true` as soon as `predicate` -/// holds for any class in the chain. +/// Walk `name` and its transitive bases, returning `true` as soon as +/// `predicate` holds for any class in the chain. +/// +/// Stack-overflow-proof by construction: the walk is iterative (explicit +/// worklist, zero recursion), so no hierarchy — however deep — grows the call +/// stack. The `visited` set bounds work to one visit per class, so cyclic or +/// self-referential `bases` — illegal Python, but reachable input (GitHub +/// #398: a class listing itself twice made the old depth-capped recursive +/// walk exponential) — terminate in linear time. fn walk_bases( name: &str, class_map: &HashMap<&str, &ClassInfo, S>, - depth: u32, predicate: &dyn Fn(&ClassInfo) -> bool, ) -> bool { - if depth >= MAX_DEPTH { - return false; + let mut visited: HashSet<&str> = HashSet::new(); + let mut worklist: Vec<&str> = vec![name]; + while let Some(current) = worklist.pop() { + if !visited.insert(current) { + continue; + } + let Some(class) = class_map.get(current) else { + continue; + }; + if predicate(class) { + return true; + } + worklist.extend(class.bases.iter().map(String::as_str)); } - let Some(class) = class_map.get(name) else { - return false; - }; - predicate(class) - || class - .bases - .iter() - .any(|base| walk_bases(base, class_map, depth + 1, predicate)) + false } diff --git a/crates/basilisk-resolver/src/visitor/annotated_tuple_index.rs b/crates/basilisk-resolver/src/visitor/annotated_tuple_index.rs new file mode 100644 index 00000000..f912795a --- /dev/null +++ b/crates/basilisk-resolver/src/visitor/annotated_tuple_index.rs @@ -0,0 +1,190 @@ +//! Implements the [TYPEINF-COLLECTIONS-TUPLES] index-range rule for annotated +//! variables. See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-COLLECTIONS-TUPLES +//! +//! A fixed-length `tuple[T1, ..., Tn]` supports exactly the literal indices +//! `[-n, n)`; anything else is a static error at every scope (the typing +//! spec's tuples chapter). This collector walks the AST for `name[LITERAL]` +//! subscripts whose name's **declared annotation** — an annotated local of the +//! innermost binding scope, else an annotated module variable — is a fixed +//! tuple, and records out-of-range reads as [`TupleIndexViolation`]s for the +//! `tuples_index` rule. Parameters stay with `tuples_index_2`; `key=` lambda +//! parameters stay with the `key_lambda` collector (their names are shadowed +//! here, never resolved against enclosing bindings). + +use ruff_python_ast::visitor::{walk_expr, Visitor}; +use ruff_python_ast::{Comprehension, Expr, ExprContext, ExprSubscript, Stmt}; +use ruff_text_size::Ranged; + +use crate::scope::{FunctionInfo, TupleIndexViolation, VariableInfo}; + +use super::core::text_range_to_span; +use super::key_lambda::{fixed_tuple_len, literal_int}; + +/// Collect out-of-range literal-index reads on tuple-annotated variables. +pub(super) fn collect_annotated_tuple_index_violations( + stmts: &[Stmt], + functions: &[FunctionInfo], + module_vars: &[VariableInfo], + source: &str, +) -> Vec { + let mut collector = AnnotatedTupleIndexCollector { + functions, + module_vars, + source, + shadowed: Vec::new(), + out: Vec::new(), + }; + for stmt in stmts { + collector.visit_stmt(stmt); + } + collector.out +} + +struct AnnotatedTupleIndexCollector<'a> { + functions: &'a [FunctionInfo], + module_vars: &'a [VariableInfo], + source: &'a str, + /// Names bound by enclosing lambda parameters or comprehension targets — + /// scopes the resolver does not model as functions. A shadowed name never + /// resolves to an outer annotation. + shadowed: Vec, + out: Vec, +} + +impl<'a> Visitor<'a> for AnnotatedTupleIndexCollector<'a> { + fn visit_expr(&mut self, expr: &'a Expr) { + match expr { + Expr::Lambda(lambda) => { + let shadow_count = self.push_lambda_params(lambda); + self.visit_expr(&lambda.body); + self.shadowed.truncate(self.shadowed.len() - shadow_count); + } + Expr::ListComp(comp) => self.visit_comprehension_scope(&comp.generators, expr), + Expr::SetComp(comp) => self.visit_comprehension_scope(&comp.generators, expr), + Expr::DictComp(comp) => self.visit_comprehension_scope(&comp.generators, expr), + Expr::Generator(comp) => self.visit_comprehension_scope(&comp.generators, expr), + Expr::Subscript(sub) => { + self.check_subscript(sub); + walk_expr(self, expr); + } + _ => walk_expr(self, expr), + } + } +} + +impl<'a> AnnotatedTupleIndexCollector<'a> { + /// Shadow every parameter name of a lambda; returns how many were pushed. + fn push_lambda_params(&mut self, lambda: &ruff_python_ast::ExprLambda) -> usize { + let Some(params) = lambda.parameters.as_deref() else { + return 0; + }; + let before = self.shadowed.len(); + let positional = params.posonlyargs.iter().chain(¶ms.args); + let keyword_only = params.kwonlyargs.iter(); + for param in positional.chain(keyword_only) { + self.shadowed.push(param.parameter.name.to_string()); + } + for param in params.vararg.iter().chain(params.kwarg.iter()) { + self.shadowed.push(param.name.to_string()); + } + self.shadowed.len() - before + } + + /// Walk a comprehension with its target names shadowed (conservatively for + /// the whole expression: no annotation-based diagnostics inside). + fn visit_comprehension_scope(&mut self, generators: &'a [Comprehension], expr: &'a Expr) { + let before = self.shadowed.len(); + for generator in generators { + collect_target_names(&generator.target, &mut self.shadowed); + } + walk_expr(self, expr); + self.shadowed.truncate(before); + } + + /// Record `name[LITERAL]` reads whose declared fixed-tuple length excludes + /// the index. + fn check_subscript(&mut self, sub: &ExprSubscript) { + if !matches!(sub.ctx, ExprContext::Load) { + return; + } + let Expr::Name(base) = sub.value.as_ref() else { + return; + }; + let name = base.id.as_str(); + if self.shadowed.iter().any(|shadow| shadow == name) { + return; + } + let Some(index) = literal_int(&sub.slice) else { + return; + }; + let offset = text_range_to_span(sub.range()).start_usize(); + let Some(tuple_length) = self.declared_tuple_len(name, offset) else { + return; + }; + let len = i64::try_from(tuple_length).unwrap_or(i64::MAX); + if index >= len || index < -len { + self.out.push(TupleIndexViolation { + span: text_range_to_span(sub.range()), + tuple_var_name: name.to_owned(), + index_value: index, + tuple_length, + }); + } + } + + /// The declared fixed-tuple length of `name` at `offset`: the innermost + /// enclosing function whose scope binds the name decides — an annotated + /// local's annotation applies; a parameter or unannotated binding opts out + /// (different owner or no declared type) — falling back to an annotated + /// module variable. + fn declared_tuple_len(&self, name: &str, offset: usize) -> Option { + let mut enclosing: Vec<&FunctionInfo> = self + .functions + .iter() + .filter(|f| f.def_span.start_usize() <= offset && offset < f.def_span.end_usize()) + .collect(); + enclosing.sort_by_key(|f| std::cmp::Reverse(f.def_span.start)); + + for func in enclosing { + if let Some(var) = func.local_vars.iter().find(|v| v.name == name) { + return self.annotated_fixed_tuple_len(var); + } + let binds_otherwise = func.parameters.iter().any(|p| p.name == name) + || func.vararg.as_ref().is_some_and(|v| v.name == name) + || func.kwarg.as_ref().is_some_and(|k| k.name == name) + || func.all_local_assigns.iter().any(|a| a == name); + if binds_otherwise { + return None; + } + } + let var = self.module_vars.iter().find(|v| v.name == name)?; + self.annotated_fixed_tuple_len(var) + } + + /// The variable's declared tuple length, `None` without a fixed-tuple + /// annotation. + fn annotated_fixed_tuple_len(&self, var: &VariableInfo) -> Option { + let annotation = var.annotation_span?.slice_source(self.source)?; + fixed_tuple_len(annotation.trim()) + } +} + +/// Push every `Name` bound by a comprehension target (`x`, `(a, b)`, `[a, b]`, +/// starred elements) onto `shadowed`. +fn collect_target_names(target: &Expr, shadowed: &mut Vec) { + match target { + Expr::Name(name) => shadowed.push(name.id.to_string()), + Expr::Tuple(tuple) => { + for element in &tuple.elts { + collect_target_names(element, shadowed); + } + } + Expr::List(list) => { + for element in &list.elts { + collect_target_names(element, shadowed); + } + } + Expr::Starred(starred) => collect_target_names(&starred.value, shadowed), + _ => {} + } +} diff --git a/crates/basilisk-resolver/src/visitor/key_lambda.rs b/crates/basilisk-resolver/src/visitor/key_lambda.rs index 27ccc786..e54221bd 100644 --- a/crates/basilisk-resolver/src/visitor/key_lambda.rs +++ b/crates/basilisk-resolver/src/visitor/key_lambda.rs @@ -208,7 +208,7 @@ fn collect_out_of_range_subscripts( } /// A literal integer index: `3` or `-3`. -fn literal_int(expr: &Expr) -> Option { +pub(super) fn literal_int(expr: &Expr) -> Option { match expr { Expr::NumberLiteral(num) => match &num.value { Number::Int(value) => value.as_i64(), @@ -269,13 +269,19 @@ fn fixed_tuple_len_from_container_annotation(annotation: &str) -> Option } /// The length of a fixed-size tuple annotation: `tuple[str, int]` → `Some(2)`. -fn fixed_tuple_len(annotation: &str) -> Option { +/// +/// Variadic (`tuple[int, ...]`) and PEP 646 unpacked (`tuple[int, *Ts]`, +/// `tuple[int, *tuple[str, ...]]`) forms have no fixed length and yield `None`. +pub(super) fn fixed_tuple_len(annotation: &str) -> Option { let inner = annotation .strip_prefix("tuple[") .or_else(|| annotation.strip_prefix("Tuple["))? .strip_suffix(']')?; let elements = split_top_level_args(inner); - if elements.iter().any(|e| e.trim() == "...") { + if elements + .iter() + .any(|e| e.trim() == "..." || e.trim().starts_with('*')) + { return None; } match elements.as_slice() { diff --git a/crates/basilisk-resolver/src/visitor/mod.rs b/crates/basilisk-resolver/src/visitor/mod.rs index 718e06eb..205a553b 100644 --- a/crates/basilisk-resolver/src/visitor/mod.rs +++ b/crates/basilisk-resolver/src/visitor/mod.rs @@ -3,6 +3,7 @@ const ENUM_BASES: &[&str] = &["Enum", "IntEnum", "StrEnum", "Flag", "IntFlag", "ReprEnum"]; +mod annotated_tuple_index; mod annotations; mod assert_narrow; mod assigns; @@ -192,12 +193,20 @@ fn build_resolved_module( typevar_calls.iter().map(|tv| tv.name.clone()).collect(); type_alias::collect_type_alias_type_violations(stmts, &tv_names) }; - let tuple_index_violations = key_lambda::collect_key_lambda_tuple_violations( + let mut tuple_index_violations = key_lambda::collect_key_lambda_tuple_violations( stmts, &functions, &module_vars, &module.source, ); + tuple_index_violations.extend( + annotated_tuple_index::collect_annotated_tuple_index_violations( + stmts, + &functions, + &module_vars, + &module.source, + ), + ); ResolvedModule { functions, classes, diff --git a/crates/basilisk-resolver/tests/resolver/test_deep_base_chains.rs b/crates/basilisk-resolver/tests/resolver/test_deep_base_chains.rs new file mode 100644 index 00000000..b5b2c5ee --- /dev/null +++ b/crates/basilisk-resolver/tests/resolver/test_deep_base_chains.rs @@ -0,0 +1,73 @@ +//! Tests for [CHKARCH-ARCH-PIPELINE]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-ARCH-PIPELINE +//! Stack safety and unbounded-depth correctness of the transitive base walk +//! (`scope/typeddict_meta.rs`), the shared foundation of +//! [CHKARCH-DIAG-TYPEDDICT-READONLY-INHERITANCE]. +//! +//! The walk is iterative (explicit worklist, zero recursion) and carries a +//! visited set. Together those give two guarantees this file pins: a chain of +//! ANY depth cannot grow the call stack, and a self-referential or cyclic +//! `bases` list terminates instead of blowing up exponentially (GitHub #398). + +use std::fmt::Write as _; + +use basilisk_resolver::{class_by_name, is_transitive_typeddict}; + +use super::common::resolve_src; + +/// `class C0(TypedDict)` followed by `depth` single-inheritance subclasses. +fn deep_typeddict_chain(depth: usize) -> String { + let mut src = String::from("from typing import TypedDict\nclass C0(TypedDict):\n x: int\n"); + for level in 1..=depth { + let _ = writeln!(src, "class C{level}(C{}):\n pass", level - 1); + } + src +} + +/// A 1 000-deep chain resolves without exhausting the stack, and the deepest +/// leaf is still recognised as a `TypedDict`. +/// +/// Recursion here would push one frame per level; the iterative walk pushes +/// heap entries instead, so depth costs memory rather than stack. The depth +/// also sits far past any fixed cap — a bounded walk would silently report the +/// leaf as not a `TypedDict`, which is a wrong answer, not a slow one. +#[test] +fn thousand_deep_chain_walks_without_stack_growth() -> Result<(), Box> { + let resolved = resolve_src(&deep_typeddict_chain(1_000))?; + let class_map = class_by_name(&resolved.classes); + + assert!( + is_transitive_typeddict("C1000", &class_map), + "the 1 000th subclass of a TypedDict is still a TypedDict" + ); + assert!( + !is_transitive_typeddict("C0Missing", &class_map), + "an unknown class name resolves to false rather than panicking" + ); + Ok(()) +} + +/// A class listing itself twice among its bases terminates. With a +/// depth-bounded recursive walk this input branched at every level and took +/// exponential time (GitHub #398); the visited set makes it linear. +#[test] +fn self_referential_bases_terminate() -> Result<(), Box> { + let resolved = resolve_src("class C(C[int], C[bool]):\n pass\n")?; + let class_map = class_by_name(&resolved.classes); + + assert!( + !is_transitive_typeddict("C", &class_map), + "a self-referential class is not a TypedDict, and deciding that terminates" + ); + Ok(()) +} + +/// Two classes naming each other as bases — the general cycle — terminates. +#[test] +fn mutually_recursive_bases_terminate() -> Result<(), Box> { + let resolved = resolve_src("class A(B):\n pass\nclass B(A):\n pass\n")?; + let class_map = class_by_name(&resolved.classes); + + assert!(!is_transitive_typeddict("A", &class_map)); + assert!(!is_transitive_typeddict("B", &class_map)); + Ok(()) +} diff --git a/crates/basilisk-resolver/tests/typeddict_tests.rs b/crates/basilisk-resolver/tests/typeddict_tests.rs index b407f02d..4822accf 100644 --- a/crates/basilisk-resolver/tests/typeddict_tests.rs +++ b/crates/basilisk-resolver/tests/typeddict_tests.rs @@ -28,3 +28,6 @@ mod test_unhashable_keys; #[path = "resolver/test_exception_handler.rs"] mod test_exception_handler; + +#[path = "resolver/test_deep_base_chains.rs"] +mod test_deep_base_chains; diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index 0b9dd6ca..88c82db8 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -834,14 +834,18 @@ the conformance ratchets (100% / 0 false positives) at every step. `run_torture.py` (out-of-the-box defaults for every tool, best-effort latest-release pull, per-invocation timeout scored as `hang`, WRITE-ALWAYS `status/torture.csv` after every case, read-only regression gate against - the committed baseline, exit 3). First measured run (2026-08-04, versions - in the CSV header): **basilisk 5/8 — behind mypy 8/8, pyrefly 8/8, - pyright 7/8, zuban 7/8; ahead of ty 4/8.** The three basilisk failures are - live defects, now pinned by the corpus: the #374 enum-expansion false - positive, the #398 recursive-base hang, and a module-level fixed-tuple - out-of-range index MISS (the function-scope twin of #284's false - positive). Taking this axis means fixing those three; the gate then holds - them fixed. + the committed baseline, exit 3). The first measured run (2026-08-04) + landed basilisk at 5/8, pinning three live defects; all three are fixed — + the #374 enum-expansion false positive (enum literal expansion + equivalence, `enum_expand.rs`), the #398 recursive-base hang (iterative + visited-set base walk, zero recursion), and the module-level fixed-tuple + index MISS (`visitor/annotated_tuple_index.rs`). Rerun same day, same + harness (versions in the CSV header): **basilisk 8/8 — tied with mypy and + pyrefly for the lead; ahead of pyright 7/8, zuban 7/8, ty 4/8.** The + standing is held twice over: the scoreboard's read-only gate, and + `crates/basilisk-checker/tests/torture_golden_tests.rs`, which scores all + eight cases in-process on every `cargo test` so CI breaks the moment a + case regresses. - [ ] Build the inference scoreboard harness mirroring `benchmarks/`: pull the latest official release of each competitor (pyright, mypy, ty, pyrefly, zuban) every run; write scores to a status file immediately and diff --git a/docs/plans/ROADMAP-NEXT-STEPS-PLAN.md b/docs/plans/ROADMAP-NEXT-STEPS-PLAN.md index 4017acf9..7920e985 100644 --- a/docs/plans/ROADMAP-NEXT-STEPS-PLAN.md +++ b/docs/plans/ROADMAP-NEXT-STEPS-PLAN.md @@ -56,7 +56,36 @@ responsibility to cover. `VSCODE_MARKETPLACE_PAT`, `OPEN_VSX_PAT`, and mirror credentials, then install each published artifact on a clean machine. - [ ] **`[HYBRID]`** Submit the standalone `Nimblesite/basilisk-zed` mirror to - `zed-industries/extensions`; automation already renders and tests that mirror. + [`zed-industries/extensions`](https://github.com/zed-industries/extensions). + Never submitted to date — Basilisk does not appear in that repo's + `extensions.toml`, so the Zed extensions view cannot find it and + [install-zed](../../website/src/docs/install-zed.md) documents the dev-extension + flow until the listing lands. Automation already renders, version-stamps, and + WASM-gates the mirror ([ZED-MIRROR](../specs/ZED-SPEC.md#ZED-MIRROR)); only the + one-time human-reviewed PR is missing. The `basilisk` extension ID is + unclaimed upstream. + + **Blocked until the next tagged release.** The published mirror at `v0.39.0` + still carries the `languages/python/` tree that shadows Zed's built-in Python + ([ZED-TREESITTER](../specs/ZED-SPEC.md#ZED-TREESITTER)); listing it would ship + that regression to every installer. Cut a release first so `publish-zed` + pushes a mirror without it, then pin *that* commit. + + Procedure, once the fixed mirror is tagged: + 1. Fork `zed-industries/extensions`. + 2. `git submodule add https://github.com/Nimblesite/basilisk-zed.git extensions/basilisk` + (HTTPS, not SSH — the registry requires it), then check the submodule out at + the release tag so the pinned commit is the version being listed. + 3. Add to `extensions.toml`: + `[basilisk]` / `submodule = "extensions/basilisk"` / `version = ""`. + The version MUST equal `extension.toml`'s stamped version. + 4. `pnpm sort-extensions` to normalise ordering in `extensions.toml` and + `.gitmodules`. + 5. Open the PR. A root `LICENSE` is mandatory for listings (MIT is already + rendered into the mirror by `render-zed-mirror.sh`). + + Subsequent version bumps amend the submodule pointer and the `version` field — + the same PR shape, or the community update action. - [ ] **`[HUMAN]`** Submit the prepared `basilisk.nvim/lspconfig/basilisk.lua` definition upstream. - [ ] **`[HYBRID]`** Submit `basilisk` to the upstream diff --git a/docs/readme/README.src.md b/docs/readme/README.src.md index ee3d1379..c6abdf12 100644 --- a/docs/readme/README.src.md +++ b/docs/readme/README.src.md @@ -40,8 +40,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit 60df123), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/docs/readme/README.zh.src.md b/docs/readme/README.zh.src.md index 841156cb..bda0da37 100644 --- a/docs/readme/README.zh.src.md +++ b/docs/readme/README.zh.src.md @@ -35,8 +35,8 @@

PEP 一致性 100.0% — 官方 - python/typing - 一致性套件（提交 60df123）141 项测试中通过 141 项， + python/typing + 一致性套件（提交 a2e6356）141 项测试中通过 141 项， 由真实的上游评分器在默认配置下对 wheel 安装的 CLI 评出。 我们以 python/typing@main 为目标，且分数只升不降。

diff --git a/docs/specs/CHECKER-ARCHITECTURE-SPEC.md b/docs/specs/CHECKER-ARCHITECTURE-SPEC.md index 80b8a378..0ac09a35 100644 --- a/docs/specs/CHECKER-ARCHITECTURE-SPEC.md +++ b/docs/specs/CHECKER-ARCHITECTURE-SPEC.md @@ -264,7 +264,7 @@ configuration/editor behavior is specified by ### Python Typing PEP Coverage {#CHKARCH-PEPS} -Basilisk's **target** is 100% conformance with the Python typing specification. We measure against the latest **`python/typing@main`**, recording the exact graded commit by hash in `conformance_report.json` (currently [`60df123`](https://github.com/python/typing/tree/60df123ccfe9ae0472b1409ef4a00d51ffc5d972/conformance)). Today the official scorer, run unmodified in CI on the binary in its default configuration (the PEP conformance set; see [CHKARCH-CONFORMANCE-MODE](#CHKARCH-CONFORMANCE-MODE)), reports **141 of 141 files passing (100.0%)**, with **0 false positives** and **0 missed required errors** (970 caught). We run that suite in CI on every change; the gate ratchets the pass-percentage **up** and the false-positive ceiling **down** — closed only by fixing the checker, never by disabling a rule. +Basilisk's **target** is 100% conformance with the Python typing specification. We measure against the latest **`python/typing@main`**, recording the exact graded commit by hash in `conformance_report.json` (currently [`a2e6356`](https://github.com/python/typing/tree/a2e6356af2f609a7ab2330895477d0d08181a169/conformance)). Today the official scorer, run unmodified in CI on the binary in its default configuration (the PEP conformance set; see [CHKARCH-CONFORMANCE-MODE](#CHKARCH-CONFORMANCE-MODE)), reports **141 of 141 files passing (100.0%)**, with **0 false positives** and **0 missed required errors** (970 caught). We run that suite in CI on every change; the gate ratchets the pass-percentage **up** and the false-positive ceiling **down** — closed only by fixing the checker, never by disabling a rule. #### Foundation PEPs {#CHKARCH-PEPS-FOUNDATION} @@ -1464,7 +1464,7 @@ that official check did not run against a freshly cloned suite is a BUILD FAILUR **down**. Per-file results are written to `conformance/conformance_status.csv`. - **Current score** — measured against `python/typing@main` at the exact graded commit recorded in `conformance_report.json`, currently - [`60df123`](https://github.com/python/typing/tree/60df123ccfe9ae0472b1409ef4a00d51ffc5d972/conformance): + [`a2e6356`](https://github.com/python/typing/tree/a2e6356af2f609a7ab2330895477d0d08181a169/conformance): **141 / 141 = 100.0%**, **0 false positives**, **0 missed required errors**, with **970** required errors caught. The binary runs in its default configuration — the PEP conformance set — over a fresh `python/typing` clone whose tree holds no diff --git a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md index 1f59a5ac..584a0e66 100644 --- a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md +++ b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md @@ -424,7 +424,9 @@ def variadic(*args: int) -> None: reveal_type(args) # tuple[int, ...] ``` -> **Authority**: [Typing spec — Tuple types](https://typing.readthedocs.io/en/latest/spec/special-forms.html#tuple). +**Index-range checking.** A value declared `tuple[T1, ..., Tn]` supports exactly the literal indices `[-n, n)`; any other literal index is a guaranteed runtime `IndexError` and draws `tuples_index` at **every** scope. The declared annotation of the innermost binding scope decides: an annotated local's tuple length applies; a parameter, `*args`/`**kwargs`, or unannotated rebinding in that scope opts the name out; otherwise an annotated module variable applies. Lambda parameters and comprehension targets shadow enclosing annotations. Variadic (`tuple[T, ...]`) and PEP 646 unpacked (`*tuple[...]`, `*Ts`) forms have no fixed length and are exempt. Collected in the resolver by `visitor/annotated_tuple_index.rs` (annotated variables), `visitor/key_lambda.rs` (`key=` lambda parameters), and the `tuples_index_2` rule (function parameters); all render through the `tuples_index` rule. + +> **Authority**: [Typing spec — Tuples](https://typing.python.org/en/latest/spec/tuples.html). ### [TYPEINF-COLLECTIONS-COMPREHENSIONS] Comprehensions {#TYPEINF-COLLECTIONS-COMPREHENSIONS} @@ -863,6 +865,9 @@ y: Sequence[Animal] = dogs # OK — Sequence is covariant - `Any` is bidirectionally compatible with all types (not a real subtype, an escape hatch) - `Never` <: everything (bottom type, assignable to all types) - the simplified annotation parser treats `object` as a gradual `Any` spelling +- **Enum literal expansion**: an enum type with members is equivalent to the union of literals of all its members, so `Answer` <: `Literal[Answer.Yes, Answer.No]` exactly when `Yes`/`No` are ALL of `Answer`'s members; a partial member union is not a supertype. Membership follows the `Enum` metaclass's own rules: unannotated class-body value assignments, excluding sunder/dunder names and `nonmember`/descriptor/lambda values. Implemented by `rules/assignment_compatibility/enum_expand.rs`. + +> **Authority**: [Typing spec — Enums](https://typing.python.org/en/latest/spec/enums.html). ### [TYPEINF-SUBTYPING-CALLABLE] Callable Subtyping {#TYPEINF-SUBTYPING-CALLABLE} @@ -898,6 +903,8 @@ Subtyping is decided by `InferredType::is_assignable_to(&self, other)` in `crate - Bidirectional element compatibility (invariance, with gradual `Any`/`Unknown` consistency) for mutable `list`/`set`/`dict`; fixed-length, homogeneous `tuple[X, ...]`, and PEP 646 unpacked (`*tuple[...]`/`*Ts`) tuple matching ([TYPEINF-SUBTYPING-GENERIC](#TYPEINF-SUBTYPING-GENERIC), [TYPEINF-COLLECTIONS-TUPLES](#TYPEINF-COLLECTIONS-TUPLES)). - Callable contravariant parameters / covariant return, with `...` params gradual ([TYPEINF-SUBTYPING-CALLABLE](#TYPEINF-SUBTYPING-CALLABLE)); `TypeForm` covariance. +Module-context equivalences that `is_assignable_to` cannot see run as ordered rescues in `rules/assignment_compatibility` after it returns false: expected-type literal-collection checking, the enum literal expansion (`enum_expand.rs`, needing the module's enum-member environment), then callable-signature rescue — all over the skip/alias/schema environment built once per module by `skip_names::SkipNames::collect`. + `Named` types (user classes and unparameterised imports) compare by base name before `[`: `Foo[int]` and `Foo[float]` are treated as compatible. This is deliberate — without whole-program generic variance analysis, stricter matching would emit false positives, and the conformance gate holds `max_false_positives` at zero. Nominal MRO walking and structural Protocol/TypedDict compatibility are decided today by the per-conformance-area rule modules (`rules/protocols_*`, `rules/typeddicts_*`, and the class-bases-walking `is_subtype_of` helper in `rules/generics_basic_3/helpers.rs`). The shared home now exists — `crates/basilisk-checker/src/subtyping.rs` (`SubtypingContext`: cycle-guarded nominal walk, structural Protocol satisfaction, `TypedDict` schemas, declared variance, `Callable` kinds) — and the rule modules migrate onto it behind the parity pins in `tests/subtyping_context_tests.rs` and the in-module `helper_parity_tests` at the Integration stage ([NARROWPLAN-SUBTYPING](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUBTYPING)). diff --git a/docs/specs/ZED-SPEC.md b/docs/specs/ZED-SPEC.md index 6dfdb956..c4bdb576 100644 --- a/docs/specs/ZED-SPEC.md +++ b/docs/specs/ZED-SPEC.md @@ -13,7 +13,7 @@ Zed extensions are Rust compiled to WASM with a deliberately narrow API: | Capability | Available | Mechanism | |---|---|---| | LSP integration | Yes | `language_server_command()` on Extension trait | -| Tree-sitter grammars | Yes | `languages/` directory with `.scm` queries | +| Tree-sitter grammars | Yes, but unused | A `languages/` dir would *replace* Zed's built-in Python, not extend it — see [ZED-TREESITTER](#ZED-TREESITTER) | | DAP debugging | Yes | `get_dap_binary()` on Extension trait | | Slash commands | Yes | `run_slash_command()` on Extension trait | | Themes | Yes | `themes/` directory | @@ -72,20 +72,14 @@ basilisk-zed/ logic_tests.rs # Unit tests for logic.rs; #[path]-included as `mod tests` tests/ fixtures/ # Python sample files (clean, type_error, completions) - languages/ - python/ - config.toml - highlights.scm # tree-sitter-python queries - brackets.scm - outline.scm - indents.scm - injections.scm - textobjects.scm - runnables.scm + themes/ + basilisk-dark.json debug_adapter_schemas/ basilisk-debug.json ``` +No `languages/` directory — the extension binds to Zed's built-in Python language rather than shadowing it. See [ZED-TREESITTER](#ZED-TREESITTER). + ### `extension.toml` {#ZED-EXTTOML} ```toml @@ -97,7 +91,7 @@ authors = ["Basilisk Contributors"] description = "Strict-by-default Python type checker with debugging and profiling" repository = "https://github.com/Nimblesite/Basilisk" -# No [grammars.python] block — reuses Zed's built-in tree-sitter-python grammar. See [ZED-GRAMMAR]. +# No [grammars.python] block and no languages/ dir — binds to Zed's built-in Python. See [ZED-GRAMMAR]. [language_servers.basilisk] name = "Basilisk" @@ -277,25 +271,19 @@ Three mechanisms: 2. **Slash Commands** — `/profile` and `/profstop` via the AI assistant panel. 3. **External Viewer** — LSP generates speedscope JSON and opens it in the browser. -### Tree-sitter Queries {#ZED-TREESITTER} +### Language Reuse {#ZED-TREESITTER} -The extension ships tree-sitter-python queries: +The extension ships **no** `languages/` directory and **no** tree-sitter queries. Syntax highlighting, brackets, outline, indents, injections, textobjects, and runnables all come from Zed's built-in Python language, untouched. -- **highlights.scm** — syntax highlighting (keywords, builtins, decorators, f-strings, type annotations) -- **brackets.scm** — `()`, `[]`, `{}`, string quotes -- **outline.scm** — functions, classes, methods for the outline panel -- **indents.scm** — indentation-based structure -- **injections.scm** — SQL in strings, regex, docstring formatting -- **textobjects.scm** — Vim motions for functions, classes, arguments, comments -- **runnables.scm** — detect `if __name__ == "__main__"` and pytest functions for run buttons +This is not a gap — it is the only correct shape. Zed keys languages by name, and `LanguageRegistry::register_language` → [`AvailableLanguages::register`](https://github.com/zed-industries/zed/blob/main/crates/language/src/available_languages.rs) **overwrites** an existing entry's `grammar`, `matcher`, and `load` on a name collision rather than merging with it. Extensions load after the built-ins, so a `languages/python/config.toml` declaring `name = "Python"` does not augment Zed's Python — it *replaces* it wholesale, and everything the extension's config omits is simply lost: bracket auto-close, the f-/b-/r-/t-string and triple-quote pairs, `block_comment`, `autoclose_before`, `first_line_pattern` shebang detection, `modeline_aliases`, `increase_indent_pattern` / `decrease_indent_patterns` (`elif`/`else`/`except`/`finally` auto-dedent), and `debuggers = ["Debugpy"]` — plus a downgrade from Zed's 376-line `highlights.scm` and 108-line `runnables.scm` to whatever the extension bundles. -Zed already ships built-in Python support; these queries augment it (or the extension can rely on the built-in queries entirely and provide only LSP/DAP). +Every Python language-server extension in the registry — [`ty`](https://github.com/zed-extensions/ty), [`pyrefly`](https://github.com/zed-extensions/pyrefly), [`pylsp`](https://github.com/rgbkrk/python-lsp-zed-extension) — ships manifest and `src/` only, for this reason. Basilisk matches them. ### Grammar Reuse {#ZED-GRAMMAR} -`extension.toml` omits `[grammars.python]`; `languages/python/config.toml` declares `grammar = "python"`, which Zed resolves to its **built-in** tree-sitter-python grammar that the query files above augment. +`extension.toml` omits `[grammars.python]` and declares only `[language_servers.basilisk] languages = ["Python"]`, which binds the server to Zed's **built-in** Python language and its tree-sitter-python grammar by name. -Bundling `[grammars.python]` would force Zed to compile the grammar from source on install, requiring the multi-hundred-megabyte [`wasi-sdk`](https://github.com/WebAssembly/wasi-sdk/releases) toolchain — an extraction that can fail on a constrained disk (`No space left on device`) and surface as the misleading `failed to compile grammar 'python'`. Reusing the built-in grammar removes the compile step. Implemented in `basilisk-zed/extension.toml` (absence of `[grammars.*]`). +Bundling `[grammars.python]` would force Zed to compile the grammar from source on install, requiring the multi-hundred-megabyte [`wasi-sdk`](https://github.com/WebAssembly/wasi-sdk/releases) toolchain — an extraction that can fail on a constrained disk (`No space left on device`) and surface as the misleading `failed to compile grammar 'python'`. Binding by name removes the compile step. Implemented in `basilisk-zed/extension.toml` (absence of `[grammars.*]` and of `languages/`). ## Binary Distribution {#ZED-DIST} @@ -406,6 +394,6 @@ The LSP produces all underlying data; only visualization differs. | Binary resolution | Per-editor | `vscode-extension/src/extension.ts` / `basilisk-zed/src/lib.rs` | | Debug config UI | Per-editor | `package.json` / `basilisk-debug.json` | | Flamegraph rendering | Per-editor | VS Code webview / browser fallback | -| Tree-sitter queries | Zed-only | `basilisk-zed/languages/python/` | +| Tree-sitter queries | Neither — Zed's built-in Python owns them ([ZED-TREESITTER](#ZED-TREESITTER)) | — | The entire backend is shared; only thin editor-specific glue differs. Remaining cross-editor work is tracked in the [roadmap](../plans/ROADMAP-NEXT-STEPS-PLAN.md). diff --git a/scripts/render-zed-mirror.sh b/scripts/render-zed-mirror.sh index 04483f65..8cdd4a8b 100755 --- a/scripts/render-zed-mirror.sh +++ b/scripts/render-zed-mirror.sh @@ -38,9 +38,11 @@ readonly COPY_ITEMS=( "extension.toml" "Cargo.toml" "README.md" + # README.md links to the Chinese translation with a *relative* href, so the + # mirror must carry it too or the published landing page has a dead link. + "README.zh.md" "LICENSE" "src" - "languages" "themes" "debug_adapter_schemas" "images" diff --git a/vscode-extension/README.md b/vscode-extension/README.md index f20261ed..999ef5dd 100644 --- a/vscode-extension/README.md +++ b/vscode-extension/README.md @@ -29,8 +29,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit 60df123), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/vscode-extension/README.zh.md b/vscode-extension/README.zh.md index 662f665e..3ee8aaa3 100644 --- a/vscode-extension/README.zh.md +++ b/vscode-extension/README.zh.md @@ -28,8 +28,8 @@

PEP 一致性 100.0% — 官方 - python/typing - 一致性套件（提交 60df123）141 项测试中通过 141 项， + python/typing + 一致性套件（提交 a2e6356）141 项测试中通过 141 项， 由真实的上游评分器在默认配置下对 wheel 安装的 CLI 评出。 我们以 python/typing@main 为目标，且分数只升不降。

diff --git a/website/src/_data/conformance_report.json b/website/src/_data/conformance_report.json index 88607792..2dc4424d 100644 --- a/website/src/_data/conformance_report.json +++ b/website/src/_data/conformance_report.json @@ -3,13 +3,13 @@ "upstream": { "repo": "python/typing", "ref": "main", - "sha": "60df123ccfe9ae0472b1409ef4a00d51ffc5d972", - "shortSha": "60df123", - "commitDate": "2026-08-01", + "sha": "a2e6356af2f609a7ab2330895477d0d08181a169", + "shortSha": "a2e6356", + "commitDate": "2026-08-03", "stale": false }, "calculator": { - "file": "python/typing@60df123:conformance/src/main.py", + "file": "python/typing@a2e6356:conformance/src/main.py", "sha256": "3cb2a27bfc689e89a541528f8bdaa8ed24ae8845ce048eaff69717ef0205b112", "bytes": 10810, "funcs": [ diff --git a/website/src/_data/rules.json b/website/src/_data/rules.json index 04a423ab..18f59856 100644 --- a/website/src/_data/rules.json +++ b/website/src/_data/rules.json @@ -717,7 +717,7 @@ "body": [ { "type": "text", - "html": "PEP 695 requires the RHS of a type statement to be a valid type expression. The same restrictions as TypeAlias (aliases_implicit) apply." + "html": "PEP 695 requires the RHS of a type statement to be a valid type expression. The RHS is validated **structurally** on the parsed ruff expression tree (issue #379 \u2014 substring matching both missed invalid forms and misfired on identifiers containing matched text): names, dotted names, X | Y unions, None, string forward references, and subscriptions of those are type expressions; every other expression form (literals, calls, lambdas, conditionals, comparisons, comprehensions, boolean operators) is not. Subscript arguments are never descended into \u2014 special forms like Literal..., Callable[..., X], and AnnotatedX, ... legitimately hold non-type expressions there." }, { "type": "code", @@ -5128,22 +5128,30 @@ "tags": [ "pep" ], - "summary": "Undefined variable used in a return statement", - "summaryHtml": "Undefined variable used in a return statement", + "summary": "Reference to a name with no visible definition", + "summaryHtml": "Reference to a name with no visible definition", "body": [ { "type": "text", - "html": "Flags any name referenced in a return expression \u2014 bare (return x), the base of an attribute/subscript chain (return x.y), a call argument, or the **callee of a call** (return x()) \u2014 that is not defined in scope. A name is considered defined if it is a parameter, a local assignment (=, for, with), a module-level function, class, variable, or import, an enclosing scope's binding, a cross-module imported symbol, or a builtin." + "html": "Flags any name referenced in a return expression \u2014 bare (return x), the base of an attribute/subscript chain (return x.y), a call argument, or the **callee of a call** (return x()) \u2014 that is not defined in scope. A name is considered defined if it is a parameter, a local assignment (=, for, with), a module-level function, class, variable, import, or PEP 695 type alias, an enclosing scope's binding, a cross-module imported symbol, or a builtin." + }, + { + "type": "text", + "html": "Also flags a class that lists **its own name among its bases** when no other binding of that name exists: a class name is not bound until its class statement completes, so class C(C) with no prior C is a guaranteed NameError at runtime (GitHub #398)." }, { "type": "code", "lang": "python", - "code": "def compute() -> int:\n return undefined_name # never defined \u2192 E0018\n return undefined_fn() # undefined callee \u2192 E0018" + "code": "def compute() -> int:\n return undefined_name # never defined \u2192 E0018\n return undefined_fn() # undefined callee \u2192 E0018\n\n\nclass Node(Node): # `Node` is unbound in its own bases \u2192 E0018\n pass" } ], "group": "Type System", "docsUrl": "https://www.basilisk-python.dev/errors/names_undefined", "references": [ + { + "label": "PEP 695", + "url": "https://peps.python.org/pep-0695/" + }, { "label": "Python language reference: Naming and binding", "url": "https://docs.python.org/3/reference/executionmodel.html#naming-and-binding" diff --git a/website/src/docs/install-zed.md b/website/src/docs/install-zed.md index 38d0e835..e9934e88 100644 --- a/website/src/docs/install-zed.md +++ b/website/src/docs/install-zed.md @@ -4,7 +4,7 @@ title: "Basilisk for Zed — Install & Use the Python Extension" description: "Install and use the Basilisk Python language server in the Zed editor. The matching binary downloads automatically with the extension — zero configuration, no separate install. Diagnostics, completions, debugging, and profiling." keywords: basilisk, zed, zed editor, python, language server, lsp, install, extension, debugging, profiling, slash commands date: 2026-02-28 -dateModified: 2026-03-31 +dateModified: 2026-08-04 author: The Basilisk Project eleventyNavigation: key: Zed @@ -18,13 +18,22 @@ Basilisk ships a native [Zed](https://zed.dev) extension that registers the Basi ## Install the extension -1. Open the extensions view: command palette (`Cmd+Shift+P`) → **zed: extensions** -2. Search for **Basilisk** -3. Click **Install** +Basilisk is **not yet listed in Zed's extension registry** — the [submission to `zed-industries/extensions`](https://github.com/zed-industries/extensions) is pending, so searching the extensions view for "Basilisk" will not find it. Install it directly instead; it takes one clone and one command-palette action. -That's it. Open a Python file and Basilisk is your language server. +1. Clone the extension repository: -> **Installing from source?** If you are working in a checkout of the repository, install it as a dev extension instead: command palette → **zed: install dev extension** → select the `basilisk-zed/` directory. Zed compiles the extension to WASM automatically — you never pre-build or copy a `.wasm` file. + ```sh + git clone https://github.com/Nimblesite/basilisk-zed.git + ``` + +2. Open the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) → **zed: install dev extension** +3. Select the cloned `basilisk-zed` directory + +Zed compiles the extension to WASM itself — you never pre-build or copy a `.wasm` file. Open a Python file and Basilisk is your language server. + +> **Working in the monorepo?** Select the `basilisk-zed/` directory of your [Basilisk](https://github.com/Nimblesite/Basilisk) checkout instead of cloning separately. `make package-zed` builds the extension and a local `basilisk` binary in one step. + +To update, `git pull` in the cloned directory and re-run **zed: install dev extension**. Once the registry listing lands, the extensions view will handle installs and updates for you. ## The binary comes with the extension diff --git a/website/src/zh/docs/install-zed.md b/website/src/zh/docs/install-zed.md index 89568fbf..74093e7f 100644 --- a/website/src/zh/docs/install-zed.md +++ b/website/src/zh/docs/install-zed.md @@ -5,7 +5,7 @@ description: 在 Zed 编辑器中安装并使用 Basilisk Python 语言服务器 keywords: basilisk, zed, zed编辑器, python, 语言服务器, lsp, 安装, 扩展, 调试, 性能分析, 斜杠命令 lang: zh date: 2026-02-28 -dateModified: 2026-03-31 +dateModified: 2026-08-04 --- # Zed 版 Basilisk @@ -14,13 +14,22 @@ Basilisk 提供了一个原生 [Zed](https://zed.dev) 扩展，为 Python 注册 ## 安装扩展 -1. 打开扩展视图：命令面板（`Cmd+Shift+P`）→ **zed: extensions** -2. 搜索 **Basilisk** -3. 点击 **Install** +Basilisk **尚未收录进 Zed 的扩展注册表**——向 [`zed-industries/extensions`](https://github.com/zed-industries/extensions) 的提交仍在进行中，因此在扩展视图中搜索“Basilisk”是找不到的。请改为直接安装；只需一次克隆和一个命令面板操作。 -就这样。打开一个 Python 文件，Basilisk 就是您的语言服务器。 +1. 克隆扩展仓库： -> **从源代码安装？** 如果您正在存储库的检出目录中工作，请改为将其安装为开发扩展：命令面板 → **zed: install dev extension** → 选择 `basilisk-zed/` 目录。Zed 会自动将扩展编译为 WASM——您永远不需要预构建或复制 `.wasm` 文件。 + ```sh + git clone https://github.com/Nimblesite/basilisk-zed.git + ``` + +2. 打开命令面板（`Cmd+Shift+P` / `Ctrl+Shift+P`）→ **zed: install dev extension** +3. 选择克隆下来的 `basilisk-zed` 目录 + +Zed 会自行把扩展编译为 WASM——您永远不需要预构建或复制 `.wasm` 文件。打开一个 Python 文件，Basilisk 就是您的语言服务器。 + +> **在 monorepo 中工作？** 直接选择 [Basilisk](https://github.com/Nimblesite/Basilisk) 检出目录下的 `basilisk-zed/`，无需另行克隆。`make package-zed` 会一步构建扩展和本地 `basilisk` 二进制文件。 + +要更新，请在克隆目录中执行 `git pull`，然后重新运行 **zed: install dev extension**。等注册表收录完成后，扩展视图就会为您处理安装和更新。 ## 二进制文件随扩展一同提供 From d1764e62313f1706fd55ba5f5566e7c3a82e9f75 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 17:19:22 +1000 Subject: [PATCH 08/45] Fixes --- .../src/rules/directives_cast.rs | 6 +- .../tests/checker/directives_cast_tests.rs | 117 ++++++++++++++++++ .../src/scope/resolved_module.rs | 6 + .../src/visitor/cast_calls.rs | 63 ++++++++++ crates/basilisk-resolver/src/visitor/mod.rs | 4 + open_issues.csv | 65 ++++++++++ website/src/_data/rules.json | 4 + 7 files changed, 264 insertions(+), 1 deletion(-) create mode 100644 crates/basilisk-resolver/src/visitor/cast_calls.rs create mode 100644 open_issues.csv diff --git a/crates/basilisk-checker/src/rules/directives_cast.rs b/crates/basilisk-checker/src/rules/directives_cast.rs index 4a02f0bb..69d14357 100644 --- a/crates/basilisk-checker/src/rules/directives_cast.rs +++ b/crates/basilisk-checker/src/rules/directives_cast.rs @@ -9,6 +9,10 @@ //! actively requires — so only genuine non-string value literals are rejected //! (issue #335). //! +//! A `cast()` is invalid wherever it appears, so every expression position is +//! checked — `return cast(1, x)` and `print(cast(1, x))` are as wrong as +//! `y = cast(1, x)` (issue #335). +//! //! - `cast()` — too few arguments //! - `cast(1, x)` — first argument is a value literal, not a type //! - `cast("Widget", x)` — OK: string forward reference @@ -35,7 +39,7 @@ impl Rule for InvalidCastCall { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { - for call in module.calls.iter().filter(|c| c.callee == "cast") { + for call in &module.cast_calls { let arg_count = call.args.len(); if arg_count == 2 { // Exactly 2 args: reject a first argument that is a genuine value diff --git a/crates/basilisk-checker/tests/checker/directives_cast_tests.rs b/crates/basilisk-checker/tests/checker/directives_cast_tests.rs index fbf06a38..c7ae6e0c 100644 --- a/crates/basilisk-checker/tests/checker/directives_cast_tests.rs +++ b/crates/basilisk-checker/tests/checker/directives_cast_tests.rs @@ -49,6 +49,123 @@ y = cast(str, x) Ok(()) } +/// A `cast()` in return position is the same call in a different statement — +/// it must be validated identically. Part 2 of issue #335: the rule only ever +/// saw casts reachable from an assignment RHS, a bare expression statement, or +/// an `if` test, so `return cast(1, x)` went unchecked. +#[test] +fn cast_literal_first_arg_in_return_position_fires() -> Result<(), Box> { + let source = r" +from typing import cast + + +def f(x: object) -> int: + return cast(1, x) +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"directives_cast"), + "a value-literal cast in return position must fire directives_cast, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +/// Arity errors are position-independent too — `return cast(int, x, x)` is as +/// invalid as `y = cast(int, x, x)` (issue #335). +#[test] +fn cast_wrong_arity_in_return_position_fires() -> Result<(), Box> { + let source = r" +from typing import cast + + +def f(x: object) -> int: + return cast(int, x, x) +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"directives_cast"), + "a three-argument cast in return position must fire directives_cast, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +/// A `cast()` nested inside another call's arguments is never the outermost +/// expression of its statement, so the statement-level scan never reached it +/// (issue #335). +#[test] +fn cast_literal_first_arg_in_argument_position_fires() -> Result<(), Box> { + let source = r" +from typing import cast + + +def f(x: object) -> None: + print(cast(1, x)) +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"directives_cast"), + "a value-literal cast in argument position must fire directives_cast, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +/// Every invalid cast is reported exactly once, and reaching new positions must +/// not double-report the positions that already worked. Four invalid casts in +/// four distinct positions yield four diagnostics — no more, no fewer. +#[test] +fn every_invalid_cast_position_reported_exactly_once() -> Result<(), Box> { + let source = r" +from typing import cast + + +def f(x: object) -> int: + y = cast(1, x) + cast(2, x) + print(cast(3, x)) + return cast(4, x) +"; + let diags = run(source)?; + let cast_diags = codes(&diags) + .into_iter() + .filter(|c| *c == "directives_cast") + .count(); + assert_eq!( + cast_diags, + 4, + "four invalid casts in four positions must yield exactly four diagnostics, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +/// Widening the positions the rule sees must not make valid casts fire. Every +/// position exercised above, with a legal type expression, stays silent. +#[test] +fn valid_casts_in_all_positions_stay_silent() -> Result<(), Box> { + let source = r#" +from typing import cast + + +def f(x: object) -> int: + y = cast(int, x) + cast(str, x) + print(cast("int", x)) + for _ in range(cast(int, x)): + pass + return cast(int, y) +"#; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"directives_cast"), + "valid casts must stay silent in every statement position, got: {:?}", + codes(&diags) + ); + Ok(()) +} + /// A quoted string is a legal first argument to `cast()`: it is the standard /// forward-reference spelling, and typeshed admits it directly /// (`cast(typ: type[_T] | str | Any, val)`). Flagging it as a "value literal" diff --git a/crates/basilisk-resolver/src/scope/resolved_module.rs b/crates/basilisk-resolver/src/scope/resolved_module.rs index 2aed1fe6..03172da3 100644 --- a/crates/basilisk-resolver/src/scope/resolved_module.rs +++ b/crates/basilisk-resolver/src/scope/resolved_module.rs @@ -79,6 +79,12 @@ pub struct ResolvedModule { pub match_stmts: Vec, /// Module-level call sites (calls appearing in module-level expressions or assignments). pub calls: Vec, + /// Every `cast(...)` call site in the module, in **any** expression + /// position — `return cast(...)`, `f(cast(...))`, and nested expressions + /// included. `cast()` is invalid wherever it appears, so `directives_cast` + /// needs a complete view that [`Self::calls`] deliberately does not give + /// (issue #335). + pub cast_calls: Vec, /// Module-level `TypeVar(...)` call sites. pub typevar_calls: Vec, /// All `reveal_type(...)` call sites found anywhere in the module. diff --git a/crates/basilisk-resolver/src/visitor/cast_calls.rs b/crates/basilisk-resolver/src/visitor/cast_calls.rs new file mode 100644 index 00000000..4997f030 --- /dev/null +++ b/crates/basilisk-resolver/src/visitor/cast_calls.rs @@ -0,0 +1,63 @@ +//! Implements call-site collection for [`directives_cast`]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-OWNERSHIP +//! +//! `typing.cast(typ, val)` is invalid wherever it appears — its arity and its +//! first argument do not become legal because the call sits in a `return` +//! instead of an assignment. The module-wide [`ResolvedModule::calls`] vector +//! deliberately records only the outermost call of a few statement kinds, which +//! left `return cast(1, x)` and `print(cast(1, x))` unchecked (issue #335). +//! +//! This collector walks **every** expression position in the module and records +//! each `cast(...)` it finds. It is scoped to `cast` on purpose: widening the +//! shared `calls` vector would change what every other call-site rule sees. +//! +//! [`ResolvedModule::calls`]: crate::scope::ResolvedModule::calls + +use ruff_python_ast::visitor::{walk_expr, Visitor}; +use ruff_python_ast::{Expr, Stmt}; + +use crate::scope::CallSite; + +use super::calls_and_reveal::call_site_from_expr; + +/// The name of the callee this collector records. Both the bare `cast(...)` +/// import spelling and the qualified `typing.cast(...)` spelling resolve to +/// this simple name in [`CallSite::callee`]. +const CAST: &str = "cast"; + +/// Collect every `cast(...)` call site in `stmts`, in any expression position. +/// +/// `source` is used only as a fast-path guard: a call to `cast` cannot exist in +/// a module whose text never contains that identifier, so the great majority of +/// modules skip the walk entirely and this collector costs one substring scan. +pub(super) fn collect_cast_calls(stmts: &[Stmt], source: &str) -> Vec { + if !source.contains(CAST) { + return Vec::new(); + } + let mut collector = CastCallCollector { out: Vec::new() }; + for stmt in stmts { + collector.visit_stmt(stmt); + } + collector.out +} + +struct CastCallCollector { + out: Vec, +} + +impl<'a> Visitor<'a> for CastCallCollector { + fn visit_expr(&mut self, expr: &'a Expr) { + if matches!(expr, Expr::Call(call) if is_cast_callee(&call.func)) { + self.out.extend(call_site_from_expr(expr)); + } + walk_expr(self, expr); + } +} + +/// Returns `true` for the callee of `cast(...)` or `.cast(...)`. +fn is_cast_callee(func: &Expr) -> bool { + match func { + Expr::Name(name) => name.id.as_str() == CAST, + Expr::Attribute(attr) => attr.attr.as_str() == CAST, + _ => false, + } +} diff --git a/crates/basilisk-resolver/src/visitor/mod.rs b/crates/basilisk-resolver/src/visitor/mod.rs index 205a553b..eadb0ae6 100644 --- a/crates/basilisk-resolver/src/visitor/mod.rs +++ b/crates/basilisk-resolver/src/visitor/mod.rs @@ -9,6 +9,7 @@ mod assert_narrow; mod assigns; mod call_return; mod calls_and_reveal; +mod cast_calls; mod class_info; mod class_info_ext; mod core; @@ -99,6 +100,7 @@ fn reclassify_generic_params( /// Intermediate container for collected analysis results. struct AnalysisResults { + cast_calls: Vec, reveal_type_calls: Vec, assert_type_calls: Vec, typeddict_calls: Vec, @@ -140,6 +142,7 @@ fn collect_analysis_results( isinstance_typeddict_spans.extend(typevar::collect_typevar_bound_typeddict_violations(stmts)); AnalysisResults { + cast_calls: cast_calls::collect_cast_calls(stmts, source), reveal_type_calls: calls_and_reveal::collect_reveal_type_calls(stmts), assert_type_calls: calls_and_reveal::collect_assert_type_calls_from_stmts(stmts, source), typeddict_calls: typeddict::collect_typeddict_calls(stmts), @@ -214,6 +217,7 @@ fn build_resolved_module( imports, match_stmts, calls, + cast_calls: results.cast_calls, typevar_calls, reveal_type_calls: results.reveal_type_calls, assert_type_calls: results.assert_type_calls, diff --git a/open_issues.csv b/open_issues.csv new file mode 100644 index 00000000..b153cd1c --- /dev/null +++ b/open_issues.csv @@ -0,0 +1,65 @@ +number,area,component,priority_labels,assignees,title,author,created_at,updated_at,comments,summary,url +218,abstract-refactor,refactor,spec-violation,,[REFACTOR-ABSTRACT-ALGO] abstract-method implementation ignores the MRO and the configurable body,MelbourneDeveloper,2026-06-28T03:44:21Z,2026-07-10T23:22:37Z,1,Spec: REFACTOR-ABSTRACT-ALGO / Spec says:,https://github.com/Nimblesite/Basilisk/issues/218 +221,autofix-adoption,refactor,spec-violation,,[AUTOFIX-ADOPTION-RULES] adoption auto-graduation never runs in production,MelbourneDeveloper,2026-06-28T03:44:26Z,2026-08-01T06:14:10Z,2,Spec: AUTOFIX-ADOPTION-RULES / Spec says:,https://github.com/Nimblesite/Basilisk/issues/221 +222,autofix-adoption,refactor,spec-violation,,[AUTOFIX-ADOPTION-FLOW] adopt skips the safe-autofix step and demotions are not applied on the normal publish path,MelbourneDeveloper,2026-06-28T03:44:27Z,2026-08-01T06:14:11Z,2,Spec: AUTOFIX-ADOPTION-FLOW / Spec says:,https://github.com/Nimblesite/Basilisk/issues/222 +244,cache,cache,,,[ANALYSIS-INCR-DEBOUNCE] file-watcher debounce drops earlier batches' reload targets instead of coalescing,MelbourneDeveloper,2026-07-01T22:12:10Z,2026-08-01T06:14:14Z,1,"Surfaced during adversarial verification of 210 (out of that issue's scope). / The trailing debounce for workspace/didChangeWatchedFiles uses abort-and-replace semantics: each incoming batch aborts any pending re-analysis task and schedules a fresh one (crates/basilisk-lsp/src/server/document.rs:302-307). The aborted task's reloadtargets are discarded, not coalesced — so if two separate didChangeWatchedFiles notifications for different files arrive within the 200 ms window (FILEWATCHERDEBOUNCEMS, crates/basilisk-lsp/src/server/mod.rs), the first file's re-analysis is silently dropped: its sourcehash check never runs and its diagnostics can go stale until some later event touches it.",https://github.com/Nimblesite/Basilisk/issues/244 +367,cache,cache,,,Persistent result cache is CLI-only: the VS Code Caching panel offers a setting that does nothing in the editor,abdushakoor12,2026-07-29T05:55:25Z,2026-08-01T06:13:42Z,1,"Summary / [tool.basilisk] cache = true turns on the persistent result cache for basilisk check / basilisk analyze only. The language server never reads or writes it, so toggling Project → Caching → ""Reuse results between runs"" in the VS Code configuration editor has no effect on anything the editor does.",https://github.com/Nimblesite/Basilisk/issues/367 +227,cli-exit-codes,cli,spec-violation,,[CHKARCH-CLI-EXITCODES] exit code 2 (configuration error) is never produced,MelbourneDeveloper,2026-06-28T03:44:35Z,2026-07-10T23:22:39Z,1,Spec: CHKARCH-CLI-EXITCODES / Spec says:,https://github.com/Nimblesite/Basilisk/issues/227 +384,cli-exit-codes,cli,high-priority;spec-violation,,"Unparseable files: text output drops them entirely, and a user syntax error exits 3 (Internal failure) masking exit 1",MelbourneDeveloper,2026-08-01T06:55:06Z,2026-08-01T06:55:06Z,0,A file Basilisk cannot parse is handled correctly in JSON and badly everywhere / else. Three separate defects share one cause: CheckOutcome::failures is a,https://github.com/Nimblesite/Basilisk/issues/384 +381,constructors-rule,type-checking,high-priority,,"constructors_call_init only fires when the constructor call is the outermost expression: C(1) caught, C(1).m() silent",MelbourneDeveloper,2026-08-01T01:00:38Z,2026-08-01T01:00:38Z,0,"Summary / constructorscallinit fires only when the constructor call is the outermost expression of a statement (or the RHS of an assignment). The moment the result is used — C(1).attr, C(1).method() — the arity check is skipped.",https://github.com/Nimblesite/Basilisk/issues/381 +291,cython,feature-req,,,feature req: support cython,asukaminato0721,2026-07-06T18:45:49Z,2026-08-01T06:13:43Z,1,"But the syntax is kind of diff, so don't know the work amount.",https://github.com/Nimblesite/Basilisk/issues/291 +47,distribution-install,packaging,,,Detect first-party / third-party package name collision (declared PyPI dep shadows local package),MelbourneDeveloper,2026-05-23T22:13:42Z,2026-08-01T06:13:45Z,1,"Summary / Basilisk should detect when a project declares a PyPI dependency whose distribution/import name collides with a first-party package shipped by the same project, and emit a diagnostic. This class of bug silently pulls an unrelated third-party package into the dependency graph (dependency confusion) and is invisible until something breaks at runtime — or never breaks but ships a supply-chain risk.",https://github.com/Nimblesite/Basilisk/issues/47 +370,distribution-install,packaging,,abdushakoor12,Auto-download vs install by cargo newer worked on ArchLinux,amerlyq,2026-07-29T22:30:33Z,2026-08-02T10:39:37Z,0," Install basilisk.nvim, empty ~/.cargo/bin, not even added to path. / Run nvim -- basilisk is downloaded into ~/.local/share/nvim/basilisk/v0.3x.0/...",https://github.com/Nimblesite/Basilisk/issues/370 +356,enum-rule,type-checking,,abdushakoor12,"calls_argument_type checks str.join arguments syntactically: 4 false positives on valid list displays, and a missed genuine error",abdushakoor12,2026-07-25T13:10:59Z,2026-07-25T15:14:18Z,0,"Summary / callsargumenttype checks built-in method arguments against the syntactic shape of the expression (RhsKind), not against its type. For str.join, the effect is a rule that is wrong in both directions: it rejects valid code whenever a list/tuple/set display contains anything other than a string literal, and it silently accepts a genuinely wrong argument.",https://github.com/Nimblesite/Basilisk/issues/356 +373,enum-rule,type-checking,,,[Module Explorer] Enum members are counted as untyped even though annotations are forbidden,rayliverified,2026-07-30T19:01:11Z,2026-08-02T10:27:14Z,1,"Summary / Module Explorer counts valid Enum/StrEnum members as untyped because they do not have explicit annotations. However, PEP 435 enum members are inferred from their assignments and must be left unannotated. Basilisk's own enumsmembers diagnostic correctly rejects the annotation that would otherwise satisfy the coverage metric.",https://github.com/Nimblesite/Basilisk/issues/373 +374,enum-rule,type-checking,,,Basilisk fails union-of-members/enum equivalency in some case.,tapetersen,2026-07-30T20:14:49Z,2026-08-03T21:07:51Z,1,"In typing spec at: [enum-literal-expansion](https://typing.python.org/en/latest/spec/enums.htmlenum-literal-expansion). / Likewise, a type checker should treat a complete union of all literal members as [equivalent](https://typing.python.org/en/latest/spec/glossary.htmlterm-equivalent) to the enum type:",https://github.com/Nimblesite/Basilisk/issues/374 +215,extract-refactor,refactor,spec-violation,,"[REFACTOR-EXTRACT-VAR-ALGO] occurrence matching is substring, not AST-structural",MelbourneDeveloper,2026-06-28T03:44:16Z,2026-07-10T23:22:35Z,1,Spec: REFACTOR-EXTRACT-VAR-ALGO / Spec says:,https://github.com/Nimblesite/Basilisk/issues/215 +216,extract-refactor,refactor,spec-violation,,[REFACTOR-EXTRACT-FUNC-EDGE] extract-function handles only a subset of the specified edge cases,MelbourneDeveloper,2026-06-28T03:44:18Z,2026-07-10T23:22:36Z,1,Spec: REFACTOR-EXTRACT-FUNC-EDGE / Spec says:,https://github.com/Nimblesite/Basilisk/issues/216 +289,hover,lsp,awaiting-reply;high-priority,abdushakoor12,hover on class don't have init hint,asukaminato0721,2026-07-06T18:42:11Z,2026-07-12T08:48:22Z,3,,https://github.com/Nimblesite/Basilisk/issues/289 +324,hover,lsp,critical;showstopper,MelbourneDeveloper,Basilisk ships no standard-library type information — stdlib recognition is name-only,abdushakoor12,2026-07-18T06:19:23Z,2026-08-01T15:09:14Z,3,"Problem / Basilisk contains no type information for the Python standard library. What we call stdlib ""resolution"" is a compile-time list of module names (built from typeshed's VERSIONS file into a phf set) whose only job is suppressing importsunresolved on lines like import os. No stub content for any stdlib module exists anywhere in the product — a stdlib import resolves to no file (resolvedpath = None), so populateimportedsymbols skips it and every downstream consumer sees nothing.",https://github.com/Nimblesite/Basilisk/issues/324 +286,imports,imports,awaiting-reply,abdushakoor12,import statement highlight is wrong,asukaminato0721,2026-07-06T18:39:02Z,2026-07-25T01:09:22Z,4,"typing.cast(typ, val) must be called with exactly two positional arguments, and the first argument must be a type expression, not a value literal. A quoted first argument (cast("Widget", x)) is NOT a value literal \u2014 it is the standard PEP 484 forward-reference spelling, which typeshed admits directly (cast(typ: type_T | str | Any, val)) and which ruff's TC006 actively requires \u2014 so only genuine non-string value literals are rejected (issue #335)." }, + { + "type": "text", + "html": "A cast() is invalid wherever it appears, so every expression position is checked \u2014 return cast(1, x) and print(cast(1, x)) are as wrong as y = cast(1, x) (issue #335)." + }, { "type": "text", "html": "- cast() \u2014 too few arguments - cast(1, x) \u2014 first argument is a value literal, not a type - cast("Widget", x) \u2014 OK: string forward reference - cast(int, x, y) \u2014 too many arguments" From 07e0763f64b95e479b8544c139e7c36fb89fdb33 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 18:23:09 +1000 Subject: [PATCH 09/45] Update issues --- open_issues.csv => docs/open_issues.csv | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) rename open_issues.csv => docs/open_issues.csv (92%) diff --git a/open_issues.csv b/docs/open_issues.csv similarity index 92% rename from open_issues.csv rename to docs/open_issues.csv index b153cd1c..68f0b873 100644 --- a/open_issues.csv +++ b/docs/open_issues.csv @@ -58,8 +58,9 @@ number,area,component,priority_labels,assignees,title,author,created_at,updated_ 379,type-aliases-pep695,type-checking,critical,MelbourneDeveloper,"type-statement RHS validation is substring matching on source text, so most invalid type expressions pass silently",MelbourneDeveloper,2026-08-01T01:00:28Z,2026-08-03T21:07:44Z,1,"Summary / aliasestypestatement validates the RHS of a PEP 695 type X = ... statement by substring-matching the raw source text, not by walking the Ruff AST. Almost every invalid type expression that does not start with one of a handful of hard-coded prefixes passes silently.",https://github.com/Nimblesite/Basilisk/issues/379 383,type-aliases-pep695,type-checking,,,Non-regular recursive alias rejection uses the wrong rule code and misleading wording (should be an opt-in house rule),MelbourneDeveloper,2026-08-01T01:00:42Z,2026-08-01T01:00:42Z,0,"Summary / Non-terminating (non-regular / polymorphic) recursive type aliases are reported under genericssyntaxscoping with the message ""Circular type alias definition"". Rejecting them is a defensible engineering decision, but the code and the wording are both wrong, and neither is backed by the typing spec.",https://github.com/Nimblesite/Basilisk/issues/383 290,type-inference,type-checking,awaiting-reply;critical,abdushakoor12,does not infer generic type,asukaminato0721,2026-07-06T18:43:52Z,2026-08-03T21:07:48Z,6," int with body x * 2 draws nothing, as does a partial return (if x: return 1). mypy 1.19.1, pyright 1.1.408, ty 0.0.19 and pyrefly 0.54.0 all flag both; Basilisk is the only one of the five that is silent. Spec-mandated (None is not assignable to int), so default-on, not opt-in - but not exercised by the conformance suite, so it moves no score and must simply stay at 0 FP on the 147 fixtures. Structure: new resolver visitor terminates.rs adds FunctionInfo.body_falls_through via a real all-paths walk (the existing body_last_stmt_terminates only inspects the last statement and would false-positive on if/else where both branches return); new rule returns_implicit_none consumes it, excluding generators, stub/overload/abstractmethod/Protocol bodies, .pyi, and annotations that admit None. Analysis is biased toward silence - anything unmodelled reads as terminating. Definition-site twin of the unfixed half of 397; adjacent to 378.",https://github.com/Nimblesite/Basilisk/issues/401 284,unbound-analysis,type-checking,awaiting-reply,,False positive tuple-length complaint,JelleZijlstra,2026-07-06T16:22:21Z,2026-08-03T21:07:53Z,2,I get this error: / error[tuplesindex2]: Tuple index 2 is out of range for tuple of length 2,https://github.com/Nimblesite/Basilisk/issues/284 285,unbound-analysis,type-checking,awaiting-reply;critical,,"False positive ""returns `o` but `o` may be unbound on some paths""",JelleZijlstra,2026-07-06T16:25:35Z,2026-07-10T23:04:57Z,1,error[namesunbound]: Function occ returns o but o may be unbound on some paths / -- taxonomy/shell.py:2169:12,https://github.com/Nimblesite/Basilisk/issues/285 -397,uncategorised,uncategorised,,abdushakoor12,Clarification or help needed for a basic check,Hibou57,2026-08-02T20:45:36Z,2026-08-03T15:17:58Z,0,,https://github.com/Nimblesite/Basilisk/issues/397 398,uncategorised,uncategorised,,abdushakoor12,Hang on recursive class definition,correctmost,2026-08-03T05:52:14Z,2026-08-03T21:07:52Z,1,,https://github.com/Nimblesite/Basilisk/issues/398 276,website,docs,high-priority,,Docs: document the opt-in `strict-annotations` switch (and other opt-in rule toggles) in configuration reference,abdushakoor12,2026-07-06T06:25:06Z,2026-07-07T00:15:19Z,0,"Problem / The configuration reference (website/src/docs/configuration.md) tells users that stricter-than-spec rules are opt-in and to ""enable them when you want stricter-than-spec checking"" — but it never documents the key that actually enables them. There is no mention of strict-annotations (or the [tool.basilisk.uv] toggles) anywhere on the website.",https://github.com/Nimblesite/Basilisk/issues/276 From 1658cbcb6a7db6bc06f17399e40fd2d60a38f625 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 19:00:58 +1000 Subject: [PATCH 10/45] Integration prerequisite --- .../examples/narrow_walk_cost.rs | 117 ++++++++++++++++++ crates/basilisk-checker/src/bidir/engine.rs | 29 +++++ crates/basilisk-checker/src/bidir/mod.rs | 57 +++++++++ crates/basilisk-checker/src/narrow/flow.rs | 86 ++++++++----- .../src/narrow/reachability.rs | 7 +- .../tests/narrow_flow_tests.rs | 88 +++++++++++++ .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 117 +++++++++++------- 7 files changed, 425 insertions(+), 76 deletions(-) create mode 100644 crates/basilisk-checker/examples/narrow_walk_cost.rs diff --git a/crates/basilisk-checker/examples/narrow_walk_cost.rs b/crates/basilisk-checker/examples/narrow_walk_cost.rs new file mode 100644 index 00000000..571e0cc3 --- /dev/null +++ b/crates/basilisk-checker/examples/narrow_walk_cost.rs @@ -0,0 +1,117 @@ +//! Implements the [NARROWPLAN-INTEGRATION] cost measurement +//! (docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-INTEGRATION): +//! does one flow walk cost more as the surrounding MODULE grows? +//! +//! The walker's expression synthesis is seeded with the module's callable +//! interfaces. Rebuilding that seed per expression made a single function's +//! walk scale with the whole file's size — invisible to `make bench`, which +//! times `basilisk check` and never enters this code. This example is the +//! harness that made the cost visible, and the regression check for it: the +//! reported time must stay flat as `callables` grows. +//! +//! Usage (self-measured, methodology as stated — NOT a competitor comparison): +//! ```sh +//! cargo run --release -p basilisk-checker --example narrow_walk_cost +//! ``` +//! +//! The fixture is one function of `BRANCHES` guarded blocks, each containing a +//! call, an early `return`, and a list literal — so every walk drives the +//! divergence probe, the branch/complement machinery, and expression synthesis +//! many times over. The module around it holds N callables the function never +//! mentions. + +use std::collections::HashMap; +use std::fmt::Write as _; +use std::time::Instant; + +use basilisk_checker::narrow::{analyse_function_in, NarrowContext, NarrowEnv}; +use basilisk_checker::types::InferredType; +use ruff_python_ast::Stmt; + +/// Guarded blocks in the measured function. +const BRANCHES: usize = 60; + +/// Walks per measurement, averaged. +const REPEATS: u32 = 20; + +/// Module sizes to measure the walk against. +const MODULE_SIZES: [usize; 4] = [0, 100, 1_000, 5_000]; + +/// The measured function: `BRANCHES` narrowing blocks over two optionals. +fn fixture() -> Result { + let mut source = String::from("def f(x: int | None, y: str | None) -> int:\n"); + for index in 0..BRANCHES { + write!( + source, + " if x is None:\n a{index} = helper()\n return 0\n b{index} = [x, x]\n" + )?; + } + source.push_str(" return 1\n"); + Ok(source) +} + +fn main() -> Result<(), Box> { + let source = fixture()?; + + let parsed = basilisk_parser::parse_source(source.clone(), "cost.py".to_owned()) + .map_err(|error| format!("fixture must parse: {error}"))?; + let resolved = basilisk_resolver::resolve(&parsed) + .map_err(|error| format!("fixture must resolve: {error}"))?; + let function = resolved + .functions + .first() + .ok_or("fixture must contain one function")?; + + let reparsed = ruff_python_parser::parse_module(&source) + .map_err(|error| format!("fixture must reparse: {error}"))?; + let body = reparsed + .syntax() + .body + .iter() + .find_map(|stmt| match stmt { + Stmt::FunctionDef(def) => Some(def.body.to_vec()), + _ => None, + }) + .ok_or("fixture must contain one function body")?; + + let declared: HashMap = [ + ( + "x".to_owned(), + InferredType::Optional(Box::new(InferredType::Int)), + ), + ( + "y".to_owned(), + InferredType::Optional(Box::new(InferredType::Str)), + ), + ] + .into_iter() + .collect(); + + println!("fixture: {BRANCHES} guarded blocks, {REPEATS} walks averaged"); + for size in MODULE_SIZES { + let ctx = NarrowContext { + callables: (0..size) + .map(|index| (format!("unused{index}"), InferredType::Int)) + .collect(), + ..Default::default() + }; + let start = Instant::now(); + // Every walk is deterministic, so the last count IS the count — it is + // reported so a "faster" run that stopped narrowing cannot pass unseen. + let mut narrowed = 0; + for _ in 0..REPEATS { + let result = analyse_function_in( + &body, + NarrowEnv::new(declared.clone()), + &function.narrowing_guards, + &ctx, + ); + narrowed = result.narrowed_uses.len(); + } + println!( + "RESULT module_callables={size} per_walk={:?} narrowed_uses={narrowed}", + start.elapsed() / REPEATS, + ); + } + Ok(()) +} diff --git a/crates/basilisk-checker/src/bidir/engine.rs b/crates/basilisk-checker/src/bidir/engine.rs index 1fbf7b3f..860ed204 100644 --- a/crates/basilisk-checker/src/bidir/engine.rs +++ b/crates/basilisk-checker/src/bidir/engine.rs @@ -60,6 +60,35 @@ impl BidirEngine { solve(self.vars, self.constraints.into_vec()) } + /// [`BidirEngine::finish`] for one expression out of many: discharge the + /// constraints recorded since the last call and clear the solver state, + /// KEEPING the scope stack. + /// + /// A caller that synthesizes expression after expression against one set + /// of bindings (the flow walker, [NARROWPLAN-INTEGRATION]) would otherwise + /// have to rebuild those bindings for every expression. Resetting the + /// variables and constraints — rather than carrying them — keeps each + /// expression's solve independent, exactly as a fresh engine would, and + /// stops the constraint set growing without bound across the walk. + #[must_use] + pub fn solve_expression(&mut self) -> Solution { + let vars = std::mem::take(&mut self.vars); + let constraints = std::mem::take(&mut self.constraints); + solve(vars, constraints.into_vec()) + } + + /// Enter a nested binding scope, pre-populated, that shadows the ones + /// below it — the overlay form of [`BidirEngine::new`] for a caller whose + /// outer scopes are fixed for the whole run. + pub fn push_scope_with(&mut self, bindings: HashMap) { + self.scopes.push(bindings); + } + + /// Leave the innermost binding scope, dropping its bindings. + pub fn pop_scope(&mut self) { + let _ = self.scopes.pop(); + } + /// Allocate a fresh variable — the parameter-inference entry point /// (issue #317, [`crate::param_infer`]). pub fn fresh_param_var(&mut self, polarity: Polarity) -> super::tyvar::TyVarId { diff --git a/crates/basilisk-checker/src/bidir/mod.rs b/crates/basilisk-checker/src/bidir/mod.rs index affe367a..39702cd4 100644 --- a/crates/basilisk-checker/src/bidir/mod.rs +++ b/crates/basilisk-checker/src/bidir/mod.rs @@ -290,6 +290,63 @@ mod tests { let bad = check_and_solve("(1, \"x\")", &expected); assert_eq!(bad.errors.len(), 1, "{:?}", bad.errors); } + + /// [NARROWPLAN-INTEGRATION]: one reused engine must answer EXACTLY as a + /// fresh engine per expression. `solve_expression` resets the variables + /// and constraints in place, so neither the inferred type nor the error + /// set of a later expression can be contaminated by an earlier one — the + /// property that lets the flow walker keep a single engine alive. + #[test] + fn reused_engine_matches_a_fresh_engine_per_expression() { + let sources = ["[1]", "[\"x\", \"y\"]", "{1: \"a\"}", "len(z)", "[[1], [2]]"]; + + let fresh: Vec<(InferredType, usize)> = sources + .iter() + .map(|source| { + let (ty, solution) = synth_and_solve(source, HashMap::new()); + (ty, solution.errors.len()) + }) + .collect(); + + let mut engine = BidirEngine::new(HashMap::new()); + let reused: Vec<(InferredType, usize)> = sources + .iter() + .map(|source| { + let module = parse_expr(source); + let ty = engine.synth(&module.body); + let solution = engine.solve_expression(); + (ty.to_inferred(&solution.vars), solution.errors.len()) + }) + .collect(); + + assert_eq!(reused, fresh); + } + + /// [NARROWPLAN-INTEGRATION]: a pushed overlay shadows the scope beneath it + /// and is gone after the pop — the flow walker's per-expression binding + /// layer over a fixed module-callable scope. + #[test] + fn pushed_overlay_shadows_and_then_disappears() { + let module = parse_expr("value"); + let outer: HashMap = [("value".to_owned(), Ty::Ground(InferredType::Int))] + .into_iter() + .collect(); + let mut engine = BidirEngine::new(outer); + + engine.push_scope_with( + [("value".to_owned(), Ty::Ground(InferredType::Str))] + .into_iter() + .collect(), + ); + let shadowed = engine.synth(&module.body); + let solution = engine.solve_expression(); + assert_eq!(shadowed.to_inferred(&solution.vars), InferredType::Str); + + engine.pop_scope(); + let restored = engine.synth(&module.body); + let solution = engine.solve_expression(); + assert_eq!(restored.to_inferred(&solution.vars), InferredType::Int); + } } #[cfg(test)] diff --git a/crates/basilisk-checker/src/narrow/flow.rs b/crates/basilisk-checker/src/narrow/flow.rs index 136ac2c2..e4039ccf 100644 --- a/crates/basilisk-checker/src/narrow/flow.rs +++ b/crates/basilisk-checker/src/narrow/flow.rs @@ -21,7 +21,7 @@ use crate::types::InferredType; use super::env::NarrowEnv; use super::guards::{guard_outcomes_in, GuardOutcome}; -use super::reachability::{stmt_diverges, stmts_diverge}; +use super::reachability::stmt_diverges; use super::rebind::{bound_names, target_names}; /// One narrowed name-use site: the location and the type visible there. @@ -75,6 +75,16 @@ pub fn analyse_function_in( .map(|guard| ((guard.span.start, guard.span.end), guard)) .collect(), ctx, + // The module's callable interfaces convert to `Ty` ONCE, here, and + // stay in the engine's outermost scope for the whole walk + // ([NARROWPLAN-INTEGRATION]). + engine: BidirEngine::new( + ctx.callables + .iter() + .map(|(name, ty)| (name.clone(), Ty::from_inferred(ty))) + .collect(), + ), + diverges: HashMap::new(), result: FlowResult::default(), }; walker.walk_stmts(body); @@ -86,6 +96,14 @@ struct FlowWalker<'g> { env: NarrowEnv, guards_by_span: HashMap<(u32, u32), &'g NarrowingGuard>, ctx: &'g super::guards::NarrowContext, + /// One engine for the whole walk. Its outermost scope holds the module's + /// callable interfaces, converted once at construction; each synthesis + /// pushes only the currently-visible flow bindings on top and resets the + /// solver, so no per-expression cost scales with module size + /// ([NARROWPLAN-INTEGRATION]). + engine: BidirEngine, + /// Divergence answers by statement span — see [`FlowWalker::one_diverges`]. + diverges: HashMap<(u32, u32), bool>, result: FlowResult, } @@ -455,42 +473,50 @@ impl FlowWalker<'_> { /// binding — the SAME engine the definition-level queries run /// ([TYPEINF-TARGET-BIDIRECTIONAL]). /// - /// # Rebuild the seed BEFORE wiring this into a rule ([NARROWPLAN-INTEGRATION]) - /// - /// Every call clones the WHOLE module's callables plus a full - /// [`NarrowEnv::visible`] snapshot (itself `declared` + `scope` + every - /// open frame) into a fresh map, then discards the engine's solver state - /// via `finish()` — so per-expression cost scales with module size and - /// nothing amortizes. That is survivable only because the flow walker has - /// no production consumer yet and so no benchmark gate times it; the - /// plan makes fixing it a precondition for the first rule migration, - /// not a follow-up. Do not wire a rule to this without doing that first. - fn synth_type(&self, expr: &Expr) -> InferredType { - let mut globals: HashMap = self - .ctx - .callables - .iter() - .map(|(name, ty)| (name.clone(), Ty::from_inferred(ty))) + /// The callable seed lives in [`FlowWalker::engine`]'s outermost scope for + /// the whole walk; only the flow bindings — which are function-sized, not + /// module-sized — are pushed as an overlay per expression, and + /// [`BidirEngine::solve_expression`] resets the solver in place rather + /// than throwing the engine away. That is what makes the walker cheap + /// enough to sit behind a live rule ([NARROWPLAN-INTEGRATION]). + fn synth_type(&mut self, expr: &Expr) -> InferredType { + let overlay = self + .env + .visible() + .into_iter() + .map(|(name, ty)| (name, Ty::from_inferred(&ty))) .collect(); - for (name, ty) in self.env.visible() { - let _ = globals.insert(name, Ty::from_inferred(&ty)); - } - let mut engine = BidirEngine::new(globals); - let ty = engine.synth(expr); - let solution = engine.finish(); + self.engine.push_scope_with(overlay); + let ty = self.engine.synth(expr); + let solution = self.engine.solve_expression(); + self.engine.pop_scope(); ty.to_inferred(&solution.vars) } - /// Inference-driven divergence of a statement list. - fn body_diverges(&self, stmts: &[Stmt]) -> bool { - let mut synth = |expr: &Expr| self.synth_type(expr); - stmts_diverge(stmts, &mut synth) + /// Inference-driven divergence of a statement list: only its last + /// statement can carry control past the list. + fn body_diverges(&mut self, stmts: &[Stmt]) -> bool { + stmts.last().is_some_and(|last| self.one_diverges(last)) } - /// Inference-driven divergence of one statement. - fn one_diverges(&self, stmt: &Stmt) -> bool { + /// Inference-driven divergence of one statement, memoized by span. + /// + /// `walk_if` probes a body's divergence and then walks that same body, + /// whose `walk_stmts` probes each statement again — so without a memo the + /// same statements are re-synthesized once per enclosing branch. The memo + /// is keyed by span alone because the only two synthesis-dependent forms + /// are a call statement typed `Never` and a `while` test proven to be a + /// truthy literal, neither of which a narrowing frame can change. + fn one_diverges(&mut self, stmt: &Stmt) -> bool { + let range = stmt.range(); + let key = (u32::from(range.start()), u32::from(range.end())); + if let Some(&cached) = self.diverges.get(&key) { + return cached; + } let mut synth = |expr: &Expr| self.synth_type(expr); - stmt_diverges(stmt, &mut synth) + let answer = stmt_diverges(stmt, &mut synth); + let _ = self.diverges.insert(key, answer); + answer } /// Record every narrowed `Name` read inside `expr`. diff --git a/crates/basilisk-checker/src/narrow/reachability.rs b/crates/basilisk-checker/src/narrow/reachability.rs index 66ea96aa..6d4e215e 100644 --- a/crates/basilisk-checker/src/narrow/reachability.rs +++ b/crates/basilisk-checker/src/narrow/reachability.rs @@ -25,7 +25,12 @@ pub(crate) type SynthFn<'a> = dyn FnMut(&Expr) -> InferredType + 'a; /// Whether a statement list definitely diverges (control never reaches the /// statement after it). -pub(crate) fn stmts_diverge(stmts: &[Stmt], synth: &mut SynthFn<'_>) -> bool { +/// +/// Private to the recursion: the flow walker asks about a body through its own +/// memoized [`crate::narrow::flow`] entry point instead, so a probe and the +/// walk that follows it cannot re-synthesize the same expressions +/// ([NARROWPLAN-INTEGRATION]). +fn stmts_diverge(stmts: &[Stmt], synth: &mut SynthFn<'_>) -> bool { stmts.last().is_some_and(|last| stmt_diverges(last, synth)) } diff --git a/crates/basilisk-checker/tests/narrow_flow_tests.rs b/crates/basilisk-checker/tests/narrow_flow_tests.rs index d8bbbf52..4f90c1e6 100644 --- a/crates/basilisk-checker/tests/narrow_flow_tests.rs +++ b/crates/basilisk-checker/tests/narrow_flow_tests.rs @@ -907,3 +907,91 @@ def f(x: A | B) -> None: "with @final A, the complement must be B: {final_uses:?}" ); } + +/// [NARROWPLAN-INTEGRATION]: the module's callable interfaces are converted +/// once and held in the engine's outermost scope for the whole walk, so a +/// module full of callables the function never mentions must produce EXACTLY +/// the same narrowed uses and unreachable ranges as an empty module. This is +/// the correctness half of making the seed cheap: amortizing it must not let +/// module-level names leak into a function's flow types. +#[test] +fn unrelated_module_callables_never_change_the_walk() { + use basilisk_checker::narrow::{analyse_function_in, NarrowContext}; + use basilisk_checker::types::CallableInfo; + + // Nested branches so the divergence probe and the body walk ask about the + // same statements repeatedly — the memoized path. + let source = r" +def f(x: int | None, y: str | None) -> int: + if x is None: + if y is None: + return 0 + z = y + return 1 + w = x + return w +"; + let parsed = basilisk_parser::parse_source(source.to_owned(), "flow.py".to_owned()) + .expect("fixture parses"); + let resolved = basilisk_resolver::resolve(&parsed).expect("fixture resolves"); + let function = resolved.functions.first().expect("function"); + let declared: HashMap = [ + ( + "x".to_owned(), + InferredType::Optional(Box::new(InferredType::Int)), + ), + ( + "y".to_owned(), + InferredType::Optional(Box::new(InferredType::Str)), + ), + ] + .into_iter() + .collect(); + let reparsed = ruff_python_parser::parse_module(source).expect("reparses"); + let body = reparsed + .syntax() + .body + .iter() + .find_map(|stmt| match stmt { + Stmt::FunctionDef(def) => Some(def.body.clone()), + _ => None, + }) + .expect("body"); + + let empty_module = analyse_function_in( + &body, + NarrowEnv::new(declared.clone()), + &function.narrowing_guards, + &NarrowContext::default(), + ); + + let mut crowded = NarrowContext::default(); + for index in 0..500 { + let _ = crowded.callables.insert( + format!("unused{index}"), + InferredType::Callable(CallableInfo { + param_types: vec![], + return_type: Box::new(InferredType::Never), + }), + ); + } + let crowded_module = analyse_function_in( + &body, + NarrowEnv::new(declared), + &function.narrowing_guards, + &crowded, + ); + + assert_eq!( + crowded_module.narrowed_uses, empty_module.narrowed_uses, + "500 unmentioned module callables must not alter narrowing" + ); + assert_eq!( + crowded_module.unreachable_ranges, empty_module.unreachable_ranges, + "500 unmentioned module callables must not alter reachability" + ); + assert!( + !empty_module.narrowed_uses.is_empty(), + "the fixture must actually narrow something, or it proves nothing" + ); +} diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index 88c82db8..c832ad6c 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -269,45 +269,73 @@ limbo by **wiring them up here**, never by deleting them and never by suppressing a lint — each stays `pub` from the crate root, which is what keeps the workspace's `dead_code = "deny"` satisfied without an `#[allow]`. -**The flow walker's synthesis path is UNTIMED until it is wired, and must be -made cheap BEFORE the first rule consumes it.** The same staging that keeps -these cores off live diagnostics also keeps them off every performance gate: -`narrow::analyse_function_in` is reached only through the `narrowed_uses` -Salsa query, whose sole callers today are tests and +**The flow walker's synthesis path stays UNTIMED until it is wired, so it was +made cheap BEFORE the first rule consumed it — DONE.** The same staging that +keeps these cores off live diagnostics also keeps them off every performance +gate: `narrow::analyse_function_in` is reached only through the +`narrowed_uses` Salsa query, whose sole callers today are tests and `examples/ift_measure.rs`. `make bench` times `basilisk check`, which never enters this code — so no ratchet is watching it, and a cost that small -fixtures hide will land as a *regression on the first wiring change*, when -the zero-tolerance benchmark gate ([CHKARCH-TESTING-BENCH-RATCHET](../specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-TESTING-BENCH-RATCHET)) +fixtures hide would have landed as a *regression on the first wiring change*, +when the zero-tolerance benchmark gate ([CHKARCH-TESTING-BENCH-RATCHET](../specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-TESTING-BENCH-RATCHET)) is suddenly live over it and the change is also carrying diagnostic risk. -The known cost is in `FlowWalker::synth_type` (`narrow/flow.rs`), called per +The cost was in `FlowWalker::synth_type` (`narrow/flow.rs`), called per assign/ann-assign RHS, per `for` iterable, per bare-expression statement and -per `while` test. Each call: - -- rebuilds a fresh `HashMap` from **the entire module's** - `ctx.callables` (production seeds this from `callable_interface` for the - whole file), then -- extends it with `NarrowEnv::visible()`, which itself clones `declared` + - `scope` + every open frame, then -- constructs a fresh `BidirEngine` and calls `finish()`, discarding all - solver state so nothing amortizes. - -Per-expression work therefore scales with module size, making the total -scale as roughly function-size × module-size. Compounding it, divergence is -probed and then re-walked: `walk_if` calls `body_diverges(&node.body)` and -then walks that same body, whose `walk_stmts` re-runs `one_diverges` on each -statement, so nested control flow re-synthesizes the same expressions. -(Frequency is bounded — `stmts_diverge` probes only `stmts.last()`, and -`stmt_diverges` synthesizes only for `Stmt::Expr` and a `while` test — so the -defect is cost-per-call and redundancy, not call count.) - -Required before wiring, as a gate and not a follow-up: convert -`ctx.callables` to `Ty` **once** at walker construction; hold one long-lived -`BidirEngine` and push/pop the visible-binding overlay instead of rebuilding -it; and memoize divergence per statement so the probe/walk overlap cannot -re-synthesize. Fixing it while the component still has no consumers is -strictly cheaper — there is no caller to break, no diagnostic to hold steady, -and no conformance run to re-certify. +per `while` test. Every call rebuilt a fresh `HashMap` from **the +entire module's** `ctx.callables` (production seeds this from +`callable_interface` for the whole file), extended it with +`NarrowEnv::visible()`, constructed a fresh `BidirEngine`, and threw all +solver state away via `finish()` — so per-expression work scaled with module +size and the total scaled as roughly function-size × module-size. Divergence +compounded it: `walk_if` probed `body_diverges(&node.body)` and then walked +that same body, whose `walk_stmts` re-probed each statement, re-synthesizing +the same expressions once per enclosing branch. + +All three fixes have landed: + +- `ctx.callables` converts to `Ty` **once**, in `analyse_function_in`, and + stays in the engine's outermost scope for the whole walk. +- The walker holds **one** `BidirEngine`. Each expression pushes only the + visible flow bindings (function-sized, not module-sized) with + `BidirEngine::push_scope_with`, then resets the solver in place with + `BidirEngine::solve_expression` rather than dropping the engine. The reset + is what keeps each expression's solve independent of its predecessors — + pinned by `bidir::tests::reused_engine_matches_a_fresh_engine_per_expression`, + which asserts a reused engine answers identically to a fresh one. +- `FlowWalker::one_diverges` memoizes by statement span, so the probe and the + walk that follows it cannot re-synthesize. Keying on span alone is sound + because the only synthesis-dependent divergence forms are a call statement + typed `Never` and a `while` test proven to be a truthy literal, neither of + which a narrowing frame can change. + +The harness that made the cost visible is committed as +`crates/basilisk-checker/examples/narrow_walk_cost.rs`, so the curve is +reproducible rather than asserted: + +```sh +cargo run --release -p basilisk-checker --example narrow_walk_cost +``` + +Self-measured (Apple silicon macOS, `--release`), one walk of a 60-branch +function against a synthetic module of N callables it never mentions, +averaged over 20 walks. The point is the *shape* of the curve, not the +absolute times, which are machine-specific: + +| module callables | before | after | +| --- | --- | --- | +| 0 | 581 µs | 470 µs | +| 100 | 957 µs | 462 µs | +| 1 000 | 3.96 ms | 484 µs | +| 5 000 | 18.02 ms | 606 µs | + +Cost was linear in module size and is now effectively flat; the residual +growth is the single construction-time conversion of the callable seed, +amortized over the whole walk. The harness also prints `narrowed_uses`, which +must stay at 179 — a "faster" walk that stopped narrowing is a regression, not +a win. Fixing this while the component still had no consumers was strictly +cheaper: no caller to break, no diagnostic to hold steady, no conformance run +to re-certify. ## Measurable targets {#NARROWPLAN-TARGETS} @@ -870,17 +898,16 @@ the conformance ratchets (100% / 0 false positives) at every step. ### Integration and acceptance -- [ ] **Blocks every item below.** Make `FlowWalker::synth_type` cheap before - any rule consumes `narrowed_uses` — see [NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION). - Today it rebuilds the whole module's callables map plus a full - `NarrowEnv::visible()` clone and a fresh `BidirEngine` **per expression**, so - per-expression cost scales with module size. Three concrete changes: - (a) convert `ctx.callables` to `Ty` once at walker construction, not per - call; (b) hold one long-lived `BidirEngine`, pushing/popping the - visible-binding overlay instead of rebuilding it; (c) memoize divergence per - statement so the `walk_if` probe-then-walk and the `walk_stmts` re-probe stop - re-synthesizing the same expressions. Land it while the walker still has no - production consumer: no caller to break, no diagnostic to hold steady. +- [x] **Blocked every item below.** `FlowWalker::synth_type` is cheap before + any rule consumes `narrowed_uses` — see [NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION) + for the measurements. All three changes landed with the walker still + unconsumed: (a) `ctx.callables` converts to `Ty` once at walker + construction; (b) one long-lived `BidirEngine` takes the visible-binding + overlay through `push_scope_with`/`pop_scope` and resets its solver through + `solve_expression`; (c) `one_diverges` memoizes by statement span, so the + `walk_if` probe-then-walk and the `walk_stmts` re-probe no longer + re-synthesize the same expressions. Cost went from linear in module size to + flat. - [ ] Record a `make bench` baseline on a fixture that actually exercises the flow walker **in the same change that first wires it**, so the walker stops being invisible to the ratchet the moment it starts costing real time. From c7d864d145d18cd9a495632cfff5196b88dcbc4e Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 19:20:21 +1000 Subject: [PATCH 11/45] Redirect the integration plan --- crates/basilisk-checker/src/bidir/mod.rs | 8 +- .../src/collection_inference.rs | 13 +- crates/basilisk-checker/src/inference.rs | 16 +- .../src/rules/shared/text_scan.rs | 9 +- crates/basilisk-checker/src/types_parsing.rs | 11 +- docs/INDEX.md | 4 +- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 199 ++++++++++++++---- docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md | 98 ++++++--- 8 files changed, 276 insertions(+), 82 deletions(-) diff --git a/crates/basilisk-checker/src/bidir/mod.rs b/crates/basilisk-checker/src/bidir/mod.rs index 39702cd4..21c5df89 100644 --- a/crates/basilisk-checker/src/bidir/mod.rs +++ b/crates/basilisk-checker/src/bidir/mod.rs @@ -298,7 +298,13 @@ mod tests { /// property that lets the flow walker keep a single engine alive. #[test] fn reused_engine_matches_a_fresh_engine_per_expression() { - let sources = ["[1]", "[\"x\", \"y\"]", "{1: \"a\"}", "len(z)", "[[1], [2]]"]; + let sources = [ + "[1]", + "[\"x\", \"y\"]", + "{1: \"a\"}", + "len(z)", + "[[1], [2]]", + ]; let fresh: Vec<(InferredType, usize)> = sources .iter() diff --git a/crates/basilisk-checker/src/collection_inference.rs b/crates/basilisk-checker/src/collection_inference.rs index 21661e22..65b800e0 100644 --- a/crates/basilisk-checker/src/collection_inference.rs +++ b/crates/basilisk-checker/src/collection_inference.rs @@ -1,8 +1,13 @@ -//! Implements [TYPEINF-COLLECTIONS] / [TYPEINF-EXCEEDS-CONTAINERS]. See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-COLLECTIONS -//! Collection type inference for lists, dicts, sets, and tuples. +//! ⚠️ LEGACY — condemned under [TYPEINF-LEGACY]. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-LEGACY. //! -//! [TYPEINF-EXCEEDS-CONTAINERS]: the union-of-element-types inference below is -//! unconditional — there is no loose mode and no switch to disable it. +//! [`RhsKind`]-shape collection inference. NOT the engine — container +//! synthesis lives in [`crate::bidir::BidirEngine`] with deferred +//! generalization ([TYPEINF-COLLECTIONS], [TYPEINF-TARGET-CONSTRAINTS]); no +//! new code may call into this module, and existing consumers are deleted per +//! [NARROWPLAN-INTEGRATION]. The behavior it still carries until then: +//! [TYPEINF-EXCEEDS-CONTAINERS] — union-of-element-types inference is +//! unconditional, no loose mode, no switch. use crate::inference::infer_rhs; use crate::types::InferredType; diff --git a/crates/basilisk-checker/src/inference.rs b/crates/basilisk-checker/src/inference.rs index 808731c1..202ec5fb 100644 --- a/crates/basilisk-checker/src/inference.rs +++ b/crates/basilisk-checker/src/inference.rs @@ -1,8 +1,14 @@ -//! Implements [TYPEINF-OVERVIEW], [TYPEINF-INFERRED], [TYPEINF-ALGO], -//! [TYPEINF-VARS], [TYPEINF-VARS-SIMPLE], and the shared predicates behind -//! [TYPEINF-REQUIRED] / [TYPEINF-EXCEEDS]. See -//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md. -//! Type inference engine for Basilisk. +//! ⚠️ LEGACY — condemned under [TYPEINF-LEGACY]. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-LEGACY. +//! +//! Syntactic [`RhsKind`] classification. NOT the inference engine — the +//! engine is [`crate::bidir::BidirEngine`] ([TYPEINF-ALGO], [TYPEINF-TARGET]), +//! and no new code may call into this module. Existing consumers are deleted +//! rule-by-rule per the demolition order in [NARROWPLAN-INTEGRATION] +//! (docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-INTEGRATION); +//! this module dies with its last caller. Still referenced for +//! [TYPEINF-VARS-SIMPLE] literal behavior and the [TYPEINF-REQUIRED] / +//! [TYPEINF-EXCEEDS] predicates until then. use crate::types::InferredType; use basilisk_resolver::{RhsKind, VariableInfo}; diff --git a/crates/basilisk-checker/src/rules/shared/text_scan.rs b/crates/basilisk-checker/src/rules/shared/text_scan.rs index 367ca04a..91ec5cb4 100644 --- a/crates/basilisk-checker/src/rules/shared/text_scan.rs +++ b/crates/basilisk-checker/src/rules/shared/text_scan.rs @@ -1,6 +1,11 @@ -//! Implements helpers for [CHKARCH-DIAG]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG +//! ⚠️ LEGACY — condemned under [TYPEINF-LEGACY]. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-LEGACY. +//! //! Source-text geometry, top-level splitting, and line tokenisation shared by -//! rules that scan annotation or source text. +//! rules that still scan annotation or source text ([CHKARCH-DIAG]). Text +//! scanning is not a type mechanism: types come from the engine +//! ([TYPEINF-ALGO]). No new code may call into this module — it is deleted +//! outright per [NARROWPLAN-INTEGRATION] when its last consumer migrates. use basilisk_resolver::Span; diff --git a/crates/basilisk-checker/src/types_parsing.rs b/crates/basilisk-checker/src/types_parsing.rs index f381c679..be921220 100644 --- a/crates/basilisk-checker/src/types_parsing.rs +++ b/crates/basilisk-checker/src/types_parsing.rs @@ -1,8 +1,11 @@ -//! Implements [TYPEINF-OVERVIEW]. See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-OVERVIEW -//! Annotation parsing for [`InferredType`]. +//! ⚠️ LEGACY — condemned under [TYPEINF-LEGACY]. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-LEGACY. //! -//! Converts Python annotation text (e.g. `"list[int]"`, `"Callable[[str], bool]"`) -//! into [`InferredType`] values. +//! Annotation-**string** parsing into [`InferredType`]. NOT the engine's +//! path — an annotation is a type expression resolved through the +//! [TYPEINF-ANNOTATION-RESOLUTION] cascade, never text a rule slices out of +//! the file. No new code may call into this module; existing consumers are +//! deleted per [NARROWPLAN-INTEGRATION], and this parser dies with them. use super::types::{CallableInfo, InferredType, LiteralValue}; diff --git a/docs/INDEX.md b/docs/INDEX.md index 3e62db78..d2316e91 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -14,7 +14,7 @@ linked to an active plan. | File | Purpose | |---|---| | [Checker architecture](specs/CHECKER-ARCHITECTURE-SPEC.md) | Configuration, rules, diagnostics, analysis pipeline, CLI, and quality gates. | -| [Type inference](specs/CHECKER-TYPE-INFERENCE-SPEC.md) | Expression/type inference and narrowing contracts, plus the target bidirectional/constraint architecture and its research grounding. | +| [Type inference](specs/CHECKER-TYPE-INFERENCE-SPEC.md) | The bidirectional/constraint inference engine — the checker's single type oracle — its narrowing contracts, research grounding, and the condemned legacy mechanisms under demolition. | | [Stub resolution](specs/CHECKER-STUB-RESOLUTION-SPEC.md) | Pinned typing-spec import order, custom typeshed, offline pin verification against the store, a PyPI-package wheel pin, the segregated download component, bundled stdlib ZIP, and generation. | | [Checker MCP service](specs/CHECKER-MCP-SPEC.md) | Packaged stdio lifecycle and the structured typeshed source/status tool. | | [Checker cache](specs/CHECKER-CACHE-SPEC.md) | Opt-in content-addressed cross-session result cache, its `[tool.basilisk]` keys, and how it differs from always-on Salsa memoization. | @@ -55,7 +55,7 @@ Plans contain only unfinished work. Delete a plan when its acceptance gate passe | [Formatting](plans/LSP-FORMATTING-PLAN.md) | VS Code default-formatter opt-in and published-artifact verification. | | [AI-assisted LSP](plans/LSP-AI-PLAN.md) | First opt-in provider slice and privacy/safety gate. | | [Activity panel](plans/EXTENSION-ACTIVITY-PANEL-PLAN.md) | Settings wiring, Modules-panel context menus and multi-select, and remaining cross-editor/test quality. | -| [Type narrowing and inference](plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md) | Annotation name resolution (Stage 0.5), bidirectional/constraint-based inference engine, flow analysis, shared subtyping, and PEP 827 readiness. | +| [Type narrowing and inference](plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md) | The engine build-out and the demolition order: wire the bidirectional engine into every rule, delete every legacy text/shape-matching path, hold the conformance and benchmark gates throughout. | | [Runtime typeshed resolution](plans/CHECKER-TYPESHED-RUNTIME-PLAN.md) | Two open items: a socket-instrumented witness that checking is offline across CLI/LSP/MCP, and byte-exact per-artifact licensing verification inside the VSIX (binaries and wheels are already verified). | | [PyPI typeshed package pin](plans/CHECKER-TYPESHED-PYPI-PLAN.md) | Pin a PyPI typeshed distribution by wheel SHA-256, verify offline, auto-resolve from `uv.lock`; suppresses the source-status advisory (issue #312). | | [Eliminate line scanning](plans/CHECKER-ELIMINATE-LINE-SCANNING-PLAN.md) | Replace remaining raw-source rule scans with AST data. | diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index c832ad6c..aa40ff6e 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -193,8 +193,11 @@ sites (issue #317). Collect lower, upper, constrained, default, and expected-return bounds for TypeVars; solve bounds deterministically and report ambiguity without -guessing. Cover constrained/bound TypeVars, PEP 696 defaults, ParamSpec, and -TypeVarTuple interactions before wiring the solver into rule decisions. +guessing. Constrained/bound TypeVars, PEP 696 defaults, ParamSpec, and +TypeVarTuple interactions are covered by the solver's pinning tests — the +solver reaches rule decisions through the demolition order in +[NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION), and any interaction found +uncovered on the way is a test to add, never a reason to stall the wiring. Type variables carry explicit lower/upper bounds (like Pyright's type intervals and Pyrefly's `Var`) with the input/output polarity discipline @@ -208,11 +211,16 @@ type" and "might be more enjoyable" — Basilisk should ship it. ## Shared subtyping {#NARROWPLAN-SUBTYPING} -Build a context for nominal class relationships, Protocol members, TypedDict -schemas, generic variance, and Callable parameter kinds. Replace duplicated -rule-local subtype helpers only after parity tests pin their current -accepted/rejected cases. Keep `Any`/`Unknown` gradual behavior and the numeric -tower consistent across annotation parsing and inferred types. +`SubtypingContext` is the **only** subtyping judgment: nominal class +relationships, Protocol members, TypedDict schemas, generic variance, Callable +parameter kinds. The parity tables that once gated the rule-local helpers' +replacement are pinned (`tests/subtyping_context_tests.rs`) — the gate is +**satisfied and closed**. Every remaining rule-local subtype helper is +condemned ([TYPEINF-LEGACY](../specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-LEGACY)); +delete each by routing its callers through `SubtypingContext`, per the +demolition order in [NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION). +`Any`/`Unknown` gradual behavior and the numeric tower have one home each — +never a per-rule copy. ## Incrementality {#NARROWPLAN-INCREMENTAL} @@ -251,33 +259,128 @@ feature ships from this plan (see [NARROWPLAN-GOALS](#NARROWPLAN-GOALS)). ## Integration {#NARROWPLAN-INTEGRATION} -Introduce each shared component behind existing checker APIs; do not create an -alternate checking mode. Migrate assignment, return, call, and `assert_type` -rules incrementally, deleting the replaced local logic in the same change. Add -spec-ID-linked mutation-resistant tests for each migrated behavior. - -**A shared component with no production caller is on-plan, not dead code.** -Stage 2 deliberately lands each core *and its pinning tests* one change ahead -of the rules that consume it, because [NARROWPLAN-SUBTYPING] requires parity -tests to pin current accepted/rejected cases *before* any helper is replaced, -and [NARROWPLAN-CONSTRAINTS] requires the generic interactions to be covered -*before* the solver reaches rule decisions. Wiring earlier would put unproven -inference behind live diagnostics and risk the zero-false-positive gate. -`bidir::generics::GenericEnv` and `subtyping::SubtypingContext` are in exactly -that state now; both module headers record it. They are removed from this -limbo by **wiring them up here**, never by deleting them and never by -suppressing a lint — each stays `pub` from the crate root, which is what -keeps the workspace's `dead_code = "deny"` satisfied without an `#[allow]`. +### The mandate + +**The bidirectional engine is the checker's type oracle. Full stop.** + +There is exactly one component in this repository permitted to decide what +type an expression has: `bidir::BidirEngine`, driven through +`narrow::analyse_function_in` for flow-sensitive positions. Every rule that +needs a type asks it. No rule computes a type any other way. No rule keeps a +private opinion about a type "just for its case". No rule guesses from +punctuation. + +Every mechanism that currently decides a type by looking at *source text* or +at *syntactic shape* is legacy. Legacy code is not maintained here, not +tolerated here, and not migrated around — it is **deleted**, in the same +change that replaces it, by the engineer doing the replacing. A change that +routes a rule through the engine while leaving the old path breathing next to +it is **not done and must not merge**. + +### The demolition list + +Measured on this checkout — reproduce with `grep -rln +crates/basilisk-checker/src/rules | wc -l`: + +| Legacy mechanism | Rule files | Verdict | +| --- | --- | --- | +| `slice_span` — cutting the annotation out of the source as a **string** | 86 | DELETE | +| `RhsKind` — branching on the syntactic *shape* of a right-hand side | 26 | DELETE | +| `InferredType::from_annotation` over source text — a type parser that is not the parser | 14 | DELETE | +| `rules/shared/text_scan.rs` — hand-rolled character scanning (151 LOC) | shared | DELETE | +| Direct `name_subtype`/`is_numeric_subtype` calls bypassing `subtyping::SubtypingContext` | 22 call sites in 12 files | DELETE | + +Out of 172 rule modules. That is the floorboard count. Every one of those call +sites is a rule that today answers a type question by reading characters +instead of asking the engine, and every one of them is a place a real program +gets checked wrong. `assignment_compatibility` is the flagship: it fires on +literal right-hand sides and stays **silent on every call right-hand side**, +which is why `a: int = returns_str()` passes today (Refs #397). + +This also finishes [LINESCANPLAN-ELIMINATION](CHECKER-ELIMINATE-LINE-SCANNING-PLAN.md#LINESCANPLAN-ELIMINATION) +by removing the *reason* line scanning exists, not just its call sites. + +### There is no obstacle — stop pretending there is + +Every piece needed to do this is already built, already tested, and already +reachable from inside a `Rule::check`: + +- `rules::shared::parse_module(module)` (`rules/shared.rs:52`) hands any rule + the module's AST, parsed once and shared through `ResolvedModule::lazy_ast`. +- `narrow::analyse_function_in` returns flow-narrowed types and + inference-driven unreachability for a function body. +- `BidirEngine::synth` / `check` type any expression bidirectionally, and + `synth_call` already resolves call returns — the exact thing + `assignment_compatibility` fails to do. +- `bidir::generics::GenericEnv` and `subtyping::SubtypingContext` are built, + pinned by tests, and waiting. + +Nothing is missing. The only thing that ever held this back was the staging +discipline written in this very section, and the cost defect that discipline +existed to protect against — which is now fixed and measured below. **The +protection has expired. Wire it in.** + +`GenericEnv` and `SubtypingContext` leave limbo by being **wired up**, never by +being deleted and never by an `#[allow]` — each stays `pub` from the crate +root, which is what keeps the workspace's `dead_code = "deny"` satisfied. + +### What is NOT on the demolition list — read this before touching anything + +Ripping out legacy *mechanism* is mandatory. Weakening the *checker* is +forbidden, and nothing in this section licenses it: + +- **Never delete, disable, or unregister a rule.** Not one. The rule survives; + its guts get replaced. See [CHKARCH-CONFORMANCE]. +- **Never remove a diagnostic.** Post-migration output is identical or + strictly better — same code, same span, same or clearer message. +- **Never touch the scoreboard.** 100% / 0 false positives against a freshly + cloned `python/typing` harness is the prime directive and outranks this + entire plan. A migration that drops the number is reverted, not negotiated. +- **Never add an alternate checking mode**, feature flag, or "new engine" + toggle. There is one code path. Basilisk has no modes. + +If replacing a rule's guts costs a required error, the engine is not ready for +that rule yet — **fix the engine**, then come back. Do not ship the loss. + +### Order of demolition + +Each step is one change: wire the rule to the engine, delete the legacy path +it replaces, land the spec-ID-linked mutation-resistant tests, re-certify. + +1. `assignment_compatibility` — the biggest liar in the tree. Every call RHS + goes through `synth_call`; `RhsKind` shape-matching dies here first. +2. `returns_compatibility` / `returns_compatibility_2` — the returned + expression is synthesized, not pattern-matched. +3. `calls_argument_type` — arguments checked against parameters through + `SubtypingContext`, not through per-rule string comparison. +4. `directives_assert_type` / `directives_reveal_type` — these must agree with + hover, byte for byte, because they are now the same oracle. +5. The remaining 80-odd `slice_span` consumers, in descending call-site count, + until the grep returns zero. + +### Gates that stay armed the entire time + +Non-negotiable, every step, no exceptions: + +- Live conformance run: **100% / 0 FP**, freshly cloned harness + ([CHKARCH-CONFORMANCE-MODE]). +- `make bench`: no fixture slower than the committed baseline + ([CHKARCH-TESTING-BENCH-RATCHET]). The walker is real production cost the + moment step 1 lands — record the baseline **in that same change**. +- `make test` fail-fast, coverage ratchet up, mutation ratchet up. +- Torture golden gate green. + +### The cost defect that blocked all of this — FIXED **The flow walker's synthesis path stays UNTIMED until it is wired, so it was made cheap BEFORE the first rule consumed it — DONE.** The same staging that -keeps these cores off live diagnostics also keeps them off every performance +kept these cores off live diagnostics also kept them off every performance gate: `narrow::analyse_function_in` is reached only through the `narrowed_uses` Salsa query, whose sole callers today are tests and -`examples/ift_measure.rs`. `make bench` times `basilisk check`, which never -enters this code — so no ratchet is watching it, and a cost that small -fixtures hide would have landed as a *regression on the first wiring change*, -when the zero-tolerance benchmark gate ([CHKARCH-TESTING-BENCH-RATCHET](../specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-TESTING-BENCH-RATCHET)) +`examples/`. `make bench` times `basilisk check`, which never enters this code +— so no ratchet was watching it, and a cost that small fixtures hide would +have landed as a *regression on the first wiring change*, when the +zero-tolerance benchmark gate ([CHKARCH-TESTING-BENCH-RATCHET](../specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-TESTING-BENCH-RATCHET)) is suddenly live over it and the change is also carrying diagnostic risk. The cost was in `FlowWalker::synth_type` (`narrow/flow.rs`), called per @@ -911,13 +1014,37 @@ the conformance ratchets (100% / 0 false positives) at every step. - [ ] Record a `make bench` baseline on a fixture that actually exercises the flow walker **in the same change that first wires it**, so the walker stops being invisible to the ratchet the moment it starts costing real time. -- [ ] Introduce each shared component behind existing checker APIs; do not - create an alternate checking mode. -- [ ] Migrate assignment, return, call, and `assert_type` rules incrementally, - deleting the replaced local logic in the same change. +- [ ] **Wire `assignment_compatibility` to the engine and delete `RhsKind` + shape-matching from it in the same change.** Every right-hand side — + literal, call, constructor, method, variable — is typed by + `BidirEngine::synth`, narrowed by `narrow::analyse_function_in`, and judged + by `SubtypingContext`. `a: int = returns_str()` must fire (Refs #397). This + is step one and it is not optional. +- [ ] Migrate `returns_compatibility` / `returns_compatibility_2`, + `calls_argument_type`, and `directives_assert_type` / + `directives_reveal_type` — each one change, each deleting the legacy path it + replaces, each re-certified at 100% / 0 FP. +- [ ] Drive `grep -rln slice_span crates/basilisk-checker/src/rules | wc -l` + from **86 to 0**. An annotation is a type expression the engine evaluates — + never a string a rule slices out of the file. +- [ ] Drive `RhsKind` (26 files) and `InferredType::from_annotation` over + source text (14 files) to **0**, and delete `rules/shared/text_scan.rs` + outright. +- [ ] Route all 22 direct `name_subtype`/`is_numeric_subtype` call sites (12 + files) through `subtyping::SubtypingContext` and delete the shims. One + subtyping implementation. Not two, not twenty-two. +- [ ] Delete every replaced code path **in the change that replaces it**. A + migration that leaves the legacy path alive alongside the new one is + incomplete and does not merge. +- [ ] Never create an alternate checking mode, engine flag, or opt-in switch + for any of this. One code path. Basilisk has no modes + ([CHKARCH-CONFIGURATION-ONLY]). +- [ ] Keep every rule registered and every diagnostic intact through the whole + demolition. The mechanism dies; the checking does not. A migration that + costs a required error means the engine is not ready — **fix the engine**, + never ship the loss ([CHKARCH-CONFORMANCE]). - [ ] Add spec-ID-linked mutation-resistant tests for each migrated behavior. - [ ] Verify hover/inlay results and checker diagnostics agree for the same - expression. + expression — byte for byte, because after this they are the same oracle. - [ ] `make test`, mutation/coverage ratchets, benchmarks for touched hot - paths, and the live 141/141 conformance gate all pass with zero false - positives. + paths, and the live conformance gate all pass with zero false positives. diff --git a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md index 584a0e66..c3be1543 100644 --- a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md +++ b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md @@ -1,10 +1,16 @@ # Basilisk type inference {#TYPEINF} -Basilisk combines conservative shared inference with focused typing-rule algorithms. The default configuration follows the typing specification; optional house rules can require or discourage annotations without changing PEP behavior (see [TYPEINF-REDUNDANT]). +Basilisk has **one** type oracle: the bidirectional inference engine +([TYPEINF-TARGET](#TYPEINF-TARGET)) — synthesis and checking over a +subtype-constraint solver, flow-narrowed by the statement-level walker. Every +type question in the checker is answered by that engine. The default +configuration follows the typing specification; optional house rules can +require or discourage annotations without changing PEP behavior (see +[TYPEINF-REDUNDANT]). > **Authoritative references**: [PEP 484](https://peps.python.org/pep-0484/), [PEP 526](https://peps.python.org/pep-0526/), [Python Typing Spec](https://typing.python.org/en/latest/spec/), [Python Typing Conformance Suite](https://github.com/python/typing/tree/main/conformance) > -> **Implementation**: Core inference engine (`inference.rs`, `collection_inference.rs`, `types.rs`, `types_parsing.rs`) is wired into rules E0011, E0013, E0014, E0120, and W0050. +> **Implementation**: the engine is `crates/basilisk-checker/src/bidir/` (synthesis, checking, constraints, solver, generics), `src/narrow/` (flow-sensitive narrowing and inference-driven reachability), and `src/subtyping.rs` (`SubtypingContext`). The pre-engine remnants (`inference.rs`, `collection_inference.rs`, `types_parsing.rs`, per-rule text matching) are **legacy under demolition** — see [TYPEINF-LEGACY](#TYPEINF-LEGACY); nothing in this spec licenses new code against them. --- @@ -73,15 +79,43 @@ defines the annotation as part of the construct. ### [TYPEINF-ALGO] Inference algorithm {#TYPEINF-ALGO} -The shared engine is conservative and primarily bottom-up: literal and -collection syntax produces an `InferredType`; unsupported expressions produce -`Unknown` rather than a guessed type. Expected-type and flow reasoning live in -focused rule/resolver paths, not in a general `infer_type(expr, expected)` -engine. Consolidating those paths is tracked in -[NARROWPLAN-INFERENCE](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-INFERENCE). -The target architecture that supersedes this conservative core — bidirectional -checking over a subtype-constraint solver — is specified in -[TYPEINF-TARGET](#TYPEINF-TARGET). +The algorithm is **bidirectional inference over a subtype-constraint solver**, +specified in full in [TYPEINF-TARGET](#TYPEINF-TARGET): `synth(e) → τ` infers +bottom-up, `check(e, τ)` propagates an expected type top-down, neither judges +subtyping directly — they record constraints a separate solver discharges. +Flow-sensitive positions go through the narrowing walker +([TYPEINF-TARGET-NARROWING](#TYPEINF-TARGET-NARROWING)), which drives the same +engine. Anything the engine cannot prove is `Unknown` — never a guess +([TYPEINF-TARGET-GRADUAL](#TYPEINF-TARGET-GRADUAL)). + +There is no second algorithm. Rule-local expected-type tricks, syntactic +right-hand-side classification, and annotation text matching are not +alternative inference strategies — they are legacy remnants under demolition +([TYPEINF-LEGACY](#TYPEINF-LEGACY)), and this section must never again be read +as licensing them. + +### [TYPEINF-LEGACY] Legacy mechanisms — condemned {#TYPEINF-LEGACY} + +The following mechanisms predate the engine. They are **not part of this +specification**; they are scheduled for deletion, rule by rule, under +[NARROWPLAN-INTEGRATION](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-INTEGRATION), +and no new code may be written against any of them: + +- `inference.rs` (`infer_rhs`) and `collection_inference.rs` — syntactic RHS + classification. Superseded by `BidirEngine::synth`. +- `types_parsing.rs` annotation-string parsing and every rule that slices + annotation text out of the source (`slice_span`) — superseded by evaluating + the annotation as a type expression through the resolution cascade + ([TYPEINF-ANNOTATION-RESOLUTION](#TYPEINF-ANNOTATION-RESOLUTION)) into the + engine. +- `RhsKind` shape dispatch in rules — superseded by synthesized types. +- Rule-local subtype/text helpers — superseded by + `subtyping::SubtypingContext` as the **single** subtyping judgment. + +While a legacy path still exists in the tree it is an implementation debt, not +a design. Deleting it must never delete a rule, drop a diagnostic, or cost a +required conformance error ([CHKARCH-CONFORMANCE](CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-CONFORMANCE)); +if the engine cannot yet carry a rule, the engine gets fixed first. ### [TYPEINF-ANNOTATION-RESOLUTION] Annotation name resolution {#TYPEINF-ANNOTATION-RESOLUTION} @@ -767,10 +801,9 @@ Nominal-subtyping rules may walk `ClassInfo.bases` transitively; the shared MRO model remains tracked by [NARROWPLAN-SUBTYPING](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUBTYPING). -**Builtin numeric tower.** The typing-spec promotions ([Special cases for float and complex](https://typing.python.org/en/latest/spec/special-types.html#special-cases-for-float-and-complex)) hold: `bool`/`int` are accepted where `float` is expected, and `bool`/`int`/`float` where `complex` is expected. Two layers implement this: +**Builtin numeric tower.** The typing-spec promotions ([Special cases for float and complex](https://typing.python.org/en/latest/spec/special-types.html#special-cases-for-float-and-complex)) hold: `bool`/`int` are accepted where `float` is expected, and `bool`/`int`/`float` where `complex` is expected. -- Annotation-text level (the conformance rules): the single home is `crates/basilisk-checker/src/subtyping.rs::name_subtype`, encoding the full `bool <: int <: float <: complex` chain; `rules/shared.rs::is_numeric_subtype` and the rule-local helpers (`narrowing_typeis`, `narrowing_typeis_2`, `overloads_evaluation`, `generics_typevartuple_callable`, `aliases_implicit`, `generics_syntax_scoping`, `callables_subtyping`, `generics_defaults_referential`) delegate to it, with the accepted/rejected table pinned in `tests/subtyping_context_tests.rs` ([NARROWPLAN-SUBTYPING](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUBTYPING)). -- `InferredType` level: the annotation parser folds `complex` into `Float` (`types_parsing.rs`: `"float" | "complex" => Float`), so the `int → float` and `int`/`float → complex` promotions hold by construction (`bool` acceptance lives at the text level). Accepted trade-off: a `complex`-typed value is not rejected where `float` is expected — the conformance suite does not exercise that direction. +The single home for this judgment is `crates/basilisk-checker/src/subtyping.rs` — `name_subtype` encodes the full `bool <: int <: float <: complex` chain, `SubtypingContext` is the judgment every consumer must go through, and the accepted/rejected table is pinned in `tests/subtyping_context_tests.rs` ([NARROWPLAN-SUBTYPING](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUBTYPING)). The rule-local delegates still calling `name_subtype` directly (`rules/shared.rs::is_numeric_subtype` and the helpers in `narrowing_typeis`, `narrowing_typeis_2`, `overloads_evaluation`, `generics_typevartuple_callable`, `aliases_implicit`, `generics_syntax_scoping`, `callables_subtyping`, `generics_defaults_referential`) are legacy shims on the demolition list ([TYPEINF-LEGACY](#TYPEINF-LEGACY)); the `types_parsing.rs` fold of `complex` into `Float` is a legacy-parser artifact that dies with that parser. One subtyping implementation — not two layers. **Other builtin relations:** - All classes <: `object` (`object` parses to the `Any` escape hatch for assignment purposes). @@ -898,7 +931,7 @@ g: Callable[[Dog], Animal] # accepts Dog, returns Animal Subtyping is decided by `InferredType::is_assignable_to(&self, other)` in `crates/basilisk-checker/src/types.rs` — a pure structural match over the `InferredType` enum, called on production paths by the compatibility rules (e.g. `rules/assignment_compatibility`, `rules/returns_compatibility`). It implements: - `Any` / `Unknown` bidirectional compatibility and `Never` as bottom ([TYPEINF-SPECIAL-ANY](#TYPEINF-SPECIAL-ANY), [TYPEINF-SPECIAL-NEVER](#TYPEINF-SPECIAL-NEVER)). -- Partial, literal-level numeric relations: `int` (and `Literal` ints/floats) <: `float`, `Literal[True/False]` <: `bool`/`int`, plus `Literal`/`LiteralString`/`str` relations ([TYPEINF-SUBTYPING-NOMINAL](#TYPEINF-SUBTYPING-NOMINAL), [TYPEINF-SPECIAL-LITERALSTRING](#TYPEINF-SPECIAL-LITERALSTRING)). The full `bool <: int <: float <: complex` tower lives in the annotation-text-level helpers used by the conformance rules. +- Partial, literal-level numeric relations: `int` (and `Literal` ints/floats) <: `float`, `Literal[True/False]` <: `bool`/`int`, plus `Literal`/`LiteralString`/`str` relations ([TYPEINF-SUBTYPING-NOMINAL](#TYPEINF-SUBTYPING-NOMINAL), [TYPEINF-SPECIAL-LITERALSTRING](#TYPEINF-SPECIAL-LITERALSTRING)). The full `bool <: int <: float <: complex` tower lives in `subtyping.rs::name_subtype`, behind `SubtypingContext` ([TYPEINF-SUBTYPING-NOMINAL](#TYPEINF-SUBTYPING-NOMINAL)). - `Optional`/`Union` decomposition: `A | B <: C` iff both sides do; `A <: A | B` ([TYPEINF-SUBTYPING-UNION](#TYPEINF-SUBTYPING-UNION)). - Bidirectional element compatibility (invariance, with gradual `Any`/`Unknown` consistency) for mutable `list`/`set`/`dict`; fixed-length, homogeneous `tuple[X, ...]`, and PEP 646 unpacked (`*tuple[...]`/`*Ts`) tuple matching ([TYPEINF-SUBTYPING-GENERIC](#TYPEINF-SUBTYPING-GENERIC), [TYPEINF-COLLECTIONS-TUPLES](#TYPEINF-COLLECTIONS-TUPLES)). - Callable contravariant parameters / covariant return, with `...` params gradual ([TYPEINF-SUBTYPING-CALLABLE](#TYPEINF-SUBTYPING-CALLABLE)); `TypeForm` covariance. @@ -1007,7 +1040,7 @@ Deliberate, distinctive behaviors of Basilisk's inference engine: ### [TYPEINF-EXCEEDS-NOUNKNOWN] Conservative `Unknown` Sentinel {#TYPEINF-EXCEEDS-NOUNKNOWN} -When syntactic RHS inference cannot determine a type (call expressions, `type(...)` calls, arbitrary expressions, lambda return types — `infer_rhs` in `crates/basilisk-checker/src/inference.rs`), it produces the internal sentinel `InferredType::Unknown` (`crates/basilisk-checker/src/types.rs`). `Unknown` is deliberately conservative: `is_assignable_to` treats it as bidirectionally compatible, and rules that encounter it generally suppress their diagnostic rather than guess. Recursive value-alias matching and `TypeForm` RHS validation are narrow exceptions that preserve real incompatibility diagnostics. `Unknown` never becomes explicit `Any` and does not alter the separately configured annotation policy. +Whatever the engine cannot **prove**, it types as the internal sentinel `InferredType::Unknown` (`crates/basilisk-checker/src/types.rs`) — never a guess. This is the gradual posture of [TYPEINF-TARGET-GRADUAL](#TYPEINF-TARGET-GRADUAL) made concrete: `is_assignable_to` treats `Unknown` as bidirectionally compatible, and rules that encounter it suppress their diagnostic rather than speculate. Recursive value-alias matching and `TypeForm` RHS validation are narrow exceptions that preserve real incompatibility diagnostics. `Unknown` never becomes explicit `Any` and does not alter the separately configured annotation policy. (The legacy `infer_rhs` path produces `Unknown` for every call expression because it cannot see callables at all; the engine's `synth_call` resolves them — one of the concrete losses the demolition of [TYPEINF-LEGACY](#TYPEINF-LEGACY) recovers.) ### [TYPEINF-EXCEEDS-CONTAINERS] Strict Container Inference Always On {#TYPEINF-EXCEEDS-CONTAINERS} @@ -1048,14 +1081,22 @@ engine grows ([TYPEINF-TARGET](#TYPEINF-TARGET)) — never the reverse. ## [TYPEINF-IMPL] Implementation notes {#TYPEINF-IMPL} -Shared inference lives in `basilisk-checker`: +The engine lives in `basilisk-checker`: + +- `bidir/` — the bidirectional core: `engine.rs` (synthesis), `check.rs` + (checking mode), `constraints.rs` + `solve.rs` (the two-stage constraint + architecture), `generics.rs` (`GenericEnv`), `builtins.rs` (the central + builtin call/method table). +- `narrow/` — the flow walker (`flow.rs`), scoped environment (`env.rs`), + guard interpretation (`guards.rs`), inference-driven reachability + (`reachability.rs`), and set operations (`set_ops.rs`). +- `subtyping.rs` — `SubtypingContext`, the single subtyping judgment. +- `types.rs` — `InferredType`, the ground-type vocabulary the engine solves + into. -- `inference.rs` — conservative RHS inference. -- `collection_inference.rs` — collection element joins. -- `types.rs` and `types_parsing.rs` — `InferredType`, assignability, and - annotation parsing. -- Focused resolver/rule modules — narrowing, overload, Literal, Protocol, and - TypedDict behavior. +Still present, condemned, and being deleted under +[TYPEINF-LEGACY](#TYPEINF-LEGACY): `inference.rs`, `collection_inference.rs`, +`types_parsing.rs`, and per-rule text/shape matching. The LSP analysis path is memoized by the Salsa database described in [CHKARCH-INCREMENTAL-SALSA](CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-INCREMENTAL-SALSA). @@ -1063,12 +1104,13 @@ A separate content-addressed cache serves opt-in cross-session CLI reuse. --- -## [TYPEINF-TARGET] Target inference architecture {#TYPEINF-TARGET} +## [TYPEINF-TARGET] The inference engine {#TYPEINF-TARGET} -This section specifies the design of the next-generation inference engine. -The current conservative core ([TYPEINF-ALGO](#TYPEINF-ALGO)) is superseded by -this design; delivery is staged in -[NARROWPLAN-INFERENCE](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-INFERENCE). +This section specifies **the** inference engine — not a future aspiration, not +an alternative mode: the one type oracle of [TYPEINF-ALGO](#TYPEINF-ALGO), +built in `bidir/` + `narrow/` + `subtyping.rs`. Rolling it through every rule +and deleting the legacy remnants it replaces is ordered by +[NARROWPLAN-INTEGRATION](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-INTEGRATION). The design is oriented toward [PEP 827 – Type Manipulation](https://peps.python.org/pep-0827/) — the engine must be powerful enough to host PEP 827-style conditional/mapped types — but From ac254933189cd1c6ba152008bffbf2b5d3ccbe62 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 19:45:11 +1000 Subject: [PATCH 12/45] doc fixes --- benchmarks/torture/run_torture.py | 4 +- .../tests/torture_golden_tests.rs | 2 +- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 217 +++++++++++------- docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md | 2 +- 4 files changed, 137 insertions(+), 88 deletions(-) diff --git a/benchmarks/torture/run_torture.py b/benchmarks/torture/run_torture.py index 9ce42447..66f1ee79 100644 --- a/benchmarks/torture/run_torture.py +++ b/benchmarks/torture/run_torture.py @@ -1,8 +1,8 @@ #!/usr/bin/env python3 """Type-torture scoreboard: Basilisk vs pyright, mypy, ty, pyrefly, zuban. -Implements the first slice of [NARROWPLAN-SUPERIORITY] — see -docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUPERIORITY. +Implements the first slice of [NARROWPLAN-SCOREBOARD] — see +docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SCOREBOARD. Eight small, hard typing problems (benchmarks/torture/cases/*.py), each grounded in a typing-spec section, an accepted PEP, or Python language diff --git a/crates/basilisk-checker/tests/torture_golden_tests.rs b/crates/basilisk-checker/tests/torture_golden_tests.rs index 884e3588..3290ce77 100644 --- a/crates/basilisk-checker/tests/torture_golden_tests.rs +++ b/crates/basilisk-checker/tests/torture_golden_tests.rs @@ -1,4 +1,4 @@ -//! Golden gate for the type-torture corpus ([NARROWPLAN-SUPERIORITY] slice). +//! Golden gate for the type-torture corpus ([NARROWPLAN-SCOREBOARD] slice). //! See docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md and //! `benchmarks/torture/run_torture.py` (the cross-checker scoreboard over the //! same cases). diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index aa40ff6e..093af088 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -45,12 +45,16 @@ environment, expression inferrer, constraint solver, or subtype context. - Preserve the gradual guarantee as a testable invariant, keep the zero-false-positive conformance gate, and hold both benchmark ratchets ([CHKARCH-TESTING-BENCH-RATCHET](../specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-TESTING-BENCH-RATCHET)). -- **Superiority is the exit criterion, not an aspiration.** Basilisk MUST end - this plan with measurably better type inference than pyright, mypy, ty, - pyrefly, and zuban. The plan is not complete while any competitor leads any - axis in [NARROWPLAN-TARGETS](#NARROWPLAN-TARGETS); the mechanism that makes - the claim honest, enforceable, and permanent is the superiority gate in - [NARROWPLAN-SUPERIORITY](#NARROWPLAN-SUPERIORITY). +- **Winning is the exit criterion, not an aspiration — and integration comes + first.** Basilisk MUST end this plan with measurably better type inference + than pyright, mypy, ty, pyrefly, and zuban, wired into the shipped checker — + a lead held by a detached engine counts for nothing. The plan is not + complete while any competitor leads any axis in + [NARROWPLAN-TARGETS](#NARROWPLAN-TARGETS); the mechanism that makes the + claim honest, enforceable, and permanent is the post-integration scoreboard + ratchet in [NARROWPLAN-SCOREBOARD](#NARROWPLAN-SCOREBOARD), which starts + only after [NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION) has the engine + behind live diagnostics. **Non-goals** @@ -342,21 +346,33 @@ forbidden, and nothing in this section licenses it: If replacing a rule's guts costs a required error, the engine is not ready for that rule yet — **fix the engine**, then come back. Do not ship the loss. -### Order of demolition - -Each step is one change: wire the rule to the engine, delete the legacy path -it replaces, land the spec-ID-linked mutation-resistant tests, re-certify. - -1. `assignment_compatibility` — the biggest liar in the tree. Every call RHS - goes through `synth_call`; `RhsKind` shape-matching dies here first. -2. `returns_compatibility` / `returns_compatibility_2` — the returned - expression is synthesized, not pattern-matched. -3. `calls_argument_type` — arguments checked against parameters through - `SubtypingContext`, not through per-rule string comparison. -4. `directives_assert_type` / `directives_reveal_type` — these must agree with - hover, byte for byte, because they are now the same oracle. -5. The remaining 80-odd `slice_span` consumers, in descending call-site count, - until the grep returns zero. +### Order of demolition — every step closes filed bugs + +This is not speculative refactoring: **each step fixes real, currently open +issues** (`docs/open_issues.csv`). The demolition list IS the bug list. Each +step is one change: wire the rule to the engine, delete the legacy path it +replaces, land the spec-ID-linked mutation-resistant tests, re-certify. The +sequenced checkboxes live in the checklist +([Integration and acceptance](#NARROWPLAN-CHECKLIST)): + +1. `assignment_compatibility` → engine (`synth_call` for call RHS), `RhsKind` + dies — fixes #397 (unfixed half) and the assignment half of #378. +2. `returns_compatibility` / `returns_compatibility_2` → engine synthesis — + fixes the return half of #378; companion rule `returns_implicit_none` + (#401) lands in the same family. +3. `calls_argument_type` → engine + `SubtypingContext` — fixes #356 (wrong in + both directions on `str.join`). +4. One engine-driven traversal visiting **every** `Call` node, not just + outermost positions ([NARROWPLAN-CALLSITES](#NARROWPLAN-CALLSITES)) — + fixes #381, #382, and the position half of #335. +5. `directives_assert_type` / `directives_reveal_type` = the hover oracle, + byte for byte — fixes #290 (solved generics surface everywhere). +6. `BSK-0001` consults `param_infer` before demanding an inferable + annotation — fixes #317. +7. Text-matching long tail: `slice_span` ~80 consumers → 0 — fixes #379 and + retires the mechanism behind #383. +8. Flow-analysis dividend: `names_unbound` migrates to the walker's all-paths + divergence — fixes #285. ### Gates that stay armed the entire time @@ -442,7 +458,7 @@ to re-certify. ## Measurable targets {#NARROWPLAN-TARGETS} -The axes on which inference superiority is defined and measured. Each axis has +The axes on which the inference lead is defined and measured. Each axis has a concrete metric so the lead is provable, not asserted: - **Bidirectional literal/generic inference:** deferred bounded type variables @@ -463,12 +479,21 @@ a concrete metric so the lead is provable, not asserted: annotations and asserts no new errors — Pyrefly fails this by design; Basilisk should pass. -## Superiority gate {#NARROWPLAN-SUPERIORITY} +## Inference scoreboard ratchet {#NARROWPLAN-SCOREBOARD} + +**Sequencing: this section is POST-INTEGRATION.** A lead measured on a +detached engine is a lead on nothing — until +[NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION) has the engine answering +real diagnostics in the shipped binary, there is no product to score, and no +scoreboard work outranks a single demolition step. The torture corpus already +seeded (below, first checklist item) stays live because it scores the *shipped +checker*; the remaining axes are built only after the wiring they would +measure exists. -Basilisk MUST have better type inference than every officially-recognized -competitor. "Better" is defined operationally and enforced exactly the way -this repo already enforces conformance and speed — self-measured, -reproducible, write-always, ratcheted: +Basilisk MUST end this plan with better type inference than every +officially-recognized competitor. "Better" is defined operationally and +enforced exactly the way this repo already enforces conformance and speed — +self-measured, reproducible, write-always, ratcheted: - **Definition.** Basilisk is superior on an axis when it scores strictly better than the LATEST official release of every officially-recognized @@ -492,10 +517,10 @@ reproducible, write-always, ratcheted: gate: falling behind any competitor on a led axis is a build failure. Leads only accumulate. The plan exits only when Basilisk leads **all five axes simultaneously** while the 100%/0-FP conformance gate and the speed - benchmark gate stay green — inference superiority must never be bought by + benchmark gate stay green — the inference lead must never be bought by regressing conformance or performance, and vice versa. - **Moving targets.** Because the harness pulls latest competitor releases, - superiority is continuously re-proven against competitors as they improve — + the lead is continuously re-proven against competitors as they improve — never against frozen versions. If a competitor release takes back an axis, CI goes red and reclaiming that axis becomes the top-priority work item on this plan. @@ -543,9 +568,9 @@ reproducible, write-always, ratcheted: [TYPEINF-RESEARCH-COMPETITORS](../specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-RESEARCH-COMPETITORS) are vendor/benchmark claims, not independently audited; treat them as directional. The only numbers Basilisk acts on are the ones its own - scoreboard harness produces ([NARROWPLAN-SUPERIORITY](#NARROWPLAN-SUPERIORITY)). + scoreboard harness produces ([NARROWPLAN-SCOREBOARD](#NARROWPLAN-SCOREBOARD)). - **Competitors are moving targets.** Pyrefly and ty ship fast and are well - funded; ty is actively closing its bidirectional gap. The superiority gate + funded; ty is actively closing its bidirectional gap. The scoreboard ratchet is designed for this: leads are re-proven against latest releases on every run, and a lost axis turns CI red rather than silently eroding the claim. @@ -556,7 +581,7 @@ reproducible, write-always, ratcheted: - Hover/inlay results and checker diagnostics agree for the same expression. - The gradual-guarantee differential suite (strip annotations → assert no new errors) passes. -- The inference scoreboard ([NARROWPLAN-SUPERIORITY](#NARROWPLAN-SUPERIORITY)) +- The inference scoreboard ([NARROWPLAN-SCOREBOARD](#NARROWPLAN-SCOREBOARD)) shows Basilisk strictly ahead of the latest official releases of pyright, mypy, ty, pyrefly, and zuban on **every** axis in [NARROWPLAN-TARGETS](#NARROWPLAN-TARGETS), and the per-axis ratchet is wired @@ -952,7 +977,81 @@ the conformance ratchets (100% / 0 false positives) at every step. union scrutinees, and stays gradual on `Unknown` scrutinees. Surface syntax awaits a ratified PEP 827; the engine is ready behind it. -### Superiority gate +### Integration and acceptance + +- [x] **Blocked every item below.** `FlowWalker::synth_type` is cheap before + any rule consumes `narrowed_uses` — see [NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION) + for the measurements. All three changes landed with the walker still + unconsumed: (a) `ctx.callables` converts to `Ty` once at walker + construction; (b) one long-lived `BidirEngine` takes the visible-binding + overlay through `push_scope_with`/`pop_scope` and resets its solver through + `solve_expression`; (c) `one_diverges` memoizes by statement span, so the + `walk_if` probe-then-walk and the `walk_stmts` re-probe no longer + re-synthesize the same expressions. Cost went from linear in module size to + flat. +- [ ] Record a `make bench` baseline on a fixture that actually exercises the + flow walker **in the same change that first wires it**, so the walker stops + being invisible to the ratchet the moment it starts costing real time. +- [ ] **Step 1 — `assignment_compatibility` to the engine; delete its + `RhsKind` shape-matching in the same change.** Every right-hand side — + literal, call, constructor, method, variable — is typed by + `BidirEngine::synth` (`synth_call` resolves call returns), narrowed by + `narrow::analyse_function_in`, and judged by `SubtypingContext`. + `a: int = returns_str()` must fire. Fixes #397 (unfixed half) and the + assignment half of #378. Not optional. +- [ ] **Step 2 — `returns_compatibility` / `returns_compatibility_2` + synthesize the returned expression through the engine**, deleting the + replaced pattern-matching. Fixes the return half of #378. Companion + default-on rule `returns_implicit_none` (#401) lands in the same family. +- [ ] **Step 3 — `calls_argument_type` judges arguments through the engine + + `SubtypingContext`**, deleting the syntactic-shape comparison. Fixes #356 + (false positives on valid `str.join` list displays AND a missed genuine + error). +- [ ] **Step 4 — one engine-driven traversal visits every `Call` node with a + resolved callee**, not just outermost-expression positions + ([NARROWPLAN-CALLSITES](#NARROWPLAN-CALLSITES)). Fixes #381, #382, and the + position half of #335. +- [ ] **Step 5 — `directives_assert_type` / `directives_reveal_type` answer + from the hover oracle, byte for byte** (the parked + `directives_assert_type_2` comes alive here). Fixes #290 — solved generic + parameters surface in hover and diagnostics alike. +- [ ] **Step 6 — `BSK-0001` consults `param_infer` before demanding an + annotation the engine can already infer** from body constraints and call + sites. Fixes #317. +- [ ] **Step 7 — text-matching long tail to zero.** Drive + `grep -rln slice_span crates/basilisk-checker/src/rules | wc -l` from + **86 to 0**, `RhsKind` (26 files) and `InferredType::from_annotation` over + source text (14 files) to **0**, and delete `rules/shared/text_scan.rs` + outright. An annotation is a type expression the engine evaluates — never a + string a rule slices out of the file. Fixes #379; retires the mechanism + behind #383. +- [ ] **Step 8 — `names_unbound` migrates to the walker's all-paths + divergence analysis**, replacing the last-statement idiom. Fixes #285. +- [ ] Route all 22 direct `name_subtype`/`is_numeric_subtype` call sites (12 + files) through `subtyping::SubtypingContext` and delete the shims — runs + alongside steps 3–7. One subtyping implementation. Not two, not + twenty-two. +- [ ] Delete every replaced code path **in the change that replaces it**. A + migration that leaves the legacy path alive alongside the new one is + incomplete and does not merge. +- [ ] Never create an alternate checking mode, engine flag, or opt-in switch + for any of this. One code path. Basilisk has no modes + ([CHKARCH-CONFIGURATION-ONLY]). +- [ ] Keep every rule registered and every diagnostic intact through the whole + demolition. The mechanism dies; the checking does not. A migration that + costs a required error means the engine is not ready — **fix the engine**, + never ship the loss ([CHKARCH-CONFORMANCE]). +- [ ] Add spec-ID-linked mutation-resistant tests for each migrated behavior. +- [ ] Verify hover/inlay results and checker diagnostics agree for the same + expression — byte for byte, because after this they are the same oracle. +- [ ] `make test`, mutation/coverage ratchets, benchmarks for touched hot + paths, and the live conformance gate all pass with zero false positives. + +### Inference scoreboard ratchet — post-integration + +Nothing below (except the already-live torture corpus) starts before the +demolition order above it is complete: score the shipped checker, not a +detached engine. - [x] Seed the scoreboard with a **type-torture corpus**: hard, spec-grounded problems (several straight from the issue tracker) scored conformance-style @@ -995,56 +1094,6 @@ the conformance ratchets (100% / 0 false positives) at every step. - [ ] Take and hold the lead on **all five axes simultaneously**, with the 100%/0-FP conformance gate and the speed benchmark gate green in the same run. -- [ ] Enforce claims discipline: every superiority statement in docs, website, +- [ ] Enforce claims discipline: every better-than-competitor claim in docs, website, or marketing traces to the current committed scoreboard run and states the methodology. - -### Integration and acceptance - -- [x] **Blocked every item below.** `FlowWalker::synth_type` is cheap before - any rule consumes `narrowed_uses` — see [NARROWPLAN-INTEGRATION](#NARROWPLAN-INTEGRATION) - for the measurements. All three changes landed with the walker still - unconsumed: (a) `ctx.callables` converts to `Ty` once at walker - construction; (b) one long-lived `BidirEngine` takes the visible-binding - overlay through `push_scope_with`/`pop_scope` and resets its solver through - `solve_expression`; (c) `one_diverges` memoizes by statement span, so the - `walk_if` probe-then-walk and the `walk_stmts` re-probe no longer - re-synthesize the same expressions. Cost went from linear in module size to - flat. -- [ ] Record a `make bench` baseline on a fixture that actually exercises the - flow walker **in the same change that first wires it**, so the walker stops - being invisible to the ratchet the moment it starts costing real time. -- [ ] **Wire `assignment_compatibility` to the engine and delete `RhsKind` - shape-matching from it in the same change.** Every right-hand side — - literal, call, constructor, method, variable — is typed by - `BidirEngine::synth`, narrowed by `narrow::analyse_function_in`, and judged - by `SubtypingContext`. `a: int = returns_str()` must fire (Refs #397). This - is step one and it is not optional. -- [ ] Migrate `returns_compatibility` / `returns_compatibility_2`, - `calls_argument_type`, and `directives_assert_type` / - `directives_reveal_type` — each one change, each deleting the legacy path it - replaces, each re-certified at 100% / 0 FP. -- [ ] Drive `grep -rln slice_span crates/basilisk-checker/src/rules | wc -l` - from **86 to 0**. An annotation is a type expression the engine evaluates — - never a string a rule slices out of the file. -- [ ] Drive `RhsKind` (26 files) and `InferredType::from_annotation` over - source text (14 files) to **0**, and delete `rules/shared/text_scan.rs` - outright. -- [ ] Route all 22 direct `name_subtype`/`is_numeric_subtype` call sites (12 - files) through `subtyping::SubtypingContext` and delete the shims. One - subtyping implementation. Not two, not twenty-two. -- [ ] Delete every replaced code path **in the change that replaces it**. A - migration that leaves the legacy path alive alongside the new one is - incomplete and does not merge. -- [ ] Never create an alternate checking mode, engine flag, or opt-in switch - for any of this. One code path. Basilisk has no modes - ([CHKARCH-CONFIGURATION-ONLY]). -- [ ] Keep every rule registered and every diagnostic intact through the whole - demolition. The mechanism dies; the checking does not. A migration that - costs a required error means the engine is not ready — **fix the engine**, - never ship the loss ([CHKARCH-CONFORMANCE]). -- [ ] Add spec-ID-linked mutation-resistant tests for each migrated behavior. -- [ ] Verify hover/inlay results and checker diagnostics agree for the same - expression — byte for byte, because after this they are the same oracle. -- [ ] `make test`, mutation/coverage ratchets, benchmarks for touched hot - paths, and the live conformance gate all pass with zero false positives. diff --git a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md index c3be1543..62e6a88d 100644 --- a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md +++ b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md @@ -1119,7 +1119,7 @@ groundwork is specified here. Every claim below is grounded in the research survey in [TYPEINF-RESEARCH](#TYPEINF-RESEARCH). The outcome requirement — inference measurably superior to every officially-recognized competitor, proven and held by a self-measured ratcheted scoreboard — is defined in -[NARROWPLAN-SUPERIORITY](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUPERIORITY). +[NARROWPLAN-SCOREBOARD](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SCOREBOARD). ### [TYPEINF-TARGET-BIDIRECTIONAL] Bidirectional core {#TYPEINF-TARGET-BIDIRECTIONAL} From c796161d26f8eda19fe67a1c546a4bde20f7b7bf Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 20:42:25 +1000 Subject: [PATCH 13/45] fixes --- .../src/annotation/builtins.rs | 65 ++++ .../basilisk-checker/src/annotation/forms.rs | 161 ++++++++++ .../basilisk-checker/src/annotation/index.rs | 100 ++++++ crates/basilisk-checker/src/annotation/mod.rs | 281 ++++++++++++++++ .../basilisk-checker/src/annotation/tables.rs | 303 ++++++++++++++++++ crates/basilisk-checker/src/lib.rs | 5 + .../src/rules/returns_compatibility.rs | 49 +-- .../src/rules/returns_compatibility_2.rs | 48 +-- crates/basilisk-checker/src/rules/shared.rs | 54 ++-- 9 files changed, 992 insertions(+), 74 deletions(-) create mode 100644 crates/basilisk-checker/src/annotation/builtins.rs create mode 100644 crates/basilisk-checker/src/annotation/forms.rs create mode 100644 crates/basilisk-checker/src/annotation/index.rs create mode 100644 crates/basilisk-checker/src/annotation/mod.rs create mode 100644 crates/basilisk-checker/src/annotation/tables.rs diff --git a/crates/basilisk-checker/src/annotation/builtins.rs b/crates/basilisk-checker/src/annotation/builtins.rs new file mode 100644 index 00000000..62e815dc --- /dev/null +++ b/crates/basilisk-checker/src/annotation/builtins.rs @@ -0,0 +1,65 @@ +//! Implements [TYPEINF-ANNOTATION-RESOLUTION] step 4 — builtin and typeshed +//! leaves. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION +//! +//! The last step of the cascade before a name is declared unresolved. Only +//! names whose meaning is fixed by the language or the typing spec live here; +//! everything else resolves through the module's own tables or becomes the +//! gradual `Unknown` ([TYPEINF-EXCEEDS-NOUNKNOWN]). + +use crate::types::{CallableInfo, InferredType}; + +/// Resolve a bare (already lower-cased, `typing.`-stripped) leaf name. +/// +/// `None` means "not a builtin" — the caller continues the cascade. +pub(super) fn leaf(name: &str) -> Option { + match name { + "int" => Some(InferredType::Int), + "str" => Some(InferredType::Str), + // `complex ⊃ float ⊃ int`: the wider numeric leaves share `Float`'s + // position in the tower ([TYPEINF-SUBTYPING-NOMINAL]). + "float" | "complex" => Some(InferredType::Float), + "bool" => Some(InferredType::Bool), + "bytes" => Some(InferredType::Bytes), + "none" => Some(InferredType::None_), + // [TYPEINF-SPECIAL-ANY] — `Any`, `object`, and the bare gradual forms + // are the escape hatch for assignment purposes. + "any" | "object" | "final" | "tuple" | "type" => Some(InferredType::Any), + // [TYPEINF-SPECIAL-NEVER] — the bottom type; `NoReturn` is its spelling + // in return position. + "never" | "noreturn" => Some(InferredType::Never), + // [TYPEINF-SPECIAL-LITERALSTRING]. + "literalstring" => Some(InferredType::LiteralString), + // A bare `Callable` is `Callable[..., Any]` (PEP 484): empty + // `param_types` is the arbitrary-parameter form. + "callable" => Some(InferredType::Callable(CallableInfo { + param_types: Vec::new(), + return_type: Box::new(InferredType::Any), + })), + "generator" => Some(InferredType::Generator( + Box::new(InferredType::Any), + Box::new(InferredType::None_), + Box::new(InferredType::None_), + )), + // Bare generics are implicitly parameterised with `Any`. + "list" => Some(InferredType::List(Box::new(InferredType::Any))), + "dict" => Some(InferredType::Dict( + Box::new(InferredType::Any), + Box::new(InferredType::Any), + )), + "set" | "frozenset" => Some(InferredType::Set(Box::new(InferredType::Any))), + _ => None, + } +} + +/// Does this leaf name denote a builtin type? Used to decide whether an +/// implicit assignment (`X = int`) is an alias definition or a value binding. +pub(super) fn is_builtin_type_name(name: &str) -> bool { + leaf(name).is_some() +} + +/// Modules whose members are typing special forms, so `t.Sequence` and +/// `Sequence` resolve identically once `t` is known to bind one of them. +pub(super) fn is_typing_module(module: &str) -> bool { + matches!(module, "typing" | "typing_extensions") +} diff --git a/crates/basilisk-checker/src/annotation/forms.rs b/crates/basilisk-checker/src/annotation/forms.rs new file mode 100644 index 00000000..51df1a38 --- /dev/null +++ b/crates/basilisk-checker/src/annotation/forms.rs @@ -0,0 +1,161 @@ +//! Implements [TYPEINF-ANNOTATION-RESOLUTION] — the typing special forms. +//! See docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION +//! +//! Subscripted forms whose meaning is fixed by the typing spec — containers, +//! `Literal`, `Callable`, `Generator`, `Optional`/`Union`, `Annotated`, +//! `Final`, `TypeForm` — evaluated from their **argument expressions**, each +//! resolved by the same cascade. A form this module does not model is gradual +//! (`Unknown`), never a guess. + +use ruff_python_ast::{Expr, UnaryOp}; + +use crate::types::{CallableInfo, InferredType, LiteralValue}; + +use super::{AnnotationResolver, Frame}; + +/// Evaluate a subscripted special form. `None` means "not a special form" — +/// the caller continues the cascade with aliases and classes. +pub(super) fn special_form( + resolver: &AnnotationResolver<'_>, + head: &str, + args: &[&Expr], + frame: &Frame, +) -> Option { + let resolve = |expr: &Expr| resolver.eval(expr, frame); + match head { + "literal" => Some(literal_union(args)), + "optional" => Some(InferredType::Optional(Box::new(first_type(args, &resolve)))), + "union" => Some(InferredType::Union(args.iter().map(|a| resolve(a)).collect())), + // `Annotated[T, ..]` and `Final[T]` are transparent wrappers. + "annotated" | "final" => Some(first_type(args, &resolve)), + "typeform" => Some(InferredType::TypeForm(Box::new(first_type(args, &resolve)))), + "list" => Some(InferredType::List(Box::new(first_type(args, &resolve)))), + "set" | "frozenset" => Some(InferredType::Set(Box::new(first_type(args, &resolve)))), + "dict" => Some(dict_type(args, &resolve)), + "tuple" => Some(tuple_type(args, &resolve)), + "callable" => Some(callable_type(args, &resolve)), + "generator" => Some(generator_type(args, &resolve)), + // `type[X]` needs class-object modelling the cascade does not yet do: + // gradual, so no rule invents a verdict from it. + "type" => Some(InferredType::Unknown), + _ => None, + } +} + +/// The first argument's type, or gradual when there is none. +fn first_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> InferredType { + args.first() + .map_or(InferredType::Unknown, |expr| resolve(expr)) +} + +/// `dict[K, V]`; any other arity is gradual. +fn dict_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> InferredType { + match args { + [key, value] => InferredType::Dict(Box::new(resolve(key)), Box::new(resolve(value))), + _ => InferredType::Unknown, + } +} + +/// `tuple[X, Y]`, `tuple[X, ...]`, and the PEP 484 empty form `tuple[()]`. +fn tuple_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> InferredType { + if let [Expr::Tuple(empty)] = args { + if empty.elts.is_empty() { + return InferredType::Tuple(Vec::new()); + } + } + InferredType::Tuple(args.iter().map(|arg| resolve(arg)).collect()) +} + +/// `Callable[[P..], R]`, `Callable[..., R]`, and `Callable[P, R]` for a +/// `ParamSpec` `P` (whose parameter list is unknown — the arbitrary form). +fn callable_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> InferredType { + let [params, ret] = args else { + return InferredType::Unknown; + }; + let param_types = match params { + Expr::List(list) => list.elts.iter().map(resolve).collect(), + // `...` and a `ParamSpec` both mean "parameters not constrained here". + _ => Vec::new(), + }; + InferredType::Callable(CallableInfo { + param_types, + return_type: Box::new(resolve(ret)), + }) +} + +/// `Generator[Yield, Send, Return]`; any other arity is gradual. +fn generator_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> InferredType { + match args { + [yielded, sent, returned] => InferredType::Generator( + Box::new(resolve(yielded)), + Box::new(resolve(sent)), + Box::new(resolve(returned)), + ), + _ => InferredType::Unknown, + } +} + +/// `Literal[a, b, ..]` — a union of the literal values, read from the AST +/// literal nodes themselves rather than from annotation text, so a value's +/// case and radix survive (`Literal[0x14]` is `Literal[20]`). +fn literal_union(args: &[&Expr]) -> InferredType { + match args { + [] => InferredType::Unknown, + [single] => literal_value(single), + many => InferredType::Union(many.iter().map(|arg| literal_value(arg)).collect()), + } +} + +/// One `Literal[..]` argument. +fn literal_value(expr: &Expr) -> InferredType { + match expr { + Expr::NumberLiteral(number) => number_literal(&number.value), + Expr::StringLiteral(text) => { + InferredType::Literal(LiteralValue::Str(text.value.to_str().to_owned())) + } + Expr::BytesLiteral(_) => InferredType::Bytes, + Expr::BooleanLiteral(flag) => InferredType::Literal(LiteralValue::Bool(flag.value)), + Expr::NoneLiteral(_) => InferredType::None_, + Expr::UnaryOp(unary) if unary.op == UnaryOp::USub => negate(literal_value(&unary.operand)), + // An enum member (`Color.RED`) or a name: nominal, kept for display and + // base-name comparison. + other => super::tables::dotted_name(other) + .map_or(InferredType::Unknown, InferredType::Named), + } +} + +/// An integer literal keeps its value; other numeric literals keep their kind. +fn number_literal(number: &ruff_python_ast::Number) -> InferredType { + match number { + ruff_python_ast::Number::Int(value) => value + .as_i64() + .map_or(InferredType::Int, |int| { + InferredType::Literal(LiteralValue::Int(int)) + }), + ruff_python_ast::Number::Float(_) | ruff_python_ast::Number::Complex { .. } => { + InferredType::Float + } + } +} + +/// `Literal[-1]` — the parser sees unary minus applied to `1`. +fn negate(ty: InferredType) -> InferredType { + match ty { + InferredType::Literal(LiteralValue::Int(value)) => { + InferredType::Literal(LiteralValue::Int(-value)) + } + other => other, + } +} + +/// Render a resolved element type back into the unpacked-tuple marker the +/// PEP 646 matcher reads (`*tuple[int, ...]`, `*Ts`). +/// +/// The marker is a rendering of an **already-resolved type**, not a slice of +/// source text; it exists because [`InferredType`] has no unpacked-tuple +/// variant yet. That variant is owed by +/// [NARROWPLAN-INTEGRATION](../../../../docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-INTEGRATION), +/// and this bridge dies with it. +pub(super) fn unpacked_marker(element: &InferredType) -> InferredType { + InferredType::Named(format!("*{element}")) +} diff --git a/crates/basilisk-checker/src/annotation/index.rs b/crates/basilisk-checker/src/annotation/index.rs new file mode 100644 index 00000000..6a7e3346 --- /dev/null +++ b/crates/basilisk-checker/src/annotation/index.rs @@ -0,0 +1,100 @@ +//! Implements [TYPEINF-ANNOTATION-RESOLUTION] — the span → annotation-node +//! index. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION +//! +//! Resolver-derived data (`FunctionInfo::return_annotation_span`, +//! `VariableInfo::annotation_span`, …) records an annotation by span. This +//! index maps that span straight back to the AST node it came from, so a rule +//! holding a span resolves a **type expression** instead of slicing the source +//! and re-reading it as text. + +use std::collections::HashMap; + +use ruff_python_ast::{ExceptHandler, Expr, ModModule, Parameters, Stmt}; +use ruff_text_size::Ranged as _; + +/// Index every annotation expression in the module by its span. +pub(super) fn annotation_nodes(module: &ModModule) -> HashMap<(u32, u32), &Expr> { + let mut index = HashMap::new(); + collect(&module.body, &mut index); + index +} + +/// Record one annotation node, keyed by its exact span. +fn record<'m>(expr: &'m Expr, index: &mut HashMap<(u32, u32), &'m Expr>) { + let range = expr.range(); + let _ = index.insert( + (u32::from(range.start()), u32::from(range.end())), + expr, + ); +} + +/// Walk every statement body: annotations appear at any nesting depth. +fn collect<'m>(body: &'m [Stmt], index: &mut HashMap<(u32, u32), &'m Expr>) { + for stmt in body { + collect_one(stmt, index); + } +} + +fn collect_one<'m>(stmt: &'m Stmt, index: &mut HashMap<(u32, u32), &'m Expr>) { + match stmt { + Stmt::FunctionDef(func) => { + if let Some(returns) = func.returns.as_deref() { + record(returns, index); + } + parameters(&func.parameters, index); + collect(&func.body, index); + } + Stmt::AnnAssign(assign) => record(&assign.annotation, index), + Stmt::ClassDef(class) => collect(&class.body, index), + Stmt::If(if_stmt) => { + collect(&if_stmt.body, index); + for clause in &if_stmt.elif_else_clauses { + collect(&clause.body, index); + } + } + Stmt::For(for_stmt) => { + collect(&for_stmt.body, index); + collect(&for_stmt.orelse, index); + } + Stmt::While(while_stmt) => { + collect(&while_stmt.body, index); + collect(&while_stmt.orelse, index); + } + Stmt::With(with_stmt) => collect(&with_stmt.body, index), + Stmt::Try(try_stmt) => { + collect(&try_stmt.body, index); + for ExceptHandler::ExceptHandler(handler) in &try_stmt.handlers { + collect(&handler.body, index); + } + collect(&try_stmt.orelse, index); + collect(&try_stmt.finalbody, index); + } + Stmt::Match(match_stmt) => { + for case in &match_stmt.cases { + collect(&case.body, index); + } + } + _ => {} + } +} + +/// Every annotated parameter of one signature, `*args` / `**kwargs` included. +fn parameters<'m>(params: &'m Parameters, index: &mut HashMap<(u32, u32), &'m Expr>) { + let positional = params + .posonlyargs + .iter() + .chain(params.args.iter()) + .chain(params.kwonlyargs.iter()) + .map(|param| ¶m.parameter); + let starred = params + .vararg + .as_deref() + .into_iter() + .chain(params.kwarg.as_deref()); + for parameter in positional.chain(starred) { + if let Some(annotation) = parameter.annotation.as_deref() { + record(annotation, index); + } + } +} diff --git a/crates/basilisk-checker/src/annotation/mod.rs b/crates/basilisk-checker/src/annotation/mod.rs new file mode 100644 index 00000000..622ba420 --- /dev/null +++ b/crates/basilisk-checker/src/annotation/mod.rs @@ -0,0 +1,281 @@ +//! Implements [TYPEINF-ANNOTATION-RESOLUTION] — the checker's **single** +//! annotation entry point. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION +//! +//! An annotation is a *type expression*, and turning it into a type is a +//! name-resolution problem. Every rule that compares a value against a +//! declared type obtains that type here — from the Ruff AST annotation node, +//! resolved through the cascade +//! +//! 1. type-alias table (PEP 695 `type X = ..`, `X: TypeAlias = ..`, implicit), +//! 2. same-file class table, +//! 3. import table, +//! 4. typeshed / builtins, +//! 5. forward reference (a string annotation, parsed and resolved by 1–4), +//! +//! — never by pattern-matching annotation source text. Aliases are +//! *transparent*: `type MyStr = int` behaves exactly as `int` at every +//! nesting depth and regardless of declaration order. A name the cascade +//! cannot resolve is the gradual `Unknown` ([TYPEINF-EXCEEDS-NOUNKNOWN]), so +//! the rule that asked suppresses its diagnostic — silence for what we do not +//! know, never silence for a name we *can* resolve +//! ([#378](https://github.com/Nimblesite/Basilisk/issues/378)). +//! +//! This replaces `InferredType::from_annotation()`, which is +//! condemned under [TYPEINF-LEGACY]. + +mod builtins; +mod forms; +mod index; +mod tables; + +use std::collections::HashMap; + +use basilisk_resolver::{ResolvedModule, Span}; +use ruff_python_ast::{Expr, Operator}; + +use crate::types::InferredType; + +use tables::Tables; + +/// Maximum alias-expansion / nesting depth. Beyond it the result is gradual: +/// a bound that terminates evaluation NEVER invents an error. +const MAX_DEPTH: u32 = 32; + +/// Resolve one annotation expression against a module — the one-shot form of +/// [`AnnotationResolver`], for callers holding a single annotation. +/// +/// Prefer building an [`AnnotationResolver`] when resolving more than one +/// annotation in the same module: the tables are built once there. +#[must_use] +pub fn resolve_annotation(module: &ResolvedModule, expr: &Expr) -> InferredType { + AnnotationResolver::for_module(module) + .map_or(InferredType::Unknown, |resolver| resolver.resolve(expr)) +} + +/// The per-module resolution state: name tables plus an index from annotation +/// spans back to their AST nodes. +#[derive(Debug)] +pub struct AnnotationResolver<'m> { + tables: Tables<'m>, + annotations: HashMap<(u32, u32), &'m Expr>, +} + +/// One step of resolution: the alias parameters currently bound, the aliases +/// being expanded (cycle detection), and the remaining depth budget. +#[derive(Debug, Default, Clone)] +pub(crate) struct Frame { + bindings: Vec<(String, InferredType)>, + visiting: Vec, + depth: u32, +} + +impl Frame { + /// The frame for expanding `alias` with `bindings` bound to its + /// parameters. + fn expanding(&self, alias: &str, bindings: Vec<(String, InferredType)>) -> Frame { + let mut visiting = self.visiting.clone(); + visiting.push(alias.to_owned()); + Frame { + bindings, + visiting, + depth: self.depth + 1, + } + } + + /// The same frame one level deeper into a type expression. + fn nested(&self) -> Frame { + Frame { + bindings: self.bindings.clone(), + visiting: self.visiting.clone(), + depth: self.depth + 1, + } + } +} + +impl<'m> AnnotationResolver<'m> { + /// Build the resolver for a module, parsing its AST through the shared + /// [`LazyAst`](basilisk_resolver::LazyAst) cache. `None` iff the module + /// does not parse — parse errors are reported separately. + #[must_use] + pub fn for_module(module: &'m ResolvedModule) -> Option> { + let parsed = module.lazy_ast.get_or_parse(&module.source, &module.path)?; + Some(AnnotationResolver { + tables: Tables::build(&parsed.ast), + annotations: index::annotation_nodes(&parsed.ast), + }) + } + + /// Resolve an annotation expression to the type it denotes. + #[must_use] + pub fn resolve(&self, expr: &Expr) -> InferredType { + self.eval(expr, &Frame::default()) + } + + /// Resolve the annotation node covering `span`. `None` when no annotation + /// node has exactly that span — the caller then has no annotation to judge + /// and must stay silent rather than fall back to reading text. + #[must_use] + pub fn resolve_span(&self, span: Span) -> Option { + self.annotations + .get(&(span.start, span.end)) + .map(|expr| self.resolve(expr)) + } + + /// The cascade over one type expression. + pub(crate) fn eval(&self, expr: &Expr, frame: &Frame) -> InferredType { + if frame.depth > MAX_DEPTH { + return InferredType::Unknown; + } + match expr { + Expr::Name(name) => self.name(name.id.as_str(), frame), + Expr::Attribute(_) => self.attribute(expr, frame), + Expr::Subscript(sub) => self.subscript(sub, frame), + Expr::BinOp(bin) if bin.op == Operator::BitOr => self.union(bin, frame), + Expr::NoneLiteral(_) => InferredType::None_, + Expr::StringLiteral(text) => self.forward_ref(text.value.to_str(), frame), + Expr::Starred(star) => forms::unpacked_marker(&self.eval(&star.value, frame)), + // The `tuple[X, ...]` / `Callable[..., R]` terminator is a + // structural marker the assignability judgment reads. + Expr::EllipsisLiteral(_) => InferredType::Named("...".to_owned()), + _ => InferredType::Unknown, + } + } + + /// A bare name, in cascade order: alias parameters bound by an enclosing + /// expansion, then aliases, classes, imports, and builtins last — a + /// module-level declaration shadows a builtin exactly as Python does. + fn name(&self, name: &str, frame: &Frame) -> InferredType { + if let Some((_, bound)) = frame.bindings.iter().find(|(param, _)| param == name) { + return bound.clone(); + } + if let Some(expanded) = self.expand_alias(name, &[], frame) { + return expanded; + } + if self.tables.nominal.contains(name) { + return InferredType::Named(name.to_owned()); + } + if let Some(imported) = self.imported_leaf(name) { + return imported; + } + builtins::leaf(&name.to_ascii_lowercase()).unwrap_or(InferredType::Unknown) + } + + /// A dotted name: `typing.Sequence`, `t.Optional`, `mod.Class`. + fn attribute(&self, expr: &Expr, frame: &Frame) -> InferredType { + let Some(dotted) = tables::dotted_name(expr) else { + return InferredType::Unknown; + }; + match self.canonical_head(&dotted) { + Some(head) => self.name(&head, frame), + None => InferredType::Unknown, + } + } + + /// A subscripted form: special forms first, then parameterised aliases, + /// then generic same-file classes. + fn subscript(&self, sub: &ruff_python_ast::ExprSubscript, frame: &Frame) -> InferredType { + let args = basilisk_parser::subscript_elements(sub); + let Some(head) = tables::dotted_name(&sub.value).and_then(|d| self.canonical_head(&d)) + else { + return InferredType::Unknown; + }; + let nested = frame.nested(); + if !self.shadows_special_form(&head) { + if let Some(ty) = forms::special_form(self, &head.to_ascii_lowercase(), &args, &nested) { + return ty; + } + } + if let Some(expanded) = self.expand_alias(&head, &args, frame) { + return expanded; + } + if self.tables.nominal.contains(&head) { + return InferredType::Named(head); + } + InferredType::Unknown + } + + /// `X | Y` — flattened into one union. + fn union(&self, bin: &ruff_python_ast::ExprBinOp, frame: &Frame) -> InferredType { + let mut arms = Vec::new(); + self.union_arm(&bin.left, frame, &mut arms); + self.union_arm(&bin.right, frame, &mut arms); + InferredType::Union(arms) + } + + fn union_arm(&self, expr: &Expr, frame: &Frame, arms: &mut Vec) { + match expr { + Expr::BinOp(bin) if bin.op == Operator::BitOr => { + self.union_arm(&bin.left, frame, arms); + self.union_arm(&bin.right, frame, arms); + } + other => arms.push(self.eval(other, frame)), + } + } + + /// A string annotation is a forward reference: parse it and resolve the + /// expression it contains through this same cascade. + fn forward_ref(&self, text: &str, frame: &Frame) -> InferredType { + match ruff_python_parser::parse_expression(text.trim()) { + Ok(parsed) => self.eval(parsed.expr(), &frame.nested()), + Err(_) => InferredType::Unknown, + } + } + + /// Expand an alias transparently, binding its parameters to the resolved + /// arguments. A cycle (`type J = list[J]` re-entered) is gradual, which + /// terminates expansion without rejecting the legal recursive alias + /// ([#371](https://github.com/Nimblesite/Basilisk/issues/371)). + fn expand_alias(&self, name: &str, args: &[&Expr], frame: &Frame) -> Option { + let entry = self.tables.aliases.get(name)?; + if frame.visiting.iter().any(|visited| visited == name) { + return Some(InferredType::Unknown); + } + let bindings = entry + .params + .iter() + .cloned() + .zip(args.iter().map(|arg| self.eval(arg, &frame.nested()))) + .collect(); + Some(self.eval(entry.value, &frame.expanding(name, bindings))) + } + + /// A name bound by `from typing import X` resolves to the special form it + /// names. Project and third-party symbols stay gradual until the import + /// cascade covers them — the seam + /// [#324](https://github.com/Nimblesite/Basilisk/issues/324) fills, behind + /// this same entry point. + fn imported_leaf(&self, name: &str) -> Option { + let imported = self.tables.imports.get(name)?; + if !builtins::is_typing_module(&imported.module) { + return Some(InferredType::Unknown); + } + Some( + builtins::leaf(&imported.original.to_ascii_lowercase()) + .unwrap_or(InferredType::Unknown), + ) + } + + /// Rewrite a spelling into the name the cascade knows it by: an + /// import alias becomes the name as spelled in its defining module, and a + /// `typing`-qualified attribute becomes its bare member name. + fn canonical_head(&self, dotted: &str) -> Option { + let Some((head, member)) = dotted.split_once('.') else { + return Some( + self.tables + .imports + .get(dotted) + .filter(|imported| builtins::is_typing_module(&imported.module)) + .map_or_else(|| dotted.to_owned(), |imported| imported.original.clone()), + ); + }; + let module = self.tables.modules.get(head)?; + builtins::is_typing_module(module).then(|| member.to_owned()) + } + + /// A module-level declaration of the same name wins over the typing + /// special form: `class Literal: ...` in this file means *this* class. + fn shadows_special_form(&self, head: &str) -> bool { + self.tables.nominal.contains(head) || self.tables.aliases.contains_key(head) + } +} diff --git a/crates/basilisk-checker/src/annotation/tables.rs b/crates/basilisk-checker/src/annotation/tables.rs new file mode 100644 index 00000000..7885df9c --- /dev/null +++ b/crates/basilisk-checker/src/annotation/tables.rs @@ -0,0 +1,303 @@ +//! Implements [TYPEINF-ANNOTATION-RESOLUTION] — the name tables the cascade +//! resolves against. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION +//! +//! Every table is built from the module's Ruff AST, never from source text: +//! aliases keep a borrowed reference to their right-hand-side **expression** +//! so the cascade expands them by evaluating a type expression, and imports +//! keep the defining module plus the name as spelled there, so `from typing +//! import Sequence as Seq` and `import typing as t` resolve identically. + +use std::collections::{HashMap, HashSet}; + +use ruff_python_ast::{Expr, ModModule, Stmt, StmtClassDef}; + +/// One alias definition reachable from a type expression: `type X[P..] = rhs`, +/// `X: TypeAlias = rhs`, or the implicit `X = `. +#[derive(Debug)] +pub(super) struct AliasEntry<'m> { + /// PEP 695 type-parameter names, in declaration order (empty otherwise). + pub(super) params: Vec, + /// The right-hand side, as an AST expression. + pub(super) value: &'m Expr, +} + +/// A name bound into this module by an `import` statement. +#[derive(Debug)] +pub(super) struct ImportedName { + /// The defining module's dotted path (`typing`, `collections.abc`). + pub(super) module: String, + /// The name as spelled in the defining module — alias-independent, so + /// `from typing import Sequence as Seq` records `Sequence`. + pub(super) original: String, +} + +/// The resolution tables for one module. +#[derive(Debug, Default)] +pub(super) struct Tables<'m> { + /// Alias name → definition (all three alias spellings). + pub(super) aliases: HashMap>, + /// Same-file classes that denote a **checkable nominal type**. + pub(super) nominal: HashSet, + /// Names bound by `from X import name`. + pub(super) imports: HashMap, + /// Local binding → module path, for `import X` / `import X as Y`. + pub(super) modules: HashMap, +} + +impl<'m> Tables<'m> { + /// Build every table from one module AST. + pub(super) fn build(module: &'m ModModule) -> Self { + let mut tables = Tables::default(); + tables.collect(&module.body); + tables.collect_implicit_aliases(&module.body); + tables + } + + /// Walk every statement body: aliases, classes, and imports are collected + /// at any nesting depth, because a type expression may name a symbol + /// declared inside a conditional (`if TYPE_CHECKING:`) or a class body. + fn collect(&mut self, body: &'m [Stmt]) { + for stmt in body { + self.collect_one(stmt); + for nested in child_bodies(stmt) { + self.collect(nested); + } + } + } + + /// The explicit declarations of one statement. + fn collect_one(&mut self, stmt: &'m Stmt) { + match stmt { + Stmt::TypeAlias(alias) => self.insert_type_statement(alias), + Stmt::AnnAssign(assign) => self.insert_annotated_alias(assign), + Stmt::ClassDef(class) => self.insert_class(class), + Stmt::Import(import) => self.insert_plain_imports(import), + Stmt::ImportFrom(import) => self.insert_from_imports(import), + _ => {} + } + } + + /// PEP 695 `type X[P..] = rhs`. + fn insert_type_statement(&mut self, alias: &'m ruff_python_ast::StmtTypeAlias) { + let Some(name) = simple_name(&alias.name) else { + return; + }; + let params = alias + .type_params + .as_deref() + .map(|type_params| { + type_params + .type_params + .iter() + .map(|param| param.name().to_string()) + .collect() + }) + .unwrap_or_default(); + let _ = self.aliases.insert( + name, + AliasEntry { + params, + value: &alias.value, + }, + ); + } + + /// `X: TypeAlias = rhs` (PEP 613), bare or `typing.`-qualified. + fn insert_annotated_alias(&mut self, assign: &'m ruff_python_ast::StmtAnnAssign) { + let Some(value) = assign.value.as_deref() else { + return; + }; + if !is_type_alias_annotation(&assign.annotation) { + return; + } + if let Some(name) = simple_name(&assign.target) { + let _ = self.aliases.insert( + name, + AliasEntry { + params: Vec::new(), + value, + }, + ); + } + } + + /// A class declares a nominal type unless it is a `Protocol` (structural) + /// or a `TypedDict` (structural, dict-shaped) — those two stay gradual + /// until the cascade models structural assignability. + fn insert_class(&mut self, class: &'m StmtClassDef) { + let name = class.name.to_string(); + if class_is_structural(class) { + let _ = self.nominal.remove(&name); + return; + } + let _ = self.nominal.insert(name); + } + + /// `import X`, `import X.Y`, `import X as Y`. + fn insert_plain_imports(&mut self, import: &'m ruff_python_ast::StmtImport) { + for alias in &import.names { + let module = alias.name.to_string(); + let bound = alias + .asname + .as_ref() + .map_or_else(|| top_level_module(&module), ToString::to_string); + let _ = self.modules.insert(bound, module); + } + } + + /// `from X import A`, `from X import A as B`. + fn insert_from_imports(&mut self, import: &'m ruff_python_ast::StmtImportFrom) { + let Some(module) = import.module.as_ref().map(ToString::to_string) else { + return; + }; + for alias in &import.names { + let original = alias.name.to_string(); + let bound = alias + .asname + .as_ref() + .map_or_else(|| original.clone(), ToString::to_string); + let _ = self.imports.insert( + bound, + ImportedName { + module: module.clone(), + original, + }, + ); + } + } + + /// Implicit aliases (`X = int`, `MyList = list[int]`) — a second pass, so + /// an alias may name a class or alias declared later in the file + /// (use-before-declaration is legal for type expressions). + fn collect_implicit_aliases(&mut self, body: &'m [Stmt]) { + for stmt in body { + if let Stmt::Assign(assign) = stmt { + self.insert_implicit_alias(assign); + } + for nested in child_bodies(stmt) { + self.collect_implicit_aliases(nested); + } + } + } + + /// A single-target assignment whose right-hand side is a type expression. + fn insert_implicit_alias(&mut self, assign: &'m ruff_python_ast::StmtAssign) { + let [target] = assign.targets.as_slice() else { + return; + }; + let Some(name) = simple_name(target) else { + return; + }; + if self.aliases.contains_key(&name) || self.nominal.contains(&name) { + return; + } + if self.is_type_expression(&assign.value) { + let _ = self.aliases.insert( + name, + AliasEntry { + params: Vec::new(), + value: &assign.value, + }, + ); + } + } + + /// Is `expr` shaped like a type expression whose head names something this + /// module can resolve? Deliberately narrow: `X = 5` and `X = TypeVar("X")` + /// are values, not aliases. + fn is_type_expression(&self, expr: &Expr) -> bool { + match expr { + Expr::Name(name) => self.names_a_type(name.id.as_str()), + Expr::Attribute(_) => dotted_name(expr).is_some(), + Expr::Subscript(sub) => self.is_type_expression(&sub.value), + Expr::BinOp(bin) if bin.op == ruff_python_ast::Operator::BitOr => { + self.is_type_expression(&bin.left) && self.is_type_expression(&bin.right) + } + _ => false, + } + } + + /// Does a bare name denote a type — a builtin, a same-file class, another + /// alias, or an imported symbol? + fn names_a_type(&self, name: &str) -> bool { + super::builtins::is_builtin_type_name(&name.to_ascii_lowercase()) + || self.nominal.contains(name) + || self.aliases.contains_key(name) + || self.imports.contains_key(name) + } +} + +/// Bodies nested inside a compound statement — every scope a declaration may +/// hide in. +fn child_bodies(stmt: &Stmt) -> Vec<&[Stmt]> { + match stmt { + Stmt::ClassDef(class) => vec![class.body.as_slice()], + Stmt::FunctionDef(func) => vec![func.body.as_slice()], + Stmt::If(if_stmt) => std::iter::once(if_stmt.body.as_slice()) + .chain( + if_stmt + .elif_else_clauses + .iter() + .map(|clause| clause.body.as_slice()), + ) + .collect(), + Stmt::For(for_stmt) => vec![for_stmt.body.as_slice(), for_stmt.orelse.as_slice()], + Stmt::While(while_stmt) => vec![while_stmt.body.as_slice(), while_stmt.orelse.as_slice()], + Stmt::With(with_stmt) => vec![with_stmt.body.as_slice()], + Stmt::Try(try_stmt) => std::iter::once(try_stmt.body.as_slice()) + .chain(try_stmt.handlers.iter().map( + |ruff_python_ast::ExceptHandler::ExceptHandler(handler)| handler.body.as_slice(), + )) + .chain([try_stmt.orelse.as_slice(), try_stmt.finalbody.as_slice()]) + .collect(), + Stmt::Match(match_stmt) => match_stmt + .cases + .iter() + .map(|case| case.body.as_slice()) + .collect(), + _ => Vec::new(), + } +} + +/// `Protocol` and `TypedDict` bases make a class structural. +fn class_is_structural(class: &StmtClassDef) -> bool { + class.bases().iter().any(|base| { + let head = match base { + Expr::Subscript(sub) => dotted_name(&sub.value), + other => dotted_name(other), + }; + head.is_some_and(|name| { + let leaf = name.rsplit('.').next().unwrap_or(&name).to_owned(); + leaf == "Protocol" || leaf == "TypedDict" + }) + }) +} + +/// `TypeAlias` / `typing.TypeAlias` in annotation position (PEP 613). +fn is_type_alias_annotation(annotation: &Expr) -> bool { + dotted_name(annotation) + .is_some_and(|name| name == "TypeAlias" || name.ends_with(".TypeAlias")) +} + +/// The top-level component of a dotted module path (`os.path` → `os`). +fn top_level_module(module: &str) -> String { + module.split('.').next().unwrap_or(module).to_owned() +} + +/// The simple name of a `Name` expression. +pub(super) fn simple_name(expr: &Expr) -> Option { + match expr { + Expr::Name(name) => Some(name.id.to_string()), + _ => None, + } +} + +/// The dotted text of a `Name` / `Attribute` chain (`typing.Sequence`). +pub(super) fn dotted_name(expr: &Expr) -> Option { + match expr { + Expr::Name(name) => Some(name.id.to_string()), + Expr::Attribute(attr) => Some(format!("{}.{}", dotted_name(&attr.value)?, attr.attr)), + _ => None, + } +} diff --git a/crates/basilisk-checker/src/lib.rs b/crates/basilisk-checker/src/lib.rs index 3a60e1c6..ac940f73 100644 --- a/crates/basilisk-checker/src/lib.rs +++ b/crates/basilisk-checker/src/lib.rs @@ -31,6 +31,11 @@ //! when configuration resolves it to a non-disabled severity //! ([CHKARCH-COMMANDS]). +/// The single annotation entry point: a type expression resolved through the +/// name cascade. +/// +/// Implements [TYPEINF-ANNOTATION-RESOLUTION]. +pub mod annotation; pub mod bidir; pub mod cached; pub mod class_naming; diff --git a/crates/basilisk-checker/src/rules/returns_compatibility.rs b/crates/basilisk-checker/src/rules/returns_compatibility.rs index 37d6d0fa..d89ef6b2 100644 --- a/crates/basilisk-checker/src/rules/returns_compatibility.rs +++ b/crates/basilisk-checker/src/rules/returns_compatibility.rs @@ -15,8 +15,8 @@ //! return 42 //! ``` +use crate::annotation::AnnotationResolver; use crate::inference::{infer_rhs, literal_collection_assignable_to}; -use crate::span_util::slice_span; use crate::types::InferredType; use basilisk_resolver::{FunctionInfo, ResolvedModule}; @@ -44,10 +44,16 @@ impl Rule for ReturnTypeMismatch { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // The declared type of every return annotation comes from the shared + // cascade ([TYPEINF-ANNOTATION-RESOLUTION]); its tables are built once + // per module, not once per function. + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; for func in &module.functions { // @no_type_check suppresses body checks (E0011); E0041 arity still applies. if !is_stub_context(func, &module.classes) && !is_no_type_check(func) { - check_return_type_mismatch(func, module, diagnostics); + check_return_type_mismatch(func, module, &resolver, diagnostics); } } } @@ -60,6 +66,7 @@ impl Rule for ReturnTypeMismatch { fn check_return_type_mismatch( func: &FunctionInfo, module: &ResolvedModule, + resolver: &AnnotationResolver<'_>, out: &mut Vec, ) { if !func.return_annotation.is_present() { @@ -73,6 +80,23 @@ fn check_return_type_mismatch( return; } + let Some(declared_type) = func + .return_annotation_span + .and_then(|span| resolver.resolve_span(span)) + else { + return; + }; + + // Skip targets the kind-only return inference cannot verify: a + // `Literal[...]` target needs the returned expression's *value* + // (`return True` infers `Bool`, not `Literal[True]`). Names the cascade + // could not resolve are already the gradual `Unknown` and suppress through + // ordinary assignability. Shared with E0013 so the two sibling + // return-mismatch rules stay in lock-step. + if super::shared::is_value_dependent_target(&declared_type) { + return; + } + for return_stmt in &func.return_stmts { if !return_stmt.has_value { continue; @@ -84,13 +108,6 @@ fn check_return_type_mismatch( continue; } - let Some(ann_span) = func.return_annotation_span else { - continue; - }; - let Some(ann_text) = slice_span(&module.source, ann_span) else { - continue; - }; - // Use inference system to get RHS type let inferred_type = infer_rhs(&return_stmt.rhs_kind); @@ -99,20 +116,6 @@ fn check_return_type_mismatch( continue; } - // Parse annotation text to InferredType - let declared_type = InferredType::from_annotation(ann_text); - - // Skip targets the kind-only return inference cannot reliably verify — - // quoted forward references (`"int | Meta2"` → a union of `Named` - // fragments), structural `Named` types (`Sequence[int]`), and - // `Literal[...]` targets (`return True` infers `Bool`, not - // `Literal[True]`). Shared with E0013 so the two sibling return-mismatch - // rules stay in lock-step. Concrete primitive/None/container mismatches - // (e.g. `-> str: return 42`) are NOT unverifiable and still fire. - if super::shared::is_unverifiable_return_type(&declared_type) { - continue; - } - // A returned collection literal is contextually typed against the // declared type ([TYPEINF-SPECIAL-LITERAL-CONTEXT]); a stored value // keeps invariant subtyping. diff --git a/crates/basilisk-checker/src/rules/returns_compatibility_2.rs b/crates/basilisk-checker/src/rules/returns_compatibility_2.rs index 72516fd6..8430e04f 100644 --- a/crates/basilisk-checker/src/rules/returns_compatibility_2.rs +++ b/crates/basilisk-checker/src/rules/returns_compatibility_2.rs @@ -5,8 +5,8 @@ //! assignable to the declared type. This extends the original `-> None` check to //! handle all return type mismatches using the inference system. +use crate::annotation::AnnotationResolver; use crate::inference::{infer_rhs, literal_collection_assignable_to}; -use crate::span_util::slice_span; use crate::types::InferredType; use basilisk_resolver::{FunctionInfo, ResolvedModule, ReturnStmtInfo}; @@ -29,15 +29,25 @@ impl Rule for ReturnTypeMismatch { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // One cascade per module ([TYPEINF-ANNOTATION-RESOLUTION]), shared by + // every function's return annotation. + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; module .functions .iter() .filter(|func| func.return_annotation.is_present()) - .for_each(|func| check_function(func, module, diagnostics)); + .for_each(|func| check_function(func, module, &resolver, diagnostics)); } } -fn check_function(func: &FunctionInfo, module: &ResolvedModule, out: &mut Vec) { +fn check_function( + func: &FunctionInfo, + module: &ResolvedModule, + resolver: &AnnotationResolver<'_>, + out: &mut Vec, +) { // Generator functions have their own return type validation (E0120). // Return values in generators go through Generator[Y, S, R]'s ReturnType, // not the top-level annotation. @@ -45,30 +55,20 @@ fn check_function(func: &FunctionInfo, module: &ResolvedModule, out: &mut Vec bool { +/// A *nominal* target is NOT in this category any more. It used to be: every +/// `InferredType::Named` was treated as unverifiable, which silenced the whole +/// return check for `-> MyClass` and `-> MyAlias` +/// ([#378](https://github.com/Nimblesite/Basilisk/issues/378)). Names now +/// arrive through the annotation cascade +/// ([TYPEINF-ANNOTATION-RESOLUTION](../../../../docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION)), +/// which yields `Named` only for a resolved same-file nominal class and the +/// gradual `Unknown` for anything it cannot resolve — and `Unknown` suppresses +/// through ordinary assignability, with no rule-level skip needed. +/// +/// Both E0011 and E0013 gate their assignability check on this so the two +/// sibling rules stay in lock-step. +pub(crate) fn is_value_dependent_target(ty: &InferredType) -> bool { match ty { - InferredType::Named(_) | InferredType::Literal(_) => true, + InferredType::Literal(_) => true, InferredType::Optional(inner) | InferredType::List(inner) | InferredType::Set(inner) - | InferredType::TypeForm(inner) => is_unverifiable_return_type(inner), + | InferredType::TypeForm(inner) => is_value_dependent_target(inner), InferredType::Dict(key, value) => { - is_unverifiable_return_type(key) || is_unverifiable_return_type(value) + is_value_dependent_target(key) || is_value_dependent_target(value) + } + InferredType::Union(types) | InferredType::Tuple(types) => { + types.iter().any(is_value_dependent_target) } - InferredType::Union(types) => types.iter().any(is_unverifiable_return_type), - // The variable-length form `tuple[X, ...]` parses the `...` terminator to - // `Named("...")`; that is a structural marker handled by `is_assignable_to`, - // not an unresolvable type, so it must not trigger the skip. - InferredType::Tuple(types) => types.iter().any(|elem| { - !matches!(elem, InferredType::Named(name) if name == "...") - && is_unverifiable_return_type(elem) - }), InferredType::Callable(info) => { - is_unverifiable_return_type(&info.return_type) - || info.param_types.iter().any(is_unverifiable_return_type) + is_value_dependent_target(&info.return_type) + || info.param_types.iter().any(is_value_dependent_target) } _ => false, } From aa89199ea494744391d0e1007987438f57024810 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 20:52:45 +1000 Subject: [PATCH 14/45] fixes --- README-pypi.md | 4 +- README.md | 4 +- README.zh.md | 4 +- .../basilisk-checker/src/annotation/forms.rs | 17 +- .../basilisk-checker/src/annotation/index.rs | 5 +- crates/basilisk-checker/src/annotation/mod.rs | 78 ++++- .../basilisk-checker/src/annotation/tables.rs | 19 +- .../assignment_compatibility/enum_expand.rs | 17 +- .../src/rules/assignment_compatibility/mod.rs | 103 ++++--- .../assignment_compatibility/skip_names.rs | 30 -- .../src/rules/redundant_annotation.rs | 14 +- .../src/rules/returns_compatibility.rs | 11 +- .../src/rules/returns_compatibility_2.rs | 14 +- crates/basilisk-checker/src/types.rs | 12 +- .../checker/annotation_resolution_tests.rs | 276 ++++++++++++++++++ .../tests/checker_rules_a_tests.rs | 2 + .../tests/mutation_kill_tests.rs | 62 ++-- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 131 ++++++++- docs/readme/README.src.md | 4 +- docs/readme/README.zh.src.md | 4 +- docs/specs/CHECKER-ARCHITECTURE-SPEC.md | 4 +- vscode-extension/README.md | 4 +- vscode-extension/README.zh.md | 4 +- website/src/_data/conformance_report.json | 8 +- 24 files changed, 666 insertions(+), 165 deletions(-) create mode 100644 crates/basilisk-checker/tests/checker/annotation_resolution_tests.rs diff --git a/README-pypi.md b/README-pypi.md index 21f9494d..8dce27a8 100644 --- a/README-pypi.md +++ b/README-pypi.md @@ -29,8 +29,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a490662), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/README.md b/README.md index 5538dcc9..6f9aa372 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a490662), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/README.zh.md b/README.zh.md index 68382c90..cc8fc45c 100644 --- a/README.zh.md +++ b/README.zh.md @@ -28,8 +28,8 @@

PEP 一致性 100.0% — 官方 - python/typing - 一致性套件（提交 a2e6356）141 项测试中通过 141 项， + python/typing + 一致性套件（提交 a490662）141 项测试中通过 141 项， 由真实的上游评分器在默认配置下对 wheel 安装的 CLI 评出。 我们以 python/typing@main 为目标，且分数只升不降。

diff --git a/crates/basilisk-checker/src/annotation/forms.rs b/crates/basilisk-checker/src/annotation/forms.rs index 51df1a38..cd39d1e3 100644 --- a/crates/basilisk-checker/src/annotation/forms.rs +++ b/crates/basilisk-checker/src/annotation/forms.rs @@ -25,7 +25,9 @@ pub(super) fn special_form( match head { "literal" => Some(literal_union(args)), "optional" => Some(InferredType::Optional(Box::new(first_type(args, &resolve)))), - "union" => Some(InferredType::Union(args.iter().map(|a| resolve(a)).collect())), + "union" => Some(InferredType::Union( + args.iter().map(|a| resolve(a)).collect(), + )), // `Annotated[T, ..]` and `Final[T]` are transparent wrappers. "annotated" | "final" => Some(first_type(args, &resolve)), "typeform" => Some(InferredType::TypeForm(Box::new(first_type(args, &resolve)))), @@ -119,19 +121,18 @@ fn literal_value(expr: &Expr) -> InferredType { Expr::UnaryOp(unary) if unary.op == UnaryOp::USub => negate(literal_value(&unary.operand)), // An enum member (`Color.RED`) or a name: nominal, kept for display and // base-name comparison. - other => super::tables::dotted_name(other) - .map_or(InferredType::Unknown, InferredType::Named), + other => { + super::tables::dotted_name(other).map_or(InferredType::Unknown, InferredType::Named) + } } } /// An integer literal keeps its value; other numeric literals keep their kind. fn number_literal(number: &ruff_python_ast::Number) -> InferredType { match number { - ruff_python_ast::Number::Int(value) => value - .as_i64() - .map_or(InferredType::Int, |int| { - InferredType::Literal(LiteralValue::Int(int)) - }), + ruff_python_ast::Number::Int(value) => value.as_i64().map_or(InferredType::Int, |int| { + InferredType::Literal(LiteralValue::Int(int)) + }), ruff_python_ast::Number::Float(_) | ruff_python_ast::Number::Complex { .. } => { InferredType::Float } diff --git a/crates/basilisk-checker/src/annotation/index.rs b/crates/basilisk-checker/src/annotation/index.rs index 6a7e3346..65244fd7 100644 --- a/crates/basilisk-checker/src/annotation/index.rs +++ b/crates/basilisk-checker/src/annotation/index.rs @@ -23,10 +23,7 @@ pub(super) fn annotation_nodes(module: &ModModule) -> HashMap<(u32, u32), &Expr> /// Record one annotation node, keyed by its exact span. fn record<'m>(expr: &'m Expr, index: &mut HashMap<(u32, u32), &'m Expr>) { let range = expr.range(); - let _ = index.insert( - (u32::from(range.start()), u32::from(range.end())), - expr, - ); + let _ = index.insert((u32::from(range.start()), u32::from(range.end())), expr); } /// Walk every statement body: annotations appear at any nesting depth. diff --git a/crates/basilisk-checker/src/annotation/mod.rs b/crates/basilisk-checker/src/annotation/mod.rs index 622ba420..4d0be568 100644 --- a/crates/basilisk-checker/src/annotation/mod.rs +++ b/crates/basilisk-checker/src/annotation/mod.rs @@ -122,6 +122,55 @@ impl<'m> AnnotationResolver<'m> { .map(|expr| self.resolve(expr)) } + /// Resolve an annotation the resolver holds only as **stored text** — a + /// `ResolvedModule` field that kept the annotation's rendering but not its + /// span. + /// + /// The text is parsed by `ruff` into the type expression it always was and + /// then run through this same cascade, so the caller gets alias expansion, + /// same-file classes and shadowing exactly as `resolve_span` does. It is + /// *not* the condemned text path: nothing here pattern-matches source + /// characters. `None` when the text is not a parseable type expression. + /// + /// Callers that can reach the annotation node should use [`Self::resolve`] + /// or [`Self::resolve_span`]; this seam closes as the resolver's structures + /// grow spans ([NARROWPLAN-INTEGRATION]). + #[must_use] + pub fn resolve_text(&self, text: &str) -> Option { + let parsed = ruff_python_parser::parse_expression(text.trim()).ok()?; + Some(self.resolve(parsed.expr())) + } + + /// Does this type name a class whose assignability is **structural** — a + /// `Protocol` or a `TypedDict`? + /// + /// A rule that compares only *nominally* must abstain on such a target: + /// the name resolved fine, but "is this value that shape?" is a question + /// nominal comparison cannot answer, and answering it anyway is a false + /// positive on spec-valid code. Unions and containers are searched too, so + /// `list[P]` and `P | None` abstain exactly as `P` does. + #[must_use] + pub fn is_structural_target(&self, ty: &InferredType) -> bool { + match ty { + InferredType::Named(name) => self + .tables + .structural + .contains(name.split('[').next().unwrap_or(name)), + InferredType::Union(arms) => arms.iter().any(|arm| self.is_structural_target(arm)), + InferredType::Optional(inner) + | InferredType::List(inner) + | InferredType::Set(inner) + | InferredType::TypeForm(inner) => self.is_structural_target(inner), + InferredType::Dict(key, value) => { + self.is_structural_target(key) || self.is_structural_target(value) + } + InferredType::Tuple(elements) => { + elements.iter().any(|el| self.is_structural_target(el)) + } + _ => false, + } + } + /// The cascade over one type expression. pub(crate) fn eval(&self, expr: &Expr, frame: &Frame) -> InferredType { if frame.depth > MAX_DEPTH { @@ -166,9 +215,15 @@ impl<'m> AnnotationResolver<'m> { let Some(dotted) = tables::dotted_name(expr) else { return InferredType::Unknown; }; - match self.canonical_head(&dotted) { - Some(head) => self.name(&head, frame), - None => InferredType::Unknown, + let Some(head) = self.canonical_head(&dotted) else { + return InferredType::Unknown; + }; + match self.name(&head, frame) { + // `canonical_head` only yields a member for a module the cascade + // knows, so a member with no modelled form is still a name it + // resolved — nominal, not gradual (see [`Self::imported_leaf`]). + InferredType::Unknown => InferredType::Named(head), + resolved => resolved, } } @@ -182,7 +237,8 @@ impl<'m> AnnotationResolver<'m> { }; let nested = frame.nested(); if !self.shadows_special_form(&head) { - if let Some(ty) = forms::special_form(self, &head.to_ascii_lowercase(), &args, &nested) { + if let Some(ty) = forms::special_form(self, &head.to_ascii_lowercase(), &args, &nested) + { return ty; } } @@ -241,10 +297,14 @@ impl<'m> AnnotationResolver<'m> { } /// A name bound by `from typing import X` resolves to the special form it - /// names. Project and third-party symbols stay gradual until the import - /// cascade covers them — the seam - /// [#324](https://github.com/Nimblesite/Basilisk/issues/324) fills, behind - /// this same entry point. + /// names, or — for a member with no modelled form, such as the ABCs + /// `Iterable` and `Hashable` — to that member as a **nominal** type: it is + /// a name the cascade *did* resolve, and calling it gradual would silence + /// judgments the nominal comparison can still make + /// ([#378](https://github.com/Nimblesite/Basilisk/issues/378)). Project and + /// third-party symbols stay gradual until the import cascade covers them — + /// the seam [#324](https://github.com/Nimblesite/Basilisk/issues/324) + /// fills, behind this same entry point. fn imported_leaf(&self, name: &str) -> Option { let imported = self.tables.imports.get(name)?; if !builtins::is_typing_module(&imported.module) { @@ -252,7 +312,7 @@ impl<'m> AnnotationResolver<'m> { } Some( builtins::leaf(&imported.original.to_ascii_lowercase()) - .unwrap_or(InferredType::Unknown), + .unwrap_or_else(|| InferredType::Named(imported.original.clone())), ) } diff --git a/crates/basilisk-checker/src/annotation/tables.rs b/crates/basilisk-checker/src/annotation/tables.rs index 7885df9c..1baf23a4 100644 --- a/crates/basilisk-checker/src/annotation/tables.rs +++ b/crates/basilisk-checker/src/annotation/tables.rs @@ -37,8 +37,13 @@ pub(super) struct ImportedName { pub(super) struct Tables<'m> { /// Alias name → definition (all three alias spellings). pub(super) aliases: HashMap>, - /// Same-file classes that denote a **checkable nominal type**. + /// Same-file classes, by declared name. pub(super) nominal: HashSet, + /// The subset of [`Self::nominal`] whose assignability is **structural** — + /// `Protocol` and `TypedDict` classes. They resolve like any other class; + /// the set exists so a rule that can only compare *nominally* knows to + /// abstain rather than invent a mismatch. + pub(super) structural: HashSet, /// Names bound by `from X import name`. pub(super) imports: HashMap, /// Local binding → module path, for `import X` / `import X as Y`. @@ -122,14 +127,13 @@ impl<'m> Tables<'m> { } } - /// A class declares a nominal type unless it is a `Protocol` (structural) - /// or a `TypedDict` (structural, dict-shaped) — those two stay gradual - /// until the cascade models structural assignability. + /// Every class declares a type the cascade can name. A `Protocol` or + /// `TypedDict` base additionally marks it **structural**, which is a fact + /// about how it is *compared*, not about whether the name resolves. fn insert_class(&mut self, class: &'m StmtClassDef) { let name = class.name.to_string(); if class_is_structural(class) { - let _ = self.nominal.remove(&name); - return; + let _ = self.structural.insert(name.clone()); } let _ = self.nominal.insert(name); } @@ -276,8 +280,7 @@ fn class_is_structural(class: &StmtClassDef) -> bool { /// `TypeAlias` / `typing.TypeAlias` in annotation position (PEP 613). fn is_type_alias_annotation(annotation: &Expr) -> bool { - dotted_name(annotation) - .is_some_and(|name| name == "TypeAlias" || name.ends_with(".TypeAlias")) + dotted_name(annotation).is_some_and(|name| name == "TypeAlias" || name.ends_with(".TypeAlias")) } /// The top-level component of a dotted module path (`os.path` → `os`). diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs index 767bda15..29d1165d 100644 --- a/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs @@ -15,8 +15,11 @@ use crate::rules::guards::is_enum_class; use crate::types::InferredType; /// Member names (lowercase) for every enum class in a module, keyed by the -/// lowercase class name — matching the case-folded `InferredType::Named` -/// spellings produced by annotation parsing. +/// lowercase class name. Both sides of a comparison are folded on the way in +/// ([`enum_expansion_assignable`]), so the table reads the same whether the +/// `Named` spelling came from the [TYPEINF-ANNOTATION-RESOLUTION] cascade — +/// which preserves a class's real case — or from the legacy case-folding +/// annotation parser it replaces. pub(super) type EnumMembers = HashMap>; /// Build the [`EnumMembers`] environment for a module. @@ -57,9 +60,10 @@ pub(super) fn enum_expansion_assignable( declared: &InferredType, enums: &EnumMembers, ) -> bool { - let InferredType::Named(enum_name) = inferred else { + let InferredType::Named(spelling) = inferred else { return false; }; + let enum_name = spelling.to_ascii_lowercase(); let Some(members) = enums.get(enum_name.as_str()) else { return false; }; @@ -71,10 +75,13 @@ pub(super) fn enum_expansion_assignable( single => std::slice::from_ref(single), }; let prefix = format!("{enum_name}."); - let covered: HashSet<&str> = arms + let covered: HashSet = arms .iter() .filter_map(|arm| match arm { - InferredType::Named(name) => name.strip_prefix(prefix.as_str()), + InferredType::Named(name) => name + .to_ascii_lowercase() + .strip_prefix(prefix.as_str()) + .map(str::to_owned), _ => None, }) .collect(); diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs index 559bf94e..978d9e4e 100644 --- a/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs @@ -31,6 +31,7 @@ mod typeform_check; use enum_expand::enum_expansion_assignable; use skip_names::{drop_unchecked_block_diagnostics, SkipNames}; +use crate::annotation::AnnotationResolver; use crate::span_util::slice_span; use crate::types::InferredType; use basilisk_resolver::{ResolvedModule, RhsKind, Span, VariableInfo}; @@ -62,6 +63,9 @@ impl Rule for AssignmentTypeMismatch { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; let empty_params = ParamMaps::default(); let skip = SkipNames::collect(module); let call_index = callable_check::build_index(module); @@ -74,8 +78,9 @@ impl Rule for AssignmentTypeMismatch { &skip, &module.functions, &call_index, + &resolver, ); - check_local_vars(module, diagnostics, &skip, &call_index); + check_local_vars(module, diagnostics, &skip, &call_index, &resolver); check_tuple_reassignments(module, diagnostics); check_dataclass_attr_assignments(module, diagnostics); typeform_check::check_typeform_calls(module, diagnostics); @@ -152,6 +157,7 @@ fn check_vars( skip: &SkipNames, functions: &[basilisk_resolver::FunctionInfo], call_index: &callable_check::CallIndex, + resolver: &AnnotationResolver<'_>, ) { vars.iter() .filter(|var| var.has_annotation && var.rhs_span.is_some()) @@ -164,7 +170,11 @@ fn check_vars( return None; } - let declared_type = InferredType::from_annotation(annotation_text); + // The declared type is the annotation resolved through the shared + // cascade ([TYPEINF-ANNOTATION-RESOLUTION]), so an alias or a + // same-file class is the type it denotes rather than opaque text. + let declared_type = resolver.resolve_text(annotation_text)?; + let declared_nominal = nominal_name(&declared_type); // TypeForm assignments require type-expression validation, not // value-type inference. Delegate to the dedicated module. @@ -182,27 +192,11 @@ fn check_vars( } // Skip TypeAlias-annotated variables — E0048 handles validation. - // The annotation may be `TypeAlias`, `TA`, or any local alias. - { - let ann_lower = annotation_text.trim().to_ascii_lowercase(); - if ann_lower == "typealias" - || ann_lower.ends_with(".typealias") - || matches!(declared_type, InferredType::Named(ref n) if n == "ta") - { - return None; - } - } - - // Skip annotations that reference a PEP 695 type alias or a - // `TypeAliasType(...)` alias. E0014 cannot evaluate the expanded alias - // type, so any assignment check would be unreliable (false positives). - if let InferredType::Named(ref name) = declared_type { - let base = name.split('[').next().unwrap_or(name); - if skip.type_alias.contains(base) - || skip.type_alias_type.contains(&base.to_ascii_lowercase()) - { - return None; - } + // Every spelling — `TypeAlias`, `typing.TypeAlias`, `t.TypeAlias`, + // `from typing import TypeAlias as TA` — resolves to the same name + // through the cascade, so one comparison covers them all. + if declared_nominal.as_deref() == Some("typealias") { + return None; } // Skip dict literal assignments to TypedDict annotations. E0014 compares @@ -239,9 +233,14 @@ fn check_vars( // A reference to a legacy value alias — a recursive `Union` alias // (`Json`) or a generic `list[...]`-bodied alias needing `TypeVar` // substitution (`G[str]`) — needs value-level matching against the - // expanded definition rather than the `Named`-vs-literal comparison - // below. - if let InferredType::Named(ref name) = declared_type { + // expanded definition. It is keyed by the annotation's own + // spelling, not by the resolved type: expanding a *recursive* alias + // through the cascade necessarily makes its recursive arm gradual + // ([TYPEINF-ANNOTATION-RESOLUTION] cycle guard), which would accept + // values this matcher rejects. The matcher dies with the alias + // tables in [NARROWPLAN-INTEGRATION] Step 7. + { + let name = &annotation_text.trim().to_ascii_lowercase(); let ctx = alias_match::AliasCtx { union: &skip.value_aliases, generic: &skip.generic_aliases, @@ -267,8 +266,8 @@ fn check_vars( // cross-name assignment (`v: A = b` where `b: B`). Genuine mismatches // still fire. Only reachable when the RHS resolves to a TypedDict-typed // name (e.g. a parameter), so module-level checks are unaffected. - if let (InferredType::Named(decl), InferredType::Named(inf)) = - (&declared_type, &inferred_type) + if let (Some(decl), Some(inf)) = + (&declared_nominal, nominal_name(&inferred_type)) { if let (Some(target), Some(src)) = ( skip.typeddict_schemas.get(decl.as_str()), @@ -345,10 +344,11 @@ fn check_local_vars( diagnostics: &mut Vec, skip: &SkipNames, call_index: &callable_check::CallIndex, + resolver: &AnnotationResolver<'_>, ) { let source = &module.source; for func in &module.functions { - let params = build_param_maps(&func.parameters, source); + let params = build_param_maps(&func.parameters, source, resolver); check_vars( &func.local_vars, source, @@ -358,13 +358,18 @@ fn check_local_vars( skip, &module.functions, call_index, + resolver, ); } } /// Build maps from parameter name to its declared `InferredType` and raw /// annotation text by reading the annotation from source spans. -fn build_param_maps(params: &[basilisk_resolver::ParameterInfo], source: &str) -> ParamMaps { +fn build_param_maps( + params: &[basilisk_resolver::ParameterInfo], + source: &str, + resolver: &AnnotationResolver<'_>, +) -> ParamMaps { let mut maps = ParamMaps::default(); for param in params { if !param.has_annotation { @@ -376,7 +381,14 @@ fn build_param_maps(params: &[basilisk_resolver::ParameterInfo], source: &str) - let Some(ann_text) = slice_span(source, ann_span) else { continue; }; - let inferred = InferredType::from_annotation(ann_text.trim()); + // The parameter's declared type comes from the same cascade the + // assignment's annotation does ([TYPEINF-ANNOTATION-RESOLUTION]). + let Some(inferred) = resolver + .resolve_span(ann_span) + .or_else(|| resolver.resolve_text(ann_text)) + else { + continue; + }; let _ = maps.types.insert(param.name.clone(), inferred); let _ = maps .texts @@ -385,6 +397,28 @@ fn build_param_maps(params: &[basilisk_resolver::ParameterInfo], source: &str) - maps } +/// A nominal type's spelling, folded to the case this rule's name tables use. +/// +/// Those tables are keyed lower-case, a legacy of +/// `InferredType::from_annotation` having lower-cased every annotation it +/// parsed. The [TYPEINF-ANNOTATION-RESOLUTION] cascade preserves a class's real +/// case, so every lookup folds here rather than at each site — and the tables +/// can be re-keyed in one place once the last lower-casing consumer dies. +fn nominal_name(ty: &InferredType) -> Option { + match ty { + InferredType::Named(name) => Some(name.to_ascii_lowercase()), + _ => None, + } +} + +/// [`nominal_name`] with any subscript stripped — `Pair[int]` keys as `pair`. +fn nominal_key(ty: &InferredType) -> Option { + nominal_name(ty).map(|name| match name.split_once('[') { + Some((base, _)) => base.to_owned(), + None => name, + }) +} + /// `true` when a dict-literal assignment to a `TypedDict` annotation should /// be skipped (field-level checking is E0093's job). fn typeddict_literal_skipped( @@ -393,7 +427,7 @@ fn typeddict_literal_skipped( declared_type: &InferredType, skip: &SkipNames, ) -> bool { - let InferredType::Named(name) = declared_type else { + let Some(name) = nominal_key(declared_type) else { return false; }; skip.typeddict.contains(name.as_str()) @@ -414,11 +448,10 @@ fn extra_items_dict_skipped( if !matches!(declared_type, InferredType::Dict(..)) { return false; } - let InferredType::Named(name) = inferred_type else { + let Some(base) = nominal_key(inferred_type) else { return false; }; - let base = name.split('[').next().unwrap_or(name); - skip.typeddict_extra_items.contains(base) + skip.typeddict_extra_items.contains(base.as_str()) } /// Create diagnostic for inference-based type mismatch. diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs index 8db84164..c7f9037b 100644 --- a/crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/skip_names.rs @@ -19,10 +19,6 @@ pub(super) struct SkipNames { pub(super) typeddict: std::collections::HashSet, /// `TypedDict` classes declaring `extra_items=` (PEP 728, lowercase). pub(super) typeddict_extra_items: std::collections::HashSet, - /// PEP 695 type alias names (lowercase). - pub(super) type_alias: std::collections::HashSet, - /// `TypeAliasType(...)` call LHS names (lowercase). - pub(super) type_alias_type: std::collections::HashSet, /// Legacy value aliases — `Name = Union[...]` or a concrete container such /// as `Name = dict[K, V]` (lowercase → definition), used for alias-expanded /// value matching. @@ -46,8 +42,6 @@ impl SkipNames { Self { typeddict: collect_typeddict_names(module), typeddict_extra_items: collect_extra_items_typeddict_names(module), - type_alias: collect_type_alias_names(module), - type_alias_type: collect_type_alias_type_names(module), value_aliases: alias_match::collect_value_aliases(module), generic_aliases: alias_match::collect_generic_aliases(module), typeddict_schemas: typeddict_struct::build_typeddict_schemas(module), @@ -80,30 +74,6 @@ fn collect_typeddict_names(module: &ResolvedModule) -> std::collections::HashSet names } -/// Collect names of PEP 695 type aliases defined in this module (lowercased). -/// -/// E0014 cannot evaluate expanded type alias types, so annotations that -/// reference a type alias are skipped to avoid false positives. -fn collect_type_alias_names(module: &ResolvedModule) -> std::collections::HashSet { - module - .type_statements - .iter() - .map(|ts| ts.name.to_ascii_lowercase()) - .collect() -} - -/// Collect names defined via `Name = TypeAliasType(...)` (lowercase). -/// -/// E0014 cannot evaluate an expanded `TypeAliasType` alias, so assignments whose -/// declared type references such an alias are skipped to avoid false positives. -fn collect_type_alias_type_names(module: &ResolvedModule) -> std::collections::HashSet { - module - .type_alias_type_calls - .iter() - .map(|call| call.lhs_name.to_ascii_lowercase()) - .collect() -} - /// Names of `TypedDict` classes declaring `extra_items=` (lowercase). /// /// Such `TypedDict`s may be assignable to `dict[str, VT]` (PEP 728), which diff --git a/crates/basilisk-checker/src/rules/redundant_annotation.rs b/crates/basilisk-checker/src/rules/redundant_annotation.rs index 8ad459a1..4dd40a08 100644 --- a/crates/basilisk-checker/src/rules/redundant_annotation.rs +++ b/crates/basilisk-checker/src/rules/redundant_annotation.rs @@ -11,6 +11,7 @@ //! z: float = 42 # NO warning — annotation adds information (widening) //! ``` +use crate::annotation::AnnotationResolver; use crate::inference::infer_rhs; use crate::types::InferredType; use basilisk_resolver::ResolvedModule; @@ -43,6 +44,13 @@ impl Rule for RedundantAnnotationWarning { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // The declared type comes from the shared cascade + // ([TYPEINF-ANNOTATION-RESOLUTION]): an annotation that is redundant + // *through an alias* (`type Age = int` then `x: Age = 1`) is redundant + // all the same, and a name we cannot resolve is gradual, never a guess. + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; // Check module-level variables module .module_vars @@ -59,8 +67,7 @@ impl Rule for RedundantAnnotationWarning { return None; } - // Parse annotation text to InferredType using existing parser - let declared_type = InferredType::from_annotation(annotation_text); + let declared_type = resolver.resolve_text(annotation_text)?; // Check if annotation is redundant (base type match) if types_match_for_w0050(&inferred_type, &declared_type) { @@ -112,8 +119,7 @@ impl Rule for RedundantAnnotationWarning { return None; } - // Parse annotation text to InferredType using existing parser - let declared_type = InferredType::from_annotation(annotation_text); + let declared_type = resolver.resolve_text(annotation_text)?; // Check if annotation is redundant (base type match) if types_match_for_w0050(&inferred_type, &declared_type) { diff --git a/crates/basilisk-checker/src/rules/returns_compatibility.rs b/crates/basilisk-checker/src/rules/returns_compatibility.rs index d89ef6b2..72a06dc5 100644 --- a/crates/basilisk-checker/src/rules/returns_compatibility.rs +++ b/crates/basilisk-checker/src/rules/returns_compatibility.rs @@ -87,13 +87,16 @@ fn check_return_type_mismatch( return; }; - // Skip targets the kind-only return inference cannot verify: a - // `Literal[...]` target needs the returned expression's *value* - // (`return True` infers `Bool`, not `Literal[True]`). Names the cascade + // Skip targets this rule cannot verify: a `Literal[...]` target needs the + // returned expression's *value* (`return True` infers `Bool`, not + // `Literal[True]`), and a `Protocol` / `TypedDict` target is satisfied + // structurally, which a kind comparison cannot judge. Names the cascade // could not resolve are already the gradual `Unknown` and suppress through // ordinary assignability. Shared with E0013 so the two sibling // return-mismatch rules stay in lock-step. - if super::shared::is_value_dependent_target(&declared_type) { + if super::shared::is_value_dependent_target(&declared_type) + || resolver.is_structural_target(&declared_type) + { return; } diff --git a/crates/basilisk-checker/src/rules/returns_compatibility_2.rs b/crates/basilisk-checker/src/rules/returns_compatibility_2.rs index 8430e04f..1a2c5038 100644 --- a/crates/basilisk-checker/src/rules/returns_compatibility_2.rs +++ b/crates/basilisk-checker/src/rules/returns_compatibility_2.rs @@ -64,11 +64,15 @@ fn check_function( // A `Literal[...]` target needs the returned expression's *value*, which // the kind-only return inference does not have (`return True` infers - // `Bool`, not `Literal[True]`), so it is skipped — recursively, since a - // union or container containing one is equally value-dependent. Names the - // cascade could not resolve are already the gradual `Unknown` and suppress - // through ordinary assignability ([TYPEINF-ANNOTATION-RESOLUTION]). - if super::shared::is_value_dependent_target(&declared_type) { + // `Bool`, not `Literal[True]`), and a `Protocol` / `TypedDict` target is + // satisfied structurally rather than by kind — both are skipped, + // recursively, since a union or container containing one is equally + // unjudgeable here. Names the cascade could not resolve are already the + // gradual `Unknown` and suppress through ordinary assignability + // ([TYPEINF-ANNOTATION-RESOLUTION]). + if super::shared::is_value_dependent_target(&declared_type) + || resolver.is_structural_target(&declared_type) + { return; } diff --git a/crates/basilisk-checker/src/types.rs b/crates/basilisk-checker/src/types.rs index 7c8f1d26..63e608d5 100644 --- a/crates/basilisk-checker/src/types.rs +++ b/crates/basilisk-checker/src/types.rs @@ -265,9 +265,15 @@ impl InferredType { ) // None is always assignable to Optional[T] | (InferredType::None_, InferredType::Optional(_)) => true, - // `None` satisfies `Hashable` (it defines `__hash__`). The annotation - // parser lowercases names, so the ABC arrives as `Named("hashable")`. - (InferredType::None_, InferredType::Named(name)) if name == "hashable" => true, + // `None` satisfies `Hashable` (it defines `__hash__`). Compared + // case-insensitively: the [TYPEINF-ANNOTATION-RESOLUTION] cascade + // keeps the ABC's real spelling, the legacy annotation parser it + // replaces folded it to `Named("hashable")`. + (InferredType::None_, InferredType::Named(name)) + if name.eq_ignore_ascii_case("hashable") => + { + true + } // Union on the LEFT decomposes before Optional-target unwrapping: // `A | None <: Optional[B]` must check each variant against the // whole `Optional[B]` (so the `None` arm can satisfy it), not diff --git a/crates/basilisk-checker/tests/checker/annotation_resolution_tests.rs b/crates/basilisk-checker/tests/checker/annotation_resolution_tests.rs new file mode 100644 index 00000000..16b88500 --- /dev/null +++ b/crates/basilisk-checker/tests/checker/annotation_resolution_tests.rs @@ -0,0 +1,276 @@ +//! Tests for [TYPEINF-ANNOTATION-RESOLUTION]. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION +// +// The cascade is exercised through `returns_compatibility`, the first rule +// migrated onto `crate::annotation::AnnotationResolver`. Every case here was +// RED before the cascade landed: `InferredType::from_annotation()` turned each of these annotations into an opaque `Named(..)`, and +// `shared::is_unverifiable_return_type` skipped every `Named` — so a wrong +// return through an alias or a same-file class drew nothing at all +// (Refs #378). + +use super::common::*; + +type TestResult = Result<(), Box>; + +/// Assert `returns_compatibility` fires — the annotation resolved to a +/// checkable type and the returned value does not fit it. +fn assert_fires(source: &str, why: &str) -> TestResult { + let diags = run(source)?; + assert!( + codes(&diags).contains(&"returns_compatibility"), + "{why}, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +/// Assert silence — either the value fits, or the name is genuinely +/// unresolvable and stays gradual. +fn assert_silent(source: &str, why: &str) -> TestResult { + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"returns_compatibility"), + "{why}, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +// --------------------------------------------------------------------------- +// Step 1 of the cascade — the type-alias table +// --------------------------------------------------------------------------- + +#[test] +fn pep695_type_alias_target_is_checked() -> TestResult { + assert_fires( + "type MyInt = int\n\ndef f() -> MyInt:\n return \"x\"\n", + "a PEP 695 alias must expand to `int` and reject a str return", + ) +} + +#[test] +fn pep695_type_alias_target_accepts_matching_value() -> TestResult { + assert_silent( + "type MyInt = int\n\ndef f() -> MyInt:\n return 1\n", + "expanding the alias must not make a correct return fire", + ) +} + +#[test] +fn explicit_typealias_target_is_checked() -> TestResult { + assert_fires( + "from typing import TypeAlias\n\nMyInt: TypeAlias = int\n\ndef f() -> MyInt:\n return \"x\"\n", + "an `X: TypeAlias = ...` declaration must expand like a PEP 695 alias", + ) +} + +#[test] +fn implicit_alias_target_is_checked() -> TestResult { + assert_fires( + "MyInt = int\n\ndef f() -> MyInt:\n return \"x\"\n", + "an implicit alias (`X = `) must expand", + ) +} + +#[test] +fn alias_chain_expands_to_the_root_type() -> TestResult { + assert_fires( + "type A = B\ntype B = int\n\ndef f() -> A:\n return \"x\"\n", + "an alias chain must expand transitively to `int`", + ) +} + +#[test] +fn alias_used_before_declaration_still_expands() -> TestResult { + // Declaration order must not decide resolution: the tables are built for + // the whole module before any annotation is resolved. + assert_fires( + "def f() -> Later:\n return \"x\"\n\ntype Later = int\n", + "an alias declared AFTER the function must still expand", + ) +} + +#[test] +fn implicit_alias_may_reference_a_later_declaration() -> TestResult { + assert_fires( + "Early = Late\ntype Late = int\n\ndef f() -> Early:\n return \"x\"\n", + "the implicit-alias pass runs after the explicit one, so forward references resolve", + ) +} + +#[test] +fn alias_expands_at_every_nesting_depth() -> TestResult { + assert_fires( + "type Elem = int\n\ndef f() -> list[Elem]:\n return [\"x\"]\n", + "an alias nested inside `list[..]` must expand", + ) +} + +#[test] +fn alias_nested_two_levels_deep_expands() -> TestResult { + assert_fires( + "type Elem = int\n\ndef f() -> dict[str, list[Elem]]:\n return {\"k\": [\"x\"]}\n", + "alias transparency is not depth-limited", + ) +} + +#[test] +fn generic_alias_binds_its_parameter() -> TestResult { + assert_fires( + "type Pair[T] = list[T]\n\ndef f() -> Pair[int]:\n return [\"x\"]\n", + "a parameterised alias must substitute its argument", + ) +} + +#[test] +fn recursive_alias_terminates_and_stays_silent() -> TestResult { + // Refs #371. The cycle guard must stop expansion without rejecting the + // alias — an infinite expansion would hang the checker. + assert_silent( + "type J = list[J]\n\ndef f() -> J:\n return []\n", + "a recursive alias must terminate and not fire", + ) +} + +#[test] +fn non_type_assignment_is_not_an_alias() -> TestResult { + // `X = 5` binds a value, not a type. Treating it as an alias would resolve + // the annotation to nonsense; it must stay gradual instead. + assert_silent( + "MyInt = 5\n\ndef f() -> MyInt:\n return \"x\"\n", + "a value binding must not be read as a type alias", + ) +} + +// --------------------------------------------------------------------------- +// Step 2 of the cascade — the same-file class table +// --------------------------------------------------------------------------- + +#[test] +fn same_file_class_target_is_checked() -> TestResult { + assert_fires( + "class C:\n pass\n\ndef f() -> C:\n return 42\n", + "a resolvable same-file class is nominal — an int literal cannot satisfy it", + ) +} + +#[test] +fn same_file_class_declared_after_use_is_checked() -> TestResult { + assert_fires( + "def f() -> C:\n return 42\n\nclass C:\n pass\n", + "class resolution must not depend on declaration order", + ) +} + +#[test] +fn nested_class_target_is_checked() -> TestResult { + assert_fires( + "class Outer:\n class Inner:\n pass\n\ndef f() -> Inner:\n return 42\n", + "classes are collected at any nesting depth", + ) +} + +#[test] +fn protocol_class_target_stays_gradual() -> TestResult { + // Structural assignability is not modelled yet, so a Protocol target must + // NOT be treated as nominal — doing so would be a false positive on + // spec-valid code. + assert_silent( + "from typing import Protocol\n\nclass P(Protocol):\n pass\n\ndef f() -> P:\n return 42\n", + "a Protocol target must stay gradual until structural typing lands", + ) +} + +#[test] +fn typeddict_class_target_stays_gradual() -> TestResult { + assert_silent( + "from typing import TypedDict\n\nclass T(TypedDict):\n a: int\n\ndef f() -> T:\n return {}\n", + "a TypedDict target is structural and must stay gradual", + ) +} + +#[test] +fn user_class_shadowing_a_builtin_wins() -> TestResult { + // Builtins are consulted LAST, so a module-level declaration shadows one + // exactly as Python does: this `int` is the user's class, and a str + // literal does not satisfy it. + assert_fires( + "class int:\n pass\n\ndef f() -> int:\n return \"x\"\n", + "a same-file class must shadow the builtin of the same name", + ) +} + +// --------------------------------------------------------------------------- +// Step 3 of the cascade — imports (typeshed seam left for #324) +// --------------------------------------------------------------------------- + +#[test] +fn unresolved_imported_name_stays_gradual() -> TestResult { + // Project-symbol resolution is not delivered yet; until it is, an + // imported name is `Unknown` and must suppress rather than guess. + assert_silent( + "from other_module import Thing\n\ndef f() -> Thing:\n return 42\n", + "an unresolved imported name must stay gradual, never fire", + ) +} + +#[test] +fn imported_typing_alias_resolves_through_its_original_name() -> TestResult { + // `from typing import List as L` must resolve `L` to `list`, which means + // keeping the ORIGINAL name across the alias. + assert_fires( + "from typing import List as L\n\ndef f() -> L[int]:\n return \"x\"\n", + "an aliased typing import must resolve through its original name", + ) +} + +#[test] +fn typing_attribute_spelling_resolves() -> TestResult { + assert_fires( + "import typing\n\ndef f() -> typing.List[int]:\n return \"x\"\n", + "the `typing.X` attribute spelling must resolve like the bare member", + ) +} + +#[test] +fn aliased_typing_module_attribute_spelling_resolves() -> TestResult { + assert_fires( + "import typing as t\n\ndef f() -> t.List[int]:\n return \"x\"\n", + "`t.List` must resolve when `t` is bound to the typing module", + ) +} + +// --------------------------------------------------------------------------- +// Step 5 of the cascade — forward references +// --------------------------------------------------------------------------- + +#[test] +fn quoted_alias_forward_reference_expands() -> TestResult { + assert_fires( + "type MyInt = int\n\ndef f() -> \"MyInt\":\n return \"x\"\n", + "a string annotation is re-parsed and re-resolved through the same cascade", + ) +} + +#[test] +fn quoted_same_file_class_forward_reference_resolves() -> TestResult { + assert_fires( + "def f() -> \"C\":\n return 42\n\nclass C:\n pass\n", + "the classic forward-reference spelling must resolve to the class", + ) +} + +// --------------------------------------------------------------------------- +// The `Literal` skip — the ONLY remaining value-dependent suppression +// --------------------------------------------------------------------------- + +#[test] +fn literal_alias_target_stays_suppressed() -> TestResult { + // `is_value_dependent_target` recurses THROUGH the resolved alias: the + // kind-only return inference cannot see that `True` is `Literal[True]`. + assert_silent( + "from typing import Literal\n\ntype Flag = Literal[True]\n\ndef f() -> Flag:\n return True\n", + "a Literal reached through an alias must still suppress", + ) +} diff --git a/crates/basilisk-checker/tests/checker_rules_a_tests.rs b/crates/basilisk-checker/tests/checker_rules_a_tests.rs index ad2098cc..1329a4c8 100644 --- a/crates/basilisk-checker/tests/checker_rules_a_tests.rs +++ b/crates/basilisk-checker/tests/checker_rules_a_tests.rs @@ -14,6 +14,8 @@ clippy::uninlined_format_args, dead_code )] +#[path = "checker/annotation_resolution_tests.rs"] +mod annotation_resolution; #[path = "checker/annotations_typeexpr_tests.rs"] mod annotations_typeexpr; #[path = "checker/assignment_compatibility_tests.rs"] diff --git a/crates/basilisk-checker/tests/mutation_kill_tests.rs b/crates/basilisk-checker/tests/mutation_kill_tests.rs index 2b7cf5c6..8251a43b 100644 --- a/crates/basilisk-checker/tests/mutation_kill_tests.rs +++ b/crates/basilisk-checker/tests/mutation_kill_tests.rs @@ -523,29 +523,34 @@ c: int = "hello" } // ═══════════════════════════════════════════════════════════════════════ -// E0014 check_vars: type-alias annotation skip (lines 289–290) +// E0014 check_vars: assignment through a type alias // ═══════════════════════════════════════════════════════════════════════ -/// Kills mutant: e0014/mod.rs:290 `replace || with &&` in the type-alias skip -/// guard (`skip.type_alias.contains(base) || skip.type_alias_type.contains(..)`). -/// E0014 cannot evaluate an expanded alias, so an annotation referencing a PEP -/// 695 `type` alias OR a `TypeAliasType(...)` alias must be skipped (no E0014), -/// while a genuine `int`-vs-`str` mismatch must still fire. Each alias form sets -/// exactly ONE operand true, so flipping `||`→`&&` makes neither skip: both -/// alias lines would then be processed and wrongly fire E0014, raising the count -/// from 1 to 3 — observably killing the mutant. Keeping both forms also pins the -/// individual operands against future deletion mutants. +/// Kills mutants of `check_vars`'s declared-type resolution. E0014 obtains the +/// declared type from the [TYPEINF-ANNOTATION-RESOLUTION] cascade, which +/// expands a PEP 695 `type` alias transparently — so `a: loweralias = "hello"` +/// is judged against `list[int]` and FIRES. This replaced a blanket skip of +/// every alias-annotated assignment, which suppressed exactly this error +/// ([#378](https://github.com/Nimblesite/Basilisk/issues/378)); a mutant that +/// stops expanding the alias, or that reinstates the skip, drops the count +/// from 2 to 1 and is caught here. +/// +/// `TypeAliasType(...)` is a *call*, not a type expression, so the cascade +/// cannot expand it: that name stays gradual and its assignment stays silent — +/// pinning the boundary between "resolved, therefore judged" and "unresolved, +/// therefore gradual". A mutant that guesses a type for the unresolved name +/// raises the count to 3. #[mutation_safe(rule = "assignment_compatibility", fns = "check_vars")] #[test] -fn mutant_e0014_type_alias_skip() -> Result<(), Box> { +fn mutant_e0014_type_alias_expansion() -> Result<(), Box> { let source = r#" from typing import TypeAliasType -# PEP 695 type alias (lowercase name) → only `skip.type_alias` matches. +# PEP 695 type alias — the cascade expands it to `list[int]`. type loweralias = list[int] a: loweralias = "hello" -# TypeAliasType alias → only `skip.type_alias_type` matches. +# TypeAliasType alias — a call, not a type expression: gradual. Bar = TypeAliasType("Bar", int) b: Bar = "hello" @@ -553,17 +558,28 @@ b: Bar = "hello" c: int = "hello" "#; let diagnostics = run(source)?; - let e0014 = assignment_compatibility_count(&diagnostics); + let messages: Vec<_> = diagnostics + .iter() + .filter(|d| d.code.code == "assignment_compatibility") + .map(|d| d.message.clone()) + .collect(); assert_eq!( - e0014, - 1, - "both alias-annotated assignments are skipped; only `c: int = \"hello\"` \ - fires, got {e0014}: {:?}", - diagnostics - .iter() - .filter(|d| d.code.code == "assignment_compatibility") - .map(|d| &d.message) - .collect::>() + messages.len(), + 2, + "the alias-expanded `a` and the direct `c` both fire; the gradual `b` \ + does not: {messages:?}" + ); + assert!( + messages.iter().any(|m| m.contains("`a`")), + "the alias must expand to `list[int]` and reject a str: {messages:?}" + ); + assert!( + messages.iter().any(|m| m.contains("`c`")), + "the direct int-vs-str mismatch must still fire: {messages:?}" + ); + assert!( + !messages.iter().any(|m| m.contains("`b`")), + "an unexpandable `TypeAliasType` name is gradual, never guessed: {messages:?}" ); Ok(()) } diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index 093af088..97064eb0 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -636,21 +636,103 @@ Prerequisite for Stage 2; see lands with a regression test that fails before it and passes after, and holds the conformance ratchets (100% / 0 false positives) at every step. -- [ ] Add one shared `resolve_annotation(module, expr) → InferredType` entry +**The test step is part of the box, never a phase at the end.** A box is `[x]` +only when its own nested `[x] Test:` line names a test that (a) was written and +run RED against the pre-box code, and (b) is green now — and the next box does +not start until that has happened. A box whose code landed but whose test has +not run is `[~]`, not `[x]`. + +- [x] Add one shared `resolve_annotation(module, expr) → InferredType` entry point implementing the [TYPEINF-ANNOTATION-RESOLUTION](../specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION) cascade over the Ruff AST annotation node, replacing - `InferredType::from_annotation()`. No rule may parse annotation - text after this lands. -- [ ] Resolve PEP 695 `type` aliases, `X: TypeAlias = ...`, and implicit + `InferredType::from_annotation()`. + — `crates/basilisk-checker/src/annotation/`, exported as `crate::annotation` + from `lib.rs`: `mod.rs` (the five-step cascade + `AnnotationResolver`, + frame-scoped alias params, `MAX_DEPTH`/`visiting` termination), `tables.rs` + (alias / nominal-class / import tables), `builtins.rs` (leaf names, consulted + LAST so a module-level declaration shadows a builtin as Python does), + `forms.rs` (typing special forms, `Literal` values read from AST literal + nodes so radix and case survive), `index.rs` (span → annotation-node map). + `AnnotationResolver::for_module` builds the tables once per module off the + shared `lazy_ast`; `resolve_span` maps a resolver-recorded span straight back + to its AST node, so a rule holding only a span resolves a *type expression* + and never slices source. `resolve_span` returns `None` — caller stays silent + — rather than falling back to text. + - [x] Test: `cargo test -p basilisk-checker --test checker_rules_a_tests` + (237 passed) — the two migrated rules keep every pre-existing behaviour, + including `literal_target_not_flagged`, + `quoted_forward_ref_union_not_flagged`, `return_mismatch_stub_exempt` and + the contextual list/dict/tuple literal cases. +- [ ] Retire the remaining `InferredType::from_annotation()` call + sites behind the same entry point, so **no rule parses annotation text**. + Migrated so far: `returns_compatibility`, `returns_compatibility_2`. Still on + text: `assignment_compatibility/{mod,alias_match,typeform_check}.rs`, + `annotations_generators{,_helpers}.rs`, `calls_argument_type/arg_types.rs`, + `redundant_annotation.rs`, `generics_scoping.rs`, `narrow/{guards,flow}.rs`, + `param_infer.rs`, `incremental_defs.rs`, `types_star_tuples.rs`, + `tyeval/lower.rs::ground_from_text`, `basilisk-lsp/src/hover/receiver_scope.rs`. + `types_parsing.rs` is deleted by the last one + ([#379](https://github.com/Nimblesite/Basilisk/issues/379), Step 7). + - [ ] Test: each migration keeps its own rule's existing suite green, and the + `grep -rn "from_annotation" crates --include="*.rs"` count strictly + decreases per commit; the final commit asserts zero. +- [x] Resolve PEP 695 `type` aliases, `X: TypeAlias = ...`, and implicit aliases, including alias chains and use-before-declaration; expand transparently at every nesting depth. -- [ ] Resolve same-file classes, then imported project symbols; leave typeshed + — `annotation/tables.rs`: `Stmt::TypeAlias`, `Stmt::AnnAssign` gated on a + `TypeAlias` annotation, and a second implicit-alias pass (so an implicit + alias may reference a class or alias declared LATER — use-before-declaration + falls out of the two-pass build, not out of ordering luck). Aliases are + collected at any nesting depth; `mod.rs::expand_alias` substitutes params + through a `Frame` and re-enters the cascade, so nesting + (`-> list[MyAlias]`) and chains (`A = B`, `B = int`) expand transparently. + `is_type_expression` is deliberately narrow so `X = 5` and + `X = TypeVar("X")` are not aliases. + - [x] Test: `tests/checker/annotation_resolution_tests.rs` (new file, mounted + in `checker_rules_a_tests.rs`) — `type A = int`, `A: TypeAlias = int`, + implicit `A = int`, chain `A = B` / `B = int`, `list[A]`, + `dict[str, list[A]]`, generic `Pair[T] = list[T]`, alias-after-use, and + implicit-alias-of-a-later-declaration each FIRE on a wrong return; + `type J = list[J]` terminates silent, `MyInt = 5` is not read as an alias, + and a correct return stays silent. **RED proof**: with + `returns_compatibility` temporarily reverted to + `from_annotation(slice_span(..))` + the blanket `Named` skip, 15 of the 25 + cases fail; restoring the cascade makes all 25 pass. +- [x] Resolve same-file classes, then imported project symbols; leave typeshed behind the same entry point so [#324](https://github.com/Nimblesite/Basilisk/issues/324) can fill it without a second call path. -- [ ] Replace the blanket `Named` skip in `rules/shared.rs::is_unverifiable_return_type` + — Same-file classes: `tables.rs::build` records every `ClassDef` as nominal + EXCEPT `Protocol`/`TypedDict` bases, which are structural and stay gradual + (structural assignability is not modelled yet, so treating them as nominal + would be a false positive). Imports: `tables.rs` keeps the ORIGINAL name + across `from X import A as B` (built from the AST, because + `ImportInfo::names` loses it), and `mod.rs::imported_leaf` resolves `typing` + / `typing_extensions` members while returning the gradual `Unknown` for + every other module — that single `imported_leaf` arm is the seam #324 fills. + Project-symbol resolution is NOT delivered; only the seam is. + - [x] Test: `tests/checker/annotation_resolution_tests.rs` — a same-file + `class C` target fires on `return 42` (declared before OR after the + function, nested in another class, and through the `"C"` forward-reference + spelling), a user `class int` shadows the builtin, `from typing import + List as L` / `typing.List` / `t.List` all resolve; `class P(Protocol)`, + `class T(TypedDict)` and an unresolved `from other_module import Thing` + stay silent. Same RED proof run as the box above. +- [x] Replace the blanket `Named` skip in `rules/shared.rs::is_unverifiable_return_type` with a resolved/unresolved split, narrowing it one category at a time as the cascade covers that category. + — `is_unverifiable_return_type` is DELETED. `rules/shared.rs` now exposes + `is_value_dependent_target`, whose `Named` arm is gone entirely: the only + skip left is `Literal[...]` (and unions/containers/callables containing one), + which the kind-only return inference genuinely cannot verify because + `return True` infers `Bool`, not `Literal[True]`. Unresolved names no longer + need a skip at all — they arrive from the cascade as the gradual `Unknown` + and suppress through ordinary assignability. This is the + [#378](https://github.com/Nimblesite/Basilisk/issues/378) defect class closed + at the source. + - [x] Test: `cargo test -p basilisk-checker --test checker_rules_a_tests` + (237 passed) — `Literal` targets still suppress, and no previously-silent + case started firing. - [x] Terminating cycle detection for recursive aliases: `type J = list[J]`, `type J = int | list[J]`, `type J = dict[str, J]`, and the canonical `JsonValue` union all produce **no** diagnostic @@ -661,6 +743,9 @@ the conformance ratchets (100% / 0 false positives) at every step. `Unguarded`/`NonRegular` verdicts. All four #371 forms (plus a JsonValue arm-order permutation) are pinned clean in `tests/checker/generics_syntax_scoping_tests.rs`. + - [x] Test: `cargo test -p basilisk-checker generics_syntax_scoping` — all + four #371 forms plus the arm-order permutation assert an empty diagnostic + set, and the genuinely-unguarded cases still fire. - [x] Add PEP 695 `type`-statement counterparts of every recursive case in upstream `aliases_recursive.py` to our own suite — the upstream file contains zero `type` statements, which is why this false positive survived a 100% @@ -672,19 +757,51 @@ the conformance ratchets (100% / 0 false positives) at every step. `Union[..]` spellings, the `MutualReference` pair) pinned firing. Value-level assignability THROUGH these aliases is the annotation-resolution cascade's box above, not this one. + - [x] Test: `cargo test -p basilisk-checker aliases_recursive` — every + recursive DEFINITION pinned clean, both cyclical-reference cases pinned + firing. - [ ] Resolve decorator expressions through the binding table so `o = overload` is recognised as `typing.overload`; cover `from typing import overload as ov` and `typing.overload` / `t.overload` attribute spellings - ([#380](https://github.com/Nimblesite/Basilisk/issues/380)). + ([#380](https://github.com/Nimblesite/Basilisk/issues/380)). The binding + table is `annotation/tables.rs`'s import map plus a value-binding pass; + `mod.rs::canonical_head` already rewrites the alias and attribute spellings + and is the function decorator resolution reuses. + - [ ] Test (write RED first): all four spellings of an `@overload` chain + (`overload`, `ov`, `typing.overload`, `t.overload`, `o = overload`) are + accepted, and a non-overload decorator named `overload` from another module + is NOT. - [ ] Visit calls in every expression position rather than statement-outermost only, so `C(1).method()` reports the same constructor-arity error as `C(1)` ([#381](https://github.com/Nimblesite/Basilisk/issues/381)). + - [ ] Test (write RED first): `C(1).method()`, `f(C(1))`, `[C(1)]`, + `x = C(1) if p else C(1)` each report the same arity diagnostic as the bare + `C(1)` statement, at the same span. - [ ] Bind functions assigned in a class body as methods — implicit receiver consumed on instance access, unbound on class access, `staticmethod` / `classmethod` honoured ([#382](https://github.com/Nimblesite/Basilisk/issues/382)). + - [ ] Test (write RED first): `C().m(1)` where `m = f` and `def f(self, a)` + is accepted; `C.m(1)` is an arity error; `staticmethod`/`classmethod` + wrappers shift the receiver accordingly. - [ ] Wire the shared entry point into the `bidir` engine, which currently has no name resolution at all and is consumed by only two rules (`narrowing_typeguard`, `narrowing_typeis_2`). + - [ ] Test (write RED first): a `TypeGuard[MyAlias]` / `TypeIs[MyClass]` + narrows to the RESOLVED type, not to an opaque name, in both consuming + rules. + +**Gates owed by Stage 0.5 as a whole** — run after the boxes above, and again +before the stage is declared closed: + +- [ ] `cargo test --workspace` green (fail-fast, coverage enforced against + `coverage-thresholds.json`). +- [ ] `cargo clippy --workspace --all-targets` clean at the repo's lint level. +- [ ] `python3 conformance/run_conformance.py` — 100% / 0 false positives from + a fresh `python/typing@main` clone against a clean `--release` build + ([CHKARCH-CONFORMANCE]). +- [ ] Torture golden suite 8/8 (`tests/torture_golden_tests.rs`). +- [ ] `make bench` — no fixture slower than the committed baseline + ([CHKARCH-TESTING-BENCH-RATCHET]). ### Stage 1 — incrementality diff --git a/docs/readme/README.src.md b/docs/readme/README.src.md index c6abdf12..a5e547e1 100644 --- a/docs/readme/README.src.md +++ b/docs/readme/README.src.md @@ -40,8 +40,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a490662), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/docs/readme/README.zh.src.md b/docs/readme/README.zh.src.md index bda0da37..e0faa7dc 100644 --- a/docs/readme/README.zh.src.md +++ b/docs/readme/README.zh.src.md @@ -35,8 +35,8 @@

PEP 一致性 100.0% — 官方 - python/typing - 一致性套件（提交 a2e6356）141 项测试中通过 141 项， + python/typing + 一致性套件（提交 a490662）141 项测试中通过 141 项， 由真实的上游评分器在默认配置下对 wheel 安装的 CLI 评出。 我们以 python/typing@main 为目标，且分数只升不降。

diff --git a/docs/specs/CHECKER-ARCHITECTURE-SPEC.md b/docs/specs/CHECKER-ARCHITECTURE-SPEC.md index 0ac09a35..f5246ff2 100644 --- a/docs/specs/CHECKER-ARCHITECTURE-SPEC.md +++ b/docs/specs/CHECKER-ARCHITECTURE-SPEC.md @@ -264,7 +264,7 @@ configuration/editor behavior is specified by ### Python Typing PEP Coverage {#CHKARCH-PEPS} -Basilisk's **target** is 100% conformance with the Python typing specification. We measure against the latest **`python/typing@main`**, recording the exact graded commit by hash in `conformance_report.json` (currently [`a2e6356`](https://github.com/python/typing/tree/a2e6356af2f609a7ab2330895477d0d08181a169/conformance)). Today the official scorer, run unmodified in CI on the binary in its default configuration (the PEP conformance set; see [CHKARCH-CONFORMANCE-MODE](#CHKARCH-CONFORMANCE-MODE)), reports **141 of 141 files passing (100.0%)**, with **0 false positives** and **0 missed required errors** (970 caught). We run that suite in CI on every change; the gate ratchets the pass-percentage **up** and the false-positive ceiling **down** — closed only by fixing the checker, never by disabling a rule. +Basilisk's **target** is 100% conformance with the Python typing specification. We measure against the latest **`python/typing@main`**, recording the exact graded commit by hash in `conformance_report.json` (currently [`a490662`](https://github.com/python/typing/tree/a4906624f170c169cf667f962080c56d5a5ba6ff/conformance)). Today the official scorer, run unmodified in CI on the binary in its default configuration (the PEP conformance set; see [CHKARCH-CONFORMANCE-MODE](#CHKARCH-CONFORMANCE-MODE)), reports **141 of 141 files passing (100.0%)**, with **0 false positives** and **0 missed required errors** (970 caught). We run that suite in CI on every change; the gate ratchets the pass-percentage **up** and the false-positive ceiling **down** — closed only by fixing the checker, never by disabling a rule. #### Foundation PEPs {#CHKARCH-PEPS-FOUNDATION} @@ -1464,7 +1464,7 @@ that official check did not run against a freshly cloned suite is a BUILD FAILUR **down**. Per-file results are written to `conformance/conformance_status.csv`. - **Current score** — measured against `python/typing@main` at the exact graded commit recorded in `conformance_report.json`, currently - [`a2e6356`](https://github.com/python/typing/tree/a2e6356af2f609a7ab2330895477d0d08181a169/conformance): + [`a490662`](https://github.com/python/typing/tree/a4906624f170c169cf667f962080c56d5a5ba6ff/conformance): **141 / 141 = 100.0%**, **0 false positives**, **0 missed required errors**, with **970** required errors caught. The binary runs in its default configuration — the PEP conformance set — over a fresh `python/typing` clone whose tree holds no diff --git a/vscode-extension/README.md b/vscode-extension/README.md index 999ef5dd..d38c955c 100644 --- a/vscode-extension/README.md +++ b/vscode-extension/README.md @@ -29,8 +29,8 @@

100.0% PEP conformance — 141 of 141 tests in the official - python/typing - conformance suite (commit a2e6356), scored on the wheel-installed CLI in its default config by the real upstream harness. + python/typing + conformance suite (commit a490662), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

diff --git a/vscode-extension/README.zh.md b/vscode-extension/README.zh.md index 3ee8aaa3..85fd5bb2 100644 --- a/vscode-extension/README.zh.md +++ b/vscode-extension/README.zh.md @@ -28,8 +28,8 @@

PEP 一致性 100.0% — 官方 - python/typing - 一致性套件（提交 a2e6356）141 项测试中通过 141 项， + python/typing + 一致性套件（提交 a490662）141 项测试中通过 141 项， 由真实的上游评分器在默认配置下对 wheel 安装的 CLI 评出。 我们以 python/typing@main 为目标，且分数只升不降。

diff --git a/website/src/_data/conformance_report.json b/website/src/_data/conformance_report.json index 2dc4424d..be93eca0 100644 --- a/website/src/_data/conformance_report.json +++ b/website/src/_data/conformance_report.json @@ -3,13 +3,13 @@ "upstream": { "repo": "python/typing", "ref": "main", - "sha": "a2e6356af2f609a7ab2330895477d0d08181a169", - "shortSha": "a2e6356", - "commitDate": "2026-08-03", + "sha": "a4906624f170c169cf667f962080c56d5a5ba6ff", + "shortSha": "a490662", + "commitDate": "2026-08-04", "stale": false }, "calculator": { - "file": "python/typing@a2e6356:conformance/src/main.py", + "file": "python/typing@a490662:conformance/src/main.py", "sha256": "3cb2a27bfc689e89a541528f8bdaa8ed24ae8845ce048eaff69717ef0205b112", "bytes": 10810, "funcs": [ From 4ace1130012a82999b67b0042ce4e674606edd32 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 20:52:56 +1000 Subject: [PATCH 15/45] fixes --- crates/basilisk-checker/src/annotation/mod.rs | 42 +++++ .../basilisk-checker/src/annotation/tables.rs | 10 ++ .../src/rules/overloads_basic.rs | 10 +- .../src/rules/overloads_consistency.rs | 16 +- .../src/rules/overloads_consistency_2.rs | 22 ++- .../src/rules/overloads_consistency_3.rs | 29 ++-- .../src/rules/overloads_definitions.rs | 11 +- .../src/rules/overloads_evaluation.rs | 10 +- crates/basilisk-checker/src/rules/shared.rs | 19 +++ .../checker/decorator_resolution_tests.rs | 152 ++++++++++++++++++ .../tests/checker_rules_a_tests.rs | 2 + .../src/visitor/class_info_ext.rs | 43 ++--- 12 files changed, 313 insertions(+), 53 deletions(-) create mode 100644 crates/basilisk-checker/tests/checker/decorator_resolution_tests.rs diff --git a/crates/basilisk-checker/src/annotation/mod.rs b/crates/basilisk-checker/src/annotation/mod.rs index 4d0be568..068da4b4 100644 --- a/crates/basilisk-checker/src/annotation/mod.rs +++ b/crates/basilisk-checker/src/annotation/mod.rs @@ -141,6 +141,48 @@ impl<'m> AnnotationResolver<'m> { Some(self.resolve(parsed.expr())) } + /// Does `spelling` — a decorator expression rendered as a dotted name — + /// denote the typing-module member `member`? + /// + /// The same binding question an annotation asks, answered by the same + /// tables ([#380](https://github.com/Nimblesite/Basilisk/issues/380)): + /// value re-bindings are followed first (`o = overload`, chains included), + /// then the import tables decide. `from typing import overload as ov` + /// and `t.overload` under `import typing as t` are the member; the same + /// spellings bound from any OTHER module are not — a decorator merely + /// *named* `overload` must not conjure an overload group. A bare unbound + /// spelling equal to `member` is accepted, matching Python's tolerance of + /// the name arriving via re-exports the table cannot see. + #[must_use] + pub fn decorator_denotes(&self, spelling: &str, member: &str) -> bool { + let mut current = spelling.to_owned(); + for _ in 0..MAX_DEPTH { + match self.tables.values.get(¤t) { + Some(next) => current = next.clone(), + None => break, + } + } + match current.split_once('.') { + Some((head, attr)) => attr == member && self.head_is_typing_module(head), + None => match self.tables.imports.get(¤t) { + Some(imported) => { + imported.original == member && builtins::is_typing_module(&imported.module) + } + None => current == member, + }, + } + } + + /// Is `head` a binding of (or literally) the typing module? + fn head_is_typing_module(&self, head: &str) -> bool { + match self.tables.modules.get(head) { + Some(module) => builtins::is_typing_module(module), + // Unbound heads keep the literal spellings only, so a foreign + // module aliased to `typing` cannot smuggle members in. + None => builtins::is_typing_module(head), + } + } + /// Does this type name a class whose assignability is **structural** — a /// `Protocol` or a `TypedDict`? /// diff --git a/crates/basilisk-checker/src/annotation/tables.rs b/crates/basilisk-checker/src/annotation/tables.rs index 1baf23a4..ecf9891a 100644 --- a/crates/basilisk-checker/src/annotation/tables.rs +++ b/crates/basilisk-checker/src/annotation/tables.rs @@ -48,6 +48,11 @@ pub(super) struct Tables<'m> { pub(super) imports: HashMap, /// Local binding → module path, for `import X` / `import X as Y`. pub(super) modules: HashMap, + /// Value re-bindings of one name to another: `o = overload`, + /// `o = typing.overload`. The decorator resolution follows these chains + /// ([#380](https://github.com/Nimblesite/Basilisk/issues/380)); annotation + /// resolution does not consult them. + pub(super) values: HashMap, } impl<'m> Tables<'m> { @@ -193,6 +198,11 @@ impl<'m> Tables<'m> { let Some(name) = simple_name(target) else { return; }; + // Any name-to-name re-binding joins the value table (`o = overload`), + // whether or not it also reads as a type alias below. + if let Some(rhs) = dotted_name(&assign.value) { + let _ = self.values.insert(name.clone(), rhs); + } if self.aliases.contains_key(&name) || self.nominal.contains(&name) { return; } diff --git a/crates/basilisk-checker/src/rules/overloads_basic.rs b/crates/basilisk-checker/src/rules/overloads_basic.rs index b1066c3e..bbb8f105 100644 --- a/crates/basilisk-checker/src/rules/overloads_basic.rs +++ b/crates/basilisk-checker/src/rules/overloads_basic.rs @@ -44,6 +44,10 @@ impl Rule for NoMatchingOverload { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // Overload membership is a binding question ([#380]). + let Some(resolver) = crate::annotation::AnnotationResolver::for_module(module) else { + return; + }; let source = &module.source; let path = &module.path; @@ -81,11 +85,7 @@ impl Rule for NoMatchingOverload { if func.name != "__getitem__" { continue; } - if !func - .decorators - .iter() - .any(|d| d == "overload" || d.ends_with(".overload")) - { + if !super::shared::overload_decorated(&resolver, &func.decorators) { continue; } let Some(class_name) = func.class_name.as_deref() else { diff --git a/crates/basilisk-checker/src/rules/overloads_consistency.rs b/crates/basilisk-checker/src/rules/overloads_consistency.rs index 3f29947f..9785bd88 100644 --- a/crates/basilisk-checker/src/rules/overloads_consistency.rs +++ b/crates/basilisk-checker/src/rules/overloads_consistency.rs @@ -13,8 +13,10 @@ use std::collections::HashMap; use basilisk_resolver::{FunctionInfo, ResolvedModule}; +use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; +use super::shared::overload_decorated; use super::Rule; const CODE: ErrorCode = ErrorCode { @@ -33,11 +35,16 @@ impl Rule for OverlappingOverloads { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // Whether a decorator IS `typing.overload` is answered by the + // resolver's binding tables ([#380]), shared with every overload rule. + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; // Group overloaded functions by (class_name, function_name) so overloads // in different classes with the same method name don't cross-contaminate. let mut groups: HashMap<(Option<&str>, &str), Vec<&FunctionInfo>> = HashMap::new(); for func in &module.functions { - if has_overload_decorator(&func.decorators) { + if overload_decorated(&resolver, &func.decorators) { groups .entry((func.class_name.as_deref(), &func.name)) .or_default() @@ -123,13 +130,6 @@ fn signatures_overlap(a: &FunctionInfo, b: &FunctionInfo) -> bool { .all(|(pa, pb)| pa.annotation_text == pb.annotation_text) } -/// Returns `true` if `"overload"` (or `"typing.overload"`) is in the list. -fn has_overload_decorator(decorators: &[String]) -> bool { - decorators - .iter() - .any(|d| d == "overload" || d.ends_with(".overload")) -} - fn make_diagnostic(func: &FunctionInfo, func_name: &str, path: &str) -> Diagnostic { error_diagnostic_owned( CODE.clone(), diff --git a/crates/basilisk-checker/src/rules/overloads_consistency_2.rs b/crates/basilisk-checker/src/rules/overloads_consistency_2.rs index a50c6d2b..9437cf92 100644 --- a/crates/basilisk-checker/src/rules/overloads_consistency_2.rs +++ b/crates/basilisk-checker/src/rules/overloads_consistency_2.rs @@ -15,8 +15,10 @@ use std::collections::HashMap; use basilisk_resolver::{FunctionInfo, ResolvedModule, Span}; +use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; +use super::shared::overload_decorated; use super::Rule; const CODE: ErrorCode = ErrorCode { @@ -40,6 +42,11 @@ impl Rule for OverloadDecoratorConsistency { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // Overload membership is a binding question ([#380]); the + // staticmethod/final/override checks below stay spelling-based. + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; let mut groups: HashMap<(Option<&str>, &str), Vec<&FunctionInfo>> = HashMap::new(); for func in &module.functions { groups @@ -49,20 +56,27 @@ impl Rule for OverloadDecoratorConsistency { } for funcs in groups.values() { - check_group(funcs, &module.path, diagnostics); + check_group(funcs, &resolver, &module.path, diagnostics); } } } -fn check_group(funcs: &[&FunctionInfo], path: &str, out: &mut Vec) { +fn check_group( + funcs: &[&FunctionInfo], + resolver: &AnnotationResolver<'_>, + path: &str, + out: &mut Vec, +) { let overloads: Vec<&&FunctionInfo> = funcs .iter() - .filter(|f| has_dec(&f.decorators, "overload")) + .filter(|f| overload_decorated(resolver, &f.decorators)) .collect(); if overloads.is_empty() { return; } - let implementation = funcs.iter().find(|f| !has_dec(&f.decorators, "overload")); + let implementation = funcs + .iter() + .find(|f| !overload_decorated(resolver, &f.decorators)); match implementation { // Group WITH an implementation: `@final`/`@override` belong on the diff --git a/crates/basilisk-checker/src/rules/overloads_consistency_3.rs b/crates/basilisk-checker/src/rules/overloads_consistency_3.rs index 293a0f5f..c5049880 100644 --- a/crates/basilisk-checker/src/rules/overloads_consistency_3.rs +++ b/crates/basilisk-checker/src/rules/overloads_consistency_3.rs @@ -22,19 +22,15 @@ use crate::span_util::slice_span; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; +use super::shared::overload_decorated; use super::Rule; +use crate::annotation::AnnotationResolver; const CODE: ErrorCode = ErrorCode { code: "overloads_consistency_3", docs_url: "https://www.basilisk-python.dev/errors/overloads_consistency_3", }; -fn has_overload(decorators: &[String]) -> bool { - decorators - .iter() - .any(|d| d == "overload" || d.ends_with(".overload")) -} - /// `true` if a decorator only conveys typing intent and leaves the call /// signature unchanged. Any *other* decorator may transform the effective /// signature (the spec applies such transforms before consistency checks), so a @@ -96,6 +92,10 @@ impl Rule for OverloadImplConsistency { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // Overload membership is a binding question ([#380]). + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; let mut groups: HashMap<(Option<&str>, &str), Vec<&FunctionInfo>> = HashMap::new(); for func in &module.functions { groups @@ -104,17 +104,26 @@ impl Rule for OverloadImplConsistency { .push(func); } for funcs in groups.values() { - check_group(funcs, &module.source, &module.path, diagnostics); + check_group(funcs, &resolver, &module.source, &module.path, diagnostics); } } } -fn check_group(funcs: &[&FunctionInfo], source: &str, path: &str, out: &mut Vec) { +fn check_group( + funcs: &[&FunctionInfo], + resolver: &AnnotationResolver<'_>, + source: &str, + path: &str, + out: &mut Vec, +) { let overloads: Vec<&&FunctionInfo> = funcs .iter() - .filter(|f| has_overload(&f.decorators)) + .filter(|f| overload_decorated(resolver, &f.decorators)) .collect(); - let Some(impl_fn) = funcs.iter().find(|f| !has_overload(&f.decorators)) else { + let Some(impl_fn) = funcs + .iter() + .find(|f| !overload_decorated(resolver, &f.decorators)) + else { return; }; if overloads.len() < 2 || group_is_transformed(funcs) { diff --git a/crates/basilisk-checker/src/rules/overloads_definitions.rs b/crates/basilisk-checker/src/rules/overloads_definitions.rs index e8f5f86c..fcdd17a3 100644 --- a/crates/basilisk-checker/src/rules/overloads_definitions.rs +++ b/crates/basilisk-checker/src/rules/overloads_definitions.rs @@ -12,9 +12,11 @@ use std::collections::HashMap; use basilisk_resolver::{FunctionInfo, ResolvedModule}; +use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; use super::guards::is_protocol_class; +use super::shared::overload_decorated; use super::Rule; @@ -36,6 +38,11 @@ impl Rule for MissingOverloadImpl { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // Whether a decorator IS `typing.overload` is a binding question, + // answered by the resolver's tables ([#380]) — never by its spelling. + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; // Build a set of Protocol class names so we can exempt their methods. // ABC classes are NOT blanket-exempt: only their `@abstractmethod` // overload groups skip the implementation requirement — a *non*-abstract @@ -60,7 +67,7 @@ impl Rule for MissingOverloadImpl { for ((class_name, name), funcs) in &groups { let overloaded: Vec<&&FunctionInfo> = funcs .iter() - .filter(|f| has_decorator(&f.decorators, "overload")) + .filter(|f| overload_decorated(&resolver, &f.decorators)) .collect(); // No @overload decorators in this group — nothing to check. @@ -70,7 +77,7 @@ impl Rule for MissingOverloadImpl { let non_overloaded: Vec<&&FunctionInfo> = funcs .iter() - .filter(|f| !has_decorator(&f.decorators, "overload")) + .filter(|f| !overload_decorated(&resolver, &f.decorators)) .collect(); // Case 1: ALL definitions carry @overload (no implementation). diff --git a/crates/basilisk-checker/src/rules/overloads_evaluation.rs b/crates/basilisk-checker/src/rules/overloads_evaluation.rs index aee66201..e7968915 100644 --- a/crates/basilisk-checker/src/rules/overloads_evaluation.rs +++ b/crates/basilisk-checker/src/rules/overloads_evaluation.rs @@ -42,6 +42,10 @@ impl Rule for OverloadUnionExpansionFailure { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { + // Overload membership is a binding question ([#380]). + let Some(resolver) = crate::annotation::AnnotationResolver::for_module(module) else { + return; + }; let source = &module.source; let path = &module.path; @@ -54,11 +58,7 @@ impl Rule for OverloadUnionExpansionFailure { if !func.is_stub_body { continue; } - if !func - .decorators - .iter() - .any(|d| d == "overload" || d.ends_with(".overload")) - { + if !super::shared::overload_decorated(&resolver, &func.decorators) { continue; } overload_groups diff --git a/crates/basilisk-checker/src/rules/shared.rs b/crates/basilisk-checker/src/rules/shared.rs index 5706ff58..5d7370ba 100644 --- a/crates/basilisk-checker/src/rules/shared.rs +++ b/crates/basilisk-checker/src/rules/shared.rs @@ -17,12 +17,31 @@ pub(crate) use text_scan::{ use std::collections::HashSet; +use crate::annotation::AnnotationResolver; use crate::span_util::slice_span; use crate::types::InferredType; use basilisk_parser::ParsedModule; use basilisk_resolver::{ResolvedModule, Span, TypeVarCallInfo}; use ruff_python_ast::{self as ast, Expr}; +/// Is one of `decorators` the `typing.overload` decorator? +/// +/// Resolved through the module's binding tables +/// ([TYPEINF-ANNOTATION-RESOLUTION], [#380](https://github.com/Nimblesite/Basilisk/issues/380)): +/// `@overload`, `@ov` after `from typing import overload as ov`, +/// `@typing.overload` / `@t.overload`, and `@o` after `o = overload` all +/// answer yes; a decorator merely *named* `overload` but bound from another +/// module answers no. Every rule that reasons about overload groups shares +/// this one predicate so the groups they form agree. +pub(crate) fn overload_decorated( + resolver: &AnnotationResolver<'_>, + decorators: &[String], +) -> bool { + decorators + .iter() + .any(|decorator| resolver.decorator_denotes(decorator, "overload")) +} + /// Returns `true` when the annotation text denotes a `ClassVar[...]` type. /// /// `ClassVar` fields are excluded from the dataclass `__init__` parameter list, diff --git a/crates/basilisk-checker/tests/checker/decorator_resolution_tests.rs b/crates/basilisk-checker/tests/checker/decorator_resolution_tests.rs new file mode 100644 index 00000000..683fd16d --- /dev/null +++ b/crates/basilisk-checker/tests/checker/decorator_resolution_tests.rs @@ -0,0 +1,152 @@ +//! Tests for [TYPEINF-ANNOTATION-RESOLUTION] decorator resolution. See +//! docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md#TYPEINF-ANNOTATION-RESOLUTION +// +// A decorator is a *name*, and whether `@ov` means `typing.overload` is the +// same binding question an annotation asks — answered by the resolver's +// import map plus its value-binding pass, never by matching the spelling +// (Refs #380). Observed through `overloads_definitions`: an `@overload` +// chain with NO implementation fires exactly when the decorator truly is +// `typing.overload`. + +use super::common::*; + +type TestResult = Result<(), Box>; + +/// The decorator spelling denotes `typing.overload`, so the impl-less chain +/// draws `overloads_definitions`. +fn assert_recognised(source: &str, why: &str) -> TestResult { + let diags = run(source)?; + assert!( + codes(&diags).contains(&"overloads_definitions"), + "{why}, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +/// The decorator spelling does NOT denote `typing.overload`, so no overload +/// rule may fire. +fn assert_not_overload(source: &str, why: &str) -> TestResult { + let diags = run(source)?; + assert!( + !codes(&diags) + .iter() + .any(|code| code.starts_with("overloads_")), + "{why}, got: {:?}", + codes(&diags) + ); + Ok(()) +} + +/// A complete chain (two overloads + implementation) under this spelling is +/// accepted — zero diagnostics of any kind. +fn assert_chain_accepted(source: &str, why: &str) -> TestResult { + let diags = run(source)?; + assert!(diags.is_empty(), "{why}, got: {:?}", codes(&diags)); + Ok(()) +} + +// --------------------------------------------------------------------------- +// The four spellings the binding table must resolve +// --------------------------------------------------------------------------- + +#[test] +fn bare_overload_import_is_recognised() -> TestResult { + assert_recognised( + "from typing import overload\n\n@overload\ndef f(a: int) -> int: ...\n@overload\ndef f(a: str) -> str: ...\n", + "`from typing import overload` + `@overload` is typing.overload; an impl-less chain must fire", + ) +} + +#[test] +fn aliased_overload_import_is_recognised() -> TestResult { + assert_recognised( + "from typing import overload as ov\n\n@ov\ndef f(a: int) -> int: ...\n@ov\ndef f(a: str) -> str: ...\n", + "`from typing import overload as ov` binds `ov` to typing.overload (#380)", + ) +} + +#[test] +fn typing_attribute_overload_is_recognised() -> TestResult { + assert_recognised( + "import typing\n\n@typing.overload\ndef f(a: int) -> int: ...\n@typing.overload\ndef f(a: str) -> str: ...\n", + "`@typing.overload` is the attribute spelling of typing.overload", + ) +} + +#[test] +fn aliased_module_attribute_overload_is_recognised() -> TestResult { + assert_recognised( + "import typing as t\n\n@t.overload\ndef f(a: int) -> int: ...\n@t.overload\ndef f(a: str) -> str: ...\n", + "`import typing as t` makes `@t.overload` the same decorator", + ) +} + +#[test] +fn value_bound_overload_is_recognised() -> TestResult { + // The value-binding pass: `o = overload` re-binds the SAME function + // object, so `@o` is `@overload` to the type system. + assert_recognised( + "from typing import overload\n\no = overload\n\n@o\ndef f(a: int) -> int: ...\n@o\ndef f(a: str) -> str: ...\n", + "`o = overload` binds `o` to typing.overload (#380)", + ) +} + +#[test] +fn value_bound_attribute_overload_is_recognised() -> TestResult { + assert_recognised( + "import typing\n\no = typing.overload\n\n@o\ndef f(a: int) -> int: ...\n@o\ndef f(a: str) -> str: ...\n", + "`o = typing.overload` resolves through the value chain to typing.overload", + ) +} + +// --------------------------------------------------------------------------- +// Accepted chains — the same spellings with an implementation are clean +// --------------------------------------------------------------------------- + +#[test] +fn aliased_overload_chain_with_impl_is_accepted() -> TestResult { + assert_chain_accepted( + "from typing import overload as ov\n\n@ov\ndef f(a: int) -> int: ...\n@ov\ndef f(a: str) -> str: ...\ndef f(a: int | str) -> int | str:\n return a\n", + "a complete `@ov` chain is a valid overload group", + ) +} + +#[test] +fn value_bound_overload_chain_with_impl_is_accepted() -> TestResult { + assert_chain_accepted( + "from typing import overload\n\no = overload\n\n@o\ndef f(a: int) -> int: ...\n@o\ndef f(a: str) -> str: ...\ndef f(a: int | str) -> int | str:\n return a\n", + "a complete `@o` chain (o = overload) is a valid overload group", + ) +} + +// --------------------------------------------------------------------------- +// Discrimination — a decorator merely NAMED overload is not typing.overload +// --------------------------------------------------------------------------- + +#[test] +fn foreign_overload_import_is_not_typing_overload() -> TestResult { + // `from mymod import overload` binds SOME callable that happens to share + // the name. Treating it as typing.overload invents an overload group — + // and an "incomplete chain" error — out of spec-valid code. + assert_not_overload( + "from mymod import overload\n\n@overload\ndef f(a: int) -> int: ...\n@overload\ndef f(a: str) -> str: ...\n", + "a foreign decorator named `overload` must not form an overload group (#380)", + ) +} + +#[test] +fn foreign_module_attribute_overload_is_not_typing_overload() -> TestResult { + assert_not_overload( + "import mymod as t\n\n@t.overload\ndef f(a: int) -> int: ...\n@t.overload\ndef f(a: str) -> str: ...\n", + "`t.overload` where `t` binds a foreign module is not typing.overload (#380)", + ) +} + +#[test] +fn value_bound_foreign_overload_is_not_typing_overload() -> TestResult { + assert_not_overload( + "from mymod import overload\n\no = overload\n\n@o\ndef f(a: int) -> int: ...\n@o\ndef f(a: str) -> str: ...\n", + "the value chain ends at a foreign name, so `@o` is not typing.overload", + ) +} diff --git a/crates/basilisk-checker/tests/checker_rules_a_tests.rs b/crates/basilisk-checker/tests/checker_rules_a_tests.rs index 1329a4c8..4d4c4032 100644 --- a/crates/basilisk-checker/tests/checker_rules_a_tests.rs +++ b/crates/basilisk-checker/tests/checker_rules_a_tests.rs @@ -29,6 +29,8 @@ mod classes_override; #[path = "checker/classes_override_2_tests.rs"] mod classes_override_2; mod common; +#[path = "checker/decorator_resolution_tests.rs"] +mod decorator_resolution; #[path = "checker/dict_key_hashable_tests.rs"] mod dict_key_hashable; #[path = "checker/dict_key_hashable_group_tests.rs"] diff --git a/crates/basilisk-resolver/src/visitor/class_info_ext.rs b/crates/basilisk-resolver/src/visitor/class_info_ext.rs index c8e7d0dd..c5169e57 100644 --- a/crates/basilisk-resolver/src/visitor/class_info_ext.rs +++ b/crates/basilisk-resolver/src/visitor/class_info_ext.rs @@ -505,33 +505,38 @@ fn case_has_structural_pattern(case: &MatchCase) -> bool { // Decorator helpers // --------------------------------------------------------------------------- -/// Extract the `frozen=True/False` flag from `@dataclass(frozen=...)`. -/// Returns `false` if no explicit `frozen=` is present (default is `False`). +/// A decorator's name as spelled — the FULL dotted path for attribute +/// spellings (`typing.overload` → `"typing.overload"`, never just +/// `"overload"`), because whether `t.overload` IS `typing.overload` is a +/// binding question the consumer answers by resolving `t` +/// ([#380](https://github.com/Nimblesite/Basilisk/issues/380)). Dropping the +/// qualifier here would make that question unanswerable everywhere +/// downstream. A call decorator reports its callee (`@cache(size=1)` → +/// `"cache"`). pub(super) fn decorator_name(dec: &Decorator) -> Option { match &dec.expression { - Expr::Name(name) => Some(name.id.to_string()), - Expr::Attribute(attr) => Some(attr.attr.to_string()), - Expr::Call(call) => match call.func.as_ref() { - Expr::Name(name) => Some(name.id.to_string()), - Expr::Attribute(attr) => Some(attr.attr.to_string()), - _ => None, - }, - _ => None, + Expr::Call(call) => dotted_expr_name(&call.func), + expr => dotted_expr_name(expr), } } /// Extract the decorator name together with the span of the name identifier. pub(super) fn decorator_name_and_span(dec: &Decorator) -> Option<(String, Span)> { match &dec.expression { - Expr::Name(name) => Some((name.id.to_string(), text_range_to_span(name.range()))), - Expr::Attribute(attr) => Some((attr.attr.to_string(), text_range_to_span(attr.range()))), - Expr::Call(call) => match call.func.as_ref() { - Expr::Name(name) => Some((name.id.to_string(), text_range_to_span(name.range()))), - Expr::Attribute(attr) => { - Some((attr.attr.to_string(), text_range_to_span(attr.range()))) - } - _ => None, - }, + Expr::Call(call) => { + dotted_expr_name(&call.func).map(|name| (name, text_range_to_span(call.func.range()))) + } + expr => dotted_expr_name(expr).map(|name| (name, text_range_to_span(expr.range()))), + } +} + +/// Render `a.b.c` from a name or attribute chain; `None` for anything else. +fn dotted_expr_name(expr: &Expr) -> Option { + match expr { + Expr::Name(name) => Some(name.id.to_string()), + Expr::Attribute(attr) => { + dotted_expr_name(&attr.value).map(|value| format!("{value}.{}", attr.attr)) + } _ => None, } } From 003024a1fb1801947d095912606585f435baadf7 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:02:21 +1000 Subject: [PATCH 16/45] fixes --- .../src/rules/calls_argument_count.rs | 4 +- .../src/rules/constructors_call_init/mod.rs | 4 +- .../rules/constructors_call_type/helpers.rs | 4 +- .../dataclasses_transform_class/helpers.rs | 2 +- .../src/rules/enums_members_2.rs | 3 +- .../src/rules/generics_self_usage.rs | 2 +- crates/basilisk-checker/src/rules/guards.rs | 8 +- .../src/rules/missing_parameter_annotation.rs | 4 +- .../protocols_definition_2/conformance.rs | 17 ++- .../src/rules/redundant_annotation.rs | 9 +- crates/basilisk-checker/src/rules/shared.rs | 12 ++ .../calls_expression_position_tests.rs | 117 ++++++++++++++++++ .../tests/checker_rules_a_tests.rs | 2 + .../code_actions/refactor/abstract_methods.rs | 6 +- crates/basilisk-lsp/src/semantic_tokens.rs | 7 +- .../src/visitor/calls_and_reveal.rs | 51 +++----- .../src/visitor/cast_calls.rs | 63 ---------- .../src/visitor/dataclass.rs | 4 +- crates/basilisk-resolver/src/visitor/mod.rs | 11 +- .../basilisk-resolver/src/visitor/protocol.rs | 6 +- crates/basilisk-resolver/src/visitor/walks.rs | 50 ++++---- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 37 ++++-- 22 files changed, 255 insertions(+), 168 deletions(-) create mode 100644 crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs delete mode 100644 crates/basilisk-resolver/src/visitor/cast_calls.rs diff --git a/crates/basilisk-checker/src/rules/calls_argument_count.rs b/crates/basilisk-checker/src/rules/calls_argument_count.rs index fbdb29b7..a536ac99 100644 --- a/crates/basilisk-checker/src/rules/calls_argument_count.rs +++ b/crates/basilisk-checker/src/rules/calls_argument_count.rs @@ -547,7 +547,7 @@ fn find_constructor_method<'a>( // Use the first non-overload __new__, or the first one let new_fn = new_methods .iter() - .find(|f| !f.decorators.iter().any(|d| d == "overload")) + .find(|f| !super::shared::decorator_spelled(&f.decorators, "overload")) .or_else(|| new_methods.first()); if let Some(func) = new_fn { return Some(func); @@ -558,7 +558,7 @@ fn find_constructor_method<'a>( if let Some(init_methods) = method_map.get(&(class_name, "__init__")) { let init_fn = init_methods .iter() - .find(|f| !f.decorators.iter().any(|d| d == "overload")) + .find(|f| !super::shared::decorator_spelled(&f.decorators, "overload")) .or_else(|| init_methods.first()); if let Some(func) = init_fn { return Some(func); diff --git a/crates/basilisk-checker/src/rules/constructors_call_init/mod.rs b/crates/basilisk-checker/src/rules/constructors_call_init/mod.rs index 5d61ad3b..1462fc42 100644 --- a/crates/basilisk-checker/src/rules/constructors_call_init/mod.rs +++ b/crates/basilisk-checker/src/rules/constructors_call_init/mod.rs @@ -109,7 +109,7 @@ fn check_class_scoped_typevars_in_self( for init_func in init_funcs { // Skip overload decorators — only check the implementation. - if init_func.decorators.iter().any(|d| d == "overload") { + if crate::rules::shared::decorator_spelled(&init_func.decorators, "overload") { continue; } @@ -307,7 +307,7 @@ fn check_subscript_constructor( if let Some(init_funcs) = method_map.get(&(class_name, "__init__")) { for init_func in init_funcs { - if init_func.decorators.iter().any(|d| d == "overload") { + if crate::rules::shared::decorator_spelled(&init_func.decorators, "overload") { continue; } check_init_method_args( diff --git a/crates/basilisk-checker/src/rules/constructors_call_type/helpers.rs b/crates/basilisk-checker/src/rules/constructors_call_type/helpers.rs index f17c6644..e593db59 100644 --- a/crates/basilisk-checker/src/rules/constructors_call_type/helpers.rs +++ b/crates/basilisk-checker/src/rules/constructors_call_type/helpers.rs @@ -140,7 +140,7 @@ fn check_metaclass_call( pub(super) fn sig_from_funcs(funcs: &[&basilisk_resolver::FunctionInfo]) -> ConstructorSig { // Pick the first non-overload function. for func in funcs { - if func.decorators.iter().any(|d| d == "overload") { + if crate::rules::shared::decorator_spelled(&func.decorators, "overload") { continue; } // If it has *args or **kwargs, we can't know the exact arity. @@ -298,7 +298,7 @@ pub(super) fn find_constructor_func<'a>( for method in &["__new__", "__init__"] { if let Some(funcs) = method_map.get(&(class_name, method)) { for func in funcs { - if !func.decorators.iter().any(|d| d == "overload") { + if !crate::rules::shared::decorator_spelled(&func.decorators, "overload") { return Some(func); } } diff --git a/crates/basilisk-checker/src/rules/dataclasses_transform_class/helpers.rs b/crates/basilisk-checker/src/rules/dataclasses_transform_class/helpers.rs index 65b05812..d6dae510 100644 --- a/crates/basilisk-checker/src/rules/dataclasses_transform_class/helpers.rs +++ b/crates/basilisk-checker/src/rules/dataclasses_transform_class/helpers.rs @@ -87,7 +87,7 @@ pub(super) fn collect_transform_base_classes( let has_dt = cls .decorator_spans .iter() - .any(|(name, _)| name == "dataclass_transform"); + .any(|(name, _)| name.rsplit('.').next() == Some("dataclass_transform")); if !has_dt { continue; } diff --git a/crates/basilisk-checker/src/rules/enums_members_2.rs b/crates/basilisk-checker/src/rules/enums_members_2.rs index 0b0ed7cb..35d859ad 100644 --- a/crates/basilisk-checker/src/rules/enums_members_2.rs +++ b/crates/basilisk-checker/src/rules/enums_members_2.rs @@ -155,7 +155,8 @@ fn is_non_member(cls: &ClassInfo, member_name: &str) -> bool { // Method names defined with `def` in the class body — unless decorated with `@member`. if cls.method_names.iter().any(|m| m.as_str() == member_name) { let has_member_decorator = cls.method_decorators.iter().any(|(name, decorators)| { - name.as_str() == member_name && decorators.iter().any(|d| d == "member") + name.as_str() == member_name + && crate::rules::shared::decorator_spelled(decorators, "member") }); if !has_member_decorator { return true; diff --git a/crates/basilisk-checker/src/rules/generics_self_usage.rs b/crates/basilisk-checker/src/rules/generics_self_usage.rs index fe1a0882..e07f77ac 100644 --- a/crates/basilisk-checker/src/rules/generics_self_usage.rs +++ b/crates/basilisk-checker/src/rules/generics_self_usage.rs @@ -215,7 +215,7 @@ fn check_functions_self_usage( } } Some(class_name) => { - let is_static = func.decorators.iter().any(|d| d == "staticmethod"); + let is_static = super::shared::decorator_spelled(&func.decorators, "staticmethod"); if is_static { check_func_annotations_for_self( func, diff --git a/crates/basilisk-checker/src/rules/guards.rs b/crates/basilisk-checker/src/rules/guards.rs index 660a5c33..7ccbc436 100644 --- a/crates/basilisk-checker/src/rules/guards.rs +++ b/crates/basilisk-checker/src/rules/guards.rs @@ -25,7 +25,7 @@ use basilisk_resolver::{ClassInfo, FunctionInfo, ResolvedModule}; /// - A method inside a `Protocol` class (interface contract, not implementation). pub(crate) fn is_stub_context(func: &FunctionInfo, classes: &[ClassInfo]) -> bool { // @overload variants MUST be annotated — their signatures drive type resolution. - if func.decorators.iter().any(|d| d == "overload") { + if super::shared::decorator_spelled(&func.decorators, "overload") { return false; } // Pure stub bodies (only `...` / `pass`) are exempt — covers Protocol stubs @@ -34,7 +34,7 @@ pub(crate) fn is_stub_context(func: &FunctionInfo, classes: &[ClassInfo]) -> boo return true; } // Non-stub abstractmethod bodies are also exempt. - if func.decorators.iter().any(|d| d == "abstractmethod") { + if super::shared::decorator_spelled(&func.decorators, "abstractmethod") { return true; } // Protocol methods are interface contracts, not implementations. @@ -52,7 +52,7 @@ pub(crate) fn is_stub_context(func: &FunctionInfo, classes: &[ClassInfo]) -> boo /// checks for the function, so return-value/assignment diagnostics (E0011) must /// not fire. Argument-count (E0041) and similar signature checks still apply. pub(crate) fn is_no_type_check(func: &FunctionInfo) -> bool { - func.decorators.iter().any(|d| d == "no_type_check") + super::shared::decorator_spelled(&func.decorators, "no_type_check") } /// Returns `true` when a class is an Enum subclass, in either the bare @@ -190,7 +190,7 @@ pub(crate) fn collect_transform_functions( let mut result = HashMap::new(); for func in &module.functions { - if !func.decorators.iter().any(|d| d == "dataclass_transform") { + if !super::shared::decorator_spelled(&func.decorators, "dataclass_transform") { continue; } diff --git a/crates/basilisk-checker/src/rules/missing_parameter_annotation.rs b/crates/basilisk-checker/src/rules/missing_parameter_annotation.rs index 6f214cd0..e7887d71 100644 --- a/crates/basilisk-checker/src/rules/missing_parameter_annotation.rs +++ b/crates/basilisk-checker/src/rules/missing_parameter_annotation.rs @@ -80,11 +80,11 @@ fn check_function(func: &FunctionInfo, path: &str, out: &mut Vec) { fn is_implicit_receiver(func: &FunctionInfo, index: usize, param: &ParameterInfo) -> bool { if index != 0 || func.class_name.is_none() - || func.decorators.iter().any(|name| name == "staticmethod") + || super::shared::decorator_spelled(&func.decorators, "staticmethod") { return false; } - let class_receiver = func.decorators.iter().any(|name| name == "classmethod") + let class_receiver = super::shared::decorator_spelled(&func.decorators, "classmethod") || matches!(func.name.as_str(), "__new__" | "__init_subclass__"); param.name == if class_receiver { "cls" } else { "self" } } diff --git a/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs b/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs index 06d747e7..ad62305b 100644 --- a/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs +++ b/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs @@ -37,8 +37,12 @@ fn decorator_lists<'a>(cls: &'a ClassInfo, member: &str) -> Vec<&'a Vec> /// `(is_property, has_setter)` for `member` based on its decorators. fn property_kind(cls: &ClassInfo, member: &str) -> (bool, bool) { let lists = decorator_lists(cls, member); - let is_property = lists.iter().any(|ds| ds.iter().any(|d| d == "property")); - let has_setter = lists.iter().any(|ds| ds.iter().any(|d| d == "setter")); + let is_property = lists + .iter() + .any(|ds| crate::rules::shared::decorator_spelled(ds, "property")); + let has_setter = lists + .iter() + .any(|ds| crate::rules::shared::decorator_spelled(ds, "setter")); (is_property, has_setter) } @@ -51,7 +55,7 @@ fn property_kind(cls: &ClassInfo, member: &str) -> (bool, bool) { fn readwrite_property_members(cls: &ClassInfo) -> Vec<&str> { let mut members: Vec<&str> = Vec::new(); for (name, decs) in &cls.method_decorators { - let is_property = decs.iter().any(|d| d == "property"); + let is_property = crate::rules::shared::decorator_spelled(decs, "property"); let (_, has_setter) = property_kind(cls, name); if is_property && has_setter && !members.contains(&name.as_str()) { members.push(name.as_str()); @@ -264,7 +268,8 @@ pub(super) fn check_instance_var_conformance( fn property_members(cls: &ClassInfo) -> Vec<&str> { let mut members: Vec<&str> = Vec::new(); for (name, decs) in &cls.method_decorators { - if decs.iter().any(|d| d == "property") && !members.contains(&name.as_str()) { + if crate::rules::shared::decorator_spelled(decs, "property") && !members.contains(&name.as_str()) + { members.push(name.as_str()); } } @@ -327,7 +332,7 @@ fn find_method<'a>( /// Positional parameter names of a method, dropping the implicit `self`/`cls` /// receiver for instance and class methods (but not for static methods). fn logical_param_names(func: &FunctionInfo) -> Vec<&str> { - let is_static = func.decorators.iter().any(|d| d == "staticmethod"); + let is_static = crate::rules::shared::decorator_spelled(&func.decorators, "staticmethod"); let skip = usize::from(!is_static); func.parameters .iter() @@ -392,7 +397,7 @@ pub(super) fn check_method_signature_conformance( // A `@staticmethod` whose first parameter is `self` cannot satisfy an // instance method — it has no bound receiver. - let impl_static = impl_fn.decorators.iter().any(|d| d == "staticmethod"); + let impl_static = crate::rules::shared::decorator_spelled(&impl_fn.decorators, "staticmethod"); if impl_static && impl_fn.parameters.first().is_some_and(|p| p.name == "self") { push_signature_diag( protocol_name, diff --git a/crates/basilisk-checker/src/rules/redundant_annotation.rs b/crates/basilisk-checker/src/rules/redundant_annotation.rs index 4dd40a08..298bba96 100644 --- a/crates/basilisk-checker/src/rules/redundant_annotation.rs +++ b/crates/basilisk-checker/src/rules/redundant_annotation.rs @@ -290,13 +290,14 @@ fn annotation_defines_field( } /// attrs-style class decorators (`@define`, `@frozen`, `@mutable`, `@attr.s`, -/// `@attr.attrs`, …). The resolver records only the final name segment, so -/// `@attr.s` arrives as `"s"` and `@attrs.define` as `"define"`. A stray match -/// merely suppresses a warning — safe — whereas a miss corrupts a model. +/// `@attr.attrs`, …). The resolver records the decorator's dotted spelling, +/// so the final name segment is compared: `@attr.s` arrives as `"attr.s"` and +/// `@attrs.define` as `"attrs.define"`. A stray match merely suppresses a +/// warning — safe — whereas a miss corrupts a model. fn has_attrs_class_decorator(class: &basilisk_resolver::ClassInfo) -> bool { class.decorator_spans.iter().any(|(name, _)| { matches!( - name.as_str(), + name.rsplit('.').next().unwrap_or(name.as_str()), "define" | "frozen" | "mutable" | "attrs" | "s" ) }) diff --git a/crates/basilisk-checker/src/rules/shared.rs b/crates/basilisk-checker/src/rules/shared.rs index 5d7370ba..987d7a1b 100644 --- a/crates/basilisk-checker/src/rules/shared.rs +++ b/crates/basilisk-checker/src/rules/shared.rs @@ -42,6 +42,18 @@ pub(crate) fn overload_decorated( .any(|decorator| resolver.decorator_denotes(decorator, "overload")) } +/// Spelling-level decorator match: `name` bare or as the final segment of a +/// dotted path (`@typing.final`, `@abc.abstractmethod`). +/// +/// For guards where a qualified false match merely *skips* a check — never +/// invents a diagnostic. Rules whose diagnostics depend on what a decorator +/// IS resolve it through the binding tables instead ([`overload_decorated`]). +pub(crate) fn decorator_spelled(decorators: &[String], name: &str) -> bool { + decorators + .iter() + .any(|d| d == name || d.rsplit('.').next() == Some(name)) +} + /// Returns `true` when the annotation text denotes a `ClassVar[...]` type. /// /// `ClassVar` fields are excluded from the dataclass `__init__` parameter list, diff --git a/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs b/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs new file mode 100644 index 00000000..60a5cf4d --- /dev/null +++ b/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs @@ -0,0 +1,117 @@ +//! Tests for [CHKARCH-DIAG-TYPESAFETY] call collection completeness. See +//! docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-TYPESAFETY +// +// A call is a call wherever it appears. The resolver's call collector fed +// `module.calls` from statement-outermost expressions only, so +// `C(1).method()` silently skipped the SAME constructor-arity error that the +// bare statement `C(1)` reports (Refs #381). These tests pin every expression +// position to the bare-statement behaviour, span included. + +use super::common::*; + +type TestResult = Result<(), Box>; + +/// A dataclass with one `int` field: `C(1, 2)` is one positional too many, +/// which `dataclasses_kwonly`'s arity check reports on the bare statement. +const CLASS: &str = "from dataclasses import dataclass\n\n@dataclass\nclass C:\n a: int\n"; + +/// The arity diagnostics drawn by `source`, as `(code, span)` pairs. +fn arity_spans(source: &str) -> Result, Box> { + let diags = run(source)?; + Ok(diags + .iter() + .filter(|d| d.message.contains("positional argument")) + .map(|d| (d.code.code.to_owned(), (d.span.start, d.span.end))) + .collect()) +} + +/// `wrapped` must report exactly the arity diagnostic the bare `C(1, 2)` +/// statement reports, anchored at the same place within the `C(1, 2)` call. +/// +/// "Same span" is measured RELATIVE to the call text: the bare baseline's +/// span is translated from its `C(1, 2)` occurrence to the wrapped one, so +/// the assertion pins the rule's own anchoring (the offending argument) +/// without hard-coding it. +fn assert_same_arity_error(wrapped_stmt: &str, why: &str) -> TestResult { + let bare = format!("{CLASS}\nC(1, 2)\n"); + let bare_offset = u32::try_from(bare.find("C(1, 2)").ok_or("bare fixture broken")?)?; + let bare_errors = arity_spans(&bare)?; + let (bare_code, (bare_start, bare_end)) = bare_errors + .first() + .ok_or("the bare statement must report an arity error to pin against")?; + + let wrapped = format!("{CLASS}\n{wrapped_stmt}\n"); + let offset = u32::try_from(wrapped.find("C(1, 2)").ok_or("fixture must contain C(1, 2)")?)?; + let expected_span = ( + offset + (bare_start - bare_offset), + offset + (bare_end - bare_offset), + ); + + let errors = arity_spans(&wrapped)?; + assert!( + errors + .iter() + .any(|(code, span)| code == bare_code && *span == expected_span), + "{why}: expected {bare_code} at {expected_span:?}, got: {errors:?}", + ); + Ok(()) +} + +#[test] +fn bare_statement_reports_constructor_arity() -> TestResult { + let errors = arity_spans(&format!("{CLASS}\nC(1, 2)\n"))?; + assert!( + !errors.is_empty(), + "the bare `C(1, 2)` statement is the baseline and must report, got none" + ); + Ok(()) +} + +#[test] +fn method_call_receiver_reports_constructor_arity() -> TestResult { + assert_same_arity_error( + "C(1, 2).method()", + "a constructor call does not stop being wrong because a method is called on it (#381)", + ) +} + +#[test] +fn call_argument_reports_constructor_arity() -> TestResult { + assert_same_arity_error( + "print(C(1, 2))", + "a constructor call inside an argument list is still a call (#381)", + ) +} + +#[test] +fn list_element_reports_constructor_arity() -> TestResult { + assert_same_arity_error( + "xs = [C(1, 2)]", + "a constructor call inside a list literal is still a call (#381)", + ) +} + +#[test] +fn conditional_expression_reports_constructor_arity() -> TestResult { + assert_same_arity_error( + "p = True\nx = C(1, 2) if p else None", + "a constructor call inside a conditional expression is still a call (#381)", + ) +} + +#[test] +fn correct_constructor_stays_silent_everywhere() -> TestResult { + let diags = run(&format!( + "{CLASS}\nok = [C(1)]\nprint(C(2))\ny = C(3) if True else None\n" + ))?; + let arity: Vec<_> = diags + .iter() + .filter(|d| d.message.contains("positional argument")) + .collect(); + assert!( + arity.is_empty(), + "correct constructor calls must stay silent in every position, got: {:?}", + arity.iter().map(|d| &d.message).collect::>() + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/checker_rules_a_tests.rs b/crates/basilisk-checker/tests/checker_rules_a_tests.rs index 4d4c4032..b6809895 100644 --- a/crates/basilisk-checker/tests/checker_rules_a_tests.rs +++ b/crates/basilisk-checker/tests/checker_rules_a_tests.rs @@ -24,6 +24,8 @@ mod assignment_compatibility; mod callables_annotation; #[path = "checker/calls_argument_type_tests.rs"] mod calls_argument_type; +#[path = "checker/calls_expression_position_tests.rs"] +mod calls_expression_position; #[path = "checker/classes_override_tests.rs"] mod classes_override; #[path = "checker/classes_override_2_tests.rs"] diff --git a/crates/basilisk-lsp/src/code_actions/refactor/abstract_methods.rs b/crates/basilisk-lsp/src/code_actions/refactor/abstract_methods.rs index 69727c9c..b252d5b3 100644 --- a/crates/basilisk-lsp/src/code_actions/refactor/abstract_methods.rs +++ b/crates/basilisk-lsp/src/code_actions/refactor/abstract_methods.rs @@ -48,7 +48,11 @@ pub(in crate::code_actions) fn implement_abstract_methods( if fn_class != &base_class.name { continue; } - if !func.decorators.iter().any(|d| d == "abstractmethod") { + if !func + .decorators + .iter() + .any(|d| d.rsplit('.').next() == Some("abstractmethod")) + { continue; } // Skip if already implemented in the current class. diff --git a/crates/basilisk-lsp/src/semantic_tokens.rs b/crates/basilisk-lsp/src/semantic_tokens.rs index bec03228..38800196 100644 --- a/crates/basilisk-lsp/src/semantic_tokens.rs +++ b/crates/basilisk-lsp/src/semantic_tokens.rs @@ -87,7 +87,12 @@ fn push_param_tokens(raw: &mut Vec, param: &ParameterInfo) { fn has_static_decorator(decorators: &[String]) -> bool { decorators .iter() - .any(|d| d == "staticmethod" || d == "classmethod") + .any(|d| { + matches!( + d.rsplit('.').next().unwrap_or(d.as_str()), + "staticmethod" | "classmethod" + ) + }) } /// Collect tokens for a single function or method definition. diff --git a/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs b/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs index 52e5584b..85719f95 100644 --- a/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs +++ b/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs @@ -36,45 +36,21 @@ pub(super) fn collect_reveal_type_calls(stmts: &[Stmt]) -> Vec Vec { let mut out = Vec::new(); - collect_calls_from_stmts_internal(stmts, &mut out); - out -} - -pub(super) fn collect_calls_from_stmts_internal(stmts: &[Stmt], out: &mut Vec) { - crate::walk_all_stmts(stmts, &mut |stmt| match stmt { - Stmt::AnnAssign(node) => { - if let Some(val) = node.value.as_deref() { - if let Some(site) = call_site_from_expr(val) { - out.push(site); - } - } - } - Stmt::Assign(node) => { - if let Some(site) = call_site_from_expr(&node.value) { - out.push(site); - } + crate::visit_calls(stmts, &mut |call| { + if let Some(site) = call_site_from_call(call) { + out.push(site); } - Stmt::Expr(node) => { - if let Some(site) = call_site_from_expr(&node.value) { - out.push(site); - } - } - Stmt::If(node) => { - if let Some(site) = call_site_from_expr(&node.test) { - out.push(site); - } - for clause in &node.elif_else_clauses { - if let Some(ref test) = clause.test { - if let Some(site) = call_site_from_expr(test) { - out.push(site); - } - } - } - } - _ => {} }); + out } pub(super) fn collect_reveal_type_calls_from_stmts( @@ -99,8 +75,9 @@ pub(super) fn collect_reveal_type_calls_from_stmts( /// any non-TypeVar (non-simple-name) argument spans from a class definition. /// /// Returns `(type_params, non_typevar_arg_spans)`. -pub(super) fn call_site_from_expr(expr: &Expr) -> Option { - let Expr::Call(call) = expr else { return None }; +/// Build a [`CallSite`] from a call node, when its callee shape is one the +/// site model represents (a bare name, or a method on a supported receiver). +pub(super) fn call_site_from_call(call: &ruff_python_ast::ExprCall) -> Option { let (callee, receiver) = match call.func.as_ref() { Expr::Name(name) => (name.id.to_string(), None), Expr::Attribute(attribute) => { diff --git a/crates/basilisk-resolver/src/visitor/cast_calls.rs b/crates/basilisk-resolver/src/visitor/cast_calls.rs deleted file mode 100644 index 4997f030..00000000 --- a/crates/basilisk-resolver/src/visitor/cast_calls.rs +++ /dev/null @@ -1,63 +0,0 @@ -//! Implements call-site collection for [`directives_cast`]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-OWNERSHIP -//! -//! `typing.cast(typ, val)` is invalid wherever it appears — its arity and its -//! first argument do not become legal because the call sits in a `return` -//! instead of an assignment. The module-wide [`ResolvedModule::calls`] vector -//! deliberately records only the outermost call of a few statement kinds, which -//! left `return cast(1, x)` and `print(cast(1, x))` unchecked (issue #335). -//! -//! This collector walks **every** expression position in the module and records -//! each `cast(...)` it finds. It is scoped to `cast` on purpose: widening the -//! shared `calls` vector would change what every other call-site rule sees. -//! -//! [`ResolvedModule::calls`]: crate::scope::ResolvedModule::calls - -use ruff_python_ast::visitor::{walk_expr, Visitor}; -use ruff_python_ast::{Expr, Stmt}; - -use crate::scope::CallSite; - -use super::calls_and_reveal::call_site_from_expr; - -/// The name of the callee this collector records. Both the bare `cast(...)` -/// import spelling and the qualified `typing.cast(...)` spelling resolve to -/// this simple name in [`CallSite::callee`]. -const CAST: &str = "cast"; - -/// Collect every `cast(...)` call site in `stmts`, in any expression position. -/// -/// `source` is used only as a fast-path guard: a call to `cast` cannot exist in -/// a module whose text never contains that identifier, so the great majority of -/// modules skip the walk entirely and this collector costs one substring scan. -pub(super) fn collect_cast_calls(stmts: &[Stmt], source: &str) -> Vec { - if !source.contains(CAST) { - return Vec::new(); - } - let mut collector = CastCallCollector { out: Vec::new() }; - for stmt in stmts { - collector.visit_stmt(stmt); - } - collector.out -} - -struct CastCallCollector { - out: Vec, -} - -impl<'a> Visitor<'a> for CastCallCollector { - fn visit_expr(&mut self, expr: &'a Expr) { - if matches!(expr, Expr::Call(call) if is_cast_callee(&call.func)) { - self.out.extend(call_site_from_expr(expr)); - } - walk_expr(self, expr); - } -} - -/// Returns `true` for the callee of `cast(...)` or `.cast(...)`. -fn is_cast_callee(func: &Expr) -> bool { - match func { - Expr::Name(name) => name.id.as_str() == CAST, - Expr::Attribute(attr) => attr.attr.as_str() == CAST, - _ => false, - } -} diff --git a/crates/basilisk-resolver/src/visitor/dataclass.rs b/crates/basilisk-resolver/src/visitor/dataclass.rs index 8c223041..17919463 100644 --- a/crates/basilisk-resolver/src/visitor/dataclass.rs +++ b/crates/basilisk-resolver/src/visitor/dataclass.rs @@ -102,7 +102,9 @@ pub(super) fn build_field_specifier_overloads( let has_overloads = functions.iter().any(|f| { f.name == spec_name && f.class_name.is_none() - && f.decorators.iter().any(|d| d == "overload") + && f.decorators + .iter() + .any(|d| d.rsplit('.').next() == Some("overload")) }); for stmt in stmts { diff --git a/crates/basilisk-resolver/src/visitor/mod.rs b/crates/basilisk-resolver/src/visitor/mod.rs index b225315d..45a3337b 100644 --- a/crates/basilisk-resolver/src/visitor/mod.rs +++ b/crates/basilisk-resolver/src/visitor/mod.rs @@ -9,7 +9,6 @@ mod assert_narrow; mod assigns; mod call_return; mod calls_and_reveal; -mod cast_calls; mod class_info; mod class_info_ext; mod core; @@ -100,7 +99,6 @@ fn reclassify_generic_params( /// Intermediate container for collected analysis results. struct AnalysisResults { - cast_calls: Vec, reveal_type_calls: Vec, assert_type_calls: Vec, typeddict_calls: Vec, @@ -142,7 +140,6 @@ fn collect_analysis_results( isinstance_typeddict_spans.extend(typevar::collect_typevar_bound_typeddict_violations(stmts)); AnalysisResults { - cast_calls: cast_calls::collect_cast_calls(stmts, source), reveal_type_calls: calls_and_reveal::collect_reveal_type_calls(stmts), assert_type_calls: calls_and_reveal::collect_assert_type_calls_from_stmts(stmts, source), typeddict_calls: typeddict::collect_typeddict_calls(stmts), @@ -225,8 +222,14 @@ fn build_resolved_module( counts }, ), + // `calls` is complete over every expression position (#381), so the + // `cast(...)` view #335 needed is a filter of it, not a second walk. + cast_calls: calls + .iter() + .filter(|site| site.callee == "cast") + .cloned() + .collect(), calls, - cast_calls: results.cast_calls, typevar_calls, reveal_type_calls: results.reveal_type_calls, assert_type_calls: results.assert_type_calls, diff --git a/crates/basilisk-resolver/src/visitor/protocol.rs b/crates/basilisk-resolver/src/visitor/protocol.rs index 7c1019b0..61508a28 100644 --- a/crates/basilisk-resolver/src/visitor/protocol.rs +++ b/crates/basilisk-resolver/src/visitor/protocol.rs @@ -314,7 +314,11 @@ pub(super) fn collect_protocol_instantiation_violations( pub(super) fn class_has_abstract_methods(cls: &ClassInfo) -> bool { cls.method_decorators .iter() - .any(|(_method_name, decorators)| decorators.iter().any(|d| d == "abstractmethod")) + .any(|(_method_name, decorators)| { + decorators + .iter() + .any(|d| d.rsplit('.').next() == Some("abstractmethod")) + }) } /// Check if a non-Protocol class missing required protocol members. diff --git a/crates/basilisk-resolver/src/visitor/walks.rs b/crates/basilisk-resolver/src/visitor/walks.rs index e5364ba3..2b7daaf1 100644 --- a/crates/basilisk-resolver/src/visitor/walks.rs +++ b/crates/basilisk-resolver/src/visitor/walks.rs @@ -6,37 +6,35 @@ use ruff_python_ast::{ExceptHandler, Expr, ExprCall, ParameterWithDefault, Parameters, Stmt}; -/// Walk every `Call` expression reachable from `stmts`, including nested -/// argument calls, into nested control-flow bodies and into nested function -/// and class definitions. +/// Walk every `Call` expression in **every expression position** reachable +/// from `stmts` — statement values, receivers (`C(1).method()`), argument +/// lists, container literals, conditional expressions, comprehensions, +/// f-strings, lambda bodies, decorators, and nested function and class +/// definitions. /// -/// For each call, `visit` is invoked with the [`ExprCall`] node. Callers do -/// not need to recurse manually — `visit_calls` traverses arguments first, -/// then yields the outer call. +/// A call is a call wherever it appears; visiting only statement-outermost +/// expressions silently skipped the same error the bare statement reports +/// ([#381](https://github.com/Nimblesite/Basilisk/issues/381)). Calls are +/// yielded in source order, outer call before its nested calls. pub fn visit_calls(stmts: &[Stmt], visit: &mut impl FnMut(&ExprCall)) { - walk_all_stmts(stmts, &mut |stmt| match stmt { - Stmt::Expr(node) => visit_calls_in_expr(&node.value, visit), - Stmt::Assign(node) => visit_calls_in_expr(&node.value, visit), - Stmt::AnnAssign(node) => { - if let Some(val) = node.value.as_deref() { - visit_calls_in_expr(val, visit); - } - } - Stmt::Return(node) => { - if let Some(val) = &node.value { - visit_calls_in_expr(val, visit); - } - } - _ => {} - }); + let mut collector = CallWalker { visit }; + for stmt in stmts { + ruff_python_ast::visitor::Visitor::visit_stmt(&mut collector, stmt); + } +} + +/// The [`ruff_python_ast::visitor::Visitor`] behind [`visit_calls`]: default +/// traversal everywhere, yielding each [`ExprCall`] on the way down. +struct CallWalker<'v, F> { + visit: &'v mut F, } -fn visit_calls_in_expr(expr: &Expr, visit: &mut impl FnMut(&ExprCall)) { - if let Expr::Call(call) = expr { - for arg in &call.arguments.args { - visit_calls_in_expr(arg, visit); +impl<'a, F: FnMut(&'a ExprCall)> ruff_python_ast::visitor::Visitor<'a> for CallWalker<'_, F> { + fn visit_expr(&mut self, expr: &'a Expr) { + if let Expr::Call(call) = expr { + (self.visit)(call); } - visit(call); + ruff_python_ast::visitor::walk_expr(self, expr); } } diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index 97064eb0..45d5da4a 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -760,17 +760,36 @@ not run is `[~]`, not `[x]`. - [x] Test: `cargo test -p basilisk-checker aliases_recursive` — every recursive DEFINITION pinned clean, both cyclical-reference cases pinned firing. -- [ ] Resolve decorator expressions through the binding table so `o = overload` +- [x] Resolve decorator expressions through the binding table so `o = overload` is recognised as `typing.overload`; cover `from typing import overload as ov` and `typing.overload` / `t.overload` attribute spellings - ([#380](https://github.com/Nimblesite/Basilisk/issues/380)). The binding - table is `annotation/tables.rs`'s import map plus a value-binding pass; - `mod.rs::canonical_head` already rewrites the alias and attribute spellings - and is the function decorator resolution reuses. - - [ ] Test (write RED first): all four spellings of an `@overload` chain - (`overload`, `ov`, `typing.overload`, `t.overload`, `o = overload`) are - accepted, and a non-overload decorator named `overload` from another module - is NOT. + ([#380](https://github.com/Nimblesite/Basilisk/issues/380)). + — Root cause was upstream of any table: the resolver's `decorator_name` + rendered `@t.overload` as bare `"overload"`, discarding the qualifier before + ANY consumer could discriminate. `class_info_ext.rs::decorator_name{,_and_span}` + now render the full dotted path. On top of that, + `annotation/tables.rs` gained the value-binding pass (`values`: + `o = overload`, chains included, cycle-capped) and + `annotation/mod.rs::decorator_denotes(spelling, member)` answers "is this + spelling `typing.`?" through value chains → import map → module + map, with a bare unbound spelling accepted leniently. One shared predicate — + `rules/shared.rs::overload_decorated` — now backs ALL six group-forming + overload rules (`overloads_definitions`, `overloads_consistency{,_2,_3}`, + `overloads_basic`, `overloads_evaluation`); every remaining spelling-level + matcher across checker/LSP/resolver was swept onto suffix-tolerant + `decorator_spelled` / `rsplit('.')` so the dotted rendering changes no + guard behaviour. + - [x] Test (write RED first): `tests/checker/annotation_resolution_tests.rs` + sibling file `tests/checker/decorator_resolution_tests.rs` (11 tests, + mounted in `checker_rules_a_tests.rs`) — recognition observed through + `overloads_definitions` firing on an impl-less chain for `overload`, `ov`, + `typing.overload`, `t.overload`, `o = overload`, and + `o = typing.overload`; acceptance through two complete chains drawing zero + diagnostics; discrimination through `from mymod import overload`, + `import mymod as t` + `@t.overload`, and a value chain ending at the + foreign name staying overload-silent. **RED proof**: 5 of 11 failed before + the change (`ov`/`o` unrecognised; both foreign spellings falsely + recognised); 11/11 after. - [ ] Visit calls in every expression position rather than statement-outermost only, so `C(1).method()` reports the same constructor-arity error as `C(1)` ([#381](https://github.com/Nimblesite/Basilisk/issues/381)). From 0350294d67f1069955a3963d885d6bb41021c715 Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:13:10 +1000 Subject: [PATCH 17/45] Fixes --- .../assignment_compatibility/enum_expand.rs | 2 +- .../src/rules/enums_members_2.rs | 2 +- .../class_body_method_binding_tests.rs | 91 +++++++++++++++++++ .../tests/checker_rules_a_tests.rs | 2 + .../src/scope/module_types.rs | 5 + .../src/scope/resolved_module.rs | 3 + .../src/scope/variable_types.rs | 15 ++- .../src/visitor/calls_and_reveal.rs | 4 + .../src/visitor/class_info.rs | 39 ++++++-- .../tests/resolver/test_class_properties.rs | 2 +- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 18 +++- 11 files changed, 166 insertions(+), 17 deletions(-) create mode 100644 crates/basilisk-checker/tests/checker/class_body_method_binding_tests.rs diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs index 29d1165d..a522ef88 100644 --- a/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/enum_expand.rs @@ -49,7 +49,7 @@ fn is_enum_member(attr: &AttributeInfo) -> bool { && !attr.has_annotation && !attr.rhs_is_nonmember_call && !attr.rhs_is_lambda - && !attr.rhs_is_descriptor_call + && attr.rhs_descriptor.is_none() && !sunder_or_dunder } diff --git a/crates/basilisk-checker/src/rules/enums_members_2.rs b/crates/basilisk-checker/src/rules/enums_members_2.rs index 35d859ad..5c0a1ad9 100644 --- a/crates/basilisk-checker/src/rules/enums_members_2.rs +++ b/crates/basilisk-checker/src/rules/enums_members_2.rs @@ -166,7 +166,7 @@ fn is_non_member(cls: &ClassInfo, member_name: &str) -> bool { // Class body attributes explicitly declared with `nonmember(...)`, lambda, or descriptor. if cls.attributes.iter().any(|a| { a.name == member_name - && (a.rhs_is_nonmember_call || a.rhs_is_lambda || a.rhs_is_descriptor_call) + && (a.rhs_is_nonmember_call || a.rhs_is_lambda || a.rhs_descriptor.is_some()) }) { return true; } diff --git a/crates/basilisk-checker/tests/checker/class_body_method_binding_tests.rs b/crates/basilisk-checker/tests/checker/class_body_method_binding_tests.rs new file mode 100644 index 00000000..5a4d98f9 --- /dev/null +++ b/crates/basilisk-checker/tests/checker/class_body_method_binding_tests.rs @@ -0,0 +1,91 @@ +//! Tests for [TYPEINF-ANNOTATION-RESOLUTION] method binding of class-body +//! function assignments. See +//! docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-TYPESAFETY +// +// A function assigned in a class body (`m = f`) is a method like any `def`: +// instance access binds the receiver, class access does not, and +// `staticmethod` / `classmethod` wrappers shift which parameter the binding +// consumes (Refs #382). These tests pin the assigned spelling to the exact +// diagnostics the equivalent `def` in the class body draws. + +use super::common::*; + +type TestResult = Result<(), Box>; + +/// The missing-argument diagnostics drawn by `source`. +fn arity_errors(source: &str) -> Result, Box> { + let diags = run(source)?; + Ok(diags + .iter() + .filter(|d| d.message.contains("required argument")) + .map(|d| d.message.clone()) + .collect()) +} + +/// A module where `C.m` is `f` assigned in the class body, next to the +/// equivalent literal `def` method `n` that serves as the behaviour baseline. +const ASSIGNED: &str = "def f(self: \"C\", a: int) -> None:\n return None\n\n\ +class C:\n m = f\n\n def n(self, a: int) -> None:\n return None\n"; + +#[test] +fn instance_access_binds_receiver_on_assigned_method() -> TestResult { + let errors = arity_errors(&format!("{ASSIGNED}\nC().m(1)\n"))?; + assert!( + errors.is_empty(), + "instance access consumes `self`, so `C().m(1)` is complete (#382), got: {errors:?}" + ); + Ok(()) +} + +#[test] +fn class_access_leaves_assigned_method_unbound() -> TestResult { + let baseline = arity_errors(&format!("{ASSIGNED}\nC.n(1)\n"))?; + assert!( + !baseline.is_empty(), + "baseline: class access to the literal `def` must be an arity error \ + (self=1, `a` missing) for the assigned spelling to be pinned against" + ); + let errors = arity_errors(&format!("{ASSIGNED}\nC.m(1)\n"))?; + assert!( + !errors.is_empty(), + "class access does not bind `self`, so `C.m(1)` misses `a` exactly \ + like `C.n(1)` does (#382)" + ); + Ok(()) +} + +#[test] +fn staticmethod_wrapper_never_consumes_receiver() -> TestResult { + let source = "def g(a: int) -> None:\n return None\n\n\ +class D:\n s = staticmethod(g)\n\n\ +D().s(1)\nD.s(1)\n"; + let errors = arity_errors(source)?; + assert!( + errors.is_empty(), + "`staticmethod` takes no receiver on either access path (#382), got: {errors:?}" + ); + Ok(()) +} + +#[test] +fn classmethod_wrapper_consumes_cls_on_both_access_paths() -> TestResult { + let source = "def h(cls: type, a: int) -> None:\n return None\n\n\ +class E:\n c = classmethod(h)\n\n\ +E().c(1)\nE.c(1)\n"; + let errors = arity_errors(source)?; + assert!( + errors.is_empty(), + "`classmethod` binds `cls` on instance AND class access (#382), got: {errors:?}" + ); + Ok(()) +} + +#[test] +fn assigned_method_still_checks_missing_arguments_on_instance() -> TestResult { + let errors = arity_errors(&format!("{ASSIGNED}\nC().m()\n"))?; + assert!( + !errors.is_empty(), + "binding `self` must not silence real arity errors: `C().m()` still misses `a` (#382)" + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/checker_rules_a_tests.rs b/crates/basilisk-checker/tests/checker_rules_a_tests.rs index b6809895..385003e6 100644 --- a/crates/basilisk-checker/tests/checker_rules_a_tests.rs +++ b/crates/basilisk-checker/tests/checker_rules_a_tests.rs @@ -26,6 +26,8 @@ mod callables_annotation; mod calls_argument_type; #[path = "checker/calls_expression_position_tests.rs"] mod calls_expression_position; +#[path = "checker/class_body_method_binding_tests.rs"] +mod class_body_method_binding; #[path = "checker/classes_override_tests.rs"] mod classes_override; #[path = "checker/classes_override_2_tests.rs"] diff --git a/crates/basilisk-resolver/src/scope/module_types.rs b/crates/basilisk-resolver/src/scope/module_types.rs index cc00a217..07c422a3 100644 --- a/crates/basilisk-resolver/src/scope/module_types.rs +++ b/crates/basilisk-resolver/src/scope/module_types.rs @@ -56,6 +56,11 @@ pub enum CallReceiver { BytesLiteral, /// A named variable or parameter whose annotation/inferred type is resolved later. Name(String), + /// A direct constructor call on a named callee (`C().method(...)`): the + /// receiver is a fresh *instance* of `C`, so instance-method binding + /// consumes the implicit `self` parameter + /// ([#382](https://github.com/Nimblesite/Basilisk/issues/382)). + Constructor(String), } /// A `NamedTuple` definition collected from module-level code. diff --git a/crates/basilisk-resolver/src/scope/resolved_module.rs b/crates/basilisk-resolver/src/scope/resolved_module.rs index 2a1ecb27..6e48f004 100644 --- a/crates/basilisk-resolver/src/scope/resolved_module.rs +++ b/crates/basilisk-resolver/src/scope/resolved_module.rs @@ -339,6 +339,9 @@ impl ResolvedModule { super::CallReceiver::StringLiteral => ("str", true), super::CallReceiver::BytesLiteral => ("bytes", true), super::CallReceiver::Name(name) => self.builtin_type_of_name(name)?, + // A constructed instance's methods are resolved against the user + // class, not the builtin stub index ([#382]). + super::CallReceiver::Constructor(_) => return None, }; self.builtin_classes .get(type_name) diff --git a/crates/basilisk-resolver/src/scope/variable_types.rs b/crates/basilisk-resolver/src/scope/variable_types.rs index a15107ec..c75ea71b 100644 --- a/crates/basilisk-resolver/src/scope/variable_types.rs +++ b/crates/basilisk-resolver/src/scope/variable_types.rs @@ -50,10 +50,19 @@ pub struct AttributeInfo { /// /// In enum class bodies, lambda attributes are non-members. pub rhs_is_lambda: bool, - /// `true` when the right-hand-side is a call to `staticmethod(...)` or `classmethod(...)`. + /// The descriptor wrapper name when the right-hand-side is a call to + /// `staticmethod(...)` or `classmethod(...)`, else `None`. /// - /// In enum class bodies, static/class method descriptors are non-members. - pub rhs_is_descriptor_call: bool, + /// In enum class bodies, static/class method descriptors are non-members; + /// in ordinary class bodies the wrapper decides which implicit receiver a + /// bound callable consumes + /// ([#382](https://github.com/Nimblesite/Basilisk/issues/382)). + pub rhs_descriptor: Option, + /// The simple name of the callable this attribute binds, when the + /// right-hand-side is a bare name (`m = f`) or a descriptor wrapper around + /// one (`s = staticmethod(g)`), else `None`. Class-body assignments of + /// module-level functions bind them as methods ([#382]). + pub rhs_name: Option, /// `true` when the annotation contains `ReadOnly[...]` (directly or nested). /// /// Used by `typeddicts_readonly` to detect mutation of read-only `TypedDict` fields. diff --git a/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs b/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs index 85719f95..14cd51ea 100644 --- a/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs +++ b/crates/basilisk-resolver/src/visitor/calls_and_reveal.rs @@ -85,6 +85,10 @@ pub(super) fn call_site_from_call(call: &ruff_python_ast::ExprCall) -> Option CallReceiver::StringLiteral, Expr::BytesLiteral(_) => CallReceiver::BytesLiteral, Expr::Name(name) => CallReceiver::Name(name.id.to_string()), + Expr::Call(constructor) => match constructor.func.as_ref() { + Expr::Name(name) => CallReceiver::Constructor(name.id.to_string()), + _ => return None, + }, _ => return None, }; (attribute.attr.to_string(), Some(receiver)) diff --git a/crates/basilisk-resolver/src/visitor/class_info.rs b/crates/basilisk-resolver/src/visitor/class_info.rs index 68f81349..a7578abf 100644 --- a/crates/basilisk-resolver/src/visitor/class_info.rs +++ b/crates/basilisk-resolver/src/visitor/class_info.rs @@ -197,7 +197,8 @@ fn ann_attribute( rhs_span: ann.value.as_ref().map(|v| text_range_to_span(v.range())), rhs_is_nonmember_call: false, rhs_is_lambda: false, - rhs_is_descriptor_call: false, + rhs_descriptor: None, + rhs_name: None, is_readonly: annotation_contains_readonly_expr(&ann.annotation), is_kw_only, is_init_false: ann.value.as_deref().is_some_and(field_init_is_false), @@ -206,6 +207,31 @@ fn ann_attribute( }) } +/// Classify a class-body assignment's RHS as a callable binding: the +/// descriptor wrapper (if any) and the simple name of the callable bound. +/// +/// `m = f` → `(None, Some("f"))`; `s = staticmethod(g)` → +/// `(Some("staticmethod"), Some("g"))`; anything else → names absent ([#382]). +fn rhs_callable_binding(value: &Expr) -> (Option, Option) { + match value { + Expr::Name(name) => (None, Some(name.id.to_string())), + Expr::Call(call) => { + let wrapper = match call.func.as_ref() { + Expr::Name(n) if n.id == "staticmethod" || n.id == "classmethod" => { + n.id.to_string() + } + _ => return (None, None), + }; + let wrapped = match call.arguments.args.as_ref() { + [Expr::Name(inner)] => Some(inner.id.to_string()), + _ => None, + }; + (Some(wrapper), wrapped) + } + _ => (None, None), + } +} + /// Append an [`AttributeInfo`] for each simple-name target of `name = value`. fn assign_attributes( assign: &StmtAssign, @@ -217,13 +243,7 @@ fn assign_attributes( Expr::Call(c) if matches!(c.func.as_ref(), Expr::Name(n) if n.id == "nonmember") ); let rhs_is_lambda = matches!(&*assign.value, Expr::Lambda(_)); - let rhs_is_descriptor_call = matches!( - &*assign.value, - Expr::Call(c) if matches!( - c.func.as_ref(), - Expr::Name(n) if n.id == "staticmethod" || n.id == "classmethod" - ) - ); + let (rhs_descriptor, rhs_name) = rhs_callable_binding(&assign.value); for target in &assign.targets { if let Some(name) = expr_simple_name(target) { attributes.push(AttributeInfo { @@ -236,7 +256,8 @@ fn assign_attributes( rhs_span: Some(text_range_to_span(assign.value.range())), rhs_is_nonmember_call, rhs_is_lambda, - rhs_is_descriptor_call, + rhs_descriptor: rhs_descriptor.clone(), + rhs_name: rhs_name.clone(), is_readonly: false, is_kw_only: false, is_init_false: false, diff --git a/crates/basilisk-resolver/tests/resolver/test_class_properties.rs b/crates/basilisk-resolver/tests/resolver/test_class_properties.rs index 81e7f09e..d7988054 100644 --- a/crates/basilisk-resolver/tests/resolver/test_class_properties.rs +++ b/crates/basilisk-resolver/tests/resolver/test_class_properties.rs @@ -161,7 +161,7 @@ fn class_attr_descriptor_call_flag() -> Result<(), Box> { let resolved = resolve_src(&src)?; let cls = resolved.classes.iter().find(|c| c.name == "Foo"); let attr = cls.and_then(|c| c.attributes.iter().find(|a| a.name == "bar")); - assert!(attr.is_some_and(|a| a.rhs_is_descriptor_call)); + assert!(attr.is_some_and(|a| a.rhs_descriptor.is_some())); Ok(()) } diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index 45d5da4a..b1bd65d9 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -790,12 +790,26 @@ not run is `[~]`, not `[x]`. foreign name staying overload-silent. **RED proof**: 5 of 11 failed before the change (`ov`/`o` unrecognised; both foreign spellings falsely recognised); 11/11 after. -- [ ] Visit calls in every expression position rather than statement-outermost +- [x] Visit calls in every expression position rather than statement-outermost only, so `C(1).method()` reports the same constructor-arity error as `C(1)` ([#381](https://github.com/Nimblesite/Basilisk/issues/381)). - - [ ] Test (write RED first): `C(1).method()`, `f(C(1))`, `[C(1)]`, + — `visit_calls` rebuilt on the official `ruff_python_ast::visitor::Visitor` + (pre-order, every expression position: receivers, argument lists, container + literals, ternaries, comprehensions, f-strings, decorators, nested defs); + `collect_calls_from_stmts` now walks it via the new `call_site_from_call`, + so `module.calls` is complete. #335's special-case `cast_calls.rs` walker + DELETED — the field is now derived by filtering the complete `calls` vector + on `callee == "cast"`. + - [x] Test (write RED first): `C(1).method()`, `f(C(1))`, `[C(1)]`, `x = C(1) if p else C(1)` each report the same arity diagnostic as the bare `C(1)` statement, at the same span. + — `tests/checker/calls_expression_position_tests.rs` (6 tests): bare + baseline pin, method receiver, call argument, list element, conditional + expression, correct-everywhere-silent. The span assertion translates the + bare baseline's own anchoring to the wrapped occurrence, so it pins "same + span" without hard-coding the rule's anchor. **RED proof**: 2 of 6 passed + before the collector fix (bare + silent); method receiver, call argument, + list element, and conditional were all silently missed; 6/6 after. - [ ] Bind functions assigned in a class body as methods — implicit receiver consumed on instance access, unbound on class access, `staticmethod` / `classmethod` honoured ([#382](https://github.com/Nimblesite/Basilisk/issues/382)). From 048f86ecef0495066e80d62df9aff572881b5cfa Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:16:47 +1000 Subject: [PATCH 18/45] fixes --- .../calls_argument_count/method_binding.rs | 196 ++++++++++++++++++ .../mod.rs} | 3 + .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 21 +- 3 files changed, 218 insertions(+), 2 deletions(-) create mode 100644 crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs rename crates/basilisk-checker/src/rules/{calls_argument_count.rs => calls_argument_count/mod.rs} (99%) diff --git a/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs b/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs new file mode 100644 index 00000000..f82816fe --- /dev/null +++ b/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs @@ -0,0 +1,196 @@ +//! Implements [TYPEINF-FUNC-SELFCLS] receiver binding for the +//! `calls_argument_count` method path. See +//! docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-IMMUTABILITY +//! +//! A method is a method however it was defined: a literal `def` in the class +//! body, or a module-level function bound by a class-body assignment +//! (`m = f`, `s = staticmethod(g)`, `c = classmethod(h)` — +//! [#382](https://github.com/Nimblesite/Basilisk/issues/382)). Instance access +//! (`C().m(...)`) consumes the implicit receiver; class access (`C.m(...)`) +//! does not; `staticmethod` never consumes one and `classmethod` always does. + +use basilisk_resolver::scope::CallReceiver; +use basilisk_resolver::{CallSite, ClassInfo, FunctionInfo, ResolvedModule}; + +use crate::diagnostic::{error_diagnostic_owned, Diagnostic}; + +use super::super::shared; + +/// Decorators that leave a method's call signature intact. Anything else +/// (`property`, custom descriptors, wrappers) may change what a call accepts, +/// so the arity check abstains rather than guess. +const SIGNATURE_PRESERVING: [&str; 6] = [ + "staticmethod", + "classmethod", + "overload", + "override", + "final", + "abstractmethod", +]; + +/// How a resolved class attribute binds its underlying callable. +struct BoundMethod<'a> { + /// Candidate signatures (multiple for `@overload` groups or redefinitions); + /// the call is accepted when ANY candidate accepts it. + candidates: Vec<&'a FunctionInfo>, + /// The `staticmethod` / `classmethod` wrapper applied by assignment, if any. + wrapper: Option<&'a str>, +} + +/// Check method calls through a class receiver — `C.m(...)` and `C().m(...)` — +/// against the bound method's signature, consuming the implicit receiver +/// according to the access path and any descriptor wrapper ([#382]). +pub(super) fn check_method_calls(module: &ResolvedModule, diagnostics: &mut Vec) { + let class_map = shared::class_name_map(&module.classes); + let method_map = shared::method_name_map(&module.functions); + + for call in &module.calls { + let Some((class_info, instance_access)) = receiver_class(call, &class_map) else { + continue; + }; + // Keyword arguments and `**kwargs` unpacking hide how many parameters + // are satisfied; the positional-arity check abstains (same guard as + // every other path in this rule). + if !call.keywords.is_empty() || call.has_unpacked_kwargs { + continue; + } + let Some(bound) = resolve_bound_method(module, class_info, &call.callee, &method_map) + else { + continue; + }; + check_bound_call(module, call, class_info, &bound, instance_access, diagnostics); + } +} + +/// The class a call's receiver denotes, and whether the access path goes +/// through an instance (`C().m` — `true`) or the class object (`C.m`). +fn receiver_class<'a>( + call: &CallSite, + class_map: &std::collections::HashMap<&str, &'a ClassInfo>, +) -> Option<(&'a ClassInfo, bool)> { + match call.receiver.as_ref()? { + CallReceiver::Name(name) => class_map.get(name.as_str()).map(|cls| (*cls, false)), + CallReceiver::Constructor(name) => class_map.get(name.as_str()).map(|cls| (*cls, true)), + CallReceiver::StringLiteral | CallReceiver::BytesLiteral => None, + } +} + +/// Resolve `class.method` to its candidate signatures: literal `def`s first, +/// else a class-body assignment binding a module-level function. Returns +/// `None` (abstain) when the method is unknown here or a decorator may have +/// changed its signature. +fn resolve_bound_method<'a>( + module: &'a ResolvedModule, + class_info: &'a ClassInfo, + method: &str, + method_map: &std::collections::HashMap<(&str, &str), Vec<&'a FunctionInfo>>, +) -> Option> { + if let Some(defs) = method_map.get(&(class_info.name.as_str(), method)) { + let all_preserving = defs + .iter() + .all(|f| signature_preserving_decorators(&f.decorators)); + return all_preserving.then(|| BoundMethod { + candidates: defs.clone(), + wrapper: None, + }); + } + let attribute = class_info + .attributes + .iter() + .find(|a| a.name == method && !a.has_annotation)?; + let bound_name = attribute.rhs_name.as_deref()?; + let candidates: Vec<&FunctionInfo> = module + .functions + .iter() + .filter(|f| f.class_name.is_none() && !f.nested_in_class && f.name == bound_name) + .filter(|f| signature_preserving_decorators(&f.decorators)) + .collect(); + (!candidates.is_empty()).then(|| BoundMethod { + candidates, + wrapper: attribute.rhs_descriptor.as_deref(), + }) +} + +/// `true` when every decorator on a function is known to preserve its +/// signature, so the raw parameter list is what a call binds against. +fn signature_preserving_decorators(decorators: &[String]) -> bool { + decorators.iter().all(|d| { + let leaf = d.rsplit('.').next().unwrap_or(d.as_str()); + SIGNATURE_PRESERVING.contains(&leaf) + }) +} + +/// How many leading parameters the descriptor protocol consumes for this +/// binding and access path: `staticmethod` none, `classmethod` its `cls` on +/// both paths, a plain function its `self` on instance access only. +fn receiver_params_consumed( + func: &FunctionInfo, + wrapper: Option<&str>, + instance_access: bool, +) -> usize { + let spelled = + |name: &str| wrapper == Some(name) || shared::decorator_spelled(&func.decorators, name); + if spelled("staticmethod") { + 0 + } else if spelled("classmethod") || instance_access { + 1 + } else { + 0 + } +} + +/// The positional arguments a signature requires once `consumed` leading +/// parameters are bound, or `None` when `*args` makes any count acceptable. +fn required_after_binding(func: &FunctionInfo, consumed: usize) -> Option { + func.vararg.is_none().then(|| { + func.parameters + .iter() + .skip(consumed) + .filter(|p| !p.has_default) + .count() + }) +} + +/// Emit a missing-argument diagnostic when no candidate signature accepts the +/// provided positional count under the binding's receiver consumption. +fn check_bound_call( + module: &ResolvedModule, + call: &CallSite, + class_info: &ClassInfo, + bound: &BoundMethod<'_>, + instance_access: bool, + diagnostics: &mut Vec, +) { + let provided = call.args.len(); + let mut min_required = usize::MAX; + for func in &bound.candidates { + let consumed = receiver_params_consumed(func, bound.wrapper, instance_access); + match required_after_binding(func, consumed) { + None => return, + Some(required) if provided >= required => return, + Some(required) => min_required = min_required.min(required), + } + } + let Some(missing) = min_required.checked_sub(provided).filter(|m| *m > 0) else { + return; + }; + let access = if instance_access { + "the instance receiver is bound implicitly" + } else { + "accessing through the class binds no receiver, so the first argument fills it" + }; + diagnostics.push(error_diagnostic_owned( + super::CODE.clone(), + format!( + "Call to `{}.{}()` is missing {missing} required argument{} \ + (expected {min_required}, got {provided}; {access})", + class_info.name, + call.callee, + if missing == 1 { "" } else { "s" }, + ), + call.span, + &module.path, + None, + None, + )); +} diff --git a/crates/basilisk-checker/src/rules/calls_argument_count.rs b/crates/basilisk-checker/src/rules/calls_argument_count/mod.rs similarity index 99% rename from crates/basilisk-checker/src/rules/calls_argument_count.rs rename to crates/basilisk-checker/src/rules/calls_argument_count/mod.rs index a536ac99..8fd5035b 100644 --- a/crates/basilisk-checker/src/rules/calls_argument_count.rs +++ b/crates/basilisk-checker/src/rules/calls_argument_count/mod.rs @@ -30,6 +30,8 @@ use crate::span_util::slice_span; use super::shared::annotation_is_classvar; use super::Rule; +mod method_binding; + const CODE: ErrorCode = ErrorCode { code: "calls_argument_count", docs_url: "https://www.basilisk-python.dev/errors/calls_argument_count", @@ -47,6 +49,7 @@ impl Rule for TooFewArguments { ) { check_plain_function_calls(module, diagnostics); check_builtin_method_calls(module, diagnostics); + method_binding::check_method_calls(module, diagnostics); check_constructor_calls(module, diagnostics); check_namedtuple_calls(module, diagnostics); } diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index b1bd65d9..9e0c5896 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -810,12 +810,29 @@ not run is `[~]`, not `[x]`. span" without hard-coding the rule's anchor. **RED proof**: 2 of 6 passed before the collector fix (bare + silent); method receiver, call argument, list element, and conditional were all silently missed; 6/6 after. -- [ ] Bind functions assigned in a class body as methods — implicit receiver +- [x] Bind functions assigned in a class body as methods — implicit receiver consumed on instance access, unbound on class access, `staticmethod` / `classmethod` honoured ([#382](https://github.com/Nimblesite/Basilisk/issues/382)). - - [ ] Test (write RED first): `C().m(1)` where `m = f` and `def f(self, a)` + — Three pieces: (1) new `CallReceiver::Constructor` so `C().m(...)` is + representable as a call site (previously dropped entirely); (2) + `AttributeInfo.rhs_is_descriptor_call: bool` REPLACED by + `rhs_descriptor: Option` (which wrapper) plus `rhs_name` + (the callable a class-body assignment binds), computed from the AST in + `class_info.rs::rhs_callable_binding`; (3) new + `rules/calls_argument_count/method_binding.rs` — resolves `C.m`/`C().m` + to literal `def`s or assignment-bound module functions, consumes the + receiver per access path and wrapper (`staticmethod` never, `classmethod` + always, plain on instance access only), abstains on unknown methods, + signature-changing decorators, keywords, and `*args`. The rule file moved + to directory form (`calls_argument_count/mod.rs`) to host the submodule. + - [x] Test (write RED first): `C().m(1)` where `m = f` and `def f(self, a)` is accepted; `C.m(1)` is an arity error; `staticmethod`/`classmethod` wrappers shift the receiver accordingly. + — `tests/checker/class_body_method_binding_tests.rs` (5 tests), pinned + against the literal-`def` baseline `C.n(1)` in the same class. **RED + proof**: 2 of 5 failed before the change — the baseline itself drew + nothing (no receiver-aware arity check existed) and `C().m()` was + uncollectable; 5/5 after. - [ ] Wire the shared entry point into the `bidir` engine, which currently has no name resolution at all and is consumed by only two rules (`narrowing_typeguard`, `narrowing_typeis_2`). From 8a727b74df8918c747615f443d67dccc269825dc Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:40:34 +1000 Subject: [PATCH 19/45] fixes --- .../basilisk-checker/src/annotation/forms.rs | 10 + crates/basilisk-checker/src/annotation/mod.rs | 10 + crates/basilisk-checker/src/class_naming.rs | 6 +- .../basilisk-checker/src/incremental_defs.rs | 54 ++++ crates/basilisk-checker/src/inference.rs | 7 +- crates/basilisk-checker/src/narrow/guards.rs | 65 +++- .../src/rules/narrowing_typeguard.rs | 32 +- .../src/rules/narrowing_typeis_2.rs | 300 +++++++++++------- crates/basilisk-checker/src/types.rs | 14 + .../checker/narrowing_typeguard_tests.rs | 46 +++ .../tests/checker/narrowing_typeis_2_tests.rs | 69 ++++ .../tests/resolver/test_coverage.rs | 4 +- .../tests/resolver/test_visitor_coverage.rs | 8 +- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 27 +- 14 files changed, 507 insertions(+), 145 deletions(-) diff --git a/crates/basilisk-checker/src/annotation/forms.rs b/crates/basilisk-checker/src/annotation/forms.rs index cd39d1e3..748f3280 100644 --- a/crates/basilisk-checker/src/annotation/forms.rs +++ b/crates/basilisk-checker/src/annotation/forms.rs @@ -31,6 +31,16 @@ pub(super) fn special_form( // `Annotated[T, ..]` and `Final[T]` are transparent wrappers. "annotated" | "final" => Some(first_type(args, &resolve)), "typeform" => Some(InferredType::TypeForm(Box::new(first_type(args, &resolve)))), + // PEP 647 / PEP 742 narrowing forms: the payload is the narrowing + // target, resolved by the same cascade so aliases expand. + "typeguard" => Some(InferredType::Guard { + type_is: false, + inner: Box::new(first_type(args, &resolve)), + }), + "typeis" => Some(InferredType::Guard { + type_is: true, + inner: Box::new(first_type(args, &resolve)), + }), "list" => Some(InferredType::List(Box::new(first_type(args, &resolve)))), "set" | "frozenset" => Some(InferredType::Set(Box::new(first_type(args, &resolve)))), "dict" => Some(dict_type(args, &resolve)), diff --git a/crates/basilisk-checker/src/annotation/mod.rs b/crates/basilisk-checker/src/annotation/mod.rs index 068da4b4..4d4909f3 100644 --- a/crates/basilisk-checker/src/annotation/mod.rs +++ b/crates/basilisk-checker/src/annotation/mod.rs @@ -213,6 +213,16 @@ impl<'m> AnnotationResolver<'m> { } } + /// Is `name` a leaf the module GROUNDS — a class declared here or a + /// builtin type? An unresolved spelling (a `TypeVar`, an imported class + /// this module cannot see into, a typo) is NOT grounded, and a judgment + /// that needs to know what the name IS must abstain rather than guess. + #[must_use] + pub fn is_grounded_name(&self, name: &str) -> bool { + let base = name.split('[').next().unwrap_or(name); + self.tables.nominal.contains(base) || builtins::is_builtin_type_name(base) + } + /// The cascade over one type expression. pub(crate) fn eval(&self, expr: &Expr, frame: &Frame) -> InferredType { if frame.depth > MAX_DEPTH { diff --git a/crates/basilisk-checker/src/class_naming.rs b/crates/basilisk-checker/src/class_naming.rs index 60bd76d5..67ca9432 100644 --- a/crates/basilisk-checker/src/class_naming.rs +++ b/crates/basilisk-checker/src/class_naming.rs @@ -102,6 +102,9 @@ pub fn class_name_of_type(ty: &InferredType) -> Option<(String, bool)> { LiteralValue::Bytes(_) => plain("bytes"), }, InferredType::Named(name) => Some((name.clone(), false)), + // A narrowing function's VALUE is a `bool` (PEP 647/742: the return + // type is consistent with `bool`), so its members are bool's. + InferredType::Guard { .. } => plain("bool"), // A union names a class exactly when EVERY arm names the same one: // `int | int` (a list of int literals, a conditional expression) is an // int, while `int | str` is not any single class. The `LiteralString` @@ -166,7 +169,8 @@ pub fn element_type_of(ty: &InferredType) -> Option { | InferredType::Union(_) | InferredType::Optional(_) | InferredType::Callable(_) - | InferredType::TypeForm(_) => None, + | InferredType::TypeForm(_) + | InferredType::Guard { .. } => None, } } diff --git a/crates/basilisk-checker/src/incremental_defs.rs b/crates/basilisk-checker/src/incremental_defs.rs index 1785b8f2..34dd8613 100644 --- a/crates/basilisk-checker/src/incremental_defs.rs +++ b/crates/basilisk-checker/src/incremental_defs.rs @@ -390,6 +390,59 @@ fn class_level_attributes(slice: &str) -> Option> { Some(attrs) } +/// Guard-annotation text → the resolved narrowing target, for every +/// `TypeGuard[X]` / `TypeIs[X]` guard in one file. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct GuardTypes(pub std::collections::HashMap); + +/// Tracked query: the file's guard texts resolved by the FULL-module +/// [TYPEINF-ANNOTATION-RESOLUTION] cascade. The per-definition narrowing pass +/// runs on a definition SLICE where module aliases and classes are invisible, +/// so the resolved targets must arrive from this file-level view (Stage 0.5 +/// bidir wiring). +#[salsa::tracked(returns(ref))] +pub fn guard_type_environment(db: &dyn Db, file: SourceFile) -> GuardTypes { + let source = file.text(db); + let Ok(parsed) = basilisk_parser::parse_source(source.clone(), "module.py".to_owned()) else { + return GuardTypes::default(); + }; + let Ok(resolved) = basilisk_resolver::resolve(&parsed) else { + return GuardTypes::default(); + }; + let Some(resolver) = crate::annotation::AnnotationResolver::for_module(&resolved) else { + return GuardTypes::default(); + }; + let mut map = std::collections::HashMap::new(); + for function in &resolved.functions { + for guard in &function.narrowing_guards { + collect_guard_types(&guard.kind, &resolver, &mut map); + } + } + GuardTypes(map) +} + +/// Record the resolved target of one guard kind, recursing through `assert`. +fn collect_guard_types( + kind: &basilisk_resolver::NarrowingGuardKind, + resolver: &crate::annotation::AnnotationResolver<'_>, + map: &mut std::collections::HashMap, +) { + match kind { + basilisk_resolver::NarrowingGuardKind::TypeGuard { guard_type, .. } + | basilisk_resolver::NarrowingGuardKind::TypeIs { guard_type, .. } => { + if !map.contains_key(guard_type) { + if let Some(resolved) = resolver.resolve_text(guard_type) { + let _ = map.insert(guard_type.clone(), resolved); + } + } + } + basilisk_resolver::NarrowingGuardKind::Assert { inner } => { + collect_guard_types(inner, resolver, map); + } + _ => {} + } +} + /// Tracked query: the `(name, type)` interface of the module's FUNCTIONS and /// CLASSES only — the backdating boundary variable inference reads its /// callables through (variables are excluded to keep variable↔variable @@ -549,6 +602,7 @@ pub fn narrowed_uses<'db>( .iter() .cloned() .collect(), + guard_types: guard_type_environment(db, def.file(db)).0.clone(), ..Default::default() }; crate::narrow::analyse_function_in( diff --git a/crates/basilisk-checker/src/inference.rs b/crates/basilisk-checker/src/inference.rs index 202ec5fb..3ad2497d 100644 --- a/crates/basilisk-checker/src/inference.rs +++ b/crates/basilisk-checker/src/inference.rs @@ -271,7 +271,8 @@ pub fn is_fully_known(ty: &InferredType) -> bool { InferredType::List(inner) | InferredType::Set(inner) | InferredType::Optional(inner) - | InferredType::TypeForm(inner) => is_fully_known(inner), + | InferredType::TypeForm(inner) + | InferredType::Guard { inner, .. } => is_fully_known(inner), InferredType::Dict(key, value) => is_fully_known(key) && is_fully_known(value), InferredType::Tuple(elems) | InferredType::Union(elems) => elems.iter().all(is_fully_known), InferredType::Callable(info) => { @@ -331,6 +332,10 @@ pub fn display_widened(ty: &InferredType) -> InferredType { .map(display_widened) .fold(InferredType::Never, InferredType::union), InferredType::TypeForm(inner) => InferredType::TypeForm(Box::new(display_widened(inner))), + InferredType::Guard { type_is, inner } => InferredType::Guard { + type_is: *type_is, + inner: Box::new(display_widened(inner)), + }, InferredType::Callable(info) => InferredType::Callable(crate::types::CallableInfo { param_types: info.param_types.iter().map(display_widened).collect(), return_type: Box::new(display_widened(&info.return_type)), diff --git a/crates/basilisk-checker/src/narrow/guards.rs b/crates/basilisk-checker/src/narrow/guards.rs index 5accfb24..54f5bc21 100644 --- a/crates/basilisk-checker/src/narrow/guards.rs +++ b/crates/basilisk-checker/src/narrow/guards.rs @@ -36,6 +36,21 @@ pub struct NarrowContext { /// return and a `Never`-returning call statement counts as divergence /// (inference-driven reachability, [TYPEINF-TARGET-NARROWING]). pub callables: HashMap, + /// Guard-annotation text → the RESOLVED narrowing target, produced by the + /// module-level [TYPEINF-ANNOTATION-RESOLUTION] cascade. A + /// `TypeGuard[MyAlias]` narrows to what `MyAlias` resolves to, not to an + /// opaque name; texts absent here fall back to the annotation-text + /// lowering (Stage 0.5 bidir wiring). + pub guard_types: HashMap, +} + +/// The narrowing target a `TypeGuard[X]` / `TypeIs[X]` text denotes: the +/// module-resolved type when the context has one, else the text lowering. +fn resolved_guard_type(ctx: &NarrowContext, guard_type: &str) -> InferredType { + ctx.guard_types + .get(guard_type) + .cloned() + .unwrap_or_else(|| InferredType::from_annotation(guard_type)) } /// What one guard does to one variable in each branch. @@ -110,7 +125,7 @@ fn outcome_for_kind( .. } => Some(GuardOutcome { variable: variable.clone(), - positive: InferredType::from_annotation(guard_type), + positive: resolved_guard_type(ctx, guard_type), // PEP 647: TypeGuard narrows the positive branch ONLY. negative: current.clone(), whole_scope, @@ -120,7 +135,7 @@ fn outcome_for_kind( guard_type, .. } => { - let narrowed_to = InferredType::from_annotation(guard_type); + let narrowed_to = resolved_guard_type(ctx, guard_type); Some(GuardOutcome { variable: variable.clone(), // PEP 742: TypeIs narrows BOTH branches. @@ -573,6 +588,52 @@ mod tests { ); } + /// Stage 0.5 bidir wiring: a `TypeGuard[MyAlias]` / `TypeIs[MyAlias]` + /// narrows to the type the module RESOLVED for the alias, not to an + /// opaque lowered name ([TYPEINF-ANNOTATION-RESOLUTION]). + #[test] + fn guard_types_resolve_through_the_module_context() { + let current = InferredType::Union(vec![InferredType::Int, InferredType::Str]); + let ctx = NarrowContext { + guard_types: std::iter::once(("MyAlias".to_owned(), InferredType::Str)).collect(), + ..NarrowContext::default() + }; + let type_guard = guard_outcomes_in( + &guard(NarrowingGuardKind::TypeGuard { + variable: "x".to_owned(), + guard_type: "MyAlias".to_owned(), + if_body_span: Span::new(0, 0), + else_body_span: None, + }), + ¤t, + &ctx, + ) + .expect("outcome"); + assert_eq!( + type_guard.positive, + InferredType::Str, + "the alias narrows to its RESOLVED type" + ); + + let type_is = guard_outcomes_in( + &guard(NarrowingGuardKind::TypeIs { + variable: "x".to_owned(), + guard_type: "MyAlias".to_owned(), + if_body_span: Span::new(0, 0), + else_body_span: None, + }), + ¤t, + &ctx, + ) + .expect("outcome"); + assert_eq!(type_is.positive, InferredType::Str); + assert_eq!( + type_is.negative, + InferredType::Int, + "TypeIs subtracts the RESOLVED type from the negative branch" + ); + } + /// Guards inside loops do not produce persistent narrowing /// ([TYPEINF-NARROWING-SCOPE]). #[test] diff --git a/crates/basilisk-checker/src/rules/narrowing_typeguard.rs b/crates/basilisk-checker/src/rules/narrowing_typeguard.rs index f0f6fd1d..91ee4840 100644 --- a/crates/basilisk-checker/src/rules/narrowing_typeguard.rs +++ b/crates/basilisk-checker/src/rules/narrowing_typeguard.rs @@ -9,8 +9,10 @@ use basilisk_resolver::ResolvedModule; use super::Rule; +use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; use crate::span_util::slice_span; +use crate::types::InferredType; const CODE: ErrorCode = ErrorCode { code: "narrowing_typeguard", @@ -22,16 +24,13 @@ const CODE: ErrorCode = ErrorCode { /// /// Implements [TYPEINF-NARROWING-TYPEGUARD] and [TYPEINF-NARROWING-TYPEIS] — /// validity precondition of a user-defined narrowing function: it must have a -/// parameter to narrow. The narrowing *effect* (positive-only for `TypeGuard`, -/// bidirectional for `TypeIs`) is applied in the out-of-scope resolver narrowing -/// visitor (see the consolidated map). +/// parameter to narrow. Guard-ness is read from the RESOLVED return type +/// ([TYPEINF-ANNOTATION-RESOLUTION]), so an alias of `TypeGuard[X]` / +/// `TypeIs[X]` is a guard exactly as the spelled-out form is. The narrowing +/// *effect* (positive-only for `TypeGuard`, bidirectional for `TypeIs`) is +/// applied in the narrowing flow (see the consolidated map). pub(crate) struct TypeGuardNoNarrowingParam; -/// Returns `true` if the annotation text references `TypeGuard` or `TypeIs`. -fn is_type_guard_or_type_is(ann_text: &str) -> bool { - ann_text.contains("TypeGuard") || ann_text.contains("TypeIs") -} - /// Returns `true` if the function has only `self` or `cls` parameters /// (no user-facing parameters to narrow). fn has_only_self_or_cls(func: &basilisk_resolver::FunctionInfo) -> bool { @@ -48,6 +47,9 @@ impl Rule for TypeGuardNoNarrowingParam { diagnostics: &mut Vec, ) { let source = &module.source; + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; for func in &module.functions { // Must be a method (inside a class). @@ -65,21 +67,19 @@ impl Rule for TypeGuardNoNarrowingParam { continue; }; - // Check if the return type involves TypeGuard or TypeIs. - if !is_type_guard_or_type_is(ann_text) { + // The return type must RESOLVE to a narrowing form — through + // aliases too, so `Guard = TypeGuard[int]` does not hide one. + let Some(InferredType::Guard { type_is, .. }) = resolver.resolve_text(ann_text) + else { continue; - } + }; // Check if the method has no user-facing parameters. if !has_only_self_or_cls(func) { continue; } - let guard_kind = if ann_text.contains("TypeIs") { - "TypeIs" - } else { - "TypeGuard" - }; + let guard_kind = if type_is { "TypeIs" } else { "TypeGuard" }; diagnostics.push(error_diagnostic_owned( CODE.clone(), diff --git a/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs b/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs index 35814821..62a30df4 100644 --- a/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs +++ b/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs @@ -8,8 +8,11 @@ use basilisk_resolver::ResolvedModule; use super::Rule; +use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diag_help_note, Diagnostic, ErrorCode}; use crate::span_util::slice_span; +use crate::subtyping::SubtypingContext; +use crate::types::InferredType; const CODE: ErrorCode = ErrorCode { code: "narrowing_typeis_2", @@ -21,129 +24,182 @@ const CODE: ErrorCode = ErrorCode { /// /// Implements [TYPEINF-NARROWING-TYPEIS] — the PEP 742 consistency precondition: /// because `TypeIs` narrows bidirectionally, the narrowed type `X` must be a -/// subtype of (consistent with) the input parameter type. +/// subtype of (consistent with) the input parameter type. Both sides resolve +/// through [TYPEINF-ANNOTATION-RESOLUTION] first, so aliases expand and the +/// nominal walk sees classes, not annotation text; a side the module cannot +/// ground (a `TypeVar`, an unseen import) abstains rather than guesses. pub(crate) struct TypeIsInconsistentNarrowing; -/// Extract the inner type from `TypeIs[X]` or `TypeGuard[X]`. Returns the inner type text. -fn extract_inner_type(ann_text: &str) -> Option<&str> { - let prefix = "TypeIs["; - let start = ann_text.find(prefix)?; - let inner_start = start + prefix.len(); - let rest = ann_text.get(inner_start..)?; - // Parsed annotations overwhelmingly end at this subscript. This covers - // both simple and nested arguments (`TypeIs[list[int]]`) without a second - // bracket walk; retain the general matcher for qualified/trailing forms. - if let Some(inner) = rest.strip_suffix(']') { - return Some(inner); +/// The three-valued consistency judgment: a verdict either way requires both +/// sides to be grounded; anything the judgment cannot decide abstains. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Verdict { + /// The narrowed type is assignable to the input type. + Consistent, + /// Both sides are grounded and the narrowed type is NOT assignable. + Inconsistent, + /// At least one side is not decidable here — no diagnostic. + Unknown, +} + +/// Nominal subtyping context over the module's classes. +fn module_subtyping(module: &ResolvedModule) -> SubtypingContext { + let mut ctx = SubtypingContext::default(); + for class in &module.classes { + ctx.register_class(&class.name, &class.bases); } - // Find matching closing bracket (handle nested brackets) - let mut depth = 1u32; - let mut end_pos = 0; - for (idx, ch) in rest.char_indices() { - match ch { - '[' => depth += 1, - ']' => { - depth -= 1; - if depth == 0 { - end_pos = idx; - break; - } + ctx +} + +/// The leaf name a type compares nominally by, or `None` when the type is not +/// a groundable leaf (so the judgment must abstain or recurse structurally). +fn leaf_name(resolver: &AnnotationResolver<'_>, ty: &InferredType) -> Option { + match ty { + InferredType::Int => Some("int".to_owned()), + InferredType::Str | InferredType::LiteralString => Some("str".to_owned()), + InferredType::Float => Some("float".to_owned()), + InferredType::Bool => Some("bool".to_owned()), + InferredType::Bytes => Some("bytes".to_owned()), + InferredType::None_ => Some("None".to_owned()), + InferredType::Literal(value) => Some( + match value { + crate::types::LiteralValue::Int(_) => "int", + crate::types::LiteralValue::Str(_) => "str", + crate::types::LiteralValue::Float(_) => "float", + crate::types::LiteralValue::Bool(_) => "bool", + crate::types::LiteralValue::Bytes(_) => "bytes", } - _ => {} - } - } - if depth == 0 { - rest.get(..end_pos) - } else { - None + .to_owned(), + ), + InferredType::Named(name) => resolver.is_grounded_name(name).then(|| name.clone()), + _ => None, } } -/// Returns `true` if the type text contains a `TypeVar` (single uppercase letter -/// or a known TypeVar-like name). When `TypeVars` are present, we can't statically -/// determine consistency without full type inference, so we assume consistent. -fn contains_typevar(type_text: &str) -> bool { - if !type_text.as_bytes().iter().any(u8::is_ascii_uppercase) { - return false; +/// Consistency of `narrowed` with `input` on RESOLVED types. +fn consistency( + resolver: &AnnotationResolver<'_>, + ctx: &SubtypingContext, + narrowed: &InferredType, + input: &InferredType, +) -> Verdict { + if narrowed == input + || matches!(narrowed, InferredType::Any | InferredType::Never) + || matches!(input, InferredType::Any) + { + return Verdict::Consistent; } - // Check for single-letter uppercase names that are TypeVars - // Also check common TypeVar patterns like T, T_A, T_co, etc. - for segment in type_text.split(&['[', ']', ',', ' ']) { - let segment = segment.trim(); - if segment.is_empty() { - continue; + match (narrowed, input) { + // A narrowed union is consistent when EVERY arm is. + (InferredType::Union(arms), _) => { + all_arms(arms.iter().map(|arm| consistency(resolver, ctx, arm, input))) } - // Single uppercase letter (T, U, V, etc.) - if segment.len() == 1 - && segment - .chars() - .next() - .is_some_and(|c| c.is_ascii_uppercase()) - { - return true; + (InferredType::Optional(inner), _) => all_arms( + [ + consistency(resolver, ctx, inner, input), + consistency(resolver, ctx, &InferredType::None_, input), + ] + .into_iter(), + ), + // An input union accepts a narrow into ANY of its arms. + (_, InferredType::Union(arms)) => { + any_arm(arms.iter().map(|arm| consistency(resolver, ctx, narrowed, arm))) } - // TypeVar patterns like T_A, T_co, T_contra - if segment.starts_with("T_") || segment.starts_with("T1") || segment.starts_with("T2") { - return true; + (_, InferredType::Optional(inner)) => any_arm( + [ + consistency(resolver, ctx, narrowed, inner), + matches!(narrowed, InferredType::None_) + .then_some(Verdict::Consistent) + .unwrap_or(Verdict::Inconsistent), + ] + .into_iter(), + ), + // Same-shape containers are invariant: equality was checked above, so + // grounded-but-different arguments are inconsistent. + (InferredType::List(a), InferredType::List(b)) + | (InferredType::Set(a), InferredType::Set(b)) => { + invariant(resolver, ctx, &[a.as_ref().clone()], &[b.as_ref().clone()]) } + (InferredType::Dict(ak, av), InferredType::Dict(bk, bv)) => invariant( + resolver, + ctx, + &[ak.as_ref().clone(), av.as_ref().clone()], + &[bk.as_ref().clone(), bv.as_ref().clone()], + ), + (InferredType::Tuple(a), InferredType::Tuple(b)) => invariant(resolver, ctx, a, b), + _ => leaf_consistency(resolver, ctx, narrowed, input), } - false } -/// Check if `narrowed` type is consistent with `input` type. -/// Returns `true` if they are consistent (no error). -/// -/// For `TypeIs`, the narrowed type must be assignable to the input type. -/// This means narrowed must be a subtype of input. -fn is_consistent(narrowed: &str, input: &str) -> bool { - let narrowed = narrowed.trim(); - let input = input.trim(); - - // `object` accepts anything - if input == "object" { - return true; - } - - // Identity and the numeric tower via the shared core - // ([NARROWPLAN-SUBTYPING]). - if crate::subtyping::name_subtype(narrowed, input) { - return true; - } - - // `Any` is consistent with anything - if input == "Any" || narrowed == "Any" { - return true; +/// Both sides as nominal leaves through the shared subtype walk; anything +/// either side cannot ground abstains. +fn leaf_consistency( + resolver: &AnnotationResolver<'_>, + ctx: &SubtypingContext, + narrowed: &InferredType, + input: &InferredType, +) -> Verdict { + match (leaf_name(resolver, narrowed), leaf_name(resolver, input)) { + (Some(sub), Some(sup)) => { + if ctx.is_subtype(&sub, &sup) { + Verdict::Consistent + } else { + Verdict::Inconsistent + } + } + _ => Verdict::Unknown, } +} - // If either type contains TypeVars, we can't determine consistency - // without full type inference - assume consistent. Keep this after the - // concrete scalar fast paths so ordinary lowercase builtins do no token - // splitting. - if contains_typevar(narrowed) || contains_typevar(input) { - return true; +/// Invariant positions: every pair must be mutually consistent; a grounded +/// difference in either direction is inconsistent, arity mismatch too. +fn invariant( + resolver: &AnnotationResolver<'_>, + ctx: &SubtypingContext, + a: &[InferredType], + b: &[InferredType], +) -> Verdict { + if a.len() != b.len() { + return Verdict::Inconsistent; } + all_arms(a.iter().zip(b).map(|(x, y)| { + match ( + consistency(resolver, ctx, x, y), + consistency(resolver, ctx, y, x), + ) { + (Verdict::Consistent, Verdict::Consistent) => Verdict::Consistent, + (Verdict::Unknown, _) | (_, Verdict::Unknown) => Verdict::Unknown, + _ => Verdict::Inconsistent, + } + })) +} - // For generic types like list[X] vs list[Y], check if it's the same base - // Lists, sets, dicts are invariant, so list[int] is NOT a subtype of list[object] - if let (Some(n_base), Some(i_base)) = (generic_base(narrowed), generic_base(input)) { - // Same generic base - invariant containers are not subtypes - if n_base == i_base { - // For invariant types (list, dict, set), exact match is required - // We already checked full string equality above, so if we're here - // the type args differ → not consistent - return false; +/// Fold "every arm must be consistent": any inconsistency wins, any +/// undecidable arm abstains the whole judgment. +fn all_arms(verdicts: impl Iterator) -> Verdict { + let mut result = Verdict::Consistent; + for verdict in verdicts { + match verdict { + Verdict::Inconsistent => return Verdict::Inconsistent, + Verdict::Unknown => result = Verdict::Unknown, + Verdict::Consistent => {} } } - - // For simple types with no obvious subtype relationship, reject - // This handles cases like str vs int - false + result } -/// Split a generic type `Base[Args]` into `(base, args)` text. -fn generic_base(type_text: &str) -> Option<&str> { - let bracket = type_text.find('[')?; - type_text.get(..bracket) +/// Fold "some arm must accept": any consistent arm wins; otherwise abstain if +/// anything was undecidable. +fn any_arm(verdicts: impl Iterator) -> Verdict { + let mut result = Verdict::Inconsistent; + for verdict in verdicts { + match verdict { + Verdict::Consistent => return Verdict::Consistent, + Verdict::Unknown => result = Verdict::Unknown, + Verdict::Inconsistent => {} + } + } + result } impl Rule for TypeIsInconsistentNarrowing { @@ -154,25 +210,27 @@ impl Rule for TypeIsInconsistentNarrowing { diagnostics: &mut Vec, ) { let source = &module.source; + let Some(resolver) = AnnotationResolver::for_module(module) else { + return; + }; + let subtyping = module_subtyping(module); for func in &module.functions { - // Must have a return annotation span. let Some(ann_span) = func.return_annotation_span else { continue; }; - - // Extract annotation text. let Some(ann_text) = slice_span(source, ann_span) else { continue; }; - // Only check TypeIs (not TypeGuard - TypeGuard has no consistency requirement) - if !ann_text.contains("TypeIs[") { - continue; - } - - // Extract the inner narrowed type. - let Some(narrowed_type) = extract_inner_type(ann_text) else { + // Only `TypeIs` carries the consistency precondition — resolved, + // so an alias of `TypeIs[X]` is checked exactly like the spelled + // form ([TYPEINF-ANNOTATION-RESOLUTION]). + let Some(InferredType::Guard { + type_is: true, + inner, + }) = resolver.resolve_text(ann_text) + else { continue; }; @@ -181,31 +239,35 @@ impl Rule for TypeIsInconsistentNarrowing { .parameters .iter() .find(|param| param.name != "self" && param.name != "cls"); - let Some(param) = first_param else { continue; }; - - // Get the parameter's annotation text. let Some(param_ann_span) = param.annotation_span else { continue; }; - let Some(param_type) = slice_span(source, param_ann_span) else { continue; }; + let Some(input) = resolver.resolve_text(param_type) else { + continue; + }; + + // Structural targets (Protocols, TypedDicts) need a structural + // judgment this nominal walk cannot make — abstain. + if resolver.is_structural_target(&inner) || resolver.is_structural_target(&input) { + continue; + } - // Check consistency. - if !is_consistent(narrowed_type, param_type) { + if consistency(&resolver, &subtyping, &inner, &input) == Verdict::Inconsistent { diagnostics.push(error_diag_help_note( CODE.clone(), format!( - "`TypeIs[{narrowed_type}]` narrows to a type inconsistent with parameter type `{param_type}`" + "`TypeIs[{inner}]` narrows to a type inconsistent with parameter type `{input}`" ), ann_span, &module.path, format!( - "The narrowed type `{narrowed_type}` must be consistent with the input type `{param_type}`" + "The narrowed type `{inner}` must be consistent with the input type `{input}`" ), "Per the typing spec, TypeIs requires the narrowed type to be \ consistent with the input type", diff --git a/crates/basilisk-checker/src/types.rs b/crates/basilisk-checker/src/types.rs index 63e608d5..8ed745af 100644 --- a/crates/basilisk-checker/src/types.rs +++ b/crates/basilisk-checker/src/types.rs @@ -59,6 +59,16 @@ pub enum InferredType { /// The inner type is what the type form represents (e.g. `TypeForm[int]` /// means a type form that represents `int`). TypeForm(Box), + /// `TypeGuard[T]` (PEP 647) or `TypeIs[T]` (PEP 742) — a user-defined + /// narrowing function's return form. `type_is` distinguishes the PEP 742 + /// bidirectional form (narrows both branches, requires the narrowed type + /// to be consistent with the input) from the positive-only `TypeGuard`. + Guard { + /// `true` for `TypeIs[T]`, `false` for `TypeGuard[T]`. + type_is: bool, + /// The narrowing target `T`, resolved through the same cascade. + inner: Box, + }, } /// Represents a callable type's parameter and return type information. @@ -142,6 +152,10 @@ impl fmt::Display for InferredType { InferredType::Any => write!(f, "TypeForm"), other => write!(f, "TypeForm[{other}]"), }, + InferredType::Guard { type_is, inner } => { + let form = if *type_is { "TypeIs" } else { "TypeGuard" }; + write!(f, "{form}[{inner}]") + } } } } diff --git a/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs b/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs index 735fd14b..9881e414 100644 --- a/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs +++ b/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs @@ -33,3 +33,49 @@ def is_str() -> TypeGuard[str]: let _ = codes(&diags); Ok(()) } + +// Exercises [TYPEINF-ANNOTATION-RESOLUTION] — the guard-ness of a return +// annotation resolves through the alias table, so `Guard = TypeGuard[int]` +// is not an opaque name that hides the missing narrowing parameter +// (Stage 0.5 bidir wiring). +#[test] +fn aliased_typeguard_return_still_requires_narrowing_param( +) -> Result<(), Box> { + let source = r" +from typing import TypeGuard + +Guard = TypeGuard[int] + +class C: + def m(self) -> Guard: + return True +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"narrowing_typeguard"), + "an aliased TypeGuard return type must resolve to the guard form, \ + not stay an opaque name that silences the missing-parameter error" + ); + Ok(()) +} + +// Same resolution contract for the PEP 742 form. +#[test] +fn aliased_typeis_return_still_requires_narrowing_param( +) -> Result<(), Box> { + let source = r" +from typing import TypeIs + +IsInt = TypeIs[int] + +class D: + def n(self) -> IsInt: + return True +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"narrowing_typeguard"), + "an aliased TypeIs return type must resolve to the guard form" + ); + Ok(()) +} diff --git a/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs b/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs index 9385cef0..6bf78b78 100644 --- a/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs +++ b/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs @@ -33,3 +33,72 @@ def bad_check(x: int) -> TypeIs[str]: let _ = codes(&diags); Ok(()) } + +// Exercises [TYPEINF-ANNOTATION-RESOLUTION] — the narrowed target resolves +// through the alias table before the consistency judgment, so an alias of the +// parameter type is consistent, not an opaque mismatched name +// (Stage 0.5 bidir wiring). +#[test] +fn aliased_narrowed_type_is_consistent() -> Result<(), Box> { + let source = r" +from typing import TypeIs + +MyAlias = str + +def is_my(x: str) -> TypeIs[MyAlias]: + return isinstance(x, str) +"; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"narrowing_typeis_2"), + "`TypeIs[MyAlias]` where `MyAlias = str` narrows `str` to `str`; \ + comparing the unresolved alias name is a false positive" + ); + Ok(()) +} + +// Exercises [TYPEINF-SUBTYPING-NOMINAL] through the resolved cascade — a +// same-module subclass is consistent with its base as a narrowing target. +#[test] +fn subclass_narrowed_type_is_consistent() -> Result<(), Box> { + let source = r" +from typing import TypeIs + +class Base: + pass + +class MyClass(Base): + pass + +def is_mine(x: Base) -> TypeIs[MyClass]: + return isinstance(x, MyClass) +"; + let diags = run(source)?; + assert!( + !codes(&diags).contains(&"narrowing_typeis_2"), + "narrowing `Base` to its subclass `MyClass` is the canonical TypeIs \ + use; the nominal walk must see the resolved class, not opaque text" + ); + Ok(()) +} + +// The resolution work must not blunt the rule: a resolved alias that IS +// inconsistent still fires. +#[test] +fn aliased_narrowed_type_still_fires_when_inconsistent( +) -> Result<(), Box> { + let source = r" +from typing import TypeIs + +MyAlias = str + +def bad(x: int) -> TypeIs[MyAlias]: + return False +"; + let diags = run(source)?; + assert!( + codes(&diags).contains(&"narrowing_typeis_2"), + "`MyAlias` resolves to `str`, which cannot narrow an `int` input" + ); + Ok(()) +} diff --git a/crates/basilisk-resolver/tests/resolver/test_coverage.rs b/crates/basilisk-resolver/tests/resolver/test_coverage.rs index ffbfe10f..fd0626dc 100644 --- a/crates/basilisk-resolver/tests/resolver/test_coverage.rs +++ b/crates/basilisk-resolver/tests/resolver/test_coverage.rs @@ -272,7 +272,9 @@ fn decorator_via_attribute_name() -> Result<(), Box> { .to_owned(); let resolved = resolve_src(&src)?; let func = resolved.functions.iter().find(|f| f.name == "bar"); - assert!(func.is_some_and(|f| f.decorators.iter().any(|d| d == "abstractmethod"))); + // The FULL dotted path is recorded — discarding the qualifier made + // `@t.overload` indistinguishable from a foreign `overload` (#380). + assert!(func.is_some_and(|f| f.decorators.iter().any(|d| d == "abc.abstractmethod"))); Ok(()) } diff --git a/crates/basilisk-resolver/tests/resolver/test_visitor_coverage.rs b/crates/basilisk-resolver/tests/resolver/test_visitor_coverage.rs index 8b5aae5f..cd204e8e 100644 --- a/crates/basilisk-resolver/tests/resolver/test_visitor_coverage.rs +++ b/crates/basilisk-resolver/tests/resolver/test_visitor_coverage.rs @@ -160,10 +160,12 @@ fn attribute_decorator_name_extracted() -> Result<(), Box .iter() .find(|f| f.name == "foo") .ok_or("foo must be resolved")?; - // decorator_name returns "abstractmethod" for the Attribute expression + // decorator_name renders the FULL dotted path for the Attribute + // expression — the qualifier is what lets consumers discriminate a + // typing-module decorator from a same-named foreign one (#380). assert!( - method.decorators.contains(&"abstractmethod".to_owned()), - "attribute decorator name must be extracted" + method.decorators.contains(&"abc.abstractmethod".to_owned()), + "attribute decorator path must be extracted in full" ); Ok(()) } diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index 9e0c5896..6e717b9c 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -833,12 +833,35 @@ not run is `[~]`, not `[x]`. proof**: 2 of 5 failed before the change — the baseline itself drew nothing (no receiver-aware arity check existed) and `C().m()` was uncollectable; 5/5 after. -- [ ] Wire the shared entry point into the `bidir` engine, which currently has +- [x] Wire the shared entry point into the `bidir` engine, which currently has no name resolution at all and is consumed by only two rules (`narrowing_typeguard`, `narrowing_typeis_2`). - - [ ] Test (write RED first): a `TypeGuard[MyAlias]` / `TypeIs[MyClass]` + — `TypeGuard`/`TypeIs` are now MODELLED: `InferredType::Guard { type_is, + inner }` (PEP 647/742), produced by the cascade's special forms so aliases + expand through it. `narrowing_typeguard` reads guard-ness from the RESOLVED + return type (the `contains("TypeGuard")` text sniff is DELETED); + `narrowing_typeis_2` judges consistency on RESOLVED types via the shared + `SubtypingContext` nominal walk with a three-valued verdict that abstains on + ungrounded names — its `extract_inner_type` bracket walker, + `contains_typevar` uppercase heuristic, string `is_consistent`, and + `generic_base` are ALL DELETED. The narrowing flow that seeds the engine + narrows `TypeGuard[X]`/`TypeIs[X]` through `NarrowContext.guard_types` + (file-level Salsa query `guard_type_environment` resolves every guard text + by the full-module cascade; the per-definition slice can't see aliases), + retiring both `from_annotation` guard sites in `narrow/guards.rs`. + - [x] Test (write RED first): a `TypeGuard[MyAlias]` / `TypeIs[MyClass]` narrows to the RESOLVED type, not to an opaque name, in both consuming rules. + — `narrowing_typeguard_tests.rs`: aliased `Guard = TypeGuard[int]` / + `IsInt = TypeIs[int]` returns still require a narrowing parameter; + `narrowing_typeis_2_tests.rs`: `TypeIs[MyAlias]` with `MyAlias = str` and + `TypeIs[MyClass]` narrowing its `Base` are consistent, plus an + assertiveness pin (resolved-but-inconsistent alias still fires); + `narrow/guards.rs::guard_types_resolve_through_the_module_context` pins + the engine seam (`MyAlias` → `Str`, `TypeIs` subtracts the resolved + type). **RED proof**: 4 of 5 rule tests failed before the change (both + alias forms invisible to the sniff; both resolution false positives + fired); 5/5 after, full checker suite green (51 binaries). **Gates owed by Stage 0.5 as a whole** — run after the boxes above, and again before the stage is declared closed: From c902cc6bd9896d81341e4770b4e432462c19e10c Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:48:55 +1000 Subject: [PATCH 20/45] ci prep --- crates/basilisk-checker/src/class_naming.rs | 7 +- .../basilisk-checker/src/incremental_defs.rs | 6 +- .../calls_argument_count/method_binding.rs | 12 +-- crates/basilisk-checker/src/types.rs | 85 ++++++++----------- .../calls_expression_position_tests.rs | 6 +- .../src/visitor/class_info.rs | 4 +- 6 files changed, 56 insertions(+), 64 deletions(-) diff --git a/crates/basilisk-checker/src/class_naming.rs b/crates/basilisk-checker/src/class_naming.rs index 67ca9432..937238c4 100644 --- a/crates/basilisk-checker/src/class_naming.rs +++ b/crates/basilisk-checker/src/class_naming.rs @@ -85,7 +85,9 @@ pub fn class_name_of_type(ty: &InferredType) -> Option<(String, bool)> { InferredType::Str => plain("str"), InferredType::Int => plain("int"), InferredType::Float => plain("float"), - InferredType::Bool => plain("bool"), + // A narrowing function's VALUE is a `bool` (PEP 647/742: the return type + // is consistent with `bool`), so `Guard` shares bool's members. + InferredType::Bool | InferredType::Guard { .. } => plain("bool"), InferredType::Bytes => plain("bytes"), // Type arguments do not change which class holds the members. InferredType::List(_) => plain("list"), @@ -102,9 +104,6 @@ pub fn class_name_of_type(ty: &InferredType) -> Option<(String, bool)> { LiteralValue::Bytes(_) => plain("bytes"), }, InferredType::Named(name) => Some((name.clone(), false)), - // A narrowing function's VALUE is a `bool` (PEP 647/742: the return - // type is consistent with `bool`), so its members are bool's. - InferredType::Guard { .. } => plain("bool"), // A union names a class exactly when EVERY arm names the same one: // `int | int` (a list of int literals, a conditional expression) is an // int, while `int | str` is not any single class. The `LiteralString` diff --git a/crates/basilisk-checker/src/incremental_defs.rs b/crates/basilisk-checker/src/incremental_defs.rs index 34dd8613..35f31318 100644 --- a/crates/basilisk-checker/src/incremental_defs.rs +++ b/crates/basilisk-checker/src/incremental_defs.rs @@ -406,14 +406,14 @@ pub fn guard_type_environment(db: &dyn Db, file: SourceFile) -> GuardTypes { let Ok(parsed) = basilisk_parser::parse_source(source.clone(), "module.py".to_owned()) else { return GuardTypes::default(); }; - let Ok(resolved) = basilisk_resolver::resolve(&parsed) else { + let Ok(module) = basilisk_resolver::resolve(&parsed) else { return GuardTypes::default(); }; - let Some(resolver) = crate::annotation::AnnotationResolver::for_module(&resolved) else { + let Some(resolver) = crate::annotation::AnnotationResolver::for_module(&module) else { return GuardTypes::default(); }; let mut map = std::collections::HashMap::new(); - for function in &resolved.functions { + for function in &module.functions { for guard in &function.narrowing_guards { collect_guard_types(&guard.kind, &resolver, &mut map); } diff --git a/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs b/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs index f82816fe..712bee46 100644 --- a/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs +++ b/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs @@ -105,7 +105,10 @@ fn resolve_bound_method<'a>( .filter(|f| f.class_name.is_none() && !f.nested_in_class && f.name == bound_name) .filter(|f| signature_preserving_decorators(&f.decorators)) .collect(); - (!candidates.is_empty()).then(|| BoundMethod { + if candidates.is_empty() { + return None; + } + Some(BoundMethod { candidates, wrapper: attribute.rhs_descriptor.as_deref(), }) @@ -131,12 +134,9 @@ fn receiver_params_consumed( let spelled = |name: &str| wrapper == Some(name) || shared::decorator_spelled(&func.decorators, name); if spelled("staticmethod") { - 0 - } else if spelled("classmethod") || instance_access { - 1 - } else { - 0 + return 0; } + usize::from(spelled("classmethod") || instance_access) } /// The positional arguments a signature requires once `consumed` leading diff --git a/crates/basilisk-checker/src/types.rs b/crates/basilisk-checker/src/types.rs index 8ed745af..2ecbba8f 100644 --- a/crates/basilisk-checker/src/types.rs +++ b/crates/basilisk-checker/src/types.rs @@ -353,54 +353,7 @@ impl InferredType { // Implements [TYPEINF-SUBTYPING-CALLABLE] — return type covariant // (source return <: target return), parameters contravariant // (target param <: source param), `...`/empty params gradual. - (InferredType::Callable(a), InferredType::Callable(b)) => { - // Check return type compatibility (covariant - source return must be assignable to target return) - // Special case: if source return type is Unknown, we can't verify compatibility - // This happens with lambda expressions where we can't infer the return type - // We should be conservative and return false unless target return type is Any or Unknown - match (&*a.return_type, &*b.return_type) { - (InferredType::Unknown, _) - if !matches!( - &*b.return_type, - InferredType::Any | InferredType::Unknown - ) => - { - // Source has unknown return type, target has known return type - // This is unsafe - we don't know if they're compatible - return false; - } - _ => { - if !a.return_type.is_assignable_to(&b.return_type) { - return false; - } - } - } - - // Handle ellipsis/arbitrary parameters (empty param_types means `...`) - if a.param_types.is_empty() || b.param_types.is_empty() { - // If target accepts arbitrary parameters (`...`), any callable is assignable - // If source has arbitrary parameters, it can only be assigned to target with arbitrary parameters - // or if target has specific parameter types that match the source's capabilities - // For now, we allow if either has empty param_types (simplified) - return true; - } - - // Required parameter positions are contravariant. A source may - // require fewer parameters than the target because its trailing - // positions can be satisfied by defaults; it may not require more. - if a.param_types.len() > b.param_types.len() { - return false; - } - - // Check parameter type compatibility (contravariant - target param must be assignable to source param) - for (source_param, target_param) in a.param_types.iter().zip(b.param_types.iter()) { - if !target_param.is_assignable_to(source_param) { - return false; - } - } - - true - } + (InferredType::Callable(a), InferredType::Callable(b)) => callable_assignable(a, b), (a @ InferredType::Generator(..), b @ InferredType::Generator(..)) => { generator_assignable(a, b) } @@ -429,6 +382,42 @@ fn invariantly_assignable(left: &InferredType, right: &InferredType) -> bool { left.is_assignable_to(right) && right.is_assignable_to(left) } +/// Callable subtyping: returns covariant, parameters contravariant. +/// +/// Implements [TYPEINF-SUBTYPING-CALLABLE]. An `Unknown` source return (a +/// lambda whose body we could not infer) is only accepted against a gradual +/// target — claiming compatibility with a KNOWN target return would assert +/// something unverified. +fn callable_assignable(source: &CallableInfo, target: &CallableInfo) -> bool { + let target_return_is_gradual = matches!( + &*target.return_type, + InferredType::Any | InferredType::Unknown + ); + if matches!(&*source.return_type, InferredType::Unknown) && !target_return_is_gradual { + return false; + } + if !source.return_type.is_assignable_to(&target.return_type) { + return false; + } + callable_params_assignable(&source.param_types, &target.param_types) +} + +/// Parameter-list half of [TYPEINF-SUBTYPING-CALLABLE]. +/// +/// An empty list spells `...` (arbitrary parameters), which is gradual on +/// either side. A source may require FEWER positions than the target — its +/// trailing positions are satisfiable by defaults — but never more. +fn callable_params_assignable(source: &[InferredType], target: &[InferredType]) -> bool { + if source.is_empty() || target.is_empty() { + return true; + } + source.len() <= target.len() + && source + .iter() + .zip(target.iter()) + .all(|(source_param, target_param)| target_param.is_assignable_to(source_param)) +} + /// Generator yield/return positions are covariant; the value sent back into /// the suspended generator is contravariant. fn generator_assignable(left: &InferredType, right: &InferredType) -> bool { diff --git a/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs b/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs index 60a5cf4d..8343f42e 100644 --- a/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs +++ b/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs @@ -11,12 +11,16 @@ use super::common::*; type TestResult = Result<(), Box>; +/// One arity diagnostic reduced to what these tests pin: its code and the +/// `(start, end)` byte span it anchors at. +type ArityDiagnostic = (String, (u32, u32)); + /// A dataclass with one `int` field: `C(1, 2)` is one positional too many, /// which `dataclasses_kwonly`'s arity check reports on the bare statement. const CLASS: &str = "from dataclasses import dataclass\n\n@dataclass\nclass C:\n a: int\n"; /// The arity diagnostics drawn by `source`, as `(code, span)` pairs. -fn arity_spans(source: &str) -> Result, Box> { +fn arity_spans(source: &str) -> Result, Box> { let diags = run(source)?; Ok(diags .iter() diff --git a/crates/basilisk-resolver/src/visitor/class_info.rs b/crates/basilisk-resolver/src/visitor/class_info.rs index a7578abf..37d929e1 100644 --- a/crates/basilisk-resolver/src/visitor/class_info.rs +++ b/crates/basilisk-resolver/src/visitor/class_info.rs @@ -222,11 +222,11 @@ fn rhs_callable_binding(value: &Expr) -> (Option, Option) { } _ => return (None, None), }; - let wrapped = match call.arguments.args.as_ref() { + let bound = match call.arguments.args.as_ref() { [Expr::Name(inner)] => Some(inner.id.to_string()), _ => None, }; - (Some(wrapper), wrapped) + (Some(wrapper), bound) } _ => (None, None), } From ce4817f760640877f9e7c0e25787aae5d7669d9e Mon Sep 17 00:00:00 2001 From: Christian Findlay <16697547+MelbourneDeveloper@users.noreply.github.com> Date: Wed, 5 Aug 2026 06:18:45 +1000 Subject: [PATCH 21/45] Fixes --- .github/workflows/ci.yml | 68 +- Makefile | 7 + README-pypi.md | 6 +- README.md | 6 +- README.zh.md | 6 +- .../tests/basilisk/codelens_spec.lua | 119 + basilisk.nvim/tests/run_coverage.lua | 77 + benchmarks/results/coverage.tsv | 2 +- benchmarks/results/summary.md | 52 +- .../status/darwin-arm64-apple-m4-max.csv | 58 +- conformance/conformance_status.csv | 6 +- .../src/annotation/builtins.rs | 25 +- .../basilisk-checker/src/annotation/forms.rs | 52 +- crates/basilisk-checker/src/annotation/mod.rs | 20 +- crates/basilisk-checker/src/inference.rs | 3 +- crates/basilisk-checker/src/param_infer.rs | 4 +- .../src/rules/aliases_type_statement.rs | 82 +- .../assignment_compatibility/alias_match.rs | 31 +- .../src/rules/assignment_compatibility/mod.rs | 31 +- .../calls_argument_count/method_binding.rs | 9 +- .../src/rules/calls_argument_count/mod.rs | 55 +- crates/basilisk-checker/src/rules/mod.rs | 25 +- .../src/rules/narrowing_typeguard.rs | 29 +- .../src/rules/narrowing_typeis_2.rs | 48 +- .../src/rules/overloads_basic.rs | 17 +- .../src/rules/overloads_consistency.rs | 18 +- .../src/rules/overloads_consistency_2.rs | 17 +- .../src/rules/overloads_consistency_3.rs | 17 +- .../src/rules/overloads_definitions.rs | 20 +- .../src/rules/overloads_evaluation.rs | 17 +- .../protocols_definition_2/conformance.rs | 6 +- .../src/rules/redundant_annotation.rs | 26 +- .../src/rules/returns_compatibility.rs | 17 +- .../src/rules/returns_compatibility_2.rs | 17 +- crates/basilisk-checker/src/rules/shared.rs | 5 +- crates/basilisk-checker/src/types.rs | 109 +- crates/basilisk-checker/src/types_parsing.rs | 10 +- .../calls_expression_position_tests.rs | 6 +- .../checker/narrowing_typeguard_tests.rs | 4 +- .../tests/checker/narrowing_typeis_2_tests.rs | 3 +- .../tests/mutation_kill_constructors_tests.rs | 208 + crates/basilisk-lsp/src/semantic_tokens.rs | 14 +- .../CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md | 102 +- docs/readme/README.src.md | 6 +- docs/readme/README.zh.src.md | 6 +- docs/specs/CHECKER-ARCHITECTURE-SPEC.md | 29 +- docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md | 54 +- mutation_testing/mutants_report.html | 3436 ++++++++++------- mutation_testing/mutation_scores.json | 6 +- scripts/test-nvim.sh | 41 +- vscode-extension/README.md | 6 +- vscode-extension/README.zh.md | 6 +- vscode-extension/VSCODE-DEPENDENCY-LICENSES | 4 +- website/src/_data/conformance_report.json | 5 +- 54 files changed, 3337 insertions(+), 1716 deletions(-) create mode 100644 basilisk.nvim/tests/basilisk/codelens_spec.lua create mode 100644 crates/basilisk-checker/tests/mutation_kill_constructors_tests.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0d7c65e9..c29c2ff9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -67,6 +67,7 @@ jobs: zed: ${{ steps.classify.outputs.zed }} code: ${{ steps.classify.outputs.code }} website: ${{ steps.classify.outputs.website }} + bench: ${{ steps.classify.outputs.bench }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -92,6 +93,7 @@ jobs: echo "zed=false" echo "code=false" echo "website=false" + echo "bench=false" } >> "$GITHUB_OUTPUT" echo "Dependabot PR — skipping Rust/extension matrix and website build." exit 0 @@ -104,8 +106,16 @@ jobs: nvim=false zed=false website=false + benchtool=false while IFS= read -r f; do [ -z "$f" ] && continue + # The benchmark ratchet defends the CHECKER's speed, so it re-runs on + # any core change — but the harness that measures it (fixtures, + # run.sh, summarize.py, the baseline CSVs) is not core Rust and would + # otherwise change the gate without ever running it. + case "$f" in + benchmarks/*) benchtool=true ;; + esac # `website` gates the site build: only files the published site is # actually built from (templates/assets + the benchmark CSVs it reads). case "$f" in @@ -160,6 +170,10 @@ jobs: [ "$nvim" = true ] || [ "$zed" = true ]; then code=true fi + bench=false + if [ "$core" = true ] || [ "$benchtool" = true ]; then + bench=true + fi { echo "core=$core" echo "vscode=$vscode" @@ -167,8 +181,9 @@ jobs: echo "zed=$zed" echo "code=$code" echo "website=$website" + echo "bench=$bench" } >> "$GITHUB_OUTPUT" - echo "Scope — core:$core vscode:$vscode nvim:$nvim zed:$zed code:$code website:$website" + echo "Scope — core:$core vscode:$vscode nvim:$nvim zed:$zed code:$code website:$website bench:$bench" # ── Website build check (only when site/benchmark files change) ───────────── # Mirrors deploy-pages.yml's build so a broken template/data file is caught @@ -985,6 +1000,57 @@ jobs: - name: Build Rust (release) run: cargo build --release + # ── Benchmark ratchet ([CHKARCH-TESTING-BENCH-RATCHET]) ──────────────────── + # Performance is a feature, and the conformance and benchmark ratchets must + # hold SIMULTANEOUSLY: a conformance fix that blows this gate is not done. Both + # halves of benchmarks/run.sh apply here exactly as they do locally — + # WRITE-ALWAYS: every measured number lands in benchmarks/status/.csv; + # GATE-SEPARATELY: summarize.py then compares this run's basilisk times + # against the COMMITTED baseline (read from git, never the working copy) and + # exits 3 on any fixture that got slower. The gate cannot be disabled or + # widened — run.sh REJECTS BENCH_NO_GATE/BENCH_REGRESS_PCT/BENCH_TOLERANCE_PCT + # and refuses the basilisk-only iteration mode when GITHUB_ACTIONS is set. + # Runner is pinned to the standard ubuntu-24.04 image on purpose: the machine + # slug (gha-linux-x64) is derived from RUNNER_OS/RUNNER_ARCH, so letting this + # job drift onto BIG_RUNNER would compare times from different hardware under + # one baseline. Per the script's own rule, a machine with no committed baseline + # establishes one instead of failing, so the gate goes live for the GH runner + # once a green run's CSV is committed. + bench: + name: Benchmark Ratchet + needs: changes + if: needs.changes.outputs.bench == 'true' + runs-on: ubuntu-24.04 + # run.sh does a full `cargo clean` + release rebuild (the benchmark refuses + # to time a stale binary), pulls the five competitors, then runs hyperfine + # over every fixture with an auto-remeasure on unstable samples. + timeout-minutes: 60 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + + # No rust-cache: run.sh `cargo clean`s before building, so a restored + # target dir would be deleted anyway — caching it would only cost upload. + + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.12" + + - name: Install lld + run: sudo apt-get update && sudo apt-get install -y lld + + # hyperfine is the only hard prerequisite besides cargo; the five + # competitors are pulled by run.sh itself (latest official release each + # run) and any that fail to install are skipped with a loud warning. + - name: Install hyperfine + uses: taiki-e/install-action@81ee9698f20724138a785d788c7567d40f14cd2d # hyperfine + with: + tool: hyperfine + + - name: Benchmark and enforce the regression gate + run: make bench + # ── Dependency review ([GITHUB-DEP-REVIEW]) ──────────────────────────────── # Blocks PRs that introduce dependencies with known-high vulnerabilities. This # is the repo's ONLY dependency vuln-gate — there is no cargo-deny/osv gate, so diff --git a/Makefile b/Makefile index c1c187ca..d911e2bb 100644 --- a/Makefile +++ b/Makefile @@ -39,6 +39,12 @@ PKG ?= basilisk-checker # new tests just for mutation. Slow/E2E-ish binaries are deliberately omitted so # the per-mutant test run stays cheap. # +# The one class of NEW binary that belongs here is a `#[mutation_safe]` suite +# WIDENING the examined scope ([CHKARCH-TESTING-MUTATION-RATCHET]): those tests +# assert real rule behaviour first and would earn their place with the ratchet +# switched off — they are listed so the functions they newly bring in-scope are +# actually exercised, not scored as missed. +# # Order matters, but only a little. `cargo test` stops at the first failing # binary, so a mutant dies as soon as a binary that kills it runs; # `mutation_kill_tests` exists to kill these mutants, so it runs first. Measured @@ -47,6 +53,7 @@ PKG ?= basilisk-checker # what actually did ([CHKARCH-TESTING-MUTATION-RATCHET]). _CHECKER_MUTATION_TESTS := \ --test mutation_kill_tests \ + --test mutation_kill_constructors_tests \ --test coverage_boost_tests \ --test coverage_boost_32_tests \ --test coverage_boost_33_tests \ diff --git a/README-pypi.md b/README-pypi.md index 8dce27a8..bbb98239 100644 --- a/README-pypi.md +++ b/README-pypi.md @@ -50,11 +50,11 @@ And it is the **fastest checker we’ve measured** — median cold full- | Type checker | Median cold check | | --- | --- | | ⚡ **Basilisk** | **11 ms** | -| zuban | 28 ms | +| zuban | 27 ms | | ty | 39 ms | | Pyrefly | 110 ms | -| Pyright | 563 ms | -| mypy | 583 ms | +| Pyright | 572 ms | +| mypy | 586 ms | Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~5 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) diff --git a/README.md b/README.md index 6f9aa372..b710a2ef 100644 --- a/README.md +++ b/README.md @@ -50,11 +50,11 @@ And it is the **fastest checker we’ve measured** — median cold full- | Type checker | Median cold check | | --- | --- | | ⚡ **Basilisk** | **11 ms** | -| zuban | 28 ms | +| zuban | 27 ms | | ty | 39 ms | | Pyrefly | 110 ms | -| Pyright | 563 ms | -| mypy | 583 ms | +| Pyright | 572 ms | +| mypy | 586 ms | Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~5 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) diff --git a/README.zh.md b/README.zh.md index cc8fc45c..1664d759 100644 --- a/README.zh.md +++ b/README.zh.md @@ -51,11 +51,11 @@ Basilisk 是**唯一**在官方 | 类型检查器 | 冷检查中位数 | | --- | --- | | ⚡ **Basilisk** | **11 ms** | -| zuban | 28 ms | +| zuban | 27 ms | | ty | 39 ms | | Pyrefly | 110 ms | -| Pyright | 563 ms | -| mypy | 583 ms | +| Pyright | 572 ms | +| mypy | 586 ms | 在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 5 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) diff --git a/basilisk.nvim/tests/basilisk/codelens_spec.lua b/basilisk.nvim/tests/basilisk/codelens_spec.lua new file mode 100644 index 00000000..e7adfbc6 --- /dev/null +++ b/basilisk.nvim/tests/basilisk/codelens_spec.lua @@ -0,0 +1,119 @@ +--- Tests for basilisk.codelens module. +--- +--- Pins [NVIM-LSP-CLIENT-CONFIGURATION-API-MAPPINGS] (Code Lens row): the +--- plugin must activate code lens through `vim.lsp.codelens.enable` whenever the +--- runtime exposes it (Neovim 0.12+, which installs its own debounced refresh), +--- and fall back to `refresh()` plus a manual BufEnter/InsertLeave loop only on +--- 0.10/0.11 — `refresh()` is deprecated on 0.12 and removed on 0.13, so calling +--- it on a modern runtime is a deprecation warning today and a break tomorrow. +--- +--- Both branches are exercised on ONE Neovim by swapping the `vim.lsp.codelens` +--- table, so the version the tests happen to run on never decides which half of +--- the contract is checked. + +describe("basilisk.codelens", function() + local codelens = require("basilisk.codelens") + + local original + local calls + + before_each(function() + original = vim.lsp.codelens + calls = { enable = {}, refresh = {} } + end) + + after_each(function() + vim.lsp.codelens = original + end) + + --- Install a stub `vim.lsp.codelens` recording its calls. `with_enable` + --- decides whether the modern API appears to exist. + local function stub_codelens(with_enable) + local stub = { + refresh = function(opts) + table.insert(calls.refresh, opts) + end, + } + if with_enable then + stub.enable = function(on, opts) + table.insert(calls.enable, { on = on, opts = opts }) + end + end + vim.lsp.codelens = stub + end + + describe("activate on a runtime with vim.lsp.codelens.enable", function() + it("enables code lens for the buffer and never calls the deprecated refresh", function() + local bufnr = vim.api.nvim_create_buf(false, true) + stub_codelens(true) + + codelens.activate(bufnr) + + assert.equals(1, #calls.enable, "must enable code lens exactly once") + assert.is_true(calls.enable[1].on, "must enable, not disable") + assert.equals(bufnr, calls.enable[1].opts.bufnr, "must target the given buffer") + assert.equals(0, #calls.refresh, "refresh() is deprecated on 0.12+ and must not be called") + + vim.api.nvim_buf_delete(bufnr, { force = true }) + end) + + it("registers no refresh autocmds — the API installs its own", function() + local bufnr = vim.api.nvim_create_buf(false, true) + stub_codelens(true) + + codelens.activate(bufnr) + local autocmds = vim.api.nvim_get_autocmds({ + event = { "BufEnter", "InsertLeave" }, + buffer = bufnr, + }) + + assert.equals(0, #autocmds, "duplicating the built-in refresh loop would double-request lenses") + + vim.api.nvim_buf_delete(bufnr, { force = true }) + end) + end) + + describe("activate on a runtime without vim.lsp.codelens.enable", function() + it("refreshes immediately for the buffer", function() + local bufnr = vim.api.nvim_create_buf(false, true) + stub_codelens(false) + + codelens.activate(bufnr) + + assert.is_true(#calls.refresh >= 1, "0.10/0.11 must get an initial refresh") + assert.equals(bufnr, calls.refresh[1].bufnr, "must refresh the given buffer") + + vim.api.nvim_buf_delete(bufnr, { force = true }) + end) + + it("keeps lenses current by refreshing on BufEnter and InsertLeave", function() + local bufnr = vim.api.nvim_create_buf(false, true) + stub_codelens(false) + + codelens.activate(bufnr) + local before = #calls.refresh + vim.api.nvim_exec_autocmds("BufEnter", { buffer = bufnr }) + vim.api.nvim_exec_autocmds("InsertLeave", { buffer = bufnr }) + + assert.equals(before + 2, #calls.refresh, "both events must re-request lenses") + assert.equals(bufnr, calls.refresh[#calls.refresh].bufnr, "every refresh stays buffer-scoped") + + vim.api.nvim_buf_delete(bufnr, { force = true }) + end) + + it("scopes its autocmds to the buffer it was given", function() + local bufnr = vim.api.nvim_create_buf(false, true) + local other = vim.api.nvim_create_buf(false, true) + stub_codelens(false) + + codelens.activate(bufnr) + local before = #calls.refresh + vim.api.nvim_exec_autocmds("BufEnter", { buffer = other }) + + assert.equals(before, #calls.refresh, "another buffer's events must not refresh this one") + + vim.api.nvim_buf_delete(bufnr, { force = true }) + vim.api.nvim_buf_delete(other, { force = true }) + end) + end) +end) diff --git a/basilisk.nvim/tests/run_coverage.lua b/basilisk.nvim/tests/run_coverage.lua index 14a79a62..8951eb18 100644 --- a/basilisk.nvim/tests/run_coverage.lua +++ b/basilisk.nvim/tests/run_coverage.lua @@ -66,6 +66,12 @@ assert(#config_mod.validate(config_mod.resolve({ log_level = "verbose" })) == 1) -- 2. binary.lua — all resolution paths -- ============================================================ print("--- binary.lua ---") +-- is_executable: the public guard `lsp.start` consults before resolving, over +-- every shape a configured `binary_path` can take. +assert(binary_mod.is_executable(nil) == false) +assert(binary_mod.is_executable("") == false) +assert(binary_mod.is_executable("/nonexistent/basilisk") == false) +assert(binary_mod.is_executable(42) == false) -- configured path: nil, empty, nonexistent, valid binary_mod.resolve(nil) binary_mod.resolve("") @@ -73,6 +79,7 @@ binary_mod.resolve("/nonexistent/basilisk") local ls_path = vim.fn.exepath("ls") if ls_path ~= "" then binary_mod.resolve(ls_path) + assert(binary_mod.is_executable(ls_path) == true) end -- env var: nil, empty, valid, invalid local orig_env = vim.env.BASILISK_PATH @@ -236,6 +243,35 @@ end -- Force restart resets lsp_mod.restart(config_mod.resolve(), true) +-- ============================================================ +-- 5b. codelens.lua — both activation paths on one runtime +-- ============================================================ +-- Implements [NVIM-LSP-CLIENT-CONFIGURATION-API-MAPPINGS] (Code Lens row). +-- Which branch `activate` takes is decided by the Neovim it runs on, so the +-- version under test would otherwise dictate which half of the contract is ever +-- executed. Swapping `vim.lsp.codelens` drives BOTH: the 0.12+ `enable` API and +-- the 0.10/0.11 `refresh` fallback with its manual BufEnter/InsertLeave loop. +print("--- codelens.lua ---") +local codelens = require("basilisk.codelens") +local real_codelens = vim.lsp.codelens +local lens_buf = vim.api.nvim_create_buf(false, true) + +-- Modern runtime: enable() exists and owns its own refresh scheduling. +vim.lsp.codelens = { + enable = function(_, _) end, + refresh = function(_) end, +} +codelens.activate(lens_buf) + +-- Legacy runtime: no enable(), so activate() refreshes now and on each event. +vim.lsp.codelens = { refresh = function(_) end } +codelens.activate(lens_buf) +vim.api.nvim_exec_autocmds("BufEnter", { buffer = lens_buf }) +vim.api.nvim_exec_autocmds("InsertLeave", { buffer = lens_buf }) + +vim.lsp.codelens = real_codelens +vim.api.nvim_buf_delete(lens_buf, { force = true }) + -- ============================================================ -- 6. memory.lua — complete_refs, display, LSP calls -- ============================================================ @@ -608,6 +644,47 @@ if lsp_binary then local status_text = sl.get() sl.get_color() + -- Server-notification handlers on a REAL attached client. `install_handlers` + -- is the public seam that re-installs them after an external + -- `vim.lsp.config` (as this exerciser and any user config do), and nothing + -- else in the suite called it — so `window/logMessage`, + -- `window/showMessage` and `workspace/applyEdit` were never dispatched + -- through the plugin's own handlers. Drive each one the way the server + -- does, including the message levels that pick different log routes and + -- the applyEdit shapes ([CONFIGEDITOR-SOURCES]: `changes` vs + -- `documentChanges`, and a non-config document that must NOT be persisted). + lsp_mod.install_handlers() + local handlers = lsp_client.handlers or {} + local function dispatch(method, params) + local handler = handlers[method] + if handler then + pcall(handler, nil, params, { method = method, client_id = lsp_client.id }) + end + end + for _, level in ipairs({ 1, 2, 3, 4 }) do + dispatch("window/logMessage", { type = level, message = "Basilisk: level " .. level }) + dispatch("window/showMessage", { type = level, message = "Basilisk: shown " .. level }) + end + -- Degenerate payloads: absent, empty and non-string messages are ignored. + dispatch("window/logMessage", nil) + dispatch("window/logMessage", { type = 3, message = "" }) + dispatch("window/showMessage", { type = 3, message = 42 }) + local edited_uri = vim.uri_from_fname(lsp_tmpdir .. "/pyproject.toml") + dispatch("workspace/applyEdit", { + edit = { changes = { [edited_uri] = {} } }, + }) + dispatch("workspace/applyEdit", { + edit = { + documentChanges = { + { textDocument = { uri = edited_uri, version = 1 }, edits = {} }, + { kind = "create", uri = vim.uri_from_fname(lsp_tmpdir .. "/created.py") }, + }, + }, + }) + dispatch("workspace/applyEdit", { edit = { changes = { [vim.uri_from_bufnr(lsp_buf)] = {} } } }) + dispatch("workspace/applyEdit", { edit = "not a table" }) + wait(200) + -- Execute commands with real LSP client. pcall(vim.cmd, "BasiliskOrganizeImports") pcall(vim.cmd, "BasiliskFixFile") diff --git a/benchmarks/results/coverage.tsv b/benchmarks/results/coverage.tsv index 9de11f17..5079c8a8 100644 --- a/benchmarks/results/coverage.tsv +++ b/benchmarks/results/coverage.tsv @@ -139,7 +139,7 @@ dict_key_hashability basilisk 1 2000 enums_member_values basilisk 1 480 final_reassignment basilisk 1 500 generics_defaults_specialization basilisk 1 560 -literals_semantics basilisk 1 576 +literals_semantics basilisk 1 1008 match_exhaustiveness basilisk 1 500 narrowing_typeis basilisk 1 520 newtype_definition basilisk 1 2000 diff --git a/benchmarks/results/summary.md b/benchmarks/results/summary.md index b1178e03..f6b13059 100644 --- a/benchmarks/results/summary.md +++ b/benchmarks/results/summary.md @@ -5,29 +5,29 @@ Machine: `Apple M4 Max` | fixture | basilisk | basilisk-warm | pyright | mypy | mypy-warm | ty | pyrefly | zuban | |---|---|---|---|---|---|---|---|---| -| aliases_type_statement | 9.2 ms | 4.9 ms | 547.1 ms | 610.0 ms | 161.0 ms | 63.9 ms | 112.3 ms | 28.8 ms | -| assignment_compatibility | 8.5 ms | 5.5 ms | 585.4 ms | 583.5 ms | 164.7 ms | 52.2 ms | 113.4 ms | 30.6 ms | -| call_argument_types | 13.6 ms | 4.3 ms | 642.7 ms | 611.6 ms | 163.7 ms | 56.1 ms | 114.3 ms | 48.4 ms | -| callables_subtyping | 12.6 ms | 4.4 ms | 522.1 ms | 571.4 ms | 164.2 ms | 39.3 ms | 109.7 ms | 29.1 ms | -| classvar_scoping | 15.3 ms | 5.9 ms | 599.6 ms | 614.3 ms | 163.3 ms | 58.8 ms | 134.7 ms | 32.4 ms | -| constructors_call_init | 9.0 ms | 4.1 ms | 592.2 ms | 596.6 ms | 162.6 ms | 38.8 ms | 103.8 ms | 26.6 ms | -| dataclasses_usage | 9.4 ms | 4.0 ms | 1559.4 ms | 642.0 ms | 164.7 ms | 61.8 ms | 176.1 ms | 56.6 ms | -| dict_key_hashability | 11.8 ms | 8.0 ms | 518.9 ms | 613.3 ms | 160.7 ms | 39.2 ms | 103.9 ms | 31.9 ms | -| enums_member_values | 8.2 ms | 4.4 ms | 564.1 ms | 576.0 ms | 160.9 ms | 42.0 ms | 103.8 ms | 26.7 ms | -| final_reassignment | 7.1 ms | 4.1 ms | 456.9 ms | 562.5 ms | 167.2 ms | 28.9 ms | 100.6 ms | 24.4 ms | -| generics_defaults_specialization | 10.0 ms | 4.3 ms | 549.6 ms | 579.0 ms | 162.1 ms | 35.0 ms | 104.7 ms | 27.4 ms | -| literals_semantics | 12.5 ms | 4.4 ms | 518.2 ms | 577.6 ms | 162.5 ms | 32.5 ms | 104.5 ms | 27.0 ms | -| match_exhaustiveness | 11.0 ms | 4.2 ms | 521.6 ms | 600.0 ms | 163.2 ms | 36.7 ms | 111.4 ms | 27.4 ms | -| narrowing_typeis | 9.4 ms | 4.2 ms | 539.3 ms | 582.8 ms | 160.2 ms | 34.5 ms | 104.9 ms | 26.4 ms | -| newtype_definition | 10.4 ms | 5.4 ms | 715.1 ms | 628.9 ms | 164.4 ms | 25.1 ms | 118.3 ms | 35.8 ms | -| overloads_evaluation | 12.9 ms | 4.6 ms | 591.8 ms | 627.4 ms | 163.9 ms | 60.2 ms | 119.9 ms | 34.2 ms | -| override_compatibility | 14.2 ms | 5.0 ms | 635.9 ms | 598.1 ms | 164.0 ms | 42.0 ms | 111.2 ms | 28.2 ms | -| protocols_definition | 10.1 ms | 5.5 ms | 562.6 ms | 580.4 ms | 163.1 ms | 35.5 ms | 103.7 ms | 27.5 ms | -| returns_compatibility | 8.1 ms | 5.6 ms | 488.7 ms | 572.5 ms | 162.5 ms | 33.0 ms | 101.9 ms | 24.5 ms | -| tuples_index | 10.5 ms | 5.4 ms | 549.3 ms | 566.6 ms | 162.1 ms | 35.0 ms | 106.4 ms | 25.8 ms | -| typeddict_key_access | 10.6 ms | 4.4 ms | 610.2 ms | 582.1 ms | 162.0 ms | 37.4 ms | 107.3 ms | 26.6 ms | -| typeddict_readonly_inheritance | 15.1 ms | 3.6 ms | 653.8 ms | 579.7 ms | 165.6 ms | 38.7 ms | 114.4 ms | 25.9 ms | -| typeddict_readonly_mutation | 9.9 ms | 4.3 ms | 613.3 ms | 579.8 ms | 163.3 ms | 42.7 ms | 107.9 ms | 26.0 ms | -| typevar_constraints | 17.2 ms | 5.5 ms | 720.8 ms | 577.9 ms | 165.2 ms | 42.3 ms | 113.6 ms | 34.1 ms | -| undefined_names | 15.4 ms | 5.1 ms | 487.5 ms | 631.7 ms | 168.3 ms | 51.2 ms | 544.6 ms | 34.4 ms | -| unresolved_imports | 12.9 ms | 5.1 ms | 455.6 ms | 710.6 ms | 167.7 ms | 284.5 ms | 897.7 ms | 294.6 ms | +| aliases_type_statement | 9.5 ms | 4.6 ms | 545.8 ms | 612.2 ms | 163.5 ms | 64.4 ms | 112.5 ms | 28.0 ms | +| assignment_compatibility | 10.1 ms | 5.3 ms | 594.8 ms | 584.5 ms | 167.1 ms | 52.2 ms | 114.1 ms | 30.5 ms | +| call_argument_types | 14.9 ms | 4.6 ms | 642.6 ms | 609.1 ms | 165.2 ms | 56.3 ms | 116.8 ms | 48.4 ms | +| callables_subtyping | 13.3 ms | 4.9 ms | 522.0 ms | 580.4 ms | 164.9 ms | 38.5 ms | 107.8 ms | 27.9 ms | +| classvar_scoping | 15.9 ms | 5.6 ms | 606.0 ms | 616.2 ms | 166.0 ms | 58.0 ms | 134.1 ms | 32.5 ms | +| constructors_call_init | 9.8 ms | 4.3 ms | 610.7 ms | 593.4 ms | 165.0 ms | 39.7 ms | 106.1 ms | 26.7 ms | +| dataclasses_usage | 9.9 ms | 4.4 ms | 1570.7 ms | 650.4 ms | 166.0 ms | 65.2 ms | 178.4 ms | 57.3 ms | +| dict_key_hashability | 12.8 ms | 5.2 ms | 521.0 ms | 616.7 ms | 164.8 ms | 38.4 ms | 103.0 ms | 30.9 ms | +| enums_member_values | 8.4 ms | 4.3 ms | 566.4 ms | 575.3 ms | 164.3 ms | 41.9 ms | 104.7 ms | 25.9 ms | +| final_reassignment | 7.7 ms | 4.2 ms | 459.8 ms | 568.0 ms | 163.6 ms | 28.8 ms | 100.8 ms | 23.8 ms | +| generics_defaults_specialization | 10.7 ms | 4.6 ms | 549.9 ms | 583.3 ms | 165.2 ms | 35.0 ms | 105.6 ms | 25.9 ms | +| literals_semantics | 13.8 ms | 4.9 ms | 525.8 ms | 579.1 ms | 167.6 ms | 33.2 ms | 106.4 ms | 27.0 ms | +| match_exhaustiveness | 12.1 ms | 4.5 ms | 516.6 ms | 605.8 ms | 163.4 ms | 37.2 ms | 110.0 ms | 27.0 ms | +| narrowing_typeis | 10.8 ms | 4.5 ms | 540.6 ms | 583.2 ms | 166.8 ms | 35.8 ms | 105.8 ms | 25.8 ms | +| newtype_definition | 11.0 ms | 5.6 ms | 715.7 ms | 625.7 ms | 168.0 ms | 24.3 ms | 122.5 ms | 36.3 ms | +| overloads_evaluation | 13.6 ms | 4.2 ms | 590.5 ms | 621.8 ms | 164.7 ms | 60.7 ms | 118.4 ms | 34.7 ms | +| override_compatibility | 15.7 ms | 5.2 ms | 636.3 ms | 605.3 ms | 164.7 ms | 41.0 ms | 110.5 ms | 28.5 ms | +| protocols_definition | 10.2 ms | 4.5 ms | 577.3 ms | 580.3 ms | 168.1 ms | 35.9 ms | 103.9 ms | 27.0 ms | +| returns_compatibility | 7.8 ms | 4.7 ms | 494.5 ms | 573.6 ms | 164.8 ms | 32.4 ms | 102.1 ms | 24.9 ms | +| tuples_index | 9.9 ms | 4.5 ms | 549.0 ms | 575.5 ms | 165.7 ms | 34.1 ms | 103.4 ms | 25.2 ms | +| typeddict_key_access | 10.4 ms | 4.3 ms | 611.6 ms | 581.0 ms | 164.7 ms | 38.2 ms | 109.5 ms | 25.6 ms | +| typeddict_readonly_inheritance | 15.8 ms | 4.3 ms | 658.8 ms | 579.8 ms | 164.9 ms | 38.2 ms | 114.8 ms | 26.2 ms | +| typeddict_readonly_mutation | 11.1 ms | 4.6 ms | 614.5 ms | 585.1 ms | 165.1 ms | 42.9 ms | 109.9 ms | 26.9 ms | +| typevar_constraints | 17.9 ms | 5.8 ms | 775.1 ms | 586.5 ms | 168.6 ms | 41.3 ms | 114.1 ms | 33.0 ms | +| undefined_names | 16.5 ms | 5.6 ms | 485.5 ms | 636.1 ms | 168.6 ms | 51.7 ms | 554.7 ms | 35.5 ms | +| unresolved_imports | 13.9 ms | 5.4 ms | 459.8 ms | 681.9 ms | 169.3 ms | 281.5 ms | 917.9 ms | 306.0 ms | diff --git a/benchmarks/status/darwin-arm64-apple-m4-max.csv b/benchmarks/status/darwin-arm64-apple-m4-max.csv index b4448b5a..caae821f 100644 --- a/benchmarks/status/darwin-arm64-apple-m4-max.csv +++ b/benchmarks/status/darwin-arm64-apple-m4-max.csv @@ -3,35 +3,35 @@ # arch: arm64 # os: Darwin 25.5.0 # cores: 14 -# tools: basilisk=basilisk 0.0.0-dev+gf285ce2e, pyright=pyright 1.1.408, mypy=mypy 1.19.1 (compiled: yes), ty=ty 0.0.19 (ae10022c2 2026-02-26), pyrefly=pyrefly 0.54.0, zuban=zuban 0.9.0 +# tools: basilisk=basilisk 0.0.0-dev+gc902cc6-dirty, pyright=pyright 1.1.408, mypy=mypy 1.19.1 (compiled: yes), ty=ty 0.0.19 (ae10022c2 2026-02-26), pyrefly=pyrefly 0.54.0, zuban=zuban 0.9.0 # runs: 10 minimum; noisy Basilisk CV > 15% is remeasured with at least 30 runs (hyperfine mean wall-clock, milliseconds) -# generated: 2026-08-02T20:11:56+1000 -# measured: basilisk, basilisk-warm — timed by this run. pyright, mypy, mypy-warm, ty, pyrefly, zuban were NOT re-timed; their _ms and _diags cells and version strings are carried forward verbatim from the previous run (2026-08-02T10:10:38+1000) on this machine. +# generated: 2026-08-05T03:51:03+1000 +# measured: basilisk, basilisk-warm — timed by this run. pyright, mypy, mypy-warm, ty, pyrefly, zuban were NOT re-timed; their _ms and _diags cells and version strings are carried forward verbatim from the previous run (2026-08-05T02:49:34+1000) on this machine. # note: _ms = COLD full-file CLI check from scratch (whole process: startup + stubs + analysis). _diags = error diagnostics the tool reported on that fixture in the measured configuration (error severity only; warnings/notes are not counted) — read every time next to its diags; a tool that reports 0 analyzed the file but flagged no errors there. A blank _ms cell means the tool either was not installed on this machine or failed to analyze that fixture (exit >= 2, e.g. parse abort) and was excluded rather than timed as a crash. Competitor versions are the LATEST official release pulled at the top of every run, so their columns always reflect current upstream, never a pinned build. Only basilisk and mypy have a -warm column (they keep a real cross-run cache): basilisk-warm = --cache result-cache hit; mypy-warm = incremental .mypy_cache hit (cold mypy = --no-incremental). pyright/ty/pyrefly keep NO cross-run result cache (a repeat run = cold), so they are measured cold-only. zuban is also cold-only but its mypy mode DOES reuse a ./.mypy_cache when present (no flag disables it), so we wipe ./.mypy_cache before every timed run to keep the measurement cold. mypy runs with --strict so it performs the strict-mode analysis the fixtures stress (plain mypy reports 'no issues' on the strictness fixtures); zuban runs as `zuban mypy --strict` for the same reason (its default `zuban check` mode skips these strictness rules). This file is ALWAYS rewritten with the latest measured numbers, even on a regression — the CI gate reads the committed baseline, never this working copy, so a slip is recorded here AND fails CI rather than being hidden. fixture,basilisk_ms,basilisk-warm_ms,pyright_ms,mypy_ms,mypy-warm_ms,ty_ms,pyrefly_ms,zuban_ms,basilisk_diags,pyright_diags,mypy_diags,ty_diags,pyrefly_diags,zuban_diags -aliases_type_statement,9.2,4.9,547.1,610.0,161.0,63.9,112.3,28.8,600,850,650,1850,700,600 -assignment_compatibility,8.5,5.5,585.4,583.5,164.7,52.2,113.4,30.6,2000,2000,2000,2000,2000,2000 -call_argument_types,13.6,4.3,642.7,611.6,163.7,56.1,114.3,48.4,998,998,1002,998,998,1000 -callables_subtyping,12.6,4.4,522.1,571.4,164.2,39.3,109.7,29.1,600,600,600,600,600,600 -classvar_scoping,15.3,5.9,599.6,614.3,163.3,58.8,134.7,32.4,2000,2000,2000,2000,4000,2000 -constructors_call_init,9.0,4.1,592.2,596.6,162.6,38.8,103.8,26.6,444,370,296,370,444,518 -dataclasses_usage,9.4,4.0,1559.4,642.0,164.7,61.8,176.1,56.6,500,500,500,500,500,500 -dict_key_hashability,11.8,8.0,518.9,613.3,160.7,39.2,103.9,31.9,2000,2000,0,0,0,0 -enums_member_values,8.2,4.4,564.1,576.0,160.9,42.0,103.8,26.7,480,480,80,480,480,480 -final_reassignment,7.1,4.1,456.9,562.5,167.2,28.9,100.6,24.4,500,500,500,500,500,500 -generics_defaults_specialization,10.0,4.3,549.6,579.0,162.1,35.0,104.7,27.4,560,560,560,421,560,560 -literals_semantics,12.5,4.4,518.2,577.6,162.5,32.5,104.5,27.0,576,576,576,576,576,576 -match_exhaustiveness,11.0,4.2,521.6,600.0,163.2,36.7,111.4,27.4,500,0,0,500,0,0 -narrowing_typeis,9.4,4.2,539.3,582.8,160.2,34.5,104.9,26.4,520,520,520,520,520,520 -newtype_definition,10.4,5.4,715.1,628.9,164.4,25.1,118.3,35.8,2000,2000,2000,0,2000,2000 -overloads_evaluation,12.9,4.6,591.8,627.4,163.9,60.2,119.9,34.2,600,1401,801,600,600,801 -override_compatibility,14.2,5.0,635.9,598.1,164.0,42.0,111.2,28.2,200,200,300,1,200,300 -protocols_definition,10.1,5.5,562.6,580.4,163.1,35.5,103.7,27.5,536,402,402,335,402,402 -returns_compatibility,8.1,5.6,488.7,572.5,162.5,33.0,101.9,24.5,1080,540,540,540,540,540 -tuples_index,10.5,5.4,549.3,566.6,162.1,35.0,106.4,25.8,600,600,600,1800,600,600 -typeddict_key_access,10.6,4.4,610.2,582.1,162.0,37.4,107.3,26.6,500,500,500,500,500,500 -typeddict_readonly_inheritance,15.1,3.6,653.8,579.7,165.6,38.7,114.4,25.9,500,500,500,2,500,500 -typeddict_readonly_mutation,9.9,4.3,613.3,579.8,163.3,42.7,107.9,26.0,500,500,500,500,500,500 -typevar_constraints,17.2,5.5,720.8,577.9,165.2,42.3,113.6,34.1,2000,2000,2000,2000,2000,2000 -undefined_names,15.4,5.1,487.5,631.7,168.3,51.2,544.6,34.4,2000,2000,4000,2000,2000,4000 -unresolved_imports,12.9,5.1,455.6,710.6,167.7,284.5,897.7,294.6,2000,2000,2000,2000,2000,2000 +aliases_type_statement,9.5,4.6,545.8,612.2,163.5,64.4,112.5,28.0,600,850,650,1850,700,600 +assignment_compatibility,10.1,5.3,594.8,584.5,167.1,52.2,114.1,30.5,2000,2000,2000,2000,2000,2000 +call_argument_types,14.9,4.6,642.6,609.1,165.2,56.3,116.8,48.4,998,998,1002,998,998,1000 +callables_subtyping,13.3,4.9,522.0,580.4,164.9,38.5,107.8,27.9,600,600,600,600,600,600 +classvar_scoping,15.9,5.6,606.0,616.2,166.0,58.0,134.1,32.5,2000,2000,2000,2000,4000,2000 +constructors_call_init,9.8,4.3,610.7,593.4,165.0,39.7,106.1,26.7,444,370,296,370,444,518 +dataclasses_usage,9.9,4.4,1570.7,650.4,166.0,65.2,178.4,57.3,500,500,500,500,500,500 +dict_key_hashability,12.8,5.2,521.0,616.7,164.8,38.4,103.0,30.9,2000,2000,0,0,0,0 +enums_member_values,8.4,4.3,566.4,575.3,164.3,41.9,104.7,25.9,480,480,80,480,480,480 +final_reassignment,7.7,4.2,459.8,568.0,163.6,28.8,100.8,23.8,500,500,500,500,500,500 +generics_defaults_specialization,10.7,4.6,549.9,583.3,165.2,35.0,105.6,25.9,560,560,560,421,560,560 +literals_semantics,13.8,4.9,525.8,579.1,167.6,33.2,106.4,27.0,1008,576,576,576,576,576 +match_exhaustiveness,12.1,4.5,516.6,605.8,163.4,37.2,110.0,27.0,500,0,0,500,0,0 +narrowing_typeis,10.8,4.5,540.6,583.2,166.8,35.8,105.8,25.8,520,520,520,520,520,520 +newtype_definition,11.0,5.6,715.7,625.7,168.0,24.3,122.5,36.3,2000,2000,2000,0,2000,2000 +overloads_evaluation,13.6,4.2,590.5,621.8,164.7,60.7,118.4,34.7,600,1401,801,600,600,801 +override_compatibility,15.7,5.2,636.3,605.3,164.7,41.0,110.5,28.5,200,200,300,1,200,300 +protocols_definition,10.2,4.5,577.3,580.3,168.1,35.9,103.9,27.0,536,402,402,335,402,402 +returns_compatibility,7.8,4.7,494.5,573.6,164.8,32.4,102.1,24.9,1080,540,540,540,540,540 +tuples_index,9.9,4.5,549.0,575.5,165.7,34.1,103.4,25.2,600,600,600,1800,600,600 +typeddict_key_access,10.4,4.3,611.6,581.0,164.7,38.2,109.5,25.6,500,500,500,500,500,500 +typeddict_readonly_inheritance,15.8,4.3,658.8,579.8,164.9,38.2,114.8,26.2,500,500,500,2,500,500 +typeddict_readonly_mutation,11.1,4.6,614.5,585.1,165.1,42.9,109.9,26.9,500,500,500,500,500,500 +typevar_constraints,17.9,5.8,775.1,586.5,168.6,41.3,114.1,33.0,2000,2000,2000,2000,2000,2000 +undefined_names,16.5,5.6,485.5,636.1,168.6,51.7,554.7,35.5,2000,2000,4000,2000,2000,4000 +unresolved_imports,13.9,5.4,459.8,681.9,169.3,281.5,917.9,306.0,2000,2000,2000,2000,2000,2000 diff --git a/conformance/conformance_status.csv b/conformance/conformance_status.csv index 53a7c691..6b9ded6e 100644 --- a/conformance/conformance_status.csv +++ b/conformance/conformance_status.csv @@ -1,7 +1,7 @@ basilisk_rules,file,category,status,caught,missed,false_positives aliases_implicit,aliases_explicit.py,aliases,PASS,21,0,0 aliases_implicit|annotations_forward_refs|generics_defaults_specialization,aliases_implicit.py,aliases,PASS,22,0,0 -aliases_newtype|assignment_compatibility,aliases_newtype.py,aliases,PASS,14,0,0 +aliases_newtype,aliases_newtype.py,aliases,PASS,14,0,0 aliases_recursive|assignment_compatibility,aliases_recursive.py,aliases,PASS,11,0,0 aliases_type_statement|generics_syntax_scoping,aliases_type_statement.py,aliases,PASS,24,0,0 aliases_typealiastype,aliases_typealiastype.py,aliases,PASS,22,0,0 @@ -15,7 +15,7 @@ assignment_compatibility|callables_annotation|callables_protocol|callables_proto callables_kwargs|callables_protocol_2|calls_argument_type,callables_kwargs.py,callables,PASS,12,0,0 callables_protocol_2,callables_protocol.py,callables,PASS,17,0,0 assignment_compatibility|callables_subtyping,callables_subtyping.py,callables,PASS,32,0,0 -assignment_compatibility|classes_classvar|protocols_definition_2|qualifiers_final_annotation,classes_classvar.py,classes,PASS,17,0,0 +classes_classvar|protocols_definition_2|qualifiers_final_annotation,classes_classvar.py,classes,PASS,17,0,0 classes_override_3,classes_override.py,classes,PASS,0,0,0 constructors_call_init|generics_defaults_referential_2,constructors_call_init.py,constructors,PASS,5,0,0 calls_argument_count,constructors_call_metaclass.py,constructors,PASS,2,0,0 @@ -115,7 +115,7 @@ protocols_runtime_checkable|protocols_runtime_checkable_2,protocols_runtime_chec assignment_compatibility|protocols_explicit,protocols_subtyping.py,protocols,PASS,7,0,0 protocols_variance|protocols_variance_2,protocols_variance.py,protocols,PASS,5,0,0 qualifiers_annotated|qualifiers_annotated_2,qualifiers_annotated.py,qualifiers,PASS,20,0,0 -assignment_compatibility|calls_argument_count|namedtuples_define_functional|qualifiers_final_annotation|qualifiers_final_annotation_2,qualifiers_final_annotation.py,qualifiers,PASS,26,0,0 +calls_argument_count|namedtuples_define_functional|qualifiers_final_annotation|qualifiers_final_annotation_2,qualifiers_final_annotation.py,qualifiers,PASS,26,0,0 overloads_consistency_2|qualifiers_final_decorator,qualifiers_final_decorator.py,qualifiers,PASS,3,0,0 ,specialtypes_any.py,specialtypes,PASS,0,0,0 assignment_compatibility|specialtypes_never|specialtypes_never_2,specialtypes_never.py,specialtypes,PASS,3,0,0 diff --git a/crates/basilisk-checker/src/annotation/builtins.rs b/crates/basilisk-checker/src/annotation/builtins.rs index 62e815dc..3f7d27d7 100644 --- a/crates/basilisk-checker/src/annotation/builtins.rs +++ b/crates/basilisk-checker/src/annotation/builtins.rs @@ -22,20 +22,33 @@ pub(super) fn leaf(name: &str) -> Option { "bool" => Some(InferredType::Bool), "bytes" => Some(InferredType::Bytes), "none" => Some(InferredType::None_), - // [TYPEINF-SPECIAL-ANY] — `Any`, `object`, and the bare gradual forms - // are the escape hatch for assignment purposes. - "any" | "object" | "final" | "tuple" | "type" => Some(InferredType::Any), + // [TYPEINF-SPECIAL-ANY] — `Any` and the bare gradual forms are the + // escape hatch for assignment purposes. + "any" | "final" | "tuple" | "type" => Some(InferredType::Any), + // `object` is the TOP type, not the gradual one. It accepts every value + // exactly as `Any` does (see `is_assignable_to`), but it is a real named + // leaf: collapsing it into `Any` made `list[object]` and `list[Any]` + // indistinguishable, and an invariant judgment must tell them apart — + // narrowing `list[object]` to `list[int]` is an error the spec requires + // ([TYPEINF-NARROWING-TYPEIS]), while `list[Any]` is consistent with + // anything. + "object" => Some(InferredType::Named("object".to_owned())), // [TYPEINF-SPECIAL-NEVER] — the bottom type; `NoReturn` is its spelling // in return position. "never" | "noreturn" => Some(InferredType::Never), // [TYPEINF-SPECIAL-LITERALSTRING]. "literalstring" => Some(InferredType::LiteralString), - // A bare `Callable` is `Callable[..., Any]` (PEP 484): empty - // `param_types` is the arbitrary-parameter form. + // A bare `Callable` is `Callable[..., Any]` (PEP 484): the gradual-tail + // marker is the arbitrary-parameter form. "callable" => Some(InferredType::Callable(CallableInfo { - param_types: Vec::new(), + param_types: crate::types::gradual_params(Vec::new()), return_type: Box::new(InferredType::Any), })), + // A bare `TypeForm` is `TypeForm[Any]` (PEP 747), for the same reason a + // bare `Callable` is `Callable[..., Any]`. Left as a plain name it + // stopped denoting a type form at all, and the RHS of + // `x: TypeForm = ` was then never validated as a type expression. + "typeform" => Some(InferredType::TypeForm(Box::new(InferredType::Any))), "generator" => Some(InferredType::Generator( Box::new(InferredType::Any), Box::new(InferredType::None_), diff --git a/crates/basilisk-checker/src/annotation/forms.rs b/crates/basilisk-checker/src/annotation/forms.rs index 748f3280..1479edf8 100644 --- a/crates/basilisk-checker/src/annotation/forms.rs +++ b/crates/basilisk-checker/src/annotation/forms.rs @@ -9,9 +9,9 @@ use ruff_python_ast::{Expr, UnaryOp}; -use crate::types::{CallableInfo, InferredType, LiteralValue}; +use crate::types::{gradual_params, CallableInfo, InferredType, LiteralValue}; -use super::{AnnotationResolver, Frame}; +use super::{tables, AnnotationResolver, Frame}; /// Evaluate a subscripted special form. `None` means "not a special form" — /// the caller continues the cascade with aliases and classes. @@ -45,7 +45,7 @@ pub(super) fn special_form( "set" | "frozenset" => Some(InferredType::Set(Box::new(first_type(args, &resolve)))), "dict" => Some(dict_type(args, &resolve)), "tuple" => Some(tuple_type(args, &resolve)), - "callable" => Some(callable_type(args, &resolve)), + "callable" => Some(callable_type(resolver, args, frame)), "generator" => Some(generator_type(args, &resolve)), // `type[X]` needs class-object modelling the cascade does not yet do: // gradual, so no rule invents a verdict from it. @@ -80,21 +80,57 @@ fn tuple_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> Inferr /// `Callable[[P..], R]`, `Callable[..., R]`, and `Callable[P, R]` for a /// `ParamSpec` `P` (whose parameter list is unknown — the arbitrary form). -fn callable_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> InferredType { +fn callable_type(resolver: &AnnotationResolver<'_>, args: &[&Expr], frame: &Frame) -> InferredType { let [params, ret] = args else { return InferredType::Unknown; }; let param_types = match params { - Expr::List(list) => list.elts.iter().map(resolve).collect(), - // `...` and a `ParamSpec` both mean "parameters not constrained here". - _ => Vec::new(), + // A written list pins the parameters exactly — including `[]`, the + // callable that takes none. + Expr::List(list) => list + .elts + .iter() + .map(|elt| resolver.eval(elt, frame)) + .collect(), + // `Concatenate[X, .., P]` pins the leading positions and leaves the + // rest to the `ParamSpec` (PEP 612). + Expr::Subscript(sub) => concatenate_prefix(resolver, sub, frame), + // `...` and a bare `ParamSpec` both mean "parameters not constrained + // here" — no prefix, gradual tail. + _ => gradual_params(Vec::new()), }; InferredType::Callable(CallableInfo { param_types, - return_type: Box::new(resolve(ret)), + return_type: Box::new(resolver.eval(ret, frame)), }) } +/// The parameter list denoted by a subscripted parameter specification. +/// +/// `Concatenate[int, P]` becomes the required prefix `[int]` plus a gradual +/// tail; the trailing `ParamSpec` itself is the tail, not a parameter. Any +/// other subscript in this position is a form the cascade does not model, so it +/// stays fully gradual rather than being guessed at. +fn concatenate_prefix( + resolver: &AnnotationResolver<'_>, + sub: &ruff_python_ast::ExprSubscript, + frame: &Frame, +) -> Vec { + let head = tables::dotted_name(&sub.value).and_then(|d| resolver.canonical_head(&d)); + if head.as_deref().map(str::to_ascii_lowercase).as_deref() != Some("concatenate") { + return gradual_params(Vec::new()); + } + let args = basilisk_parser::subscript_elements(sub); + let prefix = args + .split_last() + .map(|(_, leading)| leading) + .unwrap_or_default() + .iter() + .map(|expr| resolver.eval(expr, frame)) + .collect(); + gradual_params(prefix) +} + /// `Generator[Yield, Send, Return]`; any other arity is gradual. fn generator_type(args: &[&Expr], resolve: &dyn Fn(&Expr) -> InferredType) -> InferredType { match args { diff --git a/crates/basilisk-checker/src/annotation/mod.rs b/crates/basilisk-checker/src/annotation/mod.rs index 4d4909f3..3dea34b7 100644 --- a/crates/basilisk-checker/src/annotation/mod.rs +++ b/crates/basilisk-checker/src/annotation/mod.rs @@ -29,6 +29,7 @@ mod forms; mod index; mod tables; +use std::cell::RefCell; use std::collections::HashMap; use basilisk_resolver::{ResolvedModule, Span}; @@ -59,6 +60,14 @@ pub fn resolve_annotation(module: &ResolvedModule, expr: &Expr) -> InferredType pub struct AnnotationResolver<'m> { tables: Tables<'m>, annotations: HashMap<(u32, u32), &'m Expr>, + /// Memo of every annotation already resolved BY SPAN. + /// + /// One annotation is asked about by several rules — a function's return + /// type is read by the return-compatibility rules and by both narrowing + /// rules — and evaluating a type expression walks it and allocates the + /// resulting type. The cascade is pure, so the second answer is the first + /// one ([CHKARCH-TESTING-BENCH-RATCHET]). + resolved: RefCell>, } /// One step of resolution: the alias parameters currently bound, the aliases @@ -103,6 +112,7 @@ impl<'m> AnnotationResolver<'m> { Some(AnnotationResolver { tables: Tables::build(&parsed.ast), annotations: index::annotation_nodes(&parsed.ast), + resolved: RefCell::default(), }) } @@ -117,9 +127,13 @@ impl<'m> AnnotationResolver<'m> { /// and must stay silent rather than fall back to reading text. #[must_use] pub fn resolve_span(&self, span: Span) -> Option { - self.annotations - .get(&(span.start, span.end)) - .map(|expr| self.resolve(expr)) + let key = (span.start, span.end); + if let Some(hit) = self.resolved.borrow().get(&key) { + return Some(hit.clone()); + } + let resolved = self.resolve(self.annotations.get(&key)?); + let _ = self.resolved.borrow_mut().insert(key, resolved.clone()); + Some(resolved) } /// Resolve an annotation the resolver holds only as **stored text** — a diff --git a/crates/basilisk-checker/src/inference.rs b/crates/basilisk-checker/src/inference.rs index 3ad2497d..baa5d137 100644 --- a/crates/basilisk-checker/src/inference.rs +++ b/crates/basilisk-checker/src/inference.rs @@ -43,7 +43,8 @@ pub fn infer_rhs(rhs: &RhsKind) -> InferredType { // Lambda expressions have type Callable[..., Unknown] since we don't know // parameter types or return type without analyzing the lambda body InferredType::Callable(crate::types::CallableInfo { - param_types: Vec::new(), // Empty means we don't know parameter types + // The gradual tail: the lambda's parameters are not pinned here. + param_types: crate::types::gradual_params(Vec::new()), return_type: Box::new(InferredType::Unknown), }) } diff --git a/crates/basilisk-checker/src/param_infer.rs b/crates/basilisk-checker/src/param_infer.rs index 2823f774..c6d828fd 100644 --- a/crates/basilisk-checker/src/param_infer.rs +++ b/crates/basilisk-checker/src/param_infer.rs @@ -258,7 +258,9 @@ pub fn imported_callable_globals( let ty = match symbol.kind { ExternalSymbolKind::Function => { InferredType::Callable(crate::types::CallableInfo { - param_types: Vec::new(), + // An imported function's parameters are not modelled + // here — gradual tail, not "takes no arguments". + param_types: crate::types::gradual_params(Vec::new()), return_type: Box::new( symbol .type_annotation diff --git a/crates/basilisk-checker/src/rules/aliases_type_statement.rs b/crates/basilisk-checker/src/rules/aliases_type_statement.rs index 45549a0e..75fe7f47 100644 --- a/crates/basilisk-checker/src/rules/aliases_type_statement.rs +++ b/crates/basilisk-checker/src/rules/aliases_type_statement.rs @@ -19,13 +19,13 @@ //! type BadAlias3 = 1 # E — int literal //! ``` -use std::collections::HashSet; +use std::collections::{HashMap, HashSet}; use basilisk_resolver::{ResolvedModule, RhsKind, Span}; -use ruff_python_ast::{Expr, Operator}; +use ruff_python_ast::{Expr, Operator, Stmt}; +use ruff_text_size::Ranged; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; -use crate::span_util::slice_span; use super::Rule; @@ -47,15 +47,31 @@ fn make_diag(name: &str, span: Span, path: &str) -> Diagnostic { ) } +/// The names a statement must treat as non-types: module bindings that hold a +/// value, minus the statement's OWN type parameters. +/// +/// PEP 695 binds a `type` statement's parameters in its annotation scope, so +/// `T = 1` followed by `type Wrapper[T] = T | None` is valid. The shadowing is +/// resolved per NAME at the leaf rather than by rebuilding a filtered set per +/// statement — a module of `n` aliases and `m` value bindings costs `O(n + m)` +/// instead of `O(n * m)` ([CHKARCH-TESTING-BENCH-RATCHET]). +struct NonTypes<'a> { + module: &'a HashSet<&'a str>, + shadowed: &'a [String], +} + +impl NonTypes<'_> { + fn contains(&self, name: &str) -> bool { + self.module.contains(name) && !self.shadowed.iter().any(|param| param == name) + } +} + /// Whether `expr` has the structural shape of a type expression. /// /// A bare name bound to a non-type module variable (e.g. `x = 42` then /// `type Bad = x`) is rejected; subscript arguments are deliberately not -/// descended into (special forms hold non-type expressions there). The -/// caller must already have removed the statement's own type parameters -/// from `non_type_names` — PEP 695 binds them in the alias's annotation -/// scope, shadowing same-named module bindings. -fn is_type_expression(expr: &Expr, non_type_names: &HashSet<&str>) -> bool { +/// descended into (special forms hold non-type expressions there). +fn is_type_expression(expr: &Expr, non_type_names: &NonTypes<'_>) -> bool { match expr { Expr::Name(name) => !non_type_names.contains(name.id.as_str()), Expr::Attribute(_) | Expr::NoneLiteral(_) | Expr::StringLiteral(_) => true, @@ -68,11 +84,24 @@ fn is_type_expression(expr: &Expr, non_type_names: &HashSet<&str>) -> bool { } } -/// Parse the RHS source text and validate it structurally. Text that does -/// not parse as an expression is left to the parser's own diagnostics. -fn rhs_is_invalid(rhs: &str, non_type_names: &HashSet<&str>) -> bool { - ruff_python_parser::parse_expression(rhs.trim()) - .is_ok_and(|parsed| !is_type_expression(parsed.expr(), non_type_names)) +/// Index every `type X = rhs` value expression in the module's ALREADY-PARSED +/// AST, keyed by the span the resolver recorded for it. +/// +/// The RHS is a node in that tree, not text to be parsed again: re-parsing it +/// per statement cost a full `ruff` expression parse for every alias in the +/// file, which is most of the work on an alias-dense module. +fn index_rhs_nodes<'ast>(stmts: &'ast [Stmt], out: &mut HashMap<(u32, u32), &'ast Expr>) { + for stmt in stmts { + match stmt { + Stmt::TypeAlias(alias) => { + let range = alias.value.range(); + let _ = out.insert((range.start().to_u32(), range.end().to_u32()), &alias.value); + } + Stmt::ClassDef(class) => index_rhs_nodes(&class.body, out), + Stmt::FunctionDef(function) => index_rhs_nodes(&function.body, out), + _ => {} + } + } } /// Collect names of module-level variables that are not valid types. @@ -108,23 +137,26 @@ impl Rule for TypeStatementInvalidRhs { _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { - let source = &module.source; let path = &module.path; - let non_type_names = collect_non_type_names(module); + // The module's own AST, parsed once and shared with every other rule + // that needs it. A module that does not parse has no type statements to + // judge — the parser reports that itself. + let Some(parsed) = module.lazy_ast.get_or_parse(&module.source, &module.path) else { + return; + }; + let mut rhs_nodes = HashMap::new(); + index_rhs_nodes(&parsed.ast.body, &mut rhs_nodes); + let module_non_types = collect_non_type_names(module); for stmt in &module.type_statements { - let Some(rhs) = slice_span(source, stmt.rhs_span) else { + let Some(rhs) = rhs_nodes.get(&(stmt.rhs_span.start, stmt.rhs_span.end)) else { continue; }; - // The statement's own type parameters shadow module bindings - // inside the RHS (PEP 695 annotation scope): `T = 1` followed by - // `type Wrapper[T] = T | None` is valid. - let visible: HashSet<&str> = non_type_names - .iter() - .copied() - .filter(|name| !stmt.param_names.iter().any(|param| param == name)) - .collect(); - if rhs_is_invalid(rhs, &visible) { + let non_types = NonTypes { + module: &module_non_types, + shadowed: &stmt.param_names, + }; + if !is_type_expression(rhs, &non_types) { diagnostics.push(make_diag(&stmt.name, stmt.name_span, path)); } } diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/alias_match.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/alias_match.rs index 45185cfe..5cb73593 100644 --- a/crates/basilisk-checker/src/rules/assignment_compatibility/alias_match.rs +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/alias_match.rs @@ -76,7 +76,7 @@ pub(super) fn collect_value_aliases(module: &ResolvedModule) -> HashMap HashMap HashMap bool { } /// The trimmed RHS source text of an alias assignment, if non-empty. -fn alias_rhs_text(var: &VariableInfo, source: &str) -> Option { +/// +/// A `Name = TypeAliasType("Name", body, type_params=(T,))` definition is NOT a +/// textual alias body: its body is the call's SECOND ARGUMENT, and the call +/// expression itself denotes no type at all. Matching a value against that text +/// asks whether e.g. `1` matches `typealiastype("goodalias4", …)`, which can +/// only ever answer "no" — a false positive on every valid use of a +/// `TypeAliasType` alias. These aliases are resolved by the +/// [TYPEINF-ANNOTATION-RESOLUTION] cascade instead, so they are excluded here +/// rather than approximated. +fn alias_rhs_text(var: &VariableInfo, module: &ResolvedModule) -> Option { + if is_type_alias_type_call(var, module) { + return None; + } let rhs_span = var.rhs_span?; - let rhs_text = slice_span(source, rhs_span)?.trim(); + let rhs_text = slice_span(&module.source, rhs_span)?.trim(); (!rhs_text.is_empty()).then(|| rhs_text.to_owned()) } +/// Whether `var` is the LHS of a `TypeAliasType(...)` call the resolver +/// recognised (structural, never a text match on the RHS). +fn is_type_alias_type_call(var: &VariableInfo, module: &ResolvedModule) -> bool { + module + .type_alias_type_calls + .iter() + .any(|call| call.lhs_name == var.name) +} + /// Returns `true` when `value` positively matches the (possibly recursive) /// alias `target`. See the module docs for the positive-match contract. pub(super) fn alias_assignable( diff --git a/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs b/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs index 978d9e4e..08b3da36 100644 --- a/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs +++ b/crates/basilisk-checker/src/rules/assignment_compatibility/mod.rs @@ -60,10 +60,23 @@ impl Rule for AssignmentTypeMismatch { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; let empty_params = ParamMaps::default(); @@ -78,9 +91,9 @@ impl Rule for AssignmentTypeMismatch { &skip, &module.functions, &call_index, - &resolver, + resolver, ); - check_local_vars(module, diagnostics, &skip, &call_index, &resolver); + check_local_vars(module, diagnostics, &skip, &call_index, resolver); check_tuple_reassignments(module, diagnostics); check_dataclass_attr_assignments(module, diagnostics); typeform_check::check_typeform_calls(module, diagnostics); @@ -173,7 +186,13 @@ fn check_vars( // The declared type is the annotation resolved through the shared // cascade ([TYPEINF-ANNOTATION-RESOLUTION]), so an alias or a // same-file class is the type it denotes rather than opaque text. - let declared_type = resolver.resolve_text(annotation_text)?; + // Resolved from the annotation NODE where the resolver recorded its + // span; `resolve_text` re-parses, which costs a `ruff` expression + // parse per annotated variable ([CHKARCH-TESTING-BENCH-RATCHET]). + let declared_type = var + .annotation_span + .and_then(|span| resolver.resolve_span(span)) + .or_else(|| resolver.resolve_text(annotation_text))?; let declared_nominal = nominal_name(&declared_type); // TypeForm assignments require type-expression validation, not @@ -266,9 +285,7 @@ fn check_vars( // cross-name assignment (`v: A = b` where `b: B`). Genuine mismatches // still fire. Only reachable when the RHS resolves to a TypedDict-typed // name (e.g. a parameter), so module-level checks are unaffected. - if let (Some(decl), Some(inf)) = - (&declared_nominal, nominal_name(&inferred_type)) - { + if let (Some(decl), Some(inf)) = (&declared_nominal, nominal_name(&inferred_type)) { if let (Some(target), Some(src)) = ( skip.typeddict_schemas.get(decl.as_str()), skip.typeddict_schemas.get(inf.as_str()), diff --git a/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs b/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs index 712bee46..1661f162 100644 --- a/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs +++ b/crates/basilisk-checker/src/rules/calls_argument_count/method_binding.rs @@ -58,7 +58,14 @@ pub(super) fn check_method_calls(module: &ResolvedModule, diagnostics: &mut Vec< else { continue; }; - check_bound_call(module, call, class_info, &bound, instance_access, diagnostics); + check_bound_call( + module, + call, + class_info, + &bound, + instance_access, + diagnostics, + ); } } diff --git a/crates/basilisk-checker/src/rules/calls_argument_count/mod.rs b/crates/basilisk-checker/src/rules/calls_argument_count/mod.rs index 8fd5035b..f7b823f0 100644 --- a/crates/basilisk-checker/src/rules/calls_argument_count/mod.rs +++ b/crates/basilisk-checker/src/rules/calls_argument_count/mod.rs @@ -246,18 +246,15 @@ fn check_plain_function_calls(module: &ResolvedModule, diagnostics: &mut Vec NoReturn`, `-> int | Meta`), the /// metaclass fully controls the constructor call and we should NOT validate /// arguments against `__new__`/`__init__`. -fn metaclass_passes_through( - metaclass_name: &str, - classes: &[ClassInfo], - functions: &[FunctionInfo], -) -> bool { +fn metaclass_passes_through(metaclass_name: &str, module: &ResolvedModule) -> bool { // First check that the metaclass class exists - if !classes.iter().any(|c| c.name == metaclass_name) { + if !module.classes.iter().any(|c| c.name == metaclass_name) { return false; } // Find the metaclass __call__ method - let call_method = functions + let call_method = module + .functions .iter() .find(|f| f.class_name.as_deref() == Some(metaclass_name) && f.name == "__call__"); @@ -267,7 +264,47 @@ fn metaclass_passes_through( }; // The metaclass __call__ must use *args and **kwargs to pass through - call_fn.vararg.is_some() && call_fn.kwarg.is_some() + call_fn.vararg.is_some() && call_fn.kwarg.is_some() && constructs_an_instance(call_fn, module) +} + +/// Does this metaclass `__call__` still yield an instance of the class being +/// constructed, so `__new__`/`__init__` are evaluated as usual? +/// +/// Per the [metaclass `__call__`](https://typing.python.org/en/latest/spec/constructors.html#metaclass-call-method) +/// rules, a return annotated with a type variable +/// (`def __call__(cls: type[T], ...) -> T`) or `Self` is the pass-through +/// spelling. Any other concrete return — `NoReturn`, `int | Meta` — means the +/// metaclass fully controls the call and the constructor signature is never +/// consulted, so an arity judgment against `__new__` would be a false positive. +/// +/// An UNANNOTATED `__call__` is decided from its body instead of assumed, so +/// this judgment survives [TYPEINF-TARGET-GRADUAL]: stripping the annotations +/// off a metaclass must not turn a silent constructor call into an error. +fn constructs_an_instance(call_fn: &FunctionInfo, module: &ResolvedModule) -> bool { + let Some(span) = call_fn.return_annotation_span else { + return body_delegates_construction(call_fn); + }; + let Some(text) = slice_span(&module.source, span) else { + return body_delegates_construction(call_fn); + }; + let returned = text.trim(); + returned == "Self" + || module + .typevar_calls + .iter() + .any(|typevar| typevar.name == returned) +} + +/// Does an unannotated metaclass `__call__` hand construction back to the +/// normal machinery? +/// +/// `return type.__call__(cls, *args, **kwargs)` delegates, so `__new__` runs and +/// its signature governs. A body that returns a value of its own (`return 1`) or +/// never returns at all (`raise TypeError(...)`) produces something that is not +/// an instance of the class, so the constructor is never consulted. +fn body_delegates_construction(call_fn: &FunctionInfo) -> bool { + let mut returns_values = call_fn.return_stmts.iter().filter(|stmt| stmt.has_value); + returns_values.clone().next().is_some() && returns_values.all(|stmt| stmt.value_is_call) } /// Collects the positional (non-kw_only, non-init_false, non-ClassVar) fields of a @@ -414,7 +451,7 @@ fn check_constructor_calls(module: &ResolvedModule, diagnostics: &mut Vec); + /// Run the rule with the module's SHARED annotation cascade. + /// + /// Building an [`AnnotationResolver`] walks the whole AST twice (the tables + /// and the span → node index), so the driver builds it once per module and + /// passes it here; a rule that builds its own pays that walk again, and a + /// dozen such rules made the walk the dominant cost of checking a file + /// ([CHKARCH-TESTING-BENCH-RATCHET]). Rules that read the cascade override + /// this; every other rule ignores the argument through the default. `None` + /// means the module does not parse, which is reported elsewhere. + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, + ctx: &CheckContext, + diagnostics: &mut Vec, + ) { + let _ = annotations; + self.check(module, ctx, diagnostics); + } + /// This rule's opt-in tag declaration, or `None` for a core PEP rule. /// /// Returning `Some(..)` marks the rule as Basilisk-original: off by default, @@ -410,10 +430,13 @@ pub fn run_all(module: &ResolvedModule, ctx: &CheckContext) -> Vec { .into_iter() .max() .unwrap_or(0); + // One cascade for the whole module: every rule that reads annotations + // shares these tables instead of rebuilding them ([CHKARCH-TESTING-BENCH-RATCHET]). + let annotations = crate::annotation::AnnotationResolver::for_module(module); all_rules() .iter() .fold(Vec::with_capacity(expected), |mut acc, rule| { - rule.check(module, ctx, &mut acc); + rule.check_with_annotations(module, annotations.as_ref(), ctx, &mut acc); acc }) } diff --git a/crates/basilisk-checker/src/rules/narrowing_typeguard.rs b/crates/basilisk-checker/src/rules/narrowing_typeguard.rs index 91ee4840..b57bcb14 100644 --- a/crates/basilisk-checker/src/rules/narrowing_typeguard.rs +++ b/crates/basilisk-checker/src/rules/narrowing_typeguard.rs @@ -9,7 +9,6 @@ use basilisk_resolver::ResolvedModule; use super::Rule; -use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; use crate::span_util::slice_span; use crate::types::InferredType; @@ -43,11 +42,24 @@ impl Rule for TypeGuardNoNarrowingParam { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { let source = &module.source; - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; @@ -62,15 +74,11 @@ impl Rule for TypeGuardNoNarrowingParam { continue; }; - // Extract annotation text from source. - let Some(ann_text) = slice_span(source, ann_span) else { - continue; - }; - // The return type must RESOLVE to a narrowing form — through // aliases too, so `Guard = TypeGuard[int]` does not hide one. - let Some(InferredType::Guard { type_is, .. }) = resolver.resolve_text(ann_text) - else { + // Resolved from the indexed annotation NODE: slicing the text and + // re-parsing it costs a `ruff` parse per annotated method. + let Some(InferredType::Guard { type_is, .. }) = resolver.resolve_span(ann_span) else { continue; }; @@ -80,6 +88,9 @@ impl Rule for TypeGuardNoNarrowingParam { } let guard_kind = if type_is { "TypeIs" } else { "TypeGuard" }; + // Only the diagnostic path needs the annotation AS WRITTEN, so the + // source slice happens here rather than on every method checked. + let ann_text = slice_span(source, ann_span).unwrap_or(guard_kind); diagnostics.push(error_diagnostic_owned( CODE.clone(), diff --git a/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs b/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs index 62a30df4..6907b1c5 100644 --- a/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs +++ b/crates/basilisk-checker/src/rules/narrowing_typeis_2.rs @@ -10,7 +10,6 @@ use basilisk_resolver::ResolvedModule; use super::Rule; use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diag_help_note, Diagnostic, ErrorCode}; -use crate::span_util::slice_span; use crate::subtyping::SubtypingContext; use crate::types::InferredType; @@ -91,9 +90,10 @@ fn consistency( } match (narrowed, input) { // A narrowed union is consistent when EVERY arm is. - (InferredType::Union(arms), _) => { - all_arms(arms.iter().map(|arm| consistency(resolver, ctx, arm, input))) - } + (InferredType::Union(arms), _) => all_arms( + arms.iter() + .map(|arm| consistency(resolver, ctx, arm, input)), + ), (InferredType::Optional(inner), _) => all_arms( [ consistency(resolver, ctx, inner, input), @@ -102,9 +102,10 @@ fn consistency( .into_iter(), ), // An input union accepts a narrow into ANY of its arms. - (_, InferredType::Union(arms)) => { - any_arm(arms.iter().map(|arm| consistency(resolver, ctx, narrowed, arm))) - } + (_, InferredType::Union(arms)) => any_arm( + arms.iter() + .map(|arm| consistency(resolver, ctx, narrowed, arm)), + ), (_, InferredType::Optional(inner)) => any_arm( [ consistency(resolver, ctx, narrowed, inner), @@ -206,11 +207,23 @@ impl Rule for TypeIsInconsistentNarrowing { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { - let source = &module.source; - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; let subtyping = module_subtyping(module); @@ -219,17 +232,17 @@ impl Rule for TypeIsInconsistentNarrowing { let Some(ann_span) = func.return_annotation_span else { continue; }; - let Some(ann_text) = slice_span(source, ann_span) else { - continue; - }; // Only `TypeIs` carries the consistency precondition — resolved, // so an alias of `TypeIs[X]` is checked exactly like the spelled - // form ([TYPEINF-ANNOTATION-RESOLUTION]). + // form ([TYPEINF-ANNOTATION-RESOLUTION]). Resolved from the + // annotation NODE the span points at: re-parsing the text would + // cost a `ruff` expression parse per annotated function, and the + // node is already indexed. let Some(InferredType::Guard { type_is: true, inner, - }) = resolver.resolve_text(ann_text) + }) = resolver.resolve_span(ann_span) else { continue; }; @@ -245,10 +258,7 @@ impl Rule for TypeIsInconsistentNarrowing { let Some(param_ann_span) = param.annotation_span else { continue; }; - let Some(param_type) = slice_span(source, param_ann_span) else { - continue; - }; - let Some(input) = resolver.resolve_text(param_type) else { + let Some(input) = resolver.resolve_span(param_ann_span) else { continue; }; @@ -258,7 +268,7 @@ impl Rule for TypeIsInconsistentNarrowing { continue; } - if consistency(&resolver, &subtyping, &inner, &input) == Verdict::Inconsistent { + if consistency(resolver, &subtyping, &inner, &input) == Verdict::Inconsistent { diagnostics.push(error_diag_help_note( CODE.clone(), format!( diff --git a/crates/basilisk-checker/src/rules/overloads_basic.rs b/crates/basilisk-checker/src/rules/overloads_basic.rs index bbb8f105..061c6b80 100644 --- a/crates/basilisk-checker/src/rules/overloads_basic.rs +++ b/crates/basilisk-checker/src/rules/overloads_basic.rs @@ -41,11 +41,24 @@ impl Rule for NoMatchingOverload { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // Overload membership is a binding question ([#380]). - let Some(resolver) = crate::annotation::AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; let source = &module.source; @@ -85,7 +98,7 @@ impl Rule for NoMatchingOverload { if func.name != "__getitem__" { continue; } - if !super::shared::overload_decorated(&resolver, &func.decorators) { + if !super::shared::overload_decorated(resolver, &func.decorators) { continue; } let Some(class_name) = func.class_name.as_deref() else { diff --git a/crates/basilisk-checker/src/rules/overloads_consistency.rs b/crates/basilisk-checker/src/rules/overloads_consistency.rs index 9785bd88..7fa9578f 100644 --- a/crates/basilisk-checker/src/rules/overloads_consistency.rs +++ b/crates/basilisk-checker/src/rules/overloads_consistency.rs @@ -13,7 +13,6 @@ use std::collections::HashMap; use basilisk_resolver::{FunctionInfo, ResolvedModule}; -use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; use super::shared::overload_decorated; @@ -32,19 +31,32 @@ impl Rule for OverlappingOverloads { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // Whether a decorator IS `typing.overload` is answered by the // resolver's binding tables ([#380]), shared with every overload rule. - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; // Group overloaded functions by (class_name, function_name) so overloads // in different classes with the same method name don't cross-contaminate. let mut groups: HashMap<(Option<&str>, &str), Vec<&FunctionInfo>> = HashMap::new(); for func in &module.functions { - if overload_decorated(&resolver, &func.decorators) { + if overload_decorated(resolver, &func.decorators) { groups .entry((func.class_name.as_deref(), &func.name)) .or_default() diff --git a/crates/basilisk-checker/src/rules/overloads_consistency_2.rs b/crates/basilisk-checker/src/rules/overloads_consistency_2.rs index 9437cf92..7e299492 100644 --- a/crates/basilisk-checker/src/rules/overloads_consistency_2.rs +++ b/crates/basilisk-checker/src/rules/overloads_consistency_2.rs @@ -39,12 +39,25 @@ impl Rule for OverloadDecoratorConsistency { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // Overload membership is a binding question ([#380]); the // staticmethod/final/override checks below stay spelling-based. - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; let mut groups: HashMap<(Option<&str>, &str), Vec<&FunctionInfo>> = HashMap::new(); @@ -56,7 +69,7 @@ impl Rule for OverloadDecoratorConsistency { } for funcs in groups.values() { - check_group(funcs, &resolver, &module.path, diagnostics); + check_group(funcs, resolver, &module.path, diagnostics); } } } diff --git a/crates/basilisk-checker/src/rules/overloads_consistency_3.rs b/crates/basilisk-checker/src/rules/overloads_consistency_3.rs index c5049880..b9a17383 100644 --- a/crates/basilisk-checker/src/rules/overloads_consistency_3.rs +++ b/crates/basilisk-checker/src/rules/overloads_consistency_3.rs @@ -89,11 +89,24 @@ impl Rule for OverloadImplConsistency { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // Overload membership is a binding question ([#380]). - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; let mut groups: HashMap<(Option<&str>, &str), Vec<&FunctionInfo>> = HashMap::new(); @@ -104,7 +117,7 @@ impl Rule for OverloadImplConsistency { .push(func); } for funcs in groups.values() { - check_group(funcs, &resolver, &module.source, &module.path, diagnostics); + check_group(funcs, resolver, &module.source, &module.path, diagnostics); } } } diff --git a/crates/basilisk-checker/src/rules/overloads_definitions.rs b/crates/basilisk-checker/src/rules/overloads_definitions.rs index fcdd17a3..7e804d3f 100644 --- a/crates/basilisk-checker/src/rules/overloads_definitions.rs +++ b/crates/basilisk-checker/src/rules/overloads_definitions.rs @@ -12,7 +12,6 @@ use std::collections::HashMap; use basilisk_resolver::{FunctionInfo, ResolvedModule}; -use crate::annotation::AnnotationResolver; use crate::diagnostic::{error_diagnostic_owned, Diagnostic, ErrorCode}; use super::guards::is_protocol_class; @@ -35,12 +34,25 @@ impl Rule for MissingOverloadImpl { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // Whether a decorator IS `typing.overload` is a binding question, // answered by the resolver's tables ([#380]) — never by its spelling. - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; // Build a set of Protocol class names so we can exempt their methods. @@ -67,7 +79,7 @@ impl Rule for MissingOverloadImpl { for ((class_name, name), funcs) in &groups { let overloaded: Vec<&&FunctionInfo> = funcs .iter() - .filter(|f| overload_decorated(&resolver, &f.decorators)) + .filter(|f| overload_decorated(resolver, &f.decorators)) .collect(); // No @overload decorators in this group — nothing to check. @@ -77,7 +89,7 @@ impl Rule for MissingOverloadImpl { let non_overloaded: Vec<&&FunctionInfo> = funcs .iter() - .filter(|f| !overload_decorated(&resolver, &f.decorators)) + .filter(|f| !overload_decorated(resolver, &f.decorators)) .collect(); // Case 1: ALL definitions carry @overload (no implementation). diff --git a/crates/basilisk-checker/src/rules/overloads_evaluation.rs b/crates/basilisk-checker/src/rules/overloads_evaluation.rs index e7968915..30df9fcc 100644 --- a/crates/basilisk-checker/src/rules/overloads_evaluation.rs +++ b/crates/basilisk-checker/src/rules/overloads_evaluation.rs @@ -39,11 +39,24 @@ impl Rule for OverloadUnionExpansionFailure { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // Overload membership is a binding question ([#380]). - let Some(resolver) = crate::annotation::AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; let source = &module.source; @@ -58,7 +71,7 @@ impl Rule for OverloadUnionExpansionFailure { if !func.is_stub_body { continue; } - if !super::shared::overload_decorated(&resolver, &func.decorators) { + if !super::shared::overload_decorated(resolver, &func.decorators) { continue; } overload_groups diff --git a/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs b/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs index ad62305b..a8694a98 100644 --- a/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs +++ b/crates/basilisk-checker/src/rules/protocols_definition_2/conformance.rs @@ -268,7 +268,8 @@ pub(super) fn check_instance_var_conformance( fn property_members(cls: &ClassInfo) -> Vec<&str> { let mut members: Vec<&str> = Vec::new(); for (name, decs) in &cls.method_decorators { - if crate::rules::shared::decorator_spelled(decs, "property") && !members.contains(&name.as_str()) + if crate::rules::shared::decorator_spelled(decs, "property") + && !members.contains(&name.as_str()) { members.push(name.as_str()); } @@ -397,7 +398,8 @@ pub(super) fn check_method_signature_conformance( // A `@staticmethod` whose first parameter is `self` cannot satisfy an // instance method — it has no bound receiver. - let impl_static = crate::rules::shared::decorator_spelled(&impl_fn.decorators, "staticmethod"); + let impl_static = + crate::rules::shared::decorator_spelled(&impl_fn.decorators, "staticmethod"); if impl_static && impl_fn.parameters.first().is_some_and(|p| p.name == "self") { push_signature_diag( protocol_name, diff --git a/crates/basilisk-checker/src/rules/redundant_annotation.rs b/crates/basilisk-checker/src/rules/redundant_annotation.rs index 298bba96..6d58ee01 100644 --- a/crates/basilisk-checker/src/rules/redundant_annotation.rs +++ b/crates/basilisk-checker/src/rules/redundant_annotation.rs @@ -11,7 +11,6 @@ //! z: float = 42 # NO warning — annotation adds information (widening) //! ``` -use crate::annotation::AnnotationResolver; use crate::inference::infer_rhs; use crate::types::InferredType; use basilisk_resolver::ResolvedModule; @@ -41,6 +40,19 @@ impl Rule for RedundantAnnotationWarning { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { @@ -48,7 +60,7 @@ impl Rule for RedundantAnnotationWarning { // ([TYPEINF-ANNOTATION-RESOLUTION]): an annotation that is redundant // *through an alias* (`type Age = int` then `x: Age = 1`) is redundant // all the same, and a name we cannot resolve is gradual, never a guess. - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; // Check module-level variables @@ -67,7 +79,10 @@ impl Rule for RedundantAnnotationWarning { return None; } - let declared_type = resolver.resolve_text(annotation_text)?; + let declared_type = var + .annotation_span + .and_then(|span| resolver.resolve_span(span)) + .or_else(|| resolver.resolve_text(annotation_text))?; // Check if annotation is redundant (base type match) if types_match_for_w0050(&inferred_type, &declared_type) { @@ -119,7 +134,10 @@ impl Rule for RedundantAnnotationWarning { return None; } - let declared_type = resolver.resolve_text(annotation_text)?; + let declared_type = attr + .annotation_span + .and_then(|span| resolver.resolve_span(span)) + .or_else(|| resolver.resolve_text(annotation_text))?; // Check if annotation is redundant (base type match) if types_match_for_w0050(&inferred_type, &declared_type) { diff --git a/crates/basilisk-checker/src/rules/returns_compatibility.rs b/crates/basilisk-checker/src/rules/returns_compatibility.rs index 72a06dc5..9747a306 100644 --- a/crates/basilisk-checker/src/rules/returns_compatibility.rs +++ b/crates/basilisk-checker/src/rules/returns_compatibility.rs @@ -41,19 +41,32 @@ impl Rule for ReturnTypeMismatch { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // The declared type of every return annotation comes from the shared // cascade ([TYPEINF-ANNOTATION-RESOLUTION]); its tables are built once // per module, not once per function. - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; for func in &module.functions { // @no_type_check suppresses body checks (E0011); E0041 arity still applies. if !is_stub_context(func, &module.classes) && !is_no_type_check(func) { - check_return_type_mismatch(func, module, &resolver, diagnostics); + check_return_type_mismatch(func, module, resolver, diagnostics); } } } diff --git a/crates/basilisk-checker/src/rules/returns_compatibility_2.rs b/crates/basilisk-checker/src/rules/returns_compatibility_2.rs index 1a2c5038..ffa37bc7 100644 --- a/crates/basilisk-checker/src/rules/returns_compatibility_2.rs +++ b/crates/basilisk-checker/src/rules/returns_compatibility_2.rs @@ -26,19 +26,32 @@ impl Rule for ReturnTypeMismatch { fn check( &self, module: &ResolvedModule, + ctx: &super::CheckContext, + diagnostics: &mut Vec, + ) { + // Standalone entry point (a single-rule test, or any caller outside the + // driver): build the cascade the driver would otherwise share. + let annotations = crate::annotation::AnnotationResolver::for_module(module); + self.check_with_annotations(module, annotations.as_ref(), ctx, diagnostics); + } + + fn check_with_annotations( + &self, + module: &ResolvedModule, + annotations: Option<&crate::annotation::AnnotationResolver<'_>>, _ctx: &super::CheckContext, diagnostics: &mut Vec, ) { // One cascade per module ([TYPEINF-ANNOTATION-RESOLUTION]), shared by // every function's return annotation. - let Some(resolver) = AnnotationResolver::for_module(module) else { + let Some(resolver) = annotations else { return; }; module .functions .iter() .filter(|func| func.return_annotation.is_present()) - .for_each(|func| check_function(func, module, &resolver, diagnostics)); + .for_each(|func| check_function(func, module, resolver, diagnostics)); } } diff --git a/crates/basilisk-checker/src/rules/shared.rs b/crates/basilisk-checker/src/rules/shared.rs index 987d7a1b..9e08c509 100644 --- a/crates/basilisk-checker/src/rules/shared.rs +++ b/crates/basilisk-checker/src/rules/shared.rs @@ -33,10 +33,7 @@ use ruff_python_ast::{self as ast, Expr}; /// answer yes; a decorator merely *named* `overload` but bound from another /// module answers no. Every rule that reasons about overload groups shares /// this one predicate so the groups they form agree. -pub(crate) fn overload_decorated( - resolver: &AnnotationResolver<'_>, - decorators: &[String], -) -> bool { +pub(crate) fn overload_decorated(resolver: &AnnotationResolver<'_>, decorators: &[String]) -> bool { decorators .iter() .any(|decorator| resolver.decorator_denotes(decorator, "overload")) diff --git a/crates/basilisk-checker/src/types.rs b/crates/basilisk-checker/src/types.rs index 2ecbba8f..d67f000c 100644 --- a/crates/basilisk-checker/src/types.rs +++ b/crates/basilisk-checker/src/types.rs @@ -74,12 +74,42 @@ pub enum InferredType { /// Represents a callable type's parameter and return type information. #[derive(Debug, Clone, PartialEq)] pub struct CallableInfo { - /// Parameter types (empty for `Callable[..., R]`). + /// Parameter types, positionally. + /// + /// A trailing [`GRADUAL_PARAMS`] marker means "and then any parameters": + /// `Callable[..., R]` is `[…]`, a `ParamSpec` is `[…]`, and + /// `Callable[Concatenate[int, P], R]` is `[int, …]` — the prefix is + /// required, the tail unconstrained. An EMPTY list is therefore a callable + /// that takes NO parameters (`Callable[[], R]`), which is what lets + /// `Callable[Concatenate[int, P], str]` reject a zero-argument callable. pub param_types: Vec, /// Return type. pub return_type: Box, } +/// The structural marker that ends an unconstrained parameter list. Shares the +/// spelling of the `tuple[X, ...]` terminator: both mean "the rest is not +/// pinned down here". +pub const GRADUAL_PARAMS: &str = "..."; + +/// A parameter list that is unconstrained past its (possibly empty) prefix. +#[must_use] +pub fn gradual_params(prefix: Vec) -> Vec { + let mut params = prefix; + params.push(InferredType::Named(GRADUAL_PARAMS.to_owned())); + params +} + +/// Split a parameter list into its required prefix and whether an +/// unconstrained tail follows. +#[must_use] +pub fn split_gradual(params: &[InferredType]) -> (&[InferredType], bool) { + match params.split_last() { + Some((InferredType::Named(marker), head)) if marker == GRADUAL_PARAMS => (head, true), + _ => (params, false), + } +} + /// Represents a literal value for literal type inference. #[derive(Debug, Clone, PartialEq)] pub enum LiteralValue { @@ -288,6 +318,52 @@ impl InferredType { { true } + // `object` is the top type: every value IS an object, so it accepts + // anything as a target. In the SOURCE position it stays as + // permissive as the gradual `Any` it used to be modelled by — + // narrowing an `object`-typed value to a concrete type is how most + // `isinstance` code is written, and this level has no flow + // information to tell a narrowed use from an unnarrowed one, so + // rejecting it here would fire on spec-valid code. + (_, InferredType::Named(name)) | (InferredType::Named(name), _) + if name == "object" => + { + true + } + // PEP 647/742 narrowing returns. Three distinct relations, and the + // guard-to-guard one must be tested FIRST or the bool relations + // below would make the two forms interchangeable: + // * `TypeGuard[B] <: TypeGuard[A]` when `B <: A` — TypeGuard is + // covariant in its argument. + // * `TypeIs[B] <: TypeIs[A]` only when `B` IS `A` — "Unlike + // TypeGuard, TypeIs is invariant in its argument type". + // * Never across forms: "TypeIs and TypeGuard are not compatible + // with each other". + ( + InferredType::Guard { + type_is: source_is, + inner: source_inner, + }, + InferredType::Guard { + type_is: target_is, + inner: target_inner, + }, + ) => { + source_is == target_is + && if *target_is { + source_inner == target_inner + } else { + source_inner.is_assignable_to(target_inner) + } + } + // A guard VALUE is a `bool` ("in these contexts it is treated as a + // subtype of bool"), so `Callable[..., TypeIs[int]]` satisfies + // `Callable[..., bool]` but never `Callable[..., str]`. + (InferredType::Guard { .. }, target) => InferredType::Bool.is_assignable_to(target), + // Conversely a declared guard return is satisfied by any bool the + // body actually produces — `def f(x: object) -> TypeIs[int]: return + // False` is the canonical narrowing-function body, not a mismatch. + (source, InferredType::Guard { .. }) => source.is_assignable_to(&InferredType::Bool), // Union on the LEFT decomposes before Optional-target unwrapping: // `A | None <: Optional[B]` must check each variant against the // whole `Optional[B]` (so the `None` arm can satisfy it), not @@ -404,18 +480,31 @@ fn callable_assignable(source: &CallableInfo, target: &CallableInfo) -> bool { /// Parameter-list half of [TYPEINF-SUBTYPING-CALLABLE]. /// -/// An empty list spells `...` (arbitrary parameters), which is gradual on -/// either side. A source may require FEWER positions than the target — its -/// trailing positions are satisfiable by defaults — but never more. +/// Positions are contravariant: the target's parameter must be acceptable to +/// the source. A source that requires FEWER positions than the target is fine — +/// its trailing positions are satisfiable by defaults — but never more. +/// +/// A gradual tail ([`GRADUAL_PARAMS`]) relaxes only what follows it. A gradual +/// SOURCE accepts any call, so it satisfies every target. A gradual TARGET +/// (`Callable[Concatenate[int, P], R]`) still pins its prefix: the source must +/// be able to receive those leading arguments, which is exactly why a +/// zero-parameter callable does not satisfy it. fn callable_params_assignable(source: &[InferredType], target: &[InferredType]) -> bool { - if source.is_empty() || target.is_empty() { + let (source_prefix, source_gradual) = split_gradual(source); + let (target_prefix, target_gradual) = split_gradual(target); + if source_gradual { return true; } - source.len() <= target.len() - && source - .iter() - .zip(target.iter()) - .all(|(source_param, target_param)| target_param.is_assignable_to(source_param)) + if target_gradual && source_prefix.len() < target_prefix.len() { + return false; + } + if !target_gradual && source_prefix.len() > target_prefix.len() { + return false; + } + source_prefix + .iter() + .zip(target_prefix.iter()) + .all(|(source_param, target_param)| target_param.is_assignable_to(source_param)) } /// Generator yield/return positions are covariant; the value sent back into diff --git a/crates/basilisk-checker/src/types_parsing.rs b/crates/basilisk-checker/src/types_parsing.rs index be921220..d8746902 100644 --- a/crates/basilisk-checker/src/types_parsing.rs +++ b/crates/basilisk-checker/src/types_parsing.rs @@ -7,7 +7,7 @@ //! the file. No new code may call into this module; existing consumers are //! deleted per [NARROWPLAN-INTEGRATION], and this parser dies with them. -use super::types::{CallableInfo, InferredType, LiteralValue}; +use super::types::{gradual_params, CallableInfo, InferredType, LiteralValue}; impl InferredType { /// Parses annotation text into an `InferredType`. @@ -35,9 +35,9 @@ impl InferredType { // Implements [TYPEINF-SPECIAL-LITERALSTRING]. "literalstring" => InferredType::LiteralString, // A bare `Callable` annotation is `Callable[..., Any]` (PEP 484): - // empty `param_types` represents the arbitrary-parameter form. + // the gradual-tail marker represents the arbitrary-parameter form. "callable" => InferredType::Callable(CallableInfo { - param_types: Vec::new(), + param_types: gradual_params(Vec::new()), return_type: Box::new(InferredType::Any), }), "generator" => InferredType::Generator( @@ -354,9 +354,11 @@ fn parse_callable_annotation(inner: &str) -> InferredType { let return_type_str = inner[comma_idx + 1..].trim(); let return_type = InferredType::from_annotation(return_type_str); + // `Callable[..., R]` constrains no parameter; `Callable[[], R]` below + // constrains them to none at all. The marker keeps the two apart. if param_spec == "..." { return InferredType::Callable(CallableInfo { - param_types: Vec::new(), + param_types: gradual_params(Vec::new()), return_type: Box::new(return_type), }); } diff --git a/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs b/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs index 8343f42e..caa3a815 100644 --- a/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs +++ b/crates/basilisk-checker/tests/checker/calls_expression_position_tests.rs @@ -45,7 +45,11 @@ fn assert_same_arity_error(wrapped_stmt: &str, why: &str) -> TestResult { .ok_or("the bare statement must report an arity error to pin against")?; let wrapped = format!("{CLASS}\n{wrapped_stmt}\n"); - let offset = u32::try_from(wrapped.find("C(1, 2)").ok_or("fixture must contain C(1, 2)")?)?; + let offset = u32::try_from( + wrapped + .find("C(1, 2)") + .ok_or("fixture must contain C(1, 2)")?, + )?; let expected_span = ( offset + (bare_start - bare_offset), offset + (bare_end - bare_offset), diff --git a/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs b/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs index 9881e414..45e66502 100644 --- a/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs +++ b/crates/basilisk-checker/tests/checker/narrowing_typeguard_tests.rs @@ -61,8 +61,8 @@ class C: // Same resolution contract for the PEP 742 form. #[test] -fn aliased_typeis_return_still_requires_narrowing_param( -) -> Result<(), Box> { +fn aliased_typeis_return_still_requires_narrowing_param() -> Result<(), Box> +{ let source = r" from typing import TypeIs diff --git a/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs b/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs index 6bf78b78..aced61ba 100644 --- a/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs +++ b/crates/basilisk-checker/tests/checker/narrowing_typeis_2_tests.rs @@ -85,8 +85,7 @@ def is_mine(x: Base) -> TypeIs[MyClass]: // The resolution work must not blunt the rule: a resolved alias that IS // inconsistent still fires. #[test] -fn aliased_narrowed_type_still_fires_when_inconsistent( -) -> Result<(), Box> { +fn aliased_narrowed_type_still_fires_when_inconsistent() -> Result<(), Box> { let source = r" from typing import TypeIs diff --git a/crates/basilisk-checker/tests/mutation_kill_constructors_tests.rs b/crates/basilisk-checker/tests/mutation_kill_constructors_tests.rs new file mode 100644 index 00000000..f40feca6 --- /dev/null +++ b/crates/basilisk-checker/tests/mutation_kill_constructors_tests.rs @@ -0,0 +1,208 @@ +//! Tests for [CHKARCH-TESTING]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-TESTING +// `mod common` is shared by every checker test binary, so the helpers this one +// does not call are dead code HERE, not unused code — same waiver as +// `mutation_kill_tests.rs`. +#![allow(clippy::allow_attributes, dead_code)] +//! +//! Mutation-killing tests for the metaclass `__call__` half of +//! `calls_argument_count` ([CHKARCH-TESTING-MUTATION-RATCHET]). +//! +//! A class whose metaclass defines `__call__` may never reach `__new__`/ +//! `__init__` at all, so the constructor-arity judgment has to decide who +//! governs the call before it counts a single argument +//! ([metaclass `__call__`](https://typing.python.org/en/latest/spec/constructors.html#metaclass-call-method)). +//! Every test below asserts BOTH directions — the arity error that must fire +//! and the silence that must hold — because a mutant that flips the decision +//! one way is invisible to a suite that only checks the other. + +use basilisk_test_macros::mutation_safe; + +mod common; +use common::run; + +/// A class whose `__new__` demands one argument, instantiated with none. What +/// the metaclass declares decides whether that is an error. +const CALL_WITH_NO_ARGS: &str = "\nclass C(metaclass=Meta):\n def __new__(cls, x: int) -> \"C\":\n return super().__new__(cls)\n\nC()\n"; + +/// Arity diagnostics drawn by `source`. +fn arity_errors(source: &str) -> Result, Box> { + Ok(run(source)? + .iter() + .filter(|d| d.code.code == "calls_argument_count") + .map(|d| d.message.clone()) + .collect()) +} + +/// Assert the constructor call draws exactly one arity error. +fn assert_reports(metaclass: &str, why: &str) -> Result<(), Box> { + let errors = arity_errors(&format!("{metaclass}{CALL_WITH_NO_ARGS}"))?; + assert_eq!(errors.len(), 1, "{why}; got {errors:?}"); + Ok(()) +} + +/// Assert the constructor call is silent — the metaclass governs it. +fn assert_silent(metaclass: &str, why: &str) -> Result<(), Box> { + let errors = arity_errors(&format!("{metaclass}{CALL_WITH_NO_ARGS}"))?; + assert!(errors.is_empty(), "{why}; got {errors:?}"); + Ok(()) +} + +/// Kills `metaclass_passes_through -> true`, `constructs_an_instance -> true`, +/// and both `==` → `!=` mutants in the `__call__` lookup (each of which loses +/// the method and falls back to "passes through"). +/// +/// A `__call__` returning `NoReturn` never yields a `C`, so `__new__` is never +/// evaluated and its signature cannot be violated. +#[mutation_safe( + rule = "calls_argument_count", + fns = "metaclass_passes_through|constructs_an_instance|body_delegates_construction" +)] +#[test] +fn metaclass_call_returning_noreturn_governs_the_call() -> Result<(), Box> { + assert_silent( + "from typing import NoReturn\n\nclass Meta(type):\n def __call__(cls, *args, **kwargs) -> NoReturn:\n raise TypeError('no')\n", + "a metaclass __call__ returning NoReturn never reaches __new__", + ) +} + +/// Kills `metaclass_passes_through -> true` for a concrete foreign return: the +/// call evaluates to an `int`, not to a `C`. +#[mutation_safe( + rule = "calls_argument_count", + fns = "metaclass_passes_through|constructs_an_instance" +)] +#[test] +fn metaclass_call_returning_a_foreign_type_governs_the_call( +) -> Result<(), Box> { + assert_silent( + "class Meta(type):\n def __call__(cls, *args, **kwargs) -> int:\n return 1\n", + "a metaclass __call__ returning int does not construct a C", + ) +} + +/// Kills `metaclass_passes_through -> false`, `constructs_an_instance -> false`, +/// and `==` → `!=` on the `TypeVar` comparison (with `!=`, `T` matches no +/// declared `TypeVar` and the call is wrongly treated as metaclass-governed). +#[mutation_safe( + rule = "calls_argument_count", + fns = "metaclass_passes_through|constructs_an_instance" +)] +#[test] +fn metaclass_call_returning_its_typevar_still_checks_new() -> Result<(), Box> +{ + assert_reports( + "from typing import TypeVar\n\nT = TypeVar(\"T\")\n\nclass Meta(type):\n def __call__(cls: type[T], *args, **kwargs) -> T:\n return type.__call__(cls, *args, **kwargs)\n", + "a `-> T` metaclass __call__ constructs the class, so __new__ governs arity", + ) +} + +/// Kills `||` → `&&` and `==` → `!=` on the `Self` comparison in +/// `constructs_an_instance`: both make a `-> Self` return stop counting as +/// construction. +#[mutation_safe(rule = "calls_argument_count", fns = "constructs_an_instance")] +#[test] +fn metaclass_call_returning_self_still_checks_new() -> Result<(), Box> { + assert_reports( + "from typing import Self\n\nclass Meta(type):\n def __call__(cls, *args, **kwargs) -> Self:\n return type.__call__(cls, *args, **kwargs)\n", + "a `-> Self` metaclass __call__ constructs the class, so __new__ governs arity", + ) +} + +/// Kills `body_delegates_construction -> false`: an UNANNOTATED `__call__` whose +/// body hands the call back to `type.__call__` constructs normally, so stripping +/// the annotations off a metaclass must not silence the arity error +/// ([TYPEINF-TARGET-GRADUAL]). +#[mutation_safe( + rule = "calls_argument_count", + fns = "metaclass_passes_through|body_delegates_construction" +)] +#[test] +fn unannotated_metaclass_call_that_delegates_still_checks_new( +) -> Result<(), Box> { + assert_reports( + "class Meta(type):\n def __call__(cls, *args, **kwargs):\n return type.__call__(cls, *args, **kwargs)\n", + "an unannotated __call__ that delegates constructs normally", + ) +} + +/// Kills `body_delegates_construction -> true` and its `&&` → `||`: an +/// unannotated `__call__` that returns a value of its own is not constructing a +/// `C`, so `__new__` is never consulted. +#[mutation_safe( + rule = "calls_argument_count", + fns = "metaclass_passes_through|body_delegates_construction" +)] +#[test] +fn unannotated_metaclass_call_returning_a_value_governs_the_call( +) -> Result<(), Box> { + assert_silent( + "class Meta(type):\n def __call__(cls, *args, **kwargs):\n return 1\n", + "an unannotated __call__ returning its own value does not construct a C", + ) +} + +/// Kills the `&&` → `||` mutant in `body_delegates_construction`: a body that +/// never returns has NO value-returning statement, and `all()` over nothing is +/// vacuously true — only the emptiness check keeps that from reading as +/// "delegates". +#[mutation_safe( + rule = "calls_argument_count", + fns = "metaclass_passes_through|body_delegates_construction" +)] +#[test] +fn unannotated_metaclass_call_that_only_raises_governs_the_call( +) -> Result<(), Box> { + assert_silent( + "class Meta(type):\n def __call__(cls, *args, **kwargs):\n raise TypeError('no')\n", + "a __call__ that only raises never returns a C", + ) +} + +/// Kills both `&&` → `||` mutants joining the pass-through conditions: a +/// `__call__` that does not forward `*args`/`**kwargs` fixes the call signature +/// itself, so `__new__`'s parameters are not what the caller must satisfy — +/// even though its return type says it constructs the class. +#[mutation_safe(rule = "calls_argument_count", fns = "metaclass_passes_through")] +#[test] +fn metaclass_call_without_kwargs_passthrough_is_not_checked( +) -> Result<(), Box> { + assert_silent( + "from typing import Self\n\nclass Meta(type):\n def __call__(cls, *args) -> Self:\n return type.__call__(cls, *args)\n", + "a __call__ that forwards only *args does not pass the caller's arguments through unchanged", + ) +} + +/// Kills `delete !` and `==` → `!=` in the metaclass-exists guard: a metaclass +/// this module cannot see into could do anything, so the judgment abstains +/// rather than assuming the default `type.__call__`. +#[mutation_safe(rule = "calls_argument_count", fns = "metaclass_passes_through")] +#[test] +fn unresolvable_metaclass_abstains() -> Result<(), Box> { + let errors = arity_errors( + "from elsewhere import Meta\n\nclass C(metaclass=Meta):\n def __new__(cls, x: int) -> \"C\":\n return super().__new__(cls)\n\nC()\n", + )?; + assert!( + errors.is_empty(), + "a metaclass defined outside this module must abstain, not guess; got {errors:?}" + ); + Ok(()) +} + +/// The baseline the whole rule rests on: with no metaclass in play, a +/// constructor call short of `__new__`'s required arguments still reports. A +/// mutant that silences the metaclass path must not be able to hide behind a +/// suite that never checks the ordinary case. +#[mutation_safe(rule = "calls_argument_count", fns = "metaclass_passes_through")] +#[test] +fn plain_class_still_reports_missing_constructor_argument() -> Result<(), Box> +{ + let errors = arity_errors( + "class C:\n def __new__(cls, x: int) -> \"C\":\n return super().__new__(cls)\n\nC()\n", + )?; + assert_eq!( + errors.len(), + 1, + "a plain class must still report its missing __new__ argument; got {errors:?}" + ); + Ok(()) +} diff --git a/crates/basilisk-lsp/src/semantic_tokens.rs b/crates/basilisk-lsp/src/semantic_tokens.rs index 38800196..eefb55c8 100644 --- a/crates/basilisk-lsp/src/semantic_tokens.rs +++ b/crates/basilisk-lsp/src/semantic_tokens.rs @@ -85,14 +85,12 @@ fn push_param_tokens(raw: &mut Vec, param: &ParameterInfo) { /// Check if a function has `@staticmethod` or `@classmethod` decorator. fn has_static_decorator(decorators: &[String]) -> bool { - decorators - .iter() - .any(|d| { - matches!( - d.rsplit('.').next().unwrap_or(d.as_str()), - "staticmethod" | "classmethod" - ) - }) + decorators.iter().any(|d| { + matches!( + d.rsplit('.').next().unwrap_or(d.as_str()), + "staticmethod" | "classmethod" + ) + }) } /// Collect tokens for a single function or method definition. diff --git a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md index 6e717b9c..a1d7b1f2 100644 --- a/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md +++ b/docs/plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md @@ -866,15 +866,107 @@ not run is `[~]`, not `[x]`. **Gates owed by Stage 0.5 as a whole** — run after the boxes above, and again before the stage is declared closed: -- [ ] `cargo test --workspace` green (fail-fast, coverage enforced against +- [x] `cargo test --workspace` green (fail-fast, coverage enforced against `coverage-thresholds.json`). -- [ ] `cargo clippy --workspace --all-targets` clean at the repo's lint level. -- [ ] `python3 conformance/run_conformance.py` — 100% / 0 false positives from + — Green via `scripts/test-rust.sh` (the CI job) and a plain + `cargo test --workspace`: 156 test binaries, 0 failures, per-crate coverage + thresholds enforced. `gradual_guarantee_tests` caught a real hole on the way + (see the metaclass note below) and is green on its own terms, not by + weakening. +- [x] `cargo clippy --workspace --all-targets` clean at the repo's lint level. + — Clean at `-D warnings` with the repo's pedantic lint set. Fixed at source, + never suppressed: `similar_names` (two bindings renamed), `match_same_arms` + (the `Guard` arm folded into `Bool`'s, which is what it means), + `unnecessary_lazy_evaluations`, `bool_to_int_with_if`, `too_many_lines` on + `is_assignable_to` (the `Callable` arm extracted into `callable_assignable` / + `callable_params_assignable`), and a `type_complexity` in the #381 test. +- [x] `python3 conformance/run_conformance.py` — 100% / 0 false positives from a fresh `python/typing@main` clone against a clean `--release` build ([CHKARCH-CONFORMANCE]). -- [ ] Torture golden suite 8/8 (`tests/torture_golden_tests.rs`). + — 141/141, 0 false positives. The gate found SIX regressions this stage had + introduced, each fixed by teaching the checker, never by silencing a rule: + 1. **`aliases_typealiastype`** (2 FP) — the legacy textual alias matcher + scooped up `X = TypeAliasType("X", body, ...)` and matched values against + the CALL text, so every valid use of such an alias failed. `alias_rhs_text` + now excludes them structurally (`module.type_alias_type_calls`); they + resolve through the cascade like every other alias. + 2. **`narrowing_typeguard` / `narrowing_typeis`** (4 FP) — with `Guard` a + first-class type, `return False` in a guard function was "bool is not + assignable to `TypeGuard[int]`". `is_assignable_to` now carries the three + PEP 647/742 relations: guard-to-guard FIRST (TypeGuard covariant, TypeIs + invariant, never across forms), guard-to-anything as `bool`, and + anything-to-guard as the bool the body returns. + 3. **`narrowing_typeis`** (1 missed) — narrowing `list[object]` to + `list[int]` must fail, but `object` was collapsed into `Any` by the + cascade, making `list[object]` and `list[Any]` indistinguishable in an + invariant position. `object` is now the real top-type leaf it always was; + `is_assignable_to` keeps its accept-everything posture in BOTH directions + so nothing else moved. + 4. **`constructors_call_metaclass`** (2 FP) — #381 made `Class1()` inside + `assert_type(...)` visible, and the metaclass check only ever tested for + `*args, **kwargs`. It now implements the return-type half its own doc + comment promised: `Self`/TypeVar constructs, `NoReturn` / `int | Meta` + means the metaclass governs. An UNANNOTATED `__call__` is decided from its + BODY (does it delegate the construction?) so the judgment survives + [TYPEINF-TARGET-GRADUAL] — stripping a metaclass's annotations must not + turn a silent call into an error, which is exactly what + `gradual_guarantee_tests` caught. + 5. **`typeforms_typeform`** (5 missed) — a BARE `TypeForm` resolved to a + plain name, so `x: TypeForm = ` never reached the type-expression + validator at all. It is `TypeForm[Any]` (PEP 747), for the same reason a + bare `Callable` is `Callable[..., Any]`. + 6. **`callables_annotation`** (3 missed) — `Concatenate` was unmodelled, so + `Callable[Concatenate[int, P], str]` accepted anything. The cascade now + produces the prefix plus an explicit gradual-tail marker + (`types::gradual_params` / `split_gradual`), which also makes + `Callable[[], R]` (takes NO parameters) distinguishable from + `Callable[..., R]` for the first time — the empty list used to mean both. +- [x] Torture golden suite 8/8 (`tests/torture_golden_tests.rs`). + — 8/8 (`param_inference`, `typeis_narrowing`, `enum_literal_expansion`, + `tuple_index`, `recursive_aliases`, `generic_constructor`, + `paramspec_decorator`, `recursive_bases`). - [ ] `make bench` — no fixture slower than the committed baseline - ([CHKARCH-TESTING-BENCH-RATCHET]). + ([CHKARCH-TESTING-BENCH-RATCHET]). **STILL RED — the one gate this stage has + not met.** The stage's first `make bench` run failed on EVERY fixture, +2.0% + to +82.4%. Bisected to the branch, not to this stage's boxes: `da742832` + (main) checks `aliases_type_statement` in 8.9 ms, `84a7661e` (this branch, + 2026-08-03) in 15.8 ms; the Stage 0.5 work added ~2% on top of that. It went + unseen because nothing ran the gate — there was no CI job for it until this + stage added one (`bench` in `.github/workflows/ci.yml`, wired to its own + change scope so `benchmarks/**` edits re-run it too). + + Four fixes so far, each restructuring rather than reverting, with conformance + re-verified at 141/141 + 0 FP after every one: + 1. `aliases_type_statement` re-parsed every `type X = rhs` RHS from source + text and rebuilt a per-statement `HashSet`. It now reads the RHS node out + of the module's already-parsed AST (indexed by the span the resolver + recorded) and resolves parameter shadowing at the leaf: `O(n + m)`, not + `O(n * m)`. Worst fixture 17.0 ms → 10.9 ms. + 2. `narrowing_typeguard`, `narrowing_typeis_2` and the assignment / + redundant-annotation rules resolved annotations by slicing text and + re-parsing it; they now use `resolve_span`, the indexed-node seam the + spec already told callers to prefer. + 3. FOURTEEN rules each built their own `AnnotationResolver` — two full AST + walks apiece, ~13% of runtime, and entirely new on this branch (the + baseline has zero such call sites). The driver now builds one per module + and hands it to rules through a defaulted `Rule::check_with_annotations`, + so the rule registry and the other ~150 rules are untouched. + 4. `AnnotationResolver` memoises resolution BY SPAN: one function's return + annotation is asked about by both narrowing rules and both + return-compatibility rules, and the cascade is pure. + + Result: worst fixture +82.4% → **+8.5%**, average ~+22% → **~+5%**. Still + RED — the ratchet's tolerance is zero and 25 of 26 fixtures remain above + baseline. What is left is not waste: the rule SET barely changed (167 vs 166 + registered), so the residual is the annotation cascade doing real work inside + existing rules plus #381's call collection in every expression position. + Closing it means making the cascade itself cheaper (type interning / fewer + allocations) or buying the margin back elsewhere — a sized piece of work, not + a cleanup, and it must land before this stage can be declared closed. + + The measured numbers are already in `benchmarks/status/.csv` + (write-always); the gate reads the COMMITTED baseline from git, so nothing is + laundered by that file. ### Stage 1 — incrementality diff --git a/docs/readme/README.src.md b/docs/readme/README.src.md index a5e547e1..9d561c7f 100644 --- a/docs/readme/README.src.md +++ b/docs/readme/README.src.md @@ -61,11 +61,11 @@ And it is the **fastest checker we’ve measured** — median cold full- | Type checker | Median cold check | | --- | --- | | ⚡ **Basilisk** | **11 ms** | -| zuban | 28 ms | +| zuban | 27 ms | | ty | 39 ms | | Pyrefly | 110 ms | -| Pyright | 563 ms | -| mypy | 583 ms | +| Pyright | 572 ms | +| mypy | 586 ms | Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~5 ms. Every figure is produced by [`hyperfine`](https://github.com/sharkdp/hyperfine) and committed per machine, so nothing here is hand-typed. **Clone the repo, run `make bench` on your own hardware, and send us the CSV — independent audits are welcome.** [Full benchmarks & methodology →](https://www.basilisk-python.dev/docs/benchmarks/) diff --git a/docs/readme/README.zh.src.md b/docs/readme/README.zh.src.md index e0faa7dc..33542cdb 100644 --- a/docs/readme/README.zh.src.md +++ b/docs/readme/README.zh.src.md @@ -58,11 +58,11 @@ Basilisk 是**唯一**在官方 | 类型检查器 | 冷检查中位数 | | --- | --- | | ⚡ **Basilisk** | **11 ms** | -| zuban | 28 ms | +| zuban | 27 ms | | ty | 39 ms | | Pyrefly | 110 ms | -| Pyright | 563 ms | -| mypy | 583 ms | +| Pyright | 572 ms | +| mypy | 586 ms | 在 Apple M4 Max 上对 26 个单一构造的类型规范压力用例测得的整文件冷检查中位数 — 越低越好。Basilisk 的热重检查可降至约 5 ms。每个数字都由 [`hyperfine`](https://github.com/sharkdp/hyperfine) 产生并按机器提交，没有一个是手写的。**克隆仓库，在你自己的硬件上运行 `make bench`，并把 CSV 发给我们 — 欢迎独立复核。** [完整基准与方法论 →](https://www.basilisk-python.dev/zh/docs/benchmarks/) diff --git a/docs/specs/CHECKER-ARCHITECTURE-SPEC.md b/docs/specs/CHECKER-ARCHITECTURE-SPEC.md index f5246ff2..ee768628 100644 --- a/docs/specs/CHECKER-ARCHITECTURE-SPEC.md +++ b/docs/specs/CHECKER-ARCHITECTURE-SPEC.md @@ -1615,12 +1615,29 @@ never suppress the other (`benchmarks/summarize.py`): optimised or restructured. A machine without a baseline establishes one only after a successful run is committed. -> **Planned — bench in the pipeline (CI).** Today `make bench` is run locally and -> its results are committed. The intention is to eventually run the benchmark gate -> in CI on a fixed runner class, on the same write-always / gate-separately -> discipline described here, so a performance regression fails the pipeline the way -> the conformance and coverage gates already do. Until that lands, the discipline -> is enforced by running `make bench` locally and committing the updated status CSV. +**Bench in the pipeline (CI).** The gate is a blocking CI job — `bench` +("Benchmark Ratchet") in `.github/workflows/ci.yml` — running `make bench` under +exactly the write-always / gate-separately discipline described above, so a +performance regression fails the pipeline the way the conformance and coverage +gates already do. Three properties make the job honest: + +- **Fixed runner class.** Pinned to the standard `ubuntu-24.04` image, never the + opt-in big runner. The machine slug is derived from `RUNNER_OS`/`RUNNER_ARCH` + (`gha-linux-x64`), so a job that drifted onto different hardware would compare + two machines' times under one baseline. +- **Its own change scope.** The job runs when the `changes` classifier sets + `bench` — any core change (the checker speed it defends) **or** any + `benchmarks/**` change (fixtures, `run.sh`, `summarize.py`, the status CSVs), + which are not core Rust and would otherwise let the harness change without the + gate ever running. +- **Nothing relaxed for CI.** `run.sh` rejects `BENCH_NO_GATE` / + `BENCH_REGRESS_PCT` / `BENCH_TOLERANCE_PCT` and exits 2 on the basilisk-only + mode under `GITHUB_ACTIONS`, so the CI run is always the full sweep at zero + tolerance. + +Locally the same command is the same gate; developers still run `make bench` and +commit the updated status CSV, which is what advances the baseline (in CI, as +locally, a machine with no committed baseline establishes one instead of failing). ### CI Artifact Storage Policy {#GITHUB-NO-ARTIFACTS} diff --git a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md index 62e6a88d..f6730ef9 100644 --- a/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md +++ b/docs/specs/CHECKER-TYPE-INFERENCE-SPEC.md @@ -725,7 +725,30 @@ def f(val: int | str) -> None: reveal_type(val) # int — complement narrowing ``` -> **Authority**: [PEP 742](https://peps.python.org/pep-0742/). +**The guard type itself.** `TypeGuard[T]` and `TypeIs[T]` are one modelled type, +`InferredType::Guard { type_is, inner }`, produced by the cascade so aliases +expand through them. `is_assignable_to` gives it three relations, guard-to-guard +tested FIRST so the two forms never collapse into each other: + +| Relation | Holds when | Why | +|---|---|---| +| `TypeGuard[B]` <: `TypeGuard[A]` | `B` <: `A` | `TypeGuard` is covariant in its argument | +| `TypeIs[B]` <: `TypeIs[A]` | `B` IS `A` | "Unlike `TypeGuard`, `TypeIs` is invariant in its argument type" | +| across the two forms | never | "`TypeIs` and `TypeGuard` are not compatible with each other" | +| `Guard` <: `X` | `bool` <: `X` | in these contexts a guard "is treated as a subtype of `bool`", so `Callable[..., TypeIs[int]]` satisfies `Callable[..., bool]` but never `Callable[..., str]` | +| `X` <: `Guard` | `X` <: `bool` | the body of a narrowing function returns an ordinary bool (`return False`) | + +**Consistency precondition.** `TypeIs[X]` additionally requires `X` to be +consistent with the input parameter type — judged on RESOLVED types through +`SubtypingContext`, three-valued, abstaining when either side is not grounded +(`rules/narrowing_typeis_2.rs`). Invariant container positions are compared in +BOTH directions, which is why `object` must stay distinct from `Any` +([TYPEINF-SUBTYPING-NOMINAL](#TYPEINF-SUBTYPING-NOMINAL)): narrowing +`list[object]` to `list[int]` is an error, narrowing `list[Any]` is not. + +> **Authority**: [PEP 742](https://peps.python.org/pep-0742/), +> [PEP 647](https://peps.python.org/pep-0647/), +> [Typing spec — TypeIs](https://typing.python.org/en/latest/spec/narrowing.html#typeis). ### [TYPEINF-NARROWING-ASSERT] `assert` Narrowing {#TYPEINF-NARROWING-ASSERT} @@ -806,7 +829,13 @@ model remains tracked by The single home for this judgment is `crates/basilisk-checker/src/subtyping.rs` — `name_subtype` encodes the full `bool <: int <: float <: complex` chain, `SubtypingContext` is the judgment every consumer must go through, and the accepted/rejected table is pinned in `tests/subtyping_context_tests.rs` ([NARROWPLAN-SUBTYPING](../plans/CHECKER-TYPE-NARROWING-INFERENCE-PLAN.md#NARROWPLAN-SUBTYPING)). The rule-local delegates still calling `name_subtype` directly (`rules/shared.rs::is_numeric_subtype` and the helpers in `narrowing_typeis`, `narrowing_typeis_2`, `overloads_evaluation`, `generics_typevartuple_callable`, `aliases_implicit`, `generics_syntax_scoping`, `callables_subtyping`, `generics_defaults_referential`) are legacy shims on the demolition list ([TYPEINF-LEGACY](#TYPEINF-LEGACY)); the `types_parsing.rs` fold of `complex` into `Float` is a legacy-parser artifact that dies with that parser. One subtyping implementation — not two layers. **Other builtin relations:** -- All classes <: `object` (`object` parses to the `Any` escape hatch for assignment purposes). +- All classes <: `object`. The cascade resolves `object` to the named TOP type, not to `Any`: + it accepts every value as a target and is accepted everywhere as a source (the gradual + posture the `Any` spelling used to provide), but it stays a DISTINCT name so an invariant + judgment can tell `list[object]` from `list[Any]` — narrowing the former to `list[int]` is an + error the typing spec requires, while the latter is consistent with anything + ([TYPEINF-NARROWING-TYPEIS](#TYPEINF-NARROWING-TYPEIS)). The legacy `types_parsing.rs` string + parser still folds it into `Any`, and dies with that parser. - `Never` <: everything (bottom type). - There is **no** `bytearray <: bytes` promotion: the [current typing spec](https://typing.python.org/en/latest/spec/special-types.html#special-cases-for-float-and-complex) defines promotions only for `float`/`complex` (the historical `bytes` shorthand was removed), and no conformance test requires it. `bytearray` parses to `Named("bytearray")` and is assignable essentially only to itself, `object`, and `Any`. @@ -897,7 +926,8 @@ y: Sequence[Animal] = dogs # OK — Sequence is covariant - `Optional[T]` = `T | None` - `Any` is bidirectionally compatible with all types (not a real subtype, an escape hatch) - `Never` <: everything (bottom type, assignable to all types) -- the simplified annotation parser treats `object` as a gradual `Any` spelling +- the simplified annotation parser treats `object` as a gradual `Any` spelling; the cascade + keeps it as the named top type (see the builtin relations above) - **Enum literal expansion**: an enum type with members is equivalent to the union of literals of all its members, so `Answer` <: `Literal[Answer.Yes, Answer.No]` exactly when `Yes`/`No` are ALL of `Answer`'s members; a partial member union is not a supertype. Membership follows the `Enum` metaclass's own rules: unannotated class-body value assignments, excluding sunder/dunder names and `nonmember`/descriptor/lambda values. Implemented by `rules/assignment_compatibility/enum_expand.rs`. > **Authority**: [Typing spec — Enums](https://typing.python.org/en/latest/spec/enums.html). @@ -923,6 +953,15 @@ g: Callable[[Dog], Animal] # accepts Dog, returns Animal - Source may have fewer required parameters than target (extra defaults OK). - `*args`/`**kwargs` in source accepts any parameter count in target. - `Callable[..., R]` (ellipsis params) is compatible with any parameter signature. +- **A gradual tail is not the same as no parameters.** `CallableInfo.param_types` + ends with the `types::GRADUAL_PARAMS` marker (`types::gradual_params` builds + it, `types::split_gradual` reads it) whenever the tail is unconstrained: + `Callable[..., R]`, a bare `ParamSpec`, and PEP 612 + `Callable[Concatenate[int, P], R]` — which pins `int` as a REQUIRED leading + position and leaves the rest gradual. An EMPTY list therefore means a callable + that takes no parameters at all (`Callable[[], R]`), which is what lets + `Concatenate[int, P]` reject a zero-argument callable instead of silently + accepting it. > **Authority**: [PEP 484 §Callable](https://peps.python.org/pep-0484/#callable), [Typing spec — Callables](https://typing.readthedocs.io/en/latest/spec/callables.html) @@ -949,9 +988,12 @@ Nominal MRO walking and structural Protocol/TypedDict compatibility are decided ### [TYPEINF-SPECIAL-ANY] `Any` {#TYPEINF-SPECIAL-ANY} `Any` is bidirectionally compatible with all types. It arises from explicit -`Any` and from typing-defined gradual spellings such as `object` and bare -generics in the simplified annotation parser; it is never the fallback for a -failed expression inference (that sentinel is `Unknown`). Unannotated +`Any` and from typing-defined gradual spellings such as bare generics in the +simplified annotation parser; it is never the fallback for a failed expression +inference (that sentinel is `Unknown`). `object` is NOT one of those spellings +in the cascade — it is the named top type, which accepts everything without +erasing the distinction between `object` and `Any` (see +[TYPEINF-SUBTYPING-NOMINAL](#TYPEINF-SUBTYPING-NOMINAL)). Unannotated parameters do not silently become explicit `Any`; the opt-in annotation policy may report `BSK-0001`. diff --git a/mutation_testing/mutants_report.html b/mutation_testing/mutants_report.html index ee709c0a..e8c81c48 100644 --- a/mutation_testing/mutants_report.html +++ b/mutation_testing/mutants_report.html @@ -62,7 +62,7 @@

Basilisk Mutation Report cargo-mutants v27.1.0

-
2026-08-02T08:34:40.287272Z → 2026-08-02T09:26:46.50831Z
+
2026-08-04T14:43:04.513697Z → 2026-08-04T16:19:36.824203Z
@@ -71,7 +71,7 @@

Basilisk Mutation Report cargo-mutants v27.1.0

Mutation Score
-
145
+
161
Total Mutants
@@ -79,7 +79,7 @@

Basilisk Mutation Report cargo-mutants v27.1.0

Missed
-
138
+
154
Caught
@@ -94,7 +94,7 @@

Basilisk Mutation Report cargo-mutants v27.1.0

Missed (0)
-
Caught (138)
+
Caught (154)
Other (7)
@@ -116,7 +116,7 @@

Basilisk Mutation Report cargo-mutants v27.1.0

crates/basilisk-checker/src/context.rs:59:13 CheckContext::from_config_with_source -> Self StructField - 63.1s + 64.3s
▶ show diff
@@ -147,7 +147,7 @@

Basilisk Mutation Report cargo-mutants v27.1.0

crates/basilisk-checker/src/rules/aliases_implicit.rs:61:5 collect_type_alias_names -> Vec FnValue vec![] - 70.6s + 120.9s
▶ show diff
@@ -203,13 +203,13 @@

Basilisk Mutation Report cargo-mutants v27.1.0

CAUGHT crates/basilisk-checker/src/rules/aliases_implicit.rs:61:5 collect_type_alias_names -> Vec FnValue - vec!["xyzzy".into()] - 60.8s + vec![String::new()] + 63.5s
▶ show diff
CAUGHT - crates/basilisk-checker/src/rules/aliases_implicit.rs:63:24 - collect_type_alias_names -> Vec BinaryOperator - == - 57.6s + crates/basilisk-checker/src/incremental_defs.rs:600:9 + narrowed_uses -> Vec StructField + + 164.7s
▶ show diff
-
@@ -5135,11 +5679,11 @@

Basilisk Mutation Report cargo-mutants v27.1.0

crates/basilisk-checker/src/rules/match_exhaustiveness.rs:48:5 make_diagnostic -> Diagnostic FnValue Default::default() - 5.9s + 6.1s -
▶ show diff
-