tjs-lang 0.8.2 → 0.8.3

package/src/lang/predicate-schema.ts

@@ -0,0 +1,168 @@
+/**
+ * Predicate-aware JSON-Schema — "the missing computational half."
+ *
+ * A normal JSON-Schema node may carry a `$predicate` keyword whose value is the
+ * *source* of a predicate cluster (a few pure functions; the last is the entry,
+ * takes the value being validated, returns boolean). The source is trivially
+ * serializable (it's a string), and the predicate verifier (`./predicate`) is
+ * what makes it *safe to embed and run*: no IO, no async, fuel-bounded.
+ *
+ * Progressive enhancement falls out for free:
+ *   - A *naive* JSON-Schema validator ignores the unknown `$predicate` keyword
+ *     and validates only the structural part (`type`, `properties`, …).
+ *   - A *predicate-aware* validator (this module — and, in production, an
+ *     incoming `tosijs-schema`) ALSO runs the `$predicate`, validating the value
+ *     grammar that JSON-Schema and TS can't express (var()/calc()/!important,
+ *     order-flexible shorthands, recursive structure).
+ *
+ * This is the reference evaluator that lives with the predicate engine; the
+ * structural subset is intentionally small (type/properties/required/items) —
+ * full JSON-Schema structural validation is `tosijs-schema`'s job. The novel
+ * part is `$predicate`.
+ */
+import { verifyPredicate, compilePredicate } from './predicate'
+import type { CompilePredicateOptions } from './predicate'
+
+/** A JSON-Schema node, optionally carrying a `$predicate` (predicate source). */
+export interface PredicateSchema {
+  type?:
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'boolean'
+    | 'object'
+    | 'array'
+    | 'null'
+  properties?: Record<string, PredicateSchema>
+  required?: string[]
+  items?: PredicateSchema
+  /**
+   * Predicate cluster source. The LAST top-level function is the entry; it
+   * receives the value at this node and returns a boolean. Ignored by naive
+   * validators (it's a custom keyword); run by predicate-aware ones.
+   */
+  $predicate?: string
+  // description, title, examples, etc. are allowed and ignored.
+  [k: string]: unknown
+}
+
+export interface SchemaError {
+  /** JSON-pointer-ish path to the offending value, e.g. `/style/color`. */
+  path: string
+  message: string
+}
+
+export interface SchemaValidationResult {
+  valid: boolean
+  errors: SchemaError[]
+}
+
+export interface PredicateSchemaOptions extends CompilePredicateOptions {
+  /**
+   * Validate structure only — skip every `$predicate` (i.e. behave like a naive
+   * JSON-Schema validator). Useful for demonstrating progressive enhancement.
+   */
+  ignorePredicates?: boolean
+}
+
+const typeOf = (v: unknown): string =>
+  v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v
+
+function typeMatches(value: unknown, type: string): boolean {
+  if (type === 'integer')
+    return typeof value === 'number' && Number.isInteger(value)
+  return typeOf(value) === type
+}
+
+/**
+ * Compile a predicate-aware JSON-Schema into a reusable validator. Every
+ * `$predicate` cluster is verified + compiled once (fuel-bounded, IO-rejected);
+ * an invalid/unsafe predicate throws here, at compile time.
+ */
+export function compilePredicateSchema(
+  schema: PredicateSchema,
+  opts: PredicateSchemaOptions = {}
+): (value: unknown) => SchemaValidationResult {
+  const { ignorePredicates, ...compileOpts } = opts
+  // Compile every distinct $predicate once.
+  const compiled = new Map<string, (value: unknown) => boolean>()
+  const prepare = (node: PredicateSchema) => {
+    if (
+      node.$predicate &&
+      !ignorePredicates &&
+      !compiled.has(node.$predicate)
+    ) {
+      const src = node.$predicate
+      const names = verifyPredicate(src, compileOpts).predicates
+      const entry = names[names.length - 1]
+      if (!entry)
+        throw new Error('$predicate must declare at least one function')
+      const mod = compilePredicate(src, [entry], compileOpts)
+      compiled.set(src, mod[entry] as (value: unknown) => boolean)
+    }
+    if (node.properties)
+      for (const child of Object.values(node.properties)) prepare(child)
+    if (node.items) prepare(node.items)
+  }
+  prepare(schema)
+
+  const check = (
+    node: PredicateSchema,
+    value: unknown,
+    path: string,
+    errors: SchemaError[]
+  ) => {
+    if (node.type && !typeMatches(value, node.type)) {
+      errors.push({
+        path: path || '/',
+        message: `expected ${node.type}, got ${typeOf(value)}`,
+      })
+      return // structural mismatch — don't run value-grammar checks on it
+    }
+    if (
+      node.type === 'object' &&
+      node.properties &&
+      value &&
+      typeof value === 'object'
+    ) {
+      const obj = value as Record<string, unknown>
+      for (const key of node.required ?? []) {
+        if (!(key in obj))
+          errors.push({
+            path: `${path}/${key}`,
+            message: `missing required '${key}'`,
+          })
+      }
+      for (const [key, child] of Object.entries(node.properties)) {
+        if (key in obj) check(child, obj[key], `${path}/${key}`, errors)
+      }
+    }
+    if (node.type === 'array' && node.items && Array.isArray(value)) {
+      value.forEach((el, i) => check(node.items!, el, `${path}/${i}`, errors))
+    }
+    // The computational half — only the aware validator runs it.
+    if (node.$predicate && !ignorePredicates) {
+      const fn = compiled.get(node.$predicate)!
+      if (!fn(value))
+        errors.push({
+          path: path || '/',
+          message: `failed predicate at ${path || '/'}`,
+        })
+    }
+  }
+
+  return (value: unknown) => {
+    const errors: SchemaError[] = []
+    check(schema, value, '', errors)
+    return { valid: errors.length === 0, errors }
+  }
+}
+
+/** One-shot convenience: compile + validate. */
+export function validatePredicateSchema(
+  schema: PredicateSchema,
+  value: unknown,
+  opts?: PredicateSchemaOptions
+): SchemaValidationResult {
+  return compilePredicateSchema(schema, opts)(value)
+}

package/src/lang/predicate.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect } from 'bun:test'
+import {
+  verifyPredicate,
+  compilePredicate,
+  effectfulFromAtoms,
+  PredicateFuelExhausted,
+} from './predicate'
+import { coreAtoms } from '../vm/runtime'
+
+const ok = (src: string, opts?: any) => verifyPredicate(src, opts).safe
+const why = (src: string, opts?: any) =>
+  verifyPredicate(src, opts).diagnostics.map((d) => d.message)
+
+describe('verifyPredicate — accepts the pure substrate', () => {
+  it('pure expression + composition + recursion', () => {
+    expect(
+      ok(`
+      function isShort(s) { return typeof s == 'string' && s.length < 10 }
+      function isTag(s) { return isShort(s) && s.startsWith('#') }
+      function depth(o) {
+        if (typeof o != 'object' || o == null) { return 0 }
+        return Object.keys(o).every(isTag) ? 1 : depth(o)  // self-ref ok
+      }
+    `)
+    ).toBe(true)
+  })
+
+  it('pure builtins: regex .test, string/array methods, pure namespaces', () => {
+    expect(ok(`function f(v){ return /^#[0-9a-f]{3}$/i.test(v) }`)).toBe(true)
+    expect(
+      ok(
+        `function f(xs){ return xs.every(isThing) } function isThing(x){ return x.length > 0 }`
+      )
+    ).toBe(true)
+    expect(ok(`function f(o){ return Object.entries(o).length > 0 }`)).toBe(
+      true
+    )
+    expect(ok(`function f(a,b){ return Math.max(a,b) }`)).toBe(true)
+    expect(ok(`function f(s){ return JSON.parse(s) }`)).toBe(true)
+  })
+})
+
+describe('verifyPredicate — rejects impurity (the tightened checks)', () => {
+  it('async / await', () => {
+    expect(ok(`async function f(v){ return await g(v) }`)).toBe(false)
+  })
+  it('new', () => {
+    expect(ok(`function f(v){ return new RegExp(v).test(v) }`)).toBe(false)
+  })
+  it('IO globals (fetch / console)', () => {
+    expect(why(`function f(v){ return fetch(v) }`)[0]).toMatch(
+      /fetch.*effectful/
+    )
+    expect(why(`function f(v){ console.log(v); return true }`)[0]).toMatch(
+      /console\.log.*effectful/
+    )
+  })
+  it('nondeterministic statics (Date.now / Math.random) — caught by the whitelist', () => {
+    expect(why(`function f(){ return Date.now() }`)[0]).toMatch(
+      /Date.*effectful|nondeterministic/
+    )
+    expect(why(`function f(){ return Math.random() }`)[0]).toMatch(
+      /Math\.random.*nondeterministic/
+    )
+  })
+  it('non-pure instance methods (.then / .push)', () => {
+    // .then would let a Promise in; .push mutates — neither is a known pure method
+    expect(why(`function f(p){ return p.then(g) }`)[0]).toMatch(
+      /\.then\(\).*not a known pure method/
+    )
+    expect(why(`function f(a){ a.push(1); return a }`)[0]).toMatch(
+      /\.push\(\).*not a known pure method/
+    )
+  })
+  it('unknown reference (typo / undeclared)', () => {
+    expect(why(`function f(v){ return notDefinedAnywhere(v) }`)[0]).toMatch(
+      /unknown reference/
+    )
+  })
+})
+
+describe('verifyPredicate — driven by the real atom `effects` tag', () => {
+  const effectful = effectfulFromAtoms(coreAtoms as any)
+
+  it('rejects a predicate calling a real io-tagged atom, with a clear message', () => {
+    const r = verifyPredicate(`function isUp(u){ return httpFetch(u) }`, {
+      effectful,
+    })
+    expect(r.safe).toBe(false)
+    expect(r.diagnostics[0].message).toMatch(/httpFetch.*effectful/)
+    expect(r.diagnostics[0].line).toBeGreaterThan(0)
+  })
+
+  it('still allows pure atoms / composition', () => {
+    expect(
+      verifyPredicate(`function f(s){ return s.length < 5 }`, { effectful })
+        .safe
+    ).toBe(true)
+  })
+})
+
+describe('verifyPredicate — cross-source composition (knownPredicates)', () => {
+  it('accepts a reference to an externally-verified predicate', () => {
+    expect(
+      ok(`function isUser(u){ return isEmail(u.email) }`, {
+        knownPredicates: new Set(['isEmail']),
+      })
+    ).toBe(true)
+    // …but not an unknown one
+    expect(ok(`function isUser(u){ return isEmail(u.email) }`)).toBe(false)
+  })
+})
+
+describe('verifyPredicate — rejects loops (#3: keeps work fuel-bounded)', () => {
+  it('while / for / for-of are rejected; recursion + array methods are not', () => {
+    expect(why(`function f(n){ while(n>0){ n=n-1 } return n }`)[0]).toMatch(
+      /loops are not allowed/
+    )
+    expect(ok(`function f(n){ for(let i=0;i<n;i++){} return n }`)).toBe(false)
+    expect(ok(`function f(a){ for(const x of a){} return a }`)).toBe(false)
+    // the sanctioned forms still pass:
+    expect(
+      ok(
+        `function f(a){ return a.every(isShort) } function isShort(s){ return s.length<5 }`
+      )
+    ).toBe(true)
+  })
+})
+
+describe('compilePredicate — fuel-bounded + global-shadowed (#3)', () => {
+  it('verified predicates compile and run; IO ones throw at definition time', () => {
+    const m = compilePredicate(
+      `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 isColor(v){ return isHex(v) || isVar(v) }`,
+      ['isColor']
+    )
+    expect(m.isColor('#3a3')).toBe(true)
+    expect(m.isColor('var(--brand)')).toBe(true)
+    expect(m.isColor('nope')).toBe(false)
+
+    expect(() =>
+      compilePredicate(`function f(v){ return fetch(v) }`, ['f'])
+    ).toThrow(/Not predicate-safe/)
+  })
+
+  it('runaway recursion exhausts fuel instead of hanging', () => {
+    // verifier allows recursion (call-bounded); the runtime fuel stops it.
+    const m = compilePredicate(`function loop(n){ return loop(n) }`, ['loop'], {
+      fuel: 5000,
+    })
+    expect(() => m.loop(1)).toThrow(PredicateFuelExhausted)
+  })
+
+  it('a huge array exhausts fuel via the per-element callback', () => {
+    const m = compilePredicate(
+      `function isPos(x){ return x > 0 }
+       function allPos(a){ return a.every(isPos) }`,
+      ['allPos'],
+      { fuel: 1000 }
+    )
+    expect(m.allPos([1, 2, 3])).toBe(true) // small input fine
+    const big = Array.from({ length: 100000 }, () => 1)
+    expect(() => m.allPos(big)).toThrow(PredicateFuelExhausted)
+  })
+
+  it('each top-level call gets a fresh budget (no cross-call starvation)', () => {
+    const m = compilePredicate(
+      `function rec(n){ if (n <= 0) { return true } return rec(n - 1) }`,
+      ['rec'],
+      { fuel: 10000 }
+    )
+    // 500 deep, well under budget — and repeatable because budget resets
+    for (let i = 0; i < 5; i++) expect(m.rec(500)).toBe(true)
+  })
+
+  it('shadows effectful globals to undefined (defense-in-depth)', () => {
+    // even if a global slipped past the verifier, it is undefined at runtime
+    const m = compilePredicate(`function usesGlobal(){ return typeof fetch }`, [
+      'usesGlobal',
+    ])
+    expect(m.usesGlobal()).toBe('undefined')
+  })
+})