@domql/globusa 3.7.6

package/README.md

@@ -0,0 +1,67 @@
+# @symbo.ls/globusa
+
+Parses JavaScript source files and extracts global scope information for DOMQL components. Used by the serialization pipeline to identify module-scoped declarations (constants, functions, imports, mutable state) that component functions reference.
+
+## API
+
+### `parse(code: string)`
+
+Takes a string of JavaScript code and returns:
+
+```js
+{
+  imports: [],               // mitosis-style import objects
+  declarations: [],          // strings of non-import/export code
+  exports: [],               // strings of export statements
+  domqlComponents: [],       // [ { name: string|null, code: string }, ... ]
+  linesExcludingImports: [], // all code lines except imports
+  identifiers: []            // strings of declared names at module scope
+}
+```
+
+### Import object format
+
+```js
+{ imports: { localName: 'exportedName' }, path: 'module-path' }
+// e.g. import { createClient as sb } from '@supabase/supabase-js'
+// → { imports: { sb: 'createClient' }, path: '@supabase/supabase-js' }
+```
+
+## Usage
+
+```js
+import { parse } from '@symbo.ls/globusa'
+
+const result = parse(`
+  import { supabase } from './supabase.js'
+
+  const SUPPORTED = ['en', 'ka', 'ru']
+
+  function detectBrowserLang() {
+    return SUPPORTED[0]
+  }
+
+  export const MyComponent = {
+    onClick: (e, el) => el.scope.detectBrowserLang()
+  }
+`)
+
+result.imports     // [{ imports: { supabase: 'supabase' }, path: './supabase.js' }]
+result.identifiers // ['SUPPORTED', 'detectBrowserLang']
+result.declarations // ['const SUPPORTED = [...]', 'function detectBrowserLang() { ... }']
+```
+
+## Role in serialization pipeline
+
+When components are serialized for transport (push/publish), functions are stringified via `.toString()`. Module-scoped references (constants, helpers, imports) become free variables that break at `eval()` time.
+
+Globusa parses the **original source** to identify these references, enabling the CLI to:
+1. Extract them into `context.globalScope`
+2. Rewrite function strings to use `el.scope.X` (globalScope is in the scope prototype chain)
+3. Provide runtime resolution for external module dependencies
+
+## Dependencies
+
+- `@babel/parser` — JavaScript parsing
+- `@babel/traverse` — AST traversal
+- `@babel/types` — AST node type checks