Manage stdlib in toolchain

Author: akhilles

crates/pcb-docgen/README.md

@@ -1,123 +1,28 @@
-# stdlib-docgen
+# pcb-docgen
 
-Automated documentation generator for the Zener standard library (`@stdlib`).
+Generates stdlib docs (`stdlib.mdx`) from `.zen` files.
 
-## Overview
+## Notes
 
-This crate parses `.zen` files from the stdlib directory and generates a single `stdlib.mdx` 
-documentation file that is used by the `pcb doc` command.
+- Input stdlib path is typically `<workspace>/.pcb/stdlib`.
+- Output is deterministic and used by `pcb doc`.
 
-**Important**: The stdlib version is re-exported from `pcb-zen-core::STDLIB_VERSION`, so it 
-stays automatically in sync when the stdlib version is bumped.
-
-## How it works
-
-1. **File Discovery**: Walks the cached stdlib at `~/.pcb/cache/github.com/diodeinc/stdlib/<version>`, 
-   excluding `test/` and `kicad/` directories
-2. **Classification**: Distinguishes between library files (functions/types) and module files (instantiable components)
-3. **Library Parsing**: Extracts docstrings, functions, types, and constants using regex-based parsing
-4. **Module Signatures**: Runs `pcb build <file.zen> --netlist` to get the `__signature` JSON
-5. **MDX Generation**: Produces deterministic `docs/pages/stdlib.mdx`
-
-## Usage
-
-### CLI
+## CLI
 
 ```bash
-# Generate stdlib docs using cached stdlib (default)
-cargo run -p stdlib-docgen
-
-# Generate with custom paths (for development/testing)
-cargo run -p stdlib-docgen -- <stdlib_path> <docs_dir> <pcb_cli_path>
+cargo run -p pcb-docgen
+cargo run -p pcb-docgen -- <stdlib_path> <docs_dir> <pcb_cli_path>
 ```
 
-The tool will use the stdlib from `~/.pcb/cache/github.com/diodeinc/stdlib/<version>` by default.
-If the cache is empty, run `pcb build` on any project first to populate it.
-
-### As a library
+## Library
 
 ```rust
-use stdlib_docgen::generate_stdlib_mdx;
+use pcb_docgen::generate_stdlib_mdx;
 use std::path::Path;
 
 let result = generate_stdlib_mdx(
     Path::new("../stdlib"),
     Path::new("docs/pages"),
     Path::new("target/debug/pcb"),
 )?;
-
-println!("Generated {} libraries and {} modules", 
-    result.library_count, result.module_count);
-```
-
-## Docstring Conventions
-
-### File-level docstrings
-
-Put a triple-quoted docstring at the top of the file (after `load` statements):
-
-```python
-"""Short summary of the module.
-
-Longer description with examples if needed.
-"""
-
-load("@stdlib/units.zen", "Voltage")
-```
-
-### Function docstrings
-
-Put a triple-quoted docstring as the first statement in the function body:
-
-```python
-def my_function(arg1, arg2):
-    """Short summary of what the function does.
-
-    Args:
-        arg1: Description of arg1
-        arg2: Description of arg2
-
-    Returns:
-        Description of return value
-    """
-    ...
-```
-
-### Module files
-
-Module files are detected by the presence of `config()` or `io()` declarations.
-Their signatures are automatically extracted from `pcb build --netlist` output.
-
-Add a file-level docstring to describe the component's purpose:
-
-```python
-"""
-Pin Header Connector Component
-
-A configurable pin header component that supports:
-- Single and dual row configurations
-- Multiple pitch options
-- Various mount types
-
-Example usage:
-    PinHeader(name="J1", pins=4, P1=vcc, P2=gnd)
-"""
-
-package = config("package", Package, default=Package("0603"))
-P1 = io("P1", Net)
-```
-
-## Integration with build.rs
-
-To regenerate stdlib docs during `cargo build`, add to `pcb-docs/build.rs`:
-
-```rust
-use stdlib_docgen::generate_stdlib_mdx;
-
-// In main():
-stdlib_docgen::generate_stdlib_mdx(
-    &stdlib_root,
-    &docs_dir,
-    &pcb_cli,
-)?;
 ```

crates/pcb-docgen/src/render.rs

@@ -21,8 +21,8 @@ pub fn render_docs(
 
     // Add package URL as h1 header if provided
     if let Some(url) = package_url {
-        // Special case: display github.com/diodeinc/stdlib as @stdlib
-        let display_url = if url == "github.com/diodeinc/stdlib" {
+        // Special case: display virtual stdlib package as @stdlib
+        let display_url = if pcb_zen_core::is_stdlib_module_path(url) {
             "@stdlib"
         } else {
             url
@@ -300,7 +300,7 @@ mod tests {
     #[test]
     fn test_render_docs_stdlib_alias() {
         let files = vec![];
-        let output = render_docs(&files, Some("github.com/diodeinc/stdlib"), None);
+        let output = render_docs(&files, Some(pcb_zen_core::STDLIB_MODULE_PATH), None);
         assert!(output.contains("# @stdlib\n"));
     }
 }

crates/pcb-test-utils/src/sandbox.rs

@@ -532,13 +532,12 @@ impl Sandbox {
             .replace_all(&result, r#""net_id": Number(<ID>)"#)
             .to_string();
 
-        // Sanitize stdlib version in both paths and package IDs:
-        // - stdlib/0.5.1 -> stdlib/<STDLIB_VERSION>
-        // - stdlib@0.5.1 -> stdlib@<STDLIB_VERSION>
+        // Normalize legacy versioned stdlib paths:
+        // - stdlib/0.5.1 -> stdlib
         let stdlib_version_pattern =
             Regex::new(r"stdlib([/@])\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?").unwrap();
         result = stdlib_version_pattern
-            .replace_all(&result, "stdlib$1<STDLIB_VERSION>")
+            .replace_all(&result, "stdlib")
             .to_string();
 
         result
@@ -677,16 +676,13 @@ impl Sandbox {
         std::os::windows::fs::symlink_dir(&global_dir, &sandbox_dir).unwrap();
     }
 
-    /// Seed stdlib and common asset dependency repos for dep resolution tests.
+    /// Seed common asset dependency repos for dep resolution tests.
     ///
-    /// Uses the global cache if present; otherwise fetches via network and caches locally.
+    /// Embedded stdlib is materialized per-workspace by the toolchain, so only external
+    /// asset repos need seeding here.
     pub fn seed_stdlib(&mut self) -> &mut Self {
-        let stdlib_version = pcb_zen_core::STDLIB_VERSION;
         let kicad_version = "9.0.3";
 
-        // cache (~/.pcb/cache) - seed stdlib + common asset deps
-        self.seed_cache_repo("github.com/diodeinc/stdlib", stdlib_version, true);
-
         for repo in [
             "gitlab.com/kicad/libraries/kicad-symbols",
             "gitlab.com/kicad/libraries/kicad-footprints",
@@ -1151,23 +1147,19 @@ mod tests {
     }
 
     #[test]
-    fn test_sanitize_stdlib_version_in_path_and_package_id() {
+    fn test_sanitize_stdlib_version_in_path() {
         let sb = Sandbox::new();
         let input = r#"{
   "package_roots": {
-    "github.com/diodeinc/stdlib@0.5.8": "/tmp/vendor/github.com/diodeinc/stdlib/0.5.8",
-    "github.com/diodeinc/stdlib@0.5.8-beta.1": "/tmp/vendor/github.com/diodeinc/stdlib/0.5.8-beta.1"
+    "stdlib": "/tmp/.pcb/cache/stdlib/0.5.8",
+    "workspace": "/tmp/workspace"
   }
 }"#;
 
         let output = sb.sanitize_output(input);
 
-        assert!(output.contains("github.com/diodeinc/stdlib@<STDLIB_VERSION>"));
-        assert!(output.contains("/tmp/vendor/github.com/diodeinc/stdlib/<STDLIB_VERSION>"));
-        assert!(!output.contains("stdlib@0.5.8"));
+        assert!(output.contains("\"stdlib\": \"/tmp/.pcb/cache/stdlib\""));
         assert!(!output.contains("stdlib/0.5.8"));
-        assert!(!output.contains("stdlib@0.5.8-beta.1"));
-        assert!(!output.contains("stdlib/0.5.8-beta.1"));
     }
 
     #[test]

crates/pcb-zen-core/src/lang/eval.rs

@@ -505,18 +505,9 @@ impl EvalContextConfig {
     /// Expand alias using the resolution map.
     fn expand_alias(&self, context: &ResolveContext, alias: &str) -> Result<String, anyhow::Error> {
         let package_root = self.find_package_root_for_file(&context.current_file)?;
-        let resolved_map = self
-            .resolution
-            .package_resolutions
-            .get(&package_root)
-            .ok_or_else(|| {
-                anyhow::anyhow!(
-                    "Dependency map not loaded for package '{}'",
-                    package_root.display()
-                )
-            })?;
-
-        if let Some(url) = Self::find_alias_in_map(resolved_map, alias) {
+        if let Some(resolved_map) = self.resolution.package_resolutions.get(&package_root)
+            && let Some(url) = Self::find_alias_in_map(resolved_map, alias)
+        {
             return Ok(url);
         }
 
@@ -529,24 +520,31 @@ impl EvalContextConfig {
         context: &ResolveContext,
         package_root: &Path,
     ) -> Result<PathBuf, anyhow::Error> {
-        let spec = context.latest_spec();
-        let full_url = spec
-            .to_full_url()
-            .expect("try_resolve_workspace called with non-URL spec");
-
-        let resolved_map = self
-            .resolution
-            .package_resolutions
-            .get(package_root)
-            .ok_or_else(|| {
-                anyhow::anyhow!(
+        let full_url = if let LoadSpec::Stdlib { path } = context.latest_spec() {
+            let stdlib_root = self.resolution.workspace_info.workspace_stdlib_dir();
+            return Ok(if path.as_os_str().is_empty() {
+                stdlib_root
+            } else {
+                stdlib_root.join(path)
+            });
+        } else {
+            context
+                .latest_spec()
+                .to_full_url()
+                .expect("try_resolve_workspace called with non-URL spec")
+        };
+
+        let resolved_map = self.resolution.package_resolutions.get(package_root);
+        let best_match = resolved_map.and_then(|map| Self::find_best_dep_match(map, &full_url));
+
+        let Some((matched_dep, root_path)) = best_match else {
+            if resolved_map.is_none() {
+                anyhow::bail!(
                     "Dependency map not loaded for package '{}'",
                     package_root.display()
-                )
-            })?;
-        let best_match = Self::find_best_dep_match(resolved_map, &full_url);
+                );
+            }
 
-        let Some((matched_dep, root_path)) = best_match else {
             anyhow::bail!(
                 "No declared dependency matches '{}'\n  \
                 Add a dependency to [dependencies] in pcb.toml that covers this path",
@@ -584,22 +582,13 @@ impl EvalContextConfig {
     }
 
     /// Find the package URL for a given canonical package root path by scanning
-    /// workspace members and resolution maps.
+    /// known package roots.
     // TODO: if this becomes a bottleneck, pre-build a reverse map (PathBuf -> URL) at init time.
     fn find_url_for_package_root(&self, canonical_root: &Path) -> Option<String> {
-        let ws = &self.resolution.workspace_info;
-        for (url, member) in &ws.packages {
-            let dir = member.dir(&ws.root);
-            let canon = self.file_provider.canonicalize(&dir).unwrap_or(dir);
-            if canon == canonical_root {
-                return Some(url.clone());
-            }
-        }
-        for resolved_map in self.resolution.package_resolutions.values() {
-            for (dep_url, dep_path) in resolved_map {
-                if dep_path == canonical_root {
-                    return Some(dep_url.clone());
-                }
+        for (url, root) in self.resolution.package_roots() {
+            let canonical = self.file_provider.canonicalize(&root).unwrap_or(root);
+            if canonical == canonical_root {
+                return Some(url);
             }
         }
         None
@@ -694,22 +683,18 @@ impl EvalContextConfig {
         // Expand aliases
         if let LoadSpec::Package { package, path, .. } = context.latest_spec() {
             let expanded_url = self.expand_alias(context, package)?;
-            let full_url = if path.as_os_str().is_empty() {
-                expanded_url
-            } else {
-                format!("{}/{}", expanded_url, path.display())
+            let expanded_spec = LoadSpec::Package {
+                package: expanded_url,
+                path: path.clone(),
             };
-
-            let expanded_spec = LoadSpec::parse(&full_url)
-                .ok_or_else(|| anyhow::anyhow!("Failed to parse expanded alias: {}", full_url))?;
-            context.push_spec(expanded_spec)?;
+            if &expanded_spec != context.latest_spec() {
+                context.push_spec(expanded_spec)?;
+            }
         }
 
         let resolved_path = match context.latest_spec() {
-            LoadSpec::Github { .. } | LoadSpec::Gitlab { .. } => self.resolve_url(context)?,
             LoadSpec::Path { .. } => self.resolve_relative(context)?,
-            LoadSpec::Package { .. } => unreachable!("Package checked above"),
-            LoadSpec::PackageUri { .. } => unreachable!("PackageUri resolved in resolve_context"),
+            _ => self.resolve_url(context)?,
         };
 
         if !context.file_provider.exists(&resolved_path)