tjs-lang 0.8.7 → 0.9.1

package/src/lang/index.ts

@@ -47,6 +47,8 @@ export {
 export {
   verifyPredicate,
   compilePredicate,
+  emitVerifiedPredicate,
+  createPredicateEvaluator,
   suggest,
   effectfulFromAtoms,
   formatPredicateDiagnostics,
@@ -55,6 +57,8 @@ export {
   type PredicateVerifyResult,
   type VerifyPredicateOptions,
   type CompilePredicateOptions,
+  type EmitPredicateResult,
+  type PredicateEvaluatorOptions,
   type Suggestion,
   type SuggestOptions,
 } from './predicate'
@@ -80,11 +84,16 @@ export {
   typeDescriptorToTS,
   type GenerateDTSOptions,
 } from './emitters/dts'
-export {
-  fromTS,
-  type FromTSOptions,
-  type FromTSResult,
-} from './emitters/from-ts'
+// `fromTS` is intentionally NOT re-exported here: it pulls the TypeScript
+// compiler (~4-10MB, only a devDependency) into the main `tjs-lang` entry, which
+// crashes Node consumers that don't have `typescript` installed with
+// `Cannot find package 'typescript'` (and pulls TS at import time, breaking
+// constrained runtimes like Cloud Run). Import the value from the dedicated,
+// documented subpath instead:
+//   import { fromTS } from 'tjs-lang/lang/from-ts'
+// The types are safe to re-export — `export type` is erased at build time, so it
+// adds no runtime dependency.
+export type { FromTSOptions, FromTSResult } from './emitters/from-ts'
 export * from './inference'
 export { Schema } from './schema'
 export {

package/src/lang/parser-transforms.ts

@@ -42,6 +42,57 @@ import type {
   TokenizerState,
 } from './parser-types'
 import { extractJSValue } from './parser-params'
+import { emitVerifiedPredicate, formatPredicateDiagnostics } from './predicate'
+import type { PredicateVerification } from './types'
+
+/**
+ * If a `Type`/`FunctionPredicate` predicate body verifies as predicate-safe
+ * (pure, synchronous, no loops/IO), return a self-contained fuel-bounded guard
+ * **expression** to inline in place of the raw arrow; otherwise return null so
+ * the caller falls back to the unverified body (never rejects — see
+ * PRINCIPLES.md, TJS ⊇ JS). This is the transpile-time consumer of the predicate
+ * engine: a safe predicate "earns" the native fast path and DoS-safe validation.
+ */
+function verifiedGuardExpr(
+  name: string,
+  kind: 'Type' | 'Generic',
+  params: string,
+  body: string,
+  knownPredicates?: string[],
+  report?: PredicateVerification[]
+): string | null {
+  // Synthesize a named declaration the verifier can analyze. The body has
+  // already been through the TJS equality/typeof rewrites (Eq/NotEq/Is/IsNot/
+  // TypeOf), all whitelisted as pure in the verifier. `knownPredicates` lets a
+  // Generic predicate compose with its type-param checks (`checkT(x[0])`) — the
+  // verifier treats those calls as composition with another safe predicate.
+  //
+  // The entry function is named per-declaration (`__pred_<Type>`), not a fixed
+  // `__pred`: the guard IIFEs are inlined into the module, and two identically-
+  // named nested `function __pred`s would be picked up by the polymorphic-merge
+  // transform (which runs after this one) as ambiguous overloads. Type/Generic
+  // names are unique within a module, so this is collision-free and deterministic.
+  const entry = `__pred_${name}`
+  const fnSource = `function ${entry}(${params}) { ${body} }`
+  const r = emitVerifiedPredicate(
+    fnSource,
+    entry,
+    knownPredicates ? { knownPredicates: new Set(knownPredicates) } : {}
+  )
+  if (r.safe) {
+    report?.push({ name, kind, verified: true })
+    return r.code!
+  }
+  report?.push({
+    name,
+    kind,
+    verified: false,
+    // The verifier names the synthesized entry `__pred_<Name>`; surface the
+    // declaration name in the user-facing reason instead.
+    reason: formatPredicateDiagnostics(r.diagnostics).replace(/__pred_/g, ''),
+  })
+  return null
+}
 
 export function transformTryWithoutCatch(source: string): string {
   let result = ''
@@ -209,7 +260,10 @@ export function extractWasmBlocks(source: string): {
           ? `globalThis.${block.id}(${captureArgs})`
           : `globalThis.${block.id}()`
 
-      const dispatch = `(globalThis.${block.id} ? ${wasmCall} : (() => {${fallbackCode}})())`
+      // `globalThis.__tjs_wasm_enabled === false` forces the fallback path even
+      // when the WASM is instantiated — a public toggle for A/B benchmarking
+      // (WASM vs JS) without poking the internal `__tjs_wasm_<id>` globals (UI-#3).
+      const dispatch = `((globalThis.__tjs_wasm_enabled !== false && globalThis.${block.id}) ? ${wasmCall} : (() => {${fallbackCode}})())`
 
       result += dispatch
       i = matchEnd
@@ -1127,12 +1181,15 @@ function transformTypeofKeyword(source: string): string {
 }
 
 /**
- * Transform == and != to Is() and IsNot() calls
+ * Transform == and != to Eq() and NotEq() calls
  *
  * In TJS normal mode:
- *   a == b   -> Is(a, b)     (structural equality)
- *   a != b   -> IsNot(a, b)  (structural inequality)
+ *   a == b   -> Eq(a, b)     (footgun-free ===: unwraps boxed primitives,
+ *                             null == undefined, but does NOT coerce types and
+ *                             is NOT structural — see PRINCIPLES/guides)
+ *   a != b   -> NotEq(a, b)
  *   a === b  -> a === b      (identity, unchanged)
+ * (For deep structural equality use the explicit `Is`/`IsNot` operators.)
  *
  * Uses a two-pass algorithm:
  * 1. Find all == and != positions (outside strings/comments/regex)
@@ -1620,7 +1677,10 @@ function findRightOperandBoundary(
  *
  * When predicate + example: auto-generate type guard from example
  */
-export function transformTypeDeclarations(source: string): string {
+export function transformTypeDeclarations(
+  source: string,
+  report?: PredicateVerification[]
+): string {
   let result = ''
   let i = 0
 
@@ -1737,17 +1797,41 @@ export function transformTypeDeclarations(source: string): string {
         // Build Type() call with appropriate arguments
         // Type(description, predicateOrExample, example?, default?)
         if (predicateMatch && example) {
-          // Predicate + example
+          // Predicate + example: the example is the base schema, the predicate
+          // refines it. Verify the predicate → fuel-bounded native guard; the
+          // example schema check stays as an outer gate (constructed once via an
+          // IIFE, not per call). Falls back to the raw arrow when unverifiable.
           const params = predicateMatch[1].trim()
           const body = predicateMatch[2].trim()
           const defaultArg = defaultValue ? `, ${defaultValue}` : ''
-          result += `const ${typeName} = Type('${description}', (${params}) => { if (!globalThis.__tjs?.validate(${params}, globalThis.__tjs?.infer(${example}))) return false; ${body} }, ${example}${defaultArg})`
+          const schemaGate = `globalThis.__tjs?.validate(${params}, globalThis.__tjs?.infer(${example}))`
+          const guard = verifiedGuardExpr(
+            typeName,
+            'Type',
+            params,
+            body,
+            undefined,
+            report
+          )
+          const fn = guard
+            ? `(__g => (${params}) => (${schemaGate} ? __g(${params}) : false))(${guard})`
+            : `(${params}) => { if (!${schemaGate}) return false; ${body} }`
+          result += `const ${typeName} = Type('${description}', ${fn}, ${example}${defaultArg})`
         } else if (predicateMatch) {
-          // Predicate only
+          // Predicate only: verify → fuel-bounded native guard, else raw arrow.
           const params = predicateMatch[1].trim()
           const body = predicateMatch[2].trim()
           const defaultArg = defaultValue ? `, undefined, ${defaultValue}` : ''
-          result += `const ${typeName} = Type('${description}', (${params}) => { ${body} }${defaultArg})`
+          const guard = verifiedGuardExpr(
+            typeName,
+            'Type',
+            params,
+            body,
+            undefined,
+            report
+          )
+          const fn = guard ?? `(${params}) => { ${body} }`
+          result += `const ${typeName} = Type('${description}', ${fn}${defaultArg})`
         } else if (example) {
           // Example only (becomes validation schema)
           const defaultArg = defaultValue ? `, ${defaultValue}` : ''
@@ -1938,7 +2022,10 @@ export function transformFunctionPredicateDeclarations(source: string): string {
  *   const Pair = Generic(['T', 'U'], (obj, checkT, checkU) => { ... }, '...')
  *   const Container = Generic(['T', ['U', '']], (obj, checkT, checkU) => { ... }, '...')
  */
-export function transformGenericDeclarations(source: string): string {
+export function transformGenericDeclarations(
+  source: string,
+  report?: PredicateVerification[]
+): string {
   let result = ''
   let i = 0
 
@@ -2034,11 +2121,21 @@ export function transformGenericDeclarations(source: string): string {
           )
         })
 
+        // Verify the (type-param-rewritten) body, composing with the type-param
+        // checks; safe → fuel-bounded native guard, else the raw arrow.
+        const paramList = [valueParam, ...typeCheckParams].join(', ')
+        const guard = verifiedGuardExpr(
+          genericName,
+          'Generic',
+          paramList,
+          body,
+          typeCheckParams,
+          report
+        )
+        const fn = guard ?? `(${paramList}) => { ${body} }`
         result += `const ${genericName} = Generic([${typeParams.join(
           ', '
-        )}], (${valueParam}, ${typeCheckParams.join(
-          ', '
-        )}) => { ${body} }, '${description}')`
+        )}], ${fn}, '${description}')`
       } else {
         // No predicate - create a generic that always passes
         result += `const ${genericName} = Generic([${typeParams.join(
@@ -3542,11 +3639,12 @@ export function validateNoDate(source: string): string {
     {
       pattern: /\bnew\s+Date\b/,
       message:
-        'new Date() is not allowed in TjsDate mode. Use Timestamp.now() or Timestamp.from()',
+        'new Date() is not allowed in TjsDate mode. Use Timestamp.now()/Timestamp.from() for wall-clock dates, or performance.now() for a monotonic counter (timing, id generation)',
     },
     {
       pattern: /\bDate\.now\b/,
-      message: 'Date.now() is not allowed in TjsDate mode. Use Timestamp.now()',
+      message:
+        'Date.now() is not allowed in TjsDate mode. Use Timestamp.now() for a wall-clock date, or performance.now() for a monotonic counter (timing, id generation)',
     },
     {
       pattern: /\bDate\.parse\b/,

package/src/lang/parser-types.ts

@@ -196,6 +196,13 @@ export interface TjsModes {
   tjsNoVar: boolean
   /** TjsSafeAssign: let declarations need an initializer or `: example` annotation; literal undefined/null/void 0 assigned to typed lets is flagged */
   tjsSafeAssign: boolean
+  /**
+   * TjsStrict: the author explicitly opted into strict semantics (via the
+   * `TjsStrict` directive). Distinct from "all modes on" (native TJS's default) —
+   * only `true` when the directive is present. Escalates soft diagnostics (e.g. an
+   * unverifiable `Type`/`Generic` predicate) from a warning to a transpile error.
+   */
+  tjsStrict: boolean
 }
 
 /**

package/src/lang/parser.ts

@@ -8,6 +8,7 @@
 import * as acorn from 'acorn'
 import type { Program, FunctionDeclaration } from 'acorn'
 import { SyntaxError } from './types'
+import type { PredicateVerification } from './types'
 
 // Re-export types so external callers don't need to change imports
 export type {
@@ -124,6 +125,7 @@ export function preprocess(
   polymorphicNames: Set<string>
   extensions: Map<string, Set<string>>
   letAnnotations: Map<string, string>
+  predicates: PredicateVerification[]
 } {
   const originalSource = source
   let moduleSafety: 'none' | 'inputs' | 'all' | undefined
@@ -156,6 +158,7 @@ export function preprocess(
         tjsSafeEval: false,
         tjsNoVar: false,
         tjsSafeAssign: false,
+        tjsStrict: false,
       }
     : {
         tjsEquals: true,
@@ -166,6 +169,10 @@ export function preprocess(
         tjsSafeEval: false, // opt-in only (adds import)
         tjsNoVar: true,
         tjsSafeAssign: true,
+        // Native TJS has all modes on by default, but is NOT "strict" unless the
+        // author writes the `TjsStrict` directive — that opt-in is what escalates
+        // e.g. unverifiable predicates from a warning to a hard error.
+        tjsStrict: false,
       }
 
   // Safety: native TJS defaults to 'inputs' (runtime default),
@@ -201,7 +208,8 @@ export function preprocess(
     const directive = match[2]
 
     if (directive === 'TjsStrict') {
-      // Enable all TJS modes
+      // Enable all TJS modes + mark strict (the author's explicit opt-in, which
+      // escalates soft diagnostics like unverifiable predicates to hard errors).
       tjsModes.tjsEquals = true
       tjsModes.tjsClass = true
       tjsModes.tjsDate = true
@@ -209,6 +217,7 @@ export function preprocess(
       tjsModes.tjsNoVar = true
       tjsModes.tjsStandard = true
       tjsModes.tjsSafeAssign = true
+      tjsModes.tjsStrict = true
     } else if (directive === 'TjsCompat') {
       // Disable all TJS modes (JS-compatible)
       tjsModes.tjsEquals = false
@@ -298,8 +307,12 @@ export function preprocess(
   // Generic Bar<T, U> { ... } -> const Bar = Generic(...)
   // Union Dir 'up' | 'down' -> const Dir = Union(...)
   // Enum Status { Pending, Active, Done } -> const Status = Enum(...)
-  source = transformTypeDeclarations(source)
-  source = transformGenericDeclarations(source)
+  // Collect per-predicate verification status (Type/Generic predicate bodies:
+  // verified → native guard, or fell back to a raw function). Surfaced on the
+  // transpile result so tools can flag unverifiable predicates.
+  const predicates: PredicateVerification[] = []
+  source = transformTypeDeclarations(source, predicates)
+  source = transformGenericDeclarations(source, predicates)
   source = transformFunctionPredicateDeclarations(source)
   source = transformUnionDeclarations(source)
   source = transformEnumDeclarations(source)
@@ -437,6 +450,7 @@ export function preprocess(
     polymorphicNames: polyResult.polymorphicNames,
     extensions: extResult.extensions,
     letAnnotations,
+    predicates,
   }
 }
 
@@ -512,6 +526,7 @@ export function parse(
           tjsSafeEval: false,
           tjsNoVar: false,
           tjsSafeAssign: false,
+          tjsStrict: false,
         } as TjsModes,
       }
 

package/src/lang/predicate-evaluator.test.ts

@@ -0,0 +1,49 @@
+/**
+ * `createPredicateEvaluator` — the pluggable `(source, value) => boolean` bridge
+ * a zero-dep, predicate-aware JSON-Schema validator (tosijs-schema) injects to
+ * run `$predicate` sources. Compiles+caches per source; fails closed on an
+ * unverifiable source (never a thrown error, never a silent pass).
+ */
+import { describe, it, expect } from 'bun:test'
+import { createPredicateEvaluator } from './predicate'
+
+const POS = 'function isPos(x) { return typeof x === "number" && x > 0 }'
+const LOOPY =
+  'function bad(xs) { for (const x of xs) { if (x < 0) return false } return true }'
+
+describe('createPredicateEvaluator', () => {
+  it('evaluates a safe source against values', () => {
+    const evaluate = createPredicateEvaluator()
+    expect(evaluate(POS, 5)).toBe(true)
+    expect(evaluate(POS, -1)).toBe(false)
+    expect(evaluate(POS, 'x')).toBe(false)
+  })
+
+  it('caches: compiles a source once, reuses across calls', () => {
+    let unsafeCalls = 0
+    const evaluate = createPredicateEvaluator({
+      onUnsafe: () => unsafeCalls++,
+    })
+    // many evaluations of the same source — still one compile, zero warnings
+    for (let i = 0; i < 100; i++) expect(evaluate(POS, i + 1)).toBe(true)
+    expect(unsafeCalls).toBe(0)
+  })
+
+  it('fails closed on an unverifiable source (returns false, warns once)', () => {
+    const unsafe: string[] = []
+    const evaluate = createPredicateEvaluator({
+      onUnsafe: (src) => unsafe.push(src),
+    })
+    // a loop can't be certified predicate-safe → every value is invalid
+    expect(evaluate(LOOPY, [1, 2, 3])).toBe(false)
+    expect(evaluate(LOOPY, [1, 2, 3])).toBe(false)
+    // ...and the failure is reported exactly once (cached)
+    expect(unsafe.length).toBe(1)
+  })
+
+  it('fails closed on a runaway (fuel) rather than throwing', () => {
+    const evaluate = createPredicateEvaluator({ fuel: 100 })
+    const recur = 'function deep(n) { return deep(n + 1) }'
+    expect(evaluate(recur, 0)).toBe(false)
+  })
+})

package/src/lang/predicate-report.test.ts

@@ -0,0 +1,78 @@
+/**
+ * The `tjs()` result surfaces per-`Type`/`Generic` predicate verification status
+ * (`result.predicates`) so tools can flag unverifiable predicates, and mirrors
+ * the unverified ones into `result.warnings`. (#9 / the #5 warn-on-fallback tail.)
+ */
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+
+describe('predicate verification is reported on the transpile result', () => {
+  it('a safe Type predicate → verified, no warning', () => {
+    const r = tjs("Type Pos 'positive' { predicate(x) { return x > 0 } }")
+    expect(r.predicates).toEqual([
+      { name: 'Pos', kind: 'Type', verified: true },
+    ])
+    expect(r.warnings).toBeUndefined()
+  })
+
+  it('an unverifiable Type predicate → not verified + reason + warning', () => {
+    const r = tjs(
+      "Type Bad 'bad' { predicate(xs) { for (const x of xs) { if (x<0) return false } return true } }"
+    )
+    const p = r.predicates?.[0]
+    expect(p).toMatchObject({ name: 'Bad', kind: 'Type', verified: false })
+    expect(p?.reason).toMatch(/loop/i)
+    expect(p?.reason).not.toContain('__pred_') // internal name not leaked
+    expect(r.warnings?.some((w) => /Bad.*not verifiable/.test(w))).toBe(true)
+  })
+
+  it('reports Generic predicates too', () => {
+    const r = tjs(
+      "Generic Box<T> { description: 'b', predicate(x, T) { return T(x.value) } }"
+    )
+    expect(r.predicates?.[0]).toMatchObject({
+      name: 'Box',
+      kind: 'Generic',
+      verified: true,
+    })
+  })
+
+  it('reports each predicate in a multi-predicate module', () => {
+    const r = tjs(
+      "Type A 'a' { predicate(x) { return x > 0 } }\n" +
+        "Type B 'b' { predicate(xs) { for (const x of xs) {} return true } }"
+    )
+    const byName = Object.fromEntries(
+      (r.predicates ?? []).map((p) => [p.name, p.verified])
+    )
+    expect(byName).toEqual({ A: true, B: false })
+  })
+
+  it('omits `predicates` when there are none', () => {
+    expect(tjs('function f() { return 1 }').predicates).toBeUndefined()
+  })
+})
+
+describe('TjsStrict escalates an unverifiable predicate to a transpile error', () => {
+  const bad =
+    "Type Bad 'bad' { predicate(xs) { for (const x of xs) {} return true } }"
+
+  it('warns (does not throw) without the directive', () => {
+    const r = tjs(bad)
+    expect(r.predicates?.[0]?.verified).toBe(false)
+    expect(r.warnings?.length).toBeGreaterThan(0)
+  })
+
+  it('throws under TjsStrict, naming the predicate + reason', () => {
+    expect(() => tjs('TjsStrict\n' + bad)).toThrow(
+      /TjsStrict.*could not be verified/s
+    )
+    expect(() => tjs('TjsStrict\n' + bad)).toThrow(/Bad/)
+  })
+
+  it('does NOT throw under TjsStrict when the predicate verifies', () => {
+    const r = tjs("TjsStrict\nType Pos 'p' { predicate(x) { return x > 0 } }")
+    expect(r.predicates?.[0]?.verified).toBe(true)
+    expect(r.warnings).toBeUndefined()
+  })
+})