tjs-lang 0.8.1 → 0.8.2

package/src/lang/emitters/js.ts

@@ -81,6 +81,18 @@ export interface TJSTranspileOptions {
   sourceMap?: boolean
   /** Mode: 'dev' | 'strict' | 'production' */
   mode?: 'dev' | 'strict' | 'production'
+  /**
+   * Source dialect — what kind of source this string is:
+   * - `'tjs'` (default for a bare string): native TJS, footgun-removal modes ON
+   *   (structural `==`, `TjsStandard`, etc.).
+   * - `'js'`: plain JavaScript — modes OFF, `safety: 'none'`; the source's own
+   *   semantics are preserved (no `==`→`Eq`, no truthiness rewrite, no input
+   *   validation). Use this when feeding tjs() a vanilla `.js` string so it
+   *   transpiles without changing meaning. See PRINCIPLES.md (TJS ⊇ JS).
+   *
+   * For TypeScript, use the `fromTS` entry point (TS → TJS → JS).
+   */
+  dialect?: 'js' | 'tjs'
   /**
    * Test execution mode:
    * - true (default): run tests at transpile time, throw on failure
@@ -640,6 +652,7 @@ export function transpileToJS(
   } = parse(cleanSource, {
     filename,
     colonShorthand: true,
+    dialect: options.dialect,
     moduleLoader: options.moduleLoader,
   })
 
@@ -650,6 +663,7 @@ export function transpileToJS(
   // Pass through the moduleLoader so Phase 3 cross-file wasm composition
   // sees imported `wasm function` declarations.
   const preprocessed = preprocess(cleanSource, {
+    dialect: options.dialect,
     moduleLoader: options.moduleLoader,
     filename,
   })
@@ -1119,8 +1133,11 @@ export function transpileToJS(
     )
 
     // Check for failures and throw only if runTests === true (strict mode)
-    // 'only' and 'report' modes return results without throwing
-    const failures = testResults.filter((r) => !r.passed)
+    // 'only' and 'report' modes return results without throwing.
+    // Inconclusive results (a test that couldn't *run* — undefined refs like AJS
+    // atoms, or a module the harness can't execute) never block transpilation:
+    // that would turn subset-legal code illegal. See PRINCIPLES.md.
+    const failures = testResults.filter((r) => !r.passed && !r.inconclusive)
     if (failures.length > 0 && runTests === true) {
       const errorLines = failures.map((f) => {
         if (f.isSignatureTest) {

package/src/lang/features.test.ts

@@ -1097,14 +1097,15 @@ describe('signature tests (transpile-time)', () => {
     `,
       { runTests: 'report' }
     )
-    // Should have a signature test result that's skipped (passed), not failed
+    // The test can't run (unresolved import) → inconclusive, not failed.
+    // Inconclusive never blocks transpilation (see PRINCIPLES.md).
     expect(result.testResults).toBeDefined()
     const sigTest = result.testResults!.find((t: any) =>
       t.description.includes('validateUser')
     )
     expect(sigTest).toBeDefined()
-    expect(sigTest?.passed).toBe(true)
-    expect(sigTest?.error).toBeUndefined()
+    expect(sigTest?.passed).toBe(false)
+    expect(sigTest?.inconclusive).toBe(true)
   })
 
   it('should skip tests gracefully when imports are unresolved (function-level)', () => {
@@ -1124,8 +1125,8 @@ describe('signature tests (transpile-time)', () => {
       t.description.includes('formatDate')
     )
     expect(sigTest).toBeDefined()
-    expect(sigTest?.passed).toBe(true)
-    expect(sigTest?.error).toBeUndefined()
+    expect(sigTest?.passed).toBe(false)
+    expect(sigTest?.inconclusive).toBe(true)
   })
 
   it('should test sync functions alongside async functions', () => {

package/src/lang/index.ts

@@ -27,11 +27,23 @@ import type {
   TranspileResult,
   FunctionSignature,
 } from './types'
-import { parse, validateSingleFunction } from './parser'
+import { parse, extractFunctions } from './parser'
 import { transformFunction } from './emitters/ast'
 
 export * from './types'
-export { parse, preprocess, extractTDoc } from './parser'
+export {
+  parse,
+  preprocess,
+  extractTDoc,
+  validateSingleFunction,
+  extractFunctions,
+} from './parser'
+export {
+  dialectForFilename,
+  sourceKindForFilename,
+  type Dialect,
+  type SourceKind,
+} from './dialect'
 export { transformFunction } from './emitters/ast'
 export {
   transpileToJS,
@@ -177,15 +189,16 @@ export function transpile(
   })
 
   // Validate structure
-  const func = validateSingleFunction(program, options.filename)
+  const { entry, helpers } = extractFunctions(program, options.filename)
 
   // Transform to Agent99 AST
   const { ast, signature, warnings } = transformFunction(
-    func,
+    entry,
     originalSource,
     returnType,
     options,
-    requiredParams
+    requiredParams,
+    helpers.size > 0 ? helpers : undefined
   )
 
   return {

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
+  /**
+   * Source dialect — tells the transpiler what kind of source this string is:
+   * - `'tjs'`: native TJS, all footgun-removal modes ON (structural `==`,
+   *   `TjsStandard`, etc.). This is the default for a bare string.
+   * - `'js'`: plain JavaScript — modes OFF and `safety: 'none'`, so the source's
+   *   own semantics are preserved (no `==`→`Eq`, no truthiness rewrite, etc.).
+   *
+   * Authoritative when set; otherwise the dialect is inferred (the fromTS
+   * annotation and `vmTarget` ⇒ JS-compatible). See PRINCIPLES.md (TJS ⊇ JS).
+   */
+  dialect?: 'js' | 'tjs'
   /**
    * Optional ModuleLoader for cross-file `wasm function` composition (Phase 3).
    * When provided, imports are resolved at transpile time and matching wasm
@@ -109,6 +120,12 @@ export interface PreprocessOptions {
    * Default: false (transform == to Is() for TJS code running in regular JS)
    */
   vmTarget?: boolean
+  /**
+   * Source dialect: `'js'` ⇒ modes OFF / `safety: 'none'` (preserve plain-JS
+   * semantics); `'tjs'` ⇒ native modes ON. Authoritative when set; otherwise
+   * inferred from the fromTS annotation / `vmTarget`. See ParseOptions.dialect.
+   */
+  dialect?: 'js' | 'tjs'
   /**
    * Optional ModuleLoader for cross-file `wasm function` composition (Phase 3).
    * See ParseOptions.moduleLoader for details.

package/src/lang/parser.test.ts

@@ -814,13 +814,19 @@ test 'always fails' { throw new Error('intentional') }
   })
 
   describe('Error handling', () => {
-    it('should reject multiple functions', () => {
-      expect(() =>
-        transpile(`
-        function a() {}
-        function b() {}
+    it('accepts multiple functions as local helpers (last is the entry)', () => {
+      // Multiple top-level functions are now the local-helpers feature: the
+      // last declaration is the entry point, the rest are helpers called by
+      // name via callLocal. See use-cases/local-helpers.test.ts for semantics.
+      const { ast } = transpile(`
+        function helper(x: 0): 0 { return x }
+        function main(n: 0): 0 {
+          const r = helper(n)
+          return r
+        }
       `)
-      ).toThrow('Only a single function')
+      // Unused/used helpers are collected onto the root node by name.
+      expect((ast as any).helpers?.helper).toBeDefined()
     })
 
     it('should require a function when only a class is provided', () => {

package/src/lang/parser.ts

@@ -135,9 +135,17 @@ export function preprocess(
   // The /* tjs <- filename */ annotation is the signal
   const isFromTS = /\/\*\s*tjs\s*<-\s*\S+\s*\*\//.test(source)
 
-  // Native TJS: all modes ON by default (TJS is its own language)
-  // TS-originated or VM target (AJS): all modes OFF, safety none (JS-compatible)
-  const isCompat = isFromTS || options.vmTarget
+  // Native TJS: all modes ON by default (TJS is its own language).
+  // Plain JS (dialect: 'js'), TS-originated, or VM target: all modes OFF +
+  // safety none, so the source's own semantics are preserved (JS-compatible).
+  // An explicit `dialect` is authoritative; otherwise infer from the fromTS
+  // annotation / vmTarget. See PRINCIPLES.md (TJS ⊇ JS).
+  const isCompat =
+    options.dialect === 'js'
+      ? true
+      : options.dialect === 'tjs'
+      ? false
+      : isFromTS || options.vmTarget
   const tjsModes: TjsModes = isCompat
     ? {
         tjsEquals: false,
@@ -452,6 +460,7 @@ export function parse(
     filename = '<source>',
     colonShorthand = true,
     vmTarget = false,
+    dialect,
   } = options
 
   // Preprocess for custom syntax
@@ -472,6 +481,7 @@ export function parse(
   } = colonShorthand
     ? preprocess(source, {
         vmTarget,
+        dialect,
         moduleLoader: options.moduleLoader,
         filename: options.filename,
       })
@@ -602,6 +612,106 @@ export function validateSingleFunction(
   return functions[0]
 }
 
+/**
+ * Extract top-level function declarations from the parsed program.
+ *
+ * Returns `{ entry, helpers }` where:
+ *   - `entry` is the last function declaration (the agent's entry point)
+ *   - `helpers` are all preceding function declarations, looked up by name
+ *
+ * This matches the natural "helpers first, agent last" pattern, including
+ * the TOOL_LIBRARY use case where helper async wrappers are prepended
+ * before the user-supplied agent function.
+ *
+ * Same top-level construct restrictions as `validateSingleFunction`:
+ * imports, exports, and classes are rejected.
+ */
+export function extractFunctions(
+  ast: Program,
+  filename?: string
+): { entry: FunctionDeclaration; helpers: Map<string, FunctionDeclaration> } {
+  // Top-level construct checks (same as validateSingleFunction)
+  for (const node of ast.body) {
+    if (node.type === 'ImportDeclaration') {
+      throw new SyntaxError(
+        'Imports are not supported. All atoms must be registered with the VM.',
+        node.loc?.start || { line: 1, column: 0 },
+        undefined,
+        filename
+      )
+    }
+
+    if (
+      node.type === 'ExportNamedDeclaration' ||
+      node.type === 'ExportDefaultDeclaration'
+    ) {
+      throw new SyntaxError(
+        'Exports are not supported. The function is automatically exported.',
+        node.loc?.start || { line: 1, column: 0 },
+        undefined,
+        filename
+      )
+    }
+
+    if (node.type === 'ClassDeclaration') {
+      throw new SyntaxError(
+        'Classes are not supported. Agent99 uses functional composition.',
+        node.loc?.start || { line: 1, column: 0 },
+        undefined,
+        filename
+      )
+    }
+  }
+
+  const functions = ast.body.filter(
+    (node): node is FunctionDeclaration => node.type === 'FunctionDeclaration'
+  )
+
+  if (functions.length === 0) {
+    throw new SyntaxError(
+      'Source must contain a function declaration',
+      { line: 1, column: 0 },
+      undefined,
+      filename
+    )
+  }
+
+  const entry = functions[functions.length - 1]
+  const helpers = new Map<string, FunctionDeclaration>()
+
+  for (let i = 0; i < functions.length - 1; i++) {
+    const fn = functions[i]
+    const name = fn.id?.name
+    if (!name) {
+      throw new SyntaxError(
+        'Helper function must have a name',
+        fn.loc?.start || { line: 1, column: 0 },
+        undefined,
+        filename
+      )
+    }
+    if (helpers.has(name)) {
+      throw new SyntaxError(
+        `Duplicate helper function name: ${name}`,
+        fn.loc?.start || { line: 1, column: 0 },
+        undefined,
+        filename
+      )
+    }
+    if (name === entry.id?.name) {
+      throw new SyntaxError(
+        `Helper function cannot share a name with the entry function: ${name}`,
+        fn.loc?.start || { line: 1, column: 0 },
+        undefined,
+        filename
+      )
+    }
+    helpers.set(name, fn)
+  }
+
+  return { entry, helpers }
+}
+
 /**
  * Extract TDoc comment from before a function
  *

package/src/lang/subset-invariant.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'bun:test'
+import { tjs, transpile } from './index'
+
+/**
+ * Guards the language subset invariants engraved in PRINCIPLES.md:
+ *
+ *   AJS  ⊆  TJS            — every legal AJS source is legal TJS source
+ *   JS   ⊆  TJS (no modes) — every legal JS program is legal TJS
+ *
+ * TJS may do MORE with the same source (enforce contracts, run signature
+ * tests) but must never REJECT source the subset accepts. The classic way this
+ * breaks: a build-time signature test that can't *run* (it calls an AJS atom
+ * that doesn't exist at build time, etc.) gets escalated into a transpile
+ * error. Such tests must be *inconclusive*, never failing.
+ */
+describe('Language subset invariants (PRINCIPLES.md)', () => {
+  // Representative AJS-shaped sources. Each must be valid AJS (transpile to a
+  // VM AST) AND valid TJS (tjs() must not throw). Several carry return types
+  // and call atoms — the exact shape that used to be illegal TJS.
+  const ajsSnippets: Array<[string, string]> = [
+    [
+      'agent returning an object (no types)',
+      `function main(n: 0) {\n  return { doubled: n * 2 }\n}`,
+    ],
+    [
+      'atom call + return type',
+      `function main(url: ''): { x: '' } {\n  const x = httpFetch({ url })\n  return { x }\n}`,
+    ],
+    [
+      'helper with a typed signature',
+      `function double(x: 0): 0 {\n  return x * 2\n}\nfunction main(n: 0) {\n  const d = double(n)\n  return { d }\n}`,
+    ],
+    [
+      'helper that calls an atom + return type',
+      `function fetchIt(u: ''): '' {\n  const r = httpFetch({ url: u })\n  return r\n}\nfunction main(url: '') {\n  const x = fetchIt(url)\n  return { x }\n}`,
+    ],
+    [
+      'consistent signature example still validates',
+      `function add(a: 2, b: 3): 5 {\n  return a + b\n}\nfunction main(x: 0, y: 0) {\n  const s = add(x, y)\n  return { s }\n}`,
+    ],
+  ]
+
+  describe('TJS ⊇ AJS', () => {
+    for (const [label, src] of ajsSnippets) {
+      it(`valid as both AJS and TJS: ${label}`, () => {
+        // Valid AJS (produces a VM AST)…
+        expect(() => transpile(src, { vmTarget: true })).not.toThrow()
+        // …and therefore must be valid TJS (never rejected).
+        expect(() => tjs(src)).not.toThrow()
+      })
+    }
+  })
+
+  it('un-runnable signature tests are inconclusive, not failures', () => {
+    const r = tjs(
+      `function main(url: ''): { x: '' } {\n  const x = httpFetch({ url })\n  return { x }\n}`
+    )
+    const sig = r.testResults?.find((t: any) => t.isSignatureTest)
+    expect(sig).toBeDefined()
+    expect(sig?.passed).toBe(false)
+    expect(sig?.inconclusive).toBe(true)
+  })
+
+  it('still REJECTS a genuinely inconsistent signature example (validation intact)', () => {
+    // 2 + 3 = 5, not 99 — the test runs cleanly and mismatches → hard failure.
+    expect(() =>
+      tjs(`function add(a: 2, b: 3): 99 {\n  return a + b\n}`)
+    ).toThrow(/inconsistent/)
+  })
+
+  describe('TJS (no modes) ⊇ JS', () => {
+    // Plain JavaScript under options-off TJS (TjsCompat disables all modes).
+    const jsSnippets: Array<[string, string]> = [
+      ['arithmetic fn', `function f(x) { return x + 1 }`],
+      [
+        'control flow + array methods',
+        `function f(xs) {\n  let total = 0\n  for (const x of xs) { total += x }\n  return xs.map(v => v * 2).filter(v => v > total)\n}`,
+      ],
+      [
+        'object + destructuring',
+        `function f(o) {\n  const { a, b } = o\n  return { ...o, sum: a + b }\n}`,
+      ],
+    ]
+    for (const [label, src] of jsSnippets) {
+      it(`accepts plain JS: ${label}`, () => {
+        expect(() => tjs(`TjsCompat\n${src}`)).not.toThrow()
+      })
+    }
+  })
+})

package/src/lang/transpiler.ts

@@ -16,6 +16,14 @@ export { transpile, ajs, tjs, createAgent, getToolDefinitions } from './core'
 // Parser
 export { parse, preprocess, extractTDoc } from './parser'
 
+// Dialect resolution for file-based tooling (extension → dialect)
+export {
+  dialectForFilename,
+  sourceKindForFilename,
+  type Dialect,
+  type SourceKind,
+} from './dialect'
+
 // AST emitter
 export { transformFunction } from './emitters/ast'
 

package/src/lang/types.ts

@@ -225,6 +225,21 @@ export interface TransformContext {
   filename: string
   /** Options */
   options: TranspileOptions
+  /**
+   * Helper functions (top-level functions declared before the entry function).
+   * Calls to these names emit `callLocal` instead of treating them as atom calls.
+   */
+  helpers?: Map<string, any /* FunctionDeclaration */>
+  /**
+   * Cache of transformed helper bodies. Lazily populated as helpers are
+   * referenced from the entry function (or from other helpers).
+   */
+  helperSteps?: Map<string, { steps: any[]; paramNames: string[] }>
+  /**
+   * Names of helpers currently being transformed. Used to detect direct or
+   * transitive recursion.
+   */
+  helperTransforming?: Set<string>
 }
 
 /** Create a child context for nested scopes */
@@ -239,6 +254,9 @@ export function createChildContext(parent: TransformContext): TransformContext {
     source: parent.source,
     filename: parent.filename,
     options: parent.options,
+    helpers: parent.helpers,
+    helperSteps: parent.helperSteps,
+    helperTransforming: parent.helperTransforming,
   }
 }
 

package/src/lang/wasm.test.ts

@@ -2317,14 +2317,20 @@ describe('boundary distribution form (Phase 4)', () => {
   async function dynamicImportLibrary(transpiled: string): Promise<any> {
     const { tmpdir } = await import('node:os')
     const { join } = await import('node:path')
-    const { writeFileSync, unlinkSync } = await import('node:fs')
+    const { writeFileSync, unlinkSync, realpathSync } = await import('node:fs')
+    const { pathToFileURL } = await import('node:url')
     const path = join(
       tmpdir(),
       `tjs-lib-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.mjs`
     )
     writeFileSync(path, transpiled)
+    // Resolve macOS /var → /private/var symlink and use file:// URL — bun's
+    // resolver in subsequent test cases (after a `new Function(emittedCode)`
+    // execution earlier in the same file) fails on bare absolute paths with
+    // "Cannot find module ... from ''". This form is robust to that state.
+    const url = pathToFileURL(realpathSync(path)).href
     try {
-      const mod = await import(path)
+      const mod = await import(url)
       // Wait for the async wasm bootstrap inside the module to finish.
       // The bootstrap runs as a top-level IIFE; instantiation is async.
       await new Promise((r) => setTimeout(r, 100))

package/src/linalg/linalg.test.ts

@@ -14,9 +14,10 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { readFileSync } from 'node:fs'
+import { readFileSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
+import { pathToFileURL } from 'node:url'
 import { writeFileSync, unlinkSync } from 'node:fs'
 
 const LINALG_PATH = join(import.meta.dir, 'index.tjs')
@@ -41,8 +42,13 @@ async function dynamicImportLibrary(transpiled: string): Promise<any> {
     `linalg-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.mjs`
   )
   writeFileSync(path, transpiled)
+  // Resolve macOS /var → /private/var symlink and use file:// URL — bun's
+  // resolver in subsequent test cases (after a `new Function(emittedCode)`
+  // execution earlier in the same file) fails on bare absolute paths with
+  // "Cannot find module ... from ''". This form is robust to that state.
+  const url = pathToFileURL(realpathSync(path)).href
   try {
-    const mod = await import(path)
+    const mod = await import(url)
     // Wait for the async wasm bootstrap inside the module to finish
     await new Promise((r) => setTimeout(r, 100))
     return mod

package/src/use-cases/batteries.test.ts

@@ -252,4 +252,8 @@ describe('Batteries Included', () => {
     expect(msg.tool_calls[0].function.name).toBe('get_weather')
     expect(msg.tool_calls[0].function.arguments).toBe('{"city":"Paris"}')
   })
+
+  it('LLM battery atoms have IO-friendly timeouts', () => {
+    expect(llmPredictBattery.timeoutMs).toBeGreaterThanOrEqual(60000)
+  })
 })