tjs-lang 0.8.6 → 0.9.0

package/src/css/style.test.ts

@@ -0,0 +1,125 @@
+/**
+ * `tjs-lang/css` phase 4 — recursive style-object structure + the `$predicate`
+ * JSON-Schema. The thesis end-to-end: one serializable schema, validated two
+ * ways — naive (structure only) vs predicate-aware (the full recursive grammar).
+ */
+import { describe, it, expect } from 'bun:test'
+import {
+  compilePredicateSchema,
+  validatePredicateSchema,
+} from '../lang/predicate-schema'
+import {
+  isStyleObject,
+  isStyleValue,
+  isCssProperty,
+  isSelectorOrAtRule,
+  cssStyleSchema,
+  cssColorSchema,
+  verifyCss,
+} from './index'
+
+describe('the combined style source verifies safe', () => {
+  it('color + dimension + recursive structure all predicate-safe', () => {
+    const r = verifyCss()
+    if (!r.safe) console.error(r.diagnostics)
+    expect(r.safe).toBe(true)
+  })
+})
+
+describe('key classification', () => {
+  it('isCssProperty', () => {
+    expect(isCssProperty('color')).toBe(true)
+    expect(isCssProperty('-webkit-box-shadow')).toBe(true)
+    expect(isCssProperty('--brand')).toBe(true)
+    expect(isCssProperty('&:hover')).toBe(false)
+    expect(isCssProperty('.card')).toBe(false)
+  })
+  it('isSelectorOrAtRule', () => {
+    expect(isSelectorOrAtRule('&:hover')).toBe(true)
+    expect(isSelectorOrAtRule('.card')).toBe(true)
+    expect(isSelectorOrAtRule('> a')).toBe(true)
+    expect(isSelectorOrAtRule('@media (min-width: 600px)')).toBe(true)
+    expect(isSelectorOrAtRule('[data-x]')).toBe(true)
+    expect(isSelectorOrAtRule('color')).toBe(false)
+  })
+})
+
+describe('isStyleObject validates the recursive structure', () => {
+  it('accepts a nested style object', () => {
+    const spec = {
+      color: 'red',
+      padding: '10px',
+      '--gap': '4px',
+      '&:hover': { color: '#00f', background: 'var(--surface)' },
+      '@media (min-width: 600px)': {
+        display: 'grid',
+        '.card': { boxShadow: '0 1px 2px rgba(0,0,0,0.2)' },
+      },
+    }
+    expect(isStyleObject(spec)).toBe(true)
+  })
+  it('rejects a non-object', () => {
+    expect(isStyleObject('red')).toBe(false)
+    expect(isStyleObject(null)).toBe(false)
+    expect(isStyleObject(42)).toBe(false)
+  })
+  it('rejects a property whose value is the wrong type', () => {
+    expect(isStyleObject({ color: { nested: 'x' } })).toBe(false) // property → not an object
+    expect(isStyleObject({ color: '' })).toBe(false) // empty value
+  })
+  it('rejects a selector whose value is not a nested rule', () => {
+    expect(isStyleObject({ '&:hover': 'red' })).toBe(false)
+  })
+  it('rejects a key that is neither property nor selector', () => {
+    expect(isStyleObject({ '': 'red' })).toBe(false)
+  })
+})
+
+describe('isStyleValue (leaf)', () => {
+  it('accepts known + permissive values', () => {
+    expect(isStyleValue('red')).toBe(true) // color
+    expect(isStyleValue('10px')).toBe(true) // dimension
+    expect(isStyleValue('1px solid red')).toBe(true) // shorthand → permissive tail
+    expect(isStyleValue(0)).toBe(true) // finite number
+  })
+  it('rejects empty / non-primitive', () => {
+    expect(isStyleValue('')).toBe(false)
+    expect(isStyleValue({})).toBe(false)
+    expect(isStyleValue(Infinity)).toBe(false)
+  })
+})
+
+describe('$predicate schema — progressive enhancement', () => {
+  const schema = cssStyleSchema()
+  const good = { color: 'red', '&:hover': { color: 'blue' } }
+  const structurallyOkButBadGrammar = { '  not a prop  ': 'red' } // is an object, but a bad key
+
+  it('naive validator (structure only) checks just `type: object`', () => {
+    const naive = compilePredicateSchema(schema, { ignorePredicates: true })
+    expect(naive(good).valid).toBe(true)
+    // a plain object passes structure even with an invalid key...
+    expect(naive(structurallyOkButBadGrammar).valid).toBe(true)
+    // ...but a non-object still fails the structural `type`.
+    expect(naive('nope').valid).toBe(false)
+  })
+
+  it('predicate-aware validator runs the full recursive grammar', () => {
+    const aware = compilePredicateSchema(schema)
+    expect(aware(good).valid).toBe(true)
+    // now the bad key is caught by $predicate where the naive one passed it
+    expect(aware(structurallyOkButBadGrammar).valid).toBe(false)
+  })
+
+  it('validatePredicateSchema one-shot works for a color node', () => {
+    expect(validatePredicateSchema(cssColorSchema(), '#3a3').valid).toBe(true)
+    expect(validatePredicateSchema(cssColorSchema(), 'notacolor').valid).toBe(
+      false
+    )
+    // naive sees only `type: string`
+    expect(
+      validatePredicateSchema(cssColorSchema(), 'notacolor', {
+        ignorePredicates: true,
+      }).valid
+    ).toBe(true)
+  })
+})

package/src/css/style.ts

@@ -0,0 +1,134 @@
+/**
+ * CSS style-object structure (phase 4) — the recursive, open shape TS structural
+ * types and JSON Schema can't express, and the `$predicate` schemas that carry
+ * it. This is the thesis deliverable: a JSON-Schema node whose *structural* part
+ * (`type: 'object'`) a naive validator checks, and whose `$predicate` a
+ * predicate-aware validator runs to validate the whole recursive CSS structure —
+ * progressive enhancement, one serializable artifact.
+ *
+ * The combined source concatenates the color + dimension leaf clusters and adds
+ * the structure predicates, so `isStyleValue`/`isStyleObject` compose the leaves
+ * directly. `isStyleObject` is LAST — the entry the `$predicate` schema runs.
+ *
+ * Value precision is intentionally two-tier (as in the PoC): the *structure* is
+ * validated strictly (keys must be CSS properties or selectors/at-rules; a
+ * property maps to a value, a selector to a nested rule), while a generic leaf
+ * value falls back to "non-empty string or finite number" so a valid-but-
+ * unmodelled value (a shorthand, a not-yet-covered property) is never rejected.
+ * Per-property precision comes from the specific value schemas (`cssColorSchema`
+ * etc.) and, later, property-aware validation (phase 3 shorthands).
+ */
+import type { PredicateSchema } from '../lang/predicate-schema'
+import { CSS_COLOR_SOURCE } from './predicates'
+import { CSS_DIMENSION_SOURCE } from './dimensions'
+import { CSS_SHORTHAND_FRAGMENT } from './shorthands'
+
+/** The recursive structure predicates, layered on the leaf clusters. */
+const CSS_STRUCTURE_FRAGMENT = `
+// Properties whose value grammar is CLOSED — a value that fails the leaf
+// predicate is genuinely invalid, so it's safe to enforce (normalized:
+// lower-cased, dashes stripped, so 'background-color' === 'backgroundColor').
+var CSS_COLOR_PROPS = ['color','backgroundcolor','bordercolor','bordertopcolor','borderrightcolor','borderbottomcolor','borderleftcolor','outlinecolor','caretcolor','columnrulecolor','textdecorationcolor','accentcolor','fill','stroke','floodcolor','stopcolor','lightingcolor']
+
+function isCssProperty(k) {
+  // custom property (--foo) OR a standard/vendor-prefixed property (-webkit-…).
+  return typeof k === 'string' && /^(--[a-z0-9-]+|-?[a-z][a-z0-9-]*)$/i.test(k)
+}
+function isSelectorOrAtRule(k) {
+  if (typeof k !== 'string' || k.length === 0) { return false }
+  if (k.startsWith('@')) { return true }
+  return /[ :>~+.#&*\\[\\]]/.test(k)
+}
+function isStyleValue(val) {
+  if (typeof val === 'number') { return isFinite(val) }
+  if (typeof val !== 'string' || val.length === 0) { return false }
+  // Precise recognition for known leaves; permissive tail keeps the whole
+  // structure total (a shorthand / unmodelled value is a non-empty string).
+  return isColorValue(val) || isDimension(val) || isGlobalKeyword(val)
+      || isCssVar(val) || isCssCalc(val) || val.length > 0
+}
+function cssPropNorm(prop) {
+  return typeof prop === 'string' ? prop.toLowerCase().replace(/-/g, '') : ''
+}
+// Property-AWARE value check: tighten only the closed value grammars (color,
+// animation, transition) — a wrong value there is a real error; everything else
+// stays permissive (keyword-heavy props like width/display accept idents we don't
+// enumerate, so enforcing would false-reject valid CSS). Universal escapes
+// (global keyword / var() / calc()) are valid on any property.
+function isStyleValueFor(prop, val) {
+  if (isGlobalKeyword(val) || isCssVar(val) || isCssCalc(val)) { return true }
+  var p = cssPropNorm(prop)
+  if (CSS_COLOR_PROPS.includes(p)) { return isColorValue(val) }
+  if (p === 'animation') { return isAnimation(val) }
+  if (p === 'transition') { return isTransition(val) }
+  return isStyleValue(val)
+}
+function isStyleEntry(pair) {
+  var k = pair[0]
+  var val = pair[1]
+  if (isSelectorOrAtRule(k)) { return isStyleObject(val) }
+  if (isCssProperty(k)) { return isStyleValueFor(k, val) }
+  return false
+}
+function isStyleObject(o) {
+  if (typeof o !== 'object' || o === null) { return false }
+  return Object.entries(o).every(isStyleEntry)
+}
+`
+
+/**
+ * The full CSS style predicate cluster: color + dimension + shorthand leaves +
+ * recursive, property-aware structure. Entry = `isStyleObject` (last function).
+ * Serializable — this is exactly what a `$predicate` schema carries.
+ */
+export const CSS_STYLE_SOURCE =
+  CSS_COLOR_SOURCE +
+  '\n' +
+  CSS_DIMENSION_SOURCE +
+  '\n' +
+  CSS_SHORTHAND_FRAGMENT +
+  '\n' +
+  CSS_STRUCTURE_FRAGMENT
+
+/** Entry predicates exported by the style cluster (for compile/verify). */
+export const CSS_STYLE_ENTRIES = [
+  'isCssProperty',
+  'isSelectorOrAtRule',
+  'isStyleValue',
+  'isStyleValueFor',
+  'isStyleObject',
+] as const
+
+/**
+ * A `$predicate` JSON-Schema for a CSS style object (à la a tosijs styleSpec):
+ * naive validators check only `type: 'object'`; predicate-aware validators run
+ * `isStyleObject`, validating the whole recursive structure (nested selectors,
+ * property/value shapes). Progressive enhancement from one serializable schema.
+ */
+export function cssStyleSchema(): PredicateSchema {
+  return {
+    type: 'object',
+    title: 'CSSStyleObject',
+    description:
+      'An open, recursive CSS style object (properties + nested selectors/at-rules).',
+    $predicate: CSS_STYLE_SOURCE,
+  }
+}
+
+/**
+ * A `$predicate` schema for a single CSS **color** value (entry `isColorValue`,
+ * so a trailing `!important` is tolerated). Naive validators check `type:
+ * 'string'`; aware ones validate the color grammar.
+ */
+export function cssColorSchema(): PredicateSchema {
+  return { type: 'string', title: 'CSSColor', $predicate: CSS_COLOR_SOURCE }
+}
+
+/**
+ * A `$predicate` schema for a CSS **dimension** value (length/%/angle/time/
+ * number; entry `isDimension`). No structural `type` — a dimension may be a
+ * string (`10px`) or a number — so aware validators do all the work.
+ */
+export function cssDimensionSchema(): PredicateSchema {
+  return { title: 'CSSDimension', $predicate: CSS_DIMENSION_SOURCE }
+}

package/src/index-tsfree.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Reproduction + guard for the "`import 'tjs-lang'` crashes without the TypeScript
+ * compiler" bug (snowfox production feedback).
+ *
+ * The main entry (`src/index.ts`) does `export * from './lang'`, which reaches
+ * `src/lang/index.ts`. If that statically re-exports `fromTS`, the whole
+ * TypeScript compiler (~4-10MB) is dragged into the module graph. `typescript`
+ * is only a devDependency (externalized in the build), so a Node consumer who
+ * runs `import 'tjs-lang'` without it installed gets
+ * `Cannot find package 'typescript' imported from dist/index.js` — and it also
+ * pulls TS at import time, which breaks constrained runtimes (Cloud Run).
+ *
+ * The fix: the TS compiler must be reachable ONLY via the explicit
+ * `tjs-lang/lang/from-ts` subpath, never through the main entry. This test
+ * bundles the main entry with esbuild (same externals as `scripts/build.ts`'s
+ * `index` target) and asserts `typescript` never appears as an import specifier.
+ */
+import { describe, it, expect } from 'bun:test'
+import { buildSync } from 'esbuild'
+
+const HERE = import.meta.dir
+
+/** All static + dynamic import specifiers in a bundle (bare, relative, or URL). */
+function importSpecifiers(src: string): string[] {
+  const found: string[] = []
+  for (const m of src.matchAll(
+    /(?:^|[;\n}])import\s*(?:[^"';]*?from)?\s*["']([^"']+)["']/g
+  ))
+    found.push(m[1])
+  for (const m of src.matchAll(/import\(\s*["']([^"']+)["']\s*\)/g))
+    found.push(m[1])
+  return [...new Set(found)]
+}
+
+describe("import 'tjs-lang' must not pull in the TypeScript compiler", () => {
+  it('main entry bundle has no static `typescript` import', () => {
+    // Mirror scripts/build.ts's `index` target externals. `typescript` is
+    // externalized there, so if the main entry reaches it, esbuild leaves a
+    // bare `import "typescript"` in the output — which is exactly the crash.
+    const out = buildSync({
+      entryPoints: [`${HERE}/index.ts`],
+      bundle: true,
+      format: 'esm',
+      platform: 'neutral',
+      write: false,
+      external: [
+        'acorn',
+        'tosijs-schema',
+        'typescript',
+        'node:readline',
+        'node:fs',
+        'node:path',
+      ],
+    }).outputFiles[0].text
+
+    expect(importSpecifiers(out)).not.toContain('typescript')
+  })
+})

package/src/lang/bare-assignments.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+
+/**
+ * `transformBareAssignments` auto-const's a FIRST bare assignment to an
+ * uppercase identifier (native-TJS convenience: `Foo = Type(...)` → `const Foo`).
+ * Two invariants it must respect — both were broken and are regression-guarded
+ * here (a tosijs live-example crashed because `let B = null; … B = BABYLON`
+ * became `const B = BABYLON`, shadowing the outer `B`):
+ *   1. It is a TJS feature — must NOT touch plain JS (dialect: 'js'). TJS ⊇ JS.
+ *   2. Even in TJS, it must NOT redeclare an already-declared binding.
+ */
+const code = (src: string, dialect: 'js' | 'tjs') =>
+  tjs(src, { dialect, runTests: false }).code
+
+describe('bare assignments (auto-const) — TJS-only, first-assignment-only', () => {
+  it('dialect:js — a reassignment of a declared uppercase let is untouched', () => {
+    const out = code('let B = null\nfunction f() { B = 1 }', 'js')
+    expect(out).not.toContain('const B = 1')
+    expect(out).toContain('B = 1')
+  })
+
+  it('dialect:js — even an undeclared uppercase assignment (implicit global) is untouched', () => {
+    expect(code('Foo = 1', 'js')).not.toContain('const Foo')
+  })
+
+  it('dialect:js — the reported repro: B = BABYLON inside a method stays an assignment', () => {
+    const out = code(
+      'let B = null\nconst s = g({ m(el, BABYLON) { B = BABYLON } })',
+      'js'
+    )
+    expect(out).not.toContain('const B = BABYLON')
+    expect(out).toContain('B = BABYLON')
+  })
+
+  it('dialect:tjs — reassignment of a declared binding is preserved', () => {
+    const out = code('let B = null\nconst s = g({ m() { B = 1 } })', 'tjs')
+    expect(out).not.toContain('const B = 1')
+  })
+
+  it('dialect:tjs — the feature still fires for a FIRST assignment of an undeclared uppercase name', () => {
+    expect(code('Foo = { debug: true }', 'tjs')).toContain('const Foo')
+  })
+
+  it('never rewrites lowercase identifiers (only uppercase convention)', () => {
+    expect(code('foo = 1', 'tjs')).not.toContain('const foo')
+  })
+})

package/src/lang/doc-comment-position.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+
+/**
+ * A doc comment (`/*#` … or JSDoc `/**` …) is only a doc comment when it starts
+ * a line — whitespace-only before the `/`. A `/*#` after code on the line, or
+ * inside a string literal, is an ordinary block comment and must be ignored (not
+ * extracted as documentation). Enforced by a line-start lookbehind on every
+ * doc-comment matcher (docs.ts, from-ts, parser, bin/docs.js).
+ */
+const descOf = (src: string) =>
+  tjs(src, { dialect: 'js', runTests: false }).metadata?.greet?.description
+
+describe('doc comments must start a line (whitespace-only before the slash)', () => {
+  const fn = '\nfunction greet(name) { return name }'
+
+  it('extracts a line-start /*# doc comment', () => {
+    expect(descOf('/*#\nMy docs\n*/' + fn)).toContain('My docs')
+  })
+
+  it('extracts an indented (own-line) /*# doc comment', () => {
+    expect(descOf('  /*#\n  Indented docs\n  */' + fn)).toContain('Indented')
+  })
+
+  it('ignores a /*# that follows code on the same line', () => {
+    expect(descOf('const x = 1 /*# not a doc */' + fn)).toBeUndefined()
+  })
+
+  it('ignores a /*# inside a string literal', () => {
+    expect(descOf('const s = "/*# not a doc */"' + fn)).toBeUndefined()
+  })
+})

package/src/lang/docs.ts

@@ -169,8 +169,12 @@ export function generateDocs(source: string): DocResult {
   // Two doc-block flavors are recognized:
   //   /*# ... */   — TJS native: content is markdown verbatim
   //   /** ... */   — JSDoc: each line's leading ` * ` is stripped, then markdown
-  const docPattern = /\/\*#([\s\S]*?)\*\//g
-  const jsdocPattern = /\/\*\*([\s\S]*?)\*\//g
+  // Only a line-start doc comment (whitespace-only before the `/`) counts; a
+  // `/*#` or `/**` after code on the line — or inside a string — is an ordinary
+  // block comment, not documentation. The lookbehind keeps match.index on the
+  // `/` (no position shift for callers).
+  const docPattern = /(?<=^[ \t]*)\/\*#([\s\S]*?)\*\//gm
+  const jsdocPattern = /(?<=^[ \t]*)\/\*\*([\s\S]*?)\*\//gm
   // Match the START of a function declaration. Params (which can contain
   // nested parens like `fn = (x) => x`) are captured by balanced-paren
   // scanning below, NOT by this regex.

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

@@ -0,0 +1,95 @@
+/**
+ * Unit tests for `emitVerifiedPredicate` — the transpile-time source emitter
+ * that turns a verified-safe predicate cluster into a self-contained,
+ * fuel-bounded guard expression (the foundation of wiring predicates into
+ * `Type`/`FunctionPredicate`). Distinct from `compilePredicate`, which evals to
+ * live closures; here we assert the emitted *string* is self-contained and
+ * behaves correctly when evaluated.
+ */
+import { describe, it, expect } from 'bun:test'
+import { emitVerifiedPredicate } from './predicate'
+
+/** Evaluate an emitted guard expression to a callable, in an empty scope. */
+function guardFrom(code: string): (...a: any[]) => boolean {
+  // Indirect eval: the emitted code is a self-contained IIFE expression.
+  return new Function(`return (${code})`)()
+}
+
+describe('emitVerifiedPredicate', () => {
+  it('emits a self-contained guard for a safe predicate', () => {
+    const r = emitVerifiedPredicate(
+      'function isPos(x) { return x > 0 }',
+      'isPos'
+    )
+    expect(r.safe).toBe(true)
+    expect(r.diagnostics).toEqual([])
+    expect(typeof r.code).toBe('string')
+
+    const guard = guardFrom(r.code!)
+    expect(guard(5)).toBe(true)
+    expect(guard(-1)).toBe(false)
+    expect(guard(0)).toBe(false)
+  })
+
+  it('coerces the guard result to a real boolean', () => {
+    // Truthy/falsy body values must come back as strict booleans.
+    const r = emitVerifiedPredicate(
+      'function nonEmpty(s) { return s && s.length }',
+      'nonEmpty'
+    )
+    const guard = guardFrom(r.code!)
+    expect(guard('hi')).toBe(true)
+    expect(guard('')).toBe(false)
+  })
+
+  it('supports composition + array methods (fuel-bounded iteration)', () => {
+    const src =
+      'function isWord(s) { return typeof s === "string" && s.length > 0 }\n' +
+      'function allWords(xs) { return Array.isArray(xs) && xs.every(isWord) }'
+    const r = emitVerifiedPredicate(src, 'allWords')
+    expect(r.safe).toBe(true)
+    const guard = guardFrom(r.code!)
+    expect(guard(['a', 'b'])).toBe(true)
+    expect(guard(['a', ''])).toBe(false)
+    expect(guard('nope')).toBe(false)
+  })
+
+  it('rejects an unsafe predicate (loop) with diagnostics, no code', () => {
+    const r = emitVerifiedPredicate(
+      'function f(xs) { for (const x of xs) { if (x < 0) return false } return true }',
+      'f'
+    )
+    expect(r.safe).toBe(false)
+    expect(r.code).toBeUndefined()
+    expect(r.diagnostics.length).toBeGreaterThan(0)
+    expect(r.diagnostics[0].message).toMatch(/loop/i)
+  })
+
+  it('rejects an impure predicate (effectful call)', () => {
+    const r = emitVerifiedPredicate('function f(x) { return fetch(x) }', 'f')
+    expect(r.safe).toBe(false)
+    expect(r.code).toBeUndefined()
+  })
+
+  it('reports a missing entry name as unsafe', () => {
+    const r = emitVerifiedPredicate(
+      'function isPos(x) { return x > 0 }',
+      'nope'
+    )
+    expect(r.safe).toBe(false)
+    expect(r.diagnostics[0].message).toMatch(/not found/i)
+  })
+
+  it('returns false (does not throw) on a runaway input — DoS-safe guard', () => {
+    // Unbounded recursion: with a tiny fuel budget it must exhaust and the guard
+    // answers `false` rather than hanging or throwing to the caller.
+    const r = emitVerifiedPredicate(
+      'function deep(n) { return deep(n + 1) }',
+      'deep',
+      { fuel: 100 }
+    )
+    expect(r.safe).toBe(true)
+    const guard = guardFrom(r.code!)
+    expect(guard(0)).toBe(false)
+  })
+})

package/src/lang/emitters/dts.test.ts

@@ -166,6 +166,37 @@ export function greet(name = 'world'): '' {
     expect(dts).toContain('name?: string')
   })
 
+  // #11: a bare (untyped) param is a required *position* in a signature, not an
+  // optional *contract* — runtime `required:false` (wild-west JS) must not leak
+  // into dts optionality, or the auto .d.ts is INVALID TS (ts1016: an optional
+  // param can't precede a required one), not merely loose.
+  it('emits bare params as required positions (valid TS, not a?: before b)', () => {
+    const dts = generateDTS(
+      transpileToJS('export function f(a, b: 0) { return a }', {
+        runTests: false,
+      }),
+      'export function f(a, b: 0) { return a }'
+    )
+    expect(dts).toContain('f(a: any, b: number)')
+    expect(dts).not.toContain('a?:') // was `f(a?: any, b: number)` — invalid TS
+  })
+
+  it('keeps deliberate optionals (default / ?) optional', () => {
+    const src = "export function g(a = 1, b?: '') { return a }"
+    const dts = generateDTS(transpileToJS(src, { runTests: false }), src)
+    expect(dts).toContain('a?: number')
+    expect(dts).toContain('b?: string')
+  })
+
+  it('demotes an optional-before-required to required (no ts1016)', () => {
+    // `h(a = 1, b)` — a is a default (optional) but a required position (bare b)
+    // follows it, so a must be emitted required to keep the signature valid.
+    const src = 'export function h(a = 1, b) { return a }'
+    const dts = generateDTS(transpileToJS(src, { runTests: false }), src)
+    expect(dts).toContain('h(a: number, b: any)')
+    expect(dts).not.toContain('a?:')
+  })
+
   it('should handle multiple parameters and return types', () => {
     const source = `
 export function add(a: 0, b: 0): 0 {

package/src/lang/emitters/dts.ts

@@ -109,11 +109,30 @@ function functionDeclToTS(
   exported: boolean,
   isDefault: boolean
 ): string {
-  const params = Object.entries(info.params)
-    .map(([pName, p]) => {
-      const optional = !p.required
+  // DTS optionality is NOT the runtime `required` flag. Runtime `required` is a
+  // *contract* check: a bare (untyped) JS param is wild-west — `required:false`
+  // so the runtime doesn't reject omitting it — but it's still a required
+  // *position* in the signature, not an optional *contract*. A param is emitted
+  // optional only if (a) it's a DELIBERATE optional — a default value or `?`
+  // marker, both of which set `default` (a bare param has no `default` at all) —
+  // and (b) no required param follows it (TS forbids an optional param before a
+  // required one; ts1016). Deriving optionality from `!required` leaked wild-west
+  // omittability into the dts and produced INVALID TS (#11).
+  const entries = Object.entries(info.params)
+  const optionalFlags: boolean[] = new Array(entries.length)
+  let requiredFollows = false
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const p = entries[i][1] as (typeof entries)[number][1] & {
+      default?: unknown
+    }
+    const deliberateOptional = !p.required && p.default !== undefined
+    optionalFlags[i] = deliberateOptional && !requiredFollows
+    if (!optionalFlags[i]) requiredFollows = true
+  }
+  const params = entries
+    .map(([pName, p], i) => {
       const tsType = typeDescriptorToTS(p.type)
-      return optional ? `${pName}?: ${tsType}` : `${pName}: ${tsType}`
+      return optionalFlags[i] ? `${pName}?: ${tsType}` : `${pName}: ${tsType}`
     })
     .join(', ')
 

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

@@ -2333,7 +2333,10 @@ function extractDocComments(
   source: string
 ): Array<{ content: string; index: number }> {
   const comments: Array<{ content: string; index: number }> = []
-  const docRegex = /\/\*#[\s\S]*?\*\//g
+  // Line-start `/*#` only (whitespace-only before it); a mid-line `/*#` (after
+  // code, or inside a string) is an ordinary block comment. Lookbehind is
+  // zero-width, so match.index stays on `/*#` for the brace-depth check below.
+  const docRegex = /(?<=^[ \t]*)\/\*#[\s\S]*?\*\//gm
 
   // Track brace depth to identify top-level comments
   let braceDepth = 0

package/src/lang/emitters/js.ts

@@ -59,7 +59,11 @@ import {
   transformEqualityToStructural,
   transformIsOperators,
 } from '../parser-transforms'
-import type { TypeDescriptor, ParameterDescriptor } from '../types'
+import type {
+  TypeDescriptor,
+  ParameterDescriptor,
+  PredicateVerification,
+} from '../types'
 import { inferTypeFromValue, parseParameter } from '../inference'
 import { extractTests } from '../tests'
 import {
@@ -137,6 +141,14 @@ export interface TJSTranspileResult {
   metadata: Record<string, TJSTypeInfo>
   /** Any warnings during transpilation */
   warnings?: string[]
+  /**
+   * Per-`Type`/`Generic` predicate verification status: `verified` → compiled to
+   * a fuel-bounded, DoS-safe native guard; `!verified` → fell back to a plain
+   * function (valid, but not fuel-bounded / not safe on untrusted data — its
+   * `reason` is the verifier diagnostic). Unverified entries are also mirrored
+   * into `warnings`. Lets tools flag unverifiable predicates.
+   */
+  predicates?: PredicateVerification[]
   /** Generated test runner code (if tests were present) - DEPRECATED, tests now run at transpile time */
   testRunner?: string
   /** Number of tests extracted */
@@ -668,6 +680,24 @@ export function transpileToJS(
     filename,
   })
 
+  // Mirror unverifiable Type/Generic predicates into `warnings` (they still
+  // compile — as plain functions — but aren't fuel-bounded / safe on untrusted
+  // data). The full per-predicate status is returned as `predicates`.
+  for (const p of preprocessed.predicates) {
+    if (!p.verified) {
+      warnings.push(
+        `${p.kind} '${
+          p.name
+        }': predicate is not verifiable, compiled as a plain function (not fuel-bounded, not safe on untrusted data)${
+          p.reason ? ` — ${p.reason.replace(/\s+/g, ' ').trim()}` : ''
+        }`
+      )
+    }
+  }
+  const predicateReport = preprocessed.predicates.length
+    ? preprocessed.predicates
+    : undefined
+
   // Apply the same source-level equality transforms to extracted test/mock
   // bodies so they observe the module's TJS semantics (e.g. structural ==).
   // Test bodies are extracted as raw text before parse(), so they would
@@ -1158,6 +1188,7 @@ export function transpileToJS(
       metadata: allTypes,
       testResults,
       testCount: testResults?.length,
+      predicates: predicateReport,
     }
   }
 
@@ -1178,6 +1209,7 @@ export function transpileToJS(
     types: allTypes,
     metadata: allTypes, // alias for runtime compatibility
     warnings: warnings.length > 0 ? warnings : undefined,
+    predicates: predicateReport,
     testRunner: tests.length > 0 ? testRunner : undefined,
     testCount: tests.length > 0 ? tests.length : undefined,
     testResults,