tjs-lang 0.8.6 → 0.9.0

package/src/lang/from-ts.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'bun:test'
-import { fromTS } from './index'
+import { fromTS } from './emitters/from-ts'
 
 describe('TypeScript to TJS Transpiler', () => {
   describe('fromTS with emitTJS', () => {

package/src/lang/generic-verified-predicate.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Generic-Type predicates verify too — they compose with their type-param checks
+ * (`T(x)` → `checkT(x)`), which the verifier accepts as composition with another
+ * safe predicate (via `knownPredicates`). Safe → fuel-bounded native guard;
+ * unverifiable → raw fallback (TJS ⊇ JS).
+ */
+import { describe, it, expect } from 'bun:test'
+import { preprocess } from './parser'
+
+const src = (s: string) => preprocess(s).source
+
+describe('Generic predicate → verified fuel-bounded guard', () => {
+  it('verifies a generic predicate that composes a type-param check', () => {
+    const out = src(
+      `Generic Box<T> {\n  description: 'a boxed value'\n  predicate(x, T) { return typeof x === 'object' && x !== null && T(x.value) }\n}`
+    )
+    expect(out).toContain('const Box = Generic(')
+    expect(out).toContain('__fuel') // verified as safe
+    expect(out).toContain('checkT(') // type-param composition preserved
+  })
+
+  it('verifies a two-type-param generic predicate', () => {
+    const out = src(
+      `Generic Pair<T, U> {\n  description: 'a pair'\n  predicate(x, T, U) { return T(x[0]) && U(x[1]) }\n}`
+    )
+    expect(out).toContain('__fuel')
+    expect(out).toContain('checkT(')
+    expect(out).toContain('checkU(')
+  })
+
+  it('falls back for an unverifiable generic predicate (loop)', () => {
+    const out = src(
+      `Generic AllOf<T> {\n  description: 'all match'\n  predicate(xs, T) { for (const x of xs) { if (!T(x)) return false } return true }\n}`
+    )
+    expect(out).not.toContain('__fuel') // not certified
+    expect(out).toContain('for (const x of xs)') // raw body preserved
+    expect(out).toContain('checkT') // type-param rewrite still applied
+  })
+})

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 = ''
@@ -1127,12 +1178,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 +1674,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 +1794,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 +2019,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 +2118,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(
@@ -3126,12 +3220,19 @@ ${branches.join('\n')}
  * where the identifier starts with uppercase (to avoid breaking normal assignments)
  */
 export function transformBareAssignments(source: string): string {
+  // A bare `Foo = …` is auto-const'd only on FIRST assignment. If the name is
+  // already declared (let/const/var/function/class) anywhere in the source, the
+  // statement is a REASSIGNMENT — leave it alone, or we'd emit a duplicate/
+  // shadowing `const` (e.g. `let B = null; … B = x` → wrongly `const B = x`).
+  const declared = new Set<string>()
+  const declRe = /\b(?:let|const|var|function|class)\s+([A-Z][a-zA-Z0-9_]*)/g
+  for (let m; (m = declRe.exec(source)); ) declared.add(m[1])
+
   // Match: start of line/statement, uppercase identifier, =, not ==
-  // Negative lookbehind for const/let/var to avoid double-declaring
   return source.replace(
-    /(?<=^|[;\n{])\s*([A-Z][a-zA-Z0-9_]*)\s*=(?!=)/gm,
-    (match, name) => {
-      // Check if already has const/let/var before it
+    /(?<=^|[;\n{])(\s*)([A-Z][a-zA-Z0-9_]*)\s*=(?!=)/gm,
+    (match, _ws, name) => {
+      if (declared.has(name)) return match // reassignment of a declared binding
       return match.replace(name, `const ${name}`)
     }
   )
@@ -3535,11 +3636,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.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
@@ -298,15 +300,24 @@ 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)
 
-  // Transform bare assignments to const declarations
-  // Foo = ... -> const Foo = ...
-  source = transformBareAssignments(source)
+  // Transform bare assignments to const declarations (native-TJS convenience):
+  // Foo = ... -> const Foo = ...  Gated by TjsSafeAssign — OFF for plain JS
+  // (dialect: 'js'), TS-originated, and VM targets, so a JS reassignment like
+  // `B = value` (of an already-declared `let B`) is never rewritten. See
+  // PRINCIPLES.md (TJS ⊇ JS): plain JS must pass through unchanged.
+  if (tjsModes.tjsSafeAssign) {
+    source = transformBareAssignments(source)
+  }
 
   // Phase 3: cross-file wasm-function composition. When a ModuleLoader is
   // supplied, resolve `import { ... } from '<spec>'` statements at transpile
@@ -432,6 +443,7 @@ export function preprocess(
     polymorphicNames: polyResult.polymorphicNames,
     extensions: extResult.extensions,
     letAnnotations,
+    predicates,
   }
 }
 
@@ -737,7 +749,11 @@ export function extractTDoc(
   // This preserves full markdown content
   // Find the LAST /*# ... */ block and verify it immediately precedes the function
   // (only whitespace and line comments allowed between)
-  const allDocBlocks = [...beforeFunc.matchAll(/\/\*#([\s\S]*?)\*\//g)]
+  // Line-start `/*#` only — a `/*#` after code (or in a string) isn't a doc
+  // comment. Lookbehind keeps match.index/length on the `/*#…*/` span.
+  const allDocBlocks = [
+    ...beforeFunc.matchAll(/(?<=^[ \t]*)\/\*#([\s\S]*?)\*\//gm),
+  ]
   if (allDocBlocks.length > 0) {
     const lastBlock = allDocBlocks[allDocBlocks.length - 1]
     const afterBlock = beforeFunc.substring(

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,54 @@
+/**
+ * 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()
+  })
+})