@ndp-software/lit-md 0.3.0

package/src/renderer.ts

@@ -0,0 +1,130 @@
+import type { DocNode, CodeNode } from './parser.ts'
+
+const langAliases: Record<string, string> = {
+  typescript: 'ts',
+  javascript: 'js',
+}
+
+/** Merges consecutive code blocks of the same language */
+function mergeConsecutiveCodeBlocks(nodes: DocNode[]): DocNode[] {
+  if (nodes.length === 0) return nodes
+  
+  const result: DocNode[] = []
+  let currentCodeBlock: CodeNode | null = null
+  
+  for (const node of nodes) {
+    if (node.kind === 'code') {
+      if (currentCodeBlock && currentCodeBlock.lang === node.lang && !currentCodeBlock.title && !node.title) {
+        // Merge with current block
+        currentCodeBlock.text += '\n\n' + node.text
+      } else {
+        // Save previous block and start new one
+        if (currentCodeBlock) result.push(currentCodeBlock)
+        currentCodeBlock = { ...node }
+      }
+    } else {
+      // Non-code node: flush current block and add this node
+      if (currentCodeBlock) {
+        result.push(currentCodeBlock)
+        currentCodeBlock = null
+      }
+      result.push(node)
+    }
+  }
+  
+  // Don't forget the last code block
+  if (currentCodeBlock) result.push(currentCodeBlock)
+  
+  return result
+}
+
+export function render(nodes: DocNode[], describeFormat: string = 'hidden'): string {
+  const merged = mergeConsecutiveCodeBlocks(nodes.filter(n => n.kind !== 'output-file-display'))
+  if (!merged.length) return ''
+  let out = ''
+  let lastHeaderLevel = 0
+  for (let i = 0; i < merged.length; i++) {
+    if (i > 0) {
+      const prev = merged[i - 1]!
+      const curr = merged[i]!
+      const noBlank = (prev.kind === 'prose' && prev.noBlankAfter) ||
+                      (curr.kind === 'prose' && curr.noBlankBefore)
+      out += noBlank ? '\n' : '\n\n'
+    }
+    const rendered = renderNode(merged[i]!, describeFormat, lastHeaderLevel)
+    out += rendered
+    // Update lastHeaderLevel after rendering
+    const node = merged[i]!
+    if (node.kind === 'describe' && describeFormat !== 'hidden') {
+      const baseLevel = describeFormat === 'auto' ? lastHeaderLevel : describeFormat.length
+      lastHeaderLevel = baseLevel + node.depth
+      lastHeaderLevel = Math.min(lastHeaderLevel, 6)
+    } else if (node.kind === 'prose') {
+      // Check for headers in prose and update lastHeaderLevel
+      const proseHeaderLevel = getMaxHeaderLevelInProse(node.text)
+      if (proseHeaderLevel > 0) {
+        lastHeaderLevel = proseHeaderLevel
+      }
+    }
+  }
+  return out
+}
+
+function renderNode(node: DocNode, describeFormat: string = 'hidden', lastHeaderLevel: number = 0): string {
+  if (node.kind === 'prose') return node.text
+  if (node.kind === 'output-file-display') return ''
+  if (node.kind === 'describe') {
+    if (describeFormat === 'hidden') return ''
+    let baseLevel: number
+    if (describeFormat === 'auto') {
+      // If no headers yet, start at h1. Otherwise, go one level deeper than last header
+      baseLevel = lastHeaderLevel === 0 ? 1 : lastHeaderLevel + 1
+    } else {
+      // Explicit format (e.g., "#", "##", etc.)
+      baseLevel = describeFormat.length > 0 ? describeFormat.length : 1
+    }
+    const level = baseLevel + node.depth
+    const hashes = '#'.repeat(Math.min(level, 6))
+    return `${hashes} ${node.name}`
+  }
+  const lang = langAliases[node.lang] ?? node.lang
+  // Omit language if it's 'text'
+  const info = lang === 'text' ? (node.title ?? '') : (node.title ? `${lang} ${node.title}` : lang)
+  
+  // Use dynamic fence delimiters to handle nested code blocks
+  // Find the longest sequence of backticks in the content
+  const maxBackticks = findMaxBacktickSequence(node.text)
+  const fenceLength = Math.max(3, maxBackticks + 1)
+  const fence = '`'.repeat(fenceLength)
+  
+  return `${fence}${info}\n${node.text}\n${fence}`
+}
+
+function findMaxBacktickSequence(text: string): number {
+  let maxSeq = 0
+  let currentSeq = 0
+  for (const char of text) {
+    if (char === '`') {
+      currentSeq++
+      maxSeq = Math.max(maxSeq, currentSeq)
+    } else {
+      currentSeq = 0
+    }
+  }
+  return maxSeq
+}
+
+/** Detects the maximum header level in prose text (1-6) */
+function getMaxHeaderLevelInProse(text: string): number {
+  let maxLevel = 0
+  const lines = text.split('\n')
+  for (const line of lines) {
+    // Match lines that start with # characters
+    const match = line.match(/^(#+)\s/)
+    if (match) {
+      const level = match[1].length
+      maxLevel = Math.max(maxLevel, Math.min(level, 6))
+    }
+  }
+  return maxLevel
+}

package/src/resolver.ts

@@ -0,0 +1,65 @@
+import { spawnSync } from 'node:child_process'
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import type { DocNode, OutputFileDisplayNode } from './parser.ts'
+
+/**
+ * Resolves `output-file-display` nodes by using cached execution results (if available) or
+ * executing the shell command, reading the output file, and replacing the node with a code block.
+ * Updates the preceding prose summary to end with `:` (instead of `.`) when content is shown.
+ * Handles empty files and command failures appropriately.
+ */
+export function resolveOutputFiles(nodes: DocNode[]): DocNode[] {
+  const result: DocNode[] = []
+  for (const node of nodes) {
+    if (node.kind !== 'output-file-display') {
+      result.push(node)
+      continue
+    }
+    const content = runAndCapture(node)
+    if (content !== null) {
+      const prev = result[result.length - 1]
+      if (content.trim()) {
+        // File has content: add code block, change period to colon in preceding prose
+        if (prev?.kind === 'prose' && prev.text.endsWith('.')) {
+          result[result.length - 1] = { ...prev, text: prev.text.slice(0, -1) + ':', noBlankAfter: true }
+        }
+        result.push({ kind: 'code', lang: node.lang, text: content.trimEnd() })
+      } else {
+        // File is empty: replace period or colon with " is empty."
+        if (prev?.kind === 'prose' && (prev.text.endsWith(':') || prev.text.endsWith('.'))) {
+          result[result.length - 1] = { ...prev, text: prev.text.slice(0, -1) + ' is empty.' }
+        }
+      }
+    }
+    // If content is null (command failed), silently drop the display node
+  }
+  return result
+}
+
+function runAndCapture(node: OutputFileDisplayNode): string | null {
+  // Use cached execution if available
+  if (node.execution) {
+    if (node.execution.exitCode !== 0) return null
+    const content = node.execution.outputFiles.get(node.path)
+    return content ?? null
+  }
+
+  // Fall back to direct execution if no cache
+  const tmpDir = mkdtempSync(join(tmpdir(), 'lit-md-cap-'))
+  try {
+    for (const f of node.inputFiles) {
+      writeFileSync(join(tmpDir, f.path), f.content, 'utf8')
+    }
+    const result = spawnSync(node.cmd, { shell: true, encoding: 'utf8', cwd: tmpDir })
+    if (result.status !== 0) return null
+    try {
+      return readFileSync(join(tmpDir, node.path), 'utf8')
+    } catch {
+      return null
+    }
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true })
+  }
+}

package/src/shell.ts

@@ -0,0 +1,362 @@
+import { spawnSync } from 'node:child_process'
+import { readFileSync, writeFileSync, unlinkSync, mkdtempSync, rmSync, existsSync } from 'node:fs'
+import { isAbsolute, resolve, join, dirname, extname } from 'node:path'
+import { tmpdir } from 'node:os'
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+export { test as example, test as metaExample, describe } from 'node:test'
+
+// Module-level alias registry: name → resolved shell command string
+const _aliases = new Map<string, string>()
+
+/**
+ * Register a shell alias. `cmdString` may be a plain path or a command with
+ * arguments (e.g. `'node --experimental-strip-types ./cli.ts'`). Any token
+ * that looks like a file path (contains `/` or starts with `.`) is resolved
+ * relative to `process.cwd()` at call time. The resulting alias is prepended
+ * to every shell command executed by `shellExample`.
+ *
+ * Alias calls produce **no markdown output**.
+ */
+export function alias(name: string, cmdString: string): void {
+  const resolved = resolveCmdPath(cmdString)
+  _aliases.set(name, resolved)
+}
+
+/** Internal: clear all registered aliases. Used in tests for isolation. */
+export function _clearAliases(): void {
+  _aliases.clear()
+}
+
+/** Resolve path-like tokens in a command string to absolute paths. */
+function resolveCmdPath(cmdString: string): string {
+  return cmdString.replace(/\S+/g, token => {
+    if (token.startsWith('/') || token.startsWith('./') || token.startsWith('../') ||
+        (!isAbsolute(token) && token.includes('/'))) {
+      return resolve(process.cwd(), token)
+    }
+    return token
+  })
+}
+
+/** Build shell alias prefix lines to prepend to commands. */
+function buildAliasPrefix(): string {
+  if (_aliases.size === 0) return ''
+  const lines = [..._aliases.entries()].map(([name, cmd]) => `alias ${name}='${cmd}'`)
+  return lines.join('\n') + '\n'
+}
+
+/** Check if content matches a pattern (string or regex). */
+function matchesPattern(content: string, pattern: string | RegExp): boolean {
+  return pattern instanceof RegExp ? pattern.test(content) : content.includes(pattern)
+}
+
+export interface ShellFileAssertion {
+  path: string
+  contains?: string | RegExp
+  matches?: string | RegExp
+  displayPath?: boolean | 'hidden'
+  summary?: boolean
+}
+
+type ExampleInputFile = {
+  path: string;
+  content: string;
+  displayPath?: boolean | 'hidden';
+  display?: boolean | 'hidden';
+  summary?: boolean
+}
+
+export interface ShellExampleOpts {
+  stdout?: { contains?: string | RegExp; matches?: string | RegExp; display?: boolean }
+  outputFiles?: ShellFileAssertion[]
+  inputFiles?: Array<ExampleInputFile>
+  displayCommand?: boolean | 'hidden'
+  meta?: boolean
+  exitCode?: number
+  timeout?: number  // Timeout in milliseconds, default 3000
+}
+
+/** Internal: executes a shell command and runs any assertions. Throws on failure.
+ *  Exported for direct testing. */
+export function _runShellExample(cmd: string, opts: ShellExampleOpts): void {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'lit-md-shell-'))
+  const resolvePath = (p: string) => isAbsolute(p) ? p : join(tmpDir, p)
+  try {
+    for (const f of opts.inputFiles ?? []) {
+      writeFileSync(resolvePath(f.path), f.content, 'utf8')
+    }
+    const prefix = buildAliasPrefix()
+    const fullCmd = prefix ? `${prefix}${cmd}` : cmd
+    const timeoutMs = opts.timeout ?? 3000
+    const result = spawnSync(fullCmd, { shell: true, encoding: 'utf8', cwd: tmpDir, timeout: timeoutMs })
+    
+    // Check for timeout error
+    if (result.error && (result.error as NodeJS.ErrnoException).code === 'ETIMEDOUT') {
+      throw new Error(`Command timed out after ${timeoutMs}ms: ${cmd}`)
+    }
+    
+    const actualExitCode = result.status ?? 1
+    if (opts.exitCode !== undefined) {
+      if (actualExitCode !== opts.exitCode) {
+        const err = result.stderr || result.error?.message || ''
+        throw new Error(`Command failed: ${cmd}\nexit ${actualExitCode} (expected exit code ${opts.exitCode})${err ? ': ' + err : ''}`)
+      }
+    } else if (actualExitCode !== 0) {
+      const err = result.stderr || result.error?.message || ''
+      throw new Error(`Command failed: ${cmd}\nexit ${actualExitCode}${err ? ': ' + err : ''}`)
+    }
+    const stdout = result.stdout
+    if (opts.stdout !== undefined) {
+      if (opts.stdout.contains !== undefined) {
+        const actualDesc = stdout === '' ? '(empty)' : stdout
+        assert.ok(
+          matchesPattern(stdout, opts.stdout.contains),
+          `stdout did not contain: ${JSON.stringify(opts.stdout.contains)}\nActual: ${actualDesc}`
+        )
+      }
+      if (opts.stdout.matches !== undefined) {
+        const actualDesc = stdout === '' ? '(empty)' : stdout
+        assert.ok(
+          matchesPattern(stdout, opts.stdout.matches),
+          `stdout did not match: ${opts.stdout.matches}\nActual: ${actualDesc}`
+        )
+      }
+    }
+    for (const fa of opts.outputFiles ?? []) {
+      let content: string
+      try {
+        content = readFileSync(resolvePath(fa.path), 'utf8')
+      } catch (e) {
+        const err = e as NodeJS.ErrnoException
+        if (err.code === 'ENOENT') {
+          throw new Error(`Output file not found: ${fa.path}\n\nThe command may not have created this file, or it may be in a different location.\nCommand: ${cmd}`)
+        }
+        throw e
+      }
+      const actualDesc = content === '' ? '(empty)' : content
+      if (fa.contains !== undefined) {
+        assert.ok(
+          matchesPattern(content, fa.contains),
+          `file ${fa.path} does not contain: ${JSON.stringify(fa.contains)}\nActual:\n${actualDesc}`
+        )
+      }
+      if (fa.matches !== undefined) {
+        assert.ok(
+          matchesPattern(content, fa.matches),
+          `file ${fa.path} does not match: ${fa.matches}\nActual:\n${actualDesc}`
+        )
+      }
+    }
+    // Clean up absolute-path inputFiles (relative ones are removed with tmpDir below)
+    for (const f of opts.inputFiles ?? []) {
+      if (isAbsolute(f.path)) try { unlinkSync(f.path) } catch {}
+    }
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true })
+  }
+}
+
+
+
+/** Registers a node:test test that executes the shell command and verifies assertions. */
+export function shellExample(cmd: string, opts: ShellExampleOpts = {}): void {
+  const timeoutMs = opts.timeout ?? 3000
+  test(cmd, { timeout: timeoutMs }, () => _runShellExample(cmd, opts))
+}
+
+/**
+ * Returns `'--experimental-strip-types'` on Node.js versions where the flag is required
+ * (v22.6–v23.5), or `''` on versions where TypeScript stripping is stable (v23.6+).
+ */
+export function stripTypesFlag(): string {
+  const parts = process.versions.node.split('.')
+  const major = parseInt(parts[0] ?? '0', 10)
+  const minor = parseInt(parts[1] ?? '0', 10)
+  if (major === 22 && minor >= 6) return '--experimental-strip-types'
+  if (major === 23 && minor < 6) return '--experimental-strip-types'
+  return ''
+}
+
+/**
+ * Extract import paths from a TypeScript/JavaScript file using regex.
+ * Returns absolute paths to files that could be imported.
+ */
+function extractImportPaths(filePath: string, baseDir: string): Set<string> {
+  const importedPaths = new Set<string>()
+  try {
+    const content = readFileSync(filePath, 'utf8')
+    
+    // Match import statements: import ... from 'path' or "path"
+    const importRegex = /import\s+(?:(?:{[^}]*})|(?:\*\s+as\s+\w+)|(?:\w+))?(?:\s*,\s*(?:{[^}]*}|\*\s+as\s+\w+|\w+))*\s+from\s+['"]([^'"]+)['"]/g
+    
+    // Match require statements: require('path') or require("path")
+    const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+    
+    let match
+    while ((match = importRegex.exec(content)) !== null) {
+      const importPath = match[1]
+      if (importPath && !importPath.startsWith('.') && !importPath.startsWith('/')) {
+        // Skip node_modules and absolute imports
+        continue
+      }
+      const resolved = resolveImportPath(importPath, baseDir)
+      if (resolved) importedPaths.add(resolved)
+    }
+    
+    while ((match = requireRegex.exec(content)) !== null) {
+      const importPath = match[1]
+      if (importPath && !importPath.startsWith('.') && !importPath.startsWith('/')) {
+        continue
+      }
+      const resolved = resolveImportPath(importPath, baseDir)
+      if (resolved) importedPaths.add(resolved)
+    }
+  } catch {
+    // If we can't read the file, skip it
+  }
+  
+  return importedPaths
+}
+
+/**
+ * Resolve an import path to an actual file path.
+ * Handles .ts, .js, .tsx, .jsx extensions and directory index files.
+ */
+function resolveImportPath(importPath: string, baseDir: string): string | null {
+  const basePath = resolve(baseDir, importPath)
+  
+  // Try the path as-is
+  if (existsSync(basePath)) return basePath
+  
+  // Try with common extensions
+  for (const ext of ['.ts', '.tsx', '.js', '.jsx']) {
+    if (existsSync(basePath + ext)) {
+      return basePath + ext
+    }
+  }
+  
+  // Try as a directory with index file
+  for (const indexFile of ['index.ts', 'index.tsx', 'index.js', 'index.jsx']) {
+    const indexPath = join(basePath, indexFile)
+    if (existsSync(indexPath)) {
+      return indexPath
+    }
+  }
+  
+  return null
+}
+
+/**
+ * Recursively collect all dependencies of input files.
+ * Returns a set of all files that should be watched.
+ */
+function collectAllDependencies(inputPaths: string[], visited = new Set<string>()): Set<string> {
+  const allDeps = new Set<string>(inputPaths.map(p => resolve(p)))
+  const toProcess = [...inputPaths]
+  
+  while (toProcess.length > 0) {
+    const current = toProcess.shift()!
+    const resolvedCurrent = resolve(current)
+    
+    if (visited.has(resolvedCurrent)) continue
+    visited.add(resolvedCurrent)
+    
+    const deps = extractImportPaths(resolvedCurrent, dirname(resolvedCurrent))
+    for (const dep of deps) {
+      allDeps.add(dep)
+      if (!visited.has(dep)) {
+        toProcess.push(dep)
+      }
+    }
+  }
+  
+  return allDeps
+}
+
+/**
+ * Watch input files for changes and listen for keyboard input.
+ * Returns 'spacebar' if user presses spacebar, or 'filechange' if a file changes.
+ * Exit cleanly on Ctrl+C (SIGINT). Gracefully handles non-TTY environments by
+ * resolving immediately.
+ */
+export async function watchFilesAndWait(inputPaths: string[]): Promise<'spacebar' | 'filechange'> {
+  // Check if stdin is a TTY (interactive terminal)
+  if (!process.stdin.isTTY) {
+    // Non-interactive environment: resolve immediately without waiting
+    return 'spacebar'
+  }
+
+  const { watch } = await import('node:fs')
+
+  let lastChangeTime = 0
+  const DEBOUNCE_MS = 300
+  let changeDetected = false
+
+  // Collect all dependencies to watch, not just the input files
+  const filesToWatch = collectAllDependencies(inputPaths)
+
+  const watchers = Array.from(filesToWatch).map(filePath => {
+    return watch(filePath, (eventType) => {
+      const now = Date.now()
+      // Debounce: only consider changes if enough time has passed
+      if (now - lastChangeTime >= DEBOUNCE_MS) {
+        lastChangeTime = now
+        changeDetected = true
+      }
+    })
+  })
+
+  // Set up signal handlers for clean exit
+  const exitHandler = () => {
+    watchers.forEach(w => w.close())
+    process.stdin.setRawMode(false)
+    process.exit(0)
+  }
+
+  process.on('SIGINT', exitHandler)
+  process.on('SIGTERM', exitHandler)
+
+  // Display wait message
+  console.error('Press space to regenerate, q to quit...')
+
+  // Set raw mode to detect individual key presses
+  process.stdin.setRawMode(true)
+  process.stdin.resume()
+
+  return new Promise<'spacebar' | 'filechange'>(resolve => {
+    const onData = (data: Buffer) => {
+      const char = data[0]
+      // 0x20 is the spacebar
+      if (char === 0x20) {
+        cleanup()
+        resolve('spacebar')
+      } else if (char === 0x03 || char === 0x71 || char === 0x78 || char === 0x1b) {
+        // Ctrl+C (0x03), q (0x71), x (0x78), or esc (0x1b)
+        cleanup()
+        process.exit(0)
+      }
+    }
+
+    const checkForChanges = setInterval(() => {
+      if (changeDetected) {
+        cleanup()
+        console.error('Files changed, regenerating...')
+        resolve('filechange')
+      }
+    }, 50)
+
+    const cleanup = () => {
+      process.stdin.off('data', onData)
+      clearInterval(checkForChanges)
+      process.stdin.setRawMode(false)
+      process.stdin.pause()
+      process.removeListener('SIGINT', exitHandler)
+      process.removeListener('SIGTERM', exitHandler)
+      watchers.forEach(w => w.close())
+    }
+
+    process.stdin.on('data', onData)
+  })
+}

package/src/typecheck.ts

@@ -0,0 +1,51 @@
+import ts from 'typescript'
+import { join } from 'path'
+
+export interface TypecheckResult {
+  ok: boolean
+  messages: string[]
+}
+
+export function typecheck(files: string[]): TypecheckResult {
+  // Only look for tsconfig.json in the exact CWD (no upward walk).
+  // This matches the user's expectation: run lit-md from the project root,
+  // and if a tsconfig.json is there, it will be used.
+  const tsConfigPath = join(process.cwd(), 'tsconfig.json')
+  const configPath = ts.sys.fileExists(tsConfigPath) ? tsConfigPath : undefined
+
+  let compilerOptions: ts.CompilerOptions
+
+  if (configPath) {
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile)
+    if (configFile.error) {
+      return { ok: false, messages: [ts.flattenDiagnosticMessageText(configFile.error.messageText, '\n')] }
+    }
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, ts.sys.getCurrentDirectory())
+    compilerOptions = { ...parsed.options, noEmit: true }
+  } else {
+    // Sensible defaults when no tsconfig.json is present
+    compilerOptions = {
+      strict: true,
+      noEmit: true,
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      target: ts.ScriptTarget.ESNext,
+      allowImportingTsExtensions: true,
+    }
+  }
+
+  const program = ts.createProgram(files, compilerOptions)
+  const diagnostics = ts.getPreEmitDiagnostics(program)
+
+  if (!diagnostics.length) return { ok: true, messages: [] }
+
+  // Use TypeScript's built-in formatting with colors and context for better readability
+  const formatted = ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+    getCanonicalFileName: fileName => fileName,
+    getCurrentDirectory: () => process.cwd(),
+    getNewLine: () => '\n',
+  })
+
+  return { ok: false, messages: [formatted] }
+}
+