@ndp-software/lit-md 0.3.0

package/src/cli.ts

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname, basename, extname, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { parse } from './parser.ts'
+import { render } from './renderer.ts'
+import { typecheck } from './typecheck.ts'
+import { stripTypesFlag, watchFilesAndWait } from './shell.ts'
+import { resolveOutputFiles } from './resolver.ts'
+import { resolveDescribeFormat, resetDescribeFormat } from './describe-format.ts'
+
+// --- Argument parsing ---
+
+const args = process.argv.slice(2)
+
+function extractFlag(flag: string): boolean {
+  const idx = args.indexOf(flag)
+  if (idx === -1) return false
+  args.splice(idx, 1)
+  return true
+}
+
+function extractFlagValue(flag: string): string | undefined {
+  const idx = args.indexOf(flag)
+  if (idx === -1) {
+    // Check for --flag=value format
+    const eqIdx = args.findIndex(arg => arg.startsWith(flag + '='))
+    if (eqIdx === -1) return undefined
+    const value = args[eqIdx]!.slice(flag.length + 1)
+    args.splice(eqIdx, 1)
+    return value
+  }
+  const value = args[idx + 1]
+  args.splice(idx, 2)
+  return value
+}
+
+const showHelp = extractFlag('--help') || extractFlag('-h')
+const dryrun = extractFlag('--dryrun')
+const runTests = extractFlag('--test')
+const runTypecheck = extractFlag('--typecheck')
+const updateSnapshots = extractFlag('--update-snapshots') || extractFlag('-u')
+const wait = extractFlag('--wait')
+const outFlag = extractFlagValue('--out')
+const outputDir = extractFlagValue('--outDir')
+const describeFormat = extractFlagValue('--describe') || '##'
+
+// Helper to parse test summary from output
+function parseTestSummary(output: string): { passed: number; failed: number; total: number; hasFailed: boolean } {
+  const lines = output.split('\n')
+  let stats = { passed: 0, failed: 0, total: 0, hasFailed: false }
+  
+  for (const line of lines) {
+    if (line.includes('ℹ pass')) {
+      const match = line.match(/pass\s+(\d+)/)
+      if (match) stats.passed = parseInt(match[1])
+    }
+    if (line.includes('ℹ fail')) {
+      const match = line.match(/fail\s+(\d+)/)
+      if (match) stats.failed = parseInt(match[1])
+    }
+    if (line.includes('ℹ tests')) {
+      const match = line.match(/tests\s+(\d+)/)
+      if (match) stats.total = parseInt(match[1])
+    }
+  }
+  
+  stats.hasFailed = stats.failed > 0
+  return stats
+}
+
+// Check for unknown options
+const unknownOptions = args.filter(a => a.startsWith('--') || (a.startsWith('-') && a.length > 1 && a !== '-'))
+if (unknownOptions.length > 0) {
+  console.error(`error: unknown option${unknownOptions.length > 1 ? 's' : ''}: ${unknownOptions.join(', ')}`)
+  process.exit(1)
+}
+
+const inputPaths = args.filter(a => !a.startsWith('--'))
+
+// --- File name rewriting helper ---
+
+function getOutputFileName(inputPath: string): string {
+  const base = basename(inputPath)
+  // Check if file ends with .lit-md.ts or .lit-md.js pattern
+  if (base.endsWith('.lit-md.ts') || base.endsWith('.lit-md.js')) {
+    // Remove the entire .lit-md.ts or .lit-md.js extension
+    return base.slice(0, -(base.endsWith('.lit-md.ts') ? '.lit-md.ts'.length : '.lit-md.js'.length)) + '.md'
+  }
+  // Otherwise, remove the final extension (.ts, .js, etc.) and add .md
+  return basename(inputPath, extname(inputPath)) + '.md'
+}
+
+// --- Help ---
+
+if (showHelp) {
+  console.log(`lit-md - Generate markdown documentation from test files
+
+Usage: lit-md [options] <file.ts|js> [file2 ...]
+
+Options:
+  --help, -h                Show this help message
+  --test                    Run tests before generating markdown
+  --typecheck               Run type checking before generating markdown
+  --dryrun                  Show what would be written without writing files
+  -u, --update-snapshots    Update snapshot files instead of generating markdown
+  --wait                    After generating, keep the process alive and watch for file
+                             changes. Press space to manually regenerate, Ctrl+C to exit.
+                             Works with --test and --typecheck (reruns on each change).
+  --out <output.md>         Write to a specific output file (requires single input)
+  --outDir <dir>           Write generated markdown files to this directory
+  --describe <format>       Control describe() block rendering (default: ##)
+                            Formats:
+                              hidden  - Omit describes
+                              #       - Render as h1 headers, nested as h2, h3, etc.
+                              ##      - Render as h2 headers, nested as h3, h4, etc. (default)
+                              ###     - Render as h3 headers, nested as h4, h5, etc.
+                              ####    - Render as h4 headers, nested as h5, h6, etc.
+                              auto    - Dynamically determine level based on document structure
+                                        (h1 if no headers exist, else one level deeper than last header)
+
+By default, output is written to stdout. Use --out or --outDir to write to files.
+
+Examples:
+  lit-md README.md.test.ts                                  # outputs to stdout
+  lit-md --test --typecheck README.md.test.ts               # outputs to stdout after testing
+  lit-md --wait README.md.test.ts                           # outputs to stdout, then waits for changes
+  lit-md --out /tmp/docs.md README.md.test.ts               # writes to file
+  lit-md --outDir ./docs src/**/*.md.test.ts                # writes to directory
+  lit-md --describe="#" README.md.test.ts                   # outputs to stdout with custom format
+  lit-md --describe="auto" README.md.test.ts                # outputs to stdout with auto format
+`)
+  process.exit(0)
+}
+
+// --- Validation ---
+
+if (!inputPaths.length) {
+  console.error('Usage: lit-md [--test] [--typecheck] [--dryrun] [-u|--update-snapshots] [--out <output.md>] [--outDir <dir>] <file.ts|js> [file2 ...]')
+  process.exit(1)
+}
+
+const validDescribeFormats = ['hidden', 'auto', '#', '##', '###', '####']
+if (!validDescribeFormats.includes(describeFormat)) {
+  console.error(`error: invalid --describe format: ${describeFormat}. Valid formats: ${validDescribeFormats.join(', ')}`)
+  process.exit(1)
+}
+
+if (outFlag && outputDir) {
+  console.error('error: --out and --outDir are mutually exclusive')
+  process.exit(1)
+}
+
+if (outFlag && inputPaths.length > 1) {
+  console.error('error: --out can only be used with a single input file')
+  process.exit(1)
+}
+
+if (runTypecheck) {
+  const jsFiles = inputPaths.filter(f => extname(f) === '.js')
+  if (jsFiles.length) {
+    console.error(`error: --typecheck requires .ts files; received: ${jsFiles.join(', ')}`)
+    process.exit(1)
+  }
+}
+
+// --- Typecheck ---
+// NOTE: Moved into executeTasks() to run on each regeneration when --wait is used
+
+// --- Run tests ---
+// NOTE: Moved into executeTasks() to run on each regeneration when --wait is used
+
+// --- Generate markdown ---
+
+async function generateMarkdown(): Promise<void> {
+  let filesGenerated = 0
+  
+  for (const inputPath of inputPaths) {
+    // Reset the describe format override before processing each file
+    resetDescribeFormat()
+    
+    // Import the file to allow module-level setup (like setDescribeFormat calls)
+    const absolutePath = resolve(inputPath)
+    try {
+      // Suppress test output during import and test execution
+      const origStdoutWrite = process.stdout.write
+      const origStderrWrite = process.stderr.write
+      const origLog = console.log
+      const origInfo = console.info
+      const origWarn = console.warn
+      try {
+        process.stdout.write = () => true as any
+        process.stderr.write = () => true as any
+        console.log = () => {}
+        console.info = () => {}
+        console.warn = () => {}
+        await import(absolutePath)
+        // Wait for deferred test execution to complete while output is suppressed
+        await new Promise(resolve => setTimeout(resolve, 100))
+      } finally {
+        process.stdout.write = origStdoutWrite
+        process.stderr.write = origStderrWrite
+        console.log = origLog
+        console.info = origInfo
+        console.warn = origWarn
+      }
+    } catch {
+      // File might not be valid JavaScript/TypeScript module, continue
+    }
+    
+    const src = readFileSync(inputPath, 'utf8')
+    const lang = extname(inputPath) === '.js' ? 'javascript' : 'typescript'
+    let nodes = parse(src, lang)
+    if (!dryrun) {
+      nodes = resolveOutputFiles(nodes)
+    }
+    // Use resolved format (CLI value + file override)
+    const finalDescribeFormat = resolveDescribeFormat(describeFormat)
+    const md = render(nodes, finalDescribeFormat)
+
+    let outPath: string | null = null
+    let isStdout = false
+    if (updateSnapshots) {
+      const outputFileName = getOutputFileName(inputPath)
+      const fileNameWithoutMd = outputFileName.slice(0, -3) // Remove .md
+      outPath = join(dirname(resolve(inputPath)), `${fileNameWithoutMd}.snapshot.md`)
+    } else if (outFlag) {
+      outPath = outFlag
+    } else if (outputDir) {
+      mkdirSync(outputDir, { recursive: true })
+      outPath = join(outputDir, getOutputFileName(inputPath))
+    } else {
+      isStdout = true
+    }
+
+    if (dryrun) {
+      if (isStdout) {
+        console.error(`dry run: would write to stdout`)
+      } else {
+        console.error(`dry run: would write ${outPath}`)
+      }
+    } else if (isStdout) {
+      process.stdout.write(md + '\n')
+    } else {
+      writeFileSync(outPath!, md + '\n', 'utf8')
+      filesGenerated++
+    }
+  }
+  
+  // Show summary if files were written
+  if (!dryrun && filesGenerated > 0) {
+    const fileWord = filesGenerated === 1 ? 'file' : 'files'
+    console.error(`✅ Generated ${filesGenerated} ${fileWord}`)
+  }
+}
+
+async function executeTasks(): Promise<void> {
+  // Run typecheck before generation (if enabled)
+  if (runTypecheck) {
+    const result = typecheck(inputPaths.map(p => resolve(p)))
+    if (!result.ok) {
+      for (const msg of result.messages) console.error(msg)
+      console.error('❌ Typecheck failed')
+      // In wait mode, report error but continue; in normal mode, exit
+      if (!wait) process.exit(1)
+      // Continue to markdown generation even if typecheck failed
+    } else {
+      console.error('✅ Typecheck passed')
+    }
+  }
+
+  // Run tests before generation (if enabled)
+  if (runTests) {
+    const stripFlag = stripTypesFlag()
+    const nodeArgs = ['--test', ...(stripFlag ? [stripFlag] : []), ...inputPaths.map(p => resolve(p))]
+    
+    // In wait mode, capture output for summary display; otherwise inherit (show full output)
+    const spawnOptions = wait ? { encoding: 'utf-8' as const } : { stdio: 'inherit' as const, env: process.env }
+    
+    const result = spawnSync(process.execPath, nodeArgs, spawnOptions)
+    
+    // Handle output based on mode
+    if (wait && result.stdout) {
+      // In wait mode: capture output and show condensed summary
+      const output = result.stdout.toString()
+      const stats = parseTestSummary(output)
+      
+      if (stats.hasFailed) {
+        // Extract and show failures section
+        const failureStart = output.indexOf('✖ failing tests')
+        if (failureStart !== -1) {
+          const failureSection = output.substring(failureStart)
+          console.error(failureSection)
+        }
+        console.error(`\n❌ Tests failed: ${stats.failed}/${stats.total} failed`)
+      } else {
+        // All passed: show one-line summary
+        console.log(`✅ Tests passed: ${stats.passed} passed`)
+      }
+    }
+    
+    if (result.status !== 0) {
+      // In wait mode, report error but continue; in normal mode, exit
+      if (!wait) process.exit(result.status ?? 1)
+      // Continue to markdown generation even if tests failed
+    }
+  }
+
+  // Generate markdown (always do this, even if tests/typecheck failed)
+  await generateMarkdown()
+}
+
+;(async () => {
+  await executeTasks()
+
+  // If --wait flag is set and we're in an interactive terminal, enter the watch loop
+  if (wait && process.stdin.isTTY) {
+    while (true) {
+      const trigger = await watchFilesAndWait(inputPaths)
+      // On spacebar or file change, regenerate
+      await executeTasks()
+    }
+  }
+})()
+
+
+

package/src/describe-format.ts

@@ -0,0 +1,53 @@
+export type DescribeFormatType = 'hidden' | '#' | '##' | '###' | '####' | 'auto'
+
+let overrideFormat: DescribeFormatType | undefined = undefined
+
+/**
+ * Set the describe format for the current file, overriding the CLI --describe option.
+ * This must be called at the top of the file, before any examples or describes.
+ * 
+ * @param format - The format to use for rendering describe() block names:
+ *   - 'hidden': omit describe names (default)
+ *   - '#', '##', '###', '####': render as H1-H4 headers with nesting support
+ *   - 'auto': dynamically determine level based on document structure (h1 if no headers exist, else one level deeper than last header)
+ * 
+ * @example
+ * ```ts
+ * import { setDescribeFormat } from '@ndp-software/lit-md'
+ * setDescribeFormat('##')
+ * // All describe() blocks in this file will be rendered as H2+ headers
+ * ```
+ */
+export function setDescribeFormat(format: DescribeFormatType): void {
+  if (overrideFormat !== undefined && overrideFormat !== format) {
+    console.warn(`setDescribeFormat called multiple times with different formats: ${overrideFormat} -> ${format}. Only the last call will be used.`)
+  }
+  overrideFormat = format
+}
+
+/**
+ * Get the current describe format override (if any).
+ * Returns undefined if no override has been set.
+ * @internal
+ */
+export function getDescribeFormatOverride(): DescribeFormatType | undefined {
+  return overrideFormat
+}
+
+/**
+ * Reset the describe format override.
+ * Mainly useful for testing.
+ * @internal
+ */
+export function resetDescribeFormat(): void {
+  overrideFormat = undefined
+}
+
+/**
+ * Resolve the final describe format to use.
+ * Takes the CLI format and applies the override if set.
+ * @internal
+ */
+export function resolveDescribeFormat(cliFormat: string): string {
+  return overrideFormat ?? cliFormat
+}

package/src/docs/README.lit-md.ts

@@ -0,0 +1,126 @@
+import {
+  describe,
+  example,
+  shellExample,
+  metaExample,
+  alias,
+  stripTypesFlag,
+  setDescribeFormat
+} from '../index.ts'
+import assert from 'node:assert/strict'
+
+const _flag = stripTypesFlag()
+alias('lit-md', ['node', _flag, './src/cli.ts'].filter(Boolean).join(' '))
+
+/*
+# @ndp-software/lit-md
+
+Literate test files that generate `README.md`s.
+
+## Introduction
+
+Some projects, especially libraries, require numerous and
+detailed code examples. For those responsible for updating
+a README, or other documentation, this can be burdensome
+and error-prone.
+
+With lit-md, you write your documentation with embedded code samples
+that are automatically type-checked and run through node to
+verify them. Every example actually works!
+
+Key features:
+- works with Typescript or Javascript
+- provides utilities to include shell commands and their outputs
+  as part of your documentation. This is important if you tool has
+  a CLI, or you just need to show how it works in the terminal.
+- supports flexible assertion methods for both code examples and shell commands,
+  with options to display actual outputs in the generated markdown
+- fully tested with its own test suite, which also serves as
+  documentation and examples for users
+
+There _are_ other tools with the same aims (e.g. [TwoSlash](https://github.com/microsoft/TypeScript-Website/tree/v2/packages/ts-twoslasher)),
+but this follows in the Literate programming tradition but updated
+for the Typescript and TDD era. I have aimed to provide a great DX
+for writing documentation, with a simple syntax and powerful features
+that work well with the node ecosystem.
+
+```sh
+# You can "run" your documentation as a test:
+node --test README.lit-md.ts
+# You can also typecheck:
+tsc README.lit-md.ts
+# An it can be converted from Typescript to a plain old markdown
+# README file with `lit-md`:
+lit-md README.lit-md.ts        # generates README.md
+
+# Or, you can do it all in one step with:
+lit-md --test --typecheck README.lit-md.ts  # all-in-one!
+```
+## How it Works
+A **lit-md** file contains prose in comments and examples in test bodies.
+At a basic level, a file is processed and
+- comments are directly transferred into markdown, and
+- example (or `test`, `it`, `spec`) bodies become fenced code blocks.
+To make this work well, there are quite a few nuances and features to control
+what appears in the output and how it looks.
+
+# A simple example
+*/
+shellExample(`lit-md tmp.ts --out out.md`, {
+  inputFiles: [{
+    path: 'tmp.ts',
+    displayPath: false,
+    content: `
+describe('My Project README.', () => {
+/*
+This is a really great project! 
+Adding numbers is as simple as using the "+" operator:
+*/
+example('add example', () => {
+  const a = 1
+  const b = 2
+  console.log(a + b) // => 3
+})  
+
+// Also supported is multiplication:
+example('multiply example', () => {
+  const x = 3
+  const y = 4
+  console.log(x * y) // => 12
+})
+})
+`
+  }],
+  outputFiles: [{
+    path: "out.md"
+  }]
+})
+
+/*
+For more information on the CLI, see [CLI documentation](./docs/cli.md).
+*/
+
+describe('Shell examples', () => {
+  /*
+  Use `shellExample` to include executable shell commands in the README.
+  It verifies a 0 return code and provides flexible assertion and display options.
+  */
+
+  describe('shellExample function', () => {
+    shellExample('echo "hello world"', { meta: true, stdout: { display: true } })
+  })
+
+  /*
+  For more information on the `shellExample`, see [shellCommand documentation](./docs/shell-examples.md).
+  */
+})
+
+/*
+## CREDITS
+
+Built by Andrew J. Peterson, although there was some manual code changes,
+most of the code was Github Copilot CLI, using mostly Claude Haiku 4.5
+and some Claude Sonnet 4.6.
+Most tasks used a plan-autopilot loop, but other approaches were used as well.
+ */
+

package/src/docs/cli.lit-md.ts

@@ -0,0 +1,44 @@
+import {alias, describe, stripTypesFlag, shellExample} from '../index.ts'
+
+const _flag = stripTypesFlag()
+alias('lit-md', ['node', _flag, './src/cli.ts'].filter(Boolean).join(' '))
+
+describe('CLI', () => {
+  // By default, output is written to stdout.
+  shellExample('lit-md tmp.ts', {
+    displayCommand: true,
+    inputFiles: [{
+      path: 'tmp.ts',
+      content: `// # My Document\nimport { example } from 'node:test'\nexample('test', () => {})`
+    }],
+    stdout: {
+      contains: '# My Document',
+      display: true
+    }
+  })
+
+  describe('Custom output path', () => {
+    // Use --out to write to a different location.
+    shellExample('lit-md tmp.ts --out /tmp/docs.md', {
+      displayCommand: true,
+      inputFiles: [{
+        path: 'tmp.ts',
+        content: `// # Documentation\nimport { example } from 'node:test'`
+      }],
+      outputFiles: [{
+        path: '/tmp/docs.md',
+        contains: '# Documentation'
+      }]
+    })
+  })
+
+  describe('Help', () => {
+    // Use `lit-md --help` for options.
+    shellExample('lit-md --help', {
+      displayCommand: true,
+      stdout: {
+        display: true
+      }
+    })
+  })
+})