@ndp-software/lit-md 0.3.0 → 0.4.0

package/README.md

@@ -74,12 +74,8 @@ example('multiply example', () => {
 
 ```
 
-```sh
-$ lit-md tmp.ts --out out.md
-```
-
-Output file `out.md`:
-````markdown
+````sh
+$ lit-md my-readme.ts
 ## My Project README.
 
 This is a really great project! 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ndp-software/lit-md",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Literate test files that generate README.md",
   "license": "UNLICENSED -- All rights reserved. See LICENSE file.",
   "author": "Andy Peterson <andy@ndpsoftware.com>",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "https://github.com/ndp-software/lit-md"
   },
   "keywords": [
     "literate programming",
@@ -30,10 +30,6 @@
     "docs/**/*",
     "src/**/*"
   ],
-  "exports": {
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts"
-  },
   "scripts": {
     "prepublishOnly": "npm run verify && npm run build",
     "readme": "node ./src/cli.ts --test --typecheck --out ./README.md src/docs/README.lit-md.ts",

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

@@ -66,10 +66,11 @@ what appears in the output and how it looks.
 
 # A simple example
 */
-shellExample(`lit-md tmp.ts --out out.md`, {
+shellExample(`lit-md my-readme.ts`, {
   inputFiles: [{
-    path: 'tmp.ts',
+    path: 'my-readme.ts',
     displayPath: false,
+    display: true,
     content: `
 describe('My Project README.', () => {
 /*
@@ -91,9 +92,11 @@ example('multiply example', () => {
 })
 `
   }],
-  outputFiles: [{
-    path: "out.md"
-  }]
+  displayCommand: true,
+  stdout: {
+    display: true,
+    contains: 'This is a really great project!'
+  }
 })
 
 /*

package/src/parser.ts

@@ -3,6 +3,7 @@ import { spawnSync } from 'node:child_process'
 import { writeFileSync, mkdtempSync, rmSync, readFileSync } from 'node:fs'
 import { join, isAbsolute } from 'node:path'
 import { tmpdir } from 'node:os'
+import { buildAliasPrefix } from './shell.ts'
 
 export type ProseNode = { kind: 'prose'; text: string; terminal?: true; noBlankAfter?: true; noBlankBefore?: true }
 export type CodeNode = { kind: 'code'; lang: string; text: string; title?: string }
@@ -230,6 +231,13 @@ export function parse(src: string, lang = 'typescript'): DocNode[] {
             if (opts && isExecutionNeeded(opts)) {
               const outputPaths = extractOutputFilePaths(opts)
               execution = executeShellCommand(cmd, inputFiles, outputPaths, expectedExitCode)
+              
+              // Fail if exit code doesn't match expectations
+              if (execution && execution.exitCode !== expectedExitCode) {
+                throw new Error(
+                  `shellExample failed: ${cmd}\nexit ${execution.exitCode} (expected exit code ${expectedExitCode})`
+                )
+              }
             }
 
             const displayCommand = opts ? readBoolOption(getProp(opts, 'displayCommand')) : true
@@ -881,8 +889,10 @@ function executeShellCommand(cmd: string, inputFiles: Array<InputFileInfo>, outp
       writeFileSync(resolvePath(f.path), f.content, 'utf8')
     }
 
-    // Execute command
-    const result = spawnSync(cmd, { shell: true, encoding: 'utf8', cwd: tmpDir })
+    // Execute command with alias prefix
+    const prefix = buildAliasPrefix()
+    const fullCmd = prefix ? `${prefix}${cmd}` : cmd
+    const result = spawnSync(fullCmd, { shell: true, encoding: 'utf8', cwd: tmpDir })
     
     // Capture output files when exit code matches expectation
     const outputFiles = new Map<string, string>()
@@ -930,10 +940,16 @@ function appendShellExampleAnnotations(
       const containsProp = getProp(prop.initializer as ts.ObjectLiteralExpression, 'contains')
       const displayProp = getProp(prop.initializer as ts.ObjectLiteralExpression, 'display')
       
-      // If display is true, use cached execution or show the contains assertion
+      // If display is true, use cached execution to show stdout
       if (displayProp && displayProp.initializer.kind === ts.SyntaxKind.TrueKeyword) {
         if (execution && execution.exitCode === 0) {
           lines.push(execution.stdout)
+        } else if (execution && execution.exitCode !== 0) {
+          // This shouldn't happen now since we throw on exit code mismatch
+          lines.push(`# [ERROR] stdout unavailable (exit code: ${execution.exitCode})`)
+        } else {
+          // This shouldn't happen now since we throw on errors
+          lines.push(`# [ERROR] stdout unavailable (execution failed)`)
         }
       } else if (containsProp && ts.isStringLiteralLike(containsProp.initializer)) {
         // Show contains assertion only if display is not true

package/src/shell.ts

@@ -41,7 +41,7 @@ function resolveCmdPath(cmdString: string): string {
 }
 
 /** Build shell alias prefix lines to prepend to commands. */
-function buildAliasPrefix(): string {
+export function buildAliasPrefix(): string {
   if (_aliases.size === 0) return ''
   const lines = [..._aliases.entries()].map(([name, cmd]) => `alias ${name}='${cmd}'`)
   return lines.join('\n') + '\n'
@@ -109,6 +109,10 @@ export function _runShellExample(cmd: string, opts: ShellExampleOpts): void {
     }
     const stdout = result.stdout
     if (opts.stdout !== undefined) {
+      // If display is true, stdout must not be empty
+      if (opts.stdout.display && (!stdout || stdout.trim() === '')) {
+        throw new Error(`stdout.display: true but command produced no output (exit code: ${actualExitCode})`)
+      }
       if (opts.stdout.contains !== undefined) {
         const actualDesc = stdout === '' ? '(empty)' : stdout
         assert.ok(