tjs-lang 0.5.4 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",

package/src/cli/commands/emit.ts

@@ -6,6 +6,7 @@
  *   tjs emit <file.tjs> -o <out.js>     Emit single file to output
  *   tjs emit <dir> -o <outdir>          Emit all .tjs files in directory
  *   tjs emit --unsafe <file.tjs>        Emit without __tjs metadata (production)
+ *   tjs emit --dts <file.tjs>           Also generate .d.ts declaration file
  *   tjs emit --no-docs <file.tjs>       Suppress documentation generation
  *   tjs emit --docs-dir <dir>           Output docs to separate directory
  *   tjs emit --jfdi <file.tjs>          Emit even if tests fail (just fucking do it)
@@ -22,6 +23,7 @@ import {
 import { join, basename, dirname, extname } from 'path'
 import { tjs } from '../../lang'
 import { generateDocs } from '../../lang/docs'
+import { generateDTS } from '../../lang/emitters/dts'
 
 export interface EmitOptions {
   /** Include source locations in __tjs metadata */
@@ -40,6 +42,8 @@ export interface EmitOptions {
   docsDir?: string
   /** Emit even if tests fail (just fucking do it) */
   jfdi?: boolean
+  /** Generate .d.ts TypeScript declaration file alongside JS */
+  dts?: boolean
 }
 
 export async function emit(
@@ -149,6 +153,28 @@ async function emitFile(
         console.log(`✓ ${inputPath} -> ${outputPath}${suffix}`)
       }
 
+      // Generate .d.ts if requested
+      if (options.dts) {
+        try {
+          const dtsContent = generateDTS(result, source)
+          const dtsPath = outputPath.replace(/\.js$/, '.d.ts')
+
+          const dtsDir = dirname(dtsPath)
+          if (dtsDir && !existsSync(dtsDir)) {
+            mkdirSync(dtsDir, { recursive: true })
+          }
+
+          writeFileSync(dtsPath, dtsContent)
+          if (options.verbose) {
+            console.log(`  ${dtsPath}`)
+          }
+        } catch (dtsError: any) {
+          if (options.verbose) {
+            console.log(`  .d.ts skipped: ${dtsError.message}`)
+          }
+        }
+      }
+
       // Generate docs unless suppressed
       if (!options.noDocs) {
         try {

package/src/cli/tjs.ts

@@ -20,7 +20,7 @@ import { emit } from './commands/emit'
 import { convert } from './commands/convert'
 import { test } from './commands/test'
 
-const VERSION = '0.1.0'
+const VERSION = '0.6.0'
 
 const HELP = `
 tjs - Typed JavaScript CLI
@@ -41,6 +41,7 @@ Options:
   -v, --version   Show version
   --debug         Include source locations in __tjs metadata (emit command)
   --unsafe        Strip __tjs metadata for production builds (emit command)
+  --dts           Generate .d.ts declaration file (emit command)
   --no-docs       Suppress documentation generation (emit command)
   --docs-dir <d>  Output docs to separate directory (emit command)
   --jfdi          Emit even if tests fail (just fucking do it)
@@ -82,6 +83,7 @@ async function main() {
   const verbose = args.includes('--verbose') || args.includes('-V')
   const unsafe = args.includes('--unsafe')
   const noDocs = args.includes('--no-docs')
+  const dts = args.includes('--dts')
   const jfdi = args.includes('--jfdi')
   const emitTJS = args.includes('--emit-tjs')
 
@@ -145,6 +147,7 @@ async function main() {
           output,
           verbose,
           noDocs,
+          dts,
           docsDir,
           jfdi,
         })

package/src/lang/codegen.test.ts

@@ -1988,3 +1988,58 @@ function divide(a: 10, b: 2) -? { value: 0, error = '' } {
     })
   })
 })
+
+describe('TS overloads → TJS → JS full pipeline', () => {
+  it('dispatches by arity at runtime', () => {
+    const tsSource = `
+      function greet(name: string): string;
+      function greet(name: string, greeting: string): string;
+      function greet(name: any, greeting?: any): string {
+        return greeting ? greeting + ', ' + name : 'Hello, ' + name;
+      }
+    `
+    const tjsResult = fromTS(tsSource, { emitTJS: true })
+    const jsResult = tjs(tjsResult.code)
+
+    const savedTjs = globalThis.__tjs
+    const { createRuntime } = require('./runtime')
+    try {
+      globalThis.__tjs = createRuntime()
+      const code = jsResult.code.replace(/^const __tjs =.*\n/m, '')
+      const fn = new Function('__tjs', code + '; return greet')(
+        globalThis.__tjs
+      )
+      expect(fn('World')).toBe('Hello, World')
+      expect(fn('World', 'Hi')).toBe('Hi, World')
+    } finally {
+      globalThis.__tjs = savedTjs
+    }
+  })
+
+  it('dispatches by type at same arity', () => {
+    const tsSource = `
+      function process(x: string): string;
+      function process(x: number): number;
+      function process(x: any): any {
+        if (typeof x === 'string') return x.toUpperCase();
+        return x * 2;
+      }
+    `
+    const tjsResult = fromTS(tsSource, { emitTJS: true })
+    const jsResult = tjs(tjsResult.code)
+
+    const savedTjs = globalThis.__tjs
+    const { createRuntime } = require('./runtime')
+    try {
+      globalThis.__tjs = createRuntime()
+      const code = jsResult.code.replace(/^const __tjs =.*\n/m, '')
+      const fn = new Function('__tjs', code + '; return process')(
+        globalThis.__tjs
+      )
+      expect(fn('hello')).toBe('HELLO')
+      expect(fn(42)).toBe(84)
+    } finally {
+      globalThis.__tjs = savedTjs
+    }
+  })
+})

package/src/lang/emitters/dts.test.ts

@@ -0,0 +1,406 @@
+import { describe, it, expect } from 'bun:test'
+import { typeDescriptorToTS, generateDTS } from './dts'
+import type { TypeDescriptor } from '../types'
+import { transpileToJS } from './js'
+
+describe('typeDescriptorToTS', () => {
+  it('should convert primitive kinds', () => {
+    expect(typeDescriptorToTS({ kind: 'string' })).toBe('string')
+    expect(typeDescriptorToTS({ kind: 'number' })).toBe('number')
+    expect(typeDescriptorToTS({ kind: 'boolean' })).toBe('boolean')
+    expect(typeDescriptorToTS({ kind: 'null' })).toBe('null')
+    expect(typeDescriptorToTS({ kind: 'undefined' })).toBe('undefined')
+    expect(typeDescriptorToTS({ kind: 'any' })).toBe('any')
+  })
+
+  it('should map integer and non-negative-integer to number', () => {
+    expect(typeDescriptorToTS({ kind: 'integer' })).toBe('number')
+    expect(typeDescriptorToTS({ kind: 'non-negative-integer' })).toBe('number')
+  })
+
+  it('should handle nullable types', () => {
+    expect(typeDescriptorToTS({ kind: 'string', nullable: true })).toBe(
+      'string | null'
+    )
+    expect(typeDescriptorToTS({ kind: 'integer', nullable: true })).toBe(
+      'number | null'
+    )
+  })
+
+  it('should handle arrays', () => {
+    expect(
+      typeDescriptorToTS({ kind: 'array', items: { kind: 'string' } })
+    ).toBe('string[]')
+    expect(
+      typeDescriptorToTS({ kind: 'array', items: { kind: 'number' } })
+    ).toBe('number[]')
+    expect(typeDescriptorToTS({ kind: 'array' })).toBe('any[]')
+  })
+
+  it('should wrap union items in parens for arrays', () => {
+    const td: TypeDescriptor = {
+      kind: 'array',
+      items: {
+        kind: 'union',
+        members: [{ kind: 'string' }, { kind: 'number' }],
+      },
+    }
+    expect(typeDescriptorToTS(td)).toBe('(string | number)[]')
+  })
+
+  it('should handle object shapes', () => {
+    const td: TypeDescriptor = {
+      kind: 'object',
+      shape: {
+        name: { kind: 'string' },
+        age: { kind: 'integer' },
+      },
+    }
+    expect(typeDescriptorToTS(td)).toBe('{ name: string; age: number }')
+  })
+
+  it('should handle empty objects', () => {
+    expect(typeDescriptorToTS({ kind: 'object' })).toBe('Record<string, any>')
+    expect(typeDescriptorToTS({ kind: 'object', shape: {} })).toBe(
+      'Record<string, any>'
+    )
+  })
+
+  it('should handle unions', () => {
+    const td: TypeDescriptor = {
+      kind: 'union',
+      members: [{ kind: 'string' }, { kind: 'integer' }],
+    }
+    expect(typeDescriptorToTS(td)).toBe('string | number')
+  })
+
+  it('should handle nested object in array', () => {
+    const td: TypeDescriptor = {
+      kind: 'array',
+      items: {
+        kind: 'object',
+        shape: {
+          id: { kind: 'integer' },
+          label: { kind: 'string' },
+        },
+      },
+    }
+    expect(typeDescriptorToTS(td)).toBe('{ id: number; label: string }[]')
+  })
+
+  it('should handle nullable object', () => {
+    const td: TypeDescriptor = {
+      kind: 'object',
+      nullable: true,
+      shape: { x: { kind: 'number' } },
+    }
+    expect(typeDescriptorToTS(td)).toBe('{ x: number } | null')
+  })
+})
+
+describe('generateDTS', () => {
+  it('should generate declarations for exported functions', () => {
+    const source = `
+export function greet(name: 'Alice') -> '' {
+  return \`Hello, \${name}!\`
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('export declare function greet(')
+    expect(dts).toContain('name: string')
+    expect(dts).toContain('): string;')
+  })
+
+  it('should handle optional parameters', () => {
+    const source = `
+export function greet(name = 'world') -> '' {
+  return \`Hello, \${name}!\`
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('name?: string')
+  })
+
+  it('should handle multiple parameters and return types', () => {
+    const source = `
+export function add(a: 0, b: 0) -> 0 {
+  return a + b
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('a: number')
+    expect(dts).toContain('b: number')
+    expect(dts).toContain('): number;')
+  })
+
+  it('should skip non-exported functions when exports exist', () => {
+    const source = `
+function helper(x: '') -> '' {
+  return x.toUpperCase()
+}
+
+export function greet(name: 'Alice') -> '' {
+  return helper(name)
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('export declare function greet(')
+    expect(dts).not.toContain('helper')
+  })
+
+  it('should treat all functions as exported when no exports exist', () => {
+    const source = `
+function add(a: 0, b: 0) -> 0 {
+  return a + b
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('declare function add(')
+  })
+
+  it('should handle object parameter shapes', () => {
+    const source = `
+export function createUser(user: { name: '', age: 0 }) -> { id: 0, name: '' } {
+  return { id: 1, name: user.name }
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('user: { name: string; age: number }')
+    expect(dts).toContain('): { id: number; name: string };')
+  })
+
+  it('should handle nullable parameters', () => {
+    const source = `
+export function find(id: 0 | null) -> '' {
+  return id ? 'found' : 'not found'
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('id: number | null')
+  })
+
+  it('should skip polymorphic variant functions', () => {
+    const source = `
+export function area(radius: 3.14) {
+  return Math.PI * radius * radius
+}
+export function area(w: 0.0, h: 0.0) {
+  return w * h
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    const areaCount = (dts.match(/function area/g) || []).length
+    expect(areaCount).toBe(1)
+    expect(dts).not.toContain('area$')
+  })
+
+  it('should include JSDoc from TDoc comments', () => {
+    const source = `
+/*# Greet a person by name */
+function greet(name: 'Alice') -> '' {
+  return \`Hello, \${name}!\`
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('/** Greet a person by name */')
+  })
+
+  it('should wrap in module declaration when moduleName is given', () => {
+    const source = `
+export function add(a: 0, b: 0) -> 0 {
+  return a + b
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source, { moduleName: 'my-lib' })
+
+    expect(dts).toContain("declare module 'my-lib'")
+    expect(dts).toContain('  export declare function add(')
+    expect(dts).toContain('}')
+  })
+
+  it('should handle array return types', () => {
+    const source = `
+export function getNames(count: 0) -> [''] {
+  return Array(count).fill('test')
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('): string[];')
+  })
+})
+
+describe('generateDTS — classes', () => {
+  it('should emit exported class as callable function returning any', () => {
+    const source = `
+export class Point {
+  constructor(x: 0.0, y: 0.0) {
+    this.x = x
+    this.y = y
+  }
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    // Callable form (matches TJS wrapClass behavior)
+    expect(dts).toContain(
+      'export declare function Point(x: number, y: number): any;'
+    )
+    // Also class form for `new` usage
+    expect(dts).toContain('export declare class Point {')
+    expect(dts).toContain('constructor(x: number, y: number);')
+  })
+
+  it('should emit class with methods', () => {
+    const source = `
+export class Vec {
+  constructor(x: 0.0, y: 0.0) {
+    this.x = x
+    this.y = y
+  }
+
+  add(other: { x: 0.0, y: 0.0 }) {
+    return { x: this.x + other.x, y: this.y + other.y }
+  }
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('add(other: Record<string, any>): any;')
+  })
+
+  it('should handle class exported via export { Name }', () => {
+    const source = `
+class DateTime {
+  constructor(initial: '' | 0 | null) {
+    this.value = initial
+  }
+}
+
+export { DateTime }
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('export declare function DateTime(')
+    expect(dts).toContain('initial: string | number | null')
+  })
+
+  it('should not emit non-exported class when exports exist', () => {
+    const source = `
+class Internal {
+  constructor(x: 0) {
+    this.x = x
+  }
+}
+
+export function make(n: 0) {
+  return new Internal(n)
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).not.toContain('Internal')
+    expect(dts).toContain('export declare function make(')
+  })
+})
+
+describe('generateDTS — Type declarations', () => {
+  it('should emit Type as type guard object', () => {
+    const source = `
+export Type Name = 'World'
+
+export function greet(name: Name) -> '' {
+  return \`Hello, \${name}!\`
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('export declare const Name:')
+    expect(dts).toContain('check(value: any): boolean')
+    expect(dts).toContain('default: string')
+  })
+
+  it('should emit Type with simple value example', () => {
+    const source = `
+export Type Count = 0
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('default: number')
+  })
+})
+
+describe('generateDTS — Generic declarations', () => {
+  it('should emit Generic as factory function', () => {
+    const source = `
+export Generic Box<T> {
+  description: 'a boxed value'
+  predicate(obj, T) { return typeof obj === 'object' && T(obj.value) }
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('export declare function Box(')
+    expect(dts).toContain('...args: any[]')
+    expect(dts).toContain('check(value: any): boolean')
+  })
+})
+
+describe('generateDTS — mixed declarations', () => {
+  it('should handle file with functions, classes, types, and generics', () => {
+    const source = `
+export Type Name = 'World'
+
+export Generic Box<T> {
+  description: 'a boxed value'
+  predicate(obj, T) { return true }
+}
+
+export class Point {
+  constructor(x: 0.0, y: 0.0) {
+    this.x = x
+    this.y = y
+  }
+}
+
+export function greet(name: '') -> '' {
+  return \`Hello, \${name}!\`
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    // All four kinds present
+    expect(dts).toContain('export declare function greet(')
+    expect(dts).toContain('export declare function Point(')
+    expect(dts).toContain('export declare const Name:')
+    expect(dts).toContain('export declare function Box(')
+  })
+})