> {
use basilisk_stubs::typeshed::source::StatusWarning;
use basilisk_stubs::typeshed::warning::{TypeshedWarning, UnpinnedKind};
let mut status = basilisk_stubs::typeshed::bundle::bundled_snapshot()?.status;
status.warnings = StatusWarning::list(&[
- TypeshedWarning::DownloadFailed {
- bundled_sha: status
- .commit
- .ok_or("bundled status is missing its commit identity")?
- .to_hex(),
- },
- TypeshedWarning::Unpinned(UnpinnedKind::LatestOrBundled),
- TypeshedWarning::Unverified,
+ TypeshedWarning::LicenseChanged,
+ TypeshedWarning::UserManaged,
+ TypeshedWarning::Unpinned(UnpinnedKind::CustomFolder),
]);
let capture = Capture::default();
let subscriber = tracing_subscriber::fmt()
@@ -325,16 +317,15 @@ mod tests {
let stderr = capture.text()?;
assert!(stderr.contains("typeshed source status"), "{stderr}");
- assert!(stderr.contains("signed_release=false"), "{stderr}");
let unpinned = stderr.find("warning_code=\"UNPINNED\"");
- let failed = stderr.find("warning_code=\"DOWNLOAD FAILED\"");
- let unverified = stderr.find("warning_code=\"UNVERIFIED\"");
+ let user_managed = stderr.find("warning_code=\"USER-MANAGED SOURCE\"");
+ let license = stderr.find("warning_code=\"LICENSE CHANGED\"");
assert!(
unpinned
- .zip(failed)
- .zip(unverified)
+ .zip(user_managed)
+ .zip(license)
.is_some_and(|((first, second), third)| first < second && second < third),
- "Latest fallback warnings must remain loud and canonical: {stderr}"
+ "status warnings must stay loud and in canonical order: {stderr}"
);
Ok(())
}
diff --git a/crates/basilisk-cli/src/stubs.rs b/crates/basilisk-cli/src/stubs.rs
index e29766b9..c7c868ea 100644
--- a/crates/basilisk-cli/src/stubs.rs
+++ b/crates/basilisk-cli/src/stubs.rs
@@ -297,16 +297,19 @@ pub(super) fn find_package_source(package: &str, python_path: &Path) -> Option u8 {
let project_root = crate::pipeline::find_project_root(Path::new("."));
- let cache_dir = project_root.join(generate::cache::DEFAULT_CACHE_DIR);
+ print_status(&project_root.join(generate::cache::DEFAULT_CACHE_DIR))
+}
+
+fn print_status(cache_dir: &Path) -> u8 {
if !cache_dir.exists() {
println!("No generated stubs found ({})", cache_dir.display());
return 0;
}
- let modules: Vec = walkdir::WalkDir::new(&cache_dir)
+ let modules: Vec = walkdir::WalkDir::new(cache_dir)
.into_iter()
.filter_map(Result::ok)
.filter(|entry| entry.file_type().is_file())
- .filter_map(|entry| stub_module_name(entry.path(), &cache_dir))
+ .filter_map(|entry| stub_module_name(entry.path(), cache_dir))
.collect();
for module in &modules {
println!(" {} {module}", "✓".green());
@@ -334,3 +337,78 @@ fn stub_module_name(path: &Path, cache_dir: &Path) -> Option {
.join(".")
})
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ /// [STUBRES-AUTOGEN]: `stubs status` succeeds whether or not anything was
+ /// ever generated — an empty project is a clean report, not an error.
+ #[test]
+ fn status_reports_cleanly_with_and_without_generated_stubs(
+ ) -> Result<(), Box> {
+ let project = tempfile::tempdir()?;
+ let cache_dir = project.path().join(generate::cache::DEFAULT_CACHE_DIR);
+ assert_eq!(print_status(&cache_dir), 0, "missing cache dir is clean");
+
+ std::fs::create_dir_all(cache_dir.join("pkg"))?;
+ assert_eq!(print_status(&cache_dir), 0, "empty cache dir is clean");
+
+ std::fs::write(cache_dir.join("pkg").join("mod.pyi"), "x: int\n")?;
+ std::fs::write(cache_dir.join("notes.txt"), "not a stub\n")?;
+ assert_eq!(print_status(&cache_dir), 0, "generated stubs list cleanly");
+ Ok(())
+ }
+
+ /// Stub paths render as dotted module names relative to the cache root;
+ /// non-`.pyi` files are not stubs.
+ #[test]
+ fn stub_module_names_are_dotted_and_cache_relative() {
+ let cache = Path::new("/cache");
+ assert_eq!(
+ stub_module_name(Path::new("/cache/pkg/mod.pyi"), cache),
+ Some("pkg.mod".to_owned())
+ );
+ assert_eq!(
+ stub_module_name(Path::new("elsewhere/solo.pyi"), cache),
+ Some("elsewhere.solo".to_owned())
+ );
+ assert_eq!(stub_module_name(Path::new("/cache/notes.txt"), cache), None);
+ assert_eq!(
+ stub_module_name(Path::new("/cache/no_extension"), cache),
+ None
+ );
+ }
+ /// The three CLI mode spellings map one-to-one onto generator modes.
+ #[test]
+ fn generation_mode_arguments_map_to_generator_modes() {
+ assert!(matches!(
+ StubGenMode::from(StubGenModeArg::Runtime),
+ StubGenMode::Runtime
+ ));
+ assert!(matches!(
+ StubGenMode::from(StubGenModeArg::Ast),
+ StubGenMode::Ast
+ ));
+ assert!(matches!(
+ StubGenMode::from(StubGenModeArg::Hybrid),
+ StubGenMode::Hybrid
+ ));
+ }
+
+ /// [STUBRES-AUTOGEN]: contradictory or empty selections are rejected
+ /// before any interpreter or filesystem work happens.
+ #[test]
+ fn generation_target_selection_rejects_contradictory_requests() {
+ let root = Path::new("/nonexistent-project-root");
+ let python = Path::new("python3");
+ assert!(
+ generation_targets(&["requests".to_owned()], true, python, root).is_err(),
+ "--all plus explicit packages must be rejected"
+ );
+ assert!(
+ generation_targets(&[], false, python, root).is_err(),
+ "no packages and no --all must be rejected"
+ );
+ }
+}
diff --git a/crates/basilisk-cli/src/typeshed_cli.rs b/crates/basilisk-cli/src/typeshed_cli.rs
new file mode 100644
index 00000000..3b67892b
--- /dev/null
+++ b/crates/basilisk-cli/src/typeshed_cli.rs
@@ -0,0 +1,397 @@
+//! Implements the [STUBRES-TYPESHED-DOWNLOAD] CLI surface:
+//! `basilisk typeshed download [--commit ]`.
+//!
+//! This command — like the editor's Download buttons — is the ONLY way
+//! typeshed bytes arrive on a machine ([TYPESHEDRT-SEGREGATION]). `check` and
+//! `analyze` never download: a pin that is not in the store tanks hard with
+//! `NO SOURCE`, and this command is what that error tells the user to run.
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use basilisk_typeshed_fetch::{DownloadPhase, GithubApi, GithubClient};
+use colored::Colorize as _;
+use tracing::error;
+
+/// The `basilisk typeshed` action surface.
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum TypeshedAction {
+ /// Download and verify one typeshed commit into the content-addressed
+ /// store. With no `--commit` this resolves the latest
+ /// `python/typeshed@main` and writes the resolved SHA as the workspace's
+ /// `typeshed-commit` pin; with `--commit` it materialises that exact,
+ /// already-configured pin and writes no configuration.
+ Download {
+ /// Exact full 40-hex commit SHA to download (defaults to latest).
+ #[arg(long, value_name = "SHA")]
+ commit: Option,
+ /// Workspace whose configuration supplies the store location and, for
+ /// a latest download, receives the pin.
+ #[arg(long, default_value = ".", value_name = "DIR")]
+ workspace: PathBuf,
+ },
+}
+
+/// Dispatch a `basilisk typeshed` action. Returns the process exit code
+/// ([CHKARCH-CLI-EXITCODES]: `0` ok, `2` invalid configuration, `3` failure).
+pub(crate) fn run(action: TypeshedAction) -> u8 {
+ match action {
+ TypeshedAction::Download { commit, workspace } => run_download(commit, &workspace),
+ }
+}
+
+fn run_download(commit: Option, workspace: &Path) -> u8 {
+ let client = GithubClient::new();
+ download_action(commit, workspace, &client)
+}
+
+/// The download action with its transport injected, so tests drive the whole
+/// surface — config discovery, store resolution, progress — offline.
+fn download_action(commit: Option, workspace: &Path, api: &dyn GithubApi) -> u8 {
+ let config = basilisk_lsp::config::load_analysis_config(workspace);
+ let store = config.typeshed_store_path;
+ let progress = |phase: DownloadPhase| println!(" {}", phase_label(phase).dimmed());
+ match commit {
+ Some(sha) => download_exact(&sha, store, api, &progress),
+ None => download_latest_and_pin(workspace, store, api, &progress),
+ }
+}
+
+fn download_exact(
+ sha: &str,
+ store: Option,
+ api: &dyn GithubApi,
+ progress: &dyn Fn(DownloadPhase),
+) -> u8 {
+ let Ok(commit) = basilisk_stubs::typeshed::gittree::Oid::from_hex(sha) else {
+ error!(
+ len = sha.len(),
+ "--commit must be a full 40-character hex SHA"
+ );
+ return 2;
+ };
+ println!("Downloading typeshed {commit} into the verified store…");
+ match basilisk_typeshed_fetch::download_commit(commit, store, api, progress) {
+ Ok(outcome) => {
+ println!(
+ "{} {} (tree {}) is now available offline",
+ "ok:".green().bold(),
+ outcome.commit,
+ outcome.tree
+ );
+ 0
+ }
+ Err(download_error) => {
+ error!(%download_error, "typeshed download failed; nothing was written");
+ 3
+ }
+ }
+}
+
+fn download_latest_and_pin(
+ workspace: &Path,
+ store: Option,
+ api: &dyn GithubApi,
+ progress: &dyn Fn(DownloadPhase),
+) -> u8 {
+ println!("Downloading the latest python/typeshed commit into the verified store…");
+ let outcome = match basilisk_typeshed_fetch::download_latest(store, api, progress) {
+ Ok(outcome) => outcome,
+ Err(download_error) => {
+ error!(%download_error, "typeshed download failed; nothing was written");
+ return 3;
+ }
+ };
+ match write_pin(workspace, &outcome.commit.to_hex()) {
+ Ok(()) => {
+ println!(
+ "{} pinned typeshed-commit = {}",
+ "ok:".green().bold(),
+ outcome.commit
+ );
+ 0
+ }
+ Err(config_error) => {
+ // The store entry is verified and kept — only the pin write
+ // failed, so the command is re-runnable without a re-download.
+ error!(%config_error, commit = %outcome.commit, "downloaded but could not write the pin");
+ 2
+ }
+ }
+}
+
+/// Write `typeshed-commit` through the same validated, structure-preserving
+/// editor transaction the LSP configuration editor uses ([LSPCFGED-TYPESHED]).
+///
+/// The pin and a custom folder are the two mutually exclusive step-3 sources
+/// ([STUBRES-TYPESHED]), so the same transaction retires `typeshed-path` —
+/// byte for byte the update the LSP's Download latest button writes
+/// (`pin_update` in `crates/basilisk-lsp/src/typeshed_download.rs`). Without
+/// the retirement the patch would name both sources and validation would
+/// reject the whole write, leaving a downloaded commit unpinned.
+fn write_pin(workspace: &Path, sha: &str) -> Result<(), basilisk_config::ConfigDocumentError> {
+ let document = basilisk_config::discover_config_document(workspace)?;
+ let update = basilisk_config::ConfigurationUpdate {
+ rules: basilisk_config::RuleConfigUpdate::default(),
+ typeshed: basilisk_config::TypeshedConfigUpdate {
+ entries: BTreeMap::from([
+ (
+ basilisk_config::TypeshedConfigKey::TypeshedCommit,
+ Some(sha.to_owned()),
+ ),
+ (basilisk_config::TypeshedConfigKey::TypeshedPath, None),
+ ]),
+ },
+ };
+ let patch = basilisk_config::build_configuration_patch(&document, &update)?;
+ basilisk_config::apply_config_patch(&patch)
+}
+
+const fn phase_label(phase: DownloadPhase) -> &'static str {
+ match phase {
+ DownloadPhase::Resolving => "resolving commit metadata",
+ DownloadPhase::FetchingTree => "fetching the trusted file tree",
+ DownloadPhase::FetchingArchive => "downloading the archive",
+ DownloadPhase::Verifying => "verifying against the commit identity",
+ DownloadPhase::Writing => "writing the store entry",
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use basilisk_typeshed_fetch::testing::{fake_repo, FakeApi, Faults};
+
+ use super::*;
+
+ /// [STUBRES-TYPESHED-DOWNLOAD]: the pin write is the same validated
+ /// editor transaction the configuration editor uses — structure
+ /// preserved, full SHA required.
+ #[test]
+ fn write_pin_round_trips_through_the_validated_editor() -> Result<(), Box>
+ {
+ let dir = tempfile::tempdir()?;
+ std::fs::write(
+ dir.path().join("pyproject.toml"),
+ "# keep\n[project]\nname = \"demo\"\n\n[tool.basilisk]\n",
+ )?;
+ write_pin(dir.path(), "83c2518a9e6abbda0c44592c3483de459198f887")?;
+ let written = std::fs::read_to_string(dir.path().join("pyproject.toml"))?;
+ assert!(written.contains("# keep"));
+ assert!(
+ written.contains("typeshed-commit = \"83c2518a9e6abbda0c44592c3483de459198f887\""),
+ "pin must be written: {written}"
+ );
+
+ assert!(
+ write_pin(dir.path(), "not-a-sha").is_err(),
+ "a malformed SHA must be rejected by validation, never written"
+ );
+ Ok(())
+ }
+
+ /// [STUBRES-TYPESHED-DOWNLOAD]: pinning retires a custom folder in the
+ /// same transaction, exactly like the LSP's Download latest action. The
+ /// two step-3 sources are mutually exclusive, so a write that kept both
+ /// would be rejected outright and the download would end up unpinned.
+ #[test]
+ fn write_pin_retires_a_custom_typeshed_path() -> Result<(), Box> {
+ let dir = tempfile::tempdir()?;
+ std::fs::write(
+ dir.path().join("pyproject.toml"),
+ "[tool.basilisk]\ntypeshed-path = \"vendor/typeshed\"\ntypeshed-store-path = \"store\"\n",
+ )?;
+ write_pin(dir.path(), "83c2518a9e6abbda0c44592c3483de459198f887")?;
+ let written = std::fs::read_to_string(dir.path().join("pyproject.toml"))?;
+ assert!(
+ written.contains("typeshed-commit = \"83c2518a9e6abbda0c44592c3483de459198f887\""),
+ "the resolved pin must be written: {written}"
+ );
+ assert!(
+ !written.contains("typeshed-path"),
+ "the custom folder must be retired by the same write: {written}"
+ );
+ assert!(
+ written.contains("typeshed-store-path = \"store\""),
+ "unrelated typeshed settings must survive untouched: {written}"
+ );
+ Ok(())
+ }
+
+ #[test]
+ fn a_malformed_commit_argument_is_a_configuration_error() {
+ let api = FakeApi::new(fake_repo());
+ // No transport is touched: the SHA fails validation before any request.
+ assert_eq!(download_exact("short", None, &api, &|_phase| {}), 2);
+ }
+
+ /// The `run` dispatch reaches the same validation: a malformed pin exits
+ /// `2` before any transport work.
+ #[test]
+ fn run_rejects_a_malformed_sha_through_the_dispatch() -> Result<(), Box>
+ {
+ let dir = tempfile::tempdir()?;
+ let action = TypeshedAction::Download {
+ commit: Some("short".to_owned()),
+ workspace: dir.path().to_path_buf(),
+ };
+ assert_eq!(run(action), 2);
+ Ok(())
+ }
+
+ /// `download --commit ` materialises the exact pin into the store and
+ /// writes no configuration ([STUBRES-TYPESHED-DOWNLOAD]).
+ #[test]
+ fn download_exact_materialises_the_pin_into_the_store() -> Result<(), Box>
+ {
+ let store = tempfile::tempdir()?;
+ let api = FakeApi::new(fake_repo());
+ let sha = api.repo.commit.to_hex();
+ assert_eq!(
+ download_exact(&sha, Some(store.path().to_path_buf()), &api, &|_phase| {}),
+ 0
+ );
+ assert_eq!(
+ std::fs::read_dir(store.path())?.count(),
+ 1,
+ "exactly one verified store entry must exist"
+ );
+ Ok(())
+ }
+
+ /// A transport failure is exit `3` and writes nothing.
+ #[test]
+ fn a_transport_failure_downloading_an_exact_pin_is_exit_3(
+ ) -> Result<(), Box> {
+ let store = tempfile::tempdir()?;
+ let mut api = FakeApi::new(fake_repo());
+ api.faults = Faults {
+ resolve_fails: true,
+ ..Faults::default()
+ };
+ let sha = api.repo.commit.to_hex();
+ assert_eq!(
+ download_exact(&sha, Some(store.path().to_path_buf()), &api, &|_phase| {}),
+ 3
+ );
+ assert_eq!(std::fs::read_dir(store.path())?.count(), 0);
+ Ok(())
+ }
+
+ /// `download` with no `--commit` resolves latest, stores it, and pegs the
+ /// resolved SHA as the workspace's `typeshed-commit` pin.
+ #[test]
+ fn download_latest_pins_the_resolved_sha() -> Result<(), Box> {
+ let workspace = tempfile::tempdir()?;
+ let store = tempfile::tempdir()?;
+ std::fs::write(workspace.path().join("pyproject.toml"), "[tool.basilisk]\n")?;
+ let api = FakeApi::new(fake_repo());
+ assert_eq!(
+ download_latest_and_pin(
+ workspace.path(),
+ Some(store.path().to_path_buf()),
+ &api,
+ &|_phase| {}
+ ),
+ 0
+ );
+ let written = std::fs::read_to_string(workspace.path().join("pyproject.toml"))?;
+ assert!(
+ written.contains(&format!("typeshed-commit = \"{}\"", api.repo.commit)),
+ "the resolved SHA must be pegged as the pin: {written}"
+ );
+ Ok(())
+ }
+
+ /// A failed latest download is exit `3` and leaves the configuration
+ /// untouched — no pin without verified bytes.
+ #[test]
+ fn a_failed_latest_download_writes_no_pin() -> Result<(), Box> {
+ let workspace = tempfile::tempdir()?;
+ let store = tempfile::tempdir()?;
+ std::fs::write(workspace.path().join("pyproject.toml"), "[tool.basilisk]\n")?;
+ let mut api = FakeApi::new(fake_repo());
+ api.faults = Faults {
+ archive_fails: true,
+ ..Faults::default()
+ };
+ assert_eq!(
+ download_latest_and_pin(
+ workspace.path(),
+ Some(store.path().to_path_buf()),
+ &api,
+ &|_phase| {}
+ ),
+ 3
+ );
+ let written = std::fs::read_to_string(workspace.path().join("pyproject.toml"))?;
+ assert!(
+ !written.contains("typeshed-commit"),
+ "no pin may be written for a failed download: {written}"
+ );
+ Ok(())
+ }
+
+ /// A pin-write failure after a successful download is exit `2`; the store
+ /// entry is kept so re-running needs no re-download.
+ #[cfg(unix)]
+ #[test]
+ fn a_pin_write_failure_after_download_is_a_configuration_error(
+ ) -> Result<(), Box> {
+ use std::os::unix::fs::PermissionsExt as _;
+ let workspace = tempfile::tempdir()?;
+ let store = tempfile::tempdir()?;
+ std::fs::write(workspace.path().join("pyproject.toml"), "[tool.basilisk]\n")?;
+ let api = FakeApi::new(fake_repo());
+ std::fs::set_permissions(workspace.path(), std::fs::Permissions::from_mode(0o555))?;
+ let exit = download_latest_and_pin(
+ workspace.path(),
+ Some(store.path().to_path_buf()),
+ &api,
+ &|_phase| {},
+ );
+ std::fs::set_permissions(workspace.path(), std::fs::Permissions::from_mode(0o755))?;
+ assert_eq!(exit, 2);
+ assert_eq!(
+ std::fs::read_dir(store.path())?.count(),
+ 1,
+ "the verified store entry must survive the failed pin write"
+ );
+ Ok(())
+ }
+
+ /// The full action surface offline: config discovery resolves the
+ /// workspace-relative store, the latest commit lands there, and the pin is
+ /// pegged — the exact flow `basilisk typeshed download` runs.
+ #[test]
+ fn download_action_resolves_the_store_from_workspace_config(
+ ) -> Result<(), Box> {
+ let workspace = tempfile::tempdir()?;
+ std::fs::write(
+ workspace.path().join("pyproject.toml"),
+ "[tool.basilisk]\ntypeshed-store-path = \"store\"\n",
+ )?;
+ let api = FakeApi::new(fake_repo());
+ assert_eq!(download_action(None, workspace.path(), &api), 0);
+ assert_eq!(
+ std::fs::read_dir(workspace.path().join("store"))?.count(),
+ 1,
+ "the store entry must land in the config-resolved location"
+ );
+ Ok(())
+ }
+
+ /// Every phase renders a distinct, human-readable progress label.
+ #[test]
+ fn every_download_phase_has_a_distinct_label() {
+ let labels = [
+ phase_label(DownloadPhase::Resolving),
+ phase_label(DownloadPhase::FetchingTree),
+ phase_label(DownloadPhase::FetchingArchive),
+ phase_label(DownloadPhase::Verifying),
+ phase_label(DownloadPhase::Writing),
+ ];
+ let unique: std::collections::BTreeSet<&str> = labels.iter().copied().collect();
+ assert_eq!(unique.len(), labels.len());
+ assert!(labels.iter().all(|label| !label.is_empty()));
+ }
+}
diff --git a/crates/basilisk-cli/tests/e2e_cross_module_final.rs b/crates/basilisk-cli/tests/e2e_cross_module_final.rs
index 6cea1dd0..bddea9a6 100644
--- a/crates/basilisk-cli/tests/e2e_cross_module_final.rs
+++ b/crates/basilisk-cli/tests/e2e_cross_module_final.rs
@@ -1,4 +1,4 @@
-//! Tests for [CHKARCH-DIAG-OWNERSHIP]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#chkarch-diag-ownership
+//! Tests for [CHKARCH-DIAG-OWNERSHIP]. See docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-DIAG-OWNERSHIP
#![allow(
clippy::allow_attributes,
clippy::indexing_slicing,
diff --git a/crates/basilisk-cli/tests/e2e_stub_resolution.rs b/crates/basilisk-cli/tests/e2e_stub_resolution.rs
index d2445362..ff1e2465 100644
--- a/crates/basilisk-cli/tests/e2e_stub_resolution.rs
+++ b/crates/basilisk-cli/tests/e2e_stub_resolution.rs
@@ -104,12 +104,10 @@ fn custom_typeshed_overrides_stdlib_and_parses() {
let config = basilisk_lsp::config::WorkspaceConfig {
typeshed_path: Some(ts.clone()),
- typeshed_cache: false,
..Default::default()
};
let request = basilisk_lsp::config::typeshed_request(&config).unwrap();
- let snapshot = basilisk_stubs::typeshed::runtime::production_manager(request, None)
- .unwrap()
+ let snapshot = basilisk_stubs::typeshed::runtime::production_manager(request)
.snapshot()
.unwrap();
assert_eq!(
diff --git a/crates/basilisk-cli/tests/e2e_typeshed_config_validation.rs b/crates/basilisk-cli/tests/e2e_typeshed_config_validation.rs
index 553b5440..799c0706 100644
--- a/crates/basilisk-cli/tests/e2e_typeshed_config_validation.rs
+++ b/crates/basilisk-cli/tests/e2e_typeshed_config_validation.rs
@@ -7,7 +7,7 @@
//! with the distinct configuration-error code 2 (never the diagnostics
//! code 1, never a silent 0), prints a redacted, user-facing reason on
//! stderr, and emits no diagnostics at all — a broken pin must never
-//! silently substitute another source ([STUBRES-TYPESHED-ACQUIRE]).
+//! silently substitute another source ([STUBRES-TYPESHED-OFFLINE]).
#![allow(
clippy::allow_attributes,
clippy::expect_used,
@@ -15,10 +15,15 @@
clippy::panic
)]
+use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU64, Ordering};
+use basilisk_config::{
+ ConfigurationUpdate, RuleConfigUpdate, TypeshedConfigKey, TypeshedConfigUpdate,
+};
+
fn unique_dir(prefix: &str) -> PathBuf {
static CTR: AtomicU64 = AtomicU64::new(0);
let n = CTR.fetch_add(1, Ordering::Relaxed);
@@ -41,6 +46,12 @@ fn check_with_config(dir: &Path, basilisk_table: &str) -> Output {
)
.expect("write pyproject");
std::fs::write(dir.join("app.py"), "value: int = 1\n").expect("write app");
+ run_check(dir)
+}
+
+/// Run `basilisk check app.py` in `dir` against whatever configuration is on
+/// disk, with the ambient venv scrubbed.
+fn run_check(dir: &Path) -> Output {
Command::new(env!("CARGO_BIN_EXE_basilisk"))
.arg("check")
.arg("app.py")
@@ -50,6 +61,20 @@ fn check_with_config(dir: &Path, basilisk_table: &str) -> Output {
.expect("spawn basilisk")
}
+/// The typeshed half of a configuration update, as both pin-writing surfaces
+/// build it.
+fn typeshed_update(entries: &[(TypeshedConfigKey, Option<&str>)]) -> ConfigurationUpdate {
+ ConfigurationUpdate {
+ rules: RuleConfigUpdate::default(),
+ typeshed: TypeshedConfigUpdate {
+ entries: entries
+ .iter()
+ .map(|(key, setting)| (*key, setting.map(str::to_owned)))
+ .collect::>(),
+ },
+ }
+}
+
/// Assert the fail-closed contract shared by every invalid typeshed setting:
/// exit code 2, the exact reason on stderr, and zero diagnostics on stdout.
fn assert_fails_closed(output: &Output, expected_reason: &str) {
@@ -96,45 +121,151 @@ fn full_length_non_hex_typeshed_commit_fails_closed() {
let _ = std::fs::remove_dir_all(&dir);
}
+/// [STUBRES-TYPESHED-PIN] / [TYPESHEDRT-SEGREGATION], through the real
+/// binary: a well-formed pin that is not on this machine is VALID
+/// configuration — the check TANKS HARD (exit 3, the spec's `NO SOURCE`
+/// status line naming the recovery command, zero diagnostics) and the
+/// checker NEVER attempts to download anything: the isolated store is left
+/// byte-empty.
#[test]
-fn typeshed_url_without_sha_placeholder_fails_closed() {
- let dir = unique_dir("url_no_sha");
+fn a_valid_missing_pin_tanks_hard_and_never_downloads() {
+ let dir = unique_dir("missing_pin");
+ let pin = "0123456789012345678901234567890123456789";
let output = check_with_config(
&dir,
- "typeshed-url = \"https://mirror.example.com/typeshed.zip\"\n",
+ &format!("typeshed-commit = \"{pin}\"\ntypeshed-store-path = \"store\"\n"),
);
- assert_fails_closed(
- &output,
- "typeshed-url must be HTTPS with exactly one {sha} placeholder",
+ let stdout = String::from_utf8_lossy(&output.stdout);
+ let stderr = String::from_utf8_lossy(&output.stderr);
+
+ assert_eq!(
+ output.status.code(),
+ Some(3),
+ "a missing pin is a hard failure, not a config error and never a pass, stdout: {stdout}, stderr: {stderr}"
+ );
+ assert!(
+ stderr.contains("NO SOURCE") && stderr.contains(pin),
+ "stderr must carry the loud NO SOURCE line naming the pin, stderr: {stderr}"
+ );
+ assert!(
+ stderr.contains("basilisk typeshed download"),
+ "stderr must name the explicit recovery command, stderr: {stderr}"
+ );
+ assert!(
+ !stdout.contains("error["),
+ "no diagnostics may be emitted when the source is missing, stdout: {stdout}"
+ );
+ let store = dir.join("store");
+ let store_is_untouched = !store.exists()
+ || std::fs::read_dir(&store).is_ok_and(|mut entries| entries.next().is_none());
+ assert!(
+ store_is_untouched,
+ "the checker must never write to or fetch into the store"
);
let _ = std::fs::remove_dir_all(&dir);
}
+/// The retired download-policy keys (`typeshed-url`, `typeshed-cache`,
+/// `typeshed-verify`, `typeshed-cache-path`) are no longer configuration:
+/// they change nothing, trigger no download machinery, and their values are
+/// never echoed back ([STUBRES-TYPESHED-CONFIG] redaction).
#[test]
-fn plain_http_typeshed_url_fails_closed() {
- let dir = unique_dir("url_http");
+fn retired_download_policy_keys_are_inert_and_never_echoed() {
+ let dir = unique_dir("retired_keys");
let output = check_with_config(
&dir,
- "typeshed-url = \"http://mirror.example.com/{sha}.zip\"\n",
+ "typeshed-url = \"http://internal-host.corp.example/secret-{sha}.zip\"\ntypeshed-cache = false\ntypeshed-verify = false\ntypeshed-cache-path = \"secret-cache\"\n",
);
- assert_fails_closed(
- &output,
- "typeshed-url must be HTTPS with exactly one {sha} placeholder",
+ let stdout = String::from_utf8_lossy(&output.stdout);
+ let stderr = String::from_utf8_lossy(&output.stderr);
+
+ assert_eq!(
+ output.status.code(),
+ Some(0),
+ "retired keys must not alter the bundled-default check, stdout: {stdout}, stderr: {stderr}"
);
+ for retired_value in ["internal-host.corp.example", "secret-cache"] {
+ assert!(
+ !stderr.contains(retired_value) && !stdout.contains(retired_value),
+ "a retired key's value must never be echoed back: `{retired_value}`, stdout: {stdout}, stderr: {stderr}"
+ );
+ }
let _ = std::fs::remove_dir_all(&dir);
}
+/// [STUBRES-TYPESHED-DOWNLOAD] agreement between the two pin-writing
+/// surfaces: `basilisk typeshed download` (`write_pin` in
+/// `crates/basilisk-cli/src/typeshed_cli.rs`) and the LSP's Download latest
+/// button (`pin_update` in `crates/basilisk-lsp/src/typeshed_download.rs`)
+/// build the SAME two-entry update — set `typeshed-commit`, retire
+/// `typeshed-path` — because the two step-3 sources are mutually exclusive
+/// ([STUBRES-TYPESHED]). This drives that shared `basilisk-config`
+/// transaction over a workspace that names a custom folder and hands the
+/// result to the real binary. The commit-only half-update, which would leave
+/// both sources named, is refused wholesale — so a surface that skipped the
+/// retirement would download bytes and then fail to pin them.
#[test]
-fn typeshed_url_with_two_sha_placeholders_fails_closed() {
- let dir = unique_dir("url_two_sha");
- let output = check_with_config(
- &dir,
- "typeshed-url = \"https://mirror.example.com/{sha}/{sha}.zip\"\n",
+fn pinning_a_downloaded_commit_retires_the_custom_folder() {
+ let pin = "0123456789012345678901234567890123456789";
+ let dir = unique_dir("pin_retires_path");
+ std::fs::create_dir_all(dir.join("ts").join("stdlib")).expect("create custom tree");
+ std::fs::write(dir.join("app.py"), "value: int = 1\n").expect("write app");
+ std::fs::write(
+ dir.join("pyproject.toml"),
+ "[project]\nname = \"x\"\nversion = \"0.1.0\"\n\n[tool.basilisk]\ntypeshed-path = \"ts\"\ntypeshed-store-path = \"store\"\n",
+ )
+ .expect("write pyproject");
+
+ let document = basilisk_config::discover_config_document(&dir).expect("discover config");
+ let commit_only = typeshed_update(&[(TypeshedConfigKey::TypeshedCommit, Some(pin))]);
+ assert!(
+ basilisk_config::build_configuration_patch(&document, &commit_only).is_err(),
+ "a pin write that keeps the custom folder names two sources at once and must be refused"
);
- assert_fails_closed(
- &output,
- "typeshed-url must be HTTPS with exactly one {sha} placeholder",
+
+ let patch = basilisk_config::build_configuration_patch(
+ &document,
+ &typeshed_update(&[
+ (TypeshedConfigKey::TypeshedCommit, Some(pin)),
+ (TypeshedConfigKey::TypeshedPath, None),
+ ]),
+ )
+ .expect("the retiring pin write is a valid transaction");
+ basilisk_config::apply_config_patch(&patch).expect("apply the pin write");
+
+ let written = std::fs::read_to_string(dir.join("pyproject.toml")).expect("read pyproject");
+ assert!(
+ written.contains(&format!("typeshed-commit = \"{pin}\"")),
+ "the resolved pin must be written: {written}"
+ );
+ assert!(
+ !written.contains("typeshed-path"),
+ "the custom folder must be retired by the same write: {written}"
+ );
+ assert!(
+ written.contains("typeshed-store-path = \"store\""),
+ "unrelated typeshed settings must survive untouched: {written}"
+ );
+
+ // The real binary reads exactly one source out of the written file: the
+ // pin. It fails on resolution (`NO SOURCE`), never on configuration.
+ let output = run_check(&dir);
+ let stdout = String::from_utf8_lossy(&output.stdout);
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ !stderr.contains("mutually exclusive"),
+ "the written configuration must name a single source, stderr: {stderr}"
+ );
+ assert_eq!(
+ output.status.code(),
+ Some(3),
+ "the lone pin is valid configuration whose bytes are absent, stdout: {stdout}, stderr: {stderr}"
);
+ assert!(
+ stderr.contains("NO SOURCE") && stderr.contains(pin),
+ "stderr must carry the NO SOURCE line naming the freshly written pin, stderr: {stderr}"
+ );
+
let _ = std::fs::remove_dir_all(&dir);
}
@@ -153,45 +284,25 @@ fn typeshed_path_with_commit_pin_fails_closed() {
let _ = std::fs::remove_dir_all(&dir);
}
+/// A well-formed pin clears configuration validation: whatever happens next
+/// is source resolution (`NO SOURCE`), never a configuration error.
#[test]
-fn config_error_reason_never_echoes_the_configured_mirror_value() {
- let dir = unique_dir("redacted_mirror");
- let secret = "http://internal-host.corp.example/secret-{sha}.zip";
- let output = check_with_config(&dir, &format!("typeshed-url = \"{secret}\"\n"));
- let stderr = String::from_utf8_lossy(&output.stderr);
-
- assert_eq!(
- output.status.code(),
- Some(2),
- "the invalid mirror must fail closed, stderr: {stderr}"
- );
- assert!(
- !stderr.contains("internal-host.corp.example"),
- "the configured mirror value must never be echoed back ([STUBRES-TYPESHED-CONFIG] redaction), stderr: {stderr}"
- );
-
- let _ = std::fs::remove_dir_all(&dir);
-}
-
-#[test]
-fn valid_full_sha_paired_with_valid_mirror_passes_validation() {
+fn valid_full_sha_clears_validation_and_fails_only_on_resolution() {
let dir = unique_dir("valid_pin_shape");
- // An unreachable-but-well-formed mirror: validation must ACCEPT the
- // shape; the later transport failure is a different, non-config error.
let output = check_with_config(
&dir,
- "typeshed-commit = \"0123456789012345678901234567890123456789\"\ntypeshed-url = \"https://127.0.0.1:1/{sha}.zip\"\ntypeshed-cache = false\n",
+ "typeshed-commit = \"0123456789012345678901234567890123456789\"\ntypeshed-store-path = \"store\"\n",
);
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(
!stderr.contains("configuration error"),
- "a well-formed pin + mirror must clear validation — any failure past this point is transport, not configuration, stderr: {stderr}"
+ "a well-formed pin must clear validation — any failure past this point is resolution, not configuration, stderr: {stderr}"
);
assert_ne!(
output.status.code(),
Some(0),
- "an unreachable mirror with an exact pin must not silently pass ([STUBRES-TYPESHED-ACQUIRE] fail-closed), stderr: {stderr}"
+ "a pin that is not on this machine must not silently pass ([STUBRES-TYPESHED-PIN] fail-closed), stderr: {stderr}"
);
let _ = std::fs::remove_dir_all(&dir);
diff --git a/crates/basilisk-cli/tests/e2e_typeshed_path_heavy.rs b/crates/basilisk-cli/tests/e2e_typeshed_path_heavy.rs
index 8861039f..142e8745 100644
--- a/crates/basilisk-cli/tests/e2e_typeshed_path_heavy.rs
+++ b/crates/basilisk-cli/tests/e2e_typeshed_path_heavy.rs
@@ -132,8 +132,9 @@ fn typeshed_path_full_lifecycle_through_pyproject() {
seed_typeshed(&dir, "ts", &[("os.pyi", "def uname() -> str: ...\n")]);
write(&dir, "app.py", APP_OS_AND_FRACTIONS);
- // ── Interaction 1: NO typeshed-path → the default Latest-first runtime
- // source resolves both stdlib modules, so the project is clean. ──
+ // ── Interaction 1: NO typeshed-path → the default pinned source (an unset
+ // `typeshed-commit` selects the bundled commit, served from the embedded
+ // ZIP) resolves both stdlib modules, so the project is clean. ──
write(
&dir,
"pyproject.toml",
@@ -182,8 +183,9 @@ fn typeshed_path_full_lifecycle_through_pyproject() {
.expect("remove fractions stub");
assert_flags_unresolved(&check(&dir), "fractions", &["os", "uname"]);
- // ── Interaction 5: remove typeshed-path entirely → the default Latest-first
- // runtime source becomes active again, so the project is clean once more. ──
+ // ── Interaction 5: remove typeshed-path entirely → the default pinned
+ // source (the bundled commit) becomes active again, so the project is clean
+ // once more. ──
write(
&dir,
"pyproject.toml",
diff --git a/crates/basilisk-cli/tests/mcp_stdio_tests.rs b/crates/basilisk-cli/tests/mcp_stdio_tests.rs
index 8c8c6d12..042aca52 100644
--- a/crates/basilisk-cli/tests/mcp_stdio_tests.rs
+++ b/crates/basilisk-cli/tests/mcp_stdio_tests.rs
@@ -22,6 +22,26 @@ fn custom_typeshed_workspace() -> Result Result, Box> {
+ let requests = [
+ json!({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":PROTOCOL_VERSION,"capabilities":{},"clientInfo":{"name":"e2e","version":"1"}}}),
+ json!({"jsonrpc":"2.0","method":"notifications/initialized"}),
+ json!({"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}),
+ json!({"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"basilisk_typeshed_status","arguments":{}}}),
+ ];
+ let mut payload = Vec::new();
+ for request in requests {
+ payload.extend_from_slice(serde_json::to_string(&request)?.as_bytes());
+ payload.push(b'\n');
+ }
+ run_raw_session(workspace, &payload)
+}
+
+/// Drive one MCP session over the spawned binary's stdio with raw bytes, so
+/// tests can send lines no serializer would produce (invalid UTF-8, arrays).
+fn run_raw_session(
+ workspace: &std::path::Path,
+ payload: &[u8],
+) -> Result, Box> {
let mut child = Command::new(env!("CARGO_BIN_EXE_basilisk"))
.arg("mcp")
.arg("--workspace")
@@ -30,17 +50,8 @@ fn run_session(workspace: &std::path::Path) -> Result, Box Result<(), Box Result<(), Box>
+{
+ let workspace = custom_typeshed_workspace()?;
+ let mut payload: Vec = vec![0xFF, 0xFE, b'\n'];
+ for request in [
+ json!([1]),
+ json!({"jsonrpc":"2.0","id":true,"method":"ping"}),
+ json!({"jsonrpc":"2.0","id":1}),
+ json!({"jsonrpc":"1.0","id":2,"method":"ping"}),
+ json!({"jsonrpc":"2.0","id":3,"method":"initialize","params":{}}),
+ json!({"jsonrpc":"2.0","id":4,"method":"initialize","params":{"protocolVersion":PROTOCOL_VERSION,"capabilities":{},"clientInfo":{"name":"e2e","version":"1"}}}),
+ json!({"jsonrpc":"2.0","method":"notifications/initialized"}),
+ json!({"jsonrpc":"2.0","id":5,"method":"ping"}),
+ json!({"jsonrpc":"2.0","id":6,"method":"resources/list"}),
+ json!({"jsonrpc":"2.0","id":7,"method":"initialize","params":{"protocolVersion":PROTOCOL_VERSION}}),
+ json!({"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"nope","arguments":{}}}),
+ ] {
+ payload.extend_from_slice(serde_json::to_string(&request)?.as_bytes());
+ payload.push(b'\n');
+ }
+ let responses = run_raw_session(workspace.path(), &payload)?;
+ let codes: Vec> = responses
+ .iter()
+ .map(|response| response.pointer("/error/code").and_then(Value::as_i64))
+ .collect();
+ assert_eq!(
+ codes,
+ vec![
+ Some(-32700),
+ Some(-32600),
+ Some(-32600),
+ Some(-32600),
+ Some(-32600),
+ Some(-32602),
+ None,
+ None,
+ Some(-32601),
+ Some(-32600),
+ Some(-32602),
+ ],
+ "each guard must answer with its prescribed code: {responses:?}"
+ );
+ Ok(())
+}
diff --git a/crates/basilisk-cli/tests/stub_cli_tests.rs b/crates/basilisk-cli/tests/stub_cli_tests.rs
index 2eb009c5..5453de52 100644
--- a/crates/basilisk-cli/tests/stub_cli_tests.rs
+++ b/crates/basilisk-cli/tests/stub_cli_tests.rs
@@ -179,3 +179,18 @@ fn generate_all_with_no_untyped_imports_succeeds() -> Result<(), Box Result<(), Box> {
+ let project = TestProject::new("status_empty")?;
+ let output = project.command().args(["stubs", "status"]).output()?;
+ assert!(output.status.success(), "{}", output_text(&output));
+ assert!(
+ String::from_utf8_lossy(&output.stdout).contains("No generated stubs found"),
+ "{}",
+ output_text(&output)
+ );
+ Ok(())
+}
diff --git a/crates/basilisk-cli/tests/typeshed_cli_status_tests.rs b/crates/basilisk-cli/tests/typeshed_cli_status_tests.rs
index 779490f9..a1f720ba 100644
--- a/crates/basilisk-cli/tests/typeshed_cli_status_tests.rs
+++ b/crates/basilisk-cli/tests/typeshed_cli_status_tests.rs
@@ -14,7 +14,7 @@ fn check_uses_custom_typeshed_and_routes_status_only_to_stderr(
std::fs::write(workspace.path().join("app.py"), "from os import getcwd\n")?;
std::fs::write(
workspace.path().join("pyproject.toml"),
- "[tool.basilisk]\ntypeshed-path = \"typeshed\"\ntypeshed-cache = false\n",
+ "[tool.basilisk]\ntypeshed-path = \"typeshed\"\n",
)?;
let output = Command::new(env!("CARGO_BIN_EXE_basilisk"))
@@ -33,8 +33,15 @@ fn check_uses_custom_typeshed_and_routes_status_only_to_stderr(
assert!(!stdout.contains("UNPINNED"));
assert!(stderr.contains("typeshed source status"), "{stderr}");
assert!(stderr.contains("active_source=\"custom\""), "{stderr}");
- assert!(stderr.contains("provenance=UserManaged"), "{stderr}");
- assert!(stderr.contains("signed_release=false"), "{stderr}");
+ assert!(stderr.contains("license_status=NotSupplied"), "{stderr}");
+ assert!(
+ !stderr.contains("provenance="),
+ "active_source IS the trust story — no provenance field may reappear: {stderr}"
+ );
+ assert!(
+ !stderr.contains("signed_release="),
+ "active_source IS the trust story — no signed_release field may reappear: {stderr}"
+ );
let unpinned = stderr.find("warning_code=\"UNPINNED\"");
let user_managed = stderr.find("warning_code=\"USER-MANAGED SOURCE\"");
assert!(
@@ -46,8 +53,33 @@ fn check_uses_custom_typeshed_and_routes_status_only_to_stderr(
Ok(())
}
+/// [STUBRES-TYPESHED-DOWNLOAD]: a malformed `--commit` is rejected by
+/// validation (exit `2`) before any transport work — safe to assert offline.
+#[test]
+fn a_malformed_download_commit_is_rejected_offline() -> Result<(), Box> {
+ let workspace = tempfile::tempdir()?;
+ let output = Command::new(env!("CARGO_BIN_EXE_basilisk"))
+ .args([
+ "typeshed",
+ "download",
+ "--commit",
+ "not-a-sha",
+ "--workspace",
+ ])
+ .arg(workspace.path())
+ .output()?;
+ assert_eq!(
+ output.status.code(),
+ Some(2),
+ "stdout={}; stderr={}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+ Ok(())
+}
+
#[test]
-fn exact_commit_transport_failure_does_not_fall_back() -> Result<(), Box> {
+fn a_pin_missing_from_the_store_does_not_fall_back() -> Result<(), Box> {
let workspace = tempfile::tempdir()?;
std::fs::write(workspace.path().join("app.py"), "from os import getcwd\n")?;
std::fs::write(
@@ -55,8 +87,7 @@ fn exact_commit_transport_failure_does_not_fall_back() -> Result<(), Box Result<(), Box Result<(), ConfigDocumentError> {
- for key in [
- "typeshed-path",
- "typeshed-commit",
- "typeshed-url",
- "typeshed-cache-path",
- ] {
+ for key in ["typeshed-path", "typeshed-commit", "typeshed-store-path"] {
if basilisk.get(key).is_some_and(|value| !value.is_str()) {
return invalid(path, &format!("`{key}` must be a string"));
}
}
- for key in ["typeshed-cache", "typeshed-verify"] {
- if basilisk.get(key).is_some_and(|value| !value.is_bool()) {
- return invalid(path, &format!("`{key}` must be a boolean"));
- }
- }
if basilisk.contains_key("typeshed-path") && basilisk.contains_key("typeshed-commit") {
return invalid(
path,
@@ -262,14 +252,6 @@ fn validate_typeshed_settings(
);
}
}
- if let Some(url) = basilisk.get("typeshed-url").and_then(toml::Value::as_str) {
- if !crate::is_valid_typeshed_url_template(url) {
- return invalid(
- path,
- "`typeshed-url` must be HTTPS with exactly one {sha} placeholder",
- );
- }
- }
Ok(())
}
diff --git a/crates/basilisk-config/src/editor/patch.rs b/crates/basilisk-config/src/editor/patch.rs
index 2f1843ee..31dbb199 100644
--- a/crates/basilisk-config/src/editor/patch.rs
+++ b/crates/basilisk-config/src/editor/patch.rs
@@ -29,21 +29,16 @@ pub struct RuleConfigUpdate {
pub rule_tags: BTreeMap>,
}
-/// Closed persistence allowlist for Typeshed acquisition settings.
+/// Closed persistence allowlist for typeshed settings — the whole runtime
+/// surface is these three keys ([STUBRES-TYPESHED-CONFIG]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum TypeshedConfigKey {
- /// Custom canonical step-3 folder.
+ /// Custom typeshed folder.
TypeshedPath,
- /// Exact full commit SHA.
+ /// Exact full commit SHA pin.
TypeshedCommit,
- /// Known-SHA archive mirror template.
- TypeshedUrl,
- /// Immutable ZIP cache directory.
- TypeshedCachePath,
- /// Whether accepted downloads are reused.
- TypeshedCache,
- /// Whether the content gate is enabled.
- TypeshedVerify,
+ /// Verified content-addressed store directory.
+ TypeshedStorePath,
}
impl TypeshedConfigKey {
@@ -51,28 +46,17 @@ impl TypeshedConfigKey {
match self {
Self::TypeshedPath => "typeshed-path",
Self::TypeshedCommit => "typeshed-commit",
- Self::TypeshedUrl => "typeshed-url",
- Self::TypeshedCachePath => "typeshed-cache-path",
- Self::TypeshedCache => "typeshed-cache",
- Self::TypeshedVerify => "typeshed-verify",
+ Self::TypeshedStorePath => "typeshed-store-path",
}
}
}
-/// A TOML scalar accepted by a Typeshed setting update.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum TypeshedConfigValue {
- /// A path, URL template, or full SHA.
- Text(String),
- /// A cache or verification toggle.
- Boolean(bool),
-}
-
-/// Atomic Typeshed setting updates. `None` removes the explicit key.
+/// Atomic typeshed setting updates. Every key holds a TOML string (a path or
+/// a full SHA); `None` removes the explicit key.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct TypeshedConfigUpdate {
- /// Key to replacement scalar, or `None` to remove the explicit key.
- pub entries: BTreeMap>,
+ /// Key to replacement string, or `None` to remove the explicit key.
+ pub entries: BTreeMap>,
}
/// One atomic configuration-editor transaction.
@@ -172,12 +156,11 @@ fn patch_toml(
fn apply_typeshed_updates(
table: &mut Table,
- entries: &BTreeMap>,
+ entries: &BTreeMap>,
) {
for (key, setting) in entries {
match setting {
- Some(TypeshedConfigValue::Text(text)) => table[key.as_str()] = value(text.as_str()),
- Some(TypeshedConfigValue::Boolean(enabled)) => table[key.as_str()] = value(*enabled),
+ Some(text) => table[key.as_str()] = value(text.as_str()),
None => {
let _ = table.remove(key.as_str());
}
diff --git a/crates/basilisk-config/src/editor/tests.rs b/crates/basilisk-config/src/editor/tests.rs
index 13033cc2..f7f37858 100644
--- a/crates/basilisk-config/src/editor/tests.rs
+++ b/crates/basilisk-config/src/editor/tests.rs
@@ -11,7 +11,7 @@ use super::{
active_config_path, apply_config_patch, build_configuration_patch, build_rule_patch,
content_revision, discover_config_document, discover_config_document_with_content,
ConfigDocument, ConfigDocumentError, ConfigPatch, ConfigurationUpdate, RuleConfigUpdate,
- TypeshedConfigKey, TypeshedConfigUpdate, TypeshedConfigValue,
+ TypeshedConfigKey, TypeshedConfigUpdate,
};
use crate::{BasiliskConfig, RuleSeverity};
@@ -97,9 +97,8 @@ fn malformed_typeshed_settings_are_invalid() {
let root = temp_root("bad_typeshed_settings");
for content in [
"[tool.basilisk]\ntypeshed-commit = 42\n",
- "[tool.basilisk]\ntypeshed-cache = \"false\"\n",
"[tool.basilisk]\ntypeshed-commit = \"short\"\n",
- "[tool.basilisk]\ntypeshed-url = \"http://mirror/{sha}.zip\"\n",
+ "[tool.basilisk]\ntypeshed-store-path = false\n",
"[tool.basilisk]\ntypeshed-path = \"custom\"\ntypeshed-commit = \"83c2518a9e6abbda0c44592c3483de459198f887\"\n",
] {
let result = discover_config_document_with_content(&root, content.to_owned());
@@ -380,7 +379,7 @@ fn typeshed_settings_patch_atomically_and_preserve_project_content() {
let root = temp_root("typeshed_patch");
let document = document_for(
&root,
- "# keep\n[project]\nname = \"demo\"\n\n[tool.basilisk]\ntypeshed-cache = true\n",
+ "# keep\n[project]\nname = \"demo\"\n\n[tool.basilisk]\n",
);
let update = ConfigurationUpdate {
rules: set_rule("BSK-0001", RuleSeverity::Warning),
@@ -388,13 +387,11 @@ fn typeshed_settings_patch_atomically_and_preserve_project_content() {
entries: BTreeMap::from([
(
TypeshedConfigKey::TypeshedCommit,
- Some(TypeshedConfigValue::Text(
- "83c2518a9e6abbda0c44592c3483de459198f887".to_owned(),
- )),
+ Some("83c2518a9e6abbda0c44592c3483de459198f887".to_owned()),
),
(
- TypeshedConfigKey::TypeshedCache,
- Some(TypeshedConfigValue::Boolean(false)),
+ TypeshedConfigKey::TypeshedStorePath,
+ Some(".cache/typeshed-store".to_owned()),
),
]),
},
@@ -405,8 +402,13 @@ fn typeshed_settings_patch_atomically_and_preserve_project_content() {
assert!(patch
.content
.contains("typeshed-commit = \"83c2518a9e6abbda0c44592c3483de459198f887\""));
- assert!(patch.content.contains("typeshed-cache = false"));
- assert_eq!(patch.config.typeshed_cache, Some(false));
+ assert!(patch
+ .content
+ .contains("typeshed-store-path = \".cache/typeshed-store\""));
+ assert_eq!(
+ patch.config.typeshed_store_path,
+ Some(std::path::PathBuf::from(".cache/typeshed-store"))
+ );
assert_eq!(
patch.config.typeshed_commit.as_deref(),
Some("83c2518a9e6abbda0c44592c3483de459198f887")
@@ -421,19 +423,19 @@ fn typeshed_setting_removal_is_allowlisted_and_narrow() {
let root = temp_root("typeshed_remove");
let document = document_for(
&root,
- "[tool.basilisk]\n# keep mirror\ntypeshed-url = \"https://mirror.invalid/{sha}.zip\"\ntypeshed-verify = false\n",
+ "[tool.basilisk]\n# keep store\ntypeshed-store-path = \".cache/store\"\ntypeshed-commit = \"83c2518a9e6abbda0c44592c3483de459198f887\"\n",
);
let update = ConfigurationUpdate {
rules: RuleConfigUpdate::default(),
typeshed: TypeshedConfigUpdate {
- entries: BTreeMap::from([(TypeshedConfigKey::TypeshedVerify, None)]),
+ entries: BTreeMap::from([(TypeshedConfigKey::TypeshedCommit, None)]),
},
};
let patch = build_configuration_patch(&document, &update).unwrap();
- assert!(!patch.content.contains("typeshed-verify"));
- assert!(patch.content.contains("# keep mirror"));
- assert!(patch.content.contains("typeshed-url"));
- assert!(patch.config.typeshed_verify.is_none());
+ assert!(!patch.content.contains("typeshed-commit"));
+ assert!(patch.content.contains("# keep store"));
+ assert!(patch.content.contains("typeshed-store-path"));
+ assert!(patch.config.typeshed_commit.is_none());
let _ = std::fs::remove_dir_all(&root);
}
diff --git a/crates/basilisk-config/src/lib.rs b/crates/basilisk-config/src/lib.rs
index 20e25c0d..a04b8be9 100644
--- a/crates/basilisk-config/src/lib.rs
+++ b/crates/basilisk-config/src/lib.rs
@@ -21,9 +21,9 @@ pub use editor::{
active_config_path, apply_config_patch, build_configuration_patch, build_rule_patch,
discover_config_document, discover_config_document_with_content, ConfigDocument,
ConfigDocumentError, ConfigPatch, ConfigurationUpdate, RuleConfigUpdate, TypeshedConfigKey,
- TypeshedConfigUpdate, TypeshedConfigValue,
+ TypeshedConfigUpdate,
};
-pub use parse::{is_full_commit_sha, is_valid_typeshed_url_template, BasiliskConfig, RuleTables};
+pub use parse::{is_full_commit_sha, BasiliskConfig, RuleTables};
pub use paths::path_matches_pattern;
pub use severity::RuleSeverity;
@@ -248,8 +248,8 @@ typeshed-path = "typeshed-mp"
);
}
- /// [STUBRES-TYPESHED-CONFIG]: every runtime Typeshed setting is parsed
- /// without manufacturing a Python target or mapping it to a commit.
+ /// [STUBRES-TYPESHED-CONFIG]: the whole runtime typeshed surface is three
+ /// string keys, parsed verbatim.
#[test]
fn runtime_typeshed_settings_parse_as_one_source_policy() {
with_temp_cfg_dir(
@@ -260,10 +260,7 @@ typeshed-path = "typeshed-mp"
[tool.basilisk]
typeshed-path = "custom-typeshed"
typeshed-commit = "83c2518a9e6abbda0c44592c3483de459198f887"
-typeshed-url = "https://mirror.invalid/typeshed-{sha}.zip"
-typeshed-cache-path = ".cache/typeshed"
-typeshed-cache = false
-typeshed-verify = false
+typeshed-store-path = ".cache/typeshed-store"
"#,
)],
|cfg| {
@@ -276,23 +273,17 @@ typeshed-verify = false
Some("83c2518a9e6abbda0c44592c3483de459198f887")
);
assert_eq!(
- cfg.typeshed_url.as_deref(),
- Some("https://mirror.invalid/typeshed-{sha}.zip")
+ cfg.typeshed_store_path,
+ Some(std::path::PathBuf::from(".cache/typeshed-store"))
);
- assert_eq!(
- cfg.typeshed_cache_path,
- Some(std::path::PathBuf::from(".cache/typeshed"))
- );
- assert_eq!(cfg.typeshed_cache, Some(false));
- assert_eq!(cfg.typeshed_verify, Some(false));
assert_eq!(cfg.python_version, None);
},
);
}
- /// [STUBRES-TYPESHED-CONFIG]: unset acquisition keys stay `None`, so the
- /// selector applies Latest (no pin), default codeload URL, OS cache, and
- /// cache/verify on.
+ /// [STUBRES-TYPESHED-CONFIG]: unset keys stay `None`, so the runtime uses
+ /// the bundled commit (with `UNPINNED`) and the OS store directory —
+ /// never a download.
#[test]
fn typeshed_acquisition_keys_default_to_none() {
with_temp_cfg_dir(
@@ -300,10 +291,8 @@ typeshed-verify = false
&[("pyproject.toml", "[tool.basilisk]\n")],
|cfg| {
assert!(cfg.typeshed_commit.is_none());
- assert!(cfg.typeshed_url.is_none());
- assert!(cfg.typeshed_cache_path.is_none());
- assert!(cfg.typeshed_cache.is_none());
- assert!(cfg.typeshed_verify.is_none());
+ assert!(cfg.typeshed_path.is_none());
+ assert!(cfg.typeshed_store_path.is_none());
},
);
}
diff --git a/crates/basilisk-config/src/parse.rs b/crates/basilisk-config/src/parse.rs
index 57d721d1..8c4d3a15 100644
--- a/crates/basilisk-config/src/parse.rs
+++ b/crates/basilisk-config/src/parse.rs
@@ -71,30 +71,15 @@ pub struct BasiliskConfig {
/// standard-library stubs ([STUBRES-CUSTOM-TYPESHED]).
pub typeshed_path: Option,
- /// Exact `python/typeshed` commit to acquire at step 3
- /// ([STUBRES-TYPESHED-CONFIG]). A full SHA. Unset selects Latest `main`.
- /// A set pin fails closed — it never silently substitutes another SHA.
+ /// Exact `python/typeshed` commit pin ([STUBRES-TYPESHED-CONFIG]). A full
+ /// SHA. Unset means the bundled commit with an `UNPINNED` warning. A set
+ /// pin fails closed — the checker never downloads and never substitutes
+ /// another SHA; a pin not on this machine is `NO SOURCE`.
pub typeshed_commit: Option,
- /// Archive-mirror URL template containing `{sha}`
- /// ([STUBRES-TYPESHED-CONFIG]). Unset uses GitHub codeload. A mirror cannot
- /// resolve Latest — it only serves an already-known SHA.
- pub typeshed_url: Option,
-
- /// Directory holding gate-accepted, content-addressed typeshed ZIPs
- /// ([STUBRES-TYPESHED-CONFIG]). Unset uses the OS cache directory.
- pub typeshed_cache_path: Option,
-
- /// Whether to reuse gate-accepted cached ZIPs ([STUBRES-TYPESHED-CONFIG]).
- /// `None` means the spec default `true`; `false` downloads, validates, and
- /// discards. This forces a fresh acquisition but is not hermetic.
- pub typeshed_cache: Option,
-
- /// Whether to content-attest the archive against the trusted git tree
- /// ([STUBRES-TYPESHED-CONFIG]). `None` means the spec default `true`;
- /// `false` reports `UNVERIFIED` and never bypasses the safety, shape, or
- /// license gates.
- pub typeshed_verify: Option,
+ /// The verified content-addressed typeshed store directory
+ /// ([STUBRES-TYPESHED-STORE]). Unset uses the OS cache directory.
+ pub typeshed_store_path: Option,
/// Nearest-first chain of `[tool.basilisk]` rule tables on the ancestor
/// walk ([CHKARCH-CONFIG-DISCOVERY]). Rules are never merged: resolution
@@ -131,10 +116,7 @@ impl Default for BasiliskConfig {
stub_paths: Vec::new(),
typeshed_path: None,
typeshed_commit: None,
- typeshed_url: None,
- typeshed_cache_path: None,
- typeshed_cache: None,
- typeshed_verify: None,
+ typeshed_store_path: None,
rule_chain: Vec::new(),
python_version: None,
python_platform: None,
@@ -241,10 +223,7 @@ impl BasiliskConfig {
self.typeshed_commit = child.typeshed_commit;
}
}
- self.typeshed_url = child.typeshed_url.or(self.typeshed_url);
- self.typeshed_cache_path = child.typeshed_cache_path.or(self.typeshed_cache_path);
- self.typeshed_cache = child.typeshed_cache.or(self.typeshed_cache);
- self.typeshed_verify = child.typeshed_verify.or(self.typeshed_verify);
+ self.typeshed_store_path = child.typeshed_store_path.or(self.typeshed_store_path);
self.python_version = child.python_version.or(self.python_version);
self.python_platform = child.python_platform.or(self.python_platform);
self.narrow_attributes_across_calls = child
@@ -303,30 +282,14 @@ pub(crate) fn parse_pyproject_content(content: &str) -> Option {
cfg.typeshed_path = Some(PathBuf::from(val));
}
- // [STUBRES-TYPESHED-CONFIG]: runtime-acquisition keys. `typeshed-commit`
- // pins an exact SHA (unset => Latest); `typeshed-url` is a `{sha}` mirror
- // template; `typeshed-cache-path` relocates cached ZIPs; `typeshed-cache`
- // and `typeshed-verify` are tri-state (`None` => spec default `true`).
+ // [STUBRES-TYPESHED-CONFIG]: `typeshed-commit` pins an exact SHA (unset
+ // => bundled commit + UNPINNED); `typeshed-store-path` relocates the
+ // verified store. That is the whole runtime surface.
if let Some(val) = basilisk.get("typeshed-commit").and_then(|v| v.as_str()) {
cfg.typeshed_commit = Some(val.to_owned());
}
- if let Some(val) = basilisk.get("typeshed-url").and_then(|v| v.as_str()) {
- cfg.typeshed_url = Some(val.to_owned());
- }
- if let Some(val) = basilisk.get("typeshed-cache-path").and_then(|v| v.as_str()) {
- cfg.typeshed_cache_path = Some(PathBuf::from(val));
- }
- if let Some(val) = basilisk
- .get("typeshed-cache")
- .and_then(toml::Value::as_bool)
- {
- cfg.typeshed_cache = Some(val);
- }
- if let Some(val) = basilisk
- .get("typeshed-verify")
- .and_then(toml::Value::as_bool)
- {
- cfg.typeshed_verify = Some(val);
+ if let Some(val) = basilisk.get("typeshed-store-path").and_then(|v| v.as_str()) {
+ cfg.typeshed_store_path = Some(PathBuf::from(val));
}
// [CHKARCH-CONFIG-MODEL]: this file's one rule table. An empty or absent
@@ -402,27 +365,10 @@ pub fn is_full_commit_sha(sha: &str) -> bool {
sha.len() == 40 && sha.bytes().all(|b| b.is_ascii_hexdigit())
}
-/// Whether `template` is a usable `typeshed-url` archive-mirror template
-/// ([STUBRES-TYPESHED-CONFIG], [STUBRES-TYPESHED-ACQUIRE]).
-///
-/// Two requirements, both load-bearing for a secure, deterministic mirror:
-/// - **HTTPS scheme** — acquisition is over authenticated HTTPS only; a plain
-/// `http`/`file` mirror is rejected so bytes can never arrive over an
-/// unauthenticated transport.
-/// - **Exactly one `{sha}` placeholder** — a mirror cannot resolve Latest, so
-/// without a `{sha}` slot it could only serve one hard-coded commit; and more
-/// than one slot makes the substituted URL ambiguous.
-#[must_use]
-pub fn is_valid_typeshed_url_template(template: &str) -> bool {
- template.starts_with("https://") && template.matches("{sha}").count() == 1
-}
-
-/// Emit structured warnings for malformed typeshed-acquisition values
-/// ([STUBRES-TYPESHED-CONFIG]). Values are kept verbatim on the config so the
-/// acquisition core can fail closed on a bad pin rather than silently drop it;
-/// this only surfaces the problem. Raw values are never logged — a mirror URL
-/// may embed a token, so only the reason is recorded (URLs are redacted in
-/// logs, [STUBRES-TYPESHED-ACQUIRE]).
+/// Emit a structured warning for a malformed `typeshed-commit` pin
+/// ([STUBRES-TYPESHED-CONFIG]). The value is kept verbatim on the config so
+/// the runtime fails closed on a bad pin rather than silently dropping it;
+/// this only surfaces the problem. The raw value is never logged.
fn warn_on_malformed_typeshed_values(cfg: &BasiliskConfig) {
if let Some(sha) = cfg.typeshed_commit.as_deref() {
if !is_full_commit_sha(sha) {
@@ -432,13 +378,6 @@ fn warn_on_malformed_typeshed_values(cfg: &BasiliskConfig) {
);
}
}
- if let Some(url) = cfg.typeshed_url.as_deref() {
- if !is_valid_typeshed_url_template(url) {
- tracing::warn!(
- "typeshed-url is not a valid HTTPS template with exactly one {{sha}} placeholder"
- );
- }
- }
}
#[cfg(test)]
@@ -446,7 +385,7 @@ mod validation_tests {
use std::collections::HashMap;
use std::path::PathBuf;
- use super::{is_full_commit_sha, is_valid_typeshed_url_template, BasiliskConfig, RuleSeverity};
+ use super::{is_full_commit_sha, BasiliskConfig, RuleSeverity};
/// [STUBRES-TYPESHED-CONFIG]: only a full 40-char hex SHA is a valid pin.
#[test]
@@ -476,34 +415,6 @@ mod validation_tests {
assert!(!is_full_commit_sha(""));
}
- /// [STUBRES-TYPESHED-CONFIG]/[STUBRES-TYPESHED-ACQUIRE]: a mirror template
- /// MUST be HTTPS and carry exactly one `{sha}`.
- #[test]
- fn url_template_requires_https_and_exactly_one_sha() {
- assert!(is_valid_typeshed_url_template(
- "https://mirror.example/typeshed/{sha}.zip"
- ));
- assert!(is_valid_typeshed_url_template(
- "https://host/{sha}/archive.zip"
- ));
- // No placeholder — a mirror that can only serve one commit is invalid.
- assert!(!is_valid_typeshed_url_template(
- "https://mirror.example/typeshed/latest.zip"
- ));
- // A near-miss placeholder name does not count.
- assert!(!is_valid_typeshed_url_template("https://host/{commit}.zip"));
- // More than one `{sha}` is ambiguous — rejected.
- assert!(!is_valid_typeshed_url_template(
- "https://host/{sha}/{sha}.zip"
- ));
- // Non-HTTPS transports are rejected even with a valid placeholder.
- assert!(!is_valid_typeshed_url_template(
- "http://mirror.example/typeshed/{sha}.zip"
- ));
- assert!(!is_valid_typeshed_url_template("file:///local/{sha}.zip"));
- assert!(!is_valid_typeshed_url_template(""));
- }
-
#[test]
fn nearer_typeshed_selection_replaces_inherited_selection_atomically() {
let ancestor_pin = BasiliskConfig {
diff --git a/crates/basilisk-db/src/cache.rs b/crates/basilisk-db/src/cache.rs
index a0aad4d1..a1e712bd 100644
--- a/crates/basilisk-db/src/cache.rs
+++ b/crates/basilisk-db/src/cache.rs
@@ -1,5 +1,5 @@
//! Implements [CHKCACHE-ENTRY] / [CHKCACHE-FINGERPRINT].
-//! See docs/specs/CHECKER-CACHE-SPEC.md#chkcache-entry
+//! See docs/specs/CHECKER-CACHE-SPEC.md#CHKCACHE-ENTRY
//!
//! A generic, content-addressed, on-disk result cache.
//!
diff --git a/crates/basilisk-db/tests/cache_tests.rs b/crates/basilisk-db/tests/cache_tests.rs
index 918bf7c5..311bc8ca 100644
--- a/crates/basilisk-db/tests/cache_tests.rs
+++ b/crates/basilisk-db/tests/cache_tests.rs
@@ -1,5 +1,5 @@
//! Tests for [CHKCACHE-ENTRY] / [CHKCACHE-FINGERPRINT] / [CHKCACHE-CONTRACT].
-//! See docs/specs/CHECKER-CACHE-SPEC.md#chkcache-entry
+//! See docs/specs/CHECKER-CACHE-SPEC.md#CHKCACHE-ENTRY
#![allow(clippy::allow_attributes, clippy::unwrap_used, clippy::expect_used)]
//! Crate-boundary tests for the result cache, covering every soundness branch:
//! a hit is returned only when the fingerprint and every recorded file match.
diff --git a/crates/basilisk-lsp/Cargo.toml b/crates/basilisk-lsp/Cargo.toml
index eca84ce1..56ebabb0 100644
--- a/crates/basilisk-lsp/Cargo.toml
+++ b/crates/basilisk-lsp/Cargo.toml
@@ -13,6 +13,7 @@ basilisk-checker.workspace = true
basilisk-common.workspace = true
basilisk-uv.workspace = true
basilisk-stubs.workspace = true
+basilisk-typeshed-fetch.workspace = true
basilisk-profiler-protocol.workspace = true
salsa.workspace = true
@@ -49,7 +50,7 @@ futures-util = "0.3"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "io-util", "net", "time"] }
serde_json = "1"
tempfile = "3"
-basilisk-test-utils = { workspace = true }
+basilisk-test-utils = { workspace = true, features = ["checker"] }
tower-service = "0.3"
[lints]
diff --git a/crates/basilisk-lsp/README.md b/crates/basilisk-lsp/README.md
index d0863ec3..f9e3ddcc 100644
--- a/crates/basilisk-lsp/README.md
+++ b/crates/basilisk-lsp/README.md
@@ -13,25 +13,33 @@ Editor ⟷ [basilisk-lsp] ⟷ parser + resolver + checker
## Key concepts
- **Full LSP** — not just a type checker. Provides completions, hover, go-to-definition, find references, rename, code actions, and inlay hints.
-- **Incremental analysis** — integrates with `basilisk-db` (Salsa) for sub-10ms response times on edits.
+- **Incremental analysis** — depends on `salsa` directly and drives the `BasiliskDatabase` re-exported by `basilisk-checker` (defined in `basilisk-db`), keeping one persistent database across the session so unchanged files are served from the memo ([CHKARCH-INCREMENTAL-SALSA](../../docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-INCREMENTAL-SALSA)).
- **Integrated debugging** — spawns debugpy and brokers DAP connections so editors get F5-to-debug without separate extensions.
- **Integrated profiling** — embeds py-spy for performance profiling with heatmap visualization.
-- **Ruff integration** — delegates formatting and import organization to Ruff via subprocess.
+- **Embedded Ruff formatter** — links the `ruff_python_formatter` crate into the binary and reimplements import hygiene natively on the Ruff AST. The `ruff` CLI is not a runtime dependency and is never spawned ([LSPFMT-ENGINE](../../docs/specs/LSP-FORMATTING-SPEC.md#LSPFMT-ENGINE), [LSPFMT-IMPORTS](../../docs/specs/LSP-FORMATTING-SPEC.md#LSPFMT-IMPORTS)).
- **Code actions & refactoring** — extract function/variable, rename, move symbol, inline, and more.
- **uv integration** — detects uv workspaces, parses lock files, and provides package intelligence.
## Dependencies
+Principal direct dependencies, as declared in `Cargo.toml`:
+
| Crate | Purpose |
|-------|---------|
| `basilisk-parser` | Parsing |
| `basilisk-resolver` | Name resolution |
-| `basilisk-checker` | Type checking |
+| `basilisk-checker` | Type checking; also re-exports `BasiliskDatabase` and the salsa inputs |
| `basilisk-config` | Configuration |
| `basilisk-stubs` | Type stubs |
-| `basilisk-db` | Incremental computation |
+| `basilisk-typeshed-fetch` | Typeshed acquisition |
| `basilisk-uv` | uv package manager |
+| `basilisk-profiler-protocol` | Profiler wire protocol |
+| `salsa` | Incremental computation |
| `tower-lsp` | LSP transport |
+| `ruff_python_formatter` | In-process formatting engine |
+
+There is no direct dependency on `basilisk-db`; the Salsa database type it
+defines reaches this crate through `basilisk-checker`'s re-export.
## Status
diff --git a/crates/basilisk-lsp/src/code_actions/stubs.rs b/crates/basilisk-lsp/src/code_actions/stubs.rs
index 763f49d0..8c8f87b6 100644
--- a/crates/basilisk-lsp/src/code_actions/stubs.rs
+++ b/crates/basilisk-lsp/src/code_actions/stubs.rs
@@ -1,4 +1,4 @@
-//! Implements [STUBRES-CREATE-LOCAL]. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#stubres-create-local
+//! Implements [STUBRES-CREATE-LOCAL]. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-CREATE-LOCAL
//!
//! Quick fix for BSK-0152 (missing type stubs): scaffold a local `.pyi` stub.
//!
diff --git a/crates/basilisk-lsp/src/completion/dot.rs b/crates/basilisk-lsp/src/completion/dot.rs
index 8ebcaeed..70ab3f17 100644
--- a/crates/basilisk-lsp/src/completion/dot.rs
+++ b/crates/basilisk-lsp/src/completion/dot.rs
@@ -27,7 +27,7 @@ pub(super) fn dot_completions(
}
if receiver.as_deref() == Some("self") {
- enclosing_class(resolved, byte_offset)
+ crate::hover::access::enclosing_class(resolved, byte_offset)
.map(|c| class_member_items(c, &prefix))
.unwrap_or_default()
} else if let Some(ref recv_name) = receiver {
@@ -77,26 +77,6 @@ fn builtin_class_member_items(
.collect()
}
-/// Find the innermost class that encloses `offset`.
-///
-/// A `self.` expression always sits inside a method body, which always
-/// follows its own `def` — so the enclosing class is the one owning the
-/// NEAREST PRECEDING method start, not the first method in the file
-/// (regression: members of the file's first class leaked into every later
-/// class).
-fn enclosing_class(
- resolved: &basilisk_resolver::ResolvedModule,
- offset: usize,
-) -> Option<&basilisk_resolver::scope::ClassInfo> {
- let func = resolved
- .functions
- .iter()
- .filter(|f| f.class_name.is_some() && f.def_span.start_usize() <= offset)
- .max_by_key(|f| f.def_span.start_usize())?;
- let class_name = func.class_name.as_ref()?;
- resolved.classes.iter().find(|c| &c.name == class_name)
-}
-
/// Build completion items for all attributes and methods of `class`.
fn class_member_items(
class: &basilisk_resolver::scope::ClassInfo,
diff --git a/crates/basilisk-lsp/src/config.rs b/crates/basilisk-lsp/src/config.rs
index 5be6a4fd..e60c1c53 100644
--- a/crates/basilisk-lsp/src/config.rs
+++ b/crates/basilisk-lsp/src/config.rs
@@ -8,17 +8,26 @@
use std::path::{Path, PathBuf};
-/// Controls which files the LSP server analyses.
+/// Controls which files the LSP server analyses ([ANALYSIS-MODES]).
///
-/// See `docs/LSP-ANALYSIS-MODES-SPEC.md` for the full specification.
+/// See `docs/specs/LSP-ANALYSIS-MODES-SPEC.md` for the full specification.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum AnalysisMode {
- /// Analyse only files currently open in the editor.
+ /// Analyse only files currently open in the editor ([ANALYSIS-OPEN]).
OpenFilesOnly,
- /// Analyse all workspace Python files (default, strict-by-default).
+ /// Analyse all workspace Python files, publishing diagnostics for closed
+ /// files too (default, strict-by-default) ([ANALYSIS-WHOLE]).
#[default]
WholeModule,
- /// Cross-file import graph analysis (reserved for future use).
+ /// `WholeModule` plus cross-file import-graph analysis ([ANALYSIS-CROSS]).
+ ///
+ /// Selects the cross-module salsa diagnostics query, so a file is checked
+ /// against the **current** content of the modules it imports
+ /// ([ANALYSIS-SYMBOLS-POP]); an edit to an open module's exports re-checks
+ /// that module's importers ([ANALYSIS-SYMBOLS-INVAL]); and the import graph
+ /// is built so navigation can answer "who imports this file?"
+ /// ([ANALYSIS-GRAPH]). The other modes check each file on its own, keeping
+ /// byte-for-byte `basilisk check` parity on what they report.
CrossModule,
}
@@ -110,16 +119,12 @@ pub struct WorkspaceConfig {
/// [STUBRES-CUSTOM-TYPESHED](../../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-CUSTOM-TYPESHED)).
/// `None` uses the bundled typeshed.
pub typeshed_path: Option,
- /// Exact full `python/typeshed` commit; unset selects Latest.
+ /// Exact full `python/typeshed` commit pin; unset resolves to the bundled
+ /// commit with an `UNPINNED` warning ([STUBRES-TYPESHED-CONFIG]).
pub typeshed_commit: Option,
- /// Optional `{sha}` archive mirror used only after a SHA is known.
- pub typeshed_url: Option,
- /// Optional directory for gate-accepted immutable archive cache entries.
- pub typeshed_cache_path: Option,
- /// Whether accepted archives may be reused during this run.
- pub typeshed_cache: bool,
- /// Whether consumed bytes must be bound to the selected Git tree.
- pub typeshed_verify: bool,
+ /// Optional verified content-addressed store directory
+ /// ([STUBRES-TYPESHED-STORE]); unset uses the per-user OS default.
+ pub typeshed_store_path: Option,
/// Redacted parse error for an explicitly malformed Typeshed key.
/// Acquisition fails closed instead of silently applying a default.
pub typeshed_configuration_error: Option,
@@ -153,10 +158,7 @@ impl Default for WorkspaceConfig {
stub_paths: Vec::new(),
typeshed_path: None,
typeshed_commit: None,
- typeshed_url: None,
- typeshed_cache_path: None,
- typeshed_cache: true,
- typeshed_verify: true,
+ typeshed_store_path: None,
typeshed_configuration_error: None,
formatter: FormatterEngine::Ruff,
format_style: FormatStyle::default(),
@@ -164,17 +166,21 @@ impl Default for WorkspaceConfig {
}
}
-/// Build the config-free acquisition request shared by CLI, LSP, and MCP.
+/// Build the config-free resolution request shared by CLI, LSP, and MCP.
/// Invalid or mutually exclusive raw settings fail closed here, including when
/// a file bypassed the configuration editor's stronger source validation.
///
+/// There are exactly two sources ([STUBRES-TYPESHED]): a pinned commit or a
+/// custom folder. An unset `typeshed-commit` resolves to the bundled commit as
+/// an implicit pin (still `UNPINNED`); resolution never downloads.
+///
/// # Errors
///
-/// Returns a redacted, user-facing reason for an invalid source, pin, or
-/// mirror template. The configured mirror value itself is never echoed.
+/// Returns a redacted, user-facing reason for an invalid source or pin.
pub fn typeshed_request(
config: &WorkspaceConfig,
) -> Result {
+ use basilisk_stubs::typeshed::bundle::bundled_commit_sha;
use basilisk_stubs::typeshed::gittree::Oid;
use basilisk_stubs::typeshed::source::{SourceSelection, TypeshedRequest};
@@ -185,13 +191,6 @@ pub fn typeshed_request(
if config.typeshed_path.is_some() && config.typeshed_commit.is_some() {
return Err("typeshed-path and typeshed-commit are mutually exclusive".to_owned());
}
- if config
- .typeshed_url
- .as_deref()
- .is_some_and(|url| !basilisk_config::is_valid_typeshed_url_template(url))
- {
- return Err("typeshed-url must be HTTPS with exactly one {sha} placeholder".to_owned());
- }
let selection = if let Some(path) = config.typeshed_path.as_deref() {
SourceSelection::Custom {
path: path
@@ -200,19 +199,22 @@ pub fn typeshed_request(
.to_owned(),
}
} else if let Some(commit) = config.typeshed_commit.as_deref() {
- SourceSelection::ExactCommit {
+ SourceSelection::Pinned {
commit: Oid::from_hex(commit).map_err(|_invalid_oid| {
"typeshed-commit must be a full 40-character hex SHA".to_owned()
})?,
+ explicit: true,
}
} else {
- SourceSelection::Latest
+ SourceSelection::Pinned {
+ commit: Oid::from_hex(bundled_commit_sha())
+ .map_err(|_invalid_oid| "bundled typeshed identity is unreadable".to_owned())?,
+ explicit: false,
+ }
};
Ok(TypeshedRequest {
selection,
- verify_content: config.typeshed_verify,
- use_cache: config.typeshed_cache,
- url_template: config.typeshed_url.clone(),
+ store_path: config.typeshed_store_path.clone(),
})
}
@@ -252,8 +254,8 @@ pub fn load_analysis_config(root: &Path) -> WorkspaceConfig {
cfg.typeshed_path = cfg
.typeshed_path
.map(|p| if p.is_absolute() { p } else { root.join(p) });
- cfg.typeshed_cache_path =
- cfg.typeshed_cache_path
+ cfg.typeshed_store_path =
+ cfg.typeshed_store_path
.map(|p| if p.is_absolute() { p } else { root.join(p) });
cfg
}
@@ -404,32 +406,11 @@ fn load_json_config(path: &Path) -> Option {
cfg.typeshed_commit = Some(v.to_owned());
}
if let Some(v) = obj
- .get("typeshedUrl")
- .or_else(|| obj.get("typeshed-url"))
+ .get("typeshedStorePath")
+ .or_else(|| obj.get("typeshed-store-path"))
.and_then(|v| v.as_str())
{
- cfg.typeshed_url = Some(v.to_owned());
- }
- if let Some(v) = obj
- .get("typeshedCachePath")
- .or_else(|| obj.get("typeshed-cache-path"))
- .and_then(|v| v.as_str())
- {
- cfg.typeshed_cache_path = Some(PathBuf::from(v));
- }
- if let Some(v) = obj
- .get("typeshedCache")
- .or_else(|| obj.get("typeshed-cache"))
- .and_then(serde_json::Value::as_bool)
- {
- cfg.typeshed_cache = v;
- }
- if let Some(v) = obj
- .get("typeshedVerify")
- .or_else(|| obj.get("typeshed-verify"))
- .and_then(serde_json::Value::as_bool)
- {
- cfg.typeshed_verify = v;
+ cfg.typeshed_store_path = Some(PathBuf::from(v));
}
Some(cfg)
@@ -506,17 +487,8 @@ fn workspace_config_from_toml(section: &toml::Table) -> WorkspaceConfig {
if let Some(v) = toml_str(section, &["typeshed-commit", "typeshedCommit"]) {
cfg.typeshed_commit = Some(v.to_owned());
}
- if let Some(v) = toml_str(section, &["typeshed-url", "typeshedUrl"]) {
- cfg.typeshed_url = Some(v.to_owned());
- }
- if let Some(v) = toml_str(section, &["typeshed-cache-path", "typeshedCachePath"]) {
- cfg.typeshed_cache_path = Some(PathBuf::from(v));
- }
- if let Some(v) = toml_bool(section, &["typeshed-cache", "typeshedCache"]) {
- cfg.typeshed_cache = v;
- }
- if let Some(v) = toml_bool(section, &["typeshed-verify", "typeshedVerify"]) {
- cfg.typeshed_verify = v;
+ if let Some(v) = toml_str(section, &["typeshed-store-path", "typeshedStorePath"]) {
+ cfg.typeshed_store_path = Some(PathBuf::from(v));
}
cfg
}
@@ -527,66 +499,28 @@ fn toml_str<'a>(table: &'a toml::Table, keys: &[&str]) -> Option<&'a str> {
.find_map(|key| table.get(*key).and_then(toml::Value::as_str))
}
-/// First boolean value found among the given key spellings.
-fn toml_bool(table: &toml::Table, keys: &[&str]) -> Option {
- keys.iter()
- .find_map(|key| table.get(*key).and_then(toml::Value::as_bool))
-}
+/// Every typeshed key holds a string ([STUBRES-TYPESHED-CONFIG]).
+const TYPESHED_STRING_KEYS: [&str; 6] = [
+ "typeshed-path",
+ "typeshedPath",
+ "typeshed-commit",
+ "typeshedCommit",
+ "typeshed-store-path",
+ "typeshedStorePath",
+];
fn toml_typeshed_type_error(table: &toml::Table) -> Option {
- for key in [
- "typeshed-path",
- "typeshedPath",
- "typeshed-commit",
- "typeshedCommit",
- "typeshed-url",
- "typeshedUrl",
- "typeshed-cache-path",
- "typeshedCachePath",
- ] {
- if table.get(key).is_some_and(|value| !value.is_str()) {
- return Some(format!("{key} must be a string"));
- }
- }
- for key in [
- "typeshed-cache",
- "typeshedCache",
- "typeshed-verify",
- "typeshedVerify",
- ] {
- if table.get(key).is_some_and(|value| !value.is_bool()) {
- return Some(format!("{key} must be a boolean"));
- }
- }
- None
+ TYPESHED_STRING_KEYS
+ .iter()
+ .find(|key| table.get(**key).is_some_and(|value| !value.is_str()))
+ .map(|key| format!("{key} must be a string"))
}
fn json_typeshed_type_error(object: &serde_json::Map) -> Option {
- for key in [
- "typeshed-path",
- "typeshedPath",
- "typeshed-commit",
- "typeshedCommit",
- "typeshed-url",
- "typeshedUrl",
- "typeshed-cache-path",
- "typeshedCachePath",
- ] {
- if object.get(key).is_some_and(|value| !value.is_string()) {
- return Some(format!("{key} must be a string"));
- }
- }
- for key in [
- "typeshed-cache",
- "typeshedCache",
- "typeshed-verify",
- "typeshedVerify",
- ] {
- if object.get(key).is_some_and(|value| !value.is_boolean()) {
- return Some(format!("{key} must be a boolean"));
- }
- }
- None
+ TYPESHED_STRING_KEYS
+ .iter()
+ .find(|key| object.get(**key).is_some_and(|value| !value.is_string()))
+ .map(|key| format!("{key} must be a string"))
}
/// First array value found among the given key spellings, as `PathBuf`s.
@@ -633,7 +567,7 @@ mod tests {
assert!(cfg.typeshed_path.is_none());
}
- /// [STUBRES-TYPESHED-CONFIG]: the LSP consumes the same complete source
+ /// [STUBRES-TYPESHED-CONFIG]: the LSP consumes the same three-key source
/// policy as the CLI/config crate; path fields are rooted at the workspace.
#[test]
fn test_load_runtime_typeshed_policy_from_pyproject() {
@@ -644,10 +578,7 @@ mod tests {
concat!(
"[tool.basilisk]\n",
"typeshed-commit = \"83c2518a9e6abbda0c44592c3483de459198f887\"\n",
- "typeshed-url = \"https://mirror.invalid/{sha}.zip\"\n",
- "typeshed-cache-path = \".cache/typeshed\"\n",
- "typeshed-cache = false\n",
- "typeshed-verify = false\n",
+ "typeshed-store-path = \".cache/typeshed-store\"\n",
),
)
.unwrap();
@@ -658,12 +589,9 @@ mod tests {
Some("83c2518a9e6abbda0c44592c3483de459198f887")
);
assert_eq!(
- cfg.typeshed_url.as_deref(),
- Some("https://mirror.invalid/{sha}.zip")
+ cfg.typeshed_store_path,
+ Some(dir.join(".cache/typeshed-store"))
);
- assert_eq!(cfg.typeshed_cache_path, Some(dir.join(".cache/typeshed")));
- assert!(!cfg.typeshed_cache);
- assert!(!cfg.typeshed_verify);
assert_eq!(cfg.python_version, None);
let _ = std::fs::remove_dir_all(&dir);
@@ -881,7 +809,7 @@ mod tests {
}
#[test]
- fn typeshed_request_rejects_raw_source_conflict_and_bad_mirror() {
+ fn typeshed_request_rejects_raw_source_conflict() {
let conflict = WorkspaceConfig {
typeshed_path: Some(PathBuf::from("custom")),
typeshed_commit: Some("83c2518a9e6abbda0c44592c3483de459198f887".to_owned()),
@@ -890,28 +818,16 @@ mod tests {
assert!(typeshed_request(&conflict)
.expect_err("conflicting source settings must fail closed")
.contains("mutually exclusive"));
-
- let mirror = WorkspaceConfig {
- typeshed_url: Some("http://secret.invalid/{sha}.zip".to_owned()),
- ..WorkspaceConfig::default()
- };
- let error = typeshed_request(&mirror).expect_err("HTTP mirror must fail closed");
- assert!(error.contains("HTTPS"));
- assert!(
- !error.contains("secret.invalid"),
- "mirror URL must be redacted"
- );
}
- /// [STUBRES-TYPESHED-CONFIG]: an explicitly malformed acquisition key
- /// cannot disappear into a default Latest/verified/cache-on request.
+ /// [STUBRES-TYPESHED-CONFIG]: an explicitly malformed typeshed key cannot
+ /// disappear into the default bundled-pin request.
#[test]
fn malformed_typeshed_setting_types_fail_closed() {
for source in [
"typeshed-commit = 42",
"typeshed-path = false",
- "typeshed-cache = \"false\"",
- "typeshed-verify = \"true\"",
+ "typeshed-store-path = false",
] {
let table: toml::Table = source.parse().expect("fixture TOML");
let config = workspace_config_from_toml(&table);
@@ -924,8 +840,7 @@ mod tests {
for (key, value) in [
("typeshedCommit", serde_json::json!(42)),
("typeshedPath", serde_json::json!(false)),
- ("typeshedCache", serde_json::json!("false")),
- ("typeshedVerify", serde_json::json!("true")),
+ ("typeshedStorePath", serde_json::json!(false)),
] {
let mut object = serde_json::Map::new();
let _ = object.insert(key.to_owned(), value);
@@ -940,21 +855,39 @@ mod tests {
}
}
+ /// [STUBRES-TYPESHED]: an explicit pin is an explicit `Pinned` selection;
+ /// unset keys resolve to the bundled commit as an implicit pin — the
+ /// request has no download, cache, or verification knobs at all.
#[test]
- fn typeshed_request_preserves_exact_policy_controls() {
+ fn typeshed_request_resolves_explicit_and_default_pins() {
+ use basilisk_stubs::typeshed::source::SourceSelection;
+
let config = WorkspaceConfig {
typeshed_commit: Some("83C2518A9E6ABBDA0C44592C3483DE459198F887".to_owned()),
- typeshed_url: Some("https://mirror.invalid/{sha}.zip".to_owned()),
- typeshed_cache: false,
- typeshed_verify: false,
+ typeshed_store_path: Some(PathBuf::from("/stores/typeshed")),
..WorkspaceConfig::default()
};
let request = typeshed_request(&config).expect("valid exact request");
assert!(matches!(
request.selection,
- basilisk_stubs::typeshed::source::SourceSelection::ExactCommit { .. }
+ SourceSelection::Pinned { explicit: true, .. }
));
- assert!(!request.use_cache);
- assert!(!request.verify_content);
+ assert_eq!(request.store_path, Some(PathBuf::from("/stores/typeshed")));
+
+ let default_request =
+ typeshed_request(&WorkspaceConfig::default()).expect("default request");
+ match default_request.selection {
+ SourceSelection::Pinned { commit, explicit } => {
+ assert!(!explicit, "an unset pin must stay UNPINNED");
+ assert_eq!(
+ commit.to_hex(),
+ basilisk_stubs::typeshed::bundle::bundled_commit_sha()
+ );
+ }
+ SourceSelection::Custom { .. } => {
+ unreachable!("an unset config must resolve to the bundled pin")
+ }
+ }
+ assert_eq!(default_request.store_path, None);
}
}
diff --git a/crates/basilisk-lsp/src/configuration_editor/mod.rs b/crates/basilisk-lsp/src/configuration_editor/mod.rs
index 041a7dab..8332ebbd 100644
--- a/crates/basilisk-lsp/src/configuration_editor/mod.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/mod.rs
@@ -10,14 +10,16 @@ mod snapshot;
pub(crate) mod snapshot_typeshed;
mod state;
mod transaction;
-mod typeshed_acquisition;
+mod typeshed_resolution;
mod watch;
+pub(crate) use protocol::rpc_error;
pub(crate) use state::ConfigurationEditorState;
pub(crate) use transaction::{
- apply_rule_updates, configuration_document, refresh_after_configuration_change,
- ConfigurationRefreshHandles,
+ apply_configuration_update, apply_rule_updates, configuration_document,
+ refresh_after_configuration_change, ConfigurationRefreshHandles,
};
+pub(crate) use typeshed_resolution::{resolve_and_activate, resolve_workspace};
pub(crate) use watch::{
refresh_environment_from_disk, refresh_root_from_disk, spawn_configuration_watcher,
};
diff --git a/crates/basilisk-lsp/src/configuration_editor/model.rs b/crates/basilisk-lsp/src/configuration_editor/model.rs
index bbae4e35..6c9a4563 100644
--- a/crates/basilisk-lsp/src/configuration_editor/model.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/model.rs
@@ -40,24 +40,14 @@ pub enum TagKind {
Descriptive,
}
-/// Closed allowlist of runtime Typeshed configuration keys.
+/// Closed allowlist of runtime Typeshed configuration keys — the whole
+/// surface is three keys, every one a string ([LSPCFGED-TYPESHED]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(tag = "kind")]
pub enum TypeshedSettingKey {
TypeshedPath,
TypeshedCommit,
- TypeshedUrl,
- TypeshedCachePath,
- TypeshedCache,
- TypeshedVerify,
-}
-
-/// Typed values accepted by Typeshed setting mutations.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(tag = "kind")]
-pub enum TypeshedSettingValue {
- Text { value: String },
- Boolean { value: bool },
+ TypeshedStorePath,
}
/// The six operations the editor may ask the configuration service to apply.
@@ -80,7 +70,7 @@ pub enum EditorMutation {
},
SetTypeshedSetting {
key: TypeshedSettingKey,
- value: TypeshedSettingValue,
+ value: String,
},
RemoveTypeshedSetting {
key: TypeshedSettingKey,
diff --git a/crates/basilisk-lsp/src/configuration_editor/model_typeshed.rs b/crates/basilisk-lsp/src/configuration_editor/model_typeshed.rs
index a2a386bd..f554d680 100644
--- a/crates/basilisk-lsp/src/configuration_editor/model_typeshed.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/model_typeshed.rs
@@ -2,89 +2,59 @@
use serde::{Deserialize, Serialize};
-use super::{
- ConfigurationPreview, ConfigurationSnapshot, Revision, TypeshedSettingKey,
- TypeshedSettingValue, Uri,
-};
-
-/// The active source and the value that defines it. A pinned commit and a
-/// custom folder cannot coexist, and `Latest` cannot carry a pin — the wire
-/// model makes those states unrepresentable ([LSPCFGED-TYPESHED]).
+use super::{ConfigurationSnapshot, Revision, TypeshedSettingKey, Uri};
+
+/// The active source and the value that defines it. There are exactly two
+/// sources ([LSPCFGED-TYPESHED]): a pinned commit or a custom folder. There is
+/// no "track latest" source — freshness is the user-invoked download action.
+/// An unset pin reports the bundled default commit (still `UNPINNED`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all_fields = "camelCase")]
pub enum TypeshedSource {
- Latest,
ExactCommit { commit: String },
CustomFolder { path: String },
}
-/// Download policy of a downloaded source. A user-managed folder downloads
-/// nothing, so it has none at all.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct TypeshedDownloadPolicy {
- pub reuse_downloads: bool,
- pub verify_content: bool,
- #[serde(skip_serializing_if = "Option::is_none")]
- pub archive_url: Option,
- #[serde(skip_serializing_if = "Option::is_none")]
- pub cache_folder: Option,
-}
-
+/// Downloading is the only long-running state, and it is always user-invoked
+/// ([LSPCFGED-TYPESHED-DOWNLOAD]). `NoSource` = the selected source is not on
+/// this machine, so analysis does not run.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind")]
pub enum TypeshedLifecycle {
- Acquiring,
+ Downloading,
Ready,
- Blocked,
+ NoSource,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind")]
pub enum TypeshedAction {
- PinCurrent,
- AcquireFresh,
+ DownloadLatest,
+ DownloadPinned,
ViewLicense,
}
+/// The active source is the whole trust story (custom = user-managed, bundled
+/// = build-vetted, exact commit = attested at download, re-proven offline), so
+/// there are no separate transport or provenance fields
+/// ([STUBRES-TYPESHED-WARN]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind")]
pub enum TypeshedActiveSource {
Custom,
ExactCommit,
- Latest,
Bundled,
}
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(tag = "kind")]
-pub enum TypeshedTransport {
- CustomPath,
- EmbeddedZip,
- Codeload,
- Mirror,
-}
-
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind")]
pub enum TypeshedLicenseStatus {
- Acquiring,
Unavailable,
Approved,
Changed,
NotSupplied,
}
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(tag = "kind")]
-pub enum TypeshedProvenance {
- Pending,
- GithubTlsAttested,
- Unverified,
- BundleVetted,
- UserManaged,
-}
-
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind")]
pub enum TypeshedWarningSeverity {
@@ -105,31 +75,25 @@ pub struct TypeshedWarningState {
pub struct TypeshedStatusState {
pub lifecycle: TypeshedLifecycle,
#[serde(skip_serializing_if = "Option::is_none")]
- pub blocked_reason: Option,
+ pub no_source_reason: Option,
#[serde(skip_serializing_if = "Option::is_none")]
pub active_source: Option,
#[serde(skip_serializing_if = "Option::is_none")]
pub commit_identity: Option,
- #[serde(skip_serializing_if = "Option::is_none")]
- pub transport: Option,
pub license_status: TypeshedLicenseStatus,
- pub provenance: TypeshedProvenance,
- pub signed_release: bool,
pub warnings: Vec,
}
+/// Everything the editor needs, and nothing it can misrender: the one active
+/// source, the store folder pins resolve from (none for a custom folder), and
+/// whether a license document exists to open. Labels are client copy, not
+/// server state.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
-/// Everything the editor needs and nothing it can misrender: the one active
-/// source, the download policy that source has, the commit
-/// [`TypeshedAction::PinCurrent`] would write when pinning is possible, and
-/// whether a license document exists to open. Labels are client copy.
pub struct TypeshedConfigurationState {
pub source: TypeshedSource,
#[serde(skip_serializing_if = "Option::is_none")]
- pub downloads: Option,
- #[serde(skip_serializing_if = "Option::is_none")]
- pub pinnable_commit: Option,
+ pub store_folder: Option,
pub license_available: bool,
pub status: TypeshedStatusState,
}
@@ -139,9 +103,9 @@ pub struct TypeshedConfigurationState {
pub struct TypeshedSettingChange {
pub key: TypeshedSettingKey,
#[serde(skip_serializing_if = "Option::is_none")]
- pub before: Option,
+ pub before: Option,
#[serde(skip_serializing_if = "Option::is_none")]
- pub after: Option,
+ pub after: Option,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -169,7 +133,6 @@ pub struct TypeshedLicenseDocument {
)]
#[serde(tag = "kind")]
pub enum TypeshedActionResult {
- Preview { preview: ConfigurationPreview },
Snapshot { snapshot: ConfigurationSnapshot },
License { license: TypeshedLicenseDocument },
}
diff --git a/crates/basilisk-lsp/src/configuration_editor/mutation.rs b/crates/basilisk-lsp/src/configuration_editor/mutation.rs
index 432d4fac..767c4472 100644
--- a/crates/basilisk-lsp/src/configuration_editor/mutation.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/mutation.rs
@@ -8,15 +8,13 @@
use std::collections::HashSet;
-use basilisk_config::{
- BasiliskConfig, ConfigDocument, ConfigurationUpdate, TypeshedConfigKey, TypeshedConfigValue,
-};
+use basilisk_config::{BasiliskConfig, ConfigDocument, ConfigurationUpdate, TypeshedConfigKey};
use tower_lsp::jsonrpc::{Error, Result as LspResult};
use super::catalog::{descriptors, effective_severity, wire_to_config, SelectionError};
use super::model::{
ConfigurationImpact, EditorMutation, ResolvedRuleChange, RuleDescriptor, RuleSeverity,
- TypeshedSettingChange, TypeshedSettingKey, TypeshedSettingValue,
+ TypeshedSettingChange, TypeshedSettingKey,
};
use super::protocol::{path_uri, rpc_error, rpc_error_data};
use super::snapshot::{count_i64, Inventory};
@@ -107,48 +105,27 @@ fn typeshed_config_key(key: TypeshedSettingKey) -> TypeshedConfigKey {
match key {
TypeshedSettingKey::TypeshedPath => TypeshedConfigKey::TypeshedPath,
TypeshedSettingKey::TypeshedCommit => TypeshedConfigKey::TypeshedCommit,
- TypeshedSettingKey::TypeshedUrl => TypeshedConfigKey::TypeshedUrl,
- TypeshedSettingKey::TypeshedCachePath => TypeshedConfigKey::TypeshedCachePath,
- TypeshedSettingKey::TypeshedCache => TypeshedConfigKey::TypeshedCache,
- TypeshedSettingKey::TypeshedVerify => TypeshedConfigKey::TypeshedVerify,
+ TypeshedSettingKey::TypeshedStorePath => TypeshedConfigKey::TypeshedStorePath,
}
}
-fn validate_typeshed_value(
- key: TypeshedSettingKey,
- value: &TypeshedSettingValue,
-) -> LspResult {
- match (key, value) {
- (TypeshedSettingKey::TypeshedCommit, TypeshedSettingValue::Text { value })
- if basilisk_config::is_full_commit_sha(value) =>
- {
- Ok(TypeshedConfigValue::Text(value.clone()))
+fn validate_typeshed_value(key: TypeshedSettingKey, value: &str) -> LspResult {
+ match key {
+ TypeshedSettingKey::TypeshedCommit if basilisk_config::is_full_commit_sha(value) => {
+ Ok(value.to_owned())
}
- (TypeshedSettingKey::TypeshedCommit, _) => Err(invalid_typeshed_setting(
+ TypeshedSettingKey::TypeshedCommit => Err(invalid_typeshed_setting(
key,
"typeshed-commit must be a full 40-character hexadecimal SHA",
)),
- (TypeshedSettingKey::TypeshedUrl, TypeshedSettingValue::Text { value })
- if basilisk_config::is_valid_typeshed_url_template(value) =>
+ TypeshedSettingKey::TypeshedPath | TypeshedSettingKey::TypeshedStorePath
+ if !value.trim().is_empty() =>
{
- Ok(TypeshedConfigValue::Text(value.clone()))
+ Ok(value.to_owned())
}
- (TypeshedSettingKey::TypeshedUrl, _) => Err(invalid_typeshed_setting(
- key,
- "typeshed-url must be HTTPS with exactly one {sha} placeholder",
- )),
- (
- TypeshedSettingKey::TypeshedPath | TypeshedSettingKey::TypeshedCachePath,
- TypeshedSettingValue::Text { value },
- ) if !value.trim().is_empty() => Ok(TypeshedConfigValue::Text(value.clone())),
- (
- TypeshedSettingKey::TypeshedCache | TypeshedSettingKey::TypeshedVerify,
- TypeshedSettingValue::Boolean { value },
- ) => Ok(TypeshedConfigValue::Boolean(*value)),
- _ => Err(invalid_typeshed_setting(
- key,
- "Typeshed setting has the wrong value type or an empty value",
- )),
+ TypeshedSettingKey::TypeshedPath | TypeshedSettingKey::TypeshedStorePath => Err(
+ invalid_typeshed_setting(key, "Typeshed setting requires a non-empty path"),
+ ),
}
}
@@ -254,41 +231,17 @@ pub(super) fn resolved_changes(
.collect()
}
-fn config_typeshed_value(
- config: &BasiliskConfig,
- key: TypeshedSettingKey,
-) -> Option {
+fn config_typeshed_value(config: &BasiliskConfig, key: TypeshedSettingKey) -> Option {
match key {
- TypeshedSettingKey::TypeshedPath => {
- config
- .typeshed_path
- .as_ref()
- .map(|path| TypeshedSettingValue::Text {
- value: path.to_string_lossy().into_owned(),
- })
- }
- TypeshedSettingKey::TypeshedCommit => config
- .typeshed_commit
- .clone()
- .map(|value| TypeshedSettingValue::Text { value }),
- TypeshedSettingKey::TypeshedUrl => config
- .typeshed_url
- .clone()
- .map(|value| TypeshedSettingValue::Text { value }),
- TypeshedSettingKey::TypeshedCachePath => {
- config
- .typeshed_cache_path
- .as_ref()
- .map(|path| TypeshedSettingValue::Text {
- value: path.to_string_lossy().into_owned(),
- })
- }
- TypeshedSettingKey::TypeshedCache => config
- .typeshed_cache
- .map(|value| TypeshedSettingValue::Boolean { value }),
- TypeshedSettingKey::TypeshedVerify => config
- .typeshed_verify
- .map(|value| TypeshedSettingValue::Boolean { value }),
+ TypeshedSettingKey::TypeshedPath => config
+ .typeshed_path
+ .as_ref()
+ .map(|path| path.to_string_lossy().into_owned()),
+ TypeshedSettingKey::TypeshedCommit => config.typeshed_commit.clone(),
+ TypeshedSettingKey::TypeshedStorePath => config
+ .typeshed_store_path
+ .as_ref()
+ .map(|path| path.to_string_lossy().into_owned()),
}
}
@@ -300,10 +253,7 @@ pub(super) fn resolved_typeshed_changes(
[
TypeshedSettingKey::TypeshedPath,
TypeshedSettingKey::TypeshedCommit,
- TypeshedSettingKey::TypeshedUrl,
- TypeshedSettingKey::TypeshedCachePath,
- TypeshedSettingKey::TypeshedCache,
- TypeshedSettingKey::TypeshedVerify,
+ TypeshedSettingKey::TypeshedStorePath,
]
.into_iter()
.filter_map(|key| {
diff --git a/crates/basilisk-lsp/src/configuration_editor/mutation_tests.rs b/crates/basilisk-lsp/src/configuration_editor/mutation_tests.rs
index 248e7e56..363eee1a 100644
--- a/crates/basilisk-lsp/src/configuration_editor/mutation_tests.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/mutation_tests.rs
@@ -11,7 +11,6 @@ use std::path::PathBuf;
use basilisk_config::{
build_configuration_patch, BasiliskConfig, ConfigDocument, RuleSeverity, TypeshedConfigKey,
- TypeshedConfigValue,
};
use super::{
@@ -21,7 +20,7 @@ use super::{
};
use crate::configuration_editor::catalog::{descriptors, SelectionError};
use crate::configuration_editor::model::{
- EditorMutation, RuleSeverity as WireSeverity, TypeshedSettingKey, TypeshedSettingValue,
+ EditorMutation, RuleSeverity as WireSeverity, TypeshedSettingKey,
};
use crate::configuration_editor::snapshot::Inventory;
@@ -89,11 +88,11 @@ fn build_update_folds_all_six_mutations_into_entry_updates() {
tag: "suppressions".to_owned(),
},
EditorMutation::SetTypeshedSetting {
- key: TypeshedSettingKey::TypeshedCache,
- value: TypeshedSettingValue::Boolean { value: false },
+ key: TypeshedSettingKey::TypeshedStorePath,
+ value: "stores/typeshed".to_owned(),
},
EditorMutation::RemoveTypeshedSetting {
- key: TypeshedSettingKey::TypeshedUrl,
+ key: TypeshedSettingKey::TypeshedPath,
},
],
&catalog,
@@ -115,11 +114,14 @@ fn build_update_folds_all_six_mutations_into_entry_updates() {
update
.typeshed
.entries
- .get(&TypeshedConfigKey::TypeshedCache),
- Some(&Some(TypeshedConfigValue::Boolean(false)))
+ .get(&TypeshedConfigKey::TypeshedStorePath),
+ Some(&Some("stores/typeshed".to_owned()))
);
assert_eq!(
- update.typeshed.entries.get(&TypeshedConfigKey::TypeshedUrl),
+ update
+ .typeshed
+ .entries
+ .get(&TypeshedConfigKey::TypeshedPath),
Some(&None)
);
}
@@ -216,29 +218,23 @@ fn pep_disable_mutations_are_rejected() {
);
}
-/// [LSPCFGED-TYPESHED]: Typeshed settings reject wrong scalar types,
-/// malformed pins, and non-HTTPS/multi-placeholder mirrors.
+/// [LSPCFGED-TYPESHED]: the whole surface is three string keys — malformed
+/// pins and blank paths are request errors, and a full SHA passes.
#[test]
fn typeshed_setting_values_are_strictly_validated() {
let catalog = descriptors();
for mutation in [
EditorMutation::SetTypeshedSetting {
key: TypeshedSettingKey::TypeshedCommit,
- value: TypeshedSettingValue::Text {
- value: "short".to_owned(),
- },
+ value: "short".to_owned(),
},
EditorMutation::SetTypeshedSetting {
- key: TypeshedSettingKey::TypeshedUrl,
- value: TypeshedSettingValue::Text {
- value: "http://mirror.invalid/{sha}/{sha}.zip".to_owned(),
- },
+ key: TypeshedSettingKey::TypeshedPath,
+ value: " ".to_owned(),
},
EditorMutation::SetTypeshedSetting {
- key: TypeshedSettingKey::TypeshedVerify,
- value: TypeshedSettingValue::Text {
- value: "false".to_owned(),
- },
+ key: TypeshedSettingKey::TypeshedStorePath,
+ value: String::new(),
},
] {
let result = build_update(&[mutation], &catalog);
@@ -249,6 +245,14 @@ fn typeshed_setting_values_are_strictly_validated() {
Some(serde_json::json!("invalidTypeshedSetting"))
);
}
+ assert!(build_update(
+ &[EditorMutation::SetTypeshedSetting {
+ key: TypeshedSettingKey::TypeshedCommit,
+ value: "83c2518a9e6abbda0c44592c3483de459198f887".to_owned(),
+ }],
+ &catalog,
+ )
+ .is_ok());
}
/// [LSPCFGED-TYPESHED]: custom and exact sources cannot coexist, and custom
@@ -317,10 +321,7 @@ fn resolved_typeshed_changes_cover_the_closed_setting_allowlist() {
let after = BasiliskConfig {
typeshed_path: Some(PathBuf::from("custom-typeshed")),
typeshed_commit: Some("83c2518a9e6abbda0c44592c3483de459198f887".to_owned()),
- typeshed_url: Some("https://mirror.example/{sha}.zip".to_owned()),
- typeshed_cache_path: Some(PathBuf::from(".typeshed-cache")),
- typeshed_cache: Some(false),
- typeshed_verify: Some(false),
+ typeshed_store_path: Some(PathBuf::from("stores/typeshed")),
..BasiliskConfig::default()
};
@@ -331,10 +332,7 @@ fn resolved_typeshed_changes_cover_the_closed_setting_allowlist() {
vec![
TypeshedSettingKey::TypeshedPath,
TypeshedSettingKey::TypeshedCommit,
- TypeshedSettingKey::TypeshedUrl,
- TypeshedSettingKey::TypeshedCachePath,
- TypeshedSettingKey::TypeshedCache,
- TypeshedSettingKey::TypeshedVerify,
+ TypeshedSettingKey::TypeshedStorePath,
]
);
assert!(changes.iter().all(|change| change.before.is_none()));
diff --git a/crates/basilisk-lsp/src/configuration_editor/protocol.rs b/crates/basilisk-lsp/src/configuration_editor/protocol.rs
index 1f27e045..18abd61e 100644
--- a/crates/basilisk-lsp/src/configuration_editor/protocol.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/protocol.rs
@@ -12,10 +12,9 @@ use tower_lsp::lsp_types::Url;
use super::catalog::{descriptors, expand_selector};
use super::model::{
- ApplyConfigurationRequest, ConfigurationPreview, ConfigurationSnapshot, EditorMutation,
+ ApplyConfigurationRequest, ConfigurationPreview, ConfigurationSnapshot,
PreviewConfigurationRequest, RuleOccurrencesRequest, RuleOccurrencesResponse, TypeshedAction,
- TypeshedActionRequest, TypeshedActionResult, TypeshedLicenseDocument, TypeshedSettingKey,
- TypeshedSettingValue,
+ TypeshedActionRequest, TypeshedActionResult, TypeshedLicenseDocument,
};
use super::mutation::{
build_impact, build_update, require_mutations, require_no_pep_disable, require_revision,
@@ -175,7 +174,10 @@ impl LspServer {
))
}
- /// Handle the closed Typeshed action union ([LSPCFGED-TYPESHED]).
+ /// Handle the closed Typeshed action union ([LSPCFGED-TYPESHED]). The two
+ /// download actions are the ONLY paths that reach the network, and both
+ /// live outside the configuration editor ([TYPESHEDRT-SEGREGATION]);
+ /// their finished state is returned as a fresh snapshot.
pub(crate) async fn typeshed_action(
&self,
request: TypeshedActionRequest,
@@ -187,115 +189,20 @@ impl LspServer {
.map_err(config_error)?;
require_revision(&document, &request.base_revision)?;
match request.action {
- TypeshedAction::PinCurrent => self.pin_current_action(&root, &document, request).await,
- TypeshedAction::AcquireFresh => self.acquire_fresh_action(&root, &document).await,
- TypeshedAction::ViewLicense => self.view_license_action(&root, &document).await,
- }
- }
-
- async fn pin_current_action(
- &self,
- root: &Path,
- document: &ConfigDocument,
- request: TypeshedActionRequest,
- ) -> LspResult {
- if document.config.typeshed_path.is_some() {
- return Err(rpc_error(
- "typeshedActionUnavailable",
- "a custom Typeshed folder has no upstream commit to pin",
- ));
- }
- let commit = self
- .typeshed_generations
- .read()
- .await
- .get(root)
- .and_then(crate::server::typeshed_status::TypeshedGeneration::ready_snapshot)
- .filter(|snapshot| snapshot_matches_document(snapshot, document))
- .and_then(|snapshot| snapshot.status.commit)
- .ok_or_else(|| {
- rpc_error(
- "typeshedActionUnavailable",
- "the active Typeshed source has no commit to pin",
- )
- })?
- .to_hex();
- let preview = self
- .preview_configuration_change(PreviewConfigurationRequest {
- root_uri: request.root_uri,
- base_revision: request.base_revision,
- mutations: vec![
- EditorMutation::SetTypeshedSetting {
- key: TypeshedSettingKey::TypeshedCommit,
- value: TypeshedSettingValue::Text { value: commit },
- },
- EditorMutation::RemoveTypeshedSetting {
- key: TypeshedSettingKey::TypeshedPath,
- },
- ],
- })
- .await?;
- Ok(TypeshedActionResult::Preview { preview })
- }
-
- async fn acquire_fresh_action(
- &self,
- root: &Path,
- document: &ConfigDocument,
- ) -> LspResult {
- let staged = match super::typeshed_acquisition::acquire_fresh(self, root, &document.config)
- .await
- {
- Ok(staged) => staged,
- Err(error) => {
- let rpc_error = error.rpc_error();
- let Some(failure) = error.into_failure() else {
- return Err(rpc_error);
- };
- let handles = self.refresh_handles();
- let refresh = super::transaction::refresh_with_document(
- &handles,
- root,
- "typeshedAcquireFreshFailed",
- document,
- )
- .await;
- super::typeshed_acquisition::publish_failure(&handles, root, failure).await;
- if let Err(error) = refresh {
- tracing::warn!(root = %root.display(), error = %error, "failed to clear analysis after Typeshed refresh failure");
- }
- return Err(rpc_error);
+ TypeshedAction::DownloadLatest => {
+ crate::typeshed_download::download_latest_and_pin(self, &root, &document).await?;
+ Ok(TypeshedActionResult::Snapshot {
+ snapshot: snapshot_for_root(self, &root).await?,
+ })
}
- };
- let handles = self.refresh_handles();
- let refresh = super::transaction::refresh_with_document_and_typeshed(
- &handles,
- root,
- "typeshedAcquireFresh",
- document,
- Some(staged.candidate()),
- )
- .await;
- if let Err(error) = refresh {
- let cleanup = super::transaction::refresh_with_document(
- &handles,
- root,
- "typeshedAcquireFreshBlocked",
- document,
- )
- .await;
- staged
- .block(self, root, "configuration refresh failed")
- .await;
- if let Err(cleanup_error) = cleanup {
- tracing::warn!(root = %root.display(), error = %cleanup_error, "failed to clear analysis after Typeshed activation failure");
+ TypeshedAction::DownloadPinned => {
+ crate::typeshed_download::download_pinned(self, &root, &document).await?;
+ Ok(TypeshedActionResult::Snapshot {
+ snapshot: snapshot_for_root(self, &root).await?,
+ })
}
- return Err(error);
+ TypeshedAction::ViewLicense => self.view_license_action(&root, &document).await,
}
- staged.activate(self, root).await;
- Ok(TypeshedActionResult::Snapshot {
- snapshot: snapshot_with_document(self, root, document).await?,
- })
}
async fn view_license_action(
@@ -321,7 +228,7 @@ impl LspServer {
.ok_or_else(|| {
rpc_error(
"typeshedActionUnavailable",
- "Typeshed acquisition for this workspace has not reached a terminal source",
+ "the selected Typeshed source is not on this machine, so no license document is available",
)
})?;
let content = snapshot
@@ -348,17 +255,17 @@ fn snapshot_matches_document(
return snapshot.status.active_source
== basilisk_stubs::typeshed::source::SourceKind::Custom;
}
- match document.config.typeshed_commit.as_deref() {
- Some(commit) => snapshot
- .status
- .commit
- .is_some_and(|oid| oid.to_hex() == commit),
- None => matches!(
- snapshot.status.active_source,
- basilisk_stubs::typeshed::source::SourceKind::Latest
- | basilisk_stubs::typeshed::source::SourceKind::Bundled
- ),
- }
+ // An unset pin IS the bundled commit ([STUBRES-TYPESHED]), so the active
+ // snapshot matches when it carries the effective SHA.
+ let effective_commit = document
+ .config
+ .typeshed_commit
+ .clone()
+ .unwrap_or_else(|| basilisk_stubs::typeshed::bundle::bundled_commit_sha().to_owned());
+ snapshot
+ .status
+ .commit
+ .is_some_and(|oid| oid.to_hex() == effective_commit)
}
async fn snapshot_for_root(server: &LspServer, root: &Path) -> LspResult {
@@ -430,7 +337,7 @@ pub(super) fn config_error(error: ConfigDocumentError) -> Error {
)
}
-pub(super) fn rpc_error(kind: &str, message: &str) -> Error {
+pub(crate) fn rpc_error(kind: &str, message: &str) -> Error {
rpc_error_data(kind, message, serde_json::json!({}))
}
diff --git a/crates/basilisk-lsp/src/configuration_editor/protocol_tests.rs b/crates/basilisk-lsp/src/configuration_editor/protocol_tests.rs
index 068086a8..1e94b7bc 100644
--- a/crates/basilisk-lsp/src/configuration_editor/protocol_tests.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/protocol_tests.rs
@@ -1,4 +1,5 @@
-//! Unit tests for configuration-editor protocol guards.
+//! Unit tests for configuration-editor protocol guards and the atomic
+//! Typeshed configuration transaction ([LSPCFGED-TYPESHED]).
use basilisk_config::{BasiliskConfig, ConfigDocument};
@@ -58,47 +59,15 @@ fn snapshot_guards_reject_cross_mode_and_cross_commit_actions() {
type TestResult = Result>;
-fn latest_snapshot(
- commit: basilisk_stubs::typeshed::gittree::Oid,
-) -> TestResult {
- use basilisk_stubs::typeshed::archive::ArchiveVfs;
- use basilisk_stubs::typeshed::snapshot::Snapshot;
- use basilisk_stubs::typeshed::source::{
- Provenance, SourceIdentity, SourceKind, StatusWarning, Transport,
- };
- use basilisk_stubs::typeshed::warning::{TypeshedWarning, UnpinnedKind};
-
- let bundled = basilisk_stubs::typeshed::bundle::bundled_snapshot()?;
- let archive = bundled.vfs.archive().clone();
- let tree = archive.root_tree_oid()?;
- let identity = SourceIdentity::Commit {
- commit,
- pinned: false,
- };
- let mut status = bundled.status.clone();
- status.active_source = SourceKind::Latest;
- status.commit = Some(commit);
- status.tree = Some(tree);
- status.transport = Transport::Codeload;
- status.provenance = Provenance::GithubTlsAttested;
- status.license_reference = Some(format!(
- "https://github.com/python/typeshed/blob/{}/LICENSE",
- commit.to_hex()
- ));
- status.warnings =
- StatusWarning::list(&[TypeshedWarning::Unpinned(UnpinnedKind::LatestOrBundled)]);
- let identity_key = identity.uri_component();
- Ok(Snapshot::build(
- identity,
- status,
- ArchiveVfs::new(identity_key, archive),
- None,
- )?)
-}
+type ClientMessages = tokio::sync::mpsc::UnboundedReceiver<(String, serde_json::Value)>;
-async fn initialized_test_service() -> TestResult<(
+/// Spin up an initialized in-process server whose client pump records every
+/// client-bound message and answers `workspace/applyEdit` with `approve`.
+async fn initialized_test_service(
+ approve_edits: bool,
+) -> TestResult<(
tower_lsp::LspService,
- tokio::sync::mpsc::UnboundedReceiver,
+ ClientMessages,
tokio::task::JoinHandle<()>,
)> {
use futures_util::{SinkExt as _, StreamExt as _};
@@ -106,17 +75,17 @@ async fn initialized_test_service() -> TestResult<(
let (mut service, socket) = tower_lsp::LspService::new(crate::server::LspServer::new);
let (mut requests, mut responses) = socket.split();
- let (apply_tx, apply_rx) = tokio::sync::mpsc::unbounded_channel();
+ let (message_tx, message_rx) = tokio::sync::mpsc::unbounded_channel();
let pump = tokio::spawn(async move {
while let Some(request) = requests.next().await {
+ let method = request.method().to_owned();
+ let params = request.params().cloned().unwrap_or(serde_json::Value::Null);
+ let _ = message_tx.send((method.clone(), params));
let Some(id) = request.id().cloned() else {
continue;
};
- let result = if request.method() == "workspace/applyEdit" {
- if let Some(params) = request.params().cloned() {
- let _ = apply_tx.send(params);
- }
- serde_json::json!({ "applied": true })
+ let result = if method == "workspace/applyEdit" {
+ serde_json::json!({ "applied": approve_edits })
} else {
serde_json::Value::Null
};
@@ -153,100 +122,297 @@ async fn initialized_test_service() -> TestResult<(
if let Some(watcher) = service.inner().config_watcher.lock().await.take() {
watcher.abort();
}
- Ok((service, apply_rx, pump))
+ Ok((service, message_rx, pump))
}
-async fn pin_current_round_trip(
- snapshot: basilisk_stubs::typeshed::snapshot::Snapshot,
-) -> TestResult<()> {
+/// Register one temporary workspace root with an active bundled generation.
+async fn install_bundled_root(
+ server: &crate::server::LspServer,
+) -> TestResult<(tempfile::TempDir, String, std::path::PathBuf)> {
use std::sync::Arc;
- use super::super::model::{
- ApplyConfigurationRequest, TypeshedAction, TypeshedActionRequest, TypeshedActionResult,
- };
use crate::config::AnalysisMode;
use crate::server::typeshed_status::TypeshedGeneration;
use crate::workspace::WorkspaceIndex;
- let expected = snapshot
- .status
- .commit
- .ok_or("active snapshot has no commit")?
- .to_hex();
let root = tempfile::tempdir()?;
std::fs::write(root.path().join("pyproject.toml"), "[tool.basilisk]\n")?;
let root_path = root.path().to_path_buf();
let root_uri = tower_lsp::lsp_types::Url::from_file_path(&root_path)
.map_err(|()| "temporary root has no file URI")?
.to_string();
- let (service, mut apply_rx, pump) = initialized_test_service().await?;
- let server = service.inner();
*server.workspace_roots.write().await = vec![root_path.clone()];
*server.index.write().await = Some(WorkspaceIndex::new(
vec![root_path.clone()],
AnalysisMode::WholeModule,
BasiliskConfig::default(),
));
+ let snapshot = basilisk_stubs::typeshed::bundle::bundled_snapshot()?;
let _ = server.typeshed_generations.write().await.insert(
root_path.clone(),
TypeshedGeneration::Ready(Arc::new(snapshot)),
);
+ Ok((root, root_uri, root_path))
+}
+
+/// Drain recorded client messages until `method` is seen or the budget ends.
+async fn drain_messages_until(
+ messages: &mut ClientMessages,
+ method: &str,
+) -> Vec<(String, serde_json::Value)> {
+ let mut seen = Vec::new();
+ let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(3);
+ loop {
+ let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+ match tokio::time::timeout(remaining, messages.recv()).await {
+ Ok(Some(message)) => {
+ let matched = message.0 == method;
+ seen.push(message);
+ if matched {
+ return seen;
+ }
+ }
+ Ok(None) | Err(_) => return seen,
+ }
+ }
+}
+
+fn status_lifecycles(messages: &[(String, serde_json::Value)]) -> Vec {
+ messages
+ .iter()
+ .filter(|(method, _)| {
+ method == basilisk_common::configuration_editor::TYPESHED_STATUS_CHANGED
+ })
+ .filter_map(|(_, params)| params.pointer("/status/lifecycle/kind"))
+ .filter_map(serde_json::Value::as_str)
+ .map(str::to_owned)
+ .collect()
+}
+
+async fn preview_and_apply(
+ server: &crate::server::LspServer,
+ root_uri: &str,
+ mutations: Vec,
+) -> tower_lsp::jsonrpc::Result {
+ use super::super::model::{ApplyConfigurationRequest, PreviewConfigurationRequest};
let current = server
.configuration_snapshot(ConfigurationSnapshotRequest {
- root_uri: root_uri.clone(),
+ root_uri: root_uri.to_owned(),
})
.await?;
- let action = server
- .typeshed_action(TypeshedActionRequest {
- root_uri: root_uri.clone(),
+ let preview = server
+ .preview_configuration_change(PreviewConfigurationRequest {
+ root_uri: root_uri.to_owned(),
base_revision: current.revision,
- action: TypeshedAction::PinCurrent,
+ mutations,
})
.await?;
- let TypeshedActionResult::Preview { preview } = action else {
- return Err("Pin current did not return a preview".into());
- };
- let _applied = server
+ server
.apply_configuration_change(ApplyConfigurationRequest {
- root_uri,
+ root_uri: root_uri.to_owned(),
preview_id: preview.preview_id,
})
- .await?;
+ .await
+}
+
+/// [LSPCFGED-TYPESHED] — the UI-glitch proof: setting the pin lands the edit
+/// and publishes ONLY the terminal Ready status. No acquiring, blocked, or
+/// downloading state ever reaches the wire on a configuration change.
+#[tokio::test]
+async fn pin_edit_applies_atomically_without_intermediate_states() -> TestResult<()> {
+ use super::super::model::{EditorMutation, TypeshedLifecycle, TypeshedSettingKey};
+
+ let expected = basilisk_stubs::typeshed::bundle::bundled_commit_sha();
+ let (service, mut messages, pump) = initialized_test_service(true).await?;
+ let server = service.inner();
+ let (_root, root_uri, root_path) = install_bundled_root(server).await?;
+
+ let applied = preview_and_apply(
+ server,
+ &root_uri,
+ vec![EditorMutation::SetTypeshedSetting {
+ key: TypeshedSettingKey::TypeshedCommit,
+ value: expected.to_owned(),
+ }],
+ )
+ .await?;
+ assert_eq!(applied.typeshed.status.lifecycle, TypeshedLifecycle::Ready);
- let apply_edit = tokio::time::timeout(std::time::Duration::from_secs(2), apply_rx.recv())
- .await?
- .ok_or("Pin current sent no workspace edit")?;
- let edited_text = apply_edit
- .pointer("/edit/documentChanges/0/edits/0/newText")
+ let seen = drain_messages_until(
+ &mut messages,
+ basilisk_common::configuration_editor::TYPESHED_STATUS_CHANGED,
+ )
+ .await;
+ let edit_text = seen
+ .iter()
+ .find(|(method, _)| method == "workspace/applyEdit")
+ .and_then(|(_, params)| params.pointer("/edit/documentChanges/0/edits/0/newText"))
.and_then(serde_json::Value::as_str)
- .ok_or("Pin current workspace edit carried no replacement text")?;
+ .ok_or("pin apply sent no workspace edit")?;
assert!(
- edited_text.contains(&format!("typeshed-commit = \"{expected}\"")),
- "workspace edit must write the active commit: {edited_text}"
+ edit_text.contains(&format!("typeshed-commit = \"{expected}\"")),
+ "workspace edit must write the pin: {edit_text}"
+ );
+ let lifecycles = status_lifecycles(&seen);
+ assert_eq!(
+ lifecycles,
+ vec!["Ready".to_owned()],
+ "one terminal publish, nothing intermediate"
);
let document = server.configuration_editor.effective_document(&root_path)?;
+ assert_eq!(document.config.typeshed_commit.as_deref(), Some(expected));
+ pump.abort();
+ Ok(())
+}
+
+/// [STUBRES-TYPESHED-PIN]: a valid pin that is not on this machine is VALID
+/// configuration — the edit lands, nothing downloads, and the root publishes
+/// the terminal NO SOURCE state naming the recovery commands.
+#[tokio::test]
+async fn missing_pin_tanks_to_terminal_no_source_without_downloading() -> TestResult<()> {
+ use super::super::model::{EditorMutation, TypeshedLifecycle, TypeshedSettingKey};
+
+ let missing = "0123456789012345678901234567890123456789";
+ let empty_store = tempfile::tempdir()?;
+ let (service, mut messages, pump) = initialized_test_service(true).await?;
+ let server = service.inner();
+ let (_root, root_uri, root_path) = install_bundled_root(server).await?;
+
+ let applied = preview_and_apply(
+ server,
+ &root_uri,
+ vec![
+ EditorMutation::SetTypeshedSetting {
+ key: TypeshedSettingKey::TypeshedCommit,
+ value: missing.to_owned(),
+ },
+ EditorMutation::SetTypeshedSetting {
+ key: TypeshedSettingKey::TypeshedStorePath,
+ value: empty_store.path().to_string_lossy().into_owned(),
+ },
+ ],
+ )
+ .await?;
assert_eq!(
- document.config.typeshed_commit.as_deref(),
- Some(expected.as_str())
+ applied.typeshed.status.lifecycle,
+ TypeshedLifecycle::NoSource
);
- assert!(document
- .content
- .contains(&format!("typeshed-commit = \"{expected}\"")));
+
+ let seen = drain_messages_until(
+ &mut messages,
+ basilisk_common::configuration_editor::TYPESHED_STATUS_CHANGED,
+ )
+ .await;
+ let lifecycles = status_lifecycles(&seen);
+ assert_eq!(
+ lifecycles,
+ vec!["NoSource".to_owned()],
+ "a missing pin publishes exactly one terminal state and never Downloading"
+ );
+ let reason = seen
+ .iter()
+ .rev()
+ .find(|(method, _)| {
+ method == basilisk_common::configuration_editor::TYPESHED_STATUS_CHANGED
+ })
+ .and_then(|(_, params)| params.pointer("/status/noSourceReason"))
+ .and_then(serde_json::Value::as_str)
+ .ok_or("NoSource status carried no reason")?;
+ assert!(reason.contains("NO SOURCE"), "loud reason: {reason}");
+ assert!(reason.contains(missing), "reason names the pin: {reason}");
+ assert!(
+ reason.contains("basilisk typeshed download"),
+ "reason names the recovery command: {reason}"
+ );
+ // The store stayed byte-empty: nothing attempted a download.
+ assert_eq!(
+ std::fs::read_dir(empty_store.path())?.count(),
+ 0,
+ "resolution must never write or fetch"
+ );
+ let document = server.configuration_editor.effective_document(&root_path)?;
+ assert_eq!(document.config.typeshed_commit.as_deref(), Some(missing));
pump.abort();
Ok(())
}
+/// A rejected client edit publishes NOTHING: the staged generation is
+/// dropped, the previous source keeps serving, and no status flickers.
#[tokio::test]
-async fn pin_current_applies_the_latest_active_commit() -> TestResult<()> {
- let commit = basilisk_stubs::typeshed::gittree::Oid::from_hex(
- "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
- )?;
- pin_current_round_trip(latest_snapshot(commit)?).await
+async fn rejected_edit_publishes_no_status_change() -> TestResult<()> {
+ use super::super::model::{EditorMutation, TypeshedSettingKey};
+ use crate::server::typeshed_status::TypeshedGeneration;
+
+ let (service, mut messages, pump) = initialized_test_service(false).await?;
+ let server = service.inner();
+ let (_root, root_uri, root_path) = install_bundled_root(server).await?;
+
+ let result = preview_and_apply(
+ server,
+ &root_uri,
+ vec![EditorMutation::SetTypeshedSetting {
+ key: TypeshedSettingKey::TypeshedCommit,
+ value: "0123456789012345678901234567890123456789".to_owned(),
+ }],
+ )
+ .await;
+ assert!(result.is_err(), "a rejected edit must fail the apply");
+
+ let seen = drain_messages_until(&mut messages, "workspace/applyEdit").await;
+ assert!(
+ status_lifecycles(&seen).is_empty(),
+ "no status may be published for an unapplied edit"
+ );
+ let generation = server
+ .typeshed_generations
+ .read()
+ .await
+ .get(&root_path)
+ .cloned();
+ assert!(
+ generation
+ .as_ref()
+ .and_then(TypeshedGeneration::ready_snapshot)
+ .is_some(),
+ "the previous Ready generation must survive a rejected edit"
+ );
+ pump.abort();
+ Ok(())
}
+/// [LSPCFGED-TYPESHED]: `ViewLicense` returns the active immutable license
+/// document for the effective bundled pin.
#[tokio::test]
-async fn pin_current_offline_applies_the_bundled_commit() -> TestResult<()> {
- let snapshot = basilisk_stubs::typeshed::bundle::bundled_snapshot()?;
- pin_current_round_trip(snapshot).await
+async fn view_license_returns_the_active_immutable_license() -> TestResult<()> {
+ use super::super::model::{TypeshedAction, TypeshedActionRequest, TypeshedActionResult};
+
+ let (service, mut messages, pump) = initialized_test_service(true).await?;
+ let server = service.inner();
+ let (_root, root_uri, _root_path) = install_bundled_root(server).await?;
+
+ let current = server
+ .configuration_snapshot(ConfigurationSnapshotRequest {
+ root_uri: root_uri.clone(),
+ })
+ .await?;
+ let action = server
+ .typeshed_action(TypeshedActionRequest {
+ root_uri,
+ base_revision: current.revision,
+ action: TypeshedAction::ViewLicense,
+ })
+ .await?;
+ let TypeshedActionResult::License { license } = action else {
+ return Err("ViewLicense did not return a license document".into());
+ };
+ assert_eq!(license.title, "Typeshed License");
+ assert!(license.read_only);
+ assert!(
+ !license.content.trim().is_empty(),
+ "bundled license text must be present"
+ );
+ messages.close();
+ pump.abort();
+ Ok(())
}
diff --git a/crates/basilisk-lsp/src/configuration_editor/snapshot_tests.rs b/crates/basilisk-lsp/src/configuration_editor/snapshot_tests.rs
index d78273fc..082b620d 100644
--- a/crates/basilisk-lsp/src/configuration_editor/snapshot_tests.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/snapshot_tests.rs
@@ -7,9 +7,7 @@ use std::sync::Arc;
use basilisk_config::{BasiliskConfig, RuleSeverity as ConfigSeverity};
use basilisk_stubs::typeshed::gittree::Oid;
-use basilisk_stubs::typeshed::source::{
- LicenseStatus, Provenance, SourceKind, Transport, TypeshedStatus,
-};
+use basilisk_stubs::typeshed::source::{LicenseStatus, SourceKind, TypeshedStatus};
use basilisk_stubs::typeshed::warning::WarningSeverity;
use super::{build_snapshot, hypothetical_inventory, inventory, occurrences, page_occurrences};
@@ -170,9 +168,15 @@ fn snapshot_reports_rule_entries_effective_severities_and_tag_entries() {
let _ = std::fs::remove_dir_all(root);
}
-/// The settled, unpinned download the fixture root resolves to.
-fn assert_downloaded_latest(snapshot: &crate::configuration_editor::model::ConfigurationSnapshot) {
- assert_eq!(snapshot.typeshed.source, TypeshedSource::Latest);
+/// The bundled default the fixture root resolves to: an unset pin IS the
+/// bundled commit ([STUBRES-TYPESHED]), still explicitly `UNPINNED`.
+fn assert_bundled_default(snapshot: &crate::configuration_editor::model::ConfigurationSnapshot) {
+ assert_eq!(
+ snapshot.typeshed.source,
+ TypeshedSource::ExactCommit {
+ commit: "83c2518a9e6abbda0c44592c3483de459198f887".to_owned(),
+ }
+ );
assert_eq!(snapshot.typeshed.status.lifecycle, TypeshedLifecycle::Ready);
assert_eq!(
snapshot.typeshed.status.commit_identity.as_deref(),
@@ -187,29 +191,16 @@ fn assert_downloaded_latest(snapshot: &crate::configuration_editor::model::Confi
.map(|warning| warning.code.as_str()),
Some("UNPINNED")
);
- // A downloaded source states its complete download policy — explicit
- // entries and defaults resolved, no per-control widget descriptions.
- let downloads = snapshot.typeshed.downloads.clone();
- assert_eq!(
- downloads.as_ref().map(|policy| policy.reuse_downloads),
- Some(false)
- );
- assert_eq!(
- downloads.as_ref().map(|policy| policy.verify_content),
- Some(false)
- );
- // Pinning is offered because a gate-accepted commit is active, and the
- // offer carries the exact SHA it would write.
- assert_eq!(
- snapshot.typeshed.pinnable_commit.as_deref(),
- Some("83c2518a9e6abbda0c44592c3483de459198f887")
- );
assert!(snapshot.typeshed.license_available);
+ assert!(
+ snapshot.typeshed.store_folder.is_some(),
+ "a pinned source states the store folder it resolves from"
+ );
}
-/// [LSPCFGED-TYPESHED]: the snapshot's Typeshed source, download policy, and
-/// status come entirely from the server's parsed config plus one shared
-/// terminal runtime status.
+/// [LSPCFGED-TYPESHED]: the snapshot's Typeshed source and status come
+/// entirely from the server's parsed config plus one shared terminal runtime
+/// status — there are exactly two sources and no download-policy knobs.
#[test]
fn snapshot_describes_typeshed_controls_and_terminal_status() {
let Some((root, index)) = indexed_root("typeshed") else {
@@ -218,8 +209,6 @@ fn snapshot_describes_typeshed_controls_and_terminal_status() {
let Ok(mut document) = basilisk_config::discover_config_document(&root) else {
unreachable!("fixture configuration must parse");
};
- document.config.typeshed_cache = Some(false);
- document.config.typeshed_verify = Some(false);
let Ok(commit) = Oid::from_hex("83c2518a9e6abbda0c44592c3483de459198f887") else {
unreachable!("fixture SHA must parse");
};
@@ -227,11 +216,8 @@ fn snapshot_describes_typeshed_controls_and_terminal_status() {
active_source: SourceKind::Bundled,
commit: Some(commit),
tree: None,
- transport: Transport::EmbeddedZip,
license_status: LicenseStatus::Approved,
license_reference: Some("typeshed://license/83c2518".to_owned()),
- provenance: Provenance::BundleVetted,
- signed_release: false,
warnings: vec![basilisk_stubs::typeshed::source::StatusWarning {
code: "UNPINNED".to_owned(),
message: "UNPINNED — choose the pinned-commit source to make this reproducible"
@@ -245,9 +231,9 @@ fn snapshot_describes_typeshed_controls_and_terminal_status() {
runtime_snapshot.status = status;
let generation = TypeshedGeneration::Ready(Arc::new(runtime_snapshot));
let snapshot = build_snapshot(&index, &root, &document, Some(&generation));
- assert_downloaded_latest(&snapshot);
- // A pinned commit is carried BY the active source, and an already-pinned
- // source offers no second pin.
+ assert_bundled_default(&snapshot);
+ // A pinned commit is carried BY the active source; the matching active
+ // generation keeps its license reachable.
document.config.typeshed_commit = Some("83c2518a9e6abbda0c44592c3483de459198f887".to_owned());
let pinned = build_snapshot(&index, &root, &document, Some(&generation));
assert_eq!(
@@ -256,14 +242,11 @@ fn snapshot_describes_typeshed_controls_and_terminal_status() {
commit: "83c2518a9e6abbda0c44592c3483de459198f887".to_owned(),
}
);
- assert_eq!(pinned.typeshed.pinnable_commit, None);
- assert!(
- pinned.typeshed.downloads.is_some(),
- "a pinned commit is still downloaded, so it keeps its download policy"
- );
+ assert!(pinned.typeshed.license_available);
document.config.typeshed_commit = None;
- // A user-managed folder downloads nothing and has no upstream commit.
+ // A user-managed folder resolves nothing from the store and states its
+ // own terms.
document.config.typeshed_path = Some(root.join("custom-typeshed"));
let custom = build_snapshot(&index, &root, &document, Some(&generation));
assert_eq!(
@@ -272,63 +255,57 @@ fn snapshot_describes_typeshed_controls_and_terminal_status() {
path: root.join("custom-typeshed").to_string_lossy().into_owned(),
}
);
- assert_eq!(custom.typeshed.downloads, None);
- assert_eq!(custom.typeshed.pinnable_commit, None);
+ assert_eq!(custom.typeshed.store_folder, None);
assert!(
custom.typeshed.license_available,
"a custom tree still reports its user-managed terms"
);
document.config.typeshed_path = None;
- let blocked = TypeshedGeneration::Blocked {
- failure: TypeshedFailure::acquisition("exact commit unavailable"),
+ let no_source = TypeshedGeneration::NoSource {
+ failure: TypeshedFailure::resolution("NO SOURCE — the pin is not on this machine"),
};
- let snapshot = build_snapshot(&index, &root, &document, Some(&blocked));
+ let snapshot = build_snapshot(&index, &root, &document, Some(&no_source));
assert_eq!(
snapshot.typeshed.status.lifecycle,
- TypeshedLifecycle::Blocked
+ TypeshedLifecycle::NoSource
);
assert_eq!(
snapshot.typeshed.status.license_status,
TypeshedLicenseStatus::Unavailable
);
assert_eq!(
- snapshot.typeshed.status.blocked_reason.as_deref(),
- Some("exact commit unavailable")
+ snapshot.typeshed.status.no_source_reason.as_deref(),
+ Some("NO SOURCE — the pin is not on this machine")
);
let _ = std::fs::remove_dir_all(root);
}
-/// [LSPCFGED-TYPESHED]: acquisition is an atomic source transition. While a
-/// candidate is being acquired, no source-policy control may start a second
-/// mutation against the in-flight generation.
+/// [LSPCFGED-TYPESHED]: a root whose resolution has not run projects the
+/// terminal `NoSource` state — the wire model holds no acquiring/blocked
+/// lifecycle a client could render as a panel overlay.
#[test]
-fn acquiring_typeshed_offers_no_source_transition() {
- let Some((root, index)) = indexed_root("typeshed-acquiring") else {
+fn missing_generation_projects_terminal_no_source() {
+ let Some((root, index)) = indexed_root("typeshed-unresolved") else {
unreachable!("indexed fixture must produce diagnostics");
};
let Ok(document) = basilisk_config::discover_config_document(&root) else {
unreachable!("fixture configuration must parse");
};
- let snapshot = build_snapshot(
- &index,
- &root,
- &document,
- Some(&TypeshedGeneration::Acquiring),
- );
+ let snapshot = build_snapshot(&index, &root, &document, None);
assert_eq!(
snapshot.typeshed.status.lifecycle,
- TypeshedLifecycle::Acquiring
+ TypeshedLifecycle::NoSource
);
assert_eq!(
- snapshot.typeshed.pinnable_commit, None,
- "an in-flight generation has no settled commit to pin"
+ snapshot.typeshed.status.no_source_reason.as_deref(),
+ Some("typeshed resolution has not run for this root")
);
assert!(
!snapshot.typeshed.license_available,
- "no license document exists until the candidate settles"
+ "no license document exists without an active generation"
);
let _ = std::fs::remove_dir_all(root);
diff --git a/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed.rs b/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed.rs
index b36c9725..24e8beb8 100644
--- a/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed.rs
@@ -1,28 +1,26 @@
//! Server-described Typeshed controls and typed lifecycle projection.
use basilisk_config::BasiliskConfig;
-use basilisk_stubs::typeshed::source::{
- LicenseStatus, Provenance, SourceKind, Transport, TypeshedStatus,
-};
+use basilisk_stubs::typeshed::bundle::bundled_commit_sha;
+use basilisk_stubs::typeshed::source::{LicenseStatus, SourceKind, TypeshedStatus};
use basilisk_stubs::typeshed::warning::WarningSeverity;
use super::model::{
- TypeshedActiveSource, TypeshedConfigurationState, TypeshedDownloadPolicy,
- TypeshedLicenseStatus, TypeshedLifecycle, TypeshedProvenance, TypeshedSource,
- TypeshedStatusState, TypeshedTransport, TypeshedWarningSeverity, TypeshedWarningState,
+ TypeshedActiveSource, TypeshedConfigurationState, TypeshedLicenseStatus, TypeshedLifecycle,
+ TypeshedSource, TypeshedStatusState, TypeshedWarningSeverity, TypeshedWarningState,
};
use crate::server::typeshed_status::TypeshedGeneration;
-/// Project the one active source, carrying the value that defines it.
+/// Project the one active source, carrying the value that defines it. An
+/// unset pin IS the bundled commit ([STUBRES-TYPESHED]): the picker shows the
+/// effective SHA and the `UNPINNED` warning says it is not yet reproducible.
fn source(config: &BasiliskConfig) -> TypeshedSource {
config.typeshed_path.as_ref().map_or_else(
- || {
- config
+ || TypeshedSource::ExactCommit {
+ commit: config
.typeshed_commit
.clone()
- .map_or(TypeshedSource::Latest, |commit| {
- TypeshedSource::ExactCommit { commit }
- })
+ .unwrap_or_else(|| bundled_commit_sha().to_owned()),
},
|path| TypeshedSource::CustomFolder {
path: path.to_string_lossy().into_owned(),
@@ -30,63 +28,28 @@ fn source(config: &BasiliskConfig) -> TypeshedSource {
)
}
-/// The download policy of a downloaded source. A user-managed folder
-/// downloads nothing, so it has none ([LSPCFGED-TYPESHED]).
-fn downloads(config: &BasiliskConfig, source: &TypeshedSource) -> Option {
+/// The store directory pins resolve from. A custom folder resolves nothing
+/// from the store, so it has none ([STUBRES-TYPESHED-STORE]).
+fn store_folder(config: &BasiliskConfig, source: &TypeshedSource) -> Option {
if matches!(source, TypeshedSource::CustomFolder { .. }) {
return None;
}
- Some(TypeshedDownloadPolicy {
- reuse_downloads: config.typeshed_cache.unwrap_or(true),
- verify_content: config.typeshed_verify.unwrap_or(true),
- archive_url: config.typeshed_url.clone(),
- cache_folder: config
- .typeshed_cache_path
- .as_ref()
- .map(|path| path.to_string_lossy().into_owned()),
- })
+ config
+ .typeshed_store_path
+ .clone()
+ .or_else(basilisk_stubs::typeshed::runtime::default_store_path)
+ .map(|path| path.to_string_lossy().into_owned())
}
-/// The commit `PinCurrent` would write, present only when pinning is possible:
-/// the source must be an unpinned download and a gate-accepted commit must be
-/// active. A source the user can select but never reach does not exist.
-fn pinnable_commit(
- source: &TypeshedSource,
- acquiring: bool,
- status: Option<&TypeshedStatus>,
-) -> Option {
- if acquiring || !matches!(source, TypeshedSource::Latest) {
- return None;
+fn license_available(source: &TypeshedSource, generation: Option<&TypeshedGeneration>) -> bool {
+ match source {
+ // A custom folder always answers `ViewLicense` — with "not supplied".
+ TypeshedSource::CustomFolder { .. } => true,
+ TypeshedSource::ExactCommit { commit } => generation
+ .and_then(TypeshedGeneration::ready_status)
+ .and_then(|status| status.commit)
+ .is_some_and(|active| active.to_hex() == *commit),
}
- status
- .and_then(|current| current.commit)
- .map(|commit| commit.to_hex())
-}
-
-fn license_available(
- config: &BasiliskConfig,
- source: &TypeshedSource,
- lifecycle: TypeshedLifecycle,
- status: Option<&TypeshedStatus>,
-) -> bool {
- if matches!(source, TypeshedSource::CustomFolder { .. }) {
- return lifecycle != TypeshedLifecycle::Acquiring;
- }
- lifecycle == TypeshedLifecycle::Ready
- && status.is_some_and(|current| match source {
- TypeshedSource::ExactCommit { .. } => {
- config.typeshed_commit.as_deref().is_some_and(|commit| {
- current
- .commit
- .is_some_and(|active| active.to_hex() == commit)
- })
- }
- TypeshedSource::Latest => matches!(
- current.active_source,
- SourceKind::Latest | SourceKind::Bundled
- ),
- TypeshedSource::CustomFolder { .. } => false,
- })
}
pub(super) fn typeshed_configuration(
@@ -94,66 +57,43 @@ pub(super) fn typeshed_configuration(
generation: Option<&TypeshedGeneration>,
) -> TypeshedConfigurationState {
let source = source(config);
- let ready_status = generation.and_then(TypeshedGeneration::ready_status);
- let status =
- generation.map_or_else(|| status_projection(None), TypeshedGeneration::status_state);
- let acquiring = status.lifecycle == TypeshedLifecycle::Acquiring;
+ let status = generation.map_or_else(
+ || TypeshedStatusState {
+ lifecycle: TypeshedLifecycle::NoSource,
+ no_source_reason: Some("typeshed resolution has not run for this root".to_owned()),
+ active_source: None,
+ commit_identity: None,
+ license_status: TypeshedLicenseStatus::Unavailable,
+ warnings: Vec::new(),
+ },
+ TypeshedGeneration::status_state,
+ );
TypeshedConfigurationState {
- downloads: downloads(config, &source),
- pinnable_commit: pinnable_commit(&source, acquiring, ready_status),
- license_available: license_available(config, &source, status.lifecycle, ready_status),
+ store_folder: store_folder(config, &source),
+ license_available: license_available(&source, generation),
source,
status,
}
}
-pub(crate) fn status_projection(status: Option<&TypeshedStatus>) -> TypeshedStatusState {
- let Some(status) = status else {
- return TypeshedStatusState {
- lifecycle: TypeshedLifecycle::Acquiring,
- blocked_reason: None,
- active_source: None,
- commit_identity: None,
- transport: None,
- license_status: TypeshedLicenseStatus::Acquiring,
- provenance: TypeshedProvenance::Pending,
- signed_release: false,
- warnings: Vec::new(),
- };
- };
+/// Project an active snapshot's status. A snapshot only exists after every
+/// activation gate passed, so its lifecycle is always `Ready` — a blocked or
+/// missing source is a [`TypeshedGeneration::NoSource`], never a snapshot.
+pub(crate) fn ready_projection(status: &TypeshedStatus) -> TypeshedStatusState {
TypeshedStatusState {
- lifecycle: if status.license_status == LicenseStatus::Changed {
- TypeshedLifecycle::Blocked
- } else {
- TypeshedLifecycle::Ready
- },
- blocked_reason: (status.license_status == LicenseStatus::Changed)
- .then(|| "Typeshed license identity changed; activation requires review".to_owned()),
+ lifecycle: TypeshedLifecycle::Ready,
+ no_source_reason: None,
active_source: Some(match status.active_source {
SourceKind::Custom => TypeshedActiveSource::Custom,
SourceKind::ExactCommit => TypeshedActiveSource::ExactCommit,
- SourceKind::Latest => TypeshedActiveSource::Latest,
SourceKind::Bundled => TypeshedActiveSource::Bundled,
}),
commit_identity: status.commit.map(|oid| oid.to_hex()),
- transport: Some(match status.transport {
- Transport::CustomPath => TypeshedTransport::CustomPath,
- Transport::EmbeddedZip => TypeshedTransport::EmbeddedZip,
- Transport::Codeload => TypeshedTransport::Codeload,
- Transport::Mirror => TypeshedTransport::Mirror,
- }),
license_status: match status.license_status {
LicenseStatus::Approved => TypeshedLicenseStatus::Approved,
LicenseStatus::Changed => TypeshedLicenseStatus::Changed,
LicenseStatus::NotSupplied => TypeshedLicenseStatus::NotSupplied,
},
- provenance: match status.provenance {
- Provenance::GithubTlsAttested => TypeshedProvenance::GithubTlsAttested,
- Provenance::Unverified => TypeshedProvenance::Unverified,
- Provenance::BundleVetted => TypeshedProvenance::BundleVetted,
- Provenance::UserManaged => TypeshedProvenance::UserManaged,
- },
- signed_release: status.signed_release,
warnings: status
.warnings
.iter()
diff --git a/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed_tests.rs b/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed_tests.rs
index 6b37bd10..15674b3c 100644
--- a/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed_tests.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/snapshot_typeshed_tests.rs
@@ -1,79 +1,117 @@
//! Tests for the server-described Typeshed source projection.
use std::path::PathBuf;
+use std::sync::Arc;
+
+use basilisk_stubs::typeshed::bundle::{bundled_commit_sha, bundled_snapshot};
use super::*;
-/// [LSPCFGED-TYPESHED]: a blocked official source has no immutable license
-/// document to show, while a user-managed tree always states its own terms.
+/// [STUBRES-TYPESHED]: an unset pin IS the bundled commit — the picker shows
+/// the effective SHA, never a third "latest" source.
#[test]
-fn blocked_official_source_cannot_offer_a_stale_license() {
- let exact = BasiliskConfig {
+fn unset_pin_reports_the_bundled_commit_as_the_effective_source() {
+ let unset = BasiliskConfig::default();
+ assert_eq!(
+ source(&unset),
+ TypeshedSource::ExactCommit {
+ commit: bundled_commit_sha().to_owned(),
+ }
+ );
+
+ let pinned = BasiliskConfig {
typeshed_commit: Some("a".repeat(40)),
..BasiliskConfig::default()
};
- let exact_source = source(&exact);
assert_eq!(
- exact_source,
+ source(&pinned),
TypeshedSource::ExactCommit {
commit: "a".repeat(40),
}
);
- assert!(!license_available(
- &exact,
- &exact_source,
- TypeshedLifecycle::Blocked,
- None,
- ));
let custom = BasiliskConfig {
typeshed_path: Some(PathBuf::from("/user/typeshed")),
..BasiliskConfig::default()
};
- let custom_source = source(&custom);
- assert!(matches!(custom_source, TypeshedSource::CustomFolder { .. }));
- assert!(license_available(
- &custom,
- &custom_source,
- TypeshedLifecycle::Blocked,
- None,
+ assert!(matches!(
+ source(&custom),
+ TypeshedSource::CustomFolder { .. }
));
- assert_eq!(
- downloads(&custom, &custom_source),
- None,
- "a user-managed folder downloads nothing"
- );
}
-/// A source that cannot be reached is never offered: pinning requires an
-/// unpinned download with a settled commit behind it.
+/// [STUBRES-TYPESHED-STORE]: pins resolve from a store folder (configured or
+/// canonical); a custom folder resolves nothing from the store.
#[test]
-fn pinning_is_offered_only_for_an_unpinned_settled_download() {
- let latest = BasiliskConfig::default();
- let latest_source = source(&latest);
- assert_eq!(latest_source, TypeshedSource::Latest);
- assert_eq!(pinnable_commit(&latest_source, false, None), None);
+fn store_folder_exists_only_for_pinned_sources() {
+ let configured = BasiliskConfig {
+ typeshed_store_path: Some(PathBuf::from("/stores/typeshed")),
+ ..BasiliskConfig::default()
+ };
assert_eq!(
- pinnable_commit(&latest_source, true, None),
- None,
- "an in-flight acquisition offers no pin"
+ store_folder(&configured, &source(&configured)).as_deref(),
+ Some("/stores/typeshed")
);
- let pinned = BasiliskConfig {
- typeshed_commit: Some("b".repeat(40)),
+ let custom = BasiliskConfig {
+ typeshed_path: Some(PathBuf::from("/user/typeshed")),
+ typeshed_store_path: Some(PathBuf::from("/stores/typeshed")),
..BasiliskConfig::default()
};
- assert_eq!(pinnable_commit(&source(&pinned), false, None), None);
+ assert_eq!(store_folder(&custom, &source(&custom)), None);
+}
+
+/// [LSPCFGED-TYPESHED]: a pin without a matching active generation has no
+/// immutable license document to show, while a user-managed tree always
+/// answers `ViewLicense` with its own terms.
+#[test]
+fn license_availability_tracks_the_matching_active_generation() {
+ let custom_source = TypeshedSource::CustomFolder {
+ path: "/user/typeshed".to_owned(),
+ };
+ assert!(license_available(&custom_source, None));
+
+ let bundled_pin = TypeshedSource::ExactCommit {
+ commit: bundled_commit_sha().to_owned(),
+ };
+ assert!(!license_available(&bundled_pin, None));
+
+ let Ok(snapshot) = bundled_snapshot() else {
+ unreachable!("release bundle must activate");
+ };
+ let ready = TypeshedGeneration::Ready(Arc::new(snapshot));
+ assert!(license_available(&bundled_pin, Some(&ready)));
+
+ let other_pin = TypeshedSource::ExactCommit {
+ commit: "a".repeat(40),
+ };
+ assert!(
+ !license_available(&other_pin, Some(&ready)),
+ "a pin must not surface a different commit's license"
+ );
+}
+
+/// [LSPCFGED-TYPESHED]: every projection is terminal. A snapshot is always
+/// `Ready`; an unresolved root is `NoSource` with its reason — there is no
+/// intermediate state for a client to render as a blocking overlay.
+#[test]
+fn projections_are_always_terminal() {
+ let Ok(snapshot) = bundled_snapshot() else {
+ unreachable!("release bundle must activate");
+ };
+ let ready = ready_projection(&snapshot.status);
+ assert_eq!(ready.lifecycle, TypeshedLifecycle::Ready);
+ assert!(ready.no_source_reason.is_none());
+ assert_eq!(ready.active_source, Some(TypeshedActiveSource::Bundled));
- // Defaults resolve on the wire so the client never re-derives them.
- let policy = downloads(&latest, &latest_source);
+ let unresolved = typeshed_configuration(&BasiliskConfig::default(), None);
+ assert_eq!(unresolved.status.lifecycle, TypeshedLifecycle::NoSource);
assert_eq!(
- policy.as_ref().map(|policy| policy.reuse_downloads),
- Some(true)
+ unresolved.status.no_source_reason.as_deref(),
+ Some("typeshed resolution has not run for this root")
);
assert_eq!(
- policy.as_ref().map(|policy| policy.verify_content),
- Some(true)
+ unresolved.status.license_status,
+ TypeshedLicenseStatus::Unavailable
);
- assert_eq!(policy.and_then(|policy| policy.archive_url), None);
}
diff --git a/crates/basilisk-lsp/src/configuration_editor/transaction.rs b/crates/basilisk-lsp/src/configuration_editor/transaction.rs
index a5f6ed88..67c79080 100644
--- a/crates/basilisk-lsp/src/configuration_editor/transaction.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/transaction.rs
@@ -3,7 +3,9 @@
use std::path::Path;
use std::sync::Arc;
-use basilisk_config::{build_rule_patch, ConfigDocument, ConfigPatch, RuleConfigUpdate};
+use basilisk_config::{
+ build_configuration_patch, ConfigDocument, ConfigPatch, ConfigurationUpdate, RuleConfigUpdate,
+};
use tower_lsp::jsonrpc::Result as LspResult;
use tower_lsp::lsp_types::{
CreateFile, CreateFileOptions, DocumentChangeOperation, DocumentChanges, OneOf,
@@ -33,7 +35,7 @@ pub(crate) struct ConfigurationRefreshHandles {
pub(crate) workspace_roots: Arc>>,
/// Explicit interpreter supplied by the editor initialization options.
pub(crate) python_interpreter: Arc>>,
- /// Root-keyed active/acquiring/blocked Typeshed generations.
+ /// Root-keyed terminal (Ready/NoSource) Typeshed generations.
pub(crate) typeshed_generations:
Arc>,
/// Whether every workspace root has completed its first ready scan.
@@ -107,13 +109,27 @@ fn replacement_edit(
})
}
-/// Apply one validated entry update through the same client-edit service
-/// used by the typed preview/apply protocol.
+/// Apply one validated rule-entry update through the shared transaction.
pub(crate) async fn apply_rule_updates(
server: &LspServer,
root: &Path,
update: &RuleConfigUpdate,
reason: &str,
+) -> LspResult {
+ let update = ConfigurationUpdate {
+ rules: update.clone(),
+ typeshed: basilisk_config::TypeshedConfigUpdate::default(),
+ };
+ apply_configuration_update(server, root, &update, reason).await
+}
+
+/// Apply one validated configuration update through the same client-edit
+/// service used by the typed preview/apply protocol.
+pub(crate) async fn apply_configuration_update(
+ server: &LspServer,
+ root: &Path,
+ update: &ConfigurationUpdate,
+ reason: &str,
) -> LspResult {
let effective = server
.configuration_editor
@@ -123,7 +139,7 @@ pub(crate) async fn apply_rule_updates(
let disk_revision = server
.configuration_editor
.disk_revision_for(root, &document.revision);
- let patch = build_rule_patch(&document, update).map_err(config_error)?;
+ let patch = build_configuration_patch(&document, update).map_err(config_error)?;
apply_prepared_patch(
server,
root,
@@ -136,6 +152,10 @@ pub(crate) async fn apply_rule_updates(
.await
}
+/// The transaction order is the whole UI fix ([LSPCFGED-TYPESHED]): compute
+/// the next terminal generation locally, land the edit, then publish — a
+/// rejected edit drops the staged value with nothing ever published, so
+/// clients never observe an intermediate state.
pub(super) async fn apply_prepared_patch(
server: &LspServer,
root: &Path,
@@ -146,30 +166,20 @@ pub(super) async fn apply_prepared_patch(
reason: &str,
) -> LspResult {
let edit = replacement_edit(document, patch, document_version)?;
- let staged = super::typeshed_acquisition::stage_configuration_change(
- server,
+ let staged = super::typeshed_resolution::stage_configuration_change(
root,
&document.config,
&patch.config,
)
- .await?;
- let response = match server.client.apply_edit(edit).await {
- Ok(response) => response,
- Err(error) => {
- if let Some(staged) = staged {
- staged.rollback(server, root).await;
- }
- return Err(rpc_error_data(
- "clientRejectedEdit",
- "client failed to apply configuration edit",
- serde_json::json!({ "error": error.to_string() }),
- ));
- }
- };
+ .await;
+ let response = server.client.apply_edit(edit).await.map_err(|error| {
+ rpc_error_data(
+ "clientRejectedEdit",
+ "client failed to apply configuration edit",
+ serde_json::json!({ "error": error.to_string() }),
+ )
+ })?;
if !response.applied {
- if let Some(staged) = staged {
- staged.rollback(server, root).await;
- }
return Err(rpc_error_data(
"clientRejectedEdit",
"client rejected configuration edit",
@@ -191,33 +201,15 @@ pub(super) async fn apply_prepared_patch(
);
}
let handles = server.refresh_handles();
- let refresh = refresh_with_document_and_typeshed(
- &handles,
- root,
- reason,
- &applied,
- staged
- .as_ref()
- .map(super::typeshed_acquisition::StagedGeneration::candidate),
- )
- .await;
- if let Err(error) = refresh {
- if let Some(staged) = staged {
- let cleanup =
- refresh_with_document(&handles, root, "typeshedConfigurationBlocked", &applied)
- .await;
- staged
- .block(server, root, "configuration refresh failed")
- .await;
- if let Err(cleanup_error) = cleanup {
- tracing::warn!(root = %root.display(), error = %cleanup_error, "failed to clear analysis after Typeshed configuration failure");
- }
- }
- return Err(error);
- }
+ let candidate = staged
+ .as_ref()
+ .and_then(super::typeshed_resolution::StagedResolution::candidate)
+ .cloned();
if let Some(staged) = staged {
- staged.activate(server, root).await;
+ staged.publish(&handles, root).await;
}
+ refresh_with_document_and_typeshed(&handles, root, reason, &applied, candidate.as_ref())
+ .await?;
Ok(applied)
}
@@ -263,10 +255,7 @@ pub(super) async fn refresh_with_document_and_typeshed(
let generation_unavailable = candidate.is_none()
&& matches!(
handles.typeshed_generations.read().await.get(root),
- Some(
- crate::server::typeshed_status::TypeshedGeneration::Acquiring
- | crate::server::typeshed_status::TypeshedGeneration::Blocked { .. }
- )
+ Some(crate::server::typeshed_status::TypeshedGeneration::NoSource { .. })
);
if generation_unavailable {
return commit_without_analysis(handles, root, reason, document).await;
diff --git a/crates/basilisk-lsp/src/configuration_editor/typeshed_acquisition.rs b/crates/basilisk-lsp/src/configuration_editor/typeshed_acquisition.rs
deleted file mode 100644
index 57bcca71..00000000
--- a/crates/basilisk-lsp/src/configuration_editor/typeshed_acquisition.rs
+++ /dev/null
@@ -1,406 +0,0 @@
-//! Root-keyed production acquisition with candidate staging and rollback.
-
-use std::path::Path;
-use std::sync::Arc;
-
-use basilisk_config::BasiliskConfig;
-use basilisk_stubs::typeshed::snapshot::Snapshot;
-use tower_lsp::jsonrpc::Result as LspResult;
-
-use super::protocol::rpc_error;
-use super::transaction::ConfigurationRefreshHandles;
-use crate::server::typeshed_status::{self, TypeshedFailure, TypeshedGeneration};
-use crate::server::LspServer;
-
-/// A fully gated candidate held outside the active root map until the client
-/// accepts the matching configuration edit.
-pub(super) struct StagedGeneration {
- previous: Option,
- candidate: Arc,
-}
-
-pub(super) enum WatchedStageError {
- Busy(&'static str),
- Failed(TypeshedFailure),
-}
-
-impl WatchedStageError {
- pub(super) fn rpc_error(&self) -> tower_lsp::jsonrpc::Error {
- match self {
- Self::Busy(message) => rpc_error("typeshedAcquisitionBusy", message),
- Self::Failed(failure) => rpc_error(failure.rpc_code(), failure.reason()),
- }
- }
-
- pub(super) fn into_failure(self) -> Option {
- match self {
- Self::Busy(_) => None,
- Self::Failed(failure) => Some(failure),
- }
- }
-}
-
-impl StagedGeneration {
- pub(super) fn candidate(&self) -> &Arc {
- &self.candidate
- }
-
- pub(super) async fn activate(self, server: &LspServer, root: &Path) {
- let status = self.candidate.status.clone();
- publish_generation(
- &server.typeshed_generations,
- &server.client,
- root,
- TypeshedGeneration::Ready(self.candidate),
- )
- .await;
- typeshed_status::show_high_warnings(&server.client, &status).await;
- }
-
- pub(super) async fn activate_with(self, handles: &ConfigurationRefreshHandles, root: &Path) {
- let status = self.candidate.status.clone();
- publish_generation(
- &handles.typeshed_generations,
- &handles.client,
- root,
- TypeshedGeneration::Ready(self.candidate),
- )
- .await;
- typeshed_status::show_high_warnings(&handles.client, &status).await;
- }
-
- pub(super) async fn block(self, server: &LspServer, root: &Path, reason: &str) {
- publish_generation(
- &server.typeshed_generations,
- &server.client,
- root,
- TypeshedGeneration::Blocked {
- failure: TypeshedFailure::acquisition(reason),
- },
- )
- .await;
- }
-
- pub(super) async fn block_with(
- self,
- handles: &ConfigurationRefreshHandles,
- root: &Path,
- reason: &str,
- ) {
- publish_generation(
- &handles.typeshed_generations,
- &handles.client,
- root,
- TypeshedGeneration::Blocked {
- failure: TypeshedFailure::acquisition(reason),
- },
- )
- .await;
- }
-
- pub(super) async fn rollback(self, server: &LspServer, root: &Path) {
- let generation = self
- .previous
- .unwrap_or_else(|| TypeshedGeneration::Blocked {
- failure: TypeshedFailure::acquisition("configuration edit was not applied"),
- });
- publish_generation(
- &server.typeshed_generations,
- &server.client,
- root,
- generation,
- )
- .await;
- }
-}
-
-/// Stage a candidate only when one of the six source-policy settings changed.
-pub(super) async fn stage_configuration_change(
- server: &LspServer,
- root: &Path,
- before: &BasiliskConfig,
- after: &BasiliskConfig,
-) -> LspResult> {
- if !typeshed_policy_changed(before, after) {
- return Ok(None);
- }
- let previous = begin_acquiring(server, root).await?;
- if let Some(candidate) = pinned_active_candidate(previous.as_ref(), before, after) {
- return Ok(Some(StagedGeneration {
- previous,
- candidate,
- }));
- }
- match acquire(root, after, after.typeshed_cache.unwrap_or(true)).await {
- Ok(candidate) => Ok(Some(StagedGeneration {
- previous,
- candidate,
- })),
- Err(error) => {
- restore_after_failure(server, root, previous, error.reason()).await;
- Err(rpc_error(error.rpc_code(), error.reason()))
- }
- }
-}
-
-/// Reclassify the already-active immutable generation when `Pin current` is
-/// the only policy change. The bytes and commit are already gate-accepted, so
-/// downloading the identical archive again would add failure modes without
-/// changing the selected source.
-fn pinned_active_candidate(
- previous: Option<&TypeshedGeneration>,
- before: &BasiliskConfig,
- after: &BasiliskConfig,
-) -> Option> {
- let requested = after.typeshed_commit.as_deref()?;
- if before.typeshed_commit.is_some()
- || before.typeshed_path.is_some()
- || after.typeshed_path.is_some()
- || before.typeshed_url != after.typeshed_url
- || before.typeshed_cache_path != after.typeshed_cache_path
- || before.typeshed_cache != after.typeshed_cache
- || before.typeshed_verify != after.typeshed_verify
- {
- return None;
- }
- let active = previous.and_then(TypeshedGeneration::ready_snapshot)?;
- if active
- .status
- .commit
- .map(|commit| commit.to_hex())
- .as_deref()
- != Some(requested)
- {
- return None;
- }
-
- let mut candidate = (**active).clone();
- match &candidate.identity {
- basilisk_stubs::typeshed::source::SourceIdentity::Commit { commit, .. } => {
- candidate.identity = basilisk_stubs::typeshed::source::SourceIdentity::Commit {
- commit: *commit,
- pinned: true,
- };
- candidate.status.active_source =
- basilisk_stubs::typeshed::source::SourceKind::ExactCommit;
- candidate
- .status
- .warnings
- .retain(|warning| warning.code != "UNPINNED");
- }
- basilisk_stubs::typeshed::source::SourceIdentity::Bundled { .. } => {
- candidate.status.active_source = basilisk_stubs::typeshed::source::SourceKind::Bundled;
- candidate.status.warnings.clear();
- }
- basilisk_stubs::typeshed::source::SourceIdentity::Custom { .. } => return None,
- }
- Some(Arc::new(candidate))
-}
-
-/// Cache-bypassing one-run refresh used by the closed `AcquireFresh` action.
-pub(super) async fn acquire_fresh(
- server: &LspServer,
- root: &Path,
- config: &BasiliskConfig,
-) -> Result {
- let previous = begin_acquiring_with(&server.typeshed_generations, &server.client, root)
- .await
- .map_err(WatchedStageError::Busy)?;
- match acquire(root, config, false).await {
- Ok(candidate) => Ok(StagedGeneration {
- previous,
- candidate,
- }),
- Err(error) => Err(WatchedStageError::Failed(error)),
- }
-}
-
-/// Stage an already-observed on-disk configuration change. Unlike an editor
-/// transaction, failure cannot restore the previous generation because the
-/// source document has already changed, so the root becomes explicitly
-/// blocked and its old snapshot is never rebound to the new policy.
-pub(super) async fn stage_watched_configuration_change(
- handles: &ConfigurationRefreshHandles,
- root: &Path,
- before: &BasiliskConfig,
- after: &BasiliskConfig,
-) -> Result, WatchedStageError> {
- if !typeshed_policy_changed(before, after) {
- return Ok(None);
- }
- let _previous = begin_acquiring_with(&handles.typeshed_generations, &handles.client, root)
- .await
- .map_err(WatchedStageError::Busy)?;
- acquire(root, after, after.typeshed_cache.unwrap_or(true))
- .await
- .map(|candidate| {
- Some(StagedGeneration {
- previous: None,
- candidate,
- })
- })
- .map_err(WatchedStageError::Failed)
-}
-
-pub(super) async fn publish_failure(
- handles: &ConfigurationRefreshHandles,
- root: &Path,
- failure: TypeshedFailure,
-) {
- publish_generation(
- &handles.typeshed_generations,
- &handles.client,
- root,
- TypeshedGeneration::Blocked { failure },
- )
- .await;
-}
-
-async fn begin_acquiring(server: &LspServer, root: &Path) -> LspResult> {
- begin_acquiring_with(&server.typeshed_generations, &server.client, root)
- .await
- .map_err(|message| rpc_error("typeshedAcquisitionBusy", message))
-}
-
-async fn begin_acquiring_with(
- generations: &tokio::sync::RwLock,
- client: &tower_lsp::Client,
- root: &Path,
-) -> Result, &'static str> {
- let acquiring = TypeshedGeneration::Acquiring;
- let previous = {
- let mut generations = generations.write().await;
- replace_with_acquiring(&mut generations, root)?
- };
- typeshed_status::notify_generation(client, root, &acquiring).await;
- Ok(previous)
-}
-
-fn replace_with_acquiring(
- generations: &mut typeshed_status::TypeshedGenerations,
- root: &Path,
-) -> Result, &'static str> {
- if matches!(generations.get(root), Some(TypeshedGeneration::Acquiring)) {
- return Err("Typeshed acquisition is already in progress");
- }
- Ok(generations.insert(root.to_path_buf(), TypeshedGeneration::Acquiring))
-}
-
-async fn restore_after_failure(
- server: &LspServer,
- root: &Path,
- previous: Option,
- error: &str,
-) {
- let generation = previous.unwrap_or_else(|| TypeshedGeneration::Blocked {
- failure: TypeshedFailure::acquisition(error),
- });
- publish_generation(
- &server.typeshed_generations,
- &server.client,
- root,
- generation,
- )
- .await;
-}
-
-async fn publish_generation(
- generations: &tokio::sync::RwLock,
- client: &tower_lsp::Client,
- root: &Path,
- generation: TypeshedGeneration,
-) {
- let _ = generations
- .write()
- .await
- .insert(root.to_path_buf(), generation.clone());
- typeshed_status::notify_generation(client, root, &generation).await;
-}
-
-async fn acquire(
- root: &Path,
- config: &BasiliskConfig,
- use_cache: bool,
-) -> Result, TypeshedFailure> {
- let workspace = super::watch::workspace_config_for_basilisk(root, config);
- let cache_path = workspace.typeshed_cache_path.clone();
- let mut request =
- crate::config::typeshed_request(&workspace).map_err(TypeshedFailure::acquisition)?;
- request.use_cache = use_cache;
- tokio::task::spawn_blocking(move || {
- let manager = basilisk_stubs::typeshed::runtime::production_manager(request, cache_path)
- .map_err(|error| TypeshedFailure::acquisition(error.to_string()))?;
- manager
- .snapshot()
- .map_err(|error| TypeshedFailure::from_selection(&error))
- })
- .await
- .map_err(|_join_error| TypeshedFailure::acquisition("Typeshed acquisition task failed"))?
-}
-
-fn typeshed_policy_changed(before: &BasiliskConfig, after: &BasiliskConfig) -> bool {
- before.typeshed_path != after.typeshed_path
- || before.typeshed_commit != after.typeshed_commit
- || before.typeshed_url != after.typeshed_url
- || before.typeshed_cache_path != after.typeshed_cache_path
- || before.typeshed_cache != after.typeshed_cache
- || before.typeshed_verify != after.typeshed_verify
-}
-
-#[cfg(test)]
-mod tests {
- use std::path::Path;
-
- use super::{replace_with_acquiring, typeshed_policy_changed, WatchedStageError};
- use crate::server::typeshed_status::{TypeshedFailure, TypeshedGenerations};
- use basilisk_config::BasiliskConfig;
- use basilisk_stubs::typeshed::gittree::Oid;
- use basilisk_stubs::typeshed::selector::{BackendError, SelectionError};
-
- #[test]
- fn candidate_staging_is_limited_to_the_six_typeshed_settings() {
- let before = BasiliskConfig::default();
- let mut rule_only = before.clone();
- rule_only.python_version = Some("3.12".to_owned());
- assert!(!typeshed_policy_changed(&before, &rule_only));
-
- let mut source = before.clone();
- source.typeshed_cache = Some(false);
- assert!(typeshed_policy_changed(&before, &source));
- }
-
- #[test]
- fn concurrent_acquisition_cannot_overwrite_the_active_candidate() {
- let root = Path::new("/workspace");
- let mut generations = TypeshedGenerations::new();
- let first = replace_with_acquiring(&mut generations, root);
- assert!(first.is_ok());
- let second = replace_with_acquiring(&mut generations, root);
- assert_eq!(
- second.err(),
- Some("Typeshed acquisition is already in progress")
- );
- }
-
- #[test]
- fn license_drift_retains_its_typed_rpc_category() {
- let Ok(commit) = Oid::from_hex("0123456789012345678901234567890123456789") else {
- return;
- };
- let failure = TypeshedFailure::from_selection(&SelectionError::Exact {
- commit,
- reason: BackendError::LicenseChanged,
- });
- assert_eq!(failure.rpc_code(), "typeshedLicenseChanged");
- }
-
- #[test]
- fn failed_fresh_acquisition_carries_failure_instead_of_a_previous_generation() {
- let error = WatchedStageError::Failed(TypeshedFailure::acquisition("fresh failed"));
- let failure = error.into_failure();
- assert_eq!(
- failure.as_ref().map(TypeshedFailure::reason),
- Some("fresh failed")
- );
- }
-}
diff --git a/crates/basilisk-lsp/src/configuration_editor/typeshed_resolution.rs b/crates/basilisk-lsp/src/configuration_editor/typeshed_resolution.rs
new file mode 100644
index 00000000..b32bd5e2
--- /dev/null
+++ b/crates/basilisk-lsp/src/configuration_editor/typeshed_resolution.rs
@@ -0,0 +1,204 @@
+//! Root-keyed local Typeshed resolution — never a download.
+//!
+//! Implements [STUBRES-TYPESHED-PIN] activation for the LSP: resolving a
+//! source is a local store/bundle read ([STUBRES-TYPESHED-OFFLINE]), so a
+//! configuration change computes the NEXT terminal generation off the message
+//! loop and publishes nothing until the matching edit has actually landed
+//! ([LSPCFGED-TYPESHED]). There is no acquiring state, no busy error, and no
+//! rollback — the previous generation keeps serving analysis until its
+//! terminal replacement is swapped in atomically.
+
+use std::path::Path;
+use std::sync::Arc;
+
+use basilisk_config::{BasiliskConfig, ConfigDocument};
+use basilisk_stubs::typeshed::snapshot::Snapshot;
+use tower_lsp::jsonrpc::Result as LspResult;
+
+use super::transaction::ConfigurationRefreshHandles;
+use crate::server::typeshed_status::{self, TypeshedFailure, TypeshedGeneration};
+use crate::server::LspServer;
+
+/// The next terminal generation, computed locally and held privately until
+/// the matching configuration edit lands. Dropping it publishes nothing —
+/// which is exactly what a rejected edit requires.
+pub(super) struct StagedResolution {
+ next: TypeshedGeneration,
+}
+
+impl StagedResolution {
+ /// The candidate snapshot when the next generation is Ready.
+ pub(super) fn candidate(&self) -> Option<&Arc> {
+ self.next.ready_snapshot()
+ }
+
+ /// Atomically replace the root's generation and notify clients. Elevated
+ /// source warnings surface here, once, on activation.
+ pub(super) async fn publish(self, handles: &ConfigurationRefreshHandles, root: &Path) {
+ let next = self.next;
+ let status = next.ready_status().cloned();
+ let _ = handles
+ .typeshed_generations
+ .write()
+ .await
+ .insert(root.to_path_buf(), next.clone());
+ typeshed_status::notify_generation(&handles.client, root, &next).await;
+ if let Some(status) = status {
+ typeshed_status::show_high_warnings(&handles.client, &status).await;
+ }
+ }
+}
+
+/// Compute the next generation only when one of the three Typeshed source
+/// settings changed. A valid-but-missing pin is VALID configuration: the
+/// result is a `NoSource` generation, never a request error.
+pub(super) async fn stage_configuration_change(
+ root: &Path,
+ before: &BasiliskConfig,
+ after: &BasiliskConfig,
+) -> Option {
+ if !typeshed_policy_changed(before, after) {
+ return None;
+ }
+ Some(StagedResolution {
+ next: resolve(root, after).await,
+ })
+}
+
+/// Resolve one root's checker configuration to its terminal generation.
+pub(crate) async fn resolve(root: &Path, config: &BasiliskConfig) -> TypeshedGeneration {
+ resolve_workspace(super::watch::workspace_config_for_basilisk(root, config)).await
+}
+
+/// Resolve a workspace configuration to its terminal generation — a fast
+/// local store/bundle read on a blocking thread, never the network.
+pub(crate) async fn resolve_workspace(
+ config: crate::config::WorkspaceConfig,
+) -> TypeshedGeneration {
+ let outcome = tokio::task::spawn_blocking(move || {
+ let request =
+ crate::config::typeshed_request(&config).map_err(TypeshedFailure::resolution)?;
+ basilisk_stubs::typeshed::runtime::production_manager(request)
+ .snapshot()
+ .map_err(|error| TypeshedFailure::from_selection(&error))
+ })
+ .await
+ .unwrap_or_else(|_join_error| {
+ Err(TypeshedFailure::resolution(
+ "Typeshed resolution task failed",
+ ))
+ });
+ match outcome {
+ Ok(snapshot) => TypeshedGeneration::Ready(snapshot),
+ Err(failure) => {
+ tracing::warn!(
+ code = failure.rpc_code(),
+ reason = failure.reason(),
+ "Typeshed source is unavailable; the root resolves to NoSource"
+ );
+ TypeshedGeneration::NoSource { failure }
+ }
+ }
+}
+
+/// Re-resolve one root locally and activate the outcome: publish the terminal
+/// generation, then run the shared refresh tail. Used after a user-invoked
+/// download completes ([LSPCFGED-TYPESHED-DOWNLOAD]).
+pub(crate) async fn resolve_and_activate(
+ server: &LspServer,
+ root: &Path,
+ document: &ConfigDocument,
+) -> LspResult<()> {
+ let staged = StagedResolution {
+ next: resolve(root, &document.config).await,
+ };
+ let candidate = staged.candidate().cloned();
+ let handles = server.refresh_handles();
+ staged.publish(&handles, root).await;
+ super::transaction::refresh_with_document_and_typeshed(
+ &handles,
+ root,
+ "typeshedDownloadActivate",
+ document,
+ candidate.as_ref(),
+ )
+ .await
+}
+
+/// Whether a configuration change touches the Typeshed source policy — the
+/// whole surface is three keys ([LSPCFGED-TYPESHED]).
+fn typeshed_policy_changed(before: &BasiliskConfig, after: &BasiliskConfig) -> bool {
+ before.typeshed_path != after.typeshed_path
+ || before.typeshed_commit != after.typeshed_commit
+ || before.typeshed_store_path != after.typeshed_store_path
+}
+
+#[cfg(test)]
+mod tests {
+ use basilisk_config::BasiliskConfig;
+
+ use super::{stage_configuration_change, typeshed_policy_changed};
+
+ #[test]
+ fn staging_is_limited_to_the_three_typeshed_settings() {
+ let before = BasiliskConfig::default();
+ let mut rule_only = before.clone();
+ rule_only.python_version = Some("3.12".to_owned());
+ assert!(!typeshed_policy_changed(&before, &rule_only));
+
+ let mut pin = before.clone();
+ pin.typeshed_commit = Some("83c2518a9e6abbda0c44592c3483de459198f887".to_owned());
+ assert!(typeshed_policy_changed(&before, &pin));
+
+ let mut store = before.clone();
+ store.typeshed_store_path = Some(std::path::PathBuf::from("stores/typeshed"));
+ assert!(typeshed_policy_changed(&before, &store));
+ }
+
+ /// [LSPCFGED-TYPESHED]: a non-typeshed configuration change stages
+ /// NOTHING — no resolution runs, no status is published, so the editor
+ /// cannot flicker through any intermediate state.
+ #[tokio::test]
+ async fn unrelated_configuration_change_stages_nothing() {
+ let before = BasiliskConfig::default();
+ let mut after = before.clone();
+ after.python_version = Some("3.13".to_owned());
+ let staged =
+ stage_configuration_change(std::path::Path::new("/workspace"), &before, &after).await;
+ assert!(staged.is_none());
+ }
+
+ /// A valid-but-missing pin stages a terminal `NoSource` generation
+ /// instead of failing the transaction: the config is valid, the machine
+ /// just does not hold that commit ([STUBRES-TYPESHED-PIN]).
+ #[tokio::test]
+ async fn missing_pin_stages_a_terminal_no_source_generation() {
+ let unique = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .map_or(0, |duration| duration.as_nanos());
+ let store = std::env::temp_dir().join(format!(
+ "basilisk_resolution_empty_store_{}_{unique}",
+ std::process::id()
+ ));
+ let before = BasiliskConfig::default();
+ let mut after = before.clone();
+ after.typeshed_commit = Some("0123456789012345678901234567890123456789".to_owned());
+ after.typeshed_store_path = Some(store.clone());
+ let staged =
+ stage_configuration_change(std::path::Path::new("/workspace"), &before, &after).await;
+ let Some(staged) = staged else {
+ unreachable!("a pin change must stage a resolution");
+ };
+ assert!(staged.candidate().is_none());
+ let state = staged.next.status_state();
+ assert_eq!(
+ state.lifecycle,
+ crate::configuration_editor::model::TypeshedLifecycle::NoSource
+ );
+ assert!(state
+ .no_source_reason
+ .is_some_and(|reason| reason.contains("NO SOURCE")
+ && reason.contains("0123456789012345678901234567890123456789")));
+ let _ = std::fs::remove_dir_all(store);
+ }
+}
diff --git a/crates/basilisk-lsp/src/configuration_editor/watch.rs b/crates/basilisk-lsp/src/configuration_editor/watch.rs
index caebc13e..9796aaa3 100644
--- a/crates/basilisk-lsp/src/configuration_editor/watch.rs
+++ b/crates/basilisk-lsp/src/configuration_editor/watch.rs
@@ -109,61 +109,27 @@ pub(crate) async fn refresh_root_from_disk(
let document = handles.configuration_editor.effective_document(root);
let result = match document {
Ok(document) => {
- match super::typeshed_acquisition::stage_watched_configuration_change(
- handles,
+ let staged = super::typeshed_resolution::stage_configuration_change(
root,
&before,
&document.config,
)
- .await
- {
- Ok(Some(staged)) => {
- let refreshed = super::transaction::refresh_with_document_and_typeshed(
- handles,
- root,
- reason,
- &document,
- Some(staged.candidate()),
- )
- .await;
- match refreshed {
- Ok(()) => {
- staged.activate_with(handles, root).await;
- Ok(())
- }
- Err(error) => {
- let cleanup = super::transaction::refresh_with_document(
- handles,
- root,
- "typeshedWatchedConfigurationBlocked",
- &document,
- )
- .await;
- staged
- .block_with(handles, root, "configuration refresh failed")
- .await;
- if let Err(cleanup_error) = cleanup {
- tracing::warn!(root = %root.display(), error = %cleanup_error, "failed to clear analysis after watched Typeshed activation failure");
- }
- Err(error)
- }
- }
- }
- Ok(None) => {
- super::transaction::refresh_with_document(handles, root, reason, &document)
- .await
- }
- Err(error) => {
- let rpc_error = error.rpc_error();
- let refresh =
- super::transaction::refresh_with_document(handles, root, reason, &document)
- .await;
- if let Some(failure) = error.into_failure() {
- super::typeshed_acquisition::publish_failure(handles, root, failure).await;
- }
- refresh.and(Err(rpc_error))
- }
+ .await;
+ let candidate = staged
+ .as_ref()
+ .and_then(super::typeshed_resolution::StagedResolution::candidate)
+ .cloned();
+ if let Some(staged) = staged {
+ staged.publish(handles, root).await;
}
+ super::transaction::refresh_with_document_and_typeshed(
+ handles,
+ root,
+ reason,
+ &document,
+ candidate.as_ref(),
+ )
+ .await
}
Err(error) => Err(super::protocol::config_error(error)),
};
@@ -309,16 +275,16 @@ pub(super) fn workspace_config_for_basilisk(
}
});
config.typeshed_commit.clone_from(&basilisk.typeshed_commit);
- config.typeshed_url.clone_from(&basilisk.typeshed_url);
- config.typeshed_cache_path = basilisk.typeshed_cache_path.as_ref().map(|path| {
+ config.typeshed_store_path = basilisk.typeshed_store_path.as_ref().map(|path| {
if path.is_absolute() {
path.clone()
} else {
root.join(path)
}
});
- config.typeshed_cache = basilisk.typeshed_cache.unwrap_or(true);
- config.typeshed_verify = basilisk.typeshed_verify.unwrap_or(true);
+ // The supplied checker config is authoritative for all three Typeshed
+ // keys, so a stale on-disk type error must not leak into resolution.
+ config.typeshed_configuration_error = None;
if basilisk.python_version.is_some() {
config.python_version.clone_from(&basilisk.python_version);
}
diff --git a/crates/basilisk-lsp/src/hover/access.rs b/crates/basilisk-lsp/src/hover/access.rs
new file mode 100644
index 00000000..fdb828a0
--- /dev/null
+++ b/crates/basilisk-lsp/src/hover/access.rs
@@ -0,0 +1,219 @@
+//! Implements [LSPARCH-FEATURES-HOVER]. See docs/specs/LSP-ARCHITECTURE-SPEC.md#LSPARCH-FEATURES-HOVER
+//!
+//! How the identifier under the cursor is reached, and what type the value
+//! before the dot has.
+//!
+//! `imported_symbols` is a flat, module-agnostic map: a plain `import os`
+//! publishes every member of `os` under its own bare name, so typeshed's
+//! `error = OSError` occupies the key `"error"`. Answering `logger.error(...)`
+//! from that key is a category error — the map may only be consulted for a
+//! name the module actually *binds*. This module draws that line.
+
+use basilisk_resolver::{ImportInfo, ImportKind, ResolvedModule, Span};
+
+use crate::util::{annotation_text, find_definition_by_name, SymbolHit};
+
+/// How the identifier under the cursor is reached.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum Access {
+ /// A free name — `getLogger(...)`, `MyClass`, `count`. Module-level
+ /// bindings and imported names both apply.
+ Free,
+ /// A member access — `logger.error`, `os.getcwd`, `" ".join`.
+ Member {
+ /// The receiver when it is a simple name; `None` when the receiver is
+ /// a literal or a compound expression (`" ".join`, `f().x`).
+ receiver: Option,
+ },
+}
+
+impl Access {
+ /// The receiver name, when this is a member access on a named receiver.
+ pub(crate) fn receiver(&self) -> Option<&str> {
+ match self {
+ Self::Free => None,
+ Self::Member { receiver } => receiver.as_deref(),
+ }
+ }
+
+ /// Whether this access reaches the identifier through a `.`.
+ pub(crate) const fn is_member(&self) -> bool {
+ matches!(self, Self::Member { .. })
+ }
+}
+
+/// Classify the access at `byte_offset`.
+///
+/// The identifier is a member access exactly when the first non-whitespace
+/// character before it is a `.` — independent of whether the receiver is a
+/// name, so `" ".join` is classified as a member access too.
+pub(crate) fn access_at(source: &str, byte_offset: usize) -> Access {
+ let before = source
+ .get(..byte_offset.min(source.len()))
+ .unwrap_or(source);
+ let stripped = before.trim_end_matches(|c: char| c.is_alphanumeric() || c == '_');
+ let Some(before_dot) = stripped.trim_end().strip_suffix('.') else {
+ return Access::Free;
+ };
+ let receiver: String = before_dot
+ .trim_end()
+ .chars()
+ .rev()
+ .take_while(|c| c.is_alphanumeric() || *c == '_')
+ .collect::>()
+ .into_iter()
+ .rev()
+ .collect();
+ Access::Member {
+ receiver: (!receiver.is_empty()).then_some(receiver),
+ }
+}
+
+/// The external symbol a module-qualified access names, e.g. `os.getcwd`.
+///
+/// The flat `imported_symbols` entry is trusted only when it came from a file
+/// that one of `receiver`'s plain imports actually resolved to. Without that
+/// check `logging`'s and `os`'s same-named exports are indistinguishable, and
+/// whichever import was processed last answers for both.
+pub(crate) fn module_member<'a>(
+ resolved: &'a ResolvedModule,
+ receiver: &str,
+ member: &str,
+) -> Option<&'a basilisk_resolver::scope::ExternalSymbol> {
+ let symbol = resolved.imported_symbols.get(member)?;
+ module_imports_for(resolved, receiver)
+ .any(|import| import.resolved_path.as_deref() == Some(symbol.source_path.as_path()))
+ .then_some(symbol)
+}
+
+/// The plain imports that bind `receiver` as a module object.
+///
+/// `import os` and `import os.path as p` both bind a module; `import os.path`
+/// binds only the leading `os` segment.
+fn module_imports_for<'a>(
+ resolved: &'a ResolvedModule,
+ receiver: &'a str,
+) -> impl Iterator- {
+ resolved.imports.iter().filter(move |import| {
+ import.kind == ImportKind::Plain
+ && (import.names.iter().any(|name| name == receiver)
+ || import.module == receiver
+ || (import.names.is_empty() && import.module.split('.').next() == Some(receiver)))
+ })
+}
+
+/// Find the innermost class that encloses `offset`.
+///
+/// A `self.` expression always sits inside a method body, which always
+/// follows its own `def` — so the enclosing class is the one owning the
+/// NEAREST PRECEDING method start, not the first method in the file
+/// (regression: members of the file's first class leaked into every later
+/// class).
+pub(crate) fn enclosing_class(
+ resolved: &ResolvedModule,
+ offset: usize,
+) -> Option<&basilisk_resolver::scope::ClassInfo> {
+ let func = resolved
+ .functions
+ .iter()
+ .filter(|f| f.class_name.is_some() && f.def_span.start_usize() <= offset)
+ .max_by_key(|f| f.def_span.start_usize())?;
+ let class_name = func.class_name.as_ref()?;
+ resolved.classes.iter().find(|c| &c.name == class_name)
+}
+
+/// The name of the type a value receiver has.
+///
+/// Resolved from the receiver's own declaration only — its annotation, the
+/// literal it was assigned, or the return type of the call that produced it
+/// (`logger = logging.getLogger(...)` → `Logger`). Nothing is guessed: an
+/// unresolvable receiver yields `None` so hover stays silent rather than
+/// answering for the wrong symbol ([LSPARCH-FEATURES-HOVER]).
+///
+/// The `bool` reports a `LiteralString`-compatible receiver, which selects the
+/// `LiteralString` overloads of built-in `str` methods.
+pub(crate) fn receiver_type_name(
+ resolved: &ResolvedModule,
+ source: &str,
+ receiver: &str,
+) -> Option<(String, bool)> {
+ let (annotation_span, rhs_kind, rhs_span) = match find_definition_by_name(resolved, receiver)? {
+ SymbolHit::Variable(var) => (var.annotation_span, Some(&var.rhs_kind), var.rhs_span),
+ SymbolHit::Parameter { param, .. } => (param.annotation_span, None, None),
+ _ => return None,
+ };
+ if let Some(annotation) = annotation_text(annotation_span, source) {
+ let literal = annotation == "LiteralString" || annotation == "typing.LiteralString";
+ return Some((
+ if literal {
+ "str".to_owned()
+ } else {
+ annotation
+ },
+ literal,
+ ));
+ }
+ let inferred = crate::util::rhs_type_display(rhs_kind?);
+ if inferred.is_empty() {
+ return call_return_type(resolved, rhs_span).map(|name| (name, false));
+ }
+ let literal =
+ inferred == "str" && matches!(rhs_kind, Some(basilisk_resolver::RhsKind::StrLiteral));
+ Some((inferred, literal))
+}
+
+/// The declared return type of the call that produced a variable.
+///
+/// The resolver already recorded the call site — its callee and receiver come
+/// from the AST, never from re-scanning source text.
+fn call_return_type(resolved: &ResolvedModule, rhs_span: Option) -> Option {
+ let span = rhs_span?;
+ let call = resolved.calls.iter().find(|call| call.span == span)?;
+ let declared = match &call.receiver {
+ None => free_callee_return_type(resolved, &call.callee),
+ Some(basilisk_resolver::scope::CallReceiver::Name(module)) => {
+ module_member(resolved, module, &call.callee)?
+ .type_annotation
+ .clone()
+ }
+ Some(_) => None,
+ }?;
+ bare_type_name(&declared)
+}
+
+/// The return type declared for a free callee: a local class constructor, a
+/// local function's return annotation, or an imported declaration.
+fn free_callee_return_type(resolved: &ResolvedModule, callee: &str) -> Option {
+ if resolved.classes.iter().any(|class| class.name == callee) {
+ return Some(callee.to_owned());
+ }
+ if let Some(func) = resolved
+ .functions
+ .iter()
+ .find(|func| func.name == callee && func.class_name.is_none())
+ {
+ if let Some(annotation) = annotation_text(func.return_annotation_span, &resolved.source) {
+ return Some(annotation);
+ }
+ }
+ let symbol = resolved.imported_symbols.get(callee)?;
+ match symbol.kind {
+ basilisk_resolver::scope::ExternalSymbolKind::Class => Some(symbol.name.clone()),
+ _ => symbol.type_annotation.clone(),
+ }
+}
+
+/// Reduce a declared type to the bare class name hover can look up.
+///
+/// `logging.Logger` → `Logger`, `"Logger"` → `Logger`, `list[int]` → `list`.
+/// A union or any other compound form has no single declaring class, so it
+/// yields `None` rather than an arbitrary member of it.
+fn bare_type_name(declared: &str) -> Option {
+ let trimmed = declared.trim().trim_matches(['\'', '"']).trim();
+ let head = trimmed.split('[').next().unwrap_or(trimmed).trim();
+ let bare = head.rsplit('.').next().unwrap_or(head);
+ let plain = !bare.is_empty()
+ && bare.chars().all(|c| c.is_alphanumeric() || c == '_')
+ && !bare.starts_with(|c: char| c.is_ascii_digit());
+ plain.then(|| bare.to_owned())
+}
diff --git a/crates/basilisk-lsp/src/hover/members.rs b/crates/basilisk-lsp/src/hover/members.rs
index 0d6a0b01..6aeebef3 100644
--- a/crates/basilisk-lsp/src/hover/members.rs
+++ b/crates/basilisk-lsp/src/hover/members.rs
@@ -1,71 +1,190 @@
//! Implements [LSPARCH-FEATURES-HOVER]. See docs/specs/LSP-ARCHITECTURE-SPEC.md#LSPARCH-FEATURES-HOVER
//! Implements the shared-declaration consumer half of [TYPESHEDRT-ACCEPTANCE-HOVER].
//!
-//! Dot-access member hover lookups: methods inherited from external
-//! (stub/py.typed) base classes (GitHub #287), builtin-typed receivers like
-//! `" ".join(...)` (GitHub #288), and the class-constructor hint (GitHub #289).
-
-use std::fmt::Write as _;
+//! Member-access hover: `receiver.member`.
+//!
+//! The receiver decides the answer. It may name an imported module
+//! (`os.getcwd`), a class (`Model.model_validate` — GitHub #287), or a value
+//! whose type comes from its annotation, its literal, or the call that
+//! produced it (`logger = logging.getLogger(...)` → `Logger`). A receiver
+//! nothing can type yields no hover: answering from the flat `imported_symbols`
+//! map by bare name would name whichever module happened to export the same
+//! word last.
use basilisk_resolver::ResolvedModule;
-use crate::util::{find_definition_by_name, identifier_at_offset, SymbolHit};
+use super::access::{self, Access};
+use super::render::{SymbolCard, SymbolKind};
+use crate::util::identifier_at_offset;
-/// Hover markdown for `Receiver.member` where `member` lives on an external
-/// class — the receiver itself or a (transitive) base of a local class.
+/// Hover markdown for the member access at `byte_offset`.
///
-/// Implements the dot-access member lookup for GitHub #287: methods inherited
-/// from stub/py.typed base classes have no local definition, so the standard
-/// symbol lookups find nothing.
-pub(super) fn external_member_hover(
+/// The first resolution that names a real declaration wins: the module the
+/// receiver binds, a class in the local hierarchy, an external (stub or
+/// `py.typed`) class, then a built-in type.
+pub(super) fn member_hover(
resolved: &ResolvedModule,
source: &str,
byte_offset: usize,
+ access: &Access,
) -> Option {
let member = identifier_at_offset(source, byte_offset)?;
- let receiver = crate::completion::prefix::dot_receiver(source, byte_offset)?;
- let (class, method) = find_external_member(resolved, &receiver, &member)?;
+ let receiver = access.receiver();
+ let class_name =
+ receiver.and_then(|receiver| receiver_class_name(resolved, source, byte_offset, receiver));
+
+ receiver
+ .and_then(|receiver| module_member_hover(resolved, receiver, &member))
+ .or_else(|| local_member_hover(resolved, class_name.as_deref(), &member))
+ .or_else(|| external_member_hover(resolved, receiver, class_name.as_deref(), &member))
+ .or_else(|| builtin_member_hover(resolved, source, byte_offset, &member))
+}
+
+/// The class whose members a receiver exposes.
+///
+/// `self`/`cls` expose the enclosing class; a receiver naming a local class
+/// exposes that class's own members (`Model.model_validate`); anything else is
+/// a value, typed from its own declaration.
+fn receiver_class_name(
+ resolved: &ResolvedModule,
+ source: &str,
+ byte_offset: usize,
+ receiver: &str,
+) -> Option {
+ if matches!(receiver, "self" | "cls") {
+ return access::enclosing_class(resolved, byte_offset).map(|class| class.name.clone());
+ }
+ if resolved.classes.iter().any(|class| class.name == receiver) {
+ return Some(receiver.to_owned());
+ }
+ access::receiver_type_name(resolved, source, receiver).map(|(name, _)| name)
+}
+
+/// Hover for `module.member`, e.g. `os.getcwd`.
+fn module_member_hover(resolved: &ResolvedModule, receiver: &str, member: &str) -> Option {
+ let symbol = access::module_member(resolved, receiver, member)?;
+ super::external_symbol_card(symbol, Some(receiver.to_owned())).render()
+}
+
+/// Hover for a member declared by a class in the *local* hierarchy — its own
+/// method or attribute, or one inherited from a local base.
+fn local_member_hover(
+ resolved: &ResolvedModule,
+ class_name: Option<&str>,
+ member: &str,
+) -> Option {
+ let start = class_name?;
+ let hit = walk_class_hierarchy(resolved, start, |name| {
+ resolved
+ .functions
+ .iter()
+ .find(|func| func.name == member && func.class_name.as_deref() == Some(name))
+ .map(crate::util::SymbolHit::Function)
+ .or_else(|| {
+ resolved
+ .classes
+ .iter()
+ .find(|class| class.name == name)
+ .and_then(|class| {
+ class
+ .attributes
+ .iter()
+ .find(|attr| attr.name == member)
+ .map(|attr| crate::util::SymbolHit::Attribute { class, attr })
+ })
+ })
+ })?;
+ let signature = crate::util::format_type_signature(&hit, &resolved.source);
+ let docstring = match hit {
+ crate::util::SymbolHit::Function(func) => func.docstring.clone(),
+ _ => None,
+ };
+ // `format_type_signature` already labels local symbols with their kind, so
+ // the card contributes no second prefix.
+ SymbolCard::new(None, signature)
+ .documented(docstring)
+ .render()
+}
+
+/// Hover markdown for a member declared on an external (stub or `py.typed`)
+/// class — the receiver's own class, or a (transitive) base of it.
+///
+/// Implements the dot-access member lookup for GitHub #287: methods inherited
+/// from stub base classes have no local definition, so the standard symbol
+/// lookups find nothing. Every overload of the member is shown, matching the
+/// built-in path.
+fn external_member_hover(
+ resolved: &ResolvedModule,
+ receiver: Option<&str>,
+ class_name: Option<&str>,
+ member: &str,
+) -> Option {
+ let (class, methods) = receiver
+ .and_then(|receiver| find_external_member(resolved, receiver, member))
+ .or_else(|| class_name.and_then(|name| find_external_member(resolved, name, member)))?;
// Stub signatures render as `def name(...)`; qualify with the class name
- // to match the local-method hover style `(method) def Class.name(...)`.
- let qualified = method.signature.strip_prefix("def ").map_or_else(
- || method.signature.clone(),
- |rest| format!("def {}.{rest}", class.name),
- );
- let mut md = format!("```python\n(method) {qualified}\n```");
- if let Some(label) = class
- .provenance
- .and_then(basilisk_stubs::TypeProvenance::hover_label)
- {
- let _ = write!(md, "\n\n*{label}*");
+ // so the hover names the type that declares the member.
+ let signatures = methods
+ .iter()
+ .map(|method| {
+ method.signature.strip_prefix("def ").map_or_else(
+ || method.signature.clone(),
+ |rest| format!("def {}.{rest}", class.name),
+ )
+ })
+ .collect();
+ SymbolCard {
+ kind: Some(SymbolKind::Method),
+ signatures,
+ ..SymbolCard::default()
}
- Some(md)
+ .documented(methods.iter().find_map(|method| method.docstring.clone()))
+ .declared_in(
+ declaring_module(resolved, class.source_path.as_path()),
+ class.provenance.as_ref(),
+ Some(class.source_path.as_path()),
+ )
+ .render()
}
-/// Find `member` on an external class reachable from `receiver`.
+/// Find `member` on an external class reachable from `start`.
///
-/// `receiver` may name an imported class directly, or a local class whose
-/// (transitive) bases include one.
+/// `start` may name an imported class directly, or a local class whose
+/// (transitive) bases include one. Returns every overload of the member.
fn find_external_member<'a>(
resolved: &'a ResolvedModule,
- receiver: &str,
+ start: &'a str,
member: &str,
) -> Option<(
&'a basilisk_resolver::scope::ExternalSymbol,
- &'a basilisk_resolver::scope::ExternalMethod,
+ Vec<&'a basilisk_resolver::scope::ExternalMethod>,
)> {
use basilisk_resolver::scope::ExternalSymbolKind;
- walk_class_hierarchy(resolved, receiver, |class_name| {
+ walk_class_hierarchy(resolved, start, |class_name| {
let ext = resolved.imported_symbols.get(class_name)?;
if ext.kind != ExternalSymbolKind::Class {
return None;
}
- let method = ext.methods.iter().find(|m| m.name == member)?;
- Some((ext, method))
+ let methods: Vec<_> = ext.methods.iter().filter(|m| m.name == member).collect();
+ (!methods.is_empty()).then_some((ext, methods))
})
}
+/// The module an external declaration was read from, for the origin line.
+///
+/// Matched by resolved file, not by name: a class reached through a receiver's
+/// type (`Logger` from `logging.getLogger(...)`) is never itself a bound name,
+/// so a name lookup would find nothing.
+fn declaring_module(resolved: &ResolvedModule, source_path: &std::path::Path) -> Option {
+ resolved
+ .imports
+ .iter()
+ .find(|import| import.resolved_path.as_deref() == Some(source_path))
+ .map(|import| import.module.clone())
+}
+
/// Find the `__init__` a class would run: its own, else the nearest one in
/// its local base chain (GitHub #289).
pub(super) fn find_class_init<'a>(
@@ -107,6 +226,14 @@ fn walk_class_hierarchy<'r, T>(
.map(|base| base.split('[').next().unwrap_or(base)),
);
}
+ if let Some(external) = resolved.imported_symbols.get(class_name) {
+ queue.extend(
+ external
+ .bases
+ .iter()
+ .map(|base| base.split('[').next().unwrap_or(base)),
+ );
+ }
}
None
}
@@ -114,31 +241,32 @@ fn walk_class_hierarchy<'r, T>(
/// Hover markdown for `recv.member` where `recv` is a builtin-typed receiver.
/// Every overload comes from the structured declaration indexed from the
/// active snapshot's real `builtins.pyi` body (GitHub #288).
-pub(super) fn builtin_member_hover(
+fn builtin_member_hover(
resolved: &ResolvedModule,
source: &str,
byte_offset: usize,
+ member: &str,
) -> Option {
- let member = identifier_at_offset(source, byte_offset)?;
- let (class, declarations) =
- builtin_member_declarations(resolved, source, byte_offset, &member)?;
+ let (class, declarations) = builtin_member_declarations(resolved, source, byte_offset, member)?;
let signatures = declarations
.iter()
.map(|declaration| basilisk_stubs::render_stub_signature(declaration))
.map(|signature| {
format!(
- "(method) def {}.{rest}",
+ "def {}.{rest}",
class.declaration.name,
rest = signature.strip_prefix("def ").unwrap_or(&signature)
)
})
- .collect::>()
- .join("\n");
- let mut markdown = format!("```python\n{signatures}\n```");
- if let Some(label) = class.provenance.hover_label() {
- let _ = write!(markdown, "\n\n*{label}* — `{}`", class.source_identity);
- }
- Some(markdown)
+ .collect();
+ let mut card = SymbolCard {
+ kind: Some(SymbolKind::Method),
+ signatures,
+ ..SymbolCard::default()
+ };
+ card.provenance = class.provenance.hover_label().map(str::to_owned);
+ card.source_path = Some(class.source_identity.clone());
+ card.render()
}
/// Active structured declarations for the built-in member at an editor offset.
@@ -186,7 +314,7 @@ pub(crate) fn dot_receiver_builtin_type(
}
c if c.is_alphanumeric() || c == '_' => {
let receiver = crate::completion::prefix::dot_receiver(source, byte_offset)?;
- variable_builtin_type(resolved, source, &receiver)
+ access::receiver_type_name(resolved, source, &receiver)
}
_ => None,
}
@@ -204,34 +332,3 @@ fn str_literal_receiver(receiver_text: &str, quote: char) -> bool {
.trim_end_matches(['r', 'R'])
.ends_with(['b', 'B'])
}
-
-/// The builtin type of a named variable or parameter: its annotation when it
-/// names a builtin type, else its inferred right-hand-side type.
-fn variable_builtin_type(
- resolved: &ResolvedModule,
- source: &str,
- receiver: &str,
-) -> Option<(String, bool)> {
- let (annotation_span, rhs_kind) = match find_definition_by_name(resolved, receiver)? {
- SymbolHit::Variable(var) => (var.annotation_span, Some(&var.rhs_kind)),
- SymbolHit::Parameter { param, .. } => (param.annotation_span, None),
- _ => return None,
- };
- if let Some(annotation) = crate::util::annotation_text(annotation_span, source) {
- let literal = annotation == "LiteralString" || annotation == "typing.LiteralString";
- let type_name = if literal {
- "str".to_owned()
- } else {
- annotation
- };
- return Some((type_name, literal));
- }
- let inferred = crate::util::rhs_type_display(rhs_kind?);
- if inferred.is_empty() {
- None
- } else {
- let literal =
- inferred == "str" && matches!(rhs_kind, Some(basilisk_resolver::RhsKind::StrLiteral));
- Some((inferred, literal))
- }
-}
diff --git a/crates/basilisk-lsp/src/hover/mod.rs b/crates/basilisk-lsp/src/hover/mod.rs
index d2925f9e..795429c0 100644
--- a/crates/basilisk-lsp/src/hover/mod.rs
+++ b/crates/basilisk-lsp/src/hover/mod.rs
@@ -11,6 +11,8 @@ use std::fmt::Write as _;
use basilisk_resolver::{ImportInfo, ImportResolution, PackageDepKind, ResolvedModule};
use tower_lsp::lsp_types::{Hover, HoverContents, MarkupContent, MarkupKind};
+use render::{SymbolCard, SymbolKind};
+
use crate::util::{
find_definition_by_name, find_symbol_at_offset, format_type_signature, identifier_at_offset,
SymbolHit,
@@ -18,10 +20,16 @@ use crate::util::{
/// Compute hover information at a byte offset.
///
-/// Searches definition sites first, then tries name-based lookup for
-/// reference sites (call sites, variable uses). Also shows import resolution
-/// details when the cursor is on an import statement, and any diagnostics
-/// covering the cursor position.
+/// A definition site (the cursor directly on a symbol's `name_span`) always
+/// answers for itself. Otherwise the answer depends on how the identifier is
+/// reached: a member access (`logger.error`) is resolved through its receiver,
+/// while a free name is resolved against the module's own bindings. The two
+/// must not be mixed — `imported_symbols` is keyed by bare name, so consulting
+/// it for a member would answer `logger.error` with whichever imported module
+/// happened to export the word `error`.
+///
+/// Import resolution details are added when the cursor is on an import
+/// statement, and any diagnostics covering the cursor position are appended.
#[must_use]
pub fn hover_at(
resolved: &ResolvedModule,
@@ -31,82 +39,15 @@ pub fn hover_at(
) -> Option {
let mut sections: Vec = Vec::new();
- // 1. Definition site: cursor directly on a symbol's name_span.
+ // 1. Definition site: cursor directly on a symbol's name_span. This is
+ // span-exact, so it answers for a member's own declaration too
+ // (`self.attr = ...`).
let hit = find_symbol_at_offset(resolved, byte_offset);
- // 2. Reference site: cursor on an identifier, look up by name.
- let hit = hit.or_else(|| {
- let name = identifier_at_offset(source, byte_offset)?;
- find_definition_by_name(resolved, &name)
- });
-
if let Some(ref hit) = hit {
push_symbol_sections(resolved, source, hit, &mut sections);
- }
-
- // 2b. Imported symbol with no local definition (e.g. a function/class from a
- // `.pyi` stub or a py.typed package): show its signature/type from
- // cross-module resolution so stub types surface on hover. When cross-module
- // resolution has not (yet) populated `imported_symbols`, fall back to the
- // import declaration itself, which is always available from the same-file
- // parse — so hovering a usage of an imported name is deterministic and never
- // races cross-file indexing.
- if hit.is_none() {
- if let Some(name) = identifier_at_offset(source, byte_offset) {
- let mut pushed = false;
- if let Some(ext_sym) = resolved.imported_symbols.get(&name) {
- let mut md = if let Some(sig) = &ext_sym.signature {
- format!("```python\n{sig}\n```")
- } else if let Some(ty) = &ext_sym.type_annotation {
- format!("```python\n{name}: {ty}\n```")
- } else {
- String::new()
- };
- if let Some(label) = ext_sym
- .provenance
- .and_then(basilisk_stubs::TypeProvenance::hover_label)
- {
- if !md.is_empty() {
- md.push_str("\n\n");
- }
- let _ = write!(md, "*{label}*");
- }
- if !md.is_empty() {
- sections.push(md);
- pushed = true;
- }
- // An imported class also shows its constructor, resolved from the
- // real `.pyi` via the flattened MRO methods — its own or inherited
- // `__init__`/`__new__` (GitHub #289). Never a hand table.
- if ext_sym.kind == basilisk_resolver::scope::ExternalSymbolKind::Class {
- for ctor in external_constructor_signatures(ext_sym) {
- sections.push(format!("```python\n{ctor}\n```"));
- pushed = true;
- }
- }
- }
- if !pushed {
- if let Some(imp) = crate::util::find_import_by_bound_name(resolved, &name) {
- let sig = format_type_signature(&SymbolHit::Import(imp), source);
- sections.push(format!("```python\n{sig}\n```"));
- }
- }
- }
- }
-
- // 2c. Dot-access on a member of an external class (GitHub #287): e.g.
- // `Model.model_validate(...)` where `Model` subclasses an imported stub
- // class. Nothing local or top-level matched, so resolve the receiver to an
- // external class — directly or through local base chains — and show the
- // member's signature from the stub. Failing that, type the receiver as a
- // builtin (`" ".join(...)` — GitHub #288) and use the curated builtin
- // method signatures.
- if hit.is_none() && sections.is_empty() {
- if let Some(md) = external_member_hover(resolved, source, byte_offset)
- .or_else(|| builtin_member_hover(resolved, source, byte_offset))
- {
- sections.push(md);
- }
+ } else {
+ push_reference_sections(resolved, source, byte_offset, &mut sections);
}
// 3. Import resolution details when the cursor is on an import statement.
@@ -144,6 +85,100 @@ pub fn hover_at(
})
}
+/// Push the hover sections for a *reference* to a symbol — a use, not its
+/// declaration.
+///
+/// A member access answers through its receiver; a free name answers from the
+/// module's own bindings. Keeping the two apart is what stops a plain
+/// `import os` — which publishes every member of `os` into `imported_symbols`
+/// under its bare name — from answering `logger.error(...)` with `os.error`.
+fn push_reference_sections(
+ resolved: &ResolvedModule,
+ source: &str,
+ byte_offset: usize,
+ sections: &mut Vec,
+) {
+ let access = access::access_at(source, byte_offset);
+ if access.is_member() {
+ if let Some(md) = members::member_hover(resolved, source, byte_offset, &access) {
+ sections.push(md);
+ }
+ return;
+ }
+ let Some(name) = identifier_at_offset(source, byte_offset) else {
+ return;
+ };
+ if let Some(hit) = find_definition_by_name(resolved, &name) {
+ push_symbol_sections(resolved, source, &hit, sections);
+ return;
+ }
+ push_imported_name_sections(resolved, source, &name, sections);
+}
+
+/// Push the sections for a free name that only cross-module resolution knows:
+/// a function or class from a `.pyi` stub or a `py.typed` package.
+///
+/// When cross-module resolution has not (yet) populated `imported_symbols`,
+/// this falls back to the import declaration itself, which is always available
+/// from the same-file parse — so hovering a usage of an imported name is
+/// deterministic and never races cross-file indexing (GitHub #200).
+fn push_imported_name_sections(
+ resolved: &ResolvedModule,
+ source: &str,
+ name: &str,
+ sections: &mut Vec,
+) {
+ let mut pushed = false;
+ if let Some(ext_sym) = resolved.imported_symbols.get(name) {
+ let module = crate::util::find_import_by_bound_name(resolved, name)
+ .map(|import| import.module.clone());
+ if let Some(md) = external_symbol_card(ext_sym, module).render() {
+ sections.push(md);
+ pushed = true;
+ }
+ // An imported class also shows its constructor, resolved from the
+ // real `.pyi` via the flattened MRO methods — its own or inherited
+ // `__init__`/`__new__` (GitHub #289). Never a hand table.
+ if ext_sym.kind == basilisk_resolver::scope::ExternalSymbolKind::Class {
+ for ctor in external_constructor_signatures(ext_sym) {
+ sections.push(format!("```python\n(method) {ctor}\n```"));
+ pushed = true;
+ }
+ }
+ }
+ if !pushed {
+ if let Some(imp) = crate::util::find_import_by_bound_name(resolved, name) {
+ let sig = format_type_signature(&SymbolHit::Import(imp), source);
+ sections.push(format!("```python\n{sig}\n```"));
+ }
+ }
+}
+
+/// The hover card for an imported symbol: what it is, its declared shape, its
+/// documentation, and where the declaration was read from.
+pub(super) fn external_symbol_card(
+ symbol: &basilisk_resolver::scope::ExternalSymbol,
+ module: Option,
+) -> SymbolCard {
+ let signature = symbol.signature.clone().or_else(|| {
+ symbol
+ .type_annotation
+ .as_ref()
+ .map(|ty| format!("{}: {ty}", symbol.name))
+ });
+ SymbolCard {
+ kind: SymbolKind::of_external(&symbol.kind),
+ signatures: signature.into_iter().collect(),
+ ..SymbolCard::default()
+ }
+ .documented(symbol.docstring.clone())
+ .declared_in(
+ module,
+ symbol.provenance.as_ref(),
+ Some(symbol.source_path.as_path()),
+ )
+}
+
/// Push the hover sections for a resolved symbol hit: its signature, the
/// constructor hint for classes (GitHub #289), its docstring, and the
/// provenance annotation for imported symbols.
@@ -176,14 +211,19 @@ fn push_symbol_sections(
sections.push(ds.to_owned());
}
- // Show provenance annotation for imported symbols.
+ // Show the provenance annotation for imported symbols. The name must
+ // actually be *bound* by an import: a plain `import os` publishes every
+ // member of `os` into `imported_symbols` under its bare name, so a local
+ // `def error(...)` would otherwise be labelled as coming from Typeshed.
let hit_name = match hit {
SymbolHit::Function(f) => Some(f.name.as_str()),
SymbolHit::Class(c) => Some(c.name.as_str()),
SymbolHit::Variable(v) => Some(v.name.as_str()),
_ => None,
};
- if let Some(name) = hit_name {
+ if let Some(name) =
+ hit_name.filter(|name| crate::util::find_import_by_bound_name(resolved, name).is_some())
+ {
if let Some(ext_sym) = resolved.imported_symbols.get(name) {
if let Some(label) = ext_sym
.provenance
@@ -356,9 +396,11 @@ fn configure_severity_link(code: &str) -> Option {
))
}
+pub(crate) mod access;
pub(crate) mod members;
+mod render;
-use members::{builtin_member_hover, external_member_hover, find_class_init};
+use members::find_class_init;
#[cfg(test)]
#[expect(
diff --git a/crates/basilisk-lsp/src/hover/render.rs b/crates/basilisk-lsp/src/hover/render.rs
new file mode 100644
index 00000000..288be00f
--- /dev/null
+++ b/crates/basilisk-lsp/src/hover/render.rs
@@ -0,0 +1,157 @@
+//! Implements [LSPARCH-FEATURES-HOVER]. See docs/specs/LSP-ARCHITECTURE-SPEC.md#LSPARCH-FEATURES-HOVER
+//!
+//! Markdown rendering for one hovered symbol.
+//!
+//! Every hover answers the same three questions in the same order: *what kind
+//! of thing is this*, *what is its exact shape*, and *where did that come
+//! from*. [`SymbolCard`] is the one place those are laid out, so a signature
+//! from a local `def`, a `.pyi` stub, and the bundled Typeshed snapshot all
+//! read identically. Unknown pieces are omitted rather than fabricated.
+
+use std::fmt::Write as _;
+
+/// What a hovered symbol is, as the label that precedes its signature.
+///
+/// The label is the vocabulary the rest of the LSP already uses for local
+/// symbols, so an imported symbol is described exactly like a local one.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum SymbolKind {
+ Function,
+ Method,
+ Class,
+ Variable,
+}
+
+impl SymbolKind {
+ const fn label(self) -> &'static str {
+ match self {
+ Self::Function => "function",
+ Self::Method => "method",
+ Self::Class => "class",
+ Self::Variable => "variable",
+ }
+ }
+
+ /// The kind of an external symbol, given how it is being accessed.
+ pub(crate) const fn of_external(
+ kind: &basilisk_resolver::scope::ExternalSymbolKind,
+ ) -> Option {
+ use basilisk_resolver::scope::ExternalSymbolKind as External;
+ match kind {
+ External::Function => Some(Self::Function),
+ External::Class => Some(Self::Class),
+ External::Variable => Some(Self::Variable),
+ // A re-export is a forwarding edge, not a symbol shape of its own.
+ External::ReExport => None,
+ }
+ }
+}
+
+/// The declaration's location as a reader wants to see it.
+///
+/// A snapshot body is addressed by a logical `typeshed:/…` URI whose
+/// identity is a content digest — precise, but 40 characters of noise in a
+/// hover bubble, and the provenance annotation beside it already says which
+/// snapshot is active. The snapshot-relative path is what identifies the
+/// declaration to a reader. A real file keeps its full path, which is
+/// actionable: it can be opened.
+fn readable_source_path(path: &std::path::Path) -> String {
+ let display = path.display().to_string();
+ display
+ .strip_prefix("typeshed:")
+ .and_then(|rest| rest.split_once('/'))
+ .map_or(display.clone(), |(_identity, relative)| relative.to_owned())
+}
+
+/// Everything hover knows about one symbol.
+#[derive(Debug, Default)]
+pub(crate) struct SymbolCard {
+ /// What the symbol is. `None` when nothing determined it.
+ pub(crate) kind: Option,
+ /// One rendered line per declaration — several for an overload set.
+ pub(crate) signatures: Vec,
+ /// The symbol's own prose documentation.
+ pub(crate) docstring: Option,
+ /// The module the declaration was read from, e.g. `logging`.
+ pub(crate) module: Option,
+ /// Where the type information came from, e.g. `(typeshed)`.
+ pub(crate) provenance: Option,
+ /// The file the declaration was read from.
+ pub(crate) source_path: Option,
+}
+
+impl SymbolCard {
+ /// A card for a single declaration.
+ pub(crate) fn new(kind: Option, signature: String) -> Self {
+ Self {
+ kind,
+ signatures: vec![signature],
+ ..Self::default()
+ }
+ }
+
+ /// Attach the origin of the declaration: its module, its provenance
+ /// annotation, and the file it was read from.
+ pub(crate) fn declared_in(
+ mut self,
+ module: Option,
+ provenance: Option<&basilisk_stubs::TypeProvenance>,
+ source_path: Option<&std::path::Path>,
+ ) -> Self {
+ self.module = module;
+ self.provenance = provenance
+ .and_then(|p| basilisk_stubs::TypeProvenance::hover_label(*p))
+ .map(str::to_owned);
+ self.source_path = source_path.map(readable_source_path);
+ self
+ }
+
+ /// Attach the symbol's documentation.
+ pub(crate) fn documented(mut self, docstring: Option) -> Self {
+ self.docstring = docstring;
+ self
+ }
+
+ /// Render the card as the Markdown sections of a hover bubble.
+ ///
+ /// Returns `None` when there is no signature to show — a card with only an
+ /// origin says nothing a user can act on.
+ pub(crate) fn render(&self) -> Option {
+ if self.signatures.is_empty() {
+ return None;
+ }
+ let prefix = self
+ .kind
+ .map(|kind| format!("({}) ", kind.label()))
+ .unwrap_or_default();
+ let body = self
+ .signatures
+ .iter()
+ .map(|signature| format!("{prefix}{signature}"))
+ .collect::>()
+ .join("\n");
+ let mut markdown = format!("```python\n{body}\n```");
+ if let Some(docstring) = &self.docstring {
+ let _ = write!(markdown, "\n\n{docstring}");
+ }
+ if let Some(origin) = self.origin_line() {
+ let _ = write!(markdown, "\n\n{origin}");
+ }
+ Some(markdown)
+ }
+
+ /// The trailing attribution line: module, provenance, and source file.
+ fn origin_line(&self) -> Option {
+ let mut parts: Vec = Vec::new();
+ if let Some(module) = &self.module {
+ parts.push(format!("`{module}`"));
+ }
+ if let Some(provenance) = &self.provenance {
+ parts.push(format!("*{provenance}*"));
+ }
+ if let Some(path) = &self.source_path {
+ parts.push(format!("`{path}`"));
+ }
+ (!parts.is_empty()).then(|| parts.join(" — "))
+ }
+}
diff --git a/crates/basilisk-lsp/src/hover/tests.rs b/crates/basilisk-lsp/src/hover/tests.rs
index ebd779f8..eb231b1c 100644
--- a/crates/basilisk-lsp/src/hover/tests.rs
+++ b/crates/basilisk-lsp/src/hover/tests.rs
@@ -70,6 +70,7 @@ fn test_hover_on_imported_stub_symbol_shows_signature() {
source_path: std::path::PathBuf::from("/venv/.../acme-stubs/__init__.pyi"),
source_span: Span::new(0, 0),
signature: Some("def fetch(url: str) -> bytes".to_owned()),
+ docstring: None,
provenance: Some(basilisk_stubs::TypeProvenance::StubTier1),
methods: Vec::new(),
bases: Vec::new(),
@@ -115,10 +116,12 @@ fn test_hover_on_imported_class_shows_inherited_constructor() {
source_path: std::path::PathBuf::from("/typeshed/stdlib/unittest/mock.pyi"),
source_span: Span::new(0, 0),
signature: Some("class Mock".to_owned()),
+ docstring: None,
provenance: Some(basilisk_stubs::TypeProvenance::StubTier1),
methods: vec![ExternalMethod {
name: "__init__".to_owned(),
signature: "def __init__(spec: Any, side_effect: Any) -> None".to_owned(),
+ docstring: None,
}],
bases: vec!["CallableMixin".to_owned(), "NonCallableMock".to_owned()],
metaclass: None,
@@ -570,3 +573,101 @@ fn test_hover_infers_generic_type_args_for_dict_literal() {
markup.value
);
}
+
+/// A member access resolves through its receiver, so `self.attr` still finds
+/// the attribute the enclosing class declares — the receiver-aware path must
+/// not have traded one broken lookup for another.
+///
+/// The attribute is declared in the class body: an attribute that only ever
+/// appears as `self.x = ...` inside a method is not recorded by the resolver
+/// at all (`ClassInfo::attributes` stays empty), so no hover consumer can
+/// reach it. That gap predates the receiver-aware path and is not what this
+/// test pins.
+#[test]
+fn test_hover_on_self_attribute_resolves_through_the_enclosing_class() {
+ let source =
+ "class Point:\n x: int = 0\n\n def show(self) -> None:\n print(self.x)\n";
+ let resolved = parse_and_resolve(source);
+
+ let offset = source.rfind("self.x").expect("the read must be present") + "self.".len();
+ let hover = hover_at(&resolved, source, offset, &[]).expect("`self.x` must have hover");
+ let HoverContents::Markup(markup) = hover.contents else {
+ panic!("expected Markup hover contents");
+ };
+
+ assert!(
+ markup.value.contains("Point.x") && markup.value.contains("int"),
+ "hover must show the attribute the enclosing class declares: {}",
+ markup.value
+ );
+}
+
+/// A local method reached through a variable typed by its constructor call.
+/// Nothing binds `instance` to `Greeter` except the call, so this only
+/// resolves once the receiver is typed from the call site.
+#[test]
+fn test_hover_on_method_of_constructor_typed_receiver() {
+ let source = "class Greeter:\n def greet(self, name: str) -> str:\n return name\n\ninstance = Greeter()\nvalue = instance.greet(\"x\")\n";
+ let resolved = parse_and_resolve(source);
+
+ let offset = source.rfind("greet").expect("the call must be present") + 1;
+ let hover = hover_at(&resolved, source, offset, &[]).expect("the method call must have hover");
+ let HoverContents::Markup(markup) = hover.contents else {
+ panic!("expected Markup hover contents");
+ };
+
+ assert!(
+ markup.value.contains("Greeter.greet") && markup.value.contains("name: str"),
+ "hover must resolve the method through the receiver's constructed type: {}",
+ markup.value
+ );
+}
+
+/// A plain `import os` publishes every member of `os` into `imported_symbols`
+/// under its bare name, so a *local* symbol that happens to share one of those
+/// names was being labelled as coming from Typeshed. Provenance may only be
+/// claimed for a name an import actually binds.
+#[test]
+fn test_hover_on_local_symbol_is_not_labelled_with_import_provenance() {
+ use basilisk_resolver::scope::{ExternalSymbol, ExternalSymbolKind};
+ use basilisk_resolver::Span;
+
+ let source = "import os\n\n\ndef error(message: str) -> None:\n print(message)\n\n\nerror(\"boom\")\n";
+ let mut resolved = parse_and_resolve(source);
+
+ // Exactly what a plain `import os` produces for typeshed's `error = OSError`.
+ let _ = resolved.imported_symbols.insert(
+ "error".to_owned(),
+ ExternalSymbol {
+ name: "error".to_owned(),
+ kind: ExternalSymbolKind::Variable,
+ type_annotation: Some("OSError".to_owned()),
+ source_path: std::path::PathBuf::from("typeshed:bundled/stdlib/os/__init__.pyi"),
+ source_span: Span::new(0, 0),
+ signature: None,
+ docstring: None,
+ provenance: Some(basilisk_stubs::TypeProvenance::StubTier1),
+ methods: Vec::new(),
+ bases: Vec::new(),
+ metaclass: None,
+ metaclass_calls: Vec::new(),
+ },
+ );
+
+ let offset = source.rfind("error").expect("the call must be present") + 1;
+ let hover = hover_at(&resolved, source, offset, &[]).expect("the local call must have hover");
+ let HoverContents::Markup(markup) = hover.contents else {
+ panic!("expected Markup hover contents");
+ };
+
+ assert!(
+ markup.value.contains("def error(message: str)"),
+ "hover must show the local definition: {}",
+ markup.value
+ );
+ assert!(
+ !markup.value.contains("(typeshed)"),
+ "a local symbol must not be attributed to an import that never bound it: {}",
+ markup.value
+ );
+}
diff --git a/crates/basilisk-lsp/src/lib.rs b/crates/basilisk-lsp/src/lib.rs
index 260f2fab..86ba62bb 100644
--- a/crates/basilisk-lsp/src/lib.rs
+++ b/crates/basilisk-lsp/src/lib.rs
@@ -61,6 +61,7 @@ pub mod symbols;
pub mod test_discovery;
pub mod type_definition;
pub mod type_hierarchy;
+pub(crate) mod typeshed_download;
pub mod util;
pub mod uv_commands;
pub mod uv_failure;
diff --git a/crates/basilisk-lsp/src/profiler/aggregator.rs b/crates/basilisk-lsp/src/profiler/aggregator.rs
index 021dff39..bec171bc 100644
--- a/crates/basilisk-lsp/src/profiler/aggregator.rs
+++ b/crates/basilisk-lsp/src/profiler/aggregator.rs
@@ -135,6 +135,17 @@ fn is_runtime_scaffolding(filename: &str, function: &str) -> bool {
{
return true;
}
+ // The stdlib thread-bootstrap spine. Every non-main thread starts inside
+ // `Thread._bootstrap`, so keeping it roots each thread's flame chart three
+ // rows above the code the user wrote, and — because the debugger's own
+ // housekeeping threads are started by the stdlib too — leaves a
+ // debugpy-only thread non-empty, so it survives as pure machinery instead
+ // of being dropped. Only the bootstrap trio qualifies: a genuine
+ // `threading` wait (`join`, `acquire`) is behaviour the user asked about,
+ // and a user's own `run` override lives in the user's file, not here.
+ if basename == "threading.py" {
+ return matches!(function, "_bootstrap" | "_bootstrap_inner" | "run");
+ }
normalized
.split('/')
.any(|segment| segment == "debugpy" || segment == "pydevd")
diff --git a/crates/basilisk-lsp/src/server/init.rs b/crates/basilisk-lsp/src/server/init.rs
index d7b12523..4b272edc 100644
--- a/crates/basilisk-lsp/src/server/init.rs
+++ b/crates/basilisk-lsp/src/server/init.rs
@@ -119,19 +119,14 @@ pub(super) async fn initialize(
.and_then(parse_python_interpreter);
(*server.python_interpreter.write().await).clone_from(&python_interpreter);
- // Every root starts in an explicit non-ready generation. The
- // `initialized` notification acquires one fully gated source before any
- // workspace analysis starts, and publishes the matching root-keyed status.
- {
- let mut generations = server.typeshed_generations.write().await;
- generations.clear();
- for root in &roots {
- let _ = generations.insert(
- root.clone(),
- super::typeshed_status::TypeshedGeneration::Acquiring,
- );
- }
- }
+ // Resolve every root's terminal Typeshed generation BEFORE answering
+ // `initialize`: resolution is a local store/bundle read
+ // ([STUBRES-TYPESHED-OFFLINE]), so the initialize payload below carries
+ // real Ready/NoSource statuses and no client ever renders an
+ // intermediate state ([LSPCFGED-TYPESHED]). Statuses ride the payload;
+ // change notifications only flow for later generation changes.
+ server.typeshed_generations.write().await.clear();
+ resolve_typeshed_for_roots(server, roots.clone(), false).await;
// Load project-level checker config (pyproject.toml [tool.basilisk]) so
// that rule severity overrides, per-module, and per-path settings match
@@ -324,7 +319,6 @@ pub(super) async fn initialized(server: &LspServer) {
.log_message(MessageType::INFO, "Basilisk LSP initialized")
.await;
- acquire_initial_typeshed(server).await;
install_initial_search_paths(server).await;
let statuses = server
@@ -392,11 +386,10 @@ pub(super) async fn initialized(server: &LspServer) {
match mode {
// Implements [ANALYSIS-STARTUP-OPEN]
AnalysisMode::OpenFilesOnly => {
- // `didOpen` may arrive while the initial Typeshed generation is
- // still Acquiring. The document handler preserves that buffer's
- // authoritative text without analysing it; once acquisition has
- // completed, this is the convergence point that analyses and
- // publishes every deferred open file owned by a ready root.
+ // `didOpen` may arrive before this notification. The document
+ // handler preserves that buffer's authoritative text; this is the
+ // convergence point that analyses and publishes every deferred
+ // open file owned by a root with a Ready generation.
let guard = server.index.read().await;
let Some(index) = guard.as_ref() else { return };
let results = index.refresh_open_files_for_roots(&ready_roots);
@@ -438,55 +431,32 @@ pub(super) async fn initialized(server: &LspServer) {
spawn_initial_test_discovery(server);
}
-async fn acquire_typeshed_snapshot(
- root: &std::path::Path,
- config: crate::config::WorkspaceConfig,
-) -> Result<
- Arc,
- super::typeshed_status::TypeshedFailure,
-> {
- let cache_path = config.typeshed_cache_path.clone();
- let request = crate::config::typeshed_request(&config)
- .map_err(super::typeshed_status::TypeshedFailure::acquisition)?;
- let manager = basilisk_stubs::typeshed::runtime::production_manager(request, cache_path)
- .map_err(|error| super::typeshed_status::TypeshedFailure::acquisition(error.to_string()))?;
- let result = tokio::task::spawn_blocking(move || manager.snapshot())
- .await
- .map_err(|_join_error| {
- super::typeshed_status::TypeshedFailure::acquisition("Typeshed acquisition task failed")
- })?
- .map_err(|error| super::typeshed_status::TypeshedFailure::from_selection(&error));
- if result.is_err() {
- tracing::warn!(root = %root.display(), "initial Typeshed acquisition failed");
- }
- result
-}
-
-/// Acquire each root's immutable generation before the first scan. Identical
-/// root policies may hit the same immutable cache entry, but each result is
-/// still published under the owning root so later configuration changes can
-/// replace one generation without cross-root bleed.
-async fn acquire_initial_typeshed(server: &LspServer) {
- let mut roots = server.workspace_roots.read().await.clone();
- roots.sort();
- acquire_typeshed_for_roots(server, roots).await;
-}
-
-async fn acquire_typeshed_for_roots(server: &LspServer, roots: Vec) {
+/// Resolve each root's terminal generation from local sources only — never
+/// the network ([STUBRES-TYPESHED-OFFLINE]). Identical root policies may
+/// resolve the same immutable store entry, but each result is still keyed by
+/// its owning root so later configuration changes can replace one generation
+/// without cross-root bleed.
+async fn resolve_typeshed_for_roots(
+ server: &LspServer,
+ roots: Vec,
+ notify: bool,
+) {
let interpreter = server.python_interpreter.read().await.clone();
for root in roots {
let mut config = crate::config::load_config(&root);
config.python_interpreter.clone_from(&interpreter);
- let generation = match acquire_typeshed_snapshot(&root, config).await {
- Ok(snapshot) => super::typeshed_status::TypeshedGeneration::Ready(snapshot),
- Err(failure) => super::typeshed_status::TypeshedGeneration::Blocked { failure },
- };
+ let generation = crate::configuration_editor::resolve_workspace(config).await;
+ if generation.ready_snapshot().is_none() {
+ tracing::warn!(root = %root.display(), "Typeshed source is not on this machine; analysis will not run for this root");
+ }
let _ = server
.typeshed_generations
.write()
.await
.insert(root.clone(), generation.clone());
- super::typeshed_status::notify_generation(&server.client, &root, &generation).await;
+ if notify {
+ super::typeshed_status::notify_generation(&server.client, &root, &generation).await;
+ }
}
}
@@ -717,22 +687,8 @@ pub(super) async fn did_change_workspace_folders(
for root in &removed_roots {
let _ = generations.remove(root);
}
- for root in &added_roots {
- let _ = generations.insert(
- root.clone(),
- super::typeshed_status::TypeshedGeneration::Acquiring,
- );
- }
}
- for root in &added_roots {
- super::typeshed_status::notify_generation(
- &server.client,
- root,
- &super::typeshed_status::TypeshedGeneration::Acquiring,
- )
- .await;
- }
- acquire_typeshed_for_roots(server, added_roots).await;
+ resolve_typeshed_for_roots(server, added_roots, true).await;
let interpreter = server.python_interpreter.read().await.clone();
let checker_config = updated_roots
@@ -1626,7 +1582,7 @@ mod explicit_python_tests {
}
#[tokio::test]
- async fn startup_acquires_custom_typeshed_before_analysis() {
+ async fn startup_resolves_custom_typeshed_before_analysis() {
let unique = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_or(0, |duration| duration.as_nanos());
@@ -1649,9 +1605,13 @@ mod explicit_python_tests {
typeshed_path: Some(custom),
..crate::config::WorkspaceConfig::default()
};
- let snapshot = acquire_typeshed_snapshot(&root, config).await;
- assert!(snapshot.is_ok(), "custom startup acquisition: {snapshot:?}");
- let Ok(snapshot) = snapshot else {
+ let generation = crate::configuration_editor::resolve_workspace(config).await;
+ let snapshot = generation.ready_snapshot();
+ assert!(
+ snapshot.is_some(),
+ "custom startup resolution: {generation:?}"
+ );
+ let Some(snapshot) = snapshot.cloned() else {
let _ = std::fs::remove_dir_all(&base);
return;
};
@@ -1696,7 +1656,7 @@ mod explicit_python_tests {
let _ = std::fs::remove_dir_all(&base);
}
- /// [STUBRES-TYPESHED-ACQUIRE]: readiness follows the longest owning root;
+ /// [STUBRES-TYPESHED-OFFLINE]: readiness follows the longest owning root;
/// a ready parent must not authorize analysis inside its blocked child.
#[test]
fn nested_workspace_typeshed_readiness_uses_the_longest_owner() {
diff --git a/crates/basilisk-lsp/src/server/stub_handlers.rs b/crates/basilisk-lsp/src/server/stub_handlers.rs
index 7ce603ec..6f841cc5 100644
--- a/crates/basilisk-lsp/src/server/stub_handlers.rs
+++ b/crates/basilisk-lsp/src/server/stub_handlers.rs
@@ -1,4 +1,4 @@
-//! Implements [STUBRES-CREATE-LOCAL]. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#stubres-create-local
+//! Implements [STUBRES-CREATE-LOCAL]. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-CREATE-LOCAL
//!
//! LSP command handler for `basilisk.stubs.createLocal`.
//!
diff --git a/crates/basilisk-lsp/src/server/typeshed_status.rs b/crates/basilisk-lsp/src/server/typeshed_status.rs
index bfc8809c..af45b64b 100644
--- a/crates/basilisk-lsp/src/server/typeshed_status.rs
+++ b/crates/basilisk-lsp/src/server/typeshed_status.rs
@@ -1,8 +1,14 @@
//! Implements [STUBRES-TYPESHED-WARN] LSP routing.
//!
-//! Typeshed transport status is editor metadata. It is merged into the
+//! Typeshed source status is editor metadata. It is merged into the
//! initialize payload for persistent Service Info and elevated warnings are
//! sent with `window/showMessage`; none of it is a Python diagnostic.
+//!
+//! There is **no acquiring state**: resolution is a local read
+//! ([STUBRES-TYPESHED-OFFLINE]), so a root's generation is always terminal —
+//! `Ready` or `NoSource`. The only long-running lifecycle is a user-invoked
+//! download, which never replaces the generation until it has finished and
+//! re-resolved locally ([LSPCFGED-TYPESHED-DOWNLOAD]).
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
@@ -20,19 +26,17 @@ use tower_lsp::Client;
use crate::configuration_editor::model::{
TypeshedLicenseStatus, TypeshedLifecycle, TypeshedStatusChanged, TypeshedStatusState,
};
-use crate::configuration_editor::snapshot_typeshed::status_projection;
+use crate::configuration_editor::snapshot_typeshed::ready_projection;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TypeshedFailureKind {
LicenseChanged,
CustomUnavailable,
- ExactUnavailable,
- LatestUnavailable,
- InconsistentIdentity,
- AcquisitionFailed,
+ NoSource,
+ ResolutionFailed,
}
-/// One redacted terminal acquisition failure with the selection category kept
+/// One redacted terminal resolution failure with the selection category kept
/// intact for typed RPC/status projection.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct TypeshedFailure {
@@ -42,9 +46,9 @@ pub(crate) struct TypeshedFailure {
impl TypeshedFailure {
#[must_use]
- pub(crate) fn acquisition(reason: impl Into) -> Self {
+ pub(crate) fn resolution(reason: impl Into) -> Self {
Self {
- kind: TypeshedFailureKind::AcquisitionFailed,
+ kind: TypeshedFailureKind::ResolutionFailed,
reason: reason.into(),
}
}
@@ -55,18 +59,11 @@ impl TypeshedFailure {
// Custom sources provide user-managed terms, so they never project
// the official Typeshed license as changed.
SelectionError::Custom(_) => TypeshedFailureKind::CustomUnavailable,
- SelectionError::Exact { reason, .. } if *reason == BackendError::LicenseChanged => {
- TypeshedFailureKind::LicenseChanged
- }
- SelectionError::Exact { .. } => TypeshedFailureKind::ExactUnavailable,
- SelectionError::LatestAndBundle { latest, bundle }
- if *latest == BackendError::LicenseChanged
- || *bundle == BackendError::LicenseChanged =>
- {
+ SelectionError::NoSource { reason, .. } if *reason == BackendError::LicenseChanged => {
TypeshedFailureKind::LicenseChanged
}
- SelectionError::LatestAndBundle { .. } => TypeshedFailureKind::LatestUnavailable,
- SelectionError::InconsistentIdentity => TypeshedFailureKind::InconsistentIdentity,
+ SelectionError::NoSource { .. } => TypeshedFailureKind::NoSource,
+ SelectionError::InconsistentIdentity => TypeshedFailureKind::ResolutionFailed,
};
Self {
kind,
@@ -79,10 +76,8 @@ impl TypeshedFailure {
match self.kind {
TypeshedFailureKind::LicenseChanged => "typeshedLicenseChanged",
TypeshedFailureKind::CustomUnavailable => "typeshedCustomUnavailable",
- TypeshedFailureKind::ExactUnavailable => "typeshedExactUnavailable",
- TypeshedFailureKind::LatestUnavailable => "typeshedLatestUnavailable",
- TypeshedFailureKind::InconsistentIdentity => "typeshedInconsistentIdentity",
- TypeshedFailureKind::AcquisitionFailed => "typeshedAcquisitionFailed",
+ TypeshedFailureKind::NoSource => "typeshedNoSource",
+ TypeshedFailureKind::ResolutionFailed => "typeshedResolutionFailed",
}
}
@@ -100,20 +95,19 @@ impl TypeshedFailure {
}
}
-/// One workspace root's acquisition generation.
+/// One workspace root's terminal resolution generation.
///
/// A candidate is never exposed as Ready until every activation gate passes.
-/// Reacquisition replaces this value atomically; in-flight requests may keep
-/// their old [`Arc`], while new analysis observes only the terminal
-/// generation selected for its root.
+/// A configuration change replaces this value atomically with the *next*
+/// terminal generation — there is no intermediate state to render, which is
+/// what keeps the editor free of blocking overlays ([LSPCFGED-TYPESHED]).
#[derive(Debug, Clone)]
pub(crate) enum TypeshedGeneration {
- /// Acquisition is in progress; analysis for this root must not start.
- Acquiring,
/// One complete immutable source is active.
Ready(Arc),
- /// No candidate activated. The reason is redacted and safe for UI/MCP.
- Blocked { failure: TypeshedFailure },
+ /// The selected source is not on this machine; analysis does not run.
+ /// The reason is redacted and safe for UI/MCP.
+ NoSource { failure: TypeshedFailure },
}
impl TypeshedGeneration {
@@ -122,7 +116,7 @@ impl TypeshedGeneration {
pub(crate) fn ready_snapshot(&self) -> Option<&Arc> {
match self {
Self::Ready(snapshot) => Some(snapshot),
- Self::Acquiring | Self::Blocked { .. } => None,
+ Self::NoSource { .. } => None,
}
}
@@ -136,19 +130,35 @@ impl TypeshedGeneration {
#[must_use]
pub(crate) fn status_state(&self) -> TypeshedStatusState {
match self {
- Self::Acquiring => status_projection(None),
- Self::Ready(snapshot) => status_projection(Some(&snapshot.status)),
- Self::Blocked { failure } => {
- let mut state = status_projection(None);
- state.lifecycle = TypeshedLifecycle::Blocked;
- state.blocked_reason = Some(failure.reason().to_owned());
- state.license_status = failure.license_status();
- state
- }
+ Self::Ready(snapshot) => ready_projection(&snapshot.status),
+ Self::NoSource { failure } => TypeshedStatusState {
+ lifecycle: TypeshedLifecycle::NoSource,
+ no_source_reason: Some(failure.reason().to_owned()),
+ active_source: None,
+ commit_identity: None,
+ license_status: failure.license_status(),
+ warnings: Vec::new(),
+ },
}
}
}
+/// The transient status shown while a user-invoked download runs. The
+/// generation map is untouched — the previous source keeps serving analysis —
+/// so this state can only ever appear on the invoking control, never as a
+/// panel-blocking mode ([LSPCFGED-TYPESHED-DOWNLOAD]).
+#[must_use]
+pub(crate) fn downloading_state(commit: Option<&str>) -> TypeshedStatusState {
+ TypeshedStatusState {
+ lifecycle: TypeshedLifecycle::Downloading,
+ no_source_reason: None,
+ active_source: None,
+ commit_identity: commit.map(str::to_owned),
+ license_status: TypeshedLicenseStatus::Unavailable,
+ warnings: Vec::new(),
+ }
+}
+
/// Root-keyed generation map shared by the LSP's analysis and status surfaces.
pub(crate) type TypeshedGenerations = BTreeMap;
@@ -181,7 +191,7 @@ pub(super) fn experimental_payload(
Value::Object(root)
}
-/// Typed terminal/acquiring status notification.
+/// Typed terminal/downloading status notification.
pub(crate) enum TypeshedStatusChangedNotification {}
impl Notification for TypeshedStatusChangedNotification {
@@ -195,6 +205,11 @@ pub(crate) async fn notify_generation(
root: &Path,
generation: &TypeshedGeneration,
) {
+ notify_status(client, root, generation.status_state()).await;
+}
+
+/// Notify clients of one root's status DTO (terminal or download-transient).
+pub(crate) async fn notify_status(client: &Client, root: &Path, status: TypeshedStatusState) {
let Ok(root_uri) = Url::from_file_path(root) else {
tracing::warn!(root = %root.display(), "cannot publish Typeshed status for non-file root");
return;
@@ -202,7 +217,7 @@ pub(crate) async fn notify_generation(
client
.send_notification::(TypeshedStatusChanged {
root_uri: root_uri.to_string(),
- status: generation.status_state(),
+ status,
})
.await;
}
@@ -232,32 +247,24 @@ fn object_or_empty(value: Option) -> Map {
#[cfg(test)]
mod tests {
use basilisk_stubs::typeshed::gittree::Oid;
- use basilisk_stubs::typeshed::source::{
- LicenseStatus, Provenance, SourceKind, StatusWarning, Transport,
- };
+ use basilisk_stubs::typeshed::source::{LicenseStatus, SourceKind, StatusWarning};
use basilisk_stubs::typeshed::warning::{TypeshedWarning, UnpinnedKind};
use super::*;
- fn fallback_status() -> TypeshedStatus {
+ fn bundled_default_status() -> TypeshedStatus {
TypeshedStatus {
active_source: SourceKind::Bundled,
commit: Oid::from_hex("83c2518a9e6abbda0c44592c3483de459198f887").ok(),
tree: Oid::from_hex("66408ffce2750980efc6da09e8a6652733f852e4").ok(),
- transport: Transport::EmbeddedZip,
license_status: LicenseStatus::Approved,
license_reference: Some(
"https://github.com/python/typeshed/blob/83c2518a9e6abbda0c44592c3483de459198f887/LICENSE"
.to_owned(),
),
- provenance: Provenance::BundleVetted,
- signed_release: false,
warnings: StatusWarning::list(&[
- TypeshedWarning::Unpinned(UnpinnedKind::LatestOrBundled),
- TypeshedWarning::DownloadFailed {
- bundled_sha: "83c2518a9e6abbda0c44592c3483de459198f887".to_owned(),
- },
- TypeshedWarning::Unverified,
+ TypeshedWarning::LicenseChanged,
+ TypeshedWarning::Unpinned(UnpinnedKind::BundledDefault),
]),
}
}
@@ -267,7 +274,7 @@ mod tests {
let Ok(mut snapshot) = basilisk_stubs::typeshed::bundle::bundled_snapshot() else {
return;
};
- snapshot.status = fallback_status();
+ snapshot.status = bundled_default_status();
let generations = BTreeMap::from([(
PathBuf::from("/workspace"),
TypeshedGeneration::Ready(Arc::new(snapshot)),
@@ -290,59 +297,87 @@ mod tests {
);
assert_eq!(
payload.pointer("/basilisk/typeshedStatuses/0/status/warnings/1/code"),
- Some(&Value::String("DOWNLOAD FAILED".to_owned()))
- );
- assert_eq!(
- payload.pointer("/basilisk/typeshedStatuses/0/status/warnings/2/code"),
- Some(&Value::String("UNVERIFIED".to_owned()))
- );
- assert_eq!(
- payload.pointer("/basilisk/typeshedStatuses/0/status/provenance/kind"),
- Some(&Value::String("BundleVetted".to_owned()))
- );
- assert_eq!(
- payload.pointer("/basilisk/typeshedStatuses/0/status/transport/kind"),
- Some(&Value::String("EmbeddedZip".to_owned()))
- );
- assert_eq!(
- payload.pointer("/basilisk/typeshedStatuses/0/status/signedRelease"),
- Some(&Value::Bool(false))
+ Some(&Value::String("LICENSE CHANGED".to_owned()))
);
+ // The retired trust-bijection fields must never reappear on the wire:
+ // the active source IS the trust story ([STUBRES-TYPESHED-WARN]).
+ for retired in ["transport", "provenance", "signedRelease", "blockedReason"] {
+ assert_eq!(
+ payload.pointer(&format!("/basilisk/typeshedStatuses/0/status/{retired}")),
+ None,
+ "retired wire field: {retired}"
+ );
+ }
}
+ /// [LSPCFGED-TYPESHED]: the lifecycle union has NO acquiring/blocked
+ /// panel state — a generation is always terminal, so there is nothing a
+ /// client could render as a blocking overlay between config changes.
#[test]
- fn blocked_generation_has_no_candidate_source_or_provenance() {
- let state = TypeshedGeneration::Blocked {
- failure: TypeshedFailure::acquisition("exact commit unavailable"),
+ fn generation_states_are_terminal_ready_or_no_source() {
+ let no_source = TypeshedGeneration::NoSource {
+ failure: TypeshedFailure::resolution("NO SOURCE — pin is not on this machine"),
}
.status_state();
- assert_eq!(state.lifecycle, TypeshedLifecycle::Blocked);
+ assert_eq!(no_source.lifecycle, TypeshedLifecycle::NoSource);
assert_eq!(
- state.blocked_reason.as_deref(),
- Some("exact commit unavailable")
+ no_source.no_source_reason.as_deref(),
+ Some("NO SOURCE — pin is not on this machine")
+ );
+ assert_eq!(no_source.license_status, TypeshedLicenseStatus::Unavailable);
+ assert!(no_source.active_source.is_none());
+ assert!(no_source.commit_identity.is_none());
+
+ // Serde-level proof the retired states are gone from the wire union.
+ for retired in ["Acquiring", "Blocked"] {
+ let json = format!("{{\"kind\":\"{retired}\"}}");
+ assert!(
+ serde_json::from_str::(&json).is_err(),
+ "retired lifecycle must not deserialize: {retired}"
+ );
+ }
+ }
+
+ /// [LSPCFGED-TYPESHED-DOWNLOAD]: the transient download status carries the
+ /// requested pin but never a source — it is button state, not a panel mode.
+ #[test]
+ fn downloading_state_is_transient_button_state() {
+ let state = downloading_state(Some("83c2518a9e6abbda0c44592c3483de459198f887"));
+ assert_eq!(state.lifecycle, TypeshedLifecycle::Downloading);
+ assert_eq!(
+ state.commit_identity.as_deref(),
+ Some("83c2518a9e6abbda0c44592c3483de459198f887")
);
- assert_eq!(state.license_status, TypeshedLicenseStatus::Unavailable);
assert!(state.active_source.is_none());
- assert!(state.commit_identity.is_none());
+ assert!(state.no_source_reason.is_none());
}
#[test]
- fn exact_license_drift_projects_changed_while_custom_failure_does_not() {
+ fn no_source_license_drift_projects_changed_while_custom_failure_does_not() {
let Ok(commit) = basilisk_stubs::typeshed::gittree::Oid::from_hex(
"0123456789012345678901234567890123456789",
) else {
return;
};
- let exact = TypeshedFailure::from_selection(&SelectionError::Exact {
+ let drifted = TypeshedFailure::from_selection(&SelectionError::NoSource {
commit,
reason: BackendError::LicenseChanged,
});
- let exact_state = TypeshedGeneration::Blocked { failure: exact }.status_state();
- assert_eq!(exact_state.license_status, TypeshedLicenseStatus::Changed);
+ assert_eq!(drifted.rpc_code(), "typeshedLicenseChanged");
+ let drifted_state = TypeshedGeneration::NoSource { failure: drifted }.status_state();
+ assert_eq!(drifted_state.license_status, TypeshedLicenseStatus::Changed);
+
+ let missing = TypeshedFailure::from_selection(&SelectionError::NoSource {
+ commit,
+ reason: BackendError::Missing,
+ });
+ assert_eq!(missing.rpc_code(), "typeshedNoSource");
+ assert!(missing.reason().contains("NO SOURCE"));
let custom =
TypeshedFailure::from_selection(&SelectionError::Custom(BackendError::LicenseChanged));
- let custom_state = TypeshedGeneration::Blocked { failure: custom }.status_state();
+ assert_eq!(custom.rpc_code(), "typeshedCustomUnavailable");
+ let custom_state = TypeshedGeneration::NoSource { failure: custom }.status_state();
assert_eq!(
custom_state.license_status,
TypeshedLicenseStatus::Unavailable
@@ -351,14 +386,11 @@ mod tests {
#[test]
fn show_message_projection_contains_only_high_warnings() {
- let messages = high_warning_messages(&fallback_status());
- assert_eq!(messages.len(), 2);
+ let messages = high_warning_messages(&bundled_default_status());
+ assert_eq!(messages.len(), 1);
assert!(messages
.first()
- .is_some_and(|message| message.contains("DOWNLOAD FAILED")));
- assert!(messages
- .get(1)
- .is_some_and(|message| message.contains("UNVERIFIED")));
+ .is_some_and(|message| message.contains("LICENSE CHANGED")));
assert!(messages.iter().all(|message| !message.contains("UNPINNED")));
let source = include_str!("typeshed_status.rs");
diff --git a/crates/basilisk-lsp/src/typeshed_download.rs b/crates/basilisk-lsp/src/typeshed_download.rs
new file mode 100644
index 00000000..134cb550
--- /dev/null
+++ b/crates/basilisk-lsp/src/typeshed_download.rs
@@ -0,0 +1,222 @@
+//! User-invoked Typeshed downloads ([LSPCFGED-TYPESHED-DOWNLOAD]).
+//!
+//! Lives OUTSIDE the configuration editor ([TYPESHEDRT-SEGREGATION]): the
+//! editor only reads and writes the three Typeshed keys, while this module is
+//! the only LSP code that reaches the network — and it runs only when a
+//! person invokes one of the two Download buttons. The root's generation map
+//! is untouched while a download runs, so the active source keeps serving
+//! analysis and the transient `Downloading` status exists only on the
+//! invoking control, never as a panel-blocking mode.
+
+use std::path::{Path, PathBuf};
+
+use basilisk_config::{BasiliskConfig, ConfigDocument, ConfigurationUpdate, TypeshedConfigKey};
+use basilisk_stubs::typeshed::gittree::Oid;
+use basilisk_typeshed_fetch::{DownloadError, DownloadOutcome, DownloadPhase, GithubClient};
+use tower_lsp::jsonrpc::Result as LspResult;
+
+use crate::configuration_editor::rpc_error;
+use crate::server::typeshed_status::{downloading_state, notify_status, TypeshedGeneration};
+use crate::server::LspServer;
+
+/// Download `python/typeshed@main` into the store and write the returned SHA
+/// as the pin — the Download latest contract ([STUBRES-TYPESHED-DOWNLOAD]).
+/// The pin write rides the same validated editor transaction as any other
+/// configuration edit, which re-resolves locally and publishes the terminal
+/// generation.
+pub(crate) async fn download_latest_and_pin(
+ server: &LspServer,
+ root: &Path,
+ document: &ConfigDocument,
+) -> LspResult<()> {
+ notify_status(&server.client, root, downloading_state(None)).await;
+ let result = match run_download(store_path_for(root, &document.config), None).await {
+ Ok(outcome) => crate::configuration_editor::apply_configuration_update(
+ server,
+ root,
+ &pin_update(&outcome),
+ "typeshedDownloadLatest",
+ )
+ .await
+ .map(|_applied| ()),
+ Err(error) => Err(error),
+ };
+ // Always settle on a terminal status so the invoking control's transient
+ // download state clears — even when the pin was already current and the
+ // transaction therefore staged nothing.
+ republish_terminal(server, root).await;
+ result
+}
+
+/// Materialise the existing pin on a machine that never downloaded it. Writes
+/// no configuration; on success the root re-resolves locally and activates.
+pub(crate) async fn download_pinned(
+ server: &LspServer,
+ root: &Path,
+ document: &ConfigDocument,
+) -> LspResult<()> {
+ if document.config.typeshed_path.is_some() {
+ return Err(rpc_error(
+ "typeshedActionUnavailable",
+ "a custom Typeshed folder has no commit to download",
+ ));
+ }
+ let Some(commit_hex) = document.config.typeshed_commit.clone() else {
+ return Err(rpc_error(
+ "typeshedActionUnavailable",
+ "no pinned commit to download — the unset pin resolves to the bundled source",
+ ));
+ };
+ let commit = Oid::from_hex(&commit_hex).map_err(|_invalid_oid| {
+ rpc_error(
+ "invalidTypeshedSetting",
+ "typeshed-commit must be a full 40-character hexadecimal SHA",
+ )
+ })?;
+ notify_status(&server.client, root, downloading_state(Some(&commit_hex))).await;
+ let result = match run_download(store_path_for(root, &document.config), Some(commit)).await {
+ Ok(_outcome) => {
+ crate::configuration_editor::resolve_and_activate(server, root, document).await
+ }
+ Err(error) => Err(error),
+ };
+ republish_terminal(server, root).await;
+ result
+}
+
+/// The workspace-resolved store override, when configured. `None` lets the
+/// download component fall back to the canonical per-user store
+/// ([STUBRES-TYPESHED-STORE]).
+fn store_path_for(root: &Path, config: &BasiliskConfig) -> Option {
+ config.typeshed_store_path.as_ref().map(|path| {
+ if path.is_absolute() {
+ path.clone()
+ } else {
+ root.join(path)
+ }
+ })
+}
+
+async fn run_download(
+ store_path: Option,
+ commit: Option,
+) -> LspResult {
+ tokio::task::spawn_blocking(move || {
+ let client = GithubClient::new();
+ let progress = |phase: DownloadPhase| {
+ tracing::info!(?phase, "typeshed download progress");
+ };
+ match commit {
+ Some(commit) => {
+ basilisk_typeshed_fetch::download_commit(commit, store_path, &client, &progress)
+ }
+ None => basilisk_typeshed_fetch::download_latest(store_path, &client, &progress),
+ }
+ })
+ .await
+ .map_err(|_join_error| rpc_error("typeshedDownloadFailed", "typeshed download task failed"))?
+ .map_err(|error| rpc_error(download_error_code(error), &error.to_string()))
+}
+
+const fn download_error_code(error: DownloadError) -> &'static str {
+ match error {
+ DownloadError::LicenseChanged => "typeshedLicenseChanged",
+ DownloadError::Metadata
+ | DownloadError::Download
+ | DownloadError::Validation
+ | DownloadError::Store => "typeshedDownloadFailed",
+ }
+}
+
+fn pin_update(outcome: &DownloadOutcome) -> ConfigurationUpdate {
+ let mut update = ConfigurationUpdate::default();
+ let _ = update.typeshed.entries.insert(
+ TypeshedConfigKey::TypeshedCommit,
+ Some(outcome.commit.to_hex()),
+ );
+ let _ = update
+ .typeshed
+ .entries
+ .insert(TypeshedConfigKey::TypeshedPath, None);
+ update
+}
+
+/// Re-notify the root's current terminal status after a download settles.
+async fn republish_terminal(server: &LspServer, root: &Path) {
+ let status = server
+ .typeshed_generations
+ .read()
+ .await
+ .get(root)
+ .map(TypeshedGeneration::status_state);
+ match status {
+ Some(status) => notify_status(&server.client, root, status).await,
+ None => {
+ tracing::warn!(root = %root.display(), "no Typeshed generation to republish after download");
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use basilisk_stubs::typeshed::gittree::Oid;
+ use basilisk_typeshed_fetch::{DownloadError, DownloadOutcome};
+
+ use super::{download_error_code, pin_update, store_path_for};
+ use basilisk_config::{BasiliskConfig, TypeshedConfigKey};
+
+ /// [STUBRES-TYPESHED-DOWNLOAD]: Download latest writes the returned SHA
+ /// as the pin and clears any custom folder — the two keys are mutually
+ /// exclusive, so the update must retire one while setting the other.
+ #[test]
+ fn download_latest_pin_update_sets_commit_and_clears_custom_path() {
+ let Ok(commit) = Oid::from_hex("0123456789012345678901234567890123456789") else {
+ return;
+ };
+ let Ok(tree) = Oid::from_hex("abcdefabcdefabcdefabcdefabcdefabcdefabcd") else {
+ return;
+ };
+ let update = pin_update(&DownloadOutcome { commit, tree });
+ assert_eq!(
+ update
+ .typeshed
+ .entries
+ .get(&TypeshedConfigKey::TypeshedCommit),
+ Some(&Some("0123456789012345678901234567890123456789".to_owned()))
+ );
+ assert_eq!(
+ update
+ .typeshed
+ .entries
+ .get(&TypeshedConfigKey::TypeshedPath),
+ Some(&None)
+ );
+ assert!(!update
+ .typeshed
+ .entries
+ .contains_key(&TypeshedConfigKey::TypeshedStorePath));
+ }
+
+ #[test]
+ fn license_drift_keeps_its_typed_error_code() {
+ assert_eq!(
+ download_error_code(DownloadError::LicenseChanged),
+ "typeshedLicenseChanged"
+ );
+ assert_eq!(
+ download_error_code(DownloadError::Metadata),
+ "typeshedDownloadFailed"
+ );
+ }
+
+ #[test]
+ fn relative_store_override_roots_at_the_workspace() {
+ let mut config = BasiliskConfig::default();
+ assert!(store_path_for(std::path::Path::new("/workspace"), &config).is_none());
+ config.typeshed_store_path = Some(std::path::PathBuf::from("stores/typeshed"));
+ assert_eq!(
+ store_path_for(std::path::Path::new("/workspace"), &config),
+ Some(std::path::PathBuf::from("/workspace/stores/typeshed"))
+ );
+ }
+}
diff --git a/crates/basilisk-lsp/tests/bundled_mock_hover_tests.rs b/crates/basilisk-lsp/tests/bundled_mock_hover_tests.rs
index 6252bc2f..dae6ffd5 100644
--- a/crates/basilisk-lsp/tests/bundled_mock_hover_tests.rs
+++ b/crates/basilisk-lsp/tests/bundled_mock_hover_tests.rs
@@ -13,50 +13,31 @@
use std::sync::Arc;
-use basilisk_checker::imports::{ActiveTypeshed, ImportSearchPaths};
-use basilisk_checker::{
- cross_resolved_module, BasiliskDatabase, FileRegistry, ResolvedFile, SearchPathsInput,
- SourceFile, WorkspaceFiles,
-};
+use basilisk_checker::imports::ActiveTypeshed;
use basilisk_lsp::hover::hover_at;
use basilisk_stubs::types::{StubTarget, StubTargetPlatform};
use basilisk_stubs::typeshed::archive::{Archive, ArchiveEntry, ArchiveVfs};
use basilisk_stubs::typeshed::gittree::FileMode;
use basilisk_stubs::typeshed::snapshot::Snapshot;
-use basilisk_stubs::typeshed::source::{
- LicenseStatus, Provenance, SourceIdentity, SourceKind, Transport, TypeshedStatus,
-};
+use basilisk_stubs::typeshed::source::{LicenseStatus, SourceIdentity, SourceKind, TypeshedStatus};
use tower_lsp::lsp_types::HoverContents;
fn resolve_with_snapshot(
snapshot: Arc,
source: &str,
) -> Arc {
- let search_paths = ImportSearchPaths {
- roots: Vec::new(),
- extra_paths: Vec::new(),
- stub_paths: Vec::new(),
- workspace_members: Vec::new(),
- site_packages: None,
- registry: None,
- typeshed_snapshot: Some(ActiveTypeshed::new(
+ let search_paths = basilisk_test_utils::typeshed_search_paths(
+ ActiveTypeshed::new(
snapshot,
Some(StubTarget {
python_version: (3, 12),
platform: StubTargetPlatform::Concrete("linux".to_owned()),
}),
- )),
- };
- let database = BasiliskDatabase::default();
- let search_input = SearchPathsInput::new(&database, search_paths);
- let workspace = WorkspaceFiles::new(&database, FileRegistry::default());
- let file = SourceFile::new(&database, "main.py".to_owned(), source.to_owned());
- let ResolvedFile::Resolved(resolved) =
- cross_resolved_module(&database, file, search_input, workspace)
- else {
- panic!("the Mock fixture must parse and resolve");
- };
- Arc::clone(resolved)
+ ),
+ Vec::new(),
+ );
+ basilisk_test_utils::cross_resolve(source, search_paths)
+ .expect("the Mock fixture must parse and resolve")
}
fn custom_mock_snapshot() -> Arc {
@@ -80,11 +61,8 @@ fn custom_mock_snapshot() -> Arc {
active_source: SourceKind::Custom,
commit: None,
tree: None,
- transport: Transport::CustomPath,
license_status: LicenseStatus::NotSupplied,
license_reference: None,
- provenance: Provenance::UserManaged,
- signed_release: false,
warnings: Vec::new(),
};
Arc::new(
diff --git a/crates/basilisk-lsp/tests/custom_typeshed_hover_tests.rs b/crates/basilisk-lsp/tests/custom_typeshed_hover_tests.rs
index f90ae83f..a2179107 100644
--- a/crates/basilisk-lsp/tests/custom_typeshed_hover_tests.rs
+++ b/crates/basilisk-lsp/tests/custom_typeshed_hover_tests.rs
@@ -32,6 +32,7 @@ fn hover_on_custom_typeshed_symbol_shows_custom_annotation() -> Result<(), Strin
source_path: std::path::PathBuf::from("/proj/ts/stdlib/os.pyi"),
source_span: Span::new(0, 0),
signature: Some("def uname() -> str".to_owned()),
+ docstring: None,
provenance: Some(basilisk_stubs::TypeProvenance::StubCustomTypeshed),
methods: Vec::new(),
bases: Vec::new(),
diff --git a/crates/basilisk-lsp/tests/custom_typeshed_workspace_tests.rs b/crates/basilisk-lsp/tests/custom_typeshed_workspace_tests.rs
index efebca42..7133f271 100644
--- a/crates/basilisk-lsp/tests/custom_typeshed_workspace_tests.rs
+++ b/crates/basilisk-lsp/tests/custom_typeshed_workspace_tests.rs
@@ -81,8 +81,7 @@ fn lsp_threads_custom_typeshed_into_imported_symbols() {
let mut search_paths =
basilisk_lsp::import_resolver::search_paths_from_config(&roots, &config, None);
let request = basilisk_lsp::config::typeshed_request(&config).expect("custom request");
- let manager = basilisk_stubs::typeshed::runtime::production_manager(request, None)
- .expect("custom manager");
+ let manager = basilisk_stubs::typeshed::runtime::production_manager(request);
let snapshot = manager.snapshot().expect("custom snapshot");
search_paths.typeshed_snapshot = Some(basilisk_lsp::import_resolver::ActiveTypeshed::new(
snapshot,
diff --git a/crates/basilisk-lsp/tests/external_metaclass_constructor_tests.rs b/crates/basilisk-lsp/tests/external_metaclass_constructor_tests.rs
index 0e3d4054..14522e3d 100644
--- a/crates/basilisk-lsp/tests/external_metaclass_constructor_tests.rs
+++ b/crates/basilisk-lsp/tests/external_metaclass_constructor_tests.rs
@@ -9,19 +9,13 @@
use std::sync::Arc;
-use basilisk_checker::imports::{ActiveTypeshed, ImportSearchPaths};
-use basilisk_checker::{
- cross_resolved_module, BasiliskDatabase, FileRegistry, ResolvedFile, SearchPathsInput,
- SourceFile, WorkspaceFiles,
-};
+use basilisk_checker::imports::ActiveTypeshed;
use basilisk_lsp::hover::hover_at;
use basilisk_stubs::types::{StubTarget, StubTargetPlatform};
use basilisk_stubs::typeshed::archive::{Archive, ArchiveEntry, ArchiveVfs};
use basilisk_stubs::typeshed::gittree::FileMode;
use basilisk_stubs::typeshed::snapshot::Snapshot;
-use basilisk_stubs::typeshed::source::{
- LicenseStatus, Provenance, SourceIdentity, SourceKind, Transport, TypeshedStatus,
-};
+use basilisk_stubs::typeshed::source::{LicenseStatus, SourceIdentity, SourceKind, TypeshedStatus};
use tower_lsp::lsp_types::HoverContents;
fn metaclass_snapshot() -> Arc {
@@ -60,11 +54,8 @@ fn metaclass_snapshot() -> Arc {
active_source: SourceKind::Custom,
commit: None,
tree: None,
- transport: Transport::CustomPath,
license_status: LicenseStatus::NotSupplied,
license_reference: None,
- provenance: Provenance::UserManaged,
- signed_release: false,
warnings: Vec::new(),
};
Arc::new(
@@ -79,31 +70,18 @@ fn metaclass_snapshot() -> Arc {
}
fn resolve(source: &str) -> Arc {
- let search_paths = ImportSearchPaths {
- roots: Vec::new(),
- extra_paths: Vec::new(),
- stub_paths: Vec::new(),
- workspace_members: Vec::new(),
- site_packages: None,
- registry: None,
- typeshed_snapshot: Some(ActiveTypeshed::new(
+ let search_paths = basilisk_test_utils::typeshed_search_paths(
+ ActiveTypeshed::new(
metaclass_snapshot(),
Some(StubTarget {
python_version: (3, 12),
platform: StubTargetPlatform::Concrete("linux".to_owned()),
}),
- )),
- };
- let database = BasiliskDatabase::default();
- let search_input = SearchPathsInput::new(&database, search_paths);
- let workspace = WorkspaceFiles::new(&database, FileRegistry::default());
- let file = SourceFile::new(&database, "main.py".to_owned(), source.to_owned());
- let ResolvedFile::Resolved(resolved) =
- cross_resolved_module(&database, file, search_input, workspace)
- else {
- panic!("fixture source must parse and resolve");
- };
- Arc::clone(resolved)
+ ),
+ Vec::new(),
+ );
+ basilisk_test_utils::cross_resolve(source, search_paths)
+ .expect("fixture source must parse and resolve")
}
fn hover_markdown(
diff --git a/crates/basilisk-lsp/tests/hover_member_resolution_tests.rs b/crates/basilisk-lsp/tests/hover_member_resolution_tests.rs
new file mode 100644
index 00000000..03dc01bc
--- /dev/null
+++ b/crates/basilisk-lsp/tests/hover_member_resolution_tests.rs
@@ -0,0 +1,156 @@
+//! Implements [LSPARCH-FEATURES-HOVER]. See docs/specs/LSP-ARCHITECTURE-SPEC.md#LSPARCH-FEATURES-HOVER
+//! Acceptance for the shared-declaration consumer half of [TYPESHEDRT-ACCEPTANCE-HOVER].
+//!
+//! Hovering `receiver.member` must answer for **that member on that receiver**.
+//! A plain `import os` publishes every member of `os` into the flat
+//! `imported_symbols` map under its bare name, so typeshed's `error = OSError`
+//! occupies the key `"error"`; hover used to answer `logger.error(...)` from
+//! that key because it never looked at the receiver before the dot.
+//!
+//! These fixtures enter through the real salsa `cross_resolved_module` query
+//! over the real bundled Typeshed snapshot — no hand-built `ExternalSymbol`.
+
+#![allow(
+ clippy::expect_used,
+ clippy::panic,
+ missing_docs,
+ reason = "end-to-end acceptance fixture"
+)]
+
+use std::sync::Arc;
+
+use basilisk_checker::imports::ActiveTypeshed;
+use basilisk_lsp::hover::hover_at;
+use basilisk_stubs::types::{StubTarget, StubTargetPlatform};
+use basilisk_test_utils::{cross_resolve, typeshed_search_paths};
+use tower_lsp::lsp_types::HoverContents;
+
+/// A module that logs through a `logging.Logger` while also importing `os` —
+/// the exact collision that made hover answer with `os.error`.
+const LOGGER_SOURCE: &str = concat!(
+ "import logging\n",
+ "import os\n",
+ "\n",
+ "logger = logging.getLogger(__name__)\n",
+ "\n",
+ "\n",
+ "def mint() -> None:\n",
+ " logger.error(\"jwt_minter.no_secret\")\n",
+);
+
+fn resolve_against_bundled_typeshed(source: &str) -> Arc {
+ let snapshot = Arc::new(
+ basilisk_stubs::typeshed::bundle::bundled_snapshot()
+ .expect("the release-attested bundled snapshot must activate"),
+ );
+ let search_paths = typeshed_search_paths(
+ ActiveTypeshed::new(
+ snapshot,
+ Some(StubTarget {
+ python_version: (3, 12),
+ platform: StubTargetPlatform::Concrete("linux".to_owned()),
+ }),
+ ),
+ Vec::new(),
+ );
+ cross_resolve(source, search_paths).expect("the fixture must parse and resolve")
+}
+
+fn hover_markdown(
+ resolved: &basilisk_resolver::ResolvedModule,
+ source: &str,
+ offset: usize,
+) -> Option {
+ match hover_at(resolved, source, offset, &[])?.contents {
+ HoverContents::Markup(markup) => Some(markup.value),
+ _ => panic!("hover contents must be Markdown"),
+ }
+}
+
+/// The reported bug: hovering the `error` member of a `Logger` receiver
+/// answered from typeshed's unrelated `os.error = OSError` binding, because
+/// `identifier_at_offset` discards the `logger.` receiver and the bare-name
+/// `imported_symbols` lookup pre-empted the dot-aware member lookup.
+///
+/// A member hover must never be answered by a bare module-level name.
+#[test]
+fn hover_on_member_never_answers_from_an_unrelated_bare_module_name() {
+ let resolved = resolve_against_bundled_typeshed(LOGGER_SOURCE);
+ assert!(
+ resolved.imported_symbols.contains_key("error"),
+ "precondition: a plain `import os` publishes typeshed's `error = OSError` \
+ under the bare key, which is what hover used to answer with"
+ );
+
+ let offset = LOGGER_SOURCE
+ .rfind("error")
+ .expect("the member access must be present")
+ + 1;
+ let markdown = hover_markdown(&resolved, LOGGER_SOURCE, offset);
+
+ assert!(
+ !markdown.as_deref().is_some_and(|md| md.contains("OSError")),
+ "hovering `logger.error` must not answer with `os.error`: {markdown:?}"
+ );
+}
+
+/// [TYPESHEDRT-ACCEPTANCE-HOVER]: the receiver of a member access is typed
+/// from the declaration that produced it — `logging.getLogger(...)` returns
+/// `Logger` — so the hover shows `Logger.error`'s real typeshed signature,
+/// labelled as a method and attributed to the active snapshot.
+#[test]
+fn hover_on_member_of_call_typed_receiver_shows_declaring_class_signature() {
+ let resolved = resolve_against_bundled_typeshed(LOGGER_SOURCE);
+ let offset = LOGGER_SOURCE
+ .rfind("error")
+ .expect("the member access must be present")
+ + 1;
+ let markdown = hover_markdown(&resolved, LOGGER_SOURCE, offset)
+ .expect("a member of a typed receiver must have hover");
+
+ assert!(
+ markdown.contains("Logger.error"),
+ "hover must qualify the member with the class that declares it: {markdown}"
+ );
+ assert!(
+ markdown.contains("(method)"),
+ "hover must say the symbol is a method: {markdown}"
+ );
+ assert!(
+ markdown.contains("msg"),
+ "hover must show the member's real parameters: {markdown}"
+ );
+ assert!(
+ markdown.contains("(typeshed)"),
+ "hover must attribute the declaration to the active snapshot: {markdown}"
+ );
+}
+
+/// [LSPARCH-FEATURES-HOVER]: an imported symbol carries the same kind label a
+/// local one does. `ExternalSymbol::kind` is known at hover time and was only
+/// ever consulted to branch on classes, so imported functions rendered as a
+/// bare signature with nothing saying what they are.
+#[test]
+fn hover_on_imported_stub_function_states_its_kind_and_origin() {
+ let source = "from logging import getLogger\n\nlog = getLogger(__name__)\n";
+ let resolved = resolve_against_bundled_typeshed(source);
+ let offset = source
+ .rfind("getLogger")
+ .expect("the usage must be present")
+ + 1;
+ let markdown =
+ hover_markdown(&resolved, source, offset).expect("an imported symbol must have hover");
+
+ assert!(
+ markdown.contains("(function)"),
+ "an imported function must be labelled like a local one: {markdown}"
+ );
+ assert!(
+ markdown.contains("def getLogger("),
+ "the stub signature must still be shown: {markdown}"
+ );
+ assert!(
+ markdown.contains("logging"),
+ "hover must name the module the symbol came from: {markdown}"
+ );
+}
diff --git a/crates/basilisk-lsp/tests/lsp/ws_test_capabilities.rs b/crates/basilisk-lsp/tests/lsp/ws_test_capabilities.rs
index ee096740..b8662143 100644
--- a/crates/basilisk-lsp/tests/lsp/ws_test_capabilities.rs
+++ b/crates/basilisk-lsp/tests/lsp/ws_test_capabilities.rs
@@ -171,14 +171,20 @@ async fn test_ws_initialize_advertises_typeshed_status() -> TestResult<()> {
.get("status")
.ok_or("missing typed Typeshed state in initialize response")?;
+ // [LSPCFGED-TYPESHED]: resolution is a local read completed during
+ // `initialize`, so the payload carries the TERMINAL generation — there is
+ // no acquiring state for any client to render as a blocking overlay.
assert_eq!(
status
.pointer("/lifecycle/kind")
.and_then(serde_json::Value::as_str),
- Some("Acquiring"),
- "initialize must expose the pre-analysis Acquiring generation: {status}"
+ Some("Ready"),
+ "initialize must expose the terminal resolved generation: {status}"
+ );
+ assert!(
+ status.get("activeSource").is_some(),
+ "a Ready status names its active source: {status}"
);
- assert!(status.get("activeSource").is_none());
assert!(status
.get("warnings")
.is_some_and(serde_json::Value::is_array));
diff --git a/crates/basilisk-lsp/tests/lsp/ws_test_common.rs b/crates/basilisk-lsp/tests/lsp/ws_test_common.rs
index 7079bcd7..17b29db4 100644
--- a/crates/basilisk-lsp/tests/lsp/ws_test_common.rs
+++ b/crates/basilisk-lsp/tests/lsp/ws_test_common.rs
@@ -153,6 +153,19 @@ python-version = \"3.12\"\n\
let response = self.recv().await.ok_or("no response to initialize")?;
+ // Typeshed resolution is a local read completed during `initialize`
+ // ([STUBRES-TYPESHED-OFFLINE]): the response payload itself carries
+ // each root's terminal status, so there is no startup notification to
+ // await — and nothing intermediate a client could ever render.
+ if !response.contains("typeshedStatuses")
+ || !response.contains("\"lifecycle\":{\"kind\":\"Ready\"}")
+ {
+ return Err(format!(
+ "initialize payload must carry a terminal Ready Typeshed status: {response}"
+ )
+ .into());
+ }
+
self.send_json(&serde_json::json!({
"jsonrpc": "2.0",
"method": "initialized",
@@ -160,21 +173,7 @@ python-version = \"3.12\"\n\
}))
.await?;
- // `initialized` acquires and gates Typeshed before analysis. Await the
- // typed Ready notification so subsequent document opens can never
- // observe the deliberately empty blocked-root publication.
- for _ in 0..20 {
- let message = self
- .recv()
- .await
- .ok_or("no terminal Typeshed status after initialized")?;
- if message.contains("\"method\":\"basilisk/typeshedStatusChanged\"")
- && message.contains("\"lifecycle\":{\"kind\":\"Ready\"}")
- {
- return Ok(response);
- }
- }
- Err("Typeshed did not become ready during initialization".into())
+ Ok(response)
}
/// Send `textDocument/didOpen`.
diff --git a/crates/basilisk-lsp/tests/lsp/ws_test_execute_stubs.rs b/crates/basilisk-lsp/tests/lsp/ws_test_execute_stubs.rs
index 295f2604..f788bf98 100644
--- a/crates/basilisk-lsp/tests/lsp/ws_test_execute_stubs.rs
+++ b/crates/basilisk-lsp/tests/lsp/ws_test_execute_stubs.rs
@@ -1,4 +1,4 @@
-//! Tests for [STUBRES-CREATE-LOCAL]. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#stubres-create-local
+//! Tests for [STUBRES-CREATE-LOCAL]. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-CREATE-LOCAL
// E2E test for the `basilisk.stubs.createLocal` quick fix (BSK-0152).
//
// Drives the full pipeline through `workspace/executeCommand`:
diff --git a/crates/basilisk-lsp/tests/profiler_tests.rs b/crates/basilisk-lsp/tests/profiler_tests.rs
index e9a629fe..48d47505 100644
--- a/crates/basilisk-lsp/tests/profiler_tests.rs
+++ b/crates/basilisk-lsp/tests/profiler_tests.rs
@@ -267,6 +267,95 @@ fn scaffolding_frames_are_stripped_from_every_surface() {
assert_eq!(hot.self_samples, 1, "the user leaf keeps its self sample");
}
+/// A debugpy housekeeping thread, leaf-first: debugpy's own code sitting on
+/// the stdlib `threading.py` bootstrap spine that started it. Nothing here is
+/// the user's.
+fn debugger_housekeeping_thread_stack() -> Vec<(&'static str, &'static str, i32)> {
+ vec![
+ ("_on_run", "/site-packages/debugpy/adapter/servers.py", 191),
+ ("run", "/usr/lib/python3.14/threading.py", 1012),
+ ("_bootstrap_inner", "/usr/lib/python3.14/threading.py", 1075),
+ ("_bootstrap", "/usr/lib/python3.14/threading.py", 1032),
+ ]
+}
+
+/// The user's OWN worker thread, leaf-first: real user code on top of the same
+/// stdlib bootstrap spine.
+fn user_worker_thread_stack() -> Vec<(&'static str, &'static str, i32)> {
+ vec![
+ ("crunch", "/home/user/proj/cpu_hotspot.py", 52),
+ ("worker", "/home/user/proj/cpu_hotspot.py", 60),
+ ("run", "/usr/lib/python3.14/threading.py", 1012),
+ ("_bootstrap_inner", "/usr/lib/python3.14/threading.py", 1075),
+ ("_bootstrap", "/usr/lib/python3.14/threading.py", 1032),
+ ]
+}
+
+// Exercises [PROFILE-AGGREGATION-SCAFFOLD]. The spec requires that "a
+// machinery-only thread (debugger housekeeping, the injected sampler) is
+// dropped entirely". A debugpy housekeeping thread is started by the stdlib,
+// so once its debugpy frames are stripped what remains is the `threading.py`
+// bootstrap spine — non-empty, so the thread survived and surfaced as a
+// top-level row in the .cpuprofile flame chart, which is exactly the launcher
+// scaffolding this section exists to remove.
+#[test]
+fn a_debugger_housekeeping_thread_is_dropped_entirely() {
+ let mut data = ProfileData::default();
+ data.ingest_traces(
+ &[make_trace(7, true, debugger_housekeeping_thread_stack())],
+ 0.01,
+ false,
+ );
+
+ assert!(
+ !data.thread_stacks.contains_key(&7),
+ "a thread whose only surviving frames are the stdlib bootstrap spine \
+ is pure machinery and must not register, got: {:?}",
+ data.thread_stacks.get(&7)
+ );
+ assert!(
+ data.frames.is_empty(),
+ "no machinery frame may reach the export, got: {:?}",
+ data.frames
+ );
+}
+
+// Exercises [PROFILE-AGGREGATION-SCAFFOLD] — the other half of the contract:
+// dropping bootstrap frames must NOT drop the user's own worker threads. The
+// spine is stripped so the thread roots at the user's code, and the user's
+// frames and attribution survive intact.
+#[test]
+fn a_user_worker_thread_survives_and_roots_at_user_code() {
+ let mut data = ProfileData::default();
+ data.ingest_traces(
+ &[make_trace(9, true, user_worker_thread_stack())],
+ 0.01,
+ false,
+ );
+
+ let stacks = data
+ .thread_stacks
+ .get(&9)
+ .expect("the user's worker thread must be retained");
+ let root_frame = &data.frames[stacks[0][0]];
+ assert_eq!(
+ root_frame.file, "/home/user/proj/cpu_hotspot.py",
+ "the worker thread must root at the user's file, not the bootstrap spine"
+ );
+ assert_eq!(
+ root_frame.name, "worker",
+ "the worker thread must root at the user's own entry function"
+ );
+ assert_eq!(stacks[0].len(), 2, "only the two user frames survive");
+
+ let hot = data
+ .function_stats
+ .get("/home/user/proj/cpu_hotspot.py")
+ .and_then(|by_fn| by_fn.get("crunch"))
+ .expect("crunch must keep its stats");
+ assert_eq!(hot.self_samples, 1, "the user leaf keeps its self sample");
+}
+
#[test]
fn leaf_tracer_frames_attribute_to_the_traced_user_line() {
// Under debugpy line-tracing, pydevd's trace_dispatch can own the leaf;
diff --git a/crates/basilisk-lsp/tests/typeshed_declaration_consumers_tests.rs b/crates/basilisk-lsp/tests/typeshed_declaration_consumers_tests.rs
index 277b1a98..55673662 100644
--- a/crates/basilisk-lsp/tests/typeshed_declaration_consumers_tests.rs
+++ b/crates/basilisk-lsp/tests/typeshed_declaration_consumers_tests.rs
@@ -145,13 +145,9 @@ fn custom_builtins_mutation_replaces_every_consumer_without_bundle_mixing() {
selection: basilisk_stubs::typeshed::source::SourceSelection::Custom {
path: root.path().to_string_lossy().into_owned(),
},
- verify_content: true,
- use_cache: false,
- url_template: None,
+ store_path: None,
};
- let manager = basilisk_stubs::typeshed::runtime::production_manager(request, None);
- assert!(manager.is_ok(), "custom manager must initialize");
- let Ok(manager) = manager else { return };
+ let manager = basilisk_stubs::typeshed::runtime::production_manager(request);
let snapshot = manager.snapshot();
assert!(
snapshot.is_ok(),
diff --git a/crates/basilisk-mojo/README.md b/crates/basilisk-mojo/README.md
index 503e28c5..82900d31 100644
--- a/crates/basilisk-mojo/README.md
+++ b/crates/basilisk-mojo/README.md
@@ -4,26 +4,73 @@ Mojo-inspired ownership and immutability analysis for Basilisk.
## Role in Basilisk
-This crate implements **static ownership semantics** as type annotations over standard Python syntax. Using `Annotated` from the `typing` module, developers can declare ownership contracts that Basilisk enforces at analysis time — catching mutation of borrowed values and use-after-move before they reach production.
+This crate is **scaffolding** for static ownership semantics expressed as type
+annotations over standard Python syntax. The design goal is to let developers
+declare ownership contracts — catching mutation of borrowed values and
+use-after-move — using only `typing` constructs, with no compiler or runtime
+support required.
-## Key concepts
+Per [CHKARCH-MOJO-SAFETY](../../docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-MOJO-SAFETY),
+this analysis is "planned, opt-in, and not wired into the checker pipeline".
+Nothing here enforces anything today: the crate's only public entry point,
+`check_ownership`, has no caller outside `tests/mojo_tests.rs`.
-- **`Borrowed`** — a read-only reference. Mutation is a type error.
-- **`InOut`** — a mutable reference. Must be explicitly declared.
-- **`Owned`** — ownership is transferred. Use after transfer is a type error.
-- **Standard Python syntax** — uses `typing.Annotated`, no compiler or runtime required.
+## Key concepts (design vocabulary)
+
+- **`Borrowed`** — a read-only reference; mutation is intended to be an error.
+- **`InOut`** — a mutable reference, explicitly declared.
+- **`Owned`** — ownership is transferred; use after transfer is intended to be an error.
+- **Standard Python syntax** — the target form is `Annotated[T, Borrowed|InOut|Owned]`
+ ([CHKARCH-MOJO-OWNERSHIP](../../docs/specs/CHECKER-ARCHITECTURE-SPEC.md#CHKARCH-MOJO-OWNERSHIP)),
+ so no compiler or runtime is required.
+
+Of these, only `Borrowed` is recognised by the current prototype, and only in
+the bare subscript/name form shown below — not yet in the `Annotated[...]` form
+that the spec targets.
+
+## What the prototype actually detects
+
+`check_ownership(source: &str) -> Vec` is a line-oriented text scan, not
+an AST pass (`src/lib.rs`):
+
+1. For each line starting with `def `, it splits the parenthesised parameter list
+ on `,` and collects the names of parameters whose annotation either starts
+ with `Borrowed[` or is exactly `Borrowed`.
+2. It then flags any line containing `.(` for `` in
+ `MUTATING_METHODS` (`append`, `extend`, `insert`, `remove`, `pop`, `clear`,
+ `sort`, `reverse`, `update`, `add`, `discard`).
+
+Because step 1 splits on `,`, an annotation written as
+`Annotated[list[int], Borrowed]` is broken into two fragments and matches
+neither accepted shape, so it is **not** detected.
## Example
```python
-from typing import Annotated
-from basilisk import Borrowed
-
-def summarise(items: Annotated[list[int], Borrowed]) -> int:
- items.append(99) # generics_defaults: mutation of Borrowed parameter
+def summarise(items: Borrowed[list[int]]) -> int:
+ items.append(99) # detected: mutation of a Borrowed parameter
return sum(items)
```
+`check_ownership` returns strings, not structured diagnostics. For the source
+above it yields:
+
+```
+directives_cast: mutation of Borrowed parameter `items` via `.append()` is not allowed
+```
+
+**Known defect:** that `directives_cast:` prefix is not a diagnostic code for
+this crate. `directives_cast` is a real, registered, shipping PEP rule meaning
+"Invalid `cast()` call" (`crates/basilisk-checker/src/rules/directives_cast.rs`,
+documented at ).
+Reusing it here contradicts [CHKARCH-MOJO-SAFETY], which states that shipping
+PEP rules and this scaffolding "must not reuse these anchors or diagnostic
+descriptions". The string is hard-coded in `src/lib.rs` and needs its own code
+before any of this is wired up.
+
## Status
-Phase 4 — ownership annotations designed, implementation in progress.
+Planned. The crate is scaffolding targeted at Phase 4 (`src/lib.rs`); it is not
+registered with the checker and produces no user-visible diagnostics. Remaining
+work is tracked as unchecked TODOs under
+[CHKADVPLAN-TODO-MOJO](../../docs/plans/CHECKER-ADVANCED-FEATURES-PLAN.md#CHKADVPLAN-TODO-MOJO).
diff --git a/crates/basilisk-resolver/src/scope/external_symbol.rs b/crates/basilisk-resolver/src/scope/external_symbol.rs
index a7db3450..0932f8c0 100644
--- a/crates/basilisk-resolver/src/scope/external_symbol.rs
+++ b/crates/basilisk-resolver/src/scope/external_symbol.rs
@@ -36,6 +36,13 @@ pub struct ExternalMethod {
pub name: String,
/// The rendered `def` signature for hover display.
pub signature: String,
+ /// The method's docstring, when the defining module has one.
+ ///
+ /// `.pyi` stubs (typeshed included) carry no docstrings, so this is `None`
+ /// for them; workspace and PEP 561 `py.typed` sources do carry them, and
+ /// hover shows the prose it finds rather than dropping it
+ /// ([LSPARCH-FEATURES-HOVER]).
+ pub docstring: Option,
}
/// One class declaration indexed from the active standard-library snapshot.
@@ -76,6 +83,13 @@ pub struct ExternalSymbol {
pub source_span: Span,
/// The full function/class signature for hover display.
pub signature: Option,
+ /// The symbol's docstring, when the defining module has one.
+ ///
+ /// `.pyi` stubs (typeshed included) carry no docstrings, so this is `None`
+ /// for them; workspace and PEP 561 `py.typed` sources do carry them, and
+ /// hover shows the prose it finds rather than dropping it
+ /// ([LSPARCH-FEATURES-HOVER]).
+ pub docstring: Option,
/// Where this symbol's type information came from.
///
/// Set during cross-module resolution based on how the import was resolved.
diff --git a/crates/basilisk-stubs/Cargo.toml b/crates/basilisk-stubs/Cargo.toml
index 38a87ccc..7766eeff 100644
--- a/crates/basilisk-stubs/Cargo.toml
+++ b/crates/basilisk-stubs/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "basilisk-stubs"
-description = "Runtime python/typeshed archive acquisition, cache, and bundled snapshot for Basilisk"
+description = "Offline python/typeshed source resolution (bundle, store, custom) for Basilisk"
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -17,21 +17,21 @@ ruff_python_ast.workspace = true
ruff_text_size.workspace = true
serde.workspace = true
serde_json.workspace = true
-# Content attestation for the typeshed acquisition core ([STUBRES-TYPESHED-ACQUIRE]):
-# `sha1` reconstructs Git blob/tree object IDs to bind analysed bytes to the
-# trusted root-tree SHA; `sha2` fingerprints the cached immutable ZIP. Both are
-# pure-Rust RustCrypto crates with no system dependencies (no Dockerfile/CI change).
+# Offline pin verification ([STUBRES-TYPESHED-PIN]): `sha1` reconstructs Git
+# commit/blob/tree object IDs to bind analysed bytes to the pinned commit SHA;
+# `sha2` fingerprints the embedded bundle and legal files. Both are pure-Rust
+# RustCrypto crates with no system dependencies (no Dockerfile/CI change).
sha1 = "0.10"
sha2 = "0.10"
-# Decode the bundled stdlib ZIP and the downloaded GitHub zipball into the
-# in-memory archive model ([STUBRES-TYPESHED-ACQUIRE]). Deflate read only — no
-# bzip2/zstd/aes surface, and never a `git` transport.
+# Decode the bundled stdlib ZIP into the in-memory archive model
+# ([STUBRES-TYPESHED-BASELINE]). Deflate read only — no bzip2/zstd/aes surface.
zip = { version = "5.1.1", default-features = false, features = ["deflate"] }
thiserror.workspace = true
tracing.workspace = true
-# Production authenticated-HTTPS adapter for GitHub metadata/codeload and
-# configured archive mirrors. `https_only` is also enforced by the adapter.
-ureq = { version = "3.3.0", default-features = false, features = ["rustls"] }
+# NO HTTP client may ever appear here: the checker links this crate, and "the
+# checker never downloads" is a property of the build ([TYPESHEDRT-SEGREGATION],
+# enforced by scripts/check-dependency-shape.sh). Downloading lives in
+# `basilisk-typeshed-fetch`.
[dev-dependencies]
serde_json.workspace = true
diff --git a/crates/basilisk-stubs/README.md b/crates/basilisk-stubs/README.md
index 71729fd8..0df9af88 100644
--- a/crates/basilisk-stubs/README.md
+++ b/crates/basilisk-stubs/README.md
@@ -1,38 +1,40 @@
# basilisk-stubs
-Standard-library type resolution for Basilisk: a custom or downloaded
-`python/typeshed` tree, with a bundled full-`stdlib/` ZIP snapshot as the offline
-floor.
+Standard-library type resolution for Basilisk: a custom `python/typeshed`
+tree, or a pinned commit verified offline against the on-disk store, with a
+bundled full-`stdlib/` ZIP snapshot as the default pin.
## Role in Basilisk
This crate supplies step 3—"Typeshed stubs for the standard library"—of the
pinned typing resolution order
([`python/typing@6ef9f77`](https://github.com/python/typing/blob/6ef9f7719ecfff09dad8724ef42b621fd994fb5e/docs/spec/distributing.rst)).
-It returns a `StubResolution` with source and trust provenance; the normative
-selection contract is
+It returns a `StubResolution` whose active source IS the trust story; the
+normative selection contract is
[STUBRES-TYPESHED](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED).
## Key concepts
-- **Runtime typeshed acquisition** — an explicit `typeshed-commit` or the latest
- verified `main` supplies real `.pyi` bodies, `stdlib/VERSIONS`, and the
- distribution map from one SHA. The source archive is **downloaded over HTTPS
- (never `git clone`)**, streamed through safety/shape/license/tree gates, cached
- as an immutable ZIP that is re-hashed on every reuse, and read through the same
- archive VFS. Cached bytes standing in for the moving `main` reference expire
- after 24 hours; bytes for an explicitly pinned commit do not, because that
- commit is content-addressed and every reuse re-hashes the ZIP against its
- recorded SHA-256. An unpinned failed acquisition falls back to the bundled
- snapshot and never reuses an older commit
- ([STUBRES-TYPESHED-ACQUIRE](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-ACQUIRE)).
+- **Offline pin verification** — an explicit `typeshed-commit` (or the bundled
+ commit when unset) supplies real `.pyi` bodies, `stdlib/VERSIONS`, and the
+ distribution map from one SHA. Resolution **never downloads**: it re-hashes
+ the store entry's materialized tree against the pin's commit object, offline,
+ on every activation. A pin that is not on this machine is a terminal
+ `NO SOURCE` failure naming `basilisk typeshed download` — never a fallback
+ ([STUBRES-TYPESHED-OFFLINE](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-OFFLINE),
+ [STUBRES-TYPESHED-PIN](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-PIN)).
+ Downloading lives solely in `basilisk-typeshed-fetch`, behind explicit user
+ actions, and writes immutable entries into the content-addressed store this
+ crate reads
+ ([STUBRES-TYPESHED-STORE](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-STORE),
+ [STUBRES-TYPESHED-DOWNLOAD](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-DOWNLOAD)).
- **Bundled ZIP snapshot** — a complete typeshed `stdlib/` tree with **real
`.pyi` bodies** plus its composite `LICENSE`, pinned to one SHA and refreshed
per release. It is the offline floor, so #288/#289 hovers work with no network
([STUBRES-TYPESHED-BASELINE](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-BASELINE),
[STUBRES-TYPESHED-WARN](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-WARN)).
-- **No mixed source** — custom or downloaded content wholly bypasses the bundled
- snapshot.
+- **No mixed source** — custom or store-backed pinned content wholly bypasses
+ the bundled snapshot.
- **Custom typeshed** — `typeshed-path` is the sole step-3 source when set, as
Basilisk's implementation of the pinned "canonical source" SHOULD; a miss proceeds to step 4
([STUBRES-CUSTOM-TYPESHED](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-CUSTOM-TYPESHED)).
@@ -50,10 +52,10 @@ selection contract is
## Status
-The `typeshed-path` custom-tree override, runtime `python/typeshed` archive
-acquisition, and bundled full-`stdlib/` ZIP snapshot all produce the sole active
-step-3 snapshot consumed by `basilisk-checker`. Its real `.pyi` bodies and
-derived indexes remain one indivisible source, as defined by
+The `typeshed-path` custom-tree override, the offline store-backed pin, and
+the bundled full-`stdlib/` ZIP snapshot all produce the sole active step-3
+snapshot consumed by `basilisk-checker`. Its real `.pyi` bodies and derived
+indexes remain one indivisible source, as defined by
[STUBRES-TYPESHED](../../docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED);
-the HTTPS archive download (never `git clone`), tree-SHA verification, and
-source reporting are tracked against that spec.
+offline commit-object re-hashing, store immutability, and source reporting are
+tracked against that spec.
diff --git a/crates/basilisk-stubs/src/typeshed/archive.rs b/crates/basilisk-stubs/src/typeshed/archive.rs
index 25cc1768..1322c4e3 100644
--- a/crates/basilisk-stubs/src/typeshed/archive.rs
+++ b/crates/basilisk-stubs/src/typeshed/archive.rs
@@ -1,4 +1,4 @@
-//! Implements [STUBRES-TYPESHED-ACQUIRE] archive model + VFS. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-ACQUIRE
+//! Implements [STUBRES-TYPESHED] archive model + VFS. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED
//!
//! In-memory archive model and archive VFS.
//!
@@ -11,7 +11,7 @@
//! [`ArchiveVfs`] is the read side the resolver consumes. It returns a **stable
//! logical URI** plus bytes for `parse_pyi_source` ([STUBRES-PYI]) — there is no
//! temp extraction and no real filesystem path, so a cached immutable ZIP is
-//! never trusted through a mutable extracted tree ([STUBRES-TYPESHED-ACQUIRE]).
+//! never trusted through a mutable extracted tree ([STUBRES-TYPESHED-PIN]).
use std::collections::HashMap;
use std::sync::Arc;
diff --git a/crates/basilisk-stubs/src/typeshed/bundle.rs b/crates/basilisk-stubs/src/typeshed/bundle.rs
index edacd2ea..d7a7c134 100644
--- a/crates/basilisk-stubs/src/typeshed/bundle.rs
+++ b/crates/basilisk-stubs/src/typeshed/bundle.rs
@@ -6,9 +6,10 @@
//! and the composite `LICENSE`) is embedded with `include_bytes!`. Because the
//! bundle is a **stdlib subset**, it cannot reconstruct the full-repository Git
//! root tree, so it is verified by its **embedded ZIP SHA-256 plus the license
-//! manifest**, never by tree reconstruction ([STUBRES-TYPESHED-BASELINE]). Its
-//! provenance is [`Provenance::BundleVetted`], and it always reports `UNPINNED`
-//! (a build-time pin is not a user pin) until the user pins that commit.
+//! manifest**, never by tree reconstruction ([STUBRES-TYPESHED-BASELINE]). It
+//! is the data an unset `typeshed-commit` resolves to; the selector reports
+//! that default `UNPINNED` (a build-time pin is not a user pin) and an explicit
+//! pin of the same commit as pinned ([STUBRES-TYPESHED-WARN]).
use std::sync::OnceLock;
@@ -23,10 +24,7 @@ use super::gate::{
};
use super::gittree::{Oid, OidParseError};
use super::snapshot::{Snapshot, SnapshotError};
-use super::source::{
- LicenseStatus, Provenance, SourceIdentity, SourceKind, StatusWarning, Transport, TypeshedStatus,
-};
-use super::warning::{TypeshedWarning, UnpinnedKind};
+use super::source::{LicenseStatus, SourceIdentity, SourceKind, TypeshedStatus};
/// The embedded bundle ZIP.
static BUNDLE_ZIP: &[u8] = include_bytes!(concat!(
@@ -176,17 +174,15 @@ fn build_bundled_snapshot() -> Result {
let commit = Oid::from_hex(&manifest.source.commit_sha).map_err(BundleError::BadSha)?;
let tree = Oid::from_hex(&manifest.source.tree_sha).map_err(BundleError::BadSha)?;
let identity = SourceIdentity::Bundled { commit };
+ // Warnings are set by the selector, which knows whether an explicit pin
+ // selected this bundle (suppressing UNPINNED) or the default did not.
let status = TypeshedStatus {
active_source: SourceKind::Bundled,
commit: Some(commit),
tree: Some(tree),
- transport: Transport::EmbeddedZip,
license_status: LicenseStatus::Approved,
license_reference: Some(license_reference(&manifest.source.commit_sha)),
- provenance: Provenance::BundleVetted,
- signed_release: false,
- // A build-time pin is not a user pin ([STUBRES-TYPESHED-WARN]).
- warnings: StatusWarning::list(&[TypeshedWarning::Unpinned(UnpinnedKind::LatestOrBundled)]),
+ warnings: Vec::new(),
};
let vfs = ArchiveVfs::new(identity.uri_component(), archive);
Snapshot::build(identity, status, vfs, Some(BUNDLE_DISTRIBUTIONS_TSV))
@@ -244,14 +240,14 @@ mod tests {
};
// Identity + status honesty.
assert_eq!(snapshot.status.active_source, SourceKind::Bundled);
- assert_eq!(snapshot.status.provenance, Provenance::BundleVetted);
assert_eq!(snapshot.status.license_status, LicenseStatus::Approved);
- // Build-time pin is not a user pin: still UNPINNED.
- assert!(snapshot
- .status
- .warnings
- .iter()
- .any(|warning| warning.code == "UNPINNED"));
+ // Warnings belong to the selector, which knows whether an explicit pin
+ // chose this bundle; the raw bundle carries none of its own.
+ assert!(snapshot.status.warnings.is_empty());
+ assert_eq!(
+ snapshot.status.commit.map(|oid| oid.to_hex()).as_deref(),
+ Some(bundled_commit_sha())
+ );
}
#[test]
diff --git a/crates/basilisk-stubs/src/typeshed/cache.rs b/crates/basilisk-stubs/src/typeshed/cache.rs
deleted file mode 100644
index 0e72cc84..00000000
--- a/crates/basilisk-stubs/src/typeshed/cache.rs
+++ /dev/null
@@ -1,682 +0,0 @@
-//! Implements [STUBRES-TYPESHED-ACQUIRE] cache. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-ACQUIRE
-//!
-//! The on-disk immutable-ZIP cache.
-//!
-//! A verified download is cached as the **immutable ZIP** it was accepted as,
-//! beside a small metadata record. Reuse **re-hashes the cached ZIP** and
-//! compares it to the recorded SHA-256, so on-disk mutation is detected without
-//! extraction — the checker never trusts a mutable extracted tree
-//! ([STUBRES-TYPESHED-ACQUIRE]). Bytes standing in for the *moving* `main`
-//! reference expire after 24 hours; bytes for an explicitly pinned exact commit
-//! do not, because that commit is content-addressed and re-hashed on every
-//! reuse. See [`DiskCache::load_fresh`] and [`DiskCache::load_pinned`].
-
-use std::fs::{self, File};
-use std::io::Write as _;
-use std::path::{Path, PathBuf};
-use std::sync::atomic::{AtomicU64, Ordering};
-
-use serde::{Deserialize, Serialize};
-
-use super::gate::manifest::sha256_hex;
-
-static STAGING_SEQUENCE: AtomicU64 = AtomicU64::new(0);
-
-/// Maximum age of cached ZIP bytes reused for a **moving** reference. Commit
-/// selection is independent: an explicit pin remains the same identity when its
-/// bytes must be reacquired, and is exempt from this window entirely
-/// ([`DiskCache::load_pinned`]).
-pub const CACHE_MAX_AGE_SECONDS: u64 = 24 * 60 * 60;
-
-/// A cache key derived from a source identity's opaque URI component.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CacheKey(String);
-
-impl CacheKey {
- /// Build a key from a source identity's URI component (a SHA or path digest).
- #[must_use]
- pub fn from_identity(uri_component: &str) -> Self {
- // The component is already a SHA or digest; keep only path-safe chars.
- let safe: String = uri_component
- .chars()
- .map(|ch| {
- if ch.is_ascii_alphanumeric() || ch == '-' {
- ch
- } else {
- '_'
- }
- })
- .collect();
- Self(safe)
- }
-
- /// The on-disk subdirectory name.
- #[must_use]
- pub fn dir_name(&self) -> &str {
- &self.0
- }
-}
-
-/// The metadata stored beside a cached ZIP.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct CacheRecord {
- /// The commit SHA, when known.
- pub commit: Option,
- /// The verified root-tree SHA, when content was attested.
- pub tree: Option,
- /// SHA-256 of the cached ZIP bytes — the mutation check on every reuse.
- pub zip_sha256: String,
- /// Whether content verification ran when the entry was stored.
- pub verified: bool,
- /// Actual archive byte origin (`codeload` or `mirror`). This is persisted
- /// so reuse cannot be relabelled by a later configuration change.
- #[serde(default)]
- pub transport: Option,
- /// Unix timestamp when these downloaded bytes passed the activation gates.
- /// Legacy records default to zero and are therefore never reused.
- #[serde(default)]
- pub acquired_at_unix_seconds: u64,
- /// Trusted recursive Git file metadata retained so offline cache reuse can
- /// restore modes that codeload ZIPs do not preserve.
- #[serde(default)]
- pub tree_files: Vec,
-}
-
-/// One persisted trusted recursive-tree leaf.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct CachedTreeFile {
- /// Repository-relative path.
- pub path: String,
- /// Full Git blob object ID.
- pub oid: String,
- /// Canonical Git leaf mode (`100644`, `100755`, `120000`, or `160000`).
- pub mode: String,
-}
-
-/// A cached ZIP plus its metadata.
-#[derive(Debug, Clone)]
-pub struct CachedArchive {
- /// The immutable ZIP bytes.
- pub zip: Vec,
- /// Its metadata record.
- pub record: CacheRecord,
-}
-
-/// A cache operation failure.
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
-pub enum CacheError {
- /// A filesystem error.
- #[error("cache io error: {0}")]
- Io(String),
- /// The metadata record could not be (de)serialized.
- #[error("cache metadata error: {0}")]
- Metadata(String),
- /// The cached ZIP's hash did not match its record — on-disk mutation.
- #[error("cached archive mutated: recorded {expected}, found {actual}")]
- Mutation {
- /// The recorded SHA-256.
- expected: String,
- /// The freshly computed SHA-256.
- actual: String,
- },
-}
-
-/// The on-disk immutable-ZIP cache rooted at a directory.
-#[derive(Debug, Clone)]
-pub struct DiskCache {
- root: PathBuf,
-}
-
-impl DiskCache {
- /// Root the cache at `root`.
- #[must_use]
- pub fn new(root: impl Into) -> Self {
- Self { root: root.into() }
- }
-
- fn entry_dir(&self, key: &CacheKey) -> PathBuf {
- self.root.join(key.dir_name())
- }
-
- /// Store `zip` and `record` atomically under `key`. The record's
- /// `zip_sha256` MUST already match `zip`; callers set it from the same bytes.
- ///
- /// # Errors
- ///
- /// Returns [`CacheError`] on I/O or serialization failure.
- pub fn store(
- &self,
- key: &CacheKey,
- zip: &[u8],
- record: &CacheRecord,
- ) -> Result<(), CacheError> {
- let dir = self.entry_dir(key);
- let generations = dir.join("generations");
- fs::create_dir_all(&generations).map_err(|err| CacheError::Io(err.to_string()))?;
- let actual = sha256_hex(zip);
- if actual != record.zip_sha256 {
- return Err(CacheError::Mutation {
- expected: record.zip_sha256.clone(),
- actual,
- });
- }
- let meta = serde_json::to_vec_pretty(record)
- .map_err(|err| CacheError::Metadata(err.to_string()))?;
- let generation = generations.join(&record.zip_sha256);
- if generation.is_dir() {
- if stored_generation_matches(&generation, record) {
- return Ok(());
- }
- quarantine_generation(&generations, &generation)?;
- }
- let sequence = STAGING_SEQUENCE.fetch_add(1, Ordering::Relaxed);
- let staging = generations.join(format!(".stage-{}-{sequence}", std::process::id()));
- fs::create_dir(&staging).map_err(|err| CacheError::Io(err.to_string()))?;
- let staged = stage_generation(&staging, zip, &meta);
- if let Err(error) = staged {
- let _ = fs::remove_dir_all(&staging);
- return Err(error);
- }
- match fs::rename(&staging, &generation) {
- Ok(()) => sync_dir(&generations),
- Err(_error) if generation.is_dir() => {
- let _ = fs::remove_dir_all(&staging);
- Ok(())
- }
- Err(error) => {
- let _ = fs::remove_dir_all(&staging);
- Err(CacheError::Io(error.to_string()))
- }
- }
- }
-
- /// Load the freshest cached encoding for `key`, re-hashing every ZIP before
- /// reuse. Multiple encodings can exist for one immutable commit.
- ///
- /// Returns `Ok(None)` when the entry is absent.
- ///
- /// # Errors
- ///
- /// Returns [`CacheError::Mutation`] if the stored ZIP no longer matches its
- /// recorded hash, or an I/O/metadata error otherwise.
- pub fn load_fresh(
- &self,
- key: &CacheKey,
- now_unix_seconds: u64,
- ) -> Result, CacheError> {
- self.load_accepted(key, |record| record_is_fresh(record, now_unix_seconds))
- }
-
- /// Load the newest cached encoding for an **explicitly pinned** commit,
- /// ignoring [`CACHE_MAX_AGE_SECONDS`].
- ///
- /// The age window bounds how long bytes for a *moving* reference may stand
- /// in for it: `main` advances, so yesterday's archive would misrepresent
- /// "latest". A pinned commit has no such failure mode. It is
- /// content-addressed, so its archive can never change meaning, and every
- /// generation is re-hashed against its recorded `zip_sha256` on load
- /// regardless of age. Expiring one therefore buys no integrity — it only
- /// forces a network round-trip that stops a pinned, reproducible project
- /// from typechecking offline or while GitHub is rate-limiting
- /// ([STUBRES-TYPESHED-CONFIG]).
- ///
- /// Returns `Ok(None)` when the entry is absent.
- ///
- /// # Errors
- ///
- /// Returns [`CacheError::Mutation`] if the stored ZIP no longer matches its
- /// recorded hash, or an I/O/metadata error otherwise.
- pub fn load_pinned(&self, key: &CacheKey) -> Result, CacheError> {
- self.load_accepted(key, |_record| true)
- }
-
- fn load_accepted(
- &self,
- key: &CacheKey,
- accept: impl Fn(&CacheRecord) -> bool,
- ) -> Result, CacheError> {
- let dir = self.entry_dir(key);
- let generations = dir.join("generations");
- if !generations.is_dir() {
- return Ok(None);
- }
- let mut promoted = fs::read_dir(&generations)
- .map_err(|err| CacheError::Io(err.to_string()))?
- .collect::, _>>()
- .map_err(|err| CacheError::Io(err.to_string()))?;
- promoted.retain(|entry| {
- entry.file_type().is_ok_and(|kind| kind.is_dir())
- && !entry.file_name().to_string_lossy().starts_with('.')
- });
- let mut freshest: Option = None;
- for entry in promoted {
- let candidate = load_generation(&generations, &entry.path())?;
- if !accept(&candidate.record) {
- continue;
- }
- let replace = match &freshest {
- None => true,
- Some(current) => {
- let candidate_key = (
- candidate.record.acquired_at_unix_seconds,
- candidate.record.zip_sha256.as_str(),
- );
- let current_key = (
- current.record.acquired_at_unix_seconds,
- current.record.zip_sha256.as_str(),
- );
- candidate_key > current_key
- }
- };
- if replace {
- freshest = Some(candidate);
- }
- }
- Ok(freshest)
- }
-}
-
-fn load_generation(generations: &Path, generation: &Path) -> Result {
- let zip =
- fs::read(generation.join("archive.zip")).map_err(|err| CacheError::Io(err.to_string()))?;
- let meta =
- fs::read(generation.join("meta.json")).map_err(|err| CacheError::Io(err.to_string()))?;
- let record: CacheRecord =
- serde_json::from_slice(&meta).map_err(|err| CacheError::Metadata(err.to_string()))?;
- let actual = sha256_hex(&zip);
- if actual != record.zip_sha256 {
- quarantine_generation(generations, generation)?;
- return Err(CacheError::Mutation {
- expected: record.zip_sha256,
- actual,
- });
- }
- Ok(CachedArchive { zip, record })
-}
-
-fn record_is_fresh(record: &CacheRecord, now_unix_seconds: u64) -> bool {
- record.acquired_at_unix_seconds != 0
- && now_unix_seconds >= record.acquired_at_unix_seconds
- && now_unix_seconds - record.acquired_at_unix_seconds < CACHE_MAX_AGE_SECONDS
-}
-
-fn stored_generation_matches(generation: &Path, expected: &CacheRecord) -> bool {
- let Ok(zip) = fs::read(generation.join("archive.zip")) else {
- return false;
- };
- let Ok(meta) = fs::read(generation.join("meta.json")) else {
- return false;
- };
- let Ok(record) = serde_json::from_slice::(&meta) else {
- return false;
- };
- record == *expected && sha256_hex(&zip) == expected.zip_sha256
-}
-
-fn quarantine_generation(generations: &Path, generation: &Path) -> Result<(), CacheError> {
- let sequence = STAGING_SEQUENCE.fetch_add(1, Ordering::Relaxed);
- let quarantine = generations.join(format!(".corrupt-{}-{sequence}", std::process::id()));
- fs::rename(generation, quarantine).map_err(|err| CacheError::Io(err.to_string()))?;
- sync_dir(generations)
-}
-
-fn stage_generation(staging: &Path, zip: &[u8], meta: &[u8]) -> Result<(), CacheError> {
- write_synced(&staging.join("archive.zip"), zip)?;
- write_synced(&staging.join("meta.json"), meta)?;
- sync_dir(staging)
-}
-
-fn write_synced(path: &Path, bytes: &[u8]) -> Result<(), CacheError> {
- let mut file = File::create(path).map_err(|err| CacheError::Io(err.to_string()))?;
- file.write_all(bytes)
- .map_err(|err| CacheError::Io(err.to_string()))?;
- file.sync_all()
- .map_err(|err| CacheError::Io(err.to_string()))
-}
-
-#[cfg(unix)]
-fn sync_dir(path: &Path) -> Result<(), CacheError> {
- File::open(path)
- .and_then(|directory| directory.sync_all())
- .map_err(|err| CacheError::Io(err.to_string()))
-}
-
-#[cfg(not(unix))]
-fn sync_dir(_path: &Path) -> Result<(), CacheError> {
- Ok(())
-}
-
-#[cfg(test)]
-mod tests {
- use super::*;
-
- const NOW: u64 = 1_000_000;
-
- fn record(zip: &[u8]) -> CacheRecord {
- CacheRecord {
- commit: Some("83c2518a9e6abbda0c44592c3483de459198f887".to_owned()),
- tree: None,
- zip_sha256: sha256_hex(zip),
- verified: true,
- transport: Some("codeload".to_owned()),
- acquired_at_unix_seconds: NOW,
- tree_files: Vec::new(),
- }
- }
-
- #[test]
- fn store_then_load_round_trips() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("83c2518a9e6abbda0c44592c3483de459198f887");
- let zip = b"PK\x03\x04 fake zip bytes";
- assert!(cache.store(&key, zip, &record(zip)).is_ok());
- let loaded = cache.load_fresh(&key, NOW);
- assert!(matches!(&loaded, Ok(Some(entry)) if entry.zip == zip));
- }
-
- #[test]
- fn store_rejects_bytes_that_do_not_match_the_recorded_digest(
- ) -> Result<(), Box> {
- let dir = tempfile::tempdir()?;
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("digest-mismatch");
- let expected = record(b"expected bytes");
-
- assert!(matches!(
- cache.store(&key, b"different bytes", &expected),
- Err(CacheError::Mutation { .. })
- ));
- assert!(matches!(cache.load_fresh(&key, NOW), Ok(None)));
- Ok(())
- }
-
- #[test]
- fn conflicting_metadata_for_one_encoding_is_quarantined_and_replaced(
- ) -> Result<(), Box> {
- let dir = tempfile::tempdir()?;
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("metadata-conflict");
- let zip = b"one immutable encoding";
- let first = record(zip);
- assert!(cache.store(&key, zip, &first).is_ok());
-
- let mut replacement = first;
- replacement.acquired_at_unix_seconds = NOW + 1;
- assert!(cache.store(&key, zip, &replacement).is_ok());
-
- let loaded = cache.load_fresh(&key, NOW + 1);
- assert!(matches!(
- loaded,
- Ok(Some(entry)) if entry.record == replacement && entry.zip == zip
- ));
- let generations = dir.path().join("metadata-conflict").join("generations");
- let quarantined = fs::read_dir(generations)?
- .filter_map(Result::ok)
- .any(|entry| entry.file_name().to_string_lossy().starts_with(".corrupt-"));
- assert!(quarantined);
- Ok(())
- }
-
- #[test]
- fn missing_entry_is_none() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("deadbeef");
- assert!(matches!(cache.load_fresh(&key, NOW), Ok(None)));
- }
-
- #[test]
- fn mutation_is_detected_on_reuse() -> Result<(), Box> {
- let dir = tempfile::tempdir()?;
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("abc123");
- let zip = b"original bytes";
- assert!(cache.store(&key, zip, &record(zip)).is_ok());
- // Tamper with the stored ZIP on disk.
- let tampered = dir
- .path()
- .join("abc123")
- .join("generations")
- .join(sha256_hex(zip))
- .join("archive.zip");
- fs::write(&tampered, b"tampered bytes")?;
- assert!(matches!(
- cache.load_fresh(&key, NOW),
- Err(CacheError::Mutation { .. })
- ));
- assert!(matches!(cache.load_fresh(&key, NOW), Ok(None)));
- Ok(())
- }
-
- #[test]
- fn interrupted_staging_directory_never_activates() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("interrupted");
- let staging = dir
- .path()
- .join("interrupted")
- .join("generations")
- .join(".stage-interrupted");
- assert!(fs::create_dir_all(&staging).is_ok());
- assert!(fs::write(staging.join("archive.zip"), b"partial").is_ok());
- assert!(matches!(cache.load_fresh(&key, NOW), Ok(None)));
-
- let zip = b"complete generation";
- assert!(cache.store(&key, zip, &record(zip)).is_ok());
- assert!(matches!(cache.load_fresh(&key, NOW), Ok(Some(entry)) if entry.zip == zip));
- }
-
- #[test]
- fn concurrent_promotions_expose_only_complete_generations() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("concurrent");
- std::thread::scope(|scope| {
- for zip in [b"encoding-a".as_slice(), b"encoding-b".as_slice()] {
- let cache = cache.clone();
- let key = key.clone();
- let _ = scope.spawn(move || cache.store(&key, zip, &record(zip)));
- }
- });
- assert!(matches!(cache.load_fresh(&key, NOW), Ok(Some(_))));
- }
-
- #[test]
- fn bytes_expire_at_twenty_four_hour_boundary() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("expiry");
- let zip = b"immutable bytes";
- assert!(cache.store(&key, zip, &record(zip)).is_ok());
- assert!(matches!(
- cache.load_fresh(&key, NOW + CACHE_MAX_AGE_SECONDS - 1),
- Ok(Some(_))
- ));
- assert!(matches!(
- cache.load_fresh(&key, NOW + CACHE_MAX_AGE_SECONDS),
- Ok(None)
- ));
- }
-
- /// The age window exists to stop stale bytes standing in for a reference
- /// that moves. A pinned commit does not move, so the same bytes that
- /// [`DiskCache::load_fresh`] has expired must still be reusable through
- /// [`DiskCache::load_pinned`] — otherwise a pinned, reproducible project
- /// cannot typecheck offline or while GitHub is rate-limiting.
- #[test]
- fn a_pinned_commit_reuses_bytes_that_have_aged_out_for_a_moving_reference() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("pinned-expiry");
- let zip = b"immutable pinned bytes";
- assert!(cache.store(&key, zip, &record(zip)).is_ok());
-
- let long_past_expiry = NOW + CACHE_MAX_AGE_SECONDS * 365;
- assert!(
- matches!(cache.load_fresh(&key, long_past_expiry), Ok(None)),
- "a moving reference must not reuse year-old bytes"
- );
- assert!(
- matches!(cache.load_pinned(&key), Ok(Some(entry)) if entry.zip == zip),
- "a content-addressed pin has no expiry"
- );
- }
-
- /// Age-blindness must not become verification-blindness: the mutation check
- /// is the whole reason expiry is safe to drop, so it still runs.
- #[test]
- fn a_pinned_load_still_rejects_a_mutated_archive() -> Result<(), Box> {
- let dir = tempfile::tempdir()?;
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("pinned-mutation");
- let zip = b"pinned original bytes";
- assert!(cache.store(&key, zip, &record(zip)).is_ok());
- fs::write(
- dir.path()
- .join("pinned-mutation")
- .join("generations")
- .join(sha256_hex(zip))
- .join("archive.zip"),
- b"tampered pinned bytes",
- )?;
-
- assert!(matches!(
- cache.load_pinned(&key),
- Err(CacheError::Mutation { .. })
- ));
- Ok(())
- }
-
- #[test]
- fn future_or_legacy_timestamp_is_not_reused() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("clock");
- let zip = b"clock bytes";
- let mut future = record(zip);
- future.acquired_at_unix_seconds = NOW + 1;
- assert!(cache.store(&key, zip, &future).is_ok());
- assert!(matches!(cache.load_fresh(&key, NOW), Ok(None)));
-
- let legacy_key = CacheKey::from_identity("legacy");
- let mut legacy = record(zip);
- legacy.acquired_at_unix_seconds = 0;
- assert!(cache.store(&legacy_key, zip, &legacy).is_ok());
- assert!(matches!(cache.load_fresh(&legacy_key, NOW), Ok(None)));
- }
-
- #[test]
- fn newer_fresh_encoding_wins_over_an_expired_lower_digest() {
- let Ok(dir) = tempfile::tempdir() else {
- return;
- };
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("same-commit");
- let first = b"first archive encoding";
- let second = b"second archive encoding";
- let (expired_zip, fresh_zip) = if sha256_hex(first) < sha256_hex(second) {
- (first.as_slice(), second.as_slice())
- } else {
- (second.as_slice(), first.as_slice())
- };
- let mut expired = record(expired_zip);
- expired.acquired_at_unix_seconds = NOW - CACHE_MAX_AGE_SECONDS;
- assert!(cache.store(&key, expired_zip, &expired).is_ok());
- assert!(cache.store(&key, fresh_zip, &record(fresh_zip)).is_ok());
-
- let loaded = cache.load_fresh(&key, NOW);
- assert!(matches!(loaded, Ok(Some(entry)) if entry.zip == fresh_zip));
- }
-
- #[test]
- fn equal_age_encodings_resolve_deterministically_by_digest(
- ) -> Result<(), Box> {
- let dir = tempfile::tempdir()?;
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("equal-age");
- let first = b"first equally fresh encoding";
- let second = b"second equally fresh encoding";
- assert!(cache.store(&key, first, &record(first)).is_ok());
- assert!(cache.store(&key, second, &record(second)).is_ok());
-
- let expected = if sha256_hex(first) > sha256_hex(second) {
- first.as_slice()
- } else {
- second.as_slice()
- };
- assert!(matches!(
- cache.load_fresh(&key, NOW),
- Ok(Some(entry)) if entry.zip == expected
- ));
- Ok(())
- }
-
- #[test]
- fn fresher_encoding_wins_even_when_its_digest_sorts_lower(
- ) -> Result<(), Box> {
- let dir = tempfile::tempdir()?;
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("freshness-first");
- let first = b"first different encoding";
- let second = b"second different encoding";
- let (lower_digest, higher_digest) = if sha256_hex(first) < sha256_hex(second) {
- (first.as_slice(), second.as_slice())
- } else {
- (second.as_slice(), first.as_slice())
- };
- let mut older = record(higher_digest);
- older.acquired_at_unix_seconds = NOW - 1;
- let newer = record(lower_digest);
- assert!(cache.store(&key, higher_digest, &older).is_ok());
- assert!(cache.store(&key, lower_digest, &newer).is_ok());
-
- assert!(matches!(
- cache.load_fresh(&key, NOW),
- Ok(Some(entry)) if entry.zip == lower_digest
- ));
- Ok(())
- }
-
- #[test]
- fn malformed_promoted_metadata_fails_closed() -> Result<(), Box> {
- let dir = tempfile::tempdir()?;
- let cache = DiskCache::new(dir.path());
- let key = CacheKey::from_identity("bad-metadata");
- let generation = dir
- .path()
- .join("bad-metadata")
- .join("generations")
- .join("generation");
- fs::create_dir_all(&generation)?;
- fs::write(generation.join("archive.zip"), b"bytes")?;
- fs::write(generation.join("meta.json"), b"not json")?;
-
- assert!(matches!(
- cache.load_fresh(&key, NOW),
- Err(CacheError::Metadata(_))
- ));
- Ok(())
- }
-
- #[test]
- fn key_sanitizes_unsafe_characters() {
- let key = CacheKey::from_identity("custom-/etc/passwd");
- assert!(!key.dir_name().contains('/'));
- }
-}
diff --git a/crates/basilisk-stubs/src/typeshed/codec.rs b/crates/basilisk-stubs/src/typeshed/codec.rs
index 8b9e0a90..03887b31 100644
--- a/crates/basilisk-stubs/src/typeshed/codec.rs
+++ b/crates/basilisk-stubs/src/typeshed/codec.rs
@@ -1,4 +1,4 @@
-//! Implements [STUBRES-TYPESHED-ACQUIRE] ZIP decode. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-ACQUIRE
+//! Implements [STUBRES-TYPESHED-DOWNLOAD] ZIP decode. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-DOWNLOAD
//!
//! ZIP → [`Archive`] decoding with streaming zip-bomb caps.
//!
@@ -6,7 +6,7 @@
//! The decoder enforces entry-count, per-entry, **total**, and compression-ratio
//! caps *while reading each entry*, so an inflated entry is bounded before it is
//! fully allocated — a later gate over a fully-inflated archive would be too late
-//! ([STUBRES-TYPESHED-ACQUIRE]). Encrypted entries are rejected outright. When a
+//! ([STUBRES-TYPESHED-DOWNLOAD]). Encrypted entries are rejected outright. When a
//! top-level prefix is stripped (GitHub zipballs nest under `typeshed-/`),
//! the decoder requires a single coherent non-`..` common root, so a mixed-root
//! or `../evil`-prefixed archive can never normalize into a clean path. Path
diff --git a/crates/basilisk-stubs/src/typeshed/gate/errors.rs b/crates/basilisk-stubs/src/typeshed/gate/errors.rs
index 3b312769..3a943225 100644
--- a/crates/basilisk-stubs/src/typeshed/gate/errors.rs
+++ b/crates/basilisk-stubs/src/typeshed/gate/errors.rs
@@ -1,4 +1,4 @@
-//! Implements [STUBRES-TYPESHED-ACQUIRE] gate errors. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-ACQUIRE
+//! Implements [STUBRES-TYPESHED-DOWNLOAD] gate errors. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-DOWNLOAD
//!
//! The rejection taxonomy for the four activation gates.
diff --git a/crates/basilisk-stubs/src/typeshed/gate/manifest.rs b/crates/basilisk-stubs/src/typeshed/gate/manifest.rs
index 117027ae..765229f2 100644
--- a/crates/basilisk-stubs/src/typeshed/gate/manifest.rs
+++ b/crates/basilisk-stubs/src/typeshed/gate/manifest.rs
@@ -61,8 +61,11 @@ impl LicenseManifest {
/// Whether a path names a legal file (`LICENSE*`/`NOTICE*`, case-insensitive)
/// within the **relevant scope** — the archive root or under `stdlib/`. This
/// matches the bundle updater, so a full archive's unrelated `stubs/**` legal
-/// files never register as drift.
-fn is_legal_file(path: &str) -> bool {
+/// files never register as drift. Public because the store writer and reader
+/// share this exact rule for which paths a store entry materializes
+/// ([STUBRES-TYPESHED-STORE]).
+#[must_use]
+pub fn is_legal_file(path: &str) -> bool {
let relevant = !path.contains('/') || path.starts_with("stdlib/");
if !relevant {
return false;
diff --git a/crates/basilisk-stubs/src/typeshed/gate/mod.rs b/crates/basilisk-stubs/src/typeshed/gate/mod.rs
index 3acce3a3..570d5a3f 100644
--- a/crates/basilisk-stubs/src/typeshed/gate/mod.rs
+++ b/crates/basilisk-stubs/src/typeshed/gate/mod.rs
@@ -1,4 +1,4 @@
-//! Implements [STUBRES-TYPESHED-ACQUIRE] activation gates. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-ACQUIRE
+//! Implements [STUBRES-TYPESHED-DOWNLOAD] activation gates. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-DOWNLOAD
//!
//! The four activation gates.
//!
@@ -11,8 +11,7 @@
//! 3. **License** — the discovered `LICENSE*`/`NOTICE*` path+SHA-256 set must
//! exactly match a build-approved identity ([STUBRES-TYPESHED-LICENSE]).
//! 4. **Content** — reconstruct the Git root tree and match the trusted
-//! root-tree SHA. **Only this gate may be waived**; waiving it emits
-//! [`TypeshedWarning::Unverified`] and never disables the first three.
+//! root-tree SHA. No gate can be waived ([STUBRES-TYPESHED-PIN]).
pub mod errors;
pub mod manifest;
@@ -24,7 +23,6 @@ use std::collections::HashSet;
use super::archive::{Archive, ArchiveVfs};
use super::gittree::{FileMode, Oid};
-use super::warning::TypeshedWarning;
/// Byte and count limits enforced by the Safety gate.
#[derive(Debug, Clone, Copy)]
@@ -225,26 +223,21 @@ pub struct GateConfig {
pub approved_license: LicenseManifest,
/// The trusted root-tree SHA to attest against.
pub expected_root_tree: Oid,
- /// Whether to run the Content gate; `false` waives only content attestation.
- pub verify_content: bool,
}
-/// A successfully activated archive: its VFS, any status warnings, and the
-/// verified tree SHA (absent when content verification was waived).
+/// A successfully activated archive: its VFS and the verified tree SHA.
#[derive(Debug, Clone)]
pub struct Activation {
/// The archive VFS the resolver reads through.
pub vfs: ArchiveVfs,
- /// Composable status warnings raised during activation.
- pub warnings: Vec,
- /// The verified root-tree SHA, or `None` when content verification was off.
- pub root_tree: Option,
+ /// The verified root-tree SHA.
+ pub root_tree: Oid,
}
/// Run all four gates in order and produce an [`Activation`].
///
-/// Safety, Shape, and License always run; Content runs unless waived, in which
-/// case [`TypeshedWarning::Unverified`] is raised.
+/// Every gate always runs. There is no waiver: a pin you can switch off is a
+/// pin that does nothing ([STUBRES-TYPESHED-PIN]).
///
/// # Errors
///
@@ -257,16 +250,10 @@ pub fn run_activation(
safety_gate(&archive, &config.limits).map_err(GateError::Safety)?;
shape_gate(&archive).map_err(GateError::Shape)?;
license_gate(&archive, &config.approved_license).map_err(GateError::License)?;
- let mut warnings = Vec::new();
- let root_tree = if config.verify_content {
- Some(content_gate(&archive, &config.expected_root_tree).map_err(GateError::Content)?)
- } else {
- warnings.push(TypeshedWarning::Unverified);
- None
- };
+ let root_tree =
+ content_gate(&archive, &config.expected_root_tree).map_err(GateError::Content)?;
Ok(Activation {
vfs: ArchiveVfs::new(identity, archive),
- warnings,
root_tree,
})
}
@@ -297,32 +284,35 @@ mod tests {
]
}
- fn config_for(archive: &Archive, verify: bool) -> GateConfig {
+ fn config_for(archive: &Archive) -> GateConfig {
GateConfig {
limits: SafetyLimits::default(),
approved_license: LicenseManifest::discover(archive),
expected_root_tree: archive.root_tree_oid().unwrap(),
- verify_content: verify,
}
}
#[test]
fn valid_archive_activates_and_verifies() {
let archive = Archive::new(valid_entries());
- let config = config_for(&archive, true);
+ let config = config_for(&archive);
+ let root = config.expected_root_tree;
let activation = run_activation(archive, &config, "83c2518").unwrap();
- assert!(activation.warnings.is_empty());
- assert!(activation.root_tree.is_some());
+ assert_eq!(activation.root_tree, root);
assert_eq!(activation.vfs.identity(), "83c2518");
}
+ /// Content verification always runs — there is no waiver field, flag, or
+ /// mode; a mutated tree is terminal ([STUBRES-TYPESHED-PIN] no-waiver).
#[test]
- fn waived_content_emits_unverified_only() {
+ fn content_verification_cannot_be_waived() {
let archive = Archive::new(valid_entries());
- let config = config_for(&archive, false);
- let activation = run_activation(archive, &config, "83c2518").unwrap();
- assert_eq!(activation.warnings, vec![TypeshedWarning::Unverified]);
- assert!(activation.root_tree.is_none());
+ let mut config = config_for(&archive);
+ config.expected_root_tree = crate::typeshed::gittree::git_blob_oid(b"not the tree");
+ assert!(matches!(
+ run_activation(archive, &config, "83c2518"),
+ Err(GateError::Content(ContentViolation::TreeMismatch { .. }))
+ ));
}
#[test]
diff --git a/crates/basilisk-stubs/src/typeshed/gittree.rs b/crates/basilisk-stubs/src/typeshed/gittree.rs
index 3e7a253b..12b50eb2 100644
--- a/crates/basilisk-stubs/src/typeshed/gittree.rs
+++ b/crates/basilisk-stubs/src/typeshed/gittree.rs
@@ -1,4 +1,4 @@
-//! Implements [STUBRES-TYPESHED-ACQUIRE] Content gate. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-ACQUIRE
+//! Implements [STUBRES-TYPESHED-PIN] content addressing. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED-PIN
//!
//! Git object-ID reconstruction.
//!
@@ -175,6 +175,53 @@ pub fn git_blob_oid(content: &[u8]) -> Oid {
git_object_oid(b"blob", content)
}
+/// Compute a Git **commit** object ID for raw commit-object content (the bytes
+/// `git cat-file commit` prints, without the `commit {len}\0` framing).
+///
+/// This is the offline anchor of a pin: the stored commit object must hash to
+/// the pinned SHA before its tree SHA is trusted ([STUBRES-TYPESHED-PIN]).
+#[must_use]
+pub fn git_commit_oid(content: &[u8]) -> Oid {
+ git_object_oid(b"commit", content)
+}
+
+/// Error reading the root-tree SHA out of a raw commit object.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum CommitParseError {
+ /// The content did not begin with a `tree <40-hex>\n` header.
+ #[error("commit object does not begin with a tree header")]
+ MissingTreeHeader,
+ /// The tree header's SHA was not valid hex.
+ #[error("commit object tree header is not a valid object id: {0}")]
+ BadTreeSha(OidParseError),
+}
+
+/// Read the root-tree SHA from raw commit-object content.
+///
+/// Git guarantees the first header of a commit object is `tree `
+/// ([Git `commit-tree`](https://git-scm.com/docs/git-commit-tree)), so this
+/// parses exactly that shape and nothing else — a malformed object fails
+/// rather than being guessed at.
+///
+/// # Errors
+///
+/// Returns [`CommitParseError`] when the content does not start with a
+/// well-formed tree header.
+pub fn commit_root_tree(content: &[u8]) -> Result {
+ let rest = content
+ .strip_prefix(b"tree ")
+ .ok_or(CommitParseError::MissingTreeHeader)?;
+ let (sha_bytes, terminator) = rest
+ .split_at_checked(40)
+ .ok_or(CommitParseError::MissingTreeHeader)?;
+ if terminator.first() != Some(&b'\n') {
+ return Err(CommitParseError::MissingTreeHeader);
+ }
+ let sha =
+ std::str::from_utf8(sha_bytes).map_err(|_error| CommitParseError::MissingTreeHeader)?;
+ Oid::from_hex(sha).map_err(CommitParseError::BadTreeSha)
+}
+
/// Reconstruct the Git **root-tree** object ID for a flat set of archived files.
///
/// An empty set yields Git's canonical empty-tree ID. Reconstruction is exact
@@ -430,4 +477,41 @@ mod tests {
Err(TreeError::DuplicatePath(_))
));
}
+
+ /// Pinned Git constant: `printf 'tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904\nauthor a 0 +0000\ncommitter a 0 +0000\n\nx\n' | git hash-object -t commit --stdin`.
+ #[test]
+ fn commit_oid_matches_git() {
+ let raw = b"tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904\nauthor a 0 +0000\ncommitter a 0 +0000\n\nx\n";
+ assert_eq!(
+ git_commit_oid(raw).to_hex(),
+ "1f575658d4ebb47930907abae76eec9e594fa80d"
+ );
+ }
+
+ #[test]
+ fn commit_root_tree_reads_exactly_the_leading_tree_header() {
+ let raw = b"tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904\nauthor a 0 +0000\n\nmsg\n";
+ assert_eq!(
+ commit_root_tree(raw).map(|oid| oid.to_hex()),
+ Ok(EMPTY_TREE.to_owned())
+ );
+ // A parent header first, a truncated SHA, or non-hex all fail closed.
+ assert_eq!(
+ commit_root_tree(b"parent 4b825dc642cb6eb9a060e54bf8d69288fbee4904\n"),
+ Err(CommitParseError::MissingTreeHeader)
+ );
+ assert_eq!(
+ commit_root_tree(b"tree 4b825dc6\n"),
+ Err(CommitParseError::MissingTreeHeader)
+ );
+ assert!(matches!(
+ commit_root_tree(b"tree zz825dc642cb6eb9a060e54bf8d69288fbee4904\n"),
+ Err(CommitParseError::BadTreeSha(_))
+ ));
+ assert_eq!(
+ commit_root_tree(b"tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904"),
+ Err(CommitParseError::MissingTreeHeader),
+ "a tree header without its newline terminator is malformed"
+ );
+ }
}
diff --git a/crates/basilisk-stubs/src/typeshed/manager.rs b/crates/basilisk-stubs/src/typeshed/manager.rs
index d67b7ca1..5e3db9de 100644
--- a/crates/basilisk-stubs/src/typeshed/manager.rs
+++ b/crates/basilisk-stubs/src/typeshed/manager.rs
@@ -1,21 +1,22 @@
-//! Implements [STUBRES-TYPESHED] one-generation acquisition. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED
+//! Implements [STUBRES-TYPESHED] one-generation resolution. See docs/specs/CHECKER-STUB-RESOLUTION-SPEC.md#STUBRES-TYPESHED
//!
//! A manager is constructed for one effective, config-free [`TypeshedRequest`].
//! Its first caller performs selection; concurrent CLI/LSP/MCP consumers block
//! on the same [`OnceLock`] and receive the same [`Arc`]. Success and
-//! failure are both memoized for the run/session, so `main` is never resolved
-//! twice and no caller can observe a partially promoted generation.
+//! failure are both memoized for the run/session, so no caller can observe a
+//! partially promoted generation. Selection is a local read
+//! ([STUBRES-TYPESHED-OFFLINE]) — fast, and never a network wait.
use std::sync::{Arc, OnceLock};
-use super::selector::{select_snapshot, AcquisitionBackend, SelectionError};
+use super::selector::{select_snapshot, SelectionError, SourceBackend};
use super::snapshot::Snapshot;
use super::source::{TypeshedRequest, TypeshedStatus};
/// One config generation's single-flight typeshed manager.
pub struct TypeshedManager {
request: TypeshedRequest,
- backend: Arc,
+ backend: Arc,
selected: OnceLock, SelectionError>>,
}
@@ -32,7 +33,7 @@ impl std::fmt::Debug for TypeshedManager {
impl TypeshedManager {
/// Create a manager for one resolved configuration generation.
#[must_use]
- pub fn new(request: TypeshedRequest, backend: Arc) -> Self {
+ pub fn new(request: TypeshedRequest, backend: Arc) -> Self {
Self {
request,
backend,
@@ -40,19 +41,19 @@ impl TypeshedManager {
}
}
- /// The immutable request this manager will acquire exactly once.
+ /// The immutable request this manager will resolve exactly once.
#[must_use]
pub const fn request(&self) -> &TypeshedRequest {
&self.request
}
- /// Acquire or reuse the one complete active snapshot.
+ /// Resolve or reuse the one complete active snapshot.
///
/// # Errors
///
/// Returns a redacted [`SelectionError`]. The same failure is returned to
/// every caller for this manager; callers never retry into a different
- /// generation or expose adapter URLs/credentials.
+ /// generation and never receive a substitute source.
pub fn snapshot(&self) -> Result, SelectionError> {
self.selected
.get_or_init(|| select_snapshot(&self.request, self.backend.as_ref()).map(Arc::new))
@@ -71,7 +72,7 @@ impl TypeshedManager {
self.snapshot().map(|snapshot| snapshot.status.clone())
}
- /// The ready snapshot without starting acquisition, if selection already
+ /// The ready snapshot without starting resolution, if selection already
/// completed successfully.
#[must_use]
pub fn ready_snapshot(&self) -> Option> {
@@ -96,15 +97,15 @@ mod tests {
use super::super::gittree::{FileMode, Oid};
use super::super::selector::BackendError;
use super::super::source::{
- LicenseStatus, Provenance, SourceIdentity, SourceKind, SourceSelection, Transport,
- TypeshedStatus,
+ LicenseStatus, SourceIdentity, SourceKind, SourceSelection, TypeshedStatus,
};
use super::*;
- const LATEST_SHA: &str = "0123456789012345678901234567890123456789";
+ const PINNED_SHA: &str = "0123456789012345678901234567890123456789";
+ const BUNDLE_SHA: &str = "83c2518a9e6abbda0c44592c3483de459198f887";
struct CountingBackend {
- latest_calls: AtomicUsize,
+ pinned_calls: AtomicUsize,
custom_calls: AtomicUsize,
custom_fails: bool,
}
@@ -112,14 +113,14 @@ mod tests {
impl CountingBackend {
fn new(custom_fails: bool) -> Self {
Self {
- latest_calls: AtomicUsize::new(0),
+ pinned_calls: AtomicUsize::new(0),
custom_calls: AtomicUsize::new(0),
custom_fails,
}
}
}
- impl AcquisitionBackend for CountingBackend {
+ impl SourceBackend for CountingBackend {
fn load_custom(&self, _path: &str) -> Result {
let _ = self.custom_calls.fetch_add(1, Ordering::SeqCst);
if self.custom_fails {
@@ -128,63 +129,42 @@ mod tests {
let identity = SourceIdentity::Custom {
digest: "custom-content-digest".to_owned(),
};
- Ok(fixture_snapshot(
- identity,
- SourceKind::Custom,
- Provenance::UserManaged,
- ))
- }
-
- fn load_commit(
- &self,
- _commit: Oid,
- _request: &TypeshedRequest,
- ) -> Result
+
+
+