tjs-lang 0.7.7 → 0.7.8

package/src/lang/parser-transforms.ts

@@ -3595,3 +3595,307 @@ function findMatchingOpen(
   }
   return pos
 }
+
+/**
+ * Transform `let x: <example>` and `let x: <example> = value` declarations.
+ *
+ * Strips the `: <example>` annotation so Acorn can parse, and records the
+ * variable name + example text so the linter and (later) type inference can
+ * use the annotation. Acorn rejects the colon since it is not valid JS.
+ *
+ *   let x: ''           → let x         (annotation: x → '')
+ *   let x: 0 = 5        → let x = 5     (annotation: x → 0)
+ *   let result: { ok: false } = ...     (annotation: result → { ok: false })
+ *
+ * Only `let` is processed. `const` always has an initializer, so the type
+ * is always inferable. `var` is rejected by TjsNoVar mode.
+ */
+export function transformLetTypeAnnotations(source: string): {
+  source: string
+  annotations: Map<string, string>
+} {
+  const annotations = new Map<string, string>()
+  if (!source.includes('let ')) return { source, annotations }
+
+  type Replacement = { start: number; end: number; replacement: string }
+  const replacements: Replacement[] = []
+
+  let i = 0
+  let state: TokenizerState = 'normal'
+  const templateStack: number[] = []
+
+  while (i < source.length) {
+    const char = source[i]
+    const nextChar = source[i + 1]
+
+    switch (state) {
+      case 'single-string':
+        if (char === '\\' && i + 1 < source.length) {
+          i += 2
+          continue
+        }
+        if (char === "'") state = 'normal'
+        i++
+        continue
+      case 'double-string':
+        if (char === '\\' && i + 1 < source.length) {
+          i += 2
+          continue
+        }
+        if (char === '"') state = 'normal'
+        i++
+        continue
+      case 'template-string':
+        if (char === '\\' && i + 1 < source.length) {
+          i += 2
+          continue
+        }
+        if (char === '$' && nextChar === '{') {
+          i += 2
+          templateStack.push(1)
+          state = 'normal'
+          continue
+        }
+        if (char === '`') state = 'normal'
+        i++
+        continue
+      case 'line-comment':
+        if (char === '\n') state = 'normal'
+        i++
+        continue
+      case 'block-comment':
+        if (char === '*' && nextChar === '/') {
+          i += 2
+          state = 'normal'
+          continue
+        }
+        i++
+        continue
+      case 'regex':
+        if (char === '\\' && i + 1 < source.length) {
+          i += 2
+          continue
+        }
+        if (char === '[') {
+          i++
+          while (i < source.length && source[i] !== ']') {
+            if (source[i] === '\\' && i + 1 < source.length) i += 2
+            else i++
+          }
+          if (i < source.length) i++
+          continue
+        }
+        if (char === '/') {
+          i++
+          while (i < source.length && /[gimsuy]/.test(source[i])) i++
+          state = 'normal'
+          continue
+        }
+        i++
+        continue
+      case 'normal':
+        if (templateStack.length > 0) {
+          if (char === '{') {
+            templateStack[templateStack.length - 1]++
+          } else if (char === '}') {
+            templateStack[templateStack.length - 1]--
+            if (templateStack[templateStack.length - 1] === 0) {
+              templateStack.pop()
+              i++
+              state = 'template-string'
+              continue
+            }
+          }
+        }
+        if (char === "'") {
+          i++
+          state = 'single-string'
+          continue
+        }
+        if (char === '"') {
+          i++
+          state = 'double-string'
+          continue
+        }
+        if (char === '`') {
+          i++
+          state = 'template-string'
+          continue
+        }
+        if (char === '/' && nextChar === '/') {
+          i += 2
+          state = 'line-comment'
+          continue
+        }
+        if (char === '/' && nextChar === '*') {
+          i += 2
+          state = 'block-comment'
+          continue
+        }
+        if (char === '/') {
+          let j = i - 1
+          while (j >= 0 && /\s/.test(source[j])) j--
+          const beforeChar = j >= 0 ? source[j] : ''
+          const isRegexContext =
+            !beforeChar ||
+            /[=(!,;:{[&|?+\-*%<>~^]/.test(beforeChar) ||
+            (j >= 5 &&
+              /\b(return|case|throw|in|of|typeof|instanceof|new|delete|void)$/.test(
+                source.slice(Math.max(0, j - 10), j + 1)
+              ))
+          if (isRegexContext) {
+            i++
+            state = 'regex'
+            continue
+          }
+        }
+
+        // Detect `let <ident> :` at top-level normal state
+        if (
+          char === 'l' &&
+          source.slice(i, i + 4) === 'let ' &&
+          (i === 0 || !/[\w$]/.test(source[i - 1]))
+        ) {
+          // Skip past `let` and whitespace
+          let j = i + 4
+          while (j < source.length && /\s/.test(source[j])) j++
+          // Match identifier
+          if (j < source.length && /[a-zA-Z_$]/.test(source[j])) {
+            const nameStart = j
+            while (j < source.length && /[\w$]/.test(source[j])) j++
+            const nameEnd = j
+            const varName = source.slice(nameStart, nameEnd)
+            // Skip whitespace; require a `:` (not `::` or part of `?:`)
+            let k = j
+            while (k < source.length && /\s/.test(source[k])) k++
+            if (
+              k < source.length &&
+              source[k] === ':' &&
+              source[k + 1] !== ':'
+            ) {
+              const colonPos = k
+              // Skip whitespace after colon
+              let exStart = colonPos + 1
+              while (exStart < source.length && /[ \t]/.test(source[exStart])) {
+                exStart++
+              }
+              // Scan example expression until `=`, `,`, `;`, or newline at depth 0
+              const exEnd = scanExampleEnd(source, exStart)
+              if (exEnd > exStart) {
+                const example = source.slice(exStart, exEnd).trim()
+                annotations.set(varName, example)
+                replacements.push({
+                  start: nameEnd,
+                  end: exEnd,
+                  replacement: '',
+                })
+                i = exEnd
+                continue
+              }
+            }
+          }
+        }
+        break
+    }
+    i++
+  }
+
+  if (replacements.length === 0) return { source, annotations }
+
+  // Apply right-to-left to preserve positions
+  let result = source
+  for (let k = replacements.length - 1; k >= 0; k--) {
+    const r = replacements[k]
+    result = result.slice(0, r.start) + r.replacement + result.slice(r.end)
+  }
+  return { source: result, annotations }
+}
+
+/**
+ * Scan forward from `start` and return the position where the example
+ * expression ends. Stops at `=`, `,`, `;`, or a newline when paren/brace/
+ * bracket depth is 0. Skips through nested brackets, strings, and templates.
+ */
+function scanExampleEnd(source: string, start: number): number {
+  let i = start
+  let parens = 0
+  let braces = 0
+  let brackets = 0
+  let state: 'normal' | 'sq' | 'dq' | 'tpl' = 'normal'
+  const templateStack: number[] = []
+  while (i < source.length) {
+    const c = source[i]
+    if (state === 'sq') {
+      if (c === '\\') {
+        i += 2
+        continue
+      }
+      if (c === "'") state = 'normal'
+      i++
+      continue
+    }
+    if (state === 'dq') {
+      if (c === '\\') {
+        i += 2
+        continue
+      }
+      if (c === '"') state = 'normal'
+      i++
+      continue
+    }
+    if (state === 'tpl') {
+      if (c === '\\') {
+        i += 2
+        continue
+      }
+      if (c === '$' && source[i + 1] === '{') {
+        templateStack.push(1)
+        state = 'normal'
+        i += 2
+        continue
+      }
+      if (c === '`') state = 'normal'
+      i++
+      continue
+    }
+    // normal
+    if (templateStack.length > 0) {
+      if (c === '{') templateStack[templateStack.length - 1]++
+      else if (c === '}') {
+        templateStack[templateStack.length - 1]--
+        if (templateStack[templateStack.length - 1] === 0) {
+          templateStack.pop()
+          state = 'tpl'
+          i++
+          continue
+        }
+      }
+    }
+    if (c === "'") {
+      state = 'sq'
+      i++
+      continue
+    }
+    if (c === '"') {
+      state = 'dq'
+      i++
+      continue
+    }
+    if (c === '`') {
+      state = 'tpl'
+      i++
+      continue
+    }
+    if (c === '(') parens++
+    else if (c === ')') parens--
+    else if (c === '{') braces++
+    else if (c === '}') braces--
+    else if (c === '[') brackets++
+    else if (c === ']') brackets--
+    if (parens === 0 && braces === 0 && brackets === 0) {
+      if (c === '=' || c === ',' || c === ';' || c === '\n') return i
+    }
+    i++
+  }
+  return i
+}

package/src/lang/parser-types.ts

@@ -144,6 +144,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

@@ -51,6 +51,7 @@ import {
   transformConstBang,
   transformBangAccess,
   transformExtensionCalls,
+  transformLetTypeAnnotations,
 } from './parser-transforms'
 
 // Re-export transformExtensionCalls for js.ts
@@ -120,6 +121,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 +145,7 @@ export function preprocess(
         tjsStandard: false,
         tjsSafeEval: false,
         tjsNoVar: false,
+        tjsSafeAssign: false,
       }
     : {
         tjsEquals: true,
@@ -152,6 +155,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 +184,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 +198,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 +208,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 +223,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 +255,13 @@ 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
+
   // Transform Is/IsNot infix operators to function calls
   // a Is b -> Is(a, b)
   // a IsNot b -> IsNot(a, b)
@@ -371,6 +386,7 @@ export function preprocess(
     testErrors: testResult.errors,
     polymorphicNames: polyResult.polymorphicNames,
     extensions: extResult.extensions,
+    letAnnotations,
   }
 }
 
@@ -392,6 +408,8 @@ export function parse(
   wasmBlocks: WasmBlock[]
   tests: TestBlock[]
   testErrors: string[]
+  letAnnotations: Map<string, string>
+  tjsModes: TjsModes
 } {
   const {
     filename = '<source>',
@@ -412,6 +430,8 @@ export function parse(
     wasmBlocks,
     tests,
     testErrors,
+    letAnnotations,
+    tjsModes,
   } = colonShorthand
     ? preprocess(source, { vmTarget })
     : {
@@ -426,6 +446,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 +479,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 */