tjs-lang 0.8.1 → 0.8.3

package/src/lang/emitters/js-tests.ts

@@ -18,6 +18,13 @@ export interface TestResult {
   error?: string
   /** Whether this was an implicit signature test */
   isSignatureTest?: boolean
+  /**
+   * The test could not be *run* (e.g. it references a name TJS can't resolve at
+   * build time — like an AJS atom — or the harness couldn't execute the module).
+   * Inconclusive ≠ failed: it never blocks transpilation. Surfaced as a warning
+   * (e.g. in the playground). See PRINCIPLES.md ("more, never illegal").
+   */
+  inconclusive?: boolean
   /** Source line number (1-indexed) where the test or error occurred */
   line?: number
   /** Source column number (1-indexed) */
@@ -678,7 +685,7 @@ export function runAllTests(
       ${body}
       __testResults.push({ idx: ${i}, passed: true });
     } catch (e) {
-      __testResults.push({ idx: ${i}, passed: false, error: e.message || String(e) });
+      __testResults.push({ idx: ${i}, passed: false, isRef: e instanceof ReferenceError, error: e.message || String(e) });
     }
   `
     })
@@ -721,7 +728,10 @@ export function runAllTests(
         __sigTestResults.push({ idx: ${i}, passed: false, error: 'Expected ' + __format(__expected) + ' at \\'${testLabel}\\', got ' + __format(__actual) });
       }
     } catch (e) {
-      __sigTestResults.push({ idx: ${i}, passed: false, error: e.message || String(e) });
+      // The function threw on its example inputs — the example couldn't be
+      // *evaluated* (e.g. it calls an atom that doesn't exist at build time).
+      // That's inconclusive, not a mismatch. Never block transpilation on it.
+      __sigTestResults.push({ idx: ${i}, passed: false, threw: true, error: e.message || String(e) });
     }
   `
     })
@@ -834,62 +844,62 @@ export function runAllTests(
       typeMatches
     )
 
-    // Map block test results
+    // Map block test results. A block test that threw a ReferenceError
+    // couldn't *run* (it names something TJS can't resolve at build time, e.g.
+    // an AJS atom) → inconclusive, not failed. An assertion failure (plain
+    // Error from expect()) is a genuine failure.
     for (const r of blockResults) {
       const test = tests[r.idx]
-      // Skip block tests that fail due to unresolved imports
-      const isImportError =
-        hasUnresolvedImports &&
+      const inconclusive =
         !r.passed &&
-        r.error &&
-        /is not defined$/.test(r.error)
+        (r.isRef ||
+          (hasUnresolvedImports && r.error && /is not defined$/.test(r.error)))
       results.push({
         description: test.description,
-        passed: isImportError ? true : r.passed,
-        error: isImportError ? undefined : r.error,
+        passed: r.passed,
+        inconclusive: inconclusive || undefined,
+        error: r.error,
         line: test.line,
       })
     }
 
-    // Map signature test results
+    // Map signature test results. A test that *threw* (couldn't evaluate the
+    // example) is inconclusive; only a clean value-mismatch is a failure.
     for (const r of sigTestResults) {
       const info = syncSigTestInfos[r.idx]
-      // Skip signature tests that fail due to unresolved imports
-      const isImportError =
-        hasUnresolvedImports &&
+      const inconclusive =
         !r.passed &&
-        r.error &&
-        /is not defined$/.test(r.error)
+        (r.threw ||
+          (hasUnresolvedImports && r.error && /is not defined$/.test(r.error)))
       const label = info.className
         ? `${info.className}.${info.funcName}`
         : info.funcName
       results.push({
         description: `${label} signature example`,
-        passed: isImportError ? true : r.passed,
-        error: isImportError ? undefined : r.error,
+        passed: r.passed,
+        inconclusive: inconclusive || undefined,
+        error: r.error,
         isSignatureTest: true,
         line: info.line,
       })
     }
   } catch (e: any) {
-    // If module fails due to unresolved imports (ReferenceError from stripped imports),
-    // skip tests gracefully rather than marking them as failures
-    const isUnresolvedRef = hasUnresolvedImports && e instanceof ReferenceError
-
-    // The error came from module-level code (e.g. an undefined identifier
-    // in `console.log(... x ...)`), NOT from the function/test under test.
-    // Don't attribute a line — otherwise the editor would mark the function
-    // declaration's line as the error site, misleading the user about where
-    // the actual problem is. The test still appears as failed in the test
-    // list with the explanatory message; the user finds the real error
-    // through the runtime console.
+    // The whole module failed to execute, so NO test could run — every result
+    // here is inconclusive, never a failure. Making transpilation fail because
+    // an auto-generated test harness couldn't execute the module would turn
+    // legal code illegal (e.g. a module referencing AJS atoms, or — an edge —
+    // two top-level functions on one line). See PRINCIPLES.md.
+    //
+    // No line is attributed: the error came from module-level execution, not a
+    // specific function, and mis-attributing it would point the editor at the
+    // wrong site. The message is preserved as a warning on each result.
+    const note = `Module could not be executed for testing: ${e.message}`
     for (const test of tests) {
       results.push({
         description: test.description,
-        passed: isUnresolvedRef,
-        error: isUnresolvedRef
-          ? undefined
-          : `Module execution failed: ${e.message}`,
+        passed: false,
+        inconclusive: true,
+        error: note,
       })
     }
     for (const info of syncSigTestInfos) {
@@ -898,10 +908,9 @@ export function runAllTests(
         : info.funcName
       results.push({
         description: `${label} signature example`,
-        passed: isUnresolvedRef,
-        error: isUnresolvedRef
-          ? undefined
-          : `Module execution failed: ${e.message}`,
+        passed: false,
+        inconclusive: true,
+        error: note,
         isSignatureTest: true,
       })
     }

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,45 @@ 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 {
+  verifyPredicate,
+  compilePredicate,
+  suggest,
+  effectfulFromAtoms,
+  formatPredicateDiagnostics,
+  PredicateFuelExhausted,
+  type PredicateDiagnostic,
+  type PredicateVerifyResult,
+  type VerifyPredicateOptions,
+  type CompilePredicateOptions,
+  type Suggestion,
+  type SuggestOptions,
+} from './predicate'
+export {
+  compilePredicateSchema,
+  validatePredicateSchema,
+  type PredicateSchema,
+  type SchemaError,
+  type SchemaValidationResult,
+  type PredicateSchemaOptions,
+} from './predicate-schema'
 export { transformFunction } from './emitters/ast'
 export {
   transpileToJS,
@@ -177,15 +211,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/predicate-schema.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'bun:test'
+import {
+  compilePredicateSchema,
+  validatePredicateSchema,
+  type PredicateSchema,
+} from './predicate-schema'
+
+// A composable color predicate cluster (entry = last function, takes the value).
+const COLOR = `
+  function isHex(v){ return typeof v == 'string' && /^#[0-9a-f]{3,8}$/i.test(v) }
+  function isVar(v){ return typeof v == 'string' && v.startsWith('var(--') && v.endsWith(')') }
+  function isCalc(v){ return typeof v == 'string' && v.startsWith('calc(') && v.endsWith(')') }
+  function isColor(v){ return isHex(v) || isVar(v) || isCalc(v) }
+`
+
+// A recursive predicate cluster — validates a tree of string/number leaves.
+// Note the `!Array.isArray(o)` guard: arrays are objects in JS, so a node check
+// must exclude them explicitly (a real predicate-authoring nuance).
+const TREE = `
+  function isLeaf(v){ return typeof v == 'string' || typeof v == 'number' }
+  function isEntry(pair){ var val = pair[1]; return isLeaf(val) || isNode(val) }
+  function isNode(o){ return typeof o == 'object' && o != null && !Array.isArray(o) && Object.entries(o).every(isEntry) }
+`
+
+const colorSchema: PredicateSchema = {
+  type: 'object',
+  required: ['color'],
+  properties: {
+    color: { type: 'string', description: 'a CSS color', $predicate: COLOR },
+  },
+}
+
+describe('predicate-schema — the computational half of JSON-Schema', () => {
+  it('a predicate-aware validator validates the value grammar', () => {
+    const validate = compilePredicateSchema(colorSchema)
+    expect(validate({ color: '#3a3' }).valid).toBe(true)
+    expect(validate({ color: 'var(--brand)' }).valid).toBe(true) // TS/JSON-Schema can't
+    expect(validate({ color: 'calc(1px + 1em)' }).valid).toBe(true)
+
+    const bad = validate({ color: 'notacolor' })
+    expect(bad.valid).toBe(false)
+    expect(bad.errors[0].path).toBe('/color')
+  })
+
+  it('still does structural validation (type / required)', () => {
+    const validate = compilePredicateSchema(colorSchema)
+    expect(validate({ color: 123 }).errors[0].message).toMatch(
+      /expected string/
+    )
+    expect(validate({}).errors[0].message).toMatch(/missing required 'color'/)
+  })
+
+  it('progressive enhancement: a naive validator ignores `$predicate`', () => {
+    // ignorePredicates models any standard JSON-Schema validator that doesn't
+    // know the keyword — it sees only `type: string`.
+    const naive = compilePredicateSchema(colorSchema, {
+      ignorePredicates: true,
+    })
+    expect(naive({ color: 'notacolor' }).valid).toBe(true) // string → passes
+    // …while the aware validator catches it:
+    expect(
+      compilePredicateSchema(colorSchema)({ color: 'notacolor' }).valid
+    ).toBe(false)
+  })
+
+  it('the schema is plain serializable JSON — code travels as data', () => {
+    const roundTripped: PredicateSchema = JSON.parse(
+      JSON.stringify(colorSchema)
+    )
+    expect(roundTripped).toEqual(colorSchema)
+    // and it still validates after a serialize/deserialize round-trip
+    const validate = compilePredicateSchema(roundTripped)
+    expect(validate({ color: '#abc' }).valid).toBe(true)
+    expect(validate({ color: 'nope' }).valid).toBe(false)
+  })
+
+  it('a `$predicate` can recurse into open nested structure', () => {
+    const schema: PredicateSchema = { type: 'object', $predicate: TREE }
+    const validate = compilePredicateSchema(schema)
+    expect(validate({ a: 1, b: { c: 'x', d: { e: 2 } } }).valid).toBe(true)
+    expect(validate({ a: 1, bad: { nope: [] } }).valid).toBe(false) // array leaf
+  })
+
+  it('rejects an unsafe predicate at compile time (IO never embeds)', () => {
+    const evil: PredicateSchema = {
+      type: 'string',
+      $predicate: `function check(v){ return fetch(v) }`,
+    }
+    expect(() => compilePredicateSchema(evil)).toThrow(/Not predicate-safe/)
+  })
+
+  it('one-shot helper works too', () => {
+    expect(validatePredicateSchema(colorSchema, { color: '#fff' }).valid).toBe(
+      true
+    )
+  })
+})