tjs-lang 0.8.1 → 0.8.2

package/CLAUDE.md

@@ -113,7 +113,11 @@ createAgent(source, vm)     // Creates callable agent
 
 // VM
 const vm = new AgentVM(customAtoms)
-await vm.run(ast, args, { fuel, capabilities, timeoutMs, trace })
+await vm.run(ast, args, {
+  fuel, capabilities, timeoutMs, trace,
+  costOverrides: { atomOp: 5 },             // per-atom fuel cost override
+  timeoutOverrides: { atomOp: 60_000 },     // per-atom wall-clock override (ms; 0 disables)
+})
 
 // Builder
 Agent.take(schema).varSet(...).httpFetch(...).return(schema)
@@ -208,7 +212,7 @@ fn('a', 'b') // Returns { error: 'type mismatch', ... }
 **Design Notes:**
 
 - The two steps are intentionally separate for tree-shaking (TS support is optional)
-- `fromTS` lives in a separate entry point (`tosijs/lang/from-ts`)
+- `fromTS` lives in a separate entry point (`tjs-lang/lang/from-ts`)
 - Import only what you need to keep bundle size minimal
 - Each step is independently testable (see `src/lang/codegen.test.ts`)
 - Constrained generics (`<T extends { id: number }>`) use the constraint as the example value instead of `any`
@@ -249,7 +253,7 @@ AJS expressions behave differently from JavaScript in several important ways:
 - Unit tests alongside source files (`*.test.ts`)
 - Integration tests in `src/use-cases/` (RAG, orchestration, malicious actors)
 - Security tests in `src/use-cases/malicious-actor.test.ts`
-- Language tests split across 17 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
+- Language tests split across 18 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
 - LLM integration tests (run via full `bun test`, skipped by `SKIP_LLM_TESTS`) need a local **LM Studio** server with a chat + embedding model loaded. Setup and the hard-won gotchas (model load failures, leaked-VRAM stray `node` worker, updating runtimes, CORS, the audit-cache parallel race) are in [`docs/lm-studio-setup.md`](docs/lm-studio-setup.md).
 
 Coverage targets: 98% lines on `src/vm/runtime.ts` (security-critical), 80%+ overall.
@@ -303,6 +307,7 @@ Full syntax documentation is in [`CLAUDE-TJS-SYNTAX.md`](CLAUDE-TJS-SYNTAX.md).
 - **Return types**: `function add(a: 0, b: 0): 0 { ... }` (colon syntax, same as TypeScript)
 - **Safety markers**: `!` = unsafe (skip validation), `?` = safe (explicit validation)
 - **Mode defaults**: Native TJS has all modes ON by default (`TjsEquals`, `TjsClass`, `TjsDate`, `TjsNoeval`, `TjsNoVar`, `TjsStandard`). TS-originated code (`fromTS`) and AJS/VM code get modes OFF. `TjsCompat` directive explicitly disables all modes. `TjsStrict` enables all modes (useful for TS-originated code opting in).
+- **Source dialect (`dialect: 'js' | 'tjs'`)**: the public, programmatic way to set the modes-on/off default. `tjs(src, { dialect: 'js' })` preserves plain-JS semantics (modes OFF, `safety: 'none'`); `'tjs'` (or a bare string) is native TJS (modes ON). `dialect` is authoritative; otherwise inferred from the `fromTS` annotation / `vmTarget`. For file-based tooling, use the canonical extension→dialect helpers `dialectForFilename(filename)` / `sourceKindForFilename(filename)` from `tjs-lang/lang` (`.js`/`.mjs`/`.cjs` → `'js'`, `.tjs` → `'tjs'`, `.ts` → use `fromTS`). This upholds the **TJS ⊇ JS** invariant — see `PRINCIPLES.md`. (`.tjs` is a _better_ language, not just JS; choosing it is the opt-in to the modes.)
 - **Bang access**: `x!.foo` — returns MonadicError if `x` is null/undefined, otherwise bare `x.foo`. Chains propagate: `x!.foo!.bar`.
 - **Type/Generic/FunctionPredicate**: Three declaration forms for runtime type predicates
 - **`const!`**: Compile-time immutability, zero runtime cost
@@ -478,6 +483,7 @@ The CLI (`bun src/cli/tjs.ts run`) does NOT inject the test-block `expect` harne
 
 ### Additional Documentation
 
+- `PRINCIPLES.md` — **non-negotiable language invariants**: options-off TJS ⊇ JS, and TJS ⊇ AJS. A richer layer may do _more_ with the same source but must never make subset-legal code _illegal_ (e.g. un-runnable signature tests are inconclusive, not errors). Read before changing parser/transpiler acceptance or signature-test behavior; a subset violation is a bug.
 - `llms.txt` — agent-facing navigation index (ships in npm bundle); points to docs and source entry points
 - `guides/footguns.md` — JS footguns TJS fixes (boxed-primitive truthiness, `==` coercion, `typeof null`, uninitialized `let`, etc.). Demo: `examples/js-footguns-fixed.tjs`.
 - `guides/playground-imports.md` — how the playground/dev-server resolves bare imports: TFS service worker, default JSDelivr `/+esm` routing, esm.sh allowlist for peer-dep packages (React), CDN hints (`jsdelivr/`, `esmsh/`, `unpkg/`, `github/`), and full-URL passthrough.

package/demo/examples.test.ts

@@ -448,9 +448,13 @@ describe('Playground Examples', () => {
             args.imageUrl = '/test-shapes.jpg'
           }
 
-          // Use the SAME capabilities as the playground
+          // Use the SAME capabilities as the playground.
+          // Vision inference on a local model can take a while; give it an
+          // explicit budget well above the slow-atom timeout so the test is
+          // deterministic regardless of the run-level default.
           const runResult = await vm.run(result.ast, args, {
             fuel: 100000,
+            timeoutMs: 180000,
             capabilities: {
               fetch: httpFetch,
               llm: llmCapability || mockLLM,
@@ -466,7 +470,7 @@ describe('Playground Examples', () => {
         } finally {
           trackTestEnd()
         }
-      }, 120000)
+      }, 240000) // bun-test timeout above the vm timeoutMs (180s) + overhead
     } else if (needsRetry) {
       // Examples that use runCode need retry due to LLM variability
       it(`${example.name} - runs successfully`, async () => {

package/demo/src/playground-shared.ts

@@ -255,28 +255,36 @@ export function renderConsoleMessages(
 
 /**
  * Render test results HTML with clickable error links and editor gutter markers.
- * Returns pass/fail counts so callers can update tab indicators.
+ * Returns pass/fail/inconclusive counts so callers can update tab indicators.
  */
 export function renderTestResults(
   tests: any[],
   outputEl: HTMLElement,
   editor: CodeMirror,
   goToLine: (line: number) => void
-): { passed: number; failed: number } {
+): { passed: number; failed: number; inconclusive: number } {
   if (!tests || tests.length === 0) {
     outputEl.textContent = 'No tests defined'
     editor.clearMarkers()
-    return { passed: 0, failed: 0 }
+    return { passed: 0, failed: 0, inconclusive: 0 }
   }
 
   const passed = tests.filter((t: any) => t.passed).length
-  const failed = tests.filter((t: any) => !t.passed).length
-
-  // Mark only FAILED tests in the editor. Passing tests appear in the
-  // results panel and don't need an underline — `severity: 'info'` was
-  // rendering as a grey squiggle on every passing test's line, which is
-  // visual noise.
-  const failedWithLines = tests.filter((t: any) => t.line && !t.passed)
+  // Inconclusive = the test couldn't *run* (e.g. it calls an AJS atom that
+  // doesn't exist at build time). It is neither pass nor fail — surface it as
+  // a distinct warning state and keep it out of the failure count, so legal
+  // AJS doesn't read as broken in the playground. See PRINCIPLES.md.
+  const inconclusive = tests.filter(
+    (t: any) => !t.passed && t.inconclusive
+  ).length
+  const failed = tests.filter((t: any) => !t.passed && !t.inconclusive).length
+
+  // Mark only genuine FAILURES in the editor. Passing tests don't need an
+  // underline (it reads as visual noise), and an inconclusive test isn't a
+  // failure — a red squiggle would wrongly imply the code is broken.
+  const failedWithLines = tests.filter(
+    (t: any) => t.line && !t.passed && !t.inconclusive
+  )
   if (failedWithLines.length > 0) {
     editor.setMarkers(
       failedWithLines.map((t: any) => ({
@@ -294,19 +302,29 @@ export function renderTestResults(
   if (failed > 0) {
     html += `, <strong class="test-failed">${failed} failed</strong>`
   }
+  if (inconclusive > 0) {
+    html += `, <strong class="test-inconclusive">${inconclusive} inconclusive</strong>`
+  }
   html += `</div><ul class="test-list">`
 
   for (const test of tests) {
-    const icon = test.passed ? '✓' : '✗'
-    const cls = test.passed ? 'test-pass' : 'test-fail'
+    const state = test.passed
+      ? 'pass'
+      : test.inconclusive
+      ? 'inconclusive'
+      : 'fail'
+    const icon = test.passed ? '✓' : test.inconclusive ? '—' : '✗'
     const sigBadge = test.isSignatureTest
       ? ' <span class="sig-badge">signature</span>'
       : ''
     const dataLine = test.line ? ` data-line="${test.line}"` : ''
     const clickable = test.line ? ' clickable-test' : ''
-    html += `<li class="${cls}${clickable}"${dataLine}>${icon} ${test.description}${sigBadge}`
-    if (!test.passed && test.error) {
-      html += `<div class="test-error">${test.error}</div>`
+    html += `<li class="test-${state}${clickable}"${dataLine}>${icon} ${test.description}${sigBadge}`
+    if (test.error) {
+      // Inconclusive notes are warnings (couldn't run), not failures.
+      const noteCls = test.inconclusive ? 'test-note' : 'test-error'
+      const prefix = test.inconclusive ? 'could not run — ' : ''
+      html += `<div class="${noteCls}">${prefix}${test.error}</div>`
     }
     html += `</li>`
   }
@@ -327,7 +345,7 @@ export function renderTestResults(
     })
   })
 
-  return { passed, failed }
+  return { passed, failed, inconclusive }
 }
 
 // ---------------------------------------------------------------------------
@@ -589,6 +607,20 @@ export const sharedPlaygroundStyles: Record<string, Record<string, string>> = {
     fontFamily: 'var(--font-mono, monospace)',
   },
 
+  ':host .test-inconclusive': {
+    color: '#d97706',
+  },
+
+  ':host .test-note': {
+    marginLeft: '20px',
+    marginTop: '4px',
+    padding: '8px',
+    background: 'rgba(217, 119, 6, 0.1)',
+    borderRadius: '4px',
+    fontSize: '13px',
+    fontFamily: 'var(--font-mono, monospace)',
+  },
+
   ':host .clickable-test': {
     cursor: 'pointer',
   },

package/demo/src/playground-test-results.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test'
+import { GlobalRegistrator } from '@happy-dom/global-registrator'
+
+beforeAll(() => GlobalRegistrator.register())
+afterAll(() => GlobalRegistrator.unregister())
+
+// Imported after DOM globals exist.
+const { renderTestResults } = await import('./playground-shared')
+
+function fakeEditor() {
+  const calls: any[] = []
+  return {
+    setMarkers: (m: any) => calls.push({ setMarkers: m }),
+    clearMarkers: () => calls.push({ clearMarkers: true }),
+    _calls: calls,
+  } as any
+}
+
+describe('renderTestResults — inconclusive affordance', () => {
+  it('separates inconclusive from passed and failed', () => {
+    const out = document.createElement('div')
+    const editor = fakeEditor()
+    const counts = renderTestResults(
+      [
+        { description: 'a', passed: true },
+        { description: 'b', passed: false, error: 'Expected 5 got 6' },
+        {
+          description: 'c signature example',
+          passed: false,
+          inconclusive: true,
+          isSignatureTest: true,
+          error: 'httpFetch is not defined',
+        },
+      ],
+      out,
+      editor,
+      () => {}
+    )
+
+    expect(counts).toEqual({ passed: 1, failed: 1, inconclusive: 1 })
+
+    // Summary shows all three states
+    expect(out.querySelector('.test-summary')?.textContent).toContain(
+      '1 passed'
+    )
+    expect(out.querySelector('.test-summary')?.textContent).toContain(
+      '1 failed'
+    )
+    expect(out.querySelector('.test-summary')?.textContent).toContain(
+      '1 inconclusive'
+    )
+
+    // The inconclusive test renders with its own class + a warning note (not
+    // a red error), with the "could not run" framing.
+    const incLi = out.querySelector('li.test-inconclusive')
+    expect(incLi).not.toBeNull()
+    expect(incLi?.textContent).toContain('—') // not the ✗ failure icon
+    expect(incLi?.querySelector('.test-note')).not.toBeNull()
+    expect(incLi?.querySelector('.test-error')).toBeNull()
+    expect(incLi?.querySelector('.test-note')?.textContent).toContain(
+      'could not run'
+    )
+
+    // The genuine failure keeps the red error box + ✗ icon.
+    const failLi = out.querySelector('li.test-fail')
+    expect(failLi?.textContent).toContain('✗')
+    expect(failLi?.querySelector('.test-error')).not.toBeNull()
+  })
+
+  it('renders REAL transpiler output: atom-calling agent → inconclusive', async () => {
+    // End-to-end: the transpiler emits inconclusive for an un-runnable
+    // signature test; the playground must render it as such (not a failure).
+    const { tjs } = await import('../../src/lang')
+    const { testResults } = tjs(
+      `function main(url: ''): { x: '' } {\n  const x = httpFetch({ url })\n  return { x }\n}`
+    )
+    const out = document.createElement('div')
+    const counts = renderTestResults(
+      testResults as any,
+      out,
+      fakeEditor(),
+      () => {}
+    )
+    expect(counts.failed).toBe(0)
+    expect(counts.inconclusive).toBe(1)
+    expect(out.querySelector('li.test-inconclusive')).not.toBeNull()
+    expect(out.querySelector('li.test-fail')).toBeNull()
+  })
+
+  it('does NOT put an error marker on an inconclusive test line', () => {
+    const out = document.createElement('div')
+    const editor = fakeEditor()
+    renderTestResults(
+      [
+        {
+          description: 'sig',
+          passed: false,
+          inconclusive: true,
+          line: 3,
+          error: 'atom not defined',
+        },
+      ],
+      out,
+      editor,
+      () => {}
+    )
+    // No setMarkers with an error for the inconclusive line; clearMarkers instead.
+    const markerCalls = editor._calls.filter((c: any) => c.setMarkers)
+    expect(markerCalls).toHaveLength(0)
+    expect(editor._calls.some((c: any) => c.clearMarkers)).toBe(true)
+  })
+})

package/demo/src/tjs-playground.ts

@@ -149,7 +149,7 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
   // Split mode
   private _splitMode: null | 'code' | 'output' = null
   private _splitChannel: BroadcastChannel | null = null
-  private _splitSessionId: string = ''
+  private _splitSessionId = ''
 
   // Build flags state
   private buildFlags = {
@@ -860,21 +860,27 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
 
   private updateTestResults(result: any) {
     const tests = result.testResults
-    const { passed, failed } = renderTestResults(
+    const { passed, failed, inconclusive } = renderTestResults(
       tests,
       this.parts.testsOutput,
       this.parts.tjsEditor,
       (line) => this.goToSourceLine(line)
     )
-    this.updateTestsTabLabel(passed, failed)
+    this.updateTestsTabLabel(passed, failed, inconclusive)
   }
 
-  private updateTestsTabLabel(passed: number, failed: number) {
+  private updateTestsTabLabel(
+    passed: number,
+    failed: number,
+    inconclusive = 0
+  ) {
     const tabs = this.parts.outputTabs
     if (!tabs) return
 
     if (failed > 0) {
       tabs.style.setProperty('--test-indicator-color', '#dc2626')
+    } else if (inconclusive > 0) {
+      tabs.style.setProperty('--test-indicator-color', '#d97706')
     } else if (passed > 0) {
       tabs.style.setProperty('--test-indicator-color', '#16a34a')
     } else {
@@ -1394,7 +1400,7 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
   }
 
   // Navigate to a specific line in the source editor
-  goToSourceLine(line: number, column: number = 1) {
+  goToSourceLine(line: number, column = 1) {
     this.parts.inputTabs.value = 0 // Switch to TJS tab (first tab)
     // Wait for tab switch and editor resize before scrolling
     setTimeout(() => {

package/dist/examples/modules/dist/main.d.ts

@@ -0,0 +1,34 @@
+export function calculate(x?: number, y?: number): any;
+export namespace calculate {
+    namespace __tjs {
+        namespace params {
+            namespace x {
+                export namespace type {
+                    let kind: string;
+                }
+                export let required: boolean;
+                let _default: null;
+                export { _default as default };
+            }
+            namespace y {
+                export namespace type_1 {
+                    let kind_1: string;
+                    export { kind_1 as kind };
+                }
+                export { type_1 as type };
+                let required_1: boolean;
+                export { required_1 as required };
+                let _default_1: null;
+                export { _default_1 as default };
+            }
+        }
+        namespace returns {
+            export namespace type_2 {
+                let kind_2: string;
+                export { kind_2 as kind };
+            }
+            export { type_2 as type };
+        }
+        let source: string;
+    }
+}

package/dist/examples/modules/dist/math.d.ts

@@ -0,0 +1,120 @@
+export function add(a?: number, b?: number): any;
+export namespace add {
+    namespace __tjs {
+        namespace params {
+            namespace a {
+                export namespace type {
+                    let kind: string;
+                }
+                export let required: boolean;
+                let _default: null;
+                export { _default as default };
+            }
+            namespace b {
+                export namespace type_1 {
+                    let kind_1: string;
+                    export { kind_1 as kind };
+                }
+                export { type_1 as type };
+                let required_1: boolean;
+                export { required_1 as required };
+                let _default_1: null;
+                export { _default_1 as default };
+            }
+        }
+        namespace returns {
+            export namespace type_2 {
+                let kind_2: string;
+                export { kind_2 as kind };
+            }
+            export { type_2 as type };
+        }
+        let source: string;
+    }
+}
+export function subtract(a?: number, b?: number): any;
+export namespace subtract {
+    export namespace __tjs_1 {
+        export namespace params_1 {
+            export namespace a_1 {
+                export namespace type_3 {
+                    let kind_3: string;
+                    export { kind_3 as kind };
+                }
+                export { type_3 as type };
+                let required_2: boolean;
+                export { required_2 as required };
+                let _default_2: null;
+                export { _default_2 as default };
+            }
+            export { a_1 as a };
+            export namespace b_1 {
+                export namespace type_4 {
+                    let kind_4: string;
+                    export { kind_4 as kind };
+                }
+                export { type_4 as type };
+                let required_3: boolean;
+                export { required_3 as required };
+                let _default_3: null;
+                export { _default_3 as default };
+            }
+            export { b_1 as b };
+        }
+        export { params_1 as params };
+        export namespace returns_1 {
+            export namespace type_5 {
+                let kind_5: string;
+                export { kind_5 as kind };
+            }
+            export { type_5 as type };
+        }
+        export { returns_1 as returns };
+        let source_1: string;
+        export { source_1 as source };
+    }
+    export { __tjs_1 as __tjs };
+}
+export function multiply(a?: number, b?: number): any;
+export namespace multiply {
+    export namespace __tjs_2 {
+        export namespace params_2 {
+            export namespace a_2 {
+                export namespace type_6 {
+                    let kind_6: string;
+                    export { kind_6 as kind };
+                }
+                export { type_6 as type };
+                let required_4: boolean;
+                export { required_4 as required };
+                let _default_4: null;
+                export { _default_4 as default };
+            }
+            export { a_2 as a };
+            export namespace b_2 {
+                export namespace type_7 {
+                    let kind_7: string;
+                    export { kind_7 as kind };
+                }
+                export { type_7 as type };
+                let required_5: boolean;
+                export { required_5 as required };
+                let _default_5: null;
+                export { _default_5 as default };
+            }
+            export { b_2 as b };
+        }
+        export { params_2 as params };
+        export namespace returns_2 {
+            export namespace type_8 {
+                let kind_8: string;
+                export { kind_8 as kind };
+            }
+            export { type_8 as type };
+        }
+        export { returns_2 as returns };
+        let source_2: string;
+        export { source_2 as source };
+    }
+    export { __tjs_2 as __tjs };
+}