Accept Clojure examples that start their own server

packages/api-model/src/languages/clojure-examples.ts

@@ -29,9 +29,10 @@ export function attachCompleteClojureExamples(
   }
   const files = manifest.variants?.clojure?.files
   if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.examples) || !manifest.examples.length ||
-      !Array.isArray(files) || files.length !== 2 ||
-      new Set(files.map((file) => file.path)).size !== 2 ||
-      !files.every((file) => ['deps.edn', 'run.sh'].includes(file.path))) {
+      !Array.isArray(files) || !files.length || files.length > 2 ||
+      new Set(files.map((file) => file.path)).size !== files.length ||
+      !files.every((file) => ['deps.edn', 'run.sh'].includes(file.path)) ||
+      !files.some((file) => file.path === 'deps.edn')) {
     throw new Error('Invalid Clojure example catalog or setup')
   }
   const codeFor = (path: string): string => {
@@ -42,6 +43,8 @@ export function attachCompleteClojureExamples(
     if (!code?.trim()) throw new Error(`Missing complete Clojure example file: ${path}`)
     return code
   }
+  // A revision before libtmux-java#142 ships run.sh beside deps.edn; later ones start their own server.
+  const launcher = files.some((file) => file.path === 'run.sh')
   const urlFor = (path: string) => `https://github.com/${source.repo}/blob/${source.revision}/${path}`
   const ids = new Set<string>()
   for (const program of manifest.examples) {
@@ -71,11 +74,12 @@ export function attachCompleteClojureExamples(
         : 'Dependencies resolve from the isolated m2 directory; the core.async dependency is only enabled by its alias.'}`,
       code: codeFor(file.sourceFile), sourceUrl: urlFor(file.sourceFile),
     })), {
-      lang: 'clojure', intro: `Save the complete program as \`${program.path}\`, creating its parent directories. Closing its client leaves the launcher's server running.`,
+      lang: 'clojure', intro: `Save the complete program as \`${program.path}\`, creating its parent directories. ${launcher ? "Closing its client leaves the launcher's server running." : 'It starts a private tmux server of its own and stops it when the program closes it.'}`,
       code: codeFor(program.sourceFile), sourceUrl: urlFor(program.sourceFile),
     }, {
-      lang: 'console', intro: 'Run it with the private fixture. Set TMUX_BIN to select another tmux binary:',
-      code: `$ sh run.sh clojure \\\n  -J-Dclojure.main.report=stderr \\\n  -M${adapter ? ':core-async' : ''} \\\n  -m ${program.mainNamespace}\n`,
+      lang: 'console',
+      intro: launcher ? 'Run it with the private fixture. Set TMUX_BIN to select another tmux binary:' : 'Run it. Put the tmux you want first on PATH:',
+      code: `$ ${launcher ? 'sh run.sh ' : ''}clojure \\\n  -J-Dclojure.main.report=stderr \\\n  -M${adapter ? ':core-async' : ''} \\\n  -m ${program.mainNamespace}\n`,
     }, {
       lang: 'text', intro: program.requiresControl ? 'Expected output on tmux 3.7 or newer:' : 'Expected output:',
       code: program.expectedOutput,

packages/api-model/test/clojure-examples.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { attachCompleteClojureExamples } from '../src/languages/clojure-examples.ts'
+import type { ApiSymbol } from '../src/model.ts'
+
+const source = { repo: 'libtmux/libtmux-java', revision: 'a'.repeat(40) }
+const fixture = (launcher: boolean) => {
+  const program = {
+    id: 'clojure-Connect', variant: 'clojure', language: 'clojure', description: 'Connect to a private tmux server.',
+    mainNamespace: 'libtmux.examples.api.connect', targets: ['libtmux.core/open!'], expectedOutput: 'connected=true\n',
+    sourceFile: 'examples/src/main/clojure/libtmux/examples/api/connect.clj',
+    path: 'src/main/clojure/libtmux/examples/api/connect.clj',
+  }
+  const setup = [
+    { sourceFile: 'examples/api/clojure/deps.edn', path: 'deps.edn' },
+    ...(launcher ? [{ sourceFile: 'examples/api/run.sh', path: 'run.sh' }] : []),
+  ]
+  const manifest = { schemaVersion: 1, examples: [program], variants: { clojure: { files: setup } } }
+  const files = new Map<string, string>([
+    [program.sourceFile, '(ns libtmux.examples.api.connect)\n'],
+    ['examples/api/clojure/deps.edn', '{:paths ["src/main/clojure"]}\n'],
+    ['examples/api/run.sh', '#!/bin/sh\n'],
+  ])
+  const symbols = [{
+    id: 'libtmux.core/open!', publicId: 'libtmux.core/open!', qualifiedName: 'libtmux.core/open!', name: 'open!',
+    kind: 'function', modifiers: [], signatures: [], slug: 'open', source: { file: 'core.clj' }, doc: { summary: 'Opens.' },
+  }] as unknown as ApiSymbol[]
+  const read = (path: string) => path === 'examples/api/clojure/manifest.json' ? JSON.stringify(manifest) : files.get(path)
+  return { manifest, symbols, read }
+}
+
+describe('complete Clojure API programs', () => {
+  it('shows the launcher where the revision ships one', () => {
+    const { symbols, read } = fixture(true)
+    attachCompleteClojureExamples(symbols, read, source)
+    const blocks = symbols[0].doc!.examples!
+    expect(blocks.map((block) => block.lang)).toEqual(['console', 'clojure', 'sh', 'clojure', 'console', 'text'])
+    expect(blocks[3].intro).toContain("launcher's server")
+    expect(blocks[4].code).toBe('$ sh run.sh clojure \\\n  -J-Dclojure.main.report=stderr \\\n  -M \\\n  -m libtmux.examples.api.connect\n')
+  })
+
+  it('shows a program that starts its own server without a launcher', () => {
+    const { symbols, read } = fixture(false)
+    attachCompleteClojureExamples(symbols, read, source)
+    const blocks = symbols[0].doc!.examples!
+    expect(blocks.map((block) => block.lang)).toEqual(['console', 'clojure', 'clojure', 'console', 'text'])
+    expect(blocks[3].code).toBe('$ clojure \\\n  -J-Dclojure.main.report=stderr \\\n  -M \\\n  -m libtmux.examples.api.connect\n')
+    const prose = blocks.map((block) => `${block.intro ?? ''}\n${block.code}`).join('\n')
+    expect(prose).not.toMatch(/run\.sh|launcher|TMUX_BIN/)
+  })
+
+  it('still requires deps.edn and refuses other setup files', () => {
+    const { manifest, symbols, read } = fixture(false)
+    manifest.variants.clojure.files.pop()
+    expect(() => attachCompleteClojureExamples(symbols, read, source)).toThrow('Invalid Clojure example catalog or setup')
+    const other = fixture(false)
+    other.manifest.variants.clojure.files[0].path = 'other.edn'
+    expect(() => attachCompleteClojureExamples(other.symbols, other.read, source)).toThrow('Invalid Clojure example catalog or setup')
+  })
+})