tjs-lang 0.2.0

package/bin/benchmarks.ts

@@ -0,0 +1,351 @@
+#!/usr/bin/env bun
+/**
+ * TJS Benchmark Runner
+ *
+ * Runs performance benchmarks and generates benchmarks.md
+ *
+ * Usage: bun bin/benchmarks.ts
+ */
+
+import { writeFileSync } from 'fs'
+import { execSync } from 'child_process'
+import { tjs } from '../src/lang'
+
+const ITERATIONS = 100_000
+
+interface BenchmarkResult {
+  name: string
+  baseline: number
+  safe?: number
+  unsafe?: number
+  unit: string
+}
+
+const results: BenchmarkResult[] = []
+
+function benchmark(name: string, fn: () => void): number {
+  // Warmup
+  for (let i = 0; i < 1000; i++) fn()
+
+  const start = performance.now()
+  for (let i = 0; i < ITERATIONS; i++) fn()
+  return performance.now() - start
+}
+
+function formatRatio(value: number, baseline: number): string {
+  const ratio = value / baseline
+  if (ratio < 1.05 && ratio > 0.95) return '~1.0x'
+  return `${ratio.toFixed(1)}x`
+}
+
+console.log('Running TJS benchmarks...\n')
+
+// CLI Cold Start
+console.log('CLI Cold Start:')
+const testFile = '/tmp/bench-test.tjs'
+writeFileSync(testFile, `function add(a: 1, b: 2) -> 0 { return a + b }`)
+
+function measureCLI(cmd: string): number {
+  const times: number[] = []
+  for (let i = 0; i < 5; i++) {
+    const start = performance.now()
+    execSync(cmd, { stdio: 'pipe' })
+    times.push(performance.now() - start)
+  }
+  times.sort((a, b) => a - b)
+  return times[Math.floor(times.length / 2)]
+}
+
+const bunTsTime = measureCLI('bun /tmp/bench-test.tjs 2>/dev/null || true')
+const tjsxTime = measureCLI(
+  `bun ${import.meta.dir}/../src/cli/tjsx.ts ${testFile}`
+)
+const tjsEmitTime = measureCLI(
+  `bun ${import.meta.dir}/../src/cli/tjs.ts emit ${testFile}`
+)
+const tjsCheckTime = measureCLI(
+  `bun ${import.meta.dir}/../src/cli/tjs.ts check ${testFile}`
+)
+
+console.log(`  Bun (TS baseline): ${bunTsTime.toFixed(0)}ms`)
+console.log(`  tjsx:              ${tjsxTime.toFixed(0)}ms`)
+console.log(`  tjs emit:          ${tjsEmitTime.toFixed(0)}ms`)
+console.log(`  tjs check:         ${tjsCheckTime.toFixed(0)}ms`)
+
+results.push({
+  name: 'CLI: Bun + TypeScript',
+  baseline: bunTsTime,
+  unit: 'ms',
+})
+results.push({
+  name: 'CLI: tjsx (execute TJS)',
+  baseline: tjsxTime,
+  unit: 'ms',
+})
+results.push({
+  name: 'CLI: tjs emit',
+  baseline: tjsEmitTime,
+  unit: 'ms',
+})
+results.push({
+  name: 'CLI: tjs check',
+  baseline: tjsCheckTime,
+  unit: 'ms',
+})
+
+// Simple Arithmetic - comparing safe vs unsafe(!)
+console.log('\nSimple Arithmetic:')
+function legacyDouble(x: number): number {
+  return x * 2
+}
+
+// Safe function (default) - will have inline validation
+const safeDoubleResult = tjs(`function safeDouble(x: 0) -> 0 { return x * 2 }`)
+const safeDouble = new Function(
+  `${safeDoubleResult.code}; return safeDouble;`
+)()
+
+// Unsafe function with (!) - no validation wrapper
+const unsafeDoubleResult = tjs(
+  `function unsafeDouble(! x: 0) -> 0 { return x * 2 }`
+)
+const unsafeDouble = new Function(
+  `${unsafeDoubleResult.code}; return unsafeDouble;`
+)()
+
+const legacyTime = benchmark('legacy', () => legacyDouble(42))
+const safeTime = benchmark('safe', () => safeDouble(42))
+const unsafeTime = benchmark('unsafe(!)', () => unsafeDouble(42))
+
+console.log(`  Legacy JS:     ${legacyTime.toFixed(2)}ms`)
+console.log(
+  `  Safe (default): ${safeTime.toFixed(2)}ms (${formatRatio(
+    safeTime,
+    legacyTime
+  )})`
+)
+console.log(
+  `  Unsafe (!):    ${unsafeTime.toFixed(2)}ms (${formatRatio(
+    unsafeTime,
+    legacyTime
+  )})`
+)
+
+results.push({
+  name: 'Simple arithmetic (100K iterations)',
+  baseline: legacyTime,
+  safe: safeTime,
+  unsafe: unsafeTime,
+  unit: 'ms',
+})
+
+// Object Manipulation
+console.log('\nObject Manipulation:')
+function legacyTransform(x: number, y: number) {
+  return { sum: x + y, product: x * y }
+}
+
+const safeTransformResult = tjs(`
+  function safeTransform(x: 0, y: 0) -> { sum: 0, product: 0 } {
+    return { sum: x + y, product: x * y }
+  }
+`)
+const safeTransform = new Function(
+  `${safeTransformResult.code}; return safeTransform;`
+)()
+
+const unsafeTransformResult = tjs(`
+  function unsafeTransform(! x: 0, y: 0) -> { sum: 0, product: 0 } {
+    return { sum: x + y, product: x * y }
+  }
+`)
+const unsafeTransform = new Function(
+  `${unsafeTransformResult.code}; return unsafeTransform;`
+)()
+
+const legacyObjTime = benchmark('legacy', () => legacyTransform(3, 4))
+const safeObjTime = benchmark('safe', () => safeTransform(3, 4))
+const unsafeObjTime = benchmark('unsafe(!)', () => unsafeTransform(3, 4))
+
+console.log(`  Legacy JS:     ${legacyObjTime.toFixed(2)}ms`)
+console.log(
+  `  Safe (default): ${safeObjTime.toFixed(2)}ms (${formatRatio(
+    safeObjTime,
+    legacyObjTime
+  )})`
+)
+console.log(
+  `  Unsafe (!):    ${unsafeObjTime.toFixed(2)}ms (${formatRatio(
+    unsafeObjTime,
+    legacyObjTime
+  )})`
+)
+
+results.push({
+  name: 'Object manipulation (100K iterations)',
+  baseline: legacyObjTime,
+  safe: safeObjTime,
+  unsafe: unsafeObjTime,
+  unit: 'ms',
+})
+
+// 3-Function Chain - safe vs unsafe
+console.log('\n3-Function Chain:')
+
+// Create safe chain
+const safeStep1Result = tjs(`function safeStep1(x: 0) -> 0 { return x * 2 }`)
+const safeStep2Result = tjs(`function safeStep2(x: 0) -> 0 { return x + 10 }`)
+const safeStep3Result = tjs(`function safeStep3(x: 0) -> 0 { return x / 2 }`)
+
+const safeStep1 = new Function(`${safeStep1Result.code}; return safeStep1;`)()
+const safeStep2 = new Function(`${safeStep2Result.code}; return safeStep2;`)()
+const safeStep3 = new Function(`${safeStep3Result.code}; return safeStep3;`)()
+
+// Create unsafe chain with (!)
+const unsafeStep1Result = tjs(
+  `function unsafeStep1(! x: 0) -> 0 { return x * 2 }`
+)
+const unsafeStep2Result = tjs(
+  `function unsafeStep2(! x: 0) -> 0 { return x + 10 }`
+)
+const unsafeStep3Result = tjs(
+  `function unsafeStep3(! x: 0) -> 0 { return x / 2 }`
+)
+
+const unsafeStep1 = new Function(
+  `${unsafeStep1Result.code}; return unsafeStep1;`
+)()
+const unsafeStep2 = new Function(
+  `${unsafeStep2Result.code}; return unsafeStep2;`
+)()
+const unsafeStep3 = new Function(
+  `${unsafeStep3Result.code}; return unsafeStep3;`
+)()
+
+const plainChain = (x: number) => (x * 2 + 10) / 2
+
+const plainChainTime = benchmark('plain', () => plainChain(5))
+const safeChainTime = benchmark('safe', () =>
+  safeStep3(safeStep2(safeStep1(5)))
+)
+const unsafeChainTime = benchmark('unsafe(!)', () =>
+  unsafeStep3(unsafeStep2(unsafeStep1(5)))
+)
+
+console.log(`  Plain chain:   ${plainChainTime.toFixed(2)}ms`)
+console.log(
+  `  Safe chain:    ${safeChainTime.toFixed(2)}ms (${formatRatio(
+    safeChainTime,
+    plainChainTime
+  )})`
+)
+console.log(
+  `  Unsafe chain:  ${unsafeChainTime.toFixed(2)}ms (${formatRatio(
+    unsafeChainTime,
+    plainChainTime
+  )})`
+)
+
+results.push({
+  name: '3-function chain (100K iterations)',
+  baseline: plainChainTime,
+  safe: safeChainTime,
+  unsafe: unsafeChainTime,
+  unit: 'ms',
+})
+
+// Generate Markdown
+console.log('\nGenerating benchmarks.md...')
+
+const date = new Date().toISOString().split('T')[0]
+const nodeVersion = process.versions.bun || process.version
+const platform = `${process.platform} ${process.arch}`
+
+let markdown = `# TJS Benchmarks
+
+Generated: ${date}
+Runtime: Bun ${nodeVersion}
+Platform: ${platform}
+Iterations: ${ITERATIONS.toLocaleString()} per test
+
+## Summary
+
+| Benchmark | Baseline | Safe (default) | Unsafe (!) |
+|-----------|----------|----------------|------------|
+`
+
+for (const r of results) {
+  const baseline = `${r.baseline.toFixed(1)}${r.unit}`
+  const safeCol = r.safe
+    ? `${r.safe.toFixed(1)}${r.unit} (${formatRatio(r.safe, r.baseline)})`
+    : '-'
+  const unsafeCol = r.unsafe
+    ? `${r.unsafe.toFixed(1)}${r.unit} (${formatRatio(r.unsafe, r.baseline)})`
+    : '-'
+  markdown += `| ${r.name} | ${baseline} | ${safeCol} | ${unsafeCol} |\n`
+}
+
+markdown += `
+## Key Findings
+
+### CLI Cold Start
+
+- **Bun + TypeScript**: ~${bunTsTime.toFixed(0)}ms (native, baseline)
+- **tjsx**: ~${tjsxTime.toFixed(0)}ms (includes TJS transpiler load)
+- **Overhead**: ${(tjsxTime - bunTsTime).toFixed(
+  0
+)}ms for transpiler initialization
+
+The ~${(tjsxTime - bunTsTime).toFixed(
+  0
+)}ms overhead is from loading the acorn parser and TJS transpiler.
+A compiled binary (via \`bun build --compile\`) reduces this to ~20ms.
+
+### Safe vs Unsafe Functions
+
+TJS functions are **safe by default** with runtime type validation.
+Use \`(!)\` to mark functions as unsafe for performance-critical code:
+
+\`\`\`javascript
+// Safe (default) - validates types at runtime
+function add(a: 0, b: 0) -> 0 { return a + b }
+
+// Unsafe - no validation, maximum performance
+function fastAdd(! a: 0, b: 0) -> 0 { return a + b }
+\`\`\`
+
+Performance comparison:
+- Simple arithmetic: Safe ${formatRatio(
+  safeTime,
+  legacyTime
+)} vs Unsafe ${formatRatio(unsafeTime, legacyTime)}
+- Object manipulation: Safe ${formatRatio(
+  safeObjTime,
+  legacyObjTime
+)} vs Unsafe ${formatRatio(unsafeObjTime, legacyObjTime)}
+- 3-function chain: Safe ${formatRatio(
+  safeChainTime,
+  plainChainTime
+)} vs Unsafe ${formatRatio(unsafeChainTime, plainChainTime)}
+
+## Recommendations
+
+1. **Use safe functions at API boundaries** - The default is correct for most code
+2. **Use \`(!)\` for internal hot paths** - When inputs are already validated
+3. **Consider compiled binary for CLI** - \`bun build --compile\` for ~20ms startup
+
+## Running Benchmarks
+
+\`\`\`bash
+bun run bench
+\`\`\`
+
+Or run the test suite with timing output:
+
+\`\`\`bash
+bun test src/lang/perf.test.ts
+\`\`\`
+`
+
+writeFileSync('benchmarks.md', markdown)
+console.log('Done! Written to benchmarks.md')

package/bin/dev.ts

@@ -0,0 +1,205 @@
+/*
+ * dev.ts - Development server for agent-99 demo site
+ *
+ * Run with: bun run bin/dev.ts
+ *
+ * Features:
+ * - Serves demo site on https://localhost:8080
+ * - Watches for file changes and rebuilds
+ * - Auto-regenerates docs.json when source files change
+ */
+
+import { watch } from 'fs'
+import { join } from 'path'
+import { $, spawn } from 'bun'
+
+const PORT = 8699 // Homage to Agent-99
+
+// Kill any existing process on our port
+async function killExistingServer() {
+  try {
+    const result = await $`lsof -ti:${PORT}`.quiet()
+    const pids = result.text().trim().split('\n').filter(Boolean)
+    for (const pid of pids) {
+      console.log(`Killing existing process on port ${PORT} (PID: ${pid})`)
+      await $`kill -9 ${pid}`.quiet()
+    }
+  } catch {
+    // No process on port, that's fine
+  }
+}
+
+await killExistingServer()
+const DEMO_DIR = './demo'
+const DOCS_DIR = './docs'
+const SRC_DIR = './src'
+const EDITORS_DIR = './editors'
+const ROOT_DIR = '.'
+
+// Build the demo
+async function buildDemo() {
+  console.log('Building demo...')
+
+  try {
+    // Generate docs.json
+    await $`node bin/docs.js`
+
+    // Build the demo app (bundle everything for browser)
+    const result = await Bun.build({
+      entrypoints: ['./demo/src/index.ts'],
+      outdir: './docs',
+      minify: false,
+      sourcemap: 'external',
+      target: 'browser',
+    })
+
+    if (!result.success) {
+      console.error('Build failed:')
+      for (const log of result.logs) {
+        console.error(log)
+      }
+      return
+    }
+
+    // Copy static files
+    await $`cp demo/index.html demo/static/favicon.svg demo/static/photo-*.jpg tjs-lang.svg docs/`
+    await $`cp -r demo/static/texts docs/`
+
+    console.log('Build complete!')
+  } catch (error) {
+    console.error(
+      'Build error:',
+      error instanceof Error ? error.message : error
+    )
+  }
+}
+
+// Initial build
+await buildDemo()
+
+// Debounce rebuilds to avoid multiple rapid rebuilds
+let rebuildTimeout: ReturnType<typeof setTimeout> | null = null
+let isBuilding = false
+
+async function debouncedBuild(source: string) {
+  if (rebuildTimeout) {
+    clearTimeout(rebuildTimeout)
+  }
+  rebuildTimeout = setTimeout(async () => {
+    if (isBuilding) {
+      // Schedule another build after current one finishes
+      debouncedBuild(source)
+      return
+    }
+    isBuilding = true
+    console.log(`\n${source}`)
+    await buildDemo()
+    isBuilding = false
+  }, 100)
+}
+
+// Watch for changes
+const watcher = watch(SRC_DIR, { recursive: true }, (event, filename) => {
+  debouncedBuild(`File changed: ${filename}`)
+})
+
+const demoWatcher = watch(
+  `${DEMO_DIR}/src`,
+  { recursive: true },
+  (event, filename) => {
+    debouncedBuild(`Demo file changed: ${filename}`)
+  }
+)
+
+// Watch for editor changes
+const editorsWatcher = watch(
+  EDITORS_DIR,
+  { recursive: true },
+  (event, filename) => {
+    debouncedBuild(`Editor file changed: ${filename}`)
+  }
+)
+
+// Watch for markdown file changes in root
+const mdWatcher = watch(ROOT_DIR, { recursive: false }, (event, filename) => {
+  if (filename && filename.endsWith('.md')) {
+    debouncedBuild(`Markdown file changed: ${filename}`)
+  }
+})
+
+// Serve the docs directory
+const server = Bun.serve({
+  port: PORT,
+  async fetch(req) {
+    const url = new URL(req.url)
+    let pathname = url.pathname
+
+    // Default to index.html
+    if (pathname === '/') {
+      pathname = '/index.html'
+    }
+
+    // Try to serve from docs directory
+    const filePath = join(DOCS_DIR, pathname)
+    const file = Bun.file(filePath)
+
+    if (await file.exists()) {
+      // Set appropriate content type
+      const ext = pathname.split('.').pop()
+      const contentTypes: Record<string, string> = {
+        html: 'text/html',
+        js: 'application/javascript',
+        css: 'text/css',
+        json: 'application/json',
+        svg: 'image/svg+xml',
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        webp: 'image/webp',
+        gif: 'image/gif',
+        ico: 'image/x-icon',
+        map: 'application/json',
+      }
+
+      return new Response(file, {
+        headers: {
+          'Content-Type': contentTypes[ext || 'html'] || 'text/plain',
+          'Access-Control-Allow-Origin': '*',
+        },
+      })
+    }
+
+    // For SPA routing, serve index.html for unknown paths
+    const indexFile = Bun.file(join(DOCS_DIR, 'index.html'))
+    if (await indexFile.exists()) {
+      return new Response(indexFile, {
+        headers: { 'Content-Type': 'text/html' },
+      })
+    }
+
+    return new Response('Not Found', { status: 404 })
+  },
+})
+
+console.log(`
+  Development server running at http://localhost:${PORT}
+
+  Watching for changes in:
+  - ${SRC_DIR}/
+  - ${DEMO_DIR}/src/
+  - ${EDITORS_DIR}/
+  - *.md (root directory)
+
+  Press Ctrl+C to stop
+`)
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\nShutting down...')
+  watcher.close()
+  demoWatcher.close()
+  editorsWatcher.close()
+  mdWatcher.close()
+  server.stop()
+  process.exit(0)
+})