Move module name parsing from JS regex to WASM parser

The previous approach used a fragile regex to extract module names JS-side
before registration. This refactors to pass the tar path and source to WASM,
where the actual PureScript parser extracts the module name robustly.

- Add RawModule type (path + source before parsing)
- Add path field to PackageModule as stable identifier
- Replace register_module with register_source in WASM
- register_source returns parsed module name or None on failure

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: purefunctor

docs/src/lib/packages/fetcher.ts

@@ -1,5 +1,5 @@
 import pako from "pako";
-import type { PackageModule, PackageSet } from "./types";
+import type { RawModule, PackageSet } from "./types";
 
 const REGISTRY_URL = "https://packages.registry.purescript.org";
 const PACKAGE_SET_URL =
@@ -53,20 +53,11 @@ function parseTar(data: Uint8Array): Map<string, string> {
   return files;
 }
 
-/**
- * Extract module name from PureScript source.
- * Parses the "module X.Y.Z where" declaration.
- */
-function extractModuleName(source: string): string | null {
-  const match = source.match(/^\s*module\s+([\w.]+)/m);
-  return match ? match[1] : null;
-}
-
 export async function fetchPackage(
   packageName: string,
   version: string,
   onProgress?: (progress: number) => void
-): Promise<PackageModule[]> {
+): Promise<RawModule[]> {
   // Strip 'v' prefix from version for registry URL
   const versionNum = version.startsWith("v") ? version.slice(1) : version;
   const url = `${REGISTRY_URL}/${packageName}/${versionNum}.tar.gz`;
@@ -108,13 +99,10 @@ export async function fetchPackage(
   // Extract .purs files
   const files = parseTar(tarData);
 
-  // Convert to modules
-  const modules: PackageModule[] = [];
-  for (const [, source] of files) {
-    const moduleName = extractModuleName(source);
-    if (moduleName) {
-      modules.push({ name: moduleName, source });
-    }
+  // Convert to raw modules (path + source, no module name parsing)
+  const modules: RawModule[] = [];
+  for (const [path, source] of files) {
+    modules.push({ path, source });
   }
 
   return modules;

docs/src/lib/packages/types.ts

@@ -7,9 +7,16 @@ export interface PackageSetEntry {
 
 export type PackageSet = Record<string, PackageSetEntry>;
 
-// Internal state
+// Raw module data from tar extraction (before WASM parsing)
+export interface RawModule {
+  path: string; // tar path, e.g., "prelude-6.0.1/src/Data/Maybe.purs"
+  source: string; // PureScript source code
+}
+
+// Internal state (after WASM parsing extracts module name)
 export interface PackageModule {
-  name: string; // e.g., "Data.Maybe"
+  path: string; // tar path, e.g., "prelude-6.0.1/src/Data/Maybe.purs"
+  name: string; // module name returned from WASM, e.g., "Data.Maybe"
   source: string; // PureScript source code
 }
 

docs/src/lib/types.ts

@@ -66,5 +66,5 @@ export interface Lib {
     onProgress: (progress: PackageLoadProgress) => void
   ): Promise<LoadedPackage[]>;
   clearPackages(): Promise<void>;
-  registerModule(moduleName: string, source: string): Promise<void>;
+  registerModule(path: string, source: string): Promise<string | undefined>;
 }

docs/src/wasm/src/engine.rs

@@ -84,19 +84,30 @@ impl WasmQueryEngine {
         }
     }
 
-    /// Register an external module (from a package).
-    /// Returns the FileId for the module.
-    pub fn register_external_module(&mut self, module_name: &str, source: &str) -> FileId {
-        let path = format!("pkg://registry/{module_name}.purs");
-        let id = self.files.borrow_mut().insert(path.as_str(), source);
-
+    /// Register an external module source, parsing the module name from source.
+    /// Returns the parsed module name on success, or None if parsing fails.
+    pub fn register_external_source(&mut self, path: &str, source: &str) -> Option<String> {
+        // 1. Insert file into VFS → FileId
+        let virtual_path = format!("pkg://registry/{path}");
+        let id = self.files.borrow_mut().insert(virtual_path.as_str(), source);
+
+        // 2. Set content in input storage
         self.input.borrow_mut().content.insert(id, Arc::from(source));
 
-        let name_id = self.interned.borrow_mut().module.intern(module_name);
+        // 3. Parse (using cached query infrastructure)
+        let (parsed, _) = self.parsed(id).ok()?;
+
+        // 4. Extract module name
+        let module_name = parsed.module_name()?;
+
+        // 5. Register module name → FileId mapping
+        let name_id = self.interned.borrow_mut().module.intern(&module_name);
         self.input.borrow_mut().module.insert(name_id, id);
 
+        // Track for cleanup
         self.external_ids.push(id);
-        id
+
+        Some(module_name.to_string())
     }
 
     /// Clear all external modules (packages), keeping Prim and user modules.

docs/src/wasm/src/lib.rs

@@ -314,12 +314,11 @@ pub fn check(source: &str) -> JsValue {
     serde_wasm_bindgen::to_value(&result).unwrap()
 }
 
-/// Register an external module (from a package) with the engine.
+/// Register an external module source, parsing the module name from source.
+/// Returns the parsed module name on success, or undefined if parsing fails.
 #[wasm_bindgen]
-pub fn register_module(module_name: &str, source: &str) {
-    ENGINE.with_borrow_mut(|engine| {
-        engine.register_external_module(module_name, source);
-    });
+pub fn register_source(path: &str, source: &str) -> Option<String> {
+    ENGINE.with_borrow_mut(|engine| engine.register_external_source(path, source))
 }
 
 /// Clear all external modules (packages), keeping Prim and user modules.

docs/src/worker/docs-lib.ts

@@ -3,6 +3,7 @@ import init, * as docsLib from "docs-lib";
 import type { ParseResult, CheckResult } from "../lib/types";
 import type {
   PackageSet,
+  PackageModule,
   LoadedPackage,
   PackageLoadProgress,
   PackageStatus,
@@ -60,17 +61,21 @@ const lib = {
           onProgress({ ...progress, packages: new Map(progress.packages) });
 
           try {
-            const modules = await fetchPackage(pkgName, entry.version, (p) => {
+            const rawModules = await fetchPackage(pkgName, entry.version, (p) => {
               progress.packages.set(pkgName, { state: "downloading", progress: p });
               onProgress({ ...progress, packages: new Map(progress.packages) });
             });
 
             progress.packages.set(pkgName, { state: "extracting" });
             onProgress({ ...progress, packages: new Map(progress.packages) });
 
-            // Register modules with WASM engine
-            for (const mod of modules) {
-              docsLib.register_module(mod.name, mod.source);
+            // Register modules with WASM engine (parses module name from source)
+            const modules: PackageModule[] = [];
+            for (const raw of rawModules) {
+              const moduleName = docsLib.register_source(raw.path, raw.source);
+              if (moduleName) {
+                modules.push({ path: raw.path, name: moduleName, source: raw.source });
+              }
             }
 
             progress.packages.set(pkgName, { state: "ready", moduleCount: modules.length });
@@ -105,8 +110,8 @@ const lib = {
     docsLib.clear_packages();
   },
 
-  async registerModule(moduleName: string, source: string): Promise<void> {
-    docsLib.register_module(moduleName, source);
+  async registerModule(path: string, source: string): Promise<string | undefined> {
+    return docsLib.register_source(path, source);
   },
 };