tjs-lang 0.8.1 → 0.8.3

package/editors/codemirror/ajs-language.ts

@@ -50,6 +50,8 @@ import {
   FORBIDDEN_PATTERN,
 } from '../ajs-syntax'
 import { FORBIDDEN_KEYWORDS as TJS_FORBIDDEN_LIST } from '../tjs-syntax'
+import { collectScopeSymbols } from '../scope-symbols'
+import type { IntrospectMember } from '../introspect-value'
 
 /**
  * Forbidden keywords in AsyncJS - these will be highlighted as errors
@@ -341,6 +343,26 @@ export interface AutocompleteConfig {
    * e.g., { elements: Proxy, div: HTMLDivElement }
    */
   getLiveBindings?: () => Record<string, any> | undefined
+  /**
+   * Async member completion from the introspection bridge: given a dotted path
+   * (`todoApp.items`), returns the value's REAL runtime members from the user's
+   * executed scope in a sandbox — including proxy-generated ones nothing static
+   * can see. Used as a fallback when the path doesn't resolve in sync bindings.
+   */
+  getMembers?: (path: string) => Promise<IntrospectMember[] | undefined>
+}
+
+/** Map a serializable introspection member into a CodeMirror completion. */
+function memberToCompletion(m: IntrospectMember): CMCompletion {
+  if (m.type === 'method') {
+    const hasArgs = m.detail !== '()'
+    return snippetCompletion(`${m.label}(${hasArgs ? '${1}' : ''})`, {
+      label: m.label,
+      type: 'method',
+      detail: m.detail,
+    })
+  }
+  return { label: m.label, type: 'property', detail: m.detail }
 }
 
 // TJS keywords with snippets
@@ -616,6 +638,41 @@ function extractVariables(source: string, position: number): CMCompletion[] {
   return completions
 }
 
+/**
+ * Scope-aware locals: replaces the regex `extractFunctions`/`extractVariables`
+ * (which missed ALL destructuring — and the tosijs examples bind everything via
+ * destructuring, so nothing was suggested). Parses with acorn (acorn-loose
+ * fallback for mid-edit source) and walks binding patterns. Falls back to the
+ * regex extractors only if parsing yields nothing, so the list never goes blank.
+ */
+function completionsFromScope(
+  source: string,
+  position: number
+): CMCompletion[] {
+  const symbols = collectScopeSymbols(source, position)
+  if (symbols.length === 0) {
+    return [...extractFunctions(source), ...extractVariables(source, position)]
+  }
+  return symbols.map((s) => {
+    const detail =
+      s.origin?.member && s.origin.expr
+        ? `∈ ${s.origin.expr}`
+        : s.kind === 'import' && s.origin?.module
+        ? `import '${s.origin.module}'`
+        : s.kind === 'parameter'
+        ? 'parameter'
+        : undefined
+    if (s.kind === 'function') {
+      return snippetCompletion(`${s.name}($1)`, {
+        label: s.name,
+        type: 'function',
+        detail,
+      })
+    }
+    return { label: s.name, type: 'variable', detail }
+  })
+}
+
 /**
  * Curated property completions for common globals
  * These are hand-picked for usefulness with proper type signatures
@@ -1203,7 +1260,7 @@ function introspectObject(obj: any): CMCompletion[] {
 
         if (valueType === 'function') {
           // Try to get function signature from length
-          const fn = value as Function
+          const fn = value as (...args: unknown[]) => unknown
           const paramCount = fn.length
           const params =
             paramCount > 0
@@ -1263,32 +1320,9 @@ function getCompletionsFromLiveBinding(
   name: string,
   liveBindings?: Record<string, any>
 ): CMCompletion[] {
-  // Debug: log what we're looking for and what we have
-  console.debug(
-    '[autocomplete] Looking for:',
-    name,
-    'in bindings:',
-    liveBindings ? Object.keys(liveBindings) : 'none'
-  )
-
   // First, check if we have a live binding for this name
   if (liveBindings && name in liveBindings) {
-    const value = liveBindings[name]
-    console.debug(
-      '[autocomplete] Found binding:',
-      name,
-      '=',
-      value,
-      'type:',
-      typeof value
-    )
-    const completions = introspectObject(value)
-    console.debug(
-      '[autocomplete] Introspection returned',
-      completions.length,
-      'completions'
-    )
-    return completions
+    return introspectObject(liveBindings[name])
   }
 
   // Special case: if the name looks like it could be an HTML element variable,
@@ -1328,14 +1362,54 @@ function getCompletionsFromLiveBinding(
 }
 
 /**
- * Extract the object name before a dot from source
- * e.g., "console." -> "console", "Math.floor" -> "Math"
+ * Extract the full dotted member path before a dot, e.g. `todoApp.items.` ->
+ * `todoApp.items`. Only plain identifier chains (no calls / index access) — good
+ * enough to walk a live value for member completion.
  */
-function getObjectBeforeDot(source: string, dotPos: number): string | null {
-  // Look backwards from the dot to find the identifier
+function getPathBeforeDot(source: string, dotPos: number): string | null {
   const before = source.slice(0, dotPos)
-  const match = before.match(/(\w+)\s*$/)
-  return match ? match[1] : null
+  const match = before.match(
+    /([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*$/
+  )
+  return match ? match[1].replace(/\s+/g, '') : null
+}
+
+/** Walk a dotted path against a bindings object, returning the resolved value. */
+function resolvePath(path: string, bindings?: Record<string, any>): any {
+  if (!bindings) return undefined
+  const parts = path.split('.')
+  let value: any = bindings[parts[0]]
+  for (let i = 1; i < parts.length && value != null; i++) {
+    try {
+      value = value[parts[i]]
+    } catch {
+      return undefined
+    }
+  }
+  return value
+}
+
+/**
+ * Member completions for a dotted path resolved against live bindings — the
+ * core of introspection-driven completion. `todoApp.items.` resolves the array
+ * and introspects it (push/map/…). Single-segment names that don't resolve fall
+ * back to the element-type heuristic.
+ */
+function getCompletionsFromPath(
+  path: string,
+  liveBindings?: Record<string, any>
+): CMCompletion[] {
+  const value = resolvePath(path, liveBindings)
+  if (
+    value != null &&
+    (typeof value === 'object' || typeof value === 'function')
+  ) {
+    return introspectObject(value)
+  }
+  if (!path.includes('.')) {
+    return getCompletionsFromLiveBinding(path, liveBindings)
+  }
+  return []
 }
 
 /**
@@ -1395,10 +1469,13 @@ function getPlaceholderForParam(name: string, info: any): string {
 }
 
 /**
- * Create TJS/AJS completion source
+ * Create TJS/AJS completion source.
+ * Exported for headless testing — it touches only DOM-free CodeMirror APIs.
  */
-function tjsCompletionSource(config: AutocompleteConfig = {}) {
-  return (context: CMCompletionContext): CompletionResult | null => {
+export function tjsCompletionSource(config: AutocompleteConfig = {}) {
+  return async (
+    context: CMCompletionContext
+  ): Promise<CompletionResult | null> => {
     try {
       // Get word at cursor
       const word = context.matchBefore(/[\w$]*/)
@@ -1434,16 +1511,26 @@ function tjsCompletionSource(config: AutocompleteConfig = {}) {
         if (/expect\s*\([^)]*\)\s*\.$/.test(before)) {
           options = EXPECT_MATCHERS
         } else {
-          // Try to get object name and introspect its properties
-          const objName = getObjectBeforeDot(source, word.from - 1)
-          if (objName) {
-            // First try curated/global completions
-            options = getPropertyCompletions(objName)
-
-            // If no completions found, try live bindings (imports, variables)
+          // Resolve the full dotted path so `todoApp.items.` works, not just
+          // `todoApp.`. Curated/global completions are keyed by a single name.
+          const path = getPathBeforeDot(source, word.from - 1)
+          if (path) {
+            if (!path.includes('.')) {
+              options = getPropertyCompletions(path)
+            }
+            // Then introspect the live value the path resolves to in the sync
+            // bindings (resolved imports).
             if (options.length === 0) {
               const liveBindings = config.getLiveBindings?.()
-              options = getCompletionsFromLiveBinding(objName, liveBindings)
+              options = getCompletionsFromPath(path, liveBindings)
+            }
+            // Finally, the introspection bridge: the user's REAL executed scope
+            // (`todoApp.items` → the live array's members), incl. proxy members.
+            if (options.length === 0 && config.getMembers) {
+              const members = await config.getMembers(path)
+              if (members && members.length) {
+                options = members.map(memberToCompletion)
+              }
             }
           }
         }
@@ -1462,8 +1549,7 @@ function tjsCompletionSource(config: AutocompleteConfig = {}) {
           ...TJS_COMPLETIONS,
           ...RUNTIME_COMPLETIONS,
           ...GLOBAL_COMPLETIONS,
-          ...extractFunctions(source),
-          ...extractVariables(source, pos),
+          ...completionsFromScope(source, pos),
         ]
 
         // Add metadata-based completions if available

package/editors/codemirror/completion-source.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Drives the REAL completion source the playground uses (tjsCompletionSource),
+ * headlessly — its APIs (matchBefore / state.doc / pos / explicit) are DOM-free.
+ *
+ * Regression for the bug where the regex extractor missed destructuring, so the
+ * tosijs todo example (everything bound via destructuring) suggested nothing.
+ */
+import { describe, it, expect } from 'bun:test'
+import { EditorState } from '@codemirror/state'
+import { CompletionContext } from '@codemirror/autocomplete'
+import { tjsCompletionSource } from './ajs-language'
+import type { AutocompleteConfig } from './ajs-language'
+
+const TODO = `import { elements, tosi } from 'tosijs'
+const { todoApp } = tosi({ todoApp: { items: [], newItem: '' } })
+const { h1, ul, template, li, label, input, button } = elements
+`
+
+async function optionsFor(
+  source: string,
+  pos: number = source.length,
+  config: AutocompleteConfig = {}
+) {
+  const state = EditorState.create({ doc: source })
+  const ctx = new CompletionContext(state, pos, /* explicit */ true)
+  const result = await tjsCompletionSource(config)(ctx)
+  return result?.options ?? []
+}
+const labelsFor = async (...args: Parameters<typeof optionsFor>) =>
+  (await optionsFor(...args)).map((o) => o.label)
+
+describe('tjsCompletionSource — scope-aware locals (live provider)', () => {
+  it('suggests destructured bindings from the real todo example', async () => {
+    const labels = await labelsFor(TODO)
+    expect(labels).toContain('todoApp')
+    expect(labels).toContain('h1')
+    expect(labels).toContain('button')
+    expect(labels).toContain('elements')
+  })
+
+  it('completes `tod` to todoApp', async () => {
+    expect(await labelsFor(TODO + 'tod')).toContain('todoApp')
+  })
+
+  it('annotates a destructured binding with its source (∈ elements)', async () => {
+    const opts = await optionsFor(TODO)
+    expect(opts.find((o) => o.label === 'h1')?.detail).toBe('∈ elements')
+  })
+})
+
+describe('tjsCompletionSource — member completion via live bindings (1b-i)', () => {
+  // Stand in for the user's executed scope, live (resolved imports path).
+  const liveBindings = {
+    todoApp: { items: ['bathe the cat'], newItem: '', addItem() {} },
+  }
+  const member = (tail: string) =>
+    labelsFor(`const x = 1\n${tail}`, undefined, {
+      getLiveBindings: () => liveBindings,
+    })
+
+  it('todoApp. → its real properties (items, newItem, addItem)', async () => {
+    const labels = await member('todoApp.')
+    expect(labels).toContain('items')
+    expect(labels).toContain('newItem')
+    expect(labels).toContain('addItem')
+  })
+
+  it('todoApp.items. → array methods (push, map) — nested path resolves', async () => {
+    const labels = await member('todoApp.items.')
+    expect(labels).toContain('push')
+    expect(labels).toContain('map')
+  })
+
+  it('unknown path resolves to nothing (no crash)', async () => {
+    expect(await member('todoApp.nope.')).toEqual([])
+  })
+})
+
+describe('tjsCompletionSource — member completion via the bridge (1b-ii)', () => {
+  // The introspection bridge: async, returns the REAL runtime members for a path
+  // the sync bindings don't know about (the user's own executed scope).
+  const getMembers = async (path: string) => {
+    if (path === 'todoApp')
+      return [
+        { label: 'items', type: 'property' as const, detail: 'object' },
+        { label: 'addItem', type: 'method' as const, detail: '()' },
+      ]
+    if (path === 'todoApp.items')
+      return [{ label: 'push', type: 'method' as const, detail: '(arg1)' }]
+    return []
+  }
+
+  it('falls back to the bridge when sync bindings miss the path', async () => {
+    const labels = await labelsFor('const x = 1\ntodoApp.', undefined, {
+      getMembers,
+    })
+    expect(labels).toContain('items')
+    expect(labels).toContain('addItem')
+  })
+
+  it('bridge resolves a nested path (todoApp.items.push)', async () => {
+    const labels = await labelsFor('const x = 1\ntodoApp.items.', undefined, {
+      getMembers,
+    })
+    expect(labels).toContain('push')
+  })
+
+  it('a method member becomes a callable completion', async () => {
+    const opts = await optionsFor('const x = 1\ntodoApp.', undefined, {
+      getMembers,
+    })
+    expect(opts.find((o) => o.label === 'addItem')?.type).toBe('method')
+  })
+})

package/editors/introspect-value.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'bun:test'
+import { introspectValue, INTROSPECT_VALUE_SOURCE } from './introspect-value'
+
+const labels = (v: unknown) => introspectValue(v).map((m) => m.label)
+const member = (v: unknown, name: string) =>
+  introspectValue(v).find((m) => m.label === name)
+
+describe('introspectValue — serializable runtime introspection', () => {
+  it('object → own properties and methods, typed', () => {
+    const todoApp = { items: [], newItem: '', addItem() {} }
+    const ls = labels(todoApp)
+    expect(ls).toContain('items')
+    expect(ls).toContain('newItem')
+    expect(ls).toContain('addItem')
+    expect(member(todoApp, 'addItem')?.type).toBe('method')
+    expect(member(todoApp, 'newItem')?.type).toBe('property')
+    expect(member(todoApp, 'newItem')?.detail).toBe('string')
+  })
+
+  it('array → inherited methods from the prototype (push, map)', () => {
+    const ls = labels([1, 2, 3])
+    expect(ls).toContain('push')
+    expect(ls).toContain('map')
+    expect(ls).toContain('filter')
+    expect(member([1], 'push')?.type).toBe('method')
+  })
+
+  it('method arity becomes an arg hint', () => {
+    const o = { f(a: unknown, b: unknown) {} }
+    void o.f
+    expect(member(o, 'f')?.detail).toBe('(arg1, arg2)')
+  })
+
+  it('skips constructor and underscore-prefixed members', () => {
+    const ls = labels({ _private: 1, visible: 2 })
+    expect(ls).toContain('visible')
+    expect(ls).not.toContain('_private')
+    expect(ls).not.toContain('constructor')
+  })
+
+  it('introspects a Proxy via own keys (tosijs `elements` shape)', () => {
+    // a proxy that materialises keys on access but DOES report own keys
+    const backing: Record<string, unknown> = { h1: () => {}, div: () => {} }
+    const proxy = new Proxy(backing, {})
+    const ls = labels(proxy)
+    expect(ls).toContain('h1')
+    expect(ls).toContain('div')
+  })
+
+  it('non-objects → nothing; never throws', () => {
+    expect(introspectValue(null)).toEqual([])
+    expect(introspectValue(42)).toEqual([])
+    expect(introspectValue(undefined)).toEqual([])
+  })
+
+  it('is self-contained source (injectable into the sandbox iframe)', () => {
+    // no outer references that would break when eval-ed in another realm
+    expect(INTROSPECT_VALUE_SOURCE).toContain('function introspectValue')
+    expect(INTROSPECT_VALUE_SOURCE).not.toMatch(/\bimport\b/)
+  })
+})

package/editors/introspect-value.ts

@@ -0,0 +1,86 @@
+/**
+ * Serializable runtime introspection — the in-sandbox half of the introspection
+ * bridge. Given a live value, produce a flat list of member descriptors that
+ * survive `postMessage` (plain strings, no functions). The introspection bridge
+ * injects this function's SOURCE into the sandbox iframe (via `.toString()`), so
+ * it must be **self-contained** — no imports, no outer references.
+ *
+ * It mirrors the editor's own `introspectObject` (own keys first — important for
+ * proxies that cache accesses, like tosijs `elements` — then the prototype
+ * chain), but returns data instead of CodeMirror completions. The provider maps
+ * these descriptors back into completions on the parent side.
+ */
+
+export interface IntrospectMember {
+  label: string
+  /** 'method' for callables, else 'property'. */
+  type: 'method' | 'property'
+  /** typeof for properties, an arg hint for methods. */
+  detail: string
+}
+
+export function introspectValue(value: unknown): IntrospectMember[] {
+  if (
+    value == null ||
+    (typeof value !== 'object' && typeof value !== 'function')
+  ) {
+    return []
+  }
+
+  const out: IntrospectMember[] = []
+  const seen = new Set<string>()
+
+  const push = (key: string, v: unknown) => {
+    if (key === 'constructor' || key.startsWith('_') || seen.has(key)) return
+    seen.add(key)
+    if (typeof v === 'function') {
+      const arity = (v as { length?: number }).length ?? 0
+      const params =
+        arity > 0
+          ? Array.from({ length: arity }, (_, i) => `arg${i + 1}`).join(', ')
+          : ''
+      out.push({ label: key, type: 'method', detail: `(${params})` })
+    } else {
+      out.push({ label: key, type: 'property', detail: typeof v })
+    }
+  }
+
+  // Own enumerable keys first — handles Proxies that materialise on access.
+  try {
+    for (const key of Object.keys(value as object)) {
+      try {
+        push(key, (value as Record<string, unknown>)[key])
+      } catch {
+        /* getter threw — skip */
+      }
+    }
+  } catch {
+    /* Object.keys failed — continue with the prototype walk */
+  }
+
+  // Own properties + prototype chain (inherited methods like Array#push).
+  let current: any = value
+  while (
+    current &&
+    current !== Object.prototype &&
+    current !== Function.prototype
+  ) {
+    for (const key of Object.getOwnPropertyNames(current)) {
+      if (key === 'constructor' || key.startsWith('_') || seen.has(key))
+        continue
+      try {
+        const d = Object.getOwnPropertyDescriptor(current, key)
+        const v = d?.value ?? (d?.get ? '[getter]' : undefined)
+        push(key, v)
+      } catch {
+        /* property threw on access — skip */
+      }
+    }
+    current = Object.getPrototypeOf(current)
+  }
+
+  return out
+}
+
+/** The function source, for injection into the sandbox iframe. */
+export const INTROSPECT_VALUE_SOURCE = introspectValue.toString()

package/editors/scope-symbols.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'bun:test'
+import { collectScopeSymbols, type ScopeSymbol } from './scope-symbols'
+
+// `|` marks the cursor; returns source without it + the offset.
+function at(src: string): { source: string; position: number } {
+  const position = src.indexOf('|')
+  if (position === -1) return { source: src, position: src.length }
+  return { source: src.slice(0, position) + src.slice(position + 1), position }
+}
+
+const names = (syms: ScopeSymbol[]) => syms.map((s) => s.name).sort()
+const find = (syms: ScopeSymbol[], n: string) => syms.find((s) => s.name === n)
+
+describe('collectScopeSymbols — destructuring-aware scope', () => {
+  it('object destructuring from a call (the bug: `const { todoApp } = tosi(...)`)', () => {
+    const { source } = at(`const { todoApp } = tosi({ items: [] })`)
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toContain('todoApp')
+    expect(find(syms, 'todoApp')?.origin?.via).toBe('destructure')
+    expect(find(syms, 'todoApp')?.origin?.expr).toBe('tosi({ items: [] })')
+  })
+
+  it('multiple names destructured from an identifier carry member + source', () => {
+    const { source } = at(`const { h1, ul, button } = elements`)
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toEqual(['button', 'h1', 'ul'])
+    // origin is the introspection hook: `elements.h1`
+    expect(find(syms, 'h1')?.origin?.expr).toBe('elements')
+    expect(find(syms, 'h1')?.origin?.member).toBe('h1')
+  })
+
+  it('array destructuring, holes skipped', () => {
+    const { source } = at(`const [first, , third] = items`)
+    expect(names(collectScopeSymbols(source))).toEqual(['first', 'third'])
+  })
+
+  it('rename binds the new name, records the source key', () => {
+    const { source } = at(`const { color: c } = theme`)
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toEqual(['c'])
+    expect(find(syms, 'c')?.origin?.member).toBe('color')
+  })
+
+  it('defaults and rest', () => {
+    const a = collectScopeSymbols(at(`const { x = 1, ...rest } = o`).source)
+    expect(names(a)).toEqual(['rest', 'x'])
+    const b = collectScopeSymbols(at(`const [head, ...tail] = xs`).source)
+    expect(names(b)).toEqual(['head', 'tail'])
+  })
+
+  it('imports (named, default, namespace, renamed)', () => {
+    const { source } = at(
+      `import def, { tosi, elements as els } from 'tosijs'\nimport * as ns from 'x'`
+    )
+    const syms = collectScopeSymbols(source)
+    expect(names(syms)).toEqual(['def', 'els', 'ns', 'tosi'])
+    expect(find(syms, 'tosi')?.origin?.module).toBe('tosijs')
+    expect(find(syms, 'els')?.kind).toBe('import')
+  })
+
+  it('function name in scope; params only inside the body', () => {
+    const inside = at(`function ship(to, qty) {\n  |\n}`)
+    const syms = collectScopeSymbols(inside.source, inside.position)
+    expect(names(syms)).toEqual(['qty', 'ship', 'to'])
+
+    const outside = at(`function ship(to, qty) {}\n|`)
+    const syms2 = collectScopeSymbols(outside.source, outside.position)
+    expect(names(syms2)).toContain('ship')
+    expect(names(syms2)).not.toContain('to')
+  })
+
+  it('destructured params too', () => {
+    const inside = at(`function render({ title, items }) {\n  |\n}`)
+    const syms = collectScopeSymbols(inside.source, inside.position)
+    expect(names(syms)).toEqual(['items', 'render', 'title'])
+  })
+
+  it('position-scoped: declarations after the cursor are excluded', () => {
+    const { source, position } = at(`const before = 1\n|\nconst after = 2`)
+    const syms = collectScopeSymbols(source, position)
+    expect(names(syms)).toContain('before')
+    expect(names(syms)).not.toContain('after')
+  })
+
+  it('resilient to mid-edit / not-yet-valid source (acorn-loose)', () => {
+    // trailing incomplete line shouldn't blank out the earlier bindings
+    const { source, position } = at(`const { todoApp } = tosi({})\ntodoApp.i|`)
+    const syms = collectScopeSymbols(source, position)
+    expect(names(syms)).toContain('todoApp')
+  })
+
+  it('the real tosijs todo example surfaces every binding', () => {
+    const src = `import { elements, tosi } from 'tosijs'
+const { todoApp } = tosi({ todoApp: { items: [], newItem: '' } })
+const { h1, ul, template, li, label, input, button } = elements
+`
+    const got = names(collectScopeSymbols(src))
+    for (const n of [
+      'elements',
+      'tosi',
+      'todoApp',
+      'h1',
+      'ul',
+      'template',
+      'li',
+      'label',
+      'input',
+      'button',
+    ]) {
+      expect(got).toContain(n)
+    }
+  })
+})