tjs-lang 0.7.7 → 0.8.0

package/src/lang/parser-types.ts

@@ -15,6 +15,17 @@ export interface ParseOptions {
    * When true, skips == to Is() transformation since the VM handles == correctly.
    */
   vmTarget?: boolean
+  /**
+   * Optional ModuleLoader for cross-file `wasm function` composition (Phase 3).
+   * When provided, imports are resolved at transpile time and matching wasm
+   * functions are composed into the consumer's WebAssembly.Module. When
+   * omitted, imports are preserved verbatim (the default — runtime resolves
+   * them as before).
+   *
+   * Type is left as `any` here to avoid a circular import with module-loader.ts;
+   * callers should pass a `ModuleLoader` instance.
+   */
+  moduleLoader?: any
 }
 
 /**
@@ -37,6 +48,21 @@ export interface ParseOptions {
 export interface WasmBlock {
   /** Unique ID for this block */
   id: string
+  /**
+   * Declared function name (only set for top-level `wasm function NAME(...)`
+   * declarations — Phase 1+). Used by Phase 3 cross-file composition to
+   * match an imported symbol against a wasm function declaration. Inline
+   * `wasm {}` blocks have no name and don't participate in composition.
+   */
+  name?: string
+  /**
+   * Declared return-type annotation, e.g. `'f64'`. Only set for top-level
+   * `wasm function NAME(...): RetType` declarations; presence/absence is
+   * used to determine `hasReturn` BEFORE the body is compiled, so the
+   * function index map can be built up-front for wasm-to-wasm calls.
+   * Inline blocks have no declared return type.
+   */
+  returnType?: string
   /** The body (JS subset that compiles to WASM, also used as fallback) */
   body: string
   /** Explicit fallback body (only if different from body) */
@@ -83,6 +109,13 @@ export interface PreprocessOptions {
    * Default: false (transform == to Is() for TJS code running in regular JS)
    */
   vmTarget?: boolean
+  /**
+   * Optional ModuleLoader for cross-file `wasm function` composition (Phase 3).
+   * See ParseOptions.moduleLoader for details.
+   */
+  moduleLoader?: any
+  /** Path of the file being preprocessed (used as importer context). */
+  filename?: string
 }
 
 /**
@@ -144,6 +177,8 @@ export interface TjsModes {
   tjsSafeEval: boolean
   /** TjsNoVar: var declarations are syntax errors */
   tjsNoVar: boolean
+  /** TjsSafeAssign: let declarations need an initializer or `: example` annotation; literal undefined/null/void 0 assigned to typed lets is flagged */
+  tjsSafeAssign: boolean
 }
 
 /**

package/src/lang/parser.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'bun:test'
 import { transpile, ajs, tjs } from './index'
-import { preprocess } from './parser'
+import { preprocess, parse } from './parser'
 import { createRuntime, isMonadicError } from './runtime'
 
 describe('Transpiler', () => {
@@ -1067,4 +1067,76 @@ test 'always fails' { throw new Error('intentional') }
       expect(varSetStep.value.op).toBe('??')
     })
   })
+
+  describe('stray `=>` on function declarations', () => {
+    it('errors clearly on `function f(...): T => { body }`', () => {
+      // A common mistake — writing arrow-function syntax on a regular
+      // function declaration. Without the dedicated check, the `=>` falls
+      // through to Acorn which complains at a misleading position.
+      expect(() =>
+        tjs(`function f(s: '', n = 0): 0 => {
+  return s.length + n
+}`)
+      ).toThrow(/Unexpected '=>' after function declaration/)
+    })
+
+    it('errors with column pointing at the `=>` (not earlier in the line)', () => {
+      let caught: any
+      try {
+        tjs(`function f(): 0 => { return 0 }`)
+      } catch (e) {
+        caught = e
+      }
+      expect(caught).toBeDefined()
+      // The `=>` is at column 17 (1-indexed): `function f(): 0 ` is 16 chars
+      expect(caught.column).toBe(16)
+    })
+
+    it('does not error on regular function declarations', () => {
+      expect(() =>
+        tjs(`function f(s: ''): 0 { return s.length }`)
+      ).not.toThrow()
+    })
+
+    it('does not error on real arrow function expressions', () => {
+      expect(() => tjs(`const f = (s = '') => s.length`)).not.toThrow()
+    })
+  })
+
+  describe('let type annotations (TjsSafeAssign)', () => {
+    it("strips `: <example>` from `let x: ''` and records annotation", () => {
+      const r = parse(`let x: ''`)
+      expect(r.letAnnotations.get('x')).toBe("''")
+    })
+
+    it('strips `: <example>` from `let x: 0 = 5` and keeps the initializer', () => {
+      const r = parse(`let x: 0 = 5`)
+      expect(r.letAnnotations.get('x')).toBe('0')
+      const decl = r.ast.body[0] as any
+      expect(decl.type).toBe('VariableDeclaration')
+      expect(decl.declarations[0].init).not.toBeNull()
+    })
+
+    it('handles object-literal example with nested braces', () => {
+      const r = parse(
+        `function f() { let result: { ok: false }; return result }`
+      )
+      expect(r.letAnnotations.get('result')).toBe('{ ok: false }')
+    })
+
+    it('does not strip `:` inside string literals', () => {
+      const r = parse(`let s = 'a:b:c'`)
+      expect(r.letAnnotations.size).toBe(0)
+    })
+
+    it('TjsSafeAssign mode is on by default in native TJS', () => {
+      const r = parse(`let x = 0`)
+      expect(r.tjsModes.tjsSafeAssign).toBe(true)
+    })
+
+    it('TjsCompat directive disables TjsSafeAssign', () => {
+      const r = parse(`TjsCompat\nlet x = 0`)
+      expect(r.tjsModes.tjsSafeAssign).toBe(false)
+    })
+  })
 })

package/src/lang/parser.ts

@@ -31,6 +31,8 @@ import { transformParenExpressions } from './parser-params'
 import {
   transformTryWithoutCatch,
   extractWasmBlocks,
+  extractWasmFunctions,
+  composeImportedWasmFunctions,
   transformIsOperators,
   insertAsiProtection,
   transformEqualityToStructural,
@@ -51,6 +53,7 @@ import {
   transformConstBang,
   transformBangAccess,
   transformExtensionCalls,
+  transformLetTypeAnnotations,
 } from './parser-transforms'
 
 // Re-export transformExtensionCalls for js.ts
@@ -120,6 +123,7 @@ export function preprocess(
   testErrors: string[]
   polymorphicNames: Set<string>
   extensions: Map<string, Set<string>>
+  letAnnotations: Map<string, string>
 } {
   const originalSource = source
   let moduleSafety: 'none' | 'inputs' | 'all' | undefined
@@ -143,6 +147,7 @@ export function preprocess(
         tjsStandard: false,
         tjsSafeEval: false,
         tjsNoVar: false,
+        tjsSafeAssign: false,
       }
     : {
         tjsEquals: true,
@@ -152,6 +157,7 @@ export function preprocess(
         tjsStandard: true,
         tjsSafeEval: false, // opt-in only (adds import)
         tjsNoVar: true,
+        tjsSafeAssign: true,
       }
 
   // Safety: native TJS defaults to 'inputs' (runtime default),
@@ -180,7 +186,7 @@ export function preprocess(
   // TjsCompat disables all TJS modes (useful for native TJS opting out)
   // Individual modes: TjsEquals, TjsClass, TjsDate, TjsNoeval, TjsStandard, TjsSafeEval
   const directivePattern =
-    /^(\s*(?:\/\/[^\n]*\n|\/\*[\s\S]*?\*\/\s*)*)\s*(TjsStrict|TjsCompat|TjsEquals|TjsClass|TjsDate|TjsNoeval|TjsNoVar|TjsStandard|TjsSafeEval)\b/
+    /^(\s*(?:\/\/[^\n]*\n|\/\*[\s\S]*?\*\/\s*)*)\s*(TjsStrict|TjsCompat|TjsEquals|TjsClass|TjsDate|TjsNoeval|TjsNoVar|TjsStandard|TjsSafeEval|TjsSafeAssign)\b/
 
   let match
   while ((match = source.match(directivePattern))) {
@@ -194,6 +200,7 @@ export function preprocess(
       tjsModes.tjsNoeval = true
       tjsModes.tjsNoVar = true
       tjsModes.tjsStandard = true
+      tjsModes.tjsSafeAssign = true
     } else if (directive === 'TjsCompat') {
       // Disable all TJS modes (JS-compatible)
       tjsModes.tjsEquals = false
@@ -203,6 +210,7 @@ export function preprocess(
       tjsModes.tjsNoVar = false
       tjsModes.tjsStandard = false
       tjsModes.tjsSafeEval = false
+      tjsModes.tjsSafeAssign = false
     } else if (directive === 'TjsEquals') {
       tjsModes.tjsEquals = true
     } else if (directive === 'TjsClass') {
@@ -217,6 +225,8 @@ export function preprocess(
       tjsModes.tjsStandard = true
     } else if (directive === 'TjsSafeEval') {
       tjsModes.tjsSafeEval = true
+    } else if (directive === 'TjsSafeAssign') {
+      tjsModes.tjsSafeAssign = true
     }
 
     // Remove the directive from source
@@ -247,6 +257,21 @@ export function preprocess(
   // Must happen before acorn parsing since !. is not valid JS
   source = transformBangAccess(source)
 
+  // Transform `let x: <example>` declarations: strip annotation and record
+  // varName -> example. Must happen before paren transforms so the colon
+  // is not confused with TS-style annotations on params/returns.
+  const letAnnoResult = transformLetTypeAnnotations(source)
+  source = letAnnoResult.source
+  const letAnnotations = letAnnoResult.annotations
+
+  // Extract `wasm function NAME(...) { ... }` declarations EARLY, before
+  // any source-level transforms that would mangle wasm-body text. In
+  // particular, the equality transforms below rewrite `==` to `Eq()` and
+  // `Is`/`IsNot` to function calls — wasm bodies use literal operators
+  // and shouldn't be affected.
+  const wasmFunctions = extractWasmFunctions(source)
+  source = wasmFunctions.source
+
   // Transform Is/IsNot infix operators to function calls
   // a Is b -> Is(a, b)
   // a IsNot b -> IsNot(a, b)
@@ -275,6 +300,18 @@ export function preprocess(
   // Foo = ... -> const Foo = ...
   source = transformBareAssignments(source)
 
+  // Phase 3: cross-file wasm-function composition. When a ModuleLoader is
+  // supplied, resolve `import { ... } from '<spec>'` statements at transpile
+  // time. Any imported names that correspond to `wasm function` declarations
+  // in the source module get pulled into the consumer's wasm module, with
+  // the import statement rewritten to a local JS wrapper. No loader supplied
+  // = no behavior change (imports stay verbatim, runtime resolves them).
+  const importedWasm = composeImportedWasmFunctions(source, {
+    loader: options.moduleLoader,
+    importerPath: options.filename,
+  })
+  source = importedWasm.source
+
   // Unified paren expression transformer
   // Handles: function params, arrow params, return types, safe/unsafe markers
   // Model: open paren can be ( or (? or (!, close can be ) or )-> or )-? or )-!
@@ -309,9 +346,24 @@ export function preprocess(
   source = polyResult.source
 
   // Extract WASM blocks: wasm(args) { ... } fallback { ... }
+  // `wasm function` declarations are already extracted earlier in the pipeline
+  // (see above, before transformParenExpressions). This finds the remaining
+  // inline `wasm { ... }` blocks inside regular tjs functions.
   const wasmBlocks = extractWasmBlocks(source)
   source = wasmBlocks.source
 
+  // Combine all flavors of wasm blocks for the downstream emitter.
+  // They're indistinguishable from the compiler's perspective — all have
+  // an id, body, captures, and need the same module composition treatment.
+  //   - wasmFunctions: top-level `wasm function NAME(...)` decls in this file
+  //   - importedWasm:  cross-file `wasm function`s pulled in via Phase 3
+  //   - wasmBlocks:    inline `wasm { ... }` blocks nested in tjs functions
+  const allWasmBlocks = [
+    ...wasmFunctions.blocks,
+    ...importedWasm.blocks,
+    ...wasmBlocks.blocks,
+  ]
+
   // Extract and run test blocks: test 'desc'? { body }
   // Tests run at transpile time and are stripped from output
   const testResult = extractAndRunTests(source, options.dangerouslySkipTests)
@@ -366,11 +418,12 @@ export function preprocess(
     requiredParams,
     unsafeFunctions,
     safeFunctions,
-    wasmBlocks: wasmBlocks.blocks,
+    wasmBlocks: allWasmBlocks,
     tests: testResult.tests,
     testErrors: testResult.errors,
     polymorphicNames: polyResult.polymorphicNames,
     extensions: extResult.extensions,
+    letAnnotations,
   }
 }
 
@@ -392,6 +445,8 @@ export function parse(
   wasmBlocks: WasmBlock[]
   tests: TestBlock[]
   testErrors: string[]
+  letAnnotations: Map<string, string>
+  tjsModes: TjsModes
 } {
   const {
     filename = '<source>',
@@ -412,8 +467,14 @@ export function parse(
     wasmBlocks,
     tests,
     testErrors,
+    letAnnotations,
+    tjsModes,
   } = colonShorthand
-    ? preprocess(source, { vmTarget })
+    ? preprocess(source, {
+        vmTarget,
+        moduleLoader: options.moduleLoader,
+        filename: options.filename,
+      })
     : {
         source,
         returnType: undefined,
@@ -426,6 +487,17 @@ export function parse(
         wasmBlocks: [] as WasmBlock[],
         tests: [] as TestBlock[],
         testErrors: [] as string[],
+        letAnnotations: new Map<string, string>(),
+        tjsModes: {
+          tjsEquals: false,
+          tjsClass: false,
+          tjsDate: false,
+          tjsNoeval: false,
+          tjsStandard: false,
+          tjsSafeEval: false,
+          tjsNoVar: false,
+          tjsSafeAssign: false,
+        } as TjsModes,
       }
 
   try {
@@ -448,6 +520,8 @@ export function parse(
       wasmBlocks,
       tests,
       testErrors,
+      letAnnotations,
+      tjsModes,
     }
   } catch (e: any) {
     // Convert Acorn error to our error type

package/src/lang/runtime.ts

@@ -605,6 +605,26 @@ export function TypeOf(value: unknown): string {
   return typeof value
 }
 
+/**
+ * Honest boolean coercion. Like `Boolean(x)` but unwraps boxed primitives
+ * first, fixing the JS footgun `Boolean(new Boolean(false)) === true`.
+ *
+ * Under TjsStandard, the source rewriter wraps every truthiness context
+ * (if/while/for/do-while conditions, `!`, `&&`, `||`, ternary, and
+ * top-level `Boolean(x)` calls) with this function so a boxed `false`
+ * actually behaves as `false`.
+ */
+export function toBool(value: unknown): boolean {
+  if (
+    value instanceof Boolean ||
+    value instanceof Number ||
+    value instanceof String
+  ) {
+    return Boolean((value as any).valueOf())
+  }
+  return Boolean(value)
+}
+
 export function Eq(a: unknown, b: unknown): boolean {
   // Unwrap boxed primitives
   if (a instanceof String || a instanceof Number || a instanceof Boolean) {
@@ -844,6 +864,78 @@ type TypeSpec =
   | string
   | { check: (v: unknown) => boolean | string; description: string }
 
+/**
+ * Check that a passed-in function's declared shape matches the expected
+ * shape. Returns the function unchanged on a match, or a MonadicError on
+ * mismatch. Untyped functions (no `__tjs` metadata — anonymous arrows
+ * like `x => false`) pass through unchanged on the assumption that the
+ * caller knows what they're doing; they accept any args and return
+ * whatever they return.
+ *
+ * This is a ONE-SHOT check at pass time, NOT a per-call wrapper. The TJS
+ * design call: a wrong-shape callback is ONE error at the boundary, not
+ * N errors when the receiving function invokes the callback N times.
+ *
+ * Compatibility rules (deliberately permissive — strict subtyping is a
+ * separate, larger feature):
+ *   - For each expected param: the actual function may declare fewer
+ *     params (extras simply not used). If both declare a kind, they
+ *     must match exactly. Either side being `any` always matches.
+ *   - For the return type: same exact-match rule when both are known.
+ */
+export function checkFnShape(
+  fn: unknown,
+  expectedParamKinds: string[],
+  expectedReturnKind: string,
+  path: string
+): unknown {
+  if (typeof fn !== 'function') return fn // outer "is callable" check already ran
+  const meta = (fn as any).__tjs
+  if (!meta || !meta.params) return fn // untyped — let it run
+
+  const actualEntries = Object.entries(meta.params) as Array<
+    [string, { type?: { kind?: string } }]
+  >
+  for (let i = 0; i < expectedParamKinds.length; i++) {
+    const expectedKind = expectedParamKinds[i]
+    if (expectedKind === 'any') continue
+    const actual = actualEntries[i]
+    if (!actual) continue // function takes fewer params, OK
+    const actualKind = actual[1]?.type?.kind
+    if (!actualKind || actualKind === 'any') continue
+    if (actualKind !== expectedKind) {
+      return new MonadicError(
+        `Expected (...arg${i}: ${expectedKind}, ...) for '${path}', ` +
+          `but callback declares arg${i} as ${actualKind}`,
+        `${path}(arg${i})`,
+        expectedKind,
+        actualKind
+      )
+    }
+  }
+
+  if (expectedReturnKind !== 'any' && meta.returns) {
+    // Metadata's `returns` is `{ type: TypeDescriptor, defaults?: ... }`,
+    // but defensively also accept a bare TypeDescriptor.
+    const actualReturnKind = meta.returns.type?.kind ?? meta.returns.kind
+    if (
+      actualReturnKind &&
+      actualReturnKind !== 'any' &&
+      actualReturnKind !== expectedReturnKind
+    ) {
+      return new MonadicError(
+        `Expected callback returning ${expectedReturnKind} for '${path}', ` +
+          `but callback returns ${actualReturnKind}`,
+        `${path}(return)`,
+        expectedReturnKind,
+        actualReturnKind
+      )
+    }
+  }
+
+  return fn
+}
+
 /** Parameter metadata with optional location */
 interface ParamMeta {
   type: TypeSpec
@@ -1478,6 +1570,7 @@ export function createRuntime() {
     checkType,
     validateArgs,
     wrap,
+    checkFnShape,
     wrapClass,
     compareVersions,
     versionsCompatible,
@@ -1528,6 +1621,8 @@ export function createRuntime() {
     NotEq,
     // Honest typeof (typeof with TjsEquals)
     TypeOf,
+    // Honest truthiness (unwraps boxed primitives)
+    toBool,
     tjsEquals,
     // Extensions
     registerExtension: instanceRegisterExtension,
@@ -1559,6 +1654,7 @@ export const runtime = {
   checkType,
   validateArgs,
   wrap,
+  checkFnShape,
   wrapClass,
   compareVersions,
   versionsCompatible,
@@ -1612,6 +1708,8 @@ export const runtime = {
   NotEq,
   // Honest typeof (used by typeof with TjsEquals)
   TypeOf,
+  // Honest truthiness (used in TjsStandard for boxed-primitive coercion)
+  toBool,
 }
 
 /**

package/src/lang/types.ts

@@ -22,6 +22,7 @@ export interface TypeDescriptor {
     | 'array'
     | 'object'
     | 'union'
+    | 'function'
     | 'any'
   nullable?: boolean
   /** For arrays: the element type */
@@ -32,6 +33,11 @@ export interface TypeDescriptor {
   members?: TypeDescriptor[]
   /** For destructured parameters: full parameter descriptors */
   destructuredParams?: Record<string, ParameterDescriptor>
+  /** For functions: declared parameters with names and inferred types */
+  params?: Array<{ name: string; type: TypeDescriptor }>
+  /** For functions: inferred return type. Concise arrow bodies infer from
+   * the expression; block bodies and complex expressions stay `any`. */
+  returns?: TypeDescriptor
 }
 
 /** Describes a function parameter */