tjs-lang 0.7.7 → 0.7.8

package/src/lang/emitters/js.ts

@@ -69,6 +69,10 @@ import {
 } from './js-tests'
 export { stripModuleSyntax, stripTjsPreamble } from './js-tests'
 import { generateWasmBootstrap } from './js-wasm'
+import {
+  rewriteBoolCoercion,
+  rewriteBoolCoercionInSource,
+} from '../bool-coercion'
 
 export interface TJSTranspileOptions {
   /** Filename for error messages */
@@ -419,6 +423,19 @@ function generateInlineValidationCode(
   // 2. Type checks with proper error emission
   for (const [paramName, param] of params) {
     const path = `${pathPrefix}${funcName}.${paramName}`
+
+    // For array params: if the array contains a MonadicError, propagate
+    // the first one we find instead of failing the type check with
+    // "expected array, got X". This is the "errors propagate, not
+    // accumulate" rule — a function receiving an array of values where
+    // one is an error should surface that error, not say the array's
+    // shape is wrong.
+    if (param.type.kind === 'array') {
+      lines.push(
+        `if (Array.isArray(${paramName})) { for (const __i of ${paramName}) { if (__i instanceof Error && __i.path !== undefined) return __i } }`
+      )
+    }
+
     const typeCheck = generateTypeCheckExpr(paramName, param.type)
 
     if (typeCheck) {
@@ -436,6 +453,19 @@ function generateInlineValidationCode(
         )
       }
     }
+
+    // If the param is a function with declared shape (e.g. `fn = (x: 0) => 0`),
+    // wrap it so its arguments and return value are validated on every call.
+    // Skipped when shape is unspecified or contains non-simple kinds.
+    if (param.type.kind === 'function') {
+      const shapeCheck = generateFunctionShapeCheck(paramName, param.type, path)
+      if (shapeCheck) {
+        lines.push(shapeCheck)
+        // checkFnShape returns either the function unchanged or a
+        // MonadicError. Re-check Error propagation after the assignment.
+        lines.push(`if (${paramName} instanceof Error) return ${paramName};`)
+      }
+    }
   }
 
   if (lines.length === 0) return null
@@ -618,12 +648,18 @@ export function transpileToJS(
     if (preprocessed.tjsModes.tjsEquals) {
       t.body = transformEqualityToStructural(t.body)
     }
+    if (preprocessed.tjsModes.tjsStandard) {
+      t.body = rewriteBoolCoercionInSource(t.body)
+    }
   }
   for (const m of mocks) {
     m.body = transformIsOperators(m.body)
     if (preprocessed.tjsModes.tjsEquals) {
       m.body = transformEqualityToStructural(m.body)
     }
+    if (preprocessed.tjsModes.tjsStandard) {
+      m.body = rewriteBoolCoercionInSource(m.body)
+    }
   }
 
   // Build types map for all functions
@@ -671,6 +707,41 @@ export function transpileToJS(
     warnings.push(...funcWarnings)
     allTypes[funcName] = types
 
+    // Cross-reference inference: when a parameter default is a bare
+    // identifier referring to a previously-declared TJS function, use that
+    // function's signature as the parameter's type. So
+    //
+    //   function strLength(s: ''): 0 { ... }
+    //   function map(arr: [''], counter = strLength) { ... }
+    //
+    // makes `counter`'s type `(s: string) => integer` (instead of `any`),
+    // which means the checkFnShape pass-time check fires when a wrong-
+    // shape callback is passed at the call site.
+    for (const param of func.params) {
+      if (
+        param.type === 'AssignmentPattern' &&
+        param.left.type === 'Identifier' &&
+        param.right.type === 'Identifier'
+      ) {
+        const localName = param.left.name
+        const refName = (param.right as any).name as string
+        const refInfo = allTypes[refName]
+        if (refInfo && types.params[localName]) {
+          const fnParams = Object.entries(refInfo.params).map(([n, p]) => ({
+            name: n,
+            type: p.type,
+          }))
+          const fnReturns =
+            (refInfo as any).returns ?? ({ kind: 'any' } as TypeDescriptor)
+          types.params[localName].type = {
+            kind: 'function',
+            params: fnParams,
+            returns: fnReturns,
+          }
+        }
+      }
+    }
+
     // Clean up param defaults in the emitted JS.
     // After colon→equals transform, `x: false | undefined` becomes
     // `x = false | undefined` in the parsed source.
@@ -780,6 +851,18 @@ export function transpileToJS(
     }
   }
 
+  // Boolean coercion rewrite (TjsStandard). Rewrites every truthiness
+  // context (`if`, `while`, `for`, `do/while`, `!`, `&&`, `||`, `?:`,
+  // and `Boolean(x)` calls) to call `__tjs.toBool` so boxed primitives
+  // unwrap before coercion. See src/lang/bool-coercion.ts.
+  if (preprocessed.tjsModes.tjsStandard) {
+    const boolPatches = rewriteBoolCoercion(program, preprocessed.source)
+    for (const p of boolPatches) {
+      deletions.push({ start: p.start, end: p.end })
+      insertions.push({ position: p.start, text: p.newText })
+    }
+  }
+
   // Apply deletions first (reverse order to maintain offsets), then insertions.
   // Deletions strip | union suffixes from param defaults in the output JS.
   deletions.sort((a, b) => b.start - a.start)
@@ -821,6 +904,8 @@ export function transpileToJS(
   const needsEnum = /\bEnum\(/.test(code)
   const needsUnion = /\bUnion\(/.test(code)
   const needsBang = code.includes('__tjs.bang(')
+  const needsToBool = code.includes('__tjs.toBool(')
+  const needsCheckFnShape = code.includes('__tjs.checkFnShape(')
   const needsSafeEval = preprocessed.tjsModes.tjsSafeEval
 
   const needsRuntime =
@@ -837,6 +922,8 @@ export function transpileToJS(
     needsEnum ||
     needsUnion ||
     needsBang ||
+    needsToBool ||
+    needsCheckFnShape ||
     needsSafeEval
 
   if (needsRuntime) {
@@ -913,6 +1000,28 @@ export function transpileToJS(
         `function Union(d,...v){const vals=v.flat();return{description:d,check:x=>vals.includes(x),values:vals,__runtimeType:true}}`
       )
     }
+    // toBool — honest truthiness (unwraps boxed primitives)
+    if (needsToBool) {
+      inlineParts.push(
+        `function toBool(v){if(v instanceof Boolean||v instanceof Number||v instanceof String)return Boolean(v.valueOf());return Boolean(v)}`
+      )
+    }
+
+    // checkFnShape — pass-time shape check for function-typed params
+    if (needsCheckFnShape) {
+      // checkFnShape depends on MonadicError; ensure it's inlined
+      if (!needsTypeError) {
+        inlineParts.push(
+          `class MonadicError extends Error{constructor(m,p,e,a,c,r){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;this.reason=r}}`,
+          `function typeError(p,e,v,r){const a=v===null?'null':typeof v;const m=r?'Expected '+e+" for '"+p+"': "+r:'Expected '+e+" for '"+p+"', got "+a;const err=new MonadicError(m,p,e,a,undefined,r);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
+          `function isMonadicError(v){return v instanceof Error&&v.name==='MonadicError'&&'path' in v}`
+        )
+      }
+      inlineParts.push(
+        `function checkFnShape(fn,expectedParams,expectedReturn,path){if(typeof fn!=='function')return fn;const meta=fn.__tjs;if(!meta||!meta.params)return fn;const entries=Object.entries(meta.params);for(let i=0;i<expectedParams.length;i++){const e=expectedParams[i];if(e==='any')continue;const a=entries[i];if(!a)continue;const ak=a[1]&&a[1].type&&a[1].type.kind;if(!ak||ak==='any')continue;if(ak!==e)return new MonadicError("Expected (...arg"+i+": "+e+", ...) for '"+path+"', but callback declares arg"+i+" as "+ak,path+"(arg"+i+")",e,ak)}if(expectedReturn!=='any'&&meta.returns){const ar=(meta.returns.type&&meta.returns.type.kind)||meta.returns.kind;if(ar&&ar!=='any'&&ar!==expectedReturn)return new MonadicError("Expected callback returning "+expectedReturn+" for '"+path+"', but callback returns "+ar,path+"(return)",expectedReturn,ar)}return fn}`
+      )
+    }
+
     // Bang access (!.) — asserted non-null member access
     if (needsBang) {
       // bang depends on typeError and isMonadicError — ensure they're inlined
@@ -947,6 +1056,11 @@ export function transpileToJS(
     if (needsFunctionPredicate) fallbackEntries.push('FunctionPredicate')
     if (needsEnum) fallbackEntries.push('Enum')
     if (needsUnion) fallbackEntries.push('Union')
+    if (needsToBool) fallbackEntries.push('toBool')
+    if (needsCheckFnShape) {
+      fallbackEntries.push('checkFnShape')
+      if (!needsTypeError) fallbackEntries.push('typeError', 'isMonadicError')
+    }
     if (needsBang) {
       fallbackEntries.push('bang')
       // Ensure typeError/isMonadicError are in fallback even if not otherwise needed
@@ -1289,13 +1403,33 @@ function generateTypeCheckExpr(
       return `${fieldPath} !== null` // nullable doesn't apply to null itself
     case 'undefined':
       return `${fieldPath} !== undefined`
-    case 'array':
-      check = `!Array.isArray(${fieldPath})`
+    case 'array': {
+      // Always require an Array. If item type is known and non-trivial,
+      // also validate every item — `arr: [0]` means "array of integers",
+      // not "any array". Without this, a function returning
+      // `[MonadicError, MonadicError]` would pass the `: [0]` return-
+      // type check (it's an array) and surface a confusing array-of-
+      // errors to the caller.
+      const itemCheck =
+        type.items && type.items.kind !== 'any'
+          ? generateTypeCheckExpr('__a', type.items)
+          : null
+      if (itemCheck) {
+        check = `(!Array.isArray(${fieldPath}) || ${fieldPath}.some(__a => ${itemCheck}))`
+      } else {
+        check = `!Array.isArray(${fieldPath})`
+      }
       break
+    }
     case 'object':
       // For nested objects, just check it's an object (deep validation is separate)
       check = `(typeof ${fieldPath} !== 'object' || ${fieldPath} === null || Array.isArray(${fieldPath}))`
       break
+    case 'function':
+      // Shape isn't validated at call time (we don't introspect arity or
+      // call the function with probes) — just check it IS callable.
+      check = `typeof ${fieldPath} !== 'function'`
+      break
     case 'union': {
       const checks = (type as any).members
         .map((m: TypeDescriptor) => generateTypeCheckExpr(fieldPath, m))
@@ -1321,6 +1455,52 @@ function generateTypeCheckExpr(
 // Alias for backward compatibility with other functions that use this
 const generateTypeCheck = generateTypeCheckExpr
 
+/** Kinds checkType can validate by string name (no RuntimeType needed). */
+const SIMPLE_KINDS = new Set([
+  'string',
+  'number',
+  'integer',
+  'non-negative-integer',
+  'boolean',
+  'function',
+  'any',
+  'undefined',
+  'null',
+  'object', // checkType handles this via typeof
+])
+
+/**
+ * Generate a `__tjs.checkFnShape(...)` call that validates a passed-in
+ * function's declared shape against the expected shape ONCE at pass time.
+ * On mismatch the param is reassigned to a MonadicError; the existing
+ * `if (param instanceof Error) return param` check above handles
+ * propagation. On match the param is unchanged. Untyped functions
+ * (no `__tjs` metadata — anonymous arrows) pass through unchanged.
+ *
+ * Returns null when the expected shape can't be represented as simple
+ * TypeSpec strings, or when there's nothing useful to check (all-`any`).
+ */
+function generateFunctionShapeCheck(
+  paramName: string,
+  type: TypeDescriptor,
+  path: string
+): string | null {
+  const fnParams = (type.params ?? []) as Array<{
+    name: string
+    type: TypeDescriptor
+  }>
+  const fnReturns = type.returns ?? { kind: 'any' as const }
+  const paramKinds = fnParams.map((p) => p.type?.kind)
+  const allSimple =
+    paramKinds.every((k) => k && SIMPLE_KINDS.has(k)) &&
+    SIMPLE_KINDS.has(fnReturns.kind)
+  const hasUsefulCheck =
+    paramKinds.some((k) => k !== 'any') || fnReturns.kind !== 'any'
+  if (!allSimple || !hasUsefulCheck) return null
+  const paramTypesJson = JSON.stringify(paramKinds)
+  return `if (typeof ${paramName} === 'function') ${paramName} = __tjs.checkFnShape(${paramName}, ${paramTypesJson}, '${fnReturns.kind}', '${path}');`
+}
+
 /**
  * Generate the complete function wrapper with inline validation
  *

package/src/lang/inference.ts

@@ -137,6 +137,31 @@ export function inferTypeFromValue(node: Expression): TypeDescriptor {
       return { kind: 'any' }
     }
 
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression': {
+      // Function example value (e.g. `fn = (x) => x` or `cb = function() {}`).
+      // Capture parameter names + types and (for concise arrow bodies)
+      // infer the return type from the body expression.
+      const fn = node as any
+      const params: Array<{ name: string; type: TypeDescriptor }> =
+        fn.params.map((p: any) => paramShape(p))
+
+      // Concise arrow body: body IS the return expression, so we can
+      // infer its type. Block bodies (function expressions, multi-line
+      // arrows) stay `any` — scanning return statements is a separate
+      // can of worms.
+      let returns: TypeDescriptor = { kind: 'any' }
+      if (
+        fn.type === 'ArrowFunctionExpression' &&
+        fn.body &&
+        fn.body.type !== 'BlockStatement'
+      ) {
+        returns = inferTypeFromValue(fn.body)
+      }
+
+      return { kind: 'function', params, returns }
+    }
+
     case 'UnaryExpression': {
       const op = (node as any).operator
       const arg = (node as any).argument
@@ -168,6 +193,35 @@ export function inferTypeFromValue(node: Expression): TypeDescriptor {
   }
 }
 
+/**
+ * Extract a function-parameter shape from a Pattern AST node. Used when
+ * we encounter a function/arrow EXAMPLE value and want to record what
+ * its declared parameters look like for documentation and .d.ts emit.
+ *
+ * Plain identifier (`x`)              → { name: 'x', type: any }
+ * Default value (`x = 0`)             → { name: 'x', type: integer }
+ * Rest (`...args`)                    → { name: '...args', type: array }
+ * Destructuring (`{a}`, `[x]`)        → name: '?', type: any (we'd need
+ *                                       to mirror parseParameter to do
+ *                                       this properly; not worth the
+ *                                       complexity for example values)
+ */
+function paramShape(p: any): { name: string; type: TypeDescriptor } {
+  if (p.type === 'Identifier') {
+    return { name: p.name, type: { kind: 'any' } }
+  }
+  if (p.type === 'AssignmentPattern' && p.left?.type === 'Identifier') {
+    return { name: p.left.name, type: inferTypeFromValue(p.right) }
+  }
+  if (p.type === 'RestElement' && p.argument?.type === 'Identifier') {
+    return {
+      name: `...${p.argument.name}`,
+      type: { kind: 'array', items: { kind: 'any' } },
+    }
+  }
+  return { name: '?', type: { kind: 'any' } }
+}
+
 /**
  * Parse a parameter and extract its type and default value
  *

package/src/lang/linter.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { lint } from './linter'
+import { lint, type LintDiagnostic } from './linter'
 
 describe('TJS Linter', () => {
   describe('no-explicit-new rule', () => {
@@ -145,4 +145,107 @@ describe('TJS Linter', () => {
       expect(result.diagnostics[0].rule).toBe('parse-error')
     })
   })
+
+  describe('safe-assign rule (TjsSafeAssign)', () => {
+    const onlySafeAssign = (result: { diagnostics: LintDiagnostic[] }) =>
+      result.diagnostics.filter((d) => d.rule.startsWith('safe-assign'))
+
+    it('flags `let x` with no initializer or annotation', () => {
+      const result = lint(`function f() { let x; return x }`)
+      const diags = onlySafeAssign(result)
+      expect(diags.length).toBe(1)
+      expect(diags[0].rule).toBe('safe-assign-let-needs-type')
+      expect(diags[0].severity).toBe('warning')
+      expect(diags[0].message).toContain("'let x'")
+    })
+
+    it('flags `let x = undefined` with no annotation', () => {
+      const result = lint(`function f() { let x = undefined; return x }`)
+      const diags = onlySafeAssign(result)
+      expect(diags.length).toBe(1)
+      expect(diags[0].rule).toBe('safe-assign-let-needs-type')
+      expect(diags[0].message).toContain('undefined')
+    })
+
+    it('flags `let x = null` with no annotation', () => {
+      const result = lint(`function f() { let x = null; return x }`)
+      const diags = onlySafeAssign(result)
+      expect(diags.length).toBe(1)
+      expect(diags[0].rule).toBe('safe-assign-let-needs-type')
+    })
+
+    it('flags `let x = void 0` with no annotation', () => {
+      const result = lint(`function f() { let x = void 0; return x }`)
+      const diags = onlySafeAssign(result)
+      expect(diags.length).toBe(1)
+      expect(diags[0].rule).toBe('safe-assign-let-needs-type')
+    })
+
+    it('accepts `let x = 0` (inferable initializer)', () => {
+      const result = lint(`function f() { let x = 0; return x }`)
+      expect(onlySafeAssign(result).length).toBe(0)
+    })
+
+    it("accepts `let x: ''` (annotation, no init)", () => {
+      const result = lint(`function f() { let x: ''; return x }`)
+      expect(onlySafeAssign(result).length).toBe(0)
+    })
+
+    it("accepts `let x: '' = 'hi'` (annotation + init)", () => {
+      const result = lint(`function f() { let x: '' = 'hi'; return x }`)
+      expect(onlySafeAssign(result).length).toBe(0)
+    })
+
+    it('flags `x = undefined` reassignment to a typed let', () => {
+      const result = lint(
+        `function f() { let x = 'hi'; x = undefined; return x }`
+      )
+      const diags = onlySafeAssign(result)
+      expect(diags.length).toBe(1)
+      expect(diags[0].rule).toBe('safe-assign-no-nullish')
+      expect(diags[0].message).toContain("'x'")
+    })
+
+    it('flags `x = null` reassignment to an annotated let', () => {
+      const result = lint(`function f() { let x: 0; x = null; return x }`)
+      const diags = onlySafeAssign(result)
+      expect(diags.length).toBe(1)
+      expect(diags[0].rule).toBe('safe-assign-no-nullish')
+    })
+
+    it('does not flag `x = "hi"` reassignment', () => {
+      const result = lint(`function f() { let x = 'a'; x = 'b'; return x }`)
+      expect(onlySafeAssign(result).length).toBe(0)
+    })
+
+    it('does not run rule under TjsCompat directive', () => {
+      const result = lint(`
+        TjsCompat
+        function f() { let x; return x }
+      `)
+      expect(onlySafeAssign(result).length).toBe(0)
+    })
+
+    it('emits errors (not warnings) under strict option', () => {
+      const result = lint(`function f() { let x; return x }`, {
+        strict: true,
+      })
+      const diags = onlySafeAssign(result)
+      expect(diags.length).toBe(1)
+      expect(diags[0].severity).toBe('error')
+      expect(result.valid).toBe(false)
+    })
+
+    it('safeAssign: false option disables the rule even in native TJS', () => {
+      const result = lint(`function f() { let x; return x }`, {
+        safeAssign: false,
+      })
+      expect(onlySafeAssign(result).length).toBe(0)
+    })
+
+    it('does not flag const declarations', () => {
+      const result = lint(`function f() { const x = 0; return x }`)
+      expect(onlySafeAssign(result).length).toBe(0)
+    })
+  })
 })

package/src/lang/linter.ts

@@ -10,7 +10,14 @@
  * POC: Focus on variable usage first, then type checking.
  */
 
-import type { Program, Node, Identifier, VariableDeclaration } from 'acorn'
+import type {
+  Program,
+  Node,
+  Identifier,
+  VariableDeclaration,
+  AssignmentExpression,
+  Expression,
+} from 'acorn'
 import { parse } from './parser'
 import * as walk from 'acorn-walk'
 
@@ -36,8 +43,16 @@ export interface LintOptions {
   unreachableCode?: boolean
   /** Warn about explicit `new` keyword usage (TJS makes classes callable without new) */
   noExplicitNew?: boolean
+  /**
+   * Check `let` declarations for missing type information and forbid literal
+   * undefined/null assignments to typed lets. If undefined, the parser's
+   * `TjsSafeAssign` mode controls whether the rule runs.
+   */
+  safeAssign?: boolean
   /** Filename for error messages */
   filename?: string
+  /** Treat safeAssign violations as errors instead of warnings (TjsStrict semantics) */
+  strict?: boolean
 }
 
 const DEFAULT_OPTIONS: LintOptions = {
@@ -56,12 +71,16 @@ export function lint(source: string, options: LintOptions = {}): LintResult {
 
   // Parse the source
   let program: Program
+  let letAnnotations: Map<string, string> = new Map()
+  let safeAssignMode = false
   try {
     const result = parse(source, {
       filename: opts.filename,
       colonShorthand: true,
     })
     program = result.ast
+    letAnnotations = result.letAnnotations
+    safeAssignMode = result.tjsModes.tjsSafeAssign
   } catch (error: any) {
     return {
       diagnostics: [
@@ -76,6 +95,11 @@ export function lint(source: string, options: LintOptions = {}): LintResult {
       valid: false,
     }
   }
+  const safeAssignEnabled =
+    opts.safeAssign !== undefined ? opts.safeAssign : safeAssignMode
+  const safeAssignSeverity: LintDiagnostic['severity'] = opts.strict
+    ? 'error'
+    : 'warning'
 
   // Track variable declarations and usages per scope
   const scopes: Scope[] = [createScope()] // Global scope
@@ -177,6 +201,80 @@ export function lint(source: string, options: LintOptions = {}): LintResult {
     })
   }
 
+  // TjsSafeAssign: lets need an initializer or `: <example>` annotation, and
+  // typed lets must not be (re)assigned literal undefined/null/void 0.
+  if (safeAssignEnabled) {
+    // First pass: track which lets are "typed" (annotated OR have a non-nullish initializer)
+    const typedLets = new Set<string>()
+    walk.simple(program, {
+      VariableDeclaration(node: VariableDeclaration) {
+        if (node.kind !== 'let') return
+        for (const d of node.declarations) {
+          if (d.id.type !== 'Identifier') continue
+          const name = d.id.name
+          const annotated = letAnnotations.has(name)
+          const init = d.init
+          if (annotated) {
+            typedLets.add(name)
+          } else if (init && !isLiteralNullish(init)) {
+            typedLets.add(name)
+          }
+        }
+      },
+    })
+
+    // Declaration-site rule: missing type information
+    walk.simple(program, {
+      VariableDeclaration(node: VariableDeclaration) {
+        if (node.kind !== 'let') return
+        for (const d of node.declarations) {
+          if (d.id.type !== 'Identifier') continue
+          const name = d.id.name
+          if (letAnnotations.has(name)) continue
+          if (!d.init) {
+            diagnostics.push({
+              severity: safeAssignSeverity,
+              message: `'let ${name}' has no initializer or type annotation. Add an initializer (let ${name} = ...) or annotate (let ${name}: <example>).`,
+              line: (d as any).loc?.start?.line,
+              column: (d as any).loc?.start?.column,
+              rule: 'safe-assign-let-needs-type',
+            })
+          } else if (isLiteralNullish(d.init)) {
+            diagnostics.push({
+              severity: safeAssignSeverity,
+              message: `'let ${name}' is initialized to ${describeNullish(
+                d.init
+              )} with no type annotation. Annotate (let ${name}: <example>) to record the intended type.`,
+              line: (d as any).loc?.start?.line,
+              column: (d as any).loc?.start?.column,
+              rule: 'safe-assign-let-needs-type',
+            })
+          }
+        }
+      },
+    })
+
+    // Use-site rule: literal undefined/null assigned to a typed let
+    walk.simple(program, {
+      AssignmentExpression(node: AssignmentExpression) {
+        if (node.operator !== '=') return
+        if (node.left.type !== 'Identifier') return
+        const name = (node.left as Identifier).name
+        if (!typedLets.has(name)) return
+        if (!isLiteralNullish(node.right)) return
+        diagnostics.push({
+          severity: safeAssignSeverity,
+          message: `Cannot assign ${describeNullish(
+            node.right
+          )} to typed let '${name}'.`,
+          line: (node as any).loc?.start?.line,
+          column: (node as any).loc?.start?.column,
+          rule: 'safe-assign-no-nullish',
+        })
+      },
+    })
+  }
+
   // Check for explicit `new` keyword usage
   // In TJS, classes are callable without `new`, so using `new` is unnecessary
   if (opts.noExplicitNew) {
@@ -226,6 +324,31 @@ function createScope(): Scope {
   return { declarations: new Map() }
 }
 
+/**
+ * Is the given expression a literal that evaluates to undefined or null?
+ * Catches: `undefined`, `null`, `void 0`, `void <any-literal>`.
+ */
+function isLiteralNullish(node: Expression | null | undefined): boolean {
+  if (!node) return false
+  if (node.type === 'Identifier' && (node as Identifier).name === 'undefined') {
+    return true
+  }
+  if (node.type === 'Literal' && (node as any).value === null) return true
+  if (node.type === 'UnaryExpression' && (node as any).operator === 'void') {
+    return true
+  }
+  return false
+}
+
+function describeNullish(node: Expression): string {
+  if (node.type === 'Identifier') return 'undefined'
+  if (node.type === 'Literal' && (node as any).value === null) return 'null'
+  if (node.type === 'UnaryExpression' && (node as any).operator === 'void') {
+    return 'void <expr> (undefined)'
+  }
+  return 'a nullish value'
+}
+
 function addDeclaration(scope: Scope, node: Node, kind: Declaration['kind']) {
   if (node.type === 'Identifier') {
     scope.declarations.set((node as Identifier).name, {

package/src/lang/parser-params.ts

@@ -12,6 +12,7 @@ import type {
   ContextFrame,
   TjsModes,
 } from './parser-types'
+import { locAt } from './parser-transforms'
 
 export function transformParenExpressions(
   source: string,
@@ -331,6 +332,23 @@ export function transformParenExpressions(
           i = typeResult.endPos
         }
       }
+
+      // Catch a common mistake: writing `=> {` after a function declaration's
+      // return type (or after `)`), as if it were an arrow function. Without
+      // this check, the `=>` would pass through to Acorn, which complains
+      // with a generic "Unexpected token" at a misleading position.
+      let arrowCheck = i
+      while (arrowCheck < source.length && /\s/.test(source[arrowCheck]))
+        arrowCheck++
+      if (source[arrowCheck] === '=' && source[arrowCheck + 1] === '>') {
+        throw new SyntaxError(
+          "Unexpected '=>' after function declaration. " +
+            'Function declarations use `function name(params) { body }`, ' +
+            'not arrow syntax. Remove the `=>`.',
+          locAt(ctx.originalSource, arrowCheck),
+          ctx.originalSource
+        )
+      }
       continue
     }
 
@@ -410,6 +428,19 @@ export function transformParenExpressions(
         }
       }
 
+      // Same `=>` check for class methods.
+      let k = i
+      while (k < source.length && /\s/.test(source[k])) k++
+      if (source[k] === '=' && source[k + 1] === '>') {
+        throw new SyntaxError(
+          "Unexpected '=>' after method declaration. " +
+            'Methods use `name(params) { body }`, not arrow syntax. ' +
+            'Remove the `=>`.',
+          locAt(ctx.originalSource, k),
+          ctx.originalSource
+        )
+      }
+
       continue
     }