tjs-lang 0.8.5 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "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/emitters/from-ts.ts

@@ -1095,19 +1095,33 @@ function transformGenericInterfaceToGeneric(
   if (declarationAnnotation?.text) {
     parts.push(`declaration ${declarationAnnotation.text}`)
   } else {
-    // Auto-generate declaration block from interface members
+    // Auto-generate declaration block from interface members. Each member's
+    // type is converted to a TJS example via `typeToExample` (the same converter
+    // the non-generic interface path uses) rather than emitted as raw TS — so
+    // `path: string` → `path: ''`, `touch: () => void` → a FunctionPredicate
+    // example, and un-representable shapes (call-signature objects, etc.) degrade
+    // to a safe placeholder instead of producing TJS that won't re-parse.
+    // (The `@tjs declaration { … }` annotation path above is verbatim and
+    // unaffected — authors can still hand-write precise type signatures.)
     const declMembers: string[] = []
     for (const member of node.members) {
       if (ts.isPropertySignature(member) && member.name) {
         const propName = member.name.getText(sourceFile)
         const optional = member.questionToken ? '?' : ''
-        const typeText = member.type ? member.type.getText(sourceFile) : 'any'
-        declMembers.push(`${propName}${optional}: ${typeText}`)
+        const example = member.type
+          ? typeToExample(member.type, undefined, warnings)
+          : 'null'
+        declMembers.push(`${propName}${optional}: ${example}`)
       } else if (ts.isMethodSignature(member) && member.name) {
-        // Method: name(params): returnType
-        const methodText = member.getText(sourceFile).trim()
-        // Remove trailing semicolon if present
-        declMembers.push(methodText.replace(/;$/, ''))
+        // Method → a function example built from its return type (params are
+        // descriptive; the predicate above does the actual runtime check).
+        const propName = member.name.getText(sourceFile)
+        const ret = member.type
+          ? typeToExample(member.type, undefined, warnings)
+          : 'null'
+        declMembers.push(
+          `${propName}: FunctionPredicate('function', { returns: ${ret} })`
+        )
       }
     }
     if (declMembers.length > 0) {
@@ -1288,10 +1302,17 @@ function transformTypeAliasToType(
 
   const example = typeToExample(node.type, undefined, warnings)
 
-  // 'any' and 'undefined' — preserve original TS body for DTS round-tripping
+  // 'any' and 'undefined' — un-representable in TJS (intersections with
+  // `typeof`/index signatures, etc.). Degrade to an empty Type (validates as
+  // anything) and preserve the original TS body as a SINGLE-LINE comment so the
+  // DTS emitter can recover it. The collapse is essential: a multi-line type
+  // body would leave lines 2+ uncommented = raw TS leaking into the block =
+  // unparseable. (Representable shapes never reach here — they convert above.)
   if (example === 'any' || example === 'undefined') {
-    const originalType = node.type.getText(sourceFile).trim()
-    // Include the TS type body so the DTS emitter can recover it
+    const originalType = node.type
+      .getText(sourceFile)
+      .trim()
+      .replace(/\s+/g, ' ')
     return `Type ${typeName} {\n  // TS: ${originalType}\n}`
   }
 
@@ -1423,25 +1444,35 @@ function transformGenericTypeAliasToGeneric(
     const typeBody = node.type
 
     if (typeBody && ts.isTypeLiteralNode(typeBody)) {
-      // Object type literal: { item: T; count: number }
+      // Object type literal: { item: T; count: number }. Convert each member's
+      // type to a TJS example (degrades gracefully) rather than emitting raw TS.
       const declMembers: string[] = []
       for (const member of typeBody.members) {
         if (ts.isPropertySignature(member) && member.name) {
           const propName = member.name.getText(sourceFile)
           const optional = member.questionToken ? '?' : ''
-          const typeText = member.type ? member.type.getText(sourceFile) : 'any'
-          declMembers.push(`${propName}${optional}: ${typeText}`)
+          const example = member.type
+            ? typeToExample(member.type, undefined, warnings)
+            : 'null'
+          declMembers.push(`${propName}${optional}: ${example}`)
         } else if (ts.isMethodSignature(member) && member.name) {
-          declMembers.push(member.getText(sourceFile).trim().replace(/;$/, ''))
+          const propName = member.name.getText(sourceFile)
+          const ret = member.type
+            ? typeToExample(member.type, undefined, warnings)
+            : 'null'
+          declMembers.push(
+            `${propName}: FunctionPredicate('function', { returns: ${ret} })`
+          )
         }
       }
       if (declMembers.length > 0) {
         parts.push(`declaration {\n    ${declMembers.join('\n    ')}\n  }`)
       }
     } else if (typeBody) {
-      // Complex type (conditional, mapped, intersection, etc.)
-      // Pass through the TS type body verbatim
-      const typeText = typeBody.getText(sourceFile).trim()
+      // Complex type (conditional, mapped, intersection, …) — un-representable.
+      // Keep the TS body as a SINGLE-LINE comment (collapse newlines, else lines
+      // 2+ leak as raw TS and won't re-parse).
+      const typeText = typeBody.getText(sourceFile).trim().replace(/\s+/g, ' ')
       parts.push(`declaration {\n    // TS: ${typeText}\n  }`)
     }
   }
@@ -2302,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/from-ts.test.ts

@@ -312,3 +312,51 @@ describe('@tjs annotations', () => {
     })
   })
 })
+
+// Regression: TS→TJS must never emit TJS that won't re-parse. These real-world
+// shapes (from tosijs) used to leak raw TS into Type/Generic blocks — generic
+// interfaces emitted raw member types in `declaration {}`, and intersections /
+// complex types emitted MULTI-LINE `// TS:` comments whose lines 2+ leaked as
+// raw TS. fromTS now converts members via typeToExample and collapses
+// un-representable bodies to a single-line comment (graceful degradation).
+describe('TS→TJS round-trips (no raw-TS leak into TJS blocks)', () => {
+  const { tjs } = require('./index') as { tjs: (s: string) => { code: string } }
+  const roundTrips = (ts: string) => {
+    const emitted = fromTS(ts, { emitTJS: true }).code
+    expect(() => tjs(emitted)).not.toThrow() // emitted TJS must re-parse
+    return emitted
+  }
+
+  it('generic interface with complex members (arrow, generic arrow, call-sig)', () => {
+    const out = roundTrips(`export interface Acc<T = any> {
+      value: T
+      path: string
+      touch: () => void
+      bind: <E extends Element = Element>(el: E, b: any) => void
+      find: { (selector: (item: any) => any, value: any): any }
+    }`)
+    // members converted to examples, not raw TS
+    expect(out).toContain("path: ''")
+    expect(out).toContain('touch: FunctionPredicate')
+    expect(out).not.toMatch(/path: string\b/) // no raw type leak
+  })
+
+  it('intersection type alias (typeof / index signature) degrades, single-line', () => {
+    const out = roundTrips(`export type ProxyObj = Props<object> & {
+      [key: string]: ProxyObj | string | null
+    }`)
+    // un-representable → comment-only Type, collapsed to one line (no leak)
+    expect(out).toMatch(/\/\/ TS:.*&/)
+    expect(out).not.toMatch(/\n\s*\[key: string\]:/) // the body didn't leak raw
+  })
+
+  it('generic type alias with object body + arrow member', () => {
+    roundTrips(`export type Wrap<T> = { value: T; build: (x: T) => T }`)
+  })
+
+  it('plain type alias with arrow + union return still works', () => {
+    roundTrips(
+      `export type AnyFunction = (...args: any[]) => any | Promise<any>`
+    )
+  })
+})

package/src/lang/parser-transforms.ts

@@ -3126,12 +3126,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}`)
     }
   )

package/src/lang/parser.ts

@@ -304,9 +304,14 @@ export function preprocess(
   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
@@ -737,7 +742,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(