Offline typeshed: store-backed pins, a segregated download crate, and checking that never fetches

.devcontainer/Dockerfile

@@ -1,6 +1,7 @@
-# Dev container matching CI (GitHub Actions ubuntu-22.04-8-cores + dtolnay/rust-toolchain@stable)
-# Pin Rust to match CI's stable channel — this is the critical version.
-# 1.96.0 = current stable on the CI runners; 1.94 fails the workspace build
+# Dev container matching CI (.github/workflows/ci.yml — every job runs on
+# ubuntu-24.04, or vars.BIG_RUNNER, with dtolnay/rust-toolchain@stable).
+# CI resolves `stable` at run time; this image pins the concrete release so a
+# container rebuild is reproducible. 1.94 fails the workspace build
 # (sysinfo 0.39.3 requires rustc >= 1.95).
 FROM rust:1.96.0-bookworm
 
@@ -29,28 +30,41 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libdbus-1-3 \
     && rm -rf /var/lib/apt/lists/*
 
-# Python 3.12 (matches CI: actions/setup-python@v5 with python-version: "3.12")
+# Python. CI pins 3.12 (actions/setup-python@v6 with python-version: "3.12");
+# this base image is Debian bookworm, whose `python3` is 3.11. That is the one
+# knowingly unsynced version here — the interpreters are NOT identical, so a
+# green container run is not proof of the CI matrix.
 RUN apt-get update && apt-get install -y --no-install-recommends \
     python3 \
     python3-pip \
     python3-venv \
     && rm -rf /var/lib/apt/lists/*
 
-# Node 20 (matches CI: actions/setup-node@v4 with node-version: 20)
-RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
-    && apt-get install -y --no-install-recommends nodejs=20.* \
+# Node 22 (matches CI: actions/setup-node@v6 with node-version 22.x in the
+# `VS Code Extension` and `Shipwright Binary Gate` jobs — the ones this container
+# reproduces through `make test` / `make build`. Only the website-build job,
+# which this image does not run, pins Node 20.)
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs=22.* \
     && rm -rf /var/lib/apt/lists/*
 
-# Rust components (matches CI: dtolnay/rust-toolchain@stable with components)
-RUN rustup component add rustfmt clippy
+# Rust components + targets (matches CI: dtolnay/rust-toolchain@stable with
+# `rustfmt, clippy` in Lint, `llvm-tools-preview` in Rust Tests & Coverage — the
+# component cargo-llvm-cov needs — and the wasm32-wasip2 target in Zed Extension)
+RUN rustup component add rustfmt clippy llvm-tools-preview \
+    && rustup target add wasm32-wasip2
 
 # Rust cargo tools (pinned)
 RUN cargo install cargo-llvm-cov --version 0.8.4 --locked \
     && cargo install cargo-audit --version 0.22.2 --locked
 
 # Python packages (pinned — ruff MUST match CI and the ruff_* crate tag in
-# Cargo.toml: pip install debugpy ruff==0.15.17)
-RUN pip install --break-system-packages debugpy==1.8.14 ruff==0.15.17
+# Cargo.toml). pytest drives the Neovim e2e harness (scripts/test-nvim.sh) and is
+# pinned to CI's version; jinja2/markdown/tomlkit are the REAL python/typing
+# conformance harness's own runtime deps, installed unpinned exactly as CI does.
+RUN pip install --break-system-packages \
+        debugpy==1.8.14 ruff==0.15.17 pytest==9.1.1 \
+        jinja2 markdown tomlkit
 
 # GitHub CLI (for PR creation, issue management)
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
@@ -66,15 +80,50 @@ RUN curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh |
 # Claude Code CLI
 RUN npm install -g @anthropic-ai/claude-code
 
+# Lua coverage for the Neovim suite. CI runs `luarocks install --local luacov`
+# into the runner's HOME; installing it system-wide here puts it on the default
+# LUA_PATH, so `make _test_nvim` finds it without an `eval "$(luarocks path)"`.
+RUN apt-get update && apt-get install -y --no-install-recommends luarocks \
+    && luarocks install luacov \
+    && rm -rf /var/lib/apt/lists/*
+
 # Match CI environment variables
 ENV CARGO_TERM_COLOR=always
 ENV RUSTFLAGS="-D warnings"
 
-# Create a non-root user so Claude Code can use --dangerously-skip-permissions
+# Create a non-root user so Claude Code can use --dangerously-skip-permissions.
+# It is created BEFORE the Homebrew bootstrap below because Homebrew refuses to
+# install as root and its installer expects passwordless sudo.
 RUN useradd -m -s /bin/bash -u 1000 dev \
     && mkdir -p /workspace \
-    && chown -R dev:dev /workspace /usr/local/cargo /usr/local/rustup
+    && chown -R dev:dev /workspace /usr/local/cargo /usr/local/rustup \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends sudo git procps file build-essential \
+    && echo 'dev ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/dev \
+    && chmod 0440 /etc/sudoers.d/dev \
+    && rm -rf /var/lib/apt/lists/*
 
 USER dev
 
+# Homebrew — the package manager scripts/install-deslop.sh drives, and the one
+# the CI Lint job uses to install the deslop gate. That script relies on the
+# runner already having brew; a Debian image has to bootstrap it.
+RUN NONINTERACTIVE=1 /bin/bash -c \
+    "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+ENV PATH="/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:${PATH}"
+
+# Neovim — `make test` runs the basilisk.nvim e2e suite (`make _test_nvim`) and
+# scripts/audit.sh gates on it. basilisk.nvim requires 0.11+ (its health.lua
+# hard-errors below that, and lua/basilisk/lsp.lua uses the 0.11-only
+# vim.lsp.config/vim.lsp.enable); CI covers that floor and nightly via
+# rhysd/action-setup-vim. Debian bookworm's nvim predates 0.11, so it comes from
+# brew here — audit.sh re-verifies the floor before the suite runs either way.
+RUN brew install neovim
+
+# deslop duplication gate — `make lint` runs it ([CI-DESLOP]). Installed with the
+# repo's own script, byte-for-byte the step the CI Lint job runs, so the CLI here
+# is the same latest release CI gates on.
+COPY --chown=dev:dev scripts/install-deslop.sh /tmp/install-deslop.sh
+RUN bash /tmp/install-deslop.sh && rm /tmp/install-deslop.sh
+
 WORKDIR /workspace

.github/workflows/ci.yml

@@ -99,8 +99,12 @@ jobs:
               website/*|benchmarks/status/*|crates/basilisk-checker/src/rules/*) website=true ;;
               # The conformance score + graded python/typing commit are stamped
               # into these by scripts/gen_conformance_reference.py — editing
-              # them re-runs the website job's stamp drift guard.
-              README.md|README.zh.md|docs/specs/CHECKER-ARCHITECTURE-SPEC.md) website=true ;;
+              # them re-runs the website job's stamp drift guard. The published
+              # READMEs are generated from docs/readme/ ([README]), so touching
+              # a source OR a generated copy must re-run that guard too.
+              docs/readme/*|docs/specs/CHECKER-ARCHITECTURE-SPEC.md) website=true ;;
+              README.md|README.zh.md|README-pypi.md) website=true ;;
+              vscode-extension/README.md|vscode-extension/README.zh.md) website=true ;;
             esac
             # Route each changed path to the NARROWEST code scope that needs it.
             # Pure docs / static site / benchmark tooling / CI YAML never reach a
@@ -174,11 +178,14 @@ jobs:
           diff -u website/src/_data/rules.json /tmp/rules.json \
             || { echo "::error::rules.json is stale — run: python3 scripts/gen_rules_reference.py --data"; exit 1; }
 
-      # The README/spec quote the live score + graded python/typing commit,
-      # stamped by scripts/gen_conformance_reference.py on every scorer run;
-      # fail if the committed text drifted from conformance_report.json so a
-      # quoted commit can never go stale ([CHKARCH-CONFORMANCE]).
-      - name: Check stamped conformance references are in sync with the report
+      # The README source/spec quote the live score + graded python/typing
+      # commit, stamped by scripts/gen_conformance_reference.py on every scorer
+      # run; fail if the committed text drifted from conformance_report.json so
+      # a quoted commit can never go stale ([CHKARCH-CONFORMANCE]). The same
+      # command then verifies that every published README still renders from
+      # docs/readme/ unchanged ([README-DRIFT]) — GitHub, the VSIX (Marketplace
+      # AND Open VSX), and PyPI cannot drift apart or be edited in place.
+      - name: Check stamped conformance references and generated READMEs
         run: python3 scripts/gen_conformance_reference.py --check
 
       - name: Build site
@@ -548,9 +555,13 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install pytest and luarocks
+      - name: Install pytest, debugpy and luarocks
         run: |
-          pip install pytest==9.1.1
+          # debugpy is a real dependency of this job, not a nicety: the
+          # tests/dap specs drive basilisk's debug adapter end to end, and
+          # without it every one of them fails with "debugpy not found".
+          # Pinned to the same version as test-vscode and the devcontainer.
+          pip install pytest==9.1.1 debugpy==1.8.14
           sudo apt-get install -y luarocks
           luarocks install --local luacov
 

CLAUDE.md

@@ -166,7 +166,7 @@ Strict-by-default Python type checker and comprehensive LSP built in **Rust**. O
 - **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.
-- **Parallelism**: Rayon (work-stealing, file-level)
+- **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
 
 ## Migration to `lspkit`

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "crates/basilisk-checker",
     "crates/basilisk-cli",
     "crates/basilisk-stubs",
+    "crates/basilisk-typeshed-fetch",
     "crates/basilisk-config",
     "crates/basilisk-lsp",
     "crates/basilisk-mojo",
@@ -73,6 +74,7 @@ basilisk-checker  = { path = "crates/basilisk-checker" }
 basilisk-lsp      = { path = "crates/basilisk-lsp" }
 basilisk-compiler = { path = "crates/basilisk-compiler" }
 basilisk-stubs      = { path = "crates/basilisk-stubs" }
+basilisk-typeshed-fetch = { path = "crates/basilisk-typeshed-fetch" }
 basilisk-config     = { path = "crates/basilisk-config" }
 basilisk-common     = { path = "crates/basilisk-common" }
 basilisk-buildinfo  = { path = "crates/basilisk-buildinfo" }

Makefile

@@ -94,7 +94,7 @@ test: _audit
 	echo -e '\n\033[0;32m✓ All tests passed.\033[0m'
 
 ## lint: Run all linters/analyzers (read-only). Does NOT format.
-lint: _lint_rust _lint_vsix _lint_deslop
+lint: _lint_rust _lint_vsix _lint_deslop _lint_docs
 
 ## fmt: Format all code in-place
 fmt: _fmt_rust _fmt_python _fmt_vsix
@@ -396,6 +396,7 @@ _lint_rust:
 	cargo check --workspace --all-targets && \
 	cargo clippy --workspace --all-targets -- -D warnings && \
 	cargo audit && \
+	bash scripts/check-dependency-shape.sh && \
 	echo -e '\033[0;32m✓ Rust lint passed\033[0m'
 
 _lint_vsix:
@@ -411,6 +412,19 @@ _lint_deslop:
 	deslop . && \
 	echo -e '\033[0;32m✓ Deslop duplication gate passed\033[0m'
 
+# Generated-documentation drift gates. The published READMEs (GitHub, the VSIX
+# on both Marketplace and Open VSX, PyPI) are rendered from docs/readme/
+# ([README]), and the diagnostic reference data is generated from the checker
+# rule sources ([WEBSITE-ERROR-PAGES-DRIFT]) — editing either output by hand,
+# or editing a source without regenerating, fails here as it does in CI.
+_lint_docs:
+	@echo -e '\033[1m\033[0;36m▶ Checking generated documentation\033[0m' && \
+	python3 scripts/gen_readmes.py --check && \
+	python3 scripts/gen_rules_reference.py --data /tmp/basilisk-rules.json && \
+	diff -u website/src/_data/rules.json /tmp/basilisk-rules.json > /dev/null || \
+		{ echo 'rules.json is stale — run: python3 scripts/gen_rules_reference.py --data'; exit 1; } && \
+	echo -e '\033[0;32m✓ Generated documentation is in sync\033[0m'
+
 _fmt_rust:
 	@echo -e '\033[1m\033[0;36m▶ Formatting Rust\033[0m' && \
 	cargo fmt --all && \