@stream44.studio/encapsulate 0.4.0-rc.29 → 0.4.0-rc.31

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.29",
+    "version": "0.4.0-rc.31",
     "license": "MIT",
     "repository": {
         "type": "git",

package/src/encapsulate.ts

@@ -731,12 +731,20 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 const ownSelf = merge({}, defaultInstance, defaultPropertyValues, ...Object.values(mergedValuesByContract))
 
                 // Convert relative paths to absolute for metadata exposure
+                // When a CST exists with a source moduleFilepath, use it to derive the absolute path.
+                // This ensures that projected capsules (loaded from .~o/encapsulate.dev/caps/...)
+                // still expose the original source filepath, not the projected filepath.
+                const originalAbsoluteModuleFilepath = cst?.source?.moduleFilepath
+                    ? (cst.source.moduleFilepath.startsWith('/')
+                        ? cst.source.moduleFilepath
+                        : join(spine.spineOptions.spineFilesystemRoot || '', cst.source.moduleFilepath))
+                    : absoluteModuleFilepath
                 const absoluteCapsuleSourceLineRef = `${absoluteModuleFilepath}:${importStackLine}`
                 const capsuleMetadataStruct: Record<string, any> = {
                     capsuleName: encapsulateOptions.capsuleName,
                     capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
                     capsuleSourceNameRefHash: cst?.capsuleSourceNameRefHash,
-                    moduleFilepath: absoluteModuleFilepath,
+                    moduleFilepath: originalAbsoluteModuleFilepath,
                     // Root capsule metadata will be populated after extends chain is resolved
                     rootCapsule: {
                         capsuleName: undefined as string | undefined,
@@ -854,7 +862,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 const resolvedRootCapsule = rootCapsule || {
                     capsuleName: encapsulateOptions.capsuleName!,
                     capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
-                    moduleFilepath: absoluteModuleFilepath
+                    moduleFilepath: originalAbsoluteModuleFilepath
                 }
                 capsuleMetadataStruct.rootCapsule.capsuleName = resolvedRootCapsule.capsuleName
                 capsuleMetadataStruct.rootCapsule.capsuleSourceLineRef = resolvedRootCapsule.capsuleSourceLineRef

package/src/spine-contracts/CapsuleSpineContract.v0/Membrane.v0.ts

@@ -1,5 +1,7 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
 import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static.v0"
+import { readFileSync, existsSync } from "node:fs"
+import { dirname, relative, join } from "node:path"
 
 type CallerContext = {
     capsuleSourceLineRef: string
@@ -8,9 +10,9 @@ type CallerContext = {
     capsuleSourceNameRefHash?: string
     capsuleSourceUriLineRefInstanceId?: string
     prop?: string
-    filepath?: string
+    fileUri?: string
     line?: number
-    stack?: Array<{ function?: string, filepath?: string, line?: number, column?: number }>
+    stack?: Array<{ function?: string, fileUri?: string, line?: number, column?: number }>
 }
 
 function CapsuleMembrane(target: Record<string, any>, hooks?: {
@@ -185,7 +187,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                         const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
-                                            callerCtx.filepath = callerInfo.filepath
+                                            callerCtx.fileUri = callerInfo.fileUri
                                             callerCtx.line = callerInfo.line
                                             callerCtx.stack = stackFrames
                                         }
@@ -312,7 +314,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                             const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
                             if (stackFrames.length > 0) {
                                 const callerInfo = extractCallerInfo(stackFrames, 3)
-                                callerCtx.filepath = callerInfo.filepath
+                                callerCtx.fileUri = callerInfo.fileUri
                                 callerCtx.line = callerInfo.line
                                 callerCtx.stack = stackFrames
                             }
@@ -375,7 +377,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                         const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
-                                            callerCtx.filepath = callerInfo.filepath
+                                            callerCtx.fileUri = callerInfo.fileUri
                                             callerCtx.line = callerInfo.line
                                             callerCtx.stack = stackFrames
                                         }
@@ -878,8 +880,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             if (callerCtx.prop) {
                 event.caller.prop = callerCtx.prop
             }
-            if (callerCtx.filepath) {
-                event.caller.filepath = callerCtx.filepath
+            if (callerCtx.fileUri) {
+                event.caller.fileUri = callerCtx.fileUri
             }
             if (callerCtx.line) {
                 event.caller.line = callerCtx.line
@@ -975,9 +977,67 @@ CapsuleSpineContract['#'] = '@stream44.studio/encapsulate/spine-contracts/Capsul
 
 
 
-function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Array<{ function?: string, filepath?: string, line?: number, column?: number }> {
+// Cache for synchronous npm URI lookups (directory -> package name or null)
+const npmUriCache = new Map<string, string | null>()
+
+function constructNpmUriSync(absoluteFilepath: string): string | null {
+    // Only process absolute paths — skip V8 internal markers like "native", "node:*", etc.
+    if (!absoluteFilepath.startsWith('/')) {
+        return null
+    }
+
+    // Check for /node_modules/ in the path — use the last occurrence to handle nested node_modules
+    const nodeModulesMarker = '/node_modules/'
+    const lastIdx = absoluteFilepath.lastIndexOf(nodeModulesMarker)
+    if (lastIdx !== -1) {
+        return absoluteFilepath.substring(lastIdx + nodeModulesMarker.length)
+    }
+
+    let currentDir = dirname(absoluteFilepath)
+    const maxDepth = 20
+
+    for (let i = 0; i < maxDepth; i++) {
+        if (npmUriCache.has(currentDir)) {
+            const cachedName = npmUriCache.get(currentDir)
+            if (cachedName) {
+                const relativeFromPackage = relative(currentDir, absoluteFilepath)
+                return `${cachedName}/${relativeFromPackage}`
+            }
+            // null means no package.json with name found at this level, continue up
+            const parentDir = dirname(currentDir)
+            if (parentDir === currentDir) break
+            currentDir = parentDir
+            continue
+        }
+
+        const packageJsonPath = join(currentDir, 'package.json')
+        try {
+            if (existsSync(packageJsonPath)) {
+                const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+                const packageName = packageJson.name
+                npmUriCache.set(currentDir, packageName || null)
+                if (packageName) {
+                    const relativeFromPackage = relative(currentDir, absoluteFilepath)
+                    return `${packageName}/${relativeFromPackage}`
+                }
+            } else {
+                npmUriCache.set(currentDir, null)
+            }
+        } catch {
+            npmUriCache.set(currentDir, null)
+        }
+
+        const parentDir = dirname(currentDir)
+        if (parentDir === currentDir) break
+        currentDir = parentDir
+    }
+
+    return null
+}
+
+function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Array<{ function?: string, fileUri?: string, line?: number, column?: number }> {
     const lines = stack.split('\n')
-    const result: Array<{ function?: string, filepath?: string, line?: number, column?: number }> = []
+    const result: Array<{ function?: string, fileUri?: string, line?: number, column?: number }> = []
 
     // Skip first line (Error message), then collect ALL frames
     for (let i = 1; i < lines.length; i++) {
@@ -989,9 +1049,11 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
         // "at functionName (file:line:column)"
         const match = line.match(/at\s+(.+)/)
         if (match) {
-            const frame: { function?: string, filepath?: string, line?: number, column?: number } = {}
+            const frame: { function?: string, fileUri?: string, line?: number, column?: number } = {}
             const content = match[1]
 
+            let rawFilepath: string | undefined
+
             // Try to extract function name and location
             const funcMatch = content.match(/^(.+?)\s+\((.+)\)$/)
             if (funcMatch) {
@@ -1004,7 +1066,7 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
                 const location = funcMatch[2]
                 const locMatch = location.match(/^(.+):(\d+):(\d+)$/)
                 if (locMatch) {
-                    frame.filepath = locMatch[1]
+                    rawFilepath = locMatch[1]
                     frame.line = parseInt(locMatch[2], 10)
                     frame.column = parseInt(locMatch[3], 10)
                 }
@@ -1012,25 +1074,32 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
                 // No function name: "/path/to/file:line:column"
                 const locMatch = content.match(/^(.+):(\d+):(\d+)$/)
                 if (locMatch) {
-                    frame.filepath = locMatch[1]
+                    rawFilepath = locMatch[1]
                     frame.line = parseInt(locMatch[2], 10)
                     frame.column = parseInt(locMatch[3], 10)
                 }
             }
 
-            // Convert absolute paths to relative paths if spineFilesystemRoot is provided
-            if (frame.filepath && spineFilesystemRoot) {
-                if (frame.filepath.startsWith(spineFilesystemRoot)) {
-                    frame.filepath = frame.filepath.slice(spineFilesystemRoot.length)
-                    // Remove leading slash if present
-                    if (frame.filepath.startsWith('/')) {
-                        frame.filepath = frame.filepath.slice(1)
+            // Convert absolute filepaths to npm URIs
+            if (rawFilepath) {
+                const npmUri = constructNpmUriSync(rawFilepath)
+                if (npmUri) {
+                    // Strip file extension from URI for consistency
+                    frame.fileUri = npmUri.replace(/\.(ts|tsx|js|jsx)$/, '')
+                } else if (spineFilesystemRoot && rawFilepath.startsWith(spineFilesystemRoot)) {
+                    // Fallback: use relative path from spine root if npm URI not resolvable
+                    let relativePath = rawFilepath.slice(spineFilesystemRoot.length)
+                    if (relativePath.startsWith('/')) {
+                        relativePath = relativePath.slice(1)
                     }
+                    frame.fileUri = relativePath
+                } else {
+                    frame.fileUri = rawFilepath
                 }
             }
 
             // Include all frames, even if incomplete
-            if (frame.filepath || frame.function) {
+            if (frame.fileUri || frame.function) {
                 result.push(frame)
             }
         }
@@ -1038,14 +1107,14 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
     return result
 }
 
-function extractCallerInfo(stack: Array<{ function?: string, filepath?: string, line?: number, column?: number }>, offset: number = 0) {
+function extractCallerInfo(stack: Array<{ function?: string, fileUri?: string, line?: number, column?: number }>, offset: number = 0) {
     // Use offset to skip frames in the stack
     // offset 0 = first frame, offset 1 = second frame, etc.
 
     if (offset < stack.length) {
         const frame = stack[offset]
         return {
-            filepath: frame.filepath,
+            fileUri: frame.fileUri,
             line: frame.line
         }
     }
@@ -1053,7 +1122,7 @@ function extractCallerInfo(stack: Array<{ function?: string, filepath?: string,
     // Fallback to first frame if offset is out of bounds
     if (stack.length > 0) {
         return {
-            filepath: stack[0].filepath,
+            fileUri: stack[0].fileUri,
             line: stack[0].line
         }
     }

package/src/spine-contracts/CapsuleSpineContract.v0/README.md

@@ -397,7 +397,7 @@ Both implement the same property mapping logic. The difference is observability.
 | `call` | Function invoked | `{ target, args, eventIndex }` |
 | `call-result` | Function returns | `{ target, result, callEventIndex }` |
 
-Events include `caller` context (source capsule, property, filepath, line) when `enableCallerStackInference` is enabled. Memoized results are tagged with `memoized: true`.
+Events include `caller` context (source capsule, property, fileUri, line) when `enableCallerStackInference` is enabled. Memoized results are tagged with `memoized: true`.
 
 ### SpineRuntime & run()
 

package/src/static-analyzer.v0.ts

@@ -1006,7 +1006,7 @@ function extractModuleLocalCode(
         if (funcDecl) {
             // Analyze the function to see if it's self-contained
             const dependencies = new Set<string>()
-            const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+            const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
             if (isContained) {
                 // Mark this as module-local in ambient references
@@ -1034,9 +1034,33 @@ function extractModuleLocalCode(
                 // Collect the main function
                 collectFunction(name)
 
-                // Collect all dependencies
+                // Collect all dependencies (functions and variables)
                 for (const dep of dependencies) {
                     collectFunction(dep)
+
+                    // Also collect module-local variable dependencies
+                    const depVarDecl = moduleLocalVariables.get(dep)
+                    if (depVarDecl && !processed.has(dep)) {
+                        processed.add(dep)
+                        const varStatement = depVarDecl.parent?.parent
+                        if (varStatement && ts.isVariableStatement(varStatement)) {
+                            const varCode = varStatement.getText(sourceFile)
+                            collectedCode.push(varCode)
+                            if (!moduleLocalCode[dep]) {
+                                moduleLocalCode[dep] = varCode
+                            }
+                        }
+                        // Mark the variable dependency in ambient references
+                        if (!ambientReferences[dep]) {
+                            ambientReferences[dep] = { type: 'module-local' }
+                        }
+                        // Recursively collect transitive variable dependencies
+                        collectTransitiveVariableDependencies(
+                            depVarDecl, sourceFile, importMap, assignmentMap,
+                            moduleLocalFunctions, moduleLocalVariables,
+                            ambientReferences, moduleLocalCode
+                        )
+                    }
                 }
 
                 // Store the collected code (main function with all dependencies)
@@ -1087,7 +1111,7 @@ function extractModuleLocalCode(
 
         // Analyze if it's self-contained
         const dependencies = new Set<string>()
-        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
         if (isContained) {
             // Add this function to moduleLocalCode
@@ -1214,14 +1238,15 @@ function collectTransitiveVariableDependencies(
     visit(varDecl.initializer)
 }
 
-// Analyze if a function is self-contained (only depends on other module-local functions or builtins)
+// Analyze if a function is self-contained (only depends on other module-local functions, variables, or builtins)
 function analyzeFunctionDependencies(
     funcDecl: ts.FunctionDeclaration,
     sourceFile: ts.SourceFile,
     importMap: Map<string, { importSpecifier: string, moduleUri: string }>,
     assignmentMap: Map<string, { importSpecifier: string, moduleUri: string }>,
     moduleLocalFunctions: Map<string, ts.FunctionDeclaration>,
-    dependencies: Set<string>
+    dependencies: Set<string>,
+    moduleLocalVariables?: Map<string, ts.VariableDeclaration>
 ): boolean {
     const localIdentifiers = new Set<string>()
     const nestedFunctionScopes = new Map<ts.Node, Set<string>>()
@@ -1348,6 +1373,12 @@ function analyzeFunctionDependencies(
                 return
             }
 
+            // Check if it's a module-local variable - add as dependency
+            if (moduleLocalVariables?.has(identifierName)) {
+                dependencies.add(identifierName)
+                return
+            }
+
             // Check if it's a module-global builtin - allowed
             if (MODULE_GLOBAL_BUILTINS.has(identifierName)) {
                 return
@@ -1681,7 +1712,7 @@ function extractCapsuleAmbientReferences(
                     if (funcDecl) {
                         // Analyze if it's self-contained
                         const dependencies = new Set<string>()
-                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
                         if (isContained) {
                             // Mark as module-local
@@ -1689,7 +1720,7 @@ function extractCapsuleAmbientReferences(
                                 type: 'module-local'
                             }
 
-                            // Add import dependencies from the function's body
+                            // Add import/variable dependencies from the function's body
                             for (const depName of dependencies) {
                                 if (!ambientRefs[depName]) {
                                     const depImportInfo = importMap.get(depName)
@@ -1707,6 +1738,14 @@ function extractCapsuleAmbientReferences(
                                                 importSpecifier: depAssignmentInfo.importSpecifier,
                                                 moduleUri: depAssignmentInfo.moduleUri
                                             }
+                                        } else if (moduleLocalVariables.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
+                                        } else if (moduleLocalFunctions.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
                                         }
                                     }
                                 }
@@ -2053,7 +2092,7 @@ function extractAndValidateAmbientReferences(
                     if (funcDecl) {
                         // Analyze if it's self-contained
                         const dependencies = new Set<string>()
-                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
                         if (isContained) {
                             // Mark as module-local
@@ -2061,7 +2100,7 @@ function extractAndValidateAmbientReferences(
                                 type: 'module-local'
                             }
 
-                            // Add import dependencies from the function's body
+                            // Add import/variable dependencies from the function's body
                             for (const depName of dependencies) {
                                 if (!ambientRefs[depName]) {
                                     const depImportInfo = importMap.get(depName)
@@ -2079,6 +2118,14 @@ function extractAndValidateAmbientReferences(
                                                 importSpecifier: depAssignmentInfo.importSpecifier,
                                                 moduleUri: depAssignmentInfo.moduleUri
                                             }
+                                        } else if (moduleLocalVariables.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
+                                        } else if (moduleLocalFunctions.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
                                         }
                                     }
                                 }