tjs-lang 0.7.7 → 0.8.0

package/src/lang/docs.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { generateDocs, generateDocsMarkdown } from './docs'
+import { generateDocs, generateDocsMarkdown, prettifyTestBody } from './docs'
 
 describe('generateDocs', () => {
   describe('basic output', () => {
@@ -157,6 +157,154 @@ function second(x: 0): 0 { return x }
     })
   })
 
+  describe('JSDoc-style doc blocks', () => {
+    it('extracts /** */ blocks and strips leading asterisks', () => {
+      const source = `
+/**
+ * # Title
+ *
+ * Body line 1
+ * Body line 2
+ */
+`
+      const result = generateDocs(source)
+
+      expect(result.items).toHaveLength(1)
+      const doc = result.items[0] as any
+      expect(doc.type).toBe('doc')
+      expect(doc.content).toBe('# Title\n\nBody line 1\nBody line 2')
+    })
+
+    it('handles single-line JSDoc', () => {
+      const source = `/** A short note. */`
+      const result = generateDocs(source)
+
+      const doc = result.items[0] as any
+      expect(doc.type).toBe('doc')
+      expect(doc.content).toBe('A short note.')
+    })
+
+    it('preserves markdown lists and tables', () => {
+      const source = `
+/**
+ * ## Options
+ *
+ * | Flag | Meaning |
+ * |------|---------|
+ * | \`-v\` | verbose |
+ *
+ * - first
+ * - second
+ */
+`
+      const result = generateDocs(source)
+
+      const doc = result.items[0] as any
+      expect(doc.content).toContain('## Options')
+      expect(doc.content).toContain('| Flag | Meaning |')
+      expect(doc.content).toContain('- first')
+    })
+
+    it('leaves @param / @returns as plain markdown', () => {
+      const source = `
+/**
+ * Square the input.
+ *
+ * @param x - the input
+ * @returns the squared value
+ */
+function square(x: 0): 0 { return x * x }
+`
+      const result = generateDocs(source)
+
+      const doc = result.items[0] as any
+      expect(doc.content).toContain('@param x - the input')
+      expect(doc.content).toContain('@returns the squared value')
+    })
+
+    it('skips JSDoc inside function bodies', () => {
+      const source = `
+function outer() {
+  /**
+   * Should not be extracted — inside a body.
+   */
+  return 1
+}
+`
+      const result = generateDocs(source)
+
+      // Only the function itself, no doc item
+      const docs = result.items.filter((i) => i.type === 'doc')
+      expect(docs).toHaveLength(0)
+    })
+
+    it('skips empty JSDoc blocks', () => {
+      const source = `
+/**
+ *
+ */
+function f() {}
+`
+      const result = generateDocs(source)
+
+      const docs = result.items.filter((i) => i.type === 'doc')
+      expect(docs).toHaveLength(0)
+    })
+
+    it('does not treat /* ... */ as a doc comment', () => {
+      const source = `
+/* just a regular block comment */
+function f() {}
+`
+      const result = generateDocs(source)
+
+      const docs = result.items.filter((i) => i.type === 'doc')
+      expect(docs).toHaveLength(0)
+    })
+
+    it('interleaves JSDoc with functions in document order', () => {
+      const source = `
+/**
+ * # First
+ */
+function first(x: 0): 0 { return x }
+
+/**
+ * # Second
+ */
+function second(x: 0): 0 { return x }
+`
+      const result = generateDocs(source)
+
+      expect(result.items).toHaveLength(4)
+      expect(result.items[0].type).toBe('doc')
+      expect((result.items[0] as any).content).toContain('# First')
+      expect(result.items[1].type).toBe('function')
+      expect(result.items[2].type).toBe('doc')
+      expect((result.items[2] as any).content).toContain('# Second')
+      expect(result.items[3].type).toBe('function')
+    })
+
+    it('coexists with /*# blocks in the same file', () => {
+      const source = `
+/*#
+## TJS-native
+*/
+
+/**
+ * ## JSDoc-native
+ */
+function f(x: 0): 0 { return x }
+`
+      const result = generateDocs(source)
+
+      const docs = result.items.filter((i) => i.type === 'doc') as any[]
+      expect(docs).toHaveLength(2)
+      expect(docs[0].content).toContain('TJS-native')
+      expect(docs[1].content).toContain('JSDoc-native')
+    })
+  })
+
   describe('markdown output', () => {
     it('renders doc blocks as plain markdown', () => {
       const source = `
@@ -452,3 +600,330 @@ function second(y: ''): '' {
     expect(secondPos).toBeLessThan(afterPos)
   })
 })
+
+describe('prettifyTestBody', () => {
+  it('translates toBe', () => {
+    expect(prettifyTestBody('expect(x).toBe(y)')).toBe('x  // → y')
+  })
+
+  it('translates toEqual to ≡', () => {
+    expect(prettifyTestBody('expect(a).toEqual(b)')).toBe('a  // ≡ b')
+  })
+
+  it('handles balanced parens in expression', () => {
+    expect(
+      prettifyTestBody('expect(Boolean(new Boolean(false))).toBe(false)')
+    ).toBe('Boolean(new Boolean(false))  // → false')
+  })
+
+  it('handles balanced parens in expected value', () => {
+    expect(prettifyTestBody('expect(x).toBe(f(1, 2))')).toBe('x  // → f(1, 2)')
+  })
+
+  it('handles toBeTruthy / toBeFalsy / toBeNull / toBeUndefined', () => {
+    expect(prettifyTestBody('expect(x).toBeTruthy()')).toBe('x  // → truthy')
+    expect(prettifyTestBody('expect(x).toBeFalsy()')).toBe('x  // → falsy')
+    expect(prettifyTestBody('expect(x).toBeNull()')).toBe('x  // → null')
+    expect(prettifyTestBody('expect(x).toBeUndefined()')).toBe(
+      'x  // → undefined'
+    )
+  })
+
+  it('translates toContain / toThrow / toBeNaN', () => {
+    expect(prettifyTestBody('expect(arr).toContain(3)')).toBe(
+      'arr  // → contains 3'
+    )
+    expect(prettifyTestBody('expect(fn).toThrow()')).toBe('fn  // → throws')
+    expect(prettifyTestBody('expect(x).toBeNaN()')).toBe('x  // → NaN')
+  })
+
+  it('translates toBeGreaterThan / toBeLessThan', () => {
+    expect(prettifyTestBody('expect(x).toBeGreaterThan(5)')).toBe('x  // → > 5')
+    expect(prettifyTestBody('expect(y).toBeLessThan(10)')).toBe('y  // → < 10')
+  })
+
+  it('preserves non-expect lines', () => {
+    expect(prettifyTestBody('console.log("hi")')).toBe('console.log("hi")')
+    expect(prettifyTestBody('const x = 5')).toBe('const x = 5')
+  })
+
+  it('handles multiple expects on separate lines', () => {
+    const input = '  expect(x).toBe(1)\n  expect(y).toBeTruthy()'
+    const expected = '  x  // → 1\n  y  // → truthy'
+    expect(prettifyTestBody(input)).toBe(expected)
+  })
+
+  it('does not touch parens inside string literals', () => {
+    // The `expect(...)` inside the string literal should NOT be transformed
+    expect(prettifyTestBody(`const s = "expect(fake).toBe(impossible)"`)).toBe(
+      `const s = "expect(fake).toBe(impossible)"`
+    )
+  })
+
+  it('falls back gracefully on unknown matchers', () => {
+    expect(prettifyTestBody('expect(x).somethingWeird(y)')).toBe(
+      'x  // .somethingWeird(y)'
+    )
+  })
+})
+
+describe('function extraction', () => {
+  it('captures simple function signatures', () => {
+    const md = generateDocsMarkdown(
+      `function add(a: 0, b: 0): 0 { return a + b }`
+    )
+    expect(md).toContain('## add')
+    expect(md).toContain('function add(a: 0, b: 0): 0')
+  })
+
+  it('handles arrow-function defaults (params with nested parens)', () => {
+    // Regression: the old funcPattern used [^)]* and broke on `(x) => x`
+    const source = `
+function mapStrings(arr: [''], fn = (x) => x): [''] {
+  return arr.map(fn)
+}
+function compose(f = (x) => x, g = (x) => x): 0 {
+  return f(g(5))
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain('## mapStrings')
+    expect(md).toContain("function mapStrings(arr: [''], fn = (x) => x): ['']")
+    expect(md).toContain('## compose')
+    expect(md).toContain('function compose(f = (x) => x, g = (x) => x): 0')
+  })
+
+  it('handles object/array example values in params', () => {
+    const md = generateDocsMarkdown(
+      `function f(p: { a: 0, b: '' }, q: [0]): {} { return p }`
+    )
+    expect(md).toContain("function f(p: { a: 0, b: '' }, q: [0]): {}")
+  })
+
+  it('handles return-type annotation with quoted string', () => {
+    const md = generateDocsMarkdown(
+      `function greet(name: 'World'): 'Hello, World!' { return \`Hello, \${name}!\` }`
+    )
+    expect(md).toContain("function greet(name: 'World'): 'Hello, World!'")
+  })
+
+  it('does not extract nested function declarations', () => {
+    const source = `
+function outer() {
+  function nested() { return 1 }
+  return nested
+}
+`
+    const result = generateDocs(source)
+    const fns = result.items.filter((i) => i.type === 'function')
+    expect(fns.length).toBe(1)
+    expect(fns[0].name).toBe('outer')
+  })
+
+  describe('function param rendering in docs', () => {
+    // We need transpiled type metadata for the param-table renderer.
+    // Use the lang index's `tjs()` to get types.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { tjs } = require('./index')
+
+    it('renders an arrow-default param as `(x: any) => any` (not `function`)', () => {
+      const r = tjs(`function f(fn = (x) => x): 0 { return 0 }`)
+      const md = generateDocsMarkdown(r.code, r.types)
+      expect(md).toContain('`fn`: (x: any) => any')
+    })
+
+    it('infers return type from concise arrow body', () => {
+      const r = tjs(`function f(make = () => 5): 0 { return 0 }`)
+      const md = generateDocsMarkdown(r.code, r.types)
+      expect(md).toContain('`make`: () => number')
+    })
+
+    it('infers param types from arrow defaults', () => {
+      const r = tjs(
+        `function f(reduce = (acc = 0, x = 0) => 0): 0 { return 0 }`
+      )
+      const md = generateDocsMarkdown(r.code, r.types)
+      expect(md).toContain('`reduce`: (acc: number, x: number) => number')
+    })
+
+    it('does not show `e.g. undefined` for function example values', () => {
+      const r = tjs(`function f(fn = (x) => x): 0 { return 0 }`)
+      const md = generateDocsMarkdown(r.code, r.types)
+      expect(md).not.toContain('undefined')
+    })
+  })
+})
+
+describe('class extraction', () => {
+  it('extracts a class with constructor and methods', () => {
+    const source = `
+class Point {
+  constructor(x: 0, y: 0) {
+    this.x = x
+    this.y = y
+  }
+
+  magnitude() {
+    return Math.sqrt(this.x * this.x + this.y * this.y)
+  }
+
+  toString() {
+    return \`(\${this.x}, \${this.y})\`
+  }
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain('## Point')
+    expect(md).toContain('class Point {')
+    expect(md).toContain('constructor(x: 0, y: 0)')
+    expect(md).toContain('magnitude()')
+    expect(md).toContain('toString()')
+    // Method bodies should NOT appear
+    expect(md).not.toContain('this.x = x')
+    expect(md).not.toContain('Math.sqrt')
+  })
+
+  it('extracts multiple constructors', () => {
+    const source = `
+class Color {
+  constructor(r: +0, g: +0, b: +0) { this.r = r; this.g = g; this.b = b }
+  constructor(hex: '#000000') { /* parse */ }
+  toString() { return 'rgb(...)' }
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain('constructor(r: +0, g: +0, b: +0)')
+    expect(md).toContain("constructor(hex: '#000000')")
+    expect(md).toContain('toString()')
+  })
+
+  it('renders extends clause', () => {
+    const source = `
+class ColorWithAlpha extends Color {
+  constructor(r: 0, g: 0, b: 0, a: 1.0) { super(r, g, b); this.a = a }
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain('class ColorWithAlpha extends Color {')
+  })
+
+  it('handles static / async / get / set modifiers', () => {
+    const source = `
+class Thing {
+  static load(path: '') { return path }
+  async fetch() { return null }
+  get name() { return 'x' }
+  set name(v: '') { this._name = v }
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain("static load(path: '')")
+    expect(md).toContain('async fetch()')
+    expect(md).toContain('get name()')
+    expect(md).toContain("set name(v: '')")
+  })
+
+  it('captures return type annotations', () => {
+    const source = `
+class Math2 {
+  add(a: 0, b: 0): 0 { return a + b }
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain('add(a: 0, b: 0): 0')
+  })
+
+  it('does NOT extract `class Foo` text inside /*# */ doc blocks', () => {
+    // The doc-block prose is rendered as-is, but we should NOT emit a
+    // "## FakeClass" heading from the prose's `class FakeClass` mention.
+    const source = `
+/*#
+## Example
+Don't write this:
+
+    class FakeClass { constructor(x) {} }
+*/
+
+class RealClass {
+  constructor() {}
+}
+`
+    const result = generateDocs(source)
+    const classItems = result.items.filter((i) => i.type === 'class')
+    expect(classItems.length).toBe(1)
+    expect(classItems[0].name).toBe('RealClass')
+  })
+
+  it('does NOT extract `function` text inside /*# */ doc blocks', () => {
+    const source = `
+/*#
+Don't write this:
+
+    function fakeFn() {}
+*/
+
+function realFn() { return 1 }
+`
+    const result = generateDocs(source)
+    const fnItems = result.items.filter((i) => i.type === 'function')
+    expect(fnItems.length).toBe(1)
+    expect(fnItems[0].name).toBe('realFn')
+  })
+
+  it('handles a class with no members', () => {
+    const md = generateDocsMarkdown('class Empty {}')
+    expect(md).toContain('## Empty')
+    expect(md).toContain('class Empty {')
+    expect(md).toContain('}')
+  })
+})
+
+describe('generateDocsMarkdown — test cases section', () => {
+  it('renders each named test as a "### <name> (test cases)" heading with prettified body', () => {
+    const source = `
+test 'x is 5' {
+  expect(x).toBe(5)
+}
+test 'y is truthy' {
+  expect(y).toBeTruthy()
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain('### x is 5 (test cases)')
+    expect(md).toContain('x  // → 5')
+    expect(md).toContain('### y is truthy (test cases)')
+    expect(md).toContain('y  // → truthy')
+  })
+
+  it('skips anonymous tests (no description)', () => {
+    const source = `
+test {
+  expect(x).toBe(5)
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).not.toContain('(test cases)')
+  })
+
+  it('integrates with doc blocks and functions', () => {
+    const source = `
+/*#
+# Module
+Some intro.
+*/
+
+function add(a: 0, b: 0): 0 {
+  return a + b
+}
+
+test 'add(2, 3) is 5' {
+  expect(add(2, 3)).toBe(5)
+}
+`
+    const md = generateDocsMarkdown(source)
+    expect(md).toContain('# Module')
+    expect(md).toContain('## add')
+    expect(md).toContain('### add(2, 3) is 5 (test cases)')
+    expect(md).toContain('add(2, 3)  // → 5')
+  })
+})