tjs-lang 0.8.1 → 0.8.3

package/src/lang/predicate.ts

@@ -0,0 +1,550 @@
+/**
+ * Predicate-safety verifier.
+ *
+ * A *predicate* is a pure, synchronous function of its inputs. A cluster of
+ * predicates is **predicate-safe** iff every function in it uses only pure
+ * constructs and calls only pure builtins, pure globals, or other
+ * predicate-safe predicates — a closure property, so the cluster is safe iff
+ * each function is. Verified predicates have "earned" the native fast path:
+ * they compile to plain synchronous JS where ergonomic composition
+ * (`isHex(v) || isVar(v)`, `tokens.every(isToken)`, recursion) just works.
+ *
+ * This is pure static analysis over the parsed source, so it has none of the VM
+ * interpreter's restrictions (calls-in-expressions, named callbacks) — it
+ * accepts the ergonomic source and certifies it. The serializable AJS AST stays
+ * the portable form (the "missing computational half" of JSON Schema); native
+ * JS is the execution form.
+ *
+ * Effect classification of atoms comes from the VM's `effects` tag — pass
+ * `effectfulFromAtoms(registry)` for atom-aware checking; without it, atom calls
+ * still fail closed as "unknown reference". See `experiments/predicates/` for
+ * the CSS torture set and `src/vm/atom-effects.test.ts` for the drift guard.
+ */
+import * as acorn from 'acorn'
+import * as walk from 'acorn-walk'
+
+export interface PredicateDiagnostic {
+  /** Name of the predicate the problem is in. */
+  predicate: string
+  message: string
+  line: number
+  column: number
+}
+
+export interface PredicateVerifyResult {
+  safe: boolean
+  /** Names of the top-level functions found (the predicate cluster). */
+  predicates: string[]
+  diagnostics: PredicateDiagnostic[]
+}
+
+export interface VerifyPredicateOptions {
+  /**
+   * Names that are effectful and must not be called — IO atoms + JS IO globals.
+   * Compose from the atom registry with `effectfulFromAtoms`. The built-in JS IO
+   * globals are always included.
+   */
+  effectful?: Set<string>
+  /**
+   * Externally-verified predicate names this source may compose with (a shared
+   * registry), in addition to the functions declared in `source`.
+   */
+  knownPredicates?: Set<string>
+}
+
+// --- the safe substrate -----------------------------------------------------
+
+/** Pure deterministic globals callable by bare name. */
+const PURE_GLOBALS = new Set([
+  'parseInt',
+  'parseFloat',
+  'isNaN',
+  'isFinite',
+  'encodeURIComponent',
+  'decodeURIComponent',
+  'String',
+  'Number',
+  'Boolean',
+  'Array',
+  'Object',
+])
+
+/** Namespaces whose static methods are pure (with effectful exceptions below). */
+const PURE_NAMESPACES = new Set([
+  'Math',
+  'JSON',
+  'Object',
+  'Array',
+  'String',
+  'Number',
+])
+
+/** Static members that are NOT pure even on a pure namespace. */
+const EFFECTFUL_STATICS = new Set(['Math.random', 'Date.now'])
+
+/**
+ * Instance methods known to be pure regardless of receiver type. A method call
+ * whose method name isn't here (and whose receiver isn't a pure namespace) is
+ * flagged — so `x.then()`, `obj.fetch()`, `arr.push()` (mutates) don't pass.
+ */
+const PURE_INSTANCE_METHODS = new Set([
+  // string
+  'startsWith',
+  'endsWith',
+  'includes',
+  'indexOf',
+  'lastIndexOf',
+  'slice',
+  'substring',
+  'substr',
+  'toLowerCase',
+  'toUpperCase',
+  'trim',
+  'trimStart',
+  'trimEnd',
+  'split',
+  'replace',
+  'replaceAll',
+  'match',
+  'matchAll',
+  'charAt',
+  'charCodeAt',
+  'codePointAt',
+  'padStart',
+  'padEnd',
+  'repeat',
+  'concat',
+  'at',
+  'normalize',
+  'search',
+  'localeCompare',
+  // array (non-mutating)
+  'every',
+  'some',
+  'map',
+  'filter',
+  'reduce',
+  'reduceRight',
+  'find',
+  'findIndex',
+  'findLast',
+  'findLastIndex',
+  'flat',
+  'flatMap',
+  'join',
+  'keys',
+  'entries',
+  'values',
+  'forEach',
+  // regexp
+  'test',
+  'exec',
+  // number / shared
+  'toFixed',
+  'toPrecision',
+  'toString',
+  'valueOf',
+  'hasOwnProperty',
+])
+
+/** JS globals that perform IO / are nondeterministic / have side effects. */
+const EFFECTFUL_GLOBALS = [
+  'fetch',
+  'XMLHttpRequest',
+  'WebSocket',
+  'Date',
+  'console',
+  'setTimeout',
+  'setInterval',
+  'requestAnimationFrame',
+  'queueMicrotask',
+  'localStorage',
+  'sessionStorage',
+  'indexedDB',
+  'document',
+  'window',
+  'globalThis',
+  'self',
+  'process',
+  'require',
+  'eval',
+  'Function',
+  'import',
+  'crypto',
+  'performance',
+  'navigator',
+]
+
+/**
+ * Build the effectful-name set from a VM atom registry: every atom tagged
+ * `effects: 'io'`, plus the built-in JS IO globals. This is how the verifier
+ * consumes the atom-effects classification (the keystone).
+ */
+export function effectfulFromAtoms(
+  atoms: Record<string, { op?: string; effects?: 'pure' | 'io' }>
+): Set<string> {
+  const set = new Set(EFFECTFUL_GLOBALS)
+  for (const [name, atom] of Object.entries(atoms)) {
+    if (atom?.effects === 'io') set.add(atom.op ?? name)
+  }
+  return set
+}
+
+// --- the verifier -----------------------------------------------------------
+
+/**
+ * Verify every top-level function declaration in `source` is predicate-safe.
+ * Returns all diagnostics; `safe` is true iff there are none (closure property).
+ */
+export function verifyPredicate(
+  source: string,
+  opts: VerifyPredicateOptions = {}
+): PredicateVerifyResult {
+  const effectful = opts.effectful ?? new Set(EFFECTFUL_GLOBALS)
+  let ast: any
+  try {
+    ast = acorn.parse(source, { ecmaVersion: 'latest', locations: true })
+  } catch (e: any) {
+    return {
+      safe: false,
+      predicates: [],
+      diagnostics: [
+        {
+          predicate: '<source>',
+          message: `parse error: ${e.message}`,
+          line: e.loc?.line ?? 0,
+          column: e.loc?.column ?? 0,
+        },
+      ],
+    }
+  }
+
+  const predicateNames = new Set<string>(opts.knownPredicates ?? [])
+  for (const node of ast.body) {
+    if (node.type === 'FunctionDeclaration' && node.id)
+      predicateNames.add(node.id.name)
+  }
+
+  const diagnostics: PredicateDiagnostic[] = []
+
+  for (const fn of ast.body) {
+    if (fn.type !== 'FunctionDeclaration' || !fn.id) continue
+    const pname = fn.id.name
+    const flag = (message: string, n: any) =>
+      diagnostics.push({
+        predicate: pname,
+        message,
+        line: n?.loc?.start?.line ?? 0,
+        column: n?.loc?.start?.column ?? 0,
+      })
+
+    const loop = (n: any) =>
+      flag(
+        'loops are not allowed — iterate with recursion or array methods (every/some/map/filter/reduce) so work stays fuel-bounded',
+        n
+      )
+    walk.simple(fn, {
+      AwaitExpression(n: any) {
+        flag('`await` not allowed — predicates must be synchronous', n)
+      },
+      NewExpression(n: any) {
+        flag('`new` not allowed in a predicate (non-pure construction)', n)
+      },
+      WhileStatement: loop,
+      DoWhileStatement: loop,
+      ForStatement: loop,
+      ForInStatement: loop,
+      ForOfStatement: loop,
+      CallExpression(n: any) {
+        const callee = n.callee
+        // Bare call: f(...)
+        if (callee.type === 'Identifier') {
+          const name = callee.name
+          if (effectful.has(name))
+            flag(`'${name}' is effectful — not allowed in a predicate`, callee)
+          else if (predicateNames.has(name)) {
+            /* composition with another predicate — OK */
+          } else if (PURE_GLOBALS.has(name)) {
+            /* pure global — OK */
+          } else {
+            flag(
+              `unknown reference '${name}' — not a predicate or pure builtin`,
+              callee
+            )
+          }
+          return
+        }
+        // Method call: recv.method(...)
+        if (callee.type === 'MemberExpression' && !callee.computed) {
+          const method = callee.property.name
+          const recv = callee.object
+          if (recv.type === 'Identifier' && effectful.has(recv.name)) {
+            flag(`'${recv.name}.${method}' is effectful`, callee)
+          } else if (
+            recv.type === 'Identifier' &&
+            PURE_NAMESPACES.has(recv.name)
+          ) {
+            if (EFFECTFUL_STATICS.has(`${recv.name}.${method}`))
+              flag(`'${recv.name}.${method}' is nondeterministic`, callee)
+            // else pure namespace method — OK
+          } else if (!PURE_INSTANCE_METHODS.has(method)) {
+            flag(
+              `method '.${method}()' is not a known pure method`,
+              callee.property
+            )
+          }
+          return
+        }
+        // Anything else (computed member, call-of-call, etc.) — be conservative.
+        flag('unsupported call form in a predicate', callee)
+      },
+    })
+  }
+
+  return {
+    safe: diagnostics.length === 0,
+    predicates: [...predicateNames],
+    diagnostics,
+  }
+}
+
+/** Format diagnostics for a thrown error / log. */
+export function formatPredicateDiagnostics(d: PredicateDiagnostic[]): string {
+  return d
+    .map((x) => `  ${x.predicate} (${x.line}:${x.column}): ${x.message}`)
+    .join('\n')
+}
+
+// --- suggestion mining (#4: autocomplete companion) -------------------------
+
+export interface Suggestion {
+  value: string
+  /**
+   * `'value'` — a concrete candidate (a keyword/literal the predicate accepts);
+   * `'stub'`  — a partial completion to keep typing (e.g. `var(--`, `calc(`),
+   *             mined from a `startsWith(...)` guard. TS's `string` fallback
+   *             offers neither; a finite TS union offers only `'value'`.
+   */
+  kind: 'value' | 'stub'
+}
+
+export interface SuggestOptions extends CompilePredicateOptions {
+  /** Only return candidates relevant to the text typed so far. */
+  prefix?: string
+  /** Cap the number of suggestions (default 50). */
+  limit?: number
+  /**
+   * Run each mined *value* through the compiled entry predicate and keep only
+   * those that actually pass — so completions are guaranteed valid, not merely
+   * enumerated. Default true when the cluster is predicate-safe; stubs are never
+   * validated (they're partial by construction).
+   */
+  validate?: boolean
+  /** Entry predicate to validate against (default: last top-level function). */
+  entry?: string
+}
+
+const isStringLiteral = (n: any): n is { value: string } =>
+  n && n.type === 'Literal' && typeof n.value === 'string'
+
+/**
+ * Mine a predicate cluster's source for autocomplete candidates. Two sources:
+ *   - **values** — string literals compared with `==`/`===` and members of
+ *     array literals (the keyword sets a predicate checks membership against).
+ *   - **stubs** — the argument of a `.startsWith(...)` guard, surfaced as a
+ *     partial completion (`var(--`, `calc(`) the user keeps typing.
+ *
+ * Pure syntactic mining over the parsed source — no execution. By default the
+ * mined *values* are then run through the compiled entry predicate, so the
+ * returned set is exactly what the predicate accepts (a literal that only ever
+ * appears in a `!=` / negative context is dropped). This is the autocomplete
+ * win over a TS `string` fallback (which suggests nothing) and over a finite TS
+ * union (which can't offer the open-ended `var(--`/`calc(` stubs).
+ */
+export function suggest(
+  source: string,
+  opts: SuggestOptions = {}
+): Suggestion[] {
+  let ast: any
+  try {
+    ast = acorn.parse(source, { ecmaVersion: 'latest' })
+  } catch {
+    return []
+  }
+
+  const values = new Set<string>()
+  const stubs = new Set<string>()
+  walk.simple(ast, {
+    BinaryExpression(n: any) {
+      if (n.operator === '==' || n.operator === '===') {
+        if (isStringLiteral(n.left)) values.add(n.left.value)
+        if (isStringLiteral(n.right)) values.add(n.right.value)
+      }
+    },
+    ArrayExpression(n: any) {
+      for (const el of n.elements) if (isStringLiteral(el)) values.add(el.value)
+    },
+    CallExpression(n: any) {
+      const callee = n.callee
+      if (callee.type !== 'MemberExpression' || callee.computed) return
+      const method = callee.property.name
+      const arg = n.arguments[0]
+      if (!isStringLiteral(arg)) return
+      if (method === 'startsWith') stubs.add(arg.value)
+      // `.includes('x')` / `.endsWith('x')` aren't standalone completions:
+      // includes-arg is a substring, endsWith-arg is a tail — skip both.
+    },
+  })
+
+  // Validate mined values against the predicate unless told not to / unsafe.
+  let accept: ((v: string) => boolean) | null = null
+  if (opts.validate !== false) {
+    const verified = verifyPredicate(source, opts)
+    if (verified.safe && verified.predicates.length) {
+      const entry =
+        opts.entry ?? verified.predicates[verified.predicates.length - 1]
+      try {
+        const mod = compilePredicate(source, [entry], opts)
+        const fn = mod[entry]
+        accept = (v) => {
+          try {
+            return fn(v) === true
+          } catch {
+            return false // fuel exhaustion / runtime miss → not a suggestion
+          }
+        }
+      } catch {
+        accept = null // not compilable → fall back to raw mining
+      }
+    }
+  }
+
+  const out: Suggestion[] = []
+  for (const v of values)
+    if (!accept || accept(v)) out.push({ value: v, kind: 'value' })
+  for (const s of stubs) out.push({ value: s, kind: 'stub' })
+
+  let filtered = out
+  if (opts.prefix) {
+    const p = opts.prefix
+    filtered = out.filter(
+      (s) =>
+        s.value.startsWith(p) || (s.kind === 'stub' && p.startsWith(s.value))
+    )
+  }
+  filtered.sort(
+    (a, b) =>
+      (a.kind === b.kind ? 0 : a.kind === 'value' ? -1 : 1) ||
+      a.value.localeCompare(b.value)
+  )
+  return opts.limit ? filtered.slice(0, opts.limit) : filtered
+}
+
+/** Thrown when a predicate exceeds its fuel budget (likely a pathological input). */
+export class PredicateFuelExhausted extends Error {
+  constructor(budget: number) {
+    super(`predicate exceeded its fuel budget (${budget})`)
+    this.name = 'PredicateFuelExhausted'
+  }
+}
+
+export interface CompilePredicateOptions extends VerifyPredicateOptions {
+  /** Max fuel per top-level predicate call (default 1,000,000). */
+  fuel?: number
+}
+
+/**
+ * Inject `__fuel()` at every function-body entry and comma-wrap expression-body
+ * arrows, by splicing at source offsets (no codegen needed). Because loops are
+ * rejected, function-entry fuel bounds all iteration: recursion costs fuel per
+ * call, and array-method callbacks (`xs.every(p)`) cost fuel per element via the
+ * callback's own entry.
+ */
+function injectFuel(source: string): string {
+  const ast = acorn.parse(source, { ecmaVersion: 'latest' }) as any
+  // Each edit: [offset, text]. Applied descending so offsets stay valid.
+  const edits: Array<[number, string]> = []
+  const enterBlockBody = (n: any) => edits.push([n.body.start + 1, '__fuel();'])
+  walk.simple(ast, {
+    FunctionDeclaration: enterBlockBody,
+    FunctionExpression: enterBlockBody,
+    ArrowFunctionExpression(n: any) {
+      if (n.body.type === 'BlockStatement') {
+        edits.push([n.body.start + 1, '__fuel();'])
+      } else {
+        // expression-body arrow: `x => EXPR`  →  `x => (__fuel(), EXPR)`
+        edits.push([n.body.start, '(__fuel(), '])
+        edits.push([n.body.end, ')'])
+      }
+    },
+  })
+  edits.sort((a, b) => b[0] - a[0])
+  let out = source
+  for (const [off, text] of edits)
+    out = out.slice(0, off) + text + out.slice(off)
+  return out
+}
+
+/**
+ * Verify, then compile the cluster to native synchronous JS functions —
+ * **fuel-bounded and global-shadowed**. Throws (with located diagnostics) at
+ * definition time if not predicate-safe.
+ *
+ * Each compiled predicate runs with a fresh fuel budget; a runaway input throws
+ * `PredicateFuelExhausted` rather than hanging. The effectful globals are
+ * shadowed to `undefined` as defense-in-depth beneath the static verifier.
+ *
+ * NOTE: preserves JS semantics (no structural-`==` rewrite yet — a future
+ * opt-in). Emission is offset-spliced source, not a full AJS-AST→JS codegen.
+ */
+export function compilePredicate(
+  source: string,
+  exportNames: string[],
+  opts: CompilePredicateOptions = {}
+): Record<string, (...args: any[]) => any> {
+  const result = verifyPredicate(source, opts)
+  if (!result.safe)
+    throw new Error(
+      `Not predicate-safe:\n${formatPredicateDiagnostics(result.diagnostics)}`
+    )
+
+  const budget = opts.fuel ?? 1_000_000
+  const instrumented = injectFuel(source)
+
+  // Shadow the effectful globals to undefined (defense-in-depth under the
+  // verifier), and inject the fuel hook. `new Function` params shadow globals.
+  // Exclude reserved words that can't be parameter names (still verifier-rejected).
+  const shadowed = EFFECTFUL_GLOBALS.filter(
+    (g) => g !== 'import' && g !== 'eval' && g !== 'arguments'
+  )
+  const factory = new Function(
+    '__fuel',
+    ...shadowed,
+    `"use strict";\n${instrumented}\n;return { ${exportNames.join(', ')} };`
+  )
+
+  let fuel = 0
+  const fuelHook = () => {
+    if (--fuel < 0) throw new PredicateFuelExhausted(budget)
+  }
+  const raw = factory(fuelHook, ...shadowed.map(() => undefined))
+
+  // Each top-level call gets a fresh budget; inner composed calls share it.
+  // A stack overflow (deep recursion past the JS frame limit before fuel runs
+  // out) is the same "runaway" signal, so normalize it to PredicateFuelExhausted.
+  const wrapped: Record<string, (...args: any[]) => any> = {}
+  for (const name of exportNames) {
+    const fn = raw[name]
+    wrapped[name] = (...args: any[]) => {
+      fuel = budget
+      try {
+        return fn(...args)
+      } catch (e) {
+        if (e instanceof RangeError && /stack/i.test(e.message))
+          throw new PredicateFuelExhausted(budget)
+        throw e
+      }
+    }
+  }
+  return wrapped
+}

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()
+      })
+    }
+  })
+})